rahman-resources 1.4.0 → 1.6.0

package/lib/compose-solver-resolve.mjs

@@ -0,0 +1,165 @@
+// compose-solver-resolve.mjs — desired-set normalisation + BFS dep resolution.
+//
+// Pure functions extracted from compose-solver.mjs. Operate on candidate
+// state (Sets + arrays) — no I/O, no mutation of the caller's `contracts`
+// map. Returns the new candidate state + an updated `proof`/`notes` log.
+
+/**
+ * Fold the user's `desired` list into a candidate set, classifying each entry
+ * as contracted (with a known contract) or uncontracted (allowed under
+ * `allowUnknownSlices`, otherwise rejected with a `missing-dep` blocker).
+ *
+ * Side-effects via the `record` callback — caller owns the conflict store.
+ */
+export function buildInitialCandidates({
+  desired,
+  contracts,
+  allowUnknownSlices,
+  record,
+  proof,
+  notes,
+  uncontractedDesired,
+}) {
+  const candidateOrder = [];
+  const candidateSet = new Set();
+
+  for (const slug of desired) {
+    if (candidateSet.has(slug)) continue;
+    const contract = contracts.get(slug);
+    if (!contract) {
+      if (allowUnknownSlices) {
+        record(
+          {
+            type: "uncontracted",
+            slug,
+            detail: `Slice "${slug}" has no registered slice.contract.ts — accepted under allowUnknownSlices, but conflict checks are skipped for it.`,
+            severity: "warning",
+          },
+          slug,
+        );
+        uncontractedDesired.add(slug);
+        candidateSet.add(slug);
+        candidateOrder.push(slug);
+        notes.set(slug, "uncontracted");
+        proof.push(`! ${slug}: accepted as uncontracted (no slice.contract.ts; skipping conflict checks)`);
+      } else {
+        record(
+          {
+            type: "missing-dep",
+            slug,
+            detail: `Contract not found for "${slug}" — no slice.contract.ts registered (strict mode).`,
+            severity: "blocker",
+          },
+          slug,
+        );
+        proof.push(`- ${slug}: rejected (no contract found, strict mode)`);
+      }
+      continue;
+    }
+    candidateSet.add(slug);
+    candidateOrder.push(slug);
+  }
+  return { candidateOrder, candidateSet };
+}
+
+/**
+ * BFS over `requires.deps`, pulling transitive deps into the candidate set.
+ * Throws on cycles. Pushes informational lines to `proof`. Returns nothing —
+ * mutates `candidateOrder` / `candidateSet` in place.
+ */
+export function resolveDependencies({
+  candidateOrder,
+  candidateSet,
+  contracts,
+  installed,
+  record,
+  proof,
+}) {
+  /** @type {Array<{ slug: string; chain: string[] }>} */
+  const queue = candidateOrder
+    .filter((s) => contracts.has(s))
+    .map((slug) => ({ slug, chain: [slug] }));
+  while (queue.length > 0) {
+    const { slug, chain } = queue.shift();
+    const contract = contracts.get(slug);
+    const deps = contract?.requires?.deps ?? [];
+    for (const dep of deps) {
+      if (chain.includes(dep)) {
+        const cyclePath = [...chain.slice(chain.indexOf(dep)), dep].join(" → ");
+        throw new Error(`dependency cycle detected: ${cyclePath}`);
+      }
+      if (installed.has(dep)) continue;
+      if (candidateSet.has(dep)) continue;
+      const depContract = contracts.get(dep);
+      if (!depContract) {
+        record(
+          {
+            type: "missing-dep",
+            slug,
+            withSlug: dep,
+            detail: `Slice "${slug}" requires "${dep}" but no contract is registered for it.`,
+            severity: "blocker",
+          },
+          slug,
+        );
+        proof.push(`- ${slug}: missing dep "${dep}" (not in candidates, not installed)`);
+        continue;
+      }
+      candidateSet.add(dep);
+      candidateOrder.push(dep);
+      proof.push(`+ ${dep}: pulled in as transitive dep of ${slug}`);
+      queue.push({ slug: dep, chain: [...chain, dep] });
+    }
+  }
+}
+
+/**
+ * Without dependency resolution: surface every unmet `requires.deps` entry
+ * as a blocker. Used when the caller passed `resolveDeps: false`.
+ */
+export function reportUnresolvedDeps({
+  candidateOrder,
+  candidateSet,
+  contracts,
+  installed,
+  record,
+}) {
+  for (const slug of candidateOrder) {
+    const deps = contracts.get(slug)?.requires?.deps ?? [];
+    for (const dep of deps) {
+      if (installed.has(dep) || candidateSet.has(dep)) continue;
+      record(
+        {
+          type: "missing-dep",
+          slug,
+          withSlug: dep,
+          detail: `Slice "${slug}" requires "${dep}" (resolveDeps disabled — not auto-pulled).`,
+          severity: "blocker",
+        },
+        slug,
+      );
+    }
+  }
+}
+
+/**
+ * For each candidate, count how many OTHER candidates list it in their
+ * `requires.deps[]`. Used for arbitration tiebreaks.
+ *
+ * @returns {Map<string, number>}
+ */
+export function computeDependersCount(candidateOrder, contracts) {
+  /** @type {Map<string, number>} */
+  const dependersCount = new Map();
+  for (const slug of candidateOrder) dependersCount.set(slug, 0);
+  for (const slug of candidateOrder) {
+    const c = contracts.get(slug);
+    if (!c) continue;
+    for (const d of c.requires?.deps ?? []) {
+      if (dependersCount.has(d)) {
+        dependersCount.set(d, (dependersCount.get(d) ?? 0) + 1);
+      }
+    }
+  }
+  return dependersCount;
+}

package/lib/compose-solver.mjs

@@ -12,88 +12,31 @@
 // Public API + types live in compose-solver.d.ts.
 //
 // Runtime contract:
-//   - `loadAllContracts(repoRoot)` is the only I/O entry point. It mirrors
-//     scripts/validation/validate-contract.mjs's tsx-eval strategy.
+//   - `loadAllContracts(repoRoot)` (re-exported from compose-solver-loader)
+//     is the only I/O entry point.
 //   - `compose(req, contracts)` is pure — no fs, no env access, no mutation
 //     of inputs. Always returns a fresh result object.
-
-import { readdir } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import path from "node:path";
-
-// ---------------------------------------------------------------------------
-// Public — loadAllContracts
-// ---------------------------------------------------------------------------
-
-const SLICE_ROOT_GLOBS = [
-  ["frontend", "slices"],
-  ["template-base", "frontend", "slices"],
-];
-
-/**
- * Discover every `slice.contract.ts` under the kitab's known slice roots and
- * load them via `npx tsx`. Returns a Map<slug, SliceContract>. Contracts that
- * fail to load are silently skipped so a single broken file doesn't take
- * down the whole solver — `npm run validate:contracts` is the place to surface
- * those errors.
- *
- * @param {string} repoRoot Absolute path to the kitab repo root.
- * @returns {Promise<Map<string, import("./contract").SliceContract>>}
- */
-export async function loadAllContracts(repoRoot) {
-  /** @type {Map<string, import("./contract").SliceContract>} */
-  const out = new Map();
-  const sliceFiles = await discoverContractFiles(repoRoot);
-  for (const filePath of sliceFiles) {
-    const contract = loadContractFile(repoRoot, filePath);
-    if (contract && typeof contract.id === "string") {
-      out.set(contract.id, contract);
-    }
-  }
-  return out;
-}
-
-async function discoverContractFiles(repoRoot) {
-  const found = [];
-  for (const segs of SLICE_ROOT_GLOBS) {
-    const root = path.join(repoRoot, ...segs);
-    if (!existsSync(root)) continue;
-    const entries = await readdir(root, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      if (entry.name.startsWith("_")) continue;
-      const filePath = path.join(root, entry.name, "slice.contract.ts");
-      if (existsSync(filePath)) found.push(filePath);
-    }
-  }
-  return found;
-}
-
-/**
- * Dynamic-import a .ts contract file via `npx tsx -e` and JSON.parse the
- * stringified `contract` export. Returns null on any failure.
- */
-function loadContractFile(repoRoot, 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(() => 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;
-}
+//
+// Module split (kept ≤200 LOC each):
+//   - compose-solver-loader.mjs      — contract discovery + tsx-eval
+//   - compose-solver-resolve.mjs     — desired-set + BFS dep resolution
+//   - compose-solver-conflicts.mjs   — surface checks + pair arbitration
+
+import {
+  buildInitialCandidates,
+  resolveDependencies,
+  reportUnresolvedDeps,
+  computeDependersCount,
+} from "./compose-solver-resolve.mjs";
+import {
+  runSurfaceChecks,
+  buildProvidesLookup,
+  makeArbitrator,
+  detectPairwiseCollisions,
+  detectExplicitConflicts,
+} from "./compose-solver-conflicts.mjs";
+
+export { loadAllContracts } from "./compose-solver-loader.mjs";
 
 // ---------------------------------------------------------------------------
 // Public — compose
@@ -129,6 +72,8 @@ export function compose(req, contracts) {
   const notes = new Map();
   /** @type {Set<string>} */
   const uncontractedDesired = new Set();
+  /** @type {Set<string>} */
+  const userTyped = new Set(desired);
 
   // Helper: record a conflict and (if blocker) attribute it to a slug.
   function record(conflict, attributeTo = conflict.slug) {
@@ -141,310 +86,31 @@ export function compose(req, contracts) {
   }
 
   // ── Step 1: validate desired entries, then BFS-resolve transitive deps. ──
-  /** @type {string[]} */
-  const candidateOrder = [];
-  const candidateSet = new Set();
-  /** @type {Set<string>} */
-  const userTyped = new Set(desired);
-
-  // First, fold in each desired slug. Unknown contracts are blocker-rejected
-  // (strict mode) or warning-accepted (default, `allowUnknownSlices: true`).
-  for (const slug of desired) {
-    if (candidateSet.has(slug)) continue;
-    const contract = contracts.get(slug);
-    if (!contract) {
-      if (allowUnknownSlices) {
-        record(
-          {
-            type: "uncontracted",
-            slug,
-            detail: `Slice "${slug}" has no registered slice.contract.ts — accepted under allowUnknownSlices, but conflict checks are skipped for it.`,
-            severity: "warning",
-          },
-          slug,
-        );
-        uncontractedDesired.add(slug);
-        candidateSet.add(slug);
-        candidateOrder.push(slug);
-        notes.set(slug, "uncontracted");
-        proof.push(`! ${slug}: accepted as uncontracted (no slice.contract.ts; skipping conflict checks)`);
-      } else {
-        record(
-          {
-            type: "missing-dep",
-            slug,
-            detail: `Contract not found for "${slug}" — no slice.contract.ts registered (strict mode).`,
-            severity: "blocker",
-          },
-          slug,
-        );
-        proof.push(`- ${slug}: rejected (no contract found, strict mode)`);
-      }
-      continue;
-    }
-    candidateSet.add(slug);
-    candidateOrder.push(slug);
-  }
+  const { candidateOrder, candidateSet } = buildInitialCandidates({
+    desired, contracts, allowUnknownSlices, record, proof, notes, uncontractedDesired,
+  });
 
   if (resolveDeps) {
-    // BFS over requires.deps[]. We use a proper visited-path map per starting
-    // root so we can print the full cycle when one is encountered.
-    /** @type {Array<{ slug: string; chain: string[] }>} */
-    const queue = candidateOrder
-      .filter((s) => contracts.has(s))
-      .map((slug) => ({ slug, chain: [slug] }));
-    while (queue.length > 0) {
-      const { slug, chain } = queue.shift();
-      const contract = contracts.get(slug);
-      const deps = contract?.requires?.deps ?? [];
-      for (const dep of deps) {
-        if (chain.includes(dep)) {
-          const cyclePath = [...chain.slice(chain.indexOf(dep)), dep].join(" → ");
-          throw new Error(`dependency cycle detected: ${cyclePath}`);
-        }
-        if (installed.has(dep)) {
-          continue;
-        }
-        if (candidateSet.has(dep)) continue;
-        const depContract = contracts.get(dep);
-        if (!depContract) {
-          record(
-            {
-              type: "missing-dep",
-              slug,
-              withSlug: dep,
-              detail: `Slice "${slug}" requires "${dep}" but no contract is registered for it.`,
-              severity: "blocker",
-            },
-            slug,
-          );
-          proof.push(`- ${slug}: missing dep "${dep}" (not in candidates, not installed)`);
-          continue;
-        }
-        candidateSet.add(dep);
-        candidateOrder.push(dep);
-        proof.push(`+ ${dep}: pulled in as transitive dep of ${slug}`);
-        queue.push({ slug: dep, chain: [...chain, dep] });
-      }
-    }
+    resolveDependencies({ candidateOrder, candidateSet, contracts, installed, record, proof });
   } else {
-    for (const slug of candidateOrder) {
-      const deps = contracts.get(slug)?.requires?.deps ?? [];
-      for (const dep of deps) {
-        if (installed.has(dep) || candidateSet.has(dep)) continue;
-        record(
-          {
-            type: "missing-dep",
-            slug,
-            withSlug: dep,
-            detail: `Slice "${slug}" requires "${dep}" (resolveDeps disabled — not auto-pulled).`,
-            severity: "blocker",
-          },
-          slug,
-        );
-      }
-    }
+    reportUnresolvedDeps({ candidateOrder, candidateSet, contracts, installed, record });
   }
 
-  // Build a dependers-count map: for each candidate, count how many OTHER
-  // candidates list it in their `requires.deps[]`. Used for arbitration
-  // ranking in Step 2.
-  /** @type {Map<string, number>} */
-  const dependersCount = new Map();
-  for (const slug of candidateOrder) dependersCount.set(slug, 0);
-  for (const slug of candidateOrder) {
-    const c = contracts.get(slug);
-    if (!c) continue;
-    for (const d of c.requires?.deps ?? []) {
-      if (dependersCount.has(d)) {
-        dependersCount.set(d, (dependersCount.get(d) ?? 0) + 1);
-      }
-    }
-  }
+  const dependersCount = computeDependersCount(candidateOrder, contracts);
 
   // ── Step 2: conflict checks. ────────────────────────────────────────────
-  for (const slug of candidateOrder) {
-    if (uncontractedDesired.has(slug)) continue;
-    const contract = contracts.get(slug);
-    if (!contract) continue;
-
-    const wantAuth = contract.requires?.auth;
-    if (wantAuth && state.auth && wantAuth !== state.auth && wantAuth !== "none") {
-      record(
-        {
-          type: "auth-mismatch",
-          slug,
-          detail: `Slice requires auth="${wantAuth}" but target rr.json has auth="${state.auth}".`,
-          severity: "blocker",
-        },
-        slug,
-      );
-    }
-
-    const provTables = contract.provides?.tables ?? [];
-    for (const t of provTables) {
-      if (tablesExisting.has(t)) {
-        record(
-          {
-            type: "table-collision",
-            slug,
-            detail: `Table "${t}" already exists in target Convex schema.`,
-            severity: "blocker",
-          },
-          slug,
-        );
-      }
-    }
-
-    const reqEnv = contract.requires?.env ?? [];
-    for (const e of reqEnv) {
-      if (!envExisting.has(e)) {
-        record(
-          {
-            type: "env-missing",
-            slug,
-            detail: `Env var "${e}" required by ${slug} not present in target.`,
-            severity: "warning",
-          },
-          slug,
-        );
-      }
-    }
-  }
-
-  // Build provides lookup once.
-  /** @type {Map<string, { tables: Set<string>; rbac: Set<string> }>} */
-  const lookup = new Map();
-  for (const slug of candidateOrder) {
-    if (uncontractedDesired.has(slug)) continue;
-    const c = contracts.get(slug);
-    if (!c) continue;
-    lookup.set(slug, {
-      tables: new Set(c.provides?.tables ?? []),
-      rbac: new Set(c.requires?.rbac ?? []),
-    });
-  }
-
-  /**
-   * Pair-conflict arbitration helper.
-   *
-   * @param {string} a
-   * @param {string} b
-   * @param {import("./compose-solver").ConflictType} type
-   * @param {string} detailA
-   * @param {string} detailB
-   */
-  function arbitratePair(a, b, type, detailA, detailB) {
-    const ca = /** @type {import("./compose-solver").Conflict} */ ({
-      type, slug: a, withSlug: b, detail: detailA, severity: "blocker",
-    });
-    const cb = /** @type {import("./compose-solver").Conflict} */ ({
-      type, slug: b, withSlug: a, detail: detailB, severity: "blocker",
-    });
-    const bothInstalled = installed.has(a) && installed.has(b);
-    if (bothInstalled) {
-      allConflicts.push({ ...ca, severity: "warning", type: "both-installed-conflict" });
-      allConflicts.push({ ...cb, severity: "warning", type: "both-installed-conflict" });
-      notes.set(a, notes.get(a) ?? "both-installed-conflict");
-      notes.set(b, notes.get(b) ?? "both-installed-conflict");
-      proof.push(`! ${a} ↔ ${b}: both already installed — conflict surfaced as warning, neither dropped`);
-      return;
-    }
-    if (installed.has(a) && !installed.has(b)) {
-      record(cb, b);
-      arbitrations.push({
-        conflict: cb, winner: a, loser: b,
-        reason: `"${a}" already installed — installed slice wins`,
-      });
-      proof.push(`- ${b}: arbitrated against ${a} (installed wins)`);
-      return;
-    }
-    if (installed.has(b) && !installed.has(a)) {
-      record(ca, a);
-      arbitrations.push({
-        conflict: ca, winner: b, loser: a,
-        reason: `"${b}" already installed — installed slice wins`,
-      });
-      proof.push(`- ${a}: arbitrated against ${b} (installed wins)`);
-      return;
-    }
-    const depA = dependersCount.get(a) ?? 0;
-    const depB = dependersCount.get(b) ?? 0;
-    let winner, loser, conflictForLoser, reason;
-    if (depA !== depB) {
-      if (depA > depB) {
-        winner = a; loser = b; conflictForLoser = cb;
-        reason = `"${a}" has ${depA} dependers vs "${b}" with ${depB} — most-dependers wins`;
-      } else {
-        winner = b; loser = a; conflictForLoser = ca;
-        reason = `"${b}" has ${depB} dependers vs "${a}" with ${depA} — most-dependers wins`;
-      }
-    } else {
-      const later = a > b ? a : b;
-      const earlier = a > b ? b : a;
-      winner = earlier;
-      loser = later;
-      conflictForLoser = later === a ? ca : cb;
-      reason = `tie at ${depA} dependers — alphabetical tiebreak drops "${later}"`;
-    }
-    record(conflictForLoser, loser);
-    arbitrations.push({ conflict: conflictForLoser, winner, loser, reason });
-    proof.push(`- ${loser}: arbitrated against ${winner} (${reason})`);
-  }
-
-  for (let i = 0; i < candidateOrder.length; i++) {
-    for (let j = i + 1; j < candidateOrder.length; j++) {
-      const a = candidateOrder[i];
-      const b = candidateOrder[j];
-      const la = lookup.get(a);
-      const lb = lookup.get(b);
-      if (!la || !lb) continue;
-
-      const tableHits = [];
-      for (const t of la.tables) if (lb.tables.has(t)) tableHits.push(t);
-      if (tableHits.length > 0) {
-        const detail = `Slices "${a}" and "${b}" both declare table${tableHits.length > 1 ? "s" : ""} ${tableHits.map((t) => `"${t}"`).join(", ")}.`;
-        arbitratePair(a, b, "table-collision", detail, detail);
-      }
-      for (const p of la.rbac) {
-        if (lb.rbac.has(p)) {
-          allConflicts.push({
-            type: "rbac-collision",
-            slug: a,
-            withSlug: b,
-            detail: `Slices "${a}" and "${b}" both declare RBAC permission "${p}".`,
-            severity: "warning",
-          });
-        }
-      }
-    }
-  }
+  runSurfaceChecks({
+    candidateOrder, uncontractedDesired, contracts, state, tablesExisting, envExisting, record,
+  });
 
-  // 2e. explicit-conflict — slice declares conflicts: ["<other>:<key>.<value>"].
-  for (const slug of candidateOrder) {
-    if (uncontractedDesired.has(slug)) continue;
-    const c = contracts.get(slug);
-    if (!c) continue;
-    const conflicts = c.conflicts ?? [];
-    for (const cf of conflicts) {
-      const colon = cf.indexOf(":");
-      const dot = cf.indexOf(".", colon);
-      if (colon < 0 || dot < 0) continue;
-      const otherSlug = cf.slice(0, colon);
-      const key = cf.slice(colon + 1, dot);
-      const value = cf.slice(dot + 1);
-      if (!candidateSet.has(otherSlug)) continue;
-      if (uncontractedDesired.has(otherSlug)) continue;
-      const other = contracts.get(otherSlug);
-      if (!other) continue;
-      const provided = other.provides?.[key];
-      if (Array.isArray(provided) && provided.includes(value)) {
-        const detailA = `Slice "${slug}" declares explicit conflict with "${otherSlug}" on ${key}.${value}.`;
-        const detailB = `Slice "${otherSlug}" is the target of "${slug}"'s explicit conflict on ${key}.${value}.`;
-        arbitratePair(slug, otherSlug, "explicit-conflict", detailA, detailB);
-      }
-    }
-  }
+  const lookup = buildProvidesLookup(candidateOrder, uncontractedDesired, contracts);
+  const arbitratePair = makeArbitrator({
+    installed, dependersCount, allConflicts, arbitrations, notes, proof, record,
+  });
+  detectPairwiseCollisions({ candidateOrder, lookup, arbitratePair, allConflicts });
+  detectExplicitConflicts({
+    candidateOrder, candidateSet, uncontractedDesired, contracts, arbitratePair,
+  });
 
   // ── Step 3: decide accepted / rejected. ─────────────────────────────────
   /** @type {Set<string>} */