@molecule/api-ai-tools 1.8.2 → 1.9.1

package/dist/command-position.d.ts

@@ -21,8 +21,14 @@
  * Not command position, and therefore not an invocation: a runner named as an argument
  * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
  * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
- * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
- * stripper first (`withoutHeredocs`, in `./suite-overlap.js`).
+ * WRITES is not a command it runs, so the bodies are blanked to spaces before anything is split
+ * ({@link blankHeredocBodies}); offsets stay exact, because the blanking preserves every position.
+ *
+ * The parser also answers WHERE each statement sits ({@link locatedCommandSegments}): `start`,
+ * `end`, `programOffset` and `assignmentOffset` are the offsets a caller splices at. They are
+ * token positions from this walk, never a search for re-joined text — the words are joined back
+ * with single spaces for matching, so `command.indexOf(segment.text)` fails on irregular spacing,
+ * on grouping braces, and on anything a heredoc body shifts (xr-molecule-flash-m105 +08:12).
  *
  * @module
  */
@@ -90,6 +96,24 @@ export interface LocatedCommandSegment {
      * inside a nested `sh -c` string, for the same reason as {@link start}.
      */
     assignmentOffset: number | null;
+    /**
+     * The offset in the command one past the statement's last word — where an option of this
+     * statement's program belongs, before whatever closes it. Null inside a nested `sh -c` string.
+     */
+    end: number | null;
+    /**
+     * The offset in the command of the word in command position — the program, once every wrapper
+     * in front of it is taken away (`npx --prefix /app <here>playwright test`). Null inside a
+     * nested `sh -c` string, and for a statement that only sets variables.
+     */
+    programOffset: number | null;
+    /**
+     * The separator the shell split at immediately before this statement — `|`, `||`, `&&`, `;`,
+     * a newline or `&` — or '' when it is the first statement of the command. It is the parse's own
+     * answer, so it is known even where the offsets are not, and a caller deciding whether two
+     * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
+     */
+    separator: string;
 }
 /**
  * Every statement of a command, with its own assignments and where it sits — assignment-only

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAkVD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AA+cD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AA4ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -21,8 +21,14 @@
  * Not command position, and therefore not an invocation: a runner named as an argument
  * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
  * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
- * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
- * stripper first (`withoutHeredocs`, in `./suite-overlap.js`).
+ * WRITES is not a command it runs, so the bodies are blanked to spaces before anything is split
+ * ({@link blankHeredocBodies}); offsets stay exact, because the blanking preserves every position.
+ *
+ * The parser also answers WHERE each statement sits ({@link locatedCommandSegments}): `start`,
+ * `end`, `programOffset` and `assignmentOffset` are the offsets a caller splices at. They are
+ * token positions from this walk, never a search for re-joined text — the words are joined back
+ * with single spaces for matching, so `command.indexOf(segment.text)` fails on irregular spacing,
+ * on grouping braces, and on anything a heredoc body shifts (xr-molecule-flash-m105 +08:12).
  *
  * @module
  */
@@ -380,6 +386,123 @@ function commandStart(words) {
     }
     return { at, nested: null, timeoutSeconds };
 }
+/**
+ * A command with every heredoc BODY blanked to spaces, so its length and every offset in it are
+ * unchanged.
+ *
+ * A heredoc body is data the command writes, not a command it runs: `cat > playwright.config.ts
+ * <<'EOF' … import { defineConfig, devices } from '@playwright/test' … EOF` writes a file and runs
+ * `cat`. Read as shell, though, every line of the body is a statement — and the words joined back
+ * for matching are not the words written, so a caller that placed a statement by searching for
+ * them found nothing, in a command whose real statements sat all along. On X1
+ * xr-molecule-flash-m105 (+08:12) the body's `import { defineConfig, devices } …` alone made
+ * `suiteRunPipedAfterRunner` answer "piped" for a run with no pipe left, and the run's exit code
+ * was dropped for the rest of the session.
+ *
+ * The body runs from the line after the operator to the line whose whole content is the delimiter
+ * (leading TABS stripped for `<<-`, as `man bash` defines it); the terminator line is blanked too,
+ * and its newline kept, so the statements around it still split at the same places. Newlines
+ * inside the body are kept for the same reason. `<<<` is a herestring, not a heredoc, and a `<<`
+ * inside quotes or a comment opens nothing.
+ *
+ * @param command - The shell command.
+ * @returns The command with the bodies blanked to spaces, the same length as the input.
+ */
+function blankHeredocBodies(command) {
+    if (!command.includes('<<'))
+        return command;
+    const chars = command.split('');
+    /** Overwrite a range with spaces, keeping its newlines so statements still split there. */
+    const blank = (from, to) => {
+        for (let i = from; i < to; i++)
+            if (chars[i] !== '\n')
+                chars[i] = ' ';
+    };
+    let lineStart = 0;
+    while (lineStart < command.length) {
+        const lineEndRaw = command.indexOf('\n', lineStart);
+        const lineEnd = lineEndRaw < 0 ? command.length : lineEndRaw;
+        const openers = [];
+        let quote = null;
+        for (let i = lineStart; i < lineEnd; i++) {
+            const char = command[i] ?? '';
+            if (quote !== null) {
+                if (char === quote)
+                    quote = null;
+                continue;
+            }
+            if (char === '"' || char === "'") {
+                quote = char;
+                continue;
+            }
+            // A `#` that starts a word opens a comment: the rest of the line is not shell words.
+            if (char === '#' && (i === lineStart || /\s/.test(command[i - 1] ?? '')))
+                break;
+            if (char !== '<' || command[i + 1] !== '<')
+                continue;
+            // `<<<` is a herestring: it opens no body.
+            if (command[i + 2] === '<') {
+                i += 2;
+                continue;
+            }
+            let at = i + 2;
+            const stripTabs = command[at] === '-';
+            if (stripTabs)
+                at += 1;
+            while (command[at] === ' ' || command[at] === '\t')
+                at += 1;
+            let delimiter;
+            const opener = command[at];
+            if (opener === '"' || opener === "'") {
+                const close = command.indexOf(opener, at + 1);
+                const wordEnd = close < 0 || close > lineEnd ? lineEnd : close;
+                delimiter = command.slice(at + 1, wordEnd);
+                at = wordEnd + 1;
+            }
+            else {
+                let wordEnd = at;
+                while (wordEnd < lineEnd && !/\s/.test(command[wordEnd] ?? ''))
+                    wordEnd += 1;
+                delimiter = command.slice(at, wordEnd);
+                at = wordEnd;
+            }
+            if (delimiter !== '')
+                openers.push({ delimiter, stripTabs });
+            i = at - 1;
+        }
+        if (openers.length === 0) {
+            if (lineEndRaw < 0)
+                break;
+            lineStart = lineEnd + 1;
+            continue;
+        }
+        // The bodies follow the line that opened them, in the order the operators were written.
+        let cursor = lineEndRaw < 0 ? command.length : lineEnd + 1;
+        for (const heredoc of openers) {
+            let bodyEnd = command.length;
+            let after = command.length;
+            let from = cursor;
+            while (from < command.length) {
+                const nl = command.indexOf('\n', from);
+                const line = command.slice(from, nl < 0 ? command.length : nl);
+                const compared = heredoc.stripTabs ? line.replace(/^\t+/, '') : line;
+                if (compared === heredoc.delimiter) {
+                    bodyEnd = from;
+                    after = nl < 0 ? command.length : nl + 1;
+                    break;
+                }
+                if (nl < 0)
+                    break;
+                from = nl + 1;
+            }
+            blank(cursor, bodyEnd);
+            blank(bodyEnd, after);
+            cursor = after;
+        }
+        lineStart = cursor;
+    }
+    return chars.join('');
+}
 /**
  * A command's statements and pipeline stages, split where the shell splits them — inside quotes
  * and inside a command substitution, a `|`, `;` or `&&` belongs to that command, not to this one.
@@ -400,19 +523,21 @@ function commandStart(words) {
  * no runner, and every run of it reads as nothing).
  *
  * @param command - The shell command.
- * @returns Each segment's text and the offset in the command its first character sits at, in
- *   order, with empty ones dropped.
+ * @returns Each statement's text, the offset its first character sits at, and the separator that
+ *   ended it (`|`, `&&`, `;`, a newline, … — '' after the last one), in order, with empty ones
+ *   dropped.
  */
 function splitSegments(command) {
+    const source = blankHeredocBodies(command);
     const parts = [];
     let buffer = '';
     /** The offset in the command of the current buffer's first character. */
     let bufferStart = 0;
     /** The nestings this position sits inside, outermost first. */
     const stack = [];
-    for (let i = 0; i < command.length; i++) {
-        const char = command[i] ?? '';
-        const next = command[i + 1];
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i] ?? '';
+        const next = source[i + 1];
         const top = stack[stack.length - 1];
         // A single-quoted string expands nothing at all: no escape, no substitution, and no quote
         // but its own ends it.
@@ -469,33 +594,46 @@ function splitSegments(command) {
             continue;
         }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
-            parts.push({ text: buffer, start: bufferStart });
+            parts.push({ text: buffer, start: bufferStart, after: char + next });
             buffer = '';
             i += 1;
             bufferStart = i + 1;
             continue;
         }
         if (char === ';' || char === '|' || char === '\n') {
-            parts.push({ text: buffer, start: bufferStart });
+            parts.push({ text: buffer, start: bufferStart, after: char });
             buffer = '';
             bufferStart = i + 1;
             continue;
         }
-        if (char === '&' && command[i - 1] !== '>' && next !== '>') {
-            parts.push({ text: buffer, start: bufferStart });
+        if (char === '&' && source[i - 1] !== '>' && next !== '>') {
+            parts.push({ text: buffer, start: bufferStart, after: '&' });
             buffer = '';
             bufferStart = i + 1;
             continue;
         }
         buffer += char;
     }
-    parts.push({ text: buffer, start: bufferStart });
-    return parts
-        .map((part) => ({
-        text: part.text.trim(),
-        start: part.start + (part.text.length - part.text.trimStart().length),
-    }))
-        .filter((part) => part.text !== '');
+    parts.push({ text: buffer, start: bufferStart, after: '' });
+    const out = [];
+    // The separator of the last part, kept across the empty ones so a statement's own separator
+    // survives the blank lines around it (`a &&\n b` and a heredoc's blanked body alike).
+    let lastAfter = null;
+    for (const part of parts) {
+        const text = part.text.trim();
+        if (text === '') {
+            lastAfter = part.after;
+            continue;
+        }
+        out.push({
+            text,
+            start: part.start + (part.text.length - part.text.trimStart().length),
+            after: part.after,
+            before: lastAfter ?? '',
+        });
+        lastAfter = part.after;
+    }
+    return out;
 }
 /**
  * One segment's words: quotes kept whole, grouping parentheses dropped, and a `(` written
@@ -559,6 +697,42 @@ function leadingAssignments(text) {
 export function commandSegments(command) {
     return locatedSegmentsOf(command, 0).flatMap((located) => located.segment === null ? [] : [located.segment]);
 }
+/**
+ * Where a statement's word sits in its own raw text, as {@link segmentWords} counts the words.
+ *
+ * The words are matched for READING (quotes whole, grouping braces dropped, a leading `(` taken
+ * off the first word); a caller that writes into the statement needs the offset it was written
+ * at. Both come from this one walk, so the two can never disagree about which word is which.
+ *
+ * @param text - One statement's text.
+ * @param index - The word's index in {@link segmentWords}'s list.
+ * @returns The word's offset in `text`, or null when there is no such word.
+ */
+function wordOffset(text, index) {
+    const placement = new RegExp(WORD.source, 'g');
+    let kept = 0;
+    let first = true;
+    for (let match = placement.exec(text); match !== null; match = placement.exec(text)) {
+        if (GROUPING.has(match[0]))
+            continue;
+        if (first) {
+            first = false;
+            const bare = match[0].replace(/^[({]+/, '');
+            // `segmentWords` shifts a first word that was nothing but grouping away, so the NEXT word
+            // is not stripped and is counted from zero.
+            if (bare === '')
+                continue;
+            if (kept === index)
+                return match.index + (match[0].length - bare.length);
+            kept += 1;
+            continue;
+        }
+        if (kept === index)
+            return match.index;
+        kept += 1;
+    }
+    return null;
+}
 /**
  * Every statement of a command, with its own assignments and where it sits — assignment-only
  * statements included, because the variables those persist are exactly what a later statement of
@@ -587,9 +761,31 @@ function locatedSegmentsOf(command, depth) {
         const words = segmentWords(part.text);
         const start = commandStart(words);
         const leading = leadingAssignments(part.text);
+        /** Every offset in this statement is an offset in the command it was written in. */
+        const placed = {
+            start: part.start,
+            end: part.start + part.text.length,
+            assignmentOffset: part.start + leading.end,
+            programOffset: words[start.at] === undefined ? null : part.start + (wordOffset(part.text, start.at) ?? 0),
+        };
         if (start.nested !== null) {
-            for (const inner of locatedSegmentsOf(start.nested, depth + 1))
-                out.push({ ...inner, start: null, assignmentOffset: null });
+            const inner = locatedSegmentsOf(start.nested, depth + 1);
+            for (let i = 0; i < inner.length; i += 1) {
+                const entry = inner[i];
+                if (!entry)
+                    continue;
+                out.push({
+                    ...entry,
+                    // A nested statement's positions are positions in the nested string, not in this
+                    // command. The FIRST one keeps this statement's own separator: the shell reads the
+                    // nested string where this statement stands.
+                    start: null,
+                    end: null,
+                    assignmentOffset: null,
+                    programOffset: null,
+                    separator: i === 0 ? part.before : entry.separator,
+                });
+            }
             continue;
         }
         const word = words[start.at];
@@ -600,8 +796,9 @@ function locatedSegmentsOf(command, depth) {
                 out.push({
                     segment: null,
                     assignments: leading.words,
-                    start: part.start,
-                    assignmentOffset: part.start + leading.end,
+                    ...placed,
+                    programOffset: null,
+                    separator: part.before,
                 });
             continue;
         }
@@ -615,8 +812,8 @@ function locatedSegmentsOf(command, depth) {
                 timeoutSeconds: start.timeoutSeconds,
             },
             assignments: leading.words,
-            start: part.start,
-            assignmentOffset: part.start + leading.end,
+            ...placed,
+            separator: part.before,
         });
     }
     return out;

package/dist/failure-kind.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What a failing request actually hit, read off the runner's own output.
+ *
+ * Three layers fail in three different ways, and only one of them is the app's code:
+ *
+ * - **connection** — the request never got an answer at all: the transport timed out, was
+ *   refused, reset, or could not resolve the name or negotiate TLS. Nothing about a handler,
+ *   a header or CORS was measured, so a re-run is the only thing that tells a cold start (a
+ *   machine deployed minutes ago whose boot finishes after the URL is live) from a real outage.
+ * - **status** — a response arrived and the HTTP status disagreed with what the suite asserts.
+ * - **assertion** — a response arrived and an assertion over its body failed.
+ *
+ * X0 xr-molecule-flash-m110 (+18:42 → +20:09) is the case this exists for: one Hurl file on the
+ * freshly deployed URL failed with `(28) Operation timed out … 0 bytes received` while the other
+ * twelve passed and 138 requests executed, and every note on the result read it as an assertion.
+ * The executor rewrote a CORS middleware, bisected a second server and latency-compared the two,
+ * then re-ran the same file — which passed in 3 s. A single re-run was the whole fix, and the one
+ * fact that would have said so is the failure's LAYER.
+ *
+ * ONE classifier, used by the causes note ({@link ./utilities.ts} `failureCausesNote`) and by the
+ * platform's own proof result (`molecule-dev` `suite-proof.ts`), so the two can never disagree
+ * about whether a failure was the app's to fix.
+ *
+ * @module
+ */
+/**
+ * The layer a failure came from: the transport (no answer at all), the response's status, or an
+ * assertion over a response that arrived.
+ */
+export type RunFailureKind = 'connection' | 'status' | 'assertion';
+/** What the transport did when a request never got an answer. */
+export type ConnectionFailureKind = 'timeout' | 'refused' | 'reset' | 'dns' | 'tls' | 'empty';
+/** One failure a runner printed, classified by the layer that failed. */
+export interface RunFailureClass {
+    /** The layer that failed. */
+    kind: RunFailureKind;
+    /** For a `connection` failure, what the transport did. */
+    connection?: ConnectionFailureKind;
+    /** How long the request waited before the transport gave up, in seconds, when printed. */
+    seconds?: number;
+    /** The `file:line` the runner printed for the failure, when it printed one. */
+    at?: string;
+}
+/**
+ * Classify ONE failure's text — a Hurl `error:` block, or a Playwright failure message/body.
+ *
+ * The transport is read first: a block that carries a connection error AND an assertion is a
+ * request whose assertion never ran, so it is a connection failure. Only a block that carries no
+ * failure signature at all answers null — unknown is never a connection failure, because a
+ * misread transport hides a real app failure behind "just re-run it".
+ *
+ * @param text - One failure's text, as the runner printed it.
+ * @returns The classification, or null when the text carries no failure this reads.
+ */
+export declare function classifyRunFailure(text: string): RunFailureClass | null;
+/**
+ * Whether every one of the classified failures is a connection failure — the only shape in which
+ * no response the app produced was measured.
+ *
+ * @param failures - The run's classifications, in printed order.
+ * @returns True when there is at least one and none of them is the app's.
+ */
+export declare function allConnectionFailures(failures: ReadonlyArray<RunFailureClass | null>): failures is ReadonlyArray<RunFailureClass & {
+    kind: 'connection';
+}>;
+//# sourceMappingURL=failure-kind.d.ts.map

package/dist/failure-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-kind.d.ts","sourceRoot":"","sources":["../src/failure-kind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAA;AAElE,iEAAiE;AACjE,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAA;AAE7F,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,IAAI,EAAE,cAAc,CAAA;IACpB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,qBAAqB,CAAA;IAClC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AA0ED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAoBvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,aAAa,CAAC,eAAe,GAAG,IAAI,CAAC,GAC9C,QAAQ,IAAI,aAAa,CAAC,eAAe,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAErE"}

package/dist/failure-kind.js

@@ -0,0 +1,134 @@
+/**
+ * What a failing request actually hit, read off the runner's own output.
+ *
+ * Three layers fail in three different ways, and only one of them is the app's code:
+ *
+ * - **connection** — the request never got an answer at all: the transport timed out, was
+ *   refused, reset, or could not resolve the name or negotiate TLS. Nothing about a handler,
+ *   a header or CORS was measured, so a re-run is the only thing that tells a cold start (a
+ *   machine deployed minutes ago whose boot finishes after the URL is live) from a real outage.
+ * - **status** — a response arrived and the HTTP status disagreed with what the suite asserts.
+ * - **assertion** — a response arrived and an assertion over its body failed.
+ *
+ * X0 xr-molecule-flash-m110 (+18:42 → +20:09) is the case this exists for: one Hurl file on the
+ * freshly deployed URL failed with `(28) Operation timed out … 0 bytes received` while the other
+ * twelve passed and 138 requests executed, and every note on the result read it as an assertion.
+ * The executor rewrote a CORS middleware, bisected a second server and latency-compared the two,
+ * then re-ran the same file — which passed in 3 s. A single re-run was the whole fix, and the one
+ * fact that would have said so is the failure's LAYER.
+ *
+ * ONE classifier, used by the causes note ({@link ./utilities.ts} `failureCausesNote`) and by the
+ * platform's own proof result (`molecule-dev` `suite-proof.ts`), so the two can never disagree
+ * about whether a failure was the app's to fix.
+ *
+ * @module
+ */
+/**
+ * Transport-level failures, most specific first: the patterns curl/Hurl and Chromium/Node print
+ * for a request that never got an answer. A message can carry more than one (`page.goto: Timeout
+ * 30000ms exceeded … net::ERR_CONNECTION_REFUSED`), and the more specific reading wins.
+ */
+const CONNECTION_FAILURES = [
+    // Hurl/curl's numbered errors (curl's exit codes, printed as `(28) Operation timed out …`).
+    ['empty', /\(\s*52\)\s*Empty reply from server/],
+    ['timeout', /\(\s*28\)\s*Operation timed out|Operation timed out after \d+/],
+    ['dns', /\(\s*6\)\s*Could not resolve host|Could not resolve host/],
+    [
+        'tls',
+        /\(\s*(?:35|51|58|59|60|77|83|90|91)\)\s|SSL connect error|SSL certificate problem|self[- ]signed certificate|UNABLE_TO_VERIFY_LEAF_SIGNATURE|CERT_HAS_EXPIRED/i,
+    ],
+    [
+        'refused',
+        /\(\s*7\)\s*(?:Failed to connect|Couldn't connect)|Failed to connect to\s|Couldn't connect to server/,
+    ],
+    ['reset', /\(\s*5[56]\)\s*(?:Recv|Send) failure|Connection reset by peer|socket hang up/],
+    // The browser's own net errors, and the Node errors underneath them.
+    ['timeout', /net::ERR_(?:CONNECTION_)?TIMED_OUT|\bETIMEDOUT\b/],
+    ['dns', /net::ERR_NAME_(?:NOT_RESOLVED|RESOLUTION_FAILED)|\bENOTFOUND\b|\bEAI_AGAIN\b/],
+    ['refused', /net::ERR_CONNECTION_REFUSED|\bECONNREFUSED\b/],
+    ['empty', /net::ERR_EMPTY_RESPONSE/],
+    ['reset', /net::ERR_CONNECTION_(?:RESET|CLOSED|ABORTED)|\bECONNRESET\b/],
+    ['tls', /net::ERR_(?:CERT|SSL|BAD_SSL)\w*/i],
+];
+/** A status assertion: the response arrived and its code is what failed. */
+const STATUS_FAILURE = /^\s*error:\s*Assert status code\b|actual value is <\d{3}>|\bHTTP(?:\/[\d.]+)?\s+[1-5]\d{2}\b|Expected[: ]+[1-5]\d{2}\b|\.status\(\)/m;
+/** Any other assertion over a response that arrived. */
+const ASSERTION_FAILURE = /^\s*error:\s*Assert\b|\bAssertionError\b|\bexpect\(|\bExpected[: ]|\bReceived[: ]|\bjsonpath\b|^\s*Error:/m;
+/** Hurl's `--> file:line:col`, the location of the failing request or assertion. */
+const HURL_AT = /-->\s+(\S+?):(\d+)(?::\d+)?\s*$/m;
+/** A spec file and line, the location a Playwright block names. */
+const SPEC_AT = /([\w./~-]+\.(?:spec|test)\.[cm]?[jt]sx?):(\d+)(?::\d+)?/;
+/** How long a request waited, as curl prints it (`Operation timed out after 20002 milliseconds`). */
+const WAITED_MS = /Operation timed out after (\d+) milliseconds/;
+/** How long a request waited, as Playwright prints it (`Timeout 30000ms exceeded`). */
+const WAITED_PLAYWRIGHT = /(?<!Test )\bTimeout (\d+)ms exceeded/;
+/**
+ * The `file:line` a failure block names, when it names one.
+ *
+ * @param text - The failure block.
+ * @returns The location, or undefined when the block carries none.
+ */
+function failureLocation(text) {
+    const hurl = HURL_AT.exec(text);
+    if (hurl)
+        return `${hurl[1]}:${hurl[2]}`;
+    const spec = SPEC_AT.exec(text);
+    return spec ? `${spec[1]}:${spec[2]}` : undefined;
+}
+/**
+ * How long the request waited before it gave up, in seconds, when the runner printed it.
+ *
+ * @param text - The failure block.
+ * @returns The seconds, rounded, or undefined.
+ */
+function waitedSeconds(text) {
+    const ms = WAITED_MS.exec(text) ?? WAITED_PLAYWRIGHT.exec(text);
+    return ms ? Math.round(Number(ms[1]) / 1000) : undefined;
+}
+/**
+ * Classify ONE failure's text — a Hurl `error:` block, or a Playwright failure message/body.
+ *
+ * The transport is read first: a block that carries a connection error AND an assertion is a
+ * request whose assertion never ran, so it is a connection failure. Only a block that carries no
+ * failure signature at all answers null — unknown is never a connection failure, because a
+ * misread transport hides a real app failure behind "just re-run it".
+ *
+ * @param text - One failure's text, as the runner printed it.
+ * @returns The classification, or null when the text carries no failure this reads.
+ */
+export function classifyRunFailure(text) {
+    const body = String(text ?? '');
+    if (body.trim().length === 0)
+        return null;
+    for (const [connection, pattern] of CONNECTION_FAILURES) {
+        if (!pattern.test(body))
+            continue;
+        const result = { kind: 'connection', connection };
+        const at = failureLocation(body);
+        if (at !== undefined)
+            result.at = at;
+        const seconds = waitedSeconds(body);
+        if (seconds !== undefined)
+            result.seconds = seconds;
+        return result;
+    }
+    const at = failureLocation(body);
+    const kind = STATUS_FAILURE.test(body)
+        ? 'status'
+        : ASSERTION_FAILURE.test(body)
+            ? 'assertion'
+            : null;
+    if (kind === null)
+        return null;
+    return at === undefined ? { kind } : { kind, at };
+}
+/**
+ * Whether every one of the classified failures is a connection failure — the only shape in which
+ * no response the app produced was measured.
+ *
+ * @param failures - The run's classifications, in printed order.
+ * @returns True when there is at least one and none of them is the app's.
+ */
+export function allConnectionFailures(failures) {
+    return failures.length > 0 && failures.every((failure) => failure?.kind === 'connection');
+}

package/dist/index.d.ts

@@ -134,9 +134,11 @@ export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
 export * from './cut-run.js';
+export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.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,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,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,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

@@ -134,9 +134,11 @@ export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
 export * from './cut-run.js';
+export * from './failure-kind.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';