build(schema): build lib/settings.schema.json instead of committing it - #415
Merged
Merged
Conversation
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The schema build is consistently integrated across testing, packaging, publishing, validation, and documentation paths.
Review effort: Balanced
Findings: None
What changed in this PR
Moves the published settings schema from tracked generated output to a build artifact while preserving it in packaged releases.
Changes:
- Builds the schema before tests, fuzzing, packaging, and publishing.
- Reads the schema at runtime in tests to keep fresh checkouts typecheckable.
- Updates release validation, CI, documentation, and generated-file machinery.
| File | Description |
|---|---|
.gitignore |
Ignores the built schema. |
.github/SECURITY.md |
Documents schema packaging guarantees. |
.github/scripts/changed-sections.ts |
Updates the untracked lib/ rationale. |
.github/scripts/gen-settings-schema.ts |
Creates lib/ before schema generation. |
.github/scripts/generated.ts |
Removes the schema from committed outputs. |
.github/scripts/package-smoke.ts |
Builds the schema before packing. |
.github/scripts/release-pipeline.ts |
Requires schema in packaged commits. |
.github/workflows/auto-fix.yml |
Removes schema drift auto-fixing. |
.github/workflows/checks.yml |
Builds schema in relevant test jobs. |
.github/workflows/nightly-fuzz.yml |
Builds schema before fuzzing. |
.github/workflows/post-green.yml |
Includes schema in packaged builds. |
.github/workflows/update-release-pr.yml |
Builds schema before prerelease publishing. |
.github/workflows/update-release.yml |
Builds and publishes the schema artifact. |
AGENTS.md |
Records the new build-artifact rule. |
CONTRIBUTING.md |
Updates contributor commands and release details. |
docs/reference/library.md |
Documents built schema distribution. |
docs/start/examples.md |
Links to the packaged major-tag schema. |
lefthook.yml |
Removes obsolete schema-freshness wording. |
lib/settings.schema.json |
Removes the generated schema from source control. |
package.json |
Builds schema before tests and fuzzing. |
release-please-config.json |
Enables major-tag updates in examples. |
test/docs/library-examples.test.ts |
Reuses the shared schema path. |
test/docs/readme.test.ts |
Reads the built schema at runtime. |
test/e2e/fuzz.ts |
Routes replay commands through the build script. |
test/e2e/generators.ts |
Loads the built schema lazily. |
test/package-json.test.ts |
Uses the runtime schema reader. |
test/published-schema.test.ts |
Uses the shared schema reader. |
test/schema-corpus.test.ts |
Compiles the runtime-loaded schema. |
test/scripts/generated.test.ts |
Removes schema from tracked generated files. |
test/scripts/release-pipeline-build.test.ts |
Updates packaged-tree assertions. |
test/scripts/release-pipeline-fixture.ts |
Adds schema to package fixtures. |
test/scripts/release-pipeline.test.ts |
Tests required packaged schema files. |
test/settings-schema.ts |
Adds the shared runtime schema reader. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Vivswan
force-pushed
the
wt/schema-off-main
branch
from
September 22, 2026 09:47
930a65a to
66d91a5
Compare
Contributor
File size check0 over a hard cap (fails), 32 warning(s).
Split the file, wrap the line, shorten or exempt the comment, or list the path in 5 managed file(s) skipped; repo-platform owns them. |
Vivswan
force-pushed
the
wt/schema-off-main
branch
from
September 22, 2026 10:14
66d91a5 to
5ac650c
Compare
Vivswan
force-pushed
the
wt/schema-off-main
branch
from
September 22, 2026 10:18
5ac650c to
6851d34
Compare
Vivswan
force-pushed
the
wt/schema-off-main
branch
from
September 22, 2026 10:49
6851d34 to
738706a
Compare
Vivswan
force-pushed
the
wt/schema-off-main
branch
from
September 22, 2026 10:52
738706a to
c95e872
Compare
lib/settings.schema.json is untracked and gitignored beside lib/index.js and lib/pkg/, and every packaged commit off main now carries it as a required built file. The test and fuzz scripts, the e2e-smoke job, the package smoke, and the packaging and publish jobs run build:schema before anything loads or packs the schema. The drift machinery (the generated-output table row, the auto-fix schema branch, the schema-check job, the release hook's byte check) goes with the committed file. The $schema hints and the $id are unchanged; the examples page links the schema at the moving major tag, which release-please now rewrites.
Vivswan
force-pushed
the
wt/schema-off-main
branch
from
September 23, 2026 01:05
c95e872 to
763f65e
Compare
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Repository instructions still recommend a fresh-checkout test command that now fails before generating the schema.
Get a fresh assessment by requesting another Copilot review.
Review effort: Balanced
Findings: 1
Open (1)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
lib/settings.schema.jsonon mainbuild:check, auto-fix, and theschema-checkjoblib/index.jsandlib/pkg/vX.Y.Z,v2,latest)release-pipeline.ts)bun run test,bun run fuzz, the e2e-smoke and nightly fuzz jobs, the package smoke, and the packaging and publish jobs runbuild:schemafirsttscresolves at typecheckreadSettingsSchema()at run time (test/settings-schema.ts), so a checkout that has not built it still typechecks; a missing file fails naming the fix (bun run build:schema)Depends on
mainURL this PR removes.How
.gitignoregainslib/settings.schema.jsonbesidelib/index.js; the generator createslib/on a fresh checkout.testandfuzzscripts runbuild:schemafirst;e2e-smoke,nightly-fuzz, and the package smoke build it before the fuzzer orbuild:lib.test:e2eis unchanged:test/e2e/run.tsnever loads the schema.PACKAGED_PATHSandREQUIRED_BUILT_FILESinclude the schema;post-green.ymland both npm publishers runbuild:schema;update-release.ymldrops thegit diff --exit-codebyte check, which an untracked file never trips.generated.tsandauto-fix.yml; theschema-checkjob is deleted.blob/mainschema link in examples.md would 404 and now names thev2tag with anx-release-please-majormarker;release-please-config.jsonlists the page. The other pages say "built" where they said "committed".bun run testbuilds the schema first;bun run build:schemaalone orbun run buildalso writes it. A barebun teston a fresh checkout does not.Proof
Local, targeted:
bun run typecheckwithlib/deleted entirelybun run build:schemainto a missinglib/bun run knip,bun run lint,bun run lint:yaml,bun run build:checkbun run test <readers, test/docs, generated, auto-fix-allowlist, release-pipeline x2, generators.test>with the schema deleted firstbun run test:e2e --sections labelsbun .github/scripts/package-smoke.tswith the schema deleted firstbun run fuzz --iterations 1 --seed 2with the schema deleted firstRed proof: with the file deleted and
bun run build:schemaremoved from thetestscript,bun run test test/published-schema.test.tsfails with ENOENT onlib/settings.schema.json; restored, it passes.Technical details
$schemahints): README, getting-started, snapshot, andsrc/flows/snapshot.tsare unchanged: they name the raw URL at the moving major tag, which points at packaged commits, and those carrylib/.$id): the$idstays the HEAD raw URL by owner decision. HEAD ismain, so after this PR that URL stops serving the file, as the catalog's oldmainURL does; consumers fetch through the hints (and, once Point github-settings-as-code at its latest release asset SchemaStore/schemastore#6396 lands, the release asset), not the$id.test/docs/guides.test.ts): carries../../lib/settings.schema.jsononly inside a synthetic fixture page for the links-leaving-docs guard, not a real doc link; left as is..gitignore;.github/scripts/gen-settings-schema.ts(mkdirSyncforlib/);lib/settings.schema.jsonremoved from the index.package.json(test,fuzz);test/e2e/fuzz.ts(the printed replay commands go throughbun run fuzz);CONTRIBUTING.md(the replay recipe).checks.yml: thecheckjob builds it throughbun run test, so a failing generator fails the Test step;schema-checkdeleted;e2e-smokebuilds it before the fuzzer.nightly-fuzz.ymlgets the same step..github/scripts/package-smoke.tsbuilds it beforebuild:lib: the tarball'sfileslist and the./settings.schema.jsonexport need it..github/scripts/release-pipeline.ts(PACKAGED_PATHS,REQUIRED_BUILT_FILES, the refusal text);post-green.yml's build step;update-release-pr.ymlandupdate-release.yml(build:schema && build:lib; the byte check dropped).generated.ts,test/scripts/generated.test.ts, and every list inauto-fix.yml(header, trigger paths,git add, case arm, error message, commit subjects); thelefthook.ymlcomment.test/settings-schema.ts(the new reader);published-schema,schema-corpus,package-json,docs/readme,docs/library-examples, ande2e/generatorsread through it; the release-pipeline tests and fixture carry the schema in the packaged tree.git diff origin/main...HEAD -M --numstat: 33 files, +131 / -4227. Of the deletions, 4128 arelib/settings.schema.jsonitself; the code and prose delta is +131 / -99.BEGIN_COMMIT_OVERRIDE
build(schema): build lib/settings.schema.json instead of committing it
lib/settings.schema.json is untracked and gitignored beside lib/index.js and lib/pkg/, and every packaged commit off main now carries it as a required built file.
The test and fuzz scripts, the e2e-smoke job, the package smoke, and the packaging and publish jobs run build:schema before anything loads or packs the schema.
The drift machinery (the generated-output table row, the auto-fix schema branch, the schema-check job, the release hook's byte check) goes with the committed file.
The $schema hints and the $id are unchanged; the examples page links the schema at the moving major tag, which release-please now rewrites.
END_COMMIT_OVERRIDE