ttsc 维护者 Wiki

    构建与测试

    本页讲 ttsc 的构建脚本、两层测试体系（Go 单测 + TS e2e）、测试纪律、以及 CI 工作流。命令以 .codex/skills/project/SKILL.md 与 .codex/skills/development/SKILL.md 为准。

    构建脚本

    脚本命令作用
    buildnode scripts/build-platforms.cjs构建全部七个平台包（慢）
    build:currentnode scripts/build-current.cjs只构建当前平台（开发用）
    gen:flagsnode packages/ttsc/scripts/gen-flags.mts从 schema 生成 flag 表
    check:flagsnode packages/ttsc/scripts/check-flags.cjs验证生成 flag 产物与 schema 一致
    formatprettier + gen:flags + format:go（gofmt 2 空格）提交前必跑

    各包自己的 build 通常是 rimraf lib && tsc（TS 包）或经 scripts/go.cjs build-native（Go 二进制）。

    测试体系：两层

    pnpm test（scripts/ 编排）跑全套：

    pnpm test
# = check:flags + build:current + test:go + test:typecheck + test:features

    Go 单测（test:go）

    pnpm test:go 跑四个脚本（scripts/test-go-*.cjs）：

    node scripts/test-go-transformer.cjs       # tests/go-transformer
node scripts/test-go-utility-plugins.cjs   # banner/paths/strip
node scripts/test-go-lint.cjs              # packages/lint
node scripts/test-go-graph.cjs             # internal/graph

    每个脚本 go test -count=1 ./... 对应目录。Go 路径优先用 ~/go-sdk/go/bin 的 Go（test-go-transformer.cjs:7），其次系统 go。

    Go 单测住 packages/*/test/，规则（.codex/skills/development/SKILL.md）：一个测试一个文件，命名后断言什么。跑真实命令入口（如 go run ./plugin）让 wrapper 分支也被覆盖。

    TS e2e（test:features）

    pnpm test:features
# = pnpm --filter "./tests/test-*" -r --workspace-concurrency=1 start

    TS e2e 住 tests/test-*/src/features/，每个文件导出恰好一个 test_<snake_case> 函数、文件名匹配；DynamicExecutor 按前缀发现。它们 materialize 临时项目、spawn 真实二进制、断言可观察输出。

    tests/projects 是项目形态夹具（TestProject.copyProject 拷进临时目录），给需要真实目录布局而非合成临时 file map 的回归用。

    tests/ 各包：test-banner/test-paths/test-strip/test-lint/test-graph/test-metro/test-unplugin/test-ttsc/test-factory，加共享 utils（@ttsc/testing）、config、go-transformer、lint-contributor-demo。

    测试纪律：覆盖而非 happy path

    .codex/skills/development/SKILL.md 强调一个真实事故的教训：只喂规则自己的规范输出、断言不变，证明的是幂等性而非正确性。一批 formatter 过度匹配就是这么 ship 的。每条规则/predicate 需要：

    • 转换方向：mangled 输入 → 规范输出（输入≠输出）。
    • 负向 twin：每个正向有一个相邻、必须不动作的反例。
    • 边界：空、单元素、恰好宽度上限、最深嵌套、翻转决策的 modifier。
    • oracle 派生期望：期望取自权威 spec（format 用 Prettier 3.8.3、lint 用上游 ESLint 规则），绝不用代码自己的输出做快照（会锁进 bug）。

    每个 case 开头要有三段式 doc comment：一行 Verifies … 标题、一段说明非显然的 why（钉哪个分支/回归）、2-4 步编号场景。

    验证形态

    .codex/skills/development/SKILL.md 的验证规范——先跑证明改动的最窄命令，再跑更广命令（如果改了共享行为或打包）：

    改动类型验证
    Bug fix命名失败 case + 期望行为；跑修前 fail、修后 pass 的 repro
    Feature命名可观察行为；端到端跑
    Refactor命名应不变的；靠现有套件或行为锁定探针
    Review命名具体风险、缺失测试、回归

    CI 工作流

    .github/workflows/：

    工作流作用
    test.yml主测试套件
    build.yml多平台构建
    release.yml发布
    website.yml部署 ttsc.dev
    typia.yml nestia.yml下游兼容性夹具
    bun.yml source-map.yml experimental.yml专项

    shim 完整性闸门 shim-audit job 跑 pnpm --filter ttsc shim:audit（见 shim 审计与同步）。

    常见验证命令

    pnpm --filter ttsc shim:audit          # shim 完整性
pnpm --filter ttsc shim:audit:test     # shim 审计自测
node scripts/test-go-lint.cjs          # 只跑 lint Go 测试
pnpm --filter "./tests/test-lint" start # 只跑 lint e2e
node scripts/test-go-coverage.cjs      # Go 覆盖率

    禁止事项（来自 development skill）

    四条永不可接受，选任一即方向已错：

    • 无 monkey-patch / hardcode：别特判消费者、夹具名、期望值让输出匹配；修通用逻辑。
    • 无"只为过测试"逻辑：只为绿一条断言的分支是伪装的 bug。
    • 无强推坏设计：同类失败反复回来就是设计错了，找根因。
    • 无打地鼠：别只补浮现的那一个 case，想全这个根因能产生的所有 case 并都加覆盖。

    接下来