ttsc 维护者 Wiki

    工具插件：banner / paths / strip / lint

    packages/banner、packages/paths、packages/strip 是 ttsc 自带的小工具 transform 插件；packages/lint 是最大的 check 插件（单独有 lint 引擎子系统）。本页讲三个 transform 工具插件的共同形态与各自职责，作为"如何写一个 ttsc 插件"的活样板。

    共同形态

    三个工具插件结构一致，是源插件参考夹具：

    packages/<plugin>/
├── src/          # JS 描述符 (createTtscPlugin 工厂)
├── driver/       # 包自有的 transform 逻辑 (Go, 非 main 包)
├── plugin/       # package main 入口 (可执行旁车)
├── test/         # Go 单测
├── go.mod        # 独立 Go 模块
└── package.json

    它们的 driver/ 是非 main 包，作为链接 transform 链接进通用原生宿主（cmd/utility-host），经 driver.RegisterPlugin 注册并实现 链接插件 的某个 hook 接口。plugin/ 的 package main 让它们也能作为独立可执行旁车跑（测试用）。

    JS 描述符（src/）返回 ITtscPlugin，source 指向自己的 Go 包目录（从 context.dirname 派生绝对路径）。

    @ttsc/banner

    注入 @packageDocumentation JSDoc 横幅。它实现 SourcePreamblePlugin（见 链接插件）——在 tsgo parse 项目前前置源文本。这是 source preamble 注入的典型例子，driver 的 sourcePreambleFS 把它的输出前置到每个源文件（声明文件除外）。

    preamble 引入行偏移，emit 阶段会修正 sourcemap 坐标（见 Emit 与重写 的 AdjustEmittedSourceMap）。banner/test/ 有大量配置加载与 banner 文本解析的测试（resolve_banner_text_branches_test.go 等）。

    @ttsc/paths

    重写源路径别名，让 JS 与声明 emit 收到相对 import。TypeScript 的 paths 别名（@app/* 等）在 emit 后不会被 tsgo 自动转成相对路径；@ttsc/paths 在 transform 阶段把它们改写成相对 import，让产物能直接运行/发布。

    @ttsc/strip

    移除配置的调用与 debugger 语句。典型用于生产构建剥掉 console.log、调试钩子等。它在 transform 阶段删匹配的调用表达式与 debugger 语句。

    配置：dedicated config 文件

    按 .codex/skills/development/SKILL.md，第一方插件配置住在专门的 *.config.{ts,cts,mts,js,cjs,mjs,json} 文件，从入口向上 walk 自动发现。ttsc 自带包只接受 configFile（显式路径）外加 host 拥有的入口键。

    inline option 键已撤销：@ttsc/banner、@ttsc/paths、@ttsc/strip、@ttsc/lint 的 inline 选项键被撤销，让包配置有一个有类型、可发现的家——别重新引入它们。

    作为插件样板的价值

    这三个插件是学习插件协议的最佳起点，因为它们：

    • 展示链接 transform 的完整形态（JS 描述符 + 非 main Go 包 + RegisterPlugin）。
    • 各示范一类 hook：banner 示范 SourcePreamblePlugin，paths/strip 示范 transform 阶段重写。
    • 有完整的 Go 单测（test/），遵循"一个测试一个文件，命名后断言什么"（.codex/skills/development/SKILL.md）。

    @ttsc/lint 简述

    @ttsc/lint 是最大的插件（~102k Go LOC），是 check 阶段插件而非 transform，自带原生 lint+format 引擎。它声明 capabilities.threadingArgs 与 lsp。完整内容见 lint 引擎子系统。

    不变量

    • transform 工具插件的 driver/ 是非 main 包，链接进通用宿主。
    • 配置经 dedicated *.config.* 文件，不接受 inline 选项键。
    • 描述符 source 从 context.dirname 派生（加载模式无关）。

    维护者提示

    • 写新插件先抄这三个的结构：src/ 描述符 + driver/ Go 逻辑 + plugin/ main + test/。
    • 选对 hook：parse 前注入用 SourcePreamblePlugin，emit 注入 AST 用 EmitTransformPlugin（见 链接插件）。
    • 配置加 dedicated config 文件，别加 inline 键。

    接下来