Add `decorator-requires-scope` validation for @convenientAPI and @clientOption by iscai-msft · Pull Request #5119 · Azure/typespec-azure

iscai-msft · 2026-07-30T18:11:00Z

Summary

Adds a new onValidate-phase validation (decorator-requires-scope) that warns when TCGC decorators that require a language scope are used without one or with an invalid scope.

Decorators checked:

@convenientAPI — must be scoped to "java" and/or "csharp" (the only emitters that use this information)
@clientOption — must be scoped to any specific language

This subsumes the previous inline client-option-requires-scope diagnostic with a centralized validation approach that runs during the $onValidate phase.

Changes:

New src/validations/decorators.ts with validateDecoratorScopes() function
New decorator-requires-scope paramMessage diagnostic in lib.ts
Removed old inline scope check from $clientOption decorator
Updated all tests to use proper "java" scope for @convenientAPI
Updated all references from client-option-requires-scope to decorator-requires-scope

Fixes #3751

Related specs prs:
https://github.com/Azure/azure-rest-api-specs-pr/pull/29828
Azure/azure-rest-api-specs#45196

github-actions · 2026-07-30T18:13:58Z

❌ There is undocummented changes. Run chronus add to add a changeset or click here.

The following packages have changes but are not documented.

❌@azure-tools/azure-http-specs
❌@azure-tools/typespec-java

The following packages have already been documented:

✅ @azure-tools/typespec-client-generator-core

Show changes

`@azure-tools/typespec-client-generator-core` - feature ✏️

Add decorator-requires-scope validation that warns when @convenientAPI is used without a "java" or "csharp" scope, and when @clientOption is used without any scope. This subsumes the previous client-option-requires-scope diagnostic.

pkg-pr-new · 2026-07-30T18:21:08Z

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/azure-http-specs@5119

npm i https://pkg.pr.new/@azure-tools/typespec-client-generator-core@5119

npm i https://pkg.pr.new/@azure-tools/typespec-java@5119

commit: b884b18

azure-sdk-automation · 2026-07-30T18:25:32Z

You can try these changes here

🛝 Playground	🌐 Website

Chenjie Shi (tadelesh)

Seems a big breaking. Could you please check if any spec or spector test need to apply this breaking?

iscai-msft · 2026-08-03T19:03:10Z

Seems a big breaking. Could you please check if any spec or spector test need to apply this breaking?

It's not very breaking, went through the specs and these are the only changes
Azure/azure-rest-api-specs#45196
https://github.com/Azure/azure-rest-api-specs-pr/pull/29828

Emit a warning when @convenientAPI is used without a language scope parameter. The decorator should always be scoped to a specific language (e.g., "java", "csharp") since convenience API behavior is typically language-specific. Uses the same pattern as the existing client-option-requires-scope diagnostic — the warning fires directly in the decorator implementation. Also updates existing tests to use scoped @convenientAPI calls. Closes #3751 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

…toption

…toption Adds a new onValidate-phase validation that warns when: - @convenientAPI is used without a "java" or "csharp" scope - @clientoption is used without any language scope This subsumes the previous inline client-option-requires-scope diagnostic with a centralized validation approach. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

Only @convenientAPI(true) requires java/csharp scope. Opting out with @convenientAPI(false) is safe for any language and doesn't need scope. Revert azure-http-specs change since those use @convenientAPI(false). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

Keep scope only on tests that specifically test cross-emitter scoping behavior. Tests that just use @convenientAPI(false) to opt out don't need a scope since the validation now skips false values. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

…API and emitter option check - @convenientAPI and @protocolAPI both require java/csharp scope (true or false) - Add @protocolAPI to decorator scope validation - Add unnecessary-emitter-option diagnostic for non-java/csharp emitters using generate-convenience-methods or generate-protocol-methods - Scope all test/spec usages appropriately Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

…lidation Replace namespace-walking validation in $onValidate with the compiler's DecoratorValidatorCallbacks pattern. Each decorator (, , ) now returns { onTargetFinish } to report scope diagnostics directly, which is the preferred approach per the compiler's validation hooks. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

Validate generate-convenience-methods/generate-protocol-methods at SDK context creation time instead of in $onValidate. This is more streamlined since the emitter name and options are already available in that context. Removes the now-empty validations/decorators.ts file. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

…tor-requires-scope.md Co-authored-by: Chenjie Shi <tadelesh.shi@live.cn>

Chenjie Shi (tadelesh)

LGTM. Please help to fix the ci before merge.

Weidong Xu (weidongxu-microsoft)

The new validation has two substring-matching gaps that let JavaScript bypass the intended checks, and the diagnostic documentation contradicts the implemented behavior.

Weidong Xu (weidongxu-microsoft) · 2026-08-07T06:02:55Z

+          .split(",")
+          .map((s) => s.trim().toLowerCase());
+        const hasValidScope = parsedScopes.some((s) =>
+          VALID_SCOPES.some((allowed) => s.includes(allowed)),


Scope matching is too permissive. includes accepts scopes such as "javascript", "notjava", and "java, python". The last case applies the decorator to Python too, but no diagnostic is emitted because one token contains java. Negation patterns such as "!(python, csharp)" are also misclassified. Please parse the scope with the existing scope parser and require every effective positive scope to be exactly java or csharp.

Weidong Xu (weidongxu-microsoft) · 2026-08-07T06:02:56Z

+
+  // Warn if non-java/csharp emitter sets convenience/protocol options
+  const resolvedEmitterName = (emitterName ?? context.options["emitter-name"] ?? "").toLowerCase();
+  const isJavaOrCsharp = ["java", "csharp"].some((lang) => resolvedEmitterName.includes(lang));


JavaScript is classified as Java here. The real emitter name @azure-tools/typespec-javascript contains the substring java, so isJavaOrCsharp becomes true and the new unnecessary-emitter-option warning is skipped for JavaScript. Please compare the parsed emitter language exactly rather than searching the package name by substring.

great catch, thanks so much! i've added tests for this

Weidong Xu (weidongxu-microsoft) · 2026-08-07T06:02:56Z

+
+- **Area:** Language-scoped decorator behavior. The decorator may apply globally or to unintended emitters without a proper scope.
+- **Decorators checked:**
+  - `@convenientAPI(true)` — must be scoped to `"java"` and/or `"csharp"`. `@convenientAPI(false)` is always allowed without scope since opting out of convenience methods is safe for any language.


The documented exception does not exist in the implementation. validateJavaCsharpScope warns whenever scope is undefined, regardless of the decorator value, and the added test explicitly expects a warning for @convenientAPI(false). This page also repeats the invalid unscoped example below. Please either implement the exception or update the documentation to match the chosen behavior.

oh thanks! that was from a previous implementation, i didn't clean it up well enough

- Use exact scope matching (VALID_SCOPES.includes) instead of substring matching to prevent 'javascript' from matching 'java' - Use parseEmitterName() for emitter language detection instead of substring search on package name - Update docs to reflect that both true and false values of @convenientAPI/@protocolAPI require a scope Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

- Verify 'javascript' scope is not accepted (not confused with 'java') - Verify javascript emitter gets unnecessary-emitter-option warning - Verify java emitter does NOT get the warning Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

Use the existing parseScopes() utility instead of manual string splitting, properly handling negation patterns like '!(python)' and '!(java, csharp)'. New tests: - 'notjava' scope is rejected (not confused with 'java') - '!(python)' negation is accepted (implicitly includes java/csharp) - '!(java, csharp)' negation is rejected (excludes all valid scopes) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

iscai-msft requested review from Laurent Mazuel (lmazuel), m-nash, Mark Cowlishaw (markcowl), Timothee Guerin (timotheeguerin) and Jeff Fisher (xirzec) as code owners July 30, 2026 18:11

microsoft-github-policy-service Bot added int:azure-specs Run integration tests against azure-rest-api-specs lib:tcgc Issues for @azure-tools/typespec-client-generator-core library meta:website TypeSpec.io updates linter Issues related to linter rules labels Jul 30, 2026

iscai-msft force-pushed the iscai-msft-add-convenient-api-scope-linter-rule branch from 2ebc06d to 2d82c69 Compare July 30, 2026 18:26

iscai-msft changed the title ~~Add require-convenient-api-scope linter rule~~ Add convenient-api-requires-scope diagnostic warning Jul 30, 2026

iscai-msft changed the title ~~Add convenient-api-requires-scope diagnostic warning~~ Add decorator-requires-scope validation for @convenientAPI and @clientOption Jul 30, 2026

iscai-msft requested review from Joel Hendrix (jhendrixMSFT), Chenjie Shi (tadelesh) and Weidong Xu (weidongxu-microsoft) as code owners July 31, 2026 18:42

microsoft-github-policy-service Bot added the lib:azure-http-specs For issues/prs related to the @azure-tools/typespec-azure-http-specs package label Jul 31, 2026

Chenjie Shi (tadelesh) reviewed Aug 3, 2026

View reviewed changes

Comment thread packages/typespec-client-generator-core/src/diagnostics/decorator-requires-scope.md Outdated

iscai-msft requested review from Xiaofei Cao (XiaofeiCao), Alan Zimmer (alzimmermsft), Haoling Dong (haolingdong-msft) and Jesse Squire (jsquire) as code owners August 3, 2026 17:02

microsoft-github-policy-service Bot added the emitter:java Issues for @azure-tools/typespec-java emitter label Aug 3, 2026

iscai-msft and others added 4 commits August 3, 2026 15:03

Fix azure-http-specs: scope @convenientAPI to java,csharp

fab244e

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 600858eb-38c5-4725-a32c-5b62b51c3b44

iscai-msft and others added 4 commits August 3, 2026 15:03

iscai-msft force-pushed the iscai-msft-add-convenient-api-scope-linter-rule branch from 8a0b515 to cd21a19 Compare August 3, 2026 19:05

Update packages/typespec-client-generator-core/src/diagnostics/decora…

305d498

…tor-requires-scope.md Co-authored-by: Chenjie Shi <tadelesh.shi@live.cn>

Chenjie Shi (tadelesh) approved these changes Aug 7, 2026

View reviewed changes

Weidong Xu (weidongxu-microsoft) requested changes Aug 7, 2026

View reviewed changes

iscai-msft and others added 3 commits August 7, 2026 12:27

Navigation Menu

Uh oh!

Add `decorator-requires-scope` validation for @convenientAPI and @clientOption - #5119

Add `decorator-requires-scope` validation for @convenientAPI and @clientOption#5119
iscai-msft wants to merge 12 commits into
mainfrom
iscai-msft-add-convenient-api-scope-linter-rule

iscai-msft commented Jul 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 30, 2026 •

edited

Loading

`@azure-tools/typespec-client-generator-core` - feature ✏️

Uh oh!

pkg-pr-new Bot commented Jul 30, 2026 •

edited

Loading

Uh oh!

azure-sdk-automation Bot commented Jul 30, 2026

Uh oh!

Chenjie Shi (tadelesh) left a comment

Uh oh!

Uh oh!

iscai-msft commented Aug 3, 2026

Uh oh!

Chenjie Shi (tadelesh) left a comment •

edited

Loading

Uh oh!

Weidong Xu (weidongxu-microsoft) left a comment

Uh oh!

Weidong Xu (weidongxu-microsoft) Aug 7, 2026

Uh oh!

Weidong Xu (weidongxu-microsoft) Aug 7, 2026

Uh oh!

iscai-msft Aug 7, 2026

Uh oh!

Weidong Xu (weidongxu-microsoft) Aug 7, 2026

Uh oh!

iscai-msft Aug 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

iscai-msft commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Decorators checked:

Changes:

Uh oh!

github-actions Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

@azure-tools/typespec-client-generator-core - feature ✏️

Uh oh!

pkg-pr-new Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azure-sdk-automation Bot commented Jul 30, 2026

Uh oh!

Chenjie Shi (tadelesh) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

iscai-msft commented Aug 3, 2026

Uh oh!

Chenjie Shi (tadelesh) left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Weidong Xu (weidongxu-microsoft) left a comment

Choose a reason for hiding this comment

Uh oh!

Weidong Xu (weidongxu-microsoft) Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Weidong Xu (weidongxu-microsoft) Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

iscai-msft Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Weidong Xu (weidongxu-microsoft) Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

iscai-msft Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

iscai-msft commented Jul 30, 2026 •

edited

Loading

github-actions Bot commented Jul 30, 2026 •

edited

Loading

`@azure-tools/typespec-client-generator-core` - feature ✏️

pkg-pr-new Bot commented Jul 30, 2026 •

edited

Loading

Chenjie Shi (tadelesh) left a comment •

edited

Loading