loopgraph 0.2.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@
 
 以结构化行为模型(Feature / Flow / Loop / Junction / Scenario(GWT) / Evidence)为规范事实源,把目标仓库的代码、测试与可观测信号当作投影与证据:
 
-- **确定性增量 CI(永不调 LLM)**:T0 检查(schema / 引用完整性 / 图无环 / 锚点存在性)、canonical-writer 不变量扫描(纯 AST)、实现事实对账、`--diff` 增量、内容寻址共享缓存(跨 worktree)。全量亚秒级。
+- **确定性增量 CI(永不调 LLM)**:T0 检查(schema / 引用完整性 / 图无环 / 锚点存在性)、canonical-writer 不变量扫描(纯 AST)、实现事实对账、模型侧覆盖报告、`--diff` 增量、内容寻址共享缓存(跨 worktree)。全量亚秒级。
 - **发现靠 LLM,防腐靠引擎**:随附 agent 提示词套件(四遍扫描:假设都是 loop → 三判据证伪 → 组合 → trace 升维),由 coding agent 离线建模;引擎负责锚点核实与漂移拦截。
 - **MCP 查询 + file side-channel**:给 agent 提供任务相关的模型切片(impact / plan / scenario / evidence / matrix),替代全量阅读 spec。
 
@@ -16,6 +16,7 @@
 npx loopgraph init          # 在目标仓库生成 model/ 骨架 + .loopgraph/agent/ 指令套件
 npx loopgraph check . --repo-root . --strict-anchors   # T0 门禁(确定性,秒级)
 npx loopgraph reconcile . --repo-root .                # 实现信号 vs 模型登记对账(advisory)
+npx loopgraph coverage .                               # 模型侧覆盖:多少 loop 真被锚点/场景绑住(advisory)
 npx loopgraph snapshot . --repo-root .                 # nightly 全量快照 + 漂移报告(永不进门禁)
 npx loopgraph impact <loop-id> .                       # 改这里会牵动什么
 npx loopgraph mcp .                                    # stdio MCP server(给 agent 用)

package/dist/cli/commands/coverage.d.ts

@@ -0,0 +1,31 @@
+import { type Coverage } from "../../query/coverage.js";
+export type CoverageResult = {
+    ran: true;
+    coverage: Coverage;
+} | {
+    ran: false;
+    skippedReason: string;
+};
+/**
+ * `loopgraph coverage`: report how much of the model is directly bound to
+ * anchors/scenarios (see src/query/coverage.ts for why "directly").
+ *
+ * This command shares an advisory CI job with `check` — which is the command
+ * whose job it is to FAIL on a broken model — so it never exits non-zero and
+ * never refuses to report just because `check` will also complain. But "don't
+ * fail" must not become "report a number that isn't true:
+ *
+ * - Model dir missing/unreadable → `ran: false`. Reported as a skip, never as
+ *   "0% coverage", which reads as a real (and alarming) measurement of a model
+ *   that simply wasn't found.
+ * - EVERY file failed to parse → also `ran: false`, for the same reason. The
+ *   dir existing doesn't make `0/0` a measurement. (`findYamlFiles` only throws
+ *   on readdir errors; per-file YAML/schema failures land in `parseErrors` and
+ *   would otherwise sail straight past the catch below.)
+ * - SOME files failed to parse → report, but carry the count through so the
+ *   output can say so. Partial loading does NOT simply "depress coverage":
+ *   dropping unanchored loops shrinks the denominator and can push the reported
+ *   percentage UP (measured: one broken file moved 27/67=40% to 26/57=46%).
+ */
+export declare function runCoverage(targetDir: string): Promise<CoverageResult>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/cli/commands/coverage.js

@@ -0,0 +1,42 @@
+import { join } from "node:path";
+import { loadModel } from "../../loader/load-model.js";
+import { computeCoverage } from "../../query/coverage.js";
+/**
+ * `loopgraph coverage`: report how much of the model is directly bound to
+ * anchors/scenarios (see src/query/coverage.ts for why "directly").
+ *
+ * This command shares an advisory CI job with `check` — which is the command
+ * whose job it is to FAIL on a broken model — so it never exits non-zero and
+ * never refuses to report just because `check` will also complain. But "don't
+ * fail" must not become "report a number that isn't true:
+ *
+ * - Model dir missing/unreadable → `ran: false`. Reported as a skip, never as
+ *   "0% coverage", which reads as a real (and alarming) measurement of a model
+ *   that simply wasn't found.
+ * - EVERY file failed to parse → also `ran: false`, for the same reason. The
+ *   dir existing doesn't make `0/0` a measurement. (`findYamlFiles` only throws
+ *   on readdir errors; per-file YAML/schema failures land in `parseErrors` and
+ *   would otherwise sail straight past the catch below.)
+ * - SOME files failed to parse → report, but carry the count through so the
+ *   output can say so. Partial loading does NOT simply "depress coverage":
+ *   dropping unanchored loops shrinks the denominator and can push the reported
+ *   percentage UP (measured: one broken file moved 27/67=40% to 26/57=46%).
+ */
+export async function runCoverage(targetDir) {
+    let load;
+    try {
+        load = await loadModel(join(targetDir, "model"));
+    }
+    catch (err) {
+        return { ran: false, skippedReason: err instanceof Error ? err.message : String(err) };
+    }
+    const parseErrors = load.parseErrors.length;
+    if (parseErrors > 0 && load.entries.length === 0) {
+        return {
+            ran: false,
+            skippedReason: `all ${parseErrors} model file(s) failed to parse — run "loopgraph check" for the errors`,
+        };
+    }
+    return { ran: true, coverage: computeCoverage(load.graph, parseErrors) };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/cli/commands/snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { ImplementationFact, SignalKind } from "../../adapters/agenthub/extract.js";
+import type { Adapter, ImplementationFact, SignalKind } from "../../adapters/types.js";
 import { type Inv1CheckResult } from "../../validate/inv1/check.js";
 import type { T0Result } from "../../validate/types.js";
 export declare const SNAPSHOT_SCHEMA_VERSION: 1;
@@ -98,6 +98,8 @@ export interface SnapshotOptions {
     repoRoot?: string | undefined;
     /** Machine cache dir for facts (B3); null disables. Default: the shared cache. */
     cacheDir?: string | null | undefined;
+    /** The adapter supplying the facts (default: agenthub). Threaded to runFacts. */
+    adapter?: Adapter | undefined;
     /** Injected for reproducibility; defaults to now. */
     generatedAt?: string | undefined;
     /** Injected for tests; defaults to `git rev-parse HEAD` of repoRoot. */

package/dist/cli/run.js

@@ -2,11 +2,13 @@ import { runFacts } from "../adapters/agenthub/facts.js";
 import { adapterNames, getAdapter } from "../adapters/registry.js";
 import { loadModel } from "../loader/load-model.js";
 import { startMcpServer } from "../mcp/server.js";
+import { formatCoverage } from "../query/coverage.js";
 import { runQuery } from "../query/run-query.js";
 import { inv1ViolationsFrom } from "../validate/inv1/check.js";
 import { reconcileFacts } from "../validate/unregistered.js";
 import { parseFlags } from "./args.js";
 import { runCheck } from "./commands/check.js";
+import { runCoverage } from "./commands/coverage.js";
 import { runImport } from "./commands/import.js";
 import { runInit } from "./commands/init.js";
 import { runInspect } from "./commands/inspect.js";
@@ -30,6 +32,7 @@ const USAGE = "usage: loopgraph <init|import|check> [dir] [--adapter name] [--re
     "       loopgraph <impact|plan|scenario|evidence|matrix> <id> [dir]\n" +
     "       loopgraph mcp [dir]   # start the stdio MCP server\n" +
     "       loopgraph facts [repo] [--adapter name]   # extract implementation facts (default adapter: agenthub)\n" +
+    "       loopgraph coverage [dir]   # model-side coverage: how much of the model is anchored\n" +
     "       loopgraph snapshot [dir] --repo-root path [--out file] [--drift prior.json]   # T2 nightly scan artifact";
 /**
  * Reads a `--flag value` string option. Returns `{ error }` when the flag
@@ -48,6 +51,27 @@ function readStringFlag(flags, name) {
         return { value: raw };
     return { value: undefined, error: `--${name} requires a value` };
 }
+/**
+ * Resolve `--adapter <name>` for the fact-extracting commands (facts /
+ * reconcile / snapshot). Returns `{}` (no `adapter` key) when the flag is absent
+ * — the caller then falls back to the default adapter — or `{ error: true }`
+ * after reporting a malformed flag / unknown adapter name.
+ */
+function resolveAdapterFlag(flags, io) {
+    const f = readStringFlag(flags, "adapter");
+    if (f.error) {
+        io.error(`${f.error}. ${USAGE}`);
+        return { error: true };
+    }
+    if (f.value === undefined)
+        return {}; // no --adapter → caller uses the default
+    const adapter = getAdapter(f.value);
+    if (!adapter) {
+        io.error(`unknown adapter "${f.value}" (available: ${adapterNames().join(", ")})`);
+        return { error: true };
+    }
+    return { adapter };
+}
 /**
  * Core dispatch, factored out of the process entry point so tests can
  * drive it in-process (real filesystem via temp dirs, no subprocess
@@ -217,22 +241,12 @@ export async function run(argv, io) {
             // root, defaulting to cwd). `--no-cache` disables the B3 content cache.
             // `--adapter <name>` selects the target stack's adapter (default agenthub).
             const repo = positionals[0] ?? process.cwd();
-            const adapterFlag = readStringFlag(flags, "adapter");
-            if (adapterFlag.error) {
-                io.error(`${adapterFlag.error}. ${USAGE}`);
+            const factsAdapter = resolveAdapterFlag(flags, io);
+            if ("error" in factsAdapter)
                 return 1;
-            }
-            let adapter;
-            if (adapterFlag.value !== undefined) {
-                adapter = getAdapter(adapterFlag.value);
-                if (!adapter) {
-                    io.error(`unknown adapter "${adapterFlag.value}" (available: ${adapterNames().join(", ")})`);
-                    return 1;
-                }
-            }
             const result = await runFacts(repo, {
                 ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
-                ...(adapter ? { adapter } : {}),
+                ...(factsAdapter.adapter ? { adapter: factsAdapter.adapter } : {}),
             });
             if (!result.ran) {
                 io.log(`⚠ facts extraction skipped: ${result.skippedReason}`);
@@ -264,8 +278,14 @@ export async function run(argv, io) {
                 io.error(`reconcile needs --repo-root <repo>. ${USAGE}`);
                 return 1;
             }
+            const reconcileAdapter = resolveAdapterFlag(flags, io);
+            if ("error" in reconcileAdapter)
+                return 1;
             const model = await loadModel(`${targetDir}/model`);
-            const factsResult = await runFacts(repoRootFlag.value, flags["no-cache"] === true ? { cacheDir: null } : {});
+            const factsResult = await runFacts(repoRootFlag.value, {
+                ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
+                ...(reconcileAdapter.adapter ? { adapter: reconcileAdapter.adapter } : {}),
+            });
             if (!factsResult.ran) {
                 io.log(`⚠ reconcile skipped: ${factsResult.skippedReason}`);
                 return 0;
@@ -285,6 +305,20 @@ export async function run(argv, io) {
                 `${coveredFiles.length} model-covered file(s)`);
             return flags.strict === true && unregistered.length > 0 ? 1 : 0;
         }
+        case "coverage": {
+            // Model-side coverage (advisory, always exit 0). The counterweight to
+            // `reconcile`: that command measures code→model, this one measures how
+            // much of the model is itself anchored. A report carrying only reconcile
+            // reads as "covered" on a model that only covers one flow.
+            const result = await runCoverage(targetDir);
+            if (!result.ran) {
+                io.log(`⚠ coverage skipped: ${result.skippedReason}`);
+                return 0;
+            }
+            for (const line of formatCoverage(result.coverage))
+                io.log(line);
+            return 0;
+        }
         case "snapshot": {
             // T2 nightly full-scan artifact (Proposal 006 D2). NEVER a PR gate
             // (001 §6): this always exits 0 — drift is reported, not failed on.
@@ -297,9 +331,13 @@ export async function run(argv, io) {
                     return 1;
                 }
             }
+            const snapshotAdapter = resolveAdapterFlag(flags, io);
+            if ("error" in snapshotAdapter)
+                return 1;
             const snapshot = await runSnapshot(targetDir, {
                 repoRoot: repoRootFlag.value,
                 ...(flags["no-cache"] === true ? { cacheDir: null } : {}),
+                ...(snapshotAdapter.adapter ? { adapter: snapshotAdapter.adapter } : {}),
             });
             io.log(renderSnapshotSummary(snapshot));
             if (driftFlag.value) {

package/dist/query/coverage.d.ts

@@ -0,0 +1,77 @@
+import type { ModelGraph } from "../loader/model-graph.js";
+/**
+ * Model-side coverage: how much of the model is actually bound to something
+ * checkable. This is the OPPOSITE direction from `reconcile`, which asks
+ * "does the code contain a route/queue/poller the model forgot to register?"
+ * — a whole-repo, code→model measure that reads near-100% on a model that
+ * covers one flow, because unregistered facts are the only thing it can see.
+ * Nothing in that number tells a reader how much of the MODEL is anchored,
+ * so a report carrying only `reconcile` invites "96% — looks covered".
+ *
+ * Every count here is DIRECT attachment (`Loop.anchors`, `Loop.scenarios`,
+ * `Junction.scenarios`). Resolving `applies_to` into the covered counts would
+ * defeat the point: one `owner_match` invariant matches every loop whose free-text
+ * `owner` contains the pattern, which silently flips large parts of the model to
+ * "covered" without any loop-specific behavior being written down. That number is
+ * still worth seeing, so it is reported on its own labelled line
+ * (`loopsOnlyViaSelector`) and never folded into `loopsWithScenarios`.
+ */
+export interface FlowCoverage {
+    id: string;
+    title: string;
+    /** Loops in `traverses` (guarded_by/references deliberately excluded — see computeCoverage). */
+    loops: number;
+    /** Of those, how many carry >=1 directly-attached scenario. */
+    loopsWithScenarios: number;
+}
+export interface Coverage {
+    loops: number;
+    loopsWithAnchors: number;
+    loopsWithScenarios: number;
+    /**
+     * Loops with no directly-attached scenario that are nonetheless selected by
+     * some scenario's `applies_to`. Reported separately so query-time selection
+     * can't masquerade as attached coverage — deliberately NOT split by selector
+     * kind: `nodes` names a loop explicitly and `owner_match` sweeps a package,
+     * but neither is written on the loop, which is the distinction this line draws.
+     */
+    loopsOnlyViaSelector: number;
+    /**
+     * Model files that failed to parse. Non-zero means every count here is a LOWER
+     * BOUND on a partially-loaded graph — critically, it can move the reported
+     * PERCENTAGES either way: dropping an unanchored loop shrinks the denominator
+     * and makes coverage look better (measured: one broken file took 27/67=40% to
+     * 26/57=46%). Silently reporting the higher number would make a command whose
+     * whole purpose is to stop over-reading coverage do exactly that, so this is
+     * surfaced in the output rather than left to `check` in the same job.
+     */
+    parseErrors: number;
+    junctions: number;
+    junctionsWithScenarios: number;
+    scenarios: number;
+    /** Scenarios with a non-empty `verified_by` (the rest are unverified by construction). */
+    scenariosVerified: number;
+    /** DISTINCT `verified_by` anchor strings — the real anti-rot surface, always <= the sum of references. */
+    uniqueTestAnchors: number;
+    flows: FlowCoverage[];
+}
+/**
+ * Per-flow coverage counts only `traverses`. `guarded_by` holds watchdog loops
+ * that cover a flow without sitting in its sequence, and `references` holds
+ * sub-flows — folding either in would let C1's coverage leak into every flow
+ * that C1 guards or references, which is precisely the "looks more covered than
+ * it is" failure this command exists to prevent.
+ *
+ * A loop traversed by several flows counts toward each of them. That is
+ * intentional: the question a flow row answers is "is THIS chain's behavior
+ * written down", and a shared loop genuinely is written down for both.
+ */
+export declare function computeCoverage(graph: ModelGraph, parseErrors?: number): Coverage;
+/**
+ * Plain-text report, one fact per line, shaped to drop into the same job
+ * summary as `check`/`reconcile` output. Flows with zero covered loops are
+ * listed explicitly rather than summarized as a count — "C4 会话复活: 0/3"
+ * is the line that stops a reader assuming the whole model is anchored.
+ */
+export declare function formatCoverage(coverage: Coverage): string[];
+//# sourceMappingURL=coverage.d.ts.map

package/dist/query/coverage.js

@@ -0,0 +1,84 @@
+import { scenarioApplies } from "./effective-constraints.js";
+/**
+ * Per-flow coverage counts only `traverses`. `guarded_by` holds watchdog loops
+ * that cover a flow without sitting in its sequence, and `references` holds
+ * sub-flows — folding either in would let C1's coverage leak into every flow
+ * that C1 guards or references, which is precisely the "looks more covered than
+ * it is" failure this command exists to prevent.
+ *
+ * A loop traversed by several flows counts toward each of them. That is
+ * intentional: the question a flow row answers is "is THIS chain's behavior
+ * written down", and a shared loop genuinely is written down for both.
+ */
+export function computeCoverage(graph, parseErrors = 0) {
+    const loops = [...graph.byKind.loop.values()];
+    const junctions = [...graph.byKind.junction.values()];
+    const scenarios = [...graph.byKind.scenario.values()];
+    const loopHasScenario = new Map(loops.map((loop) => [loop.id, loop.scenarios.length > 0]));
+    const anchors = new Set();
+    let scenariosVerified = 0;
+    for (const scenario of scenarios) {
+        if (scenario.verified_by.length > 0)
+            scenariosVerified += 1;
+        for (const anchor of scenario.verified_by)
+            anchors.add(anchor);
+    }
+    const loopsOnlyViaSelector = loops.filter((loop) => loop.scenarios.length === 0 &&
+        scenarios.some((scenario) => scenarioApplies(scenario, loop.id, graph))).length;
+    const flows = [...graph.byKind.flow.values()].map((flow) => ({
+        id: flow.id,
+        title: flow.title,
+        loops: flow.traverses.length,
+        // An id in `traverses` that resolves to no loop node is a dangling
+        // reference — T0's job to flag, not ours. It counts toward `loops` (the
+        // flow does claim to traverse it) but never toward covered, so a broken
+        // reference can only ever depress coverage, never inflate it.
+        loopsWithScenarios: flow.traverses.filter((id) => loopHasScenario.get(id) === true).length,
+    }));
+    return {
+        loops: loops.length,
+        loopsWithAnchors: loops.filter((loop) => loop.anchors.length > 0).length,
+        loopsWithScenarios: loops.filter((loop) => loop.scenarios.length > 0).length,
+        loopsOnlyViaSelector,
+        parseErrors,
+        junctions: junctions.length,
+        junctionsWithScenarios: junctions.filter((j) => j.scenarios.length > 0).length,
+        scenarios: scenarios.length,
+        scenariosVerified,
+        uniqueTestAnchors: anchors.size,
+        flows,
+    };
+}
+function pct(n, total) {
+    if (total === 0)
+        return "n/a";
+    return `${Math.round((n / total) * 100)}%`;
+}
+/**
+ * Plain-text report, one fact per line, shaped to drop into the same job
+ * summary as `check`/`reconcile` output. Flows with zero covered loops are
+ * listed explicitly rather than summarized as a count — "C4 会话复活: 0/3"
+ * is the line that stops a reader assuming the whole model is anchored.
+ */
+export function formatCoverage(coverage) {
+    const lines = [];
+    // First line, not a footnote: a reader who stops after the headline number
+    // must not walk away with a figure that a broken file silently moved.
+    if (coverage.parseErrors > 0) {
+        lines.push(`⚠ ${coverage.parseErrors} model file(s) failed to parse — every count below is a lower bound on a partial graph, and the percentages may read HIGHER than reality (run \`loopgraph check\` for the ids)`);
+    }
+    lines.push(`model coverage: ${coverage.loops} loop(s), ${coverage.junctions} junction(s), ${coverage.scenarios} scenario(s)`, `  loops with anchors:   ${coverage.loopsWithAnchors}/${coverage.loops} (${pct(coverage.loopsWithAnchors, coverage.loops)})`, `  loops with scenarios: ${coverage.loopsWithScenarios}/${coverage.loops} (${pct(coverage.loopsWithScenarios, coverage.loops)})`);
+    if (coverage.loopsOnlyViaSelector > 0) {
+        lines.push(`  (+ ${coverage.loopsOnlyViaSelector} loop(s) selected only via an applies_to selector — resolved at query time, not attached to the loop)`);
+    }
+    lines.push(`  junctions with scenarios: ${coverage.junctionsWithScenarios}/${coverage.junctions}`, `  scenarios verified_by:    ${coverage.scenariosVerified}/${coverage.scenarios}, ${coverage.uniqueTestAnchors} distinct test anchor(s)`);
+    if (coverage.flows.length > 0) {
+        lines.push("  per-flow (traversed loops with >=1 scenario):");
+        for (const flow of coverage.flows) {
+            const mark = flow.loopsWithScenarios === 0 && flow.loops > 0 ? " ← no behavior modeled" : "";
+            lines.push(`    ${flow.id} ${flow.title}: ${flow.loopsWithScenarios}/${flow.loops}${mark}`);
+        }
+    }
+    return lines;
+}
+//# sourceMappingURL=coverage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopgraph",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Model-driven engineering control system: behavioral model as spec source of truth, code/tests/observability as projections and evidence.",
   "type": "module",
   "license": "MIT",