You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Select objects containing a description field recursively.
Ignore non-string descriptions.
Normalize description/name text by trimming whitespace, removing periods, and lowercasing.
Reject a description matching an explicit string name.
Otherwise reject a description matching the containing node's string path key.
Otherwise reject the literal placeholder description.
Report at the offending description field.
How the Swagger linter works
The legacy ARM rule recursively selects description-bearing Swagger objects and compares their text with an explicit name or the object's path key. Consequently it can inspect schema/property names, HTTP verbs, parameters, and x-ms-enum.values metadata. It emits at most one finding per selected object using the ordered conditions above. Its executable ARM registration is the audience source of truth despite the documentation's broader applicability wording.
The validator counts emitted occurrences, not unique authored declarations. SQL's repeated root files and AlertsManagement's inline parameter copies therefore multiply findings. Generated or qualified schema names, client compatibility types, unused source declarations, and literal route parameters also make output nodes differ from editable TypeSpec targets. Those differences are investigated rather than recreated through emitter-dependent production logic.
The native rule checks explicit documentation obtained through compiler getDoc on named models, scalars, enums, unions, enum members, union variants, model properties, and operations. HTTP path/query/header names take precedence over compiler-resolved ordinary JSON property names. getHttpOperation supplies the effective operation verb, including inferred GET without a body and POST with a body. Missing or normalized-empty documentation remains outside this rule; status-code properties remain exempt.
Earlier changes closed missing enum-member/union-variant checks and removed the blanket key-property exemption. Enum members are iterated from the enum listener, following official documentation-required prior art because the installed compiler walker does not dispatch enum-member events. Named union variants compare their name; unnamed string variants compare their literal value, while other unnamed variants are checked only for placeholder text.
Cycle1 repairs two additional native semantic omissions confirmed during promotion review:
@route("/widgets") @doc("get") op read(): string; now warns using its inferred GET verb; a body-bearing operation documented only as post likewise warns.
@encodedName("application/json", "wire-name") @doc("wire-name") sourceName: string; now warns using its JSON wire name. Documentation matching only sourceName is compliant when JSON serialization renames it.
These are supported compiler/HTTP semantics, not emitter overrides. Explicit verbs, normalization, placeholder handling, HTTP parameter-name precedence, and authored diagnostic targets are preserved.
Each violation targets its semantic declaration. The rule does not deduplicate distinct semantic instances merely because they share a source location. It does not project versions, invoke emission, predict generated schema names, or depend on OpenAPI/emitter/SDK APIs. Valid authored warnings from older versions remain native findings; selected-version attribution is separate research evidence.
Migration evidence and validation
See migration.md for the native contract, supported-shape evidence, regenerated full corpus, verified selected-version attribution reuse, all one-sided projects, six compilation exclusions, concrete outlier explanations, and preserved research limitations. The unchanged corpus diagnostic multiset did not expose the two repaired shapes; focused native tests and emitted comparison fixtures establish those fixes.
Required cycle1 validation passed: explicit maintained-file Prettier write/check, package build, changed-TypeScript oxlint with denied warnings, 41 native predicate tests, 13 strict rule fixtures, the affected 14-case PATCH fixture group, representative and full corpus runs, and diff hygiene. Independent persistent local precommit review was clean on the complete branch diff and verified all supplied content/receipt hashes, with nine additional native probes.
The documented native contract is covered; arbitrary executable Swagger equivalence remains partial, not claimed from project overlap or raw count equality. All 1,005 generated corpus changes were archived and restored through the exact approved manifest plan. Corpus/coverage outputs and temporary fixture junctions are excluded from this PR.
Cycle2 multipart source repair
Confirmed promotion review thread PRRT_kwDOKoCXvs6rCcjD (comment4237005053) exposed a missed authored multipart part name. The native rule now uses an authored getHttpPart(program, type)?.options.name when present and otherwise the source property name, including repeated parts via compiler array metadata; JSON encoded names remain limited to ordinary non-part properties. Path/query/header precedence and status-code exemption remain intact. Renamed-part violation, source-name-only compliance, default-name JSON-isolation, meaningful-documentation, and supported scalar/array/repeated-part regressions preserve earlier inferred-verb and ordinary JSON-name fixes. Production uses public compiler/HTTP APIs only.
Validation:47 native tests,15 strict target-rule fixtures and all five genuinely affected fixture groups pass. The full current468-project corpus has462 successful projects and six preserved compiler exclusions. Complete8,499 diagnostic multisets match prior archived results, allowing conservative selected-version attribution reuse:7,501 findings/142projects. Generated corpus output was archived and exactly1,005 planned paths restored; none is included in this PR. Detailed native contract, parity limits and current corpus evidence remain in the linked migration document above.
Historical Formdata required-gate failure is preserved; explicit user authorization prospectively excluded its unchanged unmapped data-plane group without retry or edit. A separately authorized single snapshot correction only reordered seven identical warnings for preexisting listener-phase drift; no unrelated semantics changed.
Outer persistent independent local review f235a949 is clean, with actual follow-up capability and additional multiple-operation/shared/spread/repeated-part probes verified. SourceRepairCycles2/3, development ordinary corrections3/3 and task-wide reserve2/3 remain unchanged. Fresh GitHub review of this exact repair head is required before promotion.
The new fallback for unnamed, non-string variants is not covered by the new suite, even though the documented contract says these variants should run only the placeholder check. Add one violating case such as union U { @doc("description") int32 } and one compliant case such as union U { @doc("int32") int32 }; otherwise this undefined branch could start comparing the underlying type name or stop checking placeholders without a regression failure.
Document commands needed to reproduce migration test results
These pass claims are not reproducible because this migration note does not record any of the commands used for the focused tests, strict fixture validation, or corpus generation. Since the generated corpus artifacts are intentionally excluded, established migration notes preserve the exact invocations here (for example, GetCollectionOnlyHasValueAndNextLink/migration.md:44-50 and ConsistentResponseSchemaForPut/migration.md:196-204). Please add the commands, including the pinned specs checkout argument and filtering/concurrency options, so the reported counts can be regenerated.
Resolve native HTTP part metadata before JSON naming and cover scalar, array, repeated and default parts. Refresh migration evidence and the diagnosed order-only snapshot baseline.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The literal-placeholder branch must format Node name:'description' when the actual node name does not match. The legacy validator does this in its final description === "description" branch, but checkTarget always formats the supplied name; the new encoded-name fallback therefore changes the existing placeholder snapshot from description to patchDescription. Keep the actual name only when normalized name equality caused the warning.
This issue also appears on line 119 of the same file.
This snapshot change records an incorrect diagnostic message. The encoded name patchDescription does not match the normalized text Description, so the legacy validator reaches its placeholder branch and emits Node name:'description'; this expectation should remain unchanged once checkTarget formats that branch correctly.
This expected name encodes the same placeholder-branch regression as the implementation. Because description. does not match wire-name, the legacy rule's final placeholder branch reports the literal node name description, not the encoded property name.
patchDescription is not the correct legacy diagnostic name for this placeholder case. Since Description does not match the encoded node name, the validator reaches its literal-placeholder branch and reports Node name:'description'; the updated snapshot demonstrates a message-parity regression rather than a correction.
Unnamed numeric union variants are a supported emitted enum shape: getUnionAsEnum retains Number literals, and AutoRest emits each unnamed value with a stringified x-ms-enum.values[*].name. This branch leaves their node name undefined, so union Code { @doc("1") 1 } is missed even though the Swagger validator reports it. Handle Number literals as ${target.type.value} and add violating/compliant coverage (with the contract updated accordingly).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Original Swagger linter
linter code: DescriptionMustNotBeNodeName
linter doc: description-must-not-be-node-name.md
Specific checks:
Select objects containing a
descriptionfield recursively.Ignore non-string descriptions.
Normalize description/name text by trimming whitespace, removing periods, and lowercasing.
Reject a description matching an explicit string
name.Otherwise reject a description matching the containing node's string path key.
Otherwise reject the literal placeholder
description.Report at the offending
descriptionfield.How the Swagger linter works
The legacy ARM rule recursively selects description-bearing Swagger objects and compares their text with an explicit name or the object's path key. Consequently it can inspect schema/property names, HTTP verbs, parameters, and
x-ms-enum.valuesmetadata. It emits at most one finding per selected object using the ordered conditions above. Its executable ARM registration is the audience source of truth despite the documentation's broader applicability wording.The validator counts emitted occurrences, not unique authored declarations. SQL's repeated root files and AlertsManagement's inline parameter copies therefore multiply findings. Generated or qualified schema names, client compatibility types, unused source declarations, and literal route parameters also make output nodes differ from editable TypeSpec targets. Those differences are investigated rather than recreated through emitter-dependent production logic.
How the migrated TypeSpec linter works
Mapping:
DescriptionMustNotBeNodeName→tsp-lintdiff-local-linter/description-must-not-be-node-name.The native rule checks explicit documentation obtained through compiler
getDocon named models, scalars, enums, unions, enum members, union variants, model properties, and operations. HTTP path/query/header names take precedence over compiler-resolved ordinary JSON property names.getHttpOperationsupplies the effective operation verb, including inferred GET without a body and POST with a body. Missing or normalized-empty documentation remains outside this rule; status-code properties remain exempt.Earlier changes closed missing enum-member/union-variant checks and removed the blanket key-property exemption. Enum members are iterated from the enum listener, following official
documentation-requiredprior art because the installed compiler walker does not dispatch enum-member events. Named union variants compare their name; unnamed string variants compare their literal value, while other unnamed variants are checked only for placeholder text.Cycle1 repairs two additional native semantic omissions confirmed during promotion review:
@route("/widgets") @doc("get") op read(): string;now warns using its inferred GET verb; a body-bearing operation documented only aspostlikewise warns.@encodedName("application/json", "wire-name") @doc("wire-name") sourceName: string;now warns using its JSON wire name. Documentation matching onlysourceNameis compliant when JSON serialization renames it.These are supported compiler/HTTP semantics, not emitter overrides. Explicit verbs, normalization, placeholder handling, HTTP parameter-name precedence, and authored diagnostic targets are preserved.
Each violation targets its semantic declaration. The rule does not deduplicate distinct semantic instances merely because they share a source location. It does not project versions, invoke emission, predict generated schema names, or depend on OpenAPI/emitter/SDK APIs. Valid authored warnings from older versions remain native findings; selected-version attribution is separate research evidence.
Migration evidence and validation
See migration.md for the native contract, supported-shape evidence, regenerated full corpus, verified selected-version attribution reuse, all one-sided projects, six compilation exclusions, concrete outlier explanations, and preserved research limitations. The unchanged corpus diagnostic multiset did not expose the two repaired shapes; focused native tests and emitted comparison fixtures establish those fixes.
Required cycle1 validation passed: explicit maintained-file Prettier write/check, package build, changed-TypeScript oxlint with denied warnings, 41 native predicate tests, 13 strict rule fixtures, the affected 14-case PATCH fixture group, representative and full corpus runs, and diff hygiene. Independent persistent local precommit review was clean on the complete branch diff and verified all supplied content/receipt hashes, with nine additional native probes.
The documented native contract is covered; arbitrary executable Swagger equivalence remains partial, not claimed from project overlap or raw count equality. All 1,005 generated corpus changes were archived and restored through the exact approved manifest plan. Corpus/coverage outputs and temporary fixture junctions are excluded from this PR.
Cycle2 multipart source repair
Confirmed promotion review thread
PRRT_kwDOKoCXvs6rCcjD(comment4237005053) exposed a missed authored multipart part name. The native rule now uses an authoredgetHttpPart(program, type)?.options.namewhen present and otherwise the source property name, including repeated parts via compiler array metadata; JSON encoded names remain limited to ordinary non-part properties. Path/query/header precedence and status-code exemption remain intact. Renamed-part violation, source-name-only compliance, default-name JSON-isolation, meaningful-documentation, and supported scalar/array/repeated-part regressions preserve earlier inferred-verb and ordinary JSON-name fixes. Production uses public compiler/HTTP APIs only.Validation:47 native tests,15 strict target-rule fixtures and all five genuinely affected fixture groups pass. The full current468-project corpus has462 successful projects and six preserved compiler exclusions. Complete8,499 diagnostic multisets match prior archived results, allowing conservative selected-version attribution reuse:7,501 findings/142projects. Generated corpus output was archived and exactly1,005 planned paths restored; none is included in this PR. Detailed native contract, parity limits and current corpus evidence remain in the linked migration document above.
Historical Formdata required-gate failure is preserved; explicit user authorization prospectively excluded its unchanged unmapped data-plane group without retry or edit. A separately authorized single snapshot correction only reordered seven identical warnings for preexisting listener-phase drift; no unrelated semantics changed.
Outer persistent independent local review
f235a949is clean, with actual follow-up capability and additional multiple-operation/shared/spread/repeated-part probes verified. SourceRepairCycles2/3, development ordinary corrections3/3 and task-wide reserve2/3 remain unchanged. Fresh GitHub review of this exact repair head is required before promotion.