@grampro/kit 2.7.0 → 2.7.2

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 };

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/README.md

@@ -266,3 +266,26 @@ CLI's own dependencies, which are no use to a JSON-RPC loop and cost around
 The catalogue it serves is the one in this package, not the components
 copied into your project — so an agent can see a component before you
 install it, and `install_component` puts it in place.
+
+### What a caller can reach
+
+Every tool argument is treated as untrusted. An agent that has read a hostile
+web page or design file can be steered into calling these tools with
+anything, so the boundary has to hold no matter who wrote the arguments.
+
+- **`get_guidance`** serves only the guidance topics that ship in this
+  package. Any other topic is refused, including one containing `../`. Before
+  2.7.1 it was not refused: a crafted topic could read any `.md` file the
+  server could open. See the changelog.
+- **`get_component`, `get_example` and `install_component`** accept only names
+  in the catalogue. A name is reduced to letters and digits before anything
+  is looked up, and `install_component` runs the CLI with an argument list,
+  never through a shell.
+- **`figma_frame` with `designFile`** reads the path it is given, with your
+  user's permissions. It only returns content from a file shaped like the
+  plugin's export, and refuses anything else without quoting it. A file that
+  *is* shaped like an export gets read as one, which is the tool's purpose.
+
+The server runs as you, so none of this stops an agent that can already read
+your files directly. What it prevents is a tool that advertises one narrow
+job being turned into a general file reader.