[Swagger Linter Migration] OperationIdNounVerb (origin)

[Yuchao Yan (msyyc)]

Original Swagger linter

• linter code: OperationIdNounVerb
• linter doc: operation-id-noun-verb.md

Specific Swagger checks:

• Ignore empty, non-string, and no-underscore operationId values.
• Split operationId at the first underscore.
• Treat the first segment as the noun and the second segment as the verb.
• Report when the verb contains the noun.
• If the noun ends with s, also report when the verb contains the singularized noun.

How the Swagger linter works

The Spectral rule runs on emitted Swagger/OpenAPI operation operationId fields and reports at the operationId JSON path. It compares emitted strings only; it does not inspect TypeSpec declarations. Its plural handling is permissive (Nouns?) and the diagnostic warns that fixing shipped SDK operation IDs can be breaking.

How the migrated TypeSpec linter works

The TypeSpec rule visits operations that TCGC includes in generated client/OpenAPI operation sets, skips template declarations and override customization operations omitted from OpenAPI, and resolves the AutoRest-style operation ID using TCGC client names/client locations plus explicit @operationId. It standardizes underscore-separated parts to match emitted AutoRest casing before applying the same noun and singularized-noun repetition check. Diagnostics target the TypeSpec operation declaration that emits the violating operation ID.

Migration evidence

See packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/migration.md for focused fixture evidence, the final full-corpus comparison (34/34 project overlap and 111/111 assessable diagnostics), eliminated TypeSpec-only/validator-only project sets, compile failures, and code-backed gap examples.

[Copilot]

🟡 Changes recommended

The updated rule/docs introduce a couple of user-facing consistency issues (notably the missing “breaking change” note in the diagnostic message and a casing mismatch in fixture documentation) that should be addressed before merging.

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

Pull request overview

This PR migrates the Swagger OperationIdNounVerb validator rule into a native TypeSpec lintdiff rule by aligning operationId resolution with TCGC/AutoRest emission behavior and expanding fixtures to cover additional authored shapes.

Changes:

• Update operation-id-noun-verb to resolve AutoRest-style operation IDs using TCGC client names/locations and to skip non-emitted operations (e.g., TCGC-omitted overrides).
• Add new fixtures covering explicit @operationId(...) and namespace-derived operationId scenarios, including validator vs TypeSpec diagnostic snapshots.
• Add/refresh migration documentation and fixture metadata (coverage/projection scope) for the rule.

File summaries

File	Description
packages/typespec-lintdiff/src/rules/operation-id-noun-verb.ts	Switch operationId resolution to TCGC/AutoRest-derived behavior and filter to emitted operations.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/rule.md	Update fixture metadata and document added coverage branches/cases.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/migration.md	Add detailed migration/equivalence evidence and rationale for the production fix.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/explicit-operation-id/main.tsp	New explicit @operationId(...) fixture input.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/explicit-operation-id/output.json	New explicit @operationId(...) emitted OpenAPI snapshot.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/explicit-operation-id/validator-diagnostics.json	New validator snapshot for explicit operationId case.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/explicit-operation-id/tsp-diagnostics.json	New TypeSpec diagnostics snapshot for explicit operationId case.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/explicit-operation-id/expect.json	New expected violation marker for explicit operationId case.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/namespace-operation/main.tsp	New namespace-derived operationId fixture input.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/namespace-operation/output.json	New namespace-derived emitted OpenAPI snapshot.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/namespace-operation/validator-diagnostics.json	New validator snapshot for namespace-derived case.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/namespace-operation/tsp-diagnostics.json	New TypeSpec diagnostics snapshot for namespace-derived case.
packages/typespec-lintdiff/test/fixtures/OperationIdNounVerb/namespace-operation/expect.json	New expected violation marker for namespace-derived case.

Review details

• Files reviewed: 13/13 changed files
• Comments generated: 3
• Review effort level: Lite

---

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

[Copilot]

🟡 Changes recommended

The rule’s noun/verb split logic can diverge from the upstream “split at first underscore” behavior for operationIds with multiple underscores, potentially missing diagnostics.

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

Review details

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

[Copilot]

🟢 Approval recommended

The updated rule implementation and fixtures consistently align TypeSpec diagnostics with emitted AutoRest/TCGC operationId behavior and include clear migration evidence without introducing unresolved correctness or test gaps.

Review details

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