supipowers 2.0.2 → 2.2.0

package/src/harness/docs/validator.ts

@@ -0,0 +1,233 @@
+/**
+ * Synchronous validator for a per-layer doc rendered by a docs-stage subagent.
+ *
+ * Validation is mechanical: LOC caps, required headings in order, frontmatter shape,
+ * agent-context section cap, sourceHash match, no TODO/XXX markers. The validator runs
+ * inside the `harness_docs_record` tool handler, so failures must be safe to surface to
+ * the subagent (structured error strings).
+ */
+
+import { parseProvenance } from "./provenance.js";
+
+export interface ValidateLayerDocOptions {
+  /** Expected layer id (from the assignment). */
+  expectedLayerId: string;
+  /** Expected sourceHash; the renderer must embed this verbatim. */
+  expectedSourceHash: string;
+  /** Hard cap on total LOC (default 150). */
+  maxDocLoc?: number;
+  /** Hard cap on the `## Agent context` section LOC (default 30). */
+  maxAgentContextLoc?: number;
+}
+
+export const DEFAULT_MAX_DOC_LOC = 150;
+export const DEFAULT_MAX_AGENT_CONTEXT_LOC = 30;
+
+/** Required headings, in the order the doc must place them. */
+export const REQUIRED_HEADINGS: readonly string[] = [
+  "## Agent context",
+  "## Purpose",
+  "## Files",
+  "## Imports",
+  "## Conventions",
+];
+
+const PLACEHOLDER_PATTERN = /\b(TODO|XXX|FIXME|TBD|<placeholder>)\b/;
+
+export interface ValidateLayerDocResult {
+  ok: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a layer-doc markdown body. Returns `{ ok, errors }`. `errors` is empty when
+ * `ok === true`.
+ */
+export function validateLayerDocMarkdown(
+  markdown: string,
+  options: ValidateLayerDocOptions,
+): ValidateLayerDocResult {
+  const errors: string[] = [];
+  const maxDocLoc = options.maxDocLoc ?? DEFAULT_MAX_DOC_LOC;
+  const maxAgentContextLoc = options.maxAgentContextLoc ?? DEFAULT_MAX_AGENT_CONTEXT_LOC;
+
+  // 1. Provenance marker on first line.
+  const parsed = parseProvenance(markdown);
+  if (!parsed) {
+    errors.push("missing or malformed provenance marker on the first line");
+  }
+
+  // 2. LOC budget.
+  const lineCount = countDocLines(markdown);
+  if (lineCount > maxDocLoc) {
+    errors.push(`doc has ${lineCount} LOC; max is ${maxDocLoc}`);
+  }
+
+  // 3. Frontmatter — between the first --- after the marker and the next ---.
+  const frontmatter = extractFrontmatter(parsed?.body ?? markdown);
+  if (!frontmatter) {
+    errors.push("missing YAML frontmatter (---\\n…\\n---) immediately after the marker");
+  } else {
+    if (frontmatter.layer !== options.expectedLayerId) {
+      errors.push(
+        `frontmatter layer mismatch (got "${frontmatter.layer ?? ""}", expected "${options.expectedLayerId}")`,
+      );
+    }
+    if (!frontmatter.generatedAt) {
+      errors.push("frontmatter is missing `generatedAt`");
+    }
+    if (!frontmatter.sourceHash) {
+      errors.push("frontmatter is missing `sourceHash`");
+    } else if (frontmatter.sourceHash !== options.expectedSourceHash) {
+      errors.push(
+        `frontmatter sourceHash mismatch (got "${frontmatter.sourceHash}", expected "${options.expectedSourceHash}")`,
+      );
+    }
+  }
+
+  // 4. Required headings in order.
+  const headingResult = checkHeadings(markdown);
+  if (headingResult.missing.length > 0) {
+    errors.push(`missing required heading(s): ${headingResult.missing.join(", ")}`);
+  }
+  if (headingResult.outOfOrder) {
+    errors.push(`required headings appear out of order — expected: ${REQUIRED_HEADINGS.join(" → ")}`);
+  }
+
+  // 5. Agent-context cap.
+  const agentSectionLoc = sectionLoc(markdown, "## Agent context");
+  if (agentSectionLoc > maxAgentContextLoc) {
+    errors.push(`## Agent context section is ${agentSectionLoc} LOC; max is ${maxAgentContextLoc}`);
+  }
+
+  // 6. Placeholder markers.
+  if (PLACEHOLDER_PATTERN.test(markdown)) {
+    errors.push("doc contains a TODO/XXX/FIXME/TBD placeholder marker; remove before recording");
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/** Count LOC ignoring a trailing empty line (matches representativeFiles `countLines`). */
+function countDocLines(markdown: string): number {
+  if (markdown.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < markdown.length; i += 1) {
+    if (markdown.charCodeAt(i) === 10 /* \n */) count += 1;
+  }
+  if (markdown.charCodeAt(markdown.length - 1) === 10) count -= 1;
+  return count;
+}
+
+interface ParsedFrontmatter {
+  layer?: string;
+  generatedAt?: string;
+  sourceHash?: string;
+  /** Raw map for tests / future fields. */
+  raw: Map<string, string>;
+}
+
+function extractFrontmatter(body: string): ParsedFrontmatter | null {
+  if (!body.startsWith("---")) return null;
+  const newlineAfterOpen = body.indexOf("\n");
+  if (newlineAfterOpen < 0) return null;
+  // Find the next "\n---" closer.
+  const closeIdx = body.indexOf("\n---", newlineAfterOpen);
+  if (closeIdx < 0) return null;
+
+  const inner = body.slice(newlineAfterOpen + 1, closeIdx);
+  const map = new Map<string, string>();
+  for (const line of inner.split("\n")) {
+    const m = line.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    map.set(m[1], m[2].trim());
+  }
+  return {
+    layer: map.get("layer"),
+    generatedAt: map.get("generatedAt"),
+    sourceHash: map.get("sourceHash"),
+    raw: map,
+  };
+}
+
+function checkHeadings(markdown: string): { missing: string[]; outOfOrder: boolean } {
+  const seen: { heading: string; index: number }[] = [];
+  for (const heading of REQUIRED_HEADINGS) {
+    const pattern = new RegExp(`^${escapeRegex(heading)}\\s*$`, "m");
+    const match = markdown.match(pattern);
+    if (match && typeof match.index === "number") {
+      seen.push({ heading, index: match.index });
+    }
+  }
+
+  const missing = REQUIRED_HEADINGS.filter(
+    (h) => !seen.some((entry) => entry.heading === h),
+  );
+
+  // Check ordering only for headings we did see.
+  let outOfOrder = false;
+  let lastIndex = -1;
+  for (const heading of REQUIRED_HEADINGS) {
+    const entry = seen.find((s) => s.heading === heading);
+    if (!entry) continue;
+    if (entry.index < lastIndex) {
+      outOfOrder = true;
+      break;
+    }
+    lastIndex = entry.index;
+  }
+  return { missing: missing.slice(), outOfOrder };
+}
+
+/** Count LOC of the section starting at `heading` (exclusive) up to the next `## ` heading. */
+export function sectionLoc(markdown: string, heading: string): number {
+  const lines = markdown.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i] === heading || lines[i].startsWith(`${heading} `)) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return 0;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i].startsWith("## ") || lines[i] === "##") {
+      end = i;
+      break;
+    }
+  }
+  // Trim trailing blank lines.
+  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  return Math.max(0, end - start - 1);
+}
+
+/** Extract the body of the `## Agent context` section. Returns "" when missing. */
+export function extractAgentContextSection(markdown: string, maxLoc?: number): string {
+  const lines = markdown.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i] === "## Agent context" || lines[i].startsWith("## Agent context ")) {
+      start = i;
+      break;
+    }
+  }
+  if (start < 0) return "";
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i].startsWith("## ") || lines[i] === "##") {
+      end = i;
+      break;
+    }
+  }
+  while (end > start + 1 && lines[end - 1].trim() === "") end -= 1;
+  let bodyLines = lines.slice(start + 1, end);
+  if (maxLoc !== undefined && bodyLines.length > maxLoc) {
+    bodyLines = bodyLines.slice(0, maxLoc);
+  }
+  return bodyLines.join("\n");
+}
+
+function escapeRegex(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}