scriptc 实战：用真实 npm 包 commander 构建原生计算器 CLI 的差分验收测试

typed-callback 边界：echo命令

echo命令是夹具中最重要的边界用例，它在源码注释中被命名为typed-callback boundary（calc.ts）：

interface EchoOptions { upper?: boolean; prefix?: string; } program .command("echo [text]") .description("echo text through an async typed action") .option("-u, --upper", "uppercase the output") .option("-p, --prefix <prefix>", "prefix the output") .action(async (rawText: string | undefined, opts: EchoOptions) => { await new Promise<void>((resolve) => { setTimeout(resolve, 1); }); const text = rawText !== undefined ? rawText : "(silence)"; const prefixed = opts.prefix !== undefined ? opts.prefix + text : text; const upper = opts.upper !== undefined && opts.upper; console.log(upper ? prefixed.toUpperCase() : prefixed); });

这段代码系统性检验了脚本从“声明层”跨入“island（动态引擎）”时，类型化回调的四种语义：

1. 可选命令参数[text]：未提供时以string | undefined的 undefined 分支到达回调；
2. commander 的 options 对象：在调用时刻转换为静态记录（record），缺失的选项自动落入可选字段的 undefined 分支（这正是EchoOptions中upper?: boolean、prefix?: string的作用）；
3. 尾随的 Command 参数：按声明参数个数（declared arity）丢弃，回调只收到rawText与opts两个参数；
4. async 函数体：其 promise 会被包装成真实引擎的 thenable，在动态引擎侧完成异步调度。

未观察拒绝路径：fail命令

fail命令（calc.ts）验证的是另一个极端：在普通parse()（同步返回）下，async action 的 rejection无人观察，于是落入未处理拒绝（unhandled rejection）报告，进程以退出码 1 结束：

program .command("fail <reason>") .description("reject asynchronously with the given reason") .action(async (reason: string) => { await new Promise<void>((resolve) => { setTimeout(resolve, 1); }); throw new Error(`cannot compute: ${reason}`); });

注释明确：此路径退出码与 Node 一致（exit 1），stderr 单行输出，但不做字节级对比（not byte-compared）。真正端到端覆盖 reject → catch 链路的是calc-async.ts。

calc-async.ts：经典 CLI 入口与双向 promise 桥

calc-async.ts 以真实 CLI 的逐字入口形态（verbatim real-CLI entry shape）书写，即parseAsync(process.argv).catch(handler)的完整链路：

program .command("double <n>") .description("double a number, asynchronously") .action(async (n: string) => { await new Promise<void>((resolve) => { setTimeout(resolve, 1); }); console.log(parseFloat(n) * 2); }); // Verbatim real-CLI entry shape. program.parseAsync(process.argv).catch((err: unknown) => { const msg = err instanceof Error ? err.message : String(err); process.stderr.write(`Error: ${msg}\n`); process.exit(1); });

其源码注释揭示了这条链路的底层机制：parseAsync(process.argv)返回的是引擎的 promise，随后通过“island → 静态 promise 桥”settle 出一个静态 promise；行内的.catch回调则是脱糖后的 typed-catch——拒绝的 async action 到达 handler 时，instanceof对桥接过来的 Error 做类型收窄，消息写入 stderr，进程退出 1。整条路径会穿越两个 promise 桥（action 的静态 promise 包装进引擎、commander 的结果 promise 桥接回来），与 Node 在相同 argv 夹具下做字节级对比。

argv 差分矩阵：npm-cases.ts

两份入口对应的命令行参数矩阵统一维护在 tests/harness/npm-cases.ts 中，并被抽成独立表，目的是让 Linux 容器内的测试车道与主车道运行完全相同的用例（相同入口、相同 argv 列表）。

commander-calc（入口 calc.ts）共 17 组 argv：

commander-calc-async（入口 calc-async.ts）共 4 组 argv：double 21（异步成功）、fail flat tire（拒绝被.catch捕获）、--help、boom（island 的process.exit路径，exit 1）。

差分契约：npm.test.ts 如何“以 Node 为 oracle”

tests/harness/npm.test.ts 是该夹具在--dynamic通道下的驱动方，其差分契约非常严格：每个夹具程序同时在 Node 下运行、以及作为 scriptc 编译出的原生二进制运行，要求 stdout字节级一致、退出码一致，并以 argv 扩展契约（CLI 包解析process.argv）。

实现上（npm.test.ts），每次构建以入口文件与夹具内所有node_modules源文件做 sha256 缓存键，随后调用compile(entry, { dynamic: true, ... })——故意不锁定 backend，让该套件跟随发布默认的 LLVM 通道，从而持续覆盖包解析、压缩源存储与 island/runtime 边界的生产面。运行侧则通过execFileAsync同时拉起node与原生二进制并逐字节比对（npm.test.ts中runBinary的实现）。值得留意的是 stdin 会立即关闭，这延续了差分测试的既有契约，避免打开管道导致两侧悬挂。

calc-npm-static.ts 与 version-npm-static.ts：--npm-static静态切片

与--dynamic相对，--npm-static是 scriptc 的实验性静态包通道（默认关闭，绝不改动无标志构建）。usage.ts 中的参数说明为：

--npm-static <pkg[,pkg…]|auto> compile the named npm packages' shipped JS statically as program modules (repeatable; "auto" opts in every eligible direct import: own .d.ts, unminified JS, no build-transform markers). A package preflight refuses falls back to the island (--dynamic) with a coverage-report note — opt-in, experimental

calc-npm-static.ts（tests/fixtures/commander-calc/calc-npm-static.ts）是该通道下的 commander 差分程序：包声明保留公共重载，而 scriptc 直接编译 commander 随包发布的 JavaScript 实现：

import { Command } from "commander"; const program = new Command(); program.name("calc"); const add = program.command("add <a> <b>"); add.description("add two numbers"); add.action((a: string, b: string) => { console.log(parseInt(a, 10) + parseInt(b, 10)); }); program.parse();

version-npm-static.ts（tests/fixtures/commander-calc/version-npm-static.ts）则覆盖 commander 的 getter/setter 形态（无参返回字符串、带参返回this的声明重载）：

import { Command } from "commander"; const program = new Command(); program.version("1.2.3"); console.log(program.version());

静态验收基线：npm-static.test.ts 中的 commander 切片

tests/harness/npm-static.test.ts 将 commander 描述为declaration-backed npm-static vertical slice（声明支撑的静态包纵切片）：包的声明文件保留重载与选定字段契约，而广泛的 JSDoc 实现辅助函数则从被触达的调用点做特化。针对calc-npm-static.ts的验收测试（npm-static.test.ts）设定了可量化的基线：

• npmStatic: ["commander"]显式点名后，覆盖报告显示status: "static"，preflight 未失败，诊断数为 0（可构建，fence 属于运行时行为）；
• 整包加入程序：总语句数（含未触达路径）> 1200；
• 静态覆盖门限：(total - failed) / total ≥ 0.95，且total - failed ≥ 1200；
• 运行 fence 上限：≤ 56，且禁止出现storing 'm5.Command' values、Command[] | Option[]的 map/forEach、target.parseArg等敏感消息；
• 差分运行：以add 20 22为 argv，Node 输出"42\n"，原生二进制与 Node 的 stdout、stderr、退出码逐字节一致。

version-npm-static.ts的对应测试（npm-static.test.ts）同样要求静态编译且与 Node 字节一致，覆盖 commander 计算选项监听器注册路径。同套件还以chainy迷你包印证了 commander getter/setter 形态的通用处理：安全声明组会投影为运行时类上的 JSDoc，函数体仍从 JS 编译，调用侧保留作者编写的声明表面。

版本管理与升级流程

由于node_modules是刻意提交的锁定测试数据，升级 commander 依赖有一套明确的流程（README 原文步骤）：

1. 进入 tests/fixtures/commander-calc 目录执行npm install --save-exact commander@<version>，将依赖精确锁定到目标版本；
2. 重新运行 harness 测试套件（npm.test.ts与npm-static.test.ts）；
3. 无需更新任何 golden 文件——因为 Node 始终是 oracle（基准），差分契约天然以 Node 的当前行为为准。

这一设计让版本升级的验收成本降到最低：只要 Node 侧行为不变、scriptc 侧字节一致，测试即通过；若 commander 新版本引入行为变化，差分结果会直接暴露差异，倒逼编译器或夹具跟进。

CLI 参数速查

两个参数正交：--dynamic决定是否内嵌动态引擎以运行 island；--npm-static决定哪些 npm 包脱离 island、以程序模块身份静态编译。preflight 拒绝的包会回退到 island 模式并附带覆盖报告注记——永远不构成构建失败，且该标志绝不改变无标志构建的行为。

小结

commander-calc夹具是理解 scriptc npm 依赖处理策略的最佳切片：calc.ts在--dynamic下检验 typed-callback 边界、选项记录转换、未观察拒绝与process.exit路径；calc-async.ts检验parseAsync的双向 promise 桥；calc-npm-static.ts与version-npm-static.ts在--npm-static下检验声明支撑的静态编译纵切片，并以 1200+ 语句、95% 覆盖、add 20 22 → 42字节一致的量化基线锚定静态前沿。全程以 Node 为 oracle 的差分契约，加上--save-exact锁定版本的升级流程，使得这套验收体系既真实又可持续维护。

• 编译器
• 语言运行时
• 开发工具
• CLI