[Swagger Linter Migration] XmsExamplesRequired (origin)

[Yuchao Yan (msyyc)]

CONTEXT:
TCGC has related logic to map operation and its example file so I plan to reuse the logic then put the rule into TCGC. But TCGC owner said there will be refactor for tsp about example then I should be able to use the native compiler function to check example mapping for each operation. So I will block this PR for now.

Original Swagger linter

• linter code: XmsExamplesRequired
• linter doc: xms-examples-required.md

Checks performed by the original rule:

• Visits Swagger path operations for get, put, post, patch, delete, options, and head through the shared az-common Spectral ruleset.
• Reports when the operation object does not define x-ms-examples.
• Treats any defined x-ms-examples value as passing, including an empty object, because of the shipped presence-check bug.

How the Swagger linter works

The Spectral function receives an emitted OpenAPI operation object and reports at that operation's JSON path when x-ms-examples is absent. It does not validate the examples' contents, referenced files, request/response coverage, or minimum/maximum payload quality.

How the migrated TypeSpec linter works

The TypeSpec rule visits HTTP operations with the same verbs. It already accepted @extension("x-ms-examples", ...); this change also accepts @Autorest.example(...), because the autorest emitter writes those decorator entries into the emitted operation's x-ms-examples object. The diagnostic target remains the source operation so authors can fix the operation-level examples evidence directly.

External examples-dir files are intentionally not used to suppress diagnostics in this PR: modeling emitter option interpolation and version-specific file loading exactly requires separate emitter-aware work, and an unsafe broad filesystem scan was rejected during review.

Migration evidence

See migration.md for focused fixtures, final full-corpus counts, one-sided project lists, compile failures, and remaining uncertainty.

[Copilot]

🟡 Changes recommended

The rule now has a runtime import from @azure-tools/typespec-autorest, but that package is currently only a devDependency of tsp-lintdiff-local-linter, which can break consumers/environments that don’t install dev deps.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR improves the migrated xms-examples-required TypeSpec lint rule to recognize @Autorest.example(...) as valid evidence that an operation will emit x-ms-examples, aligning the rule more closely with the Swagger validator’s presence-check behavior. It also adds a dedicated fixture and expands the migration documentation to capture the remaining intentional gaps (notably external examples-dir loading).

Changes:

• Update the xms-examples-required rule to treat @Autorest.example(...) as compliant (in addition to @extension("x-ms-examples", ...)).
• Add a new autorest-example fixture case with emitted Swagger output and zero diagnostics for both engines.
• Update rule documentation and add detailed migration.md notes describing scope, evidence, and remaining known gaps.

File summaries

File	Description
packages/typespec-lintdiff/src/rules/xms-examples-required.ts	Accepts @Autorest.example(...) via getExamples(...) so operations emitting x-ms-examples through Autorest decorators are compliant.
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/rule.md	Updates rule notes and adds the new autorest-example test case to the fixture documentation.
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/migration.md	Adds a detailed migration write-up documenting semantic alignment, corpus observations, and intentional exclusions.
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/autorest-example/main.tsp	New fixture authoring @Autorest.example(...) on an operation.
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/autorest-example/expect.json	Declares the fixture expectation (violation: false).
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/autorest-example/output.json	Captures emitted Swagger showing x-ms-examples populated with a $ref entry.
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/autorest-example/tsp-diagnostics.json	Records no TypeSpec diagnostics for the fixture.
packages/typespec-lintdiff/test/fixtures/XmsExamplesRequired/autorest-example/validator-diagnostics.json	Records no Swagger validator diagnostics for the fixture.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The rule change is narrowly scoped, the runtime dependency is correctly declared as a peer dependency, and fixtures/snapshots are included to validate the new compliance path.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Lite