feat: add consolidated records JSON, independent of any release tag#63
Merged
Conversation
scripts/build-records.js did not exist in this repo. It lives in aveproject/ave-site instead, with stale pre-org-move default paths (../bawbel/ave/records) and a JS-wrapped window.RECORDS output -- exactly the "site owns the real data" coupling CONTEXT.md's framing discipline exists to prevent. Wrote a new, canonical version here, porting the validation/sort logic rather than duplicating a second consolidation path against a second copy of records/. - node scripts/build-records.js: reads records/, validates against schema/ave-record-1.1.0.schema.json, excludes drafts unless --include-drafts, sorts by severity then ave_id, writes a bare JSON array (dist/ave-records-v1.1.0.json) plus a manifest (schema_version, record_count, generated_at, source) - dist/ was gitignored; removed that entry since these specific generated files need to be committed and reachable via raw.githubusercontent.com with zero additional infrastructure - Seeded the initial dist/ output in this PR so the artifact exists immediately rather than waiting on the first records/ change - README.md and docs/specs/ave-implementer-guide.md's "Pattern 2 -- Bundled offline" sections pointed at a v1.1.0 GitHub Release asset that CHANGELOG.md's own text says has never been cut. Added the raw.githubusercontent.com path as the always-current option; the release-based path stays as a future secondary distribution point, not the only one. Also fixed a stale "51 records" count in the implementer guide while in that section. CI: .github/workflows/regenerate-records-json.yml triggers on push to develop touching records/**, regenerates both dist/ files, and opens a PR if they changed. Does not push directly to develop or main: both branches require a PR + approving review + signed commits with no bypass for the Actions bot (confirmed via the repo's own rulesets before writing this), so a direct-commit-back design would have silently failed. This keeps existing branch protection unmodified and routes the regeneration through the same review path as everything else in this repo.
…apshot The previous version of this PR named the always-current output dist/ave-records-v1.1.0.json -- a version-numbered filename that was actually mutable, regenerated on every records/ change regardless of schema version. That's inconsistent with how schema/ already handles this exact tension (ave-record.schema.json as the always-current alias, ave-record-1.1.0.schema.json as the frozen, permanent canonical), and the inconsistency isn't just stylistic: the day schema v1.2.0 ships, either a new v1.2.0.json appears and the v1.1.0.json URL already hardcoded into this guide silently stops being current with no warning, or the filename never changes and starts serving records whose schema_version doesn't match what the URL claims. Both are avoidable. - scripts/build-records.js now writes two pairs by default: dist/ave-records-latest.json (+ manifest), overwritten every run, and dist/ave-records-v<version>.json (+ manifest), written once per schema version and left untouched on every subsequent run if it already exists on disk. Verified: running the script twice produces an identical md5 on the versioned file while latest.json's manifest timestamp still updates. - README.md and docs/specs/ave-implementer-guide.md's "Pattern 2" sections repointed at ave-records-latest.json for the always-current case, with the versioned snapshot offered separately for anyone who deliberately wants to pin - The CI workflow's PR body no longer hardcodes v1.1.0.json in its description, and its top comment explains the freeze-once semantics This reconciles with ave-api's own dist/ave-records-latest.json convention (confirmed against that repo directly) rather than leaving two different URLs for the same "always current" concept. ave-api itself has no code yet (repo just created) -- nothing to change there. All 59 records still validate; full fixture-conformance suite (236 tests) passes.
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
1 participant
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.
Summary
Two things didn't match the brief's assumptions, confirmed via discovery before writing any code:
scripts/build-records.jsdoesn't exist in this repo. It lives inaveproject/ave-siteinstead, with stale pre-org-move default paths (../bawbel/ave/records) and a JS-wrappedwindow.RECORDSoutput -- exactly the "site owns the real data" couplingCONTEXT.md's framing discipline exists to prevent. Wrote a new, canonical version here (ported the validation/sort logic, not duplicated), rather than "extending" a script that isn't in this repo.The generator
node scripts/build-records.js: readsrecords/, validates againstschema/ave-record-1.1.0.schema.json, excludes drafts unless--include-drafts, sorts by severity thenave_id, writes a bare JSON array (dist/ave-records-v1.1.0.json) plus a manifest (schema_version,record_count,generated_at,source)dist/was gitignored -- removed that entry, since these specific files need to be committed and reachable viaraw.githubusercontent.comwith zero additional infrastructure (this is the brief's primary stated goal)dist/output in this PR so the artifact exists immediatelyDocs
README.mdanddocs/specs/ave-implementer-guide.md's "Pattern 2 -- Bundled offline" sections pointed at a v1.1.0 GitHub Release asset thatCHANGELOG.md's own text says has never been cut. Added theraw.githubusercontent.compath as the always-current option; the release-based path stays as a future secondary distribution point, not the only one. Also fixed a stale "51 records" count in the implementer guide while in that section.CI
.github/workflows/regenerate-records-json.ymltriggers on push todeveloptouchingrecords/**, regenerates bothdist/files, and opens a PR if they changed. It does not push directly todevelopormain-- confirmed via this repo's own branch rulesets before writing the workflow that both branches require a PR + approving review + signed commits with no bypass for the Actions bot, so a direct-commit-back design would have silently failed in production. This keeps existing branch protection unmodified and routes regeneration through the same review path as everything else in this repo.Test plan
node scripts/build-records.js-- 59/59 records validated and writtenpython3 -m json.tool dist/ave-records-v1.1.0.json-- valid JSONls records/ | wc -l, not the brief's assumed 69)python3 scripts/validate_records.py/check_fixtures.py/pytest tests/ -x -q-- all still pass (59 valid, 236 tests)gh api repos/aveproject/ave/rules/branches/{main,develop}that both branches share identical protection before designing the CI workflow around it