企业官网建设流程全解析

scriptc开发者贡献指南：从pnpm沙箱测试到差分测试语料的工作流

【免费下载链接】scriptcTypeScript-to-Native Compiler项目地址: https://gitcode.com/GitHub_Trending/sc/scriptc

scriptc 是一个 TypeScript 到原生的编译器（TypeScript-to-Native Compiler），能把 TypeScript/JavaScript 直接编译成可读 C、LLVM IR、汇编、目标文件、原生可执行文件乃至 WebAssembly，产物无需 Node 即可运行。本文面向新贡献者，带你走通 scriptc 贡献的完整工作流：pnpm 工作区初始化、本地聚焦测试、pnpm test:sandbox沙箱全量验证，以及以 Node 为预言机的差分测试语料（differential corpus）。

scriptc 是什么，贡献者通常在改哪里

scriptc 是一个 pnpm monorepo，核心模块各司其职：

仓库根目录的 AGENTS.md 是唯一的贡献约定文档，涵盖测试位置规范、兼容性状态契约和生成文件的"禁手改"清单，建议贡献前通读一遍。

快速上手：pnpm 工作区初始化

贡献 scriptc 只需两步搭建环境：

1. 安装Node.js 24 或更新版本（仓库 package.json 中engines明确要求>=24.0.0）。
2. 克隆仓库并构建工作区：

git clone https://gitcode.com/GitHub_Trending/sc/scriptc cd scriptc pnpm install && pnpm -r build

💡 开发迭代时不必每次都跑全量测试。vitest 直接对编译器源码运行（无需 build 步骤，见 vitest.config.ts 中的@scriptc/compiler别名），你可以用-t <名称>只跑自己触碰的测试文件，最后再跑全量门。

pnpm test:sandbox：一条命令的全量验证门

本地测试绿了还不够，scriptc 的最终门槛是沙箱门：

pnpm test:sandbox

这条命令（入口 scripts/sandbox-test.mjs）会在一次性 Linux 沙箱中执行可移植的差分测试：自定义镜像约 4 分钟、冷启动托管回退约 9 分钟。macOS 宿主机保留原生（Darwin-native）契约，Linux 宿主则把受支持的 native-clang 契约在本地跑完，其余检查留在沙箱中。两条通道全绿才是可以提交的底线。

沙箱门的关键机制：

• 🧩按用例分片：差分语料等"墙钟时间大户"通过SCRIPTC_TEST_SHARD="i/n"在多个沙箱间切片并行（见 scripts/sandbox-test.mjs 中的分片文件清单）。
• 🔐凭据：优先使用VERCEL_OIDC_TOKEN；也可用VERCEL_TOKEN配合显式的VERCEL_TEAM_ID/VERCEL_PROJECT_ID。
• 🐳自定义镜像可选：未设置SCRIPTC_SANDBOX_IMAGE时，沙箱从通用镜像起步，安装仓库钉死的 Node、pnpm、LLVM 工具链后再构建（沙箱镜像定义见 Dockerfile.sandbox，配置见 scripts/sandbox-config.mjs）。

⚠️ 只有当 Vercel 沙箱凭据不可用时，才退回更慢的本地双通道：

SCRIPTC_TEST_WORKERS=4 pnpm test # plain 通道 SCRIPTC_TEST_WORKERS=4 SCRIPTC_SAN=1 pnpm test # 带 ASan 的 sanitized 通道

SCRIPTC_TEST_WORKERS用来限制 vitest 工作进程数，避免并行贡献者争抢 CPU；全量本地跑还会排队等待一把建议性锁（tests/harness/suite-lock.mjs），防止 CPU 超配导致的偶发失败。

差分测试语料：以 Node 为预言机，零黄金文件

这是 scriptc 最有辨识度的测试设计。语料位于 tests/corpus/，每个程序会同时跑两次：

1. 在 Node 上运行（Node 就是"预期输出"）；
2. 用 scriptc 编译成原生二进制再运行。

两边的stdout、stderr 和退出码必须逐字节一致。没有黄金文件、没有期望快照——Node 本身就是预言机，测试永远不会因手写期望值而漂移。核心实现见 tests/harness/differential.test.ts，完整规则说明见 tests/harness/README.md。

语料程序支持用前两行指令定制行为，非常轻量：

• // @exit: 1：声明预期退出码（未捕获抛错的程序在 Node 与 scriptc 下都退出 1，此时 stderr 不再比较）；
• // @dynamic：以动态岛模式（内嵌 JS 引擎）编译，Node 侧由 shim 补齐岛求值能力，仍可作为价值预言机；
• // @transform-types：Node 侧加--experimental-transform-types运行不可擦除的 TS 语法。

🔬 更妙的是 sanitized 通道：SCRIPTC_SAN=1下每个程序都以ASan + 运行时引用计数审计重新构建，整个语料瞬间变成泄漏/越界测试集。此外还有 LLVM 后端双跑差分（tests/harness/llvm-differential.test.ts）等辅助通道，均复用同一套语料。

如何添加新的差分测试用例

scriptc 的铁律是：一个新功能落地时，必须伴随能双向钉住其行为的语料程序。步骤如下：

1. 在 tests/corpus/ 新建编号命名的程序，例如2700-my-feature.ts（目录型用例用<名称>/main.ts组织模块图，可参考 tests/corpus/001-hello.ts 这类单文件入门样例）；
2. 若涉及异常退出、动态岛或非擦除语法，在文件头两行内加上对应指令；
3. 开发期聚焦运行：

pnpm exec vitest run tests/harness/differential.test.ts -t my-feature

4. 全量门绿了再提交。

测试位置遵循范围约定：白盒单测与实现文件同目录（cc.ts→cc.test.ts，放在packages/*/src下）；包级 API 与集成测试放packages/*/test；跨包差分、脚手架与端到端测试一律放根tests/目录。

缓存机制：为什么重跑这么快

约 275 个语料程序 × 两条通道，若每次都全量 clang 编译显然不可接受。scriptc 为此内置了多层内容寻址缓存，测试统一钉在node_modules/.cache/scriptc-tests/cas（可用SCRIPTC_CACHE_DIR覆盖）：

• 二进制缓存：命中即跳过编译与链接，但二进制仍真实执行，比较与审计从不跳过；
• 预言机缓存：Node 侧的 stdout/退出码按"程序字节 + Node 版本"缓存；含定时器交叉输出的实时程序则永远实时运行，保证公平比较。

想排除缓存嫌疑时，SCRIPTC_NO_CACHE=1可双向旁路所有缓存；pnpm test:cache-identity则是缓存正确性的验收工件——它分别跑无缓存与有缓存全量并 diff 所有结果，任何漂移都会非零退出。

贡献工作流总清单

提交前按顺序过一遍，全部绿了才算完成：

• ✅pnpm install && pnpm -r build—— 工作区构建通过
• ✅ 聚焦测试（-t过滤）在新语料程序上通过
• ✅pnpm test—— plain 通道全量
• ✅SCRIPTC_SAN=1 pnpm test—— sanitized 通道全量
• ✅pnpm test:sandbox—— 沙箱门双通道全绿
• ✅ 若改动了编译器判定表或兼容性清单：运行pnpm manifest与pnpm node-compat重新生成，绝不手改 packages/compiler/surface-manifest.json 等生成文件

常用命令速查

按这套"聚焦迭代 → 双通道全量 → 沙箱门 → 差分语料双向钉行为"的节奏提交，你的改动就能稳稳并入 scriptc 的原生编译之旅 🚀

【免费下载链接】scriptcTypeScript-to-Native Compiler项目地址: https://gitcode.com/GitHub_Trending/sc/scriptc