Skip to content

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

Open
Copilot wants to merge 8 commits into
mainfrom
copilot/validate-examples-in-tcgc
Open

Validate emitter coverage in TCGC "Generate client libraries" docs#4473
Copilot wants to merge 8 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

⚡ Benchmark Results

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

Metric Baseline Current Change
total 🔴 725.9ms 🔴 795.6ms +9.6% 🔴
loader 🟢 132.9ms 🟢 166.8ms +25.5% 🔴
resolver 🟢 15.2ms 🟢 17.0ms +12.3% 🔴
checker 🟢 172.1ms 🟢 189.0ms +9.8% 🔴
linter 🟢 123.0ms 🟢 134.3ms +9.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-header-explode 🟡 17.5ms 🟡 19.7ms +12.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🟡 17.6ms 🟡 19.9ms +13.3% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-response-body 🔴 21.4ms 🔴 23.9ms +11.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/response-schema-problem 🔴 20.8ms 🔴 23.1ms +10.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response 🟢 4.5ms 🟢 5.5ms +23.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header 🟡 13.3ms 🟡 15.5ms +17.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🔴 20.2ms 🔴 22.6ms +11.9% 🔴
Full details – comparing 33d3689 vs baseline cb2e2c9
Metric Baseline Current Change
total 🔴 725.9ms 🔴 795.6ms +9.6% 🔴
loader 🟢 132.9ms 🟢 166.8ms +25.5% 🔴
resolver 🟢 15.2ms 🟢 17.0ms +12.3% 🔴
checker 🟢 172.1ms 🟢 189.0ms +9.8% 🔴
validation 🟢 40.9ms 🟢 40.1ms -2.1%
 ↳ validation/@azure-tools/typespec-azure-core 🟢 5.8ms 🟢 6.4ms +9.6%
 ↳ validation/@typespec/http 🟢 5.6ms 🟢 5.4ms -2.4%
 ↳ validation/@typespec/rest 🟢 0.5ms 🟢 0.5ms -6.3%
 ↳ validation/@typespec/versioning 🔴 27.2ms 🔴 25.9ms -4.7%
 ↳ validation/compiler 🟢 1.4ms 🟢 1.4ms +1.8%
linter 🟢 123.0ms 🟢 134.3ms +9.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/auth-required 🟢 0.0ms 🟢 0.0ms +0.7%
 ↳ linter/@azure-tools/typespec-azure-core/bad-record-type 🟢 0.2ms 🟢 0.2ms -18.5%
 ↳ linter/@azure-tools/typespec-azure-core/byos 🟢 5.3ms 🟢 5.7ms +7.0%
 ↳ linter/@azure-tools/typespec-azure-core/casing-style 🟢 0.5ms 🟢 0.5ms +2.0%
 ↳ linter/@azure-tools/typespec-azure-core/composition-over-inheritance 🟢 0.1ms 🟢 0.1ms -1.5%
 ↳ linter/@azure-tools/typespec-azure-core/documentation-required 🟢 0.7ms 🟢 0.7ms +0.8%
 ↳ linter/@azure-tools/typespec-azure-core/friendly-name 🟢 0.6ms 🟢 0.5ms -13.0%
 ↳ linter/@azure-tools/typespec-azure-core/key-visibility-required 🟢 0.1ms 🟢 0.1ms +1.8%
 ↳ linter/@azure-tools/typespec-azure-core/known-encoding 🟢 0.2ms 🟢 0.2ms -12.8%
 ↳ linter/@azure-tools/typespec-azure-core/long-running-polling-operation-required 🟢 0.3ms 🟢 0.3ms +9.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-case-mismatch 🟢 0.2ms 🟢 0.2ms +7.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-closed-literal-union 🟢 0.2ms 🟢 0.2ms +1.1%
 ↳ linter/@azure-tools/typespec-azure-core/no-enum 🟢 0.0ms 🟢 0.0ms +14.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-error-status-codes 🟢 0.1ms 🟢 0.1ms +0.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops 🟢 0.1ms 🟢 0.1ms -3.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-format 🟢 0.5ms 🟢 0.4ms -16.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-generic-numeric 🟢 0.3ms 🟢 0.4ms +13.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-header-explode 🟡 17.5ms 🟡 19.7ms +12.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-legacy-usage 🟢 1.0ms 🟢 1.0ms +1.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-multiple-discriminator 🟢 0.1ms 🟢 0.1ms +8.2%
 ↳ linter/@azure-tools/typespec-azure-core/no-nullable 🟢 0.2ms 🟢 0.2ms +5.7%
 ↳ linter/@azure-tools/typespec-azure-core/no-offsetdatetime 🟢 1.1ms 🟢 1.2ms +3.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-openapi 🟢 1.7ms 🟢 1.7ms -3.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-private-usage 🟢 1.7ms 🟢 1.6ms -1.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🟡 17.6ms 🟡 19.9ms +13.3% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-response-body 🔴 21.4ms 🔴 23.9ms +11.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-rest-library-interfaces 🟢 0.0ms 🟢 0.0ms -6.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch 🟢 4.6ms 🟢 5.2ms +15.0%
 ↳ linter/@azure-tools/typespec-azure-core/no-rpc-path-params 🟢 0.2ms 🟢 0.2ms +13.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-string-discriminator 🟢 0.0ms 🟢 0.0ms +6.4%
 ↳ linter/@azure-tools/typespec-azure-core/no-unknown 🟢 0.2ms 🟢 0.1ms -12.6%
 ↳ linter/@azure-tools/typespec-azure-core/no-unnamed-union 🟢 0.3ms 🟢 0.3ms -6.9%
 ↳ linter/@azure-tools/typespec-azure-core/operation-missing-api-version 🟢 0.2ms 🟢 0.2ms -8.4%
 ↳ linter/@azure-tools/typespec-azure-core/request-body-problem 🟢 0.2ms 🟢 0.2ms +8.8%
 ↳ linter/@azure-tools/typespec-azure-core/require-versioned 🟢 0.0ms 🟢 0.0ms -5.9%
 ↳ linter/@azure-tools/typespec-azure-core/response-schema-problem 🔴 20.8ms 🔴 23.1ms +10.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/rpc-operation-request-body 🟢 0.3ms 🟢 0.3ms +13.7%
 ↳ linter/@azure-tools/typespec-azure-core/spread-discriminated-model 🟢 0.2ms 🟢 0.2ms -5.4%
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-names 🟢 4.8ms 🟢 5.5ms +15.1%
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-operations 🟢 0.1ms 🟢 0.1ms +6.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-common-types-version 🟢 3.8ms 🟢 4.2ms +11.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key 🟢 0.1ms 🟢 0.1ms -4.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage 🟢 0.1ms 🟢 0.1ms -2.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes 🟢 4.9ms 🟢 5.4ms +11.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts 🟢 4.2ms 🟢 4.8ms +15.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-record 🟢 0.3ms 🟢 0.3ms -11.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes 🟢 0.4ms 🟢 0.5ms +15.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes 🟢 0.0ms 🟢 0.0ms -11.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment 🟢 0.2ms 🟢 0.2ms -1.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property 🟢 0.1ms 🟢 0.1ms +9.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator 🟢 0.0ms 🟢 0.0ms +7.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb 🟢 0.1ms 🟢 0.1ms -12.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property 🟢 0.1ms 🟢 0.1ms +4.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format 🟢 0.0ms 🟢 0.0ms -4.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars 🟢 0.2ms 🟢 0.2ms +8.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern 🟢 0.0ms 🟢 0.0ms -5.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation 🟢 0.2ms 🟢 0.2ms -7.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response 🟢 4.5ms 🟢 5.5ms +23.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-patch 🟢 0.3ms 🟢 0.3ms +11.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars 🟢 0.2ms 🟢 0.2ms -8.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state 🟢 0.1ms 🟢 0.1ms -9.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels 🟢 0.1ms 🟢 0.1ms -6.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/empty-updateable-properties 🟢 0.1ms 🟢 0.1ms +12.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation 🟢 0.0ms 🟢 0.0ms -9.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header 🟡 13.3ms 🟡 15.5ms +17.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint 🟢 0.0ms 🟢 0.0ms -6.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers 🟢 0.3ms 🟢 0.2ms -19.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-empty-model 🟢 0.1ms 🟢 0.1ms +5.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-resource-delete-operation 🟢 0.1ms 🟢 0.2ms +8.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🔴 20.2ms 🔴 22.6ms +11.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/patch-envelope 🟢 0.1ms 🟢 0.1ms +1.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/resource-name 🟢 0.1ms 🟢 0.1ms -1.2%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/secret-prop 🟢 2.1ms 🟢 2.0ms -5.5%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/unsupported-type 🟢 0.4ms 🟢 0.3ms -3.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/version-progression 🟢 0.0ms 🟢 0.0ms -9.0%
 ↳ linter/@azure-tools/typespec-client-generator-core/property-name-conflict 🟢 0.9ms 🟢 0.9ms +0.6%
 ↳ linter/@azure-tools/typespec-client-generator-core/require-client-suffix 🟢 0.2ms 🟢 0.2ms -6.5%
emit 🟡 236.8ms 🟡 245.2ms +3.5%
 ↳ emit/@azure-tools/typespec-autorest 🟢 147.7ms 🟢 153.3ms +3.8%
 ↳ emit/@typespec/openapi3 🟢 133.5ms 🟢 136.2ms +2.0%
 ↳ emit/@typespec/openapi3/compute 🟢 120.5ms 🟢 121.7ms +1.0%
 ↳ emit/@typespec/openapi3/write 🟢 13.1ms 🟢 13.4ms +2.6%

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)

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.

5 participants