@cyning/harness 1.0.2 → 2.0.0

package/examples/demo_checkout/graph.json

@@ -0,0 +1,111 @@
+{
+  "schema_version": "graph_v2",
+  "freeze_id": "TECH_GRAPH_S2_FREEZE_20260519_V2_3",
+  "generated_at": "2026-06-17T00:00:00Z",
+  "graphs": [
+    {
+      "id": "00_main",
+      "title": "Harness P0 金样流程",
+      "source_yaml_path": "00_main.graph.yaml"
+    }
+  ],
+  "nodes": [
+    {
+      "graph_id": "00_main",
+      "id": "DONE",
+      "label": "P0 通过"
+    },
+    {
+      "graph_id": "00_main",
+      "id": "EXEC",
+      "label": "30 执行帽"
+    },
+    {
+      "graph_id": "00_main",
+      "id": "GATE",
+      "label": "gate-check"
+    },
+    {
+      "graph_id": "00_main",
+      "id": "INIT",
+      "label": "harness init"
+    },
+    {
+      "graph_id": "00_main",
+      "id": "R1",
+      "label": "22 审核帽"
+    },
+    {
+      "graph_id": "00_main",
+      "id": "START",
+      "label": "空 Git 仓"
+    },
+    {
+      "graph_id": "00_main",
+      "id": "TASK",
+      "label": "task_demo_p0_golden"
+    }
+  ],
+  "edges": [
+    {
+      "anchors": [],
+      "from": "EXEC",
+      "graph_id": "00_main",
+      "label": "40 自检",
+      "mark": "->",
+      "sync": true,
+      "to": "DONE",
+      "type": "depends_on"
+    },
+    {
+      "anchors": [],
+      "from": "GATE",
+      "graph_id": "00_main",
+      "label": "exit 0",
+      "mark": "->",
+      "sync": true,
+      "to": "EXEC",
+      "type": "depends_on"
+    },
+    {
+      "anchors": [],
+      "from": "INIT",
+      "graph_id": "00_main",
+      "label": "复制金样 task",
+      "mark": "->",
+      "sync": true,
+      "to": "TASK",
+      "type": "depends_on"
+    },
+    {
+      "anchors": [],
+      "from": "R1",
+      "graph_id": "00_main",
+      "label": "HG-AUDIT-R1 approved",
+      "mark": "->",
+      "sync": true,
+      "to": "GATE",
+      "type": "depends_on"
+    },
+    {
+      "anchors": [],
+      "from": "START",
+      "graph_id": "00_main",
+      "label": "install.sh",
+      "mark": "->",
+      "sync": true,
+      "to": "INIT",
+      "type": "depends_on"
+    },
+    {
+      "anchors": [],
+      "from": "TASK",
+      "graph_id": "00_main",
+      "label": "10 → 22",
+      "mark": "->",
+      "sync": true,
+      "to": "R1",
+      "type": "depends_on"
+    }
+  ]
+}

package/lib/cli.js

@@ -12,9 +12,23 @@ import { runBash } from './run.js';
 import { checkTaskFile } from './task.js';
 import { auditTarget } from './audit.js';
 import { mergePackageScripts } from './package-scripts.js';
+import {
+  allGraphIds,
+  checkGraph,
+  compileGraph,
+  GraphYamlError,
+  yamlPathFor,
+} from './graph-yaml.js';
+import {
+  buildSnapshot,
+  checkAxioms,
+  ingestRepoIdempotent,
+  loadEvents,
+  writeSnapshot,
+} from './graph-hgm.js';
 
-function usage() {
-  console.log(`@cyning/harness · cyning-harness CLI (v1.0.2)
+function usage(version = 'unknown') {
+  console.log(`@cyning/harness · cyning-harness CLI (v${version})
 
 用法:
   npx @cyning/harness --version | -V
@@ -27,6 +41,13 @@ function usage() {
   npx @cyning/harness verify [--target PATH] [--task FILE] [--graph]
   npx @cyning/harness sync index [--target PATH]
   npx @cyning/harness task check --file PATH [--no-circular] [--registry DIR]...
+  npx @cyning/harness graph yaml compile --graph-id ID [--input DIR] [--output FILE]
+  npx @cyning/harness graph yaml check --graph-id ID [--input DIR] [--graph-json FILE]
+  npx @cyning/harness graph yaml compile --all [--input DIR]
+  npx @cyning/harness graph yaml check --all [--input DIR] [--graph-json FILE]
+  npx @cyning/harness graph ingest [--target PATH] [--actor ACTOR] [--dry-run]
+  npx @cyning/harness graph snapshot [--target PATH]
+  npx @cyning/harness graph axioms check [--target PATH] [--json]
 
 说明:
   init        首次接入 · 内部调用 wizard/install.sh + harness-sync.sh apply
@@ -37,6 +58,10 @@ function usage() {
   verify      30 前聚合：gate-check + audit D5 + S5 warn + 可选 --graph
   sync index  生成 .cyning-harness/invoke_index.json
   task check  校验 task.harness.v1.json sidecar · --no-circular 检测 depends_on 环
+  graph yaml    Inform 图谱 YAML 编译 / 校验（v1.1+）
+  graph ingest  扫描业务仓 → 追加 HGM 事件（v2.0+）
+  graph snapshot 事件重放 → graph/snapshot.json（v2.0+）
+  graph axioms  跑 HGM 公理检查（v2.0+）
 
 环境:
   CYNING_HARNESS   覆盖产品包根（维护者本地 clone 开发）
@@ -59,7 +84,7 @@ export async function runCli(argv) {
   const pkgVersion = resolvePackageVersion(harnessRoot);
 
   if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
-    usage();
+    usage(pkgVersion);
     return;
   }
 
@@ -102,6 +127,10 @@ export async function runCli(argv) {
     await cmdTask(rest);
     return;
   }
+  if (cmd === 'graph') {
+    await cmdGraph(rest);
+    return;
+  }
 
   const err = new Error(`未知命令: ${cmd}\n`);
   err.exitCode = 1;
@@ -495,3 +524,247 @@ async function cmdTask(args) {
     console.log('depends_on: acyclic');
   }
 }
+
+async function cmdGraph(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`用法: npx @cyning/harness graph <子命令> [选项]
+
+子命令:
+  graph yaml compile --graph-id ID [--input DIR] [--output FILE]
+  graph yaml compile --all [--input DIR]
+  graph yaml check --graph-id ID [--input DIR] [--graph-json FILE]
+  graph yaml check --all [--input DIR] [--graph-json FILE]
+  graph ingest [--target PATH] [--actor ACTOR] [--dry-run]
+  graph snapshot [--target PATH]
+  graph axioms check [--target PATH] [--json]
+
+选项:
+  --input DIR         graph yaml 输入目录（默认 target/docs/_tech_graph）
+  --output FILE       graph yaml 输出 MD 路径（仅单图 compile）
+  --graph-json FILE   graph yaml 对比的 graph.json 路径
+  --target PATH       业务仓根目录（默认当前目录）
+  --actor ACTOR       ingest actor（默认 system）
+  --dry-run           ingest 仅输出事件数 · 不写入
+  --json              axioms 输出 JSON
+`);
+    return;
+  }
+
+  const [sub, ...subRest] = args;
+  if (sub === 'yaml') {
+    await cmdGraphYaml(subRest);
+    return;
+  }
+  if (sub === 'ingest') {
+    await cmdGraphIngest(subRest);
+    return;
+  }
+  if (sub === 'snapshot') {
+    await cmdGraphSnapshot(subRest);
+    return;
+  }
+  if (sub === 'axioms') {
+    await cmdGraphAxioms(subRest);
+    return;
+  }
+
+  const err = new Error(`graph 子命令未知: ${sub ?? '(空)'}`);
+  err.exitCode = 1;
+  throw err;
+}
+
+async function cmdGraphYaml(args) {
+  const [action, ...actionRest] = args;
+  if (action !== 'compile' && action !== 'check') {
+    const err = new Error(`graph yaml 动作未知: ${action ?? '(空)'}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const all = actionRest.includes('--all');
+  let rest = actionRest.filter((a) => a !== '--all');
+
+  const { value: graphId, rest: r1 } = takeOption(rest, '--graph-id');
+  rest = r1;
+  const { value: inputArg, rest: r2 } = takeOption(rest, '--input');
+  rest = r2;
+  const { value: outputArg, rest: r3 } = takeOption(rest, '--output');
+  rest = r3;
+  const { value: graphJsonArg, rest: r4 } = takeOption(rest, '--graph-json');
+  rest = r4;
+
+  if (rest.length > 0) {
+    const err = new Error(`graph yaml ${action} 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  if (!all && !graphId) {
+    const err = new Error('须指定 --graph-id ID 或 --all');
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const cwd = process.cwd();
+  const inputRoot = inputArg ? path.resolve(cwd, inputArg) : path.resolve(cwd, 'docs', '_tech_graph');
+  const graphJsonPath = graphJsonArg
+    ? path.resolve(cwd, graphJsonArg)
+    : path.join(inputRoot, 'graph.json');
+
+  try {
+    if (action === 'compile') {
+      if (all) {
+        const ids = allGraphIds(inputRoot);
+        if (ids.length === 0) {
+          console.log('未找到 *.graph.yaml');
+          return;
+        }
+        for (const id of ids) {
+          const out = compileGraph(id, inputRoot);
+          console.log(`Generated: ${out}`);
+        }
+      } else {
+        const out = compileGraph(graphId, inputRoot, outputArg ? path.resolve(cwd, outputArg) : null);
+        console.log(`Generated: ${out}`);
+      }
+      return;
+    }
+
+    // action === 'check'
+    if (all) {
+      const ids = allGraphIds(inputRoot);
+      if (ids.length === 0) {
+        console.log('未找到 *.graph.yaml');
+        return;
+      }
+      let failed = false;
+      for (const id of ids) {
+        const result = checkGraph(id, inputRoot, graphJsonPath);
+        if (result.ok) {
+          console.log(`OK: ${id}`);
+        } else {
+          failed = true;
+          console.error(`ERROR: ${id}\n${result.diff}`);
+        }
+      }
+      if (failed) {
+        const err = new Error('graph yaml check 发现差异');
+        err.exitCode = 1;
+        throw err;
+      }
+      return;
+    }
+
+    const result = checkGraph(graphId, inputRoot, graphJsonPath);
+    if (result.ok) {
+      console.log(`OK: YAML matches graph.json ${graphId} slice`);
+    } else {
+      console.error(`ERROR: Diff detected for ${graphId}:\n${result.diff}`);
+      const err = new Error('graph yaml check 发现差异');
+      err.exitCode = 1;
+      throw err;
+    }
+  } catch (err) {
+    if (err instanceof GraphYamlError) {
+      console.error(err.message);
+      const exitErr = new Error('');
+      exitErr.exitCode = 1;
+      throw exitErr;
+    }
+    throw err;
+  }
+}
+
+async function cmdGraphIngest(args) {
+  let rest = args;
+  const { value: targetArg, rest: r1 } = takeOption(rest, '--target');
+  rest = r1;
+  const { value: actor, rest: r2 } = takeOption(rest, '--actor');
+  rest = r2;
+  const dryRun = rest.includes('--dry-run');
+  rest = rest.filter((a) => a !== '--dry-run');
+
+  if (rest.length > 0) {
+    const err = new Error(`graph ingest 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const result = ingestRepoIdempotent(target, {
+    actor: actor || 'system',
+    source: 'cli',
+    dryRun,
+  });
+
+  console.log(`目标: ${target}`);
+  console.log(`新事件: ${result.count}`);
+  console.log(`跳过（已存在）: ${result.skipped}`);
+  if (dryRun) {
+    console.log('mode: dry-run（未写入）');
+  }
+}
+
+async function cmdGraphSnapshot(args) {
+  let rest = args;
+  const { value: targetArg, rest: r1 } = takeOption(rest, '--target');
+  rest = r1;
+
+  if (rest.length > 0) {
+    const err = new Error(`graph snapshot 未知参数: ${rest.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const events = loadEvents(target);
+  const snapshot = buildSnapshot(events);
+  const out = writeSnapshot(target, snapshot);
+
+  console.log(`events: ${events.length}`);
+  console.log(`nodes: ${Object.keys(snapshot.nodes).length}`);
+  console.log(`edges: ${snapshot.edges.length}`);
+  console.log(`snapshot: ${out}`);
+}
+
+async function cmdGraphAxioms(args) {
+  const [sub, ...rest] = args;
+  if (sub !== 'check') {
+    const err = new Error(`graph axioms 动作未知: ${sub ?? '(空)'}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  let remaining = rest;
+  const { value: targetArg, rest: r1 } = takeOption(remaining, '--target');
+  remaining = r1;
+  const json = remaining.includes('--json');
+  remaining = remaining.filter((a) => a !== '--json');
+
+  if (remaining.length > 0) {
+    const err = new Error(`graph axioms check 未知参数: ${remaining.join(' ')}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const target = resolveTarget(process.cwd(), targetArg);
+  const events = loadEvents(target);
+  const snapshot = buildSnapshot(events);
+  const result = checkAxioms(snapshot);
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`axioms: ${result.ok ? 'PASS' : 'FAIL'}`);
+    console.log(`violations: ${result.violations.length}`);
+    for (const v of result.violations) {
+      console.log(`  [${v.axiom}/${v.severity}] ${v.message}`);
+    }
+  }
+
+  if (!result.ok) {
+    const err = new Error('HGM axioms 未通过');
+    err.exitCode = 2;
+    throw err;
+  }
+}