@reticlehq/server 3.3.0 → 3.4.0

package/dist/features/exhaust/exhaust-run.js

@@ -0,0 +1,82 @@
+/**
+ * `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 { emptyCodeCoverage, foldCodeCoverage } from './code-coverage.js';
+import { explore } from './explorer.js';
+import { driveFailureBranches } from './failure-branches.js';
+import { LedgerStore, levelsOf, regressions } from './ledger.js';
+import { sessionPort } from './session-port.js';
+/** Default action budget: generous, because every edge replays its path from a fresh load. */
+export const EXHAUST_DEFAULT_ACTIONS = 400;
+/** The share of the budget kept back for failure paths, so exploring cannot starve them. */
+const FAILURE_SHARE = 0.25;
+export async function runExhaustive(input) {
+    const port = sessionPort({
+        sessions: input.sessions,
+        start: input.session,
+        startUrl: input.startUrl,
+        settleMs: input.settleMs,
+        now: input.now,
+        sleep: input.sleep,
+        ...(input.setMocks === undefined ? {} : { setMocks: input.setMocks }),
+    });
+    const failureBudget = Math.floor(input.maxActions * FAILURE_SHARE);
+    const report = await explore(port, {
+        maxActions: input.maxActions - failureBudget,
+        fillValue: (label) => input.fillValue(label, port.current().url),
+    });
+    const branches = await driveFailureBranches(port, report.writes, { maxActions: failureBudget });
+    const take = await input.takeCode?.(port.current().url);
+    const ledger = await new LedgerStore(input.fs, input.reticleRoot).merge({
+        routes: { reached: report.routes },
+        controls: { seen: report.seen, touched: report.touched },
+        writes: {
+            seen: report.writes.map((w) => w.key),
+            branched: branches.branched,
+            unhandled: branches.unhandled.map((u) => u.key),
+        },
+        ...(take === undefined
+            ? {}
+            : { code: foldCodeCoverage(emptyCodeCoverage(), take), codeTakenAt: input.now() }),
+    });
+    const anomalies = [
+        ...report.anomalies.map((a) => ({ kind: a.kind, ref: '', desc: a.control, detail: a.detail })),
+        ...branches.unhandled.map((u) => ({
+            kind: 'failure-unhandled',
+            ref: '',
+            desc: u.key,
+            detail: u.detail,
+        })),
+    ];
+    const counts = {};
+    for (const a of anomalies)
+        counts[a.kind] = (counts[a.kind] ?? 0) + 1;
+    return {
+        interactiveFound: report.seen.length,
+        stepsRun: report.actions,
+        anomalies,
+        counts,
+        visited: report.touched,
+        truncated: report.frontier > 0 || report.budgetExhausted,
+        exhaustive: {
+            states: report.states,
+            routes: report.routes,
+            frontier: report.frontier,
+            unreachable: report.unreachable,
+            budgetExhausted: report.budgetExhausted,
+            writes: report.writes.map((w) => w.key),
+            failureBranches: branches,
+            levels: levelsOf(ledger),
+            regressed: regressions(ledger),
+            ...(take === undefined
+                ? {
+                    codeNote: 'code coverage needs a browser Reticle drives (`reticle drive`, or RETICLE_CDP_URL)',
+                }
+                : {}),
+        },
+    };
+}

package/dist/features/exhaust/explorer.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The systematic explorer: every state the app can reach from its start page, breadth first.
+ *
+ * The crawl clicks what is on one page; the model-driven harness clicks what a model finds
+ * interesting. Neither can promise it did not skip something, and "don't skip anything" is the
+ * requirement. This walks the app's STATE GRAPH instead:
+ *
+ * - A state is a route plus the set of control names on it. An edge is one action. Values and
+ *   counts are left out on purpose (every keystroke, every added row would be a new state), so
+ *   states that differ only there are one state — see `frontier` for what that costs the report.
+ * - Every state is reached by a recorded PATH from a fresh start page, so returning to an
+ *   unexplored state is a replay, never a hope that "back" works.
+ * - Controls that differ only by a number — the rows of a table — are one control. It is covered
+ *   once, which is what keeps a 500-row page from eating the whole budget.
+ * - Text fields on a state are filled before its buttons are tried, so a submit is driven with
+ *   input rather than dismissed as dead because it refused an empty form.
+ *
+ * ponytail: breadth-first with a flat action budget, and every edge replays its path from a fresh
+ * load. That is O(states × path length), correct and slow; add prefix sharing if it proves too slow.
+ * A control that needs a choice (select, combobox) is not driven — it needs a value model.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+/** What the explorer needs from a driven page. The tool layer adapts a session to it. */
+export interface ExplorePort {
+    /** Load the start page fresh. False when it did not come back. */
+    reset(): Promise<boolean>;
+    /** The interactive tree and route of the page now. */
+    look(): Promise<{
+        tree: string;
+        route?: string;
+    }>;
+    /** Act on a control; the events are the ones this action caused. */
+    act(ref: string, action: 'click' | 'fill', value?: string): Promise<{
+        ok: boolean;
+        events: readonly ReticleEvent[];
+    }>;
+    /** Install network mocks ([] clears). Absent, or false, when no driven browser can. */
+    mock?: (rules: {
+        urlContains: string;
+        method?: string;
+        abort?: boolean;
+    }[]) => Promise<boolean>;
+}
+export interface Step {
+    key: string;
+    action: 'click' | 'fill';
+    value?: string;
+}
+export interface ExploredWrite {
+    key: string;
+    method: string;
+    /** A concrete path this write was seen at, for a mock to match. */
+    urlPath: string;
+    /** How to trigger it from a fresh start page: the last step is the action that fired it. */
+    path: Step[];
+    /** The state the write was fired from. */
+    beforeState: string;
+    /** The state the app reached when this write SUCCEEDED — what a failure must not look like. */
+    successState: string;
+}
+export interface ExploreReport {
+    states: number;
+    actions: number;
+    routes: string[];
+    seen: string[];
+    touched: string[];
+    writes: ExploredWrite[];
+    anomalies: {
+        kind: string;
+        control: string;
+        detail: string;
+    }[];
+    /**
+     * States found and never explored. Zero means every state the explorer could TELL APART was
+     * explored, not that every reachable state was: identity is the route plus the set of control
+     * names, so two states that differ only in field values, in how many of a control there are, or
+     * in behaviour behind the same controls are one state here and the second is never visited.
+     */
+    frontier: number;
+    /** States whose recorded path no longer replays — the app is not deterministic from its start. */
+    unreachable: number;
+    budgetExhausted: boolean;
+}
+interface Control {
+    ref: string;
+    key: string;
+    /** The field already holds a value — pre-filled credentials, a default. Typing over it breaks it. */
+    holdsValue: boolean;
+}
+export declare function controlsOf(tree: string): Control[];
+export declare function stateKey(route: string | undefined, controls: readonly Control[]): string;
+export declare function explore(port: ExplorePort, opts: {
+    maxActions: number;
+    fillValue: (label: string) => string;
+}): Promise<ExploreReport>;
+/**
+ * A fresh start page, then the path. False when a step's control is gone or refused. Every state
+ * is reached this way, which is what makes returning to one a replay rather than a hope.
+ */
+export declare function replayPath(port: ExplorePort, path: readonly Step[], act: (ref: string, action: 'click' | 'fill', value?: string) => Promise<{
+    ok: boolean;
+}>, spent: () => boolean): Promise<boolean>;
+export {};

package/dist/features/exhaust/explorer.js

@@ -0,0 +1,195 @@
+/**
+ * The systematic explorer: every state the app can reach from its start page, breadth first.
+ *
+ * The crawl clicks what is on one page; the model-driven harness clicks what a model finds
+ * interesting. Neither can promise it did not skip something, and "don't skip anything" is the
+ * requirement. This walks the app's STATE GRAPH instead:
+ *
+ * - A state is a route plus the set of control names on it. An edge is one action. Values and
+ *   counts are left out on purpose (every keystroke, every added row would be a new state), so
+ *   states that differ only there are one state — see `frontier` for what that costs the report.
+ * - Every state is reached by a recorded PATH from a fresh start page, so returning to an
+ *   unexplored state is a replay, never a hope that "back" works.
+ * - Controls that differ only by a number — the rows of a table — are one control. It is covered
+ *   once, which is what keeps a 500-row page from eating the whole budget.
+ * - Text fields on a state are filled before its buttons are tried, so a submit is driven with
+ *   input rather than dismissed as dead because it refused an empty form.
+ *
+ * ponytail: breadth-first with a flat action budget, and every edge replays its path from a fresh
+ * load. That is O(states × path length), correct and slow; add prefix sharing if it proves too slow.
+ * A control that needs a choice (select, combobox) is not driven — it needs a value model.
+ */
+import { asNumber, asString, isAbsenceDerived, isAdvisory, parseInteractive, } from '@reticlehq/core';
+import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
+import { controlKey, failedRequests, isConsoleError, writeKeyOf } from './session-fold.js';
+/** Roles that take typed input. */
+const TYPED = /^(?:textbox|searchbox|spinbutton)\b/;
+/** Roles that need a value model this explorer does not have, and are left alone. */
+const CHOOSER = /^(?:combobox|listbox|option|slider)\b/;
+const FAILED_STATUS = 400;
+/** A route without its query: `?__reticle_opened=1` and friends are not a different page. */
+const pathOf = (route) => route?.split('?')[0];
+export function controlsOf(tree) {
+    return parseInteractive(tree)
+        .filter((item) => item.ref.length > 0)
+        .map((item) => ({
+        ref: item.ref,
+        key: controlKey(item.desc),
+        holdsValue: /\[value="[^"]+"/.test(item.desc),
+    }));
+}
+export function stateKey(route, controls) {
+    return `${pathOf(route) ?? ''}|${[...new Set(controls.map((c) => c.key))].sort().join('\n')}`;
+}
+export async function explore(port, opts) {
+    let actions = 0;
+    let unreachable = 0;
+    const routes = new Set();
+    const seen = new Set();
+    const touched = new Set();
+    const writes = new Map();
+    const anomalies = [];
+    const explored = new Set();
+    const queued = new Set();
+    const queue = [{ path: [] }];
+    const spent = () => actions >= opts.maxActions;
+    const act = async (ref, action, value) => {
+        actions += 1;
+        return port.act(ref, action, value);
+    };
+    const goTo = (path) => replayPath(port, path, act, spent);
+    while (queue.length > 0 && !spent()) {
+        const node = queue.shift();
+        if (node === undefined)
+            break;
+        if (!(await goTo(node.path))) {
+            if (!spent())
+                unreachable += 1;
+            continue;
+        }
+        const here = await port.look();
+        const controls = controlsOf(here.tree);
+        const key = stateKey(here.route, controls);
+        if (explored.has(key))
+            continue;
+        explored.add(key);
+        const where = pathOf(here.route);
+        if (where !== undefined)
+            routes.add(where);
+        for (const c of controls)
+            seen.add(c.key);
+        // Only EMPTY fields. The first drive of the fixture typed placeholders over the login form's
+        // correct pre-filled credentials, got a 401, and never left the first page.
+        const typed = controls.filter((c) => TYPED.test(c.key) && !c.holdsValue);
+        const fills = typed.map((c) => ({
+            key: c.key,
+            action: 'fill',
+            value: opts.fillValue(c.key),
+        }));
+        // Fills first, then the targets: valid input can reveal the button that moves on (a Continue,
+        // a Submit), and a list drawn before the fill would never contain it.
+        const fillHere = async () => {
+            const before = controlsOf((await port.look()).tree);
+            for (const fill of fills) {
+                const field = before.find((c) => c.key === fill.key);
+                if (field !== undefined && !spent()) {
+                    await act(field.ref, 'fill', fill.value);
+                    touched.add(fill.key);
+                }
+            }
+            return 0 < fills.length ? controlsOf((await port.look()).tree) : before;
+        };
+        const ready = await fillHere();
+        for (const c of ready)
+            seen.add(c.key);
+        // Every control of THIS state, once. Not filtered by what other states touched: a "Save" on
+        // another screen is another control, and skipping it left reachable writes undriven.
+        const untried = [
+            ...new Set(ready.filter((c) => !TYPED.test(c.key) && !CHOOSER.test(c.key)).map((c) => c.key)),
+        ];
+        for (const [index, target] of untried.entries()) {
+            if (spent())
+                break;
+            // The first control is tried on the page already loaded and filled; every other one starts
+            // over from the recorded path, because the one before it may have changed or left this state.
+            if (index > 0 && !(await goTo(node.path)))
+                break;
+            const current = 0 === index ? ready : await fillHere();
+            const control = current.find((c) => c.key === target);
+            if (control === undefined || spent())
+                continue;
+            const result = await act(control.ref, 'click');
+            touched.add(target);
+            const path = [...node.path, ...fills, { key: target, action: 'click' }];
+            const after = await port.look();
+            const next = stateKey(after.route, controlsOf(after.tree));
+            noteWrites(result.events, path, key, next, writes);
+            noteAnomalies(result.events, target, anomalies);
+            if (!explored.has(next) && !queued.has(next)) {
+                queued.add(next);
+                queue.push({ path, key: next });
+            }
+        }
+    }
+    return {
+        states: explored.size,
+        actions,
+        routes: [...routes],
+        seen: [...seen],
+        touched: [...touched],
+        writes: [...writes.values()],
+        anomalies,
+        frontier: queue.filter((n) => n.key === undefined || !explored.has(n.key)).length,
+        unreachable,
+        budgetExhausted: spent(),
+    };
+}
+/**
+ * A fresh start page, then the path. False when a step's control is gone or refused. Every state
+ * is reached this way, which is what makes returning to one a replay rather than a hope.
+ */
+export async function replayPath(port, path, act, spent) {
+    if (!(await port.reset()))
+        return false;
+    for (const step of path) {
+        if (spent())
+            return false;
+        const target = controlsOf((await port.look()).tree).find((c) => c.key === step.key);
+        if (target === undefined)
+            return false;
+        if (!(await act(target.ref, step.action, step.value)).ok)
+            return false;
+    }
+    return true;
+}
+function noteWrites(events, path, beforeState, successState, writes) {
+    for (const event of events) {
+        const key = writeKeyOf(event);
+        if (key === undefined || writes.has(key))
+            continue;
+        const [method = '', urlPath = ''] = key.split(' ');
+        const url = event.data['url'];
+        const concrete = 'string' === typeof url ? new URL(url, 'http://localhost').pathname : urlPath;
+        writes.set(key, { key, method, urlPath: concrete, path, beforeState, successState });
+    }
+}
+function noteAnomalies(events, control, anomalies) {
+    const list = [...events];
+    for (const e of list.filter(isConsoleError))
+        anomalies.push({
+            kind: 'console-error',
+            control,
+            detail: asString(e.data['message']) ?? e.type,
+        });
+    for (const e of failedRequests(list, FAILED_STATUS))
+        anomalies.push({
+            kind: 'failed-request',
+            control,
+            detail: `${asString(e.data['method']) ?? ''} ${asString(e.data['url']) ?? ''} → ${String(asNumber(e.data['status']) ?? '')}`,
+        });
+    for (const c of findContradictions(list, { actionSince: 0 })) {
+        if (isAdvisory(c.kind) || isAbsenceDerived(c.kind))
+            continue;
+        anomalies.push({ kind: c.kind, control, detail: `${c.claim}, but ${c.counter}` });
+    }
+}

package/dist/features/exhaust/failure-branches.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `branched` level: every write the explorer found, driven down its FAILURE path.
+ *
+ * The happy path is the one every drive already takes. What a user meets when the server is down is
+ * the one nobody checks, and it is where "the toast said Saved" over a lost write lives.
+ *
+ * The break is an ABORT, not a fabricated 500 — see portal/input/network-mutation.ts: an app can read
+ * a 500 body as empty data and look fine, but no code path mistakes a request that never completed
+ * for a successful one.
+ *
+ * The oracle needs nothing app-specific: with the write failing, the app must NOT arrive at the state
+ * it reaches when the write succeeds. Arriving there is claiming success over a failure. A
+ * contradiction the engine observes in the window counts too.
+ */
+import { type ExplorePort, type ExploredWrite } from './explorer.js';
+export interface FailureBranches {
+    branched: string[];
+    unhandled: {
+        key: string;
+        detail: string;
+    }[];
+    /**
+     * Writes whose success changed nothing the explorer can see, so success and failure look the same
+     * and nothing can be concluded from where the app landed. Not a finding — a blind spot to check
+     * by hand, or to give the app a visible outcome.
+     */
+    indistinguishable: string[];
+    /** Why nothing was driven, when nothing could be. */
+    skipped?: string;
+}
+export declare function driveFailureBranches(port: ExplorePort, writes: readonly ExploredWrite[], opts: {
+    maxActions: number;
+}): Promise<FailureBranches>;

package/dist/features/exhaust/failure-branches.js

@@ -0,0 +1,92 @@
+/**
+ * The `branched` level: every write the explorer found, driven down its FAILURE path.
+ *
+ * The happy path is the one every drive already takes. What a user meets when the server is down is
+ * the one nobody checks, and it is where "the toast said Saved" over a lost write lives.
+ *
+ * The break is an ABORT, not a fabricated 500 — see portal/input/network-mutation.ts: an app can read
+ * a 500 body as empty data and look fine, but no code path mistakes a request that never completed
+ * for a successful one.
+ *
+ * The oracle needs nothing app-specific: with the write failing, the app must NOT arrive at the state
+ * it reaches when the write succeeds. Arriving there is claiming success over a failure. A
+ * contradiction the engine observes in the window counts too.
+ */
+import { EventType, asNumber, isAbsenceDerived, isAdvisory, } from '@reticlehq/core';
+import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
+import { controlsOf, replayPath, stateKey, } from './explorer.js';
+import { writeKeyOf } from './session-fold.js';
+const NO_MOCKS = 'failure paths need a driven browser to break a request in (`reticle drive`, or RETICLE_CDP_URL); none were driven, so none were proved';
+/** The target write, sent and never answered: an aborted request reports status 0. */
+function aborted(e, key) {
+    return (EventType.NET_REQUEST === e.type &&
+        writeKeyOf(e) === key &&
+        (0 === asNumber(e.data['status']) || e.data['error'] !== undefined));
+}
+export async function driveFailureBranches(port, writes, opts) {
+    const out = { branched: [], unhandled: [], indistinguishable: [] };
+    const mock = port.mock;
+    if (mock === undefined)
+        return { ...out, ...(0 < writes.length ? { skipped: NO_MOCKS } : {}) };
+    let actions = 0;
+    const spent = () => actions >= opts.maxActions;
+    const act = (ref, action, value) => {
+        actions += 1;
+        return port.act(ref, action, value);
+    };
+    for (const write of writes) {
+        if (spent())
+            break;
+        const last = write.path.at(-1);
+        if (last === undefined)
+            continue;
+        try {
+            // Everything up to the step that fires the write, THEN the break. Installed before the replay,
+            // the abort also broke any setup step sending the same request, and the replay died short of
+            // the action it existed to reach.
+            if (!(await replayPath(port, write.path.slice(0, -1), act, spent)))
+                continue;
+            if (!(await mock([{ urlContains: write.urlPath, method: write.method, abort: true }])))
+                return { ...out, skipped: NO_MOCKS };
+            const control = controlsOf((await port.look()).tree).find((c) => c.key === last.key);
+            if (control === undefined)
+                continue;
+            const result = await act(control.ref, last.action, last.value);
+            // Driven means the write was SENT and did not complete. An action that never dispatched, or a
+            // request the rule did not match, drove nothing — and judging where the app landed after a
+            // write that succeeded would accuse it of claiming success over a failure that never happened.
+            if (!result.ok || !result.events.some((e) => aborted(e, write.key)))
+                continue;
+            out.branched.push(write.key);
+            const after = await port.look();
+            const reached = stateKey(after.route, controlsOf(after.tree));
+            // The failure is OURS, so it is declared. Without that, the engine's "UI moved beside a failed
+            // request" rule cannot tell an app that swallowed the error from one that correctly RENDERED
+            // it, and every well-behaved error message read as a finding. A success signal fired over the
+            // failure still contradicts. Found by driving the fixture.
+            const contradiction = findContradictions([...result.events], {
+                actionSince: 0,
+                expectedFailures: [{ method: write.method, urlContains: write.urlPath }],
+            }).find((c) => !isAdvisory(c.kind) && !isAbsenceDerived(c.kind));
+            if (contradiction !== undefined)
+                out.unhandled.push({
+                    key: write.key,
+                    detail: `${contradiction.claim}, but ${contradiction.counter}`,
+                });
+            // Landing where success lands only ACCUSES when success visibly moved the app. A write whose
+            // success shows nothing looks identical failing, and the first version of this called that
+            // "claimed success" — found by driving the fixture, whose add-item panel claims nothing at all.
+            else if (write.successState === write.beforeState)
+                out.indistinguishable.push(write.key);
+            else if (reached === write.successState)
+                out.unhandled.push({
+                    key: write.key,
+                    detail: `with ${write.key} failing, the app arrived exactly where it goes when the write succeeds (${after.route ?? 'same page'}) — it claimed success over a failure`,
+                });
+        }
+        finally {
+            await mock([]);
+        }
+    }
+    return out;
+}