[Swagger Linter Migration] XmsPageableForListCalls

[Yuchao Yan (msyyc)]

Original Swagger linter

• linter code: XmsPageableForListCalls
• linter doc: xms-pageable-for-list-calls.md

The original rule checks that:

• the selected OpenAPI object is a GET operation on an ARM collection path;
• the path passes the validator's isListOperationPath classification;
• selector-boundary paths ending in } or /default remain excluded;
• x-ms-pageable exists with a truthy value; and
• missing or falsy x-ms-pageable values produce `x-ms-pageable` extension must be specified for LIST APIs..

How the Swagger linter works

The ARM Spectral ruleset selects GET operations on ARM paths, excluding selector-boundary paths that end in } or /default, and invokes xms-pageable-for-list-calls.ts with the OpenAPI operation object and its Spectral path. The function reads the path key from paths.path[1], delegates collection classification to isListOperationPath, and then tests the operation's x-ms-pageable value for truthiness. It reports against the selected GET operation path when that value is absent or falsy.

The validator does not inspect response schemas or verify that a nextLink property exists. The migration therefore preserves the emitted-OpenAPI behavior rather than adding response-shape requirements. Raw validator results can contain repeated occurrences for emitted API-version/files; migration evidence compares stable operation identities and does not copy that emitted-file duplication into TypeSpec diagnostics.

Source TypeSpec lintdiff rule

• Validator rule id: XmsPageableForListCalls
• Local lintdiff rule: tsp-lintdiff-local-linter/xms-pageable-for-list-calls
• Canonical validator slug: xms-pageable-for-list-calls
• Source branch: feature/lintdiff-xms-pageable-for-list-calls
• Checked source commit: eb284b1a7327f39dc75af49c314b7755bc2f2867
• Source worktree: C:\dev\worktrees\lintdiff-xms-pageable-for-list-calls
• Source rule: xms-pageable-for-list-calls.ts

The source worktree had no uncommitted rule changes. The user-marked done lintdiff source was not modified during promotion.

Destination analysis

The rule is promoted to @azure-tools/typespec-azure-resource-manager. Its source imports ARM provider helpers, limits diagnostics to ARM provider namespaces, and classifies ARM resource collection routes. Fixture metadata declares Applies to: Resource Manager (ARM) and the migration report uses the resource-manager ruleset. Azure Core is not a viable alternative because preserving these semantics would require a prohibited dependency from Core to the ARM library or duplicating ARM provider behavior.

The official name is shortened from the validator id to list-operation-missing-pageable, following the subject-oriented TypeSpec lint naming convention. The rule is explicitly registered as false in the ARM ruleset so promotion makes it available without immediately adding diagnostics to existing service specifications.

How the promoted TypeSpec linter works

The ARM rule visits emitted operations and skips uninstantiated operation/interface templates. It uses getArmProviderNamespace so operations in both the provider namespace and child namespaces are included, resolves HTTP metadata with getHttpOperation, and applies the Swagger helper's dotted-provider-tail and segment-parity collection-path heuristic. Non-GET operations, dynamic provider paths, singleton paths, and /default paths are ignored.

For matching collection GETs, the rule accepts a truthy authored OpenAPI x-ms-pageable extension. It also accepts TypeSpec list metadata only when getPagingOperation resolves a next-link property, matching what AutoRest can emit as x-ms-pageable. Otherwise it emits one warning targeted at the TypeSpec operation. This intentionally avoids Swagger's repeated emitted-file occurrences while preserving one diagnostic per semantic operation.

Fixture-to-native test mapping

Original lintdiff fixture	Native vitest case	Coverage note
compliant-with-template/main.tsp	it("allows a standard ARM list operation template")	Standard ARM list template emits pageable metadata.
decorated-custom-list/main.tsp	it("reports a custom ARM list operation without pageable metadata")	Custom @armResourceList operation remains non-pageable.
nested-provider-namespace/main.tsp	it("reports an ARM collection GET in a child provider namespace")	Child namespace inherits ARM provider membership.
explicit-pageable-extension/main.tsp	it("allows an explicit truthy x-ms-pageable extension")	Truthy authored extension is compliant.
falsy-pageable-extension/main.tsp	it("reports a falsy x-ms-pageable extension")	Falsy extension preserves validator truthiness behavior.
list-without-next-link/main.tsp	it("reports a list operation with page items but no next link")	@pageItems without @nextLink cannot emit pageable metadata.
list-without-pageable/main.tsp	it("reports raw ARM collection GETs but ignores point and default paths")	Covers top-level/resource-URI collection violations and singleton/default exclusions.
operations-path/main.tsp	it("reports the ARM operations endpoint as a collection path")	Preserves the validator's /operations classification.
selector-boundaries/main.tsp	it("ignores dynamic provider paths and uninstantiated templates")	Covers dynamic-provider and non-emitted template boundaries.

Migration evidence

The checked-in migration.md records focused fixtures, real-service project comparison, the latest full-corpus counts, compile-failure exclusions, emitted-occurrence duplication, and remaining uncertainty.

Validation

• Focused native rule tests: 9 passed.
• ARM package tests: 390 passed.
• Azure rulesets tests: 4 passed.
• ARM dependency-closure build, package build, package lint, docs regeneration, Prettier checks, repository format, and repository lint passed.
• Best-effort validate:pr passed build, lint, format, spelling, and 3,225 tests; two unrelated playground sample tests (Tracked Resource and Tenant Resource) exceeded their existing 10-second timeout. Final affected-package docs regeneration and targeted tests were rerun after synchronizing with origin/main.

Promotion sync policy

If review finds a semantic gap in the done lintdiff rule, this promotion should be blocked until the user explicitly reopens lintdiff repair. Promotion-only adaptation issues can be fixed here without modifying the source rule.

NOTE: heavy

[github-actions]

All changed packages have been documented.

• ✅ @azure-tools/typespec-azure-resource-manager
• ✅ @azure-tools/typespec-azure-rulesets

Show changes

@azure-tools/typespec-azure-resource-manager - feature ✏️

Add the list-operation-missing-pageable lint rule for ARM collection GET operations that do not define TypeSpec paging metadata.

@azure-tools/typespec-azure-rulesets - feature ✏️

Add the list-operation-missing-pageable lint rule for ARM collection GET operations that do not define TypeSpec paging metadata.

[github-actions]

📦 Package size report

✅ No notable package size changes compared to the base branch.

13 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-azure-resource-manager	177.01 KB → 177.33 KB	+326 B (+0.2%)	1.07 MB → 1.07 MB	+1.34 KB (+0.1%)
@azure-tools/typespec-azure-rulesets	5.28 KB → 5.34 KB	+65 B (+1.2%)	33.16 KB → 33.37 KB	+214 B (+0.6%)
@azure-tools/typespec-java	13.51 MB → 13.51 MB	-19 B (-0.0%)	15.04 MB → 15.04 MB	—
@azure-tools/azure-http-specs	146.76 KB → 146.76 KB	—	1.16 MB → 1.16 MB	—
@azure-tools/typespec-autorest	81.23 KB → 81.23 KB	—	396.61 KB → 396.61 KB	—
@azure-tools/typespec-autorest-canonical	7.42 KB → 7.42 KB	—	26.00 KB → 26.00 KB	—
@azure-tools/typespec-azure-core	130.84 KB → 130.84 KB	—	709.84 KB → 709.84 KB	—
@azure-tools/typespec-azure-portal-core	42.46 KB → 42.46 KB	—	193.15 KB → 193.15 KB	—
@azure-tools/typespec-client-generator-core	237.09 KB → 237.09 KB	—	1.27 MB → 1.27 MB	—
@azure-tools/typespec-go	261.39 KB → 261.39 KB	—	1.34 MB → 1.34 MB	—
@azure-tools/typespec-metadata	15.91 KB → 15.91 KB	—	62.26 KB → 62.26 KB	—
@azure-tools/typespec-python	42.22 KB → 42.22 KB	—	164.91 KB → 164.91 KB	—
@azure-tools/typespec-ts	540.59 KB → 540.59 KB	—	2.60 MB → 2.60 MB	—

_{Packed = gzipped .tgz published to npm. Unpacked = total extracted size. 🆕 added, 🗑️ removed. Packages from the core/ submodule are not included.
🔴 grew · 🟢 shrank — only changes of at least 512 B and 0.5% are marked.}

[Copilot]

🟢 Approval recommended

The rule implementation and coverage look consistent with existing ARM linter patterns, and the remaining feedback is non-blocking (documentation wording/maintainability).

Pull request overview

Promotes the Swagger validator rule XmsPageableForListCalls into the native ARM linter as list-operation-missing-pageable, ensuring ARM collection GET operations on list paths emit x-ms-pageable (or equivalent TypeSpec paging metadata), while keeping the rule disabled by default in the ARM ruleset.

Changes:

• Added the list-operation-missing-pageable linter rule (implementation + rule documentation) to @azure-tools/typespec-azure-resource-manager.
• Added a dedicated Vitest suite covering ARM list-path classification, template/dynamic-path exclusions, and extension truthiness behavior.
• Registered the rule in docs/README and in the resource-manager ruleset with a default of false.

File summaries

File	Description
website/src/content/docs/docs/libraries/azure-resource-manager/reference/linter.md	Adds the new rule to the published ARM linter rule list.
packages/typespec-azure-rulesets/src/rulesets/resource-manager.ts	Registers the new rule in the ARM ruleset (disabled by default).
packages/typespec-azure-resource-manager/test/rules/list-operation-missing-pageable.test.ts	Adds native rule tests covering compliant/noncompliant list GET shapes and exclusions.
packages/typespec-azure-resource-manager/src/rules/list-operation-missing-pageable.ts	Implements the rule logic for detecting ARM collection GETs missing pageable metadata.
packages/typespec-azure-resource-manager/src/rules/list-operation-missing-pageable.md	Adds end-user rule documentation and examples.
packages/typespec-azure-resource-manager/src/linter.ts	Wires the new rule into the ARM package linter export.
packages/typespec-azure-resource-manager/README.md	Lists the new rule in the package README rule table.
.chronus/changes/promote-xms-pageable-for-list-calls-2026-09-02.md	Adds a changelog entry for the new rule promotion.

Review details

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

---

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/typespec-azure-resource-manager@5379

npm i https://pkg.pr.new/@azure-tools/typespec-azure-rulesets@5379

commit: 9d05280

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website

[Copilot]

🟡 Changes recommended

The new rule’s diagnostic message omits the explicitly-authored truthy x-ms-pageable extension remediation path that the rule already accepts, which can mislead users.

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

Review details

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

[Copilot]

🟢 Approval recommended

The rule implementation, shared helper extraction, documentation, and targeted test coverage are consistent with existing patterns and appear complete.

Review details

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