@molecule/api-ai-tools 1.9.1 → 1.9.3

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-17T07:58:25.504Z
+Generated: 2026-10-17T20:38:26.582Z
 -->
 
 # @molecule/api-ai-tools
@@ -352,6 +352,12 @@ interface TraceRequest {
   sent?: string
   /** What came back for that 4xx, bounded the same way — the API's own error body. */
   got?: string
+  /**
+   * The browser's own resource type (`document`, `fetch`, `xhr`, `font`, `image`, `stylesheet`,
+   * `script`, …). `document` when the request was the page load itself; when it ended in a
+   * `net::ERR_*`, nothing rendered and no selector or app request was measured.
+   */
+  type?: string
 }
 ```
 
@@ -757,6 +763,28 @@ interface FailureCause {
    * (xr-molecule-flash-m110 +18:42 rewrote a CORS middleware for a 20 s connection timeout).
    */
   kind: RunFailureKind
+  /**
+   * What the page itself showed at the moment of the failure, when the caller read it from
+   * Playwright's `error-context.md` (the alert / error list). The failure's own error line names
+   * the symptom — `waitForURL` timed out — and never what the page was saying: xr-molecule-flash-
+   * m122 +23:39 grouped eight `waitForURL` timeouts under one line while the page snapshots named
+   * the cause (`email can't be blank`, `username can't be blank` — the settings form submitted
+   * before its values had loaded). Attached to the cause so the fix needs no `cat` of the file.
+   */
+  pageShowed?: string[]
+}
+```
+
+#### `CausePageErrors`
+
+One failing test's page errors, as read from its `error-context.md`.
+
+```typescript
+interface CausePageErrors {
+  /** The test's location as the log prints it (`settings.spec.ts:107`). */
+  where: string
+  /** The alert / error items the page showed at the moment it failed. */
+  items: readonly string[]
 }
 ```
 
@@ -905,6 +933,37 @@ function locatedCommandSegments(command: string): LocatedCommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage, in order.
 
+#### `statementArgumentEnd(command, start, end)`
+
+Where an option of a statement's program belongs: one past the statement's last ARGUMENT.
+
+A flag written "at the end of the command" is not the runner's: a statement can end on a
+redirection (`… 2>&1`), and a statement can sit inside a group whose closer belongs to the
+shell, not to the words (`( … )`, `{ …; }`). Appending after that closer is a different shell
+word that the group has already closed — `… --config=x 2>&1) --reporter=list` is
+`sh: Syntax error: word unexpected`, which killed a backgrounded walk at once and pushed the
+model off the platform's runner shape (xr-molecule-flash-m129 +34:29). Write the option where
+the program's own arguments end and the rest of the statement still parses:
+`… --config=x --reporter=list 2>&1)`.
+
+The statement must be one {@link locatedCommandSegments} placed in THIS command: a statement
+inside a nested `sh -c '<command>'` string has no offsets here (its positions are positions in
+that string), so null is returned rather than a splice into the outer text.
+
+```typescript
+function statementArgumentEnd(
+  command: string,
+  start: number | null,
+  end: number | null,
+): number | null
+```
+
+- `command` — The shell command.
+- `start` — The statement's first character ({@link LocatedCommandSegment.start}).
+- `end` — One past the statement's last character ({@link LocatedCommandSegment.end}).
+
+**Returns:** The offset to write the option at, or null when the statement cannot be placed here.
+
 #### `commandTimeoutSeconds(command)`
 
 The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
@@ -1227,6 +1286,30 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `pipelineExitCodeNote(command, exitCode, output)`
+
+The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a
+pipeline's last stage rather than to the check that printed the output.
+
+Two shapes, both from a hand-run check with an unguarded pipe:
+
+- the code says 0 and the output carries failures (`tsc | head` reports `head`'s 0);
+- the code is non-zero and the checker printed no failures (`tsc | head && tail missing.log`
+  reports `tail`'s 1, and the checker was clean).
+
+A command with no pipe, a pipe guarded by `pipefail`, a pipeline where no checker runs, or a
+code and an output that agree all return null.
+
+```typescript
+function pipelineExitCodeNote(command: string, exitCode: number, output: string): string | null
+```
+
+- `command` — The command as the executor sent it.
+- `exitCode` — The code the shell reported (the pipeline's last stage's).
+- `output` — The command's raw stdout and stderr, for the checker's own text.
+
+**Returns:** One sentence naming the stage the code came from, or null.
+
 #### `leadingSleepPeek(command)`
 
 The leading `sleep` of a command, when the first statement is one and it asks for at least
@@ -1316,7 +1399,7 @@ function withSuiteConfig(command: string, config: string | null | undefined): st
 
 **Returns:** The command with the flag, or the command unchanged.
 
-#### `scopedRerunCommand(command, locations, excluded, config)`
+#### `scopedRerunCommand(command, locations, excluded, config, cwd)`
 
 The whole-suite command made scoped to the tests it should re-run instead: the same
 invocation — same directory, same settings — with the named `file:line`s in place of the whole
@@ -1334,13 +1417,15 @@ function scopedRerunCommand(
   locations: readonly string[],
   excluded?: readonly string[],
   config?: string | null,
+  cwd?: string | null,
 ): string
 ```
 
 - `command` — The whole-suite run's command.
-- `locations` — The failing `file:line`s to re-run, as the run's own log printed them — or, for a run that started outside the suite, the absolute form Playwright matches each file argument against.
+- `locations` — The failing `file:line`s to re-run, as the run's own log printed them. A location the reporter printed relative to the runner's own directory (`../../fixtures/…`, which no absolute path contains) is resolved here ({@link playwrightLocations}), so the command this returns is one Playwright can match.
 - `excluded` — The test titles the request carves out. They are inverted out (`--grep-invert`) so a re-run of the failing locations cannot report one of them again — xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about a test the request had already said does not count.
 - `config` — The config the run loaded, when the caller knows it; added when the command does not name one.
+- `cwd` — The directory `exec_command` was given, when it was; the base a location is resolved against when the command does not `cd` anywhere.
 
 **Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
 
@@ -1591,6 +1676,51 @@ function parseTraceArtifacts(stdout: string): TraceArtifact[]
 
 **Returns:** One entry per trace it printed.
 
+#### `isStaticAssetRequest(request)`
+
+Whether a request is one of the page shell's, not the test's (`STATIC_ASSET_PATH`).
+
+The document itself is never incidental — a page that never loaded IS the failure — and a
+request whose type is the app's own API (`fetch`/`xhr`) is judged by its path alone.
+
+```typescript
+function isStaticAssetRequest(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request is incidental to the step under test.
+
+#### `failedRequest(request)`
+
+Whether a trace recorded a request the server actually failed: a 4xx/5xx, or a network error.
+
+A 404 on a static asset is excepted: `/sw.js` and `/fonts/*` 404 on an app that never shipped
+them, and naming one as a failure sent m125 into writing the caching worker it had asked about.
+A 5xx on an asset, or a network error, still counts — the server did fail.
+
+```typescript
+function failedRequest(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request failed in a way the note should name.
+
+#### `unansweredRequest(request)`
+
+Whether a trace recorded NO response and no reason for it — a request that was aborted or still
+in flight when the test ended. It is not evidence that the server failed (m112 +30:45), and one
+the page shell made is not evidence about the step at all (m125 +29:33).
+
+```typescript
+function unansweredRequest(request: TraceRequest): boolean
+```
+
+- `request` — One request a trace recorded.
+
+**Returns:** True when the request is still in flight and worth naming.
+
 #### `failureTraceNote(items, target, earlierFailures)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
@@ -1911,6 +2041,12 @@ are output-only ({@link isOutputOnlyFilter}): a `| tee` or `| xargs` keeps its p
 caller that reports the run's exit code must then treat it as unknown
 ({@link suiteRunPipedAfterRunner}).
 
+A statement after the run's own pipeline (`; echo done`, `&& echo ok`) does not protect the
+filters before it: the filter is thrown away and the trailing statement is kept, so the log the
+run writes still holds every failure (xr-molecule-flash-m121 — a `| tail -5; echo done` kept its
+tail, and a 95-second walk's log held only the tally while the platform's own hold had handed
+that command back).
+
 ```typescript
 function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 ```
@@ -2437,28 +2573,65 @@ function repeatingFailure(log: string): RepeatingFailure | null
 
 **Returns:** The repeating cause, or null when no signature has {@link REPEATING_FAILURE_MIN} distinct tests behind it.
 
-#### `universalCause(log, found)`
+#### `specFilesSelected(command)`
 
-Whether a repeating cause is failing the whole run — the one case where stopping it is the
-right call.
+How many test FILES a Playwright run's own command narrows it to, or null when it selects the
+whole suite (or its selection cannot be read).
+
+{@link universalCause}'s file threshold is written for a whole-suite run, which a narrowed run
+can never reach. xr-molecule-flash-m119 (+42:08) re-ran ONE spec file against a hand-started
+`vite preview` the browser could not reach, and every test in it failed `page.goto: Timeout` —
+but one file is below {@link UNIVERSAL_CAUSE_FILES}, so the wait sat out its entire 280 s
+budget on a run that had already measured all it could.
 
-The test is: the cause accounts for every failure the log names, it has hit
-{@link UNIVERSAL_CAUSE_FILES} spec files or more, and nothing has passed since its first
-failure. An app that is not up, a 5xx on every request, or a selector that is missing on every
-page all look like that, and every remaining test will fail the same way — so the run's
-remaining minutes measure nothing. Anything less is NOT this: a cause that stops at one file,
-or that leaves other tests passing, or that shares the run with failures of another shape,
-leaves the run with something to say, and the run is the only thing that will say it. X1
-flash-m83 (2026-10-16) stopped eight local runs at their first repeating cause over 14.5
-minutes and never finished one; three of its deploys each fixed a single cause that a finished
-run would have listed alongside the others.
+The command is read through {@link commandSegments}, so a `playwright test` named as an
+argument is not a run. A {@link PLAYWRIGHT_VALUE_FLAGS} flag written without `=` takes the next
+word as its value, so a `--config app/e2e-suite.config.ts` is never counted as a spec file; a
+directory or a bare substring filter names files the command does not list, which answers null
+(the whole-suite threshold) rather than a count of the wrong files.
 
 ```typescript
-function universalCause(log: string, found: RepeatingFailure): UniversalCause | null
+function specFilesSelected(command: string): number | null
+```
+
+- `command` — The run's command.
+
+**Returns:** The number of distinct test files it names, or null when it names none (the whole suite) or the selection cannot be told.
+
+#### `universalCause(log, found, command)`
+
+Whether a repeating cause is failing the whole run — the one case where stopping it is the
+right call.
+
+The test is: the cause accounts for every failure the log names, it has hit the spec-file
+threshold, and nothing has passed since its first failure. The threshold is
+{@link UNIVERSAL_CAUSE_FILES} for a whole-suite run but the number of files the command
+SELECTED for a narrowed one ({@link specFilesSelected}): a one-file run can never span three,
+and xr-molecule-flash-m119 (+42:08) waited out its whole budget on exactly that shape. An app
+that is not up, a 5xx on every request, or a selector that is missing on every page all look
+like that, and every remaining test will fail the same way — so the run's remaining minutes
+measure nothing. A CONNECTION-class cause ({@link CONNECTION_CAUSE}) needs no file span at all:
+three tests that could not reach the app, with nothing passing since, is the app-unreachable
+case however few files the run walks.
+
+Anything less is NOT this: a cause that stops at one file of a multi-file run, or that leaves
+other tests passing, or that shares the run with failures of another shape, leaves the run with
+something to say, and the run is the only thing that will say it. X1 flash-m83 (2026-10-16)
+stopped eight local runs at their first repeating cause over 14.5 minutes and never finished
+one; three of its deploys each fixed a single cause that a finished run would have listed
+alongside the others.
+
+```typescript
+function universalCause(
+  log: string,
+  found: RepeatingFailure,
+  command?: string | null,
+): UniversalCause | null
 ```
 
 - `log` — The log so far.
 - `found` — The repeating cause {@link repeatingFailure} found in it.
+- `command` — How the run was started, when the caller knows it: its spec-file selection scales the file threshold ({@link specFilesSelected}).
 
 **Returns:** The cause's count and files, or null when the run is not failing whole.
 
@@ -2469,8 +2642,10 @@ for: a PROVEN cause that is failing the whole run.
 
 Both halves are load-bearing, each of them learned from a run that lost minutes to the other.
 
-- **Failing the WHOLE run** is {@link universalCause}: every failure the log names, across
-  {@link UNIVERSAL_CAUSE_FILES} spec files or more, with nothing passing since the first — the
+- **Failing the WHOLE run** is {@link universalCause}: every failure the log names, across the
+  spec-file threshold — {@link UNIVERSAL_CAUSE_FILES}, or the files a narrowed run's own
+  command selects, or {@link CONNECTION_CAUSE_TESTS} tests of an app that never answered — with
+  nothing passing since the first. That is the
   dont-stop-runs rule. X1 flash-m83 (2026-10-16) stopped eight local runs at their first
   repeating cause in 14.5 minutes and never finished one, and a run that still has other causes
   left to name is the only thing that will name them.
@@ -2481,9 +2656,6 @@ Both halves are load-bearing, each of them learned from a run that lost minutes
   xr-molecule-flash-m99 (2026-10-16) was told `status: 'repeating_failure'` twice on that
   shape — three `url-navigation.spec.ts` tests at ~16.2 s, one `timeout: 15_000` plus teardown
   — read the early return as "stop waiting, edit now", and voided a run that was still walking;
-  the second cost a 224 s wait that ended with no result at all.
-
-Neither half alone is enough, and {@link repeatingFailure} finding a signature is not either:
 
 _(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
 
@@ -2581,6 +2753,7 @@ function failureCausesNote(
   log: string,
   excluded?: readonly string[],
   run?: { command: string; cwd?: string; log?: string; config?: string | null },
+  pageErrors?: readonly CausePageErrors[],
 ): string | null
 ```
 
@@ -2597,11 +2770,11 @@ invocation, in the same directory, narrowed to those tests — or null when the
 is not a Playwright run this can narrow.
 
 The `locations` are the paths the run's own log printed, which are relative to the directory
-that run started in, so a re-run has to resolve them there: the command names that directory
-unless it already changes into one of its own, because the executor's next command starts
-wherever it starts. The returned command is for AFTER the run ends — it is a second run against
-the same app and database, and that is exactly what is refused while the run walks
-({@link suiteRunInTheWay}).
+that run started in, so the composer resolves them there ({@link scopedRerunCommand}): the
+command names that directory unless it already changes into one of its own, because the
+executor's next command starts wherever it starts. The returned command is for AFTER the run
+ends — it is a second run against the same app and database, and that is exactly what is
+refused while the run walks ({@link suiteRunInTheWay}).
 
 ```typescript
 function rerunOfRunningSuite(
@@ -2651,12 +2824,13 @@ function repeatingFailureNote(
     stop: string
     universal?: UniversalCause | null
     run?: { command: string; cwd?: string }
+    editsInvalidateRun?: boolean
   },
 ): string
 ```
 
 - `found` — What {@link repeatingFailure} found.
-- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for an {@link earlyReturnCause} — `universal`, what {@link universalCause} found (absent means the run is not failing whole), and `run`, how the run was started ({@link rerunOfRunningSuite}) when the caller knows it.
+- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for an {@link earlyReturnCause} — `universal`, what {@link universalCause} found (absent means the run is not failing whole), `run`, how the run was started ({@link rerunOfRunningSuite}) when the caller knows it, and `editsInvalidateRun`, true when the run measures the sandbox's own app (a local run, where an edit now changes what the suite is testing and its result stops counting).
 
 **Returns:** The note.
 
@@ -3189,6 +3363,15 @@ property of the run rather than of a page.
 const UNIVERSAL_CAUSE_FILES: 3
 ```
 
+#### `CONNECTION_CAUSE_TESTS`
+
+How many tests a connection-class cause must cover before the run is stopped even when they
+are all in one file — see {@link universalCause}.
+
+```typescript
+const CONNECTION_CAUSE_TESTS: 3
+```
+
 #### `PARSE_CHECKABLE`
 
 Files a parse check can vouch for cheaply right after a write.

package/dist/index.d.ts

@@ -137,6 +137,7 @@ export * from './cut-run.js';
 export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
+export * from './pipeline-exit-note.js';
 export * from './schemas.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -137,6 +137,7 @@ export * from './cut-run.js';
 export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
+export * from './pipeline-exit-note.js';
 export * from './schemas.js';
 export * from './sleep-peek.js';
 export * from './suite-overlap.js';

package/dist/pipeline-exit-note.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The exit code a hand-run check's result carries is the pipeline's LAST stage's, and a weak
+ * executor reads the number as the check's verdict.
+ *
+ * `npx tsc --noEmit 2>&1 | head -40` reports `head`'s 0 while the output above it carries a type
+ * error, and `… | head -40 && tail -30 missing.log` reports `tail`'s 1 while the checker was clean —
+ * both measured in xr-molecule-flash-m117 (+04:06, +08:05). A model that trusts the code concludes
+ * "clean" and ships a build that does not compile, or hunts an error that is not there. This module
+ * says which stage produced the code, and what the output actually carries, in one sentence beside
+ * `exitCode`.
+ *
+ * The parse is the package's own shell reader ({@link locatedCommandSegments}), so a `|` inside
+ * quotes or a heredoc is not a stage, and `set -o pipefail` (where it really runs) turns the note
+ * off: then the code IS the check's.
+ *
+ * @module
+ */
+/**
+ * The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a
+ * pipeline's last stage rather than to the check that printed the output.
+ *
+ * Two shapes, both from a hand-run check with an unguarded pipe:
+ *
+ * - the code says 0 and the output carries failures (`tsc | head` reports `head`'s 0);
+ * - the code is non-zero and the checker printed no failures (`tsc | head && tail missing.log`
+ *   reports `tail`'s 1, and the checker was clean).
+ *
+ * A command with no pipe, a pipe guarded by `pipefail`, a pipeline where no checker runs, or a
+ * code and an output that agree all return null.
+ *
+ * @param command - The command as the executor sent it.
+ * @param exitCode - The code the shell reported (the pipeline's last stage's).
+ * @param output - The command's raw stdout and stderr, for the checker's own text.
+ * @returns One sentence naming the stage the code came from, or null.
+ */
+export declare function pipelineExitCodeNote(command: string, exitCode: number, output: string): string | null;
+//# sourceMappingURL=pipeline-exit-note.d.ts.map

package/dist/pipeline-exit-note.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-exit-note.d.ts","sourceRoot":"","sources":["../src/pipeline-exit-note.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA2GH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAsCf"}

package/dist/pipeline-exit-note.js

@@ -0,0 +1,154 @@
+/**
+ * The exit code a hand-run check's result carries is the pipeline's LAST stage's, and a weak
+ * executor reads the number as the check's verdict.
+ *
+ * `npx tsc --noEmit 2>&1 | head -40` reports `head`'s 0 while the output above it carries a type
+ * error, and `… | head -40 && tail -30 missing.log` reports `tail`'s 1 while the checker was clean —
+ * both measured in xr-molecule-flash-m117 (+04:06, +08:05). A model that trusts the code concludes
+ * "clean" and ships a build that does not compile, or hunts an error that is not there. This module
+ * says which stage produced the code, and what the output actually carries, in one sentence beside
+ * `exitCode`.
+ *
+ * The parse is the package's own shell reader ({@link locatedCommandSegments}), so a `|` inside
+ * quotes or a heredoc is not a stage, and `set -o pipefail` (where it really runs) turns the note
+ * off: then the code IS the check's.
+ *
+ * @module
+ */
+import { locatedCommandSegments } from './command-position.js';
+/** The shells whose `-o pipefail` makes a pipeline report its first failing stage. */
+const PIPEFAIL_SHELLS = new Set(['ash', 'bash', 'dash', 'ksh', 'sh', 'zsh']);
+/**
+ * The programs a pipeline may end with when all they do is read what was printed and print it
+ * again — the stages that hand back their own status in place of the check's.
+ */
+const OUTPUT_ONLY_FILTERS = new Set([
+    'awk',
+    'cat',
+    'column',
+    'cut',
+    'egrep',
+    'fgrep',
+    'fmt',
+    'fold',
+    'grep',
+    'head',
+    'jq',
+    'nl',
+    'rg',
+    'sed',
+    'sort',
+    'tail',
+    'tr',
+    'uniq',
+    'wc',
+]);
+/** `1 type error` / `2 type errors`. */
+const plural = (count, one, many) => `${count} ${count === 1 ? one : many}`;
+/**
+ * The failure count a runner's tally names. Vitest prints two tallies — `Test Files  1 failed`
+ * above `Tests  2 failed` — and the last one is the tests, which is the number the note means.
+ *
+ * @param output - The runner's output.
+ * @returns The count in the last `N failed` tally, or 0.
+ */
+const failedTally = (output) => {
+    const tallies = [...output.matchAll(/\b(\d+) failed\b/g)];
+    return Number(tallies.at(-1)?.[1] ?? 0);
+};
+/** The checkers whose output says pass or fail in text of its own. */
+const CHECKERS = [
+    {
+        name: 'tsc',
+        runs: (program) => program === 'tsc' || program === 'vue-tsc',
+        failures: (output) => {
+            const errors = output.match(/\berror TS\d+/g)?.length ?? 0;
+            if (errors > 0)
+                return errors;
+            const found = /\bFound (\d+) errors?/.exec(output);
+            return found ? Number(found[1]) : 0;
+        },
+        label: (count) => plural(count, 'type error', 'type errors'),
+    },
+    {
+        name: 'eslint',
+        runs: (program) => program === 'eslint',
+        failures: (output) => {
+            const problems = /✖\s*(\d+)\s+problems?/.exec(output);
+            return problems ? Number(problems[1]) : 0;
+        },
+        label: (count) => plural(count, 'lint problem', 'lint problems'),
+    },
+    {
+        name: 'vitest',
+        runs: (program) => program === 'vitest',
+        failures: failedTally,
+        label: (count) => plural(count, 'failing test', 'failing tests'),
+    },
+    {
+        name: 'playwright',
+        runs: (_program, text) => /^playwright\s+test\b/.test(text),
+        failures: failedTally,
+        label: (count) => plural(count, 'failing test', 'failing tests'),
+    },
+];
+/** Whether the command turns on `pipefail`, so a pipeline reports the check's own status. */
+function guardedByPipefail(segments) {
+    return segments.some(({ program, args }) => (program === 'set' || PIPEFAIL_SHELLS.has(program)) && args.includes('pipefail'));
+}
+/**
+ * The sentence an `exec_command` result carries beside `exitCode` when the code belongs to a
+ * pipeline's last stage rather than to the check that printed the output.
+ *
+ * Two shapes, both from a hand-run check with an unguarded pipe:
+ *
+ * - the code says 0 and the output carries failures (`tsc | head` reports `head`'s 0);
+ * - the code is non-zero and the checker printed no failures (`tsc | head && tail missing.log`
+ *   reports `tail`'s 1, and the checker was clean).
+ *
+ * A command with no pipe, a pipe guarded by `pipefail`, a pipeline where no checker runs, or a
+ * code and an output that agree all return null.
+ *
+ * @param command - The command as the executor sent it.
+ * @param exitCode - The code the shell reported (the pipeline's last stage's).
+ * @param output - The command's raw stdout and stderr, for the checker's own text.
+ * @returns One sentence naming the stage the code came from, or null.
+ */
+export function pipelineExitCodeNote(command, exitCode, output) {
+    const running = locatedCommandSegments(command).filter((entry) => entry.segment !== null);
+    if (running.length < 2)
+        return null;
+    if (!running.some((entry) => entry.separator.trim() === '|'))
+        return null;
+    const segments = running.map((entry) => entry.segment);
+    if (guardedByPipefail(segments))
+        return null;
+    let checkerAt = -1;
+    for (let i = segments.length - 1; i >= 0; i -= 1) {
+        const segment = segments[i];
+        if (CHECKERS.some((checker) => checker.runs(segment.program, segment.text))) {
+            checkerAt = i;
+            break;
+        }
+    }
+    if (checkerAt < 0)
+        return null;
+    // The check's own status is lost only when a stage of the SAME pipeline follows it; a `&&` after
+    // the check already reports a real failure of its own, and a check followed by nothing reports
+    // its own code.
+    if (running[checkerAt + 1]?.separator.trim() !== '|')
+        return null;
+    const checkerSegment = segments[checkerAt];
+    const checker = CHECKERS.find((candidate) => candidate.runs(checkerSegment.program, checkerSegment.text));
+    const last = segments[segments.length - 1];
+    const failures = checker.failures(output);
+    if (exitCode === 0 && failures > 0) {
+        return (`the exit code 0 is the last stage's (${last.program}), not ${checker.name}'s — ` +
+            `the output carries ${checker.label(failures)}`);
+    }
+    if (exitCode !== 0 && failures === 0 && OUTPUT_ONLY_FILTERS.has(last.program)) {
+        return (`the exit code ${exitCode} is the last stage's (${last.program}), not ${checker.name}'s — ` +
+            'the checker printed no errors');
+    }
+    return null;
+}

package/dist/suite-overlap.d.ts

@@ -89,18 +89,21 @@ export declare function withSuiteConfig(command: string, config: string | null |
  * `Cannot navigate to invalid URL` because the re-run loaded no base URL).
  *
  * @param command - The whole-suite run's command.
- * @param locations - The failing `file:line`s to re-run, as the run's own log printed them — or,
- *   for a run that started outside the suite, the absolute form Playwright matches each file
- *   argument against.
+ * @param locations - The failing `file:line`s to re-run, as the run's own log printed them. A
+ *   location the reporter printed relative to the runner's own directory (`../../fixtures/…`,
+ *   which no absolute path contains) is resolved here ({@link playwrightLocations}), so the
+ *   command this returns is one Playwright can match.
  * @param excluded - The test titles the request carves out. They are inverted out
  *   (`--grep-invert`) so a re-run of the failing locations cannot report one of them again —
  *   xr-molecule-flash-m101 re-ran the whole 139-test suite and spent ~4 minutes to be told about
  *   a test the request had already said does not count.
  * @param config - The config the run loaded, when the caller knows it; added when the command
  *   does not name one.
+ * @param cwd - The directory `exec_command` was given, when it was; the base a location is
+ *   resolved against when the command does not `cd` anywhere.
  * @returns The scoped command, or the command unchanged when it runs no Playwright suite.
  */
-export declare function scopedRerunCommand(command: string, locations: readonly string[], excluded?: readonly string[], config?: string | null): string;
+export declare function scopedRerunCommand(command: string, locations: readonly string[], excluded?: readonly string[], config?: string | null, cwd?: string | null): string;
 /**
  * One suite run, as the rule that decides whether a second may start beside it reads it.
  *

package/dist/suite-overlap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suite-overlap.d.ts","sourceRoot":"","sources":["../src/suite-overlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoB1D;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAc1F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,GAAE,SAAS,MAAM,EAAO,EAChC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CA8BR;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,SAAS,EAAE,OAAO,CAAA;IAClB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,EACzD,SAAS,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7B,QAAQ,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,GAAG,IAAI,CAMV;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD"}
+{"version":3,"file":"suite-overlap.d.ts","sourceRoot":"","sources":["../src/suite-overlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAQH;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoB1D;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAc1F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,GAAE,SAAS,MAAM,EAAO,EAChC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EACtB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAClB,MAAM,CAqCR;AA8ID;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,SAAS,EAAE,OAAO,CAAA;IAClB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,EACzD,SAAS,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7B,QAAQ,EAAE,SAAS,CAAC,EAAE,GACrB,CAAC,GAAG,IAAI,CAMV;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQvD"}