@cyning/harness 1.0.2 → 1.1.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,16 @@ 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';
 
-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 +34,10 @@ 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]
 
 说明:
   init        首次接入 · 内部调用 wizard/install.sh + harness-sync.sh apply
@@ -37,6 +48,7 @@ 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+）
 
 环境:
   CYNING_HARNESS   覆盖产品包根（维护者本地 clone 开发）
@@ -59,7 +71,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 +114,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 +511,130 @@ 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 yaml compile|check [选项]
+
+子命令:
+  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]
+
+选项:
+  --input DIR         输入目录（默认 target/docs/_tech_graph）
+  --output FILE       输出 MD 路径（仅单图 compile）
+  --graph-json FILE   对比的 graph.json 路径（默认 input/graph.json）
+  --all               处理目录下所有 *.graph.yaml
+`);
+    return;
+  }
+
+  const [sub, ...subRest] = args;
+  if (sub !== 'yaml') {
+    const err = new Error(`graph 子命令未知: ${sub ?? '(空)'}`);
+    err.exitCode = 1;
+    throw err;
+  }
+
+  const [action, ...actionRest] = subRest;
+  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;
+  }
+}