TypeSpec tspd 变更日志精读gen-extern-signature 与 doc 命令的能力演进【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespectypespec/tspd是 TypeSpec 生态中面向库和 Emitter 开发者的实验性 CLI 工具负责两件事为 TypeSpec 装饰器/函数生成带类型签名的外部声明文件以及为库生成参考文档。本文以 tspd 的 CHANGELOG 为主线逐版本拆解gen-extern-signature与doc两大命令的功能演进0.69.0 → 0.77.1并结合仓库内实际源码CLI 入口、签名生成器、文档生成管线验证每条变更记录的落地实现帮助你在编写 TypeSpec 库时正确使用这两条命令并理解其边界。tspd 在 TypeSpec 生态中的定位tspd 的 README 对工具的定位非常明确这是实验性工具This library is experimental and will most likely significantly change in future versions版本之间可能发生破坏性变更核心能力有二Generate decorator signatures and type checks生成装饰器签名与类型检查和Generate documentation for library types and emitter options为库类型与 emitter 选项生成文档。package.json 中当前版本为0.77.1与 CHANGELOG 最新条目一致并给出两个关键约束bin字段暴露tspd命令指向./cmd/tspd.jsengines要求 Node.js 22.0.0。README 给出的最小用法是tspd --enable-experimental gen-extern-signature tspd --enable-experimental doc . --output-dir ./docs/从 CLI 源码 可以看到--enable-experimental不是普通开关而是一道强制门槛yargs 的.check()回调会在未携带该标志时打印红色警告tspd (TypeSpec Library Developer Cli) is experimental and might be BREAKING between versions并直接process.exit(1)。这一设计在 0.69.0 起的所有版本中保持稳定——变更日志中没有任何移除该门槛的记录读者在 CI 脚本中使用时必须显式携带该标志。命令行全貌源码中的真实参数以下参数清单直接来自 cli.ts可以作为当前版本0.77.1的参数权威参考命令/选项说明doc entrypoint为 TypeSpec 库生成文档entrypoint为库入口路径必填位置参数doc --output-dir文档输出目录默认entrypoint/docs见 cli.ts 第 100 行 的?? resolvePath(resolvedRoot, docs)doc --skip-js跳过 JS API 文档生成doc --typekits生成 typekit 文档Currently targeted for use with Astro Starlightdoc --llmstxt为生成文档添加 llmstxt frontmatter辅助生成 llms.txt 文件doc --rules-dir逐规则参考页的输出目录相对--output-dir默认rules可写../rules放到参考目录之外gen-extern-signature entrypoint根据package.json的 exports 生成装饰器/函数签名入口路径必填--debug/--pretty全局选项调试日志 / 彩色格式化编译器错误输出默认开启注意doc与gen-extern-signature虽然入口都是库路径但gen-extern-signature并不接收--output-dir——它的输出位置由包结构决定见下文。能力演进一gen-extern-signature装饰器签名与类型检查的基础生成gen-extern-signature的基本工作流在 gen-extern-signatures.ts 中清晰可见读取库的package.json通过resolveTypeSpecExports收集所有exports中带typespec条件的条目第 55-88 行每个条目独立编译一次parseOptions: { comments: true, docs: true }保留文档注释用于生成 doc comment通过语义遍历收集装饰器与函数按命名空间聚合后交由 alloy 模板生成 TypeScript 文件用库自身的 Prettier 配置格式化输出写入generated-defs/生成前会先清空该目录第 178-181 行。生成的签名文件按命名空间命名如MyLib.ts配套的*.ts-test.ts类型检查文件会导入同一个子路径的$decorators确保签名与实际导出一致。auto 装饰器类型化访问器is*/get*0.76.0与set*0.77.0CHANGELOG 0.76.0 记录gen-extern-signature开始为auto装饰器生成类型化访问器函数isMyFlag、getMyLabel0.77.0 则补齐了类型化 settersetMyFlag、setMyLabel。对应的实现是 auto-decorator-accessors.tsx生成规则与其源码注释完全吻合无参 auto 装饰器→ 生成is*布尔检查函数内部调用编译器的hasAutoDecorator单参 auto 装饰器→ 生成get*函数返回类型解包为裸值| undefinedunwraps to the bare value to preserve parity with hand-written extern getterssetter 接受裸值并自动包装进{ paramName: value }存储记录多参 auto 装饰器→ 生成返回{ param1: T1; param2: T2 } | undefined的get*setter 接受整个 record。CHANGELOG 0.77.1 给出的示例正是这一机制的产物/** Check if the TypeSpec.GraphQL.inputType decorator was applied on the given target. */ export function isInputType(program: Program, target: Model): boolean { return hasAutoDecorator(program, TypeSpec.GraphQL.inputType, target); } /** Mark a model as a GraphQL input type in the emitted schema. */ export function setInputType(program: Program, target: Model): void { setAutoDecorator(program, TypeSpec.GraphQL.inputType, target); }这些访问器是编译器通用 auto decorator API 的薄封装源码注释原文thin wrappers around the compilers generic auto decorator API其用途是让 Emitter 与 mutator 能对合成类型做程序化标记。仓库中 http-client-csharp 的 generated-defs 等目录即可看到此类生成文件的真实形态。子路径导出sub path exports支持0.77.10.77.1 是gen-extern-signature结构性最大的一次变更签名生成扩展到了每一个exports中带typespec条件的子路径条目而不是仅根导出。README 的 Sub path exports 一节完整说明了这一行为每个导出条目独立编译装饰器/函数归属于第一个到达其声明文件的导出条目——即根入口声明的实体即使被子路径再导入回来也仍归属根输出目录布局根导出写入generated-defs/子路径写入对应子目录且生成的测试文件从同一个子路径导入$decoratorsgenerated-defs/MyLib.ts - from ., imports from my-lib generated-defs/streams/MyLib.Streams.ts - from ./streams, imports from my-lib/streamsCHANGELOG 0.77.1 中的示例展示了测试文件的导入形态// generated-defs/streams/MyLib.Streams.ts-test.ts import { $decorators } from my-lib/streams; import type { MyLibStreamsDecorators } from ./MyLib.Streams.js; const _decs: MyLibStreamsDecorators $decorators[MyLib.Streams];实现层面gen-extern-signatures.ts 的resolveSourceFileOwnership实现了先到先得的文件归属按package.json声明顺序遍历各导出根条目.恒排第一每个源文件被第一个到达它的导出认领。另外两个值得注意的细节符号链接处理源文件归属比较使用 realpath以应对 pnpm workspace 链接导致同一文件在不同 Program 中出现不同路径的情况第 165-176 行JS 入口要求子路径必须暴露自己的 JS 模块import或default条件并导出其声明装饰器的$decorators且 TypeSpec 入口必须导入该 JS 模块否则类型检查文件无法生成emitTests置为false并报告sub-export-missing-js诊断。生成访问器的文档注释0.77.10.77.1 的 Bug Fixes 中第一条为生成的 auto 装饰器访问器补充文档注释使重新导出这些函数的库能满足 api-extractor 的ae-undocumented规则。规则细节同样记录在 CHANGELOGget*/set*访问器携带其所读写装饰器的描述而is*访问器因为装饰器描述无法描述一个布尔检查改为使用通用描述。对应实现是 auto-decorator-accessors.tsx 中的AccessorDoc与getDocDescription其中有两条工程取舍值得注意注释通过独立的AccessorDoc组件渲染而非函数声明的docprop——因为后者还会输出param {Type}标签其中的类型引用会被计入值使用导致本应 type-only 的导入变成值导入源码注释明确说明了这一动机param标签会被有意丢弃只保留描述文本因为装饰器的param描述的是 TypeSpec 参数与访问器签名对不上同时internal会被转义为_internal以避免触发 tsdoc 标签解析问题。尊重库自身的 tspconfig.yaml0.77.10.77.1 还修复了一个影响opt-in 编译器特性的库的问题生成签名和参考文档时现在会读取库自己的tspconfig.yaml使得启用auto-decorators等特性的库在gen-extern-signature和doc期间不再误报错误。实现非常简洁见 library-config.tsexport async function resolveLibraryCompilerOptions( host: CompilerHost, entrypoint: string, ): PromiseCompilerOptions { const [options] await resolveCompilerOptions(host, { cwd: process.cwd(), entrypoint }); return { ...options, noEmit: true }; }即用编译器的resolveCompilerOptions解析库的配置再强制noEmit: true——注释解释为tspd only ever inspects a library, so emitting is always disabled。该函数同时被doc管线experimental.ts 第 78 行使用两个命令共享同一条配置解析路径。能力演进二doc 参考文档生成逐规则/逐诊断参考页与 documentation-missing 警告0.77.0CHANGELOG 0.77.0 记录了tspd doc的一项重要能力为每条 linter 规则生成reference/rules/name.md页面、为每个诊断生成reference/diagnostics/code.md页面内容取自规则与诊断定义上的docs字段任何未提供文档的规则或诊断都会触发documentation-missing警告。在源码中可以印证lib.ts 定义了documentation-missing诊断extractor.ts 中在十余处收集文档缺失的位置装饰器、函数、规则、诊断等实体都会发出该警告。这意味着tspd doc不只是一个生成器还是一个文档完整性检查器——退出前可以通过警告列表找出库中缺少文档的 API。--rules-dir选项0.77.0同一版本新增了--rules-dir以及 API 层rulesDir选项来控制逐规则参考页的落盘位置默认rules相对--output-dir可以设置为逃出输出目录的路径如../rules把规则页面留在生成的 reference 文件夹之外。该选项在 cli.ts 第 89-93 行 声明经由 experimental.ts 的GenerateLibraryDocsOptions传入renderToAstroStarlightMarkdown。llmstxt frontmatter0.73.00.73.0 为生成的参考文档引入了llmstxtfrontmatter用于支持 llms.txt 生态。这是一个 opt-in 特性需要显式传--llmstxt才启用对应 cli.ts 第 84-88 行 的--llmstxt选项。typekit 文档0.71.0与 emitter 选项渲染0.75.00.71.0新增--typekits标志为 typekit 生成基础文档Currently targeted for use with Astro Starlight。在 experimental.ts 中可以看到该分支options.typekits为真时调用writeTypekitDocs同版本还修复了重复 usage 段落的问题emitter usage 段落更名为 Emitter usage。0.75.0改进复杂 emitter 选项的渲染并为 sub exports 渲染文档0.75.0 的 bug fix 则让函数类型签名改用箭头语法渲染并避免内部编译器导入——这让生成文档中出现的函数签名更符合现代 TS 习惯也不会在文档里泄漏编译器内部类型。其他值得注意的修复0.74.2修复自动生成的 linter 参考页上指向规则页的 404 链接——问题出在链接丢失了网站 base path0.73.1修复装饰器签名生成中union of union联合类型的联合作为目标类型时的处理0.70.0内部装饰器签名生成迁移到 alloyTypeSpec 官方的代码生成框架package.json依赖中的alloy-js/core、alloy-js/markdown、alloy-js/typescript即由此而来0.69.0CHANGELOG 最早版本始终将emitter-output-dir加入选项列表修复typedoc缺失依赖、无 node 类型的处理等问题。版本时间线速览版本主题关键变更0.69.0基线emitter-output-dir选项typedoc 依赖修复0.70.0重构内部签名生成迁移到 alloy0.71.0功能--typekits标志Starlight 场景0.73.0功能--llmstxtopt-in frontmatter0.73.1修复union-of-union 目标类型处理0.74.0–0.74.2修复/依赖linter 参考页 404 链接修复0.75.0功能/修复复杂 emitter 选项渲染、sub export 文档、箭头签名0.76.0功能auto 装饰器is*/get*访问器0.77.0功能set*访问器规则/诊断参考页 documentation-missing--rules-dir0.77.1修复/功能访问器文档注释ae-undocumented尊重库tspconfig.yaml子路径导出签名实战建议与适用前提结合当前仓库的实际状态0.77.1使用 tspd 时需要注意以下事实边界实验性定位不变从 0.69.0 到 0.77.1 的整份 CHANGELOG 中--enable-experimental门槛从未被移除且 README 仍明确警告未来版本可能大幅变化。跨版本升级时应重点回归generated-defs/与docs/的生成结果。两个命令的输入都必须是库而非普通模型gen-extern-signature要求package.json的exports中带typespec条件否则报exports-missing诊断doc则要求库可被编译器正常编译tspMain或入口路径可达。子路径库的两个硬性前置条件子路径要暴露独立 JS 模块导出$decorators且其 TypeSpec 入口要导入该 JS 模块——缺 JS 入口时类型检查文件会被跳过并给出sub-export-missing-js警告这不是报错而是有意的降级。输出目录约定签名固定输出到库根下的generated-defs/子路径对应子目录且每次运行前清空doc默认输出到entrypoint/docs同时会回写库根目录的README.mdexperimental.ts 第 52-57 行 的renderReadme结果直接写入libraryPath/README.md——在 CI 中使用doc时这一点常被忽略。环境要求Node.js 22.0.0库自身tspconfig.yaml中的编译器特性如auto-decorators会在 0.77.1 起被正确尊重而 tspd 自身的编译始终以noEmit运行。想进一步深入实现细节建议按以下路径阅读仓库源码packages/tspd/src/cli.ts命令与参数定义、packages/tspd/src/gen-extern-signatures/签名生成组件含 alloy 模板、packages/tspd/src/ref-doc/文档提取与 Starlight/Docusaurus/Markdown 三种 emitter、packages/tspd/src/utils/library-config.ts库配置解析以及 packages/tspd/test/ 下的测试用例。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
