makersclaw 0.5.2 → 0.7.0

package/src/lockfile.mjs

@@ -0,0 +1,468 @@
+// The app's pnpm-lock.yaml, cut from the release's.
+//
+// Each template ships one lock beside its files (templates/next/
+// pnpm-lock.yaml, made by `npm run lock`): the template's dependencies and
+// every free block's, resolved together once, when the release is made.
+// An app's lock is the part of it the app's package.json names. So every
+// app on one version resolves every package the same way, whenever it is
+// laid, and every app's packages are the same files in one pnpm store.
+//
+// Only the release lock is ever resolved. Cutting a part of it needs no
+// registry and no pnpm: the lines of each entry are kept exactly as pnpm
+// wrote them, in pnpm's order (code-unit order of the keys). The one field
+// that depends on the rest of the graph, a snapshot's `optional: true`
+// (reached only through optional edges), is worked out again for the part.
+// Cutting the whole lock for the whole package.json gives it back byte for
+// byte; test/lockfile.test.mjs holds that.
+//
+// What the release lock does not name (a package the app installed itself,
+// a premium block's) is not the release's to lock. Its entries are carried
+// over from the app's current lock unless a peer in them was resolved to a
+// version the release does not hold (a hook library bound to another
+// React); then it is left to the install, which resolves it against the
+// release's versions and writes it in (src/pm.mjs installs without
+// --frozen-lockfile then).
+//
+// No YAML library: the CLI has no dependencies. The reader takes pnpm's
+// lockfile v9 as pnpm writes it and refuses anything else by name.
+
+export const LOCKFILE = "pnpm-lock.yaml";
+
+/** A lockfile this reader does not take. */
+export class LockError extends Error {}
+
+const SECTIONS = ["dependencies", "devDependencies", "optionalDependencies"];
+const TOP = ["lockfileVersion", "settings", "importers", "packages", "snapshots"];
+
+const lex = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** One YAML scalar as pnpm's writer (js-yaml) prints it: plain, 'single'
+ *  or "double" quoted. */
+function scalar(raw) {
+  const s = raw.trim();
+  if (s.startsWith("'")) {
+    if (!s.endsWith("'") || s.length < 2) throw new LockError(`unreadable scalar ${s}`);
+    return s.slice(1, -1).replace(/''/g, "'");
+  }
+  if (s.startsWith('"')) {
+    try {
+      return JSON.parse(s);
+    } catch {
+      throw new LockError(`unreadable scalar ${s}`);
+    }
+  }
+  return s;
+}
+
+/** `key: value`, `key:` or `key: {}` after the indent → [key, value | null]. */
+function keyValue(body) {
+  let key;
+  let rest;
+  if (body.startsWith("'")) {
+    let i = 1;
+    for (; i < body.length; i++) {
+      if (body[i] !== "'") continue;
+      if (body[i + 1] === "'") i++;
+      else break;
+    }
+    key = scalar(body.slice(0, i + 1));
+    rest = body.slice(i + 1);
+  } else if (body.startsWith('"')) {
+    const end = body.indexOf('":');
+    if (end < 0) throw new LockError(`unreadable key ${body}`);
+    key = scalar(body.slice(0, end + 1));
+    rest = body.slice(end + 1);
+  } else {
+    const m = /^(.*?)(:(?: .*)?)$/.exec(body);
+    if (!m || m[1].includes(": ")) throw new LockError(`unreadable line ${body}`);
+    key = m[1];
+    rest = m[2];
+  }
+  if (rest === ":") return [key, null];
+  if (!rest.startsWith(": ")) throw new LockError(`unreadable line ${body}`);
+  return [key, rest.slice(2)];
+}
+
+const indentOf = (line) => line.length - line.trimStart().length;
+
+/** A dependency's reference → the snapshot key it points at (pnpm's
+ *  refToRelative for lockfile v9): `7.0.0` under `is-number` is
+ *  `is-number@7.0.0`; an alias's reference is already a key; a link is
+ *  none. */
+export function refToKey(name, ref) {
+  if (ref.startsWith("link:")) return null;
+  if (ref.startsWith("@")) return ref;
+  const at = ref.indexOf("@");
+  if (at === -1) return `${name}@${ref}`;
+  const paren = ref.indexOf("(");
+  const colon = ref.indexOf(":");
+  if ((paren === -1 || at < paren) && (colon === -1 || at < colon)) return ref;
+  return `${name}@${ref}`;
+}
+
+/** A snapshot key without its peer suffix: the key of its `packages` entry. */
+export const packageKey = (key) => {
+  const paren = key.indexOf("(");
+  return paren === -1 ? key : key.slice(0, paren);
+};
+
+/** name@version → [name, version]; a scoped name keeps its first "@". */
+const splitKey = (key) => {
+  const at = key.indexOf("@", 1);
+  return at === -1 ? [key, ""] : [key.slice(0, at), key.slice(at + 1)];
+};
+
+/** The peers a snapshot was resolved with, from its key's suffix:
+ *  `a@1.0.0(react-dom@19.3.0(react@19.3.0))(react@19.3.0)` →
+ *  [["react-dom", "19.3.0"], ["react", "19.3.0"]]. A patch hash is not a
+ *  peer. */
+export function peersOf(key) {
+  const out = [];
+  let depth = 0;
+  let start = -1;
+  for (let i = key.indexOf("("); i >= 0 && i < key.length; i++) {
+    if (key[i] === "(") {
+      if (depth++ === 0) start = i + 1;
+    } else if (key[i] === ")" && --depth === 0) {
+      const [name, version] = splitKey(packageKey(key.slice(start, i)));
+      if (version) out.push([name, version]);
+    }
+  }
+  return out;
+}
+
+/** Split a section's lines into entries: a line at indent 2 opens one,
+ *  blank lines separate them. */
+function entries(lines, section) {
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    if (line === "") {
+      cur = null;
+      continue;
+    }
+    const indent = indentOf(line);
+    if (indent === 2) {
+      cur = { head: line, lines: [line] };
+      out.push(cur);
+    } else if (indent >= 4 && cur) {
+      cur.lines.push(line);
+    } else {
+      throw new LockError(`${section}: unexpected line "${line}"`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Read a pnpm lockfile v9 → {
+ *   head      the lockfileVersion and settings lines, as written
+ *   importer  section → Map(name → { specifier, version, lines }) for "."
+ *   packages  Map(key → lines)
+ *   snapshots Map(key → { lines, deps: [{ name, key, optional }] })
+ * }. Throws a LockError for anything else: another lockfile version, a
+ * workspace, overrides, patches, catalogs, a block scalar.
+ */
+export function parseLock(text) {
+  const lines = String(text).replace(/\r\n/g, "\n").split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const tops = new Map();
+  let cur = null;
+  for (const line of lines) {
+    if (line !== "" && indentOf(line) === 0) {
+      const [key, value] = keyValue(line);
+      if (!TOP.includes(key)) throw new LockError(`the lockfile has "${key}", which makersclaw does not read`);
+      if (tops.has(key)) throw new LockError(`the lockfile has "${key}" twice`);
+      cur = { value, lines: [] };
+      tops.set(key, cur);
+    } else if (cur) {
+      cur.lines.push(line);
+    } else if (line !== "") {
+      throw new LockError(`unexpected line "${line}"`);
+    }
+  }
+  if (tops.get("lockfileVersion")?.value !== "'9.0'") {
+    throw new LockError(`lockfileVersion is ${tops.get("lockfileVersion")?.value ?? "missing"}; makersclaw reads 9.0 (pnpm 9 and 10)`);
+  }
+  for (const line of lines) if (/:\s[|>][-+0-9]*$/.test(line)) throw new LockError(`a block scalar: ${line.trim()}`);
+
+  const settings = tops.get("settings");
+  const head = ["lockfileVersion: '9.0'", ""];
+  if (settings) {
+    if (settings.value !== null) throw new LockError("settings is not a mapping");
+    head.push("settings:", ...settings.lines.filter((l) => l !== ""), "");
+  }
+
+  const importer = new Map(SECTIONS.map((s) => [s, new Map()]));
+  const imp = tops.get("importers");
+  if (imp) {
+    const list = entries(imp.lines, "importers");
+    for (const e of list) {
+      const [id, v] = keyValue(e.head.slice(2));
+      if (id !== ".") throw new LockError(`importer "${id}": makersclaw reads one project, not a workspace`);
+      if (v === "{}") continue;
+      if (v !== null) throw new LockError(`importer "." is not a mapping`);
+      let section = null;
+      let dep = null;
+      for (const line of e.lines.slice(1)) {
+        const indent = indentOf(line);
+        const [k, val] = keyValue(line.slice(indent));
+        if (indent === 4) {
+          if (!SECTIONS.includes(k) || val !== null) throw new LockError(`importer ".": "${k}" is not read by makersclaw`);
+          section = importer.get(k);
+          dep = null;
+        } else if (indent === 6 && section && val === null) {
+          dep = { specifier: null, version: null, lines: [line] };
+          section.set(k, dep);
+        } else if (indent === 8 && dep && (k === "specifier" || k === "version") && val !== null) {
+          dep[k] = scalar(val);
+          dep.lines.push(line);
+        } else {
+          throw new LockError(`importer ".": unexpected line "${line}"`);
+        }
+      }
+    }
+  }
+  for (const [s, deps] of importer) {
+    for (const [name, d] of deps) if (d.specifier === null || d.version === null) throw new LockError(`importer ".": ${s}.${name} lacks a specifier or a version`);
+  }
+
+  const packages = new Map();
+  const pk = tops.get("packages");
+  if (pk && pk.value !== "{}") {
+    for (const e of entries(pk.lines, "packages")) packages.set(keyValue(e.head.slice(2))[0], e.lines);
+  }
+
+  const snapshots = new Map();
+  const sn = tops.get("snapshots");
+  if (sn && sn.value !== "{}") {
+    for (const e of entries(sn.lines, "snapshots")) {
+      const [key] = keyValue(e.head.slice(2));
+      const deps = [];
+      let edge = null;
+      for (const line of e.lines.slice(1)) {
+        const indent = indentOf(line);
+        if (indent === 4) {
+          const [k] = keyValue(line.slice(4));
+          edge = k === "dependencies" ? false : k === "optionalDependencies" ? true : null;
+        } else if (indent === 6 && edge !== null) {
+          const [name, ref] = keyValue(line.slice(6));
+          const target = refToKey(name, scalar(ref ?? ""));
+          if (target) deps.push({ name, key: target, optional: edge });
+        }
+      }
+      snapshots.set(key, { lines: e.lines, deps });
+    }
+  }
+  return { head, importer, packages, snapshots };
+}
+
+/** The app's direct dependencies, by section, from its package.json. */
+export function manifestDeps(pkg) {
+  return new Map(SECTIONS.map((s) => [s, new Map(Object.entries(pkg?.[s] ?? {}))]));
+}
+
+/** Does the lock name exactly the app's dependencies, specifier for
+ *  specifier? pnpm installs --frozen-lockfile only then. Returns the first
+ *  difference, or null when it matches. */
+export function lockDifference(lock, pkg) {
+  const want = manifestDeps(pkg);
+  for (const s of SECTIONS) {
+    const have = lock.importer.get(s);
+    for (const [name, spec] of want.get(s)) {
+      const d = have.get(name);
+      if (!d) return `${s}.${name} is not in ${LOCKFILE}`;
+      if (d.specifier !== spec) return `${s}.${name} is ${spec} in package.json, ${d.specifier} in ${LOCKFILE}`;
+    }
+    for (const name of have.keys()) if (!want.get(s).has(name)) return `${s}.${name} is in ${LOCKFILE}, not in package.json`;
+  }
+  return null;
+}
+
+/** Every snapshot reached from `roots` ([{ key, optional }]); `required`
+ *  holds those reached without crossing an optional edge — every other one
+ *  is `optional: true`. A key with no snapshot is listed in `missing`. */
+function reach(snapshots, roots) {
+  const all = new Set();
+  const required = new Set();
+  const missing = new Set();
+  const walk = (start, set, requiredOnly) => {
+    const stack = [...start];
+    while (stack.length) {
+      const key = stack.pop();
+      if (set.has(key)) continue;
+      const snap = snapshots.get(key);
+      if (!snap) {
+        missing.add(key);
+        continue;
+      }
+      set.add(key);
+      for (const d of snap.deps) if (!(requiredOnly && d.optional)) stack.push(d.key);
+    }
+  };
+  walk(roots.map((r) => r.key), all, false);
+  walk(roots.filter((r) => !r.optional).map((r) => r.key), required, true);
+  return { all, required, missing };
+}
+
+/** A snapshot's lines with `optional: true` set or cleared. pnpm writes it
+ *  last; an entry with nothing else is `key: {}`. */
+function withOptional(lines, optional) {
+  const [head, ...body] = lines;
+  const rest = body.filter((l) => l !== "    optional: true");
+  const key = head.replace(/: \{\}$/, ":");
+  if (optional) return [key, ...rest, "    optional: true"];
+  return rest.length ? [key, ...rest] : [`${key.replace(/:$/, "")}: {}`];
+}
+
+const sectionOf = (s) => (s === "optionalDependencies" ? true : false);
+
+/**
+ * The app's lock: what the release lock resolves for the app's
+ * package.json, plus what the app's current lock resolves for the rest,
+ * when that cannot clash.
+ *
+ *   release  parseLock() of the template's release lock
+ *   pkg      the app's package.json
+ *   current  parseLock() of the app's own lock, or null
+ *
+ * Returns { text, covered, carried, left }: covered — names the release
+ * locks; carried — names kept from the current lock; left — names neither
+ * locks, for the install to resolve (the lock then does not match
+ * package.json, and the install is not frozen).
+ */
+export function deriveLock(release, pkg, current = null) {
+  const want = manifestDeps(pkg);
+  const covered = [];
+  const carryWanted = [];
+  const left = [];
+  const importer = new Map(SECTIONS.map((s) => [s, new Map()]));
+  const roots = [];
+
+  const inRelease = (name) => {
+    for (const s of SECTIONS) if (release.importer.get(s).has(name)) return release.importer.get(s).get(name);
+    return null;
+  };
+  for (const s of SECTIONS) {
+    for (const [name, spec] of want.get(s)) {
+      const r = inRelease(name);
+      if (r && r.specifier === spec) {
+        importer.get(s).set(name, r);
+        roots.push({ key: refToKey(name, r.version), optional: sectionOf(s) });
+        covered.push(name);
+        continue;
+      }
+      const c = current?.importer.get(s).get(name);
+      if (c && c.specifier === spec) carryWanted.push({ s, name, dep: c });
+      else left.push(name);
+    }
+  }
+
+  const fromRelease = reach(release.snapshots, roots);
+  if (fromRelease.missing.size) throw new LockError(`the release lock has no snapshot for ${[...fromRelease.missing].join(", ")}`);
+
+  // A carried package must not hold a peer the release resolves to
+  // another version: a hook library carried with React 19.2 beside the
+  // release's 19.3 gets its own React, and two Reacts break every hook.
+  // A second version of an ordinary dependency is fine (npm and pnpm both
+  // nest one), and what the release does not hold at all is the app's.
+  const releaseVersions = new Map();
+  for (const key of fromRelease.all) {
+    const [name, v] = splitKey(packageKey(key));
+    releaseVersions.set(name, (releaseVersions.get(name) ?? new Set()).add(v));
+  }
+  const carried = [];
+  const carriedRoots = [];
+  for (const c of carryWanted) {
+    const root = { key: refToKey(c.name, c.dep.version), optional: sectionOf(c.s) };
+    const r = reach(current.snapshots, [root]);
+    const clash =
+      r.missing.size > 0 ||
+      [...r.all].some((key) => peersOf(key).some(([name, v]) => releaseVersions.has(name) && !releaseVersions.get(name).has(v)));
+    if (clash) {
+      left.push(c.name);
+      continue;
+    }
+    importer.get(c.s).set(c.name, c.dep);
+    carriedRoots.push(root);
+    carried.push(c.name);
+  }
+
+  const snapshots = new Map();
+  for (const key of fromRelease.all) snapshots.set(key, release.snapshots.get(key));
+  for (const key of reach(current?.snapshots ?? new Map(), carriedRoots).all) if (!snapshots.has(key)) snapshots.set(key, current.snapshots.get(key));
+  const { required } = reach(snapshots, [...roots, ...carriedRoots]);
+  const lines = new Map([...snapshots].map(([key, snap]) => [key, withOptional(snap.lines, !required.has(key))]));
+  const text = emit(release.head, importer, lines, (key) => release.packages.get(key) ?? current?.packages.get(key));
+  return { text, covered: covered.sort(lex), carried: carried.sort(lex), left: left.sort(lex) };
+}
+
+/** A lockfile as pnpm writes it: the head, the importer's sections, then
+ *  every package and every snapshot in code-unit order, a blank line
+ *  between entries. `packageLines(key)` gives a packages entry. */
+function emit(head, importer, snapshotLines, packageLines) {
+  const out = [...head, "importers:", ""];
+  const deps = SECTIONS.filter((s) => importer.get(s).size);
+  if (deps.length) {
+    out.push("  .:");
+    for (const s of deps) {
+      out.push(`    ${s}:`);
+      for (const name of [...importer.get(s).keys()].sort(lex)) out.push(...importer.get(s).get(name).lines);
+    }
+  } else {
+    out.push("  .: {}");
+  }
+  out.push("");
+  const keys = [...snapshotLines.keys()].sort(lex);
+  const pkgKeys = [...new Set(keys.map(packageKey))].sort(lex);
+  if (pkgKeys.length) {
+    out.push("packages:", "");
+    for (const key of pkgKeys) {
+      const lines = packageLines(key);
+      if (!lines) throw new LockError(`no packages entry for ${key}`);
+      out.push(...lines, "");
+    }
+    out.push("snapshots:", "");
+    for (const key of keys) out.push(...snapshotLines.get(key), "");
+  } else {
+    out.push("packages: {}", "", "snapshots: {}", "");
+  }
+  // pnpm ends the file on the last entry's newline, not a blank line.
+  while (out.at(-1) === "") out.pop();
+  return `${out.join("\n")}\n`;
+}
+
+/**
+ * The lock without the snapshots in `drop`, and without every edge to
+ * them: what pnpm's current lockfile (node_modules/.pnpm/lock.yaml) would
+ * say had those packages never been locked. src/pm.mjs drops the ones
+ * pnpm skipped as another platform's; see trimCurrentLock there.
+ */
+export function dropSnapshots(lock, drop) {
+  const kept = new Map();
+  for (const [key, snap] of lock.snapshots) {
+    if (drop.has(key)) continue;
+    const [head, ...body] = snap.lines;
+    const out = [];
+    let section = null;
+    for (const line of body) {
+      const indent = indentOf(line);
+      if (indent === 4) {
+        section = keyValue(line.slice(4))[0];
+        out.push(line);
+      } else if (indent === 6 && (section === "dependencies" || section === "optionalDependencies")) {
+        const [name, ref] = keyValue(line.slice(6));
+        if (!drop.has(refToKey(name, scalar(ref ?? "")))) out.push(line);
+      } else {
+        out.push(line);
+      }
+    }
+    // A section header left with nothing under it goes too.
+    const tidy = out.filter((line, i) => !(indentOf(line) === 4 && line.endsWith(":") && !(out[i + 1] && indentOf(out[i + 1]) > 4)));
+    kept.set(key, tidy.length ? [head.replace(/: \{\}$/, ":"), ...tidy] : [`${head.replace(/: \{\}$/, "").replace(/:$/, "")}: {}`]);
+  }
+  const importer = new Map(
+    SECTIONS.map((s) => [s, new Map([...lock.importer.get(s)].filter(([name, d]) => !drop.has(refToKey(name, d.version))))]),
+  );
+  return emit(lock.head, importer, kept, (key) => lock.packages.get(key));
+}