euthyna 0.1.0 → 0.2.0

package/plugin/index.js

@@ -0,0 +1,60 @@
+/**
+ * The DSH half of euthyna: mounts the packaged skill on `ctx.skills`.
+ *
+ * The CLI (`bin/euthyna.js`) produces the facts; this plugin is what makes the
+ * discipline that consumes them installable with `dsh plugin add euthyna`. It
+ * serves the skill directory shipped inside this package, so the bundle carries
+ * the skill itself rather than pointing at a checkout.
+ *
+ * The official filesystem provider is imported instead of reimplemented:
+ * frontmatter parsing and root ranking then stay byte-identical with the
+ * built-in provider, and the only thing this package decides is which root to
+ * serve.
+ *
+ * @module euthyna/plugin
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem';
+
+export const name = 'euthyna';
+
+/** Without the skill registry there is nothing to register onto. */
+export const inject = ['skills'];
+
+/** This module's directory: `<package>/plugin`, in the repo and in the tarball alike. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** The packaged skill root, at the same relative path in both layouts. */
+export const SKILLS_ROOT = join(MODULE_DIR, '..', '.agents', 'skills');
+
+/**
+ * Register the packaged skill directory as a provider.
+ *
+ * `includeDefaultRoots: false` keeps this provider to euthyna's own skill: the
+ * built-in provider goes on serving the user's other skills, so installing this
+ * bundle adds a skill rather than replacing the catalogue. Registration is a
+ * plain call — the provider disposes itself through the control signal it is
+ * handed.
+ *
+ * A missing bundle throws rather than mounting an empty provider, because a
+ * plugin that installs cleanly and contributes nothing is worse than one that
+ * fails where someone can see it.
+ *
+ * @param ctx - the cordis context, which must expose `skills`.
+ * @param config - optional `{ skillsDir }` override for a relocated skill root.
+ */
+export function apply(ctx, config = {}) {
+  const root = resolve(config.skillsDir ?? SKILLS_ROOT);
+  const bundle = join(root, 'euthyna', 'SKILL.md');
+  if (!existsSync(bundle)) {
+    throw new Error(`euthyna: no skill bundle at ${bundle} — set config.skillsDir to the directory holding euthyna/SKILL.md`);
+  }
+  ctx.skills.registerProvider((control) => new FileSystemSkillProvider(ctx, control, {
+    providerName: 'euthyna',
+    includeDefaultRoots: false,
+    customSkillDirs: [root],
+    watch: false,
+  }));
+}

package/src/cli.js

@@ -15,8 +15,11 @@
  */
 import process from 'node:process';
 import path from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { collectHistoryFacts } from './facts/history.js';
 import { collectCoverageFacts } from './facts/coverage.js';
+import { collectDependencyFacts } from './facts/deps.js';
+import { parseGateReport, validateFindings, verifyFinding, renderGateReport } from './gate.js';
 import { makeReport, renderReport, safeTextLines, KIND } from './contract.js';
 import { repoToplevel, revParse } from './git.js';
 
@@ -37,6 +40,11 @@ const COVERAGE_PRODUCER = {
   version: '0.1.0',
   purpose: '符号调用计数（只能证伪）'
 };
+const DEPS_PRODUCER = {
+  name: 'euthyna-deps',
+  version: '0.1.0',
+  purpose: '依赖锁定版本（读取 lockfile，不含漏洞判定）'
+};
 
 const HELP = `
 euthyna —— 给 AI 编码 agent 用的确定性事实产出器
@@ -44,24 +52,40 @@ euthyna —— 给 AI 编码 agent 用的确定性事实产出器
 它不是扫描器。它只回答两个模型算不准的问题，并把答案写成带证据的事实。
 
 用法:
-  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--json]
+  euthyna history  --base <rev> [--head <rev>] [--repo <dir>] [--pickaxe] [--origins] [--json]
   euthyna coverage --coverage <file> --symbol <name> [--file <path>] [--json]
+  euthyna deps     [--repo <dir>] [--lockfile <file>] --dep <name> [--dep <name>] [--json]
+  euthyna gate     <报告文件> [--verify] [--cwd <dir>] [--json]
 
 命令:
   history    本次变更删掉了哪些代码、它们分别由哪个提交引入、该提交是不是安全修复
              --base    必填，比较的基线版本（如 main、HEAD~5、某个 commit）
              --head    可选，默认 HEAD
              --pickaxe 额外检查「曾被移除又加回来」的新增行（有探针上限）
+             --origins 用 git log -S 把删除行归属到「最初引入」该内容的提交，
+                       而非 blame 的「最后修改者」（有探针上限，比默认慢）
   coverage   某个符号在测试运行中到底有没有被调用过
              --coverage  覆盖率数据文件，c8 的 coverage-final.json
              --symbol    要查询的符号名，可重复
              --file      可选，限定到某个文件
+  deps       某个依赖在 lockfile 里被锁定/声明成什么版本（供应链声明的裁决依据）
+             --repo      可选，依赖清单所在目录（默认当前目录，自动检测）
+             --lockfile  可选，显式指定清单文件（支持 package-lock.json / Cargo.lock / go.mod）
+             --dep       要查询的依赖名，可重复
+             注：只报版本事实，不判「是否含漏洞」——版本到 CVE 的映射归判定层
+  gate       检查一份审计报告是否符合 6 门禁契约（不测量，只核对报告的自我声明）
+             <报告文件>   报告的 markdown 文件，裁定格式见技能 SKILL.md
+             --verify     重跑每条 TRUE POSITIVE 的复现命令（按 argv 执行，不经过 shell）
+                          默认只执行 git 命令；⚠ 执行结果以你的权限生效，只对你信任的报告用
+             --allow-exec 允许 --verify 执行解释器命令（node/npm/python）——
+                          它们能跑报告里的任意代码，加了它就等于你为该报告背书
+             --cwd <dir>  --verify 的工作目录（默认当前目录）
 
 退出码:
-  0   已测量，没有安全相关的发现
-  10  已测量，且存在被分类为 security 的事实
+  0   已测量，没有安全相关的发现；或 gate 报告全部通过门禁契约
+  10  已测量，且存在被分类为 security 的事实；或 gate 报告有 finding 被降级
   1   用法错误
-  2   完全无法测量（此时**不得**当作干净）
+  2   完全无法测量（此时**不得**当作干净）；或 gate 报告无法读取/没有可校验的 finding
 
 注意: 缺数据不等于干净。无法测量的判据会列在输出的「未评估的判据」一节。
 `;
@@ -146,7 +170,8 @@ async function runHistory(flags) {
     cwd: toplevel,
     base,
     head,
-    pickaxe: flags.pickaxe === true
+    pickaxe: flags.pickaxe === true,
+    origins: flags.origins === true
   });
 
   const report = makeReport({
@@ -198,6 +223,123 @@ async function runCoverage(flags) {
   return { exit: measured ? EXIT.CLEAN : EXIT.UNMEASURED, report };
 }
 
+async function runDeps(flags) {
+  const cwd = path.resolve(flags.repo ? String(flags.repo) : process.cwd());
+  const deps = asArray(flags.dep).map(String);
+  const lockfile = flags.lockfile ? String(flags.lockfile) : undefined;
+
+  // Asking for nothing is a caller mistake, not a measurement failure.
+  if (deps.length === 0) {
+    return { exit: EXIT.USAGE, error: 'deps 需要至少一个 --dep <name>' };
+  }
+
+  const { facts, evaluated, notEvaluated, measured } = await collectDependencyFacts({
+    cwd,
+    lockfile,
+    deps
+  });
+
+  const report = makeReport({
+    producer: DEPS_PRODUCER,
+    subject: { repo: cwd, lockfile: lockfile ?? '(自动检测)', deps },
+    facts,
+    evaluated,
+    notEvaluated
+  });
+
+  return { exit: measured ? EXIT.CLEAN : EXIT.UNMEASURED, report };
+}
+async function runGate(flags, positional) {
+  const file = positional[1];
+  if (!file) {
+    return { exit: EXIT.USAGE, error: 'gate 需要 <报告文件>（markdown，裁定格式见技能 SKILL.md）' };
+  }
+
+  let text;
+  try {
+    text = await readFile(path.resolve(file), 'utf8');
+  } catch (error) {
+    // An unreadable report is not a clean pass: there is nothing to check, and
+    // "nothing was checked" must not read as "everything passed".
+    return { exit: EXIT.UNMEASURED, error: `无法读取报告 ${file}: ${error.message}` };
+  }
+
+  const { findings, unparseable } = parseGateReport(text);
+  if (findings.length === 0 && unparseable.length === 0) {
+    return { exit: EXIT.UNMEASURED, error: `报告 ${file} 中没有可校验的 finding（需要 BUG #N <VERDICT> — 说明 形式）` };
+  }
+
+  const validated = validateFindings(findings);
+  for (const line of unparseable) {
+    validated.push({ unparseableLine: line, violations: ['无法解析的 BUG 行'], downgraded: true });
+  }
+
+  if (flags.verify) {
+    const cwd = path.resolve(flags.cwd ? String(flags.cwd) : process.cwd());
+    const allowInterpreters = flags['allow-exec'] === true;
+    for (const entry of validated) {
+      if (entry.unparseableLine) continue;
+      entry.verification = await verifyFinding(entry.finding, { cwd, allowInterpreters });
+      const v = entry.verification;
+      // Every status other than "verified" means the reproduction claim was
+      // not actually checked, which is a downgrade: a refused tool, an
+      // interpreter awaiting consent, an unparseable command and a failed run
+      // are different failures, but none of them is a verified reproduction.
+      if (v.status === 'failed') {
+        entry.violations.push(`复现命令未通过（exit ${v.exitCode ?? '?'}${v.detail ? `: ${v.detail}` : ''}）`);
+        entry.downgraded = true;
+      } else if (v.status === 'refused') {
+        entry.violations.push(`复现命令被拒绝（${v.tool} 不在白名单）——复现未验证`);
+        entry.downgraded = true;
+      } else if (v.status === 'needs-consent') {
+        entry.violations.push(`复现命令是解释器命令（${v.tool}），未执行——复现未验证；信任该报告时加 --allow-exec`);
+        entry.downgraded = true;
+      } else if (v.status === 'unparseable') {
+        entry.violations.push('复现命令无法拆分为 argv——复现未验证');
+        entry.downgraded = true;
+      }
+      // no-command is already a structural violation (a TRUE POSITIVE without a
+      // reproduce line), so --verify does not double-report it.
+    }
+  }
+
+  const downgraded = validated.filter(e => e.downgraded).length;
+  const result = { file, findings: validated, unparseable, downgraded, verify: flags.verify === true };
+
+  if (flags.json) {
+    return {
+      exit: downgraded > 0 ? EXIT.FLAGGED : EXIT.CLEAN,
+      json: JSON.stringify(
+        {
+          command: 'gate',
+          file,
+          findings: validated.map(e => ({
+            ...(e.unparseableLine
+              ? { unparseable: e.unparseableLine }
+              : {
+                  number: e.finding.number,
+                  verdict: e.finding.verdict,
+                  claim: e.finding.claim,
+                  evidence: e.finding.evidence,
+                  reproduce: e.finding.reproduce,
+                  impact: e.finding.impact,
+                  gates: e.finding.gates
+                }),
+            violations: e.violations,
+            downgraded: e.downgraded
+          })),
+          downgraded
+        },
+        null,
+        2
+      )
+    };
+  }
+
+  renderGateReport(result);
+  return { exit: downgraded > 0 ? EXIT.FLAGGED : EXIT.CLEAN, report: null };
+}
+
 /** Entry point. Returns the process exit code. */
 export async function main(argv = process.argv.slice(2)) {
   const { positional, flags } = parseArgs(argv);
@@ -213,6 +355,10 @@ export async function main(argv = process.argv.slice(2)) {
     result = await runHistory(flags);
   } else if (command === 'coverage') {
     result = await runCoverage(flags);
+  } else if (command === 'deps') {
+    result = await runDeps(flags);
+  } else if (command === 'gate') {
+    result = await runGate(flags, positional);
   } else {
     // stderr boundary, mirroring the render boundary in contract.js: text that
     // reaches the error channel may carry user or repo-controlled bytes (an
@@ -228,9 +374,14 @@ export async function main(argv = process.argv.slice(2)) {
     return result.exit;
   }
 
+  if (result.json) {
+    process.stdout.write(`${result.json}\n`);
+    return result.exit;
+  }
+
   if (flags.json) {
     process.stdout.write(`${JSON.stringify(result.report, null, 2)}\n`);
-  } else {
+  } else if (result.report) {
     renderReport(result.report);
   }
 

package/src/contract.js

@@ -66,7 +66,8 @@ export function safeTextLines(value) {
 export const KIND = Object.freeze({
   HISTORY: 'history',
   REINTRODUCTION: 'reintroduction',
-  TEST_COVERAGE: 'test_coverage'
+  TEST_COVERAGE: 'test_coverage',
+  DEPENDENCY: 'dependency'
 });
 
 /** Fact status. `unknown` is a first-class value, not an error. */

package/src/facts/coverage.js

@@ -62,14 +62,18 @@ function reproduceCommand({ coverageFile, symbol, file }) {
 /**
  * Read a coverage report.
  *
- * Two formats are accepted:
+ * Three formats are accepted, all identified by shape rather than by filename:
  *
  * 1. c8 / v8-to-istanbul `coverage-final.json` — per-file keys are
  *    path/all/statementMap/s/branchMap/b/fnMap/f. There is no istanbul `hash`,
  *    and `branchMap` is a relabelled V8 block range rather than an if/else
  *    model, so a consumer written against classic istanbul field lists reads
  *    the wrong thing.
- * 2. coverage.py JSON (`coverage json`, format 3) — top level is
+ * 2. classic istanbul (jest's default provider, nyc) `coverage-final.json` —
+ *    the same per-file statementMap/s/branchMap/b/fnMap/f plus a `hash` field.
+ *    The symbol locator only reads fnMap/f, which classic istanbul and c8 emit
+ *    in the same shape, so both resolve through the same code path.
+ * 3. coverage.py JSON (`coverage json`, format 3) — top level is
  *    `{meta, files}`, and per-file `functions` maps a function name
  *    (`name`, or `Class.method` for methods) to
  *    `{executed_lines, missing_lines, start_line, ...}`. There is **no
@@ -77,6 +81,10 @@ function reproduceCommand({ coverageFile, symbol, file }) {
  *    evidence that the function was never entered. coverage.py reports
  *    functions that were never called as long as their module was loaded,
  *    which is exactly what makes "never invoked" an established fact.
+ *
+ * Anything that matches none of these shapes is **not a coverage report this
+ * producer can read**, and is reported as notEvaluated — never fed through the
+ * locator, where it would answer "symbol not located" with a straight face.
  */
 export async function loadCoverage(coverageFile) {
   const raw = await readFile(coverageFile, 'utf8');
@@ -98,6 +106,35 @@ function isCoveragePyReport(coverage) {
   );
 }
 
+/**
+ * Identify the coverage format by shape, or null when the file is not a
+ * coverage report at all. c8 and classic istanbul share the fnMap/f shape the
+ * locator reads; they differ only in `hash` (istanbul has it, c8 does not) and
+ * `all` (c8 has it), neither of which the locator reads — but naming the format
+ * honestly is still part of the fact, so the distinction is kept.
+ */
+export function detectCoverageFormat(coverage) {
+  if (isCoveragePyReport(coverage)) return 'coverage.py';
+
+  const entries = Object.entries(coverage).filter(([, v]) => v && typeof v === 'object');
+  if (entries.length === 0) return null;
+
+  // A real c8/istanbul entry carries both `fnMap` (function metadata) and `f`
+  // (per-index invocation counts). Requiring both stops a partial shape — a
+  // file with `fnMap` but no `f`, say — from being classified as coverage and
+  // then emitting "never invoked" for a count a missing `f` defaults to zero.
+  // coverage.py's per-file `functions` is only valid inside a `meta.files`
+  // report, which isCoveragePyReport already handled above; a bare `functions`
+  // object is not a JS report and must not be accepted here.
+  const jsShaped = entries.some(
+    ([, e]) =>
+      e.fnMap && typeof e.fnMap === 'object' && e.f && typeof e.f === 'object'
+  );
+  if (!jsShaped) return null;
+
+  return entries.some(([, e]) => typeof e === 'object' && 'hash' in e) ? 'istanbul' : 'c8';
+}
+
 /**
  * Locate a symbol inside one file entry and normalise the hit.
  *
@@ -215,6 +252,21 @@ export async function collectCoverageFacts({ coverageFile, targets = [] } = {})
     return { facts, evaluated, notEvaluated, measured: false };
   }
 
+  // A non-empty object that matches no known shape is not a coverage report at
+  // all. Feeding it through the locator would answer "symbol not located" with
+  // a straight face — the confident wrong answer this producer exists to refuse.
+  const format = detectCoverageFormat(coverage);
+  if (format === null) {
+    notEvaluated.push(
+      notEvaluatedEntry(
+        KIND.TEST_COVERAGE,
+        '覆盖率数据不是可识别的报告形状（既无 c8/istanbul 的 fnMap/f，也无 coverage.py 的 functions）——' +
+          '它可能根本不是覆盖率文件，任何「符号未定位/未覆盖」的结论在此都不可信'
+      )
+    );
+    return { facts, evaluated, notEvaluated, measured: false };
+  }
+
   if (targets.length === 0) {
     notEvaluated.push(notEvaluatedEntry(KIND.TEST_COVERAGE, '没有指定要查询的符号（--symbol）'));
     return { facts, evaluated, notEvaluated, measured: false };
@@ -331,6 +383,7 @@ export async function collectCoverageFacts({ coverageFile, targets = [] } = {})
   evaluated.push({
     kind: KIND.TEST_COVERAGE,
     producer: 'euthyna-coverage',
+    format,
     count: facts.length
   });