@grampro/kit 2.7.1 → 2.7.2

package/tools/doctor/index.cjs

@@ -0,0 +1,246 @@
+/*
+ * `grampro-kit doctor` — what has changed in the components you installed,
+ * what has changed upstream, and what an update would break.
+ *
+ * Copy-in means you own the code, which means you will edit it, which means
+ * you leave the upgrade path the moment you do. A text diff against upstream
+ * shows which lines moved but not what breaks. This compares contracts — the
+ * props, values, handlers, exports and agent operations each component
+ * promises — between the version you installed, your copy, and the version
+ * this CLI carries, and then finds the call sites in your code that depend on
+ * the difference.
+ *
+ * Three levels, each needing more than the last:
+ *   files      always — from the install manifest, no TypeScript needed
+ *   contracts  needs TypeScript in the project, to read your edited copy
+ *   impact     scans your source for the components' JSX
+ *
+ * Read-only. It never writes a file.
+ */
+const fs = require("fs");
+const path = require("path");
+const { inspect } = require("./baseline.cjs");
+const { compactContract, threeWay, acceptedNames } = require("./contract.cjs");
+const { scanUsage } = require("./usage.cjs");
+
+const PASSPORT = "passport.json";
+const SHARED = "shared";
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+const normalise = (name) => String(name).toLowerCase().replace(/[^a-z0-9]/g, "");
+
+/** -1, 0 or 1 for dotted versions; unknown sorts as oldest. */
+function compareVersions(a, b) {
+  if (!a) return -1;
+  const left = String(a).split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  const right = String(b).split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/** Component folders installed in `dest` that this CLI also knows. */
+function installedFolders(dest, kitRoot) {
+  if (!fs.existsSync(dest)) return [];
+  const known = new Set(
+    fs.readdirSync(kitRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name),
+  );
+  return fs
+    .readdirSync(dest, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== SHARED && known.has(e.name))
+    .map((e) => e.name)
+    .sort();
+}
+
+/** "Button", "datepicker", "date-picker" or "MultiSelect" → the folder that holds it. */
+function folderFor(name, kitRoot, folders) {
+  const wanted = normalise(name);
+  for (const folder of folders) {
+    if (normalise(folder) === wanted) return folder;
+    const passport = readJson(path.join(kitRoot, folder, PASSPORT));
+    const names = [passport?.identity?.component, ...(passport?.identity?.exports || [])].filter(Boolean);
+    if (names.some((n) => normalise(n) === wanted)) return folder;
+  }
+  return null;
+}
+
+/**
+ * Read the project's own copies as contracts.
+ *
+ * Uses the same generator the kit uses on itself, pointed at the project, so
+ * "your contract" means exactly what the kit would have written had it shipped
+ * your edits. Needs TypeScript resolvable from the project; when it is not,
+ * the report says so and stays at the file level instead of guessing.
+ */
+function readProjectContracts(dest, cwd) {
+  let passport;
+  try {
+    passport = require("../passport/index.cjs");
+  } catch (error) {
+    return { error: `Passport tooling unavailable: ${error.message}` };
+  }
+  try {
+    const { results, reactTypes } = passport.buildAll({
+      libRoot: dest,
+      repoRoot: cwd,
+      libraryVersion: "local",
+      includeLocal: false,
+    });
+    const contracts = new Map();
+    for (const result of results) contracts.set(result.name, compactContract(result.effective));
+    return { contracts, reactTypes: Boolean(reactTypes) };
+  } catch (error) {
+    if (error && (error.code === "ETYPESCRIPT_MISSING" || error.code === "ETYPESCRIPT_API")) {
+      // The loader's own message says which case this is and the exact fix.
+      return {
+        error: `Contracts not compared — file-level changes only. ${error.message.replace(/\n\s*/g, " ")}`,
+      };
+    }
+    return { error: `Could not read your components as contracts: ${error.message}` };
+  }
+}
+
+/** Props and handlers an attribute list uses that `lost` takes away. */
+const brokenProps = (props, lost) =>
+  props.filter((p) => lost.has(p) && !p.startsWith("data-") && !p.startsWith("aria-") && p !== "key");
+
+/**
+ * @param {object} options
+ * @param {string} options.cwd        project root
+ * @param {string} options.dest       the installed component library, e.g. <root>/component-lib
+ * @param {string} options.kitRoot    this CLI's source/components
+ * @param {string} options.kitVersion this CLI's version
+ * @param {string[]} [options.only]   component names to limit the report to
+ * @param {boolean} [options.contracts=true] read edited copies as contracts (needs TypeScript)
+ * @param {boolean} [options.impact=true]    scan the project for call sites
+ */
+function runDoctor(options) {
+  const { cwd, dest, kitRoot, kitVersion, only, contracts = true, impact = true } = options;
+  const installed = installedFolders(dest, kitRoot);
+
+  let folders = installed;
+  const notInstalled = [];
+  if (only && only.length) {
+    folders = [];
+    for (const name of only) {
+      const folder = folderFor(name, kitRoot, installed);
+      if (folder) {
+        if (!folders.includes(folder)) folders.push(folder);
+      } else notInstalled.push(name);
+    }
+  }
+
+  const rows = folders.map((folder) => {
+    const dir = path.join(dest, folder);
+    const kitDir = path.join(kitRoot, folder);
+    const kitPassport = readJson(path.join(kitDir, PASSPORT));
+    const theirs = compactContract(kitPassport);
+    const status = inspect(dir, { folder, kitDir, kitVersion });
+    const behind = compareVersions(status.installedVersion, kitVersion) < 0;
+    return {
+      folder,
+      component: theirs?.component || folder,
+      names: [theirs?.component, ...(theirs?.exports || [])].filter(Boolean),
+      ...status,
+      kitVersion,
+      behind,
+      theirs,
+    };
+  });
+
+  // Contracts for edited copies only: a pristine copy's contract is its baseline.
+  let contractNote = null;
+  let reactTypes = true;
+  const needContracts = contracts && rows.some((row) => row.state !== "pristine");
+  if (needContracts) {
+    const read = readProjectContracts(dest, cwd);
+    if (read.error) contractNote = read.error;
+    else {
+      reactTypes = read.reactTypes;
+      for (const row of rows) {
+        if (row.state !== "pristine") row.mine = read.contracts.get(row.folder) || null;
+      }
+    }
+  }
+
+  for (const row of rows) {
+    const mine = row.state === "pristine" ? row.baseContract : row.mine;
+    if (row.state !== "pristine" && mine && row.theirs) {
+      row.comparison = threeWay(row.baseContract, mine, row.theirs);
+    } else if (row.state === "pristine" && row.behind && row.baseContract && row.theirs) {
+      // Untouched but behind: what upstream changed since you installed.
+      row.comparison = threeWay(row.baseContract, row.baseContract, row.theirs);
+    }
+    // Everything your copy accepts that upstream would not: what an update takes away.
+    if (mine && row.theirs) {
+      const keep = acceptedNames(row.theirs);
+      row.lost = new Set([...acceptedNames(mine)].filter((name) => !keep.has(name)));
+      row.lostExports = mine.exports.filter((name) => !row.theirs.exports.includes(name));
+    }
+  }
+
+  // One walk of the project for every component that has something to lose.
+  let truncated = false;
+  const relevant = rows.filter((row) => (row.lost && row.lost.size) || (row.lostExports && row.lostExports.length));
+  if (impact && relevant.length) {
+    const names = [...new Set(relevant.flatMap((row) => [...row.names, ...(row.lostExports || [])]))];
+    const scan = scanUsage(cwd, names, { skip: [dest] });
+    truncated = scan.truncated;
+    for (const row of relevant) {
+      const mine = new Set([...row.names, ...(row.lostExports || [])]);
+      row.breaks = scan.usages
+        .filter((use) => mine.has(use.component))
+        .map((use) => ({
+          ...use,
+          props: (row.lostExports || []).includes(use.component)
+            ? use.props
+            : brokenProps(use.props, row.lost || new Set()),
+          lostExport: (row.lostExports || []).includes(use.component),
+        }))
+        .filter((use) => use.lostExport || use.props.length > 0);
+    }
+  }
+
+  for (const row of rows) row.verdict = verdictOf(row);
+
+  return {
+    kitVersion,
+    dest,
+    rows,
+    notInstalled,
+    contractNote,
+    reactTypes,
+    truncated,
+  };
+}
+
+/** One line on what to do, for a person and for an agent reading the JSON. */
+function verdictOf(row) {
+  const breaks = row.breaks?.length || 0;
+  const conflicts = row.comparison?.conflicts?.length || 0;
+  if (row.state === "pristine") {
+    if (!row.behind) return { status: "up-to-date", action: null };
+    return {
+      status: breaks ? "update-breaks-callers" : "update-available",
+      action: `npx @grampro/kit add ${row.component}`,
+    };
+  }
+  return {
+    status: conflicts ? "conflict" : breaks ? "update-breaks-callers" : row.state === "unknown" ? "unverified" : "edited",
+    // Never suggested as the fix: it discards the user's work, so it is only
+    // ever presented as the choice it is.
+    action: null,
+    force: `npx @grampro/kit add ${row.component} --force`,
+  };
+}
+
+module.exports = { runDoctor, compareVersions, installedFolders, folderFor };

package/tools/doctor/usage.cjs

@@ -0,0 +1,95 @@
+/*
+ * Where a project uses the components, and with which props.
+ *
+ * Answers the one question a contract diff cannot answer alone: "does this
+ * change break *me*?" A removed prop nobody passes is a footnote; the same
+ * prop passed in forty places is the whole upgrade.
+ *
+ * Bounded on purpose. It walks the user's tree, so it skips everything that
+ * is not their source (dependencies, build output, the component library
+ * itself), refuses to follow symlinks, and stops at a file count and a file
+ * size rather than trusting the tree to be reasonable.
+ */
+const fs = require("fs");
+const path = require("path");
+const { jsxOpenings } = require("../jsx-tags.cjs");
+
+const SOURCE = /\.(tsx|jsx|ts|js|mdx)$/i;
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".turbo",
+  ".vercel",
+  ".cache",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "storybook-static",
+]);
+const MAX_FILES = 20000;
+const MAX_BYTES = 1024 * 1024;
+
+/**
+ * @param {string} root            the project root
+ * @param {string[]} names         component names to look for, e.g. ["Button", "Select"]
+ * @param {{ skip?: string[] }} [options]  extra absolute directories to skip (the component library)
+ * @returns {{ usages: { component: string, file: string, line: number, props: string[] }[], truncated: boolean }}
+ */
+function scanUsage(root, names, options = {}) {
+  const wanted = new Set(names);
+  const skip = new Set((options.skip || []).map((dir) => path.resolve(dir)));
+  const usages = [];
+  let files = 0;
+  let truncated = false;
+
+  const walk = (dir) => {
+    if (truncated) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return; // unreadable: not ours to report on
+    }
+    for (const entry of entries) {
+      if (truncated) return;
+      if (entry.isSymbolicLink()) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || skip.has(path.resolve(full))) continue;
+        walk(full);
+        continue;
+      }
+      if (!SOURCE.test(entry.name) || /\.d\.ts$/.test(entry.name)) continue;
+      if (++files > MAX_FILES) {
+        truncated = true;
+        return;
+      }
+      let text;
+      try {
+        if (fs.statSync(full).size > MAX_BYTES) continue;
+        text = fs.readFileSync(full, "utf8");
+      } catch {
+        continue;
+      }
+      if (!text.includes("<")) continue;
+      for (const tag of jsxOpenings(text)) {
+        if (!wanted.has(tag.name)) continue;
+        usages.push({
+          component: tag.name,
+          file: path.relative(root, full).split(path.sep).join("/"),
+          line: tag.line,
+          props: tag.attrs,
+        });
+      }
+    }
+  };
+
+  walk(path.resolve(root));
+  return { usages, truncated };
+}
+
+module.exports = { scanUsage };

package/tools/jsx-tags.cjs

@@ -0,0 +1,120 @@
+/*
+ * Find the opening tags of capitalised JSX elements, and the attribute names
+ * on each — without a parser.
+ *
+ * Used by `validate_usage`, which checks a fragment an agent just wrote, and by
+ * `doctor`, which walks a whole project to find the call sites an upgrade
+ * would break. Tolerant on purpose: both are given code that may not compile,
+ * and the question is only "which props does this element receive".
+ *
+ * Linear in the input. Each character is visited a bounded number of times
+ * and no regular expression here can backtrack, which matters because
+ * `validate_usage` takes arbitrary text from a model (this was checked under
+ * load in a VAPT pass: a megabyte of pathological input returns in ~70ms).
+ */
+
+// A fresh RegExp per call: a shared global one carries `lastIndex` between
+// callers, which is a bug waiting for the first time two scans interleave.
+const OPENING_SOURCE = "<([A-Z][A-Za-z0-9]*)(?=[\\s/>])";
+
+/**
+ * Attribute names at the top level of a tag's attribute text.
+ *
+ * Words inside `{...}` and inside quotes are not attributes. The previous
+ * version matched names anywhere in the tag, so `title={ok ? a : b}` reported
+ * `a` and `b` as attributes — a false "not a prop" from validate_usage, and,
+ * worse, a false "your code uses a removed prop" from doctor.
+ */
+function attributeNames(raw) {
+  const names = [];
+  let depth = 0;
+  let quote = null;
+  let i = 0;
+  while (i < raw.length) {
+    const ch = raw[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      i += 1;
+      continue;
+    }
+    if (ch === "{") {
+      depth += 1;
+      i += 1;
+      continue;
+    }
+    if (ch === "}") {
+      depth = Math.max(0, depth - 1);
+      i += 1;
+      continue;
+    }
+    // A name starts at depth 0, after whitespace or the start of the text.
+    if (depth === 0 && /[a-zA-Z]/.test(ch) && (i === 0 || /\s/.test(raw[i - 1]))) {
+      let j = i + 1;
+      while (j < raw.length && /[a-zA-Z0-9:_-]/.test(raw[j])) j += 1;
+      // Followed by `=`, whitespace or the end: an attribute, or a boolean one.
+      let k = j;
+      while (k < raw.length && /\s/.test(raw[k])) k += 1;
+      if (k >= raw.length || raw[k] === "=" || k > j || raw[k] === "/") names.push(raw.slice(i, j));
+      i = j;
+      continue;
+    }
+    i += 1;
+  }
+  return names;
+}
+
+/**
+ * Every capitalised opening tag in `source`.
+ *
+ * @returns {{ name: string, index: number, line: number, attrs: string[] }[]}
+ */
+function jsxOpenings(source) {
+  const text = String(source || "");
+  const found = [];
+  // Matches arrive in order, so the line count is carried forward rather than
+  // recounted from the top for each tag — recounting is quadratic, and this
+  // runs on untrusted input.
+  let lineAt = 0;
+  let line = 1;
+  const OPENING = new RegExp(OPENING_SOURCE, "g");
+  let match;
+  while ((match = OPENING.exec(text))) {
+    for (; lineAt < match.index; lineAt += 1) if (text.charCodeAt(lineAt) === 10) line += 1;
+    /*
+     * Scan to the tag's own `>` rather than matching one. An attribute can
+     * hold an arrow function — `onDismiss={() => {}}` — so the first `>` is
+     * usually inside a brace, and a regex that stops there finds nothing.
+     */
+    let depth = 0;
+    let quote = null;
+    let end = -1;
+    for (let i = match.index + match[0].length; i < text.length; i += 1) {
+      const ch = text[i];
+      if (quote) {
+        if (ch === quote) quote = null;
+      } else if (ch === '"' || ch === "'" || ch === "`") {
+        quote = ch;
+      } else if (ch === "{") {
+        depth += 1;
+      } else if (ch === "}") {
+        depth -= 1;
+      } else if (ch === ">" && depth === 0) {
+        end = i;
+        break;
+      }
+    }
+    if (end === -1) continue; // Unterminated fragment; nothing reliable to say.
+
+    let raw = text.slice(match.index + match[0].length, end).trimEnd();
+    if (raw.endsWith("/")) raw = raw.slice(0, -1); // self-closing
+    found.push({ name: match[1], index: match.index, line, attrs: attributeNames(raw) });
+  }
+  return found;
+}
+
+module.exports = { jsxOpenings, attributeNames };

package/tools/mcp/server.cjs

@@ -24,6 +24,7 @@ const fs = require("fs");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const { figmaFrame } = require("./figma.cjs");
+const { jsxOpenings } = require("../jsx-tags.cjs");
 
 const CATALOGUE = path.join(__dirname, "..", "..", "source", "components");
 const REFERENCES = path.join(__dirname, "..", "..", ".gbs", "skills", "gbs-components", "references");
@@ -241,43 +242,10 @@ function validateUsage(code) {
 
   const issues = [];
   const used = [];
-  const opening = /<([A-Z][A-Za-z0-9]*)(?=[\s/>])/g;
-  let match;
-
-  while ((match = opening.exec(source))) {
-    const [, name] = match;
+  // Shared with `doctor`, which scans whole projects with the same rules.
+  for (const { name, attrs } of jsxOpenings(source)) {
     const entry = known.get(name);
     if (!entry) continue; // Not ours; the agent may compose with its own components.
-
-    /*
-     * Scan to the tag's own `>` rather than matching one. An attribute can
-     * hold an arrow function — `onDismiss={() => {}}` — so the first `>` is
-     * usually inside a brace, and a regex that stops there finds nothing.
-     */
-    let depth = 0;
-    let quote = null;
-    let end = -1;
-    for (let i = match.index + match[0].length; i < source.length; i += 1) {
-      const ch = source[i];
-      if (quote) {
-        if (ch === quote) quote = null;
-      } else if (ch === '"' || ch === "'" || ch === "`") {
-        quote = ch;
-      } else if (ch === "{") {
-        depth += 1;
-      } else if (ch === "}") {
-        depth -= 1;
-      } else if (ch === ">" && depth === 0) {
-        end = i;
-        break;
-      }
-    }
-    if (end === -1) continue; // Unterminated fragment; nothing reliable to say.
-
-    const rawAttrs = source.slice(match.index + match[0].length, end);
-    const attrs = [...rawAttrs.matchAll(/(?:^|\s)([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s*=|\s|$)/g)].map(
-      (m) => m[1],
-    );
     used.push({ component: name, props: attrs });
 
     for (const attr of attrs) {
@@ -340,18 +308,57 @@ function installComponents(names) {
   }
 
   const cli = path.join(__dirname, "..", "..", "index.cjs");
+  let stdout = "";
+  let stderr = "";
+  let failed = false;
   try {
-    const output = execFileSync(process.execPath, [cli, "add", ...wanted], {
+    stdout = execFileSync(process.execPath, [cli, "add", ...wanted], {
       cwd: process.cwd(),
       encoding: "utf8",
       timeout: 120000,
+      // Captured, not forwarded: the installer explains a refusal on stderr,
+      // and that explanation is what the agent most needs to read.
+      stdio: ["ignore", "pipe", "pipe"],
     });
-    // The installer prints the one manual step; the agent needs to see it.
-    const importLine = (output.match(/^\s*@import .+$/gm) || []).map((l) => l.trim());
-    return { installed: wanted, stylesheet: importLine, output: output.trim().slice(-1200) };
   } catch (error) {
-    return { error: `Install failed: ${(error.stdout || error.message || "").toString().slice(-600)}` };
+    failed = true;
+    stdout = (error.stdout || "").toString();
+    stderr = (error.stderr || "").toString();
+    if (!stdout && !stderr) return { error: `Install failed: ${error.message}` };
   }
+
+  // The installer prints the one manual step; the agent needs to see it.
+  const importLine = (stdout.match(/^\s*@import .+$/gm) || []).map((l) => l.trim());
+  const done = [...stdout.matchAll(/✓ Component (\S+) /g)].map((m) => m[1]);
+
+  /*
+   * A component the project has edited is left alone by `add`, and this tool
+   * never passes --force. That is deliberate: replacing someone's edited
+   * component is their decision, and an agent asked to "install Button" has
+   * not been asked to discard the Button they already customised. So the
+   * agent is told what was kept, why, and how the user can see the changes —
+   * not handed a generic failure it might try to work around.
+   */
+  const kept = [...stderr.matchAll(/✗ (\S+) was not replaced/g)].map((m) => m[1]);
+  if (kept.length) {
+    return {
+      installed: done,
+      kept,
+      reason:
+        "These components have changes made in this project since they were installed, and " +
+        "install_component never overwrites them. They are still in place and still usable.",
+      advice:
+        "Do not try to replace them. Tell the user, and suggest " +
+        `\`npx @grampro/kit doctor ${kept.join(" ")}\`: it shows what was changed locally, what the ` +
+        "new version changes, and which call sites an update would break. Replacing them with " +
+        "--force discards the user's work, which is their decision to make.",
+      detail: stderr.trim().slice(-1500),
+      stylesheet: importLine,
+    };
+  }
+
+  if (failed) return { error: `Install failed: ${(stderr || stdout).trim().slice(-600)}` };
+  return { installed: wanted, stylesheet: importLine, output: stdout.trim().slice(-1200) };
 }
 
 const TOOLS = [

package/tools/passport/extract.cjs

@@ -14,9 +14,9 @@
 
 const fs = require("fs");
 const path = require("path");
-const crypto = require("crypto");
 const { allowlistFor } = require("./policy.cjs");
 const { describable } = require("./merge.cjs");
+const { hashEntries } = require("./hash.cjs");
 
 const PASSPORT_VERSION = "1.0.0";
 
@@ -27,23 +27,56 @@ const PASSPORT_VERSION = "1.0.0";
  * the runtime dependency story. The caller's project is searched first, so a
  * consumer regenerating a forked component uses their own TypeScript.
  */
+/*
+ * TypeScript 7 is a native rewrite and its npm package does not expose the
+ * compiler API this generator is built on — `createProgram`, `JsxEmit` and the
+ * rest are simply absent. It is also what `npm i -D typescript` installs now,
+ * so a current project has a `typescript` that loads fine and then fails on
+ * the first enum it is asked for, with an error about `ReactJSX` that says
+ * nothing useful.
+ *
+ * So a candidate is only accepted if it actually has the API. After the
+ * project's own `typescript`, a TypeScript 6 installed under an alias is
+ * tried: it sits beside a TypeScript 7 build without replacing it.
+ */
+const TS6_ALIASES = ["typescript-6", "typescript6"];
+const hasCompilerApi = (ts) => Boolean(ts && typeof ts.createProgram === "function" && ts.JsxEmit);
+
 function loadTypeScript(searchFrom = []) {
   const paths = [...searchFrom, process.cwd(), __dirname].filter(Boolean);
-  try {
-    return require(require.resolve("typescript", { paths }));
-  } catch {
+  const tryLoad = (name) => {
     try {
-      return require("typescript");
+      return require(require.resolve(name, { paths }));
     } catch {
-      const error = new Error(
-        "Passport generation needs the TypeScript compiler API.\n" +
-          "  Install it as a dev dependency:  npm i -D typescript\n" +
-          "  It is only needed to generate passports, never to run a component.",
-      );
-      error.code = "ETYPESCRIPT_MISSING";
-      throw error;
+      return null;
     }
+  };
+
+  const primary = tryLoad("typescript");
+  if (hasCompilerApi(primary)) return primary;
+  for (const alias of TS6_ALIASES) {
+    const candidate = tryLoad(alias);
+    if (hasCompilerApi(candidate)) return candidate;
   }
+
+  if (primary) {
+    const error = new Error(
+      `This project's TypeScript (${primary.version || "unknown version"}) does not provide the compiler API that ` +
+        "passports are read with: TypeScript 7 is a native rewrite without it.\n" +
+        "  Install TypeScript 6 alongside it, under another name, so your build keeps using 7:\n" +
+        "    npm i -D typescript-6@npm:typescript@6\n" +
+        "  It is only used to read component contracts, never to build or run a component.",
+    );
+    error.code = "ETYPESCRIPT_API";
+    throw error;
+  }
+  const error = new Error(
+    "Passport generation needs the TypeScript compiler API.\n" +
+      "  Install it as a dev dependency:  npm i -D typescript-6@npm:typescript@6\n" +
+      "  It is only needed to read component contracts, never to run a component.",
+  );
+  error.code = "ETYPESCRIPT_MISSING";
+  throw error;
 }
 
 const posix = (p) => p.replace(/\\/g, "/");
@@ -74,14 +107,8 @@ function sourceFiles(dir) {
  * how the file was checked out.
  */
 function hashSources(files, root) {
-  const h = crypto.createHash("sha256");
-  for (const f of [...files].sort()) {
-    h.update(posix(path.relative(root, f)));
-    h.update("\0");
-    h.update(fs.readFileSync(f, "utf8").replace(/\r\n/g, "\n"));
-    h.update("\0");
-  }
-  return `sha256:${h.digest("hex")}`;
+  // One implementation, shared with the installer: see hash.cjs for why.
+  return hashEntries(files.map((file) => ({ label: posix(path.relative(root, file)), file })));
 }
 
 /* ------------------------------------------------------------------ program */