Skip to content

docs(spec): 用 #5757 的实测事实刷新 gen:openapi 豁免的 why #6949

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-project-manager merged 1 commit into from
Aug 9, 2026
Merged

docs(spec): 用 #5757 的实测事实刷新 gen:openapi 豁免的 why #6949

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 21 additions & 5 deletions packages/spec/scripts/check-generated.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,13 +238,29 @@ const UNGATED_GENERATORS: ReadonlyArray<{ gen: string; why: string }> = [
// #5744 that names a reconciliation with no second party: the document
// carries no route section at all — built-in routes are produced at serve
// time by the package that mounts them (#5588 ruling C, #5078, ADR-0076), so
// there is nothing here to compare against a route table. What IS still
// ungated is staleness against `src/api`: nothing fails when a contract
// schema changes and the artifact is not regenerated. Coherence is covered
// (the generator self-checks before writing, #5168) — currency is not.
// there is nothing here to compare against a route table. Coherence is
// covered (the generator self-checks before writing, #5168); currency this
// aggregate still does not verify. #5757 measured what that omission costs
// and the answer was nothing — staleness here is unreachable, not merely
// unpunished — so "add a gate" was ruled not planned. The `why` carries the
// measurement so the next reader does not re-file it.
{
gen: 'gen:openapi',
why: 'the OpenAPI document is generated but nothing compares its components.schemas against src/api — a stale artifact fails nothing (it IS self-checked for coherence at write time, #5168, and since #5744 it describes no routes to reconcile)',
why:
'nothing here compares the document\'s components.schemas against src/api — but per the #5757 ' +
'measurement a stale artifact is not merely unpunished, it is unreachable on every canonical path. ' +
'Staleness cannot outlive one build of this package: `json-schema/**` is a turbo build OUTPUT and is ' +
'gitignored, so it is never a task input; `build` declares no `inputs`, so it hashes every git-tracked ' +
'file in the package; and everything this generator reads sits in there (the `src/**` closure reached ' +
'through `src/api`, these scripts, the manifest). That input surface is a SUBSET of the build task\'s, ' +
'so any edit able to make the artifact stale is exactly the edit that busts the cache — and `build` ' +
'runs the generator unconditionally (`gen:schema && gen:openapi && tsup`). Deleting the artifact does ' +
'not even bust the cache: the next build restores it byte-identically (measured, FULL TURBO). What a ' +
'stale copy could mislead is bounded too — the served document holds 0 $refs into components.schemas, ' +
'leaving the nine contract schemas an unreferenced island (#6797). It IS self-checked for coherence at ' +
'write time (#5168), and since #5744 it describes no routes to reconcile. Gating it would also be ' +
'dormant: CI runs this aggregate only as `--reconcile-only` (lint.yml), and a full run sits after ' +
'`pnpm build` — green by construction, the #4177/#4232 class.',
},
{ gen: 'gen:sbom', why: 'the SBOM is a release artifact, regenerated at publish time rather than checked in' },
];
Expand Down
Loading