@ia-qa/self-healing 1.5.7 → 1.6.1

package/README.md

@@ -279,13 +279,84 @@ The shard format **is** the interface; the Playwright/Cypress/Selenium helpers a
 
 Any `*.json` in that directory is merged into contracts by the next `ia-qa-heal` verb — named to match `config.pages` so it pairs with your baseline. That is the whole contract: no import, no Node required.
 
-### Selector inventory — `ia-qa-heal ingest`
+### Locator inventory — `ia-qa-heal ingest`
 
 ```bash
 npx ia-qa-heal ingest tests/        # or no args: reads config.testPaths
 ```
 
-Statically scans your tests/POMs for selector literals (Playwright, Cypress, Selenium call shapes + `…Selector = '…'` properties) → `.ia-qa/usage.json`. With it, `diff` annotates every drifted selector with *used N× in M test files* / *not referenced by your tests*, and `fix` no longer needs the test paths on the command line. Display-only: the verdict still judges the whole contract.
+Statically scans your tests/POMs → `.ia-qa/usage.json`. Two halves, because suites are written two ways:
+
+- **Selectors** — Playwright, Cypress, Selenium call shapes + `…Selector = '…'` properties. `diff` annotates every drifted selector with *used N× in M test files*, and `fix` no longer needs the test paths on the command line.
+- **Names** — the `get|find|queryBy…` family (Playwright, Testing Library, `@testing-library/cypress`): `ByRole`, `ByLabel(Text)`, `ByPlaceholder(Text)`, `ByText`, `ByTitle`, `ByAltText` — plus `cy.contains(…)` (both forms) and Selenium's `By.linkText` / `By.LINK_TEXT` / `By.PARTIAL_LINK_TEXT`. These are what makes the rename gate below possible.
+
+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.
+
+### 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.
+
+Once `ingest` has run, `diff` cross-references every rename against what your tests reference:
+
+| Situation | Verdict | What `fix` does |
+|---|---|---|
+| No test names that label | unchanged (`PASS`) | nothing — adopting this adds no noise |
+| One element carries the new label | **FIX** | rewrites the call: `getByRole('button', { name: 'Enregistrer' })` |
+| The **old** label now sits on another element | **BLOCK** | nothing — your locator would silently target the wrong element (the name-space twin of `rebound`) |
+| Several elements carry the new label | **BLOCK** | nothing — a human picks |
+| The reference is text-anchored (see below) | **BLOCK** | nothing — reported with its `file:line` |
+
+**Only calls that state a role are ever rewritten.** That is the line between the two halves of the inventory, and it is not arbitrary:
+
+| Rewritten | Reported, never rewritten |
+|---|---|
+| `getByRole` / `findByRole` / `queryByRole` (Playwright, Testing Library, `@testing-library/cypress`) | `getByText` / `findByText` |
+| `getByLabel` · `getByLabelText` · `getByPlaceholder(Text)` — the role is implied | `cy.contains(…)`, both forms |
+| `By.linkText` / `By.LINK_TEXT` / `By.PARTIAL_LINK_TEXT` (Selenium: role = link) | `getByTitle` · `getByAltText` |
+
+`getByText('Archive')` names a *string*, not an element, and the contract maps interactive elements only — so it cannot prove the test meant the renamed button rather than a heading that never moved. Rewriting it would break a test that was passing, which is worse than any drift this tool detects. Those references are printed with their `file:line` and hold the verdict at BLOCK for a human instead.
+
+Without `usage.json` nothing is escalated at all, so an un-ingested project behaves exactly as before.
+
+### Is the app itself sound? — `ia-qa-heal check`
+
+```bash
+npx ia-qa-heal check              # dead links + static checks
+npx ia-qa-heal check --offline    # skip the network half, fully local
+npx ia-qa-heal check --strict     # fail the pipeline on warnings too
+```
+
+`diff` answers *what moved since the baseline?*. `check` answers what a diff structurally cannot: **is the current contract healthy at all?** A green diff over a page whose every link 404s is still a green diff — verified on a sample app where `diff` exits 0 and `check` exits 1 at the same instant.
+
+Every check is admitted under one rule: **it must be able to fail for a reason a contract diff would not already catch.** "The button still exists" is rejected by that rule — `diff` proves it better and without a browser. What survives:
+
+| Check | Fails when | Verdict |
+|---|---|---|
+| **dead links** | the app answered 4xx/5xx (401/403 excluded — that is a working link behind auth) | **FAIL** |
+| **unnamed** | an interactive element has no accessible name: no screen-reader announcement, no `getByRole`, no healing | WARN |
+| **ambiguous** | two elements share role + name — every name-anchored locator for them is a coin flip, and a strict-mode violation waiting | WARN |
+| **orphans** | a mapped page nothing links to | WARN |
+
+FAIL is reserved for a fact the app itself stated. The rest are real but arguable — an unnamed icon button, a deep-link-only page — so they warn and exit 0 unless you ask for `--strict`. A gate nobody can leave on is a gate nobody turns on.
+
+**Findings are de-duplicated across pages.** A navbar repeated on 142 pages is one thing to fix, not 142 findings — same reasoning that puts shared layouts in `_layouts/` for the diff.
+
+**Network.** The link check requests URLs on your own `baseUrl` and nothing else: same site only, GET only, and never a URL that *acts* — `/logout`, `/orders/1/delete` and friends are skipped using the same denylist as `discover --crawl`, because a GET on those is not a check, it is a logout or a deletion. The run announces the host and the count **before** the first request. `--offline` drops that half entirely.
+
+### Day one, no baseline — `ia-qa-heal audit`
+
+```bash
+npx ia-qa-heal audit tests/         # advisory, exit 0
+npx ia-qa-heal audit --strict       # exit 1 on a finding
+```
+
+Every other verb compares two moments, so its value arrives one drift *after* you install it. Nobody adopts a healing tool before their tests break. `audit` answers the question you have on the day you arrive — *does my suite still name things that exist?* — from a **single capture**: it cross-references the inventory against `mapping/` and flags locators that match no element, with the closest live label as a suggestion.
+
+Deliberately conservative, and it says so out loud:
+
+- Only **role-anchored** locators carry the verdict, and only for roles a contract can hold. `getByText('Terms of service')` may point at a paragraph `map` never captured, and `getByRole('heading', …)` at a heading it never captures — their absence proves nothing, so they are counted and not judged.
+- **Advisory by default** (exit 0). A "missing" locator may live on a page not in `config.pages`, or in a page *state* `map` never saw (a label behind a tab or a mode toggle). Both caveats are printed next to the findings. Add `--strict` once your coverage is real.
+- Read-only. `audit` never edits and never applies a suggestion.
 
 ### Elements with no accessible name
 
@@ -296,7 +367,7 @@ An icon button or image link with no `aria-label`/text has **no role + name iden
 | | For | Entry point |
 |---|---|---|
 | **MCP server** (stdio) | AI agents — "map my app at \<url\>" | `ia-qa-heal-mcp` → tools `map_app`, `diff_mappings`, `fix_tests`, `suggest_heal` (optional AI) |
-| **CLI** | humans & CI | `ia-qa-heal` → `init`, `discover`, `map`, `baseline`, `diff`, `fix`, `ingest`, `run` |
+| **CLI** | humans & CI | `ia-qa-heal` → `init`, `discover`, `map`, `baseline`, `diff`, `fix`, `ingest`, `audit`, `run` |
 | **AI add-on** (optional, BYOK) | semantic renames the deterministic engine gives up on | `ia-qa-heal-ai` → `suggest` — see [Optional AI add-on](#optional-ai-add-on--semantic-suggestions-ia-qa-heal-ai-byok) |
 
 ### Locale
@@ -513,11 +584,14 @@ jobs:
         with: { node-version: '20' }
       - run: npm ci
       - run: npx playwright install --with-deps chromium
-      - run: npm start &          # your app on its usual port
-      - run: npx ia-qa-heal map   # re-capture into .ia-qa/mapping/
-      - run: npx ia-qa-heal diff  # 0 = PASS/FIX · 1 = BLOCK · 2 = bad input
+      - run: npm start &            # your app on its usual port
+      - run: npx ia-qa-heal map     # re-capture into .ia-qa/mapping/
+      - run: npx ia-qa-heal ingest  # inventory selectors AND names your tests use
+      - run: npx ia-qa-heal diff    # 0 = PASS/FIX · 1 = BLOCK · 2 = bad input
 ```
 
+`ingest` is what makes the gate see a rename your tests locate by name. Skip it and `diff` judges selectors only — which is what it did before 1.6.0, and what it still does for any project without a `usage.json`.
+
 `diff` with no arguments compares the committed `.ia-qa/baseline/` against what `map` just re-captured — which is why the baseline has to be in git. Add `--report drift-report.html` to attach a branded HTML report to the build, and `--strict` to fail on FIX too. The full workflow (report upload, artifact, `--strict`) is in **[TUTORIAL.md → Putting it in CI](TUTORIAL.md#8-putting-it-in-ci)**.
 
 ## Map artifacts

package/dist/checks.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Contract checks — the assertions a mapped app answers on its own.
+ *
+ * `diff` compares two moments and says what moved. These say something a diff
+ * never can: whether the *current* contract is sound at all. They exist under one
+ * rule, and it is the rule that keeps this from becoming a generator of tests
+ * that pass forever —
+ *
+ *   **a check earns its place only if it can fail for a reason the contract diff
+ *   would not already catch.**
+ *
+ * "This button still exists" fails that test: `diff` proves it better, faster,
+ * and without a browser. "This link 404s", "two buttons share a name", "no page
+ * links here" all pass it — a diff is green on every one of them.
+ *
+ * Pure functions over contracts: no I/O, no network, no config. The CLI does the
+ * reading and the fetching; this file is what the tests can hold still.
+ */
+export interface CheckElement {
+    role: string;
+    name: string;
+    selector: string;
+    context?: string;
+    href?: string;
+}
+export interface CheckPage {
+    /** Mapping file basename — `_layouts/foo` for a shared layout. */
+    page: string;
+    /** The page's own URL as captured, absolute or path. */
+    url?: string;
+    elements: CheckElement[];
+    isLayout?: boolean;
+}
+export interface UnnamedFinding {
+    role: string;
+    selector: string;
+    context?: string;
+    /** Every page carrying it — one entry means one place to fix. */
+    pages: string[];
+}
+/**
+ * An interactive element with no accessible name.
+ *
+ * Three separate failures in one: a screen reader announces nothing, a
+ * `getByRole` locator cannot target it, and self-healing cannot recover it after
+ * a move — identity here *is* role + name. This is the precondition of
+ * everything else this package does, which is why it is checked rather than
+ * merely counted.
+ */
+export declare function findUnnamed(pages: CheckPage[]): UnnamedFinding[];
+export interface AmbiguousFinding {
+    role: string;
+    name: string;
+    count: number;
+    selectors: string[];
+    /** Every page where this exact collision occurs. */
+    pages: string[];
+}
+/**
+ * Two elements on one page sharing a role AND an accessible name.
+ *
+ * Every name-anchored locator for them is a coin flip — `getByRole('button', {
+ * name: 'Edit' })` raises a Playwright strict-mode violation, and the healer
+ * reports `ambiguous` and refuses. This is drift that has not happened yet: the
+ * check names it while it is still cheap to fix with a `data-testid`.
+ *
+ * Layout elements are excluded from a page's count by the caller — a navbar
+ * repeated on 40 pages is one element, not 40 collisions.
+ */
+export declare function findAmbiguousNames(pages: CheckPage[]): AmbiguousFinding[];
+export interface OrphanFinding {
+    page: string;
+    url: string;
+}
+/**
+ * A configured page that no *other* mapped page links to.
+ *
+ * Either the navigation lost a link (a real regression a selector diff shows as
+ * a perfectly healthy `lost` on some other page, or not at all), or the page is
+ * deep-link-only and the finding is noise the user dismisses once. Reported, not
+ * failed, for exactly that reason.
+ *
+ * Links from layouts count: a navbar entry is how most pages are reached.
+ */
+export declare function findOrphanPages(pages: CheckPage[], pathOf: (href: string) => string | null): OrphanFinding[];
+export interface LinkTarget {
+    /** Absolute URL to request. */
+    url: string;
+    /** Where it was found — every page carrying this href. */
+    from: Array<{
+        page: string;
+        name: string;
+    }>;
+}
+/**
+ * Collect the distinct internal destinations the app links to.
+ *
+ * De-duplicated by absolute URL so a footer link on 40 pages is one request, and
+ * filtered by the caller's safety predicate — the same one `discover --crawl`
+ * uses. A GET is not harmless on a URL that *acts*: requesting `/logout` ends the
+ * session the rest of the run depends on, and `/orders/12/delete` is not a link
+ * check, it is data loss. Those are skipped and said out loud.
+ */
+export declare function collectLinkTargets(pages: CheckPage[], resolve: (href: string) => string | null): {
+    targets: LinkTarget[];
+    skipped: number;
+};
+export interface DeadLink extends LinkTarget {
+    status: number | null;
+    error?: string;
+}
+/** A response code that means the link is broken, not merely guarded. */
+export declare function isDeadStatus(status: number): boolean;
+export interface CheckReport {
+    pagesChecked: number;
+    elements: number;
+    unnamed: UnnamedFinding[];
+    ambiguous: AmbiguousFinding[];
+    orphans: OrphanFinding[];
+    deadLinks: DeadLink[];
+    linksChecked: number;
+    linksSkipped: number;
+    /** True when the network half was skipped — the verdict then covers less. */
+    offline: boolean;
+    /**
+     * Checks that did not run, and why.
+     *
+     * A verdict that omits its own gaps is the false green this project keeps
+     * relearning: "0 locators checked · all resolve", "N ok that were never
+     * compared". PASS here means "the checks that ran found nothing", and the only
+     * way that is not a lie is to say which ones ran.
+     */
+    skipped: Array<{
+        check: string;
+        why: string;
+    }>;
+}
+export type CheckVerdict = 'PASS' | 'WARN' | 'FAIL';
+/**
+ * FAIL is reserved for a dead link: a request the app itself answered with an
+ * error, which is a fact, not a judgement. Everything else is real but arguable —
+ * an unnamed icon button, a deep-link-only page — so it warns and exits 0 unless
+ * the user asks for `--strict`. A gate nobody can leave on is a gate nobody turns
+ * on.
+ */
+export declare function checkVerdict(r: CheckReport): CheckVerdict;
+/** How much of the check ran: e.g. `{ ran: 2, total: 4 }`. */
+export declare const CHECK_NAMES: readonly ["dead links", "unnamed", "ambiguous", "orphans"];
+export declare function checkCoverage(r: CheckReport): {
+    ran: number;
+    total: number;
+};

package/dist/checks.js.map

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

package/dist/cli/args.js

@@ -22,6 +22,8 @@ exports.KNOWN_FLAGS = {
     diff: ['--strict', '--json', '--dir', '--report', '--open'],
     fix: ['--dry-run', '--locators', '--dir'],
     ingest: [],
+    audit: ['--strict', '--json'],
+    check: ['--strict', '--json', '--offline'],
     graph: ['--format', '--kind', '--out', '--open'],
     run: ['--yes', '--no-verify', '--locators', '--report', '--open'],
 };

package/dist/cli/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":";;;AAwBA,gDAeC;AAvCD;;;;;;;;;;;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,EAAE;IACP,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IAC3D,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC;IACzC,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAChD,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAC;CAClE,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":";;;AA0BA,gDAeC;AAzCD;;;;;;;;;;;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,EAAE;IACP,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IAC3D,GAAG,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC;IACzC,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC7B,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC1C,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAChD,GAAG,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,CAAC;CAClE,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

@@ -0,0 +1,63 @@
+import { Usage } from '../ingest';
+import { NameSite } from '../nameLocators';
+/**
+ * `ia-qa-heal audit [--strict] [--json]` — a verdict on day one, with no baseline.
+ *
+ * Every other verb in this tool compares two moments, which means its value
+ * arrives one drift *after* you install it: map, wait for the app to change, then
+ * find out. Nobody adopts a healing tool before their tests break, so that
+ * ordering is the adoption problem, not the technology.
+ *
+ * `audit` answers the question you have the day you arrive — *does my suite still
+ * name things that exist?* — from a single capture. It cross-references the
+ * locator inventory (`ingest`) against the current contract (`map`): a
+ * `getByRole('button', { name: 'Save' })` that matches no button on any mapped
+ * page cannot pass, and saying so needs no history at all.
+ *
+ * Deliberately conservative, and deliberately advisory by default:
+ *
+ * - Only **role-anchored** locators carry the verdict. `extractInPage` maps
+ *   interactive elements, so `getByText('Terms of service')` may well point at a
+ *   paragraph the contract never saw — its absence is not evidence, and
+ *   reporting it would be a false positive. Those are counted, never judged.
+ * - Exit 0 unless `--strict`. The mapping covers the pages in `config.pages`, not
+ *   necessarily the pages the suite visits; a locator that is "missing" may just
+ *   live on an unmapped page. Gate on this once coverage is real — the header
+ *   says how many pages that is.
+ *
+ * Local end to end: reads `.ia-qa/`, reads your test files, calls nothing.
+ */
+interface DeadLocator {
+    /** As written in the test file, not as normalized for lookup. */
+    name: string;
+    roles: string[] | null;
+    sites: NameSite[];
+    suggestion?: {
+        name: string;
+        role: string;
+        score: number;
+        pages: string[];
+        kind: 'fuzzy' | 'extended';
+    };
+}
+interface MappedElement {
+    role: string;
+    name: string;
+    selector: string;
+    page: string;
+}
+/**
+ * Does `haystack` contain `needle` on word boundaries? "save" is inside "save
+ * changes" but not inside "saved searches" — substring alone would claim both.
+ */
+export declare function containsAsWords(haystack: string, needle: string): boolean;
+/**
+ * Which inventoried names resolve to nothing the contract holds?
+ *
+ * A name is alive as soon as ONE mapped page answers it: the audit has no way of
+ * knowing which page a given test visits, so "found somewhere" is the only
+ * reading that cannot manufacture a false positive.
+ */
+export declare function findDeadLocators(usage: Usage, elements: MappedElement[]): DeadLocator[];
+export declare function runAudit(args: string[]): Promise<void>;
+export {};