@ia-qa/self-healing 1.16.0 → 1.19.0

package/dist/sessionCheck.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Why a session is not opening the app — told apart, not listed.
+ *
+ * `assertLanded` names three causes: "expired, rotated, or never covering this domain". All
+ * three are true statements about the world and the message offers no way to choose between
+ * them, so the reader is left to guess — and one of them means "run `login` again" while
+ * another means "your `baseUrl` and your session are about different hosts", which no amount
+ * of logging in will fix. A field report ended with someone writing their own
+ * `check-session.mjs` to answer it.
+ *
+ * **Two of the three are answerable from the file alone**, which is the finding that makes
+ * this verb worth having rather than a second wrapper around a browser:
+ *
+ *  - **expired** — a cookie carries its own `expires`. A file whose session cookies are all
+ *    in the past cannot authenticate anything, and no request has to be made to know it.
+ *  - **wrong-host** — a cookie carries its `domain`. If nothing in the file is scoped to the
+ *    host `baseUrl` points at, the session was taken somewhere else. This is the one a
+ *    person can stare at for an hour: the session works, the app works, and they are not the
+ *    same app. `www.` and an apex fold together, as everywhere else in this package.
+ *  - **rotated** — cookies present, unexpired, correctly scoped, and the app still answers
+ *    with a login. Only the server knows why (a deploy, a secret rotation, a forced logout),
+ *    and only a request can observe it.
+ *
+ * So the offline analysis runs first and the browser is used only for the question it is the
+ * only witness to. Everything here is pure; the I/O lives in `cli/session.ts`.
+ */
+/** Playwright's storageState, as much of it as this file needs. */
+export interface StoredSession {
+    cookies?: Array<{
+        name: string;
+        domain?: string;
+        path?: string;
+        expires?: number;
+    }>;
+    origins?: Array<{
+        origin: string;
+        localStorage?: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+}
+export type SessionCause = 
+/** Every cookie's `expires` is in the past. */
+'expired'
+/** Nothing in the file is scoped to the host `baseUrl` names. */
+ | 'wrong-host'
+/** The file looks usable and the app still shows a login — the server dropped it. */
+ | 'rotated'
+/** A storageState with nothing in it: this app keeps its token where the file cannot reach. */
+ | 'empty'
+/** It opens the app. */
+ | 'holds'
+/** The check could not run — a navigation error is not a verdict about the session. */
+ | 'unknown';
+export interface SessionFacts {
+    cookies: number;
+    origins: number;
+    /** Cookies whose `expires` is in the past, and the soonest one still valid. */
+    expired: number;
+    /** Seconds until the first cookie expires, when any says. Negative: all gone. */
+    expiresInSeconds: number | null;
+    /** Cookie domains, as written in the file. */
+    domains: string[];
+    /** True when at least one cookie or origin is scoped to the app's host. */
+    coversHost: boolean;
+    host: string;
+}
+/** `www.` and an apex are one site, the same fold `discover --sitemap` applies. */
+export declare function foldHost(host: string): string;
+/** A cookie domain (`.example.com`) covers a host when the host ends with it. */
+export declare function domainCovers(domain: string, host: string): boolean;
+export declare function readFacts(state: StoredSession, baseUrl: string, now?: number): SessionFacts;
+export interface SessionVerdict {
+    cause: SessionCause;
+    /** True only when the app was actually opened and did not show a login. */
+    holds: boolean;
+    headline: string;
+    /** What to do, or nothing when it holds — a remedy printed on a good run is noise. */
+    remedy: string[];
+}
+/**
+ * The verdict, from the file's own facts plus — when one was possible — what the app
+ * answered.
+ *
+ * `landed` is undefined when no request was made, which is a legitimate state: the offline
+ * causes are conclusive on their own, and opening a browser to re-confirm an expiry date is
+ * a request nobody needs to make.
+ */
+export declare function judgeSession(facts: SessionFacts, replay?: {
+    landed: string;
+    wall: boolean;
+    error?: string;
+}, loginCommand?: string): SessionVerdict;
+/** "3 days", "4 hours", "12 minutes" — enough precision to act, never a timestamp to parse. */
+export declare function describeAge(seconds: number): string;

package/dist/sessionCheck.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Why a session is not opening the app — told apart, not listed.
+ *
+ * `assertLanded` names three causes: "expired, rotated, or never covering this domain". All
+ * three are true statements about the world and the message offers no way to choose between
+ * them, so the reader is left to guess — and one of them means "run `login` again" while
+ * another means "your `baseUrl` and your session are about different hosts", which no amount
+ * of logging in will fix. A field report ended with someone writing their own
+ * `check-session.mjs` to answer it.
+ *
+ * **Two of the three are answerable from the file alone**, which is the finding that makes
+ * this verb worth having rather than a second wrapper around a browser:
+ *
+ *  - **expired** — a cookie carries its own `expires`. A file whose session cookies are all
+ *    in the past cannot authenticate anything, and no request has to be made to know it.
+ *  - **wrong-host** — a cookie carries its `domain`. If nothing in the file is scoped to the
+ *    host `baseUrl` points at, the session was taken somewhere else. This is the one a
+ *    person can stare at for an hour: the session works, the app works, and they are not the
+ *    same app. `www.` and an apex fold together, as everywhere else in this package.
+ *  - **rotated** — cookies present, unexpired, correctly scoped, and the app still answers
+ *    with a login. Only the server knows why (a deploy, a secret rotation, a forced logout),
+ *    and only a request can observe it.
+ *
+ * So the offline analysis runs first and the browser is used only for the question it is the
+ * only witness to. Everything here is pure; the I/O lives in `cli/session.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.foldHost = foldHost;
+exports.domainCovers = domainCovers;
+exports.readFacts = readFacts;
+exports.judgeSession = judgeSession;
+exports.describeAge = describeAge;
+/** `www.` and an apex are one site, the same fold `discover --sitemap` applies. */
+function foldHost(host) {
+    return host.replace(/^www\./i, '').toLowerCase();
+}
+/** A cookie domain (`.example.com`) covers a host when the host ends with it. */
+function domainCovers(domain, host) {
+    const d = foldHost(domain.replace(/^\./, ''));
+    const h = foldHost(host);
+    return h === d || h.endsWith(`.${d}`);
+}
+function readFacts(state, baseUrl, now = Date.now()) {
+    let host = '';
+    try {
+        // `hostname`, never `host`: a cookie is not scoped by port (RFC 6265 ignores it
+        // entirely), so comparing `127.0.0.1` against `127.0.0.1:49331` reports a session on
+        // the right machine as belonging to another application. Caught by the live test on the
+        // first run, and it would have hit every `localhost:3000` in existence — a confidently
+        // wrong diagnosis, in the one verb written to stop those.
+        host = new URL(baseUrl).hostname;
+    }
+    catch {
+        /* an unusable baseUrl is the caller's problem to report */
+    }
+    const cookies = state.cookies ?? [];
+    const origins = state.origins ?? [];
+    // `expires` is seconds since epoch, and -1 means a session cookie: no stated expiry, which
+    // is not the same as expired. Counting those as gone would report a live session as dead.
+    const dated = cookies.filter((c) => typeof c.expires === 'number' && c.expires > 0);
+    const nowSeconds = now / 1000;
+    const expired = dated.filter((c) => c.expires < nowSeconds).length;
+    const future = dated.filter((c) => c.expires >= nowSeconds).map((c) => c.expires);
+    const expiresInSeconds = future.length > 0
+        ? Math.round(Math.min(...future) - nowSeconds)
+        : dated.length > 0
+            ? Math.round(Math.max(...dated.map((c) => c.expires)) - nowSeconds)
+            : null;
+    const domains = [...new Set(cookies.map((c) => c.domain ?? '').filter(Boolean))];
+    const coversHost = host === '' ||
+        domains.some((d) => domainCovers(d, host)) ||
+        origins.some((o) => {
+            try {
+                return foldHost(new URL(o.origin).hostname) === foldHost(host);
+            }
+            catch {
+                return false;
+            }
+        });
+    return { cookies: cookies.length, origins: origins.length, expired, expiresInSeconds, domains, coversHost, host };
+}
+/**
+ * The verdict, from the file's own facts plus — when one was possible — what the app
+ * answered.
+ *
+ * `landed` is undefined when no request was made, which is a legitimate state: the offline
+ * causes are conclusive on their own, and opening a browser to re-confirm an expiry date is
+ * a request nobody needs to make.
+ */
+function judgeSession(facts, replay, loginCommand = 'ia-qa-heal login') {
+    if (facts.cookies === 0 && facts.origins === 0) {
+        return {
+            cause: 'empty',
+            holds: false,
+            headline: 'This session file holds nothing — no cookies, no local storage.',
+            remedy: [
+                'A storageState carries cookies and local storage, and nothing else. An app that keeps',
+                'its token in IndexedDB, in memory or in a service worker leaves nothing for it to hold,',
+                'however logged in the browser was.',
+                `For those, capture during your own suite's run instead: IAQA_CAPTURE=1 with "testCommand".`,
+            ],
+        };
+    }
+    if (facts.cookies > 0 && facts.expired === facts.cookies) {
+        const ago = facts.expiresInSeconds === null ? '' : ` (the last one ${describeAge(-facts.expiresInSeconds)} ago)`;
+        return {
+            cause: 'expired',
+            holds: false,
+            headline: `Every cookie in this session has expired${ago}.`,
+            remedy: [`A person logs in again: ${loginCommand}`, 'Nothing about your app or your config is wrong.'],
+        };
+    }
+    if (!facts.coversHost) {
+        return {
+            cause: 'wrong-host',
+            holds: false,
+            headline: `Nothing in this session is scoped to ${facts.host} — its cookies are for ${facts.domains.length > 0 ? facts.domains.join(', ') : '(no domain stated)'}.`,
+            remedy: [
+                'The session and the baseUrl are about different applications, so logging in again will',
+                'produce the same file. Either point baseUrl at the host this session was taken on, or',
+                `take one on this host: ${loginCommand} --url ${facts.host ? `https://${facts.host}` : '<your app>'}`,
+                '(www. and the apex are treated as one host, so that difference is not the cause here.)',
+            ],
+        };
+    }
+    if (replay?.error) {
+        return {
+            cause: 'unknown',
+            holds: false,
+            headline: `The session looks usable, but the app could not be opened to confirm it: ${replay.error}`,
+            remedy: [
+                'This is not a verdict about the session — nothing was proven either way.',
+                'Check that the app is reachable from this machine, then run this again.',
+            ],
+        };
+    }
+    if (replay && !replay.wall) {
+        return {
+            cause: 'holds',
+            holds: true,
+            headline: `This session opens the app — landed on ${replay.landed}, no login form.`,
+            remedy: [],
+        };
+    }
+    if (replay?.wall) {
+        return {
+            cause: 'rotated',
+            holds: false,
+            headline: `The cookies are valid and scoped to ${facts.host}, but the app still answered with a login (landed on ${replay.landed}).`,
+            remedy: [
+                'The server dropped this session: a deploy, a secret rotation, a forced logout, or a',
+                'second factor it now asks for. Nothing in the file can say which.',
+                `A person logs in again: ${loginCommand}`,
+            ],
+        };
+    }
+    // No replay was attempted and no offline cause fired: the file is plausible, and plausible
+    // is not the same as working. Saying "holds" here is the exact false green this package
+    // exists to refuse.
+    return {
+        cause: 'unknown',
+        holds: false,
+        headline: 'This session file looks usable, but nothing opened the app to prove it.',
+        remedy: ['Run the check without --offline to find out.'],
+    };
+}
+/** "3 days", "4 hours", "12 minutes" — enough precision to act, never a timestamp to parse. */
+function describeAge(seconds) {
+    const s = Math.abs(Math.round(seconds));
+    if (s < 90)
+        return `${s} second${s === 1 ? '' : 's'}`;
+    const m = Math.round(s / 60);
+    if (m < 90)
+        return `${m} minute${m === 1 ? '' : 's'}`;
+    const h = Math.round(m / 60);
+    if (h < 48)
+        return `${h} hour${h === 1 ? '' : 's'}`;
+    const d = Math.round(h / 24);
+    return `${d} day${d === 1 ? '' : 's'}`;
+}
+//# sourceMappingURL=sessionCheck.js.map

package/dist/sessionCheck.js.map

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

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.16.0",
+  "version": "1.19.0",
   "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.