[Swagger Linter Migration] ParametersInPointGet (origin)

[Yuchao Yan (msyyc)]

Original Swagger linter

Rule: ParametersInPointGet / RPC-Get-V1-08

Docs: https://github.com/Azure/azure-openapi-validator/blob/6243cb01c16c7535cd3b8df6f45fbeb3c095ed7f/docs/parameters-in-point-get.md

Source: https://github.com/Azure/azure-openapi-validator/blob/6243cb01c16c7535cd3b8df6f45fbeb3c095ed7f/packages/rulesets/src/spectral/functions/parameters-in-point-get.ts

The original rule checks that:

• the inspected Swagger value is a paths object
• each path is classified as a point resource path by getResourcesPathHierarchyBasedOnResourceType
• only get operations are considered
• GET query parameters named exactly api-version are allowed
• every other GET query parameter is reported at the operation parameters array

How the Swagger linter works

The Spectral function iterates each Swagger path item, asks the ARM path helper whether the URI has at least one resource hierarchy entry, and then inspects the path item's get.parameters array. It filters parameters where in === "query" and name !== "api-version", emitting one diagnostic per offending query parameter at [paths, <uri>, get, parameters].

The validator reports emitted OpenAPI operation-parameter occurrences. This PR does not copy that emitted-occurrence cardinality into TypeSpec, and it does not narrow the shared TypeSpec implementation to GET-only because the same TypeSpec rule also intentionally covers the broader staging-only ValidQueryParametersForPointOperations Swagger rule for point GET, PUT, PATCH, and DELETE.

How the migrated TypeSpec linter works

valid-query-parameters-for-point-operations visits TypeSpec operations, resolves each HttpOperation with getHttpOperation, keeps only point-operation paths recognized by the shared ARM point-path helper, and reports query parameters other than api-version on the authored parameter target. The implementation currently covers GET, PUT, PATCH, and DELETE so that ParametersInPointGet and ValidQueryParametersForPointOperations share one source-level rule.

The corpus comparison uses the existing projected TypeSpec result for the selected latest Swagger API version. The 22 TypeSpec-only projects in the GET-only ParametersInPointGet row are latest-version PUT/PATCH/DELETE diagnostics explained by the broader staging rule, not older-version-only diagnostics or false positives.

Migration evidence

The detailed migration evidence is in packages/typespec-lintdiff/test/fixtures/ParametersInPointGet/migration.md. It records the focused fixture result, report reconciliation, selected-latest-version population, full-corpus project overlap, TypeSpec-only project explanations, compile failures, diagnostic-cardinality explanation, and the conclusion that no production TypeSpec rule change is required.

Generated corpus and coverage files under packages/typespec-lintdiff/specs are excluded from this PR.

[Yuchao Yan (msyyc)]

Finding from the ParametersInPointGet migration check: we do not need a separate TypeSpec linter for ParametersInPointGet.

ParametersInPointGet is the older production Swagger rule for point GET operations only. The migrated TypeSpec rule in this PR, valid-query-parameters-for-point-operations, is the right shared implementation because it covers that GET behavior and also covers the broader staging-only Swagger rule ValidQueryParametersForPointOperations for point GET/PUT/PATCH/DELETE.

So the expected follow-up is documentation/evidence only: map ParametersInPointGet to this broader rule and explain the apparent TypeSpec-only projects as PUT/PATCH/DELETE coverage from the broader rule, not as false positives or a need for another rule.

So we could use same tsp linter rule PR: #5273