@ia-qa/self-healing 0.6.0 → 0.8.0

package/README.md

@@ -9,9 +9,11 @@ Self-healing E2E toolkit: a **local MCP server** for AI agents, a guided **CLI**
 ## Quick start
 
 ```bash
-npx -y -p @ia-qa/self-healing ia-qa-heal init    # wizard → .ia-qa/config.json
-npx -y -p @ia-qa/self-healing ia-qa-heal map     # → .ia-qa/mapping/<page>.json + .md
-npx -y -p @ia-qa/self-healing ia-qa-heal diff before.json after.json   # → PASS / FIX / BLOCK
+npx -y -p @ia-qa/self-healing ia-qa-heal init      # wizard → .ia-qa/config.json
+npx -y -p @ia-qa/self-healing ia-qa-heal map      # → .ia-qa/mapping/<page>.json + .md
+npx -y -p @ia-qa/self-healing ia-qa-heal baseline # → .ia-qa/baseline/ — the reference. Commit it.
+#   …change the app, then `map` again…
+npx -y -p @ia-qa/self-healing ia-qa-heal diff     # baseline/ vs mapping/ → PASS / FIX / BLOCK
 ```
 
 Install it in the project that holds your tests to drop the `-p` dance — and to get the `aiClick` / `aiFill` runtime helpers, which are imported, not run:
@@ -69,22 +71,29 @@ Only if all four fail does it error, listing the three fixes. `map_app` exposes
    The `<page>.md` groups elements by role and carries a self-describing header telling a model exactly how to use it. **The CI auto-heal loop:** when a UI test fails, hand the failing test file + the current `<page>.md` to an LLM — it finds the element by role + accessible name, reads the current selector, and rewrites the test in **whatever framework and language** it is written in (Cypress, Playwright, Selenium; JS or Python). The contract is the source of truth; the model handles the syntax. The same contract is downloadable from the zero-install **Selector Drift Detector** page on ia-qa.com.
 
    Alongside the page contracts, `map` rebuilds the app index and the navigation graph — see [Map artifacts](#map-artifacts).
-3. **`ia-qa-heal diff <before.json> <after.json>`** — CI-gate verdict. Diffs two mappings (from `map` or the ia-qa.com browser snippet) and reports which selectors survived, which the runtime healer would recover, and which will hard-fail:
+3. **`ia-qa-heal baseline`** — promote `.ia-qa/mapping/` to `.ia-qa/baseline/`, the reference `diff` compares against. Commit it: a reference that is not in git cannot be reviewed or reverted, and accepting drift is a code-review decision like any other.
+
+   Drift is a claim about **two moments**, and `map` only ever captures one. Promotion is the second half, and it is a separate verb on purpose — deliberately *not* a flag on `map`, because promoting in the same breath as capturing would make the reference incapable of ever being older than what it is compared to. `map` records what the app **is**; `baseline` says it is also what the app is **supposed to be**. That second claim is a human judgement.
+
+   Skip it and the natural workaround is `cp current.json baseline.json && diff` — which compares a capture to a copy of itself and prints `PASS ✅ No drift`. That verdict is green because nothing was compared, not because nothing changed. `diff` now refuses it outright (exit `2`): every side carries a `capturedAt`, equal timestamps mean one `map` run, and one run cannot drift from itself. A gate that reports green without looking is worse than no gate, because it is trusted.
+4. **`ia-qa-heal diff [before.json] [after.json]`** — CI-gate verdict. With no arguments, diffs `baseline/` against `mapping/` — the everyday case. Diffs two mappings (from `map` or the ia-qa.com browser snippet) and reports which selectors survived, which the runtime healer would recover, and which will hard-fail:
    ```
    ⛔  BLOCK
       before.json → after.json  ·  3 ok · 2 healable · 1 lost · 2 new
       🔧 healable  button "Se connecter"      button#login-btn → button.btn-primary (exact name)
       ⛔ lost      button "Supprimer le compte"  button#delete → (no match)
    ```
-   Exit codes for pipelines: `0` = PASS or FIX, `1` = BLOCK — lost, ambiguous, or rebound (add `--strict` to fail on FIX too), `2` = bad input. Use `--json` for machine-readable output. Same diff engine as the web tool (`src/browser/match.js`).
+   Exit codes for pipelines: `0` = PASS or FIX, `1` = BLOCK — lost, ambiguous, or rebound (add `--strict` to fail on FIX too), `2` = bad input, no baseline, or nothing to compare. Use `--json` for machine-readable output. Same diff engine as the web tool (`src/browser/match.js`).
+
+   A contract that was **not re-mapped** since the baseline carries the baseline's own `capturedAt`, so it cannot show drift. Those are listed and left **out** of the verdict rather than counted as `ok` — padding a gate with comparisons that never happened is the same lie in smaller print. `--json` reports them as `staleExcluded`.
 
    Every element carries a **context** (nearest landmark + section heading) so two elements with the same role + accessible name (five "Delete" buttons) stay distinguishable. The diff classifies each baseline element as `ok`, `renamed` (same element, new accessible name — a *content* drift to eyeball), `healable` (deterministic old→new rewrite), `ambiguous` (several equal matches — the tool **refuses to guess**, a human decides), or `lost` (no match).
 
    Identity comes from the contract (role + accessible name), never from the selector string. A selector that still resolves only proves the *position* is still occupied: insert one button above a tab bar and every `nth-of-type` below it silently slides onto its neighbour. Any row where that happened is flagged `rebound` — the old selector resolves, but to a **different element**, so the suite is green while clicking the wrong thing. Rebound rows are rewritten like any other healable row, and they **BLOCK**: a `FIX` verdict exits `0`, which is exactly how this ships unnoticed.
-4. **`ia-qa-heal fix <before.json> <after.json> <test-paths…>`** — the deterministic half. Applies **only** the `healable` rewrites to your test files, replacing the selector only where it appears as a quoted string literal (`'…'`/`"…"`/`` `…` ``, quote-safe for attribute selectors), across any framework/language. Every rewrite is applied in a single pass against the selector each occurrence had in the file, so a *permuted* set (`nth-of-type(1)→(2)`, `(2)→(3)`) can never chain and drag `(1)` to `(3)`. LOST / AMBIGUOUS / RENAMED are printed but never touched — they need judgment. It **edits the working tree and never commits**: review with `git diff`, then push or discard. `--dry-run` previews the plan. This is "prepare the ground, the human decides" as a command.
+5. **`ia-qa-heal fix <before.json> <after.json> <test-paths…>`** — the deterministic half. Applies **only** the `healable` rewrites to your test files, replacing the selector only where it appears as a quoted string literal (`'…'`/`"…"`/`` `…` ``, quote-safe for attribute selectors), across any framework/language. Every rewrite is applied in a single pass against the selector each occurrence had in the file, so a *permuted* set (`nth-of-type(1)→(2)`, `(2)→(3)`) can never chain and drag `(1)` to `(3)`. LOST / AMBIGUOUS / RENAMED are printed but never touched — they need judgment. It **edits the working tree and never commits**: review with `git diff`, then push or discard. `--dry-run` previews the plan. This is "prepare the ground, the human decides" as a command.
 
    **`--locators`** rewrites to a Playwright role locator — `page.getByRole('button', { name: 'Validator' })` — instead of a selector, wherever role + accessible name identifies exactly one element. A repaired positional selector is only correct until the next insertion; a role locator is what the contract already means, so it does not drift at all. Applies to `.js`/`.ts` files and Playwright call shapes (`page.click('…')`, `page.locator('…')`, `page.fill('…', v)`, …); every other file and every element without an unambiguous role + name keeps the plain selector rewrite. `getByRole` is strict, so a locator is emitted only when it provably resolves to one element — otherwise the tool would trade a silent wrong click for a loud crash.
-5. **Runtime healing** — in your Playwright tests:
+6. **Runtime healing** — in your Playwright tests:
    ```ts
    import { aiClick, aiFill } from '@ia-qa/self-healing';
 
@@ -101,10 +110,13 @@ Beyond one contract per page, every `map` run rebuilds two views of the whole ap
 
 **`_navigation.md` / `_navigation.svg`** — the navigation graph, written when pages link to each other, built from link `href`s. The `.md` is a Mermaid fence (GitHub, GitLab and the VS Code preview render it natively); the `.svg` is the same graph, hand-rolled, opening in any browser offline — no mermaid.js, no CDN, nothing fetched.
 
-The graph draws **what a page table cannot tell you: pages that link to each other**. Three things are deliberately left out, on one principle — a picture should not spend ink on what the page list already says:
+The graph draws **what a page table cannot tell you: pages that link to each other selectively**. Four things are deliberately left out, on one principle — a picture should not spend ink on what a sentence already says:
 - **shell links** (navbar, footer) — in the overview, listed once, instead of an edge from every page to every navbar destination;
 - **isolated pages** — a box with no arrow;
-- **hub fans** — a page whose spokes link nowhere else is stated in one sentence (`home` fans out to 144 pages) instead of drawn as 144 identical arrows crossing every other line. That is the catalogue shape, and no node-link diagram survives it.
+- **hub fans** — a page whose spokes link nowhere else is stated in one sentence (`home` fans out to 144 pages) instead of drawn as 144 identical arrows crossing every other line. That is the catalogue shape, and no node-link diagram survives it;
+- **meshes** — when nearly every mapped page links to nearly every other (the related-tools-widget shape: 16 links between 5 pages), the whole drawing carries one fact — "these pages cross-link" — so the overview states it and no graph is written.
+
+Pages **nothing links to** are called out as entry points (orange border in the `.svg` and the Mermaid graph): the way in — a login, a home — or a page only the shell reaches. The map cannot tell which; you can.
 
 What is left is the real structure: a checkout tunnel stays, its noise does not. If nothing survives, both files are removed rather than left stale — for that app, the page list genuinely is the whole story.
 

package/TUTORIAL.md

@@ -165,10 +165,12 @@ The agent launches a browser in the background and gives you back something like
 | Valider         | main › Paiement  | `button[data-testid="pay"]` |
 ```
 
-**That's your baseline.** Commit it — it lives in git like code:
+**That's a capture of what the app is right now.** To make it the reference everything is
+measured against, promote it — then commit both, they live in git like code:
 
 ```bash
-git add .ia-qa/mapping
+npx ia-qa-heal baseline          # .ia-qa/mapping → .ia-qa/baseline
+git add .ia-qa/mapping .ia-qa/baseline
 git commit -m "Add page contract baseline"
 ```
 
@@ -238,13 +240,28 @@ Commit them.
 Here's the loop you'll actually live in.
 
 ### Step 6.1 — You have a baseline
-From step 4.4 or 5.3, committed to git. Call it `checkout.baseline.json` (just copy it):
+From step 4.4 or 5.3: promoted with `ia-qa-heal baseline` and committed to git.
 
 ```bash
-cp .ia-qa/mapping/checkout.json .ia-qa/mapping/checkout.baseline.json
-git add .ia-qa/mapping && git commit -m "baseline"
+npx ia-qa-heal baseline
+git add .ia-qa/mapping .ia-qa/baseline && git commit -m "baseline"
 ```
 
+Promotion is its own step because **drift is a claim about two moments**, and `map` only
+ever captures one. `map` records what the app *is*; `baseline` says it is also what the app
+is *supposed to be*. That second claim is yours to make, so it gets its own command.
+
+Do it now and `diff` will refuse — correctly. Nothing has been re-mapped, so both sides are
+the same capture, and a capture cannot drift from itself:
+
+```
+❌ Nothing to compare: all 2 pairs are the same capture on both sides.
+```
+
+That refusal *is* the feature. The obvious shortcut — copy the file, diff against the copy —
+prints `PASS ✅ No drift — your suite is safe to run`, which sounds like an answer and is
+not one: nothing was compared. A green gate that never looked is worse than no gate.
+
 ### Step 6.2 — Someone changes the UI
 A developer ships a redesign. Your tests start failing. **Normal.**
 
@@ -256,18 +273,22 @@ Terminal: `npx ia-qa-heal map checkout`
 Agent: **"Diff the baseline against the new contract"**
 Terminal:
 ```bash
-npx ia-qa-heal diff .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json
+npx ia-qa-heal diff          # baseline/ against mapping/ — no arguments needed
 ```
 
+Now there are two moments, so there is a verdict. Any page you did **not** re-map still
+carries the baseline's own timestamp; it is listed and left out of the verdict rather than
+counted as `ok`, because it was never compared either.
+
 ### Step 6.5 — Apply the safe fixes
 Agent: **"Fix my tests in the tests/ folder using that diff"**
 Terminal:
 ```bash
 # Preview first — nothing is written
-npx ia-qa-heal fix .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json tests/ --dry-run
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/ --dry-run
 
 # Do it
-npx ia-qa-heal fix .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json tests/
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/
 ```
 
 ### Step 6.5b — Stop fixing the same test twice (`--locators`)
@@ -351,9 +372,14 @@ jobs:
         run: npx ia-qa-heal map
 
       - name: Fail if selectors drifted with no safe fix
-        run: npx ia-qa-heal diff .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json
+        run: npx ia-qa-heal diff
 ```
 
+`diff` with no arguments compares the committed `.ia-qa/baseline/` against the `.ia-qa/mapping/`
+the previous step just re-captured — which is why the baseline has to be in git for CI to have
+anything to check out. It exits `2` if there is no baseline, or if nothing was re-mapped, so a
+misconfigured job fails loudly instead of passing without comparing anything.
+
 Add `--strict` if you want **FIX** to fail the build too (forces tests to be updated, not just healed).
 
 ---
@@ -419,9 +445,11 @@ Yes, any URL your machine can reach.
 ```bash
 npx ia-qa-heal init                       # one-time setup
 npx ia-qa-heal map                        # scan → *.json + *.md + _overview.md + _navigation.md/.svg
-npx ia-qa-heal diff before.json after.json    # verdict: PASS / FIX / BLOCK
-npx ia-qa-heal fix before.json after.json tests/ --dry-run   # preview
-npx ia-qa-heal fix before.json after.json tests/             # apply (never commits)
+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/)
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/ --dry-run   # preview
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/             # apply (never commits)
 ```
 
 Talking to an agent instead:

package/dist/aom.d.ts

@@ -23,6 +23,30 @@ export interface PageMapping {
     capturedAt: string;
     elements: MappedElement[];
 }
+/**
+ * Did these two mappings come out of the same `map` run?
+ *
+ * `capturedAt` is stamped once per page per run, so equality means one capture is being
+ * compared to a copy of itself. That is what a hand-rolled baseline (`cp current.json
+ * baseline.json && diff`) always produces on its first run, and the diff of a file against
+ * itself is `PASS · N ok · 0 healable` — printed under "✅ No drift — your suite is safe to
+ * run". Every word of that is false: nothing was compared, so nothing is known about the
+ * suite. A green gate that never looked is worse than no gate, because it is trusted.
+ *
+ * Two real `map` runs collide only if stamped on the same millisecond, which does not
+ * happen across the app changes a drift check exists to find. A *missing* timestamp is
+ * malformed input, not a self-comparison: two `undefined`s share nothing meaningful, and
+ * blocking on them would refuse a legitimate diff over a field the diff never reads.
+ *
+ * Lives here rather than beside either caller because both doors into the diff — the CLI
+ * and the MCP server — have to agree on what is not a comparison. One guarding and the
+ * other not would just move the false green to whichever door the user knocked on.
+ */
+export declare function isSameCapture(baseline: {
+    capturedAt?: string;
+} | null | undefined, current: {
+    capturedAt?: string;
+} | null | undefined): boolean;
 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

@@ -33,12 +33,35 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSameCapture = isSameCapture;
 exports.extractInteractiveElements = extractInteractiveElements;
 exports.saveMapping = saveMapping;
 exports.loadMapping = loadMapping;
 const fs = __importStar(require("fs"));
 const config_1 = require("./config");
 const extract_1 = require("./browser/extract");
+/**
+ * Did these two mappings come out of the same `map` run?
+ *
+ * `capturedAt` is stamped once per page per run, so equality means one capture is being
+ * compared to a copy of itself. That is what a hand-rolled baseline (`cp current.json
+ * baseline.json && diff`) always produces on its first run, and the diff of a file against
+ * itself is `PASS · N ok · 0 healable` — printed under "✅ No drift — your suite is safe to
+ * run". Every word of that is false: nothing was compared, so nothing is known about the
+ * suite. A green gate that never looked is worse than no gate, because it is trusted.
+ *
+ * Two real `map` runs collide only if stamped on the same millisecond, which does not
+ * happen across the app changes a drift check exists to find. A *missing* timestamp is
+ * malformed input, not a self-comparison: two `undefined`s share nothing meaningful, and
+ * blocking on them would refuse a legitimate diff over a field the diff never reads.
+ *
+ * Lives here rather than beside either caller because both doors into the diff — the CLI
+ * and the MCP server — have to agree on what is not a comparison. One guarding and the
+ * other not would just move the false green to whichever door the user knocked on.
+ */
+function isSameCapture(baseline, current) {
+    return Boolean(baseline?.capturedAt) && baseline.capturedAt === current?.capturedAt;
+}
 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,gEAEC;AAED,kCAKC;AAED,kCAQC;AAnDD,uCAAyB;AAEzB,qCAAmD;AACnD,+CAAkD;AA6B3C,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,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,sCAKC;AAED,gEAEC;AAED,kCAKC;AAED,kCAQC;AA7ED,uCAAyB;AAEzB,qCAAmD;AACnD,+CAAkD;AA6BlD;;;;;;;;;;;;;;;;;;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,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,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"}

package/dist/cli/baseline.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `ia-qa-heal baseline` — promote the current mappings to the reference `diff` compares against.
+ *
+ * Drift is a claim about two moments, so it needs a promoted "before". Without a command for
+ * it, everyone invents one, and the obvious invention — copy the current mapping, then diff
+ * against the copy — compares a capture to itself and reports `PASS  ✅ No drift`. The
+ * verdict is green because nothing was compared, which is the one failure mode a CI gate
+ * must never have. So the promotion is a command, and `diff` refuses a verdict when it
+ * catches the copy anyway (see `assertComparable` in `diff.ts`).
+ *
+ * Deliberately not a flag on `map`: promoting in the same breath as capturing would rebuild
+ * the trap, since the reference could then never be older than what it is compared to. The
+ * separation *is* the feature — `map` records what the app is now, `baseline` says it is
+ * also what the app is supposed to be. That second claim is a human judgement, and it gets
+ * its own verb.
+ *
+ * Copies `.json` only. `diff` reads nothing else, and the markdown contracts in `mapping/`
+ * already describe the app as it is today — a frozen second copy of them would be prose that
+ * silently goes stale, and twice the diff to review on every promotion.
+ */
+export declare function runBaseline(args?: string[]): Promise<void>;

package/dist/cli/baseline.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBaseline = runBaseline;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+/**
+ * `ia-qa-heal baseline` — promote the current mappings to the reference `diff` compares against.
+ *
+ * Drift is a claim about two moments, so it needs a promoted "before". Without a command for
+ * it, everyone invents one, and the obvious invention — copy the current mapping, then diff
+ * against the copy — compares a capture to itself and reports `PASS  ✅ No drift`. The
+ * verdict is green because nothing was compared, which is the one failure mode a CI gate
+ * must never have. So the promotion is a command, and `diff` refuses a verdict when it
+ * catches the copy anyway (see `assertComparable` in `diff.ts`).
+ *
+ * Deliberately not a flag on `map`: promoting in the same breath as capturing would rebuild
+ * the trap, since the reference could then never be older than what it is compared to. The
+ * separation *is* the feature — `map` records what the app is now, `baseline` says it is
+ * also what the app is supposed to be. That second claim is a human judgement, and it gets
+ * its own verb.
+ *
+ * Copies `.json` only. `diff` reads nothing else, and the markdown contracts in `mapping/`
+ * already describe the app as it is today — a frozen second copy of them would be prose that
+ * silently goes stale, and twice the diff to review on every promotion.
+ */
+async function runBaseline(args = []) {
+    const from = (0, config_1.mappingDir)();
+    const to = (0, config_1.baselineDir)();
+    if (!fs.existsSync(from)) {
+        console.error(`❌ No mappings found in ${rel(from)} — run \`ia-qa-heal map\` first.`);
+        process.exitCode = 2;
+        return;
+    }
+    const pages = jsonFilesIn(from);
+    const layouts = jsonFilesIn(path.join(from, config_1.LAYOUT_DIRNAME));
+    if (pages.length === 0 && layouts.length === 0) {
+        console.error(`❌ ${rel(from)} holds no mapping files — run \`ia-qa-heal map\` first.`);
+        process.exitCode = 2;
+        return;
+    }
+    const replaced = jsonFilesIn(to).length + jsonFilesIn(path.join(to, config_1.LAYOUT_DIRNAME)).length;
+    fs.mkdirSync(to, { recursive: true });
+    for (const file of pages) {
+        fs.copyFileSync(path.join(from, file), path.join(to, file));
+    }
+    if (layouts.length > 0) {
+        fs.mkdirSync(path.join(to, config_1.LAYOUT_DIRNAME), { recursive: true });
+        for (const file of layouts) {
+            fs.copyFileSync(path.join(from, config_1.LAYOUT_DIRNAME, file), path.join(to, config_1.LAYOUT_DIRNAME, file));
+        }
+    }
+    const total = pages.length + layouts.length;
+    console.log(`\n📌 Baseline promoted → ${rel(to)}`);
+    console.log(`   ${pages.length} ${pages.length === 1 ? 'page' : 'pages'}` +
+        (layouts.length > 0 ? ` · ${layouts.length} ${layouts.length === 1 ? 'layout' : 'layouts'}` : '') +
+        (replaced > 0 ? `  (replaced a baseline of ${replaced} ${replaced === 1 ? 'file' : 'files'})` : ''));
+    // Promoting over a reference that had drift in it accepts that drift as correct, silently
+    // and irreversibly outside of git. Saying so is the difference between "I meant that" and
+    // "I did not know that was what the command did".
+    if (replaced > 0) {
+        console.log(`   Any drift against the old baseline is now the expected state.`);
+    }
+    console.log(`\n   Commit it — a reference that is not in git cannot be reviewed or reverted:`);
+    console.log(`     git add ${rel(to).replace(/\\/g, '/')} && git commit -m "baseline: ${total} contracts"`);
+    console.log(`\n   Then change the app, \`ia-qa-heal map\` again, and \`ia-qa-heal diff\` has two`);
+    console.log(`   different moments to compare.\n`);
+    if (args.length > 0) {
+        console.log(`   (ignored: ${args.join(' ')} — \`baseline\` takes no arguments)\n`);
+    }
+}
+function jsonFilesIn(dir) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+        return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.json') && !f.startsWith('.'));
+}
+function rel(p) {
+    return path.relative(process.cwd(), p) || p;
+}
+//# sourceMappingURL=baseline.js.map

package/dist/cli/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../src/cli/baseline.ts"],"names":[],"mappings":"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"}

package/dist/cli/diff.d.ts

@@ -1,8 +1,10 @@
 /**
- * `ia-qa-heal diff <baseline.json> <current.json> [--strict] [--json] [--dir]`
+ * `ia-qa-heal diff [baseline] [current] [--strict] [--json] [--dir]`
  *
- * Two modes:
- *   file mode (default) — diffs two individual mapping files.
+ * Three modes:
+ *   no arguments — the everyday case: the promoted `baseline/` against what `map` just
+ *     wrote to `mapping/`. Implies `--dir`.
+ *   file mode — diffs two individual mapping files.
  *   directory mode (`--dir`) — both args are directories of mapping files.
  *     Finds matching pairs by filename, diffs each, and produces an aggregate
  *     verdict. Layouts in `_layouts/` are diffed first (once instead of N
@@ -11,6 +13,6 @@
  * Exit codes (so a pipeline can gate on it):
  *   0 — PASS, or FIX without `--strict`
  *   1 — BLOCK (a selector broke with no semantic match), or FIX with `--strict`
- *   2 — bad usage / unreadable input
+ *   2 — bad usage / unreadable input / nothing to compare
  */
 export declare function runDiff(args: string[]): Promise<void>;

package/dist/cli/diff.js

@@ -36,12 +36,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runDiff = runDiff;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const aom_1 = require("../aom");
 const match_1 = require("../browser/match");
+const config_1 = require("../config");
 /**
- * `ia-qa-heal diff <baseline.json> <current.json> [--strict] [--json] [--dir]`
+ * `ia-qa-heal diff [baseline] [current] [--strict] [--json] [--dir]`
  *
- * Two modes:
- *   file mode (default) — diffs two individual mapping files.
+ * Three modes:
+ *   no arguments — the everyday case: the promoted `baseline/` against what `map` just
+ *     wrote to `mapping/`. Implies `--dir`.
+ *   file mode — diffs two individual mapping files.
  *   directory mode (`--dir`) — both args are directories of mapping files.
  *     Finds matching pairs by filename, diffs each, and produces an aggregate
  *     verdict. Layouts in `_layouts/` are diffed first (once instead of N
@@ -50,16 +54,35 @@ const match_1 = require("../browser/match");
  * Exit codes (so a pipeline can gate on it):
  *   0 — PASS, or FIX without `--strict`
  *   1 — BLOCK (a selector broke with no semantic match), or FIX with `--strict`
- *   2 — bad usage / unreadable input
+ *   2 — bad usage / unreadable input / nothing to compare
  */
 async function runDiff(args) {
     const strict = args.includes('--strict');
     const json = args.includes('--json');
-    const dirMode = args.includes('--dir');
-    const files = args.filter((a) => !a.startsWith('--'));
+    let dirMode = args.includes('--dir');
+    let files = args.filter((a) => !a.startsWith('--'));
+    // No arguments: compare the promoted reference to what `map` just captured. This is what
+    // everyone means by "diff", and leaving it unspoken is what pushed people into scripting
+    // their own baseline out of a `cp` — the loop this default exists to close.
+    if (files.length === 0) {
+        const base = (0, config_1.baselineDir)();
+        if (!fs.existsSync(base)) {
+            console.error(`❌ No baseline to compare against — ${rel(base)} does not exist.\n\n` +
+                `   Drift is a claim about two moments, and only one has been captured. Promote it:\n` +
+                `     ia-qa-heal map        capture the app as it is now\n` +
+                `     ia-qa-heal baseline   promote that capture to the reference\n\n` +
+                `   Then change the app, run \`ia-qa-heal map\` again, and \`ia-qa-heal diff\` has two\n` +
+                `   different moments to compare.`);
+            process.exitCode = 2;
+            return;
+        }
+        dirMode = true;
+        files = [base, (0, config_1.mappingDir)()];
+    }
     if (files.length !== 2) {
         const mode = dirMode ? '<baseline-dir> <current-dir>' : '<baseline.json> <current.json>';
-        console.error(`Usage: ia-qa-heal diff ${mode} [--strict] [--json]${dirMode ? '' : ' [--dir]'}`);
+        console.error(`Usage: ia-qa-heal diff [${mode}] [--strict] [--json]${dirMode ? '' : ' [--dir]'}\n` +
+            `       ia-qa-heal diff    (no arguments: baseline/ against mapping/)`);
         process.exitCode = 2;
         return;
     }
@@ -68,6 +91,11 @@ async function runDiff(args) {
         return;
     }
     const [baseline, current] = files.map((f) => readMapping(f));
+    if ((0, aom_1.isSameCapture)(baseline, current)) {
+        console.error(sameCaptureMessage(baseline.capturedAt));
+        process.exitCode = 2;
+        return;
+    }
     const report = (0, match_1.diffMappings)(baseline, current);
     if (json) {
         console.log(JSON.stringify(report, null, 2));
@@ -93,6 +121,10 @@ async function runDirDiff(baselineDir, currentDir, opts) {
         process.exit(2);
     }
     const reports = [];
+    // Pairs where both sides came out of the same `map` run. They cannot show drift, so they
+    // are 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 = [];
     // Diff layouts first
     const layoutsDir = path.join(baselineDir, '_layouts');
     if (fs.existsSync(layoutsDir)) {
@@ -106,6 +138,10 @@ async function runDirDiff(baselineDir, currentDir, opts) {
             try {
                 const baseline = readMapping(baselineFile);
                 const current = readMapping(currentFile);
+                if ((0, aom_1.isSameCapture)(baseline, current)) {
+                    stale.push(`_layouts/${name}`);
+                    continue;
+                }
                 const report = (0, match_1.diffMappings)(baseline, current);
                 reports.push({ name: `_layouts/${name}`, report, isLayout: true });
             }
@@ -128,6 +164,10 @@ async function runDirDiff(baselineDir, currentDir, opts) {
         try {
             const baseline = readMapping(baselineFile);
             const current = readMapping(currentFile);
+            if ((0, aom_1.isSameCapture)(baseline, current)) {
+                stale.push(name);
+                continue;
+            }
             const report = (0, match_1.diffMappings)(baseline, current);
             reports.push({ name, report, isLayout: false });
         }
@@ -135,6 +175,17 @@ async function runDirDiff(baselineDir, currentDir, opts) {
             console.error(`⚠ Skipping ${name}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    if (reports.length === 0 && stale.length > 0) {
+        console.error(`❌ Nothing to compare: ${stale.length === 1 ? 'the only pair is' : `all ${stale.length} pairs are`} ` +
+            `the same capture on both sides.\n\n` +
+            `   ${rel(baselineDir)} and ${rel(currentDir)} hold the same \`map\` run, so every file\n` +
+            `   would be compared against a copy of itself. A PASS would mean "nothing was compared",\n` +
+            `   not "nothing changed".\n\n` +
+            `   Change the app and run \`ia-qa-heal map\` again — then the baseline has something to be\n` +
+            `   a baseline against.`);
+        process.exitCode = 2;
+        return;
+    }
     if (reports.length === 0) {
         console.error('❌ No matching mapping pairs found.');
         process.exitCode = 2;
@@ -142,6 +193,8 @@ async function runDirDiff(baselineDir, currentDir, opts) {
     }
     // Aggregate verdict
     const aggregate = aggregateReports(reports);
+    if (stale.length > 0)
+        aggregate.staleExcluded = stale;
     if (opts.json) {
         console.log(JSON.stringify(aggregate, null, 2));
     }
@@ -217,6 +270,12 @@ function printAggregate(agg, reports, baselineDir, currentDir) {
             `${pr.counts.ok} ok · ${pr.counts.healable} heal · ${pr.counts.lost} lost · ${pr.counts.added} new`);
     }
     console.log('');
+    if (agg.staleExcluded?.length) {
+        const n = agg.staleExcluded.length;
+        console.log(`   ⏸  ${n} ${n === 1 ? 'contract' : 'contracts'} left out of the verdict — same capture on both`);
+        console.log(`      sides, so ${n === 1 ? 'it cannot' : 'they cannot'} show drift: ${agg.staleExcluded.join(', ')}`);
+        console.log(`      Re-map ${n === 1 ? 'it' : 'them'} to bring ${n === 1 ? 'it' : 'them'} back into the gate.`);
+    }
     if (agg.totals.lost > 0) {
         console.log('   ⛔ Some selectors are lost — a human must fix or delete the test.');
     }
@@ -225,6 +284,20 @@ function printAggregate(agg, reports, baselineDir, currentDir) {
     }
     console.log('');
 }
+function sameCaptureMessage(capturedAt) {
+    return (`❌ Both sides are the same capture (capturedAt ${capturedAt}).\n\n` +
+        `   A capture cannot drift from itself, so there is no verdict to give. A PASS here would\n` +
+        `   mean "nothing was compared" — not "nothing changed" — and a gate that reports green\n` +
+        `   without looking is worse than no gate at all.\n\n` +
+        `   Drift needs two moments:\n` +
+        `     ia-qa-heal baseline   promote this capture to the reference\n` +
+        `     …change the app…\n` +
+        `     ia-qa-heal map        capture it again\n` +
+        `     ia-qa-heal diff       now there are two moments to compare`);
+}
+function rel(p) {
+    return path.relative(process.cwd(), p) || p;
+}
 function readMapping(file) {
     let raw;
     try {