diff --git a/.chronus/changes/add-body-or-no-content-scenario-2026-8-14.md b/.chronus/changes/add-body-or-no-content-scenario-2026-8-14.md new file mode 100644 index 00000000000..d4934d23b1f --- /dev/null +++ b/.chronus/changes/add-body-or-no-content-scenario-2026-8-14.md @@ -0,0 +1,16 @@ +--- +changeKind: feature +packages: + - "@typespec/http-specs" +--- + +Add scenario for an operation whose successful response is either a model body (`200`) or no content (`204`). + +```tsp +op getBody(): { + @statusCode statusCode: 200; + @body layout: BlobLayout; +} | { + @statusCode statusCode: 204; +}; +``` diff --git a/.chronus/changes/add-python-post-paging-lro-with-body-test-2026-7-22-2-4-0.md b/.chronus/changes/add-python-post-paging-lro-with-body-test-2026-7-22-2-4-0.md new file mode 100644 index 00000000000..f0b0c763632 --- /dev/null +++ b/.chronus/changes/add-python-post-paging-lro-with-body-test-2026-7-22-2-4-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Add mock API tests for the new ARM operation-templates scenarios (`postPagingLroWithBody`, `getLro`, `postActionPaging`, `markAsPageable`, `Legacy.routedGet`, and `Legacy.createOrReplaceOptionalBody`). diff --git a/.chronus/changes/copilot-http-client-java-add-test-for-new-end-to-end-cases-2026-6-15-9-37-11.md b/.chronus/changes/copilot-http-client-java-add-test-for-new-end-to-end-cases-2026-6-15-9-37-11.md new file mode 100644 index 00000000000..bb80d8761ab --- /dev/null +++ b/.chronus/changes/copilot-http-client-java-add-test-for-new-end-to-end-cases-2026-6-15-9-37-11.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Add SpecialChars e2e test, encode/boolean test (disabled), and type/union/discriminated e2e tests \ No newline at end of file diff --git a/.chronus/changes/disable-vs-build-nuget-audit-2026-8-7.md b/.chronus/changes/disable-vs-build-nuget-audit-2026-8-7.md new file mode 100644 index 00000000000..271c3071fae --- /dev/null +++ b/.chronus/changes/disable-vs-build-nuget-audit-2026-8-7.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "typespec-vs" +--- + +Disable NuGet package auditing during cross-platform Visual Studio extension builds so restores do not fail when the vulnerability feed is unavailable. diff --git a/.chronus/changes/expose-required-fields-as-ctor-args-2026-7-24-10-11-0.md b/.chronus/changes/expose-required-fields-as-ctor-args-2026-7-24-10-11-0.md new file mode 100644 index 00000000000..d34df907ddd --- /dev/null +++ b/.chronus/changes/expose-required-fields-as-ctor-args-2026-7-24-10-11-0.md @@ -0,0 +1,13 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-java" +--- + +Expose the `required-fields-as-ctor-args` emitter option in `tspconfig.yaml`. It controls whether required model properties are generated as constructor arguments. The default remains `true`. + +```yaml +options: + "@typespec/http-client-java": + required-fields-as-ctor-args: false +``` diff --git a/.chronus/changes/feat-client-api-version-init-kind-2026-6-17-14-21-20.md b/.chronus/changes/feat-client-api-version-init-kind-2026-6-17-14-21-20.md new file mode 100644 index 00000000000..41748039f53 --- /dev/null +++ b/.chronus/changes/feat-client-api-version-init-kind-2026-6-17-14-21-20.md @@ -0,0 +1,7 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-java" +--- + +Support clientApiVersions \ No newline at end of file diff --git a/.chronus/changes/fix-model-base-docstrings-2026-7-8-14-9-0.md b/.chronus/changes/fix-model-base-docstrings-2026-7-8-14-9-0.md deleted file mode 100644 index a4e55282507..00000000000 --- a/.chronus/changes/fix-model-base-docstrings-2026-7-8-14-9-0.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/http-client-python" ---- - -Clarify docstrings in the generated `_MyMutableMapping` base class in `_model_base.py` so they no longer use the ambiguous `D` placeholder (e.g. `Remove all items from D.` is now `Remove all items from the dictionary.`) diff --git a/.chronus/changes/fix-models-mode-none-constructor-2026-7-10-9-46-0.md b/.chronus/changes/fix-models-mode-none-constructor-2026-7-10-9-46-0.md deleted file mode 100644 index 099a85bb66d..00000000000 --- a/.chronus/changes/fix-models-mode-none-constructor-2026-7-10-9-46-0.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/http-client-python" ---- - -Fix crash when generating with `models-mode=none`. Options passed to the `OptionsDict` constructor are now normalized through the same validation/transform path as `__setitem__`, so `models-mode=none` is correctly treated as falsy and a modelless client is produced instead of crashing. diff --git a/.chronus/changes/fix-per-client-serviceversion-2026-7-17-11-10-0.md b/.chronus/changes/fix-per-client-serviceversion-2026-7-17-11-10-0.md new file mode 100644 index 00000000000..cc513156429 --- /dev/null +++ b/.chronus/changes/fix-per-client-serviceversion-2026-7-17-11-10-0.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Fix multi-client packages generating a separate `ServiceVersion` enum per client when all clients share the same api-versions. The api-version comparison now compares version strings instead of `ApiVersion` object references, restoring a single shared `ServiceVersion` for such packages. diff --git a/.chronus/changes/fix-python-emitter-invalid-type-annotations-2026-4-18-0-0-0.md b/.chronus/changes/fix-python-emitter-invalid-type-annotations-2026-4-18-0-0-0.md new file mode 100644 index 00000000000..c17c99318de --- /dev/null +++ b/.chronus/changes/fix-python-emitter-invalid-type-annotations-2026-4-18-0-0-0.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-python" +--- + +Fix invalid Python type annotations generated in `types.py` files. Internal enums used as TypedDict fields are now imported (as a bare symbol) from their private `_enums` submodule so the annotation resolves; duplicate runtime + `TYPE_CHECKING` imports of the same symbol are deduplicated to avoid `no-redef`; and TypedDicts that change an inherited field's requiredness are emitted as a flat (non-inheriting) TypedDict to satisfy PEP 589. diff --git a/.chronus/changes/fix-standalone-cli-version-sync-2026-7-2.md b/.chronus/changes/fix-standalone-cli-version-sync-2026-7-2.md new file mode 100644 index 00000000000..11d1776f559 --- /dev/null +++ b/.chronus/changes/fix-standalone-cli-version-sync-2026-7-2.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/standalone-cli" +--- + +Align standalone CLI version with `@typespec/compiler` version to fix mismatch between `tsp --version` output and package manager listings (Scoop, winget, Homebrew). diff --git a/.chronus/changes/fix-typeddict-constant-enum-literal-2026-07-08.md b/.chronus/changes/fix-typeddict-constant-enum-literal-2026-07-08.md deleted file mode 100644 index a91b5185109..00000000000 --- a/.chronus/changes/fix-typeddict-constant-enum-literal-2026-07-08.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: fix -packages: - - "@typespec/http-client-python" ---- - -Fix constant enum values referencing the nonexistent `_enums` module in `models-mode: typeddict`. In typeddict mode enums are emitted as `Literal` aliases in `types.py` and `_enums.py` is never generated, so a single constant enum value now annotates with its literal value (e.g. `Literal["red"]`) and no longer imports from `_enums`. diff --git a/.chronus/changes/forward-python-package-index-environment-2026-8-7.md b/.chronus/changes/forward-python-package-index-environment-2026-8-7.md new file mode 100644 index 00000000000..1bca0d34314 --- /dev/null +++ b/.chronus/changes/forward-python-package-index-environment-2026-8-7.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-python" +--- + +Forward package index and Python mirror environment variables to tox test environments so tests can install dependencies from configured feeds. diff --git a/.chronus/changes/http-client-java-enable-query-dollarsign-2026-7-20-16-28-0.md b/.chronus/changes/http-client-java-enable-query-dollarsign-2026-7-20-16-28-0.md new file mode 100644 index 00000000000..ac5f4797e79 --- /dev/null +++ b/.chronus/changes/http-client-java-enable-query-dollarsign-2026-7-20-16-28-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Enable the `parameters.query.QueryTests` dollar-sign test in the clientcore test module now that the `@typespec/http-specs` dollar-sign route fix is published. diff --git a/.chronus/changes/http-client-java-fix-xml-serializer-bytes-2026-7-22-0-21-49.md b/.chronus/changes/http-client-java-fix-xml-serializer-bytes-2026-7-22-0-21-49.md new file mode 100644 index 00000000000..3a5675d2799 --- /dev/null +++ b/.chronus/changes/http-client-java-fix-xml-serializer-bytes-2026-7-22-0-21-49.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Fix XML serialization to only apply for `azure-v1` data-plane clients, and to skip the XML `ObjectSerializer` for raw `byte[]`/`BinaryData` payloads that are not structured XML models. This avoids emitting a reference to a non-generated `XmlSerializerProviders` helper (which caused a build break) for operations that return raw XML bytes. diff --git a/.chronus/changes/http-client-java-premium-changelog-api-version-2026-7-29-0-0-1.md b/.chronus/changes/http-client-java-premium-changelog-api-version-2026-7-29-0-0-1.md new file mode 100644 index 00000000000..bbf0e735ea4 --- /dev/null +++ b/.chronus/changes/http-client-java-premium-changelog-api-version-2026-7-29-0-0-1.md @@ -0,0 +1,7 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-java" +--- + +Add `Package api-version` annotation to `CHANGELOG.md` for Fluent Premium. When generating a Premium SDK with an existing `CHANGELOG.md`, the top-most version section gets a `- Package api-version {...}.` line reflecting the service api-version(s), matching the behavior already available for Fluent Lite. diff --git a/.chronus/changes/http-client-java-preserve-sdk-integration-properties-2026-08-12.md b/.chronus/changes/http-client-java-preserve-sdk-integration-properties-2026-08-12.md new file mode 100644 index 00000000000..1bf3aa4cc92 --- /dev/null +++ b/.chronus/changes/http-client-java-preserve-sdk-integration-properties-2026-08-12.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Preserve existing properties files for certain libraries during SDK integration. diff --git a/.chronus/changes/http-client-java-remove-autorest-settings-2026-7-29-0-0-0.md b/.chronus/changes/http-client-java-remove-autorest-settings-2026-7-29-0-0-0.md new file mode 100644 index 00000000000..5f073721f0b --- /dev/null +++ b/.chronus/changes/http-client-java-remove-autorest-settings-2026-7-29-0-0-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Remove legacy AutoRest settings. `AutorestSettings` is renamed to `ProjectSettings` and only retains `output-folder`; the unused `java-sdks-folder` and `title` options, the `SwaggerReadmeTemplate` generation, and the AutoRest `tag` based service description are removed (management service description now uses the api-version instead). diff --git a/.chronus/changes/http-client-java-remove-model-generation-2026-08-17.md b/.chronus/changes/http-client-java-remove-model-generation-2026-08-17.md new file mode 100644 index 00000000000..83e1a344d02 --- /dev/null +++ b/.chronus/changes/http-client-java-remove-model-generation-2026-08-17.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Fix `remove-model` for TypeSpec management clients, including enum models. diff --git a/.chronus/changes/http-client-java-remove-model-option-2026-08-13.md b/.chronus/changes/http-client-java-remove-model-option-2026-08-13.md new file mode 100644 index 00000000000..b0a451b2a6b --- /dev/null +++ b/.chronus/changes/http-client-java-remove-model-option-2026-08-13.md @@ -0,0 +1,8 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-java" +--- + +Support removing models from management clients with the `remove-model` emitter option. +``` diff --git a/.chronus/changes/http-client-java-response-header-javadocs-2026-08-10.md b/.chronus/changes/http-client-java-response-header-javadocs-2026-08-10.md new file mode 100644 index 00000000000..e12363eaa32 --- /dev/null +++ b/.chronus/changes/http-client-java-response-header-javadocs-2026-08-10.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Document response headers in protocol API Javadocs. diff --git a/.chronus/changes/http-client-java-response-headers-as-model-2026-7-28.md b/.chronus/changes/http-client-java-response-headers-as-model-2026-7-28.md new file mode 100644 index 00000000000..e1d22517203 --- /dev/null +++ b/.chronus/changes/http-client-java-response-headers-as-model-2026-7-28.md @@ -0,0 +1,13 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-java" +--- + +Add opt-in support for returning significant response headers as a strongly-typed model from the convenience method of a data-plane operation that has response headers but no response body (for example, a `HEAD` operation). Enable it per operation via the `responseHeadersAsModel` client option: + +```typespec +@@clientOption(ResponseHeaderOp.getResourceMetadata, "responseHeadersAsModel", true, "java"); +``` + +The convenience method then returns the generated header model (built directly from the response headers, without any serialization) instead of `void`, while the protocol method continues to return `Response`. Using the option on an operation that has a response body reports an error. diff --git a/.chronus/changes/http-client-java-test-new-generated-clients-2026-08-13.md b/.chronus/changes/http-client-java-test-new-generated-clients-2026-08-13.md new file mode 100644 index 00000000000..102f9b6bafb --- /dev/null +++ b/.chronus/changes/http-client-java-test-new-generated-clients-2026-08-13.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Add end-to-end tests for newly generated Java clients \ No newline at end of file diff --git a/.chronus/changes/http-client-java-update-node-dependencies-2026-08-13.md b/.chronus/changes/http-client-java-update-node-dependencies-2026-08-13.md new file mode 100644 index 00000000000..9e205d47a4e --- /dev/null +++ b/.chronus/changes/http-client-java-update-node-dependencies-2026-08-13.md @@ -0,0 +1,7 @@ +--- +changeKind: dependencies +packages: + - "@typespec/http-client-java" +--- + +Update Node.js dependencies and regenerate Java test assets \ No newline at end of file diff --git a/.chronus/changes/http-client-java-update-node-dependencies-2026-7-15.md b/.chronus/changes/http-client-java-update-node-dependencies-2026-7-15.md new file mode 100644 index 00000000000..70f3ab4d717 --- /dev/null +++ b/.chronus/changes/http-client-java-update-node-dependencies-2026-7-15.md @@ -0,0 +1,7 @@ +--- +changeKind: dependencies +packages: + - "@typespec/http-client-java" +--- + +Update Node.js dependencies diff --git a/.chronus/changes/http-client-java_bump-dep-2026-7-6-12-54-44.md b/.chronus/changes/http-client-java_bump-dep-2026-7-6-12-54-44.md new file mode 100644 index 00000000000..ecf6c39b566 --- /dev/null +++ b/.chronus/changes/http-client-java_bump-dep-2026-7-6-12-54-44.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Bump dependencies \ No newline at end of file diff --git a/.chronus/changes/http-client-java_bump-dep-part2-2026-7-10-13-33-30.md b/.chronus/changes/http-client-java_bump-dep-part2-2026-7-10-13-33-30.md new file mode 100644 index 00000000000..28c222b6397 --- /dev/null +++ b/.chronus/changes/http-client-java_bump-dep-part2-2026-7-10-13-33-30.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +bump dependencies \ No newline at end of file diff --git a/.chronus/changes/http-client-java_dpg-xml-2026-6-20-12-47-29.md b/.chronus/changes/http-client-java_dpg-xml-2026-6-20-12-47-29.md new file mode 100644 index 00000000000..084614f6742 --- /dev/null +++ b/.chronus/changes/http-client-java_dpg-xml-2026-6-20-12-47-29.md @@ -0,0 +1,7 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client-java" +--- + +Support XML serialization for models: generate XmlSerializer helper classes and use the XML ObjectSerializer overload of toObject/fromObject in convenience methods for XML request/response bodies. \ No newline at end of file diff --git a/.chronus/changes/iscai-msft-add-sse-spector-scenarios-2026-7-10-14-23-58.md b/.chronus/changes/iscai-msft-add-sse-spector-scenarios-2026-7-10-14-23-58.md new file mode 100644 index 00000000000..47a907457c6 --- /dev/null +++ b/.chronus/changes/iscai-msft-add-sse-spector-scenarios-2026-7-10-14-23-58.md @@ -0,0 +1,11 @@ +--- +changeKind: feature +packages: + - "@typespec/http-specs" +--- + +Add SSE protocol coverage for event IDs, retry fields, and reconnection + +```tsp +op reconnect(): SSEStream; +``` diff --git a/.chronus/changes/java-diagnostic-doc-path-2026-08-06-13-10-00.md b/.chronus/changes/java-diagnostic-doc-path-2026-08-06-13-10-00.md new file mode 100644 index 00000000000..8c6108b1e72 --- /dev/null +++ b/.chronus/changes/java-diagnostic-doc-path-2026-08-06-13-10-00.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Make the diagnostic documentation source path configurable for reuse across emitter packages. diff --git a/.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md b/.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md new file mode 100644 index 00000000000..620f6f34ee7 --- /dev/null +++ b/.chronus/changes/java-diagnostic-docs-2026-08-04-16-55-00.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Add reference documentation for Java emitter diagnostics. diff --git a/.chronus/changes/java-premium-sample-client-routing-2026-08-12-13-27-00.md b/.chronus/changes/java-premium-sample-client-routing-2026-08-12-13-27-00.md new file mode 100644 index 00000000000..7cd99c348bf --- /dev/null +++ b/.chronus/changes/java-premium-sample-client-routing-2026-08-12-13-27-00.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Fix Fluent Premium samples to use the correct service client for resource metadata suffixes. diff --git a/.chronus/changes/josh-experimental-diagnostic-id-2026-7-14-15-54-50.md b/.chronus/changes/josh-experimental-diagnostic-id-2026-7-14-15-54-50.md new file mode 100644 index 00000000000..db14f58c0fa --- /dev/null +++ b/.chronus/changes/josh-experimental-diagnostic-id-2026-7-14-15-54-50.md @@ -0,0 +1,12 @@ +--- +changeKind: feature +packages: + - "@typespec/http-client" +--- + +Add diagnostic and dependency metadata to `@experimental`. + +```typespec +@experimental(#{ diagnosticId: "C", dependsOn: #["A", "B"] }) +op bar(): void; +``` \ No newline at end of file diff --git a/.chronus/changes/playground-preserve-sample-config-2026-08-13.md b/.chronus/changes/playground-preserve-sample-config-2026-08-13.md new file mode 100644 index 00000000000..975fc5db36d --- /dev/null +++ b/.chronus/changes/playground-preserve-sample-config-2026-08-13.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/playground" +--- + +Preserve a sample's preferred emitter and compiler options when loading it in the playground. diff --git a/.chronus/changes/python-arm-service-group-tests-2026-7-27-8-59-27.md b/.chronus/changes/python-arm-service-group-tests-2026-7-27-8-59-27.md new file mode 100644 index 00000000000..330b02ebc10 --- /dev/null +++ b/.chronus/changes/python-arm-service-group-tests-2026-7-27-8-59-27.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Add test coverage for Azure ARM service group extension resources and ARM resource identifier group scope diff --git a/.chronus/changes/python-enable-arm-operationtemplates-tests-2026-08-17.md b/.chronus/changes/python-enable-arm-operationtemplates-tests-2026-08-17.md new file mode 100644 index 00000000000..dfa70624d02 --- /dev/null +++ b/.chronus/changes/python-enable-arm-operationtemplates-tests-2026-08-17.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Enable sync and async Azure ARM operation templates test coverage. diff --git a/.chronus/changes/python-spector-tests-arm-optemplate-clientapiversions-2026-7-27-8-55-0.md b/.chronus/changes/python-spector-tests-arm-optemplate-clientapiversions-2026-7-27-8-55-0.md new file mode 100644 index 00000000000..adc0284cc01 --- /dev/null +++ b/.chronus/changes/python-spector-tests-arm-optemplate-clientapiversions-2026-7-27-8-55-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Add mock API tests for new Spector scenarios: ARM operation templates (Legacy RoutedOperations, LRO on GET, POST LRO with paging body, POST action paging, markAsPageable) and `@clientApiVersions` decorator diff --git a/.chronus/changes/refactor-api-metadata-2026-08-04-13-50-00.md b/.chronus/changes/refactor-api-metadata-2026-08-04-13-50-00.md new file mode 100644 index 00000000000..15f6c0e8729 --- /dev/null +++ b/.chronus/changes/refactor-api-metadata-2026-08-04-13-50-00.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Centralize generated API metadata in a dedicated model. diff --git a/.chronus/changes/remove-dpg-java-diagnostic-docs-2026-08-07-10-05-00.md b/.chronus/changes/remove-dpg-java-diagnostic-docs-2026-08-07-10-05-00.md new file mode 100644 index 00000000000..4f8d7821465 --- /dev/null +++ b/.chronus/changes/remove-dpg-java-diagnostic-docs-2026-08-07-10-05-00.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Remove Azure-specific diagnostic documentation from the unbranded Java emitter. diff --git a/.chronus/changes/standalone-skip-shell-rerun-2026-7-30-1-48-14.md b/.chronus/changes/standalone-skip-shell-rerun-2026-7-30-1-48-14.md new file mode 100644 index 00000000000..fe489bff5d2 --- /dev/null +++ b/.chronus/changes/standalone-skip-shell-rerun-2026-7-30-1-48-14.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/standalone-cli" +--- + +Fix install script adding duplicate PATH entries to shell config files (`.bashrc`, `.zshrc`, etc.) on subsequent runs. The script now detects if TypeSpec is already configured and skips the shell update. Also fix `--skip-shell` flag which was using an inconsistent variable name and had no effect. diff --git a/.chronus/changes/type-import-emitter-java-2026-7-31.md b/.chronus/changes/type-import-emitter-java-2026-7-31.md new file mode 100644 index 00000000000..30858f5275c --- /dev/null +++ b/.chronus/changes/type-import-emitter-java-2026-7-31.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-java" +--- + +Enable `verbatimModuleSyntax` in the emitter's TypeScript config and convert type-only imports/exports to `import type`/`export type`. diff --git a/.chronus/changes/weidongxu-microsoft-fix-maxpagesize-sample-2026-6-29-14-26-5.md b/.chronus/changes/weidongxu-microsoft-fix-maxpagesize-sample-2026-6-29-14-26-5.md new file mode 100644 index 00000000000..c415de10873 --- /dev/null +++ b/.chronus/changes/weidongxu-microsoft-fix-maxpagesize-sample-2026-6-29-14-26-5.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Fixed an issue where the generated sample for a pageable method included the hidden maxpagesize parameter, producing code that did not match the client method signature. \ No newline at end of file diff --git a/.chronus/changes/weidongxu-microsoft-fix-random-map-key-credential-2026-6-29-13-47-42.md b/.chronus/changes/weidongxu-microsoft-fix-random-map-key-credential-2026-6-29-13-47-42.md new file mode 100644 index 00000000000..5989a721b15 --- /dev/null +++ b/.chronus/changes/weidongxu-microsoft-fix-random-map-key-credential-2026-6-29-13-47-42.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Fixed an issue where a randomly generated JSON map key in the mock test could contain a credential phrase (e.g. key) and be unexpectedly redacted to fakeTokenPlaceholder by the test proxy. \ No newline at end of file diff --git a/.chronus/changes/weidongxu-nested-pageable-2026-07-31-11-59-00.md b/.chronus/changes/weidongxu-nested-pageable-2026-07-31-11-59-00.md new file mode 100644 index 00000000000..d42a7510ba9 --- /dev/null +++ b/.chronus/changes/weidongxu-nested-pageable-2026-07-31-11-59-00.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-java" +--- + +Support nested property paths in Azure pageable responses. diff --git a/.chronus/config.yaml b/.chronus/config.yaml index 39eb1f5dd5b..7231b371acf 100644 --- a/.chronus/config.yaml +++ b/.chronus/config.yaml @@ -59,7 +59,8 @@ versionPolicies: - "@typespec/sse" - "@typespec/streams" - "@typespec/xml" - - "@typespec/standalone-cli" + - "@typespec/http-specs" + - "@typespec/graphql" - name: standalone type: independent diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 00000000000..968b2b43b42 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,16 @@ +{ + "permissions": { + "allow": [ + "Bash(npx vitest *)", + "Bash(node -e \"const p=require\\('./packages/compiler/package.json'\\); console.log\\(JSON.stringify\\(p.exports['./testing'],null,2\\)\\); console.log\\('---main---'\\); console.log\\(JSON.stringify\\(p.exports['.'],null,2\\)\\)\")", + "Bash(node -e \"const p=require\\('./packages/compiler/package.json'\\); console.log\\('declared:', p.dependencies['vscode-languageserver']\\)\")", + "Bash(node -e \"const p=require\\('./node_modules/.pnpm/vscode-languageserver@9.0.1/node_modules/vscode-languageserver/package.json'\\); console.log\\(JSON.stringify\\(p.exports,null,2\\)\\)\")", + "Bash(npm run *)", + "Bash(node -e \"const p=require\\('./node_modules/.pnpm/lock'\\);\")", + "Bash(pnpm chronus *)", + "Bash(xargs cat)", + "Bash(npx prettier *)", + "Bash(pnpm run *)" + ] + } +} diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index cea8dd89635..2af0291724a 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -1,3 +1,13 @@ -FROM mcr.microsoft.com/devcontainers/javascript-node:24 +FROM mcr.microsoft.com/devcontainers/base:ubuntu -RUN npm install -g pnpm +# Install mise for toolchain management (node, pnpm, etc.) +RUN curl https://mise.run | MISE_INSTALL_PATH=/usr/local/bin/mise sh \ + && echo 'eval "$(/usr/local/bin/mise activate bash)"' >> /home/vscode/.bashrc \ + && echo 'eval "$(/usr/local/bin/mise activate zsh)"' >> /home/vscode/.zshrc + +# Pre-install all toolchain versions pinned in mise.toml/mise.lock into the image +COPY mise.toml mise.lock /tmp/mise-setup/ +RUN chown -R vscode:vscode /tmp/mise-setup +USER vscode +RUN cd /tmp/mise-setup && mise trust && mise install +USER root diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index f6a0d44226a..bc90b1deeda 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,8 +1,10 @@ { "name": "Standard", "build": { - "dockerfile": "Dockerfile" + "dockerfile": "Dockerfile", + "context": ".." }, + "postCreateCommand": "mise trust && pnpm install", "customizations": { // Configure properties specific to VS Code. "vscode": { diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f8f844c556a..134d246ac5a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,5 +1,5 @@ # Catch all -* @bterlson @markcowl @timotheeguerin @witemple-msft @iscai-msft @catalinaperalta +* @markcowl @timotheeguerin @iscai-msft @catalinaperalta @lmazuel # Those files/folders can be modified by anyone .chronus/changes/ @@ -9,37 +9,37 @@ cspell.yaml ###################### # Emiter Shared ###################### -/eng/emitters/ @JoshLove-msft @iscai-msft @timotheeguerin @l0lawrence -/docs/samples/client/ @lmazuel @JoshLove-msft @iscai-msft @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @tadelesh @msyyc @joheredi @timotheeguerin @qiaozha @MaryGao @l0lawrence +/eng/emitters/ @JoshLove-msft @iscai-msft @timotheeguerin @l0lawrence @xirzec @markcowl @catalinaperalta +/docs/samples/client/ @lmazuel @JoshLove-msft @iscai-msft @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @tadelesh @msyyc @xirzec @timotheeguerin @qiaozha @MaryGao @l0lawrence ###################### # CSharp ###################### -/packages/http-client-csharp/ @m-nash @JoshLove-msft @jorgerangel-msft @jsquire @ShivangiReja @joseharriaga -/docs/samples/client/csharp @JoshLove-msft @jorgerangel-msft @jsquire @ShivangiReja @joseharriaga -/website/src/content/docs/docs/emitters/clients/http-client-csharp/ @JoshLove-msft @jorgerangel-msft @jsquire @ShivangiReja @joseharriaga +/packages/http-client-csharp/ @m-nash @JoshLove-msft @jorgerangel-msft @jsquire @joseharriaga +/docs/samples/client/csharp @JoshLove-msft @jorgerangel-msft @jsquire @joseharriaga +/website/src/content/docs/docs/emitters/clients/http-client-csharp/ @JoshLove-msft @jorgerangel-msft @jsquire @joseharriaga ###################### # Java ###################### -/packages/http-client-java/ @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @alzimmermsft -/website/src/content/docs/docs/emitters/clients/http-client-java/ @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @alzimmermsft -/.github/instructions/http-client-java.instructions.md @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @alzimmermsft +/packages/http-client-java/ @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @alzimmermsft @jsquire +/website/src/content/docs/docs/emitters/clients/http-client-java/ @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @alzimmermsft @jsquire +/.github/instructions/http-client-java.instructions.md @weidongxu-microsoft @haolingdong-msft @XiaofeiCao @alzimmermsft @jsquire ###################### # Python ###################### -/packages/http-client-python/ @iscai-msft @tadelesh @msyyc @timotheeguerin @lmazuel @catalinaperalta @ChenxiJiang333 @l0lawrence @kashifkhan -/website/src/content/docs/docs/emitters/clients/http-client-python/ @iscai-msft @tadelesh @msyyc @timotheeguerin @lmazuel @catalinaperalta @ChenxiJiang333 @l0lawrence @kashifkhan +/packages/http-client-python/ @iscai-msft @tadelesh @msyyc @timotheeguerin @lmazuel @catalinaperalta @ChenxiJiang333 @l0lawrence @kashifkhan @xirzec @markcowl +/website/src/content/docs/docs/emitters/clients/http-client-python/ @iscai-msft @tadelesh @msyyc @timotheeguerin @lmazuel @catalinaperalta @ChenxiJiang333 @l0lawrence @kashifkhan @xirzec @markcowl ###################### # JavaScript ###################### -/packages/http-client-js/ @joheredi @timotheeguerin @timovv @qiaozha @MaryGao @xirzec @bterlson @markcowl @witemple-msft +/packages/http-client-js/ @timotheeguerin @qiaozha @MaryGao @xirzec @markcowl @maorleger @iscai-msft @catalinaperalta ###################### # IDE ###################### -/packages/typespec-vs/ @RodgeFu @lirenhe @bterlson @markcowl @witemple-msft @timotheeguerin @iscai-msft @catalinaperalta -/packages/typespec-vscode/ @RodgeFu @lirenhe @bterlson @markcowl @witemple-msft @timotheeguerin @iscai-msft @catalinaperalta -/packages/compiler/src/server/ @RodgeFu @bterlson @markcowl @witemple-msft @timotheeguerin @iscai-msft @catalinaperalta +/packages/typespec-vs/ @RodgeFu @lirenhe @bterlson @markcowl @timotheeguerin @iscai-msft @catalinaperalta @lmazuel +/packages/typespec-vscode/ @RodgeFu @lirenhe @bterlson @markcowl @timotheeguerin @iscai-msft @catalinaperalta @lmazuel +/packages/compiler/src/server/ @RodgeFu @bterlson @markcowl @timotheeguerin @iscai-msft @catalinaperalta @lmazuel diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml index 70185d3180b..7ffdcda72ff 100644 --- a/.github/actions/setup/action.yml +++ b/.github/actions/setup/action.yml @@ -11,10 +11,10 @@ runs: steps: - name: Install pnpm - uses: pnpm/action-setup@v3 + uses: pnpm/action-setup@v6 - name: Set node version to ${{ inputs.node-version }} - uses: actions/setup-node@v4 + uses: actions/setup-node@v5 with: node-version: ${{ inputs.node-version }} cache: pnpm diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6c393aedfa5..09a403d1adc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -26,7 +26,7 @@ TypeSpec is a language for defining cloud service APIs and shapes. This monorepo ### Testing and Validation - **CRITICAL**: Run all tests: `pnpm test` (takes ~5 minutes, NEVER CANCEL - set timeout to 10+ minutes) -- Run E2E tests: `pnpm test:e2e` and `node e2e/e2e-tests.js` (~1 minute) +- Run E2E tests: `pnpm test:e2e` and `node e2e/e2e-tests.ts` (~1 minute) - Run tests with coverage: `pnpm test:ci` - Run tests in watch mode (in specific package): `pnpm test:watch` @@ -120,8 +120,9 @@ TypeSpec is a language for defining cloud service APIs and shapes. This monorepo ## Commit instructions -- Always run the linting and the formatting commands before any commit. +- Always run the linting and the formatting commands before any commit. In particular, always run `pnpm format` before committing. - Follow conventional commits. +- Avoid committing `pnpm-lock.yaml` unless absolutely necessary. ## Pull Request instructions @@ -152,6 +153,11 @@ Out-of-sync releases and hotfix releases follow the same flow using a `publish/` - For **out-of-sync releases**, the PR targets `main` - For **hotfix releases**, the PR targets the corresponding `release/*` branch (e.g., `release/v0.60`) instead of `main` +## Branch and PR Workflow + +- When creating new branches or worktrees, base them off the main Microsoft fork's `main` branch (`Microsoft/typespec`). This remote might be called `upstream` or `origin` depending on your local git setup — the key point is to always branch from the main Microsoft fork, not a personal fork. +- When pushing changes and creating pull requests, push to your personal fork and open PRs against the main Microsoft fork's `main` branch. + ## Available Task Instructions - [Testserver Generation](./prompts/testserver-generation.md): Instructions for generating TypeSpec HTTP spec test servers diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 3527461144a..1e718f8a844 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -13,6 +13,8 @@ updates: package-ecosystem: pip schedule: interval: weekly + cooldown: + default-days: 7 - directory: / exclude-paths: - packages/http-client-csharp @@ -115,6 +117,8 @@ updates: package-ecosystem: npm schedule: interval: weekly + cooldown: + default-days: 7 - directory: / exclude-paths: - .github/workflows/*.lock.{yaml,yml} @@ -128,4 +132,6 @@ updates: package-ecosystem: github-actions schedule: interval: weekly + cooldown: + default-days: 7 version: 2 diff --git a/.github/instructions/http-client-java.instructions.md b/.github/instructions/http-client-java.instructions.md index 2362bc4a8ec..98d1338a792 100644 --- a/.github/instructions/http-client-java.instructions.md +++ b/.github/instructions/http-client-java.instructions.md @@ -4,6 +4,7 @@ applyTo: "packages/http-client-java/**/*" - The directories mentioned in this instruction are relative to `/packages/http-client-java`. For example, the root is the folder `/packages/http-client-java`; the directory `generator/http-client-generator-test` refers to `/packages/http-client-java/generator/http-client-generator-test`. - Always use absolute paths when changing directories or running scripts. +- Whenever calling `npm`, use `--registry=https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-js/npm/registry/`. # Update Node.js packages for latest dependencies @@ -11,7 +12,7 @@ Steps: 1. Run `ncu -u` on `package.json` in the root and on the two `package.json` files in `generator/http-client-generator-clientcore-test` and `generator/http-client-generator-test`. 2. Update package versions in `peerDependencies` (keep the semver ranges) in the root `package.json` to match the corresponding package versions listed in `devDependencies`. -3. Update package versions in `override` (keep the semver ranges) in the other two `package.json` files to match the corresponding package versions in the root `package.json`. +3. Update package versions in `overrides` (keep the semver ranges) in the other two `package.json` files to match the corresponding package versions in the root `package.json`. 4. Save the files and run `npm install` in the root so that `package-lock.json` is updated. 5. Commit the changes to `package.json` and `package-lock.json`. 6. If there is an update to the `http-specs` or `azure-http-specs` libraries, run `Generate.ps1` in `generator/http-client-generator-test` and commit the generated changes in that folder. @@ -34,9 +35,9 @@ The publish workflow (to NPM) will be automatically triggered after the PR is me Typical task: `add e2e test case for , scenario is `. -- The execution of `mvn` and `npm` command should be done in the test directory `/packages/http-client-java/generator/http-client-generator-test`. +- The execution of `mvn` and `npm` commands should be done in the test directory `/packages/http-client-java/generator/http-client-generator-test`. - Only commit Java files written by you. Do not commit any generated files. -- If no scenario URL provided, search the related files in either https://github.com/microsoft/typespec/tree/main/packages/http-specs/specs or https://github.com/Azure/typespec-azure/tree/main/packages/azure-http-specs/specs +- If no scenario URL is provided, search the related files in either https://github.com/microsoft/typespec/tree/main/packages/http-specs/specs or https://github.com/Azure/typespec-azure/tree/main/packages/azure-http-specs/specs 0. Run `pwsh Setup.ps1` in `generator/http-client-generator-test` to set up the environment if not done before. 1. The source files for the generated client under test are located in `generator/http-client-generator-test/src/main/java/`. @@ -44,9 +45,9 @@ Typical task: `add e2e test case for , scenario is `. 3. Read the Java model classes under `generator/http-client-generator-test/src/main/java//models` to understand the data types used by the APIs. 4. Read the TypeSpec file at the given `` to understand the scenario. The TypeSpec file contains the expected HTTP request and response in the `@scenarioDoc` decorator. 5. Optionally, check for a `client.tsp` in the same folder (replace `main.tsp` with `client.tsp` in the URL). Use it if present. -6. Review a few existing test cases in `generator/http-client-generator-test/src/test/java/` to learn the test structure and patterns used. Do not read file under `**/generated` folder. -7. Add a new test class in `generator/http-client-generator-test/src/test/java//` named `Tests.java`, following existing conventions. The test class should not extend other class. -8. Make sure compile pass (`mvn clean compile`). +6. Review a few existing test cases in `generator/http-client-generator-test/src/test/java/` to learn the test structure and patterns used. Do not read files under the `**/generated` folder. +7. Add a new test class in `generator/http-client-generator-test/src/test/java//` named `Tests.java`, following existing conventions. The test class should not extend any other class. +8. Make sure compilation passes (`mvn clean compile`). 9. Start Spector server by `npm run spector-start`. 10. Run the tests (`mvn test`). Make sure all tests pass. 11. Stop Spector server by `npm run spector-stop`. @@ -54,4 +55,63 @@ Typical task: `add e2e test case for , scenario is `. # Add feature or fix bug -- Run `npm run format` and commit the formatted code, before finalizing. Do not include any other changes in the commit. +- Run `npm run format` and commit the formatted code before finalizing. Do not include any other changes in the commit. +- Add a changelog entry: `pnpm change add @typespec/http-client-java --kind= --message=""` (use `feature` for new features, `fix` for bug fixes). Commit the new md file in the ".chronus" folder of the repository root. + +# Modify the code generator (emitter + generator e2e loop) + +Use this workflow when a change requires modifying how client code is generated (not just adding tests). + +The code generator has two connected parts, linked by a `code-model.yaml`: + +- `emitter/` — TypeScript. Consumes the TypeSpec compiler output and produces `code-model.yaml`. +- `generator/` — Java. Consumes `code-model.yaml` and emits the Java client source. + +After a compile, inspect `tsp-output/**/code-model.yaml` in the test module to see what the emitter passed to the generator. + +## Edit → update emitter → test loop + +1. Make the emitter (TypeScript) and/or generator (Java) changes. +2. Ensure the generator compiles: `mvn clean install --define spotless:skip --define skipTests --no-transfer-progress -T 1C -f ./generator/pom.xml` (from `/packages/http-client-java`). +3. Ensure the emitter builds: `npm run build:emitter`. +4. Format Java with `mvn spotless:apply --no-transfer-progress -T 1C --activate-profiles test -f ./generator/pom.xml` and TypeScript via `npm run format`. +5. Run `pwsh Setup.ps1` in `generator/http-client-generator-test`. This packs the emitter (bundling the freshly built generator jar) and installs it into the test module. Re-run it after every generator/emitter change you want reflected in generation. +6. Regenerate by compiling a spec. Do NOT hardcode the TypeSpec file name — it varies per feature, and sometimes you must author a new `/main.tsp` first. The test module's `tspconfig.yaml` already configures the emitter and its output dir, so a plain compile is enough; output goes to `tsp-output/`: + `npx tsp compile ` + (Optionally add `--option "@typespec/http-client-java.emitter-output-dir=$PWD/tsp-output/"` to isolate output into a subfolder for an easier diff.) + Do NOT run `Generate.ps1` to test one spec. It regenerates every test client, deletes and rebuilds generated source directories, and is reserved for intentional full regeneration (such as a test-spec dependency update). +7. Verify the generated code under `tsp-output/**/src` is as expected. When the spec corresponds to sources tracked in `src/main/java`, compare against them and, if correct, copy the generated files into `src` (replacing existing files) but EXCLUDE `module-info.java`. Some specs do not map to `src` — in that case just verify the output, without comparing or copying. +8. When the spec maps to `src` and you copied the generated code in, run the tests (`mvn test`, or a targeted `--define "test=."`). Restart the Spector server if needed (`npm run spector-stop` then `npm run spector-start`). If the spec does not map to `src`, verifying the generated output (step 7) is sufficient. + +### Inspect the TCGC output (SDK model) + +To debug how the emitter sees a spec, dump the TCGC SDK model (`SdkPackage`) it consumes — upstream of `code-model.yaml` — instead of adding emitter debug logging. Run TCGC as the emitter (already installed in the test module): + +``` +npx tsp compile --emit @azure-tools/typespec-client-generator-core --option "@azure-tools/typespec-client-generator-core.emitter-output-dir=$PWD/tcgc-output" +``` + +This writes `tcgc-output/tcgc-output.yaml` (keys starting with `__` are omitted). It changes no code; the dump is verification-only, so do NOT commit it — delete it when done. + +### Test on a real Azure service spec + +Smoke-test a generator change against a real service spec from `azure-rest-api-specs`, generating into an actual `azure-sdk-for-java` package. Use this for behavior the spector-style specs do not exercise (for example `sdk-integration` output such as `CHANGELOG.md`). Works the same for data-plane and management (Fluent Lite / Premium) — only the emitter options differ (see the service's `tspconfig.yaml`). Assumes both repos are cloned locally with TypeSpec library versions matching the emitter's. + +1. Install the local emitter into the test module: `pwsh Setup.ps1` in `generator/http-client-generator-test`. +2. The service spec resolves emitters from **its own** `node_modules` (the published `@azure-tools/typespec-java`, not your local build). Do NOT swap jars or hand-edit `node_modules`. Instead, `robocopy $specDir $tmp *.tsp /S` the spec's `*.tsp` files (preserving layout) into a temp folder under the test module, so resolution falls back to the test module's `node_modules` (your fresh emitter + all azure libs). Copy any sibling spec folders the entry imports via relative paths too; shared/common models pulled from libraries (for example ARM common-types) resolve from `node_modules` and need not be copied. The copy has no `tspconfig.yaml`, so only your `--emit` runs. +3. Compile the entry (`client.tsp`, else `main.tsp`) with the emitter options from the service's real `tspconfig.yaml` (`@azure-tools/typespec-java` block), pointing `emitter-output-dir` at the **real** SDK package. Generating into the existing package is also what drives `sdk-integration` detection: + ``` + npx tsp compile --emit "@typespec/http-client-java" \ + --option "@typespec/http-client-java.emitter-output-dir=" \ + --option "@typespec/http-client-java.=" # namespace, service-name, flavor=azure, (premium), ... + ``` +4. Verify the change your feature/fix is expected to produce (for example `git --no-pager diff -- /`). +5. Clean up — generation overwrites the whole package. Restore it (`git checkout` + `git clean -fdq` on the package) and delete the temp copy. Do not commit generated changes to either external repo. + +## Emitting static helper classes from resource templates + +Some helpers are shipped verbatim as resource templates rather than built up in code: + +- `generator/http-client-generator/src/main/java/.../TypeSpecPlugin.java` — `writeHelperClasses(...)` emits per-client helper classes into the implementation subpackage via `JavaPackage.addJavaFromResources(packageName, resourceName[, fileName])`. +- Resource templates live under `generator/http-client-generator-core/src/main/resources/*.java` and must START with `import` statements — do NOT include a `package` line or the license header. The file factory injects the license header, the `package` statement, and reorders imports. The class name must match the resource/file name. +- Class-name constants live in `generator/http-client-generator-core/src/main/java/.../util/ClientModelUtil.java`. diff --git a/.github/policies/prs.external-reviewers.generated.yml b/.github/policies/prs.external-reviewers.generated.yml new file mode 100644 index 00000000000..404ceb92720 --- /dev/null +++ b/.github/policies/prs.external-reviewers.generated.yml @@ -0,0 +1,32 @@ +# This file is generated by the sync-labels script DO NOT EDIT manually +# cspell:ignore fionabronwen steverice swatkatz +id: prs.external-reviewers +name: Notify external area owners on PRs +description: GitHub doesn't allow CODEOWNERS entries or formal review requests + for users that are not repository collaborators, but some areas are + contributed by external teams. Mention those owners in a comment instead. + https://github.com/orgs/community/discussions/23042 +resource: repository +disabled: false +configuration: + resourceManagementConfiguration: + eventResponderTasks: + - if: + - payloadType: Pull_Request + then: + - if: + - includesModifiedFiles: + files: + - packages/graphql/**/* + - not: + hasLabel: + label: emitter:graphql + then: + - addReply: + reply: "@fionabronwen @swatkatz @steverice — this PR modifies files in the + `emitter:graphql` area, which your team owns. Please take a + look. (You can't be added as a formal reviewer because + you're not a repository collaborator, so this is a heads-up + instead.)" + - addLabel: + label: emitter:graphql diff --git a/.github/policies/prs.external-reviewers.yml b/.github/policies/prs.external-reviewers.yml deleted file mode 100644 index 697150e62a5..00000000000 --- a/.github/policies/prs.external-reviewers.yml +++ /dev/null @@ -1,21 +0,0 @@ -# cspell:ignore swatkatz -id: prs.external-reviewers -name: Assign External Reviewers to PRs. -description: Github doesn't allow CODEOWNERS to have external users but some emitters are contributed externally https://github.com/orgs/community/discussions/23042 -resource: repository -disabled: false -configuration: - resourceManagementConfiguration: - eventResponderTasks: - - if: - - payloadType: Pull_Request - then: - - if: - - includesModifiedFiles: - files: - - packages/graphql/**/* - then: - - requestReview: - reviewer: steverice - - requestReview: - reviewer: swatkatz diff --git a/.github/skills/csharp-spector-coverage-gaps/SKILL.md b/.github/skills/csharp-spector-coverage-gaps/SKILL.md index c95fb1a5a7b..2232af6b222 100644 --- a/.github/skills/csharp-spector-coverage-gaps/SKILL.md +++ b/.github/skills/csharp-spector-coverage-gaps/SKILL.md @@ -240,11 +240,12 @@ The test directory structure mirrors the spec path with these transformations: **Namespace pattern**: `TestProjects.Spector.Tests.Http.` Example mappings: -| Spec path | Test directory | Namespace | -|-----------|---------------|-----------| -| `http/encode/duration` | `Http/Encode/Duration/` | `TestProjects.Spector.Tests.Http.Encode.Duration` | + +| Spec path | Test directory | Namespace | +| ------------------------------- | --------------------------------- | ----------------------------------------------------------- | +| `http/encode/duration` | `Http/Encode/Duration/` | `TestProjects.Spector.Tests.Http.Encode.Duration` | | `http/type/union/discriminated` | `Http/_Type/Union/Discriminated/` | `TestProjects.Spector.Tests.Http._Type.Union.Discriminated` | -| `http/special-words` | `Http/SpecialWords/` | `TestProjects.Spector.Tests.Http.SpecialWords` | +| `http/special-words` | `Http/SpecialWords/` | `TestProjects.Spector.Tests.Http.SpecialWords` | ### Test file template diff --git a/.github/workflows/agentics-maintenance.yml b/.github/workflows/agentics-maintenance.yml index bb3cc13188e..afcb1b247cf 100644 --- a/.github/workflows/agentics-maintenance.yml +++ b/.github/workflows/agentics-maintenance.yml @@ -158,7 +158,7 @@ jobs: operation: ${{ steps.record.outputs.operation }} steps: - name: Checkout repository - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -249,7 +249,7 @@ jobs: run_url: ${{ steps.record.outputs.run_url }} steps: - name: Checkout actions folder - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: sparse-checkout: | actions @@ -297,7 +297,7 @@ jobs: issues: write steps: - name: Checkout repository - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -343,7 +343,7 @@ jobs: issues: write steps: - name: Checkout repository - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -448,7 +448,7 @@ jobs: issues: write steps: - name: Checkout repository - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false @@ -577,7 +577,7 @@ jobs: issues: write steps: - name: Checkout repository - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml new file mode 100644 index 00000000000..e3a433ee54c --- /dev/null +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -0,0 +1,147 @@ +name: "python / emitter diff" + +# Diffs generated code between this PR's emitter and the merge-base baseline. +# Informational only: reports a sticky PR comment + HTML artifact, and fails the +# job only on a tool/build error (never on a diff). See eng/emitter-diff. +# +# The tool runs `npm run regenerate` verbatim in each tree. It auto-prepares the +# baseline tree it fetches from GitHub (via the preset's --setup: install + +# build + venv), so this workflow only builds the head (PR) emitter itself. + +on: + pull_request: + branches: [main, release/*] + paths: + - "packages/http-client-python/**" + - "eng/emitter-diff/**" + - ".github/workflows/ci-emitter-diff-python.yml" + workflow_dispatch: + inputs: + baseline: + description: "Baseline emitter ref (local path or github ref). Defaults to the PR merge-base. A gh:/github: ref is fetched and auto-prepared (install + build) by the tool; a local: path is used as-is." + required: false + default: "" + +permissions: + contents: read + pull-requests: write + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + emitter-diff: + name: "Generate & Diff" + runs-on: ubuntu-latest + # Fork PRs are intentionally skipped + if: github.event.pull_request.head.repo.fork != true + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 + - uses: ./.github/actions/setup + - uses: actions/setup-python@v7 + with: + python-version: "3.12" + + - name: Install repo dependencies + run: pnpm install + + - name: Determine baseline + id: baseline + # Dispatch input is untrusted: pass via env, reference only as "$VAR". + env: + BASELINE_INPUT: ${{ github.event.inputs.baseline || '' }} + BASE_REF: ${{ github.event.pull_request.base.ref || github.event.repository.default_branch }} + run: | + input="$BASELINE_INPUT" + if [ -n "$input" ]; then + echo "ref=$input" >> "$GITHUB_OUTPUT" + echo "Baseline (explicit): $input" + else + # merge-base = a real commit on the base branch; survives squash/rebase. + git fetch --no-tags origin "$BASE_REF" + base_sha="$(git merge-base FETCH_HEAD HEAD)" + [ -n "$base_sha" ] || { echo "::error::No merge-base with $BASE_REF."; exit 1; } + # gh: = this repo at the merge-base. The tool fetches that tree + # and auto-preps it (install + build + venv) via the preset's --setup. + echo "ref=gh:$base_sha" >> "$GITHUB_OUTPUT" + echo "Baseline (merge-base): gh:$base_sha" + fi + + - name: Prepare head emitter (build + venv) + working-directory: packages/http-client-python + # http-client-python is excluded from the pnpm workspace (standalone, + # registry-versioned deps), so the repo-level `pnpm install` above does + # NOT provision its node_modules. Install them first (scripts skipped), + # then `npm run setup` (build + venv). Mirrors the baseline tree prep the + # tool does via the python preset's --setup. + run: | + npm install --ignore-scripts + npm run setup + + - name: Run emitter diff + id: diff + working-directory: packages/http-client-python + env: + BASELINE_REF: ${{ steps.baseline.outputs.ref }} + RUNNER_TEMP: ${{ runner.temp }} + run: | + set +e + # No --fail-on-diff (informational); tool/build errors still exit non-zero + # (checked in "Fail on tool error"). + npm run diff-spector-tests -- \ + --ci \ + --baseline "$BASELINE_REF" \ + --html "$RUNNER_TEMP/emitter-diff.html" \ + --md "$RUNNER_TEMP/emitter-diff.md" \ + | tee "$RUNNER_TEMP/emitter-diff.log" + echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" + # Reuse the tool's own summary line (strip ANSI) instead of re-parsing. + summary="$(sed -r 's/\x1b\[[0-9;]*m//g' "$RUNNER_TEMP/emitter-diff.log" \ + | grep -oE 'Diff summary: [0-9]+ file\(s\), \+[0-9]+ / -[0-9]+' | head -1)" + echo "summary=${summary:-No changes to generated output.}" >> "$GITHUB_OUTPUT" + # Render the diff inline on the run page. + if [ -f "$RUNNER_TEMP/emitter-diff.md" ]; then + cat "$RUNNER_TEMP/emitter-diff.md" >> "$GITHUB_STEP_SUMMARY" + fi + + - name: Upload HTML diff + if: always() + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: emitter-diff-html + path: ${{ runner.temp }}/emitter-diff.html + if-no-files-found: ignore + retention-days: 7 + + - name: Comment on PR + if: always() && github.event_name == 'pull_request' + continue-on-error: true + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 + env: + BASELINE: ${{ steps.baseline.outputs.sha || steps.baseline.outputs.ref }} + STATUS: ${{ steps.diff.outputs.status }} + SUMMARY: ${{ steps.diff.outputs.summary }} + with: + script: | + const marker = ""; + const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; + const { STATUS, SUMMARY, BASELINE } = process.env; + let body = `${marker}\n### Python emitter diff\nBaseline \`${BASELINE}\` vs this PR.\n\n`; + body += STATUS !== "0" + ? `⚠️ **emitter-diff failed** (exit \`${STATUS}\`) — tool/build error, not a diff. See the [run](${runUrl}).\n` + : `${SUMMARY}\n\nRendered diff: inline on the [run summary](${runUrl}), or the **emitter-diff-html** artifact.\n`; + body += `\n_Informational check (eng/emitter-diff); does not block the PR._`; + const { owner, repo } = context.repo, issue_number = context.issue.number; + const { data } = await github.rest.issues.listComments({ owner, repo, issue_number }); + const hit = data.find((c) => c.body && c.body.includes(marker)); + if (hit) await github.rest.issues.updateComment({ owner, repo, comment_id: hit.id, body }); + else await github.rest.issues.createComment({ owner, repo, issue_number, body }); + + - name: Fail on tool error + if: always() + env: + STATUS: ${{ steps.diff.outputs.status }} + run: '[ "$STATUS" = "0" ] || { echo "::error::emitter-diff failed (exit $STATUS)."; exit 1; }' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 85454b9e07d..80814d1b043 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -41,7 +41,7 @@ jobs: # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@v4 + uses: github/codeql-action/init@v4.37.3 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. @@ -54,7 +54,7 @@ jobs: # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift). # If this step fails, then you should remove it and run the build manually (see below) - name: Autobuild - uses: github/codeql-action/autobuild@v4 + uses: github/codeql-action/autobuild@v4.37.3 # ℹ️ Command-line programs to run using the OS shell. # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun @@ -67,6 +67,6 @@ jobs: # ./location_of_script_within_repo/buildscript.sh - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4 + uses: github/codeql-action/analyze@v4.37.3 with: category: "/language:${{matrix.language}}" diff --git a/.github/workflows/consistency.yml b/.github/workflows/consistency.yml index e83a123e568..80cc88e26dd 100644 --- a/.github/workflows/consistency.yml +++ b/.github/workflows/consistency.yml @@ -137,3 +137,6 @@ jobs: - run: pnpm run check-catalog name: Check catalog usage + + - run: pnpm run check-lockfile + name: Check lockfile has no tarball URLs diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index db2c9e6a635..3046362efc3 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -21,6 +21,6 @@ jobs: - name: Checkout repository uses: actions/checkout@v7 - name: Install gh-aw extension - uses: github/gh-aw/actions/setup-cli@v0.81.6 + uses: github/gh-aw/actions/setup-cli@v0.83.4 with: version: v0.50.1 diff --git a/.github/workflows/core-ci.yml b/.github/workflows/core-ci.yml index 92800c7d323..c7cff6f9f12 100644 --- a/.github/workflows/core-ci.yml +++ b/.github/workflows/core-ci.yml @@ -32,7 +32,7 @@ jobs: with: node-version: ${{ matrix.node-version }} - - uses: actions/setup-dotnet@v5 + - uses: actions/setup-dotnet@v6 with: dotnet-version: 8.0.x @@ -58,7 +58,7 @@ jobs: retention-days: 5 - name: Check for changed files - run: node eng/common/scripts/check-for-changed-files.js + run: node eng/common/scripts/check-for-changed-files.ts website: name: Website @@ -79,7 +79,7 @@ jobs: run: pnpm --filter "@typespec/website..." run build - name: Check for changed files - run: node eng/common/scripts/check-for-changed-files.js + run: node eng/common/scripts/check-for-changed-files.ts e2e: name: E2E Tests @@ -94,6 +94,8 @@ jobs: - uses: actions/checkout@v7 - uses: ./.github/actions/setup + with: + node-version: 26.x - name: Install dependencies run: pnpm install @@ -139,7 +141,7 @@ jobs: retention-days: 5 - name: Check for changed files - run: node eng/common/scripts/check-for-changed-files.js + run: node eng/common/scripts/check-for-changed-files.ts docker: name: Docker Build diff --git a/.github/workflows/dependabot-pnpm-install.yml b/.github/workflows/dependabot-pnpm-install.yml new file mode 100644 index 00000000000..dab19772c67 --- /dev/null +++ b/.github/workflows/dependabot-pnpm-install.yml @@ -0,0 +1,41 @@ +name: Dependabot pnpm install + +on: + pull_request: + branches: ["main"] + types: [opened] + paths: + - "**/package.json" + - "pnpm-lock.yaml" + - "pnpm-workspace.yaml" + +permissions: {} + +jobs: + sync: + runs-on: ubuntu-latest + if: github.actor == 'dependabot[bot]' + permissions: + contents: write + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ github.head_ref }} + submodules: recursive + + - uses: ./.github/actions/setup + + - run: pnpm install --no-frozen-lockfile + name: Install dependencies + + - name: Commit and push changes + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add -A + if git diff --staged --quiet; then + echo "No changes to commit" + else + git commit -m "Update lockfile" + git push + fi diff --git a/.github/workflows/external-integration.yml b/.github/workflows/external-integration.yml index b5d273fd655..415dba49a60 100644 --- a/.github/workflows/external-integration.yml +++ b/.github/workflows/external-integration.yml @@ -33,7 +33,7 @@ jobs: steps: - name: Setup Node.js - uses: actions/setup-node@v6 + uses: actions/setup-node@v7 with: node-version: lts/* diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 9d70044bebb..33cf79b52b1 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -24,7 +24,7 @@ jobs: with: fetch-depth: 0 ## Needed for Changesets to find `main` branch - - uses: actions/setup-dotnet@v5 + - uses: actions/setup-dotnet@v6 name: Setup .NET with: # Automatically read .NET SDK version from global.json to stay in sync @@ -33,12 +33,18 @@ jobs: - uses: ./.github/actions/setup - name: Install dependencies - run: npx tsx eng/tsp-core/tpm/cli.ts install --since origin/main + run: node eng/tsp-core/tpm/cli.ts install --since origin/main - name: Build - run: npx tsx eng/tsp-core/tpm/cli.ts build --since origin/main + run: node eng/tsp-core/tpm/cli.ts build --since origin/main - name: Bump version to prerelease targets run: pnpm chronus version --prerelease "{nextVersion}-pr.${{ github.event.pull_request.number }}.${{ github.run_number }}" - - run: pnpm tsx eng/tsp-core/pkg-pr-new.ts + # `chronus version --prerelease` rewrites package.json specifiers (e.g. workspace:^ -> + # a concrete prerelease range) without updating the lockfile. pnpm 11's verifyDepsBeforeRun + # check then fails the next `pnpm` invocation with ERR_PNPM_OUTDATED_LOCKFILE. Disable it + # for the remainder of the job since the mismatch is expected here. + - run: pnpm config set verifyDepsBeforeRun false --location project + + - run: node eng/tsp-core/pkg-pr-new.ts diff --git a/.github/workflows/python-integration.yml b/.github/workflows/python-integration.yml index 34390a3abc7..a5b548fc142 100644 --- a/.github/workflows/python-integration.yml +++ b/.github/workflows/python-integration.yml @@ -67,12 +67,15 @@ jobs: - name: Build run: pnpm turbo run --filter "@azure-tools/typespec-python..." build - - name: Use pinned http-specs versions - run: | - rm -rf core/packages/http-specs/dist - cp -r core/packages/http-client-python/node_modules/@typespec/http-specs/dist core/packages/http-specs/dist - rm -rf packages/azure-http-specs/dist - cp -r core/packages/http-client-python/node_modules/@azure-tools/azure-http-specs/dist packages/azure-http-specs/dist + - name: Build http-specs and azure-http-specs from source + # Build the mock servers from the checked-out typespec-azure (+ PR core) + # source, so the mock stays in lockstep with the client that is + # regenerated from the same source below. Previously these build outputs + # were overwritten with the versions resolved via http-client-python's + # package.json pin, which caused client/mock spec skew whenever + # typespec-azure main advanced a spec beyond the pinned bundle and failed + # otherwise-green PRs. See microsoft/typespec#11348. + run: pnpm turbo run build --filter "@typespec/http-specs..." --filter "@azure-tools/azure-http-specs..." - name: Prepare Python environment run: pnpm run prepare diff --git a/.gitignore b/.gitignore index fb099c3ec88..692c2245fd6 100644 --- a/.gitignore +++ b/.gitignore @@ -211,6 +211,13 @@ vite.config.ts.timestamp-* packages/*/etc/ **/docs/**/js-api/ +# Generated linter rule and diagnostic reference pages (produced by `tspd doc` / +# regen-docs from each rule/diagnostic's `docs` field). Regenerated during the +# website build (build:web), so they are not tracked. The source docs live in +# packages/*/src/rules/*.md and packages/*/src/diagnostics/*.md. +website/src/content/docs/docs/**/rules/ +website/src/content/docs/docs/**/reference/diagnostics/ + # VS Code test web temp files .vscode-test-web/ @@ -243,3 +250,6 @@ packages/http-client-python/tests/.wheels/ # Turborepo .turbo + +# agents +.claude/settings.local.json diff --git a/.npmrc b/.npmrc index 6faa8adb1a7..e0f904d9771 100644 --- a/.npmrc +++ b/.npmrc @@ -1,4 +1,3 @@ -auto-install-peers=true -package-manager-strict=false manage-package-manager-versions=true engine-strict=true +update-notifier=false diff --git a/.vscode/launch.json b/.vscode/launch.json index 49952259cee..d3c4b7e94e9 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -122,6 +122,9 @@ "request": "launch", "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/typespec-vscode"], "outFiles": ["${workspaceFolder}/packages/typespec-vscode/dist/**/*.cjs"], + // Closing the Extension Development Host window ends this session without a manual stop, + // which compound `stopAll` does not cover, so cascade the termination explicitly. + "cascadeTerminateToConfigurations": ["Attach to Language Server"], "env": { // Log elapsed time for each call to server. //"TYPESPEC_SERVER_LOG_TIMING": "true", @@ -187,6 +190,9 @@ { "name": "VS Code Extension", "configurations": ["VS Code Extension (Client)", "Attach to Language Server"], + // Stopping either the extension host or the language server session terminates both, + // instead of leaving an orphan session behind in the Call Stack view. + "stopAll": true, "presentation": { "order": 1 } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 8fac5c73094..b5aaa63ea6b 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -37,7 +37,7 @@ "label": "watch-tmlanguage", "type": "process", "command": "node", - "args": ["${workspaceFolder}/packages/compiler/scripts/watch-tmlanguage.js"], + "args": ["${workspaceFolder}/packages/compiler/scripts/watch-tmlanguage.ts"], "problemMatcher": { "base": "$msCompile", "background": { @@ -63,7 +63,7 @@ "label": "watch-spec", "type": "process", "command": "node", - "args": ["${workspaceFolder}/packages/spec/scripts/watch-spec.js"], + "args": ["${workspaceFolder}/packages/spec/scripts/watch-spec.ts"], "problemMatcher": { "base": "$msCompile", "background": { diff --git a/AGENTS.md b/AGENTS.md index 83280ab7036..4be3eef925f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,4 +10,5 @@ Your training data may be outdated — these docs match your installed version. - [@alloy-js/core](./packages/http-server-csharp/node_modules/@alloy-js/core/docs/index.md) - [@alloy-js/cli](./packages/http-server-csharp/node_modules/@alloy-js/cli/docs/index.md) — Alloy cli for building alloy components + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3e55323483..908808ed0a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,13 +4,37 @@ This section goes over the setup of the repo for development. ## Repo setup -- Install [Node.js](https://nodejs.org/) 24 LTS -- Install [pnpm](https://pnpm.io/) +You need [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/). Pick +whichever of the following options you prefer to install them. + +### Option 1: Use mise (recommended) + +[mise](https://mise.jdx.dev/getting-started.html) installs the repository's +development tools consistently across platforms. Install mise and +[activate it for your shell](https://mise.jdx.dev/getting-started.html#activate-mise), +then, from the repository root, run: + +```bash +mise install +``` + +This installs the exact tool versions recorded in `mise.toml` and `mise.lock` +(Node.js and pnpm). + +### Option 2: Install the tools yourself + +If you prefer to manage tools yourself (or use another version manager), just +install [Node.js](https://nodejs.org/). We support all active +[Node.js LTS](https://nodejs.org/en/about/previous-releases) versions, so any of +them works. pnpm self-manages its version from the `packageManager` field in +`package.json`, so you only need to install pnpm itself: ```bash npm install -g pnpm ``` +### Install and build + - Install dependencies ```bash @@ -24,12 +48,14 @@ pnpm install-conflict # This will reset the lockfile to the upstream version and pnpm build ``` -- (Optional) Install [Playwright](https://playwright.dev/) browsers for UI testing +- (Optional) Install [Playwright](https://playwright.dev/) browsers for UI testing and server-side Mermaid diagram rendering in the website ```bash -npx playwright install +npx playwright install --with-deps chromium ``` +> **Note:** Without Playwright, `pnpm build` still succeeds. Mermaid diagrams in the website will fall back to client-side rendering instead of being pre-rendered as SVGs. + - Start the build in watch mode to automatically rebuild on save ```bash diff --git a/cspell.yaml b/cspell.yaml index 4efb8e61b94..af8ebc2a006 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -61,6 +61,8 @@ words: - debugpy - Declipse - dedented + - dedup + - dedupe - Dedupes - deps - deser @@ -155,6 +157,7 @@ words: - MACVMIMAGEM - marshal - mday + - Menlo - methodsubscriptionid - mgmt - mgmtplane @@ -200,6 +203,7 @@ words: - onigasm - onwarn - openapi + - opfields - oxlint - openapiv - Packument @@ -218,6 +222,7 @@ words: - ptvsd - pwsh - pycache + - pydantic - pyexpat - pygen - pygments @@ -225,6 +230,7 @@ words: - pylint - pylintrc - pyodide + - pypi - pyproject - pyright - pyrightconfig @@ -235,6 +241,7 @@ words: - reactivex - recase - recorda + - redef - regen - rehype - reinjected @@ -323,6 +330,7 @@ words: - Vsts - vswhere - wday + - WCAG - weidxu - westus - WHATWG @@ -366,6 +374,7 @@ ignorePaths: - "**/*.plist" - .git/** - .gitignore + - .claude/** - .vscode/** - .editorconfig - .github/CODEOWNERS diff --git a/docker/Dockerfile b/docker/Dockerfile index 37071f7b30b..205d1408e68 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -12,8 +12,16 @@ COPY . /app # && tdnf clean all WORKDIR /app -RUN npm install -g pnpm -RUN pnpm install --filter "@typespec/compiler..." + +# Install exact version of pnpm to avoid problems with private registries +RUN --mount=type=secret,id=npmrc \ + NPM_CONFIG_USERCONFIG=/run/secrets/npmrc \ + npm install -g $(node -p "require('./package.json').packageManager") + +RUN --mount=type=secret,id=npmrc \ + NPM_CONFIG_USERCONFIG=/run/secrets/npmrc \ + pnpm install --filter "@typespec/compiler..." + RUN pnpm --filter "@typespec/compiler..." run build WORKDIR /app/packages/compiler @@ -26,6 +34,8 @@ FROM mcr.microsoft.com/azurelinux/base/nodejs:24 COPY --from=builder /app/packages/compiler/*.tgz /tmp/compiler.tgz -RUN npm install -g /tmp/compiler.tgz && rm /tmp/compiler.tgz +RUN --mount=type=secret,id=npmrc \ + NPM_CONFIG_USERCONFIG=/run/secrets/npmrc \ + npm install --verbose -g /tmp/compiler.tgz && rm /tmp/compiler.tgz ENTRYPOINT ["tsp"] diff --git a/e2e/e2e-tests.js b/e2e/e2e-tests.ts similarity index 98% rename from e2e/e2e-tests.js rename to e2e/e2e-tests.ts index 299000dfa22..59d0b47b39f 100644 --- a/e2e/e2e-tests.js +++ b/e2e/e2e-tests.ts @@ -3,7 +3,7 @@ import { existsSync, readdirSync, rmSync, writeFileSync } from "fs"; import { readdir } from "fs/promises"; import { join } from "path"; -import { repoRoot } from "../eng/common/scripts/helpers.js"; +import { repoRoot } from "../eng/common/scripts/helpers.ts"; import { runOrExit } from "../packages/internal-build-utils/dist/src/index.js"; const e2eTestDir = join(repoRoot, "e2e"); diff --git a/e2e/package.json b/e2e/package.json index 6ba7bda879d..fd3161f300d 100644 --- a/e2e/package.json +++ b/e2e/package.json @@ -4,6 +4,6 @@ "version": "0.0.1", "private": true, "scripts": { - "test:e2e": "node ./e2e-tests.js" + "test:e2e": "node ./e2e-tests.ts" } } diff --git a/eng/common/config/area.ts b/eng/common/config/area.ts index d66a60b59de..1b17c4f3c3f 100644 --- a/eng/common/config/area.ts +++ b/eng/common/config/area.ts @@ -1,4 +1,4 @@ -import type { AreaLabels } from "./labels.js"; +import type { AreaLabels } from "./labels.ts"; /** * Set the paths that each area applies to. @@ -34,6 +34,18 @@ export const AreaPaths: Record = { spector: ["packages/spector/", "packages/http-specs"], }; +/** + * External area owners: teams/users outside the org that should be notified on PRs + * touching their area. GitHub does not allow non-collaborators in CODEOWNERS, nor can + * they be added as formal reviewers, so they are @-mentioned in a comment instead. + * + * Keyed by the same area names as {@link AreaPaths}; the paths are reused from there. + */ +export const ExternalOwners: Partial> = { + // cspell:ignore swatkatz fionabronwen + "emitter:graphql": ["fionabronwen", "swatkatz", "steverice"], +}; + /** * Path that should trigger every CI build. */ diff --git a/eng/common/config/labels.ts b/eng/common/config/labels.ts index 286c297f5f5..8935f48cdb8 100644 --- a/eng/common/config/labels.ts +++ b/eng/common/config/labels.ts @@ -1,7 +1,7 @@ // cspell:ignore bfff -import { defineConfig, defineLabels } from "../scripts/labels/config.js"; -import { repo } from "../scripts/utils/common.js"; -import { AreaPaths } from "./area.js"; +import { defineConfig, defineLabels } from "../scripts/labels/config.ts"; +import { repo } from "../scripts/utils/common.ts"; +import { AreaPaths, ExternalOwners } from "./area.ts"; /** * Labels that are used to categorize issue for which area they belong to. @@ -230,4 +230,5 @@ export default defineConfig({ }, }, areaPaths: AreaPaths, + externalOwners: ExternalOwners, }); diff --git a/eng/common/pipelines/ci.yml b/eng/common/pipelines/ci.yml index 3c9f2a85a77..64f7ea29b64 100644 --- a/eng/common/pipelines/ci.yml +++ b/eng/common/pipelines/ci.yml @@ -37,10 +37,10 @@ extends: - script: pnpm install displayName: Install JavaScript Dependencies - - script: node $(Build.SourcesDirectory)/eng/common/scripts/resolve-target-branch.js + - script: node $(Build.SourcesDirectory)/eng/common/scripts/resolve-target-branch.ts displayName: Resolve target branch - - script: pnpm tsx ./eng/common/scripts/dispatch-area-triggers.ts --target-branch $(TARGET_BRANCH) + - script: node ./eng/common/scripts/dispatch-area-triggers.ts --target-branch $(TARGET_BRANCH) displayName: "Analyze PR changes" name: InitStep diff --git a/eng/common/pipelines/templates/1es-redirect.yml b/eng/common/pipelines/templates/1es-redirect.yml index 7711cb6d7a1..00be16b2438 100644 --- a/eng/common/pipelines/templates/1es-redirect.yml +++ b/eng/common/pipelines/templates/1es-redirect.yml @@ -27,6 +27,7 @@ extends: parameters: settings: skipBuildTagsForGitHubPullRequests: true + networkIsolationPolicy: Permissive, CFSClean sdl: codeql: compiled: diff --git a/eng/common/pipelines/templates/steps/maven-authenticate.yml b/eng/common/pipelines/templates/steps/maven-authenticate.yml new file mode 100644 index 00000000000..1b84e984add --- /dev/null +++ b/eng/common/pipelines/templates/steps/maven-authenticate.yml @@ -0,0 +1,17 @@ +parameters: + SourceDirectory: $(Build.SourcesDirectory) + +steps: + # Copy mirror settings to default Maven location so all requests go through CFS + - pwsh: | + $m2Dir = if ($env:USERPROFILE) { "$env:USERPROFILE\.m2" } else { "$HOME/.m2" } + New-Item -ItemType Directory -Force -Path $m2Dir | Out-Null + Copy-Item -Path "${{ parameters.SourceDirectory }}/eng/settings.xml" -Destination "$m2Dir/settings.xml" + displayName: "Setup Maven mirror settings" + + # Authenticate with Azure Artifacts feeds + # MavenAuthenticate adds entries to ~/.m2/settings.xml matching mirror id 'azure-sdk-for-java' + - task: MavenAuthenticate@0 + displayName: "Maven Authenticate" + inputs: + artifactsFeeds: "azure-sdk-for-java" diff --git a/eng/common/pipelines/templates/steps/pypi-auth-dev-feed.yml b/eng/common/pipelines/templates/steps/pypi-auth-dev-feed.yml new file mode 100644 index 00000000000..fc2396c8448 --- /dev/null +++ b/eng/common/pipelines/templates/steps/pypi-auth-dev-feed.yml @@ -0,0 +1,49 @@ +parameters: + DevFeedName: "public/azure-sdk-for-python" + EnableTwineAuth: true + EnablePipAuth: true + EnableUvAuth: true + +steps: + - pwsh: | + # For safety default to publishing to the private feed. + # Publish to https://dev.azure.com/azure-sdk/internal/_packaging?_a=feed&feed=azure-sdk-for-python-pr + $devopsFeedName = 'internal/azure-sdk-for-python-pr' + if (-not ('$(Build.Repository.Name)').EndsWith('-pr')) { + # Publish to https://dev.azure.com/azure-sdk/public/_packaging?_a=feed&feed=azure-sdk-for-python + $devopsFeedName = '${{ parameters.DevFeedName }}' + } + echo "##vso[task.setvariable variable=DevFeedName]$devopsFeedName" + echo "Using DevopsFeed = $devopsFeedName" + displayName: Setup DevOpsFeedName + + - ${{ if eq(parameters.EnableTwineAuth, true) }}: + - task: TwineAuthenticate@0 + displayName: "Twine Authenticate to feed" + inputs: + artifactFeeds: $(DevFeedName) + + - ${{ if eq(parameters.EnablePipAuth, true) }}: + - task: PipAuthenticate@1 + displayName: "Pip Authenticate to feed" + inputs: + artifactFeeds: $(DevFeedName) + onlyAddExtraIndex: false + + - ${{ if eq(parameters.EnableUvAuth, true) }}: + - pwsh: | + if ($env:PIP_INDEX_URL) { + Write-Host "Found pip index URL: $($env:PIP_INDEX_URL)" + # UV_DEFAULT_INDEX is the canonical replacement for the deprecated UV_INDEX_URL (uv 0.4.23+). + # PIP_INDEX_URL is set by PipAuthenticate@1 and contains embedded credentials, which uv + # will use for Basic auth against the ADO feed (and its PyPI upstream) per astral-sh/uv#12651. + Write-Host "##vso[task.setvariable variable=UV_DEFAULT_INDEX]$($env:PIP_INDEX_URL)" + # Disable keyring so uv uses the URL-embedded credentials directly. + Write-Host "##vso[task.setvariable variable=UV_KEYRING_PROVIDER]disabled" + } else { + Write-Host "##[warning]PIP_INDEX_URL not set - uv will fall back to public PyPI." + } + # Force any managed Python downloads to go directly to GitHub releases + # rather than the default CDN (releases.astral.sh). + Write-Host "##vso[task.setvariable variable=UV_PYTHON_INSTALL_MIRROR]https://github.com/astral-sh/python-build-standalone/releases/download" + displayName: "Configure UV Authentication" diff --git a/eng/common/scripts/check-catalog.ts b/eng/common/scripts/check-catalog.ts index 521dc9870ae..36b9b5db2b3 100644 --- a/eng/common/scripts/check-catalog.ts +++ b/eng/common/scripts/check-catalog.ts @@ -2,7 +2,7 @@ import { execSync } from "child_process"; import { readFileSync } from "fs"; import { join, relative } from "path"; import { parse } from "yaml"; -import { repoRoot } from "./utils/common.js"; +import { repoRoot } from "./utils/common.ts"; /** * Validates that all workspace package dependencies use `catalog:` or `workspace:` protocols, diff --git a/eng/common/scripts/check-for-changed-files.js b/eng/common/scripts/check-for-changed-files.ts similarity index 83% rename from eng/common/scripts/check-for-changed-files.js rename to eng/common/scripts/check-for-changed-files.ts index db9c79760e1..d6ac8a06adb 100644 --- a/eng/common/scripts/check-for-changed-files.js +++ b/eng/common/scripts/check-for-changed-files.ts @@ -1,7 +1,6 @@ -// @ts-check -import { run } from "../../tsp-core/scripts/legacy-helpers.js"; +import { spawnSync, type SpawnSyncReturns } from "child_process"; -const proc = run("git", ["status", "--porcelain"], { +const proc: SpawnSyncReturns = spawnSync("git", ["status", "--porcelain"], { encoding: "utf-8", stdio: [null, "pipe", "pipe"], }); diff --git a/eng/common/scripts/check-lockfile.ts b/eng/common/scripts/check-lockfile.ts new file mode 100644 index 00000000000..130fc40f5c0 --- /dev/null +++ b/eng/common/scripts/check-lockfile.ts @@ -0,0 +1,41 @@ +import { readFileSync } from "fs"; +import { join } from "path"; +import { repoRoot } from "./utils/common.ts"; + +/** + * Validates that `pnpm-lock.yaml` does not contain explicit `tarball:` URLs in its + * resolution entries. Some registry proxies (e.g. packagefeedproxy.microsoft.io) inject + * load-balanced tarball URLs (ms-feed-N.pkgs.visualstudio.com) into the lockfile which are + * environment-specific and break CI. The lockfile should stay integrity-only. + */ + +const lockfilePath = join(repoRoot, "pnpm-lock.yaml"); +const content = readFileSync(lockfilePath, "utf8"); + +const offenders: string[] = []; +const lines = content.split(/\r?\n/); +for (let i = 0; i < lines.length; i++) { + if (lines[i].includes("tarball:")) { + offenders.push(` pnpm-lock.yaml:${i + 1}: ${lines[i].trim()}`); + } +} + +if (offenders.length > 0) { + console.log(`\n✘ Found ${offenders.length} tarball URL(s) in pnpm-lock.yaml:`); + const preview = offenders.slice(0, 20); + for (const o of preview) { + console.log(o); + } + if (offenders.length > preview.length) { + console.log(` ...and ${offenders.length - preview.length} more.`); + } + console.log( + "\nThe lockfile must stay integrity-only (no explicit `tarball:` URLs). These are usually" + + "\ninjected by a registry proxy and are not portable across environments. Regenerate the" + + "\nlockfile against the pinned registry, or strip the `, tarball: ...` suffix from each" + + "\n`resolution:` entry.", + ); + process.exit(1); +} + +console.log("✔ pnpm-lock.yaml is integrity-only (no tarball URLs)."); diff --git a/eng/common/scripts/dispatch-area-triggers.ts b/eng/common/scripts/dispatch-area-triggers.ts index 7968a04c4bb..0ea1f52eafb 100644 --- a/eng/common/scripts/dispatch-area-triggers.ts +++ b/eng/common/scripts/dispatch-area-triggers.ts @@ -1,8 +1,8 @@ import { parseArgs } from "util"; -import { setOutputVariable } from "./utils/ado.js"; -import { repoRoot } from "./utils/common.js"; -import { findAreasChanged } from "./utils/find-area-changed.js"; -import { listChangedFilesSince } from "./utils/git.js"; +import { setOutputVariable } from "./utils/ado.ts"; +import { repoRoot } from "./utils/common.ts"; +import { findAreasChanged } from "./utils/find-area-changed.ts"; +import { listChangedFilesSince } from "./utils/git.ts"; const args = parseArgs({ args: process.argv.slice(2), diff --git a/eng/common/scripts/helpers.js b/eng/common/scripts/helpers.js deleted file mode 100644 index aedbb5a1dac..00000000000 --- a/eng/common/scripts/helpers.js +++ /dev/null @@ -1,7 +0,0 @@ -// @ts-check -import { dirname, resolve } from "path"; -import { fileURLToPath } from "url"; - -export const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../.."); -export const prettier = resolve(repoRoot, "packages/compiler/node_modules/.bin/prettier"); -export const tsc = resolve(repoRoot, "packages/compiler/node_modules/.bin/tsc"); diff --git a/eng/common/scripts/helpers.ts b/eng/common/scripts/helpers.ts new file mode 100644 index 00000000000..d912d5cd3c0 --- /dev/null +++ b/eng/common/scripts/helpers.ts @@ -0,0 +1,4 @@ +import { dirname, resolve } from "path"; +import { fileURLToPath } from "url"; + +export const repoRoot: string = resolve(dirname(fileURLToPath(import.meta.url)), "../../.."); diff --git a/eng/common/scripts/labels/automation.ts b/eng/common/scripts/labels/automation.ts index f3b110cc2ee..97f14ac8a55 100644 --- a/eng/common/scripts/labels/automation.ts +++ b/eng/common/scripts/labels/automation.ts @@ -1,9 +1,12 @@ import { resolve } from "path"; import { stringify } from "yaml"; -import { CheckOptions, syncFile } from "../utils/common.js"; -import { expandFolder } from "../utils/find-area-changed.js"; +import type { CheckOptions } from "../utils/common.ts"; +import { removeFile, syncFile } from "../utils/common.ts"; +import { expandFolder } from "../utils/find-area-changed.ts"; +import type { PolicyServiceConfig } from "./policy.ts"; import { - PolicyServiceConfig, + addLabel, + addReply, and, eventResponderTask, hasLabel, @@ -14,8 +17,8 @@ import { not, or, payloadType, -} from "./policy.js"; -import type { RepoConfig } from "./types.js"; +} from "./policy.ts"; +import type { RepoConfig } from "./types.ts"; const policyFolder = resolve(process.cwd(), ".github", "policies"); @@ -24,15 +27,39 @@ export interface SyncLabelAutomationOptions extends CheckOptions {} export async function syncLabelAutomation(config: RepoConfig, options: SyncLabelAutomationOptions) { await syncPolicyFile(createIssueTriageConfig(config), options); await syncPolicyFile(createPrTriageConfig(config), options); + + const externalOwners = collectExternalOwners(config); + if (externalOwners.length > 0) { + await syncPolicyFile(createExternalReviewersConfig(config), options, externalOwners); + } else { + // No external owners to ping means the policy would have no tasks, so avoid + // emitting an empty generated file (and remove any stale one). + await removeFile(resolve(policyFolder, "prs.external-reviewers.generated.yml"), options); + } } -async function syncPolicyFile(policy: PolicyServiceConfig, options: CheckOptions) { +async function syncPolicyFile( + policy: PolicyServiceConfig, + options: CheckOptions, + ignoreWords: string[] = [], +) { const yaml = stringify(policy); - const content = `# This file is generated by the sync-labels script DO NOT EDIT manually\n${yaml}`; + const cspell = ignoreWords.length > 0 ? `# cspell:ignore ${ignoreWords.join(" ")}\n` : ""; + const content = `# This file is generated by the sync-labels script DO NOT EDIT manually\n${cspell}${yaml}`; const filename = resolve(policyFolder, `${policy.id}.generated.yml`); await syncFile(filename, content, options); } +function collectExternalOwners(config: RepoConfig): string[] { + const all = new Set(); + for (const owners of Object.values(config.externalOwners)) { + for (const owner of owners) { + all.add(owner); + } + } + return [...all].sort(); +} + function createIssueTriageConfig(config: RepoConfig): PolicyServiceConfig { const areaLabels = config.labels.area.labels; return { @@ -129,3 +156,40 @@ function createPrTriageConfig(config: RepoConfig): PolicyServiceConfig { }, }; } +function createExternalReviewersConfig(config: RepoConfig): PolicyServiceConfig { + const entries = Object.entries(config.externalOwners).filter(([, owners]) => owners.length > 0); + return { + id: "prs.external-reviewers", + name: "Notify external area owners on PRs", + description: + "GitHub doesn't allow CODEOWNERS entries or formal review requests for users that are not repository collaborators, but some areas are contributed by external teams. Mention those owners in a comment instead. https://github.com/orgs/community/discussions/23042", + resource: "repository", + disabled: false, + configuration: { + resourceManagementConfiguration: { + eventResponderTasks: [ + eventResponderTask({ + if: [payloadType("Pull_Request")], + then: entries.map(([area, owners]) => { + const globs = (config.areaPaths[area] ?? []).map(expandFolder); + const mentions = owners.map((owner) => `@${owner}`).join(" "); + // The area label doubles as the "already notified" guard: it is added + // below the first time the paths match so owners are pinged once and not + // on every subsequent push (the prs.triage policy also adds it, but adding + // it here guarantees the guard is set even if that policy hasn't run yet). + return { + if: [includesModifiedFiles(globs), not(hasLabel(area))], + then: [ + addReply( + `${mentions} — this PR modifies files in the \`${area}\` area, which your team owns. Please take a look. (You can't be added as a formal reviewer because you're not a repository collaborator, so this is a heads-up instead.)`, + ), + addLabel(area), + ], + }; + }), + }), + ], + }, + }, + }; +} diff --git a/eng/common/scripts/labels/config.ts b/eng/common/scripts/labels/config.ts index 7d41c45e795..e91a4143e9e 100644 --- a/eng/common/scripts/labels/config.ts +++ b/eng/common/scripts/labels/config.ts @@ -1,4 +1,4 @@ -import { RepoConfig } from "./types.js"; +import type { RepoConfig } from "./types.ts"; export function defineConfig(config: RepoConfig) { return config; diff --git a/eng/common/scripts/labels/definitions.ts b/eng/common/scripts/labels/definitions.ts index cbc1b00cfcc..cf458ff05de 100644 --- a/eng/common/scripts/labels/definitions.ts +++ b/eng/common/scripts/labels/definitions.ts @@ -6,7 +6,7 @@ import { resolve } from "path"; import pc from "picocolors"; import { format, resolveConfig } from "prettier"; import { inspect } from "util"; -import { RepoConfig } from "./types.js"; +import type { RepoConfig } from "./types.ts"; const Octokit = OctokitCore.plugin(paginateGraphQL).plugin(restEndpointMethods); type Octokit = InstanceType; diff --git a/eng/common/scripts/labels/policy.ts b/eng/common/scripts/labels/policy.ts index fb04c9b6348..af6a1248dae 100644 --- a/eng/common/scripts/labels/policy.ts +++ b/eng/common/scripts/labels/policy.ts @@ -31,7 +31,8 @@ export type IsActivitySender = { export type IsAction = { isAction: { - action: // Issues + action: + // Issues | "Opened" | "Closed" | "Reopened" @@ -166,3 +167,23 @@ export type EventResponderTask = { export function eventResponderTask(options: EventResponderTask): EventResponderTask { return options; } + +export type AddReply = { + addReply: { reply: string }; +}; + +/** + * Post a comment on the issue/PR. @-mentions in the body notify the mentioned users, + * including users that are not repository collaborators. + */ +export function addReply(reply: string): AddReply { + return { addReply: { reply } }; +} + +export type AddLabel = { + addLabel: { label: string }; +}; + +export function addLabel(label: string): AddLabel { + return { addLabel: { label } }; +} diff --git a/eng/common/scripts/labels/sync-labels.ts b/eng/common/scripts/labels/sync-labels.ts index 192e00efe27..dc2795d9d3b 100644 --- a/eng/common/scripts/labels/sync-labels.ts +++ b/eng/common/scripts/labels/sync-labels.ts @@ -1,8 +1,8 @@ import { resolve } from "path"; import { parseArgs } from "util"; -import { syncLabelAutomation } from "./automation.js"; -import { syncLabelsDefinitions } from "./definitions.js"; -import { RepoConfig } from "./types.js"; +import { syncLabelAutomation } from "./automation.ts"; +import { syncLabelsDefinitions } from "./definitions.ts"; +import type { RepoConfig } from "./types.ts"; const options = parseArgs({ args: process.argv.slice(2), diff --git a/eng/common/scripts/labels/types.ts b/eng/common/scripts/labels/types.ts index a461d553d12..4c1809f6d71 100644 --- a/eng/common/scripts/labels/types.ts +++ b/eng/common/scripts/labels/types.ts @@ -5,6 +5,7 @@ export interface RepoConfig { }; labels: LabelsConfig; areaPaths: Record; + externalOwners: Record; } export interface LabelsConfig { diff --git a/eng/common/scripts/resolve-target-branch.js b/eng/common/scripts/resolve-target-branch.ts similarity index 65% rename from eng/common/scripts/resolve-target-branch.js rename to eng/common/scripts/resolve-target-branch.ts index 271876df1d3..4e67a66f4ab 100644 --- a/eng/common/scripts/resolve-target-branch.js +++ b/eng/common/scripts/resolve-target-branch.ts @@ -1,6 +1,5 @@ -// @ts-check -const prTargetBranch = process.env["SYSTEM_PULLREQUEST_TARGETBRANCHNAME"]; -const currentBranch = process.env["BUILD_SOURCEBRANCH"]; +const prTargetBranch: string | undefined = process.env["SYSTEM_PULLREQUEST_TARGETBRANCHNAME"]; +const currentBranch: string | undefined = process.env["BUILD_SOURCEBRANCH"]; console.log("Branches:", { prTargetBranch, @@ -11,7 +10,9 @@ if (prTargetBranch !== undefined) { console.log("Target branch is", prTargetBranch); console.log(`##vso[task.setvariable variable=TARGET_BRANCH]${prTargetBranch}`); } else if (currentBranch) { - const match = currentBranch.match(/refs\/heads\/gh-readonly-queue\/(.*)\/pr-.*/); + const match: RegExpMatchArray | null = currentBranch.match( + /refs\/heads\/gh-readonly-queue\/(.*)\/pr-.*/, + ); if (match !== null) { const targetBranch = match[1]; console.log("Target branch is", targetBranch); diff --git a/eng/common/scripts/utils/common.ts b/eng/common/scripts/utils/common.ts index f8fbe47f7e4..316158959ec 100644 --- a/eng/common/scripts/utils/common.ts +++ b/eng/common/scripts/utils/common.ts @@ -1,4 +1,5 @@ -import { readFile, writeFile } from "fs/promises"; +import { existsSync } from "fs"; +import { readFile, rm, writeFile } from "fs/promises"; import { dirname, resolve } from "path"; import { fileURLToPath } from "url"; @@ -27,3 +28,14 @@ export async function syncFile(filename: string, newContent: string, options: Ch await writeFile(filename, newContent); } } + +export async function removeFile(filename: string, options: CheckOptions) { + if (!existsSync(filename)) { + console.log(`${filename} is correctly absent.`); + } else if (options.check) { + console.error(`${filename} should not exist, run pnpm sync-labels to remove it`); + process.exit(1); + } else { + await rm(filename); + } +} diff --git a/eng/common/scripts/utils/find-area-changed.test.ts b/eng/common/scripts/utils/find-area-changed.test.ts index 8cc44fc782d..58dc1356e3e 100644 --- a/eng/common/scripts/utils/find-area-changed.test.ts +++ b/eng/common/scripts/utils/find-area-changed.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { findAreasChanged } from "./find-area-changed.js"; +import { findAreasChanged } from "./find-area-changed.ts"; describe("paths that should trigger CSharp CI", () => { it.each([ diff --git a/eng/common/scripts/utils/find-area-changed.ts b/eng/common/scripts/utils/find-area-changed.ts index 30924e400a4..eb9eb3aa892 100644 --- a/eng/common/scripts/utils/find-area-changed.ts +++ b/eng/common/scripts/utils/find-area-changed.ts @@ -1,6 +1,6 @@ import micromatch from "micromatch"; import pc from "picocolors"; -import { CIRules } from "../../config/area.js"; +import { CIRules } from "../../config/area.ts"; export function findAreasChanged(files: string[]): (keyof typeof CIRules)[] { const result: (keyof typeof CIRules)[] = []; diff --git a/eng/common/scripts/utils/git.ts b/eng/common/scripts/utils/git.ts index 03ecde8c7bc..d1abca3c0b9 100644 --- a/eng/common/scripts/utils/git.ts +++ b/eng/common/scripts/utils/git.ts @@ -1,4 +1,4 @@ -import { execAsync, type ExecResult } from "./exec-async.js"; +import { execAsync, type ExecResult } from "./exec-async.ts"; export async function listChangedFilesSince( ref: string, diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md new file mode 100644 index 00000000000..0b21c083226 --- /dev/null +++ b/eng/emitter-diff/README.md @@ -0,0 +1,199 @@ +# emitter-diff + +A language-agnostic tool for **diffing the generated code produced by two versions of a +TypeSpec emitter**. + +It runs the emitter's own regenerate command against a **baseline** source tree and a **head** +source tree, then shows the diff between the two generated outputs. Use it locally during +development and in CI on PRs. + +The tool contains **zero language logic**. An emitter integrates by naming three things — its +regenerate command, the package directory to run it in, and the generated-code directory to diff — +either as flags or via a built-in `--emitter` preset. + +## How it works + +```text + baseline tree ─► run in ─► snapshot ─┐ + ├─► git diff ─► terminal / HTML + head tree ─────► run in ─► snapshot ─┘ +``` + +- A **source tree** is resolved for each side (`--baseline` / `--head`). +- The **`--command`** is run verbatim (tokenized to argv — no shell) inside + `/`. This is the emitter's _unmodified_ regenerate command; the tool does + not reach into it. +- The `/` subtree is snapshotted for each side and the + two snapshots are diffed. `--generated-code-path` accepts **multiple roots** — an emitter that + writes generated code to several directories (e.g. Go) passes a comma-separated list or repeats + the flag; each root is snapshotted under its own relative path so outputs never collide. + +Because the tool just runs a command, **any emitter with a regenerate script works** — no per-language +plugin code. + +## Usage + +```bash +# Using a built-in preset (fills in command + paths): +node eng/emitter-diff/src/cli.ts --emitter python --baseline gh: + +# Fully explicit (no preset needed): +node eng/emitter-diff/src/cli.ts \ + --command "npm run regenerate" \ + --emitter-path packages/http-client-python \ + --generated-code-path tests/generated \ + --baseline gh: + +# Multiple generated roots (e.g. Go writes several) — comma-separated (or repeat the flag): +node eng/emitter-diff/src/cli.ts \ + --command "npm run tspcompile" \ + --emitter-path packages/typespec-go \ + --generated-code-path test/http-specs,test/azure-http-specs \ + --baseline github:Azure/autorest.go@ +``` + +> This tool is a set of plain `.ts` scripts — not an installed package. It runs through `node` +> (which executes TypeScript directly on the versions this repo supports), so there is nothing to +> build. Typecheck with `npx tsc -p eng/emitter-diff`. + +> **Build your checkout first.** `--head` defaults to the current working tree, and the tool runs +> the regenerate command against it **as-is** — it never installs or builds your checkout (see +> [Command prep](#command-prep---setup)). Build the emitter for the head side before diffing; for +> **python** that's `npm run setup` in `packages/http-client-python` (builds the emitter and creates +> the venv `regenerate` requires). Only trees the tool fetches from GitHub are auto-prepared. + +### Emitter config + +| Flag | Meaning | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--emitter ` | Built-in preset that fills in the three fields below. | +| `--command ` | Regenerate command, run verbatim in `--emitter-path`. | +| `--emitter-path ` | Package dir (relative to a tree root) to run the command in. | +| `--generated-code-path ` | Generated-code dir (relative to `--emitter-path`) to diff. Accepts **multiple roots** — comma-separated (`a,b`) or by repeating the flag — for an emitter with several generated roots (e.g. Go); each is snapshotted under its own relative path. | + +A preset supplies all three; each flag still overrides the preset value. To onboard a new language, +add a row to `EMITTER_DEFAULTS` in `src/registry.ts` — or just pass the three flags directly and +skip `--emitter`. + +### Refs + +| Syntax | Meaning | +| --------------------------------- | ------------------------------------ | +| `local:/path` or `./path` | a local source folder (run in place) | +| `github:owner/repo@` | a GitHub source at a ref | +| `gh:` | this repo (origin remote) at a ref | + +`--head` defaults to the **current working tree**. `--baseline` defaults to the `upstream` remote's +repo at its default branch, falling back to `origin` (e.g. `github:microsoft/typespec@main`). + +### Command prep (`--setup`) + +The `--command` is run **as-is** — it does not install deps or build. Instead, prep is handled by +**`--setup`**, which runs **only in a tree the tool freshly fetched from GitHub** (a `gh:`/`github:` +ref). The current working tree and user-provided `local:` paths are assumed already built and are +**never touched** (so setup never mutates your checkout or a prepared CI worktree). + +- A **preset** supplies sensible setup defaults, so `--emitter python --baseline gh:main` installs + + builds the fetched baseline automatically (python: `npm install --ignore-scripts` → `npm run setup`; + typescript: `pnpm install` → `npm run build`). +- Override with one or more `--setup ` (each runs in order, in `/`), or + disable entirely with `--no-setup`. + +Each `--setup` command — like `--command` — is tokenized to argv and run **without a shell**, so +multi-step pipelines (`&&`, `|`) are not supported; pass repeated `--setup` flags instead. + +### Common options + +By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and +prints a `file://` link to it. + +- `--baseline ` / `--head `: the two source trees to compare. +- `--setup ` (repeatable) / `--no-setup`: prep commands for freshly fetched GitHub trees. +- `--work-dir `: scratch dir for snapshots (default: a fresh temp dir). +- `--sequential`: regenerate baseline then head one after another instead of in parallel. Useful on + a single machine where running both at once oversubscribes the CPU (each regenerate already fans + out across cores) or trips generator races. +- `--ci`: disable the local baseline-output cache (intended for CI). +- `--html `: write the rendered HTML report to this path. +- `--md `: write a Markdown report (collapsible per-file `diff` blocks) to this path. Handy for + a CI job summary (`$GITHUB_STEP_SUMMARY`) or a PR comment body. +- `--no-group`: render every file separately in the HTML/Markdown reports. By default, files that + share the same change — the same added/removed lines, even when the surrounding generated code + differs — are merged into a single collapsible group (with the shared diff shown once and every + once and every affected file listed), so a repeated change across many generated files is reviewed + once instead of N times. +- `--fail-on-diff`: exit non-zero when output differs (exit `2` = diff present, `1` = hard error). +- `-- `: everything after `--` is appended to `--command` verbatim on **both** sides, so the + diff stays apples-to-apples. Use it to regenerate only a subset of tests by forwarding the + regenerate script's own filter flags. + +### Regenerating a subset of tests + +The tool doesn't define its own test-filter flags — it forwards `-- ` to each emitter's +regenerate command, which owns the filtering. For the **Python** emitter (`regenerate.ts`): + +- `-n, --name `: case-insensitive substring match on package name. +- `-f, --flavor `: limit to one flavor. +- `-j, --jobs `: parallel job count. + +```sh +# Only the authentication packages, azure flavor +node ../../eng/emitter-diff/src/cli.ts --emitter python -- --name authentication --flavor azure + +# Via the package script (first `--` is npm's, second is emitter-diff's passthrough separator) +npm run diff-spector-tests -- -- --name type/array +``` + +`--name` filters the spec set already bundled in the package's `node_modules` +(`@azure-tools/azure-http-specs` + `@typespec/http-specs`); it does not point the test set at an +arbitrary folder or ref. Other emitters expose their own filter flags — pass whatever their +regenerate command accepts. + +## CI integration + +`.github/workflows/ci-emitter-diff-.yml` runs on PRs that touch the language emitter or this +tool. The **baseline** is the base-branch commit the PR is based on (the `git merge-base` with the +target branch). Because the tool runs the regenerate command as-is, the workflow **prepares both +trees** (installs deps, builds the emitter, creates any venv) before invoking the tool, then: + +- posts a **sticky PR comment** (updated in place on each push) linking the diff artifact, and +- uploads the rendered **HTML report** as an artifact. + +**Informational:** the check **always passes unless the tool hits a real tool/build error** — a +generated-output diff does not fail the PR. CI runs the tool without `--fail-on-diff`, so a diff +still exits `0`; only a non-zero exit (a build/venv/generate failure) fails the job. + +**Fork PRs are not run.** The job checks out and executes the PR's code (builds the emitter, runs +`regenerate`), so a job-level `if` guard restricts it to same-repo PRs — it skips any PR whose head +is a fork. + +## Adding a new language + +Either add a preset row to `EMITTER_DEFAULTS` (`src/registry.ts`): + +```ts +rust: { + command: "npm run tspcompile", + emitterPath: "packages/typespec-rust", + generatedCodePath: "test/generated", +}, +``` + +…or skip the preset entirely and pass `--command` / `--emitter-path` / +`--generated-code-path` directly. Either way, ensure each side's tree can actually run the +command (see **Command prep** above). The orchestrator, ref resolver, and diff engine need no +changes. + +## Notes & limitations + +- `--html` renders a self-contained, GitHub-style HTML report (inline CSS, no external requests). + `--md` renders a Markdown report (collapsible per-file `diff` blocks) suitable for a CI job + summary or PR comment. Both reports group files that share the same change into one block by + default (`--no-group` to disable), so reviewing a repeated diff is a one-time effort. The diff + itself is produced by `git diff --no-index`; the tool leans on only a couple of small repo dev + dependencies (`execa`, `picocolors`) for process spawning and terminal coloring. +- For github refs (including fork repos), the resolver uses a detached, commit-keyed cached git + worktree under the temp directory, created from an isolated cache repo (not from your active + checkout). Repeated runs on the same commit reuse it. +- Spec inputs come from each side's own dependencies (e.g. `node_modules/@typespec/http-specs`). + Spec versions rarely change, so any drift between baseline/head is treated as acceptable noise. diff --git a/eng/emitter-diff/src/baseline-cache.ts b/eng/emitter-diff/src/baseline-cache.ts new file mode 100644 index 00000000000..004a2502d0c --- /dev/null +++ b/eng/emitter-diff/src/baseline-cache.ts @@ -0,0 +1,141 @@ +import { createHash } from "node:crypto"; +import { cpSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; + +import type { Logger } from "./types.ts"; +import { ensureDir, git } from "./util.ts"; + +export interface BaselineCacheProfileInput { + emitter?: string; + baselineRef: string; + command: string; + emitterPath: string; + generatedCodePath: string | string[]; + setup: string[]; + passthrough: string[]; +} + +interface BaselineCacheIndexEntry { + baselineIdentity: string; + updatedAt: string; +} + +type BaselineCacheIndex = Record; + +export function computeBaselineProfileKey(input: BaselineCacheProfileInput): string { + return createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 16); +} + +export async function detectBaselineIdentity(dir: string): Promise { + const gitHead = await git(["rev-parse", "--verify", "HEAD"], { cwd: dir }); + const sha = gitHead.code === 0 ? gitHead.stdout.trim() : ""; + if (sha) return `git:${sha}`; + + // Non-git local dir: best-effort path identity (can't detect in-place edits). + return `path:${resolve(dir)}`; +} + +function baselineCachePaths(cacheKey: string): { dir: string; marker: string } { + const root = baselineCacheRoot(); + return { + dir: join(root, cacheKey), + marker: join(root, `${cacheKey}.done`), + }; +} + +function baselineCacheRoot(): string { + return ensureDir(join(tmpdir(), "emitter-diff-cache", "baseline-output")); +} + +function baselineCacheIndexPath(): string { + return join(baselineCacheRoot(), "index.json"); +} + +function readBaselineCacheIndex(log?: Logger): BaselineCacheIndex { + const path = baselineCacheIndexPath(); + if (!existsSync(path)) return {}; + try { + return JSON.parse(readFileSync(path, "utf8")) as BaselineCacheIndex; + } catch (err) { + log?.warn( + `Ignoring unreadable baseline cache index at ${path}; treating as empty. ${String(err)}`, + ); + return {}; + } +} + +function writeBaselineCacheIndex(index: BaselineCacheIndex): void { + const targetPath = baselineCacheIndexPath(); + const tmpPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`; + writeFileSync(tmpPath, `${JSON.stringify(index, null, 2)}\n`, "utf8"); + renameSync(tmpPath, targetPath); +} + +function persistBaselineIndex(index: BaselineCacheIndex, log: Logger): void { + try { + writeBaselineCacheIndex(index); + } catch (err) { + log.warn(`Could not persist baseline cache index (ignored). ${String(err)}`); + } +} + +/** + * Reuse a previously cached baseline output for `profileKey` into `snapshotDir`, + * but only when the cache entry's identity matches `baselineIdentity` (so a + * moved branch or edited source invalidates it). Returns whether the cached + * output was reused; a miss or any error returns false so the caller + * regenerates. + */ +export function tryReuseBaselineOutput( + profileKey: string, + baselineIdentity: string, + snapshotDir: string, + log: Logger, +): boolean { + try { + const index = readBaselineCacheIndex(log); + const entry = index[profileKey]; + if (!entry || entry.baselineIdentity !== baselineIdentity) return false; + + const cache = baselineCachePaths(profileKey); + if (existsSync(cache.marker) && existsSync(cache.dir)) { + log.step("Baseline output regeneration (reusing cached output)"); + rmSync(snapshotDir, { recursive: true, force: true }); + cpSync(cache.dir, snapshotDir, { recursive: true, force: true }); + return true; + } + // Index entry without materialized output: drop the stale entry. + delete index[profileKey]; + persistBaselineIndex(index, log); + return false; + } catch (err) { + log.warn(`Could not read baseline cache index; regenerating baseline. ${String(err)}`); + return false; + } +} + +/** + * Persist the freshly regenerated baseline output at `snapshotDir` under + * `profileKey`, tagged with `baselineIdentity`. Best effort: a cache-write + * failure is logged and swallowed so it never fails an otherwise-good diff. + */ +export function saveBaselineOutput( + profileKey: string, + baselineIdentity: string, + snapshotDir: string, + log: Logger, +): void { + try { + const cache = baselineCachePaths(profileKey); + rmSync(cache.dir, { recursive: true, force: true }); + cpSync(snapshotDir, cache.dir, { recursive: true, force: true }); + writeFileSync(cache.marker, `${new Date().toISOString()} ${baselineIdentity}\n`, "utf8"); + + const index = readBaselineCacheIndex(log); + index[profileKey] = { baselineIdentity, updatedAt: new Date().toISOString() }; + writeBaselineCacheIndex(index); + } catch (err) { + log.warn(`Could not update baseline cache. ${String(err)}`); + } +} diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts new file mode 100644 index 00000000000..a4d4f104b2f --- /dev/null +++ b/eng/emitter-diff/src/cli.ts @@ -0,0 +1,495 @@ +#!/usr/bin/env -S node +/** + * emitter-diff — language-agnostic generated-code diff runner. + * + * It resolves a baseline and a head source tree, runs the emitter's own + * regenerate command verbatim inside `/` for each side, then + * diffs `/` between the two. The tool + * contains zero language logic: an emitter integrates by naming its regenerate + * command and two paths (directly, or via a built-in `--emitter` preset). + */ +import { createHash } from "node:crypto"; +import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { parseArgs } from "node:util"; + +import { + computeBaselineProfileKey, + detectBaselineIdentity, + saveBaselineOutput, + tryReuseBaselineOutput, +} from "./baseline-cache.ts"; +import { diffDirs, printSummary, writeHtml, writeMarkdown } from "./diff.ts"; +import { getEmitterDefaults, listEmitters } from "./registry.ts"; +import { + classifyRef, + defaultWorkDir, + describeRef, + getRemoteRepo, + materializeTree, + resolveGithubIdentity, +} from "./resolver.ts"; +import type { ClassifiedRef, EmitterConfig, Logger } from "./types.ts"; +import { color, createLogger, ensureDir, git, gitChecked, runChecked } from "./util.ts"; + +function shouldUseBaselineCache(ciMode: boolean): { enabled: boolean; reason?: string } { + if (ciMode) { + return { enabled: false, reason: "--ci" }; + } + // Restrict caching to clearly local, interactive usage by default. + if (!process.stdout.isTTY || !process.stderr.isTTY) { + return { enabled: false, reason: "non-interactive terminal" }; + } + return { enabled: true }; +} + +const HELP = `${color.bold("emitter-diff")} — diff generated code across emitter versions + +${color.bold("Usage:")} + emitter-diff [--emitter ] --command --emitter-path \\ + --generated-code-path [options] + +${color.bold("What it does:")} + Runs verbatim inside / for a baseline tree and a + head tree, then diffs / between them. + A tree the tool fetches fresh from GitHub is first prepared with --setup (a + preset supplies install+build defaults); the current working tree and local: + paths are assumed already built and are never touched. + +${color.bold("Emitter config")} (a preset fills these; each is overridable): + --emitter Built-in preset. Available: ${listEmitters().join(", ") || "(none)"} + --command Regenerate command, e.g. "npm run regenerate". + --emitter-path Package dir (rel to tree root) to run the command in. + --generated-code-path + Generated-code dir (rel to --emitter-path) to diff. + For an emitter that writes to several roots (e.g. Go), + pass a comma-separated list or repeat the flag; each + root is snapshotted under its own relative path. + --setup Prep command run in a freshly fetched GitHub tree before + (repeatable, runs in order; a preset supplies + defaults like install+build). Overrides preset defaults. + --no-setup Skip setup even when a preset defines it. + +${color.bold("Refs")} (for --baseline / --head): + local:/path | ./path a local source folder + github:owner/repo@ a GitHub source at a ref + gh: this repo (origin remote) at a ref + +${color.bold("Options:")} + --baseline Old source tree. Default: gh:upstream/main if present, + otherwise gh:origin/main. + --head New source tree. Default: the current working tree. + --work-dir Scratch dir for snapshots. Default: a fresh temp dir. + --sequential Regenerate baseline then head one after another instead + of in parallel (avoids CPU oversubscription / races). + --ci CI mode: disable local baseline cache. + --html Write the rendered HTML diff (default: /emitter-diff.html). + --md Write a Markdown diff summary (for $GITHUB_STEP_SUMMARY). + --no-group Render every file separately in the HTML/Markdown + reports. By default, files that share the same change + (same +/- lines) are merged into one group to cut + review effort. + --fail-on-diff Exit non-zero when output differs (2 = diff, 1 = error). + -- Everything after -- is appended to verbatim + on both sides (e.g. a regenerate --name/--filter flag to + diff only a subset of tests). + -h, --help Show this help. +`; + +async function resolveDefaultBaselineRef(repoRoot: string): Promise { + const originHead = await git(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], { + cwd: repoRoot, + }); + const branch = + (originHead.code === 0 && originHead.stdout.trim().replace(/^refs\/remotes\/origin\//, "")) || + "main"; + + // Target the `upstream` remote (fork workflow), then `origin`. + // A bare `gh:` ref would always resolve against + // origin, so `gh:upstream/main` on a fork would wrongly fetch branch + // "upstream/main" from origin. + for (const remote of ["upstream", "origin"]) { + const repo = await getRemoteRepo(repoRoot, remote); + if (repo) return `github:${repo}@${branch}`; + } + + return `gh:${branch}`; +} + +/** + * Split a command string into argv, honoring single/double quotes but WITHOUT + * invoking a shell + */ +function tokenizeCommand(command: string): string[] { + const tokens: string[] = []; + const re = /"([^"]*)"|'([^']*)'|(\S+)/g; + let m: RegExpExecArray | null; + while ((m = re.exec(command)) !== null) { + tokens.push(m[1] ?? m[2] ?? m[3]); + } + return tokens; +} + +/** + * Build the full argv (command args + passthrough) for a regenerate command. + * + * `npm`/`pnpm run + diff --git a/website/src/components/starlight-overrides/Sidebar.astro b/website/src/components/starlight-overrides/Sidebar.astro index 4601c965b92..32d6101709d 100644 --- a/website/src/components/starlight-overrides/Sidebar.astro +++ b/website/src/components/starlight-overrides/Sidebar.astro @@ -2,7 +2,22 @@ import MobileMenuFooter from "@astrojs/starlight/components/MobileMenuFooter.astro"; import SidebarPersister from "@astrojs/starlight/components/SidebarPersister.astro"; import SidebarSublist from "@astrojs/starlight/components/SidebarSublist.astro"; -import { getCollection } from "astro:content"; +import Link from "@typespec/astro-utils/components/link.astro"; + +// Primary site navigation. On documentation pages the site header's own menu +// button is hidden so it doesn't overlap Starlight's sidebar menu button +// (#10795 / #10796). Surface those links here (mobile menu only) so they stay +// reachable from the single remaining menu button. +const primaryNav = [ + { label: "OpenAPI", href: "/openapi" }, + { label: "Data Validation", href: "/data-validation" }, + { label: "Tooling support", href: "/tooling" }, + { label: "Docs", href: "/docs" }, + { label: "Videos", href: "/videos" }, + { label: "Playground", href: "/playground" }, + { label: "Blog", href: "/blog" }, + { label: "Community", href: "/community" }, +]; const { sidebar } = Astro.locals.starlightRoute; const pathname = Astro.url.pathname; @@ -18,29 +33,24 @@ function isReleaseNotesGroup(entry: SidebarEntry): boolean { return entry.entries.some((e) => e.type === "link" && e.href.startsWith(base + "release-notes/")); } +// Release notes are sorted newest-first (and their pagination fixed) by the Starlight route +// middleware in src/starlight-route-data.ts. const filtered = sidebar.filter((entry) => isReleaseNotes ? isReleaseNotesGroup(entry) : !isReleaseNotesGroup(entry), ); +--- -// Sort release notes entries by releaseDate so newest appear first. -if (isReleaseNotes) { - const releaseNotes = await getCollection("docs", (x) => x.id.startsWith("release-notes/")); - const dateByHref = new Map(); - for (const note of releaseNotes) { - const href = base + note.id + "/"; - dateByHref.set(href, note.data.releaseDate?.getTime() ?? 0); - } - for (const entry of filtered) { - if (entry.type === "group" && isReleaseNotesGroup(entry)) { - entry.entries.sort((a, b) => { - const dateA = a.type === "link" ? (dateByHref.get(a.href) ?? 0) : 0; - const dateB = b.type === "link" ? (dateByHref.get(b.href) ?? 0) : 0; - return dateB - dateA; - }); + @@ -49,3 +59,29 @@ if (isReleaseNotes) {
+ + diff --git a/website/src/components/window-carousel.astro b/website/src/components/window-carousel.astro index 32c9606cf14..5a4ce0a5f4b 100644 --- a/website/src/components/window-carousel.astro +++ b/website/src/components/window-carousel.astro @@ -1,6 +1,11 @@ --- import Window from "./window.astro"; const tabs = Object.keys(Astro.slots); +const slug = (name: string) => + name + .toLowerCase() + .replace(/[^a-z0-9]+/g, "-") + .replace(/^-+|-+$/g, ""); --- @@ -73,25 +88,33 @@ const tabs = Object.keys(Astro.slots); tabs.map(async (name, i) => { const render = await Astro.slots.render(name); return ( - + ); }) } -
    +
      { tabs.map((name, i) => ( )) } @@ -100,15 +123,14 @@ const tabs = Object.keys(Astro.slots); +
      -
      +
      {footer &&