@ia-qa/self-healing 1.6.6 → 1.6.8

package/README.md

@@ -16,7 +16,29 @@ One command. `ia-qa-heal run` runs your suite, watches it break, diffs the live
 
 *Real commands against a live site, real stdout — only the typing speed is synthesised.*
 
-## Quick start
+## Easiest start — have your agent set it up
+
+If you already work with Claude Code, Cursor, Copilot or another coding agent, don't configure this
+by hand. Paste this to it:
+
+```text
+Install and set up @ia-qa/self-healing in this project.
+1. First run `npx -y -p @ia-qa/self-healing ia-qa-heal skill --print` and follow it.
+   That output is the authoritative doc — do not guess any command or flag from memory.
+2. Register the MCP server so you can drive it yourself:
+   command `npx`, args ["-y", "-p", "@ia-qa/self-healing", "ia-qa-heal-mcp"].
+3. Read my e2e tests and my router, propose the page list for .ia-qa/config.json,
+   and wait for me to confirm before mapping anything.
+4. Then explain to me, in five lines: what map / baseline / diff / fix each do,
+   and which locators you will never rewrite without asking me.
+```
+
+Step 1 matters more than it looks: this package is newer than most models' training data, so an agent
+left to improvise will invent flags that don't exist. `skill --print` hands it the real instructions —
+including [the four prohibitions](#working-with-an-ai-agent--ia-qa-heal-skill) — before it touches
+anything. Step 4 is how you check it actually read them instead of guessing.
+
+## Quick start — by hand
 
 ```bash
 npx -y -p @ia-qa/self-healing ia-qa-heal init      # wizard → .ia-qa/config.json
@@ -37,7 +59,7 @@ npx ia-qa-heal init
 
 An agent that asks a browser where a button went is doing by hand what `.ia-qa/mapping/*.json` already answers offline: every interactive element's **role, accessible name and selector**, captured. A `link` the suite still calls a `button` shows up in one `grep`.
 
-`ia-qa-heal skill` installs that reflex — plus the rules that must not be broken — as a skill your agent loads:
+`ia-qa-heal skill` installs that reflex — plus the rules that must not be broken — as a skill your agent loads (this is what step 1 of the [paste-block above](#easiest-start--have-your-agent-set-it-up) makes it read):
 
 ```bash
 ia-qa-heal skill                 # where it would go, and whether it is current — writes nothing
@@ -213,6 +235,56 @@ Run again with --apply to add the uncovered pages to config.pages.
 
 Then `ia-qa-heal map` captures their contracts as usual. Discovery never maps, heals, or edits a test — it only ever edits `config.json`, and only with `--apply`.
 
+## The console — `ia-qa-heal ui`
+
+The report tells you what drifted. The console lets you **act on it**.
+
+```bash
+npx ia-qa-heal ui
+```
+
+…or, for someone who should never have to open a terminal at all:
+
+```bash
+npx ia-qa-heal ui --shortcut     # once per project
+```
+
+That puts an icon on the desktop — the ia-qa logo, wired to *this* project. Double-click it: the console starts and the browser opens on it. No URL is ever typed or copied, which is also how the session token stays out of a human's hands. Click it twice and it reuses the console it already opened. **Closing the browser tab stops the server**, so a click never leaves a process running behind your back (`--keep-alive` opts out).
+
+It opens a local page with three things the terminal cannot give you:
+
+- **The rows waiting on a human** — every `ambiguous`, `lost` and `rebound` row, each with a **highlighted crop** of the candidates as they look on the page right now (needs `map --screenshots`). When five identical "Copy" buttons exist, the row's selector tells you nothing; the picture tells you which one. Alongside them, the `file:line` of every test that will break.
+- **The verbs as buttons** — capture, ingest, diff, audit, check, preview/apply the rewrites — with the output streamed back.
+- **The run history as charts** — verdicts over time, mean coverage, and which pages actually churn.
+
+**How it is kept safe**, because a server on a QA's machine is not free:
+
+| | |
+|---|---|
+| **Loopback only** | bound to `127.0.0.1`, never `0.0.0.0` — in a container that would be a published port |
+| **A one-time token** | in the URL, required on every request. Without it, *any* page open in your browser could `fetch` the console and read the contracts of your authenticated app, or trigger an action |
+| **Host pinning** | requests whose `Host` is not loopback are refused, which is the DNS-rebinding case a token alone does not cover |
+| **No new authority** | buttons spawn this package's own CLI with a fixed argv from an allowlist — never a string from the request. The console can do **nothing the CLI would refuse**: an `ambiguous` locator is never rewritten from here either |
+
+Nothing is uploaded, there is no telemetry and no external asset — the page is inline HTML/CSS/JS and every byte it shows came off your disk. It refuses to start under CI, where an interactive surface would just hang; use `--json`, `--junit` or the exit code there.
+
+### Several projects — the switcher
+
+The header carries a **Project** dropdown as soon as there is more than one. It is governed by a single rule:
+
+> **A project is reachable only if you opened a console in it.**
+
+Nothing scans your disk. `~/.ia-qa/projects.json` is a consent list, and there are exactly two ways to consent: run `ia-qa-heal ui` in a folder, or pick **＋ Add another project…** in the dropdown and give the path. Switching between listed projects resolves the requested directory against that list *exactly* — a folder outside it cannot be named. Entries whose project has been deleted are dropped rather than offered, and actions are handed `--config <active project>` explicitly rather than inheriting anything.
+
+Adding from the console is a deliberate action by whoever holds the session token — the same token that already authorizes *Repair my test files*. What the list defends against is a **drive-by**: another page in your browser reaching localhost. That is stopped by the token and the `Host` check, not by making you walk to a terminal.
+
+```bash
+ia-qa-heal ui --forget            # clear the whole list
+ia-qa-heal ui --forget ../shop    # drop one project
+```
+
+Forgetting only removes a folder from the switcher — it deletes nothing in the project, and opening a console there again re-adds it. `IAQA_HOME` relocates the list (useful on a shared machine).
+
 ## Visualize the app — `ia-qa-heal graph`
 
 Turn the mappings you already have into a **navigation graph** (page → page, derived from the `href` on each page's links — the same engine `map` uses for `_overview.md`). Read-only: it never rewrites your mapping files, it just renders them.
@@ -611,6 +683,50 @@ jobs:
 
 `diff` with no arguments compares the committed `.ia-qa/baseline/` against what `map` just re-captured — which is why the baseline has to be in git. Add `--report drift-report.html` to attach a branded HTML report to the build, and `--strict` to fail on FIX too. The full workflow (report upload, artifact, `--strict`) is in **[TUTORIAL.md → Putting it in CI](TUTORIAL.md#8-putting-it-in-ci)**.
 
+### Trend charts for free — `--junit`
+
+`diff --junit` and `run --junit` write the verdict as **JUnit XML**, which Jenkins, GitLab, CircleCI, Azure DevOps and the GitHub Actions reporters all ingest natively — including the per-build history graph. You get the trend without this package rendering anything in CI.
+
+```bash
+npx ia-qa-heal diff --junit reports/selector-drift.xml
+```
+
+It is language-agnostic by construction: what it describes is your **contract**, not your suite, so a Cypress/JS, Selenium/Python or Playwright/.NET project produces identically shaped XML.
+
+| contract row | JUnit | why |
+|---|---|---|
+| `ok` | pass | the locator still finds the same element |
+| `renamed` | pass + `system-out` | the selector still works; the label moved |
+| `healable` | failure `type="healable"` | broken today — auto-repairable, but broken |
+| `ambiguous` · `lost` · `rebound` | failure, typed | broken, and no deterministic repair exists |
+| name drift | failure `type="name-drift-*"` | a name-anchored locator names nothing now |
+| page not compared | **skipped** | not measured — reporting it as a pass would be the false green this tool exists to prevent |
+
+> ⚠️ **Publish it under its own file pattern**, separate from your suite's results. Merged into one trend, the two sets of numbers stop meaning anything.
+
+`run --json` (and `diff --json`) give the same verdict as one JSON document on stdout. For `run`, every other line moves to stderr so a pipe stays parseable.
+
+### The trend, locally — `ia-qa-heal history`
+
+Every `diff` and `run` appends one line to `.ia-qa/history.jsonl`: verdict, counters, capture source, page coverage and the git commit. It is the one thing no single invocation can reconstruct afterwards, so it is recorded as it happens.
+
+```
+📈 Run history  ·  6 recorded
+   6 comparable runs captured by `map`  ·  67% ended with drift  ·  100% mean coverage
+
+   ⛔ BLOCK  8/9/26, 6:25 PM     3 drifted  2/2 pages
+   ✅ PASS   8/9/26, 6:26 PM     0 drifted  2/2 pages
+   …
+   🔥 Where the churn lives
+      checkout  13 drifted elements across 4 runs
+```
+
+Runs captured **differently** — a `map` baseline versus a live suite capture — are held **out** of the trend and named, never averaged in: the two read a page differently, so charting both would invent a trend out of a capture artifact. Same for a run that covered far fewer pages than the rest.
+
+The file is small, deterministic text (unlike `_shots/`), so committing it is defensible if you want the trend to survive across machines and CI.
+
+Agents get the same numbers through the MCP tool **`heal_history`** — one `summarize()`, three renderings (terminal, console charts, MCP).
+
 ## Map artifacts
 
 Beyond one contract per page, every `map` run rebuilds two views of the whole app. Both are derived entirely from the mappings on disk (no extra page visit) and rebuilt on every run, including `map <page>`, so they never drift out of date.

package/TUTORIAL.md

@@ -12,9 +12,9 @@
 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)
-6. [Your first real workflow](#6-your-first-real-workflow-the-whole-point)
+6. [Your first real workflow](#6-your-first-real-workflow-the-whole-point) — including [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)
+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)
 9. [Optional: AI suggestions (BYOK)](#9-optional-ai-suggestions-for-the-lost-ones-byok)
 10. [Troubleshooting](#10-troubleshooting)
 11. [FAQ](#11-faq)
@@ -83,7 +83,30 @@ Whatever it uses, it tells you: `Browser: system browser (channel "chrome")`.
 
 *Use this if you have Claude Code, Claude Desktop, Cursor, or another MCP-compatible agent. You'll talk to your app in plain English.*
 
-### Step 4.1 — Add the tool to your agent
+### Step 4.0 — The shortcut: let your agent do the whole setup
+
+The steps below are the manual version. If your agent can edit files in your project (Claude Code, Cursor, Copilot in your IDE), just paste this to it and skip straight to step 4.4 below:
+
+```text
+Install and set up @ia-qa/self-healing in this project.
+1. First run `npx -y -p @ia-qa/self-healing ia-qa-heal skill --print` and follow it.
+   That output is the authoritative doc — do not guess any command or flag from memory.
+2. Register the MCP server so you can drive it yourself:
+   command `npx`, args ["-y", "-p", "@ia-qa/self-healing", "ia-qa-heal-mcp"].
+3. Read my e2e tests and my router, propose the page list for .ia-qa/config.json,
+   and wait for me to confirm before mapping anything.
+4. Then explain to me, in five lines: what map / baseline / diff / fix each do,
+   and which locators you will never rewrite without asking me.
+```
+
+Two things to know about that prompt, because they are the difference between it working and it wasting your afternoon:
+
+- **Step 1 is not optional politeness.** This package is newer than most models' training data. An agent left to improvise invents flags that don't exist, they fail, and you conclude the tool is broken. `skill --print` hands it the real instructions — including the four things it must never do on its own — before it touches anything.
+- **Step 4 is your check.** If the five-line explanation is vague or mentions a verb that isn't `map`, `baseline`, `diff` or `fix`, it didn't read the skill. Tell it to run step 1 again.
+
+You will still have to **restart your agent** (step 4.2 below) after it writes the MCP config — it can't load a server it registered mid-conversation.
+
+### Step 4.1 — Add the tool to your agent (manual)
 
 Find your agent's MCP config file and add the `ia-qa-self-healing` block below.
 
@@ -134,6 +157,8 @@ Then point the config at the built file (use the **absolute** path):
 
 ### Step 4.1b — Teach your agent how to use it (recommended)
 
+*Skip this if you used step 4.0 — that prompt already made your agent do it.*
+
 The MCP block above gives your agent four *tools*. It does not give it the **judgment** to use them: when to read the contract instead of opening a browser, which verb answers which question, and — most importantly — which locators it must never rewrite on its own.
 
 ```bash
@@ -434,6 +459,49 @@ Three optional config keys make it better (`ia-qa-heal init` asks for them):
 
 `run` keeps every judgment where it was: **BLOCK stops for you**, healable rewrites are shown as a dry run and applied only after you confirm (`--yes` for CI), and nothing is ever committed. **After applying the fix it re-runs your suite once more — without `IAQA_CAPTURE`, so it checks rather than re-maps — and reports whether the tests pass now.** The exit code follows that verdict (`0` green, `1` still failing), so CI catches a fix that rewrote the selector but left the test red. `--no-verify` skips the re-run; with `--report`, the HTML also lists the applied `old → new` edits (file + lines) and the verify verdict.
 
+### Step 6.8 — No terminal? Open the console
+
+Everything above is a command line. If the person who has to *decide* is a manual QA, that is a
+wall — and the decision is the one thing the tool cannot take from them.
+
+```bash
+ia-qa-heal ui
+```
+
+A local page opens in your browser with three things a terminal cannot give you:
+
+- **The rows waiting on a human.** Each `ambiguous` / `lost` / `rebound` row, with a **highlighted
+  picture** of each candidate as it looks on the page right now (needs `map --screenshots`), the
+  `file:line` of every test that will break, and — the part that matters — **a sentence saying what
+  to do about it**. When five identical "Copy" buttons exist, `div:nth-of-type(4) > … > button`
+  tells you nothing; the picture tells you which one.
+- **The verbs as buttons**, in plain words: *Look at the app again*, *Check for changes*,
+  *Repair my test files ✎*. Every result is a sentence, not an exit code, with the raw output one
+  click away.
+- **The run history as charts** — see [§8.3](#83-the-trend-ia-qa-heal-history).
+
+Once, per project, so nobody ever types a command again:
+
+```bash
+ia-qa-heal ui --shortcut
+```
+
+That puts an icon on the desktop, bound to *this* project. Double-click → the console starts and
+the browser opens on it. `ia-qa-heal init` offers to do this for you at the end of setup.
+
+**What it is not:** it is not a website, and nothing is hosted. The server binds `127.0.0.1` only,
+every request needs a one-time token that lives in the URL the tool opened, and requests whose
+`Host` is not loopback are refused. Closing the browser tab stops the server, so a click never
+leaves a process running behind your back. It can do **nothing the CLI would refuse** — an
+`ambiguous` locator is never rewritten from the console either. It refuses to start under CI, where
+it would simply hang.
+
+Working on several projects? The header carries a **Project** dropdown. Pick
+**＋ Add another project…** and paste the folder's path — it must already contain a `.ia-qa`
+directory (run `ia-qa-heal init` there once if not). Everything you add is remembered, so it is one
+click from then on, and `ia-qa-heal ui --forget [dir]` takes it back out (deleting nothing inside
+the project).
+
 ---
 
 ## 7. Reading the verdict
@@ -523,6 +591,67 @@ 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).
 
+### 8.2 Trend charts for free — `--junit`
+
+Your CI already knows how to chart a test run over time. Give it the verdict in the format it
+speaks and you get the history graph without this tool drawing anything:
+
+```bash
+npx ia-qa-heal diff --junit reports/selector-drift.xml
+```
+
+Jenkins, GitLab, CircleCI, Azure DevOps and the GitHub Actions reporters all ingest JUnit XML —
+including the per-build trend. It is **language-agnostic by construction**: what it describes is
+your *contract*, not your suite, so a Cypress/JS, Selenium/Python or Playwright/.NET project
+produces identically shaped XML.
+
+| Your contract | In the CI |
+|---|---|
+| `ok` | pass |
+| `renamed` | pass, with the label change in the output |
+| `healable` | failure, typed `healable` (broken today — repairable, but broken) |
+| `ambiguous` · `lost` · `rebound` | failure, typed |
+| a renamed label your tests use | failure, typed `name-drift-*` |
+| a page that could not be compared | **skipped** |
+
+That last row is the one to notice: a page left out of the verdict is **not** a pass, and reporting
+it as `skipped` puts the coverage gap in your CI's own summary instead of only in our log.
+
+> ⚠️ **Publish it under its own file pattern**, separate from your suite's results. Merged into one
+> trend, the two sets of numbers stop meaning anything.
+
+`--json` gives the same verdict as one document on stdout (`run --json` moves every human line to
+stderr, so a pipe stays parseable).
+
+### 8.3 The trend — `ia-qa-heal history`
+
+Every `diff` and `run` appends one line to `.ia-qa/history.jsonl`: verdict, counts, how the capture
+was taken, how many pages it covered, and the git commit. It is the one thing no single run can
+reconstruct afterwards — so it is recorded as it happens, and the runs you have not made yet are
+the only ones you can still get.
+
+```
+$ ia-qa-heal history
+
+📈 Run history  ·  7 recorded
+   7 comparable runs captured by `map` · 71% ended with drift · 100% mean coverage
+
+   ⛔ BLOCK  8/9/26, 6:25 PM     3 drifted  2/2 pages
+   ✅ PASS   8/9/26, 6:26 PM     0 drifted  2/2 pages
+   …
+   🔥 Where the churn lives
+      checkout  16 drifted elements across 5 runs
+```
+
+Runs captured **differently** — a `map` baseline versus a live suite capture — are held **out** of
+the trend and named, never quietly averaged in: the two read a page differently, so charting both
+would invent a trend out of a capture artifact. Same for a run that covered far fewer pages than
+the rest.
+
+The file is small, deterministic text (unlike `_shots/`), so committing it is defensible if you
+want the trend to survive across machines and CI. Agents get the same numbers through the
+`heal_history` MCP tool.
+
 ---
 
 ## 9. Optional: AI suggestions for the `lost` ones (BYOK)
@@ -655,6 +784,12 @@ npx ia-qa-heal check                      # is the app sound? dead links · unna
 npx ia-qa-heal graph --format markdown    # the navigation graph, one card per page (RAG chunk / Confluence)
 npx ia-qa-heal run                        # the whole loop: capture (your suite, IAQA_CAPTURE=1) → diff → confirm → fix → re-run to verify
 
+npx ia-qa-heal ui                         # the local console: decide with pictures, verbs as buttons, history as charts
+npx ia-qa-heal ui --shortcut              # once per project: a desktop icon that opens it in one click
+npx ia-qa-heal ui --forget [dir]          # drop a project from the console's switcher
+npx ia-qa-heal history [--json]           # the trend: verdicts over time, coverage, which pages churn
+npx ia-qa-heal diff --junit reports/x.xml # JUnit XML — your CI charts the trend natively
+
 npx ia-qa-heal skill --install            # teach your AI agent the rules (→ .claude/skills/ia-qa-heal/)
 ```
 

package/dist/cli/args.js

@@ -19,14 +19,16 @@ exports.KNOWN_FLAGS = {
     discover: ['--sitemap', '--crawl', '--no-reveal', '--strict-host', '--apply', '--max', '--depth'],
     map: ['--screenshots'],
     baseline: [],
-    diff: ['--strict', '--json', '--dir', '--report', '--open'],
+    diff: ['--strict', '--json', '--junit', '--dir', '--report', '--open'],
     fix: ['--dry-run', '--locators', '--dir'],
     ingest: [],
     audit: ['--strict', '--json'],
     check: ['--strict', '--json', '--offline'],
     graph: ['--format', '--kind', '--out', '--open'],
-    run: ['--yes', '--no-verify', '--locators', '--report', '--open'],
+    run: ['--yes', '--no-verify', '--locators', '--report', '--junit', '--json', '--open'],
     skill: ['--install', '--user', '--dir', '--print', '--force'],
+    history: ['--json', '--limit'],
+    ui: ['--port', '--no-open', '--shortcut', '--keep-alive', '--forget'],
 };
 function rejectUnknownFlags(command, args) {
     const known = exports.KNOWN_FLAGS[command];

package/dist/cli/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AA2BA,gDAeC;AA1CD;;;;;;;;;;;GAWG;AACU,QAAA,WAAW,GAAsC;IAC5D,IAAI,EAAE,EAAE;IACR,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC;IACjG,GAAG,EAAE,CAAC,eAAe,CAAC;IACtB,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IAC3D,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC;IACzC,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC7B,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC1C,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAChD,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAC;IACjE,KAAK,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;CAC9D,CAAC;AAEF,SAAgB,kBAAkB,CAAC,OAAe,EAAE,IAAc;IAChE,MAAM,KAAK,GAAG,mBAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAChC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,eAAe,OAAO,0FAA0F;gBAC9G,4GAA4G;gBAC5G,8FAA8F,CACjG,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,qBAAqB,OAAO,8CAA8C,CAAC,CAAC;IAChH,CAAC;AACH,CAAC"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AA6BA,gDAeC;AA5CD;;;;;;;;;;;GAWG;AACU,QAAA,WAAW,GAAsC;IAC5D,IAAI,EAAE,EAAE;IACR,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC;IACjG,GAAG,EAAE,CAAC,eAAe,CAAC;IACtB,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IACtE,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC;IACzC,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC7B,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC1C,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAChD,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC;IACtF,KAAK,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;IAC7D,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC9B,EAAE,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,CAAC;CACtE,CAAC;AAEF,SAAgB,kBAAkB,CAAC,OAAe,EAAE,IAAc;IAChE,MAAM,KAAK,GAAG,mBAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,SAAS;QAChC,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,eAAe,OAAO,0FAA0F;gBAC9G,4GAA4G;gBAC5G,8FAA8F,CACjG,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,qBAAqB,OAAO,8CAA8C,CAAC,CAAC;IAChH,CAAC;AACH,CAAC"}

package/dist/cli/diff.d.ts

@@ -1,6 +1,6 @@
 import { Usage } from '../ingest';
 import { NameDriftFinding } from '../nameDrift';
-import { FixOutcome } from '../htmlReport';
+import { FixOutcome, ReportEvidence } from '../htmlReport';
 /**
  * `ia-qa-heal diff [baseline] [current] [--strict] [--json] [--dir]`
  *
@@ -53,6 +53,11 @@ export declare function openInBrowser(file: string): void;
  */
 export declare function pageUrlMap(): Map<string, string> | undefined;
 export declare function pageShotMap(): Map<string, string> | undefined;
+export declare function buildEvidence(reports: Array<{
+    name: string;
+    report: Report;
+    isLayout: boolean;
+}>, currentDir: string): ReportEvidence | undefined;
 /** Render the drift report to `reportPath` and announce it. Never throws on a bad write path to callers of the gate — reporting is a side effect, not the verdict. */
 export declare function writeDriftReport(reportPath: string, agg: DirReport, reports: Array<{
     name: string;

package/dist/cli/diff.js

@@ -38,6 +38,7 @@ exports.openHint = openHint;
 exports.openInBrowser = openInBrowser;
 exports.pageUrlMap = pageUrlMap;
 exports.pageShotMap = pageShotMap;
+exports.buildEvidence = buildEvidence;
 exports.writeDriftReport = writeDriftReport;
 exports.runDiff = runDiff;
 exports.printNameDrift = printNameDrift;
@@ -55,7 +56,9 @@ const captureMerge_1 = require("../captureMerge");
 const nameHint_1 = require("../nameHint");
 const nameDrift_1 = require("../nameDrift");
 const htmlReport_1 = require("../htmlReport");
+const evidence_1 = require("../evidence");
 const summary_1 = require("./summary");
+const emit_1 = require("./emit");
 /**
  * `ia-qa-heal diff [baseline] [current] [--strict] [--json] [--dir]`
  *
@@ -177,10 +180,91 @@ function pageShotMap() {
     }
     return shots.size > 0 ? shots : undefined;
 }
+/**
+ * Highlighted crops for every row a human has to decide, assembled from what
+ * `map --screenshots` left on disk.
+ *
+ * Only `ambiguous` and `rebound` rows are considered — the ones where the tool
+ * has stopped and handed over. Everything degrades to nothing: no screenshots,
+ * no rects, an unreadable mapping, or a page over budget all produce a report
+ * identical to the one this function did not exist for.
+ *
+ * The budget is separate from (and smaller than) the page-thumbnail budget
+ * because these images serve a decision rather than an illustration, and a
+ * report nobody can open in a browser helps no one. Pages are taken
+ * most-decisions-first, so the budget buys the most answers.
+ */
+const EVIDENCE_BUDGET_BYTES = 4 * 1024 * 1024;
+function buildEvidence(reports, currentDir) {
+    const needing = reports
+        // A layout is compared as a set across pages; it has no single screenshot to
+        // crop from, so there is nothing here to show for it.
+        .filter((r) => !r.isLayout)
+        .map(({ name, report }) => ({
+        name,
+        rows: report.rows.filter((r) => r.status === 'ambiguous' || r.rebound === true),
+    }))
+        .filter((p) => p.rows.length > 0)
+        .sort((a, b) => b.rows.length - a.rows.length);
+    if (needing.length === 0)
+        return undefined;
+    const css = [];
+    const rows = {};
+    let spent = 0;
+    for (const p of needing) {
+        const shot = (0, evidence_1.loadPageShot)(p.name);
+        if (!shot)
+            continue;
+        let after;
+        try {
+            after = JSON.parse(fs.readFileSync(path.join(currentDir, `${p.name}.json`), 'utf8'));
+            if (!Array.isArray(after.elements))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const cls = `pg-${p.name.replace(/[^a-zA-Z0-9_-]/g, '-')}`;
+        const pageRows = {};
+        let usesImage = false;
+        for (const r of p.rows) {
+            const ev = (0, evidence_1.rowEvidence)(r, after, shot);
+            if (!ev)
+                continue;
+            if (ev.nowAt || ev.candidates.length > 0)
+                usesImage = true;
+            pageRows[r.selector] = {
+                ...(ev.nowAt ? { nowAt: { ...ev.nowAt, crop: { cls, ...ev.nowAt.crop } } } : {}),
+                candidates: ev.candidates.map((c) => ({ ...c, crop: { cls, ...c.crop } })),
+                ...(ev.note ? { note: ev.note } : {}),
+            };
+        }
+        if (Object.keys(pageRows).length === 0)
+            continue;
+        if (usesImage) {
+            if (spent + shot.dataUri.length > EVIDENCE_BUDGET_BYTES)
+                continue;
+            css.push(`.${cls}{background-image:url("${shot.dataUri}")}`);
+            spent += shot.dataUri.length;
+        }
+        rows[p.name] = pageRows;
+    }
+    if (Object.keys(rows).length === 0)
+        return undefined;
+    return { css: css.join('\n'), rows };
+}
 /**
  * When a directory of contracts was captured. Read off any one of them — `map`
  * stamps them all in the same run.
  */
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function capturedAtOf(dir) {
     try {
         const file = fs.readdirSync(dir).find((f) => f.endsWith('.json') && !f.startsWith('.') && !f.startsWith('_'));
@@ -209,6 +293,9 @@ function writeDriftReport(reportPath, agg, reports, baselineDirPath, currentDirP
         pageShots: pageShotMap(),
         baselineCapturedAt: capturedAtOf(baselineDirPath),
         currentCapturedAt: capturedAtOf(currentDirPath),
+        // Single-file mode passes two files, not two directories; the evidence for a
+        // page lives beside its mapping either way.
+        evidence: buildEvidence(reports, isDirectory(currentDirPath) ? currentDirPath : path.dirname(currentDirPath)),
     });
     const dest = path.resolve(reportPath);
     fs.writeFileSync(dest, html, 'utf8');
@@ -229,7 +316,8 @@ function refuseToCompare(reason, human, hint, json) {
 }
 async function runDiff(args) {
     (0, captureMerge_1.mergeCapturesAnnounced)();
-    const { reportPath: explicitReport, rest: argsNoReport } = takeReportFlag(args);
+    const { reportPath: explicitReport, rest: afterReport } = takeReportFlag(args);
+    const { value: junitPath, rest: argsNoReport } = (0, emit_1.takeValueFlag)(afterReport, '--junit', emit_1.JUNIT_DEFAULT_PATH);
     const strict = argsNoReport.includes('--strict');
     const json = argsNoReport.includes('--json');
     const open = argsNoReport.includes('--open');
@@ -262,7 +350,7 @@ async function runDiff(args) {
         return;
     }
     if (dirMode) {
-        await runDirDiff(files[0], files[1], { strict, json, reportPath, open });
+        await runDirDiff(files[0], files[1], { strict, json, reportPath, open, junitPath });
         return;
     }
     const [baseline, current] = files.map((f) => readMapping(f));
@@ -284,10 +372,19 @@ async function runDiff(args) {
         printHuman(report, files, usage);
         printNameDrift(report.nameDrift);
     }
+    const single = [{ name: path.basename(files[1]).replace(/\.json$/, ''), report, isLayout: false }];
+    const singleAgg = aggregateReports(single);
     if (reportPath) {
-        const single = [{ name: path.basename(files[1]).replace(/\.json$/, ''), report, isLayout: false }];
-        writeDriftReport(reportPath, aggregateReports(single), single, files[0], files[1], usage, open);
+        writeDriftReport(reportPath, singleAgg, single, files[0], files[1], usage, open);
     }
+    if (junitPath) {
+        (0, emit_1.writeJUnit)(junitPath, singleAgg, single, {
+            baseUrl: (0, config_1.configuredBaseUrl)(),
+            baselineName: path.basename(files[0]),
+            currentName: path.basename(files[1]),
+        });
+    }
+    (0, emit_1.recordDriftRun)('diff', singleAgg, { baseUrl: (0, config_1.configuredBaseUrl)() });
     const failing = report.verdict === 'BLOCK' || (strict && report.verdict === 'FIX');
     process.exitCode = failing ? 1 : 0;
     if (!json)
@@ -388,6 +485,19 @@ async function runDirDiff(baselineDir, currentDir, opts) {
     if (opts.reportPath) {
         writeDriftReport(opts.reportPath, aggregate, reports, baselineDir, currentDir, usage, opts.open);
     }
+    if (opts.junitPath) {
+        (0, emit_1.writeJUnit)(opts.junitPath, aggregate, reports, {
+            baseUrl: (0, config_1.configuredBaseUrl)(),
+            baselineName: path.basename(baselineDir),
+            currentName: path.basename(currentDir),
+        });
+    }
+    (0, emit_1.recordDriftRun)('diff', aggregate, {
+        currentDir,
+        reports,
+        stale,
+        baseUrl: (0, config_1.configuredBaseUrl)(),
+    });
     const failing = aggregate.verdict === 'BLOCK' || (opts.strict && aggregate.verdict === 'FIX');
     process.exitCode = failing ? 1 : 0;
     if (!opts.json)