@mmerterden/multi-agent-toolkit-mcp 3.0.0

package/tools/design-check/index.js

@@ -0,0 +1,219 @@
+/**
+ * design-check tool family - mock-mode vs Figma design audit primitives.
+ *
+ * Generic and platform-agnostic. The heavy orchestration (Figma fetch, variant
+ * matching, driving the app screen-to-screen, report assembly) lives in the
+ * multi-agent pipeline; this module exposes the mechanical steps:
+ *
+ *   design_mock_detect    - can this project be run in a mock mode?
+ *   design_scenario_inventory - every state driver the mock build exposes (audit target set)
+ *   design_mock_launch    - launch the app in mock mode (UserDefaults launch arg / intent extra)
+ *   design_ui_geometry    - flat element bounding boxes of the current screen
+ *   design_visual_compare - normalize + pixel/geometry/color/type diff vs a Figma render
+ *   design_report         - render HTML (+ optional PDF) from a report object
+ */
+
+import { join } from "path";
+import { existsSync, mkdirSync } from "fs";
+
+import { detectMock } from "./mock-detect.js";
+import { inventoryScenarios } from "./scenario-inventory.js";
+import { flattenIosAxTree, flattenAndroidUiXml, flattenIdbDescribeAll } from "./geometry.js";
+import { compareVisual } from "./visual-compare.js";
+import { writeReport } from "./report.js";
+
+// Single-quote for POSIX sh; the swift dumper path is interpolated into a shell
+// command via ctx.run. Kept local so this module stays self-contained.
+function shq(value) {
+  return `'${String(value ?? "").replace(/'/g, "'\\''")}'`;
+}
+
+export const DESIGN_TOOLS = [
+  {
+    name: "design_mock_detect",
+    description: "Detect whether a mobile project (iOS/Android) can be launched in a mock/stub mode for deterministic screen capture. Returns { supported: true|false|'debug-only', mechanism, activation, variantsHint[], evidence[] }. Signal-based and generic: naming conventions (*MockService), #if DEBUG DI branches, MockData fixtures, and well-known runtime switch keys (extendable via extra_keys). Use at the repo/module pick step to gate the audit.",
+    inputSchema: { type: "object", properties: {
+      repo_path: { type: "string", description: "Absolute path to the repo or module to scan" },
+      platform: { type: "string", enum: ["ios", "android"], description: "Optional; auto-detected if omitted" },
+      extra_keys: { type: "array", items: { type: "string" }, description: "Project-specific mock switch keys to also look for" },
+    }, required: ["repo_path"] },
+  },
+  {
+    name: "design_scenario_inventory",
+    description: "Enumerate every state driver a mock-mode build exposes, so a design audit has a countable target set instead of walking the UI until it feels done. Returns { targets:[{id,kind,label,screen,driver,cost,evidence}], plan[], relaunchCount, groups[], byKind, byCost, targetCount, ignored[], truncated }. Kinds: launch-arg (relaunch flags / boolean intent extras), scenario-case (cases of *Scenario / *Outcome / *MockCase enums), code-scenario (short uppercase codes typed at an entry field, read only from debug/mock code), fixture (MockData JSON), deep-link (custom-scheme URLs). Each target carries a cost ('relaunch' vs 'in-app') and `plan` batches them so ONE relaunch serves every in-app target on that screen - relaunchCount, not targetCount, is the real cost of full coverage. Signal-based and generic; every target has file+line evidence. Run right after design_mock_detect; feed targets + truncated into the design_report coverage gate.",
+    inputSchema: { type: "object", properties: {
+      repo_path: { type: "string", description: "Absolute path to the repo or module to scan" },
+      platform: { type: "string", enum: ["ios", "android"], description: "Optional; auto-detected if omitted" },
+      extra_launch_args: { type: "array", items: { type: "string" }, description: "Project-specific launch args no signal reveals" },
+      extra_targets: { type: "array", items: { type: "object" }, description: "Config-declared targets [{id,kind,label,screen,driver}]" },
+      ignore_targets: { type: "array", items: { type: "string" }, description: "Target ids to drop entirely (dead drivers, states retired in code). Returned in `ignored` - unlike a skip these never reach the coverage gate, so prefer a skip with a reason." },
+      summary: { type: "boolean", description: "Return counts, groups and plan without the per-target list. The full payload measured 71k characters for a 109-target module and exceeded the tool-result cap on every run; plan[].targetIds and groups[].ids still carry every id, so a run can be driven from the summary and fetch labels + file/line evidence later with summary:false." },
+    }, required: ["repo_path"] },
+  },
+  {
+    name: "design_mock_launch",
+    description: "Launch an already-installed app in mock mode using the activation returned by design_mock_detect. iOS: sets a UserDefaults key via simctl launch argument (Debug build required). Android: passes an intent boolean extra. For 'debug-only' projects there is no runtime switch - just launch the Debug build.",
+    inputSchema: { type: "object", properties: {
+      platform: { type: "string", enum: ["ios", "android"] },
+      bundle_id: { type: "string", description: "iOS bundle id" },
+      package_name: { type: "string", description: "Android package name" },
+      activity: { type: "string", description: "Android launcher activity (optional)" },
+      launch_arg: { type: "string", description: "iOS launch argument string e.g. '-debugMockMode YES'" },
+      intent_extra: { type: "string", description: "Android intent extra e.g. '--ez mockEnabled true'" },
+      device_id: { type: "string" },
+    }, required: ["platform"] },
+  },
+  {
+    name: "design_ui_geometry",
+    description: "Dump the current on-screen element bounding boxes as a flat list ({role,label,text,identifier,x,y,w,h}) plus the screen size, for measuring pixel-level spacing/position deltas against a Figma spec. iOS via the AX tree (points), Android via uiautomator (pixels). Use when a live screen has to be measured against a design. CAVEAT: these are accessibility boxes - glyph runs and hit areas - not layout containers, so a text element reports the ink extent and not the box it sits in. A 247pt design text container compared against its 78pt glyph box produces phantom findings; measure insets and gaps from the pixels (design_visual_compare) rather than differencing these boxes against design frames.",
+    inputSchema: { type: "object", properties: {
+      platform: { type: "string", enum: ["ios", "android"] },
+      device_id: { type: "string" },
+      max_depth: { type: "number", description: "iOS AX tree depth (default 12)" },
+    }, required: ["platform"] },
+  },
+  {
+    name: "design_visual_compare",
+    description: "Compare a Figma render PNG against a live device screenshot WITHOUT failing on size mismatch. RESPONSIVE BY DEFAULT: because the device and the Figma frame are usually different widths (e.g. 402pt vs 375pt), raw width/height deltas are meaningless - so it measures what a designer actually specs, in POINTS: per-element edge insets (left/right), the GAPS between consecutive elements (text <-> divider spacing), vertical placement, font size/family and text colour (sampled from the text ink, not the box average). Height is still reported but flagged advisory, since a content-hugging container changes height whenever the fixture differs; advisories never decide pass/fail. Pass responsive:false for the legacy absolute-delta behaviour. Writes figma/live/diff/overlay/side-by-side PNGs. Returns findings + image paths. For a BOTTOM SHEET / modal / partial overlay pass live_region (the sheet's bounds from design_ui_geometry): the Figma frame covers only the sheet while the capture is the whole screen, and stretching one onto the other misplaces every element inside it. Add expected_region to have the sheet's own edge insets reported as findings - a design showing a sheet flush to the edges is not satisfied by one floating inset from them.",
+    inputSchema: { type: "object", properties: {
+      figma_png: { type: "string", description: "Path to the Figma render PNG (design truth)" },
+      live_png: { type: "string", description: "Path to the live device screenshot" },
+      out_dir: { type: "string", description: "Directory to write comparison images into" },
+      label: { type: "string", description: "Screen/variant label (used in filenames)" },
+      crop_top_live: { type: "number", description: "Pixels to crop from top of live capture (status bar). Ignored when live_region is given, since the region crop already excludes chrome." },
+      crop_top_figma: { type: "number", description: "Pixels to crop from top of Figma render" },
+      live_region: { type: "object", description: "{x,y,w,h} of the region to compare, in live_screen units (iOS points / Android px) - e.g. a bottom sheet's container bounds from design_ui_geometry. Live coordinates are rebased onto this box." },
+      expected_region: { type: "object", description: "{x,y,w,h} where the design says that region should sit, same units. Enables 'inset' findings for each edge (left/right/top/bottom) beyond tolerance_px." },
+      figma_spec: { type: "array", items: { type: "object" }, description: "Flat Figma elements (from flattenFigmaNode): {x,y,w,h,label,text,color,fontSize,...}" },
+      live_geometry: { type: "array", items: { type: "object" }, description: "Flat live elements from design_ui_geometry" },
+      pairs: { type: "array", items: { type: "object" }, description: "Optional explicit [{figma, live}] matches; auto-matched by text/label if omitted" },
+      figma_frame: { type: "object", description: "{w,h} of the Figma frame the spec coords are in" },
+      live_screen: { type: "object", description: "{w,h} of the live screen the geometry coords are in" },
+      tolerance_px: { type: "number", description: "Ignore deltas ≤ this many px (default 2)" },
+      tolerance_pt: { type: "number", description: "Ignore inset/gap/position deltas ≤ this many POINTS (defaults to tolerance_px)" },
+      design_copy: { type: "array", items: { type: "string" }, description: "The design's source-of-truth UX-writing strings for this screen (from the Figma node's UX-writing annotations, in the run's language). Compared against the live text: an exact match verifies the string, a near match is reported as a copy defect (a truncated or stale translation), and a string with no counterpart is advisory because the capture may not show its state." },
+      edges: { type: "boolean", description: "Default true. For every element report its four LOCAL distances (to the nearest overlapping sibling on each side, else the frame edge) - the same measurement an on-device layout inspector shows. Computed identically on the design and live box lists, so a row displaced by a taller fixture above it stays silent while a genuinely changed padding surfaces on the exact edge, naming what it is measured against." },
+      relations: { type: "boolean", description: "Default true. Emit content-independent relational checks - centred-in-frame, left/right margin symmetry, shared centre lines (is the close button aligned with the title), and icon/control sizing. These are what actually answer 'is it built 1:1', because absolute Y moves with the mock content above it." },
+      responsive: { type: "boolean", description: "Default true. Measure edge insets + inter-element gaps in points instead of raw width/height in the stretched compare space. Requires figma_frame + live_screen. Turn off only to get legacy absolute deltas." },
+      verify_font_family: { type: "boolean", description: "Emit an advisory per text element naming the design's font family (not readable from the device, so it is a code-review item, never a measured delta). Default false." },
+      content_cardinality: { type: "boolean", description: "Demote the geometry findings a fixture-count difference explains (5 design rows vs 3 live rows shifts every container height and everything below it). Default true. Demoted findings are NOT removed - they become advisory with a shared root cause and are reported in `contentCardinality.demoted`. Copy, colour, typography and tap-target findings, and anything above the first differing group, are never demoted. Pass false to see the raw findings." },
+      color_tolerance: { type: "number", description: "Ignore color ΔE ≤ this (default 3)" },
+      perceptual_precision: { type: "number", description: "pixelmatch threshold 0..1 (default 0.1)" },
+      max_diff_pct: { type: "number", description: "Perceptual diff pass ceiling (default 1.0)" },
+    }, required: ["figma_png", "live_png", "out_dir"] },
+  },
+  {
+    name: "design_report",
+    description: "Render a design-audit report object into a self-contained HTML file (base64 images, CSS-positioned annotations over the live capture) and optionally PDF. Enforces a COVERAGE GATE: pass report.coverage = { targets, covered, skipped:[{id,group,reason}], floor? } and every target must be audited or skipped WITH a reason - otherwise the returned object carries coverage.gate='fail' + coverageError and the report renders a red gate banner. Human-facing wording comes from report.lang ('en' default, 'tr' built in) and per-key report.labels overrides. Returns written file paths + the coverage verdict. Confluence upload is handled by the caller.",
+    inputSchema: { type: "object", properties: {
+      report: { type: "object", description: "{ project, module, platform, figmaUrl, timestamp, lang, labels, coverage:{targets,covered,skipped:[{id,group,reason}],floor}, variants:[{name, figmaNodeId, perceptualPct, passed, compareSize, images:{figma,live,diff,overlay,sideBySide}, findings:[...], fixPrompt, componentRefs:[{name,image}] }] }" },
+      out_dir: { type: "string", description: "Directory to write report into" },
+      formats: { type: "array", items: { type: "string", enum: ["html", "pdf", "confluence"] }, description: "Default ['html']" },
+    }, required: ["report", "out_dir"] },
+  },
+];
+
+function ensureDir(d) { if (d && !existsSync(d)) mkdirSync(d, { recursive: true }); return d; }
+
+// Guard shell interpolation: bundle ids / package names / activities are strict
+// identifiers; launch args / intent extras may not contain shell metacharacters.
+function safeId(x, label) {
+  if (!x) return x;
+  if (!/^[A-Za-z0-9._/-]+$/.test(x)) throw new Error(`Invalid ${label}: ${x}`);
+  return x;
+}
+function safeArg(x, label) {
+  if (!x) return "";
+  if (/[;&|`$(){}<>\n\r\\"']/.test(x)) throw new Error(`Unsafe ${label} (shell metacharacters): ${x}`);
+  return x;
+}
+
+// ctx: { run, iosDevice, adbFlag, dumperScript }
+export async function handleDesign(name, args, ctx) {
+  switch (name) {
+    case "design_mock_detect":
+      return JSON.stringify(detectMock({ repoPath: args.repo_path, platform: args.platform, extraKeys: args.extra_keys || [] }), null, 2);
+
+    case "design_scenario_inventory":
+      return JSON.stringify(inventoryScenarios({
+        repoPath: args.repo_path, platform: args.platform,
+        extraLaunchArgs: args.extra_launch_args || [], extraTargets: args.extra_targets || [],
+        ignoreTargets: args.ignore_targets || [], summary: args.summary === true,
+      }), null, 2);
+
+    case "design_mock_launch": {
+      if (args.platform === "ios") {
+        const d = ctx.iosDevice(args.device_id);
+        if (!args.bundle_id) return "ERROR: bundle_id required for iOS";
+        const bid = safeId(args.bundle_id, "bundle_id");
+        const arg = args.launch_arg ? ` ${safeArg(args.launch_arg, "launch_arg")}` : "";
+        return ctx.run(`xcrun simctl launch ${d} ${bid}${arg}`) || `Launched ${bid} (mock)`;
+      }
+      const df = ctx.adbFlag(args.device_id);
+      if (!args.package_name) return "ERROR: package_name required for Android";
+      const pkg = safeId(args.package_name, "package_name");
+      const comp = args.activity ? `${pkg}/${safeId(args.activity, "activity")}` : `$(adb ${df} shell cmd package resolve-activity --brief ${pkg} | tail -1)`;
+      const extra = args.intent_extra ? ` ${safeArg(args.intent_extra, "intent_extra")}` : "";
+      return ctx.run(`adb ${df} shell am start -n ${comp}${extra}`) || `Launched ${pkg} (mock)`;
+    }
+
+    case "design_ui_geometry": {
+      if (args.platform === "ios") {
+        const d = ctx.iosDevice(args.device_id);
+        // Prefer idb describe-all (headless, no Simulator GUI). Fall back to the AX dumper.
+        if (ctx.hasIdb) {
+          const raw = ctx.idb(`ui describe-all --udid ${d} --json`, { timeout: 20000 });
+          const elements = flattenIdbDescribeAll(raw);
+          if (elements.length) {
+            const app = elements.find((e) => (e.role || "").includes("Application"));
+            let sw = 0, sh = 0;
+            try { const arr = JSON.parse(raw.trim().startsWith("[") ? raw : "[" + raw.trim().split("\n").join(",") + "]"); const a = arr.find((x) => (x.type === "Application")); if (a && a.frame) { sw = Math.round(a.frame.width); sh = Math.round(a.frame.height); } } catch {}
+            return JSON.stringify({ platform: "ios", unit: "points", source: "idb", screen: { w: sw, h: sh }, count: elements.length, elements }, null, 2);
+          }
+        }
+        const depth = Number(args.max_depth) || 12;
+        const raw = ctx.run(`swift ${shq(ctx.dumperScript)} ${depth}`, { timeout: 15000 });
+        let tree; try { tree = JSON.parse(raw); } catch { return `ERROR: idb unavailable and AX dumper failed: ${String(raw).slice(0, 200)}`; }
+        const elements = flattenIosAxTree(tree);
+        const rf = tree.frame || {};
+        return JSON.stringify({ platform: "ios", unit: "points", source: "ax-dumper", screen: { w: Math.round(rf.w || 0), h: Math.round(rf.h || 0) }, count: elements.length, elements }, null, 2);
+      }
+      const df = ctx.adbFlag(args.device_id);
+      ctx.run(`adb ${df} shell uiautomator dump /sdcard/_design_ui.xml`);
+      const xml = ctx.run(`adb ${df} shell cat /sdcard/_design_ui.xml`);
+      const elements = flattenAndroidUiXml(xml);
+      const sizeRaw = ctx.run(`adb ${df} shell wm size`);
+      const sm = /(\d+)x(\d+)/.exec(sizeRaw || "");
+      return JSON.stringify({ platform: "android", unit: "pixels", screen: sm ? { w: +sm[1], h: +sm[2] } : null, count: elements.length, elements }, null, 2);
+    }
+
+    case "design_visual_compare": {
+      ensureDir(args.out_dir);
+      const res = await compareVisual({
+        figmaPng: args.figma_png, livePng: args.live_png, outDir: args.out_dir, label: args.label,
+        cropTopLive: args.crop_top_live || 0, cropTopFigma: args.crop_top_figma || 0,
+        figmaSpec: args.figma_spec || [], liveGeometry: args.live_geometry || [], pairs: args.pairs || null,
+        figmaFrame: args.figma_frame || null, liveScreen: args.live_screen || null,
+        liveRegion: args.live_region || null, expectedRegion: args.expected_region || null,
+        tolerancePx: args.tolerance_px, colorTolerance: args.color_tolerance,
+        tolerancePt: args.tolerance_pt != null ? args.tolerance_pt : null,
+        responsive: args.responsive !== false,
+        contentCardinality: args.content_cardinality !== false,
+        relations: args.relations !== false,
+        edges: args.edges !== false,
+        designCopy: args.design_copy || null,
+        verifyFontFamily: args.verify_font_family === true,
+        perceptualPrecision: args.perceptual_precision, maxDiffPct: args.max_diff_pct,
+      });
+      return JSON.stringify(res, null, 2);
+    }
+
+    case "design_report": {
+      ensureDir(args.out_dir);
+      const out = await writeReport({ report: args.report, outDir: args.out_dir, formats: args.formats || ["html"] });
+      return JSON.stringify(out, null, 2);
+    }
+
+    default: return null;
+  }
+}

package/tools/design-check/mock-detect.js

@@ -0,0 +1,213 @@
+/**
+ * design_mock_detect - decide whether a mobile project can be launched in a
+ * mock/stub mode so its screens can be captured deterministically.
+ *
+ * Fully generic: no project, owner, or repo name is hardcoded. Detection is
+ * signal-based (naming conventions + DI patterns + well-known switch NAMES),
+ * and the caller may inject project-specific switch keys via opts.extraKeys.
+ * Scanning uses ripgrep when available (fast, .gitignore-aware) and falls back
+ * to a bounded node walk otherwise.
+ *
+ * returns:
+ *   {
+ *     supported: true | false | "debug-only",
+ *     platform:  "ios" | "android" | "unknown",
+ *     mechanism: "userdefaults-launcharg" | "interceptor" | "debug-di" | null,
+ *     activation: { kind, key?, value?, launchArg?/intentExtra?, buildConfig },
+ *     variantsHint: [ ... ],
+ *     evidence: [ { signal, file, line, snippet } ],
+ *     reason: <human string when unsupported>
+ *   }
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { basename } from "path";
+
+import { hasRg, rg, walk, rel, detectPlatform, SRC_EXT } from "./scan.js";
+
+const KNOWN_MOCK_KEYS = [
+  "debugMockMode", "mockServiceIsActive", "mock-service-is-active",
+  "traceweave.mock.enabled", "isMockEnabled", "isMockMode", "useMockData",
+  "useMockServices", "MOCK_MODE", "UITEST_MOCK", "mockEnabled",
+];
+
+function hasLaunchableAndroidApp(repoPath) {
+  if (hasRg()) {
+    try {
+      const app = rg("com\\.android\\.application|applicationId\\s+[\"']", repoPath,
+        { globs: ["-g", "*.gradle", "-g", "*.gradle.kts"] });
+      if (app.length) return true;
+      const launcher = rg("android\\.intent\\.category\\.LAUNCHER", repoPath, { globs: ["-g", "AndroidManifest.xml"] });
+      return launcher.length > 0;
+    } catch { /* fall through */ }
+  }
+  let launchable = false;
+  walk(repoPath, (f) => {
+    const b = basename(f);
+    if (b === "build.gradle" || b === "build.gradle.kts" || b === "AndroidManifest.xml") {
+      let t = ""; try { t = readFileSync(f, "utf-8"); } catch { return; }
+      if (/com\.android\.application|applicationId\s+["']|android\.intent\.category\.LAUNCHER/.test(t)) launchable = true;
+    }
+  });
+  return launchable;
+}
+
+// Core signal scan. Populates `state` with runtimeKey/interceptor/debugDI/etc.
+function scanWithRg(repoPath, keys, state) {
+  const keyAlt = keys.map((k) => k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+  // 1. known/injected runtime switch keys
+  for (const hit of rg(`["'](?:${keyAlt})["']`, repoPath)) {
+    const km = /["']([^"']+)["']/.exec(hit.text);
+    const k = km ? km[1] : "?";
+    if (/traceweave\.mock|URLProtocol|interceptor/i.test(hit.text) || k.includes("traceweave")) state.interceptor = true;
+    state.runtimeKey = state.runtimeKey || k;
+    state.push(`runtime-switch:${k}`, hit, repoPath);
+  }
+  // 2. generic AppStorage/UserDefaults "mock" bool key
+  if (!state.runtimeKey) {
+    for (const hit of rg(`(?:@AppStorage|forKey|defaults\\.\\w+)\\s*\\(?\\s*["'][A-Za-z0-9_.\\-]*[Mm]ock[A-Za-z0-9_.\\-]*["']`, repoPath)) {
+      const km = /["']([A-Za-z0-9_.\-]*[Mm]ock[A-Za-z0-9_.\-]*)["']/.exec(hit.text);
+      if (km) { state.runtimeKey = km[1]; state.push(`runtime-switch:${km[1]}`, hit, repoPath); break; }
+    }
+  }
+  // 2b. launch-argument mock (ProcessInfo.processInfo.arguments.contains) + arg constants
+  if (!state.runtimeKey) {
+    const la = rg("ProcessInfo\\.processInfo\\.arguments\\.contains", repoPath);
+    if (la.length) {
+      const argHits = rg("static let \\w+\\s*=\\s*\"(-[A-Za-z]*[Mm]ock[A-Za-z0-9]*)\"", repoPath);
+      const am = argHits.length ? /"(-[A-Za-z0-9]+)"/.exec(argHits[0].text) : null;
+      state.runtimeKey = am ? am[1] : "-Mock";
+      state.launchArg = true;
+      state.push("runtime-launcharg", la[0], repoPath);
+    }
+  }
+  // 2c. constant-defined UserDefaults mock key (string literal with 'mock', not inline @AppStorage)
+  if (!state.runtimeKey) {
+    const ck = rg("static let \\w+\\s*=\\s*\"[A-Za-z0-9_.\\-]*[Mm]ock[A-Za-z0-9_.\\-]*\"", repoPath);
+    if (ck.length) {
+      const cm = /"([A-Za-z0-9_.\-]*[Mm]ock[A-Za-z0-9_.\-]*)"/.exec(ck[0].text);
+      if (cm) { state.runtimeKey = cm[1]; state.push(`runtime-switch:${cm[1]}`, ck[0], repoPath); }
+    }
+  }
+  // 3. mock type declarations
+  const typeHits = rg(`\\b(?:class|struct|final class|object|enum)\\s+(?:Mock[A-Za-z0-9]+|[A-Za-z0-9]+Mock(?:Service|NetworkService|Repository|Provider|DataSource))\\b`, repoPath);
+  state.mockTypeCount = typeHits.length;
+  typeHits.slice(0, 8).forEach((h) => {
+    const tm = /\s(Mock[A-Za-z0-9]+|[A-Za-z0-9]+Mock(?:Service|NetworkService|Repository|Provider|DataSource))\b/.exec(h.text);
+    state.push(`mock-type:${tm ? tm[1] : "Mock"}`, h, repoPath);
+  });
+  // 4. #if DEBUG return Mock (compile-time DI)
+  const diHits = rg(`#if\\s+DEBUG.{0,400}?return\\s+Mock[A-Za-z0-9]+`, repoPath, { multiline: true });
+  if (diHits.length) { state.debugDI = true; state.push("debug-di", diHits[0], repoPath); }
+  // 5. MockData fixtures → variant hints
+  for (const f of rg("**/MockData/**/*.json", repoPath, { files: true, globs: [] })) {
+    const b = basename(f.file);
+    const vm = /([A-Za-z0-9]+)_mock\.json$|mock_([A-Za-z0-9]+)\.json$/i.exec(b);
+    state.variants.add((vm ? (vm[1] || vm[2]) : b.replace(/\.json$/i, "")).toLowerCase());
+  }
+}
+
+function scanWithWalk(repoPath, keys, state) {
+  const keyRegexes = keys.map((k) => ({ k, re: new RegExp(`["']${k.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`) }));
+  const genericRe = /(?:@AppStorage|forKey|defaults\.\w+)\s*\(?\s*["']([A-Za-z0-9_.\-]*[Mm]ock[A-Za-z0-9_.\-]*)["']/;
+  const typeRe = /\b(?:class|struct|final class|object|enum)\s+(Mock[A-Za-z0-9]+|[A-Za-z0-9]+Mock(?:Service|NetworkService|Repository|Provider|DataSource))\b/;
+  const diRe = /#if\s+DEBUG[\s\S]{0,400}?\breturn\s+Mock[A-Za-z0-9]+/;
+  const varRe = /([A-Za-z0-9]+)_mock\.json$|mock_([A-Za-z0-9]+)\.json$/i;
+  const laUseRe = /ProcessInfo\.processInfo\.arguments\.contains/;
+  const laConstRe = /static let \w+\s*=\s*"(-[A-Za-z]*[Mm]ock[A-Za-z0-9]*)"/;
+  const constKeyRe = /static let \w+\s*=\s*"([A-Za-z0-9_.\-]*[Mm]ock[A-Za-z0-9_.\-]*)"/;
+  walk(repoPath, (file) => {
+    const b = basename(file);
+    const ext = "." + (b.split(".").pop() || "");
+    if (ext === ".json" && /\/MockData\//.test(file)) {
+      const m = varRe.exec(b);
+      state.variants.add((m ? (m[1] || m[2]) : b.replace(/\.json$/i, "")).toLowerCase());
+      return;
+    }
+    if (!SRC_EXT.has(ext)) return;
+    let txt = ""; try { txt = readFileSync(file, "utf-8"); } catch { return; }
+    if (!/[Mm]ock/.test(txt)) return;
+    const mkHit = (idx) => { const line = txt.slice(0, idx).split("\n").length; return { file, line, text: (txt.split("\n")[line - 1] || "").trim() }; };
+    for (const { k, re } of keyRegexes) {
+      const m = re.exec(txt);
+      if (m) { if (/traceweave\.mock|URLProtocol|interceptor/i.test(txt) || k.includes("traceweave")) state.interceptor = true; state.runtimeKey = state.runtimeKey || k; state.push(`runtime-switch:${k}`, mkHit(m.index), repoPath); }
+    }
+    if (!state.runtimeKey) { const gm = genericRe.exec(txt); if (gm) { state.runtimeKey = gm[1]; state.push(`runtime-switch:${gm[1]}`, mkHit(gm.index), repoPath); } }
+    // launch-argument mock (ProcessInfo.arguments.contains) + arg constant (may be in different files)
+    if (laUseRe.test(txt)) state.launchArgUsed = true;
+    if (!state.launchArgConst) { const lm = laConstRe.exec(txt); if (lm) { state.launchArgConst = lm[1]; state.launchArgHit = mkHit(lm.index); } }
+    if (!state.constKeyCand) { const cm = constKeyRe.exec(txt); if (cm && !cm[1].startsWith("-")) { state.constKeyCand = cm[1]; state.constKeyHit = mkHit(cm.index); } }
+    const dm = diRe.exec(txt); if (dm) { state.debugDI = true; state.push("debug-di", mkHit(dm.index), repoPath); }
+    const tm = typeRe.exec(txt); if (tm) { state.mockTypeCount++; if (state.mockTypeCount <= 8) state.push(`mock-type:${tm[1]}`, mkHit(tm.index), repoPath); }
+  });
+}
+
+export function detectMock({ repoPath, platform, extraKeys = [] } = {}) {
+  if (!repoPath || !existsSync(repoPath)) {
+    return { supported: false, platform: "unknown", mechanism: null, reason: `repoPath not found: ${repoPath}`, evidence: [] };
+  }
+  const plat = platform || detectPlatform(repoPath);
+  const keys = [...new Set([...KNOWN_MOCK_KEYS, ...extraKeys])];
+
+  const evidence = [];
+  const state = {
+    runtimeKey: null, launchArg: false, interceptor: false, debugDI: false, mockTypeCount: 0,
+    variants: new Set(),
+    push(signal, hit, rp) { evidence.push({ signal, file: rel(rp, hit.file), line: hit.line, snippet: (hit.text || "").slice(0, 160) }); },
+  };
+
+  let scanned = false;
+  if (hasRg()) { try { scanWithRg(repoPath, keys, state); scanned = true; } catch { /* fall back */ } }
+  if (!scanned) scanWithWalk(repoPath, keys, state);
+
+  // Resolve launch-argument / constant-defined mock switches (either scan sets the flags).
+  if (!state.runtimeKey) {
+    if (state.launchArgUsed && state.launchArgConst) {
+      state.runtimeKey = state.launchArgConst; state.launchArg = true;
+      if (state.launchArgHit) state.push(`runtime-launcharg:${state.launchArgConst}`, state.launchArgHit, repoPath);
+    } else if (state.constKeyCand) {
+      state.runtimeKey = state.constKeyCand;
+      if (state.constKeyHit) state.push(`runtime-switch:${state.constKeyCand}`, state.constKeyHit, repoPath);
+    }
+  }
+
+  const variantsHint = [...state.variants].slice(0, 40);
+
+  // If platform is still unknown, infer it from the evidence file extensions so
+  // the activation (iOS launch arg vs Android intent extra) is never mis-picked.
+  let effPlat = plat;
+  if (effPlat === "unknown") {
+    const exts = evidence.map((e) => (e.file || "").split(".").pop());
+    if (exts.includes("swift")) effPlat = "ios";
+    else if (exts.includes("kt") || exts.includes("kts")) effPlat = "android";
+  }
+
+  if (effPlat === "android" && !hasLaunchableAndroidApp(repoPath)) {
+    return { supported: false, platform: effPlat, mechanism: null,
+      reason: "No launchable Android application module found (library set only) - nothing to run in mock mode.",
+      variantsHint, evidence };
+  }
+
+  if (state.runtimeKey) {
+    const isFlag = state.launchArg || state.runtimeKey.startsWith("-");
+    const kind = state.interceptor ? "interceptor" : (isFlag ? "launch-argument" : "userdefaults-launcharg");
+    return {
+      supported: true, platform: effPlat, mechanism: kind,
+      activation: effPlat === "android"
+        ? { kind, key: state.runtimeKey, value: "true", intentExtra: `--ez ${state.runtimeKey.replace(/^-/, "")} true`, buildConfig: "debug" }
+        : { kind, key: state.runtimeKey, value: isFlag ? "(flag)" : "YES", launchArg: isFlag ? state.runtimeKey : `-${state.runtimeKey} YES`, buildConfig: "Debug" },
+      variantsHint, evidence,
+    };
+  }
+  if (state.debugDI || state.mockTypeCount > 0) {
+    return {
+      supported: "debug-only", platform: effPlat, mechanism: "debug-di",
+      activation: { kind: "build-config", buildConfig: effPlat === "android" ? "debug" : "Debug" },
+      note: "Mocks are compiled into the Debug build via #if DEBUG DI. No runtime switch → variants cannot be toggled at launch; only the default Debug state is comparable.",
+      variantsHint, evidence,
+    };
+  }
+  return { supported: false, platform: effPlat, mechanism: null,
+    reason: "No mock switch, mock service naming, or MockData fixtures detected - project has no mock support this tool can drive.",
+    variantsHint, evidence };
+}