agent-method 1.5.12

package/lib/cli/deps.js

@@ -0,0 +1,234 @@
+/** wwa deps — dependency graph visualization and analysis. */
+
+import { resolve } from "node:path";
+import { findOrphans } from "../dependencies.js";
+import { loadDocGraph } from "../boundaries.js";
+import { printCliReport, writeLastRunSummary } from "./report-helpers.js";
+
+export function register(program) {
+  program
+    .command("deps [directory]")
+    .description("Show document dependency graph from doc-tokens.yaml")
+    .option("--full", "Show all nodes and edges")
+    .option("--orphans", "Show only disconnected nodes")
+    .option("--path <from-to>", "Show dependency chain between two files (from:to)")
+    .option("--type <type>", "Filter edges by type (cascades_to, reads_from, seeds, validates)")
+    .option("--cross-boundary", "Show edges crossing internal/release boundary")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const docGraph = await loadDocGraph(d);
+      if (!docGraph) {
+        console.log("\n  No dependency graph found in token registry.");
+        console.log("  Run `wwa init` or complete brownfield onboarding to generate one.\n");
+        return;
+      }
+
+      const nodes = docGraph.nodes || [];
+      const edges = docGraph.edges || [];
+
+      // Filter edges by type if requested
+      const filteredEdges = opts.type
+        ? edges.filter((e) => e.type === opts.type)
+        : edges;
+
+      if (opts.json) {
+        const output = {
+          lastScan: docGraph.last_scan || null,
+          defaultsApplied: docGraph.defaults_applied || null,
+          nodes,
+          edges: filteredEdges,
+          orphans: findOrphans(docGraph),
+        };
+        if (opts.path) {
+          const [from, to] = opts.path.split(":");
+          output.chain = findChain(nodes, edges, from, to);
+        }
+        console.log(JSON.stringify(output, null, 2));
+        return;
+      }
+
+      if (opts.orphans) {
+        const orphans = findOrphans(docGraph);
+        console.log(`\n  Orphan nodes (${orphans.length}):\n`);
+        if (orphans.length === 0) {
+          console.log("    All nodes have at least one edge.");
+        } else {
+          for (const o of orphans) {
+            const node = nodes.find((n) => n.path === o);
+            console.log(`    - ${o}${node?.role ? ` — ${node.role}` : ""}`);
+          }
+        }
+        console.log("");
+        return;
+      }
+
+      if (opts.crossBoundary) {
+        const { loadBoundaries, isInternal, isRelease } = await import("../boundaries.js");
+        const bounds = await loadBoundaries(d);
+        const crossEdges = edges.filter((e) => {
+          const fromInt = isInternal(e.from, bounds);
+          const fromRel = isRelease(e.from, bounds);
+          const toInt = isInternal(e.to, bounds);
+          const toRel = isRelease(e.to, bounds);
+          return (fromInt && toRel) || (fromRel && toInt);
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify({ crossBoundaryEdges: crossEdges }, null, 2));
+          return;
+        }
+
+        console.log(`\n  Cross-boundary edges (${crossEdges.length}):\n`);
+        if (crossEdges.length === 0) {
+          console.log("    No edges cross the internal/release boundary.");
+        } else {
+          for (const e of crossEdges) {
+            const fromZone = isInternal(e.from, bounds) ? "internal" : "release";
+            const toZone = isInternal(e.to, bounds) ? "internal" : "release";
+            console.log(`    ${e.from} [${fromZone}] —[${e.type}]→ ${e.to} [${toZone}]`);
+          }
+        }
+        console.log("");
+        return;
+      }
+
+      if (opts.path) {
+        const [from, to] = opts.path.split(":");
+        if (!from || !to) {
+          console.error("  Use --path from:to format (e.g. --path STATE.md:ROADMAP.md)");
+          return;
+        }
+        const chain = findChain(nodes, edges, from, to);
+        console.log(`\n  Dependency chain: ${from} → ${to}\n`);
+        if (chain.length === 0) {
+          console.log("    No path found between these nodes.");
+        } else {
+          for (let i = 0; i < chain.length; i++) {
+            const step = chain[i];
+            if (i < chain.length - 1) {
+              const edge = edges.find(
+                (e) => e.from === step && e.to === chain[i + 1]
+              );
+              const edgeType = edge ? ` —[${edge.type}]→ ` : " → ";
+              console.log(`    ${i + 1}. ${step}${edgeType}`);
+            } else {
+              console.log(`    ${i + 1}. ${step}`);
+            }
+          }
+        }
+        console.log("");
+        return;
+      }
+
+      // Default: summary view
+      const orphans = findOrphans(docGraph);
+      const summary = [
+        `${nodes.length} nodes, ${edges.length} edges.`,
+        `${orphans.length} orphan(s).`,
+        opts.full ? "Full node list shown below." : "Run wwa deps --full for all nodes.",
+      ].join(" ");
+      const inputRef = `directory=${directory}`;
+      printCliReport({ command: "deps", inputRef, summary });
+      console.log("  Detail — Document Dependency Graph\n");
+      console.log(`  Last scan: ${docGraph.last_scan || "unknown"}`);
+      console.log(`  Defaults: ${docGraph.defaults_applied || "none"}`);
+      console.log(`  Nodes: ${nodes.length}  Edges: ${edges.length}`);
+      console.log(`  Orphans: ${orphans.length}`);
+
+      // Edge type breakdown
+      const byType = {};
+      for (const e of edges) {
+        byType[e.type] = (byType[e.type] || 0) + 1;
+      }
+      if (Object.keys(byType).length > 0) {
+        console.log(`\n  Edge types:`);
+        for (const [type, count] of Object.entries(byType).sort()) {
+          console.log(`    ${type}: ${count}`);
+        }
+      }
+
+      if (opts.full) {
+        // Group nodes by category
+        const byCategory = {};
+        for (const n of nodes) {
+          const cat = n.category || "unknown";
+          if (!byCategory[cat]) byCategory[cat] = [];
+          byCategory[cat].push(n);
+        }
+
+        console.log("");
+        for (const [cat, catNodes] of Object.entries(byCategory).sort()) {
+          console.log(`  [${cat}]`);
+          for (const n of catNodes) {
+            const outgoing = filteredEdges
+              .filter((e) => e.from === n.path)
+              .map((e) => `→ ${e.to} (${e.type})`);
+            console.log(`    ${n.path} — ${n.role}`);
+            for (const a of outgoing) {
+              console.log(`      ${a}`);
+            }
+          }
+        }
+      }
+
+      console.log("");
+      writeLastRunSummary(d, { command: "deps", inputRef, summary });
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** BFS to find shortest path between two nodes, searching forward then reverse edges. */
+function findChain(nodes, edges, from, to) {
+  const nodePaths = new Set(nodes.map((n) => n.path));
+  if (!nodePaths.has(from) || !nodePaths.has(to)) return [];
+
+  // Build adjacency (forward: from → to)
+  const fwd = {};
+  for (const p of nodePaths) fwd[p] = [];
+  for (const e of edges) {
+    if (fwd[e.from]) fwd[e.from].push(e.to);
+  }
+
+  // BFS forward
+  const visited = new Set([from]);
+  const queue = [[from]];
+  while (queue.length > 0) {
+    const path = queue.shift();
+    const current = path[path.length - 1];
+    if (current === to) return path;
+    for (const next of fwd[current] || []) {
+      if (!visited.has(next)) {
+        visited.add(next);
+        queue.push([...path, next]);
+      }
+    }
+  }
+
+  // BFS reverse (follow edges backwards: to → from)
+  const rev = {};
+  for (const p of nodePaths) rev[p] = [];
+  for (const e of edges) {
+    if (rev[e.to]) rev[e.to].push(e.from);
+  }
+  const visited2 = new Set([from]);
+  const queue2 = [[from]];
+  while (queue2.length > 0) {
+    const path = queue2.shift();
+    const current = path[path.length - 1];
+    if (current === to) return path;
+    for (const next of rev[current] || []) {
+      if (!visited2.has(next)) {
+        visited2.add(next);
+        queue2.push([...path, next]);
+      }
+    }
+  }
+
+  return [];
+}

package/lib/cli/digest.js

@@ -0,0 +1,73 @@
+/** wwa digest — show management digest and project health. */
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { printCliReport, writeLastRunSummary } from "./report-helpers.js";
+
+export function register(program) {
+  program
+    .command("digest [directory]")
+    .description("Show management digest from Management/DIGEST.md")
+    .option("--status", "Show Management/STATUS.md instead of digest")
+    .option("--json", "Output as JSON")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const digestPath = join(d, "Management", "DIGEST.md");
+      const statusPath = join(d, "Management", "STATUS.md");
+
+      const target = opts.status ? statusPath : digestPath;
+      const label = opts.status ? "STATUS" : "DIGEST";
+
+      if (!existsSync(target)) {
+        // Try to synthesize from SUMMARY.md or STATE.md
+        const summaryPath = join(d, "SUMMARY.md");
+        const statePath = join(d, "STATE.md");
+
+        if (opts.json) {
+          console.log(
+            JSON.stringify(
+              {
+                error: `Management/${label}.md not found`,
+                hasSummary: existsSync(summaryPath),
+                hasState: existsSync(statePath),
+              },
+              null,
+              2
+            )
+          );
+          return;
+        }
+
+        console.log(`\n  Management/${label}.md not found.\n`);
+        if (existsSync(summaryPath) || existsSync(statePath)) {
+          console.log("  Available alternatives:");
+          if (existsSync(summaryPath))
+            console.log("    - SUMMARY.md (session audit trail)");
+          if (existsSync(statePath))
+            console.log("    - STATE.md (current position + decisions)");
+        }
+        console.log(
+          "\n  To get management reports, use the starter or full template tier:" +
+            "\n    wwa init <type>\n"
+        );
+        return;
+      }
+
+      const content = readFileSync(target, "utf-8");
+
+      if (opts.json) {
+        console.log(JSON.stringify({ file: target, content }, null, 2));
+        return;
+      }
+
+      const lineCount = content.split("\n").length;
+      const summary = `Management/${label}.md: ${lineCount} lines. Project health and digest below.`;
+      const inputRef = `directory=${directory}, source=${label}`;
+      printCliReport({ command: "digest", inputRef, summary });
+      console.log("  Detail\n");
+      console.log(content);
+      writeLastRunSummary(d, { command: "digest", inputRef, summary });
+    });
+}