testaro 78.0.6 → 78.4.0

package/docs/checkpoint-scanning.md

@@ -0,0 +1,199 @@
+# Checkpoints: scanning across a serial action flow
+
+**Status:** Phases 0, 1, and 1b shipped in Testaro 78.2 (2026-09-02); Phases 2 (`report.flow`),
+3 (`scope: 'changed'`), and 4 (incremental pruning, selector acts, the user-path converter)
+shipped in 78.3 (2026-09-02). The interaction modalities and the yra-monitor ingestion changes
+remain follow-ups.
+
+## Why
+
+A job is a serial list of acts: launch a browser, interact with the page, test it. Until 78.2,
+the interaction acts had no effect on any test: every `test` act ran in a child process that
+launched its own browser and navigated to the job target, and the element catalog was built
+once, before any act, for that same page. A job of the form launch → click → test therefore
+tested the page as first loaded, and any test after a `url` act resolved its elements against
+the wrong page's catalog.
+
+The maintainer's goals: keep the serial action flow; keep or extend a running list of found
+issues as the flow progresses; use explicit triggers for re-scanning rather than re-running
+every tool after every action; and re-scan either the whole page or only the parts that
+changed, as the case requires.
+
+## The model
+
+A **checkpoint** is a named page state reached by the flow, snapshotted and tested:
+
+- **Checkpoint 0** is the job target as launched. `getCatalog` creates it before any act, as
+  it always built the catalog, and records it as `report.checkpoints[0]` (named `start`).
+- A **`checkpoint` act** (`{type: 'checkpoint', which: '<name>'}`) creates the next one from
+  the live page in the parent process: catalog entries for the current state, page image(s)
+  if the job asks for them, the URL and title, an ARIA snapshot, and a DOM digest.
+- A **`test` act belongs to the most recent checkpoint** (`act.checkpoint`), and every
+  standard instance it reports carries `checkpoint`.
+
+Checkpoint mode is opt-in: it is on only when the job contains a `checkpoint` act. Legacy
+jobs (no such act) run as before and produce today's report plus the `checkpoint: 0` fields;
+if interaction acts precede a test act in a legacy job, `jobData.warnings` says that the act
+tests checkpoint 0. In checkpoint mode, interaction acts followed by a test act without an
+intervening checkpoint produce an implicit checkpoint (named `act<N>`) and a warning; the
+warning never fails the job.
+
+### Navigation and interaction checkpoints
+
+A checkpoint is a **navigation checkpoint** when the page was reached by navigation alone
+(a `launch` or `url` act) and no interaction act ran since; it is an **interaction
+checkpoint** when acts on a page (button, link, text, press, reveal, …) reached it. The
+distinction decides how a test act's browser reaches the state:
+
+- Navigation checkpoint: the child navigates to the checkpoint's URL. Every tool runs.
+- Interaction checkpoint: the child navigates to the URL the interaction started from
+  (`launchURL`) and **replays** the recorded interaction acts (`replay`, act indexes) before
+  running the tool. The replay happens inside `launchOnce` after navigation and before any
+  `data-xpath` stamping, so elements the acts reveal or create are stamped like the rest,
+  and every per-rule relaunch of a contaminating testaro rule replays automatically.
+
+Replay is a re-enactment, not a restore. Server state, sessions, timers and randomness can
+make the replayed DOM differ from the snapshot. Each test act records
+`data.replay = {checkpoint, acts, elapsedMs, fidelity}` where `fidelity` is `exact` when
+the replayed DOM's digest equals the checkpoint's, else `divergent`. A replay failure
+prevents the test act with `checkpoint replay failed at act N (…)` and is not retried.
+
+### What each tool can observe
+
+`procs/job.js` `toolInputs` declares what a tool tests:
+
+| input | tools | interaction checkpoints |
+| --- | --- | --- |
+| `page` | alfa, aslint, axe, ed11y, htmlcs, ibm, pour, surea11y, testaro | yes (replayed page) |
+| `html` | qualWeb, nuVal, nuVnu (they read the live page's HTML) | yes (replayed page) |
+| `url` | wave; nuVal and nuVnu with `withSource: true` | no: prevented with a stated reason |
+
+### Report shape
+
+- `report.checkpoints[k]`: `{index, name, implicit, actIndex, launchActIndex, launchURL,
+  replay, interaction: {modality}, kind: 'navigation' | 'interaction', url, title,
+  imageIndexes, catalogRange, elementCount, ariaSnapshot, domDigest, elapsedMs, testActs}`.
+- `report.catalog` stays one flat map. Entries carry `checkpoint`; indexes come from a
+  monotonic job-time counter (`report.catalogNextIndex`), so entries of different checkpoints
+  never collide, and the job-time `report.pathIDs` is scoped per checkpoint so the same XPath
+  in two states maps to two entries. Pruning keeps only cited entries, as before.
+- `report.images`: `images[0]` (and `[1]` at `imageScale > 1`) keep meaning checkpoint 0;
+  later checkpoints' images are indexed by `checkpoints[k].imageIndexes`. The testaro `motion`
+  rule compares against its checkpoint's image.
+- `jobData.catalogData.checkpoints[k]`: element and entry counts per checkpoint.
+- `report.flow` (two or more checkpoints): `{checkpoints: [{index, name, kind, url, actIndex,
+  testActs, tools, issueCount}], deltas: [{from, to, tools, notObserved, added, persisted,
+  removed, notRetested, structure, aria}]}`; each issue is `{tool, ruleID, pathID, startTag,
+  what, ordinalSeverity, outcome, count, actIndexes}`.
+- Test acts: `scope` (`page` default or `changed`) and `data.scope = {requested, applied,
+  reason, roots, pathIDs, commonRoot, localRules?, pageRules?}`. Job-time only, deleted by
+  `pruneCatalog`: `report.scope`, `report.ruleScopeRoots`.
+- Progress events: `checkpointStart` and `checkpointEnd` (with `kind` and `elapsedMs`);
+  `actEnd` carries `checkpoint`.
+
+### Interaction modality (planned)
+
+The act executors live in `procs/actDo.js` and take an `interaction` option
+(`{modality: 'efficient'}` today), recorded on each checkpoint so replay uses the same
+modality. Low-level events (`mousedown`/`mouseup`), emulated human mouse travel and key
+pauses, and pass-to-pass comparisons between modalities are designed to slot in there.
+
+## Phases
+
+- **Phase 0 (shipped):** act-loop repairs (`next` acts, failed launches, the `url` and
+  `state` acts), `procs/actDo.js`, `procs/xPathScript.js`, `catalogPage`, checkpoint 0.
+- **Phase 1 (shipped):** the `checkpoint` act, `procs/checkpoint.js`, replay in the
+  launcher, implicit checkpoints, tool gating, the `validation/tests/jobProperties/checkpoint`
+  validator with report-level expectations.
+- **Phase 1b (shipped):** the `isolation` job property (or the `ISOLATION` environment
+  default): `process` (the default: a child process and browser per test act), `browser`
+  (one browser shared by the job's launches, a fresh context per test act, replay), `page`
+  (tools run in sequence in the job's process on the live checkpoint page, no replay;
+  contaminating testaro rules still get a fresh context with replay). `procs/testAct.js`
+  performs a test act for both the child process and the in-process levels; the launcher
+  keeps the shared browser and prepares a live page (XPath script or attributes, accessible
+  names) without changing its DOM. Recorded in `jobData.isolation`. Only `process` can kill a
+  tool that overruns its time limit; the others report the act as timed out and continue.
+- **Phase 2 (shipped):** `report.flow` (`procs/flow.js`, `getFlow(report)`), added at job end
+  before pruning when the job has two or more checkpoints, and usable standalone on a stored
+  report (the structure diff then covers cited elements only). `flow.checkpoints[k]`
+  summarizes each checkpoint; `flow.deltas[k - 1]` compares checkpoints `k - 1` and `k`:
+  `added`, `persisted`, and `removed` issues with identity `tool | ruleID | pathID | startTag`
+  (box and text excluded, since layout and copy shift without the defect changing; a summary
+  instance has an empty element key), compared only for the `tools` that observed both
+  checkpoints with a non-prevented act (`notObserved` lists the rest); `structure`, the
+  catalog diff (`procs/scope.js`, `getStructureDiff`): `added`, `removed`, and `changed`
+  (start tag) XPaths, `textChanged` XPaths, and `roots`, the outermost changed elements (the
+  nearest surviving ancestor stands for a removed element; a text change counts only where no
+  descendant changed, because the catalog text of an element includes its descendants'); and
+  `aria`, a line diff of the ARIA snapshots (`diff`, the jsdiff library yra-monitor also uses;
+  at most 500 changed lines recorded, `truncated` otherwise).
+- **Phase 3 (shipped):** `scope: 'page' | 'changed'` on test acts (`actSpecs.js`; a job with a
+  changed-scope act must have a checkpoint act). Before such an act the acts loop calls
+  `getChangedRoots(report, k)`, which converts the structure roots of the diff between
+  checkpoints `k - 1` and `k` to CSS selectors (`/html/body/main[1]/div[2]` becomes
+  `html > body > main:nth-of-type(1) > div:nth-of-type(2)`, exact because `getXPath`
+  subscripts among same-tag siblings, which is what `nth-of-type` counts) and gives them to
+  the tool as the job-time `report.scope` when the tool is in `toolScopes` (`procs/job.js`:
+  axe, surea11y, testaro). The act records `data.scope`; when the act cannot be scoped (no
+  previous checkpoint, no change, more than `maxRoots` = 50 roots, an XPath with no selector,
+  a tool without a root option) it tests the whole page with `applied: false` and a reason,
+  and `jobData.warnings` says so. axe takes the roots as its `include` context; surea11y takes
+  the nearest common ancestor of the roots (`commonRoot`), since its context is one selector;
+  the testaro tool sets `report.ruleScopeRoots` per rule to the roots for a rule with
+  `local: true` in `allRules` and to null otherwise, and `doTest` keeps only candidates inside
+  a root (`getBasicResult` rules, hover and role, are not local). The conservative first-pass
+  classification marks as not local: allHidden, bulk, docType, dupAtt, headEl, headingAmb,
+  secHeading, linkAmb, labClash, radioSet, styleDiff, targetsNear, title, motion, role, hover,
+  hovInd, focAll, focAndOp, focInd, focVis, tabNav, buttonMenu, elements, textNodes. Whether a
+  partial scan is valid is not automated; the author chooses per act, and the rule metadata
+  protects the choice. Limits: the diff is by XPath, so inserting one sibling shifts later
+  same-tag indexes and the changed set can grow to the container (correct but coarse); a
+  changed-scope act finds only defects inside the roots, so `flow` unions the findings of every
+  act at a checkpoint rather than trusting one act.
+- **Phase 4 (shipped):** three parts.
+  - *Incremental pruning.* When checkpoint `k + 1` is created, `makeCheckpoint` first records
+    the structure diff between `k` and `k + 1` on the new checkpoint (job-time
+    `checkpoints[k + 1].structure`, which `getChangedRoots` and `getFlow` read instead of
+    recomputing, and which the acts loop deletes once `flow` holds it), then calls
+    `pruneCheckpoint(report, k)` (`procs/catalog.ts`), which deletes checkpoint `k`'s entries
+    that no test act of checkpoint `k` cites and drops its job-time XPath map. No later test
+    act can cite checkpoint `k`, since a test act belongs to the latest checkpoint, so the
+    temporary report that every test act reads stays bounded by one checkpoint's page plus
+    the cited entries of earlier ones. `catalogData.elementCount` is therefore the count of
+    entries ever made (`catalogNextIndex`), not the count at pruning time. A single-checkpoint
+    job is unaffected.
+  - *Selector acts.* The move acts (`button`, `checkbox`, `link`, `radio`, `search`, `select`,
+    `text`) accept a `selector` property, any Playwright selector (CSS, `text=`, `role=`,
+    `label=`), which replaces the act type's element selector and text matching; `index`
+    still picks among matches. A `text` act with `clear: true` replaces the input's value
+    instead of appending to it, and a `select` act whose `what` matches no option text falls
+    back to Playwright's value-or-label matching. Replay uses the same executors, so
+    selector acts replay like the rest.
+  - *User-path converter.* `procs/userPath.js` `getUserPathActs({startUrl, actions,
+    testActs, scanAtCheckpoints, what})` maps a recorded user path of the shape yra-monitor
+    stores (actions `click`, `fill`, `select`, `navigate`, `wait`, `checkpoint`, with
+    Playwright selectors) to a job's acts: launch, then one act per action (`button`, `text`
+    with `clear`, `select`, `url`, `state: idle` for a pause), and for each `checkpoint`
+    action a `checkpoint` act (named from its label, made unique) followed by a copy of each
+    requested test act, with `scope: 'changed'` downgraded to `page` at the first checkpoint.
+    The `userPath` validator runs the converter's output for a fill, select, checkpoint,
+    click, wait, checkpoint, navigate, checkpoint path. yra-monitor's user-path executor still
+    replays actions itself and runs a stub axe scan at checkpoints; replacing that with a
+    Testaro job built by this converter waits on the ingestion changes below.
+  - `flow` and scoped acts: a tool whose acts at a checkpoint were all scoped to changed
+    subtrees observed nothing outside them, so an earlier issue of that tool whose element
+    lies outside the roots is listed in the delta as `notRetested`, not `removed`.
+
+## Relationship to yra-monitor
+
+yra-monitor's DOM-difference feature captures outerHTML, a screenshot, element positions
+and the ARIA snapshot per URL per scan and diffs them across scans. Checkpoints capture the
+same artifacts per page state inside one job. The cross-scan history and comparison UI stay
+downstream; a later consolidation can store Testaro's checkpoint-0 artifacts instead of
+launching a separate capture browser.
+
+Until yra-monitor carries `checkpoint` and the checkpoint URL on stored rows, adds a
+checkpoint dimension to its unique-issue key and auto-resolve scoping, and stores one
+screenshot per checkpoint, multi-checkpoint reports must not be fed through its scan
+ingestion path.

package/docs/standard-result-outcome.md

@@ -0,0 +1,165 @@
+# Certainty in the standard result: the `outcome` field
+
+**Status:** Phase A shipped in Testaro 78.1.0 (2026-09-01). Phases B–D are recommendations for
+the Testilo fork and yra-monitor, and for a later Testaro major version.
+**Companion:** yra-monitor `docs/plans/engine-candidacy-pipeline.md` (Stage-1 instance policy,
+Stage-3b taxonomy mapping).
+
+## Why
+
+Rule engines report two different things about a finding: how bad it is (impact) and whether
+they are sure it is a defect (certainty). Every Testaro adapter used to fold certainty into
+`ordinalSeverity`, and each did it differently:
+
+| tool | uncertain native value | ordinal | certain native value | ordinal |
+| --- | --- | --- | --- | --- |
+| axe, pour, surea11y | incomplete / cantTell | 0–1 | violation / fail | 2–3 |
+| htmlcs | Warning | 0 | Error | 2 |
+| ibm | recommendation | 0 | violation and potential violation | 2 |
+| alfa | cantTell (rule ID rewritten) | 0 | failed | 2 |
+| aslint | warning | 1 | error | 2 |
+| qualWeb act-rules | warning | 1 | failed | 3 |
+| qualWeb best-practices | warning | 0 | failed | 1 |
+| wave | alert | 0 | error, contrast | 3 |
+| ed11y | dismissable warning | 0 | error | 2 |
+| nuVal, nuVnu | info | 0 | error | 3 |
+
+So severity 0 meant "definitely minor" for some tools and "possibly critical" for others, and
+nothing downstream could recover certainty except by the heuristic "ordinal 2 or above means
+asserted". The ACT validation harness had to read native results to score sensitivity and
+specificity by certainty band. The Testilo issue classification (tic) grew 57 `*Risk` issues to
+hold uncertain findings at weight 1, and its scorer counted an axe `incomplete` contrast finding
+exactly like an asserted violation because it maps rule IDs only.
+
+The two new candidate engines make the loss visible: pour separates `violations`, `incomplete`,
+and `manualReview`; surea11y grades per occurrence (`fail` / `cantTell`) and publishes six
+machine-readable `uncertainty` codes with a `needed` sentence saying what a reviewer must
+determine.
+
+## The model
+
+Four dimensions, kept separate:
+
+| dimension | meaning | where it lives |
+| --- | --- | --- |
+| outcome (per instance) | did the engine assert a failure, or could it not tell | standard instance, set by the adapter |
+| rule certainty (per rule) | is the check deterministic, or a heuristic that can only say "suspicious" | tic tool-rule entry, as an override |
+| impact (per instance) | how bad for a user | `ordinalSeverity`, once it means impact only |
+| issue weight (per issue) | severity of the defect class | tic `weight` |
+
+Certainty exists at two levels because engines both under-assert (axe `incomplete`) and
+over-assert (a heuristic reported as an error). The instance level is Testaro's job; the rule
+level is the taxonomy's.
+
+## Phase A: Testaro 78.1.0 (shipped)
+
+Every standard instance now has:
+
+```js
+{
+  ruleID, what, ordinalSeverity, count, catalogIndex,   // unchanged
+  outcome: 'failed' | 'cantTell',                        // required; ACT Rules Format vocabulary
+  uncertainty: 'not-computable' | 'judgement-required' | 'runtime-dependent'
+             | 'spec-only' | 'equivalence-unknown' | 'out-of-scope',   // optional, cantTell only
+  needed: '<what a reviewer must determine>'             // optional, cantTell only, ≤ 300 chars
+}
+```
+
+and `standardResult.outcomeTotals = {failed, cantTell}` (count-weighted).
+
+- `procs/standard.ts` is the one place the shape is built (`getStandardResult`, `getInstance`,
+  `addInstance`, `pushInstance`). Adapters that compute `totals` from native counts (ibm, htmlcs,
+  ed11y, wave, testaro) use `pushInstance`; the rest use `addInstance`.
+- `ordinalSeverity` and `totals` are unchanged for every tool. The golden diff on the pour and
+  surea11y validation jobs is identical after stripping the new fields.
+- Per-tool mapping: axe/pour/surea11y violations → `failed`, incomplete → `cantTell`; htmlcs
+  Warning → `cantTell`; ibm potential violation, potential recommendation, and manual →
+  `cantTell`; alfa `cantTell` → `cantTell` (the adapter no longer rewrites the rule ID to
+  `cantTell` / `cantTellTextContrast` or prefixes `what`; r66 and r69 carry
+  `judgement-required`); aslint warning, qualWeb warning, wave alert, nuVal/nuVnu info →
+  `cantTell`; ed11y dismissable warning → `cantTell` with `judgement-required`.
+- surea11y forwards `uncertainty.code` and `uncertainty.needed` (occurrence first, then check).
+  Its `confidence` value is dropped as non-portable.
+- Testaro's own rules default to `failed`. An `allRules` entry may set `outcome` and
+  `uncertainty` (`allCaps` is `cantTell` / `judgement-required`, consistent with the earlier
+  ruling that AI confidence must not be encoded in `ordinalSeverity`). A violation description
+  may carry a prefix: `2:` severity only, `2?:` severity plus `cantTell`, `?:` `cantTell` at the
+  rule's default severity. `getBasicResult` accepts `outcome`, `uncertainty`, and `needed` on
+  each violation.
+- `validation/act/capture.js` records `outcomeTotals` and per-instance `outcome` and
+  `uncertainty`, and marks a row as an error if any instance lacks a valid outcome.
+
+Why `outcome` and not `certainty`: the ACT Rules Format and EARL already use `failed` /
+`cantTell`, the ACT testcase feed the harness scores against uses `failed`, and a closed
+two-value enum keeps consumer logic total. A graded `certainty` would invite scales no two
+engines share and collide with surea11y's separate `confidence`.
+
+Why `needed` is its own field: `what` is an identity key downstream (unique-issue rows, tsp
+description sampling). Appending guidance to it would fracture identity across pages.
+
+## Phase B: Testilo fork (recommended)
+
+Tool-rule entries in the tic gain optional properties; issues gain two:
+
+```js
+tools: { htmlcs: { 'W-AAA.1_4_3.G18.BgImage': {
+  variable: false, quality: 1, what: '…',
+  outcome: 'cantTell',            // override; 'cantTell' is the common case
+  uncertainty: 'not-computable',  // rule-level default; the instance value wins
+  review: '…',                    // fallback "what to confirm" when the engine gives no `needed`
+  ignore: 'invalid'               // replaces prose [invalid]/[irrelevant]/[duplicative]/[unreliable]
+}}}
+issue: { how: '<one imperative fix sentence>', group: 'landmarkNotTop' }
+```
+
+- Precedence: `rule.outcome` > `instance.outcome` > legacy inference > `failed`. Legacy
+  inference (reports without `outcome`) is per tool: axe, pour, surea11y, htmlcs, ibm, wave,
+  qualWeb → `ordinalSeverity >= 2 ? failed : cantTell`; alfa → rule ID starts with `cantTell`;
+  testaro, ed11y, aslint, nuVal, nuVnu → `failed`.
+- `[speculative]` becomes `outcome: 'cantTell'`; the other bracket tags become `ignore`. The
+  `ignorable` pseudo-issue dissolves into per-rule `ignore`. A loader assertion rejects any
+  `what` still carrying a bracket tag.
+- Consolidate the 57 `*Risk` issues: merge into the base issue when one exists with the same fix
+  (7 name twins plus about 11 semantic twins such as contrastRisk → contrastAA/AAA by level);
+  rename (drop `Risk`) when the issue is the sole home of a defect class with a concrete fix
+  (pseudoHeadingRisk → pseudoHeading, which already holds axe `p-as-heading` and takes pour's
+  at `failed`; eventKeyboardRisk → eventKeyboard; labelConfusionRisk → labelPlacement with every
+  rule `cantTell` / `judgement-required`); keep three page-environment advisories
+  (applicationRisk, browserSupportRisk, noScriptRisk) with every rule `cantTell`. Export a
+  `migrations` map (`{contrastRisk: 'contrastAA', …}`) for downstream issue-ID rewrites.
+- Scoring: `cantTellWeight = 0.25` per instance inside the quality-weighted count (a weight-1
+  Risk issue merged into a weight-4 base is score-neutral). Element-aware dedup: an element's
+  outcome is `failed` if any tool says so, corroborated when more than one does;
+  `effectiveCount = max(old per-tool max with the factor applied, element-union count)`.
+  Output stays additive (`instanceCounts` numeric; add `outcomeCounts`, `elementCounts`,
+  `details.elements`; `details.element` byte-identical).
+- Granularity principle: one tic issue = one remediation class = one WCAG success criterion ×
+  one fix. `ruleID` and `what` carry the diagnosis; certainty is never a reason to split an
+  issue. Families get `group`; element-conditioned splits (pour `link-name` → image link vs text
+  link) are done in the adapter with a `.`-suffixed faceted rule ID, two tic entries each.
+
+## Phase C: yra-monitor (recommended)
+
+Types, `tic-manager` `resolveOutcome`, scoring-service passthrough, standardized rows and DB
+columns (`outcome`, `uncertainty`, `needed`) with a promote-only conflict rule (`failed` wins),
+issue-ID rewrite from `migrations`, a "Needs review" badge and filter, and for `cantTell` rows
+the text `instance.needed ?? rule.review ?? 'Manual review required'` under a "To confirm"
+heading.
+
+## Phase D: Testaro 79 (recommended)
+
+Redefine `ordinalSeverity` as impact only: 0 minor, 1 moderate, 2 serious, 3 critical, which is
+what yra-monitor already labels it as. `totals` keeps its shape but its composition changes
+(an axe incomplete + critical finding moves from `totals[1]` to `totals[3]`). Safe only after
+Phases B and C, when every consumer reads `outcome`.
+
+## Open decisions
+
+1. `cantTellWeight = 0.25`: confirm against Stage-4 precision on surea11y's `cantTell` band.
+2. The semantic Risk merges need a "same fix?" pass; videoCaptionRisk → videoNoText and
+   fieldSetRisk → fieldSetMissing are the least certain.
+3. Weights for renamed heuristic issues once they can carry a `failed` band.
+4. The alfa rule-ID change is visible to the current Testilo now: r66/r69 `cantTell` instances
+   map to contrastAAA/contrastAA at full weight until the scorer reads `outcome`. Pin Testaro
+   78.1 in the worker only together with the Phase-B Testilo.
+5. Whether `unique_issues.severity` should roll up (`GREATEST`) on conflict.

package/env.example

@@ -2,8 +2,6 @@
 WAVE_KEY=__placeholder__
 # You can get an Anthropic API key at https://console.anthropic.com/.
 ANTHROPIC_API_KEY=__placeholder__
-# Name to identify this Testaro instance to a server.
-AGENT=__placeholder__
 # Whether to make the browser visible (normally false).
 HEADED_BROWSER=false
 # Whether to output even forked-job logging to the primary log (normally false).
@@ -12,23 +10,44 @@ DEBUG=false
 WAITS=0
 # See https://nodejs.org/api/cli.html#options for all permitted options.
 NODE_OPTIONS='--trace-uncaught --trace-warnings'
-# Suppresses a routine warning from QualWeb.
+# Whether to suppress a routine warning from QualWeb.
 PUPPETEER_DISABLE_HEADLESS_WARNING=true
-# Replace the next 2 placeholders with http://localhost:3000 if Kilotest and Testaro are on the same host or the URL of the server (e.g., https://kilotest.com) if they are on different hosts.
-# URL to poll for available jobs when watching the network.
-NETWATCH_URL_JOB=__placeholder__/api/testaro-agent/job
-# URL to report results to when watching the network.
-NETWATCH_URL_REPORT=__placeholder__/api/testaro-agent/report
-# Password of this Testaro agent
-NETWATCH_URL_AUTH=__placeholder__
 # Directory (relative to project root) to watch for jobs.
 JOBDIR=__placeholder__
 # Directory (relative to project root) to write reports to when watching a directory for jobs.
 REPORTDIR=__placeholder__
 # Multiplier for time limits (normally 1).
 TIMEOUT_MULTIPLIER=1
+# Default isolation of test acts when a job does not specify one: process (a child process and
+# browser per test act), browser (one browser per job, a fresh context per test act), or page
+# (test acts share the live page of the current checkpoint). See docs/checkpoint-scanning.md.
+ISOLATION=process
 # Whether to abort the job when launch retries are exhausted or a test act crashes (default false).
 ABORT_ASSERTIVELY=false
+
+# Deployment options. A job property of the same meaning overrides each of these.
+
+# Load state a navigation waits for before tools run: networkidle (default), load, or
+# domcontentloaded. Retries relax it one step. networkidle never arrives on pages whose
+# network never quiets (beacons, polling), so a deployment scanning such pages may prefer load.
+NAV_WAIT_UNTIL=networkidle
+# Navigation time limit in milliseconds (default 10000).
+NAV_TIMEOUT=10000
+# Whether a 4xx response (other than 408 and 429) ends launch retries at once (default false).
+NAV_FAIL_FAST_4XX=false
+# Scanner identity sent as the X-YRA-Scanner request header, so firewalls can recognize the
+# scanner by a stable value (default none; jobs may set scannerId).
+SCANNER_ID=__placeholder__
+# Whether to scroll the full page after navigation so lazily loaded content is present before
+# cataloguing, imaging, and each tool (default false; jobs may set scroll).
+PRESCAN_SCROLL=false
+# Launch retries per rule of the testaro tool, which relaunches per contaminating rule
+# (default 2; raise for non-Chromium browsers, which navigate flakily on relaunch).
+TESTARO_RULE_RETRIES=2
+# Whether the qualWeb tool's browser runs stealth evasions and blocks ads and trackers
+# (default true; a qualWeb test act may set stealth and adBlock).
+QUALWEB_STEALTH=true
+QUALWEB_ADBLOCK=true
 # URL of any non-default (e.g., self-hosted) Nu Html Checker API (see ghcr.io/validator/validator).
 TESTARO_NU_URL=__placeholder__
 # Whether to launch the Playwright chromium browser without its sandbox (normally false).
@@ -37,6 +56,21 @@ TESTARO_NU_URL=__placeholder__
 # or run containers with a seccomp profile that permits user-namespace cloning.
 TESTARO_CHROMIUM_NO_SANDBOX=false
 
+# netWatch variables
+
+# Replace the next 2 placeholders with the URL of the server (e.g., http://localhost:3000 or  https://kilotest.com), including the path required by the server.
+# URL to poll for available jobs.
+NETWATCH_URL_JOB=__placeholder__
+# URL to send a job report.
+NETWATCH_URL_REPORT=__placeholder__
+# Type of authentication (none, pathBody, or header) required by the server.
+NETWATCH_AUTH_TYPE=__placeholder__
+# ID of this instance. Recorded in reports as sources.agent and used by header
+# authentication (where it must not contain a colon).
+NETWATCH_WORKER_ID=__placeholder__
+# Password of this instance. Required when NETWATCH_AUTH_TYPE is pathBody or header.
+NETWATCH_WORKER_SECRET=__placeholder__
+
 ## License
 
 # © 2021–2025 CVS Health and/or one of its affiliates. All rights reserved.

package/eslint.config.mjs

@@ -0,0 +1,101 @@
+/*
+  © 2026 Jeff Witt.
+
+  Licensed under the MIT License. See LICENSE file at the project root or
+  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  eslint.config.mjs
+  Flat ESLint configuration, replacing .eslintrc.json (unsupported since ESLint 9).
+*/
+
+// IMPORTS
+
+import js from '@eslint/js';
+import globals from 'globals';
+import {defineConfig, globalIgnores} from 'eslint/config';
+
+// CONFIGURATION
+
+export default defineConfig([
+  globalIgnores([
+    // Build output.
+    'dist/',
+    // Vendored HTML CodeSniffer bundle; not to be reformatted.
+    'htmlcs/HTMLCS.js',
+    // Vendored Editoria11y bundles.
+    'ed11y/',
+    // Vendored SureA11y standalone browser bundle (MPL-2.0; not to be modified).
+    'surea11y/surea11y.browser.js',
+    // Vendored Pour Engine bundle, built with esbuild (see pour/README.md).
+    'pour/pour.min.js',
+    // Files emitted by tsc from TypeScript sources (issue #73); lint the .ts sources instead.
+    'types.js',
+    'procs/catalog.js',
+    'procs/standard.js',
+    'procs/testaro.js',
+    'procs/xPath.js',
+    'testaro/*.js',
+    'tests/*.js',
+    '**/*.d.ts',
+    // Validation fixtures, some of which are intentionally defective.
+    'validation/tests/targets/'
+  ]),
+  {
+    files: ['**/*.js'],
+    extends: [js.configs.recommended],
+    languageOptions: {
+      ecmaVersion: 2021,
+      sourceType: 'commonjs',
+      globals: {
+        ...globals.browser,
+        ...globals.node
+      }
+    },
+    rules: {
+      indent: [
+        'error',
+        2,
+        {
+          MemberExpression: 0,
+          ObjectExpression: 'first'
+        }
+      ],
+      'linebreak-style': [
+        'error',
+        'unix'
+      ],
+      quotes: [
+        'error',
+        'single'
+      ],
+      semi: [
+        'error',
+        'always'
+      ],
+      'no-use-before-define': [
+        'error'
+      ],
+      'brace-style': [
+        'error',
+        'stroustrup'
+      ],
+      /*
+        Transitional demotions to warnings, so linting can gate changes now.
+        These rules have pre-existing violations, some of them latent defects.
+        Each is to be restored to an error once its violations are repaired.
+      */
+      'no-async-promise-executor': 'warn',
+      'no-const-assign': 'warn',
+      'no-constant-binary-expression': 'warn',
+      'no-empty': 'warn',
+      'no-undef': 'warn',
+      'no-unused-vars': 'warn',
+      'no-use-before-define': 'warn',
+      'no-useless-assignment': 'warn'
+    }
+  }
+]);