@ia-qa/self-healing 1.7.13 → 1.7.15

package/README.md

@@ -209,6 +209,33 @@ extensions and the code paths are exercised, but the test suite's rewrite cases
 against `.js`/`.ts` files. Treat non-JS rewriting as working-but-less-travelled: run
 `fix --dry-run` first, which you should be doing anyway.
 
+### One more axis: how much of the page is under contract at all
+
+`map` records the state a page **loads in**. Everything behind a dropdown, a tab, an accordion
+or a modal is in no contract — so when it drifts, nothing says so. It is a coverage hole and
+never a false alarm, which is what makes it survive: the gate stays green over a surface it
+never looked at.
+
+```bash
+ia-qa-heal map --deep     # open them, and contract what appears
+```
+
+Measured on ia-qa.com: one page 105 → 133 elements, another 126 → 264. Across eight unrelated
+sites (MDN, Bootstrap, Material UI, GOV.UK, Wikipedia, Docusaurus…), seven gained elements —
+the gain is largest on component-framework apps and near zero on content sites, so it is worth
+saying which one you have before reaching for it.
+
+- **It cannot mutate your app.** Every non-GET request is aborted for the walk, and controls
+  named like actions (*log out*, *delete*, *pay*…) are never clicked — a logout handler that
+  only clears local storage sends no request for the network guard to catch.
+- **What it reaches but cannot contract is reported**, not hidden (`↩ N left out`): a selector
+  must name exactly one element, and a positional one captured inside a menu can collide with
+  the page behind it.
+- **A deep baseline is only comparable to a deep capture.** Mixing the two reports everything
+  behind a menu as `lost`; `diff` and the MCP both warn before the verdict.
+- **~1 minute per page** against seconds for a plain `map`. It is for building a baseline, not
+  for a per-commit gate.
+
 ## The verdict
 
 ```
@@ -341,6 +368,18 @@ and they never fail your tests. Each worker writes its own shard to
 page contracts `map` produces — byte-compatible, named from `config.pages` so they pair with
 your baseline.
 
+**One suite, several applications.** A page name is a filename, so two URLs sharing one name
+claim to be the same page — and five products each with a `/login` are not. A URL on a host
+other than your `baseUrl` is therefore named `<host>--<path>`
+(`partner.example.com--login`), never `login`. Single-host suites are unaffected: the prefix
+only appears where two applications would otherwise have overwritten each other's contract, and
+`www.`/apex and `http`/`https` count as the same host. To choose the name yourself, declare the
+page with its **absolute** URL:
+
+```json
+{ "name": "partner-login", "url": "https://partner.example.com/login" }
+```
+
 **Any other framework or language.** The shard format *is* the interface; the helpers above are
 sugar over it. Run the extractor in the page (`extract.js` in this package, also a copy-paste
 DevTools snippet on ia-qa.com) and drop a JSON file into `.ia-qa/mapping/.capture/`:

package/SPEC-selector-resolution.md

@@ -297,6 +297,24 @@ Requirements when it is built:
    silently compared against one captured by `map`. Same reasoning as `run`'s
    source-mismatch warning.
 
+### 7.1 `map --deep` reaches states, and resolution deliberately does not follow it
+
+`--deep` (see CLAUDE.md) opens menus, tabs and dialogs and contracts what they reveal. It would
+be easy to assume selector resolution comes along — it does not, and the restraint is deliberate.
+`resolvePageSelectors` runs against the **loaded** state, before exploration starts, because
+exploration ends with the page in whatever state its walk finished in. Resolving after it would
+probe the suite's selectors against an open modal and report a *working* binding as broken —
+the one error this package treats as worse than the drift it heals.
+
+So a deep contract holds elements with **no binding row**. That is `unresolved`-shaped, and §2.2
+already governs it: silence is never evidence of absence. What it costs is real and worth stating
+— the highest-value finding here, a selector that now reaches a *different* element, cannot be
+made about anything behind a menu.
+
+Closing that gap is phase 2's job, not a patch to `map`: the states `--deep` reaches are the same
+states the shards see for free, and resolution belongs where the page is already standing in one.
+Do not "fix" it by moving `resolvePageSelectors` after `explorePage`.
+
 ---
 
 ## 8. What this feature is not

package/TUTORIAL.md

@@ -11,7 +11,7 @@
 2. [The 30-second mental model](#2-the-30-second-mental-model)
 3. [Before you start](#3-before-you-start)
 4. [Path A — I use an AI agent (easiest)](#4-path-a--i-use-an-ai-agent-easiest)
-5. [Path B — I use a terminal](#5-path-b--i-use-a-terminal)
+5. [Path B — I use a terminal](#5-path-b--i-use-a-terminal) — including [menus, tabs and modals: `map --deep`](#step-53b--what-about-my-menus-tabs-and-modals-map---deep)
 6. [Your first real workflow](#6-your-first-real-workflow-the-whole-point) — including [a test just failed, is it drift?](#step-64b--you-didnt-run-diff-you-got-a-red-build--explain) · [the console, if you don't want a terminal](#step-68--no-terminal-open-the-console)
 7. [Reading the verdict](#7-reading-the-verdict)
 8. [Putting it in CI](#8-putting-it-in-ci) — [JUnit trends](#82-trend-charts-for-free--junit) · [the run history](#83-the-trend--ia-qa-heal-history)
@@ -344,6 +344,48 @@ Plus, for the whole app:
 
 Commit them.
 
+### Step 5.3b — What about my menus, tabs and modals? `map --deep`
+
+A page has more than one state, and `map` records the one it loads in. Everything behind a
+dropdown, a tab, an accordion or a dialog is simply not there — so if it drifts, nothing tells
+you. It is a **coverage** hole rather than a false alarm, which is what makes it easy to miss:
+the gate stays green over a surface it never looked at.
+
+```bash
+npx ia-qa-heal map --deep
+```
+
+It opens what can be opened and contracts what appears. On ia-qa.com: `/method` 105 → 133
+elements, the home page 126 → 264.
+
+```
+✔ 264 interactive elements → .ia-qa/mapping/home.json + .ia-qa/mapping/home.md
+  🔍 deep: +140 behind interaction (124 on load) · 37 states · 54 clicks, 9 reloads
+  ↩ 133 revealed elements left out — selector already names another element
+  🛡  34 non-GET requests blocked during exploration (nothing mutating left the browser)
+```
+
+Four things worth knowing before you use it:
+
+**It cannot break your app.** Every non-GET request is aborted for the whole walk, so a click
+that would have deleted, paid or submitted anything never reaches your server — and controls
+whose name reads like an action (*log out*, *delete*, *pay*…) are not clicked at all, because a
+logout handler that just clears local storage sends no request for the guard to stop.
+
+**Elements it reaches but cannot contract are reported, not hidden** (`↩ 133 left out`). A
+selector must name exactly one element; a positional one captured inside a menu can collide with
+an element on the page behind it, and a contract holding the same selector twice makes the diff
+pair rows at random. Those are dropped and counted.
+
+**A deep baseline may only be diffed against a deep capture.** Mixing them reports everything
+behind a menu as `lost` — the tool warns you before the verdict, in the CLI and over MCP alike.
+Decide once, per baseline.
+
+**It costs about a minute per page** where a plain `map` costs seconds. Use it to build or
+refresh a baseline, not on every commit. `--depth 2` goes one click deeper; it was measured at
+three times the time for a contract that never finishes, so leave it alone unless you have a
+reason.
+
 ### Step 5.4 — Day one, before any drift: `audit`
 
 Everything after this point pays off at the *next* UI change. `audit` pays off now: it asks **does my test suite still name things that exist?**
@@ -858,6 +900,7 @@ npx ia-qa-heal init                       # one-time setup
 npx ia-qa-heal discover [--crawl] [--apply]  # optional: propose pages for config.json (sitemap or safe crawl)
 npx ia-qa-heal map                        # scan → *.json + *.md + _overview.md + _navigation.md/.svg
 npx ia-qa-heal map --screenshots          # + one JPEG per page, shown in the --report HTML (gitignore _shots/)
+npx ia-qa-heal map --deep                 # + open menus/tabs/dialogs and contract what they reveal (see below)
 npx ia-qa-heal baseline                   # promote mapping/ → baseline/ (commit it)
 #   …change the app, then `map` again…
 npx ia-qa-heal diff                       # verdict: PASS / FIX / BLOCK (baseline/ vs mapping/)

package/dist/aom.d.ts

@@ -102,6 +102,35 @@ export declare function isSameCapture(baseline: {
 } | null | undefined, current: {
     capturedAt?: string;
 } | null | undefined): boolean;
+/**
+ * Were these two contracts explored to the same depth?
+ *
+ * A deep contract holds the elements behind menus, tabs and dialogs; a shallow one cannot, so
+ * diffing one against the other reports every one of them as `lost`. That is not a handful of
+ * noisy rows — most of a page's surface can sit behind interaction, so the mismatch manufactures
+ * the whole BLOCK out of how the two captures were taken.
+ *
+ * Absent means depth 0 — the loaded state only. That is a *known* value, not an unknown one:
+ * every contract written before `--deep` existed describes exactly one state. (`captureState` is
+ * the opposite case, where absent genuinely means "cannot tell", and must never read as a match.)
+ *
+ * Lives here, beside `isSameCapture`, for the same reason: both doors into a diff — the CLI and
+ * the MCP server — have to agree on what is not a comparison. One warning and the other silent
+ * would just move the phantom verdict to whichever door the user knocked on.
+ */
+export declare function depthMismatch(baseline: {
+    exploredDepth?: number;
+} | null | undefined, current: {
+    exploredDepth?: number;
+} | null | undefined): {
+    baseline: number;
+    current: number;
+} | null;
+/** The sentence every door prints or attaches when `depthMismatch` returns non-null. */
+export declare function depthMismatchMessage(m: {
+    baseline: number;
+    current: number;
+}): string;
 export declare function extractInteractiveElements(page: Page): Promise<MappedElement[]>;
 export declare function saveMapping(mapping: PageMapping, dir?: string): string;
 export declare function loadMapping(pageName: string, dir?: string): PageMapping;

package/dist/aom.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSameCapture = isSameCapture;
+exports.depthMismatch = depthMismatch;
+exports.depthMismatchMessage = depthMismatchMessage;
 exports.extractInteractiveElements = extractInteractiveElements;
 exports.saveMapping = saveMapping;
 exports.loadMapping = loadMapping;
@@ -63,6 +65,36 @@ const extract_1 = require("./browser/extract");
 function isSameCapture(baseline, current) {
     return Boolean(baseline?.capturedAt) && baseline.capturedAt === current?.capturedAt;
 }
+/**
+ * Were these two contracts explored to the same depth?
+ *
+ * A deep contract holds the elements behind menus, tabs and dialogs; a shallow one cannot, so
+ * diffing one against the other reports every one of them as `lost`. That is not a handful of
+ * noisy rows — most of a page's surface can sit behind interaction, so the mismatch manufactures
+ * the whole BLOCK out of how the two captures were taken.
+ *
+ * Absent means depth 0 — the loaded state only. That is a *known* value, not an unknown one:
+ * every contract written before `--deep` existed describes exactly one state. (`captureState` is
+ * the opposite case, where absent genuinely means "cannot tell", and must never read as a match.)
+ *
+ * Lives here, beside `isSameCapture`, for the same reason: both doors into a diff — the CLI and
+ * the MCP server — have to agree on what is not a comparison. One warning and the other silent
+ * would just move the phantom verdict to whichever door the user knocked on.
+ */
+function depthMismatch(baseline, current) {
+    const b = baseline?.exploredDepth ?? 0;
+    const c = current?.exploredDepth ?? 0;
+    return b === c ? null : { baseline: b, current: c };
+}
+/** The sentence every door prints or attaches when `depthMismatch` returns non-null. */
+function depthMismatchMessage(m) {
+    const deeper = m.baseline > m.current ? 'baseline' : 'current capture';
+    const shallower = deeper === 'baseline' ? 'current capture' : 'baseline';
+    return (`Exploration depth mismatch — the ${deeper} was captured with \`map --deep\`, the ${shallower} ` +
+        `was not (depth ${m.baseline} vs ${m.current}). A deep contract holds the elements behind ` +
+        `menus, tabs and dialogs; a shallow one cannot, so those elements read as \`lost\` here. Most ` +
+        `of this verdict is probably that, not drift in your app. Capture both sides the same way.`);
+}
 async function extractInteractiveElements(page) {
     return page.evaluate(extract_1.extractInPage);
 }

package/dist/aom.js.map

@@ -1 +1 @@
-{"version":3,"file":"aom.js","sourceRoot":"","sources":["../src/aom.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2GA,sCAKC;AAED,gEAEC;AAED,kCAwBC;AAED,kCAQC;AAxJD,uCAAyB;AACzB,2CAA6B;AAE7B,qCAAmD;AACnD,+CAAkD;AAoFlD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,aAAa,CAC3B,QAAoD,EACpD,OAAmD;IAEnD,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,QAAS,CAAC,UAAU,KAAK,OAAO,EAAE,UAAU,CAAC;AACvF,CAAC;AAEM,KAAK,UAAU,0BAA0B,CAAC,IAAU;IACzD,OAAO,IAAI,CAAC,QAAQ,CAAC,uBAAa,CAA6B,CAAC;AAClE,CAAC;AAED,SAAgB,WAAW,CAAC,OAAoB,EAAE,MAAc,IAAA,mBAAU,GAAE;IAC1E,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACtE,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC;YAC9D,OAAO,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,8BAA8B,IAAI,CAAC,UAAU,iBAAiB,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACxD,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAExC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACxC,IAAI,KAAK,KAAK,GAAG,OAAO,CAAC,IAAI,OAAO;YAAE,SAAS;QAC/C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAChE,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC;gBAC/D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAC3C,OAAO,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,wBAAwB,KAAK,oCAAoC,CAAC,CAAC;YACpG,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,WAAW,CAAC,QAAgB,EAAE,MAAc,IAAA,mBAAU,GAAE;IACtE,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,8BAA8B,QAAQ,MAAM,IAAI,2BAA2B,QAAQ,WAAW,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;AAClE,CAAC"}
+{"version":3,"file":"aom.js","sourceRoot":"","sources":["../src/aom.ts"],"names":[],"mappings":"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"}

package/dist/captureMerge.js

@@ -40,6 +40,7 @@ exports.mergeCapturesAnnounced = mergeCapturesAnnounced;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const config_1 = require("./config");
+const pageName_1 = require("./pageName");
 const aom_1 = require("./aom");
 const markdown_1 = require("./markdown");
 const union_1 = require("./browser/union");
@@ -58,6 +59,39 @@ exports.CAPTURE_DIRNAME = '.capture';
 function captureDir(cwd = (0, config_1.baseDir)()) {
     return path.join((0, config_1.mappingDir)(cwd), exports.CAPTURE_DIRNAME);
 }
+/**
+ * One contract, two applications — say so instead of writing it.
+ *
+ * A page name is an identity claim, and `resolvePageName` keeps it honest by putting
+ * the host in the name whenever the URL is not the app's own. That needs a `baseUrl`,
+ * so it needs a config; without one every host's `/login` still resolves to `login`,
+ * and this merge would union five products into one contract, then diff it against
+ * whichever one it happened to hold last — a permanent phantom drift on a suite that
+ * is green, offered to `fix` as a rename.
+ *
+ * We cannot pick the namespace here (there is no declared app to be foreign *to*, and
+ * inventing one from whichever host appeared most would make the names depend on
+ * worker scheduling). So we name the collision and the remedy, rather than let silence
+ * read as "checked, fine". The remedy differs by cause, and the cause is *checked*, not
+ * assumed: with a config in place these names cannot come from this version's capture,
+ * so they came from a stale `.capture/` or a hand-written shard.
+ */
+function warnHostCollisions(byPage, configured) {
+    for (const [name, { hosts }] of byPage) {
+        if (hosts.size < 2)
+            continue;
+        const remedy = configured
+            ? `     This version names an off-\`baseUrl\` page \`<host>--<path>\`, so these shards were ` +
+                `written by an older version or by hand. Delete \`${config_1.CONFIG_DIR}/mapping/.capture/\`, re-run ` +
+                `the suite, and declare any page you want named yourself in "pages" with its absolute URL.`
+            : `     There is no ${config_1.CONFIG_DIR}/config.json here, so nothing names the app these pages ` +
+                `belong to; with a "baseUrl", every other host is prefixed into the page name instead. ` +
+                `Run \`ia-qa-heal init\`, or declare each one in "pages" with its absolute URL.`;
+        console.warn(`⚠ Page "${name}" was captured from ${hosts.size} different hosts this run ` +
+            `(${Array.from(hosts).join(', ')}) — they are sharing one contract, so its diff is not ` +
+            `meaningful.\n${remedy}`);
+    }
+}
 function mergeCaptures(cwd = (0, config_1.baseDir)()) {
     const dir = captureDir(cwd);
     if (!fs.existsSync(dir))
@@ -84,9 +118,17 @@ function mergeCaptures(cwd = (0, config_1.baseDir)()) {
             if (!p?.page || !Array.isArray(p.elements))
                 continue;
             const prev = byPage.get(p.page);
+            const hosts = prev ? prev.hosts : new Set();
+            try {
+                hosts.add((0, pageName_1.foldHost)(new URL(p.url)));
+            }
+            catch {
+                /* an unparseable URL says nothing about which app this was */
+            }
             byPage.set(p.page, {
                 url: p.url,
                 elements: prev ? (0, union_1.unionElements)(prev.elements, p.elements) : p.elements,
+                hosts,
             });
         }
     }
@@ -94,12 +136,15 @@ function mergeCaptures(cwd = (0, config_1.baseDir)()) {
     // here at the merge — one place covering the Playwright, Cypress and Selenium
     // hooks at once. No config, no patterns: live capture without one stays as-is.
     let patterns = [];
+    let configured = false;
     try {
         patterns = (0, volatile_1.parseVolatilePatterns)((0, config_1.loadConfig)(cwd).volatile);
+        configured = true;
     }
     catch {
         /* config optional for a merge */
     }
+    warnHostCollisions(byPage, configured);
     const capturedAt = new Date().toISOString();
     const outDir = (0, config_1.mappingDir)(cwd);
     const pages = [];

package/dist/captureMerge.js.map

@@ -1 +1 @@
-{"version":3,"file":"captureMerge.js","sourceRoot":"","sources":["../src/captureMerge.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBA,gCAEC;AAwBD,sCAkEC;AAMD,wDAeC;AArID,uCAAyB;AACzB,2CAA6B;AAC7B,qCAAsE;AACtE,+BAAgE;AAChE,yCAA0C;AAC1C,2CAAgD;AAgCvC,8FAhCA,qBAAa,OAgCA;AA/BtB,yCAAoF;AACpF,yCAA2C;AAE3C;;;;;;;GAOG;AAEU,QAAA,eAAe,GAAG,UAAU,CAAC;AAE1C,SAAgB,UAAU,CAAC,MAAc,IAAA,gBAAO,GAAE;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAA,mBAAU,EAAC,GAAG,CAAC,EAAE,uBAAe,CAAC,CAAC;AACrD,CAAC;AAwBD,SAAgB,aAAa,CAAC,MAAc,IAAA,gBAAO,GAAE;IACnD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,UAAU,GAAG,EAAE;SAClB,WAAW,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;SAClC,IAAI,EAAE,CAAC;IACV,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsD,CAAC;IAC7E,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,KAAmB,CAAC;QACxB,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAiB,CAAC;QACpF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,mBAAmB,IAAI,+BAA+B,CAAC,CAAC;YACrE,SAAS;QACX,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;gBAAE,SAAS;YACrD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE;gBACjB,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,IAAA,qBAAa,EAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ;aACvE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,8EAA8E;IAC9E,+EAA+E;IAC/E,IAAI,QAAQ,GAAsB,EAAE,CAAC;IACrC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAA,gCAAqB,EAAC,IAAA,mBAAU,EAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,iCAAiC;IACnC,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAA,mBAAU,EAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;QAC/C,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAA,yBAAc,EAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC9D,gBAAgB,IAAI,QAAQ,CAAC;QAC7B,MAAM,OAAO,GAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC5F,IAAA,iBAAW,EAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,IAAA,uBAAY,EAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,+EAA+E;IAC/E,oBAAoB;IACpB,IAAI,CAAC;QACH,IAAA,wBAAa,EAAC,IAAA,mBAAU,EAAC,GAAG,CAAC,EAAE,IAAA,mBAAU,EAAC,GAAG,CAAC,EAAE,IAAA,kBAAS,EAAC,GAAG,CAAC,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,iFAAiF;IACnF,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,MAAc,IAAA,gBAAO,GAAE;IAC5D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,CAAC,GAAG,CACT,aAAa,MAAM,CAAC,MAAM,iBAAiB,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,6BAA6B;gBACpG,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,YAAY,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACpG,CAAC,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,MAAM,CAAC,gBAAgB,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CACV,wCAAwC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC3F,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"captureMerge.js","sourceRoot":"","sources":["../src/captureMerge.ts"],"names":[],"mappings":"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"}

package/dist/cli/diff.d.ts

@@ -167,6 +167,16 @@ export interface DirReport {
     totals: Report['counts'];
     /** Pairs left out of the verdict: same capture on both sides, so incapable of showing drift. */
     staleExcluded?: string[];
+    /**
+     * The two sides were explored to different depths (`map --deep`) — so much of this verdict is
+     * probably an artefact of how the contracts were captured rather than drift in the app.
+     * Carried on the aggregate so `--json` and the report state it, not only the terminal.
+     */
+    depthMismatch?: {
+        baseline: number;
+        current: number;
+        why: string;
+    };
     /**
      * Renamed labels the suite locates by name, de-duped across pages — a shared
      * header renames once, not once per page that carries it.

package/dist/cli/diff.js

@@ -365,6 +365,11 @@ async function runDiff(args) {
         refuseToCompare('same-capture', sameCaptureMessage(baseline.capturedAt), 'Change the app and run `ia-qa-heal map` again, so the two sides are different moments.', json);
         return;
     }
+    // Before the verdict, never after: a depth mismatch does not colour a few rows, it can invent
+    // the entire BLOCK. Same check as `diff --dir` and the MCP — one shared function, three doors.
+    const depths = (0, aom_1.depthMismatch)(baseline, current);
+    if (depths && !json)
+        console.error(`\n⚠️  ${(0, aom_1.depthMismatchMessage)(depths)}`);
     const usage = (0, ingest_1.loadUsage)();
     const report = attachBaselineHrefs((0, nameMask_1.diffWithMasks)(baseline, current, (0, nameMask_1.loadNameMasks)(), usage), baseline);
     // Same rule as the directory walk: the resolutions sit next to the mappings they
@@ -547,7 +552,7 @@ async function runDirDiff(baselineDir, currentDir, opts) {
         console.error(`❌ "${currentDir}" is not a directory.`);
         process.exit(2);
     }
-    const { reports, stale, systemic, depthMismatch } = collectDirDiff(baselineDir, currentDir);
+    const { reports, stale, systemic, depthMismatch: depths } = collectDirDiff(baselineDir, currentDir);
     if (reports.length === 0 && stale.length > 0) {
         refuseToCompare('same-capture', `❌ Nothing to compare: ${stale.length === 1 ? 'the only pair is' : `all ${stale.length} pairs are`} ` +
             `the same capture on both sides.\n\n` +
@@ -566,21 +571,19 @@ async function runDirDiff(baselineDir, currentDir, opts) {
     // it can invent the entire BLOCK, because everything the deep side found behind a menu is
     // simply absent from the shallow side and reads as `lost`. Someone who meets the verdict
     // first will start hand-repairing drift that never happened.
-    if (depthMismatch) {
-        const deeper = depthMismatch.baseline > depthMismatch.current ? 'baseline' : 'current capture';
-        const shallower = deeper === 'baseline' ? 'current capture' : 'baseline';
-        console.error(`\n⚠️  Exploration depth mismatch — the ${deeper} was captured with \`map --deep\`, the ` +
-            `${shallower} was not\n   (depth ${depthMismatch.baseline} vs ${depthMismatch.current}). ` +
-            `A deep contract holds the elements behind menus, tabs and dialogs;\n   a shallow one ` +
-            `cannot, so those elements read as \`lost\` here. Most of what follows is probably that,\n` +
-            `   not drift in your app.\n` +
-            `   Capture both sides the same way: \`ia-qa-heal map --deep\` before diffing, or re-baseline` +
-            ` without it.`);
+    if (depths) {
+        console.error(`\n⚠️  ${(0, aom_1.depthMismatchMessage)(depths)}\n` +
+            `   \`ia-qa-heal map --deep\` before diffing, or re-baseline without it.`);
     }
     // Aggregate verdict
     const aggregate = aggregateReports(reports);
     if (stale.length > 0)
         aggregate.staleExcluded = stale;
+    // Onto the aggregate, not only the terminal: `--json` is what a pipeline reads, and a CI that
+    // sees BLOCK without knowing the two sides were captured differently is the same blind spot
+    // the MCP had. Every consumer of a verdict gets the caveat attached to it.
+    if (depths)
+        aggregate.depthMismatch = { ...depths, why: (0, aom_1.depthMismatchMessage)(depths) };
     if (systemic.groups.length > 0)
         aggregate.systemic = systemic;
     Object.assign(aggregate, (0, nextStep_1.nextStepFor)(aggregate.verdict, {
@@ -683,8 +686,7 @@ function collectDirDiff(baselineDir, currentDir) {
     // Exploration depth, settled the same way and for the same reason. Absent means the loaded
     // state only, which is depth 0 — a real value here, not unknown: every contract written
     // before `--deep` existed describes exactly one state, and that is knowable.
-    let baselineDepth = 0;
-    let currentDepth = 0;
+    let deepest = null;
     // Kept out of the verdict rather than counted as `ok` — N ok that were never
     // compared is exactly the false green this guard exists to stop.
     const stale = [];
@@ -695,8 +697,7 @@ function collectDirDiff(baselineDir, currentDir) {
     const assess = (baseline, current, baselineFile, currentFile, page) => {
         baselineState ??= baseline.captureState;
         currentState ??= current.captureState;
-        baselineDepth = Math.max(baselineDepth, baseline.exploredDepth ?? 0);
-        currentDepth = Math.max(currentDepth, current.exploredDepth ?? 0);
+        deepest ??= (0, aom_1.depthMismatch)(baseline, current);
         const report = attachBaselineHrefs((0, nameMask_1.diffWithMasks)(baseline, current, masks, usage), baseline);
         report.nameDrift = (0, nameDrift_1.assessNameDrift)(report.rows, current.elements, usage);
         report.verdict = (0, nameDrift_1.escalateVerdict)(report.verdict, report.nameDrift);
@@ -760,7 +761,7 @@ function collectDirDiff(baselineDir, currentDir) {
         reports,
         stale,
         systemic,
-        depthMismatch: baselineDepth === currentDepth ? null : { baseline: baselineDepth, current: currentDepth },
+        depthMismatch: deepest,
     };
 }
 function aggregateReports(reports) {