Repository navigation
feat(Conformance): require an included key in answers to include - #415
Merged
Merged
Conversation
Owner
Author
|
The failing check is the Audit step ( Generated by Claude Code |
thomasfosterau
force-pushed
the
issue-256-included-on-include
branch
from
October 22, 2026 00:13
48fb7a2 to
6479594
Compare
thomasfosterau
enabled auto-merge
October 22, 2026 00:53
Add `spec/document/included-on-include` (JSON:API 1.1 §Fetching Includes): every 2xx answer to a read carrying `include` must have a top-level `included` array, `[]` when nothing is included. The rule reads the kit's compound probes and sends a bare `?include=` to each endpoint declaring `include`, since presence is the signal. It skips when no such request drew a 2xx. The canned baseline answers `included: []` to a supplied empty `include`. Closes #256 Closes #232 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ZgiUeCy5QxSz5oQt2gT1H
thomasfosterau
force-pushed
the
issue-256-included-on-include
branch
from
October 22, 2026 00:57
6479594 to
a3de719
Compare
8 tasks done
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.
Summary
Adds the conformance rule for JSON:API 1.1 §Fetching Includes: "If an endpoint supports the
includeparameter and a client supplies it: the server's response MUST be a compound document with anincludedkey — even if thatincludedkey holds an empty array."spec/document/included-on-include(MUST,src/internal/conformance/spec.ts, afterno-duplicate-resources). It reads the compound probesdocumentProbesalready sends (?include=<inline-linkage relationships>). It also sends a bare?include=to every read endpoint that declaresinclude. A supplied emptyincludeasks for nothing, so its answer has to carryincluded: [], which tests the empty-array case directly. That follows the fix: answer a bare?include=and an empty related to-one with anincludedkey (follow-up to #257) #266 decision that presence ofincludeis the signal (comment on feat(Conformance): a rule that a response to?include=carries anincludedkey, even empty #256). A probe counts when its URL carriesincludeat all, including apathsURL that already has one. Each 2xx answer must have a top-levelincludedarray. A finding names the URL and the top-level members it did find. A response to a request withoutincludeis never checked for the key. The rule reportsSkippedwhen no endpoint declaresinclude, or when no request carryingincludedrew a 2xx.src/Conformance.test.ts). The canned baseline now answersincluded: []to a supplied but emptyinclude. A server that dropsincludedfrom answers toincludefails exactly this rule (broken, which also checks that nothing else fails). A server that leaves out only the empty array gets one finding per bare?include=probe. The baseline passes over 4 probes, and its bare responses (noincluded) are not counted. A server that refuses everyincludewith 400 skips the rule.docs/conformance.md: rule count 61 → 62 (55spec, 7profile; recounted after rebasing onto trunk). §3 Document structure lists the rule and describes the extra probe.Passedover 8, 16 and 16 probes, checked locally), so their known-failure lists are unchanged.?include=probe already tests theincluded: []case cheaply. Probing a relationship that resolves to nothing would mean searching the responses for empty linkage.Closes #256
Closes #232 (its last remaining item: the builders were fixed in #257 / #266)
Verification
pnpm install --frozen-lockfile: passedvp run build: passedvp check: passed (0 errors; no new lint warnings in the changed lines)vp run check(sources, type-level tests, examples, emitted declarations): passedvp run -r test:unit: passed. In the full run, twotest/entry-points.test.tscases timed out at 5s while sibling worktrees were loading the machine. Rerun alone: 25/25 passed.src/Conformance.test.ts: 444/444 passed.vp run docgen(every JSDoc@examplecompiled and executed): passedfallow audit --base origin/trunk: gate verdictpass(only inherited findings remain)Changeset
.changeset/conformance-included-on-include.md: minor (a new conformance rule, so a run against a server that omits the key now fails)Notes
?include=(empty) as absent and omitsincludednow fails this rule. That matches the spec text and fix: answer a bare?include=and an empty related to-one with anincludedkey (follow-up to #257) #266's decision. If the owner reverses fix: answer a bare?include=and an empty related to-one with anincludedkey (follow-up to #257) #266 (treating[]as absent), drop the bare-probe part of the rule.#fetching-includes), with the idspec/document/included-on-includethat the issue proposed.https://claude.ai/code/session_018ZgiUeCy5QxSz5oQt2gT1H
Generated by Claude Code