@reticlehq/server 3.3.0 → 3.4.0

package/dist/features/crawl/crawl.js

@@ -7,6 +7,7 @@
 import { span } from '../../trace.js';
 import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
 import { crawlEmptyNote } from './crawl-empty.js';
+import { failedRequests, isConsoleError } from '../exhaust/session-fold.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { parseInteractive } from '@reticlehq/core';
 import { sourceOf } from '../../surface/tools/tools-helpers.js';
@@ -44,9 +45,6 @@ function isActivity(e) {
         e.type === EventType.ANIM_START ||
         e.type === EventType.ANIM_END);
 }
-function isConsoleError(e) {
-    return e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
-}
 const SOURCE_FRAME = /^(.*):(\d+):(\d+)$/;
 const COMPONENT_STACK_FIELDS = ['componentStack', 'message'];
 const URL_SOURCE_PROTOCOLS = new Set([
@@ -156,14 +154,6 @@ function sourceFromConsoleError(event) {
         ? undefined
         : `${file}:${String(directLine)}`;
 }
-function failedRequests(events, floor) {
-    return events.filter((e) => {
-        if (e.type !== EventType.NET_REQUEST)
-            return false;
-        const status = asNumber(e.data['status']);
-        return status !== undefined && status >= floor;
-    });
-}
 /**
  * Controls whose correct behaviour IS to do nothing when clicked.
  *
@@ -198,17 +188,26 @@ export function legitimatelyInert(desc) {
  * fails — this is a disclosure, and failing the whole crawl to report on coverage would be worse
  * than the silence it is fixing.
  */
-async function countRevealed(session, opts, before) {
+async function revealedItems(session, opts, before) {
     const snap = await session.command(ReticleCommand.SNAPSHOT, {
         mode: 'interactive',
         ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
     });
     if (!snap.ok)
-        return 0;
+        return [];
     const tree = (snap.result ?? {}).tree ?? '';
     const known = new Set(before.map((i) => (i.ref !== '' ? i.ref : i.desc)));
-    return parseInteractive(tree).filter((i) => !known.has(i.ref !== '' ? i.ref : i.desc)).length;
+    return parseInteractive(tree).filter((i) => !known.has(i.ref !== '' ? i.ref : i.desc));
 }
+/**
+ * How many times a crawl re-enumerates to follow what its own clicks revealed.
+ *
+ * ponytail: rounds, not a real frontier. Each round clicks what the previous one uncovered (a
+ * dashboard behind a login, a modal's contents), which is the depth a one-pass crawl never had. A
+ * page that reveals something new on every click would otherwise never end; past this it reports
+ * the rest as unvisited, as before. `maxSteps` still bounds the total.
+ */
+const REVEAL_ROUNDS = 2;
 /**
  * The confirmation half of the dead-control rule. Kept separate so the rule above reads as one
  * question, and so the second click gets its own window: reusing the first would let the first
@@ -218,14 +217,14 @@ async function countRevealed(session, opts, before) {
  * wrong here returns `false`: a confirmation that cannot run is not evidence, and the direction that
  * costs a missed finding is better than the one that invents one.
  */
-async function stillSilent(session, item, settleMs, opts, sleep) {
+async function stillSilent(session, item, settleMs, confirm, sleep) {
     const since = session.elapsed();
     session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
     try {
         const again = await session.command(ReticleCommand.ACT, {
             ref: item.ref,
             action: ActionType.CLICK,
-            args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+            args: confirm ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
         });
         await sleep(settleMs);
         // A control that has GONE (the first click removed it) is not a dead control — it did something.
@@ -260,152 +259,167 @@ export async function crawl(session, opts, sleep) {
     const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
     const seen = new Set();
     let stepsRun = 0;
-    for (const item of items) {
-        if (stepsRun >= maxSteps)
-            break;
-        // Dedupe by ref (the unique element), not by label — two "Delete"/"Edit" controls share a desc
-        // but are different controls; collapsing them by label under-covers list/table UIs.
-        const dedupeKey = item.ref !== '' ? item.ref : item.desc;
-        if (seen.has(dedupeKey))
-            continue; // don't re-click the same control
-        seen.add(dedupeKey);
-        stepsRun += 1;
-        visited.push(item.desc);
-        const since = session.elapsed();
-        session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
-        let act;
-        /*
-         * A full page load reconnects the SDK, which rejects whatever command was in flight.
-         *
-         * On a server-rendered app that is what following a link DOES — every navigation replaces the
-         * session — so the rejection is evidence the click worked, not that it failed. Crawl used to let
-         * it propagate and died on link one of every Django, Rails or plain-HTML app.
-         *
-         * Recorded as a navigation rather than swallowed: a control that took the page somewhere is the
-         * opposite of a dead one, and reporting it as dead would be the false negative crawl exists to
-         * find.
-         */
-        let navigatedAway = false;
-        try {
-            // One span per control clicked, so a slow crawl names the control rather than reporting a
-            // single multi-second total. The settle sleep below is INSIDE it deliberately: it is part of
-            // what a step costs, and hiding it would make the fixed budget look free.
-            act = await span('crawl.step', { ref: item.ref, desc: item.desc }, async () => {
-                const clicked = await session.command(ReticleCommand.ACT, {
+    const found = [...items];
+    let frontier = items;
+    for (let round = 0;; round += 1) {
+        // `confirmDangerous` covers the controls on the page the caller pointed the crawl at. What a
+        // click REVEALED is new: the "Yes, delete" behind a "Delete" was confirmed with the same flag,
+        // so one call finished a deletion nobody authorized the second half of.
+        const confirm = 0 === round && true === opts.confirmDangerous;
+        for (const item of frontier) {
+            if (stepsRun >= maxSteps)
+                break;
+            // Dedupe by ref (the unique element), not by label — two "Delete"/"Edit" controls share a desc
+            // but are different controls; collapsing them by label under-covers list/table UIs.
+            const dedupeKey = item.ref !== '' ? item.ref : item.desc;
+            if (seen.has(dedupeKey))
+                continue; // don't re-click the same control
+            seen.add(dedupeKey);
+            stepsRun += 1;
+            visited.push(item.desc);
+            const since = session.elapsed();
+            session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
+            let act;
+            /*
+             * A full page load reconnects the SDK, which rejects whatever command was in flight.
+             *
+             * On a server-rendered app that is what following a link DOES — every navigation replaces the
+             * session — so the rejection is evidence the click worked, not that it failed. Crawl used to let
+             * it propagate and died on link one of every Django, Rails or plain-HTML app.
+             *
+             * Recorded as a navigation rather than swallowed: a control that took the page somewhere is the
+             * opposite of a dead one, and reporting it as dead would be the false negative crawl exists to
+             * find.
+             */
+            let navigatedAway = false;
+            try {
+                // One span per control clicked, so a slow crawl names the control rather than reporting a
+                // single multi-second total. The settle sleep below is INSIDE it deliberately: it is part of
+                // what a step costs, and hiding it would make the fixed budget look free.
+                act = await span('crawl.step', { ref: item.ref, desc: item.desc }, async () => {
+                    const clicked = await session.command(ReticleCommand.ACT, {
+                        ref: item.ref,
+                        action: ActionType.CLICK,
+                        args: confirm ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+                    });
+                    await sleep(settleMs);
+                    return clicked;
+                });
+            }
+            catch (err) {
+                if (!isSessionReplacedError(err))
+                    throw err;
+                navigatedAway = true;
+            }
+            finally {
+                // Close on every exit so a throw cannot leak the window onto the next control's events.
+                session.finishAction?.();
+            }
+            const events = session.eventsSince(since);
+            // Captured at act time, so it survives a click that unmounts its own control.
+            const src = sourceOf(asRecord(act?.result)['source']);
+            const controlSource = src === undefined ? undefined : `${src.file}:${String(src.line)}`;
+            const source = controlSource === undefined ? {} : { source: controlSource };
+            const errs = events.filter(isConsoleError);
+            for (const e of errs) {
+                counts.consoleErrors += 1;
+                const errorSource = sourceFromConsoleError(e) ?? controlSource;
+                anomalies.push({
+                    kind: CrawlAnomalyKind.CONSOLE_ERROR,
                     ref: item.ref,
-                    action: ActionType.CLICK,
-                    args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+                    desc: item.desc,
+                    detail: asString(e.data['message']) ?? e.type,
+                    ...(errorSource === undefined ? {} : { source: errorSource }),
                 });
-                await sleep(settleMs);
-                return clicked;
-            });
-        }
-        catch (err) {
-            if (!isSessionReplacedError(err))
-                throw err;
-            navigatedAway = true;
-        }
-        finally {
-            // Close on every exit so a throw cannot leak the window onto the next control's events.
-            session.finishAction?.();
-        }
-        const events = session.eventsSince(since);
-        // Captured at act time, so it survives a click that unmounts its own control.
-        const src = sourceOf(asRecord(act?.result)['source']);
-        const controlSource = src === undefined ? undefined : `${src.file}:${String(src.line)}`;
-        const source = controlSource === undefined ? {} : { source: controlSource };
-        const errs = events.filter(isConsoleError);
-        for (const e of errs) {
-            counts.consoleErrors += 1;
-            const errorSource = sourceFromConsoleError(e) ?? controlSource;
-            anomalies.push({
-                kind: CrawlAnomalyKind.CONSOLE_ERROR,
-                ref: item.ref,
-                desc: item.desc,
-                detail: asString(e.data['message']) ?? e.type,
-                ...(errorSource === undefined ? {} : { source: errorSource }),
-            });
-        }
-        for (const e of failedRequests(events, CRAWL_DEFAULTS.FAILED_STATUS)) {
-            counts.failedRequests += 1;
-            const method = asString(e.data['method']) ?? '';
-            const url = asString(e.data['url']) ?? '';
-            const status = asNumber(e.data['status']);
-            anomalies.push({
-                kind: CrawlAnomalyKind.FAILED_REQUEST,
-                ref: item.ref,
-                desc: item.desc,
-                detail: `${method} ${url} → ${status ?? ''}`.trim(),
-                ...source,
-            });
-        }
-        // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
-        // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
-        // A crawl clicks controls that navigate, so its windows are the ones most likely to straddle a
-        // document boundary — and a finding here is reported against a specific control by name.
-        for (const c of findContradictions(events, {
-            currentDocumentId: session.currentDocumentId,
-            currentEditEpoch: session.currentEditEpoch,
-            appOrigin: session.url,
-            background: session.background,
-            // A hidden tab cannot be observed, so its silence is not evidence. Stated from the session
-            // rather than left to a heartbeat landing inside a 300ms window.
-            pageHidden: session.throttled?.(),
-            // The crawl's window IS one control's click, so it can name the floor the consequence rules
-            // need — without it a crawl would report nothing about the UI moving, which is most of what a
-            // crawl is for.
-            actionSince: since,
-        })) {
-            counts.contradictions += 1;
-            anomalies.push({
-                kind: c.kind,
-                ref: item.ref,
-                desc: item.desc,
-                detail: `${c.claim}, but ${c.counter} — ${c.detail}`,
-                ...source,
-            });
-        }
-        // DEAD: the click dispatched but the app produced no activity and no error to explain it.
-        //
-        // Unless the control is SUPPOSED to be inert. A control clicked twice with no reaction may be
-        // legitimately inert — a `[disabled]` button, an already `[checked]` radio, a text input (a click
-        // focuses it; mutating would be the surprise). An anomaly list that is all false positives is
-        // worse than no anomaly list: the agent spends its budget disproving it and learns to skip it.
-        //
-        // Deliberately NOT fixed by counting focus as activity: focus moving is not the app reacting, and
-        // treating it as such would make a genuinely dead button that takes focus look alive — trading
-        // noise for the false negative this check exists to catch.
-        const dispatched = asRecord(act?.result)['dispatched'] !== false && true === act?.ok;
-        if (
-        // A control that took the page somewhere is the OPPOSITE of a dead one. Without this, every
-        // link on a server-rendered app would be reported as an anomaly by the check that exists to
-        // find controls which do nothing.
-        !navigatedAway &&
-            dispatched &&
-            0 === errs.length &&
-            !events.some(isActivity) &&
-            !legitimatelyInert(item.desc)) {
-            // CONFIRM IT. One silent sample is a sample, not a fact, and this is the strongest claim the
-            // crawler makes — "your button does nothing" is the finding a reader acts on immediately.
-            //
-            // Measured on a fixture whose FIXED twin has a working primary CTA: the crawl reported it dead
-            // on 2 of 3 runs, always a control the drive had already clicked successfully moments earlier.
-            // A false positive in this tier is the most expensive kind there is — it is the tier a verdict
-            // is built from, and the twin column is the whole claim this product makes.
-            //
-            // A second click costs one round trip on the rare control that looked dead, and nothing at all
-            // on every control that did not. A genuinely dead control is silent twice; the flake is not.
-            if (await stillSilent(session, item, settleMs, opts, sleep)) {
-                counts.deadControls += 1;
+            }
+            for (const e of failedRequests(events, CRAWL_DEFAULTS.FAILED_STATUS)) {
+                counts.failedRequests += 1;
+                const method = asString(e.data['method']) ?? '';
+                const url = asString(e.data['url']) ?? '';
+                const status = asNumber(e.data['status']);
                 anomalies.push({
-                    kind: CrawlAnomalyKind.DEAD_CONTROL,
+                    kind: CrawlAnomalyKind.FAILED_REQUEST,
                     ref: item.ref,
                     desc: item.desc,
-                    detail: 'clicked TWICE and the app did nothing either time (no DOM/network/route/signal change)',
+                    detail: `${method} ${url} → ${status ?? ''}`.trim(),
                     ...source,
                 });
             }
+            // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
+            // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
+            // A crawl clicks controls that navigate, so its windows are the ones most likely to straddle a
+            // document boundary — and a finding here is reported against a specific control by name.
+            for (const c of findContradictions(events, {
+                currentDocumentId: session.currentDocumentId,
+                currentEditEpoch: session.currentEditEpoch,
+                appOrigin: session.url,
+                background: session.background,
+                // A hidden tab cannot be observed, so its silence is not evidence. Stated from the session
+                // rather than left to a heartbeat landing inside a 300ms window.
+                pageHidden: session.throttled?.(),
+                // The crawl's window IS one control's click, so it can name the floor the consequence rules
+                // need — without it a crawl would report nothing about the UI moving, which is most of what a
+                // crawl is for.
+                actionSince: since,
+            })) {
+                counts.contradictions += 1;
+                anomalies.push({
+                    kind: c.kind,
+                    ref: item.ref,
+                    desc: item.desc,
+                    detail: `${c.claim}, but ${c.counter} — ${c.detail}`,
+                    ...source,
+                });
+            }
+            // DEAD: the click dispatched but the app produced no activity and no error to explain it.
+            //
+            // Unless the control is SUPPOSED to be inert. A control clicked twice with no reaction may be
+            // legitimately inert — a `[disabled]` button, an already `[checked]` radio, a text input (a click
+            // focuses it; mutating would be the surprise). An anomaly list that is all false positives is
+            // worse than no anomaly list: the agent spends its budget disproving it and learns to skip it.
+            //
+            // Deliberately NOT fixed by counting focus as activity: focus moving is not the app reacting, and
+            // treating it as such would make a genuinely dead button that takes focus look alive — trading
+            // noise for the false negative this check exists to catch.
+            const dispatched = asRecord(act?.result)['dispatched'] !== false && true === act?.ok;
+            if (
+            // A control that took the page somewhere is the OPPOSITE of a dead one. Without this, every
+            // link on a server-rendered app would be reported as an anomaly by the check that exists to
+            // find controls which do nothing.
+            !navigatedAway &&
+                dispatched &&
+                0 === errs.length &&
+                !events.some(isActivity) &&
+                !legitimatelyInert(item.desc)) {
+                // CONFIRM IT. One silent sample is a sample, not a fact, and this is the strongest claim the
+                // crawler makes — "your button does nothing" is the finding a reader acts on immediately.
+                //
+                // Measured on a fixture whose FIXED twin has a working primary CTA: the crawl reported it dead
+                // on 2 of 3 runs, always a control the drive had already clicked successfully moments earlier.
+                // A false positive in this tier is the most expensive kind there is — it is the tier a verdict
+                // is built from, and the twin column is the whole claim this product makes.
+                //
+                // A second click costs one round trip on the rare control that looked dead, and nothing at all
+                // on every control that did not. A genuinely dead control is silent twice; the flake is not.
+                if (await stillSilent(session, item, settleMs, confirm, sleep)) {
+                    counts.deadControls += 1;
+                    anomalies.push({
+                        kind: CrawlAnomalyKind.DEAD_CONTROL,
+                        ref: item.ref,
+                        desc: item.desc,
+                        detail: 'clicked TWICE and the app did nothing either time (no DOM/network/route/signal change)',
+                        ...source,
+                    });
+                }
+            }
         }
+        if (coverageCapped || stepsRun >= maxSteps || REVEAL_ROUNDS <= round)
+            break;
+        const next = await revealedItems(session, opts, found);
+        if (0 === next.length)
+            break;
+        found.push(...next);
+        frontier = next;
     }
     // One more look, AFTER the clicks. The enumeration above happened before any of them, so anything
     // the crawl itself unlocked — a dashboard behind a login, a modal's contents, a tab's panel — was
@@ -414,9 +428,9 @@ export async function crawl(session, opts, sleep) {
     // as new, and a surface that SHRANK (a modal closed) reports nothing, because nothing went
     // unvisited. Skipped when the snapshot was already capped: that case has its own note and a second
     // one would only muddy it.
-    const revealed = coverageCapped ? 0 : await countRevealed(session, opts, items);
+    const revealed = coverageCapped ? 0 : (await revealedItems(session, opts, found)).length;
     return {
-        interactiveFound: items.length,
+        interactiveFound: found.length,
         stepsRun,
         anomalies,
         counts,
@@ -424,7 +438,7 @@ export async function crawl(session, opts, sleep) {
         // True when coverage was bounded for EITHER reason: the step budget ran out, or the page was
         // bigger than one snapshot. Conflating "I stopped early" with "I saw everything" is what turns a
         // partial sweep into "all controls healthy".
-        truncated: items.length > stepsRun || coverageCapped || revealed > 0,
+        truncated: found.length > stepsRun || coverageCapped || revealed > 0,
         ...(coverageCapped
             ? { coverageNote: CAPPED_SNAPSHOT_NOTE }
             : revealed > 0
@@ -434,7 +448,7 @@ export async function crawl(session, opts, sleep) {
         // same answer. See crawl-empty.
         ...(() => {
             const note = crawlEmptyNote({
-                interactiveFound: items.length,
+                interactiveFound: found.length,
                 stepsRun,
                 maxSteps,
                 truncated: coverageCapped,

package/dist/features/exhaust/app-coverage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `reticle_coverage { scope: "app" }` — fold this session into the ledger and say where "everything"
+ * stands, level by level.
+ */
+import type { ReticleEvent } from '@reticlehq/core';
+import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type RawScriptCoverage } from './code-coverage.js';
+import { type LevelReport } from './ledger.js';
+export interface AppCoverageReport {
+    levels: LevelReport[];
+    /** Writes whose failure path was driven and the app claimed success anyway. Findings, not gaps. */
+    unhandledWrites: string[];
+    /** Levels below the best they ever reached. */
+    regressed: {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    note?: string;
+}
+export declare function foldAppCoverage(input: {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    seen: readonly string[];
+    session: {
+        url: string;
+        actedLabels(): ReadonlySet<string>;
+        provedLabels?(): ReadonlySet<string>;
+        eventsSince(cursor: number): ReticleEvent[];
+    };
+    takeCode?: (sessionUrl: string) => Promise<readonly RawScriptCoverage[] | undefined>;
+    now: () => number;
+}): Promise<AppCoverageReport>;

package/dist/features/exhaust/app-coverage.js

@@ -0,0 +1,31 @@
+/**
+ * `reticle_coverage { scope: "app" }` — fold this session into the ledger and say where "everything"
+ * stands, level by level.
+ */
+import { emptyCodeCoverage, foldCodeCoverage } from './code-coverage.js';
+import { LedgerStore, levelsOf, regressions } from './ledger.js';
+import { sessionDelta } from './session-fold.js';
+const NO_CODE_NOTE = 'The `executed` level is unmeasured here: code coverage needs a browser Reticle drives (`reticle drive`, or RETICLE_CDP_URL), and collection starts at the first coverage request, so drive and ask again. The other levels are real.';
+export async function foldAppCoverage(input) {
+    const { session } = input;
+    const take = await input.takeCode?.(session.url);
+    const delta = sessionDelta({
+        seen: input.seen,
+        acted: session.actedLabels(),
+        proved: session.provedLabels?.() ?? [],
+        url: session.url,
+        events: session.eventsSince(0),
+    });
+    const ledger = await new LedgerStore(input.fs, input.reticleRoot).merge({
+        ...delta,
+        ...(take === undefined
+            ? {}
+            : { code: foldCodeCoverage(emptyCodeCoverage(), take), codeTakenAt: input.now() }),
+    });
+    return {
+        levels: levelsOf(ledger),
+        unhandledWrites: ledger.writes.unhandled,
+        regressed: regressions(ledger),
+        ...(take === undefined && 0 === Object.keys(ledger.code).length ? { note: NO_CODE_NOTE } : {}),
+    };
+}

package/dist/features/exhaust/code-coverage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What of the app's own code ever ran, from the browser Reticle drives.
+ *
+ * Every other coverage number measures what Reticle already knew about — routes it reached, controls
+ * it listed. None can say what NEVER ran, including a branch no screen shows. V8 function coverage
+ * can, because it is counted against the app's source rather than against what the driving found.
+ *
+ * ponytail: FUNCTION coverage, keyed by name and start offset in the served (transformed) module.
+ * It needs no source maps and answers "did this handler ever run". Line coverage needs the source
+ * map of each module; add it when function granularity proves too coarse.
+ */
+/** One script as `page.coverage.stopJSCoverage()` reports it — only the fields read here. */
+export interface RawScriptCoverage {
+    url: string;
+    functions: readonly {
+        functionName: string;
+        ranges: readonly {
+            startOffset: number;
+            endOffset: number;
+            count: number;
+        }[];
+    }[];
+}
+/** Per file, per function key: its name and whether it ever ran. JSON-safe so it can persist. */
+export type CodeCoverage = Record<string, Record<string, {
+    name: string;
+    executed: boolean;
+}>>;
+export interface CodeSummary {
+    total: number;
+    executed: number;
+    files: {
+        file: string;
+        functions: number;
+        executed: number;
+        unexecuted: string[];
+    }[];
+}
+/** The repo-relative-looking path of an app script, or undefined for anything that is not the app. */
+export declare function appFileOf(url: string): string | undefined;
+export declare function emptyCodeCoverage(): CodeCoverage;
+/**
+ * Fold one take into the accumulated coverage. A union: a function that ran once stays run, so a
+ * reload or a later drive can only add to what is known.
+ */
+export declare function foldCodeCoverage(into: CodeCoverage, take: readonly RawScriptCoverage[]): CodeCoverage;
+export declare function summarizeCode(coverage: CodeCoverage): CodeSummary;

package/dist/features/exhaust/code-coverage.js

@@ -0,0 +1,77 @@
+/**
+ * What of the app's own code ever ran, from the browser Reticle drives.
+ *
+ * Every other coverage number measures what Reticle already knew about — routes it reached, controls
+ * it listed. None can say what NEVER ran, including a branch no screen shows. V8 function coverage
+ * can, because it is counted against the app's source rather than against what the driving found.
+ *
+ * ponytail: FUNCTION coverage, keyed by name and start offset in the served (transformed) module.
+ * It needs no source maps and answers "did this handler ever run". Line coverage needs the source
+ * map of each module; add it when function granularity proves too coarse.
+ */
+/** Path segments that are never the app under test. */
+// `dist`: built output is not source, and a monorepo serves Reticle's own SDK from it.
+const NOT_APP = /(?:^|\/)(?:node_modules|@vite|@id|@react-refresh|@reticlehq|\.vite|dist)(?:\/|$)/;
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/;
+/** The repo-relative-looking path of an app script, or undefined for anything that is not the app. */
+export function appFileOf(url) {
+    let path;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        return undefined;
+    }
+    if (NOT_APP.test(path) || !SOURCE_FILE.test(path))
+        return undefined;
+    return path.replace(/^\/+/, '');
+}
+export function emptyCodeCoverage() {
+    return {};
+}
+/**
+ * Fold one take into the accumulated coverage. A union: a function that ran once stays run, so a
+ * reload or a later drive can only add to what is known.
+ */
+export function foldCodeCoverage(into, take) {
+    const out = { ...into };
+    for (const script of take) {
+        const file = appFileOf(script.url);
+        if (file === undefined)
+            continue;
+        const fns = { ...(out[file] ?? {}) };
+        for (const f of script.functions) {
+            const first = f.ranges[0];
+            if (first === undefined)
+                continue;
+            // The module's own top-level body is reported as an anonymous function starting at 0. It
+            // always runs when the file loads, so counting it would inflate every file by one.
+            if ('' === f.functionName && 0 === first.startOffset)
+                continue;
+            const key = `${f.functionName}@${String(first.startOffset)}`;
+            const ran = first.count > 0 || true === fns[key]?.executed;
+            fns[key] = { name: '' === f.functionName ? '(anonymous)' : f.functionName, executed: ran };
+        }
+        out[file] = fns;
+    }
+    return out;
+}
+export function summarizeCode(coverage) {
+    const files = Object.entries(coverage)
+        .map(([file, fns]) => {
+        const list = Object.values(fns);
+        return {
+            file,
+            functions: list.length,
+            executed: list.filter((f) => f.executed).length,
+            unexecuted: list.filter((f) => !f.executed).map((f) => f.name),
+        };
+    })
+        .filter((f) => f.functions > 0)
+        .sort((a, b) => a.file.localeCompare(b.file));
+    return {
+        total: files.reduce((n, f) => n + f.functions, 0),
+        executed: files.reduce((n, f) => n + f.executed, 0),
+        files,
+    };
+}

package/dist/features/exhaust/exhaust-run.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `reticle_crawl { exhaustive: true }` — explore every reachable state, drive every write's failure
+ * path, take the code coverage, fold all of it into the ledger, and say what is left.
+ *
+ * It answers in crawl's own shape, so every caller that reads a crawl keeps working, and adds one
+ * `exhaustive` block with what only this mode knows.
+ */
+import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
+import { type RawScriptCoverage } from './code-coverage.js';
+import { type PortSession } from './session-port.js';
+/** Default action budget: generous, because every edge replays its path from a fresh load. */
+export declare const EXHAUST_DEFAULT_ACTIONS = 400;
+export declare function runExhaustive(input: {
+    sessions: {
+        get(id: string): PortSession | undefined;
+    };
+    session: PortSession;
+    startUrl: string;
+    maxActions: number;
+    settleMs: number;
+    /** What to type into a field, given the page it is on — a secret is only for its own origin. */
+    fillValue: (label: string, pageUrl: string) => string;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    setMocks?: (sessionUrl: string, rules: {
+        urlContains: string;
+        method?: string;
+        abort?: boolean;
+    }[]) => Promise<boolean>;
+    takeCode?: (sessionUrl: string) => Promise<readonly RawScriptCoverage[] | undefined>;
+    fs: FileSystemPort;
+    reticleRoot: string;
+}): Promise<Record<string, unknown>>;