euthyna 0.1.0

package/src/cli.js

@@ -0,0 +1,238 @@
+/**
+ * euthyna CLI.
+ *
+ * Exit code contract. The positioning work found that none of the eight
+ * measurement plugins in this ecosystem publish a process exit code, so their
+ * output cannot gate anything in CI. This one does:
+ *
+ *   0   measured; nothing security-classified found
+ *   10  measured; at least one security-classified fact found
+ *   1   usage error
+ *   2   could not measure at all (no facts and a recorded reason)
+ *
+ * 2 is deliberately distinct from 0: a run that could not measure must never be
+ * read as a clean run.
+ */
+import process from 'node:process';
+import path from 'node:path';
+import { collectHistoryFacts } from './facts/history.js';
+import { collectCoverageFacts } from './facts/coverage.js';
+import { makeReport, renderReport, safeTextLines, KIND } from './contract.js';
+import { repoToplevel, revParse } from './git.js';
+
+export const EXIT = Object.freeze({
+  CLEAN: 0,
+  FLAGGED: 10,
+  USAGE: 1,
+  UNMEASURED: 2
+});
+
+const HISTORY_PRODUCER = {
+  name: 'euthyna-history',
+  version: '0.1.0',
+  purpose: '被删除代码的来源归属与安全分类'
+};
+const COVERAGE_PRODUCER = {
+  name: 'euthyna-coverage',
+  version: '0.1.0',
+  purpose: '符号调用计数（只能证伪）'
+};
+
+const HELP = `
+euthyna —— 给 AI 编码 agent 用的确定性事实产出器
+
+它不是扫描器。它只回答两个模型算不准的问题，并把答案写成带证据的事实。
+
+用法:
+  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--json]
+  euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--json]
+
+命令:
+  history    本次变更删掉了哪些代码、它们分别由哪个提交引入、该提交是不是安全修复
+             --base    必填，比较的基线版本（如 main、HEAD~5、某个 commit）
+             --head    可选，默认 HEAD
+             --pickaxe 额外检查「曾被移除又加回来」的新增行（有探针上限）
+  coverage   某个符号在测试运行中到底有没有被调用过
+             --coverage  覆盖率数据文件，c8 的 coverage-final.json
+             --symbol    要查询的符号名，可重复
+             --file      可选，限定到某个文件
+
+退出码:
+  0   已测量，没有安全相关的发现
+  10  已测量，且存在被分类为 security 的事实
+  1   用法错误
+  2   完全无法测量（此时**不得**当作干净）
+
+注意: 缺数据不等于干净。无法测量的判据会列在输出的「未评估的判据」一节。
+`;
+
+/**
+ * Minimal argv parser: `--key value`, `--flag`, and repeated `--key` flags.
+ *
+ * A repeated flag accumulates into an array. Overwriting instead would silently
+ * drop all but the last value, which for `--symbol` means reporting on one
+ * symbol while the user asked about several - a wrong answer delivered
+ * confidently, which is the failure mode this project exists to remove.
+ */
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+
+  const record = (key, value) => {
+    if (key in flags) {
+      flags[key] = Array.isArray(flags[key]) ? [...flags[key], value] : [flags[key], value];
+    } else {
+      flags[key] = value;
+    }
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      record(key, true);
+    } else {
+      record(key, next);
+      i++;
+    }
+  }
+  return { positional, flags };
+}
+
+/** Collect repeatable flags into an array. */
+function asArray(value) {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+async function runHistory(flags) {
+  const cwd = path.resolve(flags.repo ? String(flags.repo) : process.cwd());
+
+  const toplevel = await repoToplevel(cwd);
+  if (!toplevel) {
+    return {
+      exit: EXIT.UNMEASURED,
+      report: makeReport({
+        producer: HISTORY_PRODUCER,
+        subject: { repo: cwd },
+        facts: [],
+        notEvaluated: [
+          { kind: KIND.HISTORY, reason: `${cwd} 不在任何 git 仓库内，无法测量历史` }
+        ]
+      })
+    };
+  }
+
+  if (!flags.base) {
+    return { exit: EXIT.USAGE, error: 'history 需要 --base <rev>' };
+  }
+
+  const base = await revParse(toplevel, String(flags.base));
+  if (!base) {
+    return { exit: EXIT.USAGE, error: `无法解析 --base "${flags.base}" 为一个提交` };
+  }
+
+  const head = await revParse(toplevel, String(flags.head ?? 'HEAD'));
+  if (!head) {
+    return { exit: EXIT.USAGE, error: `无法解析 --head "${flags.head ?? 'HEAD'}" 为一个提交` };
+  }
+
+  const { facts, evaluated, notEvaluated, measured } = await collectHistoryFacts({
+    cwd: toplevel,
+    base,
+    head,
+    pickaxe: flags.pickaxe === true
+  });
+
+  const report = makeReport({
+    producer: HISTORY_PRODUCER,
+    subject: { repo: toplevel, base, head },
+    facts,
+    evaluated,
+    notEvaluated
+  });
+
+  const flagged = facts.some(
+    f => f.kind === KIND.HISTORY && f.detail && f.detail.classification === 'security'
+  );
+
+  // "Nothing was deleted" is a completed measurement whose answer is empty, not
+  // a measurement failure. Only `measured === false` means we could not answer.
+  return {
+    exit: !measured ? EXIT.UNMEASURED : flagged ? EXIT.FLAGGED : EXIT.CLEAN,
+    report
+  };
+}
+
+async function runCoverage(flags) {
+  const coverageFile = path.resolve(
+    String(flags.coverage ?? 'coverage/coverage-final.json')
+  );
+  const symbols = asArray(flags.symbol).map(String);
+  const file = flags.file ? String(flags.file) : undefined;
+
+  // Asking for nothing is a caller mistake, not a measurement failure.
+  if (symbols.length === 0) {
+    return { exit: EXIT.USAGE, error: 'coverage 需要至少一个 --symbol <name>' };
+  }
+
+  const targets = symbols.map(symbol => ({ symbol, ...(file ? { file } : {}) }));
+  const { facts, evaluated, notEvaluated, measured } = await collectCoverageFacts({
+    coverageFile,
+    targets
+  });
+
+  const report = makeReport({
+    producer: COVERAGE_PRODUCER,
+    subject: { coverageFile, symbols, file },
+    facts,
+    evaluated,
+    notEvaluated
+  });
+
+  return { exit: measured ? EXIT.CLEAN : EXIT.UNMEASURED, report };
+}
+
+/** Entry point. Returns the process exit code. */
+export async function main(argv = process.argv.slice(2)) {
+  const { positional, flags } = parseArgs(argv);
+  const command = positional[0];
+
+  if (!command || command === 'help' || flags.help) {
+    process.stdout.write(HELP);
+    return EXIT.CLEAN;
+  }
+
+  let result;
+  if (command === 'history') {
+    result = await runHistory(flags);
+  } else if (command === 'coverage') {
+    result = await runCoverage(flags);
+  } else {
+    // stderr boundary, mirroring the render boundary in contract.js: text that
+    // reaches the error channel may carry user or repo-controlled bytes (an
+    // unknown command echoes argv; a usage error embeds flag values), so it is
+    // made terminal-safe once, here. HELP is multi-line and static; safeTextLines
+    // preserves its line structure and is a no-op on its plain text.
+    process.stderr.write(safeTextLines(`未知命令: ${command}\n${HELP}`));
+    return EXIT.USAGE;
+  }
+
+  if (result.error) {
+    process.stderr.write(safeTextLines(`${result.error}\n`));
+    return result.exit;
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(result.report, null, 2)}\n`);
+  } else {
+    renderReport(result.report);
+  }
+
+  return result.exit;
+}

package/src/contract.js

@@ -0,0 +1,249 @@
+/**
+ * The fact contract, in code.
+ *
+ * Facts produced here are consumed by an adjudication layer. Two properties are
+ * enforced mechanically rather than by convention, because a convention is what
+ * erodes first:
+ *
+ *   1. Facts carry no verdict. No score, no severity, no recommendation. A
+ *      measurement layer that emits "risk: high" has decided for the
+ *      adjudicator, and the decision is not reproducible.
+ *   2. Every fact is three-state. "Established", "refuted" and "unknown" are
+ *      distinct, and a missing measurement is never silently reported as clean.
+ *
+ * See docs/fact-contract-zh.md.
+ */
+
+import { stripVTControlCharacters } from 'node:util';
+
+export const SCHEMA_VERSION = '0.1';
+
+/**
+ * Quote a value for pasting into a POSIX shell.
+ *
+ * Single quotes make every byte literal except the single quote itself, which
+ * the `'\''` idiom escapes. JSON.stringify is not enough here: inside double
+ * quotes a backtick or $( ) still executes, so a repo-controlled filename or
+ * symbol would survive it as code, not data.
+ */
+export function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Render repo-controlled text safely for the terminal: every C0 control and
+ * DEL becomes a visible escape (\n, \r, \t, else \xHH). Nothing is preserved
+ * raw — a literal \r would let a filename overwrite the report line on screen
+ * — and nothing is deleted silently — a command whose BEL was dropped would
+ * no longer reproduce the fact when pasted. stripVTControlCharacters removes
+ * complete CSI/OSC sequences first; the regex catches the stragglers.
+ */
+export function safeText(value) {
+  return stripVTControlCharacters(String(value)).replace(/[\x00-\x1F\x7F]/g, (ch) => {
+    if (ch === '\n') return '\\n';
+    if (ch === '\r') return '\\r';
+    if (ch === '\t') return '\\t';
+    return `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`;
+  });
+}
+
+/**
+ * safeText for multi-line text: every line is made terminal-safe, real newlines
+ * are preserved as structure. The render boundary never sees a newline
+ * (renderReport writes line by line), but the error path does — a stack trace
+ * flattened into one line of \n escapes would be unreadable. What must never
+ * survive is a control that acts on the terminal: CR (line overwrite), BEL,
+ * ESC, every other C0 and DEL are still made visible, per line.
+ */
+export function safeTextLines(value) {
+  return String(value)
+    .split('\n')
+    .map(safeText)
+    .join('\n');
+}
+
+/** Fact kinds. Kept explicit so an unknown kind fails loudly instead of passing. */
+export const KIND = Object.freeze({
+  HISTORY: 'history',
+  REINTRODUCTION: 'reintroduction',
+  TEST_COVERAGE: 'test_coverage'
+});
+
+/** Fact status. `unknown` is a first-class value, not an error. */
+export const STATUS = Object.freeze({
+  ESTABLISHED: 'established',
+  REFUTED: 'refuted',
+  UNKNOWN: 'unknown'
+});
+
+/**
+ * Keys that must never appear on a fact: they belong to the adjudication layer.
+ * Checked recursively so a nested object cannot smuggle one in.
+ */
+const FORBIDDEN_KEYS = [
+  'severity',
+  'score',
+  'risk',
+  'confidence_score',
+  'recommendation',
+  'remediation',
+  'fix',
+  'verdict',
+  'exploitable',
+  'priority'
+];
+
+/**
+ * Throw if a value contains a key reserved for the adjudication layer.
+ * A measurement layer that can set these has stopped being a measurement layer.
+ */
+export function assertNoVerdictFields(value, path = 'fact') {
+  if (value === null || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoVerdictFields(item, `${path}[${index}]`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.includes(key.toLowerCase())) {
+      throw new Error(
+        `fact contract violation: "${path}.${key}" is reserved for the adjudication layer. ` +
+          `The measurement layer must not emit ${key}.`
+      );
+    }
+    assertNoVerdictFields(child, `${path}.${key}`);
+  }
+}
+
+/**
+ * Build one fact. Throws when a required field is missing, so a malformed fact
+ * cannot reach the adjudication layer and be read as a weaker claim than intended.
+ *
+ * @param {object} input
+ * @param {string} input.kind       one of KIND
+ * @param {string} input.statement  one sentence a human can check
+ * @param {string} input.status     one of STATUS
+ * @param {object} input.evidence   {file, line?, commit?, snippet?}
+ * @param {string} input.method     'command' | 'static' | 'tool'
+ * @param {string} [input.command]  required when method is 'command'
+ * @param {'exact'|'approximate'} [input.confidence]
+ * @param {object} [input.detail]   kind-specific structured payload
+ * @param {string} input.id
+ */
+export function makeFact(input) {
+  const { id, kind, statement, status, evidence, method, command, confidence = 'exact', detail } = input;
+
+  if (!id) throw new Error('fact requires an id');
+  if (!Object.values(KIND).includes(kind)) throw new Error(`fact ${id}: unknown kind "${kind}"`);
+  if (!Object.values(STATUS).includes(status)) throw new Error(`fact ${id}: unknown status "${status}"`);
+  if (!statement) throw new Error(`fact ${id}: statement is required`);
+  if (!evidence || !evidence.file) throw new Error(`fact ${id}: evidence.file is required`);
+  if (method === 'command' && !command) {
+    throw new Error(`fact ${id}: method "command" requires the reproducible command`);
+  }
+
+  const fact = {
+    id,
+    kind,
+    statement,
+    status,
+    evidence,
+    method,
+    ...(command ? { command } : {}),
+    confidence,
+    ...(detail ? { detail } : {})
+  };
+
+  assertNoVerdictFields(fact);
+  return fact;
+}
+
+/**
+ * Build the report envelope.
+ *
+ * `notEvaluated` is the honesty surface: anything the producer could not
+ * measure must be listed with a reason. An empty `notEvaluated` alongside zero
+ * facts means "measured, nothing found"; a populated one means "do not read
+ * this as clean".
+ */
+export function makeReport({ producer, subject, facts, evaluated = [], notEvaluated = [] }) {
+  for (const fact of facts) assertNoVerdictFields(fact);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    producer,
+    subject,
+    facts,
+    coverage: { evaluated, notEvaluated }
+  };
+}
+
+/** Convenience: an entry for the coverage.notEvaluated list. */
+export function notEvaluated(kind, reason) {
+  if (!reason) throw new Error(`notEvaluated("${kind}") requires a specific reason`);
+  return { kind, reason };
+}
+
+/**
+ * Render a report for a terminal reader.
+ *
+ * Ordering is deliberate: what was NOT measured comes last but is never
+ * omitted, so a reader cannot finish the output without seeing it.
+ */
+export function renderReport(report, { write: rawWrite = console.log } = {}) {
+  // Render boundary: every repo-controlled string below passes through safeText
+  // exactly once, here, rather than at each producer. The JSON channel
+  // (cli.js) needs no equivalent — JSON.stringify escapes control bytes.
+  const write = (line) => rawWrite(safeText(line));
+  const { producer, subject, facts, coverage } = report;
+
+  const established = facts.filter(f => f.status === STATUS.ESTABLISHED);
+  const refuted = facts.filter(f => f.status === STATUS.REFUTED);
+  const unknown = facts.filter(f => f.status === STATUS.UNKNOWN);
+
+  write('');
+  write(`euthyna ${producer.name} — ${producer.purpose || ''}`.trim());
+  write(`目标: ${subject.repo ?? subject.coverageFile ?? '(未指定)'}`);
+  if (subject.base || subject.head) {
+    write(`范围: ${subject.base ?? '?'}..${subject.head ?? 'HEAD'}`);
+  }
+  write('');
+
+  const section = (title, list) => {
+    if (list.length === 0) return;
+    write(`${title} (${list.length})`);
+    for (const fact of list) {
+      write(`  • ${fact.statement}`);
+      const where = [fact.evidence.file, fact.evidence.line].filter(Boolean).join(':');
+      write(`      证据: ${where}${fact.evidence.commit ? ` (${fact.evidence.commit.slice(0, 10)})` : ''}`);
+      if (fact.command) write(`      复现: ${fact.command}`);
+      if (fact.confidence === 'approximate') {
+        write('      ⚠ approximate —— 不得用于门禁判定');
+      }
+    }
+    write('');
+  };
+
+  section('已确证', established);
+  section('已证伪', refuted);
+  section('无法判定', unknown);
+
+  if (facts.length === 0) {
+    write('  本次运行没有产出任何事实。');
+    write('');
+  }
+
+  if (coverage.notEvaluated.length > 0) {
+    write('⚠ 未评估的判据（缺数据不等于干净）：');
+    for (const item of coverage.notEvaluated) {
+      write(`  • ${item.kind}: ${item.reason}`);
+    }
+    write('');
+  }
+
+  if (coverage.evaluated.length > 0) {
+    write('已评估的判据：');
+    for (const item of coverage.evaluated) {
+      write(`  • ${item.kind}: ${item.count} 条 (${item.producer})`);
+    }
+    write('');
+  }
+}