agent-method 1.5.12

package/lib/cli/check.js

@@ -0,0 +1,323 @@
+/** wwa check — validate entry point and project setup. */
+
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  findEntryPoint,
+  resolveProjectType,
+  getPipeline,
+  loadRegistryData,
+} from "./helpers.js";
+import { resolveTokensPath, loadBoundaries } from "../boundaries.js";
+import { printCliReport, writeLastRunSummary } from "./report-helpers.js";
+
+/** Phase 7q-2: Detect if PROTOCOL.yaml has an active (uncommented) boundaries section. */
+function hasActiveBoundariesSection(raw) {
+  const lines = raw.split("\n");
+  for (const line of lines) {
+    if (/^\s*boundaries\s*:/.test(line)) return !line.trimStart().startsWith("#");
+  }
+  return false;
+}
+
+export function register(program) {
+  program
+    .command("check [entry-point]")
+    .description("Validate your entry point and project setup")
+    .option(
+      "-p, --project-type <type>",
+      "Project type: code, context, data, mix, general (auto-detected if omitted)"
+    )
+    .option("--registry <path>", "Path to feature-registry.yaml")
+    .option("--json", "Output as JSON")
+    .action(async (entryPoint, opts) => {
+      const { validateEntryPoint, detectProjectType } = await getPipeline();
+      const reg = await loadRegistryData(opts.registry);
+
+      if (!entryPoint) {
+        entryPoint = findEntryPoint(".");
+        if (!entryPoint) {
+          console.error(
+            "No entry point found in current directory " +
+              "(looked for CLAUDE.md, .cursorrules, AGENT.md).\n" +
+              "Specify a path: wwa check path/to/CLAUDE.md"
+          );
+          process.exit(1);
+        }
+      }
+
+      let projectType;
+      if (opts.projectType) {
+        projectType = resolveProjectType(opts.projectType);
+      } else {
+        const detected = detectProjectType(resolve(dirname(resolve(entryPoint))));
+        projectType = detected.project_type || "general";
+      }
+
+      const result = validateEntryPoint(entryPoint, projectType, reg);
+
+      // Resolve project root once for consistent path resolution (Phase 7q-2)
+      const entryResolved = resolve(entryPoint);
+      const epDir = dirname(entryResolved);
+      const epDirAbs = resolve(epDir);
+
+      // V-09: PROTOCOL.yaml presence and structure
+      let epContent;
+      try { epContent = readFileSync(entryResolved, "utf-8"); } catch { epContent = ""; }
+      if (epContent.includes("PROTOCOL.yaml")) {
+        const protocolPath = join(epDirAbs, ".context", "PROTOCOL.yaml");
+        if (existsSync(protocolPath)) {
+          try {
+            const yaml = (await import("js-yaml")).default;
+            const raw = readFileSync(protocolPath, "utf-8");
+            const parsed = yaml.load(raw);
+            const requiredKeys = ["scoping", "cascade", "close_check"];
+            const missingKeys = requiredKeys.filter(k => !parsed || !parsed[k]);
+            if (missingKeys.length > 0) {
+              result.checks["V-09_protocol_structure"] = { pass: false, missing: missingKeys };
+              result.issues.push({
+                check: "V-09",
+                severity: "medium",
+                description: `PROTOCOL.yaml missing required sections: ${missingKeys.join(", ")}`,
+              });
+            } else {
+              result.checks["V-09_protocol_structure"] = { pass: true };
+            }
+          } catch (e) {
+            result.checks["V-09_protocol_structure"] = { pass: false };
+            result.issues.push({
+              check: "V-09",
+              severity: "high",
+              description: `PROTOCOL.yaml parse error: ${e.message}`,
+            });
+          }
+        } else {
+          result.checks["V-09_protocol_presence"] = { pass: false };
+          result.issues.push({
+            check: "V-09",
+            severity: "warning",
+            description: `PROTOCOL.yaml not found at expected path`,
+            expectedPath: protocolPath,
+            suggestion: "Create .context/ and copy PROTOCOL.yaml from a template, or run wwa init.",
+          });
+        }
+      }
+
+      // V-10: doc_graph health (informational — does not affect overall validity)
+      const docTokensPath = await resolveTokensPath(epDirAbs);
+      if (existsSync(docTokensPath)) {
+        try {
+          const yaml = (await import("js-yaml")).default;
+          const dtRaw = readFileSync(docTokensPath, "utf-8");
+          const dtParsed = yaml.load(dtRaw);
+          if (dtParsed?.doc_graph) {
+            const nodes = dtParsed.doc_graph.nodes || [];
+            const edges = dtParsed.doc_graph.edges || [];
+            const nodePaths = new Set(nodes.map((n) => n.path));
+            const missingOnDisk = nodes.filter(
+              (n) => !existsSync(join(epDirAbs, n.path))
+            );
+            const danglingEdges = edges.filter(
+              (e) => !nodePaths.has(e.from) || !nodePaths.has(e.to)
+            );
+            const pass = missingOnDisk.length === 0 && danglingEdges.length === 0;
+            result.checks["V-10_doc_graph_health"] = {
+              pass,
+              nodes: nodes.length,
+              edges: edges.length,
+              missingOnDisk: missingOnDisk.map((n) => n.path),
+              danglingEdges: danglingEdges.length,
+            };
+            if (!pass) {
+              result.issues.push({
+                check: "V-10",
+                severity: "info",
+                description: `doc_graph: ${missingOnDisk.length} nodes missing on disk, ${danglingEdges.length} dangling edges`,
+              });
+            }
+          }
+        } catch {
+          // doc-tokens.yaml parse error — skip V-10 silently
+        }
+      }
+
+      // V-11: Boundaries configuration health (informational) — Phase 7q-2: distinguish not configured vs file not found
+      const protocolForBounds = join(epDirAbs, ".context", "PROTOCOL.yaml");
+      if (existsSync(protocolForBounds)) {
+        try {
+          const protocolRaw = readFileSync(protocolForBounds, "utf-8");
+          const boundariesConfigured = hasActiveBoundariesSection(protocolRaw);
+          if (!boundariesConfigured) {
+            result.checks["V-11_boundaries_health"] = { pass: false, reason: "boundaries_not_configured" };
+            result.issues.push({
+              check: "V-11",
+              severity: "info",
+              description: "Boundaries section not configured or commented out in .context/PROTOCOL.yaml.",
+              suggestion: "Uncomment the boundaries section and set registries.tokens, registries.feature_registry, docs_map, and output. Run `wwa init` to generate a project with boundaries enabled, or copy from templates.",
+            });
+          } else {
+            const bounds = await loadBoundaries(epDirAbs);
+            const issues = [];
+            const details = [];
+            for (const [key, relPath] of Object.entries(bounds.registries || {})) {
+              if (key === "output") continue;
+              const absPath = join(epDirAbs, relPath);
+              if (!existsSync(absPath)) {
+                issues.push(`registries.${key}: ${relPath} not found`);
+                details.push({ key, configuredPath: relPath, resolvedPath: absPath });
+              }
+            }
+            const internalSet = new Set(bounds.visibility?.internal || []);
+            for (const r of bounds.visibility?.release || []) {
+              if (internalSet.has(r)) issues.push(`visibility overlap: ${r} in both internal and release`);
+            }
+            const pass = issues.length === 0;
+            result.checks["V-11_boundaries_health"] = { pass, issues, details };
+            if (!pass) {
+              const firstDetail = details[0];
+              let description = `Boundaries: ${issues.length} issue(s) — `;
+              if (firstDetail) {
+                description += `registries.${firstDetail.key}: file not found at ${firstDetail.resolvedPath} (configured as "${firstDetail.configuredPath}")`;
+              } else {
+                description += issues[0];
+              }
+              result.issues.push({
+                check: "V-11",
+                severity: "info",
+                description,
+                suggestion: details.length > 0 ? "Ensure registry files exist at the paths in .context/PROTOCOL.yaml boundaries.registries, or run wwa init to create them." : undefined,
+              });
+            }
+          }
+        } catch (e) {
+          result.checks["V-11_boundaries_health"] = { pass: false, reason: "path_resolution_failed", error: e.message };
+          result.issues.push({
+            check: "V-11",
+            severity: "info",
+            description: `Path resolution failed: ${e.message}`,
+            suggestion: "Check that .context/PROTOCOL.yaml is valid YAML and boundaries.registries paths are relative to project root.",
+          });
+        }
+      }
+
+      // V-12: Token drift detection (informational — compares registry values against source of truth)
+      if (existsSync(docTokensPath)) {
+        try {
+          const yaml = (await import("js-yaml")).default;
+          const dtRaw = readFileSync(docTokensPath, "utf-8");
+          const dtParsed = yaml.load(dtRaw);
+          if (dtParsed?.tokens) {
+            const driftIssues = [];
+            const t = dtParsed.tokens;
+
+            // Compare against feature registry (source of truth for counts)
+            const bounds = await loadBoundaries(epDirAbs);
+            const regPath = join(epDirAbs, bounds.registries.feature_registry);
+            if (existsSync(regPath)) {
+              const reg = yaml.load(readFileSync(regPath, "utf-8"));
+              if (reg?.features) {
+                const actual = Object.keys(reg.features).length;
+                if (t.feature_count && t.feature_count !== actual) {
+                  driftIssues.push(`feature_count: token=${t.feature_count} actual=${actual}`);
+                }
+              }
+              if (reg?.workflows) {
+                const actual = reg.workflows.length;
+                if (t.workflow_count && t.workflow_count !== actual) {
+                  driftIssues.push(`workflow_count: token=${t.workflow_count} actual=${actual}`);
+                }
+              }
+              if (reg?.domains) {
+                const actual = reg.domains.length;
+                if (t.domain_count && t.domain_count !== actual) {
+                  driftIssues.push(`domain_count: token=${t.domain_count} actual=${actual}`);
+                }
+              }
+              if (reg?.protocol?.core_directives) {
+                const actual = reg.protocol.core_directives.length;
+                if (t.directive_count && t.directive_count !== actual) {
+                  driftIssues.push(`directive_count: token=${t.directive_count} actual=${actual}`);
+                }
+              }
+            }
+
+            const pass = driftIssues.length === 0;
+            result.checks["V-12_token_drift"] = { pass, driftIssues };
+            if (!pass) {
+              result.issues.push({
+                check: "V-12",
+                severity: "info",
+                description: `Token drift: ${driftIssues.length} mismatch(es) — ${driftIssues[0]}${driftIssues.length > 1 ? ` (+${driftIssues.length - 1} more)` : ""}`,
+              });
+            }
+          }
+        } catch {
+          // drift check failed — skip silently
+        }
+      }
+
+      // V-13: Legacy registry paths (informational — detect .context/ YAML when registry/ exists)
+      const registryDir = join(epDirAbs, "registry");
+      if (existsSync(registryDir)) {
+        const legacyFiles = [];
+        const legacyTokens = join(epDirAbs, ".context", "doc-tokens.yaml");
+        const legacyFeatures = join(epDirAbs, ".context", "feature-registry.yaml");
+        if (existsSync(legacyTokens)) legacyFiles.push(".context/doc-tokens.yaml");
+        if (existsSync(legacyFeatures)) legacyFiles.push(".context/feature-registry.yaml");
+        if (legacyFiles.length > 0) {
+          result.checks["V-13_legacy_registry_paths"] = { pass: false, legacyFiles };
+          result.issues.push({
+            check: "V-13",
+            severity: "info",
+            description: `Legacy registry files in .context/: ${legacyFiles.join(", ")} — run \`wwa upgrade\` to migrate to registry/`,
+          });
+        } else {
+          result.checks["V-13_legacy_registry_paths"] = { pass: true };
+        }
+      }
+
+      // Recompute overall validity (V-10, V-11, V-12, V-13 are informational, exclude from pass/fail)
+      const informational = new Set(["V-10_doc_graph_health", "V-11_boundaries_health", "V-12_token_drift", "V-13_legacy_registry_paths"]);
+      result.valid = Object.entries(result.checks).every(
+        ([key, c]) => c.pass || informational.has(key)
+      );
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const overall = result.valid ? "PASS" : "FAIL";
+        const issueCount = result.issues?.length ?? 0;
+        const firstSuggestion = result.issues?.[0]?.suggestion;
+        const summary = [
+          `Validation ${overall}.`,
+          issueCount
+            ? `${issueCount} issue(s) found.${firstSuggestion ? ` Fix: ${firstSuggestion}` : " See issues below."}`
+            : "All checks passed.",
+        ].join(" ");
+        const inputRef = `entry-point=${entryPoint}, project type=${projectType}`;
+        printCliReport({ command: "check", inputRef, summary });
+        console.log(`  Detail — Checking: ${entryPoint} (type: ${projectType})`);
+        console.log(`  Overall: ${overall}`);
+        for (const [checkId, chk] of Object.entries(result.checks)) {
+          const cStatus = chk.pass ? "PASS" : "FAIL";
+          let extra = "";
+          if (chk.missing && chk.missing.length > 0) {
+            extra = ` (missing: ${chk.missing.join(", ")})`;
+          }
+          console.log(`  ${checkId}: ${cStatus}${extra}`);
+        }
+        if (result.issues && result.issues.length > 0) {
+          console.log("\n  Issues:");
+          for (const issue of result.issues) {
+            console.log(
+              `    [${issue.severity}] ${issue.check}: ${issue.description}`
+            );
+            if (issue.suggestion) {
+              console.log(`      Suggestion: ${issue.suggestion}`);
+            }
+          }
+        }
+        writeLastRunSummary(epDirAbs, { command: "check", inputRef, summary });
+      }
+    });
+}