[Swagger Linter Migration] XmsResourceInPutResponse (origin)

[Yuchao Yan (msyyc)]

Original Swagger linter

• linter code: XmsResourceInPutResponse
• linter doc: xms-resource-in-put-response.md

The original rule:

• selects PUT operations under both paths and x-ms-paths;
• examines the first response schema under status 200, then 201;
• accepts x-ms-azure-resource: true on the response schema or an inline allOf ancestor;
• reports at the PUT operation path when no marked response schema is found.

How the Swagger linter works

The Spectral helper uses getReturnedSchema and recursively inspects inline allOf objects. It does not dereference external $ref ancestry. As a result, standard ARM resources inheriting marked common-types schemas can produce validator-only findings. This PR records that discrepancy rather than copying it into semantic TypeSpec behavior.

How the migrated TypeSpec linter works

The rule visits namespace-level and interface operations owned by an ARM provider namespace, including child namespaces, using upward getArmProviderNamespace lookup. For HTTP PUT it chooses the first model body for 200 then 201 and accepts either a registered ARM resource (getArmResource) or explicit x-ms-azure-resource: true metadata in the base-model hierarchy. Resource-shaped manual responses lacking both are diagnosed on the response model. Global operations, non-PUT operations, and non-model bodies are ignored.

This corrects three concrete defects in the imported rule: registered resources were mistaken for non-resources, all interface operations were skipped, and descendant namespace search could miss child-provider operations while classifying unrelated global operations.

Migration evidence

See migration.md for the emission matrix, seven focused fixtures, reviewed validator discrepancy, full 468-project corpus results, project overlap and one-sided lists, compile failures, selected-version handling, diagnostic identities, and remaining uncertainty.

[Copilot]

🟢 Approval recommended

The rule fix uses the correct ARM library APIs and the expanded fixture suite (including the documented validator discrepancy case) appears consistent with the stated migration intent.

Pull request overview

This PR completes the migration of the Swagger validator rule XmsResourceInPutResponse into the typespec-lintdiff local linter by repairing the rule’s ARM semantics and expanding fixture coverage to reflect the intended TypeSpec behavior (including documented, intentional discrepancies vs Swagger’s $ref ancestry limitations).

Changes:

• Fix the rule implementation to correctly scope to ARM provider-owned operations and to treat registered ARM resources as compliant (via getArmProviderNamespace + getArmResource).
• Add/refresh focused fixtures to cover interface-owned operations, nested provider namespaces, global PUT exclusion, and the validator-only $ref ancestry discrepancy case.
• Add migration evidence documentation and update the fixture suite description.

File summaries

File	Description
packages/typespec-lintdiff/src/rules/xms-resource-in-put-response.ts	Fixes provider scoping and resource recognition using ARM library APIs; diagnoses non-compliant manual resource-shaped PUT responses.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/rule.md	Updates the documented semantic matrix and test-case table to match the repaired rule + new fixtures.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/migration.md	Adds detailed migration/equivalence evidence and documents intentional validator discrepancies.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-nested-namespace-missing-azure-resource/main.tsp	New fixture: PUT under a child namespace of the provider namespace returning an unmarked resource-shaped model.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-nested-namespace-missing-azure-resource/output.json	Snapshot output for the nested-namespace fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-nested-namespace-missing-azure-resource/tsp-diagnostics.json	TypeSpec diagnostics snapshot for the nested-namespace fixture (includes the migrated rule diagnostic).
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-nested-namespace-missing-azure-resource/validator-diagnostics.json	Validator diagnostics snapshot for the nested-namespace fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-nested-namespace-missing-azure-resource/expect.json	Expected violation outcome for the nested-namespace fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-interface-missing-azure-resource/main.tsp	New fixture: PUT declared in an interface returning an unmarked resource-shaped model.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-interface-missing-azure-resource/output.json	Snapshot output for the interface PUT fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-interface-missing-azure-resource/tsp-diagnostics.json	TypeSpec diagnostics snapshot for the interface PUT fixture (includes the migrated rule diagnostic).
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-interface-missing-azure-resource/validator-diagnostics.json	Validator diagnostics snapshot for the interface PUT fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-interface-missing-azure-resource/expect.json	Expected violation outcome for the interface PUT fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-arm-resource/main.tsp	New fixture: standard ARM template PUT returning a registered TrackedResource to guard against prior false positives.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-arm-resource/output.json	Snapshot output for the registered-resource fixture (shows external $ref inheritance that triggers the validator-only discrepancy).
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-arm-resource/tsp-diagnostics.json	TypeSpec diagnostics snapshot for the registered-resource fixture (should not include the migrated rule diagnostic).
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-arm-resource/validator-diagnostics.json	Validator diagnostics snapshot for the registered-resource fixture (captures the known validator $ref limitation).
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/put-arm-resource/expect.json	Expected non-violation outcome plus recorded validator-only diagnostic count for the discrepancy case.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/global-put-ignored/main.tsp	New fixture: global PUT outside provider namespace to ensure the selector doesn’t match unrelated global operations.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/global-put-ignored/output.json	Snapshot output for the global PUT fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/global-put-ignored/tsp-diagnostics.json	TypeSpec diagnostics snapshot for the global PUT fixture (no migrated-rule diagnostic expected).
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/global-put-ignored/validator-diagnostics.json	Validator diagnostics snapshot for the global PUT fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/global-put-ignored/expect.json	Expected non-violation outcome and ambient diagnostic counts for the global PUT fixture.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/patch-ignored/tsp-diagnostics.json	Updates PATCH fixture diagnostics snapshot to reflect additional ambient warnings now emitted.
packages/typespec-lintdiff/test/fixtures/XmsResourceInPutResponse/patch-ignored/expect.json	Updates PATCH fixture expected ambient diagnostic counts accordingly.

Review details

• Files reviewed: 25/25 changed files
• Comments generated: 0
• 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 logic changes are narrowly scoped, align with documented intent, and are backed by expanded focused fixtures (including the validator-only discrepancy case).

Review details

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

[Copilot]

🟡 Changes recommended

The migration evidence doc contains a concrete example snippet that doesn’t match the checked-in fixture output, which should be corrected to keep the recorded equivalence evidence internally consistent.

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

Review details

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