Task 5: OpenAPI vendoring and contract check (spike with decision) (#5) #38
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "task/5-openapi-vendor-contract"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What this builds
cargo xtask vendor-spec --from <path-or-url>(xtask/src/vendor_spec.rs): copies the fork's generatedopenapi.jsonbyte for byte intocrates/fluxer-proto/spec/openapi.jsonand writesspec/SOURCE(fork commit <sha>,-dirtyif the file differs from that commit;url <url> <date>;file <path> <date>outside a checkout). Refuses anything that is not an OpenAPI 3 document withcomponents.schemas.cargo xtask spec-check(xtask/src/spec_check.rs): runs the contract test.ba98441b(the file is tracked in the fork, so the generator was not run).crates/fluxer-proto/tests/spec_contract.rs::hand_written_models_match_spec_schemasforUserPartial,Guild,Channel,Message,Role,GuildMember: every model field is a schema property; everyrequiredproperty is a model field; a required non-nullable property is not anOption; a required nullable one is accepted asnull. Plusvendored_spec_records_its_source.typifyis not adopted (recorded with the measurements incrates/fluxer-proto/README.md).typify0.8.0 over all ofcomponents.schemasemits ~35,700 lines that do not compile (166 errors; seven schemas defined twice or infinitely recursive). Cut by hand to the 50 schemas the four key types reach it compiles, but every struct isdeny_unknown_fields, integer enums reject unknown values, andreferenced_messageloses absent-vs-null — all against the Global Constraints.How it was tested
Optionfield and add a stale allowlist entry; each was reported.vendor_spec.rs(validation, verbatim copy, SOURCE, a rejected document is not written);xtask/tests/ci_smoke.rsupdated (the two subcommands are no longer "not implemented";vendor-specwithout--fromis a usage error).cargo xtask cigreen locally on Linux.Deviations from the plan
MessageResponseSchema, notMessageResponse(the plan said to adjust).GuildResponserequires twelve properties Foundation does not model, and several required properties are nullable. The test keeps the intent with two exact allowlists (not_modelled: those twelve;not_in_spec:Guild::joined_atandGuild::unavailable, gateway-only state) whose stale entries fail, and it checks nullable required properties acceptnullinstead of demanding non-Option.curlinstead of addingreqwest(blocking) to xtask: no HTTP/TLS stack in a crate every CI run builds, and no clash with Task 6, which introducesreqwestto the workspace.xtask/src/main.rs(dispatch,--from),xtask/Cargo.toml+Cargo.lock(serde_json,time, both already workspace dependencies),xtask/tests/ci_smoke.rs,xtask/README.md,crates/fluxer-proto/README.md.For the reviewer
SOURCEnames the fork checkout's HEAD; the document itself last changed in fork commitbcfed66b(2026-10-30). One later fork commit touched schema sources the same day, so the tracked document may lag the schemas slightly; regenerating means runningpnpm openapi:generateinside the fork, which this task must not modify.fixtures/rest/guild.jsonomits four propertiesGuildResponserequires anduser_me.jsonomits manyUserPrivateResponseones. The fixtures are deliberately trimmed, so this is not treated as a bug; the contract test does not validate fixtures against the document.Closes #5
🤖 Generated with Claude Code
Independent review — Task 5 (reviewed at
ec45491)Verdict: APPROVE — 0 blocking, 4 minor. Local
cargo xtask cigreen (all steps passed, exit 0; remote runners not checked).What I verified
hand_written_models_match_spec_schemasexists and covers the six-model map. Schema names checked against the vendored file: five match the plan;MessageResponsedoes not exist,MessageResponseSchemadoes (the plan allows adjusting names).Role.namemadeOption-> fails; bogus field onGuildMember-> fails; removing anot_modelledentry -> fails; a stalenot_in_specentry -> fails.cargo xtask vendor-spec --from <path-or-url>andcargo xtask spec-checkexist as written. Re-vendoring from the fork checkout leaves the tree clean;spec/openapi.jsonis byte-identical to the fork's file (OpenAPI 3.1.0, 715 schemas, 347 paths, 1,853,768 bytes);SOURCE= fork HEADba98441b, clean.python -m http.server— success writesurl <url> <date>and the contract test still passes; a 404 and a refused connection exit 1 with curl's message and write nothing.fluxer-core/fluxer-ui; xtask gains onlyserde_jsonandtime(already workspace deps, no HTTP/TLS stack); no token-shaped strings in the vendored document; no model changes, so unknown-field/unknown-enum tolerance is untouched. Commits carryRefs #5and the co-author line; PR title/body follow the contract.crates/fluxer-proto/README.mdwith reasons. I did not re-run typify; the stated reasons (deny_unknown_fields, closed enums, lost absent-vs-null) are consistent with the document, where every checked schema hasadditionalProperties: false.Findings
CLAUDE.md(crate rules) still says "REST types are generated from the vendored OpenAPI document". The spike decided the opposite; the agent contract should be updated so later tasks do not try to generate.xtask/src/vendor_spec.rsfile_source/git_commit: any git checkout yieldsfork commit <sha>, including this repo or an unrelated one, and the sha is the checkout's HEAD rather than the commit that produced the file. A gitignored source file also reports clean (git status --porcelainprints nothing for ignored files), so the-dirtymarker can be missed.SOURCEis parsed by whitespace intests/spec_contract.rs::vendored_spec_records_its_sourceand in the xtask unit testvendoring_a_file_copies_it_verbatim_and_writes_source. Afile <path> <date>line whose path contains a space fails both; the unit test would fail on a Windows runner whose temp dir has a space in it.GuildResponseproperties sit innot_modelled, and the "non-Option" check goes through serde, so fields usingnull_to_default(e.g.features,flags,Role.color) accept anullthe document forbids. That is lenient in the direction the "never panic" rule wants; noting it so nobody reads the test as strict validation.Suggest a
follow-upissue for 1-3 before or after merge; none of them blocks.ec454914c8d5a8323f23