feat(X402-44): JSON API stability — snapshot test + contract doc + versioning rule#78
Merged
Merged
Conversation
…rsioning rule Locks `bazaar-check --log json` as a documented public API contract per ADR-004 Pillar 2. Three deliverables: - src/bazaar/json-api.md — envelope shape + per-check `detail` keys + verdict discriminator + exit-code contract + stability rules + regeneration workflow - tests/fixtures/bazaar/json-api-snapshot.json — hand-rolled canonical exemplar of one deterministic looks_correct run - tests/integration/bazaar-check-json-api.test.ts — 6 tests catch field renames, removals, additions, and reordering against the exemplar (deep-equal + per-result key-order + verdict key-order + 4-canonical-check-names invariants) Versioning rule committed: - Additive (new optional fields, new check names, new verdict.kind values, new detail.* keys) → MINOR + ### JSON API CHANGELOG entry - Shape-breaking (renames, removals, type changes, fixed-position reordering) → MAJOR + deprecation cycle + integrator notice - Exit-code contract (0 looks_correct / 2 implementation_issue / 3 upstream_issue) preserved across all minor versions; D.3's upstream_stuck will roll up to exit code 3, not a new code Docs: - README JSON API section under bazaar-check, links to the contract doc - CONTRIBUTING.md JSON API discipline section with a PR self-check No shape changes to the JSON envelope itself this PR — the exemplar captures the shape after D.4 + D.5 land, including the additive detail.variant (D.5) and well-known skip message (D.4). TomSmart_ai's mapper-integration is the named consumer this contract is committed to. Tests: 466 total pass (was 460); 6 new snapshot tests. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
7 tasks
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
X402-44 — locks
bazaar-check --log jsonas a documented public API contract per ADR-004 Pillar 2. Three deliverables land together. Lands BEFORE D.2/D.3 so those tickets are forced through the snapshot contract from the start.What this PR delivers
1. Contract doc:
src/bazaar/json-api.mdEnvelope shape, per-check
detailkeys, verdict discriminator, exit-code contract, stability rules, regeneration workflow. The canonical reference for any consumer (mapper integrations, agent filters, future bazaar-aware tools) taking a runtime dependency on the JSON output.2. Frozen exemplar:
tests/fixtures/bazaar/json-api-snapshot.jsonHand-rolled deterministic JSON capturing one canonical
looks_correctrun with all four checks passing. Regenerated only when JSON shape is intentionally changed (workflow documented in the contract doc).3. Snapshot test:
tests/integration/bazaar-check-json-api.test.ts6 tests catch the four classes of shape drift:
The deterministic fetcher in the test produces exactly the shape in the fixture; any divergence fails the test with a regenerate-snapshot instruction.
Versioning rule (committed per ADR-004 Pillar 2)
verdict.kindvalues, newdetail.*keys) → MINOR +### JSON APICHANGELOG entry0looks_correct/2implementation_issue/3upstream_issue). D.3'supstream_stuckcomposite (X402-46) will roll up to exit code 3, NOT introduce exit code 4 — verdict prose carries the granularity.Docs updates
--log jsonis a public contract" section under thebazaar-checkdocumentation, linking to the contract doc.No shape changes to the JSON envelope this PR
The exemplar captures the shape after D.4 + D.5 land, including the additive
detail.variant(D.5) and well-known skip message (D.4). This PR establishes the contract; the shape itself is unchanged.Acceptance criteria (X402-44)
tests/fixtures/bazaar/json-api-snapshot.jsonexists with current v0.3.2 JSON shape capturedtests/integration/bazaar-check-json-api.test.tsasserts the snapshot matches; tests fail on intentional shape change with a clear regenerate-snapshot instruction (file header documents the regen workflow)src/bazaar/json-api.mddocuments the contract (top-level keys, each facet's shape, versioning rule)src/bazaar/json-api.mdCHANGELOG.md[Unreleased]has a### JSON APIsubsection covering the new commitments + additive changes from D.4/D.5CONTRIBUTING.mdhas a section explaining the JSON API discipline + how to regenerate the snapshotnode:fslike PR chore: capture TomSmart_ai 19-URL production set as v0.3.2 fixture bed #69's fixture test) — confirmed via check:publish-surfaceStrict audit gate — abbreviated (user-in-loop mode)
971ab4c(PR feat(X402-42): --endpoint <paid-url> per-route 402 probe mode (D.4) #77 D.4 merged HEAD); .gitignore WIP not stagedfixfield removalWhat unblocks on merge
metadata_propagationfacet AND the snapshot test will fail-loud unless the regen + CHANGELOG entry happen togetherindexer_state+upstream_stuckverdict🤖 Generated with Claude Code