@ia-qa/self-healing 1.7.18 → 1.7.20

package/dist/aom.js

@@ -88,12 +88,26 @@ function depthMismatch(baseline, current) {
 }
 /** The sentence every door prints or attaches when `depthMismatch` returns non-null. */
 function depthMismatchMessage(m) {
-    const deeper = m.baseline > m.current ? 'baseline' : 'current capture';
-    const shallower = deeper === 'baseline' ? 'current capture' : 'baseline';
-    return (`Exploration depth mismatch — the ${deeper} was captured with \`map --deep\`, the ${shallower} ` +
+    const baselineDeeper = m.baseline > m.current;
+    const deeper = baselineDeeper ? 'baseline' : 'current capture';
+    const shallower = baselineDeeper ? 'current capture' : 'baseline';
+    const head = `Exploration depth mismatch — the ${deeper} was captured with \`map --deep\`, the ${shallower} ` +
         `was not (depth ${m.baseline} vs ${m.current}). A deep contract holds the elements behind ` +
-        `menus, tabs and dialogs; a shallow one cannot, so those elements read as \`lost\` here. Most ` +
-        `of this verdict is probably that, not drift in your app. Capture both sides the same way.`);
+        `menus, tabs and dialogs; a shallow one cannot. `;
+    // What follows must describe what the tool then DOES, and since 1.7.17 that changed:
+    // those elements are held out of the verdict rather than counted `lost`. The old wording
+    // survived the change and contradicted the line printed a few rows below it in the same
+    // run — the precise failure `depthDelta.ts` warns about, two readers of one run made to
+    // disagree. Branched, because only the deep-baseline direction holds anything out: the
+    // reverse produces `added` rows, which never moved a verdict.
+    return baselineDeeper
+        ? head +
+            `Those elements are held OUT of this verdict rather than counted as \`lost\` — neither ` +
+            `present nor gone, simply not measured, and listed below. Capture both sides the same ` +
+            `way to gate them.`
+        : head +
+            `The extra elements the deep side found appear as \`added\`, which never moves a verdict, ` +
+            `so this comparison stands. Capture both sides the same way to gate them too.`;
 }
 async function extractInteractiveElements(page) {
     return page.evaluate(extract_1.extractInPage);

package/dist/aom.js.map

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

package/dist/cli/diff.d.ts

@@ -100,6 +100,58 @@ export declare function runDiff(args: string[]): Promise<void>;
  * counts. A verdict that changed without a line saying why is the silent behaviour this
  * package treats as a defect, and here the silence would be a green one.
  */
+/**
+ * The CSS-Page-Object check did not run, and the verdict above does not cover it.
+ *
+ * Printed wherever a verdict is: this is the difference between "your selectors are fine"
+ * and "nobody looked at your selectors", and the second one wearing the first one's green
+ * is the failure mode this whole package exists to refuse.
+ */
+/**
+ * How to get a gate that DOES cover the suite's selectors — which depends on whether this
+ * project has pages to walk.
+ *
+ * `map && diff` was printed unconditionally, and on the zero-config path `init` now
+ * recommends it is a closed loop: `pages` is empty, so `map` exits 1 with "No pages
+ * configured" and points back at capture-during-run, which is where the reader already is.
+ * A remedy that returns you to your starting point is worse than none — it costs a run to
+ * find out, and it teaches that the advice is not to be trusted.
+ */
+/**
+ * The exit code when a run left the suite's own selectors unjudged.
+ *
+ * Transparency fixed the honesty of the message and left the harder question open: what
+ * should a CI *do* with it? For a team whose Page Objects are CSS, the check that did not
+ * run is the whole gate — so `diff` returned exit 0 while their suite was red, and no flag
+ * could say otherwise.
+ *
+ * **It is `2`, not `1`, and that is the whole design.** The contract in `exitCodes.ts` is
+ * explicit: 1 is "answered, and the answer is no"; 2 is "could not answer — NOT a failure
+ * of your app, and never a pass". Bindings that were never resolved are the second, exactly.
+ * Returning 1 would tell a pipeline the application drifted, which is the mistake this
+ * package documents at length — an agent once wrote `non-zero = BLOCK` into a generated
+ * workflow and turned "I do not know" into a permanently red build.
+ *
+ * **Behind `--strict`, and not on by default.** Every capture-path project would otherwise
+ * go non-zero on upgrade, over a limitation none of them introduced; a gate nobody can
+ * leave on is a gate nobody turns on. `--strict` already means "tighten what counts as
+ * failure", so it is the lever that exists rather than a new one to discover.
+ *
+ * **A real finding outranks an unanswered question.** BLOCK (and `--strict` FIX) still
+ * exit 1: something WAS answered and it is bad. Only a run that would otherwise be green
+ * reports 2 — a green that covers less than the reader thinks.
+ */
+export declare function bindingExitCode(failing: boolean, strict: boolean, coverage: BindingCoverage | undefined): 0 | 1 | 2;
+export declare function bindingGateRemedy(hasDeclaredPages: boolean): string;
+/**
+ * Why the process is leaving with 2 on a run whose verdict says PASS.
+ *
+ * An exit code with no sentence behind it is the thing this package refuses everywhere
+ * else: the reader sees a green verdict and a non-zero exit and has to guess which is
+ * lying. Neither is — they answer different questions.
+ */
+export declare function printBindingStrictExit(c: BindingCoverage | undefined, json: boolean): void;
+export declare function printBindingCoverage(c: BindingCoverage | undefined): void;
 export declare function printDepthUnmeasured(u: DepthUnmeasured | undefined): void;
 export declare function printSystemic(outcome: SystemicOutcome): void;
 export declare function printNameMasks(outcome: MaskOutcome | undefined): void;
@@ -117,7 +169,7 @@ export declare function printNameDrift(findings: NameDriftFinding[] | undefined)
  * and never in `--json` mode, where it would corrupt the machine-readable payload.
  * Shared with `run`, which ends on the same verdict.
  */
-export declare function driftSummaryLine(verb: string, verdict: 'PASS' | 'FIX' | 'BLOCK', c: Report['counts'], nameDrift?: NameDriftFinding[], bindingDrift?: BindingDrift[], depthUnmeasured?: DepthUnmeasured): void;
+export declare function driftSummaryLine(verb: string, verdict: 'PASS' | 'FIX' | 'BLOCK', c: Report['counts'], nameDrift?: NameDriftFinding[], bindingDrift?: BindingDrift[], depthUnmeasured?: DepthUnmeasured, bindingCoverage?: BindingCoverage): void;
 export interface DirDiffCollection {
     reports: Array<{
         name: string;
@@ -220,6 +272,8 @@ export interface DirReport {
      * that the green it just got covers less than the contract does.
      */
     depthUnmeasured?: DepthUnmeasured;
+    /** The CSS-Page-Object check did not run this walk. Emitted, not merely printed. */
+    bindingCoverage?: BindingCoverage;
 }
 export declare function aggregateReports(reports: Array<{
     name: string;
@@ -291,4 +345,24 @@ export interface Report {
      * the same way — never "none were held out because none exist".
      */
     depthUnmeasured?: DepthUnmeasured;
+    /**
+     * The suite's own selector strings were NOT judged this run, though the inventory holds
+     * some. Absent means they were judged — never "there were none to judge", which is what
+     * silence used to mean and what made a capture-path `diff` a false green.
+     */
+    bindingCoverage?: BindingCoverage;
+}
+/**
+ * Why the CSS-Page-Object check did not run.
+ *
+ * `absent` — no `_resolved/` for this side. Capture-during-run writes contracts and no
+ * bindings (it has no browser at merge time), so this is the whole `run` path today.
+ * `stale` — one was there and was refused: it describes an older moment than the contract
+ * beside it, so using it would compare a live capture against a `map` from before the drift.
+ */
+export interface BindingCoverage {
+    reason: 'absent' | 'stale';
+    /** How many selector strings the inventory holds — the size of what went unjudged. */
+    inventoried: number;
+    side: 'baseline' | 'current' | 'both';
 }

package/dist/cli/diff.js

@@ -41,6 +41,10 @@ exports.pageShotMap = pageShotMap;
 exports.buildEvidence = buildEvidence;
 exports.writeDriftReport = writeDriftReport;
 exports.runDiff = runDiff;
+exports.bindingExitCode = bindingExitCode;
+exports.bindingGateRemedy = bindingGateRemedy;
+exports.printBindingStrictExit = printBindingStrictExit;
+exports.printBindingCoverage = printBindingCoverage;
 exports.printDepthUnmeasured = printDepthUnmeasured;
 exports.printSystemic = printSystemic;
 exports.printNameMasks = printNameMasks;
@@ -376,7 +380,7 @@ async function runDiff(args) {
     const report = attachBaselineHrefs((0, nameMask_1.diffWithMasks)(baseline, current, (0, nameMask_1.loadNameMasks)(), usage), baseline);
     // Same rule as the directory walk: the resolutions sit next to the mappings they
     // describe, so a two-file diff reaches them without being told where to look.
-    attachBindingDrift(report, files[0], files[1], baseline.page);
+    attachBindingDrift(report, files[0], files[1], baseline.page, baseline, current);
     // A rename is harmless to a CSS-anchored suite and fatal to a name-anchored
     // one. Only the test inventory can tell the two apart, so the verdict is
     // raised here rather than inside the shared matcher.
@@ -388,6 +392,7 @@ async function runDiff(args) {
     else {
         printHuman(report, files, usage);
         printDepthUnmeasured(report.depthUnmeasured);
+        printBindingCoverage(report.bindingCoverage);
         printNameMasks(report.nameMask);
         printNameDrift(report.nameDrift);
     }
@@ -405,9 +410,11 @@ async function runDiff(args) {
     }
     (0, emit_1.recordDriftRun)('diff', singleAgg, { baseUrl: (0, config_2.configuredBaseUrl)() });
     const failing = report.verdict === 'BLOCK' || (strict && report.verdict === 'FIX');
-    process.exitCode = failing ? 1 : 0;
+    process.exitCode = bindingExitCode(failing, strict, report.bindingCoverage);
+    if (process.exitCode === 2)
+        printBindingStrictExit(report.bindingCoverage, json);
     if (!json)
-        driftSummaryLine('diff', report.verdict, report.counts, report.nameDrift, report.bindingDrift, report.depthUnmeasured);
+        driftSummaryLine('diff', report.verdict, report.counts, report.nameDrift, report.bindingDrift, report.depthUnmeasured, report.bindingCoverage);
 }
 /**
  * What `nameMask` did, in two registers.
@@ -440,6 +447,111 @@ async function runDiff(args) {
  * counts. A verdict that changed without a line saying why is the silent behaviour this
  * package treats as a defect, and here the silence would be a green one.
  */
+/**
+ * The CSS-Page-Object check did not run, and the verdict above does not cover it.
+ *
+ * Printed wherever a verdict is: this is the difference between "your selectors are fine"
+ * and "nobody looked at your selectors", and the second one wearing the first one's green
+ * is the failure mode this whole package exists to refuse.
+ */
+/**
+ * How to get a gate that DOES cover the suite's selectors — which depends on whether this
+ * project has pages to walk.
+ *
+ * `map && diff` was printed unconditionally, and on the zero-config path `init` now
+ * recommends it is a closed loop: `pages` is empty, so `map` exits 1 with "No pages
+ * configured" and points back at capture-during-run, which is where the reader already is.
+ * A remedy that returns you to your starting point is worse than none — it costs a run to
+ * find out, and it teaches that the advice is not to be trusted.
+ */
+/**
+ * The exit code when a run left the suite's own selectors unjudged.
+ *
+ * Transparency fixed the honesty of the message and left the harder question open: what
+ * should a CI *do* with it? For a team whose Page Objects are CSS, the check that did not
+ * run is the whole gate — so `diff` returned exit 0 while their suite was red, and no flag
+ * could say otherwise.
+ *
+ * **It is `2`, not `1`, and that is the whole design.** The contract in `exitCodes.ts` is
+ * explicit: 1 is "answered, and the answer is no"; 2 is "could not answer — NOT a failure
+ * of your app, and never a pass". Bindings that were never resolved are the second, exactly.
+ * Returning 1 would tell a pipeline the application drifted, which is the mistake this
+ * package documents at length — an agent once wrote `non-zero = BLOCK` into a generated
+ * workflow and turned "I do not know" into a permanently red build.
+ *
+ * **Behind `--strict`, and not on by default.** Every capture-path project would otherwise
+ * go non-zero on upgrade, over a limitation none of them introduced; a gate nobody can
+ * leave on is a gate nobody turns on. `--strict` already means "tighten what counts as
+ * failure", so it is the lever that exists rather than a new one to discover.
+ *
+ * **A real finding outranks an unanswered question.** BLOCK (and `--strict` FIX) still
+ * exit 1: something WAS answered and it is bad. Only a run that would otherwise be green
+ * reports 2 — a green that covers less than the reader thinks.
+ */
+function bindingExitCode(failing, strict, coverage) {
+    if (failing)
+        return 1;
+    return strict && coverage ? 2 : 0;
+}
+function bindingGateRemedy(hasDeclaredPages) {
+    return hasDeclaredPages
+        ? '      For a gate that covers them: `ia-qa-heal map && ia-qa-heal diff`.'
+        : '      To gate them you need declared pages — `map` walks a list, and this project has none:\n' +
+            '        ia-qa-heal discover --sitemap --apply     (reads them from the app)\n' +
+            '        then  ia-qa-heal map && ia-qa-heal diff\n' +
+            '      Until then this run gates elements and labels, never the selector strings.';
+}
+/** Does this project declare pages? Absent or unreadable config is treated as none. */
+function hasDeclaredPages() {
+    try {
+        return (0, config_2.loadConfig)().pages.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why the process is leaving with 2 on a run whose verdict says PASS.
+ *
+ * An exit code with no sentence behind it is the thing this package refuses everywhere
+ * else: the reader sees a green verdict and a non-zero exit and has to guess which is
+ * lying. Neither is — they answer different questions.
+ */
+function printBindingStrictExit(c, json) {
+    if (!c || json)
+        return;
+    console.error(`\n⚠️  --strict: exiting 2 because ${c.inventoried} test selector` +
+        `${c.inventoried === 1 ? '' : 's'} went unjudged (see above).\n` +
+        `   2 means "could not answer", never "your app is broken" — the drift that WAS\n` +
+        `   measured is PASS. Drop \`--strict\`, or give the run a way to resolve them.`);
+}
+function printBindingCoverage(c) {
+    if (!c)
+        return;
+    const remedy = bindingGateRemedy(hasDeclaredPages());
+    // `side` names the side that LACKS a usable resolution, so every sentence below has to
+    // read that way round — "the current has one that describes this capture" said the
+    // opposite of what the field means.
+    const where = c.side === 'both' ? 'neither side has one' : `the ${c.side} side has none`;
+    if (c.reason === 'stale') {
+        console.log(`\n   🧭 Selector bindings NOT measured — ${where} that describes this capture.\n` +
+            `      A resolution left by an earlier \`map\` was found and refused: it is older than the\n` +
+            `      contract beside it, so it would have compared your live capture against the app as\n` +
+            `      it was BEFORE the drift — a green built out of a stale file.\n` +
+            `      Your ${c.inventoried} inventoried test selector${c.inventoried === 1 ? '' : 's'} ` +
+            `${c.inventoried === 1 ? 'is' : 'are'} not covered by the verdict above.\n` +
+            remedy);
+        return;
+    }
+    console.log(`\n   🧭 Selector bindings NOT measured — ${where}.\n` +
+        `      Capture-during-run records contracts, not bindings: resolving a test's own CSS\n` +
+        `      selectors needs a live DOM, and the merge that writes these contracts has none.\n` +
+        `      So the CSS-Page-Object check — the one that catches \`.btn-primary\` breaking — is\n` +
+        `      NOT running here, and your ${c.inventoried} inventoried selector${c.inventoried === 1 ? '' : 's'} ` +
+        `${c.inventoried === 1 ? 'is' : 'are'} unjudged.\n` +
+        `      Label drift and element drift above are real; this is what they do not cover.\n` +
+        remedy);
+}
 function printDepthUnmeasured(u) {
     if (!u || u.selectors.length === 0)
         return;
@@ -526,7 +638,7 @@ function printNameDrift(findings) {
  * and never in `--json` mode, where it would corrupt the machine-readable payload.
  * Shared with `run`, which ends on the same verdict.
  */
-function driftSummaryLine(verb, verdict, c, nameDrift = [], bindingDrift = [], depthUnmeasured) {
+function driftSummaryLine(verb, verdict, c, nameDrift = [], bindingDrift = [], depthUnmeasured, bindingCoverage) {
     const kind = verdict === 'PASS' ? 'ok' : verdict === 'FIX' ? 'fix' : 'block';
     const nameFixable = nameDrift.filter((f) => f.fixable).length;
     const nameManual = nameDrift.length - nameFixable;
@@ -550,10 +662,16 @@ function driftSummaryLine(verb, verdict, c, nameDrift = [], bindingDrift = [], d
     // contract has to say so here — the same rule that makes a page left out of a `run`
     // `stale` rather than a pass.
     const unmeasured = depthUnmeasured?.selectors.length ?? 0;
+    // "suite safe" is a claim about the SUITE, and the check that judges the suite's own
+    // selectors is exactly the one the capture path does not run. A PASS that says it while
+    // N inventoried selectors went unjudged is the sentence a CI stops reading at.
     const headline = verdict === 'PASS'
-        ? unmeasured > 0
-            ? `PASS · no drift in what was measured · ${unmeasured} not measured (depth mismatch)`
-            : 'PASS · no drift, suite safe'
+        ? bindingCoverage
+            ? `PASS · no drift in what was measured · ${bindingCoverage.inventoried} test selector` +
+                `${bindingCoverage.inventoried === 1 ? '' : 's'} not judged`
+            : unmeasured > 0
+                ? `PASS · no drift in what was measured · ${unmeasured} not measured (depth mismatch)`
+                : 'PASS · no drift, suite safe'
         : verdict === 'FIX'
             ? `FIX · ${fixCause} → \`fix\``
             : `BLOCK · ${blockCause} — human needed`;
@@ -623,6 +741,7 @@ async function runDirDiff(baselineDir, currentDir, opts) {
     else {
         printAggregate(aggregate, reports, baselineDir, currentDir, usage);
         printDepthUnmeasured(aggregate.depthUnmeasured);
+        printBindingCoverage(aggregate.bindingCoverage);
         printSystemic(systemic);
         printNameMasks(aggregate.nameMask);
         printNameDrift(aggregate.nameDrift);
@@ -644,9 +763,11 @@ async function runDirDiff(baselineDir, currentDir, opts) {
         baseUrl: (0, config_2.configuredBaseUrl)(),
     });
     const failing = aggregate.verdict === 'BLOCK' || (opts.strict && aggregate.verdict === 'FIX');
-    process.exitCode = failing ? 1 : 0;
+    process.exitCode = bindingExitCode(failing, opts.strict, aggregate.bindingCoverage);
+    if (process.exitCode === 2)
+        printBindingStrictExit(aggregate.bindingCoverage, opts.json);
     if (!opts.json)
-        driftSummaryLine('diff', aggregate.verdict, aggregate.totals, aggregate.nameDrift, aggregate.bindingDrift, aggregate.depthUnmeasured);
+        driftSummaryLine('diff', aggregate.verdict, aggregate.totals, aggregate.nameDrift, aggregate.bindingDrift, aggregate.depthUnmeasured, aggregate.bindingCoverage);
 }
 /**
  * Judge the suite's own selector strings against the two moments, and fold the result
@@ -659,9 +780,36 @@ async function runDirDiff(baselineDir, currentDir, opts) {
  * `elementNow` is the contract diff's own conclusion, handed in rather than recomputed:
  * a binding verdict must never disagree with the element verdict printed beside it.
  */
-function attachBindingDrift(report, baselineFile, currentFile, page) {
-    const before = (0, resolution_1.loadResolution)(page, path.join(path.dirname(baselineFile), config_1.RESOLVED_DIRNAME));
-    const after = (0, resolution_1.loadResolution)(page, path.join(path.dirname(currentFile), config_1.RESOLVED_DIRNAME));
+function attachBindingDrift(report, baselineFile, currentFile, page, baseline, current) {
+    const loadFor = (file, mapping) => {
+        const found = (0, resolution_1.loadResolution)(page, path.join(path.dirname(file), config_1.RESOLVED_DIRNAME));
+        if (!found)
+            return { resolution: null, stale: false };
+        // A resolution left behind by an earlier `map`, sitting next to a contract a live
+        // capture just rewrote, describes a page that is 34 seconds out of date — and being
+        // identical to the baseline's, it makes the binding diff empty. That is the false
+        // green, and it is why this is checked rather than trusted.
+        if (mapping && !(0, resolution_1.resolutionMatchesCapture)(found, mapping))
+            return { resolution: null, stale: true };
+        return { resolution: found, stale: false };
+    };
+    const b = loadFor(baselineFile, baseline);
+    const c = loadFor(currentFile, current);
+    const before = b.resolution;
+    const after = c.resolution;
+    // Not measured, and said so. The inventory is the trigger: a project that never ran
+    // `ingest` has no selector strings to judge and is owed no notice — but one that HAS
+    // them and gets no binding verdict is being handed a green over the very check the
+    // README opens with ("a Page Object written in CSS"). Same rule as `stale` pages and
+    // the depth hold-out: a thing nobody looked at is never a pass.
+    const inventoried = Object.keys((0, ingest_1.loadUsage)()?.selectors ?? {}).length;
+    if (inventoried > 0 && (!before || !after)) {
+        report.bindingCoverage = {
+            reason: b.stale || c.stale ? 'stale' : 'absent',
+            inventoried,
+            side: !before && !after ? 'both' : !before ? 'baseline' : 'current',
+        };
+    }
     if (!before || !after)
         return report;
     const bySelector = new Map(report.rows.map((r) => [r.selector, r]));
@@ -729,7 +877,7 @@ function collectDirDiff(baselineDir, currentDir) {
         const report = attachBaselineHrefs((0, nameMask_1.diffWithMasks)(baseline, current, masks, usage), baseline);
         report.nameDrift = (0, nameDrift_1.assessNameDrift)(report.rows, current.elements, usage);
         report.verdict = (0, nameDrift_1.escalateVerdict)(report.verdict, report.nameDrift);
-        return attachBindingDrift(report, baselineFile, currentFile, page);
+        return attachBindingDrift(report, baselineFile, currentFile, page, baseline, current);
     };
     const layoutsDir = path.join(baselineDir, '_layouts');
     if (fs.existsSync(layoutsDir)) {
@@ -828,12 +976,15 @@ function aggregateReports(reports) {
     const bindingDrift = reports.flatMap((r) => r.report.bindingDrift ?? []);
     const nameMask = (0, nameMask_1.mergeMaskOutcomes)(reports.map((r) => r.report.nameMask));
     const depthUnmeasured = (0, depthDelta_1.mergeDepthUnmeasured)(reports.map((r) => r.report.depthUnmeasured));
+    // One fact about the run, not one per page: every page shares the same _resolved/ dir.
+    const bindingCoverage = reports.map((r) => r.report.bindingCoverage).find(Boolean);
     return {
         verdict,
         ...(nameDrift.length > 0 ? { nameDrift } : {}),
         ...(bindingDrift.length > 0 ? { bindingDrift } : {}),
         ...(nameMask ? { nameMask } : {}),
         ...(depthUnmeasured ? { depthUnmeasured } : {}),
+        ...(bindingCoverage ? { bindingCoverage } : {}),
         layoutVerdict,
         layoutCounts,
         pageReports: pageReports.map((r) => ({