euthyna 0.9.0 → 0.10.0

package/.agents/skills/euthyna/references/fact-producers.md

@@ -99,7 +99,7 @@ node <euthyna 仓库>/bin/euthyna.js history --base <改前版本> --no-origins
 ### 输出长什么样（真实捕获）
 
 ```
-euthyna euthyna-history — 被删除代码的来源归属与安全分类
+euthyna-history — 被删除代码的来源归属与安全分类
 目标: D:/axe-core/axe-core
 范围: 8390a5a9…..397f5fce…
 
@@ -243,7 +243,7 @@ node <euthyna 仓库>/bin/euthyna.js coverage `
 ### 输出长什么样（真实捕获，一次查询命中两种结果）
 
 ```
-euthyna euthyna-coverage — 符号调用计数（只能证伪）
+euthyna-coverage — 符号调用计数（只能证伪）
 
 已确证 (1)
   • 符号 cleanup 在本次测试运行中一次都没有被调用（调用计数为 0）

package/.agents/skills/euthyna-en/references/fact-producers.md

@@ -89,7 +89,7 @@ When the fork point is uncertain, use the result of `git merge-base <target bran
 ### What the output looks like (real capture)
 
 ```
-euthyna euthyna-history — attribution and security classification of deleted code
+euthyna-history — attribution and security classification of deleted code
 Target: D:/axe-core/axe-core
 Range: 8390a5a9…..397f5fce…
 
@@ -217,7 +217,7 @@ node <euthyna repo>/bin/euthyna.js coverage `
 ### What the output looks like (real capture; one query hitting both result kinds)
 
 ```
-euthyna euthyna-coverage — symbol invocation counts (can only falsify)
+euthyna-coverage — symbol invocation counts (can only falsify)
 
 Established (1)
   • Symbol cleanup was never invoked in this test run (invocation count 0) — any behavior depending on it was never exercised

package/README.md

@@ -213,6 +213,11 @@ removed and are now being added back. Origin tracing is on by default (deleted l
 are attributed to the commit that first introduced their content); `--no-origins`
 falls back to blame's last-modifier attribution, which is faster.
 
+Every command also takes `--out <file>`: the report goes to a UTF-8 (no BOM) file
+instead of stdout — the CI-friendly way to keep the artifact, and the exit code
+contract is unchanged. The PR-gate recipe in [docs/ci-integration.md](docs/ci-integration.md)
+uses it.
+
 `--graph` on `audit` or `history` draws what `history` already computed — the range, the commit
 that last modified each deleted line, and the commit that first introduced its content — as
 Mermaid source, renderable straight into a GitHub comment. It measures nothing new and never

package/__init__.py

@@ -2,7 +2,7 @@
 
 The CLI (``bin/euthyna.js``, installed by ``npm install -g euthyna``) produces
 the deterministic facts; this plugin registers ``/euthyna`` so a user can invoke
-the four CLI subcommands from inside a Hermes session without leaving chat. The
+the CLI's subcommands from inside a Hermes session without leaving chat. The
 handler shells out to the real CLI and returns its output verbatim — it does not
 reimplement any measurement, and it injects nothing into the conversation.
 
@@ -15,19 +15,27 @@ CLI prints comes back as the command result.
 import shutil
 import subprocess
 
-# Ponytail: one flat dict, not a command framework — there are exactly four
-# subcommands and the CLI already owns usage/exit codes.
+# The subcommands /euthyna reaches. This is the single source the guard in
+# test/hermes-plugin.test.js compares against the CLI's own dispatch, so a new
+# command there is red here until it is wired — which is how `audit` (the
+# entry point since 0.4.0) went seven releases unnoticed behind a hand-written
+# list of four.
+_FORWARDS = ("audit", "coverage", "deps", "gate", "help", "history")
+
 _USAGE = """euthyna slash command — usage:
 
+  /euthyna audit <path> [<path>...]            history + dependency surface in one run
   /euthyna history <path> [<path> <rev>...]   deleted-code provenance & security classification
   /euthyna coverage <path>                    symbol invocation counts from a coverage run
   /euthyna deps <path>                        dependency pinned versions from lockfiles
   /euthyna gate <report> [--verify]           validate an audit report against the six gates
+  /euthyna help                               the CLI's own usage, with every flag
 
 Args after the subcommand are passed to the CLI unchanged. Requires the CLI:
 npm install -g euthyna (Node >= 20)."""
 
 
+
 def _find_cli():
     """Return the absolute path of the euthyna CLI, or None if not installed."""
     for name in ("euthyna", "euthyna.cmd", "euthyna.exe"):
@@ -40,10 +48,13 @@ def _find_cli():
 def _run(raw_args: str):
     """Handle /euthyna: forward <subcommand> <args...> to the CLI, return its output."""
     argv = raw_args.split()
-    if not argv or argv[0] in ("help", "-h", "--help"):
+    # `-h`/`--help` print this command's own quick usage; bare `help` is forwarded
+    # so the flag list has exactly one owner — the CLI's help, which the skill and
+    # the docs both quote.
+    if not argv or argv[0] in ("-h", "--help"):
         return _USAGE
     sub, rest = argv[0], argv[1:]
-    if sub not in ("history", "coverage", "deps", "gate"):
+    if sub not in _FORWARDS:
         return f"unknown subcommand: {sub}\n\n{_USAGE}"
 
     cli = _find_cli()
@@ -73,8 +84,8 @@ def register(ctx):
     ctx.register_command(
         "euthyna",
         handler=_run,
-        description="euthyna security audit: run history/coverage/deps/gate fact producers",
-        args_hint="<history|coverage|deps|gate> <args…>",
+        description="euthyna security audit: drive the fact-producing CLI (audit is the single entry point)",
+        args_hint="<audit|history|coverage|deps|gate|help> <args…>",
     )
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "euthyna",
-  "version": "0.9.0",
-  "description": "Deterministic fact producers for security auditing: which deleted code came from a security fix, and which changed symbols no test ever executed.",
+  "version": "0.10.0",
+  "description": "Audit framework for AI coding agents: produces the deterministic facts a model cannot compute — deleted-code provenance, symbol invocations, dependency pins — and adjudicates every claim against six gates, downgrading what cannot produce evidence to an observation. Not a scanner.",
   "type": "module",
   "main": "./plugin/index.js",
   "bin": {

package/plugin.yaml

@@ -1,6 +1,6 @@
 name: euthyna
-version: 0.9.0
-description: euthyna audit discipline — slash commands that drive the euthyna fact-producing CLI (history / coverage / deps / gate)
+version: 0.10.0
+description: euthyna audit discipline — the /euthyna slash command driving the euthyna CLI, whose single entry point is `euthyna audit`
 license: Apache-2.0
 homepage: https://github.com/slow-stack/euthyna
 tags:

package/src/cli.js

@@ -15,7 +15,7 @@
  */
 import process from 'node:process';
 import path from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { collectHistoryFacts } from './facts/history.js';
 import { collectCoverageFacts } from './facts/coverage.js';
 import { collectDependencyFacts, listDependencies, detectManifest, manifestTypeForFile } from './facts/deps.js';
@@ -72,14 +72,19 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
 它不是扫描器。它只回答两个模型算不准的问题，并把答案写成带证据的事实。
 
 用法:
-  euthyna audit    [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
-  euthyna history  [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
-  euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--source <dir>] [--json]
-  euthyna deps     [--repo <dir>] [--lockfile <file>] (--dep <name> | --all) [--json]
-  euthyna gate     <报告文件> [--verify] [--cwd <dir>] [--json]
+  euthyna audit    [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph] [--out <file>]
+  euthyna history  [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph] [--out <file>]
+  euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--source <dir>] [--json] [--out <file>]
+  euthyna deps     [--repo <dir>] [--lockfile <file>] (--dep <name> | --all) [--json] [--out <file>]
+  euthyna gate     <报告文件> [--verify] [--cwd <dir>] [--json] [--out <file>]
 
 语言: 默认中文。加 --lang en 或设环境变量 EUTHYNA_LANG=en 切换英文输出。
 
+全局选项:
+  --out <file>  把本次输出写入文件而非 stdout（内容随 --json / --graph 切换）。
+                恒为 UTF-8 无 BOM；写失败按用法错误退出（1），即使测量本身成功；
+                写入后 stderr 提示一行目标路径
+
 命令:
   audit      一次跑完变更面审计：history + deps（枚举 lockfile 全部依赖），合并报告
              这是技能文档默认推荐入口；coverage 因需要覆盖率文件和符号名不在其中
@@ -131,15 +136,21 @@ It is not a scanner. It answers only the two questions a model cannot compute
 reliably, and writes the answers as facts with evidence.
 
 Usage:
-  euthyna audit    [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
-  euthyna history  [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph]
-  euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--source <dir>] [--json]
-  euthyna deps     [--repo <dir>] [--lockfile <file>] (--dep <name> | --all) [--json]
-  euthyna gate     <report file> [--verify] [--cwd <dir>] [--json]
+  euthyna audit    [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph] [--out <file>]
+  euthyna history  [--base <rev>] [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json] [--graph] [--out <file>]
+  euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--source <dir>] [--json] [--out <file>]
+  euthyna deps     [--repo <dir>] [--lockfile <file>] (--dep <name> | --all) [--json] [--out <file>]
+  euthyna gate     <report file> [--verify] [--cwd <dir>] [--json] [--out <file>]
 
 Language: Chinese by default. Pass --lang en or set the environment variable
 EUTHYNA_LANG=en for English output.
 
+Global options:
+  --out <file>  write this run's output to a file instead of stdout (the content
+                follows --json / --graph). Always UTF-8 without a BOM; a write
+                failure exits 1 even when the measurement itself succeeded;
+                stderr carries one line naming the target path
+
 Commands:
   audit      the change-surface audit in one run: history + deps (every lockfile
              dependency enumerated), one merged report. The default entry point
@@ -245,6 +256,24 @@ function asArray(value) {
   return Array.isArray(value) ? value : [value];
 }
 
+/**
+ * Write the `--out` artifact. Returns null on success, or a short failure
+ * reason the caller wraps in a localized usage error.
+ *
+ * UTF-8 without a BOM, deliberately: a shell redirect is how this used to be
+ * done, and this project's own record has PowerShell `>` writing UTF-16 and
+ * a BOM breaking `gh api --input` JSON — the file written here must be
+ * byte-clean for whatever reads it next.
+ */
+async function writeOutFile(outPath, content) {
+  try {
+    await writeFile(outPath, content, 'utf8');
+    return null;
+  } catch (error) {
+    return `${error.code ?? error.message}: ${outPath}`;
+  }
+}
+
 async function runHistory(flags, lang) {
   const t = T(lang);
   const cwd = path.resolve(flags.repo ? String(flags.repo) : process.cwd());
@@ -761,6 +790,26 @@ async function runGate(flags, positional, lang) {
     };
   }
 
+  // --out for gate's rendered channel: gate renders internally, so the file
+  // decision happens here rather than in main(). The --json channel returns a
+  // result.json and main() writes it out.
+  if (flags.out !== undefined) {
+    const outPath = path.resolve(String(flags.out));
+    const lines = [];
+    renderGateReport(result, { write: (line) => lines.push(line), lang });
+    const failure = await writeOutFile(outPath, `${lines.join('\n')}\n`);
+    if (failure) {
+      return {
+        exit: EXIT.USAGE,
+        error: t(`无法写入 --out 目标 ${failure}`, `cannot write the --out target ${failure}`)
+      };
+    }
+    process.stderr.write(
+      safeTextLines(t(`输出已写入 ${outPath}`, `output written to ${outPath}`) + '\n')
+    );
+    return { exit: downgraded > 0 ? EXIT.FLAGGED : EXIT.CLEAN, report: null };
+  }
+
   renderGateReport(result, { lang });
   return { exit: downgraded > 0 ? EXIT.FLAGGED : EXIT.CLEAN, report: null };
 }
@@ -800,6 +849,18 @@ export async function main(argv = process.argv.slice(2)) {
     return EXIT.USAGE;
   }
 
+  // A bare `--out` records `true`, a repeated one accumulates into an array,
+  // and an empty string cannot name a file. Writing a file literally named
+  // "true" or "a,b" would be a silent trap, so all three are caller mistakes.
+  if (flags.out === true || flags.out === '' || Array.isArray(flags.out)) {
+    process.stderr.write(
+      safeTextLines(
+        t('--out 需要且只需要一个文件路径', '--out requires exactly one file path') + '\n'
+      )
+    );
+    return EXIT.USAGE;
+  }
+
   if (!command || command === 'help' || flags.help) {
     process.stdout.write(helpText(lang));
     return EXIT.CLEAN;
@@ -841,6 +902,42 @@ export async function main(argv = process.argv.slice(2)) {
     return result.exit;
   }
 
+  // --out: the artifact a run would have printed goes to a file instead, and
+  // stdout stays silent for it. The exit code stays the measurement's — a
+  // flagged run that was written out must still exit 10 — except when the file
+  // could not be written: a caller who asked for an artifact and did not get
+  // one must not read the run as complete, so that is a usage error.
+  if (flags.out !== undefined) {
+    const outPath = path.resolve(String(flags.out));
+    let content = null;
+    if (result.json) {
+      content = `${result.json}\n`;
+    } else if (flags.json && result.report) {
+      content = `${JSON.stringify(result.report, null, 2)}\n`;
+    } else if (flags.graph && result.report) {
+      content = `${safeTextLines(provenanceGraph(result.report))}\n`;
+    } else if (result.report) {
+      // renderReport applies the render boundary (safeText) per line before it
+      // calls write, so the collected lines are byte-identical to stdout.
+      const lines = [];
+      renderReport(result.report, { write: (line) => lines.push(line), lang });
+      content = `${lines.join('\n')}\n`;
+    }
+    if (content !== null) {
+      const failure = await writeOutFile(outPath, content);
+      if (failure) {
+        process.stderr.write(
+          safeTextLines(t(`无法写入 --out 目标 ${failure}`, `cannot write the --out target ${failure}`) + '\n')
+        );
+        return EXIT.USAGE;
+      }
+      process.stderr.write(
+        safeTextLines(t(`输出已写入 ${outPath}`, `output written to ${outPath}`) + '\n')
+      );
+      return result.exit;
+    }
+  }
+
   if (result.json) {
     process.stdout.write(`${result.json}\n`);
     return result.exit;

package/src/contract.js

@@ -203,7 +203,10 @@ export function renderReport(report, { write: rawWrite = console.log, lang = DEF
   const unknown = facts.filter(f => f.status === STATUS.UNKNOWN);
 
   write('');
-  write(`euthyna ${producer.name} — ${producer.purpose || ''}`.trim());
+  // The producer name is `euthyna-history`, `euthyna-audit`, …: it already names
+  // the tool, so the header prints it as the contract emits it — the same string
+  // the `--json` `producer` field carries.
+  write(`${producer.name} — ${producer.purpose || ''}`.trim());
   write(`${t('目标: ', 'Target: ')}${subject.repo ?? subject.coverageFile ?? t('(未指定)', '(unspecified)')}`);
   if (subject.base || subject.head) {
     write(

package/src/facts/deps.js

@@ -16,8 +16,8 @@
  *   - package-lock.json  (npm v1/v2/v3)
  *   - Cargo.lock         (Rust)
  *   - go.mod             (Go; the DECLARED requirement version, not the resolved one —
- *                         go.sum has no versions, so this producer says "declared",
- *                         never "locked", for Go)
+ *                         go.sum records version-hash pairs but not the selected build
+ *                         list, so this producer says "declared", never "locked", for Go)
  * Anything else found at auto-detect (pnpm/yarn/poetry/...) is reported as
  * notEvaluated with the filenames named, rather than guessed at.
  */
@@ -44,19 +44,38 @@ const UNSUPPORTED = [
   'bun.lock'
 ];
 
-/** 1-indexed line of the first line containing `needle`, or null. */
-function lineOf(text, needle) {
-  return lineOfAt(text, text.indexOf(needle));
+/**
+ * A line-number lookup over a fixed text: newline offsets collected once,
+ * queried by binary search.
+ *
+ * It answers exactly what counting the newlines before an index answers — the
+ * table just does not re-count. That matters on the whole-manifest path: the
+ * prefix walk was O(prefix) per evidence lookup, and with every dependency in
+ * the manifest queried (`euthyna audit`), the whole run compounded
+ * quadratically (bench/perf-deps.js measured the per-dependency cost doubling
+ * with each doubling of the manifest). Build once per file, query per hit.
+ */
+function makeLineTable(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return (index) => {
+    if (index < 0 || index >= text.length) return null;
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid] <= index) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
 }
 
-/** 1-indexed line of the absolute text index, or null when it is not found. */
-function lineOfAt(text, index) {
-  if (index < 0) return null;
-  let line = 1;
-  for (let i = 0; i < index; i++) {
-    if (text[i] === '\n') line++;
-  }
-  return line;
+/** 1-indexed line of the first line containing `needle`, or null when absent. */
+function lineOf(text, needle, lineAt) {
+  return lineAt(text.indexOf(needle));
 }
 
 /**
@@ -65,33 +84,53 @@ function lineOfAt(text, index) {
  * v2/v3: `packages` maps "node_modules/<name>" (possibly nested, and possibly
  * scoped "@scope/name") to metadata; the package name is the path segment after
  * the last "node_modules/". v1: a recursive `dependencies` tree.
+ *
+ * Called once per queried dependency — and `euthyna audit` queries every
+ * dependency — so the name→entries indexes are built once per file and the
+ * per-dep work is a Map lookup, not a rescan of every key.
  */
-function resolveNpm(root, dep, text) {
-  const found = [];
+function makeNpmResolver(root, text, lineAt) {
+  const found = (dep) => {
+    const hits = [];
+    for (const { version, key } of byKey.get(dep) ?? []) {
+      hits.push({ version, location: key, line: lineOf(text, `"${key}":`, lineAt) });
+    }
+    for (const version of byName.get(dep) ?? []) {
+      // Anchor at this dep's own block: a same-version string earlier in the
+      // file (some other package) must not hijack the evidence pointer.
+      const blockAt = text.indexOf(`"${dep}":`);
+      const verAt = blockAt < 0 ? -1 : text.indexOf(`"version": "${version}"`, blockAt);
+      hits.push({
+        version,
+        location: `dependencies.${dep}`,
+        line: lineAt(verAt)
+      });
+    }
+    return hits;
+  };
 
+  const byKey = new Map();
   if (root.packages && typeof root.packages === 'object') {
     for (const [key, meta] of Object.entries(root.packages)) {
       if (!key.includes('node_modules/')) continue;
       if (!meta || typeof meta !== 'object' || !meta.version) continue;
-      if (key.split('node_modules/').pop() !== dep) continue;
-      found.push({ version: meta.version, location: key, line: lineOf(text, `"${key}":`) });
+      const name = key.split('node_modules/').pop();
+      if (!name) continue;
+      const list = byKey.get(name) ?? [];
+      list.push({ version: meta.version, key });
+      byKey.set(name, list);
     }
   }
 
+  const byName = new Map();
   if (root.dependencies && typeof root.dependencies === 'object') {
     const walk = (tree) => {
       for (const [name, meta] of Object.entries(tree)) {
         if (!meta || typeof meta !== 'object') continue;
-        if (name === dep && meta.version) {
-          // Anchor at this dep's own block: a same-version string earlier in the
-          // file (some other package) must not hijack the evidence pointer.
-          const blockAt = text.indexOf(`"${name}":`);
-          const verAt = blockAt < 0 ? -1 : text.indexOf(`"version": "${meta.version}"`, blockAt);
-          found.push({
-            version: meta.version,
-            location: `dependencies.${name}`,
-            line: lineOfAt(text, verAt)
-          });
+        if (meta.version) {
+          const list = byName.get(name) ?? [];
+          list.push(meta.version);
+          byName.set(name, list);
         }
         if (meta.dependencies && typeof meta.dependencies === 'object') walk(meta.dependencies);
       }
@@ -102,25 +141,39 @@ function resolveNpm(root, dep, text) {
   return found;
 }
 
-/** Cargo.lock: [[package]] blocks with `name = "..."` and `version = "..."`. */
-function resolveCargo(text, dep) {
-  const found = [];
+/**
+ * Cargo.lock: [[package]] blocks with `name = "..."` and `version = "..."`.
+ * Blocks are parsed once per file (per-dep splits of the whole text were the
+ * measured quadratic term on this format, bench/perf-deps.js).
+ */
+function makeCargoResolver(text, lineAt) {
+  const byName = new Map();
   for (const block of text.split('[[package]]')) {
     const name = /^\s*name\s*=\s*"([^"]+)"/m.exec(block);
     const version = /^\s*version\s*=\s*"([^"]+)"/m.exec(block);
-    if (!name || !version || name[1] !== dep) continue;
+    if (!name || !version) continue;
+    const list = byName.get(name[1]) ?? [];
+    list.push(version[1]);
+    byName.set(name[1], list);
+  }
+
+  return (dep) => {
+    const versions = byName.get(dep);
+    if (!versions) return [];
     // Package names are unique in a Cargo.lock, so anchoring the version line
     // at this dep's own name block keeps the pointer on this crate even when a
     // different crate earlier in the file pins the same version string.
     const nameAt = text.indexOf(`name = "${dep}"`);
-    const verAt = nameAt < 0 ? -1 : text.indexOf(`version = "${version[1]}"`, nameAt);
-    found.push({
-      version: version[1],
-      location: `[[package]] ${dep}`,
-      line: lineOfAt(text, verAt)
+    if (nameAt < 0) return [];
+    return versions.map((version) => {
+      const verAt = text.indexOf(`version = "${version}"`, nameAt);
+      return {
+        version,
+        location: `[[package]] ${dep}`,
+        line: lineAt(verAt)
+      };
     });
-  }
-  return found;
+  };
 }
 
 /** go.mod require lines, single or inside a require (...) block. */
@@ -152,6 +205,7 @@ function resolveGo(text, dep) {
  */
 function makeResolver(type, text, lang = DEFAULT_LANG) {
   const t = T(lang);
+  const lineAt = makeLineTable(text);
   if (type === 'npm') {
     const root = JSON.parse(text); // throws on malformed JSON
     // A syntactically valid but structurally empty file (e.g. `{}`) is not a
@@ -169,7 +223,7 @@ function makeResolver(type, text, lang = DEFAULT_LANG) {
         )
       );
     }
-    return (dep) => resolveNpm(root, dep, text);
+    return makeNpmResolver(root, text, lineAt);
   }
   if (type === 'cargo') {
     if (!/\[\[package\]\]|^version\s*=/m.test(text)) {
@@ -180,7 +234,7 @@ function makeResolver(type, text, lang = DEFAULT_LANG) {
         )
       );
     }
-    return (dep) => resolveCargo(text, dep);
+    return makeCargoResolver(text, lineAt);
   }
   if (type === 'go') {
     if (!/^module\s+\S+/m.test(text)) {

package/src/facts/history.js

@@ -53,6 +53,39 @@ export function parseDeletedRanges(diffText) {
   return ranges;
 }
 
+/**
+ * Sort by start and merge overlapping or adjacent ranges.
+ *
+ * `parseDeletedRanges` already yields disjoint ranges, so well-formed input
+ * comes back unchanged; the merge exists because an overlap would double-count
+ * the shared lines across two `-L` flags, and because merging neighbours keeps
+ * a batch's argv small.
+ */
+export function mergeRanges(ranges) {
+  const sorted = [...ranges].sort((a, b) => a.start - b.start || a.count - b.count);
+  const merged = [];
+  for (const range of sorted) {
+    const end = range.start + range.count - 1;
+    const last = merged[merged.length - 1];
+    const lastEnd = last ? last.start + last.count - 1 : -Infinity;
+    if (last && range.start <= lastEnd + 1) {
+      last.count = Math.max(lastEnd, end) - last.start + 1;
+    } else {
+      merged.push({ start: range.start, count: range.count });
+    }
+  }
+  return merged;
+}
+
+/**
+ * Ranges blamed per `git blame` process. One process carries one `-L` flag per
+ * range, so the batch size is the process-count divider; 400 keeps the argv
+ * (≈14 bytes per flag) far under every platform's command-line limit while
+ * cutting the per-range process cost by that factor (baseline: bench/perf.js,
+ * measured ~48 ms per deleted range when each range was its own process).
+ */
+const BLAME_BATCH = 400;
+
 /**
  * Attribute every line in `ranges` to the commit that last touched it, as of `rev`.
  *
@@ -60,28 +93,28 @@ export function parseDeletedRanges(diffText) {
  * numbers rather than a bare count, because the fact has to carry a command a
  * reader can actually paste: `git blame -L 104,104` reproduces the claim, while
  * `git blame -L <deleted-range>` is a placeholder, not evidence.
+ *
+ * The multi-`-L` invocation is the same form the emitted reproduce commands
+ * already rely on (`git blame --porcelain -L a,b -L c,d <base> -- <file>`), so
+ * batching adds no new assumption about git — it only stops paying process
+ * startup per range. A batch git refuses (a range past EOF, a binary file) is
+ * retried range by range, so one bad range costs itself and not its neighbours.
  */
 export async function blameRanges({ cwd, rev, file, ranges }) {
   const byCommit = new Map();
-  // ponytail: 顺序 blame，每个区间一次 git 进程，耗时与删除区间数线性相关
-  // （基准见 bench/perf.js）。若吞吐不满足要求：改成每文件一次 blame 覆盖
-  // 全部区间，或对单行区间做有界并发。
-  for (const range of ranges) {
-    const end = range.start + range.count - 1;
-    const out = await git(
-      ['blame', '--porcelain', '-L', `${range.start},${end}`, rev, '--', file],
-      { cwd, allowFailure: true }
-    );
-    if (!out) continue;
 
+  // Porcelain emits `<sha> <origLine> <finalLine> [<groupSize>]`. `origLine`
+  // is the line number in the commit that introduced the line, which is NOT
+  // where the line sits in the revision being blamed; `finalLine` is. Using
+  // the wrong one produces a command that looks right and blames other lines.
+  const parse = (out) => {
     let current = null;
-    // Porcelain emits `<sha> <origLine> <finalLine> [<groupSize>]`. `origLine`
-    // is the line number in the commit that introduced the line, which is NOT
-    // where the line sits in the revision being blamed; `finalLine` is. Using
-    // the wrong one produces a command that looks right and blames other lines.
     let lineNumber = null;
     for (const raw of out.split('\n')) {
-      const header = /^([0-9a-f]{40}) (\d+) (\d+)(?: (\d+))?$/.exec(raw);
+      // The object id is 40 hex (sha1) or 64 hex (sha256) — a repository picks
+      // its own format, and the attribution must survive either. Same split as
+      // mergeBase() in git.js.
+      const header = /^([0-9a-f]{40}|[0-9a-f]{64}) (\d+) (\d+)(?: (\d+))?$/.exec(raw);
       if (header) {
         current = header[1];
         lineNumber = Number(header[3]);
@@ -94,6 +127,29 @@ export async function blameRanges({ cwd, rev, file, ranges }) {
         lineNumber++;
       }
     }
+  };
+
+  const blame = (batch) =>
+    git(
+      // Ranges are {start, count}: the -L end is start+count-1, computed here.
+      // A `${r.end}` on a count-shaped range would hand git "undefined" and the
+      // swallowed failure would read as "no attribution" downstream.
+      ['blame', '--porcelain', ...batch.flatMap((r) => ['-L', `${r.start},${r.start + r.count - 1}`]), rev, '--', file],
+      { cwd, allowFailure: true }
+    );
+
+  const merged = mergeRanges(ranges);
+  for (let i = 0; i < merged.length; i += BLAME_BATCH) {
+    const batch = merged.slice(i, i + BLAME_BATCH);
+    const out = await blame(batch);
+    if (out) {
+      parse(out);
+      continue;
+    }
+    for (const range of batch) {
+      const single = await blame([range]);
+      if (single) parse(single);
+    }
   }
   return byCommit;
 }