@rafinery/cli 0.3.0 → 0.4.1

package/lib/gate/compile.mjs

@@ -0,0 +1,549 @@
+// The contract gate — the deterministic compiler between the agents' markdown and
+// the platform. Lives INSIDE @rafinery/cli (blueprint split, 0.4.0): the gate moves
+// with the CLI version, never vendored. Reads every brain file, parses frontmatter
+// with a STRICT grammar (contract §0), validates against the contract, and on
+// success emits .rafa/manifest.json — the exact JSON the platform ingests.
+//
+// NO ASSUMPTIONS: a missing required field, a bad enum, or a malformed cite is a
+// hard error (path · field · rule). It never fills a default for a required field.
+// Returns exit code 1 with a structured error list so the authoring agent can
+// correct + retry.
+//
+// CLI:  rafa compile [--repo=owner/repo] [--branch=main] [--codeSha=<sha>] [--root=.rafa]
+
+import {
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  existsSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+const SCHEMA_VERSION = 1;
+
+// ── strict frontmatter parser (contract §0 grammar) ─────────────────────────
+// Legal value forms only: scalar | "quoted" | [flow,list] | { flow: map }.
+// Plus `key:` followed by `  - item` block lists and folded scalars. Anything
+// else → error.
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (s === "") return "";
+  if (/^".*"$/.test(s) || /^'.*'$/.test(s)) return s.slice(1, -1);
+  if (s === "true") return true;
+  if (s === "false") return false;
+  if (/^-?\d+$/.test(s)) return Number(s);
+  return s;
+}
+// Strip a trailing YAML comment ( whitespace + # … ) from an UNQUOTED top-level
+// scalar. Not applied to block-list items (cites/links are exact strings that may
+// legitimately contain `#`).
+function stripComment(s) {
+  if (/^["']/.test(s.trim())) return s;
+  const i = s.search(/\s#/);
+  return i === -1 ? s : s.slice(0, i);
+}
+function parseFlowList(raw) {
+  const inner = raw.trim().slice(1, -1).trim();
+  if (inner === "") return [];
+  return inner.split(",").map((x) => parseScalar(x));
+}
+function parseFlowMap(raw) {
+  const inner = raw.trim().slice(1, -1).trim();
+  const out = {};
+  if (inner === "") return out;
+  for (const pair of inner.split(",")) {
+    const i = pair.indexOf(":");
+    if (i === -1) return null; // malformed
+    out[pair.slice(0, i).trim()] = parseScalar(pair.slice(i + 1));
+  }
+  return out;
+}
+// Returns { data } or { error: "reason" }.
+export function parseFrontmatter(text) {
+  if (!text.startsWith("---")) return { error: "no frontmatter block" };
+  const end = text.indexOf("\n---", text.indexOf("\n"));
+  if (end === -1) return { error: "unterminated frontmatter" };
+  const lines = text.slice(text.indexOf("\n") + 1, end).split("\n");
+  const data = {};
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*):(.*)$/);
+    if (!m) return { error: `illegal line: ${JSON.stringify(line)}` };
+    const key = m[1];
+    // Strip a trailing comment first, so `cites:   # note` reads as an empty value
+    // (block list follows), not as the comment being the value.
+    const rest = stripComment(m[2]).trim();
+    if (rest === "") {
+      // block list follows
+      const items = [];
+      while (i + 1 < lines.length && /^\s*-\s+/.test(lines[i + 1])) {
+        items.push(parseScalar(lines[++i].replace(/^\s*-\s+/, "")));
+      }
+      data[key] = items;
+    } else if (rest === ">-" || rest === ">") {
+      // folded scalar (contract §0): indented continuation lines join with one space
+      const parts = [];
+      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
+        parts.push(lines[++i].trim());
+      }
+      data[key] = parts.join(" ");
+    } else if (rest.startsWith("[")) {
+      const close = rest.lastIndexOf("]"); // ignore any trailing comment after ]
+      if (close === -1) return { error: `unclosed flow list at ${key}` };
+      data[key] = parseFlowList(rest.slice(0, close + 1));
+    } else if (rest.startsWith("{")) {
+      const close = rest.lastIndexOf("}");
+      if (close === -1) return { error: `unclosed flow map at ${key}` };
+      const fm = parseFlowMap(rest.slice(0, close + 1));
+      if (fm === null) return { error: `malformed flow map at ${key}` };
+      data[key] = fm;
+    } else {
+      data[key] = parseScalar(rest);
+    }
+  }
+  return { data };
+}
+
+const CITE_RE = /^(.+):(\d+(?:-\d+)?)\s*::\s*(.+)$/;
+const DUTY_RE = /^(\S[^:]*?)\s+::\s+(\S+)\s+::\s+(\S.*)$/;
+
+export function runCompile(argv = []) {
+  const arg = (k, d) => {
+    const m = argv.find((a) => a.startsWith(`--${k}=`));
+    return m ? m.slice(k.length + 3) : d;
+  };
+  const ROOT = arg("root", ".rafa");
+  // Paths in the manifest are relative to the brain-repo root (`.rafa/` IS the root),
+  // so the platform can fetch a prose body straight from the brain repo.
+  const rel = (p) => (p.startsWith(ROOT + "/") ? p.slice(ROOT.length + 1) : p);
+
+  const errors = [];
+  const fail = (path, field, rule) => errors.push({ path, field, rule });
+
+  // ── validators (contract §2–§6) ────────────────────────────────────────────
+  function parseCites(list, path) {
+    if (!Array.isArray(list) || list.length === 0) {
+      fail(path, "cites", "required · ≥ 1");
+      return [];
+    }
+    const out = [];
+    for (const c of list) {
+      const m = String(c).match(CITE_RE);
+      if (!m) {
+        fail(path, "cites", `malformed cite: ${JSON.stringify(c)}`);
+        continue;
+      }
+      out.push({ file: m[1].trim(), line: m[2], token: m[3].trim() });
+    }
+    return out;
+  }
+  const isEnum = (v, allowed) => allowed.includes(v);
+  function reqStr(d, key, path) {
+    const v = d[key];
+    if (typeof v !== "string" || v.trim() === "") {
+      fail(path, key, "required · non-empty string");
+      return "";
+    }
+    return v;
+  }
+  function reqEnum(d, key, allowed, path) {
+    const v = d[key];
+    if (!isEnum(v, allowed)) {
+      fail(path, key, `required · one of ${allowed.join("|")}`);
+      return allowed[0];
+    }
+    return v;
+  }
+  function checkVersion(d, path) {
+    if (d.schemaVersion !== SCHEMA_VERSION)
+      fail(path, "schemaVersion", `must be ${SCHEMA_VERSION}`);
+  }
+  function checkId(d, path, name) {
+    const stem = name.replace(/\.md$/, "");
+    if (d.id !== stem) fail(path, "id", `must equal filename stem "${stem}"`);
+    return stem;
+  }
+
+  function walk(dir) {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir).flatMap((e) => {
+      const p = join(dir, e);
+      return statSync(p).isDirectory()
+        ? walk(p)
+        : e.endsWith(".md") && !e.startsWith("_")
+          ? [p]
+          : [];
+    });
+  }
+  const read = (p) => readFileSync(p, "utf8");
+
+  function compileNotes(kind, dir) {
+    const notes = [];
+    for (const path of walk(dir)) {
+      const name = path.split("/").pop();
+      const { data, error } = parseFrontmatter(read(path));
+      if (error) {
+        fail(path, "frontmatter", error);
+        continue;
+      }
+      checkVersion(data, path);
+      const id = checkId(data, path, name);
+      notes.push({
+        id,
+        kind,
+        type: reqEnum(data, "type", ["contract", "convention", "flow", "how-to"], path),
+        domain: reqStr(data, "domain", path),
+        title: reqStr(data, "title", path),
+        summary: reqStr(data, "summary", path),
+        links: Array.isArray(data.links) ? data.links.map(String) : [],
+        ...(data.failure === "silent" || data.failure === "loud"
+          ? { failure: data.failure }
+          : {}),
+        cites: parseCites(data.cites, path),
+        path: rel(path),
+      });
+    }
+    return notes;
+  }
+
+  function compileImprovements(dir) {
+    const out = [];
+    for (const path of walk(dir)) {
+      const name = path.split("/").pop();
+      const { data, error } = parseFrontmatter(read(path));
+      if (error) {
+        fail(path, "frontmatter", error);
+        continue;
+      }
+      checkVersion(data, path);
+      const id = checkId(data, path, name);
+      const lev = data.leverage;
+      if (
+        typeof lev !== "object" ||
+        !isEnum(lev?.impact, ["low", "medium", "high"]) ||
+        !isEnum(lev?.effort, ["low", "medium", "high"])
+      )
+        fail(path, "leverage", "required · { impact, effort } ∈ low|medium|high");
+      out.push({
+        id,
+        priority: reqEnum(data, "priority", ["P0", "P1", "P2", "P3"], path),
+        lens: reqEnum(
+          data,
+          "lens",
+          ["security", "correctness", "performance", "architecture", "product", "ops"],
+          path,
+        ),
+        status: reqEnum(data, "status", ["open", "backlog", "fixed", "wontfix"], path),
+        title: reqStr(data, "title", path),
+        summary: reqStr(data, "summary", path),
+        fix: reqStr(data, "fix", path),
+        leverage: {
+          impact: lev?.impact ?? "low",
+          effort: lev?.effort ?? "low",
+        },
+        blastRadius: Array.isArray(data.blast_radius)
+          ? data.blast_radius.map(String)
+          : [],
+        cites: parseCites(data.cites, path),
+        path: rel(path),
+      });
+    }
+    return out;
+  }
+
+  function compileHealth() {
+    const path = join(ROOT, "brain", "checklist.md");
+    if (!existsSync(path)) return null;
+    const { data, error } = parseFrontmatter(read(path));
+    if (error) {
+      fail(path, "frontmatter", error);
+      return null;
+    }
+    checkVersion(data, path);
+    const g = data.gates,
+      c = data.counts;
+    if (!isEnum(g?.fidelity, ["pass", "fail"]) || !isEnum(g?.coverage, ["pass", "fail"]))
+      fail(path, "gates", "required · { fidelity, coverage } ∈ pass|fail");
+    if (
+      typeof c?.blockers !== "number" ||
+      typeof c?.majors !== "number" ||
+      typeof c?.minors !== "number"
+    )
+      fail(path, "counts", "required · { blockers, majors, minors } ints");
+    if (typeof data.score !== "number") fail(path, "score", "required · 0–100 int");
+    return {
+      verdict: reqEnum(data, "verdict", ["PASS", "ITERATE"], path),
+      score: typeof data.score === "number" ? data.score : 0,
+      gates: { fidelity: g?.fidelity ?? "fail", coverage: g?.coverage ?? "fail" },
+      counts: {
+        blockers: c?.blockers ?? 0,
+        majors: c?.majors ?? 0,
+        minors: c?.minors ?? 0,
+      },
+    };
+  }
+
+  function compileLedger() {
+    const path = join(ROOT, "improve", "ledger.md");
+    if (!existsSync(path)) return null;
+    const { data, error } = parseFrontmatter(read(path));
+    if (error) {
+      fail(path, "frontmatter", error);
+      return null;
+    }
+    checkVersion(data, path);
+    const bp = data.by_priority;
+    const okBp =
+      bp && ["P0", "P1", "P2", "P3"].every((k) => typeof bp[k] === "number");
+    if (!okBp) fail(path, "by_priority", "required · { P0, P1, P2, P3 } ints");
+    if (typeof data.open !== "number") fail(path, "open", "required · int");
+    if (typeof data.debt_score !== "number")
+      fail(path, "debt_score", "required · int");
+    return {
+      open: typeof data.open === "number" ? data.open : 0,
+      debtScore: typeof data.debt_score === "number" ? data.debt_score : 0,
+      byPriority: okBp
+        ? { P0: bp.P0, P1: bp.P1, P2: bp.P2, P3: bp.P3 }
+        : { P0: 0, P1: 0, P2: 0, P3: 0 },
+    };
+  }
+
+  function compileCoverage() {
+    const path = join(ROOT, "brain", "coverage.md");
+    if (!existsSync(path)) return null;
+    const { data, error } = parseFrontmatter(read(path));
+    if (error) {
+      fail(path, "frontmatter", error);
+      return null;
+    }
+    checkVersion(data, path);
+    const d = data.domains;
+    if (typeof d !== "object" || Array.isArray(d)) {
+      fail(path, "domains", "required · { domain: status } flow map");
+      return { domains: [] };
+    }
+    const STATUS = ["mapped", "thin", "stubbed", "empty"];
+    const domains = [];
+    for (const [domain, status] of Object.entries(d)) {
+      if (!STATUS.includes(status))
+        fail(path, `domains.${domain}`, `status ∈ ${STATUS.join("|")}`);
+      domains.push({ domain, status: String(status) });
+    }
+    return { domains };
+  }
+
+  // Plans (contract §7): parent+child files under plans/**. Global id uniqueness,
+  // parent/child cross-checks, progress never stored, active.md → activePlanId.
+  // VALIDATED here (files are the authoring surface — determinism holds) but
+  // since 0.4.0 plans do NOT ride the manifest: they travel through the
+  // dedicated push-on-approval plans channel (push_plan). Terminal statuses
+  // (superseded/abandoned) close a plan honestly without pretending `done`.
+  const PLAN_STATUSES = [
+    "todo",
+    "in-progress",
+    "done",
+    "blocked",
+    "superseded",
+    "abandoned",
+  ];
+  function compilePlans() {
+    const plans = [];
+    const seen = new Map(); // id → path (global uniqueness across plans/**)
+    for (const path of walk(join(ROOT, "plans"))) {
+      const name = path.split("/").pop();
+      const { data, error } = parseFrontmatter(read(path));
+      if (error) {
+        fail(path, "frontmatter", error);
+        continue;
+      }
+      checkVersion(data, path);
+      const id = checkId(data, path, name);
+      if (seen.has(id))
+        fail(path, "id", `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`);
+      seen.set(id, path);
+      if ("progress" in data)
+        fail(path, "progress", "never stored · parent progress is derived by counting children");
+      const kind = reqEnum(data, "kind", ["parent", "child"], path);
+      const plan = reqStr(data, "plan", path);
+      const status = data.status;
+      if (kind === "child") {
+        if (!isEnum(status, PLAN_STATUSES))
+          fail(path, "status", `required (child) · ${PLAN_STATUSES.join("|")}`);
+        if (data.parent !== plan)
+          fail(path, "parent", `must equal plan "${plan}" for a child (flat v1)`);
+      } else {
+        if (data.parent !== null && data.parent !== "null")
+          fail(path, "parent", "must be null for kind: parent");
+        if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: parent`);
+        if (status !== undefined && !isEnum(status, PLAN_STATUSES))
+          fail(path, "status", `optional (parent) · ${PLAN_STATUSES.join("|")}`);
+      }
+      plans.push({
+        id,
+        plan,
+        parent: kind === "parent" ? null : plan,
+        kind,
+        title: reqStr(data, "title", path),
+        ...(isEnum(status, PLAN_STATUSES) ? { status } : {}),
+        ...(typeof data.branch === "string" && data.branch !== ""
+          ? { branch: data.branch }
+          : {}),
+        ...(typeof data.baseSha === "string" && data.baseSha !== ""
+          ? { baseSha: String(data.baseSha) }
+          : {}),
+        path: rel(path),
+      });
+    }
+    // Cross-check: every child's plan resolves to a kind:parent in this compile.
+    const parents = new Set(plans.filter((p) => p.kind === "parent").map((p) => p.id));
+    for (const p of plans)
+      if (p.kind === "child" && !parents.has(p.plan))
+        fail(p.path, "plan", `no parent plan "${p.plan}" in this compile (dangling child)`);
+    return plans;
+  }
+
+  // active.md (generated pointer) → activePlanId. First line `# <plan-id>` must
+  // resolve to a kind:parent plan; `# No active plan` or a missing file → null
+  // (documented default: the pointer is generated, absence means "none").
+  function compileActivePlanId(plans) {
+    const path = join(ROOT, "active.md");
+    if (!existsSync(path)) return null;
+    const first = read(path).split("\n")[0].trim();
+    const m = first.match(/^#\s+(.+)$/);
+    if (!m) {
+      fail(path, "pointer", 'first line must be "# <plan-id>" or "# No active plan"');
+      return null;
+    }
+    const val = m[1].trim();
+    if (/^no active plan$/i.test(val)) return null;
+    if (!plans.some((p) => p.kind === "parent" && p.id === val)) {
+      fail(path, "pointer", `active plan "${val}" is not a kind:parent plan in this compile`);
+      return null;
+    }
+    return val;
+  }
+
+  // Agent cards (contract §10): the shipped agents are contract-governed — validated
+  // as a LOCAL gate, never emitted into the manifest. Cards live in the CODE repo at
+  // .claude/agents/*.md. Duty SOP paths resolve against the code-repo root
+  // (.claude/skills/rafa-*/SKILL.md); legacy `.rafa/`-relative paths still resolve
+  // during the migration window.
+  function compileAgentCards() {
+    const repoRoot = join(ROOT, "..");
+    const dir = join(repoRoot, ".claude", "agents");
+    let count = 0;
+    for (const path of walk(dir)) {
+      const name = path.split("/").pop();
+      const { data, error } = parseFrontmatter(read(path));
+      if (error) {
+        fail(path, "frontmatter", error);
+        continue;
+      }
+      count++;
+      const stem = name.replace(/\.md$/, "");
+      if (data.name !== stem) fail(path, "name", `must equal filename stem "${stem}"`);
+      if (!/^\d+\.\d+\.\d+$/.test(String(data.version ?? "")))
+        fail(path, "version", "required · semver MAJOR.MINOR.PATCH");
+      reqStr(data, "model", path);
+      reqStr(data, "description", path);
+      reqStr(data, "tools", path);
+      reqEnum(
+        data,
+        "groundTruth",
+        ["code-at-sha", "code-vs-claim", "code-trend", "sessions-over-time"],
+        path,
+      );
+      const duties = data.duties;
+      if (!Array.isArray(duties) || duties.length === 0) {
+        fail(path, "duties", "required · block list of ≥ 1 duty DSL strings");
+        continue;
+      }
+      for (const d of duties) {
+        const m = String(d).match(DUTY_RE);
+        if (!m) {
+          fail(path, "duties", `malformed duty (want "<duty> :: <sop> :: <bar>"): ${JSON.stringify(d)}`);
+          continue;
+        }
+        const sop = m[2];
+        if (!existsSync(join(repoRoot, sop)) && !existsSync(join(ROOT, sop)))
+          fail(path, "duties", `sop does not resolve: ${sop} (a duty without a procedure is a claim)`);
+      }
+    }
+    return count;
+  }
+
+  // ── assemble ─────────────────────────────────────────────────────────────
+  const gitOpts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }; // no stderr leak
+  function gitSha() {
+    try {
+      return execSync("git rev-parse HEAD", gitOpts).trim();
+    } catch {
+      return arg("codeSha", "");
+    }
+  }
+  function gitBranch() {
+    try {
+      return execSync("git rev-parse --abbrev-ref HEAD", gitOpts).trim();
+    } catch {
+      return arg("branch", "main");
+    }
+  }
+
+  const notes = [
+    ...compileNotes("rule", join(ROOT, "brain", "rules")),
+    ...compileNotes("playbook", join(ROOT, "brain", "playbooks")),
+  ];
+  const improvements = compileImprovements(join(ROOT, "improve", "improvements"));
+  const health = compileHealth();
+  const ledger = compileLedger();
+  const coverage = compileCoverage();
+  const plans = compilePlans();
+  const activePlanId = compileActivePlanId(plans);
+  const agentCards = compileAgentCards();
+
+  // Cross-check: ledger.open / by_priority must match the actual open improvements.
+  if (ledger) {
+    const open = improvements.filter((i) => i.status === "open");
+    const bp = { P0: 0, P1: 0, P2: 0, P3: 0 };
+    for (const i of open) bp[i.priority]++;
+    if (ledger.open !== open.length)
+      fail("improve/ledger.md", "open", `says ${ledger.open}, rows have ${open.length}`);
+    for (const k of ["P0", "P1", "P2", "P3"])
+      if (ledger.byPriority[k] !== bp[k])
+        fail("improve/ledger.md", `by_priority.${k}`, `says ${ledger.byPriority[k]}, rows have ${bp[k]}`);
+  }
+
+  if (errors.length) {
+    console.error(`✗ rafa compile: ${errors.length} contract violation(s)\n`);
+    for (const e of errors) console.error(`  ${e.path}  ·  ${e.field}  ·  ${e.rule}`);
+    console.error(`\nFix these files to match the contract (.claude/rafa/contract.md), then re-run compile.`);
+    return 1;
+  }
+
+  // The manifest carries KNOWLEDGE only (plans channel, 0.4.0): plans + the
+  // active pointer are validated above but travel through push_plan, never here.
+  const manifest = {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    repo: arg("repo", ""),
+    branch: gitBranch(),
+    codeSha: gitSha(),
+    health,
+    ledger,
+    coverage,
+    notes,
+    improvements,
+  };
+  writeFileSync(join(ROOT, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  console.log(
+    `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
+      `${plans.length} plans validated${activePlanId ? ` (active: ${activePlanId})` : ""} (plans travel via the plans channel, not the manifest) · ` +
+      `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
+      `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} · ` +
+      `${agentCards} agent cards (local gate) → ${ROOT}/manifest.json`,
+  );
+  return 0;
+}