[clabonte]

Closes #163.

What

New Spectral rule specfuse-error-rule-name-in-code (warn). It flags a description or summary anywhere in the document that assigns or compares a snake_case rule name to code:

• error.code = template_in_use
• errors[0].code == 'page_size_over_limit'
• `code`: `slot_already_booked`
• "code": "delete_not_allowed"

Since #160 (compatibility.md §54), code is the HTTP status and the rule name goes in reason. Migrating the schema leaves prose like this behind, and nothing else checks it. Response examples are already covered: spectral:oas example validation rejects a string code.

Keeping it quiet on correct prose

• Gate: the rule runs only when components.schemas.Error.properties.code is type: integer. A project still on the old string-code shape gets §54's migration note instead of warnings.
• Underscore required: the matched value must contain one. That separates a rule name from code: integer or code = 409. The cost: a single-word rule name isn't caught.
• No suffix matches: \b before code keeps status_code and reason_code out.

The rule is implemented as a custom function (functions/openapiErrorReasonProse.js), because the gate reads components while the matches come from anywhere in the document.

Verification (local, Spectral 6.16.2)

• fixtures/error-reason-prose.yaml:
  • fires at exactly 4 places: an operation description, an operation summary, a nested 409 response description and an x-* block;
  • silent on /clean (error.reason = …), /status (code = 409, code: integer) and /otherCodes (status_code, reason_code, postal code).
• fixtures/error-reason-prose-string-code.yaml: the same prose under a string code, with 0 findings (the gate holds).
• hello-orders: 0 findings from the new rule, and the total is unchanged at 74.
  • In a copy, I injected error.code = order_locked into one referenced operation file. It reported exactly once, mapped to that file, so the multi-file $ref setup works.
• Scaffold: a grep of templates/, examples/ and samples/ finds no prose the rule would flag.
• Rule coverage: the harness passes on the fixtures. The new rule's given is $, so it always selects.
• CI: a new example-regen.yml step asserts all of the above. I ran its assertions locally and they pass.

Docs

• API Handbook §11 names the rule.
• compatibility.md:
  • §51 item 2 no longer says the rule was never forwarded.
  • §54 migration step 1 points at the rule.
  • A new "Prose lint" paragraph in §54 records the gate and the underscore choice.

🤖 Generated with Claude Code