@grampro/kit 2.7.1 → 2.7.2

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/textarea/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/agent.ts",
       "core/count.ts",

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/api.ts",
       "core/index.ts",

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.7.1",
+    "libraryVersion": "2.7.2",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/tools/doctor/baseline.cjs

@@ -0,0 +1,227 @@
+/*
+ * What a component looked like when it was installed, and whether it still does.
+ *
+ * Components are copied into a project to be edited — that is the point of
+ * copy-in. Until 2.7.2 nothing recorded what was copied, so `add` could not
+ * tell a pristine Button from one somebody had spent a week on, and it
+ * overwrote both. This is the record.
+ *
+ * Each installed component gets `.install-manifest.json` beside its files:
+ * the kit version it came from, a hash of every file as written, and a
+ * compact copy of its contract. The contract is stored here, not just in
+ * passport.json, because the `passport` command regenerates passport.json
+ * from the project's own source — after which it describes the edits, not the
+ * baseline. Nothing rewrites the manifest except installing the component.
+ *
+ * Components installed before 2.7.2 have no manifest. For those the
+ * passport's own `sourceHash` is still usable: it was computed over the
+ * kit's files with the kit's path labels, and recomputing it over the
+ * project's copy with those same labels says whether anything changed.
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { hashEntries } = require("../passport/hash.cjs");
+const { compactContract } = require("./contract.cjs");
+
+const MANIFEST = ".install-manifest.json";
+const PASSPORT = "passport.json";
+const TESTS_DIR = "__tests__";
+const MANIFEST_VERSION = 1;
+
+/*
+ * passport.json is derived, and the `passport` command regenerates it on
+ * purpose. Counting that as an edit would flag every project that ever ran
+ * it, so it is left out of change detection; the manifest carries the
+ * baseline contract instead.
+ */
+const DERIVED = new Set([PASSPORT]);
+
+/* The consumer's own overlay, which the CLI never writes. Adding it is not an edit. */
+const OWNED = new Set(["passport.local.json"]);
+
+const TEXT = /\.(tsx?|jsx?|mjs|cjs|css|md|json|svg|html?)$/i;
+
+/** A file's hash, ignoring line endings for text — autocrlf is not an edit. */
+function hashFile(file) {
+  const bytes = fs.readFileSync(file);
+  const content = TEXT.test(file) ? bytes.toString("utf8").replace(/\r\n/g, "\n") : bytes;
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+/** Every file in a component folder, relative and "/"-separated, minus the manifest and tests. */
+function listFiles(dir, prefix = "") {
+  if (!fs.existsSync(path.join(dir, prefix))) return [];
+  return fs
+    .readdirSync(path.join(dir, prefix), { withFileTypes: true })
+    .flatMap((entry) => {
+      if (entry.name === MANIFEST || entry.name === TESTS_DIR) return [];
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isSymbolicLink()) return []; // never follow a link out of the folder
+      return entry.isDirectory() ? listFiles(dir, relative) : [relative];
+    })
+    .sort();
+}
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Record a component as just installed. Hashes are taken from the source the
+ * kit copied, so the record describes what the kit wrote, whatever happened
+ * to the copy between the copy and this call.
+ */
+function writeManifest(destDir, { component, version, sourceDir }) {
+  const files = listFiles(sourceDir);
+  const manifest = {
+    manifestVersion: MANIFEST_VERSION,
+    component,
+    version,
+    installedAt: new Date().toISOString(),
+    files: Object.fromEntries(files.map((file) => [file, hashFile(path.join(sourceDir, file))])),
+    contract: compactContract(readJson(path.join(sourceDir, PASSPORT))),
+  };
+  fs.writeFileSync(path.join(destDir, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return manifest;
+}
+
+/** The passport's sourceHash, recomputed over the project's copy with the kit's labels. */
+function kitRelativeHash(dir, folder, passport) {
+  const files = passport?.source?.files;
+  if (!Array.isArray(files)) return null;
+  const entries = [];
+  for (const relative of files) {
+    // A path that climbs out of the folder is not one the kit ever wrote.
+    if (typeof relative !== "string" || relative.split(/[\\/]/).includes("..")) return null;
+    const file = path.join(dir, relative);
+    if (!fs.existsSync(file)) return null; // a file the passport lists is gone: not pristine
+    entries.push({ label: `source/components/${folder}/${relative}`, file });
+  }
+  // The generator hashes styles.css alongside the source when there is one.
+  const styles = path.join(dir, "styles.css");
+  if (fs.existsSync(styles)) entries.push({ label: `source/components/${folder}/styles.css`, file: styles });
+  return hashEntries(entries);
+}
+
+/**
+ * Where an installed component stands against what was installed.
+ *
+ * `state` is one of:
+ *   pristine  every file is as the kit wrote it
+ *   edited    something changed; `changed`/`missing`/`added` say what, when known
+ *   unknown   installed before 2.7.2 and no longer matches what any record
+ *             describes — it may hold edits, so it is treated as edited
+ *
+ * @param {string} dir      the installed component folder
+ * @param {object} options
+ * @param {string} options.folder   its name, e.g. "date-picker"
+ * @param {string} [options.kitDir] the same component in the running CLI, for
+ *                                  the case where versions match and the files
+ *                                  can be compared directly
+ * @param {string} [options.kitVersion]
+ */
+function inspect(dir, { folder, kitDir, kitVersion }) {
+  const manifest = readJson(path.join(dir, MANIFEST));
+
+  if (manifest && manifest.files && typeof manifest.files === "object") {
+    const present = new Set(listFiles(dir));
+    const changed = [];
+    const missing = [];
+    for (const [file, hash] of Object.entries(manifest.files)) {
+      if (DERIVED.has(file)) continue;
+      if (!present.has(file)) missing.push(file);
+      else if (hashFile(path.join(dir, file)) !== hash) changed.push(file);
+    }
+    const added = [...present].filter(
+      (file) => !(file in manifest.files) && !DERIVED.has(file) && !OWNED.has(file),
+    );
+    return {
+      baseline: "manifest",
+      installedVersion: manifest.version || null,
+      state: changed.length || missing.length || added.length ? "edited" : "pristine",
+      changed,
+      missing,
+      added,
+      // Updating copies over the folder: it never deletes an added file, but it
+      // does replace a changed one and restore a deleted one.
+      destructive: changed.length > 0 || missing.length > 0,
+      baseContract: manifest.contract || null,
+    };
+  }
+
+  // Before 2.7.2: no manifest. Is the passport still the one the kit wrote?
+  const passport = readJson(path.join(dir, PASSPORT));
+  const recorded = passport?.source?.sourceHash;
+  const recomputed = recorded ? kitRelativeHash(dir, folder, passport) : null;
+  if (recorded && recomputed === recorded) {
+    return {
+      baseline: "passport",
+      installedVersion: passport.source.libraryVersion || null,
+      state: "pristine",
+      changed: [],
+      missing: [],
+      added: [],
+      destructive: false,
+      baseContract: compactContract(passport),
+    };
+  }
+
+  /*
+   * No record that still applies. Compare with the running CLI's own copy:
+   * identical files are pristine at this version. Any difference could be an
+   * edit or simply an older version, and there is no telling which — so it is
+   * reported as unknown, and `add` will not overwrite it without --force.
+   * Refusing once too often costs a flag; overwriting once too often costs
+   * someone's work.
+   */
+  if (kitDir && fs.existsSync(kitDir)) {
+    const ours = new Set(listFiles(kitDir).filter((file) => !DERIVED.has(file)));
+    const theirs = new Set(listFiles(dir).filter((file) => !DERIVED.has(file) && !OWNED.has(file)));
+    const changed = [...ours].filter(
+      (file) => theirs.has(file) && hashFile(path.join(dir, file)) !== hashFile(path.join(kitDir, file)),
+    );
+    const missing = [...ours].filter((file) => !theirs.has(file));
+    const added = [...theirs].filter((file) => !ours.has(file));
+    if (!changed.length && !missing.length && !added.length) {
+      return {
+        baseline: "kit",
+        installedVersion: kitVersion || null,
+        state: "pristine",
+        changed,
+        missing,
+        added,
+        destructive: false,
+        baseContract: compactContract(readJson(path.join(kitDir, PASSPORT))),
+      };
+    }
+    return {
+      baseline: "none",
+      installedVersion: passport?.source?.libraryVersion || null,
+      state: "unknown",
+      // Differences from the running CLI's copy — not necessarily your edits.
+      changed,
+      missing,
+      added,
+      destructive: true,
+      baseContract: null,
+    };
+  }
+
+  return {
+    baseline: "none",
+    installedVersion: null,
+    state: "unknown",
+    changed: [],
+    missing: [],
+    added: [],
+    destructive: true,
+    baseContract: null,
+  };
+}
+
+module.exports = { MANIFEST, inspect, writeManifest, listFiles, hashFile, kitRelativeHash };

package/tools/doctor/contract.cjs

@@ -0,0 +1,252 @@
+/*
+ * What a component promises, reduced to what a caller depends on, and how two
+ * of those promises differ.
+ *
+ * A text diff of two versions of Button.tsx says which lines moved. It cannot
+ * say that `variant` stopped accepting "ghost", or that a prop became
+ * required, or that the agent runtime lost an operation — and those are the
+ * only differences that break someone. The passport already records each of
+ * them, so the comparison is done there.
+ *
+ * Pure: no filesystem, no TypeScript. Everything here takes passports, or the
+ * compact contracts made from them, and returns plain data.
+ */
+
+/** The parts of a passport a caller can depend on. */
+function compactContract(passport) {
+  if (!passport || typeof passport !== "object") return null;
+  const props = {};
+  for (const prop of passport.props || []) {
+    if (!prop || typeof prop.name !== "string") continue;
+    props[prop.name] = {
+      type: prop.type || "",
+      typeText: normaliseType(prop.typeText || ""),
+      required: Boolean(prop.required),
+      origin: prop.origin || "derived",
+      ...(prop.default !== undefined ? { default: String(prop.default) } : {}),
+      ...(Array.isArray(prop.values) && prop.values.length
+        ? { values: prop.values.map(String).sort() }
+        : {}),
+    };
+  }
+  const events = {};
+  for (const event of passport.events || []) {
+    if (event && typeof event.name === "string") events[event.name] = normaliseType(event.signature || "");
+  }
+  return {
+    component: passport.identity?.component || null,
+    version: passport.source?.libraryVersion || null,
+    exports: [...(passport.identity?.exports || [])].map(String).sort(),
+    props,
+    events,
+    operations: Object.keys(passport.operations || {}).sort(),
+  };
+}
+
+/** Whitespace is not a type change. */
+const normaliseType = (text) => String(text).replace(/\s+/g, " ").trim();
+
+/*
+ * Inherited props come from React's DOM types, and whether they appear at all
+ * depends on whether @types/react was found when the passport was made. A
+ * project without it would report every one of them as "removed" — so when
+ * one side has inherited props and the other has none, only the component's
+ * own props are compared, and the report says so.
+ */
+function comparableProps(before, after) {
+  const has = (c) => Object.values(c.props).some((p) => p.origin === "inherited");
+  const ownOnly = has(before) !== has(after);
+  const pick = (c) =>
+    Object.fromEntries(Object.entries(c.props).filter(([, p]) => !ownOnly || p.origin !== "inherited"));
+  return { before: pick(before), after: pick(after), ownOnly };
+}
+
+/**
+ * Every difference between two contracts, oldest first.
+ *
+ * `severity` is what a caller should take from it:
+ *   breaking  code that worked against `before` may not compile or behave against `after`
+ *   changed   the promise moved, but existing callers keep working
+ *   added     something new, which nobody can be depending on yet
+ */
+function diffContracts(before, after) {
+  if (!before || !after) return { changes: [], ownPropsOnly: false };
+  const changes = [];
+  const add = (kind, name, change, severity, detail = {}) =>
+    changes.push({ kind, name, change, severity, ...detail });
+
+  const { before: bp, after: ap, ownOnly } = comparableProps(before, after);
+
+  for (const [name, was] of Object.entries(bp)) {
+    const now = ap[name];
+    if (!now) {
+      add("prop", name, "removed", "breaking", { from: was.typeText });
+      continue;
+    }
+    if (!was.required && now.required) add("prop", name, "now required", "breaking");
+    if (was.required && !now.required) add("prop", name, "now optional", "changed");
+
+    if (was.values || now.values) {
+      const gone = (was.values || []).filter((v) => !(now.values || []).includes(v));
+      const fresh = (now.values || []).filter((v) => !(was.values || []).includes(v));
+      if (gone.length) add("prop", name, "values removed", "breaking", { values: gone });
+      if (fresh.length) add("prop", name, "values added", "added", { values: fresh });
+    } else if (was.typeText !== now.typeText) {
+      // Without enumerated values there is no telling a widening from a
+      // narrowing, so it is reported without claiming either.
+      add("prop", name, "type changed", "changed", { from: was.typeText, to: now.typeText });
+    }
+
+    if ((was.default ?? null) !== (now.default ?? null)) {
+      add("prop", name, "default changed", "changed", { from: was.default ?? null, to: now.default ?? null });
+    }
+  }
+  for (const [name, now] of Object.entries(ap)) {
+    if (bp[name]) continue;
+    const type = now.values ? now.values.map((v) => JSON.stringify(v)).join(" | ") : now.typeText.replace(/ \| undefined$/, "");
+    add("prop", name, "added", now.required ? "breaking" : "added", { type, ...(now.required ? { required: true } : {}) });
+  }
+
+  for (const [name, signature] of Object.entries(before.events)) {
+    if (!(name in after.events)) add("event", name, "removed", "breaking");
+    else if (after.events[name] !== signature) {
+      add("event", name, "signature changed", "changed", { from: signature, to: after.events[name] });
+    }
+  }
+  for (const name of Object.keys(after.events)) {
+    if (!(name in before.events)) add("event", name, "added", "added");
+  }
+
+  for (const name of before.exports) if (!after.exports.includes(name)) add("export", name, "removed", "breaking");
+  for (const name of after.exports) if (!before.exports.includes(name)) add("export", name, "added", "added");
+
+  // An agent that drove this operation yesterday is refused it today.
+  for (const name of before.operations) {
+    if (!after.operations.includes(name)) add("operation", name, "removed", "breaking");
+  }
+  for (const name of after.operations) if (!before.operations.includes(name)) add("operation", name, "added", "added");
+
+  return { changes, ownPropsOnly: ownOnly };
+}
+
+const keyOf = (change) => `${change.kind}:${change.name}`;
+
+/**
+ * Your edits and upstream's, measured from the version you installed, and the
+ * places both of you changed the same thing.
+ *
+ * Without a base, only the difference between your copy and upstream can be
+ * reported, with no telling who moved — so it is reported as that, not
+ * dressed up as a three-way result.
+ */
+function threeWay(base, mine, theirs) {
+  if (!base) {
+    const differences = diffContracts(theirs, mine);
+    return { mode: "two-way", differences: differences.changes, ownPropsOnly: differences.ownPropsOnly };
+  }
+  const yours = diffContracts(base, mine);
+  const upstream = diffContracts(base, theirs);
+
+  const group = (changes) => {
+    const by = new Map();
+    for (const change of changes) by.set(keyOf(change), [...(by.get(keyOf(change)) || []), change]);
+    return by;
+  };
+  const ours = group(yours.changes);
+  const conflicts = [];
+  const merges = [];
+
+  for (const [key, upstreamChanges] of group(upstream.changes)) {
+    const ownChanges = ours.get(key);
+    if (!ownChanges) continue;
+    const { kind, name } = upstreamChanges[0];
+    const verdict = reconcile(kind, name, ownChanges, upstreamChanges, { base, mine, theirs });
+    if (verdict.conflict) conflicts.push({ kind, name, yours: verdict.yours, upstream: verdict.upstream });
+    else if (verdict.merged) merges.push({ kind, name, ...verdict.merged });
+  }
+
+  return {
+    mode: "three-way",
+    yours: yours.changes,
+    upstream: upstream.changes,
+    conflicts,
+    merges,
+    ownPropsOnly: yours.ownPropsOnly || upstream.ownPropsOnly,
+  };
+}
+
+const describeAll = (changes) => [...new Set(changes.map((c) => c.change))].join(", ");
+
+/*
+ * Two sides touched the same entry. Whether that is a conflict depends on
+ * what each did to it, not merely on both having done something:
+ *
+ *   - you added "ghost"-less values while upstream added "link": value sets
+ *     combine, so that merges, and the merged set is reported;
+ *   - one side removed the prop while the other changed it: a conflict, since
+ *     no combination keeps both intentions;
+ *   - both changed the type, the default, or the required-ness, to different
+ *     results: a conflict;
+ *   - both made the identical change: agreement, not reported at all.
+ */
+function reconcile(kind, name, ownChanges, upstreamChanges, { base, mine, theirs }) {
+  const kinds = (changes) => new Set(changes.map((c) => c.change));
+  const own = kinds(ownChanges);
+  const up = kinds(upstreamChanges);
+  const conflict = () => ({ conflict: true, yours: describeAll(ownChanges), upstream: describeAll(upstreamChanges) });
+
+  if (kind !== "prop") {
+    // Exports and operations either exist or do not, so both sides changing one
+    // means both made the same change. Events can diverge in signature.
+    if (kind === "event" && own.has("signature changed") && up.has("signature changed")) {
+      return mine.events[name] === theirs.events[name] ? {} : conflict();
+    }
+    if (own.has("removed") !== up.has("removed")) return conflict();
+    return {};
+  }
+
+  const minePropNow = mine.props[name];
+  const theirsPropNow = theirs.props[name];
+
+  // One side deleted it, the other kept and changed it.
+  if (own.has("removed") !== up.has("removed")) return conflict();
+  if (own.has("removed") && up.has("removed")) return {};
+
+  // Both added a prop of the same name: fine only if they agree on what it is.
+  if (own.has("added") && up.has("added")) {
+    return JSON.stringify(minePropNow) === JSON.stringify(theirsPropNow) ? {} : conflict();
+  }
+
+  if (minePropNow?.typeText !== theirsPropNow?.typeText && own.has("type changed") && up.has("type changed")) {
+    return conflict();
+  }
+  if (own.has("default changed") && up.has("default changed") && minePropNow?.default !== theirsPropNow?.default) {
+    return conflict();
+  }
+  if ((own.has("now required") && up.has("now optional")) || (own.has("now optional") && up.has("now required"))) {
+    return conflict();
+  }
+
+  // Value sets merge: start from the base, apply both sides' removals and additions.
+  const valueEdits = (s) => s.has("values added") || s.has("values removed");
+  if (valueEdits(own) && valueEdits(up)) {
+    const was = new Set(base.props[name]?.values || []);
+    const mineValues = new Set(minePropNow?.values || []);
+    const theirValues = new Set(theirsPropNow?.values || []);
+    const merged = new Set(was);
+    for (const v of was) if (!mineValues.has(v) || !theirValues.has(v)) merged.delete(v);
+    for (const v of mineValues) if (!was.has(v)) merged.add(v);
+    for (const v of theirValues) if (!was.has(v)) merged.add(v);
+    return { merged: { values: [...merged].sort() } };
+  }
+  return {};
+}
+
+/**
+ * Names a caller can write on this component's JSX: props and handlers. What
+ * your copy accepts and upstream does not is exactly what replacing yours with
+ * upstream would take away from your call sites.
+ */
+const acceptedNames = (contract) => new Set([...Object.keys(contract.props), ...Object.keys(contract.events)]);
+
+module.exports = { compactContract, diffContracts, threeWay, acceptedNames };

package/tools/doctor/format.cjs

@@ -0,0 +1,160 @@
+/*
+ * The doctor report, for a person. Agents get the same data as --json.
+ *
+ * Ordered by what someone has to act on: conflicts and broken call sites
+ * first, then edits, then updates available, then everything that is fine —
+ * summarised in a single line, because a list of twenty-four "up to date"
+ * rows buries the three that matter.
+ */
+
+const SIGN = { breaking: "!", changed: "~", added: "+" };
+const RANK = { conflict: 0, "update-breaks-callers": 1, unverified: 2, edited: 3, "update-available": 4, "up-to-date": 5 };
+
+function describeChange(change) {
+  const sign = SIGN[change.severity] || " ";
+  // "+ prop tone  "info" | "warn"" reads as what it is; "added" repeated would not.
+  if (change.change === "added") {
+    return `${sign} ${change.kind} ${change.name}${change.type ? `  ${short(change.type)}` : ""}${change.required ? " (required)" : ""}`;
+  }
+  let text = `${sign} ${change.kind} ${change.name}: ${change.change}`;
+  if (change.values) text += ` ${change.values.map((v) => JSON.stringify(v)).join(", ")}`;
+  if (change.from !== undefined && change.to !== undefined) {
+    text += ` (${short(change.from)} → ${short(change.to)})`;
+  }
+  return text;
+}
+
+const short = (value) => {
+  const text = value === null ? "none" : String(value);
+  return text.length > 48 ? `${text.slice(0, 45)}...` : text;
+};
+
+function headline(row) {
+  switch (row.verdict.status) {
+    case "up-to-date":
+      return `up to date · ${row.kitVersion}`;
+    case "update-available":
+      return `untouched · ${row.installedVersion || "older version"} → ${row.kitVersion} available, safe to update`;
+    case "update-breaks-callers":
+      if (row.state === "pristine") return `untouched · ${row.kitVersion} available, but it breaks call sites below`;
+      return row.behind
+        ? `your changes · taking ${row.kitVersion} would break call sites below`
+        : `your changes · reverting to ${row.kitVersion} would break call sites below`;
+    case "conflict":
+      return `your changes · conflict with ${row.kitVersion}`;
+    case "unverified":
+      return "may contain your changes · installed before 2.7.2, so there is no record to compare against";
+    default:
+      return row.behind
+        ? `your changes · installed ${row.installedVersion || "?"}, ${row.kitVersion} available`
+        : `your changes · on ${row.installedVersion || row.kitVersion}`;
+  }
+}
+
+function formatReport(report) {
+  const lines = [];
+  const pad = (label) => label.padEnd(12);
+  lines.push(`Doctor · ${report.dest} · kit ${report.kitVersion}`);
+  lines.push("");
+
+  const rows = [...report.rows].sort(
+    (a, b) => RANK[a.verdict.status] - RANK[b.verdict.status] || a.component.localeCompare(b.component),
+  );
+  const quiet = rows.filter((row) => row.verdict.status === "up-to-date");
+  const loud = rows.filter((row) => row.verdict.status !== "up-to-date");
+
+  for (const row of loud) {
+    lines.push(`  ${row.component.padEnd(14)}${headline(row)}`);
+
+    const files = [];
+    if (row.changed.length) files.push(`changed ${row.changed.join(", ")}`);
+    if (row.missing.length) files.push(`deleted ${row.missing.join(", ")}`);
+    if (row.added.length) files.push(`added ${row.added.join(", ")}`);
+    if (files.length) {
+      const label = row.state === "unknown" ? "vs current" : "files";
+      lines.push(`    ${pad(label)}${files.join(" · ")}`);
+    }
+
+    const cmp = row.comparison;
+    if (cmp?.mode === "three-way") {
+      if (row.state !== "pristine") {
+        lines.push(`    ${pad("yours")}${cmp.yours.length ? describeChange(cmp.yours[0]) : "no contract changes (implementation only)"}`);
+        for (const change of cmp.yours.slice(1)) lines.push(`    ${pad("")}${describeChange(change)}`);
+      }
+      if (row.behind) {
+        lines.push(`    ${pad("upstream")}${cmp.upstream.length ? describeChange(cmp.upstream[0]) : "no contract changes"}`);
+        for (const change of cmp.upstream.slice(1)) lines.push(`    ${pad("")}${describeChange(change)}`);
+      }
+      for (const [i, c] of cmp.conflicts.entries()) {
+        lines.push(`    ${pad(i === 0 ? "conflict" : "")}${c.kind} ${c.name}: you ${c.yours}; upstream ${c.upstream}`);
+      }
+      // Both sides changed it, compatibly: say what the combination is.
+      for (const [i, m] of (cmp.merges || []).entries()) {
+        const values = m.values ? m.values.map((v) => JSON.stringify(v)).join(" | ") : "";
+        lines.push(`    ${pad(i === 0 ? "merges" : "")}${m.kind} ${m.name} → ${values}  (both edits combine)`);
+      }
+    } else if (cmp?.mode === "two-way") {
+      lines.push(`    ${pad("contract")}${cmp.differences.length ? describeChange(cmp.differences[0]) : "same as current"}`);
+      for (const change of cmp.differences.slice(1)) lines.push(`    ${pad("")}${describeChange(change)}`);
+    }
+
+    if (row.breaks?.length) {
+      for (const [i, use] of row.breaks.slice(0, 8).entries()) {
+        const what = use.lostExport ? `<${use.component}> (no longer exported)` : `<${use.component} ${use.props.join(" ")}>`;
+        lines.push(`    ${pad(i === 0 ? "would break" : "")}${use.file}:${use.line}  ${what}`);
+      }
+      if (row.breaks.length > 8) lines.push(`    ${pad("")}…and ${row.breaks.length - 8} more`);
+    }
+
+    if (row.verdict.action) {
+      lines.push(`    ${pad("update")}${row.verdict.action}`);
+    } else if (row.verdict.force && row.behind) {
+      lines.push(`    ${pad("choices")}keep your copy (nothing to do), or replace it with ${row.kitVersion}`);
+      lines.push(`    ${pad("")}and lose your changes: ${row.verdict.force}`);
+    }
+    lines.push("");
+  }
+
+  if (quiet.length) {
+    lines.push(`  Up to date: ${quiet.map((row) => row.component).join(", ")}`);
+    lines.push("");
+  }
+
+  for (const name of report.notInstalled) lines.push(`  ${name}: not installed here`);
+  if (report.contractNote) lines.push(`  Note: ${report.contractNote}`);
+  if (!report.reactTypes) {
+    lines.push("  Note: @types/react was not found, so inherited DOM props were left out of the comparison.");
+  }
+  if (report.truncated) lines.push("  Note: stopped scanning after 20,000 source files; call sites past that were not checked.");
+
+  const edited = rows.filter((row) => row.state !== "pristine").length;
+  const conflicts = rows.reduce((n, row) => n + (row.comparison?.conflicts?.length || 0), 0);
+  const breaks = rows.reduce((n, row) => n + (row.breaks?.length || 0), 0);
+  lines.push(
+    `${rows.length} component(s) · ${edited} with your changes · ${conflicts} conflict(s) · ${breaks} call site(s) at risk`,
+  );
+  return lines.join("\n");
+}
+
+/* JSON for agents and CI: the report minus Sets and the bulky contracts. */
+function toJson(report) {
+  return {
+    kitVersion: report.kitVersion,
+    notInstalled: report.notInstalled,
+    note: report.contractNote,
+    components: report.rows.map((row) => ({
+      component: row.component,
+      folder: row.folder,
+      state: row.state,
+      baseline: row.baseline,
+      installedVersion: row.installedVersion,
+      behind: row.behind,
+      files: { changed: row.changed, deleted: row.missing, added: row.added },
+      comparison: row.comparison || null,
+      breaks: row.breaks || [],
+      verdict: row.verdict,
+    })),
+  };
+}
+
+module.exports = { formatReport, toJson };