Validate emitter coverage in TCGC "Generate client libraries" docs#4473
Validate emitter coverage in TCGC "Generate client libraries" docs#4473Copilot wants to merge 8 commits into
Conversation
Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/804a91da-a2d6-4613-88c3-569e4875021d Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/3907df17-87e7-4ef4-9971-95382ae74dd4 Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
|
No changes needing a change description found. |
Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/b4576197-d98c-451b-97d1-0ada89f68241 Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
|
You can try these changes here
|
Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/9e422d12-ee92-4f3b-9c1d-766386e01497 Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
… emitter output Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/3858476f-263e-4a1e-9f0a-0d59e7aa0ab6 Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
|
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:
If you need me to access, download, or install something from one of these locations, you can either:
|
|
@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>
Fixed in 0508349: added a blank line around 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:
If you need me to access, download, or install something from one of these locations, you can either:
|
… to sub-client) Agent-Logs-Url: https://github.com/Azure/typespec-azure/sessions/bb0d0b05-a8da-43cb-87e6-1fabe76a5a6b Co-authored-by: tadelesh <1726438+tadelesh@users.noreply.github.com>
|
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:
If you need me to access, download, or install something from one of these locations, you can either:
|
⚡ Benchmark Results
Full details – comparing
|
| 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)
The TCGC how-to docs under
website/src/content/docs/docs/howtos/Generate client libraries/contained ~25// TODOplaceholders ("check if current emitter supports it") and ~35NOT_SUPPORTEDmarkers 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
@@clientNamespace)MatchConditions)Pageable<User>/AsyncPageable<User>)@encode(string) int64@addedon operation and on model property (ServiceVersionenum emitted, but no version guards)Incorrect
NOT_SUPPORTEDmarkers correctedReplaced with the actually-generated surface:
@access internal,clientLocation(subscriptionId), simple@override,replaceParameter,removeParameter,reorderParameters; Java for@responseAsBool(HEAD →boolean)NewListWithPagePager) for all four continuation-token variantsRecord<string | null>additional properties (map[string]*string) and for@encode(string) int64(customMarshalJSONviastrconv.FormatInt)usagereworded fromNOT_SUPPORTEDto "doesn't generate different code based on usage" (matches Python/TS wording)Doc spec corrections
@@clientInitialization(Storage, { initializedBy: individually | parent })to the top-levelStoragenamespace, which fails to compile in TCGC withinvalid-initialized-by("First level client must haveInitializedBy.individuallyspecified"). Updated the spec to apply@@clientInitializationto a sub-namespace (Storage.Blob) so it compiles. The C#/TS/Java tabs are left as// TODOso the Java sample can be manually updated with theenable-subclient: truetspconfig flag.Notable findings worth a reviewer's eye
Markers kept as
NOT_SUPPORTEDbecause verification confirmed them; a few are doc/TCGC issues rather than emitter limitations:04method.mdxMerge @sharedRoute operations– the doc example fails to compile in current TCGC (duplicate-client-name); pre-existing doc issue, kept out of scope.04method.mdxChaining transformations –reorderParameters(replaceParameter(...), ...)triggers a TCGC internal compiler error; pre-existing TCGC bug.04method.mdxaddParameter,@responseAsBool,convenientAPI(false)for Go – the Go emitter throws an internal error.05pagingOperations.mdxcontinuation-token variants – Java tabs kept asNOT_SUPPORTEDper 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.mdxGo@encode(string) int64block: added a blank line around<ClientTabItem lang="go" >so prettier doesn't garble the embedded Go code.cspell.yaml: addedstrconv(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 modelmarkers in03client.mdx– open design questions, not emitter-support checks.context.TODO()in09renaming.mdx– Go stdlib syntax, not a placeholder.Legacy.clientDefaultValueC#/TS/Java/Go tabs (both model property and operation parameter sections) in08types.mdx– left asTODOper reviewer feedback.