@mmerterden/multi-agent-toolkit-mcp 3.14.0 → 3.15.0

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

@@ -12,7 +12,8 @@
  * 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
+ *   scenario-case  cases of enums named *Scenario / *Outcome / *MockCase / *MockState,
+ *                  only when debug evidence backs the name (see resolveSelectors)
  *   code-scenario  short uppercase switch codes ( case "AGN" ) used as scenario triggers
  *   fixture        MockData/**\/*.json response fixtures
  *   deep-link      custom-scheme URL literals
@@ -23,6 +24,8 @@
  *     targets: [ { id, kind, label, screen, driver, evidence:{file,line,snippet} } ],
  *     groups:  [ { group, kind, ids[] } ],
  *     byKind:  { <kind>: n },
+ *     acceptedSelectors: [ { type, file, line, basis } ],
+ *     rejectedSelectors: [ { type, file, line, reason, productionReferences[] } ],
  *     truncated: bool
  *   }
  */
@@ -73,6 +76,16 @@ const PREFIX_CODE_RE = /\.\s*has(?:Prefix|Suffix)\(\s*"([A-Z][A-Z0-9]{1,9})"\s*\
 // 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;
+// Android build variants that never reach a release build: src/debug,
+// src/mock, src/mockDebug, src/stagingDebug, ...
+const DEBUG_SOURCE_SET_RE = /(^|[/\\])src[/\\](debug|mock[A-Za-z]*|[a-z][A-Za-z]*(Debug|Mock))([/\\]|$)/;
+// Test targets reference production and debug types alike, so a reference from
+// one says nothing about which of the two a selector is.
+const TEST_PATH_RE = /(^|[/\\])(Tests?|[A-Za-z]*Tests|src[/\\](test|androidTest)[A-Za-z]*)([/\\]|$)|Tests?\.(swift|kt|kts)$/;
+const MOCK_FILE_RE = /(^|[/\\])Mock[A-Za-z0-9_]*\.(swift|kt|kts)$/;
+// Readers of a value the tester sets at launch or on the device: a selector
+// constructed from one of these is switchable without a rebuild.
+const RUNTIME_KEY_RE = /\b(UserDefaults|ProcessInfo|CommandLine\.arguments|launchArguments|launchEnvironment|getSharedPreferences|SharedPreferences|getStringExtra|getIntExtra|getBooleanExtra|getSerializableExtra|getParcelableExtra|intent\.extras|getQueryParameter)\b/;
 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;
@@ -150,17 +163,24 @@ function maskLiteralsAndComments(text) {
 // 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);
+// [open, stop) of the brace-balanced body that follows `declIdx`, or null.
+function bodyRange(masked, declIdx) {
   const open = masked.indexOf("{", declIdx);
-  if (open < 0) return [];
+  if (open < 0) return null;
   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;
+  return [open, end < 0 ? masked.length : end];
+}
+
+function enumCases(text, declIdx) {
+  const masked = maskLiteralsAndComments(text);
+  const range = bodyRange(masked, declIdx);
+  if (!range) return [];
+  const [open, stop] = range;
   const body = text.slice(open + 1, stop);
   const maskedBody = masked.slice(open + 1, stop);
   const lines = body.split("\n");
@@ -185,6 +205,117 @@ function enumCases(text, declIdx) {
   return out;
 }
 
+// Per-line flag: is this line compiled only into a debug/mock build? Swift
+// `#if` blocks whose condition names DEBUG or a MOCK* flag (not negated), with
+// `#else` flipping and nesting honoured. Kotlin has no preprocessor, so an
+// Android file answers through its source set instead.
+function debugLineMask(text) {
+  const lines = text.split("\n");
+  const out = new Array(lines.length).fill(false);
+  const stack = [];
+  const debugCond = (cond) => /(^|[^!\w])(DEBUG|MOCK[A-Z0-9_]*)\b/.test(cond);
+  const negatedCond = (cond) => /!\s*(DEBUG|MOCK[A-Z0-9_]*)\b/.test(cond);
+  for (let n = 0; n < lines.length; n++) {
+    const t = lines[n].trim();
+    let m;
+    if ((m = /^#if\b(.*)$/.exec(t))) { stack.push({ debug: debugCond(m[1]), negated: negatedCond(m[1]) }); continue; }
+    if ((m = /^#elseif\b(.*)$/.exec(t)) && stack.length) { stack[stack.length - 1] = { debug: debugCond(m[1]), negated: negatedCond(m[1]) }; continue; }
+    if (/^#else\b/.test(t) && stack.length) { const top = stack[stack.length - 1]; stack[stack.length - 1] = { debug: top.negated, negated: false }; continue; }
+    if (/^#endif\b/.test(t)) { stack.pop(); continue; }
+    out[n] = stack.some((f) => f.debug);
+  }
+  return out;
+}
+
+function pathClass(relPath) {
+  const p = relPath || "";
+  if (TEST_PATH_RE.test(p)) return "test";
+  if (DEBUG_SOURCE_SET_RE.test(p)) return "debug-source-set";
+  if (DEBUG_PATH_RE.test(p) || MOCK_FILE_RE.test(p)) return "debug";
+  return "production";
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Decide which suffix-matched selector types are real state drivers.
+ *
+ * A name like *Outcome or *Scenario is also a common production type (a service
+ * result, a domain state), and counting its cases puts targets in the coverage
+ * denominator that no debug switch can reach. A candidate becomes a target when
+ * one of these holds:
+ *   a. it is declared where only a debug build sees it - inside `#if DEBUG`, or
+ *      in an Android debug/mock source set
+ *   b. no production code references it, and something debug does - its own
+ *      declaration file (Debug/, Mock*, DevSupport) or a referencing file
+ *   c. it is constructed next to a runtime key reader (launch argument,
+ *      UserDefaults, SharedPreferences, intent extra), so a tester can switch it
+ * References from test targets are neutral, and a type's mentions of itself
+ * inside its own body are not references.
+ *
+ * `referenceFiles` is every source file mentioning at least one candidate name,
+ * as { relPath, text }; both scanners hand over the same set.
+ */
+function resolveSelectors(candidates, referenceFiles) {
+  const byName = new Map();
+  for (const c of candidates) {
+    if (!byName.has(c.enumName)) byName.set(c.enumName, []);
+    byName.get(c.enumName).push({ ...c, prod: [], debugRefs: 0, runtimeKey: null });
+  }
+  if (!byName.size) return { accepted: [], rejected: [] };
+  const nameRe = new RegExp(`\\b(${[...byName.keys()].map(escapeRe).join("|")})\\b`, "g");
+
+  for (const { relPath, text } of referenceFiles) {
+    const masked = maskLiteralsAndComments(text);
+    const lines = masked.split("\n");
+    const debugLines = debugLineMask(text);
+    const cls = pathClass(relPath);
+    const lineStarts = [0];
+    for (let i = 0; i < masked.length; i++) if (masked[i] === "\n") lineStarts.push(i + 1);
+    const lineAt = (idx) => { let lo = 0, hi = lineStarts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (lineStarts[mid] <= idx) lo = mid; else hi = mid - 1; } return lo; };
+    nameRe.lastIndex = 0;
+    for (let m; (m = nameRe.exec(masked)); ) {
+      for (const c of byName.get(m[1])) {
+        const own = c.relPath === relPath;
+        if (own && m.index === c.nameIdx) continue;
+        const ln = lineAt(m.index);
+        const window = [lines[ln - 1], lines[ln], lines[ln + 1]].filter(Boolean).join("\n");
+        if (!c.runtimeKey && RUNTIME_KEY_RE.test(window)) c.runtimeKey = { file: relPath, line: ln + 1 };
+        if (own && c.body && m.index > c.body[0] && m.index < c.body[1]) continue;
+        if (cls === "test") continue;
+        if (cls !== "production" || debugLines[ln]) c.debugRefs++;
+        else c.prod.push({ file: relPath, line: ln + 1 });
+      }
+    }
+  }
+
+  const accepted = [], rejected = [];
+  for (const list of byName.values()) {
+    for (const c of list) {
+      const declClass = pathClass(c.relPath);
+      let basis = null;
+      if (c.declInDebugBlock || declClass === "debug-source-set") basis = "debug-declaration";
+      else if (c.runtimeKey) basis = "runtime-key";
+      else if (!c.prod.length && (declClass === "debug" || c.debugRefs > 0)) basis = "debug-only-references";
+      const head = { type: c.enumName, file: c.relPath, line: c.line };
+      if (basis) {
+        accepted.push({ ...head, basis, ...(c.runtimeKey ? { runtimeKey: c.runtimeKey } : {}), candidate: c });
+      } else {
+        const refs = c.prod.slice().sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+        rejected.push({
+          ...head,
+          reason: refs.length
+            ? `referenced from production code (${refs.length} site${refs.length === 1 ? "" : "s"}); not a debug state selector`
+            : "declared in production code and referenced from no debug or mock code",
+          productionReferences: refs.slice(0, 5),
+        });
+      }
+    }
+  }
+  const order = (a, b) => a.type.localeCompare(b.type) || a.file.localeCompare(b.file);
+  return { accepted: accepted.sort(order), rejected: rejected.sort(order) };
+}
+
 // 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
@@ -200,12 +331,141 @@ const DRIVER_COST = {
   "manual": "unknown",
 };
 
+/**
+ * The target shape, shared by the scanner's own output, the MCP tool's
+ * `targets[]` input and a `targets_file` catalog. One definition, so a catalog
+ * saved from a run and a catalog written by hand are the same thing.
+ *
+ * Catalog file: either a bare array of targets, or
+ *   { "version": 1, "platform"?: "ios"|"android", "description"?: string, "targets": [ ... ] }
+ */
+export const TARGET_DRIVER_FIELDS = {
+  "launch-arg": ["launchArg"],
+  "intent-extra": ["intentExtra"],
+  "deeplink": ["url"],
+  "scenario": ["enum", "case"],
+  "code": ["code"],
+  "fixture": ["file"],
+  "manual": [],
+};
+const str = { type: "string" };
+export const TARGET_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "driver"],
+  properties: {
+    id: { type: "string", minLength: 1 },
+    kind: str,
+    label: str,
+    screen: str,
+    cost: { type: "string", enum: ["relaunch", "in-app", "unknown"] },
+    driver: {
+      type: "object",
+      additionalProperties: false,
+      required: ["type"],
+      properties: {
+        type: { type: "string", enum: Object.keys(TARGET_DRIVER_FIELDS) },
+        launchArg: str, intentExtra: str, url: str, enum: str, case: str,
+        code: str, appliesTo: str, file: str, note: str,
+      },
+    },
+    evidence: {
+      type: "object",
+      additionalProperties: false,
+      properties: { file: str, line: { type: "integer", minimum: 0 }, snippet: str, basis: str },
+    },
+  },
+};
+export const TARGET_CATALOG_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["targets"],
+  properties: {
+    version: { type: "integer", enum: [1] },
+    platform: { type: "string", enum: ["ios", "android"] },
+    description: str,
+    targets: { type: "array", items: TARGET_SCHEMA },
+  },
+};
+
+const typeOk = (v, t) => (t === "string" ? typeof v === "string"
+  : t === "integer" ? Number.isInteger(v)
+  : t === "number" ? typeof v === "number" && Number.isFinite(v)
+  : t === "boolean" ? typeof v === "boolean"
+  : t === "array" ? Array.isArray(v)
+  : t === "object" ? v !== null && typeof v === "object" && !Array.isArray(v)
+  : true);
+
+// The JSON-Schema subset the schemas above use: type, enum, required,
+// additionalProperties:false, minLength, minimum, items. Returns the first
+// violation as "<path>: <problem>", or null.
+export function schemaViolation(schema, value, path) {
+  if (schema.type && !typeOk(value, schema.type)) return `${path}: must be ${schema.type}`;
+  if (schema.enum && !schema.enum.includes(value)) return `${path}: must be one of ${JSON.stringify(schema.enum)}`;
+  if (typeof value === "string" && Number.isFinite(schema.minLength) && value.length < schema.minLength) return `${path}: must not be empty`;
+  if (typeof value === "number" && Number.isFinite(schema.minimum) && value < schema.minimum) return `${path}: must be >= ${schema.minimum}`;
+  if (Array.isArray(value) && schema.items) {
+    for (let i = 0; i < value.length; i++) {
+      const e = schemaViolation(schema.items, value[i], `${path}[${i}]`);
+      if (e) return e;
+    }
+  }
+  if (schema.type === "object" && typeOk(value, "object")) {
+    for (const req of schema.required || []) if (value[req] === undefined) return `${path}: missing required field: ${req}`;
+    const props = schema.properties || {};
+    if (schema.additionalProperties === false) {
+      const extra = Object.keys(value).find((k) => !Object.hasOwn(props, k));
+      if (extra) return `${path}: unexpected field: ${extra}`;
+    }
+    for (const [k, sub] of Object.entries(props)) {
+      if (value[k] === undefined) continue;
+      const e = schemaViolation(sub, value[k], `${path}.${k}`);
+      if (e) return e;
+    }
+  }
+  return null;
+}
+
+// Validates a target list against TARGET_SCHEMA plus what a schema cannot say:
+// the per-driver-type fields and id uniqueness. Throws on the first problem.
+export function validateTargets(list, path) {
+  const e = schemaViolation({ type: "array", items: TARGET_SCHEMA }, list, path);
+  if (e) throw new Error(`invalid target catalog: ${e}`);
+  const ids = new Set();
+  list.forEach((t, i) => {
+    for (const f of TARGET_DRIVER_FIELDS[t.driver.type]) {
+      if (typeof t.driver[f] !== "string" || !t.driver[f]) {
+        throw new Error(`invalid target catalog: ${path}[${i}].driver: type '${t.driver.type}' requires ${f}`);
+      }
+    }
+    if (ids.has(t.id)) throw new Error(`invalid target catalog: duplicate target id: ${t.id}`);
+    ids.add(t.id);
+  });
+  return list;
+}
+
+export function loadTargetCatalog(file) {
+  let raw;
+  try { raw = readFileSync(file, "utf-8"); } catch (err) { throw new Error(`targets_file unreadable: ${file} (${err.code || err.message})`); }
+  let doc;
+  try { doc = JSON.parse(raw); } catch (err) { throw new Error(`targets_file is not valid JSON: ${file} (${err.message})`); }
+  if (Array.isArray(doc)) return validateTargets(doc, "targets_file");
+  if (!typeOk(doc, "object")) throw new Error(`targets_file must hold an array of targets or { targets: [...] }: ${file}`);
+  const e = schemaViolation({ ...TARGET_CATALOG_SCHEMA, properties: { ...TARGET_CATALOG_SCHEMA.properties, targets: { type: "array" } } }, doc, "targets_file");
+  if (e) throw new Error(`invalid target catalog: ${e}`);
+  return validateTargets(doc.targets, "targets_file.targets");
+}
+
 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 }) {
+// `cap` bounds what a source scan may add; `onDrop` hears about every target
+// refused for reaching it, which is what `truncated` reports. Caller-declared
+// targets go through an adder without a cap.
+function makeAdder(targets, seen, { cap = Infinity, onDrop = () => {} } = {}) {
+  return function add(kind, key, { label, screen, driver, file, line, snippet, basis }) {
     const id = `${kind}:${slug(key)}`;
-    if (seen.has(id) || targets.length >= MAX_TARGETS) return false;
+    if (seen.has(id)) return false;
+    if (targets.length >= cap) { onDrop(id); return false; }
     seen.add(id);
     targets.push({
       id, kind,
@@ -213,7 +473,7 @@ function makeAdder(targets, seen) {
       screen: screen || "Unknown",
       driver,
       cost: DRIVER_COST[driver && driver.type] || "unknown",
-      evidence: { file, line: line || 0, snippet: (snippet || "").slice(0, 160) },
+      evidence: { file, line: line || 0, snippet: (snippet || "").slice(0, 160), ...(basis ? { basis } : {}) },
     });
     return true;
   };
@@ -254,7 +514,7 @@ export function buildPlan(targets) {
 
   // Riders are assigned by BEST match, not by whoever iterates first.
   //
-  // Screen names rarely spell identically ("Apis Form" vs "APIS"), so a substring
+  // Screen names rarely spell identically ("Order Form" vs "ORDER"), 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
@@ -318,7 +578,7 @@ export function buildPlan(targets) {
   return batches;
 }
 
-function collectFromText({ text, absFile, relPath, platform, add }) {
+function collectFromText({ text, absFile, relPath, platform, add, selectors }) {
   const lineOf = (idx) => text.slice(0, idx).split("\n").length;
   const lineText = (n) => (text.split("\n")[n - 1] || "").trim();
 
@@ -338,22 +598,23 @@ function collectFromText({ text, absFile, relPath, platform, add }) {
     });
   }
 
-  // 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.
+  // 2. scenario selector enums - collected as candidates here and admitted by
+  // resolveSelectors once every reference in the tree is known. 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;
+  let masked = null, debugLines = null;
   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),
-      });
-    }
+    if (masked === null) { masked = maskLiteralsAndComments(text); debugLines = debugLineMask(text); }
+    selectors.push({
+      enumName, relPath, line: ln, snippet: lineText(ln),
+      nameIdx: em.index + em[0].lastIndexOf(enumName),
+      body: bodyRange(masked, em.index),
+      declInDebugBlock: !!debugLines[ln - 1],
+      cases: enumCases(text, em.index),
+    });
   }
 
   // 3a. reference-prefix variants: the mock repository that branches on them names
@@ -436,16 +697,38 @@ const TEXT_SIGNAL_RE = /[Mm]ock|Scenario|Outcome|:\/\//;
 // 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}` };
+// Every source file that mentions a candidate selector name. The rg path and
+// the walk path must return the same set, or the selector decision - and so the
+// coverage denominator - would depend on which scanner ran.
+function selectorReferenceFiles({ repoPath, names, useRg }) {
+  if (!names.length) return [];
+  const re = new RegExp(`\\b(?:${names.map(escapeRe).join("|")})\\b`);
+  const files = new Set();
+  let viaRg = false;
+  if (useRg) {
+    try {
+      for (const hit of rg(`\\b(?:${names.map(escapeRe).join("|")})\\b`, repoPath)) files.add(hit.file);
+      viaRg = true;
+    } catch { files.clear(); }
   }
-  const plat = platform || detectPlatform(repoPath);
-  const targets = [];
-  const seen = new Set();
-  const add = makeAdder(targets, seen);
+  if (!viaRg) {
+    walk(repoPath, (absFile) => {
+      const ext = "." + (basename(absFile).split(".").pop() || "");
+      if (SRC_EXT.has(ext)) files.add(absFile);
+    });
+  }
+  const out = [];
+  for (const absFile of [...files].sort()) {
+    let text = ""; try { text = readFileSync(absFile, "utf-8"); } catch { continue; }
+    if (!re.test(text)) continue;
+    out.push({ relPath: rel(repoPath, absFile), text });
+  }
+  return out;
+}
+
+// Source scan: every signal in the tree, plus the MockData fixtures. Returns
+// the strategy that ran and the selector decisions, adding targets via `add`.
+function scanSources({ repoPath, platform: plat, strategy, add }) {
   const useRg = strategy === "rg" || (strategy === "auto" && hasRg());
 
   const candidates = new Set();
@@ -455,11 +738,12 @@ export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], e
       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 selectors = [];
   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 });
+    collectFromText({ text, absFile, relPath, platform: plat, add, selectors });
   };
   let scanStrategy;
   if (candidates.size) {
@@ -476,6 +760,21 @@ export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], e
     });
   }
 
+  const selectorDecision = resolveSelectors(selectors, selectorReferenceFiles({
+    repoPath, names: [...new Set(selectors.map((c) => c.enumName))], useRg: scanStrategy === "rg",
+  }));
+  for (const { candidate: c, basis } of selectorDecision.accepted) {
+    for (const cs of c.cases) {
+      if (PASSTHROUGH_CASE.test(cs)) continue;
+      add("scenario-case", `${c.enumName}-${cs}`, {
+        label: `${titleize(c.enumName)} → ${titleize(cs)}`,
+        screen: titleize(c.enumName.replace(SCENARIO_SUFFIX, "")) || screenFor(c.relPath, c.enumName),
+        driver: { type: "scenario", enum: c.enumName, case: cs },
+        file: c.relPath, line: c.line, snippet: c.snippet, basis,
+      });
+    }
+  }
+
   // 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 = [];
@@ -496,6 +795,67 @@ export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], e
     });
   }
 
+  return {
+    scanStrategy,
+    acceptedSelectors: selectorDecision.accepted.map(({ candidate, ...rest }) => rest),
+    rejectedSelectors: selectorDecision.rejected,
+  };
+}
+
+export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], extraTargets = [], ignoreTargets = [], targets: catalogTargets = null, targetsFile = null, strategy = "auto", summary = false } = {}) {
+  // A catalog replaces the scan, so it is loaded (and refused) before anything
+  // else: an invalid catalog must fail the call, never degrade into a scan that
+  // quietly produces a different target set.
+  const useCatalog = catalogTargets != null || targetsFile != null;
+  const catalog = [];
+  if (targetsFile != null) catalog.push(...loadTargetCatalog(targetsFile).map((t) => ({ t, source: basename(String(targetsFile)) })));
+  if (catalogTargets != null) catalog.push(...validateTargets(catalogTargets, "targets").map((t) => ({ t, source: "targets[]" })));
+  if (useCatalog) validateTargets(catalog.map((c) => c.t), "catalog");
+
+  const repoFound = !!repoPath && existsSync(repoPath);
+  if (!repoFound && !useCatalog) {
+    return { platform: "unknown", targetCount: 0, targets: [], groups: [], byKind: {}, byCost: {},
+      plan: [], relaunchCount: 0, truncated: false, ignored: [], scanStrategy: "none",
+      acceptedSelectors: [], rejectedSelectors: [],
+      reason: `repoPath not found: ${repoPath}` };
+  }
+  const plat = platform || (repoFound ? detectPlatform(repoPath) : "unknown");
+  const targets = [];
+  const seen = new Set();
+  // The cap guards a source scan against a runaway match set. It never applies
+  // to what the caller declared (a catalog, config extras, extra launch args):
+  // those are an explicit target list, and dropping part of one silently would
+  // shrink the coverage denominator behind the caller's back.
+  let scanDropped = 0;
+  const scanAdd = makeAdder(targets, seen, { cap: MAX_TARGETS, onDrop: () => { scanDropped += 1; } });
+  const add = makeAdder(targets, seen);
+
+  // Every caller-declared target - catalog entry or config extra - enters here,
+  // so both get the same id dedup and cost derivation as scanned ones.
+  const addDeclared = (t, evidenceFile) => {
+    if (!t || !t.id) return;
+    const id = String(t.id);
+    if (seen.has(id)) return;
+    seen.add(id);
+    const driver = t.driver || { type: "manual" };
+    targets.push({
+      id, kind: t.kind || "config", label: t.label || titleize(id),
+      screen: t.screen || "Config", driver,
+      cost: t.cost || DRIVER_COST[driver.type] || "unknown",
+      evidence: t.evidence
+        ? { file: t.evidence.file || evidenceFile, line: t.evidence.line || 0, snippet: t.evidence.snippet || "", ...(t.evidence.basis ? { basis: t.evidence.basis } : {}) }
+        : { file: evidenceFile, line: 0, snippet: "" },
+    });
+  };
+
+  let scanStrategy = "catalog";
+  let acceptedSelectors = [], rejectedSelectors = [];
+  if (useCatalog) {
+    for (const { t, source } of catalog) addDeclared(t, source);
+  } else {
+    ({ scanStrategy, acceptedSelectors, rejectedSelectors } = scanSources({ repoPath, platform: plat, strategy, add: scanAdd }));
+  }
+
   // Caller-supplied additions: project config knows states no signal can reveal.
   for (const a of extraLaunchArgs) {
     add("launch-arg", a, {
@@ -504,17 +864,7 @@ export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], e
       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: "" },
-    });
-  }
+  for (const t of extraTargets) addDeclared(t, "design-check-config.json");
 
   // 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
@@ -561,24 +911,28 @@ export function inventoryScenarios({ repoPath, platform, extraLaunchArgs = [], e
     byKind,
     byCost,
     scanStrategy,
+    ...(useCatalog ? { catalog: { source: targetsFile != null ? String(targetsFile) : "targets[]", count: catalog.length } } : {}),
     // 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,
+    acceptedSelectors,
+    rejectedSelectors,
     // 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,
+    // A scan that found exactly the cap lost nothing, so only a refused target
+    // counts.
+    truncated: scanDropped > 0,
   };
 
   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.
+  // Summary mode. On a module with a hundred-odd targets the full payload
+  // exceeds a typical host tool-result cap, and targets[] is nearly all of it:
+  // 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

package/tools/design-check/visual-compare.js

@@ -378,6 +378,10 @@ export async function compareVisual(opts) {
     tolerancePt = null,
     verifyFontFamily = false,
     contentCardinality = true,
+    // The component this capture region belongs to, as componentFindingFields
+    // (component-walk.js) builds it. Stamped onto every finding that does not
+    // name its own, so the report can show the main component and its variants.
+    component = null,
     label = "screen",
   } = opts;
 
@@ -539,12 +543,16 @@ export async function compareVisual(opts) {
 
   const designWpx = figmaFrame && figmaFrame.w > 0 ? figmaFrame.w : null;
   const liveWpx = regionSize ? regionSize.w : (liveScreen && liveScreen.w > 0 ? liveScreen.w : null);
+  // The live PNG was cropped to the region, so its height in live units is the
+  // region's, not the screen's. Sampling a row at y/screenH would read a
+  // different row of the component.
+  const liveHpx = regionSize ? regionSize.h : (liveScreen ? liveScreen.h - cropUnits : null);
   for (const m of measured) {
     m.px = null;
     if (!responsive || !designWpx || !liveWpx) continue;
     if (!(m.d.w >= designWpx * 0.8 && m.l.w >= liveWpx * 0.8)) continue;
     const vf = visualRowInsets(figma, m.d.y + m.d.h / 2, designWpx, figmaFrame.h);
-    const vl = visualRowInsets(live, m.l.y + m.l.h / 2, liveWpx, liveScreen.h);
+    const vl = visualRowInsets(live, m.l.y + m.l.h / 2, liveWpx, liveHpx);
     if (vf && vl) m.px = { design: vf, live: vl };
   }
 
@@ -711,7 +719,7 @@ export async function compareVisual(opts) {
     for (let i = 0; i < measured.length; i++) {
       const m = measured[i];
       const dc = edgeContext(dAll[i], dAll, designW, figmaFrame ? figmaFrame.h : null);
-      const lc = edgeContext(lAll[i], lAll, liveW, liveScreen ? liveScreen.h : null);
+      const lc = edgeContext(lAll[i], lAll, liveW, liveHpx);
       for (const side of ["left", "right", "top", "bottom"]) {
         const dv = dc[side], lv = lc[side];
         if (!Number.isFinite(dv) || !Number.isFinite(lv)) continue;
@@ -928,6 +936,12 @@ export async function compareVisual(opts) {
     }
   }
 
+  if (component && typeof component === "object") {
+    for (let i = 0; i < findings.length; i++) {
+      if (!findings[i].component) findings[i] = { ...component, ...findings[i] };
+    }
+  }
+
   // Advisories (content-driven height, unmeasurable font family) must not decide
   // pass/fail - otherwise a fixture with one extra row fails a conformant screen.
   const deviations = findings.filter((f) => !f.advisory);
@@ -946,6 +960,7 @@ export async function compareVisual(opts) {
     deviationCount: deviations.length,
     advisoryCount: findings.length - deviations.length,
     findings,
+    ...(component ? { component } : {}),
     images: paths,
     compareSize: `${W}x${H}`,
     liveSize: `${live.width}x${live.height}`,