euthyna 0.7.0 → 0.9.0

package/src/cli.js

@@ -21,7 +21,8 @@ import { collectCoverageFacts } from './facts/coverage.js';
 import { collectDependencyFacts, listDependencies, detectManifest, manifestTypeForFile } from './facts/deps.js';
 import { parseGateReport, validateFindings, verifyFinding, renderGateReport } from './gate.js';
 import { makeReport, renderReport, safeTextLines, KIND } from './contract.js';
-import { repoToplevel, revParse, git } from './git.js';
+import { provenanceGraph } from './graph.js';
+import { repoToplevel, revParse, mergeBase, git } from './git.js';
 import { resolveLang, T, isLang, DEFAULT_LANG } from './lang.js';
 
 export const EXIT = Object.freeze({
@@ -71,8 +72,8 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
 它不是扫描器。它只回答两个模型算不准的问题，并把答案写成带证据的事实。
 
 用法:
-  euthyna audit    --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
-  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
+  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]
@@ -83,17 +84,24 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
   audit      一次跑完变更面审计：history + deps（枚举 lockfile 全部依赖），合并报告
              这是技能文档默认推荐入口；coverage 因需要覆盖率文件和符号名不在其中
   history    本次变更删掉了哪些代码、它们分别由哪个提交引入、该提交是不是安全修复
-             --base        必填，比较的基线版本（如 main、HEAD~5、某个 commit）
+             --base        可选：省略时按 merge-base(HEAD, origin/main) 推断分叉点。
+                           推断会写在「范围」那一行，并在「未评估的判据」里加一条 range-inferred：
+                           推断出的范围只到分叉点，不是被审历史的全貌。两个引用都解析不出来时报错，
+                           不退回去猜 HEAD~1
              --head        可选，默认 HEAD
              --pickaxe     额外检查「曾被移除又加回来」的新增行（有探针上限）
              --no-origins  关闭来源追溯；默认用 git log -S 把删除行归属到「最初引入」
                            该内容的提交（有探针上限，比纯 blame 慢）
+             --graph     输出 Mermaid 来源谱系图：范围 → 最后修改这些行的提交 → 最初引入
+                           其内容的提交（第二条边来自 -S 追溯，--no-origins 时没有）。
+                           图只画测到的状态与行数，不画严重性；与 --json 互斥，只适用于 history 与 audit
   coverage   某个符号在测试运行中到底有没有被调用过
-             --coverage  覆盖率数据文件，c8 的 coverage-final.json
+             --coverage  覆盖率数据文件，按形状自动识别 c8 / istanbul、
+                         coverage.py JSON、Go -coverprofile 文本、lcov tracefile
              --symbol    要查询的符号名，可重复
              --file      可选，限定到某个文件
              --source    可选，Go profile（go test -coverprofile）必需：模块根目录，
-                         用于把行区间映射回函数（profile 不含函数名）
+                         用于把行区间映射回函数（profile 不含函数名）；其余格式不需要
   deps       某个依赖在 lockfile 里被锁定/声明成什么版本（供应链声明的裁决依据）
              --repo      可选，依赖清单所在目录（默认当前目录，自动检测）
              --lockfile  可选，显式指定清单文件（支持 package-lock.json / Cargo.lock / go.mod）
@@ -123,8 +131,8 @@ 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]
-  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--no-origins] [--json]
+  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]
@@ -139,19 +147,30 @@ Commands:
              and symbol names only the adjudicator knows)
   history    which lines did this change delete, which commit introduced them,
              and was that commit a security fix?
-             --base        required, the baseline revision to compare against
+             --base        optional: omitted means the fork point is inferred as
+                           merge-base(HEAD, origin/main). The inference is stated on the range
+                           line and declared as range-inferred among the criteria not evaluated —
+                           an inferred range reaches the fork point, not the whole history. When
+                           neither ref resolves the run stops rather than guessing HEAD~1
              --head        optional, defaults to HEAD
              --pickaxe     also check added lines that were once removed and now return (probe-capped)
              --no-origins  disable origin tracing; by default git log -S attributes deleted
                            lines to the commit that FIRST introduced their content
                            (probe-capped, slower than plain blame)
+             --graph     print a Mermaid provenance graph: the range → the commit that last
+                           modified the deleted lines → the commit that first introduced their
+                           content (the second edge comes from -S tracing; --no-origins has
+                           none). It draws measured states and line counts, never severity;
+                           mutually exclusive with --json, history and audit only
   coverage   was this symbol ever actually invoked by a test run?
-             --coverage  the coverage data file, c8's coverage-final.json
+             --coverage  the coverage data file; identified by shape as c8 / istanbul,
+                         coverage.py JSON, a Go -coverprofile, or an lcov tracefile
              --symbol    symbol name(s) to query, repeatable
              --file      optional, restrict to one file
              --source    optional, required for Go profiles (go test -coverprofile):
                          the module root, used to map line ranges back to
-                         functions (the profile carries no function names)
+                         functions (the profile carries no function names); other
+                         formats do not need it
   deps       what version does the lockfile pin or declare for a dependency? (the basis for supply-chain claims)
              --repo      optional, directory containing the manifest (default cwd, auto-detected)
              --lockfile  optional, explicit manifest path (package-lock.json / Cargo.lock / go.mod)
@@ -251,18 +270,6 @@ async function runHistory(flags, lang) {
     };
   }
 
-  if (!flags.base) {
-    return { exit: EXIT.USAGE, error: t('history 需要 --base <rev>', 'history requires --base <rev>') };
-  }
-
-  const base = await revParse(toplevel, String(flags.base));
-  if (!base) {
-    return {
-      exit: EXIT.USAGE,
-      error: t(`无法解析 --base "${flags.base}" 为一个提交`, `cannot resolve --base "${flags.base}" to a commit`)
-    };
-  }
-
   const head = await revParse(toplevel, String(flags.head ?? 'HEAD'));
   if (!head) {
     return {
@@ -271,6 +278,12 @@ async function runHistory(flags, lang) {
     };
   }
 
+  const range = await resolveRangeBase({ flags, cwd: toplevel, head, t });
+  if (range.error) {
+    return { exit: EXIT.USAGE, error: range.error };
+  }
+  const base = range.base;
+
   // Origin tracing is the default (see runAudit); --no-origins opts out.
   const origins = flags['no-origins'] !== true;
 
@@ -283,9 +296,13 @@ async function runHistory(flags, lang) {
     lang
   });
 
+  if (range.ref) {
+    notEvaluated.push(rangeInferenceDeclaration({ ref: range.ref, head }, t));
+  }
+
   const report = makeReport({
     producer: producerFor(HISTORY_PRODUCER, lang),
-    subject: { repo: toplevel, base, head },
+    subject: { repo: toplevel, base, head, ...(range.ref ? { rangeSource: range.ref } : {}) },
     facts,
     evaluated,
     notEvaluated
@@ -409,6 +426,56 @@ async function runDeps(flags, lang) {
  * symbol names only the adjudicator knows, so there is nothing honest to
  * auto-measure there.
  */
+/**
+ * Declare the range the run inferred, in the shape every other declaration uses:
+ * a `notEvaluated` entry with a `code`, so the JSON channel carries it and a
+ * reader of the terminal output meets it in the caveat list.
+ *
+ * Pure, so the wording is testable in both languages without building a repository.
+ */
+export function rangeInferenceDeclaration({ ref, head }, t) {
+  const short = (sha) => (sha ?? '').slice(0, 10);
+  return {
+    kind: KIND.HISTORY,
+    code: 'range-inferred',
+    reason: t(
+      `未给 --base，比较范围按 merge-base(${short(head)}, ${ref}) 推断——这不是被审历史的全貌，换范围请显式传 --base <rev>`,
+      `no --base given: the range was inferred as merge-base(${short(head)}, ${ref}). That is not the whole history under review — pass --base <rev> to audit another range`
+    )
+  };
+}
+
+/**
+ * Resolve `--base`, or infer the fork point when the caller gave none.
+ *
+ * The inference is where an argument-free run could quietly narrow what is
+ * audited — a smaller range deletes edges and reads as cleaner — so the rule used
+ * comes back with the value and the caller must declare it. It forks from the
+ * resolved `--head`, not from whatever happens to be checked out: asking about
+ * another commit and getting this commit's ancestor would report a range nobody
+ * requested. There is no fallback to HEAD~1: with no remote-tracking branch to
+ * fork from, this says so and the run does not happen.
+ */
+export async function resolveRangeBase({ flags, cwd, head, t }) {
+  if (flags.base !== undefined) {
+    const base = await revParse(cwd, String(flags.base));
+    if (!base) {
+      return { error: t(`无法解析 --base "${flags.base}" 为一个提交`, `cannot resolve --base "${flags.base}" to a commit`) };
+    }
+    return { base };
+  }
+  for (const ref of ['origin/main', 'origin/HEAD']) {
+    const base = await mergeBase(cwd, head, ref);
+    if (base) return { base, ref };
+  }
+  return {
+    error: t(
+      '未给 --base，且 origin/main 与 origin/HEAD 都无法解析出分叉点——请显式传 --base <rev>',
+      'no --base given, and neither origin/main nor origin/HEAD resolves to a fork point — pass --base <rev>'
+    )
+  };
+}
+
 /**
  * Decide whether the manifest `audit` measured is the manifest --head holds.
  *
@@ -457,10 +524,6 @@ async function runAudit(flags, lang) {
   const t = T(lang);
   const cwd = path.resolve(flags.repo ? String(flags.repo) : process.cwd());
 
-  if (!flags.base) {
-    return { exit: EXIT.USAGE, error: t('audit 需要 --base <rev>', 'audit requires --base <rev>') };
-  }
-
   // --- history half (mirrors runHistory's repo/base/head resolution) ---
   const toplevel = await repoToplevel(cwd);
   if (!toplevel) {
@@ -483,14 +546,6 @@ async function runAudit(flags, lang) {
     };
   }
 
-  const base = await revParse(toplevel, String(flags.base));
-  if (!base) {
-    return {
-      exit: EXIT.USAGE,
-      error: t(`无法解析 --base "${flags.base}" 为一个提交`, `cannot resolve --base "${flags.base}" to a commit`)
-    };
-  }
-
   const head = await revParse(toplevel, String(flags.head ?? 'HEAD'));
   if (!head) {
     return {
@@ -499,6 +554,12 @@ async function runAudit(flags, lang) {
     };
   }
 
+  const range = await resolveRangeBase({ flags, cwd: toplevel, head, t });
+  if (range.error) {
+    return { exit: EXIT.USAGE, error: range.error };
+  }
+  const base = range.base;
+
   const origins = flags['no-origins'] !== true;
   const history = await collectHistoryFacts({
     cwd: toplevel,
@@ -555,10 +616,13 @@ async function runAudit(flags, lang) {
   const facts = [...history.facts, ...depFacts];
   const evaluated = [...history.evaluated, ...depEvaluated];
   const notEvaluated = [...history.notEvaluated, ...depNotEvaluated];
+  if (range.ref) {
+    notEvaluated.push(rangeInferenceDeclaration({ ref: range.ref, head }, t));
+  }
 
   const report = makeReport({
     producer: producerFor(AUDIT_PRODUCER, lang),
-    subject: { repo: toplevel, base, head },
+    subject: { repo: toplevel, base, head, ...(range.ref ? { rangeSource: range.ref } : {}) },
     facts,
     evaluated,
     notEvaluated
@@ -726,11 +790,31 @@ export async function main(argv = process.argv.slice(2)) {
   const lang = resolveLang({ flag: flagLang });
   const t = T(lang);
 
+  // `--graph` is a render mode, not an extra channel: a graph with a JSON
+  // document glued to it on one stdout makes a CI step that parses either one
+  // fail without saying which.
+  if (flags.graph && flags.json) {
+    process.stderr.write(
+      safeTextLines(t('--graph 与 --json 互斥，一次只选一种输出', '--graph and --json are mutually exclusive; choose one output') + '\n')
+    );
+    return EXIT.USAGE;
+  }
+
   if (!command || command === 'help' || flags.help) {
     process.stdout.write(helpText(lang));
     return EXIT.CLEAN;
   }
 
+  // Only `history` and `audit` produce deleted-line attribution. Drawing the
+  // provenance graph for another command prints a range node with no edges, which
+  // reads as "no provenance found" — the one thing this must not imply.
+  if (flags.graph && command !== 'history' && command !== 'audit') {
+    process.stderr.write(
+      safeTextLines(t('--graph 只适用于 history 与 audit', '--graph applies to history and audit only') + '\n')
+    );
+    return EXIT.USAGE;
+  }
+
   let result;
   if (command === 'history') {
     result = await runHistory(flags, lang);
@@ -764,6 +848,10 @@ export async function main(argv = process.argv.slice(2)) {
 
   if (flags.json) {
     process.stdout.write(`${JSON.stringify(result.report, null, 2)}\n`);
+  } else if (flags.graph && result.report) {
+    // The graph is terminal output like every other render: safeTextLines keeps
+    // its line structure and neutralises control bytes a repo path could carry.
+    process.stdout.write(safeTextLines(`${provenanceGraph(result.report)}\n`));
   } else if (result.report) {
     renderReport(result.report, { lang });
   }

package/src/contract.js

@@ -206,7 +206,12 @@ export function renderReport(report, { write: rawWrite = console.log, lang = DEF
   write(`euthyna ${producer.name} — ${producer.purpose || ''}`.trim());
   write(`${t('目标: ', 'Target: ')}${subject.repo ?? subject.coverageFile ?? t('(未指定)', '(unspecified)')}`);
   if (subject.base || subject.head) {
-    write(`${t('范围: ', 'Range: ')}${subject.base ?? '?'}..${subject.head ?? 'HEAD'}`);
+    write(
+      `${t('范围: ', 'Range: ')}${subject.base ?? '?'}..${subject.head ?? 'HEAD'}` +
+        // An inferred range is a decision the tool made on the reader's behalf, so
+        // it is said on the line that states the range — not only in the caveat list.
+        (subject.rangeSource ? t(`（推断：与 ${subject.rangeSource} 的分叉点）`, ` (inferred: the fork point from ${subject.rangeSource})`) : '')
+    );
   }
   write('');