@ia-qa/self-healing 1.18.0 → 1.19.1

package/dist/unrepaired.d.ts

@@ -0,0 +1,73 @@
+import type { Usage } from './ingest';
+/**
+ * "No test file referenced any of the drifted selectors" — the false negative.
+ *
+ * Field report: that line was printed over a project whose Page Object contains, verbatim,
+ * `a[href="/index.php/cart"]` — one of the drifted selectors. The statement was simply
+ * untrue, and the reader could only conclude the inventory was broken.
+ *
+ * The line was measuring the wrong set. `rewrites` holds the rows the tool decided it could
+ * **repair**; a row that drifted and could not be repaired is in neither `rewrites` nor the
+ * resulting edits, so "nothing matched a file" got reported as "your tests do not use any of
+ * this". Two very different sentences: one is about the suite, the other about the tool's
+ * own reach.
+ *
+ * What the reader needed was the third sentence, which nobody was writing: **your tests do
+ * reference it, and here is why I cannot repair it.** Saying "no" where the honest answer is
+ * "I don't know, for this reason" is the single failure mode that costs the most trust,
+ * because it is indistinguishable from a working check.
+ *
+ * Everything here is pure, and it reads the two files that were already on disk the whole
+ * time: the drift rows, and `usage.json`.
+ */
+export interface UnrepairedRow {
+    status: string;
+    role?: string;
+    name?: string;
+    selector?: string;
+    newName?: string;
+    candidateCount?: number;
+    nameMasked?: boolean;
+}
+export interface UnrepairedFinding {
+    selector?: string;
+    role: string;
+    name: string;
+    status: string;
+    /** Why this one could not be repaired, in a sentence about the element. */
+    why: string;
+    /** How the suite reaches it. */
+    via: Array<'selector' | 'name'>;
+    sites: Array<{
+        file: string;
+        line: number;
+    }>;
+}
+/**
+ * Why a drifted row the suite uses was left alone.
+ *
+ * Each sentence names the property of the ELEMENT that makes the repair unprovable, not the
+ * internal status word — a reader who is told `ambiguous` has learned a vocabulary, and a
+ * reader told "two elements now share that role and name, so a repair would be a coin flip"
+ * has learned what to go and look at.
+ */
+export declare function reasonFor(row: UnrepairedRow): string;
+/**
+ * Rows that drifted, were not repaired, and that the suite demonstrably uses.
+ *
+ * `repaired` is the set of selector literals the fix is about to rewrite — anything in it is
+ * already reported as an edit and must not be listed again as a gap.
+ *
+ * No inventory ⇒ no findings, and the caller must then say "not measured" rather than
+ * anything resembling "no". That distinction is the whole point of this module.
+ */
+export declare function referencedButUnrepaired(rows: UnrepairedRow[], repaired: Set<string>, usage: Usage | null): UnrepairedFinding[];
+/**
+ * The block that replaces "no test file referenced any of the drifted selectors".
+ *
+ * Three states, and they must stay three: repaired nothing *and* your tests use none of it;
+ * repaired nothing *but* your tests use these, here is why; and repaired nothing *and*
+ * nobody has told me what your tests use. The middle one did not exist, and the third was
+ * being printed as the first.
+ */
+export declare function unrepairedLines(findings: UnrepairedFinding[], hasInventory: boolean): string[];

package/dist/unrepaired.js.map

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

package/dist/volatile.d.ts

@@ -29,8 +29,16 @@ export interface VolatilePattern {
 export declare function parseVolatilePatterns(patterns: string[] | undefined): VolatilePattern[];
 /** Shared with `nameMask.ts`, so both declarations speak one pattern dialect. */
 export declare function globToRegex(glob: string): RegExp;
+/** The pattern that excludes this element, or null. Named, because the message needs it. */
+export declare function matchVolatile(el: MappedElement, patterns: VolatilePattern[]): VolatilePattern | null;
 export declare function isVolatile(el: MappedElement, patterns: VolatilePattern[]): boolean;
+/** An element that left the contract, with the pattern that removed it. */
+export interface VolatileExclusion {
+    element: MappedElement;
+    pattern: string;
+}
 export declare function filterVolatile(elements: MappedElement[], patterns: VolatilePattern[]): {
     kept: MappedElement[];
     excluded: number;
+    exclusions: VolatileExclusion[];
 };

package/dist/volatile.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseVolatilePatterns = parseVolatilePatterns;
 exports.globToRegex = globToRegex;
+exports.matchVolatile = matchVolatile;
 exports.isVolatile = isVolatile;
 exports.filterVolatile = filterVolatile;
 const FIELDS = ['href', 'selector', 'name', 'role'];
@@ -22,27 +23,43 @@ function globToRegex(glob) {
     const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
     return new RegExp(`^${escaped}$`, 'i');
 }
-function isVolatile(el, patterns) {
+/** The pattern that excludes this element, or null. Named, because the message needs it. */
+function matchVolatile(el, patterns) {
     for (const p of patterns) {
         if (p.field === 'any') {
             if ((el.href !== undefined && p.regex.test(el.href)) ||
                 p.regex.test(el.selector) ||
                 p.regex.test(el.name)) {
-                return true;
+                return p;
             }
         }
         else {
             const value = el[p.field];
             if (value !== undefined && p.regex.test(value))
-                return true;
+                return p;
         }
     }
-    return false;
+    return null;
+}
+function isVolatile(el, patterns) {
+    return matchVolatile(el, patterns) !== null;
 }
 function filterVolatile(elements, patterns) {
     if (patterns.length === 0)
-        return { kept: elements, excluded: 0 };
-    const kept = elements.filter((el) => !isVolatile(el, patterns));
-    return { kept, excluded: elements.length - kept.length };
+        return { kept: elements, excluded: 0, exclusions: [] };
+    const kept = [];
+    const exclusions = [];
+    for (const el of elements) {
+        const hit = matchVolatile(el, patterns);
+        // The excluded elements are kept, not just counted. They are the only evidence that
+        // can answer "is anything my tests use being silently dropped?" — see
+        // `volatileBlindSpots`, and they exist nowhere else: by construction they never
+        // reach a contract.
+        if (hit)
+            exclusions.push({ element: el, pattern: hit.raw });
+        else
+            kept.push(el);
+    }
+    return { kept, excluded: exclusions.length, exclusions };
 }
 //# sourceMappingURL=volatile.js.map

package/dist/volatile.js.map

@@ -1 +1 @@
-{"version":3,"file":"volatile.js","sourceRoot":"","sources":["../src/volatile.ts"],"names":[],"mappings":";;AAiCA,sDAWC;AAGD,kCAGC;AAED,gCAgBC;AAED,wCAOC;AA9CD,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAE7D,SAAgB,qBAAqB,CAAC,QAA8B;IAClE,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,OAAO,GAAI,MAA4B,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/D,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,CAAC,CAAE,MAAmC,CAAC,CAAC,CAAC,KAAK;YAC7D,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YACxD,GAAG;SACJ,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AACjF,SAAgB,WAAW,CAAC,IAAY;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAChF,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,SAAgB,UAAU,CAAC,EAAiB,EAAE,QAA2B;IACvE,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;YACtB,IACE,CAAC,EAAE,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;gBAChD,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC;gBACzB,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EACrB,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC9D,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,cAAc,CAC5B,QAAyB,EACzB,QAA2B;IAE3B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAClE,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"volatile.js","sourceRoot":"","sources":["../src/volatile.ts"],"names":[],"mappings":"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"}

package/dist/volatileBlindSpot.d.ts

@@ -0,0 +1,67 @@
+import type { Usage } from './ingest';
+import type { VolatileExclusion } from './volatile';
+/**
+ * The declaration that removes an element, checked against the suite that uses it.
+ *
+ * `volatile` is the most destructive declaration this tool takes: a matching element never
+ * enters a contract at all — not its selector, not its name, not its href, not its
+ * coverage. That is correct for a rotating feed item, and it is a **permanent blind spot**
+ * for anything else. Nothing ever reports drift on an element that is not in the contract,
+ * because from the gate's point of view it does not exist.
+ *
+ * Until now `map` printed only a count — `N volatile excluded` — and a count cannot
+ * distinguish "40 feed cards" from "40 feed cards and the cart button your suite clicks".
+ * Field report: an element excluded by a pattern was referenced by a Page Object, and
+ * nobody was told for fifteen days.
+ *
+ * **Its conservative sibling already does this.** `nameMask.ts` refuses a mask that would
+ * swallow a label `usage.names` says the tests locate by — the exact same cross-check,
+ * between the exact same two files. `volatile` is the one that removes more and checked
+ * less.
+ *
+ * Three restraints, and they are what makes this a warning worth reading:
+ *
+ * **It warns, it never refuses.** A mask is a comparison-time policy and can be declined
+ * without losing anything; `volatile` is applied at capture, and refusing it would either
+ * write a contract the user did not ask for or abandon the page. The user declared this on
+ * purpose. What they did not choose is being uninformed about it.
+ *
+ * **No inventory ⇒ no message.** A project that has never run `ingest` has no evidence
+ * either way, and "no test uses it" is exactly the false negative this file exists to stop
+ * being printed. Silence here means *not measured*, and the caller says so rather than
+ * implying the exclusions are safe.
+ *
+ * **Silent on the good case.** An exclusion nothing references produces no line at all. A
+ * warning that fires on the ordinary run is one people learn to scroll past, and then it is
+ * not there on the day it matters.
+ */
+export interface VolatileBlindSpot {
+    /** What was excluded, as the contract would have addressed it. */
+    selector: string;
+    name: string;
+    role: string;
+    /** The `volatile` pattern that removed it — the line the user would edit. */
+    pattern: string;
+    /** How the suite reaches it: by selector, by accessible name, or both. */
+    via: Array<'selector' | 'name'>;
+    /** Where, in the user's own files. */
+    sites: Array<{
+        file: string;
+        line: number;
+    }>;
+}
+/**
+ * Which excluded elements the suite actually uses.
+ *
+ * Deduplicated by selector + name: a navbar element excluded on 142 pages is one blind
+ * spot and one fix, not 142 findings — the same reasoning `check` applies to dead links.
+ */
+export declare function volatileBlindSpots(exclusions: VolatileExclusion[], usage: Usage | null): VolatileBlindSpot[];
+/**
+ * The warning, as one block.
+ *
+ * Rendered here rather than in the CLI so the message cannot be worded one way by `map` and
+ * another by whatever reads this next — the `checkHeadline` rule. Returns null when there
+ * is nothing to say, which is the ordinary case.
+ */
+export declare function volatileBlindSpotLines(spots: VolatileBlindSpot[]): string[] | null;

package/dist/volatileBlindSpot.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ia-qa/self-healing",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "description": "Your Playwright, Cypress or Selenium tests break when a selector moves — this finds the element again and rewrites the test. Deterministic: no LLM decides whether your build passes. Runs entirely on your machine, with a local MCP server for agents.",
   "keywords": [
     "self-healing",

package/skills/ia-qa-heal/SKILL.md

@@ -64,6 +64,7 @@ exists only in a state nothing captured (behind a tab, a modal, a mode toggle).
 | "is this getting better or worse?" | `history` (`--json`) — the trend no single run can reconstruct |
 | "gate my pipeline on it" | `diff --junit <file>` — every major CI charts the trend natively |
 | `map` says "login wall" / the app is behind SSO | if a storageState already exists (most authenticated Playwright suites write one in `globalSetup`): `--session <file>`, `IAQA_SESSION`, or `"session"` in config.json — no second login. Otherwise tell the human to run `ia-qa-heal login` — **you cannot do it** (§4.12) |
+| "is the session still good?" / before blaming the app for a wall | `session --check`. It tells the three causes **apart**: `expired` (every cookie's date is past) and `wrong-host` (nothing is scoped to `baseUrl`) are decided **from the file, no browser**; `rotated` (the file is fine, the server still answers a login) needs one request. Exit 0 holds · 1 does not · 2 could not tell. `--offline` skips the browser entirely. Run it **before** a long `map`, and when a tour or a map reports a wall — a `wrong-host` is the one no amount of logging in will fix |
 | "let me look at it / decide myself" | tell the human to run `ia-qa-heal ui` — **do not run it yourself** (§4.8) |
 | first-time setup | `ia-qa-heal init --yes --base-url <url> --discover [--tests <paths>] [--bootstrap]` — asks nothing, so it cannot hang. `--discover` fills `pages` from their sitemap (plain fetch, no browser); `--bootstrap` also chains ingest → map → baseline. Writing `.ia-qa/config.json` by hand still works |
 | "288 lost, red everywhere, on an app that looks fine" | read the **systemic delta** block `diff` prints — the same element gone from ~every page is one fact about the *capture*, not N drifts. Usually a consent banner, a tour or a flag: the fix is `prepare` in config.json (§4.16), not a rewrite |
@@ -125,6 +126,9 @@ clicking the wrong thing), or a name-drift finding that is not attributable.
    included, so a real break on that button would never be caught again. And never propose a mask
    over a label the tests locate by name: the tool refuses it out loud, and talking the human past
    that refusal is putting a green gate over a red suite.
+   **`map` now names the elements a `volatile` pattern removed that the suite still uses**, with
+   `file:line` and the pattern to narrow — relay that warning in full. It fires only on the bad
+   case, so if you see it, something the tests click will never be gated again.
 10. **Never read a `map` that exited 1 as "nothing was mapped".** A page that fails is now isolated:
    the rest are still written, its own previous contract is left untouched, and the summary says
    `N of M pages mapped`. Read that line — the pages it did not reach are `stale` in the next diff,
@@ -139,7 +143,13 @@ clicking the wrong thing), or a name-drift finding that is not attributable.
 12. **Never try to log a suite in yourself.** When `map` reports a login wall it prints the whole
    remedy: a filled-in `auth` block when the form is readable, and the fact that a form fill
    cannot pass SSO with MFA, a consent screen or a magic link. Read past the first line before
-   concluding anything. For everything a form cannot answer there is exactly one step, and it
+   concluding anything. **Run `session --check` first**: it says *which* of expired / wrong-host /
+   rotated it is, and two of those need no browser. `wrong-host` means the session and the
+   `baseUrl` are about different applications — telling the human to log in again there wastes
+   their time and produces the identical file. Note that with a session in use, `map` now stops
+   at the first wall instead of walking every remaining page into it: `N of M pages mapped` with
+   the rest **not attempted** (they keep their previous contracts and read `stale`), so do not
+   report those as pages that failed. For everything a form cannot answer there is exactly one step, and it
    belongs to the human: `ia-qa-heal login` opens a visible browser, they log in once, and the
    session is reused by `map`. It refuses without a TTY and under CI — that refusal is aimed at
    you. Never ask for their password, never put a credential in `config.json` (it holds `secrets`
@@ -197,11 +207,19 @@ clicking the wrong thing), or a name-drift finding that is not attributable.
    `run`'s live coverage and `map`'s "N of M pages": a surface left unmeasured is never a pass.
    The remedy is `--deep-budget <n>` or a narrower `--depth 1`, never ignoring the line.
 
-19. **Never present `--deep` as free.** It clicks its way through the page's states, so it costs
+19. **Never read "nothing could be rewritten" as "their tests do not use it".** `fix` prints
+   three different sentences and they mean three different things: *nothing to repair and your
+   tests reference none of it*; *nothing to repair **but** your tests DO reference these — here
+   is each one with `file:line` and why it could not be repaired*; and *not measured, because no
+   `usage.json` exists*. The middle one is the interesting case and the last one is not a "no".
+   Relay the reason per element — "two elements now answer to that role and name, so repairing
+   would be a coin flip" is what the human acts on, not the status word.
+
+20. **Never present `--deep` as free.** It clicks its way through the page's states, so it costs
    ~1 min per page where a plain `map` costs seconds. Recommend it for building or refreshing a
    **baseline**, not for a per-commit gate, and say so when you propose it.
 
-20. **Never raise `--depth` to "get better coverage".** The default is 1 because it *finishes*.
+21. **Never raise `--depth` to "get better coverage".** The default is 1 because it *finishes*.
    Depth 2 was measured at +30% elements for 3× the time and **never completed at any budget** —
    80, 150 and 250 clicks all returned the same elements, so the extra clicks re-walk states that
    hold nothing new. If a user asks for deeper, tell them what it costs and that the contract
@@ -227,6 +245,14 @@ Nothing, except: requests to the user's **own** `baseUrl` (`check`'s link half,
 — GET only, same origin, never a `/logout` or `/delete` URL), and `ia-qa-heal-ai` calling the
 user's own LLM if they opted in. Say that plainly rather than implying more or less.
 
+**Where the key lives.** `ia-qa-heal-ai` needs a provider key, and it is never a file value.
+Prefer the OS store — hand the human `ia-qa-heal secret set <NAME>` to run themselves (it asks
+for the value on a terminal and refuses a pipe or an argument), then reference it as
+`{ "source": "keychain", "key": "<NAME>" }`. You can confirm it resolves with
+`secret check <NAME>`; **there is no verb that prints a stored value and you must not look for
+one**. In CI there is no store and no person: keep `{ "source": "env" }` and let the runner
+hold the secret. Never ask the human to paste a key to you; if they do, tell them to rotate it.
+
 `ui` does not change that: it binds `127.0.0.1` only, is gated by a per-process token, and serves a
 page with no external asset. If asked whether it "hosts" anything, the answer is no — it is a local
 process that dies with the browser tab.