@warpgogol/forge 2.8.0 → 2.8.2

package/os/rfc/dna-trace.ts

@@ -0,0 +1,280 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0331: DNA-trace builder, validate command, and generate command.
+Parses DNA invariants from docs/architecture-dna.md, collects satisfies
+entries from all RFCs, and builds a bidirectional trace matrix.
+</purpose>
+<non-goals>
+  <item>Do not validate registry establishment — that is dna.registry.validate (RFC-0158).</item>
+  <item>Do not backfill satisfies for pre-cutoff RFCs.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0331: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { writeFileAtomic } from "../../src/utils/fs-atomic.ts";
+import { buildGeneratedHeader } from "../../src/utils/generated-marker.ts";
+import { stringify as yamlStringify } from "yaml";
+import { listRfcFiles, readAndParseRfc } from "./frontmatter-io.ts";
+import { RFC_DIR } from "./types.ts";
+import type {
+  Diagnostic,
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../src/types.ts";
+
+const DNA_REGISTRY_PATH = "docs/architecture-dna.md";
+const DNA_HEADING_RE = /^##\s+DNA-(\d+)\b/gm;
+
+export interface DnaTraceEntry {
+  dnaId: string;
+  satisfiedBy: {
+    implemented: string[];
+    accepted: string[];
+    draft: string[];
+    other: string[];
+  };
+}
+
+export interface DnaTraceResult {
+  command: "rfc.dna.trace.validate";
+  status: "pass" | "fail";
+  dnaCount: number;
+  tracedDnaCount: number;
+  entries: DnaTraceEntry[];
+  diagnostics: Diagnostic[];
+  written?: string;
+}
+
+async function parseDnaRegistry(workspaceRoot: string): Promise<Set<string>> {
+  const ids = new Set<string>();
+  try {
+    const src = await readFile(join(workspaceRoot, DNA_REGISTRY_PATH), "utf-8");
+    for (const m of src.matchAll(DNA_HEADING_RE)) {
+      ids.add(`DNA-${m[1]}`);
+    }
+  } catch {
+    // handled by caller
+  }
+  return ids;
+}
+
+interface RfcSatisfiesEntry {
+  rfcId: string;
+  status: string;
+  satisfies: string[];
+}
+
+async function collectSatisfies(workspaceRoot: string): Promise<RfcSatisfiesEntry[]> {
+  const rfcDirPath = join(workspaceRoot, RFC_DIR);
+  const files = await listRfcFiles(rfcDirPath);
+  const entries: RfcSatisfiesEntry[] = [];
+  for (const fileName of files) {
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    if (!result || "error" in result) continue;
+    const fm = result.parsed.frontmatter;
+    const rfcId = String(fm["id"] ?? "");
+    const status = String(fm["status"] ?? "");
+    const satisfies = Array.isArray(fm["satisfies"])
+      ? (fm["satisfies"] as unknown[]).map(String)
+      : [];
+    if (satisfies.length > 0) {
+      entries.push({ rfcId, status, satisfies });
+    }
+  }
+  return entries;
+}
+
+export async function buildDnaTrace(
+  workspaceRoot: string,
+): Promise<{ entries: DnaTraceEntry[]; diagnostics: Diagnostic[]; registryIds: Set<string> }> {
+  const registryIds = await parseDnaRegistry(workspaceRoot);
+  const rfcEntries = await collectSatisfies(workspaceRoot);
+  const diagnostics: Diagnostic[] = [];
+
+  if (registryIds.size === 0) {
+    diagnostics.push({
+      ruleId: "DNA-TRACE-00",
+      severity: "error",
+      file: DNA_REGISTRY_PATH,
+      message: `DNA registry not found or unreadable at ${DNA_REGISTRY_PATH}.`,
+    });
+  }
+
+  // Build entries for every registry DNA id
+  const entries: DnaTraceEntry[] = [];
+  for (const dnaId of [...registryIds].sort()) {
+    const satisfiedBy = {
+      implemented: [] as string[],
+      accepted: [] as string[],
+      draft: [] as string[],
+      other: [] as string[],
+    };
+    for (const rfc of rfcEntries) {
+      if (!rfc.satisfies.includes(dnaId)) continue;
+      switch (rfc.status) {
+        case "implemented":
+          satisfiedBy.implemented.push(rfc.rfcId);
+          break;
+        case "accepted":
+          satisfiedBy.accepted.push(rfc.rfcId);
+          break;
+        case "draft":
+        case "reviewing":
+          satisfiedBy.draft.push(rfc.rfcId);
+          break;
+        default:
+          satisfiedBy.other.push(rfc.rfcId);
+          break;
+      }
+    }
+    entries.push({ dnaId, satisfiedBy });
+  }
+
+  // DNA-TRACE-01: satisfies entry references a DNA id absent from the registry
+  for (const rfc of rfcEntries) {
+    for (const id of rfc.satisfies) {
+      if (!/^DNA-\d+$/.test(id)) continue; // V-24 handles format
+      if (!registryIds.has(id)) {
+        diagnostics.push({
+          ruleId: "DNA-TRACE-01",
+          severity: "error",
+          message: `${rfc.rfcId} satisfies "${id}" but this DNA id is not in the registry (${DNA_REGISTRY_PATH}).`,
+        });
+      }
+    }
+  }
+
+  // DNA-TRACE-02: DNA invariant with zero accepted/implemented satisfiers
+  for (const entry of entries) {
+    const hasCoverage =
+      entry.satisfiedBy.implemented.length > 0 || entry.satisfiedBy.accepted.length > 0;
+    if (!hasCoverage) {
+      diagnostics.push({
+        ruleId: "DNA-TRACE-02",
+        severity: "info",
+        file: DNA_REGISTRY_PATH,
+        message: `${entry.dnaId} has no accepted/implemented RFC referencing it via satisfies (historical RFCs are exempt).`,
+      });
+    }
+  }
+
+  // DNA-TRACE-03: satisfies on a rejected RFC
+  for (const rfc of rfcEntries) {
+    if (rfc.status === "rejected") {
+      for (const id of rfc.satisfies) {
+        diagnostics.push({
+          ruleId: "DNA-TRACE-03",
+          severity: "warning",
+          message: `${rfc.rfcId} (status: rejected) still declares satisfies "${id}" — a rejected RFC satisfies nothing; the claim is stale.`,
+        });
+      }
+    }
+  }
+
+  return { entries, diagnostics, registryIds };
+}
+
+export async function runRfcDnaTraceValidate(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<DnaTraceResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const dnaFilter = input.flags["dna"] as string | undefined;
+
+  const { entries, diagnostics, registryIds } = await buildDnaTrace(workspaceRoot);
+
+  let filteredEntries = entries;
+  if (dnaFilter) {
+    filteredEntries = entries.filter((e) => e.dnaId === dnaFilter);
+    if (filteredEntries.length === 0) {
+      diagnostics.push({
+        ruleId: "DNA-TRACE-INFO",
+        severity: "info",
+        message: `--dna ${dnaFilter} matched no registry entries.`,
+      });
+    }
+  }
+
+  const tracedDnaCount = entries.filter(
+    (e) => e.satisfiedBy.implemented.length > 0 || e.satisfiedBy.accepted.length > 0,
+  ).length;
+
+  const hasErrors = diagnostics.some((d) => d.severity === "error");
+  const status: DnaTraceResult["status"] = hasErrors ? "fail" : "pass";
+
+  if (outputFormat === "pretty") {
+    logger.section(`DNA trace (${registryIds.size} invariants, ${tracedDnaCount} traced)`);
+    for (const entry of filteredEntries) {
+      const impl = entry.satisfiedBy.implemented.join(", ");
+      const acc = entry.satisfiedBy.accepted.join(", ");
+      logger.info(`${entry.dnaId}: implemented=[${impl}] accepted=[${acc}]`);
+    }
+    for (const d of diagnostics) {
+      if (d.severity === "error") logger.error(`[${d.ruleId}] ${d.message}`);
+      else if (d.severity === "warning") logger.warn(`[${d.ruleId}] ${d.message}`);
+    }
+  }
+
+  return {
+    data: {
+      command: "rfc.dna.trace.validate",
+      status,
+      dnaCount: registryIds.size,
+      tracedDnaCount,
+      entries: filteredEntries,
+      diagnostics,
+    },
+    exitCode: hasErrors ? 1 : 0,
+    summary: `rfc.dna.trace.validate: ${registryIds.size} DNA invariants, ${tracedDnaCount} traced, ${diagnostics.filter((d) => d.severity === "error").length} error(s)`,
+  };
+}
+
+export async function runRfcDnaTraceGenerate(
+  _input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<DnaTraceResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+
+  const { entries, diagnostics, registryIds } = await buildDnaTrace(workspaceRoot);
+
+  const tracedDnaCount = entries.filter(
+    (e) => e.satisfiedBy.implemented.length > 0 || e.satisfiedBy.accepted.length > 0,
+  ).length;
+
+  const hasErrors = diagnostics.some((d) => d.severity === "error");
+  const status: DnaTraceResult["status"] = hasErrors ? "fail" : "pass";
+
+  const outRel = join(RFC_DIR, "dna-trace.generated.yaml");
+  const payload: DnaTraceResult = {
+    command: "rfc.dna.trace.validate",
+    status,
+    dnaCount: registryIds.size,
+    tracedDnaCount,
+    entries,
+    diagnostics,
+    written: outRel,
+  };
+  const jsonContent = `${buildGeneratedHeader({ filePath: outRel, ownerCommand: "rfc.dna.trace.generate" })}${yamlStringify({ ...payload })}\n`;
+  await writeFileAtomic(join(workspaceRoot, outRel), jsonContent);
+
+  if (outputFormat === "pretty") {
+    logger.section(
+      `DNA trace generated (${registryIds.size} invariants, ${tracedDnaCount} traced)`,
+    );
+    logger.success(`Wrote ${outRel}`);
+  }
+
+  return {
+    data: payload,
+    exitCode: hasErrors ? 1 : 0,
+    summary: `rfc.dna.trace.generate: wrote ${outRel} (${registryIds.size} DNA, ${tracedDnaCount} traced)`,
+  };
+}

package/os/rfc/frontmatter-io.test.ts

@@ -0,0 +1,132 @@
+import { test, expect, describe } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { listRfcFiles, readAndParseRfc, parseRfcFile } from "./frontmatter-io.ts";
+
+describe("listRfcFiles — recursive scanning (RFC-0491)", () => {
+  test("scans archive/ subdirectories recursively", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-test-"));
+    try {
+      // Create top-level RFC files
+      await fs.writeFile(
+        path.join(tmpDir, "rfc-0100-active.md"),
+        "---\nid: RFC-0100\n---\n# RFC-0100\n",
+      );
+      // Create archive subdirectory with a higher-numbered RFC
+      await fs.mkdir(path.join(tmpDir, "archive", "implemented"), { recursive: true });
+      await fs.writeFile(
+        path.join(tmpDir, "archive", "implemented", "rfc-0500-archived.md"),
+        "---\nid: RFC-0500\n---\n# RFC-0500\n",
+      );
+
+      const files = await listRfcFiles(tmpDir);
+
+      // Both the top-level and archived RFC must be found
+      expect(files).toContain("rfc-0100-active.md");
+      expect(files).toContain("archive/implemented/rfc-0500-archived.md");
+      expect(files.length).toBe(2);
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns empty array when directory does not exist", async () => {
+    const files = await listRfcFiles(path.join(os.tmpdir(), "nonexistent-rfc-dir-xyz"));
+    expect(files).toEqual([]);
+  });
+
+  test("excludes rfc-0000 template and README.md", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-test-"));
+    try {
+      await fs.writeFile(
+        path.join(tmpDir, "rfc-0000-template.md"),
+        "---\nid: RFC-0000\n---\n# RFC-0000\n",
+      );
+      await fs.writeFile(path.join(tmpDir, "README.md"), "# RFC docs\n");
+      await fs.writeFile(
+        path.join(tmpDir, "rfc-0100-real.md"),
+        "---\nid: RFC-0100\n---\n# RFC-0100\n",
+      );
+
+      const files = await listRfcFiles(tmpDir);
+
+      expect(files).toContain("rfc-0100-real.md");
+      expect(files).not.toContain("rfc-0000-template.md");
+      expect(files).not.toContain("README.md");
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("readAndParseRfc — YAML parse error handling (RFC-0755)", () => {
+  test("returns error variant for malformed YAML frontmatter", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-parse-"));
+    try {
+      const malformedYaml =
+        "---\nid: RFC-0100\ntitle: Test\n  bad: indentation: here\n---\n# Body\n";
+      await fs.writeFile(path.join(tmpDir, "rfc-0100-bad.md"), malformedYaml);
+
+      const result = await readAndParseRfc(tmpDir, "rfc-0100-bad.md");
+
+      expect(result).toBeDefined();
+      expect(result && "error" in result).toBe(true);
+      if (result && "error" in result) {
+        expect(result.error).toContain("YAML parse error");
+        expect(result.fileName).toBe("rfc-0100-bad.md");
+      }
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns parsed variant for valid YAML frontmatter", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-parse-"));
+    try {
+      const validYaml = "---\nid: RFC-0100\ntitle: Test\nstatus: draft\n---\n# Body\n";
+      await fs.writeFile(path.join(tmpDir, "rfc-0100-ok.md"), validYaml);
+
+      const result = await readAndParseRfc(tmpDir, "rfc-0100-ok.md");
+
+      expect(result).toBeDefined();
+      expect(result && "parsed" in result).toBe(true);
+      if (result && "parsed" in result) {
+        expect(result.parsed.frontmatter["id"]).toBe("RFC-0100");
+        expect(result.parsed.body).toContain("# Body");
+      }
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns error variant for non-existent file", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "rfc-parse-"));
+    try {
+      const result = await readAndParseRfc(tmpDir, "nonexistent.md");
+      expect(result).toBeDefined();
+      expect(result && "error" in result).toBe(true);
+      if (result && "error" in result) {
+        expect(result.error).toContain("YAML parse error");
+      }
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("parseRfcFile — basic parsing", () => {
+  test("parses valid frontmatter and body", () => {
+    const source = "---\nid: RFC-0100\n---\n# RFC-0100\n\nBody text.\n";
+    const result = parseRfcFile(source);
+    expect(result.frontmatter["id"]).toBe("RFC-0100");
+    expect(result.body).toContain("Body text.");
+  });
+
+  test("returns empty frontmatter when no frontmatter block", () => {
+    const source = "# Just a title\n\nNo frontmatter here.\n";
+    const result = parseRfcFile(source);
+    expect(result.frontmatter).toEqual({});
+    expect(result.body).toBe(source);
+  });
+});

package/os/rfc/frontmatter-io.ts

@@ -0,0 +1,130 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Shared RFC frontmatter file I/O — extracted from handlers.ts so both
+handlers.ts and acceptance.ts (RFC-0268) can read RFC files without a
+circular import between the two.
+</purpose>
+<non-goals>
+  <item>Do not validate frontmatter shape — that is handlers.ts / acceptance.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0268: extracted from handlers.ts to break a circular import with acceptance.ts.</item>
+  <item>Post-refactor hardening: added basename-based RFC id matching for archived RFC paths.</item>
+  <item>RFC-0521: added getRfcStatusById and loadRfcStatusMap helpers for plan/audit archive commands.</item>
+  <item>RFC-0755: readAndParseRfc now returns { fileName, error } on YAML parse failure instead of undefined.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+export interface ParsedRfc {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+export function parseRfcFile(source: string): ParsedRfc {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: source };
+  }
+  return {
+    frontmatter: (YAML.parse(match[1]!) ?? {}) as Record<string, unknown>,
+    body: match[2] ?? "",
+  };
+}
+
+export async function listRfcFiles(rfcDirPath: string): Promise<string[]> {
+  const results: string[] = [];
+
+  async function scanDir(dirPath: string, relativePrefix: string): Promise<void> {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+          await scanDir(path.join(dirPath, entry.name), relativePath);
+        } else if (
+          entry.isFile() &&
+          entry.name.endsWith(".md") &&
+          !entry.name.startsWith("rfc-0000") &&
+          entry.name !== "README.md"
+        ) {
+          results.push(relativePath);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or is unreadable — return empty
+    }
+  }
+
+  await scanDir(rfcDirPath, "");
+  return results.sort();
+}
+
+export function rfcFileMatchesId(fileName: string, targetId: string): boolean {
+  return path.basename(fileName).toLowerCase().startsWith(targetId.toLowerCase());
+}
+
+export type ReadAndParseRfcResult =
+  { fileName: string; parsed: ParsedRfc } | { fileName: string; error: string };
+
+export async function readAndParseRfc(
+  rfcDirPath: string,
+  fileName: string,
+): Promise<ReadAndParseRfcResult | undefined> {
+  try {
+    const filePath = path.join(rfcDirPath, fileName);
+    const content = await fs.readFile(filePath, "utf-8");
+    return { fileName, parsed: parseRfcFile(content) };
+  } catch (e) {
+    if (e instanceof Error) {
+      const linePos = (e as Error & { linePos?: Array<{ line: number; col: number }> }).linePos;
+      if (linePos?.length) {
+        const pos = linePos[0]!;
+        return {
+          fileName,
+          error: `YAML parse error at line ${pos.line}, column ${pos.col}: ${e.message}`,
+        };
+      }
+      return { fileName, error: `YAML parse error: ${e.message}` };
+    }
+    return { fileName, error: `YAML parse error: ${String(e)}` };
+  }
+}
+
+export async function getRfcStatusById(
+  rfcDirPath: string,
+  rfcId: string,
+): Promise<string | undefined> {
+  const files = await listRfcFiles(rfcDirPath);
+  for (const fileName of files) {
+    if (rfcFileMatchesId(fileName, rfcId)) {
+      const result = await readAndParseRfc(rfcDirPath, fileName);
+      if (result && "parsed" in result) {
+        const status = String(result.parsed.frontmatter["status"] ?? "").trim();
+        if (status) return status;
+      }
+    }
+  }
+  return undefined;
+}
+
+export async function loadRfcStatusMap(rfcDirPath: string): Promise<Map<string, string>> {
+  const files = await listRfcFiles(rfcDirPath);
+  const statusMap = new Map<string, string>();
+  for (const fileName of files) {
+    const result = await readAndParseRfc(rfcDirPath, fileName);
+    if (result && "parsed" in result) {
+      const id = String(result.parsed.frontmatter["id"] ?? "").trim();
+      const status = String(result.parsed.frontmatter["status"] ?? "").trim();
+      if (id && status) {
+        statusMap.set(id, status);
+      }
+    }
+  }
+  return statusMap;
+}