Skip to content

feat: impl catalog schema v2 - #39

Merged
aceforeverd merged 1 commit into
masterfrom
feat-schema-v2
Oct 12, 2026
Merged

aceforeverd merged 1 commit into
masterfrom
feat-schema-v2

Conversation

@aceforeverd

Copy link
Copy Markdown
Contributor

Schemas

  • variant.schema.json (new): one variant per file, with apiVersion: catalog.swiss/v2 and kind: Variant. version (semver) and releaseDate are required, plus optional deprecated and replaces.
  • metadata.v2.schema.json (new): adds defaultVariant, series and quantization. Tuning refs must be @, and the legacy version stays optional for index.json.
  • index-v2.schema.json (new): v2 models and their variant files only.
  • catalog.schema.json: adds repo and raw; catalog.yaml sets repo.

Library and build

  • hack/lib/history.js (new): one walk of master's first-parent git history, with the bytes of each change. A shallow clone is refused.
  • hack/lib/catalog.js:
    • Files are classified by content (versionFiles, variantFiles).
    • buildIndexV2() builds index-v2.json and every history.json.
    • checkIndexV2() checks the result against its schema and history.
    • revisionProblems() enforces that every change raises the version and changes something else.
    • buildIndex() publishes a v2 model's legacy tuning with ids stripped, so index.json is unchanged.
  • server/data.js and server/index.js:
    • The build and the catalog server also write and serve index-v2.json, the v2 variant files and the histories.
    • catalog.json reads tuning ids without @Version, so the site renders exactly as before.

Validators

  • validate:schema:
    • checks v1 and v2 files by content;
    • checks the v2 path and id, LWS size against nodes, and that the chart matches the engine;
    • requires defaultVariant to name a real variant and tuning to pin an existing version;
    • applies the version rule and refuses a committed history.json;
    • with --base, also refuses deleting a variant that wasn't deprecated, and new v1 files in a v2 model.
  • validate:helm and validate:images cover variant files. The image check reads a tuning ref's pinned version, from git when it isn't the current one.
  • hack/migrate-v2.js (new): migrates a model from its latest v1 file, with a --dry-run diff. It refuses any variant whose content would change.

CI and repo

  • Both workflows use fetch-depth: 0, and lint runs validate:schema --base .
  • The pre-commit hook runs validate:schema --base HEAD.
  • .gitignore ignores *.history.json under models/.
  • package.json adds the migration test to npm test.
  • README.md gains a short Schema v2 spec.

Tests: fixture-repo tests for the library, server tests for index-v2 and the catalog.json pairing, a migration test over every v1 model, and Helm selection tests for variant files. 70 node and 11 site tests pass.

Schemas
- variant.schema.json (new): one variant per file, with apiVersion: catalog.swiss/v2 and kind: Variant. version (semver) and releaseDate are required, plus optional deprecated and replaces.
- metadata.v2.schema.json (new): adds defaultVariant, series and quantization. Tuning refs must be <id>@<version>, and the legacy version stays optional for index.json.
- index-v2.schema.json (new): v2 models and their variant files only.
- catalog.schema.json: adds repo and raw; catalog.yaml sets repo.

Library and build
- hack/lib/history.js (new): one walk of master's first-parent git history, with the bytes of each change. A shallow clone is refused.
- hack/lib/catalog.js:
  - Files are classified by content (versionFiles, variantFiles).
  - buildIndexV2() builds index-v2.json and every history.json.
  - checkIndexV2() checks the result against its schema and history.
  - revisionProblems() enforces that every change raises the version and changes something else.
  - buildIndex() publishes a v2 model's legacy tuning with ids stripped, so index.json is unchanged.
- server/data.js and server/index.js:
  - The build and the catalog server also write and serve index-v2.json, the v2 variant files and the histories.
  - catalog.json reads tuning ids without @Version, so the site renders exactly as before.

Validators
- validate:schema:
  - checks v1 and v2 files by content;
  - checks the v2 path and id, LWS size against nodes, and that the chart matches the engine;
  - requires defaultVariant to name a real variant and tuning to pin an existing version;
  - applies the version rule and refuses a committed history.json;
  - with --base, also refuses deleting a variant that wasn't deprecated, and new v1 files in a v2 model.
- validate:helm and validate:images cover variant files. The image check reads a tuning ref's pinned version, from git when it isn't the current one.
- hack/migrate-v2.js (new): migrates a model from its latest v1 file, with a --dry-run diff. It refuses any variant whose content would change.

CI and repo
- Both workflows use fetch-depth: 0, and lint runs validate:schema --base <PR base>.
- The pre-commit hook runs validate:schema --base HEAD.
- .gitignore ignores *.history.json under models/.
- package.json adds the migration test to npm test.
- README.md gains a short Schema v2 spec.

Tests: fixture-repo tests for the library, server tests for index-v2 and the catalog.json pairing, a migration test over every v1 model, and Helm selection tests for variant files. 70 node and 11 site tests pass.
@aceforeverd
aceforeverd merged commit 7460780 into master Oct 12, 2026
3 checks passed
@aceforeverd
aceforeverd deleted the feat-schema-v2 branch October 12, 2026 11:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant