@mmerterden/dev-toolkit-mcp 2.24.1

package/tools/design-check/scenario-inventory.js

@@ -0,0 +1,598 @@
+/**
+ * design_scenario_inventory - enumerate every state driver a mock-mode build
+ * exposes, so a design audit has a countable target set instead of "walk the UI
+ * until it feels done".
+ *
+ * The gap this closes: a screen reachable only by relaunching with a different
+ * launch argument, picking a different debug scenario case, or seeding a coded
+ * fixture is invisible to UI-walking. An auditor that only taps captures the
+ * linear happy path and silently drops the rest.
+ *
+ * Fully generic - no project, repo, or screen name is hardcoded. Every target
+ * comes from a source signal with file+line evidence:
+ *
+ *   launch-arg     "-MockSomething" argument literals (iOS) / boolean intent extras (Android)
+ *   scenario-case  cases of enums named *Scenario / *Outcome / *MockCase / *MockState
+ *   code-scenario  short uppercase switch codes ( case "AGN" ) used as scenario triggers
+ *   fixture        MockData/**\/*.json response fixtures
+ *   deep-link      custom-scheme URL literals
+ *
+ * returns:
+ *   {
+ *     platform, targetCount,
+ *     targets: [ { id, kind, label, screen, driver, evidence:{file,line,snippet} } ],
+ *     groups:  [ { group, kind, ids[] } ],
+ *     byKind:  { <kind>: n },
+ *     truncated: bool
+ *   }
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { basename, dirname, sep } from "path";
+
+import { hasRg, rg, walk, rel, detectPlatform, SRC_EXT } from "./scan.js";
+
+const MAX_TARGETS = 400;
+
+// Path segments that describe plumbing, not a screen.
+const INFRA_DIRS = new Set([
+  "sources", "source", "src", "classes", "common", "core", "shared", "base",
+  "debug", "mock", "mocks", "mockdata", "fixtures", "resources", "assets",
+  "helpers", "utils", "utilities", "extensions", "models", "model", "network",
+  "networking", "services", "service", "managers", "manager", "main", "app",
+  "java", "kotlin", "swift", "test", "tests",
+  "constants", "entities", "entity", "domain", "data", "presentation", "scenes",
+  "views", "view", "viewmodels", "repositories", "repository", "stores", "store",
+  "usecases", "screens", "features", "modules",
+]);
+
+// Suffixes that mark a type as a debug state selector rather than a domain type.
+const SCENARIO_SUFFIX = /(Scenario|Outcome|MockCase|MockState|DebugCase|MockVariant)$/;
+
+// A selector case meaning "don't override" produces no distinct visual state.
+const PASSTHROUGH_CASE = /^(useDefault|default|none|unset|disabled|off|live)$/i;
+
+const SCENARIO_ENUM_RE = /\b(?:enum|sealed class|sealed interface)\s+([A-Za-z0-9_]*(?:Scenario|Outcome|MockCase|MockState|DebugCase|MockVariant))\b/g;
+const LAUNCH_ARG_RE = /"(-[A-Za-z][A-Za-z0-9]*[Mm]ock[A-Za-z0-9]*|-[Mm]ock[A-Za-z0-9]*)"/g;
+const INTENT_EXTRA_RE = /(?:getBooleanExtra|hasExtra|putExtra)\s*\(\s*"([A-Za-z0-9_.]*[Mm]ock[A-Za-z0-9_.]*)"/g;
+// Coded scenario triggers appear as switch cases ( case "AGN" ) and as constants
+// ( let network = "NET" ). Both are trusted ONLY inside debug/mock support code:
+// elsewhere an uppercase string literal is far more likely a currency, locale,
+// country, or HTTP-verb constant, and a false target makes the coverage gate
+// unreachable. A scenario code living outside debug code is better recovered via
+// the config's extraTargets than by guessing here.
+const CODE_CASE_RE = /case\s+"([A-Z][A-Z0-9]{1,7})"/g;
+const CODE_CONST_RE = /(?:static\s+)?(?:let|val|const)\s+\w+\s*(?::\s*String)?\s*=\s*"([A-Z][A-Z0-9]{1,7})"/g;
+// The dominant variant mechanism in booking-style apps: a mock repository branches
+// on the prefix of the reference the user types, so each prefix is a distinct
+// screen state. These carry no enum and no constant - only a string test - which
+// is why an inventory that looks for selectors alone misses most of the matrix.
+const PREFIX_CODE_RE = /\.\s*has(?:Prefix|Suffix)\(\s*"([A-Z][A-Z0-9]{1,9})"\s*\)/g;
+// Debug support DIRECTORIES only. Deliberately not widened to Mock*-named files:
+// the per-screen mock repositories are already opened by their text signal, and
+// prefix detection below is not gated on this, so widening it would only enlarge
+// the false-positive surface for the uppercase-constant patterns.
+const DEBUG_PATH_RE = /(^|[/\\])(Debug|Mock[A-Za-z]*|DevSupport)([/\\]|$)/i;
+const DEEPLINK_RE = /"([a-z][a-z0-9+.-]{2,}):\/\/[A-Za-z0-9_\-./?=&{}]*"/g;
+// Schemes that are transport or platform plumbing, never an app entry point.
+const NON_APP_SCHEME = /^(https?|file|mailto|tel|sms|data|ftp|ws|wss|content|android\.resource|market|package|intent|jdbc|about|blob|javascript)$/i;
+
+function slug(s) {
+  return String(s || "").replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+
+function titleize(s) {
+  return String(s || "")
+    .replace(/^-+/, "")
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// Best-effort screen/feature name for a target: the most specific non-infra
+// directory on the path, falling back to the declaring symbol's own name.
+function screenFor(relPath, symbol) {
+  const parts = dirname(relPath || "").split(sep).filter(Boolean);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const p = parts[i];
+    if (!INFRA_DIRS.has(p.toLowerCase()) && !/^[.@]/.test(p)) return titleize(p);
+  }
+  if (symbol) return titleize(String(symbol).replace(SCENARIO_SUFFIX, ""));
+  const b = basename(relPath || "", ".swift").replace(/\.(kt|kts|json)$/, "");
+  return titleize(b) || "Unknown";
+}
+
+// The screen a launch argument drives, read from the argument itself - far more
+// specific than its declaration site, which is usually a shared constants file.
+function screenFromArg(arg) {
+  const core = String(arg).replace(/^-+/, "").replace(/^[Mm]ock/, "");
+  return titleize(core) || "Unknown";
+}
+
+// Blank out line comments and string literals so brace counting cannot be thrown
+// off by a `{` inside a doc comment or a raw-value string ( case open = "{" ).
+// Length is preserved, so indices into the sanitized copy still address the
+// original text.
+function maskLiteralsAndComments(text) {
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "/" && text[i + 1] === "/") {
+      const nl = text.indexOf("\n", i);
+      const end = nl < 0 ? text.length : nl;
+      out += " ".repeat(end - i);
+      i = end;
+    } else if (c === "/" && text[i + 1] === "*") {
+      const close = text.indexOf("*/", i + 2);
+      const end = close < 0 ? text.length : close + 2;
+      for (let k = i; k < end; k++) out += text[k] === "\n" ? "\n" : " ";
+      i = end;
+    } else if (c === '"') {
+      let k = i + 1;
+      while (k < text.length && text[k] !== '"' && text[k] !== "\n") {
+        if (text[k] === "\\") k++;
+        k++;
+      }
+      const end = Math.min(k + 1, text.length);
+      out += " ".repeat(end - i);
+      i = end;
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+// Cases of the enum whose declaration starts at `declIdx`. Brace-balanced, and
+// only cases at the enum's own nesting level count - a nested enum's cases
+// belong to that nested enum, which gets its own targets.
+function enumCases(text, declIdx) {
+  const masked = maskLiteralsAndComments(text);
+  const open = masked.indexOf("{", declIdx);
+  if (open < 0) return [];
+  let depth = 0, end = -1;
+  for (let i = open; i < masked.length; i++) {
+    const c = masked[i];
+    if (c === "{") depth++;
+    else if (c === "}") { depth--; if (depth === 0) { end = i; break; } }
+  }
+  const stop = end < 0 ? masked.length : end;
+  const body = text.slice(open + 1, stop);
+  const maskedBody = masked.slice(open + 1, stop);
+  const lines = body.split("\n");
+  const maskedLines = maskedBody.split("\n");
+  const out = [];
+  let level = 0;
+  for (let n = 0; n < lines.length; n++) {
+    if (level === 0) {
+      const m = /^\s*case\s+([A-Za-z_][\w]*(?:\s*,\s*[A-Za-z_][\w]*)*)/.exec(lines[n]);
+      if (m) {
+        for (const raw of m[1].split(",")) {
+          const name = raw.trim();
+          if (name && !out.includes(name)) out.push(name);
+        }
+      }
+    }
+    for (const ch of maskedLines[n] || "") {
+      if (ch === "{") level++;
+      else if (ch === "}") level = Math.max(0, level - 1);
+    }
+  }
+  return out;
+}
+
+// What it costs to put the app into this state. The single biggest reason a design
+// audit under-covers a module is treating every state as equally expensive: a
+// scenario case flips inside the running app, while a launch argument costs a full
+// relaunch plus re-navigation. Ordering by cost is what makes full coverage
+// affordable in one run.
+const DRIVER_COST = {
+  "launch-arg": "relaunch",
+  "intent-extra": "relaunch",
+  "deeplink": "relaunch",
+  "scenario": "in-app",
+  "code": "in-app",
+  "fixture": "unknown",
+  "manual": "unknown",
+};
+
+const screenKey = (s) => String(s || "").replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+
+function makeAdder(targets, seen) {
+  return function add(kind, key, { label, screen, driver, file, line, snippet }) {
+    const id = `${kind}:${slug(key)}`;
+    if (seen.has(id) || targets.length >= MAX_TARGETS) return false;
+    seen.add(id);
+    targets.push({
+      id, kind,
+      label: label || titleize(key),
+      screen: screen || "Unknown",
+      driver,
+      cost: DRIVER_COST[driver && driver.type] || "unknown",
+      evidence: { file, line: line || 0, snippet: (snippet || "").slice(0, 160) },
+    });
+    return true;
+  };
+}
+
+/**
+ * Order the targets into launch batches so one relaunch serves as many targets as
+ * possible: each relaunch target opens a screen, and every in-app target for that
+ * same screen is flipped while the app is already sitting there. In-app targets
+ * with no matching relaunch target go in a final default-launch batch.
+ *
+ * The batch count IS the relaunch count, which is the run's real cost.
+ */
+/**
+ * Group targets into launch batches.
+ *
+ * Exported for the determinism test: target discovery walks the filesystem and
+ * that read order is not stable across runs, so this function has to produce the
+ * same plan for any permutation of its input. Proving that by construction is
+ * worth more than a suite that happens to pass, because the failure it guards
+ * against showed up as an intermittently red gate rather than a wrong answer.
+ */
+export function buildPlan(targets) {
+  const relaunch = targets.filter((t) => t.cost === "relaunch");
+  const inApp = targets.filter((t) => t.cost !== "relaunch");
+  const claimed = new Set();
+  const batches = [];
+
+  // Relaunch order is canonical, not discovery order. Target discovery walks the
+  // filesystem and that order is not stable across runs, so a first-come rider
+  // claim made the whole plan nondeterministic: identical input produced
+  // different batches between runs of the same audit.
+  const orderedRelaunch = [...relaunch].sort(
+    (a, b) =>
+      screenKey(a.screen).localeCompare(screenKey(b.screen)) ||
+      String(a.id).localeCompare(String(b.id)),
+  );
+
+  // Riders are assigned by BEST match, not by whoever iterates first.
+  //
+  // Screen names rarely spell identically ("Apis Form" vs "APIS"), so a substring
+  // match still counts - but it must not outrank an exact one, and among equal
+  // matches the relaunch that carries an actual launch argument has to win: a
+  // relaunch with no argument cannot put the app into the mock state its riders
+  // need, so parking them there produces a plan that cannot be driven. Both used
+  // to be decided by iteration order alone.
+  //
+  // Score is a tuple, compared high to low:
+  //   screen match   exact (2) > substring (1) > none (0)
+  //   drivability    has a launch argument (1) > does not (0)
+  //   canonical order first wins, so the result never depends on discovery order
+  const matchScore = (relaunchScreen, riderScreen) => {
+    const x = screenKey(relaunchScreen);
+    const y = screenKey(riderScreen);
+    if (!x || !y) return 0;
+    if (x === y) return 2;
+    if (x.includes(y) || y.includes(x)) return 1;
+    return 0;
+  };
+  const drivable = (t) => (t.driver && t.driver.launchArg ? 1 : 0);
+
+  const ridersFor = new Map(orderedRelaunch.map((t) => [t.id, []]));
+  for (const rider of inApp) {
+    let best = null;
+    let bestKey = [0, 0];
+    for (const t of orderedRelaunch) {
+      const key = [matchScore(t.screen, rider.screen), drivable(t)];
+      if (key[0] === 0) continue;
+      // Strictly greater on the tuple: ties fall to canonical order.
+      if (key[0] > bestKey[0] || (key[0] === bestKey[0] && key[1] > bestKey[1])) {
+        bestKey = key;
+        best = t;
+      }
+    }
+    if (best) {
+      ridersFor.get(best.id).push(rider);
+      claimed.add(rider.id);
+    }
+  }
+
+  const byId = (a, b) => String(a).localeCompare(String(b));
+  for (const t of orderedRelaunch) {
+    const riders = ridersFor.get(t.id) || [];
+    batches.push({
+      launch: t.driver,
+      screen: t.screen,
+      // Rider ids are sorted too: which relaunch owns a rider is decided above,
+      // but the order they are listed in still followed discovery order, so the
+      // plan was not yet byte-identical between runs. Batch membership is a set.
+      targetIds: [t.id, ...riders.map((x) => x.id).sort(byId)],
+    });
+  }
+
+  const orphans = inApp.filter((x) => !claimed.has(x.id));
+  if (orphans.length) {
+    batches.push({
+      launch: null,
+      screen: "(default launch)",
+      targetIds: orphans.map((x) => x.id).sort(byId),
+    });
+  }
+  return batches;
+}
+
+function collectFromText({ text, absFile, relPath, platform, add }) {
+  const lineOf = (idx) => text.slice(0, idx).split("\n").length;
+  const lineText = (n) => (text.split("\n")[n - 1] || "").trim();
+
+  // 1. launch arguments / intent extras - each is a distinct relaunch target.
+  const argRe = platform === "android" ? INTENT_EXTRA_RE : LAUNCH_ARG_RE;
+  argRe.lastIndex = 0;
+  for (let m; (m = argRe.exec(text)); ) {
+    const arg = m[1];
+    const ln = lineOf(m.index);
+    add("launch-arg", arg, {
+      label: titleize(arg),
+      screen: screenFromArg(arg),
+      driver: platform === "android"
+        ? { type: "intent-extra", intentExtra: `--ez ${arg} true` }
+        : { type: "launch-arg", launchArg: arg },
+      file: relPath, line: ln, snippet: lineText(ln),
+    });
+  }
+
+  // 2. debug scenario enums - one target per case (per-screen outcome pickers).
+  // Every declaration in the file counts: a debug store commonly nests one
+  // outcome enum per screen inside a single namespace type.
+  SCENARIO_ENUM_RE.lastIndex = 0;
+  for (let em; (em = SCENARIO_ENUM_RE.exec(text)); ) {
+    const enumName = em[1];
+    const ln = lineOf(em.index);
+    for (const c of enumCases(text, em.index)) {
+      if (PASSTHROUGH_CASE.test(c)) continue;
+      add("scenario-case", `${enumName}-${c}`, {
+        label: `${titleize(enumName)} → ${titleize(c)}`,
+        screen: titleize(enumName.replace(SCENARIO_SUFFIX, "")) || screenFor(relPath, enumName),
+        driver: { type: "scenario", enum: enumName, case: c },
+        file: relPath, line: ln, snippet: lineText(ln),
+      });
+    }
+  }
+
+  // 3a. reference-prefix variants: the mock repository that branches on them names
+  // the screen they belong to, so they group with that screen rather than into a
+  // cross-cutting bucket.
+  PREFIX_CODE_RE.lastIndex = 0;
+  for (let m; (m = PREFIX_CODE_RE.exec(text)); ) {
+    const code = m[1];
+    const ln = lineOf(m.index);
+    const screen = screenFor(relPath, basename(relPath || "").replace(/^Mock|Repository\.\w+$/g, ""));
+    add("prefix-code", `${screen}-${code}`, {
+      label: `${code} → ${screen}`,
+      screen,
+      driver: { type: "code", code, appliesTo: screen },
+      file: relPath, line: ln, snippet: lineText(ln),
+    });
+  }
+
+  // 3b. short uppercase scenario codes declared as switch cases or constants, read
+  // only from debug/mock support code - see NON_APP_SCHEME's neighbours for why.
+  // Unlike 3a these carry no owning screen, so they stay in a shared bucket.
+  const codeSources = DEBUG_PATH_RE.test(relPath || "") ? [CODE_CASE_RE, CODE_CONST_RE] : [];
+  for (const re of codeSources) {
+    re.lastIndex = 0;
+    for (let m; (m = re.exec(text)); ) {
+      const code = m[1];
+      const ln = lineOf(m.index);
+      add("code-scenario", code, {
+        label: code,
+        // Codes are typed at an entry field and steer whichever screen follows -
+        // pinning them to their declaration site's folder would mislead.
+        screen: "Scenario codes",
+        driver: { type: "code", code },
+        file: relPath, line: ln, snippet: lineText(ln),
+      });
+    }
+  }
+
+  // 4. custom-scheme deep links - direct entry points to otherwise deep screens.
+  DEEPLINK_RE.lastIndex = 0;
+  for (let m; (m = DEEPLINK_RE.exec(text)); ) {
+    const url = m[0].slice(1, -1);
+    if (NON_APP_SCHEME.test(m[1])) continue;
+    const ln = lineOf(m.index);
+    add("deep-link", url, {
+      label: url,
+      screen: screenFor(relPath, null),
+      driver: { type: "deeplink", url },
+      file: relPath, line: ln, snippet: lineText(ln),
+    });
+  }
+}
+
+// rg narrows the file set; the walk fallback opens every source file. Both must
+// admit exactly the same files, or the inventory - and therefore the coverage
+// denominator - would depend on whether ripgrep happens to be on PATH.
+//
+// Content probes mirror TEXT_SIGNAL_RE plus the two literal shapes that carry no
+// mock/scenario word of their own (uppercase switch cases and uppercase constants).
+export const RG_PROBES = [
+  `[Mm]ock`,
+  `(?:enum|sealed class|sealed interface)\\s+[A-Za-z0-9_]*(?:Scenario|Outcome|MockCase|MockState|DebugCase|MockVariant)\\b`,
+  `case\\s+"[A-Z][A-Z0-9]{1,7}"`,
+  `(?:let|val|const)\\s+\\w+\\s*(?::\\s*String)?\\s*=\\s*"[A-Z][A-Z0-9]{1,7}"`,
+  `has(?:Prefix|Suffix)\\(\\s*"[A-Z][A-Z0-9]{1,9}"`,
+  `"[a-z][a-z0-9+.-]{2,}://`,
+];
+// Path probes mirror the DEBUG_PATH_RE half of shouldOpen: a debug constants file
+// whose whole content is `let agency = "AGN"` matches no content probe, and the
+// walk would open it on its path alone. Without these globs the rg path would
+// silently miss exactly the scenario codes this tool exists to find.
+export const RG_PATH_GLOBS = [
+  "**/Debug/**/*.swift", "**/Debug/**/*.kt", "**/Debug/**/*.kts",
+  "**/Mock*/**/*.swift", "**/Mock*/**/*.kt", "**/Mock*/**/*.kts",
+  "**/DevSupport/**/*.swift", "**/DevSupport/**/*.kt", "**/DevSupport/**/*.kts",
+  "**/*Mock*.swift", "**/*Mock*.kt", "**/*Mock*.kts",
+];
+const TEXT_SIGNAL_RE = /[Mm]ock|Scenario|Outcome|:\/\//;
+// Debug/mock support code is admitted on its path alone: a constants file holding
+// nothing but scenario codes carries no other signal.
+const shouldOpen = (relPath, text) => DEBUG_PATH_RE.test(relPath || "") || TEXT_SIGNAL_RE.test(text);
+
+export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], extraTargets = [], ignoreTargets = [], strategy = "auto", summary = false } = {}) {
+  if (!repoPath || !existsSync(repoPath)) {
+    return { platform: "unknown", targetCount: 0, targets: [], groups: [], byKind: {}, byCost: {},
+      plan: [], relaunchCount: 0, truncated: false, ignored: [], scanStrategy: "none",
+      reason: `repoPath not found: ${repoPath}` };
+  }
+  const plat = platform || detectPlatform(repoPath);
+  const targets = [];
+  const seen = new Set();
+  const add = makeAdder(targets, seen);
+  const useRg = strategy === "rg" || (strategy === "auto" && hasRg());
+
+  const candidates = new Set();
+  if (useRg) {
+    try {
+      for (const p of RG_PROBES) for (const hit of rg(p, repoPath)) candidates.add(hit.file);
+      for (const g of RG_PATH_GLOBS) for (const hit of rg(g, repoPath, { files: true, globs: [] })) candidates.add(hit.file);
+    } catch { candidates.clear(); }
+  }
+  const consider = (absFile) => {
+    let text = ""; try { text = readFileSync(absFile, "utf-8"); } catch { return; }
+    const relPath = rel(repoPath, absFile);
+    if (!shouldOpen(relPath, text)) return;
+    collectFromText({ text, absFile, relPath, platform: plat, add });
+  };
+  let scanStrategy;
+  if (candidates.size) {
+    scanStrategy = "rg";
+    for (const absFile of candidates) consider(absFile);
+  } else {
+    // Reached when rg is absent, unusable, or genuinely found nothing - in the last
+    // case the walk confirms the empty result rather than trusting a silent zero.
+    scanStrategy = "walk";
+    walk(repoPath, (absFile) => {
+      const ext = "." + (basename(absFile).split(".").pop() || "");
+      if (!SRC_EXT.has(ext)) return;
+      consider(absFile);
+    });
+  }
+
+  // 5. response fixtures - a fixture that no launch arg or scenario case names is
+  // still a distinct state someone has to look at.
+  const fixtures = [];
+  if (useRg) {
+    try { for (const f of rg("**/MockData/**/*.json", repoPath, { files: true, globs: [] })) fixtures.push(f.file); } catch { /* fall through */ }
+  }
+  if (!fixtures.length) {
+    walk(repoPath, (f) => { if (/\/MockData\//.test(f) && f.endsWith(".json")) fixtures.push(f); });
+  }
+  for (const absFile of fixtures) {
+    const relPath = rel(repoPath, absFile);
+    const name = basename(absFile, ".json");
+    add("fixture", relPath, {
+      label: titleize(name.replace(/_?mock_?/i, "")) || titleize(name),
+      screen: screenFor(relPath, name),
+      driver: { type: "fixture", file: relPath },
+      file: relPath, line: 0, snippet: "",
+    });
+  }
+
+  // Caller-supplied additions: project config knows states no signal can reveal.
+  for (const a of extraLaunchArgs) {
+    add("launch-arg", a, {
+      label: titleize(a), screen: "Config",
+      driver: plat === "android" ? { type: "intent-extra", intentExtra: `--ez ${a} true` } : { type: "launch-arg", launchArg: a },
+      file: "design-check-config.json", line: 0, snippet: "",
+    });
+  }
+  for (const t of extraTargets) {
+    if (!t || !t.id) continue;
+    const id = String(t.id);
+    if (seen.has(id) || targets.length >= MAX_TARGETS) continue;
+    seen.add(id);
+    targets.push({
+      id, kind: t.kind || "config", label: t.label || titleize(id),
+      screen: t.screen || "Config", driver: t.driver || { type: "manual" },
+      evidence: { file: "design-check-config.json", line: 0, snippet: "" },
+    });
+  }
+
+  // Config-declared drops: dead drivers, or states retired in code but still
+  // referenced. Unlike a skip these never reach the coverage gate, so they are
+  // reported back explicitly rather than disappearing.
+  const ignore = new Set(ignoreTargets.map(String));
+  const kept = ignore.size ? targets.filter((t) => !ignore.has(t.id)) : targets;
+  const ignored = ignore.size ? targets.filter((t) => ignore.has(t.id)).map((t) => t.id) : [];
+
+  const byScreen = new Map();
+  const byKindRaw = {};
+  for (const t of kept) {
+    byKindRaw[t.kind] = (byKindRaw[t.kind] || 0) + 1;
+    const k = `${t.screen}`;
+    if (!byScreen.has(k)) byScreen.set(k, []);
+    byScreen.get(k).push(t.id);
+  }
+  const groups = [...byScreen.entries()]
+    .map(([group, ids]) => ({ group, ids }))
+    // Tie-break on the group name: without it, two screens with the same target
+    // count keep whatever relative order target discovery happened to produce,
+    // and that order is not stable across runs.
+    .sort((a, b) => b.ids.length - a.ids.length || a.group.localeCompare(b.group));
+
+  const plan = buildPlan(kept);
+  const byCostRaw = {};
+  for (const t of kept) byCostRaw[t.cost] = (byCostRaw[t.cost] || 0) + 1;
+
+  // Count maps are emitted with sorted keys. Target discovery walks the
+  // filesystem and directory read order is not stable across runs, so insertion
+  // order was too: two calls on identical input produced identical counts whose
+  // `JSON.stringify` differed, which is what made the inventory tests flaky and
+  // would defeat any diff or golden-file comparison of a report. A count map has
+  // no meaningful order, so canonicalising it changes no behaviour.
+  const sortedKeys = (o) =>
+    Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
+  const byKind = sortedKeys(byKindRaw);
+  const byCost = sortedKeys(byCostRaw);
+
+  const full = {
+    platform: plat,
+    targetCount: kept.length,
+    targets: kept,
+    groups,
+    byKind,
+    byCost,
+    scanStrategy,
+    // Relaunch count == batch count. Drive the batches in order and full coverage
+    // costs this many relaunches, not one per target.
+    plan,
+    relaunchCount: plan.filter((b) => b.launch).length,
+    ignored,
+    // The cap is a runaway guard, not a sampling strategy: a truncated inventory
+    // means the coverage gate is measuring an incomplete target set, and the run
+    // must say so rather than report a clean percentage of a partial denominator.
+    truncated: targets.length >= MAX_TARGETS,
+  };
+
+  if (!summary) return full;
+
+  // Summary mode. The full payload for a 109-target module measured 71,196
+  // characters and blew the host's tool-result cap on all seven runs of a real
+  // audit, forcing a write-to-file round trip every time. targets[] is nearly
+  // all of that: one entry per target carrying label, screen, driver and a
+  // file+line+snippet evidence block.
+  //
+  // Dropping it costs nothing structural, because `plan` already carries every
+  // target id in the order they should be driven, and `groups` carries the
+  // per-screen id lists. What is lost is the per-target label and evidence,
+  // which a caller can fetch by asking for the full payload once it knows which
+  // targets it cares about.
+  //
+  // targetsOmitted is stated rather than implied: a consumer must be able to see
+  // that the target list was withheld on purpose, not that the scan found none.
+  const { targets: _omitted, ...rest } = full;
+  return {
+    ...rest,
+    summary: true,
+    targetsOmitted: kept.length,
+    hint: "targets[] withheld for size; ids are in plan[].targetIds and groups[].ids. Call again with summary:false for labels and file+line evidence.",
+  };
+}