@ia-qa/self-healing 1.7.7 → 1.7.10

package/dist/explain.d.ts

@@ -0,0 +1,225 @@
+import { Usage } from './ingest';
+/**
+ * The core of `ia-qa-heal explain` — turn a test FAILURE into a drift verdict.
+ *
+ * Every other verb in this package starts from a *contract*: map, baseline, diff.
+ * Nobody arrives holding a contract. They arrive holding a red build and an error
+ * message, and until now there was no door for that. `explain` is the door: it takes
+ * whatever the runner printed, works out which locator the failure is about, and asks
+ * the existing two-moment machinery what happened to it.
+ *
+ * Two rules shape everything below, and both exist to keep this from becoming the
+ * guessing engine it would otherwise be:
+ *
+ * 1. **It never parses a runner's grammar.** Not `NoSuchElementException`, not
+ *    `Timed out retrying after 4000ms`, not `waiting for locator`. That list never ends
+ *    and rots at every upstream release. Instead the failure text is intersected with
+ *    the locator inventory `ingest` already built by reading the SOURCE — so the
+ *    question is never "what does this runner's error mean" but "does this text quote a
+ *    string my suite is known to use as a locator". That is framework-agnostic and
+ *    language-agnostic for free, and it hands back `file:line` as a side effect.
+ *
+ * 2. **The contract is the arbiter, never the extractor.** Bending the inventory
+ *    lookup (see below) means a stray key can now be read; the guard is that a matched
+ *    string still has to be judged against the mapping before it can produce anything
+ *    but BLOCK. A bad extraction therefore degrades to "I cannot tell", never to a
+ *    wrong rewrite.
+ *
+ * A note on rule 2, because it bends a documented invariant. `ingest.ts` says: *every
+ * consumer of `usage.selectors` looks it up by a selector taken from the contract, so a
+ * key matching no element is never read* — that is what licenses its permissive Page
+ * Object pattern. This file is the first consumer to look up by a string taken from a
+ * *message*. False-positive keys become reachable here, and the containment tier below
+ * is where that is most likely. It is bounded on purpose: such a candidate finds
+ * nothing in the contract and comes back `not-measured` / `not-in-contract` — BLOCK,
+ * for a human, which is exactly what "I matched something meaningless" should cost.
+ *
+ * This file is pure: no fs, no config, no console, no browser. It is handed the
+ * failure text, the inventory, and an already-computed diff. `cli/explain.ts` does the
+ * I/O, exactly as `checks.ts` / `cli/check.ts` are split.
+ */
+/** One failing test, as read from a JUnit file or from raw text. */
+export interface FailureInput {
+    /** The test name, when the source gave one. */
+    test?: string;
+    /** The file the runner attributed it to, when it said. Not the locator's file. */
+    file?: string;
+    /** message + detail, concatenated — the haystack. */
+    text: string;
+}
+/**
+ * How a locator was recovered from the failure text.
+ *
+ * `quoted` is an exact match against a string the message put in quotes — the shape
+ * essentially every runner uses, and effectively certain. `contained` is the fallback
+ * for messages that quote nothing; it is reported as such, because a reader deciding
+ * whether to trust a finding needs to know which of the two produced it.
+ */
+export type CandidateSource = 'quoted' | 'contained';
+export interface LocatorCandidate {
+    kind: 'selector' | 'name';
+    /** The literal as the inventory holds it — for a name, as the test file writes it. */
+    literal: string;
+    source: CandidateSource;
+    sites: Array<{
+        file: string;
+        line: number;
+    }>;
+}
+/**
+ * Why a locator got the verdict it got. Exported because the terminal, the JSON and the
+ * MCP tool all state it, and a fourth wording would be a fourth thing to drift.
+ */
+export type ExplainReason = 'resolves' | 'name-intact' | 'broken-repairable' | 'renamed-repairable' | 'rebound' | 'ambiguous' | 'gone' | 'unattributable' | 'never-bound' | 'not-in-contract' | 'not-measured';
+export interface ExplainFinding {
+    kind: 'selector' | 'name';
+    literal: string;
+    source: CandidateSource;
+    verdict: 'PASS' | 'FIX' | 'BLOCK';
+    reason: ExplainReason;
+    /** Every place the suite writes this literal, from the inventory. */
+    sites: Array<{
+        file: string;
+        line: number;
+    }>;
+    /** Which mapped page produced the verdict, when one did. */
+    page?: string;
+    /**
+     * The rewrite to PROPOSE. Never applied here — `explain` is read-only, and the
+     * apply path stays `fix`, with all of its refusals intact.
+     */
+    repair?: {
+        from: string;
+        to: string;
+    };
+    /** What the locator reaches now — `rebound` only, and the reason it is BLOCK. */
+    now?: string;
+}
+export interface ExplainReport {
+    verdict: 'PASS' | 'FIX' | 'BLOCK';
+    failuresRead: number;
+    findings: ExplainFinding[];
+    /**
+     * Quoted strings in the failure that LOOK like locators but are in no inventory.
+     * Named rather than guessed at: it usually means `ingest` has not seen the file,
+     * or the locator is built dynamically and no static scan can reach it.
+     */
+    unmatched: string[];
+    pagesCompared: number;
+    /** Pairs the diff could not judge. A page left out is never counted as a pass. */
+    stalePages: string[];
+}
+export declare function unescapeXml(s: string): string;
+/**
+ * Read the failures out of a JUnit XML report.
+ *
+ * JUnit is the input format for the same reason `--junit` is an output format here:
+ * every major runner in every language either emits it or has a reporter that does, so
+ * one parser covers pytest, Jest, Playwright, Cypress, JUnit, WebdriverIO, Robot and
+ * whatever comes next — without this package knowing any of them exist.
+ *
+ * Hand-rolled on purpose: this package ships with one runtime dependency and an XML
+ * library for four regexes would be a poor trade. There is no official JUnit XSD, so
+ * the conservative intersection is all that is safe to rely on anyway — `testcase`
+ * carrying `failure` or `error`, either self-closed or with a body.
+ */
+export declare function parseJUnitFailures(xml: string): FailureInput[];
+/**
+ * Every quoted run in the text, in the three quote styles error messages use.
+ *
+ * This is the whole of the "parser": runners quote the locator they could not find —
+ * `'.btn-primary'`, `"#pay-now"`, `` `Pay now` `` — and that convention is shared far
+ * more widely than any message grammar. Newlines terminate a run so an unbalanced quote
+ * in a stack trace cannot swallow the rest of the report.
+ *
+ * The three styles are scanned INDEPENDENTLY, and that is not a detail. One alternating
+ * regex scans left to right and lets whichever quote opens first consume everything
+ * after it — so WebdriverIO's `Can't call click on element with selector ".btn-primary"
+ * because element wasn't found` pairs the apostrophes of *Can't* and *wasn't*, swallows
+ * the real locator between them, and the failure comes back with nothing found. English
+ * prose is full of apostrophes; a separate pass per style cannot lose a locator to one.
+ *
+ * The cost is over-generation — that apostrophe pair still yields its nonsense run — and
+ * it is free: every run is then looked up in the inventory, and a run that names nothing
+ * a test writes matches nothing and disappears.
+ */
+export declare function quotedRuns(text: string): string[];
+/**
+ * Which inventoried locators does this failure name?
+ *
+ * Two tiers, and the second is skipped per kind as soon as the first finds anything:
+ * a message that quotes its locators has told us which they are, and adding
+ * containment hits on top of that only adds noise to an answer we already have.
+ */
+export declare function extractLocators(failures: FailureInput[], usage: Usage): {
+    candidates: LocatorCandidate[];
+    unmatched: string[];
+};
+/**
+ * The shapes this file needs out of an already-computed diff, declared structurally
+ * rather than imported from `cli/diff.ts`.
+ *
+ * Same reason `nameDrift.ts` declares `RenamedRowLike`: it keeps the judge a pure
+ * function with no import edge into the CLI layer, so a test can hand it two literals
+ * and a hand-written report without a filesystem, a config, or a browser.
+ */
+export interface ExplainRowLike {
+    status: string;
+    role: string;
+    name: string;
+    selector: string;
+    newName?: string;
+    healedSelector?: string;
+}
+export interface ExplainNameFindingLike {
+    oldName: string;
+    newName: string;
+    fixable: boolean;
+    unattributable: Array<{
+        file: string;
+        line: number;
+    }>;
+}
+export interface ExplainBindingLike {
+    selector: string;
+    was: string;
+    status: string;
+    now?: string;
+    healedSelector?: string;
+}
+export interface ExplainPageLike {
+    name: string;
+    rows: ExplainRowLike[];
+    nameDrift?: ExplainNameFindingLike[];
+    bindingDrift?: ExplainBindingLike[];
+}
+/**
+ * What the CURRENT capture saw each inventoried selector reach — `mapping/_resolved/`.
+ *
+ * Needed for the half of the answer a diff cannot give. A diff is silent about a
+ * selector that did not drift, and silence has two meanings that must never be
+ * conflated: *it still resolves* (PASS, the real product of this verb) and *nobody ever
+ * probed it* (not measured, and never a pass). Only the resolution files separate them.
+ */
+export type ResolutionIndex = Map<string, Array<{
+    page: string;
+    status: string;
+}>>;
+export declare function judgeLocators(candidates: LocatorCandidate[], pages: ExplainPageLike[], resolutions: ResolutionIndex): ExplainFinding[];
+/**
+ * The verdict of the whole failure — the worst of its locators.
+ *
+ * PASS only when every locator resolves, and it is the answer this verb exists for:
+ * *your selectors are fine, this red build is about something else*. It says nothing
+ * about what that something else is. A re-run that passes proves "not reproducible
+ * right now", never "flaky", and this tool has not re-run anything at all.
+ */
+export declare function explainVerdict(findings: ExplainFinding[]): 'PASS' | 'FIX' | 'BLOCK';
+export declare function explainHeadline(r: Pick<ExplainReport, 'verdict' | 'findings'>): string;
+export declare function explainCounts(r: Pick<ExplainReport, 'failuresRead' | 'pagesCompared' | 'stalePages'>): string[];
+/**
+ * The one-line "what do I do now" per reason, shared by every surface that renders a
+ * finding. Kept here so the terminal, the JSON and an agent cannot word the same
+ * verdict differently — the rule `checkHeadline` and `auditHeadline` already follow.
+ */
+export declare const REASON_ADVICE: Record<ExplainReason, string>;

package/dist/explain.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REASON_ADVICE = void 0;
+exports.unescapeXml = unescapeXml;
+exports.parseJUnitFailures = parseJUnitFailures;
+exports.quotedRuns = quotedRuns;
+exports.extractLocators = extractLocators;
+exports.judgeLocators = judgeLocators;
+exports.explainVerdict = explainVerdict;
+exports.explainHeadline = explainHeadline;
+exports.explainCounts = explainCounts;
+const ingest_1 = require("./ingest");
+const nameLocators_1 = require("./nameLocators");
+/* ------------------------------------------------------------------ *
+ * JUnit input
+ * ------------------------------------------------------------------ */
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+function unescapeXml(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+        if (body[0] === '#') {
+            const code = body[1] === 'x' || body[1] === 'X'
+                ? parseInt(body.slice(2), 16)
+                : parseInt(body.slice(1), 10);
+            return Number.isFinite(code) && code > 0 ? String.fromCodePoint(code) : whole;
+        }
+        const hit = ENTITIES[body.toLowerCase()];
+        return hit === undefined ? whole : hit;
+    });
+}
+function attrs(raw) {
+    const out = {};
+    const re = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+    let m;
+    while ((m = re.exec(raw)) !== null) {
+        out[m[1]] = unescapeXml(m[2] !== undefined ? m[2] : m[3]);
+    }
+    return out;
+}
+/**
+ * Read the failures out of a JUnit XML report.
+ *
+ * JUnit is the input format for the same reason `--junit` is an output format here:
+ * every major runner in every language either emits it or has a reporter that does, so
+ * one parser covers pytest, Jest, Playwright, Cypress, JUnit, WebdriverIO, Robot and
+ * whatever comes next — without this package knowing any of them exist.
+ *
+ * Hand-rolled on purpose: this package ships with one runtime dependency and an XML
+ * library for four regexes would be a poor trade. There is no official JUnit XSD, so
+ * the conservative intersection is all that is safe to rely on anyway — `testcase`
+ * carrying `failure` or `error`, either self-closed or with a body.
+ */
+function parseJUnitFailures(xml) {
+    const out = [];
+    const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase\s*>)/g;
+    let c;
+    while ((c = caseRe.exec(xml)) !== null) {
+        const body = c[2];
+        if (!body)
+            continue;
+        const meta = attrs(c[1]);
+        const failRe = /<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1\s*>)/g;
+        let f;
+        while ((f = failRe.exec(body)) !== null) {
+            const fa = attrs(f[2]);
+            const detail = f[3] ? unescapeXml(stripCdata(f[3])) : '';
+            const text = [fa.message ?? '', detail].filter(Boolean).join('\n');
+            if (!text.trim())
+                continue;
+            out.push({
+                test: meta.name || undefined,
+                file: meta.file || meta.classname || undefined,
+                text,
+            });
+        }
+    }
+    return out;
+}
+function stripCdata(s) {
+    return s.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1');
+}
+/* ------------------------------------------------------------------ *
+ * Extraction — intersection, not parsing
+ * ------------------------------------------------------------------ */
+/**
+ * A `contained` match must be at least this long. Short literals turn a long stack
+ * trace into a lottery: `.btn` occurs inside a dozen unrelated words, and a false
+ * candidate costs a reader more than a missed one — they can always pass `--message`
+ * with the locator themselves.
+ */
+const MIN_CONTAINED = 5;
+/** Beyond this, the failure is not about one locator and listing more helps nobody. */
+const MAX_CANDIDATES = 25;
+/**
+ * Every quoted run in the text, in the three quote styles error messages use.
+ *
+ * This is the whole of the "parser": runners quote the locator they could not find —
+ * `'.btn-primary'`, `"#pay-now"`, `` `Pay now` `` — and that convention is shared far
+ * more widely than any message grammar. Newlines terminate a run so an unbalanced quote
+ * in a stack trace cannot swallow the rest of the report.
+ *
+ * The three styles are scanned INDEPENDENTLY, and that is not a detail. One alternating
+ * regex scans left to right and lets whichever quote opens first consume everything
+ * after it — so WebdriverIO's `Can't call click on element with selector ".btn-primary"
+ * because element wasn't found` pairs the apostrophes of *Can't* and *wasn't*, swallows
+ * the real locator between them, and the failure comes back with nothing found. English
+ * prose is full of apostrophes; a separate pass per style cannot lose a locator to one.
+ *
+ * The cost is over-generation — that apostrophe pair still yields its nonsense run — and
+ * it is free: every run is then looked up in the inventory, and a run that names nothing
+ * a test writes matches nothing and disappears.
+ */
+function quotedRuns(text) {
+    const hits = [];
+    for (const re of [/'([^'\n]{1,200})'/g, /"([^"\n]{1,200})"/g, /`([^`\n]{1,200})`/g]) {
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            if (m[1] && m[1].trim())
+                hits.push({ at: m.index, value: m[1] });
+        }
+    }
+    return hits.sort((a, b) => a.at - b.at).map((h) => h.value);
+}
+/**
+ * Which inventoried locators does this failure name?
+ *
+ * Two tiers, and the second is skipped per kind as soon as the first finds anything:
+ * a message that quotes its locators has told us which they are, and adding
+ * containment hits on top of that only adds noise to an answer we already have.
+ */
+function extractLocators(failures, usage) {
+    const text = failures.map((f) => f.text).join('\n');
+    const runs = quotedRuns(text);
+    const runSet = new Set(runs);
+    const normRuns = new Set(runs.map((r) => (0, nameLocators_1.normalizeName)(r)));
+    const selectorKeys = Object.keys(usage.selectors ?? {});
+    const nameKeys = Object.keys(usage.names ?? {});
+    const selectors = [];
+    const names = [];
+    for (const key of selectorKeys) {
+        if (!runSet.has(key))
+            continue;
+        selectors.push({
+            kind: 'selector',
+            literal: key,
+            source: 'quoted',
+            sites: (usage.selectors[key] ?? []).map((s) => ({ file: s.file, line: s.line })),
+        });
+    }
+    for (const key of nameKeys) {
+        if (!normRuns.has(key))
+            continue;
+        const sites = usage.names?.[key] ?? [];
+        names.push({
+            kind: 'name',
+            // The inventory is keyed normalized, but every message a human reads must quote
+            // what is actually in their file — `"save"` when the line says `'Save'` costs a grep.
+            literal: sites[0]?.text ?? key,
+            source: 'quoted',
+            sites: sites.map((s) => ({ file: s.file, line: s.line })),
+        });
+    }
+    if (selectors.length === 0) {
+        for (const key of selectorKeys) {
+            if (key.length < MIN_CONTAINED || !text.includes(key))
+                continue;
+            selectors.push({
+                kind: 'selector',
+                literal: key,
+                source: 'contained',
+                sites: (usage.selectors[key] ?? []).map((s) => ({ file: s.file, line: s.line })),
+            });
+        }
+    }
+    if (names.length === 0) {
+        const normText = (0, nameLocators_1.normalizeName)(text);
+        for (const key of nameKeys) {
+            if (key.length < MIN_CONTAINED || !normText.includes(key))
+                continue;
+            const sites = usage.names?.[key] ?? [];
+            names.push({
+                kind: 'name',
+                literal: sites[0]?.text ?? key,
+                source: 'contained',
+                sites: sites.map((s) => ({ file: s.file, line: s.line })),
+            });
+        }
+    }
+    const candidates = [...dropSubsumed(selectors), ...dropSubsumed(names)].slice(0, MAX_CANDIDATES);
+    // A quoted string that reads like a selector and is in no inventory is worth naming:
+    // it is the signature of an un-ingested file or of a dynamically built locator, and
+    // both are things the user can act on. Silence there would look like "nothing found".
+    const known = new Set(selectorKeys);
+    const knownNames = new Set(nameKeys);
+    const unmatched = Array.from(new Set(runs)).filter((r) => (0, ingest_1.plausibleSelector)(r) && !known.has(r) && !knownNames.has((0, nameLocators_1.normalizeName)(r)));
+    return { candidates, unmatched };
+}
+/**
+ * Drop a `contained` literal that sits inside a longer accepted one — `.btn` reported
+ * beside `.btn-primary` is one finding pretending to be two. `quoted` literals are
+ * never dropped: if the message quoted `.btn`, then `.btn` is what failed, whatever
+ * else the inventory happens to contain.
+ */
+function dropSubsumed(list) {
+    const sorted = [...list].sort((a, b) => b.literal.length - a.literal.length);
+    const kept = [];
+    for (const c of sorted) {
+        if (c.source === 'contained' && kept.some((k) => k.literal.includes(c.literal)))
+            continue;
+        kept.push(c);
+    }
+    return kept;
+}
+const HEALTHY_BINDING = new Set(['bound', 'anchored', 'outside']);
+function judgeSelector(c, pages, resolutions) {
+    const base = { kind: 'selector', literal: c.literal, source: c.source, sites: c.sites };
+    // The two-moment verdict first: it is the only one that can see a binding that broke,
+    // and the only one that can see the worst case here — a string that now reaches a
+    // DIFFERENT element, where the test goes green and acts on the wrong thing.
+    for (const p of pages) {
+        const d = (p.bindingDrift ?? []).find((x) => x.selector === c.literal);
+        if (!d)
+            continue;
+        if (d.status === 'broken' && d.healedSelector) {
+            return { ...base, verdict: 'FIX', reason: 'broken-repairable', page: p.name,
+                repair: { from: c.literal, to: d.healedSelector } };
+        }
+        if (d.status === 'rebound') {
+            return { ...base, verdict: 'BLOCK', reason: 'rebound', page: p.name, now: d.now };
+        }
+        if (d.status === 'ambiguous') {
+            return { ...base, verdict: 'BLOCK', reason: 'ambiguous', page: p.name };
+        }
+        return { ...base, verdict: 'BLOCK', reason: 'gone', page: p.name };
+    }
+    // The literal may itself BE a contract selector (a suite written against `map`'s
+    // output, or a `data-testid` the extractor also picked). Then the element rows judge it.
+    for (const p of pages) {
+        const row = p.rows.find((r) => r.selector === c.literal);
+        if (!row)
+            continue;
+        if (row.status === 'healable' && row.healedSelector) {
+            return { ...base, verdict: 'FIX', reason: 'broken-repairable', page: p.name,
+                repair: { from: c.literal, to: row.healedSelector } };
+        }
+        if (row.status === 'ok' || row.status === 'renamed') {
+            return { ...base, verdict: 'PASS', reason: 'resolves', page: p.name };
+        }
+        if (row.status === 'rebound')
+            return { ...base, verdict: 'BLOCK', reason: 'rebound', page: p.name };
+        if (row.status === 'ambiguous')
+            return { ...base, verdict: 'BLOCK', reason: 'ambiguous', page: p.name };
+        return { ...base, verdict: 'BLOCK', reason: 'gone', page: p.name };
+    }
+    // No drift row. Did anything actually look at this string?
+    const seen = resolutions.get(c.literal);
+    if (!seen || seen.length === 0) {
+        return { ...base, verdict: 'BLOCK', reason: 'not-measured' };
+    }
+    const healthy = seen.find((s) => HEALTHY_BINDING.has(s.status));
+    if (healthy)
+        return { ...base, verdict: 'PASS', reason: 'resolves', page: healthy.page };
+    if (seen.some((s) => s.status === 'ambiguous')) {
+        return { ...base, verdict: 'BLOCK', reason: 'ambiguous', page: seen[0].page };
+    }
+    // Probed everywhere, reaches nothing anywhere — and it did not break between the two
+    // moments, so there is no surviving element to heal towards. `audit` is the verb that
+    // answers "did it ever exist", not this one.
+    return { ...base, verdict: 'BLOCK', reason: 'never-bound', page: seen[0].page };
+}
+function judgeName(c, pages) {
+    const base = { kind: 'name', literal: c.literal, source: c.source, sites: c.sites };
+    const key = (0, nameLocators_1.normalizeName)(c.literal);
+    for (const p of pages) {
+        const f = (p.nameDrift ?? []).find((x) => (0, nameLocators_1.normalizeName)(x.oldName) === key);
+        if (!f)
+            continue;
+        // A rewrite this tool cannot prove correct is not a rewrite. `getByText` and
+        // `cy.contains` name a string without saying what carries it, and the contract holds
+        // interactive elements only — editing one could break a test that was passing.
+        if (f.unattributable.length > 0) {
+            return { ...base, verdict: 'BLOCK', reason: 'unattributable', page: p.name };
+        }
+        if (f.fixable) {
+            return { ...base, verdict: 'FIX', reason: 'renamed-repairable', page: p.name,
+                repair: { from: c.literal, to: f.newName } };
+        }
+        return { ...base, verdict: 'BLOCK', reason: 'ambiguous', page: p.name };
+    }
+    for (const p of pages) {
+        const row = p.rows.find((r) => (0, nameLocators_1.normalizeName)(r.name) === key);
+        if (!row)
+            continue;
+        // `healable` moved the SELECTOR, not the label — a locator that names a role and a
+        // name does not care where the element sits in the DOM. For this kind, that is a pass.
+        if (row.status === 'ok' || row.status === 'healable') {
+            return { ...base, verdict: 'PASS', reason: 'name-intact', page: p.name };
+        }
+        if (row.status === 'ambiguous')
+            return { ...base, verdict: 'BLOCK', reason: 'ambiguous', page: p.name };
+        if (row.status === 'rebound')
+            return { ...base, verdict: 'BLOCK', reason: 'rebound', page: p.name };
+        // `renamed` with no nameDrift finding beside it means the inventory never saw this
+        // call site. Reporting the label as intact would be exactly wrong.
+        return { ...base, verdict: 'BLOCK', reason: row.status === 'renamed' ? 'unattributable' : 'gone', page: p.name };
+    }
+    // The label is nowhere in the compared pages. That is not a pass — it may live on a
+    // page nobody mapped, which is a coverage answer, not a drift one.
+    return { ...base, verdict: 'BLOCK', reason: 'not-in-contract' };
+}
+function judgeLocators(candidates, pages, resolutions) {
+    const findings = candidates.map((c) => c.kind === 'selector' ? judgeSelector(c, pages, resolutions) : judgeName(c, pages));
+    const rank = { BLOCK: 0, FIX: 1, PASS: 2 };
+    return findings.sort((a, b) => rank[a.verdict] - rank[b.verdict]);
+}
+/**
+ * The verdict of the whole failure — the worst of its locators.
+ *
+ * PASS only when every locator resolves, and it is the answer this verb exists for:
+ * *your selectors are fine, this red build is about something else*. It says nothing
+ * about what that something else is. A re-run that passes proves "not reproducible
+ * right now", never "flaky", and this tool has not re-run anything at all.
+ */
+function explainVerdict(findings) {
+    if (findings.some((f) => f.verdict === 'BLOCK'))
+        return 'BLOCK';
+    if (findings.some((f) => f.verdict === 'FIX'))
+        return 'FIX';
+    return 'PASS';
+}
+function explainHeadline(r) {
+    const n = r.findings.length;
+    const locs = `${n} locator${n === 1 ? '' : 's'}`;
+    if (r.verdict === 'PASS')
+        return `PASS · ${locs} still resolve${n === 1 ? 's' : ''} — not selector drift`;
+    if (r.verdict === 'FIX') {
+        const k = r.findings.filter((f) => f.verdict === 'FIX').length;
+        return `FIX · ${k} of ${locs} drifted, repair proposed`;
+    }
+    const k = r.findings.filter((f) => f.verdict === 'BLOCK').length;
+    return `BLOCK · ${k} of ${locs} need${k === 1 ? 's' : ''} a human`;
+}
+function explainCounts(r) {
+    return [
+        `${r.failuresRead} failure${r.failuresRead === 1 ? '' : 's'} read`,
+        `${r.pagesCompared} page${r.pagesCompared === 1 ? '' : 's'} compared`,
+        r.stalePages.length > 0 ? `${r.stalePages.length} stale` : '',
+    ].filter(Boolean);
+}
+/**
+ * The one-line "what do I do now" per reason, shared by every surface that renders a
+ * finding. Kept here so the terminal, the JSON and an agent cannot word the same
+ * verdict differently — the rule `checkHeadline` and `auditHeadline` already follow.
+ */
+exports.REASON_ADVICE = {
+    resolves: 'This selector still reaches its element. The failure is not drift — look at timing, test data, or an app error.',
+    'name-intact': 'This label still exists on the mapped contract. The failure is not a rename — look elsewhere.',
+    'broken-repairable': 'The string reaches nothing, but its element survived. `ia-qa-heal fix` can rewrite it.',
+    'renamed-repairable': 'The element is the same, its label changed. `ia-qa-heal fix` can rewrite the role-stating calls.',
+    rebound: 'WORST CASE: it now reaches a DIFFERENT element. The test can go green while acting on the wrong thing. Never rewritten automatically — read it yourself.',
+    ambiguous: 'Two or more elements answer to this. Any rewrite would be a coin flip, so none is offered.',
+    gone: 'The element it pointed at is not in the current capture. Nothing to rewrite towards.',
+    unattributable: 'The call names a string without saying what carries it (getByText, cy.contains…). Rewriting it could break a test that was passing, so it is only reported.',
+    'never-bound': 'This string reached nothing at either moment. It is not drift — check the selector was ever correct, or that the page is mapped.',
+    'not-in-contract': 'No compared page holds this label. It may live on a page you do not map — `ia-qa-heal discover` lists those.',
+    'not-measured': 'Nothing probed this string. Run `ia-qa-heal ingest` then `ia-qa-heal map` so the binding exists, then ask again.',
+};
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

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

package/dist/ingest.d.ts

@@ -56,6 +56,19 @@ export declare function usagePath(cwd?: string): string;
  * Shared call shapes (`.type`, `.press`, `.fill`…) take text in one framework and
  * a selector in another, so a captured literal is only recorded when it *reads*
  * like a selector. A bare tag (`click('button')`) is the accepted miss.
+ *
+ * "Reads like a selector" used to mean *contains a structural character* — a `>`,
+ * a `[`, a leading `.`. That test cannot tell `div > span` from `age > 18`, and
+ * the permissive Page Object shape below offers it every `foo = '…'` in the suite,
+ * so a SQL condition typed into a field was inventoried as a selector. The cost
+ * was argued as one line in an advisory count; `explain` then made it a red gate
+ * (`exit 1`) pointing at a healthy test line. So the test is now *validity*, not
+ * presence: `18` is not a type selector, `.5` is not a class, `fix:` is not a
+ * pseudo. Seven of the eight parasites in the reference corpus are refused by the
+ * grammar alone, and none of them needed a list of known-bad shapes.
+ *
+ * What the grammar cannot see stays: `a.b.c` is a valid selector whether it names
+ * an element or a JWT. That residue is real and is not worth a length heuristic.
  */
 export declare function plausibleSelector(value: string): boolean;
 export declare function scanText(text: string, file: string): Array<{