ttsc 维护者 Wiki

    仓库地图

    本页是顶层目录导览。先给出整个工作区的版图，再逐个解释每个目录的职责、重要性、何时需要改它，以及哪些是生成物 / 夹具 / 缓存。

    工作区性质

    根 package.json 名为 @ttsc/station（private: true），它是一个 pnpm workspace（pnpm-workspace.yaml 列出 config、packages/*、tests/*、website）。包管理器固定为 pnpm@10.6.4。catalog 把 typescript 固定到 7.0.1-rc（即 tsgo），同时保留 ts-legacy（npm:typescript@~6.0.3）给少数需要旧 JS 编译器 API 的工具（如 @rollup/plugin-typescript、typescript-eslint、factory 的奇偶校验 oracle）。

    规模量级（排除 node_modules、dist、lib）：

    语言 / 区域约 LOC
    Go（packages/*，不含 shim）~144,000
    Go（packages/ttsc/shim）~3,600
    TypeScript（packages/* 源码）~48,000
    TypeScript（tests/*）~42,000
    Go（tests/*）~1,700
    工作区脚本（scripts/）~1,900

    Go 体量集中在 packages/lint（~102k LOC，含 60k 的 linthost 引擎和数百条规则）和 packages/ttsc（36k LOC 的宿主/驱动/shim）。

    顶层目录

    目录作用重要性何时改它
    packages/ttsc核心：JS 启动层 + API，Go 宿主（cmd/*、driver、internal、utility、shim/）。最高改编译/转换/LSP/插件加载/CLI 行为
    packages/lint@ttsc/lint：自带原生 lint+format 引擎与 720+ 规则。高加/改规则、格式化器、lint LSP
    packages/graph@ttsc/graph：把 checker 解析出的代码图谱通过 MCP 暴露给编码代理。高改图谱模型、MCP 工具、3D 查看器
    packages/factory@ttsc/factory：零依赖、手写的 TypeScript AST factory + 宽度感知 printer。中扩展 AST 节点/printer 覆盖面
    packages/banner packages/paths packages/strip工具 transform 插件，自带 driver/ 逻辑链接进通用原生宿主。中改这些插件的转换行为
    packages/unplugin@ttsc/unplugin：把 ttsc 插件接进 Vite/Rollup/Rolldown/esbuild/Webpack/Rspack/Next/Farm/Bun。中改打包器适配
    packages/metro@ttsc/metro：React Native / Expo 的 Metro transformer。中改 RN/Expo 集成
    packages/wasm@ttsc/wasm：浏览器内 ttsc playground 的 Go host 与 JS 引导。中改浏览器编译宿主
    packages/playground@ttsc/playground：可复用的 Web Worker + React 外壳，建在 @ttsc/wasm 上。中改 playground 组件 / worker
    packages/vscodeVS Code 扩展，把 vscode-languageclient 接到 ttscserver。中改编辑器扩展
    packages/ttsc-{platform}七个按平台分发的包（原生 helper + 打包的 Go SDK）。中发布管线 / 平台二进制
    tests/projects项目形态的夹具，TestProject.copyProject 拷进临时目录。高加需要真实目录布局的 e2e 场景
    tests/test-*各功能 e2e 测试包（pnpm test:features 跑）。高加功能测试
    tests/utils共享测试辅助（@ttsc/testing）。中改测试基础设施
    website基于 Nextra 的官方指南站点（src/content/docs/**/*.mdx），即 https://ttsc.dev。高改面向使用者的文档
    experimental基准测试、安装演练、source-map 探针、tarball 打包等实验脚本。中改基准/打包流程
    config scripts共享 tsconfig 与工作区脚本。中改构建/测试编排脚本
    .githubCI 工作流（build、test、release、website、typia、nestia 等）。中改 CI

    node_modules/、各包的 lib/、dist/、doc_build/、.work/ 是构建输出或依赖缓存，本 Wiki 不当源码解释。packages/lint/linthost/*_gen.go 与 shim/*/surface.go、*/enums_gen.go、*/flags_gen.go 是生成文件（详见各子系统页）。

    packages/ttsc 内部布局

    这是产品心脏，单独展开：

    packages/ttsc/
├── src/                       # JavaScript 启动层 + 公共 API（~11.7k LOC TS）
│   ├── index.ts               # 只导出 TtscCompiler / TtscService / structures
│   ├── TtscCompiler.ts        # 编程式编译宿主
│   ├── TtscService.ts         # 常驻转换服务（热宿主）
│   ├── launcher/              # 三个 CLI 入口 + 内部
│   ├── compiler/internal/     # 项目解析、原生二进制构建、build/transform 编排
│   ├── plugin/internal/       # 插件发现/加载 + go build 缓存
│   ├── flags/                 # 统一 flag schema + 解析器
│   └── structures/            # 公共 DTO 接口（ITtscPlugin 等）
├── cmd/                        # Go 可执行入口
│   ├── ttsc/                  # 原生编译宿主（build/check/api-compile/api-transform/demo）
│   ├── ttscserver/            # LSP 宿主入口
│   ├── ttscgraph/             # 图谱 dump CLI
│   ├── utility-host/          # 链接插件的通用宿主 + 常驻 serve
│   ├── platform/ graphbench/ graphdump/  # 辅助命令
├── driver/                     # 唯一允许 import shim/* 的 Go 包：编译器外观层
├── internal/
│   ├── lspserver/             # 字节级 LSP 代理（~2.9k LOC）
│   ├── graph/                 # checker 解析的代码图谱构建（~4.5k LOC）
│   └── cwd/                    # cwd 解析小工具
├── utility/                    # 通用原生宿主的 host/serve 逻辑
├── shim/                       # 逐个再导出 typescript-go internal/* 的子模块
└── tools/                      # gen_shims（生成器）、shim_audit（完整性闸门）

    packages/ttsc 的 package.json 里 bin 暴露三个 CLI（ttsc/ttscserver/ttsx），types 指向 src/index.ts，七个平台包列为 optionalDependencies。详见 ttsc 包。

    语言与构建系统

    • TypeScript 用 tsgo（typescript@7.0.1-rc）编译；JS 层产物落在各包的 lib/。
    • Go 由 打包在平台包里的 Go SDK 编译，不依赖系统 Go（见 go build 缓存 的 resolveGoCompiler）。
    • 工作区根脚本 pnpm build → scripts/build-platforms.cjs；pnpm build:current → scripts/build-current.cjs（只构建当前平台，测试前用）。
    • 测试分两层：pnpm test:go（Go 单测，见 scripts/test-go-*.cjs）与 pnpm test:features（TS e2e，跑各 tests/test-* 包）。

    生成物与夹具速查

    类别位置说明
    生成的 shim 表面shim/*/surface.go、shim/*/enums_gen.gogo run ./tools/gen_shims 产出，勿手改
    生成的 flag 表src/flags/* 由 scripts/gen-flags.mts 触发，linthost/flags_gen.gopnpm gen:flags
    手写 shimshim/*/shim.go（首行 // gen_shims:hand-maintained）生成器跳过
    项目夹具tests/projects/*拷进临时目录运行
    基准夹具外部 GitHub 仓库 samchon/ttsc-benchmark-*见 基准测试

    下一步：架构总览。