checker: report a shared-schema change once, and list where else it applies - #1265

Implements the #1256 decision, on top of #1263 (the walk memo) and #1264 (the diff carrying component names).

What changes

A schema that several properties of one payload reference is one schema, so a change in it, or below it, is one change to the operation's contract. Each check now reports it once, at one of those properties, and says where else it applies:

the `customerId` response's property pattern `^[0-9]+$` was added for the status `200` (shared schema: Id, also at `userId`)
    A change in a schema that several properties of this payload reach is reported once per check, at one of
    those properties: it is a single change to the contract, and it applies wherever the schema is used.

JSON and YAML carry the full list as a field, so a consumer never has to parse the text:

"sharedSchema": {
  "name": "Id",
  "properties": ["customerId", "userId"]
}

main already drops userId here with no explanation, since #1263 merged; v1.33.0 reported both. This PR keeps the single record and puts the information back.

• The text names one other property and counts the rest, as in and 1 more, because these paths are long. The field lists every one.
• One entry per reference, not per path. Each reference to the schema is listed at the path the walk took to it. In a nested spec the number of paths can run to millions; the number of references stays small. The longest list on the GitHub REST API description is 44.
• A change below the shared schema names it too, and lists the same properties with the rest of the change's path appended.
• Fingerprints do not change. The fingerprint hashes the arguments, not the text, so the shared schema is context only. A formatter test pins this. docs/FINGERPRINT.md said the text was hashed, and is corrected.
• The label says "shared schema", because the schema named is the innermost one several references reach, which is not always the one that changed.
• Deduplication is per check. Every check walks the payload itself, so a shared schema that gained a property and a pattern produces one finding from each check. Each change and each operation also still gets its own line.

A fix to #1264 in the diff

In OpenAPI 3.1 a description beside a $ref overrides the component's, and the parser applies it to a copy of the component. The copy is not the components.schemas entry, so #1264's lookup by schema object missed it and recorded no name. The name now comes from the $ref when that lookup misses. A $ref to a schema inside a component stays unnamed.

The copies keep the component's children, so what several references reach can be an inline child of the component. That is the case on the spec reported in #1252: ten references reach Company's inline users array. Such a schema is named after the component the walk passed through to reach it, so those findings name Company. Without the diff fix they would name MarketPartner, a schema that only references Company. A test fails without either half.

Measured

Adding one optional property to simple-user in the GitHub REST API description (13 MB):

On the spec from #1252, with one property added inside the cycle: 31 findings on main and here, all 31 now naming Company with ten references each. Fingerprints and finding counts are identical to this branch before the list was added, on both specs.

Known limitation

The walk deduplicates by schema object, and a description beside each $ref gives each reference its own copy. So a property added to Address, where billing and shipping both $ref it with a description, is still reported twice with no explanation. Without the descriptions it is reported once, with the list. That matches v1.33.0, so nothing regresses. Treating the copies as one schema would mean keying the walk on the component name, which could hide a real difference between copies. That needs a separate decision.

Follow-up, not in this PR

Grouping across operations, which is where most of the remaining volume is: of the 358 findings above, 355 are the same property spread over 298 operations. The output has to keep one record per operation, because the fingerprint covers the operation and tools that consume the output key changes by it. So that grouping belongs in presentation: a schema identity field on every change, and a schemas view next to the existing endpoint grouping in the formatters.

Tests

• userId and customerId share Id: one finding listing both, and three properties render as "and 1 more" (shared_schema_two_properties_*).
• A schema reached through two parents, each through two properties, is one finding listing the reference through the other parent (shared_schema_two_parents_*).
• A change below the shared schema lists the same properties with its own path appended.
• Two checks on the same shared schema each report once.
• An inline shared schema behind description overrides is named after its component (shared_schema_override_*), and a $ref straight into a component stays unnamed (shared_schema_unnamed_*).
• The diff names a $ref with an override and leaves a $ref into a component unnamed. Mutation-checked.
• The published output schema validates a sample that emits sharedSchema.

Full suite, go vet, golangci-lint and gofmt pass.

For the release notes

• Fingerprints of the dropped duplicates disappear, so a review decision stored against one of them does not carry forward. Surviving findings keep their fingerprints.
• A new sharedSchema field in JSON and YAML output.
• An --err-ignore entry written against the old text of a shared-schema finding no longer matches, because the text now carries the schema and the other properties.

🤖 Generated with Claude Code