[Yuchao Yan (msyyc)]

Test-target follow-up (October 21, 2026)

Replaced ignored diagnostic target expectations with native source markers and supported position assertions in 6f682caa3. All 16 canonical cases remain, including namespace and per-API-version targets. The dependency-closure build, focused changed-test typecheck, root formatting/lint, and diff hygiene passed. The full test project retains 37 baseline diagnostics (39 before this correction); it is not claimed clean. Final-head CI was pending and was not awaited.

This test-only update does not complete the sample split or remove the #5783 prerequisite described below. Earlier test counts describe their historical revisions.

Valid-only follow-up and sample prerequisite (October 21, 2026)

Published focused namespace-selection guidance and a rule-only release note in 94ec55905. The actual final snippets were checked once in explicit public ARM context: missing selection warns, v3 warns, and v6 has zero diagnostics. The 16 canonical rule tests, generated docs, root format/lint and diff hygiene passed. This is not standalone or continuous documentation coverage.

The sample upgrades, emitted snapshots, v6 fixtures, local-reference validation and explicit fixture synchronization are published separately in prerequisite #5783, validated at its own main/compiler revisions (34 sample/reference tests passed). Legacy/version-compatibility suppressions remain tied to this rule's enabled-warning change. The sample delta is still present in this PR until #5783 lands and main can be incorporated; the split is not yet complete, and this PR is not declared ready. No merge is performed by this workflow.

Test-responsibility cleanup

Applied the guidance merged in #5572 from the #5507 review. Removed framework suppression and imported-library exclusion tests while retaining registry selection, overrides, authored targets, and the rule-owned ARM-service guard. No production code changed.

Current cleanup validation: mise exec -- pnpm --filter @azure-tools/typespec-azure-resource-manager exec vitest run test\rules\arm-common-types-version.test.ts passed 17 tests. Repository pnpm format, pnpm lint, and git diff --check passed. Earlier validation counts below describe historical revisions, not this cleanup; the full test suite was not rerun.

Summary

Extend the existing @azure-tools/typespec-azure-resource-manager/arm-common-types-version rule to require the latest effective ARM common-types selection. Following Mark and Timothée's review, this PR no longer adds a separate use-latest-version-of-common-types rule or traverses HTTP payloads and legacy type usages.

Intentional behavior change: arm-common-types-version is already enabled in the resource-manager ruleset. Its new latest-version warnings therefore apply wherever that existing rule is enabled; they are not opt-in. Services selecting older versions must update @armCommonTypesVersion or intentionally suppress the existing rule for compatibility. Existing suppressions cover both missing-configuration and outdated-selection diagnostics.

Current implementation

Consolidation commit: 1722f99264f78dea42a5f084ca936a7b77161b47.

• Preserve the existing missing-explicit-configuration diagnostic, message, and namespace target. When configuration is incomplete, report that diagnostic rather than adding warnings for implicit defaults.
• Check ARM service namespaces directly, without HTTP operation enumeration.
• Read the latest available version from the common-types registry, whose versions are ordered newest first; no hard-coded latest version or filename map.
• Check the effective selection for each API version, honoring enum-member overrides and namespace defaults. Report outdated selections on the API-version enum member, or on the namespace for an unversioned service.
• Report through context.reportDiagnostic, preserving rule suppression and project-location filtering.
• Remove the separate rule, registration, disabled ruleset entry, usage traversal, version-history traversal, reference checking, and resolution diagnostics.
• Rewrite documentation around focused service-namespace version selection. Update generated listings, the ARM inventory, RPC coverage description, and changelog.

Deliberately narrower migration scope

This is version-selection guidance, not full behavioral equivalence with the Swagger/lintdiff reference checker. A service selecting the latest version can still use a legacy symbol that resolves to an older common-type record. The consolidated rule intentionally does not detect that condition, inspect payload visibility or historical types, or validate common-type resolution. Existing legacy/deprecation warnings overlap with this concern but do not cover every former traversal case. The emitter's independent validation is unchanged.

The user explicitly approved this consolidation and the enabled-ruleset behavior change on September 20. The immutable lintdiff source is not being repaired or rewritten.

Original Swagger linter

• Rule: LatestVersionOfCommonTypesMustBeUsed.
• Implementation.
• Documentation.
• ARM ruleset registration.

The Swagger rule scans emitted $ref strings matching ARM common-types paths and compares their file/version against a filename-to-latest-version map. It reports at each emitted reference, unlike the consolidated TypeSpec rule's namespace/API-version targets. The historical lintdiff report records stale-map false positives for valid v6 networksecurityperimeter.json and managedidentitywithdelegation.json references; those maps are not copied here.

Source provenance and destination

• Source lintdiff ID: LatestVersionOfCommonTypesMustBeUsed.
• Source local rule slug: latest-version-of-common-types-must-be-used.
• Immutable source SHA: be310817b95a8c2fba64b7906e23624ec38efab0.
• Source branch: feature/lintdiff-latest-version-common-types, restored on September 15 at that exact SHA without changing source contents.
• Original source worktree: C:\dev\worktrees\lintdiff-latest-version-common-types-source, recorded as clean during promotion.
• Pinned source rule.
• Pinned migration report.

Destination: @azure-tools/typespec-azure-resource-manager, consolidated into its existing arm-common-types-version rule. This behavior depends on ARM provider namespaces and common-types metadata; placing it in azure-core would reverse the package dependency direction. The previous unpublished promotion name, use-latest-version-of-common-types, is removed rather than retained as an alias.

Fixture-to-native test mapping

Native tests now live in packages/typespec-azure-resource-manager/test/rules/arm-common-types-version.test.ts. Fixture links below use the unchanged restored source ref. Removed coverage is marked explicitly rather than presented as equivalent.

Original lintdiff fixture	Native vitest case	Coverage note
older-common-types	reports an older namespace selection for each API version	Checks inherited v3 selection and each API-version target.
latest-common-types	does not emit when the service namespace has a common type version without version on enum values	Latest namespace selection applies to both API versions.
version-override-older-common-types	reports an older enum-member override of a latest namespace selection	Older override warns; the member inheriting latest remains valid.
version-override-latest-common-types	accepts a latest enum-member override of an older namespace selection	Does not warn about an overridden namespace default.
legacy-location-parameter	Removed: out of scope	Individual legacy parameter references are no longer inspected.
legacy-managed-identity	checks only the selected version, not legacy common-type usages	Intentionally asserts no warning for latest selection with a legacy identity in a standard ARM resource operation.
versioned-legacy-property	Removed: out of scope	No legacy-property availability traversal.
repeated-legacy-reference	Removed: out of scope	No operation/reference diagnostic counting or deduplication.
payload-visibility-excludes-legacy	Removed: out of scope	No payload or visibility traversal.
N/A (existing behavior)	emits diagnostic when a version in the enum is missing a common type version	Preserves missing-configuration message and namespace target without implicit-version warnings.
N/A (existing behavior)	emits diagnostic when unversioned service namespace is missing a common type version	Preserves unversioned missing-configuration diagnostics.
N/A	does not emit when the service version enum has a common type version on all enum values	Latest explicit selections on all API versions.
N/A	does not emit when an unversioned service selects the latest version	Valid unversioned selection.
N/A	uses the latest version from the common-types registry	Virtual future common-types library adds v7; v6 then warns.
N/A	reports an older unversioned namespace selection: %s	Parameterized v3, v4, and v5 cases.
N/A	checks explicit per-version selections without a namespace selection	Mixed current/outdated API versions.
N/A	supports string version selections	Preserves the supported string decorator form.
N/A	checks each ARM service independently	One outdated service and one current service.
N/A	does not check non-ARM services or Azure library namespaces	Excludes a non-ARM service and Azure.Core/Azure.ResourceManager library namespaces.
N/A (framework-only coverage removed)	Not ported (framework-only)	Suppression and imported-library diagnostic filtering belong to the compiler/linter framework, not this rule's version-selection predicate.
N/A (ruleset)	enables consolidated ARM common-types version guidance	Existing rule remains enabled; removed rule has no registration or ruleset entry.

The former projection, dependency-history, metadata-layout, and resolution-error regressions were removed with their implementation. They are not claimed as coverage of the consolidated selection-only rule.

Validation

Consolidation follow-up (September 20)

• ARM and rulesets package builds passed.
• Final focused ARM rule suite: 21 tests passed, including a future-v7 registry regression. Ruleset validation suite: 6 tests passed.
• Broader ARM/rulesets run: 494 passed and two unrelated cold setup hooks timed out; both affected files subsequently passed all 18 tests with reduced concurrency. An additional focused run also encountered a cold setup timeout; the final direct-package run with explicit timeouts passed all 21 rule tests.
• Correct documentation example compiled with the consolidated rule enabled and no diagnostics.
• ARM documentation regenerated; existing unrelated missing-documentation warnings remain.
• Repository formatting, lint, spelling, and git diff --check passed. pnpm validate:pr --skip-build --skip-test --verbose completed successfully, with a warning that the branch is behind main and explicit skips for full build/test/regen-docs; affected-package builds, tests, and docs regeneration were run separately. Its committed-diff checks ran before this consolidation commit, so they are not presented as a final-head diff audit.
• The existing int:azure-specs label triggered External Integration for the new head: run 35491909140, currently pending. The previous head's successful integration is not evidence for the new enabled warnings.
• No lintdiff corpus rerun was performed. The pinned migration report remains historical evidence for the broader source implementation, not proof of parity with this intentionally narrower rule.

Historical context

Earlier follow-ups replaced whole-service mutation with direct version metadata, fixed reference-resolution reporting through the linter, restored source links, and added migration/inventory documentation. Those changes and their historical validation remain in the commit/review history; traversal-related implementations and tests are superseded by this consolidation. The pinned source report and its corpus results are unchanged.

The original promotion's pnpm validate:pr attempt hung and was stopped; that historical limitation is distinct from the September 20 successful run with the explicit skips described above.

Promotion sync policy

The source lintdiff rule and migration report remain immutable at the pinned SHA. The September 20 user-approved consolidation is an explicit destination-scope change, not a source repair or a claim of complete migration parity. Any future repair of the source rule still requires explicitly reopening that work.

Review cleanup (October 19, 2026)

Removed the synthetic future-version fixture that invoked CommonTypes.Private.armCommonTypesVersions; public defaults and explicit version-selection controls remain. Required validation exposed a pre-existing merge inconsistency: the lockfile/catalog came from the main merge parent but the compiler pin was retained from the other parent. Restored only core to the exact already-merged main-parent revision (not current main), with byte-identical lockfile/catalog and no dependency-manifest edits. Frozen ARM-closure installation and the dependency-closure build now pass. The earlier full-workspace install subsequently stopped in an unrelated local Python prepare step; a full-workspace install is not claimed to pass.

Published in d22e03b. Fresh focused validation: 16 tests passed, package production typecheck, root pnpm format, root pnpm lint, and diff hygiene passed. The full test TypeScript project retains pre-existing diagnostics (19 before, 18 after); the baseline test-file comparison found no new diagnostics, accounting explicitly for moved tests and any removed fixture. This is not a claim that the full test TypeScript project is error-free or that pending CI has passed. These current file-layout/coverage statements supersede earlier descriptions of the removed test files; historical validation remains historical.

[github-actions]

All changed packages have been documented.

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

Show changes

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

Extend arm-common-types-version to warn when an ARM service or API version selects an older common-types version, while preserving the existing warning for missing explicit version configuration.,> ,> Latest-version warnings are now active wherever this existing rule is enabled, including the resource-manager ruleset. Update @armCommonTypesVersion to the latest version in Azure.ResourceManager.CommonTypes.Versions, or suppress @azure-tools/typespec-azure-resource-manager/arm-common-types-version when an older version is required for compatibility.,> ,> The rule checks effective version selections only.

[github-actions]

📦 Package size report

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

14 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-azure-resource-manager	192.89 KB → 193.28 KB	+399 B (+0.2%)	1.15 MB → 1.15 MB	+2.07 KB (+0.2%)
@azure-tools/azure-http-specs	143.53 KB → 143.53 KB	—	1.20 MB → 1.20 MB	—
@azure-tools/typespec-autorest	87.87 KB → 87.87 KB	—	424.17 KB → 424.17 KB	—
@azure-tools/typespec-autorest-canonical	7.42 KB → 7.42 KB	—	26.00 KB → 26.00 KB	—
@azure-tools/typespec-azure-core	136.55 KB → 136.55 KB	—	733.30 KB → 733.30 KB	—
@azure-tools/typespec-azure-examples	80.15 KB → 80.15 KB	—	383.36 KB → 383.36 KB	—
@azure-tools/typespec-azure-portal-core	36.26 KB → 36.26 KB	—	242.62 KB → 242.62 KB	—
@azure-tools/typespec-azure-rulesets	6.00 KB → 6.00 KB	—	35.20 KB → 35.20 KB	—
@azure-tools/typespec-client-generator-core	248.86 KB → 248.86 KB	—	1.32 MB → 1.32 MB	—
@azure-tools/typespec-go	264.28 KB → 264.28 KB	—	1.35 MB → 1.35 MB	—
@azure-tools/typespec-java	20.22 MB → 20.22 MB	—	22.51 MB → 22.51 MB	—
@azure-tools/typespec-metadata	15.91 KB → 15.91 KB	—	62.26 KB → 62.26 KB	—
@azure-tools/typespec-python	42.58 KB → 42.58 KB	—	166.02 KB → 166.02 KB	—
@azure-tools/typespec-ts	530.76 KB → 530.76 KB	—	2.67 MB → 2.67 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.}

[pkg-pr-new]

Open in StackBlitz

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

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

commit: 6f682ca

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website

[catalinaperalta]

looks good, just some comments to improve clarity

[Yuchao Yan (msyyc)]

CI follow-up in db29d80:

• Updated 21 current ARM samples to select common-types v6 and regenerated their OpenAPI snapshots. Snapshot changes are exclusively v5-to-v6 common-type references; legacy references without v6 support remain unchanged.
• Added scoped, justified suppressions to the 10 grandfathered samples and the older-version private-links compatibility example. Their generated schemas remain unchanged.
• All 40 sample tests pass without snapshot recording, and all 21 playground sample checks pass. Repository formatting, lint, and diff checks pass.
• The consolidated arm-common-types-version rule remains enabled. No weakening of its checks or test assertions was introduced.

External Integration is a separate, still-unresolved rollout dependency: existing azure-rest-api-specs services select v3-v5 and now fail under warnings-as-errors (see https://github.com/Azure/typespec-azure/actions/runs/35491909140). The user explicitly chose to fix repository samples only and defer external-spec compatibility changes. This commit does not claim to resolve that check; downstream compatibility updates or scoped suppressions must land before it can pass.

[microsoft-github-policy-service]

Hi @Yuchao Yan (@msyyc). Your PR has had no update for 14 days and it is marked as a stale PR. If it is not updated within 14 days, the PR will automatically be closed. If you want to refresh the PR, please remove the stale label.

[Pan Shao (pshao25)]

All these files are copied from specs repo? How do we keep consistence? Why do we need these files here?

[Timothee Guerin (timotheeguerin)]

there is a CI check/script that syncs them but please have this change as a separate pr, this is not related to a new linting rule

[Yuchao Yan (msyyc)]

Yes—the seven files match packages/samples/common-types/existing/v6 byte for byte. They let emitted sample $refs resolve; the rule itself reads native metadata. Prerequisite #5787 now synchronizes both v6 locations and checks byte equality. The sample delta here still awaits that prerequisite landing.
Timothee Guerin (@timotheeguerin) after 5787 merged, this PR could be simplified.