Skip to content

Validate emitter coverage in TCGC "Generate client libraries" docs#4473

Merged
tadelesh merged 10 commits into
mainfrom
copilot/validate-examples-in-tcgc
Jun 2, 2026
Merged

Validate emitter coverage in TCGC "Generate client libraries" docs#4473
tadelesh merged 10 commits into
mainfrom
copilot/validate-examples-in-tcgc

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 20, 2026

The TCGC how-to docs under website/src/content/docs/docs/howtos/Generate client libraries/ contained ~25 // TODO placeholders ("check if current emitter supports it") and ~35 NOT_SUPPORTED markers that had never been verified against the actual language emitters.

Each placeholder was validated by building a minimal compilable TypeSpec spec matching the surrounding doc, running all five emitters (@azure-typespec/http-client-csharp, @azure-tools/typespec-ts, @azure-tools/typespec-java, @azure-tools/typespec-go, @azure-tools/typespec-python), and inspecting the generated public API surface.

TODO placeholders filled with real emitter output

  • 02package.mdx – C# tabs (basic namespace, @@clientNamespace)
  • 03client.mdx – C# tab (operations split across sub-namespaces)
  • 04method.mdx – C# tab (conditional request headers → MatchConditions)
  • 05pagingOperations.mdx – C# tabs for all four continuation-token variants (Pageable<User> / AsyncPageable<User>)
  • 07multipart.mdx – C# tab (only protocol method generated; no convenience overload or model class)
  • 08types.mdx – C# tabs for namespace placement and renaming; C# and Java tabs for nullable; C# tab for @encode(string) int64
  • 10versioning.mdx – C# tabs for @added on operation and on model property (ServiceVersion enum emitted, but no version guards)

Incorrect NOT_SUPPORTED markers corrected

Replaced with the actually-generated surface:

  • 04method.mdx – Go for @access internal, clientLocation (subscriptionId), simple @override, replaceParameter, removeParameter, reorderParameters; Java for @responseAsBool (HEAD → boolean)
  • 05pagingOperations.mdx – Go (NewListWithPagePager) for all four continuation-token variants
  • 08types.mdx – Go for Record<string | null> additional properties (map[string]*string) and for @encode(string) int64 (custom MarshalJSON via strconv.FormatInt)
  • 04method.mdx – Go usage reworded from NOT_SUPPORTED to "doesn't generate different code based on usage" (matches Python/TS wording)

Doc spec corrections

  • 03client.mdx "Change Sub Client Initialization Way" – the original example applied @@clientInitialization(Storage, { initializedBy: individually | parent }) to the top-level Storage namespace, which fails to compile in TCGC with invalid-initialized-by ("First level client must have InitializedBy.individually specified"). Updated the spec to apply @@clientInitialization to a sub-namespace (Storage.Blob) so it compiles. The C#/TS/Java tabs are left as // TODO so the Java sample can be manually updated with the enable-subclient: true tspconfig flag.

Notable findings worth a reviewer's eye

Markers kept as NOT_SUPPORTED because verification confirmed them; a few are doc/TCGC issues rather than emitter limitations:

  • 04method.mdx Merge @sharedRoute operations – the doc example fails to compile in current TCGC (duplicate-client-name); pre-existing doc issue, kept out of scope.
  • 04method.mdx Chaining transformations – reorderParameters(replaceParameter(...), ...) triggers a TCGC internal compiler error; pre-existing TCGC bug.
  • 04method.mdx addParameter, @responseAsBool, convenientAPI(false) for Go – the Go emitter throws an internal error.
  • 05pagingOperations.mdx continuation-token variants – Java tabs kept as NOT_SUPPORTED per reviewer feedback (Java's continuationToken support is in unbranded only and is not shipped for Azure).
  • 10versioning.mdx @clientApiVersions – Java emits only spec-defined versions (V4, V5); Go emits no api-version constants.

CI fixes

  • 08types.mdx Go @encode(string) int64 block: added a blank line around <ClientTabItem lang="go" > so prettier doesn't garble the embedded Go code.
  • cspell.yaml: added strconv (Go stdlib package referenced in the new Go example) to the words allowlist.

Out of scope (not modified)

  • // TODO: how do you pass in the options model markers in 03client.mdx – open design questions, not emitter-support checks.
  • context.TODO() in 09renaming.mdx – Go stdlib syntax, not a placeholder.
  • Legacy.clientDefaultValue C#/TS/Java/Go tabs (both model property and operation parameter sections) in 08types.mdx – left as TODO per reviewer feedback.

Copy link
Copy Markdown
Member

@tadelesh tadelesh left a comment

Choose a reason for hiding this comment

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

@copilot Resolve the comments.

@azure-sdk
Copy link
Copy Markdown
Collaborator

No changes needing a change description found.

Copilot AI requested a review from tadelesh May 20, 2026 10:36
@azure-sdk
Copy link
Copy Markdown
Collaborator

You can try these changes here

🛝 Playground 🌐 Website

Comment thread website/src/content/docs/docs/howtos/Generate client libraries/03client.mdx Outdated
Comment thread website/src/content/docs/docs/howtos/Generate client libraries/08types.mdx Outdated
Copy link
Copy Markdown
Contributor Author

Copilot AI commented May 21, 2026

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • iojs.org
    • Triggering command: /usr/bin/curl curl -q --fail --compressed -L -s REDACTED -o - (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

@tadelesh
Copy link
Copy Markdown
Member

@copilot Format the change and fix the spell check issue in ci.

Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/6f5784c7-b756-488e-aeb1-30219c0f0bed

Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented May 21, 2026

@copilot Format the change and fix the spell check issue in ci.

Fixed in 0508349: added a blank line around <ClientTabItem lang="go" > in 08types.mdx so prettier no longer garbles the embedded Go code, and added strconv to cspell.yaml. Both pnpm run format:check and pnpm run cspell now pass locally.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • iojs.org
    • Triggering command: /usr/bin/curl curl -q --fail --compressed -L -s REDACTED -o - (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Copy link
Copy Markdown
Contributor Author

Copilot AI commented May 21, 2026

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • iojs.org
    • Triggering command: /usr/bin/curl curl -q --fail --compressed -L -s REDACTED -o - (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Comment thread website/src/content/docs/docs/howtos/Generate client libraries/03client.mdx Outdated
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 21, 2026

⚡ Benchmark Results

⚠️ 3 metric(s) regressed above the +5% threshold:

Metric Baseline Current Change
loader 🟢 158.7ms 🟡 209.9ms +32.3% 🔴
 ↳ emit/@azure-tools/typespec-autorest 🟢 156.7ms 🟢 188.5ms +20.3% 🔴
 ↳ emit/@typespec/openapi3/compute 🟢 125.8ms 🟢 133.9ms +6.4% 🔴
Full details – comparing 2a8a81c vs baseline 7ee08d0
Metric Baseline Current Change
total 🔴 6.52s 🔴 6.37s -2.3%
loader 🟢 158.7ms 🟡 209.9ms +32.3% 🔴
resolver 🟢 18.4ms 🟢 17.0ms -7.7% 🟢
checker 🟢 182.5ms 🟢 178.8ms -2.0%
validation 🟢 40.9ms 🟢 40.7ms -0.6%
 ↳ validation/@azure-tools/typespec-azure-core 🟢 6.2ms 🟢 5.9ms -4.3%
 ↳ validation/@typespec/http 🟢 5.1ms 🟢 5.2ms +1.2%
 ↳ validation/@typespec/rest 🟢 0.5ms 🟢 0.5ms +9.4%
 ↳ validation/@typespec/versioning 🔴 27.7ms 🔴 27.2ms -1.5%
 ↳ validation/compiler 🟢 1.4ms 🟢 1.5ms +2.3%
linter 🟢 126.5ms 🟢 123.5ms -2.3%
 ↳ linter/@azure-tools/typespec-azure-core/auth-required 🟢 0.0ms 🟢 0.0ms -7.4%
 ↳ linter/@azure-tools/typespec-azure-core/bad-record-type 🟢 0.2ms 🟢 0.2ms -3.6%
 ↳ linter/@azure-tools/typespec-azure-core/byos 🟢 5.5ms 🟢 5.3ms -3.4%
 ↳ linter/@azure-tools/typespec-azure-core/casing-style 🟢 0.6ms 🟢 0.6ms +0.7%
 ↳ linter/@azure-tools/typespec-azure-core/composition-over-inheritance 🟢 0.1ms 🟢 0.1ms +13.8%
 ↳ linter/@azure-tools/typespec-azure-core/documentation-required 🟢 0.8ms 🟢 0.8ms -1.7%
 ↳ linter/@azure-tools/typespec-azure-core/friendly-name 🟢 0.6ms 🟢 0.6ms +1.4%
 ↳ linter/@azure-tools/typespec-azure-core/key-visibility-required 🟢 0.1ms 🟢 0.2ms +1.0%
 ↳ linter/@azure-tools/typespec-azure-core/known-encoding 🟢 0.3ms 🟢 0.3ms +0.9%
 ↳ linter/@azure-tools/typespec-azure-core/long-running-polling-operation-required 🟢 0.3ms 🟢 0.3ms -2.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-case-mismatch 🟢 0.2ms 🟢 0.2ms -8.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-closed-literal-union 🟢 0.2ms 🟢 0.2ms -4.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-enum 🟢 0.0ms 🟢 0.0ms -5.6%
 ↳ linter/@azure-tools/typespec-azure-core/no-error-status-codes 🟢 0.1ms 🟢 0.1ms +3.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops 🟢 0.1ms 🟢 0.1ms +0.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-format 🟢 0.6ms 🟢 0.6ms +0.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-generic-numeric 🟢 0.4ms 🟢 0.4ms -2.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-header-explode 🟡 18.1ms 🟡 17.2ms -4.6%
 ↳ linter/@azure-tools/typespec-azure-core/no-legacy-usage 🟢 1.1ms 🟢 1.1ms +1.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-multiple-discriminator 🟢 0.1ms 🟢 0.1ms +3.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-nullable 🟢 0.2ms 🟢 0.2ms -2.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-offsetdatetime 🟢 1.1ms 🟢 1.1ms -2.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-openapi 🟢 2.1ms 🟢 2.0ms -4.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-private-usage 🟢 1.8ms 🟢 1.8ms -3.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🟡 17.6ms 🟡 17.9ms +1.4%
 ↳ linter/@azure-tools/typespec-azure-core/no-response-body 🔴 23.0ms 🔴 22.5ms -2.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-rest-library-interfaces 🟢 0.0ms 🟢 0.0ms -10.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch 🟢 4.8ms 🟢 4.3ms -10.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-rpc-path-params 🟢 0.2ms 🟢 0.2ms -8.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-string-discriminator 🟢 0.0ms 🟢 0.0ms -0.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-unknown 🟢 0.2ms 🟢 0.2ms +2.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-unnamed-union 🟢 0.3ms 🟢 0.3ms -4.6%
 ↳ linter/@azure-tools/typespec-azure-core/operation-missing-api-version 🟢 0.2ms 🟢 0.2ms -8.5%
 ↳ linter/@azure-tools/typespec-azure-core/request-body-problem 🟢 0.3ms 🟢 0.3ms -4.8%
 ↳ linter/@azure-tools/typespec-azure-core/require-versioned 🟢 0.0ms 🟢 0.0ms -13.1%
 ↳ linter/@azure-tools/typespec-azure-core/response-schema-problem 🔴 20.9ms 🔴 20.2ms -3.4%
 ↳ linter/@azure-tools/typespec-azure-core/rpc-operation-request-body 🟢 0.3ms 🟢 0.3ms -2.6%
 ↳ linter/@azure-tools/typespec-azure-core/spread-discriminated-model 🟢 0.3ms 🟢 0.3ms -4.1%
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-names 🟢 4.6ms 🟢 4.8ms +4.2%
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-operations 🟢 0.1ms 🟢 0.1ms -2.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-common-types-version 🟢 3.5ms 🟢 3.5ms -1.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key 🟢 0.1ms 🟢 0.1ms -10.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage 🟢 0.1ms 🟢 0.1ms +4.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes 🟢 4.9ms 🟢 4.8ms -2.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts 🟢 4.0ms 🟢 3.8ms -4.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-record 🟢 0.3ms 🟢 0.3ms -1.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes 🟢 0.4ms 🟢 0.4ms -5.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes 🟢 0.0ms 🟢 0.0ms -1.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment 🟢 0.2ms 🟢 0.2ms -7.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property 🟢 0.1ms 🟢 0.1ms +5.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator 🟢 0.0ms 🟢 0.0ms -17.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb 🟢 0.1ms 🟢 0.1ms -5.4%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property 🟢 0.1ms 🟢 0.1ms +2.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format 🟢 0.0ms 🟢 0.0ms -5.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars 🟢 0.2ms 🟢 0.2ms -2.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern 🟢 0.0ms 🟢 0.0ms -11.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation 🟢 0.2ms 🟢 0.2ms -9.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response 🟢 4.2ms 🟢 4.3ms +0.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-patch 🟢 0.3ms 🟢 0.3ms -6.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars 🟢 0.2ms 🟢 0.2ms +0.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state 🟢 0.1ms 🟢 0.1ms +2.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels 🟢 0.1ms 🟢 0.1ms -2.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/empty-updateable-properties 🟢 0.1ms 🟢 0.1ms -7.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation 🟢 0.0ms 🟢 0.0ms +7.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header 🟡 13.7ms 🟡 13.8ms +0.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint 🟢 0.0ms 🟢 0.0ms -3.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers 🟢 0.3ms 🟢 0.3ms -6.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-empty-model 🟢 0.1ms 🟢 0.1ms -8.4%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-resource-delete-operation 🟢 0.2ms 🟢 0.2ms -1.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🟡 18.8ms 🟡 19.5ms +3.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/patch-envelope 🟢 0.1ms 🟢 0.1ms +1.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/resource-name 🟢 0.1ms 🟢 0.1ms -8.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/secret-prop 🟢 2.3ms 🟢 2.0ms -13.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/unsupported-type 🟢 0.4ms 🟢 0.4ms -0.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/version-progression 🟢 0.0ms 🟢 0.0ms -13.9%
 ↳ linter/@azure-tools/typespec-client-generator-core/property-name-conflict 🟢 1.0ms 🟢 1.0ms -2.7%
 ↳ linter/@azure-tools/typespec-client-generator-core/require-client-suffix 🟢 0.2ms 🟢 0.2ms -10.1%
emit 🔴 5.90s 🔴 5.77s -2.3%
 ↳ emit/@azure-tools/typespec-autorest 🟢 156.7ms 🟢 188.5ms +20.3% 🔴
 ↳ emit/@azure-tools/typespec-python 🔴 4.35s 🔴 4.21s -3.3%
 ↳ emit/@typespec/http-client-js 🔴 1.13s 🔴 1.08s -4.7%
 ↳ emit/@typespec/openapi3 🟢 145.8ms 🟢 152.0ms +4.2%
 ↳ emit/@typespec/openapi3/compute 🟢 125.8ms 🟢 133.9ms +6.4% 🔴
 ↳ emit/@typespec/openapi3/write 🟢 20.3ms 🟢 18.2ms -10.2% 🟢

Averaged across 3 specs (azure-arm-resource-manager, azure-core-dataplane, azure-full).
Threshold: changes > ±5% are highlighted.
🟢 Fast · 🟡 Moderate (stages >200ms, rules >10ms) · 🔴 Slow (stages >400ms, rules >20ms)

@tadelesh
Copy link
Copy Markdown
Member

@JoshLove-msft Could you help to check the .NET part in this PR? The example is for data plane.

Comment thread website/src/content/docs/docs/howtos/Generate client libraries/04method.mdx Outdated
Co-authored-by: JoshLove-msft <54595583+JoshLove-msft@users.noreply.github.com>
@tadelesh tadelesh enabled auto-merge June 2, 2026 01:42
@tadelesh tadelesh added this pull request to the merge queue Jun 2, 2026
Merged via the queue into main with commit 2a0019c Jun 2, 2026
23 checks passed
@tadelesh tadelesh deleted the copilot/validate-examples-in-tcgc branch June 2, 2026 02:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

meta:website TypeSpec.io updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants