Add reference documentation for TCGC diagnostics by tadelesh · Pull Request #4982 · Azure/typespec-azure

tadelesh · 2026-07-21T03:28:02Z

Summary

Adds auto-generated reference documentation for all @azure-tools/typespec-client-generator-core (TCGC) diagnostics, and takes the opportunity to clean up the diagnostic set and tighten a few severities.

Each diagnostic now has a source markdown file under packages/typespec-client-generator-core/src/diagnostics/*.md that tspd doc turns into a reference page (mirroring the linter-rule docs from #4968). The generated website pages are gitignored; the markdown files are the source of truth.

Changes

Diagnostic reference docs

Added a doc markdown file for every diagnostic, following the @typespec/openapi3 style: a "This diagnostic is issued when ..." paragraph, a specific "To fix this issue, ..." paragraph, and a ### Example where it helps.
Every example is grounded in the diagnostic's real report site and, where one exists, in an actual test case.
Added a doc(code) helper in lib.ts that wires up both docs (the source markdown) and url (the published reference page). The url lets editors surface the reference via the diagnostic code's codeDescription link.
Gitignored the generated pages at website/src/content/docs/docs/libraries/*/reference/diagnostics/ (merged with the existing linter-rule ignore).

Diagnostic cleanup

Removed diagnostics with no report site in the source: client-service, api-version-not-string, duplicate-decorator.
Replaced invariant checks with compilerAssert (and removed the diagnostics): discriminator-not-constant, discriminator-not-string, unexpected-http-param-type, unexpected-pageable-operation-return-type.
Kept no-emitter-name and invalid-client-service-multiple as diagnostics (both are reachable / tested; see review threads).

Severity changes (breaking)

Raised these from warning to error: inconsistent-multiple-service-dependency, missing-scope, mark-as-lro-ineffective, client-name-ineffective, missing-service-versions. Specs that previously compiled with only these warnings will now fail.

Validation

Build, lint (oxlint), and prettier all pass.
Full TCGC test suite passes (affected tests updated for the new severities).
tspd regeneration produces one page per diagnostic with no documentation-missing warnings; regenerate with pnpm --filter @azure-tools/typespec-client-generator-core regen-docs.

Add a `docs` field (via `fileRef.fromPackageRoot`) to all 67 typespec-client-generator-core diagnostics so `tspd doc` generates a reference page per diagnostic. Diagnostic doc content lives in packages/typespec-client-generator-core/src/diagnostics/*.md, and the generated pages under website .../reference/diagnostics/ are gitignored, mirroring the linter rule docs setup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

azure-sdk-automation · 2026-07-21T03:29:56Z

All changed packages have been documented.

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

Show changes

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

Add reference documentation for TCGC diagnostics so each diagnostic gets an auto-generated reference page.

pkg-pr-new · 2026-07-21T03:35:35Z

Open in StackBlitz

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

commit: 5135fcf

azure-sdk-automation · 2026-07-21T03:38:43Z

You can try these changes here

🛝 Playground	🌐 Website

Reshape all 67 diagnostic docs into the openapi3 reference format: an opening "This diagnostic is issued when ..." paragraph describing the trigger, a specific "To fix this issue, ..." paragraph, and a grounded TypeSpec `### Example` where it clarifies the fix (37 files). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

- Merge the diagnostic and linter gitignore comments into one block. - Apply reviewer doc fixes (nested-client-service-not-subset, client-location-conflict, client-option, duplicate-client-name-warning, flatten-polymorphism, example-value-no-mapping, required-parameter-scoped-out, inconsistent-multiple-service-dependency, add-parameter-duplicate). - Remove unused diagnostics with no report site: client-service, api-version-not-string, duplicate-decorator. - Replace discriminator-not-constant / discriminator-not-string checks with compilerAssert (invariants that should not happen) and remove the diagnostics. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

…lerAssert - Add a doc(code) helper that produces both the docs fileRef and a url to the published diagnostic reference page, and use ...doc("<code>") for every diagnostic. The url lets editors surface the reference (the language server maps it to the diagnostic code's codeDescription link). - Replace unexpected-http-param-type and unexpected-pageable-operation-return-type diagnostics with compilerAssert (invariants that should not happen) and remove the diagnostics. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

Change inconsistent-multiple-service-dependency, missing-scope, mark-as-lro-ineffective, client-name-ineffective and missing-service-versions from warning to error, and update the affected tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

Add an ### Example to the 15 diagnostic docs that have a triggering test but were missing an example, each grounded in the actual test case: union-circular, conflicting-multipart-model-usage, unsupported-generic-decorator-arg-type, duplicate-client-name-warning, example-loading, example-value-no-mapping, conflict-access-override, invalid-encode-for-collection-format, legacy-hierarchy-building-conflict, legacy-hierarchy-building-circular-reference, mark-as-pageable-ineffective, api-version-undefined, inconsistent-multiple-service, client-option, auto-merge-service-conflict. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

- Remove the `using` statements from all example code blocks (not needed in reference examples). - Remove the meaningless examples from example-loading and unsupported-generic-decorator-arg-type. - Show `#suppress` in the client-option, duplicate-client-name-warning and required-parameter-scoped-out examples. - Add the JSON example to example-value-no-mapping to show the exact mismatch. - Separate the fix guidance from the example in client-location-conflict and clarify the auto-merge-service-conflict example. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

lirenhe · 2026-07-22T07:48:10Z

+model ExtraParams {
+  name: string;
+}
+alias Modified = addParameter(MyService.myOp, ExtraParams.name);


Could you add the comments here that this line would cause t he diagnostic error.

lirenhe · 2026-07-22T07:56:17Z

+};
+
+op getInsights(...WithPreviewHeader<FeatureOptInKeys.insights>): void;
+op getSchedules(...WithPreviewHeader<FeatureOptInKeys.schedules>): void;


Could you add a comment about which line would cause problem and provide a suggested fix?
The part of 'to fix this issue' is a bit difficult to understand.

Reshape all 60 TCGC diagnostic docs to the linter-rule structure: an Impact section (specific per diagnostic), an Incorrect Usage example where one exists, a Diagnostic Message section showing the real message text, a How to Fix section, and a Suppression section only for warning-severity diagnostics. Diagnostics with multiple trigger cases (e.g. client-location-conflict, duplicate-client-name, example-loading) present each case separately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: de8537de-5e61-4a0d-b2de-59ec12c15dc4

tadelesh · 2026-07-22T09:30:13Z

+- **Area:** Client operation and parameter placement. Generation continues, but the requested `@clientLocation` move cannot be applied safely to the generated client structure.
+- **Not affected:** HTTP routes, parameter wire names, and service operation definitions are unchanged.
+
+### String target with multiple root clients


These four cases (string-target-with-multiple-root-clients, operation-to-operation, model-property-to-client-initialization, model-property-to-string) are Diagnostic Message only — only the Moved parameters with conflicting types case (below) has a grounded Incorrect Usage / How to Fix, because it is the only one with a test. Should I add examples for the other four cases too, or is message-only acceptable for them?

tadelesh · 2026-07-22T09:30:19Z

+- **Area:** SDK visibility overrides. Blocks the invalid `@access` value from changing generated public/internal visibility.
+- **Not affected:** Model structure, operation signatures, and wire payloads are unchanged.
+
+#### ❌ Incorrect Usage


Heads up: this Incorrect Usage example is inferred, not taken from a test — there is currently no test that triggers invalid-access. Please sanity-check that @access(CustomAccess.private) is a faithful trigger.

tadelesh · 2026-07-22T09:30:21Z

+- **Area:** SDK model usage overrides. Blocks unsupported explicit usage flags from being added to generated model, enum, or union metadata.
+- **Not affected:** Usage inferred from actual operation inputs and outputs is still calculated separately.
+
+#### ❌ Incorrect Usage


Same caveat as invalid-access: this example is inferred (no test triggers invalid-usage). Please confirm the trigger shape is accurate.

tadelesh · 2026-07-22T09:30:22Z

+- **Area:** SDK namespace customization. Generation continues, but the empty `@clientNamespace` override cannot place generated declarations in a custom namespace.
+- **Not affected:** Model names, operation routes, and payload serialization are unchanged.
+
+#### ❌ Incorrect Usage


This example is inferred — no test triggers empty-client-namespace. Please confirm @clientNamespace("") (empty value) is the right trigger.

tadelesh · 2026-07-22T09:30:23Z

@@ -0,0 +1,26 @@
+This diagnostic is issued when TCGC cannot determine the emitter's language because no usable emitter name is available (for example, the emitter name is missing or does not match the expected `*-<language>` pattern).
+
+## Impact


Note on Impact/Suppression: this diagnostic only fires when TCGC runs without a real emitter (tooling / language server / tests where program.emitters is empty). It is kept as a warning with a Suppression section on that basis — flag if you'd rather frame it differently (it is not something a normal spec author hits).

tadelesh requested review from bterlson, iscai-msft, lmazuel, m-nash, markcowl, srnagar and timotheeguerin as code owners July 21, 2026 03:28

microsoft-github-policy-service Bot added the lib:tcgc Issues for @azure-tools/typespec-client-generator-core library label Jul 21, 2026

tadelesh commented Jul 21, 2026

View reviewed changes

timotheeguerin reviewed Jul 21, 2026

View reviewed changes

Comment thread packages/typespec-client-generator-core/src/lib.ts Outdated

tadelesh and others added 3 commits July 22, 2026 11:17

tadelesh commented Jul 22, 2026

View reviewed changes

tadelesh and others added 2 commits July 22, 2026 15:30

Merge branch 'main' into tadelesh/tcgc-diagnostic-docs

e85c7a8

lirenhe reviewed Jul 22, 2026

View reviewed changes

tadelesh commented Jul 22, 2026

View reviewed changes

		@@ -0,0 +1,26 @@
		This diagnostic is issued when TCGC cannot determine the emitter's language because no usable emitter name is available (for example, the emitter name is missing or does not match the expected `*-<language>` pattern).

		## Impact

Uh oh!

Conversation

tadelesh commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Diagnostic reference docs

Diagnostic cleanup

Severity changes (breaking)

Validation

Uh oh!

azure-sdk-automation Bot commented Jul 21, 2026

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

Uh oh!

pkg-pr-new Bot commented Jul 21, 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 21, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lirenhe Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

lirenhe Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

tadelesh Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

tadelesh Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

tadelesh Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

tadelesh Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

tadelesh Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tadelesh commented Jul 21, 2026 •

edited

Loading

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

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

edited

Loading