Skip to content

[WIP][Swagger Linter Development] LroExtension - #5639

Merged
Yuchao Yan (msyyc) merged 6 commits into
feature/lintdiff-migration-newfrom
feature/lintdiff-lro-extension
Oct 10, 2026
Merged

Yuchao Yan (msyyc) merged 6 commits into
feature/lintdiff-migration-newfrom
feature/lintdiff-lro-extension

Conversation

@msyyc

@msyyc Yuchao Yan (msyyc) commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

Original Swagger linter

linter code: LroExtension

linter doc: lro-extension.md

  • Inspect OAS2 PUT, PATCH, POST and DELETE operations with an explicit 202 response.
  • Require a truthy x-ms-long-running-operation on the selected operation; an absent or false extension violates the original check.
  • Exempt GET and operations without an explicit 202 response.

The Spectral selector $.paths[*][put,patch,post,delete].responses[?(@property == '202')]^^ walks from each selected response back to its operation, where the extension is checked. The diagnostic concerns the operation's extension/missing extension, not whether its Location header actually describes polling. Copying that extension-based behavior would miss native semantic failures and duplicate existing ARM prerequisites.

Migrated native TypeSpec behavior

Mapping: LroExtension → lro-extension (tsp-lintdiff-local-linter/lro-extension). Coverage is deliberately partial, limited to supported uncovered ARM semantics.

The maintained resource-manager ruleset already owns registered resource-instance POST/PUT/DELETE response-code checks. This migration does not duplicate them. It checks PATCH and ARM-marked collection/provider POST operations with exact HTTP 202 responses, using compiler listServices, HTTP getHttpService, ARM isArmCollectionAction, and Azure Core getLroMetadata. Supported customized ArmCustomPatchAsync and ArmProviderActionAsync headers can retain a plain Location header while losing native polling metadata; those operations receive one warning on the authored operation. Semantic LRO headers/default async templates are compliant. Supported synchronous template response customizations are also covered.

The temporary mixed ARM/data-plane lintdiff runner uses service-root getArmProviderNamespace only for isolation. The documented promotion adaptation removes that guard when the official ARM ruleset supplies the audience boundary. Production logic uses compiler/HTTP/Core/ARM only: no emitter, OpenAPI extensions, TCGC, reference-string inference, or unsafe version mutation.

Polling metadata, not emitted extension overrides or historical Swagger snapshots, defines the native contract. Version attribution is assessed separately against corpus-selected API versions; this is not an all-historical-version or universal Swagger-equivalence claim.

The earlier nested-service warning regression retains one target warning for an overlapping missing-metadata operation and two for distinct operations sharing response types. The cycle-1 repair additionally marks each eligible semantic Operation visited before impure metadata resolution, including compliant operations. A real registered-package regression uses nested services that are both ARM-provider marked, a standard async provider action, and original-uri final state with no GET at that route. It now produces exactly one Azure Core no-operation-at-original-uri diagnostic, zero lro-extension diagnostics, and no other diagnostics, rather than resolving metadata twice. Eligibility, service isolation, warning severity/message, and authored Operation targets are unchanged.

Migration evidence and validation

Migration note: latest results, complete project accounting, supported-shape evidence, version attribution and limitations.

  • Scoped four-file formatting/check, package build and changed-TypeScript lint passed before the new commit.
  • Focused native tests: 17 passed (the original 16 plus the actual registered-linter regression). The original overlap-warning1 and distinct-operation-warning2 controls remain covered.
  • All four affected fixture groups passed with unchanged snapshot/expectation enforcement: 51 cases. Explicitly reviewed ambient expectations, intentional Swagger/native discrepancies, and the existing mapped-compliance advisory are preserved; this is not a claim of 51 universally equivalent or universally clean cases.
  • Required fresh full ARM corpus: 468 attempted, 462 compiled successfully, with six unchanged compile failures (DeviceProvisioningServices, TenantActionGroups, Network/Network, Quota, Resources/deployments and ServiceLinker; duplicate-body/missing-uri-param). Their details and impact are disclosed in the migration note.
  • Retained Swagger results: 39 diagnostics / 14 projects; native results: 14 diagnostics / 5 projects. Five projects overlap; nine are validator-only; none are TypeSpec-only. The 25 intentional exclusions are POST14, PUT6 and DELETE5, belonging to documented prerequisites/out-of-contract operations rather than unexplained supported-native misses.
  • The fresh representative/full corpus after the cycle-1 production repair preserved all 14 native diagnostic identities and all six known compilation failures.
  • Validation retained the prepared source profile: Core a6137cac43a727ce0c2656364fd72d50c272ee4a, integrated base adf0d2865887d9e12609d7a4d398b96211510a85, and checked-in runner settings. The fetched migration base had advanced to b4fdf202afdda010789557603b571f046f0ca70c; the branch/Core/profile were not moved or replayed.
  • The historical complete 596-case fixture baseline had 72 snapshot mismatches and three expectation mismatches previously established as noncausal. It was not rerun this cycle and is not represented as a fully green suite.
  • A fresh persistent independent local reviewer found no significant issues in the complete 57-file task diff, including the registered regression, after an actual same-reviewer follow-up. The new incremental commit changes exactly four approved files.
  • Generated corpus output was archived and restored through the exact-digest reviewed cleanup plan (971 generated changes); no generated coverage, logs, dependency manifests, Core gitlink changes or skill changes are committed.

Published source head: 9afb5818fba089835296258049ad7104e8a92c50, parent f0973f43bffa73169fdde0436566c2534bdab595, on the existing development branch.

This remains the development-stage draft. A new current-head GitHub review is pending; the earlier f097 review does not cover this commit. Official promotion draft #5652 remains unchanged at d2d665bb160a96c384daee82d91b264f98368087 with its previous f097 source pin, pending a clean new source review and an explicitly authorized incremental refresh. Neither PR is merged by this workflow.

Cover supported custom PATCH and ARM provider/collection POST responses without native polling metadata; retain existing resource status-code ownership and document partial Swagger coverage. Include native tests, strict migration fixtures, corpus evidence, and nested-service operation deduplication.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Checked-in catalog metadata remains stale, and documented synchronous compliance paths and migration-report reconciliation need coverage.

4 open findings
What changed in this PR

Migrates LroExtension to native TypeSpec semantics for uncovered ARM PATCH and collection/provider POST operations.

Changes:

  • Uses native polling metadata to validate explicit 202 responses.
  • Adds focused unit tests, fixtures, snapshots, and corpus evidence.
  • Reclassifies the migration as partial, unconstrained coverage.
File Description
packages/​typespec-lintdiff/​src/​rules/​lro-extension.ts Implements the native semantic rule.
packages/​typespec-lintdiff/​test/​rules/​lro-extension.test.ts Tests applicability, metadata, targeting, and deduplication.
packages/​typespec-lintdiff/​test/​harness/​triage-data.ts Reclassifies the validator rule.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​rule.md Documents the native contract and coverage boundary.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​migration.md Records migration and corpus evidence.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​resource.tsp Adds shared ARM fixture models.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​standard-operations.tsp Adds shared standard operations.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-sync-plain-location/​main.tsp Adds sync provider violation input.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-sync-plain-location/​expect.json Marks the sync provider violation.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-sync-plain-location/​output.json Captures emitted Swagger.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-sync-plain-location/​tsp-diagnostics.json Captures native diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-sync-plain-location/​validator-diagnostics.json Captures validator diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-async-plain-location/​main.tsp Adds async provider violation input.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-async-plain-location/​expect.json Marks the async provider violation.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-async-plain-location/​output.json Captures emitted Swagger.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-async-plain-location/​tsp-diagnostics.json Captures native diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-async-plain-location/​validator-diagnostics.json Captures validator diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-semantic-location/​main.tsp Adds compliant provider input.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-semantic-location/​expect.json Marks the provider case compliant.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-semantic-location/​output.json Captures compliant Swagger.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-semantic-location/​tsp-diagnostics.json Captures compliant native diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​provider-semantic-location/​validator-diagnostics.json Captures compliant validator output.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-sync-plain-location/​main.tsp Adds sync PATCH violation input.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-sync-plain-location/​expect.json Marks the sync PATCH violation.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-sync-plain-location/​output.json Captures emitted Swagger.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-sync-plain-location/​tsp-diagnostics.json Captures native diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-sync-plain-location/​validator-diagnostics.json Captures validator diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-async-plain-location/​main.tsp Adds async PATCH violation input.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-async-plain-location/​expect.json Marks the async PATCH violation.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-async-plain-location/​output.json Captures emitted Swagger.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-async-plain-location/​tsp-diagnostics.json Captures native diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-async-plain-location/​validator-diagnostics.json Captures validator diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-semantic-location/​main.tsp Adds compliant semantic PATCH input.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-semantic-location/​expect.json Marks semantic PATCH compliant.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-semantic-location/​output.json Captures compliant Swagger.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-semantic-location/​tsp-diagnostics.json Captures compliant native diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​custom-patch-semantic-location/​validator-diagnostics.json Captures compliant validator output.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​missing-lro-for-202/​expect.json Records the intentional native exclusion.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​missing-lro-for-202/​tsp-diagnostics.json Removes the excluded native warning.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​false-lro-extension/​expect.json Records the intentional false-extension exclusion.
packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​false-lro-extension/​tsp-diagnostics.json Removes the excluded native warning.
packages/​typespec-lintdiff/​test/​fixtures/​XmsPageableMustHaveCorrespondingResponse/​accepted-response-with-nextlink/​expect.json Reconciles ambient diagnostics.
packages/​typespec-lintdiff/​test/​fixtures/​XmsPageableMustHaveCorrespondingResponse/​accepted-response-with-nextlink/​tsp-diagnostics.json Updates ambient warning snapshots.
packages/​typespec-lintdiff/​test/​fixtures/​XmsPageableMustHaveCorrespondingResponse/​accepted-response-missing-nextlink/​tsp-diagnostics.json Updates ambient warning snapshots.
packages/​typespec-lintdiff/​test/​fixtures/​ConsistentResponseSchemaForPut/​put-200-202-different-schemas/​expect.json Removes the excluded PUT warning expectation.
packages/​typespec-lintdiff/​test/​fixtures/​ConsistentResponseSchemaForPut/​put-200-202-different-schemas/​tsp-diagnostics.json Removes the redundant PUT warning.
packages/​typespec-lintdiff/​test/​fixtures/​ConsistentPatchProperties/​scoped-get-fallback/​tsp-diagnostics.json Updates the LRO diagnostic snapshot.
packages/​typespec-lintdiff/​test/​fixtures/​ConsistentPatchProperties/​get-201-fallback/​tsp-diagnostics.json Updates the LRO diagnostic snapshot.
packages/​typespec-lintdiff/​test/​fixtures/​ConsistentPatchProperties/​async-get-fallback/​expect.json Adds the new ambient warning expectation.
packages/​typespec-lintdiff/​test/​fixtures/​ConsistentPatchProperties/​async-get-fallback/​tsp-diagnostics.json Captures the new native warning.

🧠 Review effort: Balanced


Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The checked-in validation report and its derived summaries still publish the previous coverage classification and omit the new fixtures.

1 open finding
4 resolved since last review

🧠 Review effort: Balanced

Regenerate the complete validation report after the LroExtension partial mapping and refresh its derived documentation summaries.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The implementation and evidence are internally consistent; only the non-blocking PR-description test count remains stale.

1 open finding
1 resolved since last review

🧠 Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The migration record lacks code-backed evidence for the validator-only exclusions supporting its partial-coverage conclusion.

1 open finding
1 resolved since last review

🧠 Review effort: Balanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The validation claim references a 50-file review while the current head contains 56 changed files.

0 open findings

1 resolved since last review
Previously missed (1)

In code that hasn't changed since last review

Low severity Update review claim to match 56 changed files

packages/​typespec-lintdiff/​test/​fixtures/​LroExtension/​migration.md:597

The PR description says the complete reviewed diff contains 50 files, but the current PR metadata reports 56 changed files. Please update that validation claim (or explain which six files were intentionally excluded) so the stated independent review evidence matches the current head.

🧠 Review effort: Balanced

Visit each eligible semantic operation before resolving LRO metadata so
compliant operations do not duplicate Azure Core diagnostics. Preserve
the partial ARM eligibility and authored-operation warning contract.

Add a real registered-linter regression asserting one Core diagnostic
and no LroExtension warning, and refresh the migration evidence.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The 57-file partial migration and disclosed non-green full baseline warrant final human verification despite strong focused coverage.

0 open findings

🧠 Review effort: Balanced

Yuchao Yan (msyyc) added a commit that referenced this pull request Oct 10, 2026
## Summary

Clarify Windows publication command safety for the LintDiff queue and
review loop.

- Separate read-only identity checks from short rooted staging, commit,
push, and publication steps.
- Validate multi-line PowerShell publication syntax before executing it.
- Use native Git exit codes, not stdout truthiness, for outputless
commands.
- Inspect the actual refreshed diagnostic-snapshot set instead of a
guessed file count.

## Evidence

The LroExtension workflow in #5639 completed its required review-fix
validation but stopped before staging because a large PowerShell
publication wrapper had a missing closing parenthesis. Earlier
outputless Git wrappers and a guessed five-snapshot guard also
obstructed valid work; the actual nine changed snapshots were
independently verified as diagnostic-message replacements.

The primary review loop is stopped. This independent PR changes only
skill documentation and does not resume that workflow, alter rule code,
or grant an additional correction attempt. Parser rejection still counts
as a command failure under the existing finite recovery policy, despite
zero native mutation attempts.

## Validation

Formatted only the two changed Markdown files with the existing Prettier
3.9.5 installation and identical repository configuration. Checked the
complete diff, relative documentation links, staged scope, and `git diff
--check`.

No dependency installation, submodule initialization, package build,
corpus rerun, CI retry, or additional Copilot review loop is required
for this documentation-only PR.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a
Preserve LroExtension and current base classifications and recompute the combined catalog summary.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 625c0cd9-bacc-4f9c-8b96-4ded1932a30a
@msyyc
Yuchao Yan (msyyc) merged commit 9803b83 into feature/lintdiff-migration-new Oct 10, 2026
2 checks passed
@msyyc
Yuchao Yan (msyyc) deleted the feature/lintdiff-lro-extension branch October 10, 2026 02:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants