perf: batch the blame, index the deps manifests, and add --out

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

bench/perf-deps.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * Scaling benchmark for the `deps` producer's whole-manifest path.
+ *
+ * `euthyna audit` queries EVERY dependency the manifest names (the `--all`
+ * shape). The per-dep resolvers re-scan the manifest text for each dependency —
+ * `resolveNpm` iterates every `packages` key per dep, `resolveCargo` splits the
+ * whole file per dep, and each evidence line lookup walks the text prefix — so
+ * the whole-manifest cost may grow faster than the manifest itself. This script
+ * measures exactly that shape at increasing sizes, so a change to indexing has
+ * a baseline to be judged against, and a reader can see at a glance whether the
+ * per-dependency cost is flat or compounding.
+ *
+ * The manifests are synthetic but shape-real: npm v3 with scoped and unscoped
+ * names, Cargo.lock with [[package]] blocks. Absolute numbers are
+ * machine-dependent; the per-dependency ratio is the number that matters.
+ *
+ *   node bench/perf-deps.js [--npm-sizes 500,1000,2000,4000] [--cargo-sizes 500,1000,2000]
+ *
+ * 索引化之前实测（本机）：npm 每依赖 0.46 → 0.92 → 1.81 → 3.75 ms（清单每翻倍
+ * 翻一倍，O(n²) 形状），cargo 0.27 → 0.91 ms/依赖 同形。
+ * 索引化之后实测（同机）：npm 0.04 → 0.09 ms/依赖，cargo 恒定 ~0.05 —— 4000 依赖
+ * 从 15.0s 降到 0.36s。npm 残留的轻微超线性来自每个命中一次的原生 indexOf 证据
+ * 锚定（O(文件) 但字节速度），绝对值已不构成实际天花板。
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const args = process.argv.slice(2);
+const opt = (name, fallback) => {
+  const i = args.indexOf(name);
+  return i === -1 ? fallback : args[i + 1];
+};
+const parseSizes = (raw) =>
+  String(raw)
+    .split(',')
+    .map(Number);
+const NPM_SIZES = parseSizes(opt('--npm-sizes', '500,1000,2000,4000'));
+const CARGO_SIZES = parseSizes(opt('--cargo-sizes', '500,1000,2000'));
+
+function npmLockfile(n) {
+  const packages = {
+    '': { name: 'fixture', version: '1.0.0', dependencies: {} }
+  };
+  for (let i = 0; i < n; i++) {
+    // Scoped names every seventh package: resolveNpm must handle both, and the
+    // nested-scope key form is what makes its split-by-node_modules non-trivial.
+    const name = i % 7 === 0 ? `@scope/pkg-${i}` : `pkg-${i}`;
+    packages[`node_modules/${name}`] = {
+      version: `${(i % 20) + 1}.${i % 9}.${i % 5}`,
+      resolved: `https://registry.example/${name}/-/${name}.tgz`,
+      integrity: `sha512-${'a'.repeat(40)}`
+    };
+  }
+  return JSON.stringify({ name: 'fixture', lockfileVersion: 3, packages }, null, 2);
+}
+
+function cargoLockfile(n) {
+  let text = '# This file is automatically @generated by Cargo.\nversion = 3\n\n';
+  for (let i = 0; i < n; i++) {
+    text += `[[package]]\nname = "crate-${i}"\nversion = "1.${i % 10}.${i % 7}"\nsource = "registry+https://github.com/rust-lang/crates.io-index"\nchecksum = "${'b'.repeat(40)}"\n\n`;
+  }
+  return text;
+}
+
+async function measure(label, file, type, text, size) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'euthyna-deps-perf-'));
+  fs.writeFileSync(path.join(dir, file), text);
+  try {
+    const { listDependencies, collectDependencyFacts } = await import('../src/facts/deps.js');
+    const names = listDependencies(type, text);
+    const start = process.hrtime.bigint();
+    const { measured } = await collectDependencyFacts({ cwd: dir, deps: names });
+    const ms = Number(process.hrtime.bigint() - start) / 1e6;
+    if (!measured) throw new Error(`${label} ${size}: the producer could not measure its own fixture`);
+    process.stdout.write(
+      `  ${String(size).padStart(6)} 依赖  ${ms.toFixed(0).padStart(7)} ms  (${(ms / size).toFixed(2)} ms/依赖, 清单 ${(text.length / 1024 / 1024).toFixed(1)} MB)\n`
+    );
+    return ms / size;
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  if (!NPM_SIZES.every(Number.isFinite) || !CARGO_SIZES.every(Number.isFinite)) {
+    throw new Error('--npm-sizes/--cargo-sizes 必须是逗号分隔的整数');
+  }
+
+  const results = [];
+  for (const size of NPM_SIZES) {
+    const ratio = await measure('npm', 'package-lock.json', 'npm', npmLockfile(size), size);
+    results.push({ kind: 'npm', size, ratio });
+  }
+  for (const size of CARGO_SIZES) {
+    const ratio = await measure('cargo', 'Cargo.lock', 'cargo', cargoLockfile(size), size);
+    results.push({ kind: 'cargo', size, ratio });
+  }
+
+  for (const kind of ['npm', 'cargo']) {
+    const rows = results.filter((r) => r.kind === kind);
+    if (rows.length < 2) continue;
+    const spread = Math.max(...rows.map((r) => r.ratio)) / Math.min(...rows.map((r) => r.ratio));
+    const first = rows[0];
+    const last = rows[rows.length - 1];
+    console.log(`\n结论 (${kind}):`);
+    if (last.ratio > first.ratio * 2) {
+      console.log(
+        '  每依赖成本在随清单变大 —— 超线性。若绝对值回到秒级，' +
+          '先查每依赖是否又在重扫全文（name→条目索引是否还在），' +
+          '以及证据行锚定的 indexOf 是否回到了逐字符的前缀遍历。'
+      );
+    } else if (last.ratio < first.ratio * 0.5) {
+      console.log('  每依赖成本在变小 —— 次线性，固定开销在小规模档位里占比较高。');
+    } else {
+      console.log('  每依赖成本基本恒定 —— 线性缩放，当前形状没有明显天花板。');
+    }
+  }
+  console.log('  绝对数值依赖机器；横向比较 ms/依赖 而非 ms。');
+}
+
+main().catch((error) => {
+  console.error(`bench/perf-deps.js: ${error.message}`);
+  process.exitCode = 1;
+});

bench/perf.js

@@ -3,24 +3,24 @@
 /**
  * Scaling benchmark for the `history` producer.
  *
- * The producer blames each deleted range sequentially
- * (`src/facts/history.js`: one `git blame` per range), so its cost grows with
- * the number of deleted ranges. This script builds synthetic repositories and
- * measures the producer at increasing deletion sizes, so a change to batching
- * or parallelization has a baseline to be judged against — and a reader can see
- * at a glance whether the current shape is linear.
+ * The producer blames deleted ranges in batches (`src/facts/history.js`: one
+ * `git blame` process per ~400 ranges, one `-L` flag per range). This script
+ * builds synthetic repositories and measures the producer at increasing
+ * deletion sizes, so a change to the batching has a baseline to be judged
+ * against — and a reader can see at a glance how the shape moves.
  *
  * The deleted lines are interleaved (every other line in a region), which
- * produces one single-line range per deletion — the worst case for a sequential
- * blamer. The file size is held fixed while the deletion count grows, so the
- * ms/deleted-line ratio isolates the sequential per-range cost from the
- * (separate) cost of blaming a bigger file. Absolute numbers are
- * machine-dependent; the ratio is the number that matters.
+ * produces one single-line range per deletion — the case that used to cost one
+ * process per range (measured ~48 ms/行 linear on this machine, 2000 ranges
+ * ≈ 97 s) and now costs one process per 400. The file size is held fixed while
+ * the deletion count grows. Absolute numbers are machine-dependent; the ratio
+ * is the number that matters.
  *
  *   node bench/perf.js [--total 12000] [--min 250] [--max 4000] [--steps 5]
  *
- * 默认档实测 4000 个删除区间约 80s（~21ms/区间，线性）；全程 5 档 + 造仓约
- * 2-3 分钟。要快速看曲线就调小 --max/--total。
+ * 分批后实测（--total 8000 --max 2000 --steps 4）：2000 个删除区间约 3.7s
+ * （~1.9ms/行，次线性）。默认全程 5 档 + 造仓约 2-3 分钟（估算，未逐档实测）。
+ * 要快速看曲线就调小 --max/--total。
  */
 
 const fs = require('node:fs');
@@ -134,10 +134,9 @@ async function main() {
   } else if (spread < 1.5) {
     const biggest = rows[rows.length - 1];
     console.log(
-      '  每删除行的耗时基本恒定 —— 确认是顺序 blame 的线性缩放。' +
-        `实测 ${biggest.deletedLines} 个删除区间约 ${(biggest.ms / 1000).toFixed(1)}s，` +
-        '即真实 PR 里删几千个分散行会达到分钟级——这是当前实现的实际天花板。' +
-        '升级路径: 按文件批量 blame、或对单行区间做并发。'
+      '  每删除行的耗时基本恒定 —— 线性缩放。' +
+        `实测 ${biggest.deletedLines} 个删除区间约 ${(biggest.ms / 1000).toFixed(1)}s。` +
+        '若回到分钟级，先查 blame 是否退化成了每区间一个进程。'
     );
   } else if (ratios[ratios.length - 1] > ratios[0]) {
     console.log(

docs/ci-integration-zh.md

@@ -87,15 +87,13 @@ GitHub 把任何非零退出当作步骤失败，所以 `0` 显示绿，`10`、`
 
 ## 把报告挂到 PR 上
 
-运行会把人类可读的报告打进步骤日志。要作为附件挂到 PR 上：
+运行会把人类可读的报告打进步骤日志。要作为附件挂到 PR 上，用 `--out` 直接写文件——
+不用重定向、不用 `tee`、也没有 `pipefail` 的坑：artifact 直达文件，步骤状态仍是
+audit 自己的。
 
 ```yaml
       - name: 变更面审计
-        run: |
-          set -o pipefail
-          npx --yes euthyna@latest audit --base "origin/${{ github.base_ref }}" --head HEAD \
-            | tee audit-report.txt
-        continue-on-error: true
+        run: npx --yes euthyna@latest audit --base "origin/${{ github.base_ref }}" --head HEAD --out audit-report.txt
         id: audit
       - uses: actions/upload-artifact@v4
         if: always()
@@ -104,12 +102,12 @@ GitHub 把任何非零退出当作步骤失败，所以 `0` 显示绿，`10`、`
           path: audit-report.txt
 ```
 
-没有 `pipefail` 时，步骤的状态是 `tee` 的（永远 0），audit 的 `1`/`2`/`10` 会被吞掉、
-门禁假绿。Actions 的默认 shell 是 `bash -e`，**不**隐含 `pipefail`，所以要显式写
-`set -o pipefail`。
+`--out` 以 UTF-8 无 BOM 写入，退出码契约不变：被标记的运行仍然退出 `10`，文件写不进去
+则退出 `1`，不会被读成一次干净的运行。Linux runner 上 shell 重定向（`> audit-report.txt`）
+也可用，但 Windows PowerShell 的 `>` 写的是 UTF-16——`--out` 把这一类问题整个移掉了。
 
-下游消费方（评论机器人、裁定 agent）要读 fact 而不是散文时，加 `--json` 并把 artifact
-指向 JSON 文件。
+下游消费方（评论机器人、裁定 agent）要读 fact 而不是散文时，加 `--json --out report.json`
+并把 artifact 指向 JSON 文件。
 
 ## 这个门禁回答什么、不回答什么
 

docs/ci-integration.md

@@ -92,15 +92,13 @@ is the honest gate. Use the two-step form only when `10` must not block merges.
 
 ## Reading the report in the PR
 
-The run prints the human-readable report to the step log. To attach it to the PR instead:
+The run prints the human-readable report to the step log. To attach it to the PR instead,
+write it to a file with `--out` — no redirect, no `tee`, and no `pipefail` subtlety: the
+artifact goes straight to the file and the step's status is still the audit's own.
 
 ```yaml
       - name: Change-surface audit
-        run: |
-          set -o pipefail
-          npx --yes euthyna@latest audit --base "origin/${{ github.base_ref }}" --head HEAD \
-            | tee audit-report.txt
-        continue-on-error: true
+        run: npx --yes euthyna@latest audit --base "origin/${{ github.base_ref }}" --head HEAD --out audit-report.txt
         id: audit
       - uses: actions/upload-artifact@v4
         if: always()
@@ -109,12 +107,13 @@ The run prints the human-readable report to the step log. To attach it to the PR
           path: audit-report.txt
 ```
 
-Without `pipefail`, the step's status is `tee`'s (always 0), so a `1`/`2`/`10` from the
-audit would turn the gate green. Actions' default shell is `bash -e`, which does **not**
-imply `pipefail`, hence the explicit `set -o pipefail` line.
+`--out` writes UTF-8 without a BOM and keeps the exit code contract: a flagged run still
+exits `10`, and a file that could not be written exits `1` rather than reading as a clean
+run. A shell redirect (`> audit-report.txt`) also works on a Linux runner, but `>` writes
+UTF-16 in Windows PowerShell — `--out` removes that class of problem entirely.
 
-Add `--json` and point the artifact at the JSON file when a downstream consumer (a comment bot,
-an adjudicator agent) should read facts rather than prose.
+Add `--json --out report.json` and point the artifact at the JSON file when a downstream
+consumer (a comment bot, an adjudicator agent) should read facts rather than prose.
 
 ## What the gate does and does not answer