scriptc开发者贡献指南从pnpm沙箱测试到差分测试语料的工作流【免费下载链接】scriptcTypeScript-to-Native Compiler项目地址: https://gitcode.com/GitHub_Trending/sc/scriptcscriptc 是一个 TypeScript 到原生的编译器TypeScript-to-Native Compiler能把 TypeScript/JavaScript 直接编译成可读 C、LLVM IR、汇编、目标文件、原生可执行文件乃至 WebAssembly产物无需 Node 即可运行。本文面向新贡献者带你走通 scriptc 贡献的完整工作流pnpm 工作区初始化、本地聚焦测试、pnpm test:sandbox沙箱全量验证以及以 Node 为预言机的差分测试语料differential corpus。scriptc 是什么贡献者通常在改哪里scriptc 是一个 pnpm monorepo核心模块各司其职模块职责位置编译器前端与后端tsc API → 类型化 IR → C / LLVM 后端packages/compiler/C 运行时编译进每个 scriptc 二进制的原生运行时packages/runtime/CLIscriptc build \| run \| coveragepackages/cli/Node 兼容性清单与 Node v24 的 API 对齐账本internal/compatibility/差分测试语料与快照跨包差分、诊断快照、测试脚手架tests/仓库根目录的 AGENTS.md 是唯一的贡献约定文档涵盖测试位置规范、兼容性状态契约和生成文件的禁手改清单建议贡献前通读一遍。快速上手pnpm 工作区初始化贡献 scriptc 只需两步搭建环境安装Node.js 24 或更新版本仓库 package.json 中engines明确要求24.0.0。克隆仓库并构建工作区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_SHARDi/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_WORKERS4 pnpm test # plain 通道 SCRIPTC_TEST_WORKERS4 SCRIPTC_SAN1 pnpm test # 带 ASan 的 sanitized 通道SCRIPTC_TEST_WORKERS用来限制 vitest 工作进程数避免并行贡献者争抢 CPU全量本地跑还会排队等待一把建议性锁tests/harness/suite-lock.mjs防止 CPU 超配导致的偶发失败。差分测试语料以 Node 为预言机零黄金文件这是 scriptc 最有辨识度的测试设计。语料位于 tests/corpus/每个程序会同时跑两次在 Node 上运行Node 就是预期输出用 scriptc 编译成原生二进制再运行。两边的stdout、stderr 和退出码必须逐字节一致。没有黄金文件、没有期望快照——Node 本身就是预言机测试永远不会因手写期望值而漂移。核心实现见 tests/harness/differential.test.ts完整规则说明见 tests/harness/README.md。语料程序支持用前两行指令定制行为非常轻量// exit: 1声明预期退出码未捕获抛错的程序在 Node 与 scriptc 下都退出 1此时 stderr 不再比较// dynamic以动态岛模式内嵌 JS 引擎编译Node 侧由 shim 补齐岛求值能力仍可作为价值预言机// transform-typesNode 侧加--experimental-transform-types运行不可擦除的 TS 语法。 更妙的是 sanitized 通道SCRIPTC_SAN1下每个程序都以ASan 运行时引用计数审计重新构建整个语料瞬间变成泄漏/越界测试集。此外还有 LLVM 后端双跑差分tests/harness/llvm-differential.test.ts等辅助通道均复用同一套语料。如何添加新的差分测试用例scriptc 的铁律是一个新功能落地时必须伴随能双向钉住其行为的语料程序。步骤如下在 tests/corpus/ 新建编号命名的程序例如2700-my-feature.ts目录型用例用名称/main.ts组织模块图可参考 tests/corpus/001-hello.ts 这类单文件入门样例若涉及异常退出、动态岛或非擦除语法在文件头两行内加上对应指令开发期聚焦运行pnpm exec vitest run tests/harness/differential.test.ts -t my-feature全量门绿了再提交。测试位置遵循范围约定白盒单测与实现文件同目录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_CACHE1可双向旁路所有缓存pnpm test:cache-identity则是缓存正确性的验收工件——它分别跑无缓存与有缓存全量并 diff 所有结果任何漂移都会非零退出。贡献工作流总清单提交前按顺序过一遍全部绿了才算完成✅pnpm install pnpm -r build—— 工作区构建通过✅ 聚焦测试-t过滤在新语料程序上通过✅pnpm test—— plain 通道全量✅SCRIPTC_SAN1 pnpm test—— sanitized 通道全量✅pnpm test:sandbox—— 沙箱门双通道全绿✅ 若改动了编译器判定表或兼容性清单运行pnpm manifest与pnpm node-compat重新生成绝不手改 packages/compiler/surface-manifest.json 等生成文件常用命令速查命令用途pnpm test本地全量plain 通道SCRIPTC_SAN1 pnpm test本地全量ASan RC 审计通道pnpm test:sandboxVercel 沙箱全量验证门pnpm test:ts7TypeScript 7 前端一致性测试pnpm test:test262钉死版本的 Test262 回归档案pnpm bench:builds开发构建延迟基准256 函数模块图pnpm node-compat:backlog按 API 族导出 Node 兼容性工作队列按这套聚焦迭代 → 双通道全量 → 沙箱门 → 差分语料双向钉行为的节奏提交你的改动就能稳稳并入 scriptc 的原生编译之旅 【免费下载链接】scriptcTypeScript-to-Native Compiler项目地址: https://gitcode.com/GitHub_Trending/sc/scriptc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考