rahman-resources 1.4.0 → 1.6.0

package/bin/graph.mjs

@@ -6,15 +6,10 @@
 //   rr graph <slug>           → full DNA for a single slice + ASCII lineage tree
 //   rr graph <slug?> --json   → emit JSON instead of ASCII
 //
-// Dispatched from bin/cli.js. Imports from ../lib/dna.mjs.
+// Dispatched from bin/cli.js. ASCII renderers live in graph-render.mjs.
 
-import kleur from "kleur";
-
-import {
-  buildLineageGraph,
-  listAllDNA,
-  readDNA,
-} from "../lib/dna.mjs";
+import { buildLineageGraph, listAllDNA, readDNA } from "../lib/dna.mjs";
+import { printSummary, printSliceTree } from "./graph-render.mjs";
 
 /**
  * Entry point invoked by cli.js with the post-`graph` argv tail.
@@ -71,177 +66,3 @@ function parseFlags(rest) {
   }
   return { positional, flags };
 }
-
-// ─── ASCII renderers ──────────────────────────────────────────────────────
-
-function printSummary() {
-  const slices = listAllDNA();
-  if (slices.length === 0) {
-    console.log(
-      kleur.yellow("No DNA files in .kitab/lineage/. ") +
-        kleur.dim("Seed some via `rr graph` integrations or manual write."),
-    );
-    return;
-  }
-  console.log(kleur.bold(`\nDNA graph — ${slices.length} slice(s)\n`));
-
-  // Header table: slug | lineage count | consumers | newest source
-  const rows = [];
-  for (const dna of slices) {
-    const newest = dna.lineage[dna.lineage.length - 1];
-    rows.push({
-      slug: dna.id,
-      lineage: dna.lineage.length,
-      consumers: Object.keys(dna.consumers).length,
-      source: newest ? newest.from : "—",
-    });
-  }
-  const w1 = Math.max(4, ...rows.map((r) => r.slug.length));
-  const w4 = Math.max(6, ...rows.map((r) => String(r.source).length));
-  console.log(
-    "  " +
-      kleur.bold("slug".padEnd(w1)) +
-      "  " +
-      kleur.bold("hops".padEnd(4)) +
-      "  " +
-      kleur.bold("adopts".padEnd(6)) +
-      "  " +
-      kleur.bold("latest source".padEnd(w4)),
-  );
-  console.log(
-    "  " +
-      kleur.dim("-".repeat(w1)) +
-      "  " +
-      kleur.dim("----") +
-      "  " +
-      kleur.dim("------") +
-      "  " +
-      kleur.dim("-".repeat(w4)),
-  );
-  for (const r of rows) {
-    console.log(
-      "  " +
-        kleur.cyan(r.slug.padEnd(w1)) +
-        "  " +
-        String(r.lineage).padEnd(4) +
-        "  " +
-        String(r.consumers).padEnd(6) +
-        "  " +
-        kleur.dim(r.source),
-    );
-  }
-
-  // Consumer adoption matrix.
-  /** @type {Set<string>} */
-  const consumerSet = new Set();
-  for (const dna of slices) {
-    for (const c of Object.keys(dna.consumers)) consumerSet.add(c);
-  }
-  const consumers = [...consumerSet].sort();
-  if (consumers.length > 0) {
-    console.log(kleur.bold(`\nAdoption matrix\n`));
-    const cw = Math.max(4, ...rows.map((r) => r.slug.length));
-    console.log(
-      "  " +
-        " ".repeat(cw) +
-        "  " +
-        consumers
-          .map((c) => kleur.bold(c.slice(0, 10).padEnd(10)))
-          .join("  "),
-    );
-    for (const dna of slices) {
-      const cells = consumers
-        .map((c) => {
-          const ad = dna.consumers[c];
-          if (!ad) return kleur.dim("·".padEnd(10));
-          const drift = ad.drift_score;
-          const tag = `v${ad.version} ${drift}%`.slice(0, 10).padEnd(10);
-          if (drift >= 40) return kleur.red(tag);
-          if (drift >= 15) return kleur.yellow(tag);
-          return kleur.green(tag);
-        })
-        .join("  ");
-      console.log("  " + kleur.cyan(dna.id.padEnd(cw)) + "  " + cells);
-    }
-    console.log(
-      kleur.dim(
-        `\n  legend: green <15% drift, yellow 15-39%, red >=40%, · = not adopted`,
-      ),
-    );
-  }
-
-  console.log(
-    kleur.dim(
-      `\nRun \`rr graph <slug>\` for the full lineage tree, \`--json\` for machine output.\n`,
-    ),
-  );
-}
-
-function printSliceTree(slug) {
-  const dna = readDNA(slug);
-  if (!dna) {
-    console.error(
-      kleur.red(`✖ No DNA found for "${slug}".`) +
-        kleur.dim(`  (expected .kitab/lineage/${slug}.dna.json)`),
-    );
-    process.exit(1);
-  }
-  console.log(
-    `\n${kleur.bold(dna.id)}  ${kleur.dim(
-      `created ${dna.created_at}`,
-    )}\n`,
-  );
-
-  // Lineage chain — chronological top-down tree.
-  console.log(kleur.bold("Lineage"));
-  if (dna.lineage.length === 0) {
-    console.log("  " + kleur.dim("(no lineage entries)"));
-  } else {
-    const sorted = [...dna.lineage].sort((a, b) =>
-      String(a.at).localeCompare(String(b.at)),
-    );
-    sorted.forEach((entry, i) => {
-      const isLast = i === sorted.length - 1;
-      const bullet = isLast ? "└─" : "├─";
-      const cont = isLast ? "  " : "│ ";
-      console.log(
-        `  ${kleur.dim(bullet)} ${kleur.cyan(entry.from)}` +
-          (entry.to ? ` ${kleur.dim("→")} ${kleur.green(entry.to)}` : "") +
-          `  ${kleur.dim(entry.at)}`,
-      );
-      if (entry.transforms?.length) {
-        console.log(
-          `  ${kleur.dim(cont)}   ${kleur.dim("transforms:")} ${entry.transforms.join(", ")}`,
-        );
-      }
-      if (entry.actor) {
-        console.log(`  ${kleur.dim(cont)}   ${kleur.dim("actor:")} ${entry.actor}`);
-      }
-    });
-  }
-
-  // Consumer adoption rows.
-  console.log(`\n${kleur.bold("Consumers")}`);
-  const consumers = Object.entries(dna.consumers);
-  if (consumers.length === 0) {
-    console.log("  " + kleur.dim("(no consumers recorded)"));
-  } else {
-    const w = Math.max(4, ...consumers.map(([c]) => c.length));
-    for (const [name, ad] of consumers) {
-      const drift = ad.drift_score;
-      const driftStr =
-        drift >= 40
-          ? kleur.red(`${drift}%`)
-          : drift >= 15
-            ? kleur.yellow(`${drift}%`)
-            : kleur.green(`${drift}%`);
-      const sync = ad.last_synced_at ? ` synced ${ad.last_synced_at}` : "";
-      console.log(
-        `  ${kleur.cyan(name.padEnd(w))}  v${ad.version}  drift ${driftStr}  ${kleur.dim(
-          `adopted ${ad.adopted_at}${sync}`,
-        )}`,
-      );
-    }
-  }
-  console.log("");
-}

package/bin/migrate-load.mjs

@@ -0,0 +1,189 @@
+// migrate-load.mjs — contract-loading helpers for `rr migrate`.
+//
+// Extracted from migrate.mjs. Resolves on-disk vs historic contract files
+// (via git show) and evaluates them with `npx tsx` to JSON-serialize the
+// named `contract` export. Also exposes argv parsing + repo-root finder
+// shared with the dispatcher.
+
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+export function parseFlags(rest) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = rest[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+export function findRepoRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 8; i++) {
+    if (
+      existsSync(path.join(dir, "packages")) &&
+      existsSync(path.join(dir, "package.json"))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const SLICE_ROOTS = [
+  ["frontend", "slices"],
+  ["template-base", "frontend", "slices"],
+];
+
+function resolveContractPath(repoRoot, slug) {
+  for (const segs of SLICE_ROOTS) {
+    const p = path.join(repoRoot, ...segs, slug, "slice.contract.ts");
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+function resolveContractRelPath(repoRoot, slug) {
+  for (const segs of SLICE_ROOTS) {
+    const rel = [...segs, slug, "slice.contract.ts"].join("/");
+    if (existsSync(path.join(repoRoot, rel))) return rel;
+  }
+  return null;
+}
+
+export function loadCurrentContract(repoRoot, slug) {
+  const p = resolveContractPath(repoRoot, slug);
+  if (!p) return null;
+  return evalContract(repoRoot, p, null);
+}
+
+/**
+ * Resolve the contract at a historic version. Strategy:
+ *   1. Try git tags `v<ver>`, `<ver>`, `<slug>-v<ver>` against the contract file.
+ *   2. If none have the right version, scan recent commits touching the file
+ *      and pick the most recent one whose contract.version === fromVersion.
+ */
+export function loadHistoricContract(repoRoot, slug, fromVersion) {
+  const rel = resolveContractRelPath(repoRoot, slug);
+  if (!rel) return null;
+
+  const candidates = [`v${fromVersion}`, fromVersion, `${slug}-v${fromVersion}`];
+  for (const ref of candidates) {
+    const text = gitShowFile(repoRoot, ref, rel);
+    if (text) {
+      const c = evalContract(repoRoot, null, text);
+      if (c && c.version === fromVersion) return c;
+    }
+  }
+
+  // Fallback: scan commit history for the file.
+  const log = spawnSync("git", ["log", "--format=%H", "--", rel], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+  if (log.status === 0 && log.stdout) {
+    const hashes = log.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+    for (const sha of hashes) {
+      const text = gitShowFile(repoRoot, sha, rel);
+      if (!text) continue;
+      const c = evalContract(repoRoot, null, text);
+      if (c && c.version === fromVersion) return c;
+    }
+  }
+  return null;
+}
+
+function gitShowFile(repoRoot, ref, relPath) {
+  const res = spawnSync("git", ["show", `${ref}:${relPath}`], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+  if (res.status === 0 && typeof res.stdout === "string") return res.stdout;
+  return null;
+}
+
+/**
+ * Eval a contract file by spawning `npx tsx` and reading the JSON output.
+ * Pass `filePath` (absolute) for the on-disk version OR `inlineText` for a
+ * historic version pulled via git show.
+ */
+function evalContract(repoRoot, filePath, inlineText) {
+  if (filePath) {
+    const rel = "./" + path.relative(repoRoot, filePath);
+    const code = [
+      `import(${JSON.stringify(rel)})`,
+      `  .then(m => { const c = m.contract || (m.default && m.default.contract); if (!c) { process.exit(2); } process.stdout.write(JSON.stringify(c)); })`,
+      `  .catch((e) => { process.stderr.write(String(e && e.stack || e)); process.exit(3); });`,
+    ].join("\n");
+    const res = spawnSync("npx", ["--no-install", "tsx", "-e", code], {
+      cwd: repoRoot,
+      encoding: "utf8",
+    });
+    if (res.status === 0 && res.stdout) {
+      try {
+        return JSON.parse(res.stdout);
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  // Inline mode: write to a temp file under the kitab root (so its tsconfig +
+  // path aliases resolve) and eval. We use a `.migration-tmp/` folder so the
+  // temp file is colocated with packages/ but easy to ignore.
+  if (typeof inlineText !== "string") return null;
+  const tmpDir = path.join(repoRoot, ".migration-tmp");
+  mkdirSync(tmpDir, { recursive: true });
+  const tmpFile = path.join(
+    tmpDir,
+    `contract-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`,
+  );
+  try {
+    // Rewrite the import path back to the absolute kitab `contract` module so
+    // `../../../packages/cli/lib/contract` (from a historic file pulled via
+    // git show) keeps resolving after we move it to a different directory.
+    const adjusted = adjustContractImport(inlineText, repoRoot, tmpDir);
+    writeFileSync(tmpFile, adjusted);
+    return evalContract(repoRoot, tmpFile, null);
+  } finally {
+    try {
+      if (existsSync(tmpFile)) unlinkSync(tmpFile);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/**
+ * Replace any `from "..contract"` import in the contract body with an
+ * absolute path so the temp-file copy still resolves the same module.
+ */
+function adjustContractImport(text, repoRoot, tmpDir) {
+  const contractMod = path.join(repoRoot, "packages", "cli", "lib", "contract");
+  const relFromTmp = path
+    .relative(tmpDir, contractMod)
+    .split(path.sep)
+    .join("/");
+  // Match imports ending in /contract or /contract.ts (with or without .ts).
+  return text.replace(
+    /from\s+["'][^"']*\/contract(?:\.ts)?["']/g,
+    `from "${relFromTmp}"`,
+  );
+}

package/bin/migrate-print.mjs

@@ -0,0 +1,75 @@
+// migrate-print.mjs — ASCII rendering of a MigrationPlan.
+//
+// Extracted from migrate.mjs.
+
+import kleur from "kleur";
+
+export function printPlan(plan) {
+  const head = plan.summary.totalSteps === 0
+    ? kleur.green("✓ no migration needed")
+    : kleur.bold(`→ ${plan.slug}: v${plan.fromVersion} → v${plan.toVersion}`);
+  process.stdout.write(`\n${head}\n\n`);
+
+  if (plan.summary.totalSteps === 0) {
+    process.stdout.write(kleur.dim("  (contracts are equivalent — nothing to migrate)\n\n"));
+    return;
+  }
+
+  // Header row.
+  const cols = ["id", "kind", "risk", "rev", "description"];
+  const widths = [28, 26, 6, 4, 50];
+  const sep =
+    "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+\n";
+  const row = (vals) =>
+    "|" +
+    vals
+      .map((v, i) => " " + String(v).padEnd(widths[i]).slice(0, widths[i]) + " ")
+      .join("|") +
+    "|\n";
+
+  process.stdout.write(sep);
+  process.stdout.write(row(cols));
+  process.stdout.write(sep);
+  for (const step of plan.steps) {
+    process.stdout.write(
+      row([
+        step.id,
+        step.kind,
+        step.risk,
+        step.reversible ? "yes" : "NO",
+        step.description.replace(/\s+/g, " ").slice(0, widths[4]),
+      ]),
+    );
+  }
+  process.stdout.write(sep);
+
+  // Per-step detail.
+  for (const step of plan.steps) {
+    process.stdout.write(`\n${kleur.bold(step.id)} ${kleur.dim("(" + step.kind + ")")}\n`);
+    process.stdout.write(`  ${step.description}\n`);
+    if (step.artifacts.note) {
+      process.stdout.write(`  ${kleur.dim("note:")} ${step.artifacts.note}\n`);
+    }
+    if (step.artifacts.envExample) {
+      process.stdout.write(`  ${kleur.dim(".env.example:")} ${step.artifacts.envExample}\n`);
+    }
+  }
+
+  process.stdout.write(
+    `\n${kleur.bold("summary")}: ${plan.summary.totalSteps} step(s) — ` +
+      `${kleur.red(plan.summary.highRisk + " high-risk")}, ` +
+      `${kleur.yellow(plan.summary.irreversible + " irreversible")}\n`,
+  );
+
+  if (plan.warnings.length > 0) {
+    process.stdout.write(`\n${kleur.bold("warnings:")}\n`);
+    for (const w of plan.warnings) {
+      process.stdout.write(`  ${kleur.yellow("⚠")} ${w}\n`);
+    }
+  }
+  process.stdout.write(
+    `\n${kleur.dim(
+      "pass --json for machine-readable output, --write-files to materialize convex/migrations/.",
+    )}\n\n`,
+  );
+}