@ia-qa/self-healing 1.6.16 → 1.7.0

package/README.md

@@ -173,7 +173,63 @@ Everything the tool needs lives in **one JSON file**, written for you by `ia-qa-
 - **"My diff BLOCKs on links that just… rotate (a news feed, a blog widget)?"** → That is content churn, not UI drift: the feed's links entered the contract as if they were buttons, and the next capture caught the feed mid-rotation. Name what rotates in `"volatile"` (see above) and it never enters a contract again — the diff even prints a hint pointing here when a BLOCK is made of lost external links.
 - **"The same rows come back as `renamed` every run — a cart counter, a call total, a clock."** → Only the *label* is moving, so only the label should stop being compared: put the pattern in `"nameMask"` (`"Cart (*)"`), not in `"volatile"`. `volatile` would delete the element from the contract — counter, button, href and coverage together — so a real selector break on it would go unnoticed forever; a mask keeps all of that gating and exempts the name alone. The diff prints the exact config line to paste when it spots the pattern. Two masks it refuses to apply, and says so: one that would hide a label your tests locate by name (that is a red suite behind a green gate), and one that would leave two elements of the same role wearing one name (a locator coin flip the mask itself created).
 - **"How do I add a page behind a click, not a URL?"** → add `steps` to that page (see `billing` above): a list of `{ "click": { "role": "...", "name": "..." } }`. Named by role + accessible name, exactly like the contract — never a CSS selector.
-- **"My app spans several domains behind a single sign-on (federated SSO) — does `map` cover it?"** → **Not with one `auth` block.** `auth` runs **one** login against **one** domain, before the first page. A federated IdP that re-challenges each project/domain with its own scope (`?projectName=…`, a different sub-domain per portal) is never satisfied by that single login — the second domain bounces back to a login the first one never covered, and the page maps empty (map now warns when an authenticated target returns 0 elements). Two ways through: **one `.ia-qa/` per domain/portal**, each selected with `--config <dir>` (see **Monorepos** below), or **`ia-qa-heal run` with `IAQA_CAPTURE=1`** so your own suite — which already handles the full SSO dance (cookies, redirects, per-project scope) — does the auth and the contract is captured during that real run. For a multi-portal app, capture-during-run is the intended path; `map --auth` is for single-domain apps.
+- **"My app spans several domains behind a single sign-on (federated SSO) — does `map` cover it?"** → **Not with one `auth` block.** `auth` runs **one** login against **one** domain, before the first page. A federated IdP that re-challenges each project/domain with its own scope (`?projectName=…`, a different sub-domain per portal) is never satisfied by that single login — the second domain bounces back to a login the first one never covered, and the page maps empty (map now warns when an authenticated target returns 0 elements). Two ways through: **one `.ia-qa/` per domain/portal**, each selected with `--config <dir>` (see **Monorepos** below), or **`ia-qa-heal run` with `IAQA_CAPTURE=1`** so your own suite — which already handles the full SSO dance (cookies, redirects, per-project scope) — does the auth and the contract is captured during that real run. And since 1.7.0 there is a third, which is the general one: **`ia-qa-heal login`** — you log in once in a visible browser, whatever the app asks, and `map` reuses that session (see below). For a multi-portal app, capture-during-run is the intended path in CI; `map --auth` is for single-domain apps.
+
+### Behind any login — `ia-qa-heal login`
+
+`auth` fills a form: a username field, a password field, a submit button. That is *one shape of
+login*, and plenty of apps do not have it — federated SSO, MFA, a consent screen, a magic link, a
+device check. No list of selectors gets through any of those, so for those apps "add an `auth`
+block" is not an answer at all.
+
+```bash
+ia-qa-heal login            # opens a visible browser at your first configured page
+                            # you log in there, however your app asks
+ia-qa-heal map              # reuses that session — no auth block needed
+```
+
+It models nothing about your login, which is exactly why it works anywhere: the human does
+whatever the app requires, and the browser session is saved to `.ia-qa/session.json` in
+Playwright's `storageState` shape. `map` and `discover --crawl` pick it up automatically and say
+so; it takes precedence over `auth` when both exist (you ran `login` *because* the form fill
+could not get through — re-running it silently would be the tool arguing with you).
+
+- **That file is a secret.** It holds live cookies: whoever has it is logged in as you. It never
+  leaves your machine — nothing here uploads it — and `login` writes `.ia-qa/.gitignore` so a
+  commit cannot carry it.
+- **It needs a person.** It refuses without a TTY and under CI, and an AI agent driving the CLI
+  cannot perform it: the agent hands the step to you by name.
+- **It expires.** When the session dies, `map` hits the login wall again and says to re-run
+  `login` — it never silently maps a login form under the name of your dashboard.
+- **It is not a CI mechanism.** In a pipeline, use `auth` (reproducible, secrets from env/SSM) or
+  capture-during-run (`IAQA_CAPTURE=1` + `testCommand`, your own suite logs itself in).
+
+`--url <path>` opens a page other than the first one in `config.pages`.
+
+#### You already have a session — use it
+
+An authenticated Playwright suite usually writes a `storageState` in `globalSetup`. Point at
+it and skip logging in a second time:
+
+```bash
+ia-qa-heal map --session playwright/.auth/user.json   # a flag
+IAQA_SESSION=playwright/.auth/user.json ia-qa-heal map # or an env var
+```
+
+```jsonc
+// …or in .ia-qa/config.json, so every verb picks it up:
+"session": "playwright/.auth/user.json"
+```
+
+Precedence: `--session` → `IAQA_SESSION` → `config.session` → the file `login` wrote. Relative
+paths resolve from the project root, and `--session` works on `map`, `discover` and `login`
+(there it says *where to write*, so a refresh updates the file you already point at).
+
+**A session you named and that cannot be read stops the run** — it never falls through to
+"no session". Silently ignoring it would capture the login page under your pages' names, which
+is the one failure this tool treats as worse than stopping. Same for a file that is not a
+storageState: it says so, instead of failing later inside the browser.
+
 
 ### Monorepos — one config per portal (`--config <dir>`)
 
@@ -337,6 +393,24 @@ capture → ingest → diff → dry-run of the fixes → your confirmation → f
 - **After the fix, `run` re-runs your suite once more (without `IAQA_CAPTURE`) to confirm the rewrite is actually green** — a selector fix is only worth anything if the tests pass after it. The exit code follows that re-run: `0` if the suite passes, `1` if it still fails (the rewrite landed but something else is red). `--no-verify` applies the fix and skips the re-run; the re-run is also skipped, with a reason, when nothing was rewritten or there is no `testCommand`.
 - With `--report`, the HTML for a `run` additionally carries the **applied** `old → new` edits (file and line numbers) and the verify verdict — the file-level before/after the `diff` report only promised.
 
+### Already ran your suite with `IAQA_CAPTURE=1`? Just `diff`
+
+`run` is a convenience, not the only door. If the capture already happened — your suite ran with
+`IAQA_CAPTURE=1`, in CI or by hand — the verdict is one offline command away:
+
+```bash
+IAQA_CAPTURE=1 npx playwright test     # your suite, as usual
+ia-qa-heal diff                        # merges .capture/ and compares — no browser, no re-run
+```
+
+`diff`, `fix` and `baseline` all merge the staging directory (`.ia-qa/mapping/.capture/`) on the
+way in and say so. **Do not run `map` to "finish" a capture**: `map` opens its own browser and
+starts over, without whatever session your suite had.
+
+And on a slow suite, `run` runs it **twice** — once to capture, once to verify the fix. `run
+--no-verify` keeps the first only; the exit code then reflects the diff rather than a re-proved
+green suite.
+
 ### Capture during your test run — `@ia-qa/self-healing/capture`
 
 One line at the top of a spec (or wrap your own extended `test` with `withCapture`):
@@ -402,6 +476,51 @@ Statically scans your tests/POMs → `.ia-qa/usage.json`. Two halves, because su
 
 Purely static: no execution, no network. A locator built by concatenation or holding `${…}` is invisible here — and invisible to `fix` too, which is why it is skipped rather than guessed at.
 
+### Page Objects written in CSS — `_resolved/`
+
+Your Page Object says `.btn-primary`. The contract says `#pay-now`. Both name the same
+button, and until they are **bound** every drift row reads `not referenced by your tests` —
+technically true, practically useless, and the reason a CSS-anchored suite used to get
+nothing out of a diff.
+
+So `map` binds them: with `usage.json` present (run `ia-qa-heal ingest` first), each
+selector your tests write is evaluated against the page and recorded in
+`.ia-qa/mapping/_resolved/<page>.json`. `baseline` promotes those alongside the contracts,
+and `diff` compares the two moments.
+
+What that buys you — an example that no other check in this package can catch:
+
+```
+🔧  FIX
+   2 ok · 0 renamed · 0 healable · 0 lost          ← the contract did not drift at all
+
+   🔗 1 selector your tests write no longer reaches what it used to:
+      🔧 .btn-primary  →  #pay-now
+         the element is still there, only its address moved.
+         tests/checkout.spec.js:1, tests/checkout.spec.js:4
+```
+
+The button never moved; someone renamed a CSS class. The element diff is spotless, the
+suite is broken, and `ia-qa-heal fix` rewrites the literal in your files.
+
+Four outcomes, and only one of them is repaired automatically:
+
+| | |
+|---|---|
+| the string now reaches **nothing**, and the element is still there | 🔧 rewritten |
+| the string now reaches a **different** element | ⛔ never rewritten — your test still passes and acts on the wrong thing |
+| the string now reaches **several** elements | ⛔ a coin flip, a human decides |
+| the element it named is **gone** | ⛔ nothing to rewrite towards |
+
+And the case that stays quiet: a selector matching something the contract does not hold —
+a row, a cell, a container. That is most of a real Page Object, it is proof the selector
+**works**, and calling it "not found" would bury the four rows above under hundreds of
+false ones.
+
+No `usage.json` ⇒ no bindings ⇒ nothing changes. Same rule as name drift: **no inventory,
+no escalation.** Today the bindings are captured by `map`; capture-during-run is specified
+in `SPEC-selector-resolution.md` and not built yet.
+
 ### The rename your suite actually depends on
 
 A relabelled element is classified `renamed`: the selector still resolves, the click still lands on the right thing. **For a CSS-anchored suite that is harmless. For a name-anchored one it is fatal** — `getByRole('button', { name: 'Save' })` stops matching the moment the button says "Enregistrer", and a selector-only diff would exit 0 while your suite goes red.

package/TUTORIAL.md

@@ -248,14 +248,41 @@ It asks a few questions (your app's URL, whether there's a login, which pages to
 
 - **🔑 Credentials** — you store the *name* of an environment variable, never the password itself. The real value stays in your `.env` / shell / AWS. **Loading it is your job:** the CLI reads `process.env` and never opens a `.env` file, so a key sitting only in `.env` will not be seen — run `map` under `npx dotenv-cli --` (or Node's `--env-file-if-exists`, 20.12+). Only `map` logs in; `diff`, `baseline`, `audit` and `check` read the mapping and need no credentials. If a variable is missing, the tool stops and names the exact variable to set — it never guesses and never writes a secret to disk.
 - **🌐 URLs to visit** — the list of pages to map. A page that lives behind a click instead of its own URL (a tab or modal an app swaps in) is reached by naming the control to click, not by a URL.
-- **🔐 One login** — the wizard sets up a single login sequence. **Want to test as several users (admin, then guest)?** Two options: keep a separate `.ia-qa/` config per role — select each with `--config <dir>`, the same flag a monorepo uses to keep one config per app/portal — **or** skip the login wiring entirely and use `ia-qa-heal run` (Step 6.7) — it captures the map *while your own test suite runs*, so whatever logins your tests already do, for however many users (and across however many domains), are covered automatically.
+- **🔐 One login** — the wizard sets up a single login sequence. **And a form fill only covers a login that *is* a form** — SSO with MFA, a consent screen, a magic link and a device check are out of reach of any list of selectors. For those, `ia-qa-heal login` opens a visible browser, you log in once however the app asks, and the session is reused by `map` (Step 5.2a). Already have a `storageState` from your suite's `globalSetup`? Point at it with `--session <file>`, `IAQA_SESSION`, or `"session"` in the config — no second login. **Want to test as several users (admin, then guest)?** Two options: keep a separate `.ia-qa/` config per role — select each with `--config <dir>`, the same flag a monorepo uses to keep one config per app/portal — **or** skip the login wiring entirely and use `ia-qa-heal run` (Step 6.7) — it captures the map *while your own test suite runs*, so whatever logins your tests already do, for however many users (and across however many domains), are covered automatically.
 
 The full annotated `config.json` — every field explained, plus a note for AI agents helping you set it up — is in the package's [README on npm](https://www.npmjs.com/package/@ia-qa/self-healing).
 
 > 🔐 **Your password is never written to that file** — only the *name* of the environment variable that holds it.
 
-### Step 5.2b — (optional) Find the pages you're *not* testing: `discover`
+### Step 5.2a — Behind a login? `ia-qa-heal login`
+
+Most apps worth mapping are behind a login, and only some of those logins are a form. This verb
+models **nothing** about yours, which is why it works anywhere:
+
+```bash
+npx ia-qa-heal login     # a real browser window opens at your first configured page
+                         # you log in there — SSO, MFA, a consent screen, a magic link, all of it
+npx ia-qa-heal map       # reuses that session; no "auth" block needed
+```
+
+Nothing is typed for you and no credential is read or stored by the tool. What is saved is the
+**browser session** (`.ia-qa/session.json`) — live cookies, so treat it like a password: it stays
+on your machine, nothing uploads it, and `login` writes `.ia-qa/.gitignore` so a commit cannot
+carry it. It expires like any session; when it does, `map` says so and tells you to run this again
+rather than quietly mapping the login page under your dashboard's name.
 
+**Already have a session?** An authenticated Playwright suite usually writes a `storageState` in
+`globalSetup` — point at it instead of logging in twice: `ia-qa-heal map --session
+playwright/.auth/user.json` (or `IAQA_SESSION=…`, or `"session"` in `.ia-qa/config.json`).
+
+Two things it deliberately will not do: it **refuses without a terminal and under CI** (it waits
+for a person — twice: at the browser, then at the keyboard), and it is **not a CI mechanism**. In a
+pipeline, use `auth` (secrets from env/SSM) or capture-during-run (Step 6.7), where your own suite
+logs itself in. An AI agent driving the CLI cannot perform this step — it will hand it to you.
+
+
+
+### Step 5.2b — (optional) Find the pages you're *not* testing: `discover`
 You list a handful of pages to map — but how many pages does your app actually have? `discover` answers that: it reads your whole site (the sitemap, or a safe crawl) and shows you **what you're not covering yet**. It **only suggests** — it changes nothing until you add `--apply`.
 
 ```bash
@@ -265,7 +292,7 @@ npx ia-qa-heal discover --crawl --apply   # happy with the list? add the missing
 ```
 
 - **The sitemap way** (default) is instant and touches nothing — it treats `www.yoursite.com` and `yoursite.com` as the same site, so you don't have to match them exactly. Its limit: a sitemap lists your *public* pages and stops at the login.
-- **The crawl way** (`--crawl`) goes further: it logs in like `map` does and follows links to find the pages behind the login. It's built to be **safe** — it only ever *reads* pages (never clicks "Delete", "Log out", "Pay"…), and to peek inside a menu or dropdown it just **opens** it and moves on. Nothing is submitted, nothing is changed.
+- **The crawl way** (`--crawl`) goes further: it authenticates exactly like `map` does — the same `auth` block, or the same saved session (`ia-qa-heal login` / `--session`) — and follows links to find the pages behind the login. It's built to be **safe** — it only ever *reads* pages (never clicks "Delete", "Log out", "Pay"…), and to peek inside a menu or dropdown it just **opens** it and moves on. Nothing is submitted, nothing is changed.
 
 You'll see your coverage gap:
 
@@ -455,7 +482,7 @@ Three optional config keys make it better (`ia-qa-heal init` asks for them):
   ```
   (Other frameworks / non-JS Selenium: write a capture shard directly — the format is documented in the README. The shard, not the import, is the real interface.)
 
-  (Playwright: your own extended `test`? Wrap it: `withCapture(myTest)`.) All are **inert without `IAQA_CAPTURE=1`** — a normal run pays nothing. **This is also the way through a multi-domain / federated-SSO app**: `map`'s single login can't reach every portal, but your suite already logs into each — capture rides that real run, with no `auth` block and without ever touching your credentials. (Monorepo with one `.ia-qa/` per portal? Set `IAQA_CONFIG_DIR=apps/xsp` so the shards land in the right one.) No `testCommand` → `run` falls back to `map`.
+  (Playwright: your own extended `test`? Wrap it: `withCapture(myTest)`.) All are **inert without `IAQA_CAPTURE=1`** — a normal run pays nothing. **This is also the way through a multi-domain / federated-SSO app**: `map`'s single login can't reach every portal, but your suite already logs into each — capture rides that real run, with no `auth` block and without ever touching your credentials. (No suite yet, or you want `map` to work on its own? `ia-qa-heal login` is the other way in: one browser, one human login, one reused session — see Step 5.2a.) (Monorepo with one `.ia-qa/` per portal? Set `IAQA_CONFIG_DIR=apps/xsp` so the shards land in the right one.) No `testCommand` → `run` falls back to `map`.
 
 - **`testPaths`** (e.g. `["tests/"]`) — feeds `ia-qa-heal ingest`, which inventories the selector literals your tests/POMs actually use into `.ia-qa/usage.json`. `diff` then tells you *used 3× in 2 test files* vs *not referenced by your tests*, and `fix` finds your files on its own.
 

package/dist/browser/resolve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve a Page Object's selector strings against the live DOM.
+ *
+ * Runs inside the browser (serialized by Playwright into `page.evaluate`), so it stays
+ * dependency-free like everything else in `src/browser/`. Unlike its neighbours it is
+ * **npm-only**: the web tool imports `match.js`, `contract.js` and `extract.js`, and
+ * nothing here is needed there — a page contract has no Page Object.
+ *
+ * Why this exists: `ingest` inventories the literal strings a suite uses (`.btn-primary`),
+ * while the contract stores a selector `extract.js` synthesized (`#pay-now`). The two
+ * never intersect, so a CSS-written suite gets "0 drifted selectors referenced by your
+ * tests" on every run — true, and useless. The missing fact is that both name the same
+ * button, and only a browser can establish it.
+ *
+ * See SPEC-selector-resolution.md. The statuses are load-bearing, `outside` above all:
+ * a Page Object is full of selectors for containers, rows and cells, which are real
+ * elements the contract deliberately does not hold. Calling those "not found" would print
+ * hundreds of false findings on the first run.
+ */
+export function resolveSelectors(args: any): {};

package/dist/browser/resolve.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSelectors = resolveSelectors;
+/**
+ * Resolve a Page Object's selector strings against the live DOM.
+ *
+ * Runs inside the browser (serialized by Playwright into `page.evaluate`), so it stays
+ * dependency-free like everything else in `src/browser/`. Unlike its neighbours it is
+ * **npm-only**: the web tool imports `match.js`, `contract.js` and `extract.js`, and
+ * nothing here is needed there — a page contract has no Page Object.
+ *
+ * Why this exists: `ingest` inventories the literal strings a suite uses (`.btn-primary`),
+ * while the contract stores a selector `extract.js` synthesized (`#pay-now`). The two
+ * never intersect, so a CSS-written suite gets "0 drifted selectors referenced by your
+ * tests" on every run — true, and useless. The missing fact is that both name the same
+ * button, and only a browser can establish it.
+ *
+ * See SPEC-selector-resolution.md. The statuses are load-bearing, `outside` above all:
+ * a Page Object is full of selectors for containers, rows and cells, which are real
+ * elements the contract deliberately does not hold. Calling those "not found" would print
+ * hundreds of false findings on the first run.
+ */
+function resolveSelectors(args) {
+    // One argument: Playwright serializes this function into the page and calls it with a
+    // single serializable value. Two parameters would silently arrive as one.
+    const pomSelectors = args.pom;
+    const contractSelectors = args.contract;
+    // Element → the contract selector that names it. Built once; first writer wins, so two
+    // contract entries resolving to the same node cannot make a binding look ambiguous.
+    const contracted = new Map();
+    for (const cs of contractSelectors) {
+        try {
+            const el = document.querySelector(cs);
+            if (el && !contracted.has(el))
+                contracted.set(el, cs);
+        }
+        catch {
+            /* a contract selector the browser cannot parse costs its own entry, not the page */
+        }
+    }
+    const out = {};
+    for (const pom of pomSelectors) {
+        let nodes;
+        try {
+            nodes = Array.prototype.slice.call(document.querySelectorAll(pom));
+        }
+        catch {
+            // Not parseable as a selector — usually a template string the static scan caught
+            // mid-concatenation, occasionally a real bug in the test.
+            out[pom] = { status: 'invalid' };
+            continue;
+        }
+        if (nodes.length === 0) {
+            // Says nothing about whether the element exists: this page, this state, this moment.
+            out[pom] = { status: 'unresolved' };
+            continue;
+        }
+        const mapped = [];
+        for (const n of nodes) {
+            const cs = contracted.get(n);
+            if (cs && mapped.indexOf(cs) === -1)
+                mapped.push(cs);
+        }
+        if (nodes.length === 1 && mapped.length === 1) {
+            out[pom] = { status: 'bound', selector: mapped[0] };
+        }
+        else if (mapped.length === 0) {
+            // It matches the page, just not anything under contract — a row, a cell, a heading.
+            // Proof the selector works, and never a finding.
+            out[pom] = { status: 'outside' };
+        }
+        else {
+            out[pom] = { status: 'ambiguous', count: nodes.length };
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/browser/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/browser/resolve.js"],"names":[],"mappings":";;AAmBA,4CAoDC;AAvED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,gBAAgB,CAAC,IAAI;IACnC,sFAAsF;IACtF,0EAA0E;IAC1E,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC;IAC9B,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC;IACxC,uFAAuF;IACvF,oFAAoF;IACpF,MAAM,UAAU,GAAG,IAAI,GAAG,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,IAAI,iBAAiB,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;YACtC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,oFAAoF;QACtF,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,EAAE,CAAC;IACf,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC;QACV,IAAI,CAAC;YACH,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,iFAAiF;YACjF,0DAA0D;YAC1D,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;YACjC,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,qFAAqF;YACrF,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;YACpC,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,EAAE,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,CAAC;aAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,oFAAoF;YACpF,iDAAiD;YACjD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cli/args.js

@@ -16,12 +16,13 @@ exports.rejectUnknownFlags = rejectUnknownFlags;
  */
 exports.KNOWN_FLAGS = {
     init: [],
-    discover: ['--sitemap', '--crawl', '--no-reveal', '--strict-host', '--apply', '--max', '--depth'],
-    map: ['--screenshots'],
+    discover: ['--sitemap', '--crawl', '--no-reveal', '--strict-host', '--apply', '--max', '--depth', '--session'],
+    login: ['--url', '--session'],
+    map: ['--screenshots', '--session'],
     baseline: [],
     diff: ['--strict', '--json', '--junit', '--dir', '--report', '--open'],
     fix: ['--dry-run', '--locators', '--dir'],
-    ingest: [],
+    ingest: ['--json'],
     audit: ['--strict', '--json'],
     check: ['--strict', '--json', '--offline', '--concurrency'],
     graph: ['--format', '--kind', '--out', '--open'],

package/dist/cli/args.js.map

@@ -1 +1 @@
-{"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,EAAE,eAAe,CAAC;IAC3D,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,EAAE,WAAW,CAAC;CACnF,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":";;;AA8BA,gDAeC;AA7CD;;;;;;;;;;;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,EAAE,WAAW,CAAC;IAC9G,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC;IAC7B,GAAG,EAAE,CAAC,eAAe,EAAE,WAAW,CAAC;IACnC,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,CAAC,QAAQ,CAAC;IAClB,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC7B,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,CAAC;IAC3D,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,EAAE,WAAW,CAAC;CACnF,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/audit.d.ts

@@ -77,5 +77,45 @@ export declare function containsAsWords(haystack: string, needle: string): boole
  * reading that cannot manufacture a false positive.
  */
 export declare function findDeadLocators(usage: Usage, elements: MappedElement[]): DeadLocator[];
+/**
+ * Why an audit produced no verdict. Never a PASS — see `auditProject`.
+ */
+export type AuditRefusalReason = 'no-mapping' | 'no-inventory' | 'no-files' | 'no-locators' | 'nothing-judgeable';
+export interface AuditRefusal {
+    ok: false;
+    reason: AuditRefusalReason;
+    /** The composed explanation, identical on every surface that states it. */
+    message: string;
+    pagesMapped: number;
+    scanned: number;
+}
+export interface AuditSuccess {
+    ok: true;
+    report: AuditReport;
+    /** Contract size behind the verdict — how much the audit had to look at. */
+    elements: number;
+    /** Call sites carrying a dead name, not distinct names. */
+    deadSites: number;
+    selectorCount: number;
+    /** Every name-anchored site found, judged or not — the renderer splits them. */
+    allSites: NameSite[];
+}
+export type AuditOutcome = AuditSuccess | AuditRefusal;
+/**
+ * The audit itself: read the contract, read the inventory, decide.
+ *
+ * Extracted from `runAudit` so the terminal and the MCP tool `audit_suite` share
+ * one computation *and* one wording. Two surfaces re-deriving the same verdict is
+ * the CLI/MCP dispatch split this project treats as a defect — and the refusals
+ * are the half most worth sharing, because they are the ones a second
+ * implementation would quietly turn into a pass.
+ *
+ * No console, no `process.exitCode`: the caller renders and decides what a
+ * refusal costs it.
+ */
+export declare function auditProject(opts?: {
+    testPaths?: string[];
+    strict?: boolean;
+}): AuditOutcome;
 export declare function runAudit(args: string[]): Promise<void>;
 export {};

package/dist/cli/audit.js

@@ -37,6 +37,7 @@ exports.auditHeadline = auditHeadline;
 exports.auditCounts = auditCounts;
 exports.containsAsWords = containsAsWords;
 exports.findDeadLocators = findDeadLocators;
+exports.auditProject = auditProject;
 exports.runAudit = runAudit;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -172,19 +173,34 @@ function findDeadLocators(usage, elements) {
     }
     return dead.sort((a, b) => b.sites.length - a.sites.length);
 }
-async function runAudit(args) {
-    const strict = args.includes('--strict');
-    const json = args.includes('--json');
-    const paths = args.filter((a) => !a.startsWith('--'));
+/**
+ * The audit itself: read the contract, read the inventory, decide.
+ *
+ * Extracted from `runAudit` so the terminal and the MCP tool `audit_suite` share
+ * one computation *and* one wording. Two surfaces re-deriving the same verdict is
+ * the CLI/MCP dispatch split this project treats as a defect — and the refusals
+ * are the half most worth sharing, because they are the ones a second
+ * implementation would quietly turn into a pass.
+ *
+ * No console, no `process.exitCode`: the caller renders and decides what a
+ * refusal costs it.
+ */
+function auditProject(opts = {}) {
+    const paths = opts.testPaths ?? [];
+    const strict = !!opts.strict;
     const dir = (0, config_1.mappingDir)();
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
-        console.error(`❌ No mapping to audit against — ${path.resolve(dir)} does not exist.\n\n` +
-            `   \`audit\` reads one capture of the app and asks whether your suite still names\n` +
-            `   things that exist in it. Capture it first:\n` +
-            `     ia-qa-heal map\n\n` +
-            `   No baseline needed — unlike \`diff\`, this works on the very first run.`);
-        process.exitCode = 2;
-        return;
+        return {
+            ok: false,
+            reason: 'no-mapping',
+            pagesMapped: 0,
+            scanned: 0,
+            message: `❌ No mapping to audit against — ${path.resolve(dir)} does not exist.\n\n` +
+                `   \`audit\` reads one capture of the app and asks whether your suite still names\n` +
+                `   things that exist in it. Capture it first:\n` +
+                `     ia-qa-heal map\n\n` +
+                `   No baseline needed — unlike \`diff\`, this works on the very first run.`,
+        };
     }
     // Test paths on the command line re-scan in memory; otherwise the inventory on
     // disk is used, and only if it exists — auditing against a stale file the user
@@ -202,11 +218,15 @@ async function runAudit(args) {
         }
     }
     if (!usage) {
-        console.error(`❌ No locator inventory to audit.\n\n` +
-            `   Run \`ia-qa-heal ingest <test-dir>\` first, add "testPaths" to .ia-qa/config.json,\n` +
-            `   or pass the test paths directly: \`ia-qa-heal audit tests/\`.`);
-        process.exitCode = 2;
-        return;
+        return {
+            ok: false,
+            reason: 'no-inventory',
+            pagesMapped: 0,
+            scanned: 0,
+            message: `❌ No locator inventory to audit.\n\n` +
+                `   Run \`ia-qa-heal ingest <test-dir>\` first, add "testPaths" to .ia-qa/config.json,\n` +
+                `   or pass the test paths directly: \`ia-qa-heal audit tests/\`.`,
+        };
     }
     const { pages, elements } = readMappings(dir);
     const dead = findDeadLocators(usage, elements);
@@ -224,7 +244,7 @@ async function runAudit(args) {
             : allSites.length === 0 && selectorCount === 0
                 ? 'no-locators'
                 : 'nothing-judgeable';
-        const human = reason === 'no-files'
+        const message = reason === 'no-files'
             ? `❌ Nothing to audit: no test files found${paths.length > 0 ? ` under ${paths.join(', ')}` : ''}.\n\n` +
                 `   A brand-new project has nothing to check yet — that is not a pass, it is an\n` +
                 `   empty question. The ${pages.length} mapped page${pages.length === 1 ? '' : 's'} in .ia-qa/mapping/*.md already list every\n` +
@@ -239,19 +259,15 @@ async function runAudit(args) {
                     `   \`audit\` answers one question — does a locator still NAME something that exists? —\n` +
                     `   and only role-anchored calls (getByRole, getByLabel, By.linkText) can be held to it.\n` +
                     `   A CSS selector says where, not what: use \`map\` + \`baseline\` + \`diff\` to gate those.`;
-        console.error(human);
-        if (json) {
-            console.log(JSON.stringify({ verdict: null, reason, pagesMapped: pages.length, scanned: usage.scanned }, null, 2));
-        }
-        process.exitCode = 2;
-        return;
+        return { ok: false, reason, message, pagesMapped: pages.length, scanned: usage.scanned };
     }
     const selectorNames = Object.keys(usage.selectors);
     const mappedSelectors = new Set(elements.map((e) => e.selector));
     const unresolvedSelectors = selectorNames.filter((s) => !mappedSelectors.has(s));
     const verdict = dead.length === 0 ? 'PASS' : dead.every((d) => d.suggestion) ? 'FIX' : 'BLOCK';
-    if (json) {
-        console.log(JSON.stringify({
+    return {
+        ok: true,
+        report: {
             verdict,
             pagesMapped: pages.length,
             locatorsJudged: judgedSites.length,
@@ -259,7 +275,36 @@ async function runAudit(args) {
             deadLocators: dead,
             unresolvedSelectors,
             advisory: !strict,
-        }, null, 2));
+        },
+        elements: elements.length,
+        deadSites,
+        selectorCount,
+        allSites,
+    };
+}
+async function runAudit(args) {
+    const strict = args.includes('--strict');
+    const json = args.includes('--json');
+    const paths = args.filter((a) => !a.startsWith('--'));
+    const outcome = auditProject({ testPaths: paths, strict });
+    if (!outcome.ok) {
+        console.error(outcome.message);
+        // The two preconditions have nothing to report; the three "ran but cannot
+        // speak" reasons do, and `--json` states them so a caller is not left
+        // parsing prose for the difference.
+        if (json && outcome.reason !== 'no-mapping' && outcome.reason !== 'no-inventory') {
+            console.log(JSON.stringify({ verdict: null, reason: outcome.reason, pagesMapped: outcome.pagesMapped, scanned: outcome.scanned }, null, 2));
+        }
+        process.exitCode = 2;
+        return;
+    }
+    const { report, elements: elementCount, deadSites, selectorCount, allSites } = outcome;
+    const { verdict, deadLocators: dead, unresolvedSelectors } = report;
+    const pageCount = report.pagesMapped;
+    const judged = report.locatorsJudged;
+    const unjudgedSites = report.locatorsNotJudged;
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
         process.exitCode = strict && verdict !== 'PASS' ? 1 : 0;
         return;
     }
@@ -270,8 +315,8 @@ async function runAudit(args) {
     const against = (0, summary_1.againstLine)((0, config_1.configuredBaseUrl)());
     if (against)
         console.log(against);
-    console.log(`   ${pages.length} mapped page${pages.length === 1 ? '' : 's'} · ${elements.length} elements · no baseline needed`);
-    console.log(`   ${judgedSites.length} role-anchored locator${judgedSites.length === 1 ? '' : 's'} checked` +
+    console.log(`   ${pageCount} mapped page${pageCount === 1 ? '' : 's'} · ${elementCount} elements · no baseline needed`);
+    console.log(`   ${judged} role-anchored locator${judged === 1 ? '' : 's'} checked` +
         (deadSites > 0 ? ` · ${deadSites} name nothing` : ' · all resolve'));
     if (dead.length > 0) {
         console.log(`\n   ⛔ ${dead.length} locator name${dead.length === 1 ? '' : 's'} match no mapped element:`);
@@ -306,7 +351,7 @@ async function runAudit(args) {
         }
     }
     if (unresolvedSelectors.length > 0) {
-        console.log(`   ℹ️  ${unresolvedSelectors.length} of ${selectorNames.length} CSS selectors appear in no contract —` +
+        console.log(`   ℹ️  ${unresolvedSelectors.length} of ${selectorCount} CSS selectors appear in no contract —` +
             ` expected for containers and text nodes, worth a look for the rest.`);
     }
     // The two ways a finding can be wrong, named up front. Both are about what the
@@ -315,13 +360,13 @@ async function runAudit(args) {
     if (dead.length > 0) {
         console.log(`\n   Before believing a finding, check the capture behind it:` +
             `\n     · unmapped page — the locator may live on a page not in config.pages` +
-            `\n       (\`ia-qa-heal discover\` lists them; ${pages.length} page${pages.length === 1 ? ' is' : 's are'} mapped today)` +
+            `\n       (\`ia-qa-heal discover\` lists them; ${pageCount} page${pageCount === 1 ? ' is' : 's are'} mapped today)` +
             `\n     · unmapped state — \`map\` captures a page in ONE state. A label that only` +
             `\n       appears after a click (a tab, a mode toggle, an open dialog) is not in the` +
             `\n       contract, and a test that clicks first is right while this says otherwise.`);
     }
     else {
-        console.log(`\n   Coverage decides what this verdict is worth: ${pages.length} page${pages.length === 1 ? '' : 's'} mapped.` +
+        console.log(`\n   Coverage decides what this verdict is worth: ${pageCount} page${pageCount === 1 ? '' : 's'} mapped.` +
             `\n   \`ia-qa-heal discover\` lists what you are not mapping yet.`);
     }
     if (!strict && verdict !== 'PASS') {
@@ -330,7 +375,7 @@ async function runAudit(args) {
     else {
         console.log('');
     }
-    (0, summary_1.summaryLine)('audit', verdict === 'PASS' ? 'ok' : verdict === 'FIX' ? 'fix' : 'block', auditHeadline({ verdict, deadLocators: dead, locatorsJudged: judgedSites.length }), auditCounts({ pagesMapped: pages.length, locatorsNotJudged: unjudgedSites }));
+    (0, summary_1.summaryLine)('audit', verdict === 'PASS' ? 'ok' : verdict === 'FIX' ? 'fix' : 'block', auditHeadline({ verdict, deadLocators: dead, locatorsJudged: judged }), auditCounts({ pagesMapped: pageCount, locatorsNotJudged: unjudgedSites }));
     process.exitCode = strict && verdict !== 'PASS' ? 1 : 0;
 }
 //# sourceMappingURL=audit.js.map