项目定位与目标

scriptc 是 Vercel Labs 推出的一款实验性命令行工具，目标是把 TypeScript 源码直接编译为原生可执行文件。它以 TypeScript 作为解析与类型检查入口，复用官方 Compiler API 完成诊断与 AST 构造，再借助 LLVM/clang 工具链生成 C 代码与机器码，最终产出无需 V8 或 Node 运行时即可独立运行的二进制产物。

工具通过 npm install -g scriptc 安装后，以 scriptc 命令对外提供 build、run 等子命令，使用者只需维护一份 .ts 源文件，即可获得端到端的本地原生构建体验。

资料来源：README.md:1-40 资料来源：packages/cli/README.md:1-40

代码仓库结构

项目采用 monorepo 组织方式，根目录的 package.json 声明了 workspaces，统一管理多个子包及其依赖。整体职责划分为三层：

• packages/cli：负责命令入口、参数解析、子命令调度与用户交互，并暴露 scriptc 可执行文件。
• packages/compiler：承担 TypeScript 解析、类型擦除、C 源码生成以及 clang 编译驱动等核心职责，是工具链的大脑。
• packages/compiler/ambient：提供编译器与目标运行时所需的 TypeScript ambient 类型声明，让平台层语义在 TS 侧可被正确推断。

子包之间通过 package.json 中的 dependencies 与 workspaces 协议互相引用：CLI 组装用户参数并调用 compiler 包对外暴露的 API，compiler 包再依赖 ambient 子包获得类型基础。

资料来源：package.json:1-40 资料来源：packages/cli/package.json:1-40 资料来源：packages/compiler/package.json:1-40 资料来源：packages/compiler/ambient/package.json:1-40

核心编译流程

整体流水线可概括为「TypeScript 源码 → 类型检查 → AST 转换 → C 代码生成 → clang 编译 → 原生二进制」。CLI 接收用户脚本路径后，调用 compiler 包，借助 TypeScript Compiler API 加载并解析文件、执行类型推断与诊断，再把 AST 翻译为对应的 C 源码，最后调用 clang 完成编译与链接。

flowchart LR
    A["用户 .ts 源码"] --> B["TypeScript Compiler API"]
    B --> C["类型擦除 / AST 转换"]
    C --> D["生成 C 源码"]
    D --> E["clang 编译链接"]
    E --> F["原生可执行文件"]

资料来源：README.md:10-80 资料来源：packages/cli/README.md:10-50

版本演进与平台支持

最新发布版本为 0.0.17，重点修复了 Windows 平台上的路径与可执行后缀处理问题：TypeScript 虚拟文件系统现在统一使用正斜杠形式的 Windows 路径，默认可执行文件名会在原生与跨平台 Windows 构建中追加 .exe 后缀，工作区构建命令也兼容 PowerShell 与 Git Bash 的引号转义；项目还新增了一条 Windows CI lane，专门锁定路径相关的回归，并驱动 scriptc run 跑通端到端验证。

资料来源：README.md:60-140

在更早的 0.0.16 中，社区曾报告 scriptc run 在 Windows 原生环境下出现 ts7 createProgram: project failed to open 的失败（参考 Issue #10），本次修复正是针对该问题。

社区方面，也有作者建议引入对 JavaScript/ECMAScript 源码的编译能力（参考 Issue #13 "JavaScript support"），希望增加 JS 类型推断 IR 层并复用现有 C 代码生成后端；但截至当前版本，项目仍以 TypeScript 作为唯一受支持的源码格式。

资料来源：packages/compiler/package.json:1-40

src 目录是 scriptc 项目的核心源码组织空间，按职责划分为若干并列的子包：cli、compiler、create-program、tsc-paths。每个子包通过独立的 src 目录暴露 TypeScript 入口，并由 tsc 编译为 JavaScript 后对外提供能力。整个 src 模块的职责是把 TypeScript 源码通过 tsc 与 clang 链路转换为原生可执行文件，并在 Windows / Unix 上保持一致的命令行体验。

模块组成与职责

cli 子包是用户交互入口，负责解析命令行参数、调度构建与运行子命令。其核心文件包括：

• main.ts：CLI 入口与子命令分发。
• paths.ts：跨平台路径规范化（解决 Windows 上的 ts7 createProgram 失败问题）。
• build.ts：调用 create-program 与 compiler 完成构建流程。
• run.ts：调用 build 产物并执行生成的二进制文件。

compiler 子包负责把 tsc 生成的 JavaScript / 目标文件链接为原生二进制：

• index.ts：编译器对外 API。
• linker.ts：调用 clang 完成链接与产物输出。

create-program 子包封装了为给定源码创建 TypeScript Program 的过程，并返回供 tsc 与后续工具使用的虚拟文件系统与程序实例。tsc-paths 子包则负责解析 tsconfig.json 中的 paths / baseUrl 等路径映射，使 tsc 的 createProgram 在解析跨包引用时能够正确定位源码。

资料来源：packages/cli/src/main.ts:1-40, packages/cli/src/paths.ts:1-30, packages/compiler/src/index.ts:1-30, packages/create-program/src/index.ts:1-40, packages/tsc-paths/src/index.ts:1-40, packages/compiler/src/linker.ts:1-30。

CLI 子模块的内部流程

cli/src/main.ts 注册并路由 build、run、check 等子命令。run 子命令内部会先调用 build 模块产出可执行文件，再通过 run.ts 启动该文件。paths.ts 在 Windows 上把反斜杠统一转换为正斜杠，使 TypeScript 虚拟文件系统能够正确加载项目；并为 Windows 目标平台自动为可执行文件追加 .exe 后缀。

资料来源：packages/cli/src/main.ts:20-120, packages/cli/src/paths.ts:10-60, packages/cli/src/build.ts:1-80, packages/cli/src/run.ts:1-60。

这一处理直接对应社区反馈中关于 Windows 上 scriptc run 失败的修复（参见 issue #10），v0.0.17 在该区域补齐了路径规范化、可执行后缀与 Shell 引号转义三项修复。

编译器与程序创建协作

create-program/src/index.ts 返回的 Program 与虚拟文件系统被传递给 tsc 进行类型检查与代码生成；compiler/src/index.ts 进一步消费这些产物并通过 linker.ts 调用 clang 完成链接。tsc-paths/src/index.ts 在创建 Program 之前根据 tsconfig.json 的 paths 字段改写模块解析逻辑，确保跨包源码能够被正确发现。

flowchart LR
  A[cli/main.ts] --> B[cli/paths.ts]
  A --> C[cli/build.ts]
  A --> D[cli/run.ts]
  C --> E[tsc-paths/src/index.ts]
  C --> F[create-program/src/index.ts]
  F --> G[tsc 类型检查与代码生成]
  G --> H[compiler/src/index.ts]
  H --> I[compiler/linker.ts]
  I --> J[clang 链接产物]
  D --> J

资料来源：packages/cli/src/main.ts:40-100, packages/compiler/src/index.ts:10-60, packages/compiler/src/linker.ts:10-80, packages/create-program/src/index.ts:20-90, packages/tsc-paths/src/index.ts:10-60。

跨平台与扩展点

src 模块的设计在跨平台层面集中在两个扩展点：路径处理（paths.ts）与产物命名（build.ts 与 linker.ts 中对 executableName 的处理）。当需要新增目标平台（如新增架构或操作系统）时，主要改动集中在 paths.ts 的平台判断与 linker.ts 调用的 clang 参数拼接部分。

社区中关于 JavaScript 支持的讨论（issue #13）暗示，未来 src 模块可能会在 create-program 之上扩展一层 JavaScript 类型推断 IR，但当前的源码组织并未体现该能力，仍以 TypeScript 作为唯一输入语言。

资料来源：packages/cli/src/paths.ts:20-80, packages/compiler/src/linker.ts:20-70, packages/create-program/src/index.ts:40-120, packages/cli/src/build.ts:20-80。

子模块入口速查

资料来源：packages/cli/src/main.ts:1-20, packages/cli/src/paths.ts:1-10, packages/cli/src/build.ts:1-10, packages/cli/src/run.ts:1-10, packages/compiler/src/index.ts:1-10, packages/compiler/src/linker.ts:1-10, packages/create-program/src/index.ts:1-10, packages/tsc-paths/src/index.ts:1-10。

概述与职责

Cli 模块是 scriptc 项目的命令行前端，负责向用户暴露 scriptc run 等可执行入口，串联 TypeScript 解析、类型检查与 LLVM/Clang 编译产物之间的整体工作流。该模块被打包成独立的 npm 包，并通过 bin 字段注册到全局 PATH 中，使开发者可以直接通过终端调用。

• 包级别元数据与可执行入口声明位于 packages/cli/package.json。
• 项目根目录说明、安装与基础命令示例见 packages/cli/README.md。
• 编译配置（目标、模块系统）由 packages/cli/tsconfig.json 控制。

资料来源：packages/cli/package.json:1-40、packages/cli/README.md:1-60、packages/cli/tsconfig.json:1-30

入口与命令结构

CLI 的运行时入口是 packages/cli/src/main.ts，它负责解析用户参数、根据子命令派发任务，并将控制权转交给下游编译器与运行器模块。

主要行为包括：

• 解析 scriptc run 等子命令及其附带参数。
• 调用路径处理工具，将相对或绝对路径标准化为底层编译器可接受的形态。
• 触发编译流水线并执行生成的可执行文件。
• 将 stdout/stderr 透传给用户终端。

资料来源：packages/cli/src/main.ts:1-120

跨平台路径处理（paths.ts）

由于 Windows 与类 Unix 系统在路径分隔符、可执行后缀以及 Shell 转义上的差异，CLI 将所有路径相关逻辑收敛到 packages/cli/src/paths.ts：

这一层抽象直接对应社区反馈的痛点：Issue #10 报告 scriptc run 在 Windows 下因路径问题触发 ts7 createProgram: project failed to open，v0.0.17 版本即在此模块完成修复，并新增 Windows CI 通道进行回归保护。

资料来源：packages/cli/src/paths.ts:1-90、packages/cli/package.json:1-40

工作流概览

flowchart LR
    A[用户执行 scriptc run] --> B[main.ts 参数解析]
    B --> C[paths.ts 路径规范化]
    C --> D[调用编译器与运行器]
    D --> E[生成可执行文件 .exe 或 ELF]
    E --> F[透传 stdout/stderr]

工作流清晰划分了"命令解析 → 平台适配 → 编译执行"三段职责，使 CLI 既能在类 Unix 平台开箱即用，也能在 Windows 原生环境下稳定运行。

资料来源：packages/cli/src/main.ts:1-120、packages/cli/src/paths.ts:1-90

关联社区讨论

• Issue #10 反映了在 Windows 下运行 scriptc run 时的路径与可执行名处理问题，本模块的 paths.ts 正是修复落点。
• 最新版本 v0.0.17 的 Release Notes 中明确指出："TypeScript 的虚拟文件系统现在能够看到统一斜杠规范化后的 Windows 路径"、"默认可执行文件名携带必需的 .exe 后缀"、"工作区构建命令在 Windows Shell 引号下仍可幸存"，这些改进均直接发生在 CLI 模块内。
• Issue #13 讨论的 JavaScript 支持属于编译器层面的扩展，不在当前 CLI 模块的职责范围内，但若后续扩展子命令，main.ts 的派发结构提供了清晰的接入点。

资料来源：packages/cli/src/paths.ts:1-90、packages/cli/src/main.ts:1-120

Pitfall Log / 踩坑日志

项目：vercel-labs/scriptc

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Static builds fail on Linux/glibc: host clang path is missing -D_GNU_SOURCE and -lm。

1. 安装坑 · 来源证据：Static builds fail on Linux/glibc: host `clang` path is missing `-D_GNU_SOURCE` and `-lm`

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Static builds fail on Linux/glibc: host clang path is missing -D_GNU_SOURCE and -lm
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vercel-labs/scriptc/issues/3 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：scriptc run` fails with "ts7 createProgram: project failed to open" on Windows (0.0.16)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：scriptc run` fails with "ts7 createProgram: project failed to open" on Windows (0.0.16)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vercel-labs/scriptc/issues/10 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://news.ycombinator.com/item?id=49063175 | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063175 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=49063175 | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=49063175 | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：JavaScript support

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：JavaScript support
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/vercel-labs/scriptc/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063175 | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063175 | release_recency=unknown