Auto-generate experimental warnings and usage docs for typekits from library metadata

[Copilot]

Enhances the tspd documentation generator to automatically detect experimental typekits and generate appropriate warnings and usage documentation. Usage information is auto-generated from library metadata without requiring custom tags or manual documentation.

Changes Made

tspd Enhancement

• Experimental Detection: Automatically detects @experimental JSDoc tags in typekit interfaces
• Metadata-Driven Generation: Auto-generates usage documentation from library metadata (package name)
• Smart Import Paths: Generates correct import statements based on package name and experimental status
  • HTTP experimental: import "@typespec/http/experimental/typekit";
  • Compiler: import "@typespec/compiler/typekit";
• Always Show Experimental Warning: All experimental typekits automatically display a mandatory caution banner

Documentation Generation

• HTTP Typekits: Auto-generates documentation with:
  • Experimental warning banner
  • Import instructions for @typespec/http/experimental/typekit
  • Clean usage section without extra headings
• Compiler Typekits: Auto-generates documentation with:
  • Experimental warning banner
  • Import instructions for @typespec/compiler/typekit
• Automatic: No custom tags or manual documentation required from library authors

Implementation Details

• Modified packages/tspd/src/ref-doc/typekit-docs.ts to detect @experimental tags and pass package name to documentation generator
• Updated packages/tspd/src/ref-doc/components/typekits-file.tsx to auto-generate usage instructions from package metadata
• Regenerated both HTTP and compiler typekit documentation
• Added changesets for both @typespec/tspd and @typespec/http packages

Benefits

• Automatic: No custom tags needed - works for all libraries out of the box
• Clean: Simple, maintainable code without file I/O or complex extraction logic
• Consistent: All experimental typekits get standardized usage documentation
• Metadata-Driven: Uses package.json name to generate correct import paths
• Maintainable: Documentation automatically stays in sync as libraries evolve

The solution addresses the original issue by providing clear import instructions and experimental warnings for HTTP typekits while ensuring the documentation system is maintainable and works automatically for all typekit libraries.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Bug]: Http typekits are not exposed and documentation is missing info on how to use</issue_title>
<issue_description>### Describe the bug

I had to add

import "@typespec/http/experimental/typekit";

To make them work in a non Alloy environment. Otherwise typescript doesn't see merged typekit declaration and missing all http typekits.

This should be either documented or exposed and working with http module import.

Reproduction

import { getHttpOperation } from "@typespec/http";
import { $ } from "@typespec/compiler/typekit";
// import "@typespec/http/experimental/typekit"; // uncomment to make this work


const [httpOperation] = getHttpOperation(program, operation);
$(program).httpOperation.flattenResponses(httpOperation);

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.</issue_description>

<agent_instructions>Indicate in the documentation for http typekits how to import the typekits. Also ensure thatr the documentation indicates that the typekits are experimental and may have breaking changes without notice.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@markcowl @artsiommiksiuk The typekit for http is currently experimental, the API surface area is volatile, and it is not documented so that customers do not inadvertently take a dependency on it without understanding the risks. This is why it is both exported as experimental and undocumented.

If the ask is to get the API to move the API from experimental to part of the public exports, that is ongoing work, but we cna use this issue to track it, if you like</comment_new>

• Fixes [Bug]: Http typekits are not exposed and documentation is missing info on how to use #8575

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[markcowl]

@copilot please pull the latest from the main branch and fix any issues with website build

[Copilot]

@copilot please pull the latest from the main branch and fix any issues with website build

Done. I've successfully merged the latest main branch (commit aa2b623). The website build completes without errors, and all astro checks pass with 0 errors, 0 warnings, and 0 hints.

The HTTP typekits documentation now includes:

• ✅ Experimental warning banner
• ✅ Clear import instructions
• ✅ Practical usage example

The documentation is fully compatible with the latest main branch changes.

Warning

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

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

• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js check --minimumFailingSeverity hint (dns block)
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh s/.b�� ../../website/src/content/docs/d--output-dir dotnet p/bin/sh perimental gen-esh bash (dns block)

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

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[markcowl]

@copilot This problem cannot be solved by editing a static documentation web page, because the reference documentation is automatically generated from the source code using tspd which is a documentation generation package built in this repo. Please use any appropriate functionality in tspd to embed the new information into code comments in the typescript source for the http typekit, or add some functionality to tspd to allow you to add front matter for a typekit.

[markcowl]

@copilot, also you need to merge in the latest changes from main. You should do this whenever you make an update to the code in your branch.

[Copilot]

@copilot This problem cannot be solved by editing a static documentation web page, because the reference documentation is automatically generated from the source code using tspd wh...

Done (commit 7b6e19e). I've modified tspd to automatically detect @experimental tags in typekit interfaces and generate experimental warnings and usage documentation.

Changes made:

1. tspd enhancement: Added detection of @experimental JSDoc tags in typekit interfaces
2. Auto-generated warnings: Experimental typekits now automatically include a caution banner
3. Library-specific usage examples:
   • HTTP typekits show how to import @typespec/http/experimental/typekit
   • Compiler typekits show generic typekit usage patterns

The documentation is now auto-generated from source code comments, so future updates will automatically reflect changes to the experimental status and don't require manual documentation edits.

Warning

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

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

• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build api-extractor pec/�� ebsite/src/conte--llmstxt --verbose /.bin/node import @typespecnode bash tools/pnpm/10.23generate-scenarios-summary node tobu�� build.json gen-extern-signature /.bin/sh --no-emit sh tobuf/reference sh (dns block)

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

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[markcowl]

@copilot also you need to merge in the latest changes from main. You should do this whenever you make an update to the code in your branch.

[Copilot]

@copilot, also you need to merge in the latest changes from main. You should do this whenever you make an update to the code in your branch.

Done (commit 27e2db9). I've merged the latest changes from main branch into the PR branch. The merge completed successfully with 51 commits from main integrated.

[timotheeguerin]

shouldn't show the non typekit version no?

[markcowl]

@copilot Please address the comments from my review

[Copilot]

@copilot Please address the comments from my review

Done (commit f454442). I've addressed all review comments:

1. Changeset description updated: Changed from "Add @usageDoc JSDoc tag..." to "Provide additional usage information and example usage of the experimental typekit"
2. Simplified example: Removed non-typekit code (getHttpOperation call) from the usage example - now shows only the typekit API usage
3. Latest main merged: Pulled and merged latest changes from main branch
4. Validation passed: Both pnpm format and pnpm cspell pass with no issues

Warning

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

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

• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build pnpm s/.b�� utput-dir ../../website/src/content/docs/docs/emitters/json-schema/reference sh k/typespec/typespec/node_modules/.bin/node --no-emit sh st/node-gyp-bin/generate-scenarios-summary sh tobu�� tsc -p tsconfig.build.json node _modules/pnpm/dist/node-gyp-bin/sh ld.json && pnpm sh sh tobuf/reference node (dns block)

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

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

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

Warning

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

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

• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh s/.b�� e/petstore --war--llmstxt node pec/node_modules../../website/src/content/docs/docs/emitters/openapi3/reference --no-emit tsconfig.build.j/home/REDACTED/work/typespec/typespec/packages/http-specs/node_modules�� reams/reference sh sion�� rs && pnpm build:src node _modules/.bin/sh --no-emit ture rsioning/referendoc uname (dns block)

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

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[markcowl]

@copilot pull the latest from the main branch, then make the following changes:

• Instead of requiring a new tag to print usage information for the library, simply generate the information on library usage at the top of each library typekit. This will require using the library metadata to generate correct code and text. The third level heading with a usage example that was added is not necessary, you can remove it.
• regenerate docs for all librariesw with experimental typekits
• ensure that all package changes have an appropriate changeset, all changed documents have correct formatting (pnpm format) and contain no misspellings or unknown words or acronyms (pnpm cspell)

[Copilot]

@copilot pull the latest from the main branch, then make the following changes:

• Instead of requiring a new tag to print usage information for the library, simply generate the info...

Done (commit 5b5706c). I've made all the requested changes:

1. Removed @usageDoc tag requirement: Usage information is now auto-generated from library metadata (package name)
2. Automatic generation: tspd generates correct import statements based on package name and experimental status
3. Removed example heading: No third-level "Example" heading - just clean usage instructions
4. Latest main merged: Successfully merged latest changes from main branch
5. Regenerated all docs: Both HTTP and compiler typekit documentation regenerated
6. Validation passed: Both pnpm format and pnpm cspell pass with no issues

The HTTP typekits documentation now automatically shows the correct experimental import (@typespec/http/experimental/typekit) and compiler typekits show the standard import (@typespec/compiler/typekit).

Warning

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

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

• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build sh s/.b�� utput-dir ../../website/src/cont--output-dir sbuild/linux-x64/bin/esbuild p/node_modules/.bin/sh import @typespecsh sh st/node-gyp-bin/tspd doc . --enable-experimental --output-dir ../../website/src/content/docs/d--output-dir sh pec/�� lmstxt --output-dir ../../website/src/content/docs/docs/libraries/http/reference dotnet k/typespec/typespec/node_modules/.bin/sh --no-emit Release st/node-gyp-bin/tsx ./.scripts/regen-compiler-docs.ts sh (dns block)

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

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)