agent-method 1.5.12

package/lib/cli/doc-review.js

@@ -0,0 +1,486 @@
+/** wwa doc-review — generate docs/internal/ registry from doc-tokens.yaml and DOCS-MAP.md. */
+
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { safeWriteFile } from "./helpers.js";
+import { resolveTokensPath, resolveDocsMapPath, resolveOutputDir } from "../boundaries.js";
+
+export function register(program) {
+  program
+    .command("doc-review [directory]")
+    .description(
+      "Generate docs/internal/ document registry (doc-registry.yaml + doc-registry.md)"
+    )
+    .option("--yaml-only", "Only generate doc-registry.yaml")
+    .option("--md-only", "Only generate doc-registry.md")
+    .option("--json", "Output registry data as JSON (no file write)")
+    .action(async (directory, opts) => {
+      directory = directory || ".";
+      const d = resolve(directory);
+
+      const data = await gatherRegistryData(d);
+
+      if (data.errors.length > 0) {
+        console.error("Cannot generate document registry:");
+        for (const e of data.errors) console.error(`  - ${e}`);
+        process.exit(1);
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+
+      const internalDir = await resolveOutputDir(d);
+      if (!existsSync(internalDir)) {
+        mkdirSync(internalDir, { recursive: true });
+      }
+
+      const results = [];
+
+      if (!opts.mdOnly) {
+        const yamlPath = join(internalDir, "doc-registry.yaml");
+        const wrote = await generateRegistryYaml(yamlPath, data);
+        if (wrote) results.push(yamlPath);
+      }
+
+      if (!opts.yamlOnly) {
+        const mdPath = join(internalDir, "doc-registry.md");
+        generateRegistryMd(mdPath, data);
+        results.push(mdPath);
+      }
+
+      if (results.length > 0) {
+        console.log("\n  Document registry generated:\n");
+        for (const r of results) {
+          console.log(`    - ${r}`);
+        }
+        console.log(
+          `\n  Nodes: ${data.dependencyGraph.nodes.length}  Edges: ${data.dependencyGraph.edges.length}  Orphans: ${data.health.orphanNodes}\n`
+        );
+      }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Data gathering
+// ---------------------------------------------------------------------------
+
+async function gatherRegistryData(dir) {
+  const data = {
+    generated: new Date().toISOString().slice(0, 10),
+    generator: "wwa doc-review",
+    dependencyGraph: { nodes: [], edges: [], orphans: [], readOrder: [] },
+    terminology: { modules: [], apis: [], entities: [], conventions: [] },
+    health: {
+      totalDocs: 0,
+      docsOnDisk: 0,
+      docsMissing: 0,
+      orphanNodes: 0,
+      staleDocs: 0,
+      dependencyCoverage: "0%",
+    },
+    docsInventory: [],
+    componentMappings: [],
+    errors: [],
+    warnings: [],
+  };
+
+  // --- Load doc_graph from doc-tokens.yaml ---
+  const tokensPath = await resolveTokensPath(dir);
+  if (!existsSync(tokensPath)) {
+    data.errors.push(
+      "No doc-tokens.yaml found — run wwa init or complete brownfield onboarding first"
+    );
+    return data;
+  }
+
+  let parsed;
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const raw = readFileSync(tokensPath, "utf-8");
+    parsed = yaml.load(raw);
+  } catch (e) {
+    data.errors.push(`Failed to parse doc-tokens.yaml: ${e.message}`);
+    return data;
+  }
+
+  // Dependency graph
+  const docGraph = parsed?.doc_graph;
+  if (docGraph) {
+    const nodes = docGraph.nodes || [];
+    const edges = docGraph.edges || [];
+    data.dependencyGraph.nodes = nodes;
+    data.dependencyGraph.edges = edges;
+
+    // Compute orphans
+    const connected = new Set();
+    for (const e of edges) {
+      connected.add(e.from);
+      connected.add(e.to);
+    }
+    data.dependencyGraph.orphans = nodes
+      .filter((n) => !connected.has(n.path))
+      .map((n) => n.path);
+
+    // Topological read order (Kahn's algorithm on reads_from edges)
+    data.dependencyGraph.readOrder = computeReadOrder(nodes, edges);
+  } else {
+    data.warnings.push("No doc_graph section in doc-tokens.yaml — graph will be empty");
+  }
+
+  // Terminology
+  const projectNames = parsed?.project_names;
+  if (projectNames) {
+    data.terminology.modules = projectNames.modules || [];
+    data.terminology.apis = projectNames.apis || [];
+    data.terminology.entities = projectNames.entities || [];
+    data.terminology.conventions = projectNames.conventions || [];
+  }
+
+  // --- Load DOCS-MAP.md ---
+  const docsMapPath = await resolveDocsMapPath(dir);
+  if (existsSync(docsMapPath)) {
+    const content = readFileSync(docsMapPath, "utf-8");
+    const mapData = parseDocsMap(content);
+    data.docsInventory = mapData.inventory;
+    data.componentMappings = mapData.mappings;
+  }
+
+  // --- Health: check nodes against disk ---
+  const nodes = data.dependencyGraph.nodes;
+  let onDisk = 0;
+  let missing = 0;
+  const lastScan = docGraph?.last_scan || null;
+
+  for (const n of nodes) {
+    const fullPath = join(dir, n.path);
+    if (existsSync(fullPath)) {
+      onDisk++;
+    } else {
+      missing++;
+    }
+  }
+
+  const totalEdgeNodes = new Set();
+  for (const e of data.dependencyGraph.edges) {
+    totalEdgeNodes.add(e.from);
+    totalEdgeNodes.add(e.to);
+  }
+
+  data.health = {
+    totalDocs: nodes.length,
+    docsOnDisk: onDisk,
+    docsMissing: missing,
+    orphanNodes: data.dependencyGraph.orphans.length,
+    staleDocs: 0, // Could enhance with mtime comparison
+    dependencyCoverage:
+      nodes.length > 0
+        ? Math.round((totalEdgeNodes.size / nodes.length) * 100) + "%"
+        : "0%",
+    lastScan,
+  };
+
+  return data;
+}
+
+function computeReadOrder(nodes, edges) {
+  const readsFrom = edges.filter((e) => e.type === "reads_from");
+  if (readsFrom.length === 0) return nodes.map((n) => n.path).sort();
+
+  const pathSet = new Set(nodes.map((n) => n.path));
+  const inDegree = {};
+  const adj = {};
+  for (const p of pathSet) {
+    inDegree[p] = 0;
+    adj[p] = [];
+  }
+  for (const e of readsFrom) {
+    if (pathSet.has(e.from) && pathSet.has(e.to)) {
+      adj[e.to].push(e.from); // to must be read before from
+      inDegree[e.from] = (inDegree[e.from] || 0) + 1;
+    }
+  }
+
+  const queue = [];
+  for (const p of pathSet) {
+    if (inDegree[p] === 0) queue.push(p);
+  }
+  queue.sort();
+
+  const result = [];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    result.push(node);
+    for (const neighbor of (adj[node] || []).sort()) {
+      inDegree[neighbor]--;
+      if (inDegree[neighbor] === 0) queue.push(neighbor);
+    }
+  }
+
+  // Add any remaining nodes (cycles) at the end
+  for (const p of pathSet) {
+    if (!result.includes(p)) result.push(p);
+  }
+  return result;
+}
+
+function parseDocsMap(content) {
+  const inventory = [];
+  const mappings = [];
+
+  const parseTable = (sectionName) => {
+    const re = new RegExp(
+      `## ${sectionName}[ \\t]*\\n\\n?\\|[^\\n]+\\n\\|[-| :]+\\n((?:\\|[^\\n]+\\n)*)`,
+    );
+    const m = content.match(re);
+    if (!m) return [];
+    return m[1]
+      .trim()
+      .split("\n")
+      .map((row) =>
+        row
+          .split("|")
+          .map((c) => c.trim())
+          .filter((c) => c && !c.startsWith("<!--"))
+      )
+      .filter((cols) => cols.length >= 2);
+  };
+
+  for (const cols of parseTable("Docs inventory")) {
+    inventory.push({
+      path: cols[0],
+      purpose: cols[1],
+      sources: cols[2] || "",
+      status: cols[3] || "",
+    });
+  }
+  for (const cols of parseTable("Component-to-docs mapping")) {
+    mappings.push({
+      component: cols[0],
+      documentedIn: cols[1],
+      trigger: cols[2] || "",
+    });
+  }
+
+  return { inventory, mappings };
+}
+
+// ---------------------------------------------------------------------------
+// YAML output
+// ---------------------------------------------------------------------------
+
+async function generateRegistryYaml(yamlPath, data) {
+  try {
+    const yaml = (await import("js-yaml")).default;
+
+    const structured = {
+      generated: data.generated,
+      generator: data.generator,
+      dependency_graph: {
+        nodes: data.dependencyGraph.nodes,
+        edges: data.dependencyGraph.edges,
+        orphans: data.dependencyGraph.orphans,
+        read_order: data.dependencyGraph.readOrder,
+      },
+      terminology: data.terminology,
+      health: data.health,
+      docs_inventory: data.docsInventory,
+      component_mappings: data.componentMappings,
+    };
+
+    const yamlOutput = yaml.dump(structured, {
+      lineWidth: 120,
+      noRefs: true,
+      quotingType: '"',
+    });
+    const header = [
+      "# Document Registry — dependency graph, terminology, and health metrics",
+      `# Generated: ${data.generated} by wwa doc-review`,
+      "# Source: doc-tokens.yaml (doc_graph, project_names) + DOCS-MAP.md (resolved via boundaries)",
+      "",
+    ].join("\n");
+
+    safeWriteFile(yamlPath, header + yamlOutput, "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Markdown output
+// ---------------------------------------------------------------------------
+
+function generateRegistryMd(mdPath, data) {
+  const lines = [];
+
+  lines.push(
+    "# Document Registry",
+    "",
+    `<!-- Generated: ${data.generated} by wwa doc-review -->`,
+    ""
+  );
+
+  // Dependency tree
+  lines.push("## Dependency tree", "");
+  if (data.dependencyGraph.readOrder.length > 0) {
+    lines.push("Read order (foundational files first):", "");
+    let i = 1;
+    for (const p of data.dependencyGraph.readOrder) {
+      const node = data.dependencyGraph.nodes.find((n) => n.path === p);
+      const role = node ? ` — ${node.role}` : "";
+      lines.push(`${i}. \`${p}\`${role}`);
+      i++;
+    }
+  } else {
+    lines.push("No dependency data available.");
+  }
+  lines.push("");
+
+  // Terminology glossary
+  lines.push("## Terminology glossary", "");
+
+  const term = data.terminology;
+  const hasTerminology =
+    term.modules.length > 0 ||
+    term.apis.length > 0 ||
+    term.entities.length > 0 ||
+    term.conventions.length > 0;
+
+  if (hasTerminology) {
+    if (term.modules.length > 0) {
+      lines.push(
+        "### Modules",
+        "",
+        "| Canonical | Aliases | Location |",
+        "|-----------|---------|----------|"
+      );
+      for (const m of term.modules) {
+        const aliases = Array.isArray(m.aliases) ? m.aliases.join(", ") : "";
+        lines.push(
+          `| ${m.canonical || m} | ${aliases} | ${m.location || ""} |`
+        );
+      }
+      lines.push("");
+    }
+    if (term.apis.length > 0) {
+      lines.push(
+        "### APIs",
+        "",
+        "| Endpoint | Methods | Documented in |",
+        "|----------|---------|---------------|"
+      );
+      for (const a of term.apis) {
+        const methods = Array.isArray(a.methods) ? a.methods.join(", ") : "";
+        lines.push(
+          `| ${a.canonical || a} | ${methods} | ${a.documented_in || ""} |`
+        );
+      }
+      lines.push("");
+    }
+    if (term.entities.length > 0) {
+      lines.push(
+        "### Entities",
+        "",
+        "| Entity | Schema location |",
+        "|--------|-----------------|"
+      );
+      for (const e of term.entities) {
+        lines.push(
+          `| ${e.canonical || e} | ${e.schema_location || ""} |`
+        );
+      }
+      lines.push("");
+    }
+    if (term.conventions.length > 0) {
+      lines.push("### Conventions", "");
+      for (const c of term.conventions) {
+        if (typeof c === "string") {
+          lines.push(`- ${c}`);
+        } else {
+          lines.push(`- **${c.name}**: ${c.pattern || ""}`);
+        }
+      }
+      lines.push("");
+    }
+  } else {
+    lines.push("No project terminology captured yet.", "");
+  }
+
+  // Health dashboard
+  const h = data.health;
+  lines.push(
+    "## Health dashboard",
+    "",
+    "| Metric | Value |",
+    "|--------|-------|",
+    `| Total nodes | ${h.totalDocs} |`,
+    `| Nodes on disk | ${h.docsOnDisk} |`,
+    `| Nodes missing | ${h.docsMissing} |`,
+    `| Orphan nodes | ${h.orphanNodes} |`,
+    `| Dependency coverage | ${h.dependencyCoverage} |`,
+    `| Last scan | ${h.lastScan || "unknown"} |`,
+    ""
+  );
+
+  if (data.dependencyGraph.orphans.length > 0) {
+    lines.push("### Orphan nodes (no edges)", "");
+    for (const o of data.dependencyGraph.orphans) {
+      lines.push(`- \`${o}\``);
+    }
+    lines.push("");
+  }
+
+  // Cross-reference index
+  lines.push("## Cross-reference index", "");
+  if (data.dependencyGraph.nodes.length > 0) {
+    for (const node of data.dependencyGraph.nodes) {
+      const upstream = data.dependencyGraph.edges
+        .filter((e) => e.to === node.path)
+        .map((e) => `\`${e.from}\` (${e.type})`);
+      const downstream = data.dependencyGraph.edges
+        .filter((e) => e.from === node.path)
+        .map((e) => `\`${e.to}\` (${e.type})`);
+
+      if (upstream.length > 0 || downstream.length > 0) {
+        lines.push(`### \`${node.path}\``, "");
+        if (upstream.length > 0) {
+          lines.push(`- **Upstream**: ${upstream.join(", ")}`);
+        }
+        if (downstream.length > 0) {
+          lines.push(`- **Downstream**: ${downstream.join(", ")}`);
+        }
+        lines.push("");
+      }
+    }
+  } else {
+    lines.push("No cross-references available.", "");
+  }
+
+  lines.push(
+    "---",
+    "",
+    "*Generated by `wwa doc-review` from doc-tokens.yaml and DOCS-MAP.md (resolved via boundaries).*",
+    ""
+  );
+
+  safeWriteFile(mdPath, lines.join("\n"), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Public: load registry data for --internal-registry consumers
+// ---------------------------------------------------------------------------
+
+export async function loadInternalRegistry(dir) {
+  const outputDir = await resolveOutputDir(dir);
+  const registryPath = join(outputDir, "doc-registry.yaml");
+  if (!existsSync(registryPath)) return null;
+  try {
+    const yaml = (await import("js-yaml")).default;
+    const raw = readFileSync(registryPath, "utf-8");
+    return yaml.load(raw);
+  } catch {
+    return null;
+  }
+}