@reticlehq/server 3.9.0 → 3.10.0

package/dist/features/exhaust/edges/edge-drive.js

@@ -0,0 +1,364 @@
+/**
+ * Edge cases, driven: the inputs and the interaction orders the plain explorer never tries, run on
+ * the states it found, and judged by the checks in `invariants.ts`.
+ *
+ * The order is the order defects are found in. Controls whose click sent a write come first: a
+ * submit pressed twice and a double click on them, then a reload after their write. Edge-case
+ * values for each field come next, one round across every field before the next value of any field.
+ * Controls that only read come after, then the rest of the sequences, then cancel controls.
+ *
+ * Each probe replays its state from a fresh start page, so the budget buys whole probes in that
+ * order and the caller keeps it apart from exploration's. Deterministic: the same states, port and
+ * clock give the same probes in the same order.
+ */
+import { EdgeAction, EdgeInteraction, describeStep, edgeInputs, edgeInteractions, looksLikeSubmit, } from '../edge-cases.js';
+import { controlsOf, } from '../explorer.js';
+import { CrawlAnomalyKind } from '@reticlehq/core';
+import { isActivity } from '../session-fold.js';
+import { Invariant, samePage, checkDeterministic, checkReloadKeeps, checkRepeat, checkUndo, } from '../invariants.js';
+import { faultsOf, runEdge, shownVsSent } from './edge-run.js';
+/** Edge-case values per field. `edgeInputs` puts the most telling first. */
+export const VALUES_PER_FIELD = 6;
+/** A value shorter than this is found on almost any page, so its absence after a reload says nothing. */
+const MIN_KEPT_VALUE = 3;
+const CANCEL = /^button\s+"(?:cancel|close|undo|dismiss)\b/i;
+const FIELD_LINE = /^\s*-?\s*(?:textbox|searchbox|spinbutton|combobox)\b/;
+const SETTLE = { action: EdgeAction.SETTLE };
+const OK_MIN = 200;
+const OK_END = 300;
+const click = (key) => ({ action: EdgeAction.CLICK, key });
+/** Each control that sends a request or looks like a submit, once, on the first state it is on. */
+function targetsOf(surfaces) {
+    const seen = new Set();
+    const out = [];
+    for (const surface of surfaces) {
+        for (const control of surface.order) {
+            if (seen.has(control) || (!surface.requests.includes(control) && !looksLikeSubmit(control))) {
+                continue;
+            }
+            seen.add(control);
+            out.push({ surface, control, writes: surface.writes.includes(control) });
+        }
+    }
+    return out;
+}
+/** A field's spec from its control key and the attributes the page gave. */
+export function specOf(control, attrs = {}) {
+    const [, role = '', name] = /^(\S+)(?:\s+"([^"]*)")?/.exec(control) ?? [];
+    const count = (raw) => {
+        const n = Number(raw);
+        return raw === undefined || !Number.isInteger(n) ? undefined : n;
+    };
+    const optional = {
+        name,
+        type: attrs['type'],
+        inputMode: attrs['inputmode'],
+        min: attrs['min'],
+        max: attrs['max'],
+        pattern: attrs['pattern'],
+        maxLength: count(attrs['maxlength']),
+        minLength: count(attrs['minlength']),
+    };
+    const spec = { role, required: attrs['required'] !== undefined };
+    for (const [key, value] of Object.entries(optional)) {
+        if (value !== undefined) {
+            Object.assign(spec, { [key]: value });
+        }
+    }
+    return spec;
+}
+/** The writes in `twice` beyond those `once` sent: a second request to the same endpoint. */
+function extraWrites(twice, once) {
+    const left = [...once];
+    return twice.filter((w) => {
+        const index = left.findIndex((o) => o.key === w.key);
+        if (index < 0) {
+            return true;
+        }
+        left.splice(index, 1);
+        return false;
+    });
+}
+const shownOutsideFields = (page, value) => page.tree.split('\n').some((line) => !FIELD_LINE.test(line) && line.includes(value));
+/** Two pages are one view: the same route and the same controls, whatever the fields hold. */
+const sameView = (a, b) => {
+    const keys = (page) => [...new Set(controlsOf(page.tree).map((c) => c.key))].sort().join('\n');
+    return a.route === b.route && keys(a) === keys(b);
+};
+const sourceOf = (run) => run.source === undefined ? {} : { source: run.source };
+export async function driveEdges(port, surfaces, opts) {
+    let actions = 0;
+    let failed = 0;
+    const spent = () => actions >= opts.maxActions;
+    const known = new Set(opts.known ?? []);
+    const found = [];
+    const probed = new Set();
+    const driver = {
+        port,
+        act: (ref, action, value, actOpts) => {
+            actions += 1;
+            return port.act(ref, action, value, actOpts);
+        },
+        move: (action) => {
+            const move = EdgeAction.BACK === action ? port.back : port.reload;
+            if (move === undefined) {
+                return Promise.resolve(false);
+            }
+            actions += 1;
+            return move();
+        },
+        spent,
+        ...(opts.wait === undefined ? {} : { wait: opts.wait }),
+    };
+    const report = (control, findings) => {
+        for (const finding of findings) {
+            found.push({ control, finding });
+        }
+    };
+    /** Run, report the faults any run can show, and hand the run to `judge` for the rest. */
+    const probe = async (target, steps, shown, judge = () => []) => {
+        const run = await runEdge(driver, target.surface.path, steps);
+        if (run !== undefined) {
+            report(target.control, [
+                ...faultsOf(run, target.control, shown, known),
+                ...shownVsSent(run, shown),
+                ...judge(run),
+            ]);
+        }
+        return run;
+    };
+    const baselines = new Map();
+    /** The control pressed once after its fills, with a settle before the press. */
+    const baseline = async (t) => {
+        if (!baselines.has(t.control)) {
+            const steps = [...t.surface.fills, SETTLE, click(t.control)];
+            baselines.set(t.control, await probe(t, steps, [...t.surface.fills, click(t.control)]));
+        }
+        return baselines.get(t.control);
+    };
+    const sequence = (t, kind) => {
+        const seq = edgeInteractions({
+            control: t.control,
+            order: t.surface.order,
+            fills: t.surface.fills,
+        }).find((s) => s.kind === kind);
+        if (seq === undefined) {
+            return undefined;
+        }
+        // The two submit sequences place the fills themselves; every other one starts from a filled form.
+        const own = EdgeInteraction.SUBMIT_TWICE === kind || EdgeInteraction.SUBMIT_BEFORE_FILL === kind;
+        return own ? seq.steps : [...t.surface.fills, ...seq.steps];
+    };
+    const submitTwice = async (t) => {
+        const shown = sequence(t, EdgeInteraction.SUBMIT_TWICE);
+        if (shown === undefined) {
+            return false;
+        }
+        const fills = t.surface.fills.length;
+        const steps = [...shown.slice(0, fills), SETTLE, ...shown.slice(fills)];
+        const run = await probe(t, steps, shown, (r) => checkRepeat({
+            before: r.marks[0] ?? r.before,
+            afterFirst: r.marks[1] ?? r.after,
+            afterSecond: r.after,
+            firstWrites: r.writes[1] ?? [],
+            secondWrites: r.writes[2] ?? [],
+            steps: shown,
+            ...sourceOf(r),
+        }));
+        return run !== undefined;
+    };
+    /** Pressed back to back, against a run pressed once. Only writes the single press did not send count. */
+    const repeated = async (t, kind) => {
+        const shown = sequence(t, kind);
+        const once = await baseline(t);
+        if (shown === undefined || once === undefined) {
+            return false;
+        }
+        const fills = t.surface.fills.length;
+        const steps = [...shown.slice(0, fills), SETTLE, ...shown.slice(fills)];
+        const run = await probe(t, steps, shown, (r) => checkRepeat({
+            before: once.marks[0] ?? once.before,
+            afterFirst: once.after,
+            afterSecond: r.after,
+            firstWrites: once.writes[1] ?? [],
+            secondWrites: extraWrites(r.writes[1] ?? [], once.writes[1] ?? []),
+            steps: shown,
+            ...sourceOf(r),
+        }));
+        return run !== undefined;
+    };
+    /** A write, a settle, then a reload: every value the saved page showed must still be there. */
+    const reloadKeeps = async (t) => {
+        const shown = [...t.surface.fills, click(t.control)];
+        const steps = [...shown, SETTLE, { action: EdgeAction.RELOAD }];
+        const run = await probe(t, steps, shown, (r) => {
+            const saved = r.marks[0];
+            const ok = (r.writes[0] ?? []).some((w) => w.status !== undefined && w.status >= OK_MIN && w.status < OK_END);
+            // The reload must land on the view that showed the save. An app without deep links lands
+            // elsewhere, which loses the user's place, not the value, and the value cannot be looked for.
+            if (saved === undefined || !ok || !sameView(saved, r.after)) {
+                return [];
+            }
+            return t.surface.fills.flatMap((fill) => {
+                const value = (fill.value ?? '').trim();
+                if (value.length < MIN_KEPT_VALUE || !shownOutsideFields(saved, value)) {
+                    return [];
+                }
+                return checkReloadKeeps({ value, afterReload: r.after, steps: shown, ...sourceOf(r) });
+            });
+        });
+        return run !== undefined;
+    };
+    const deterministic = async (t) => {
+        const once = await baseline(t);
+        if (once === undefined) {
+            return false;
+        }
+        const shown = [...t.surface.fills, click(t.control)];
+        const run = await probe(t, [...t.surface.fills, SETTLE, click(t.control)], shown, (r) => checkDeterministic({ first: once.after, second: r.after, steps: shown, ...sourceOf(r) }));
+        return run !== undefined;
+    };
+    const plain = async (t, kind) => {
+        const steps = sequence(t, kind);
+        return steps !== undefined && (await probe(t, steps, steps)) !== undefined;
+    };
+    /** One edge value in one field, the other fields as the explorer filled them, then the submit. */
+    const edgeInput = async (surface, submit, field, value) => {
+        const fill = { key: field, action: EdgeAction.FILL, value };
+        // A pre-filled field is not among the explorer's fills: it gets its fill after them.
+        const fills = surface.fills.some((f) => f.key === field)
+            ? surface.fills.map((f) => (f.key === field ? fill : f))
+            : [...surface.fills, fill];
+        const steps = [...fills, click(submit)];
+        return (await probe({ surface, control: field }, steps, steps)) !== undefined;
+    };
+    /**
+     * A control the explorer saw do nothing, pressed again. Dead only when this press shows no
+     * activity either and the whole page, text included, is the same before and after it.
+     */
+    const dead = async (surface, control) => {
+        const steps = [...surface.fills, click(control)];
+        const run = await runEdge(driver, surface.path, steps);
+        if (run === undefined) {
+            return false;
+        }
+        if (!run.events.some(isActivity) && samePage(run.before, run.after)) {
+            report(control, [
+                {
+                    kind: CrawlAnomalyKind.DEAD_CONTROL,
+                    invariant: Invariant.RESPONDS,
+                    detail: 'pressed twice, from a fresh page each time, and the app did nothing: no request, no page change, no route change',
+                    sequence: steps.map(describeStep),
+                    ...(run.source === undefined
+                        ? {}
+                        : { source: `${run.source.file}:${String(run.source.line)}` }),
+                },
+            ]);
+        }
+        return true;
+    };
+    /** A cancel on a dialog: the page after it must be the page before the dialog opened. */
+    const undo = async (surface, cancel) => {
+        const open = surface.path.at(-1);
+        if (open === undefined || EdgeAction.CLICK !== open.action) {
+            return false;
+        }
+        const shown = [click(open.key), click(cancel)];
+        const run = await runEdge(driver, surface.path.slice(0, -1), [
+            click(open.key),
+            SETTLE,
+            click(cancel),
+        ]);
+        if (run === undefined) {
+            return false;
+        }
+        // Only a dialog: a cancel that leaves for another page loads it fresh, and a fresh page is
+        // not the page the user left.
+        if (run.marks[0]?.route === run.before.route) {
+            report(cancel, checkUndo({ before: run.before, after: run.after, steps: shown, ...sourceOf(run) }));
+        }
+        report(cancel, faultsOf(run, cancel, shown, known));
+        return true;
+    };
+    const targets = targetsOf(surfaces);
+    const writers = targets.filter((t) => t.writes);
+    const readers = targets.filter((t) => !t.writes);
+    const probes = [];
+    const add = (control, run) => {
+        probes.push({ control, run });
+    };
+    // Every control that writes gets one probe before any gets a second: a double press first, which
+    // also sends the write once to compare with.
+    for (const t of writers) {
+        add(t.control, () => repeated(t, EdgeInteraction.DOUBLE_ACTIVATION));
+    }
+    for (const surface of surfaces) {
+        for (const control of surface.inert) {
+            add(control, () => dead(surface, control));
+        }
+    }
+    for (const t of writers) {
+        add(t.control, () => submitTwice(t));
+    }
+    for (const t of writers) {
+        add(t.control, () => reloadKeeps(t));
+    }
+    const inputs = surfaces.flatMap((surface) => {
+        const submit = surface.writes[0] ?? surface.requests[0] ?? surface.order.find((c) => looksLikeSubmit(c));
+        if (submit === undefined) {
+            return [];
+        }
+        return surface.fields.map((field) => ({
+            surface,
+            submit,
+            field,
+            values: edgeInputs(specOf(field, surface.attrs[field]), {
+                now: opts.now,
+                max: VALUES_PER_FIELD,
+            }),
+        }));
+    });
+    for (let round = 0; round < VALUES_PER_FIELD; round += 1) {
+        for (const i of inputs) {
+            const edge = i.values[round];
+            if (edge !== undefined) {
+                add(i.field, () => edgeInput(i.surface, i.submit, i.field, edge.value));
+            }
+        }
+    }
+    for (const t of readers) {
+        add(t.control, () => repeated(t, EdgeInteraction.DOUBLE_ACTIVATION));
+        add(t.control, () => deterministic(t));
+    }
+    for (const t of targets) {
+        add(t.control, () => repeated(t, EdgeInteraction.RAPID_REPEAT));
+        add(t.control, () => plain(t, EdgeInteraction.ACT_THEN_BACK));
+        add(t.control, () => plain(t, EdgeInteraction.SUBMIT_BEFORE_FILL));
+        add(t.control, () => plain(t, EdgeInteraction.OUT_OF_ORDER));
+    }
+    for (const surface of surfaces) {
+        for (const cancel of surface.order.filter((c) => CANCEL.test(c))) {
+            add(cancel, () => undo(surface, cancel));
+        }
+    }
+    for (const p of probes) {
+        if (spent()) {
+            break;
+        }
+        try {
+            if (await p.run()) {
+                probed.add(p.control);
+            }
+        }
+        catch {
+            failed += 1;
+        }
+    }
+    return {
+        probed: [...probed],
+        found,
+        actions,
+        budgetExhausted: spent(),
+        failed,
+    };
+}

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

@@ -0,0 +1,59 @@
+/**
+ * One edge sequence, driven, and what its run shows without a reference answer.
+ *
+ * `runEdge` replays a state from a fresh start page, runs the steps, and reads what the checks in
+ * `invariants.ts` compare: the page before the steps, the page at each settle, the page at the end,
+ * and the writes of each stretch between settles. Two steps with no settle between them run back
+ * to back, which is how a double click reaches the app before the first click's request comes back.
+ *
+ * `faultsOf` and `shownVsSent` judge any run. A fault the plain click of the same control already
+ * showed is the explorer's finding, not an edge case's, so the caller passes it in `known`.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+import { EdgeAction, type EdgeStep } from '../edge-cases.js';
+import { type ActResult, type ExplorePort, type Step } from '../explorer.js';
+import { type PageObservation, type WriteObservation } from '../invariants.js';
+import type { BehaviourFinding } from '../ledger.js';
+export interface EdgeRun {
+    /** The page after the state was replayed, before the first step. */
+    before: PageObservation;
+    /** The page at each settle step, in order. */
+    marks: PageObservation[];
+    /** The page after the last step. */
+    after: PageObservation;
+    /** The writes of each stretch between settle steps. */
+    writes: WriteObservation[][];
+    /** Every event the steps caused. */
+    events: ReticleEvent[];
+    /** The source of the first control the run acted on, when the app gives it. */
+    source?: {
+        file: string;
+        line: number;
+    };
+}
+/** The port, with the budget the caller counts. */
+export interface EdgeDriver {
+    port: ExplorePort;
+    act: (ref: string, action: 'click' | 'fill', value?: string, opts?: {
+        settle?: boolean;
+    }) => Promise<ActResult>;
+    /** Back or reload, counted as one action. */
+    move: (action: typeof EdgeAction.BACK | typeof EdgeAction.RELOAD) => Promise<boolean>;
+    spent: () => boolean;
+    wait?: () => Promise<void>;
+}
+/** Replay `path`, then run `steps`. Undefined when the state or a step's control was not there. */
+export declare function runEdge(d: EdgeDriver, path: readonly Step[], steps: readonly EdgeStep[]): Promise<EdgeRun | undefined>;
+/**
+ * The faults the run's events show: page errors, server errors and contradictions. A fault already
+ * in `known` (as `control\nkind`) is skipped, and each new one is added, so it is reported once.
+ */
+export declare function faultsOf(run: EdgeRun, control: string, steps: readonly EdgeStep[], known: Set<string>): BehaviourFinding[];
+/** The value a field shows on a page, when the field is there and shows one. */
+export declare function shownValue(page: PageObservation, field: string): string | undefined;
+/**
+ * For each field the steps filled: when a write sent a value under the field's name, the field
+ * must show that value after the write. Matched by name only.
+ * ponytail: top-level JSON keys only; a nested or form-encoded body is not read.
+ */
+export declare function shownVsSent(run: EdgeRun, steps: readonly EdgeStep[]): BehaviourFinding[];

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

@@ -0,0 +1,169 @@
+/**
+ * One edge sequence, driven, and what its run shows without a reference answer.
+ *
+ * `runEdge` replays a state from a fresh start page, runs the steps, and reads what the checks in
+ * `invariants.ts` compare: the page before the steps, the page at each settle, the page at the end,
+ * and the writes of each stretch between settles. Two steps with no settle between them run back
+ * to back, which is how a double click reaches the app before the first click's request comes back.
+ *
+ * `faultsOf` and `shownVsSent` judge any run. A fault the plain click of the same control already
+ * showed is the explorer's finding, not an edge case's, so the caller passes it in `known`.
+ */
+import { REDACTED_VALUE, asNumber, asString } from '@reticlehq/core';
+import { EdgeAction, describeStep } from '../edge-cases.js';
+import { controlsOf, noteAnomalies, replayPath, } from '../explorer.js';
+import { Invariant, checkShownMatchesSent, } from '../invariants.js';
+import { controlKey, writeKeyOf } from '../session-fold.js';
+/** A server error is a fault whatever the input was. A 4xx is the server refusing bad input. */
+const SERVER_FAULT = 500;
+const VALUE_ATTR = /\[value="((?:[^"\\]|\\.)*)"/;
+/** Letters and digits only, lower case: `First name` and `firstName` are one name. */
+const bare = (name) => name.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+const writesOf = (events) => events.flatMap((e) => {
+    const key = writeKeyOf(e);
+    if (key === undefined) {
+        return [];
+    }
+    const status = asNumber(e.data['status']);
+    const response = asString(e.data['responseBody']);
+    return [
+        {
+            key,
+            ...(status === undefined ? {} : { status }),
+            ...(response === undefined ? {} : { response }),
+        },
+    ];
+});
+/** Replay `path`, then run `steps`. Undefined when the state or a step's control was not there. */
+export async function runEdge(d, path, steps) {
+    if (!(await replayPath(d.port, path, d.act, d.spent))) {
+        return undefined;
+    }
+    const read = () => (d.port.lookFull ?? d.port.look)();
+    const before = await read();
+    let controls = controlsOf((await d.port.look()).tree);
+    const marks = [];
+    const stretches = [[]];
+    let source;
+    for (const [index, step] of steps.entries()) {
+        if (d.spent()) {
+            return undefined;
+        }
+        if ('key' in step) {
+            const control = controls.find((c) => c.key === step.key);
+            if (control === undefined) {
+                return undefined;
+            }
+            const next = steps[index + 1];
+            const settle = next === undefined || EdgeAction.SETTLE === next.action;
+            const result = await d.act(control.ref, step.action, step.value, { settle });
+            source ??= result.source;
+            stretches.at(-1)?.push(...result.events);
+        }
+        else if (EdgeAction.SETTLE === step.action) {
+            await d.wait?.();
+            marks.push(await read());
+            controls = controlsOf((await d.port.look()).tree);
+            stretches.push([]);
+        }
+        else {
+            if (!(await d.move(step.action))) {
+                return undefined;
+            }
+            controls = controlsOf((await d.port.look()).tree);
+        }
+    }
+    await d.wait?.();
+    const after = await read();
+    return {
+        before,
+        marks,
+        after,
+        writes: stretches.map(writesOf),
+        events: stretches.flat(),
+        ...(source === undefined ? {} : { source }),
+    };
+}
+const findingFrom = (kind, detail, steps, source) => ({
+    kind,
+    invariant: Invariant.NO_FAULT,
+    detail,
+    sequence: steps.map(describeStep),
+    ...(source === undefined ? {} : { source: `${source.file}:${String(source.line)}` }),
+});
+/**
+ * The faults the run's events show: page errors, server errors and contradictions. A fault already
+ * in `known` (as `control\nkind`) is skipped, and each new one is added, so it is reported once.
+ */
+export function faultsOf(run, control, steps, known) {
+    const anomalies = [];
+    noteAnomalies(run.events, control, anomalies, SERVER_FAULT);
+    const out = [];
+    for (const a of anomalies) {
+        const id = `${control}\n${a.kind}`;
+        if (!known.has(id)) {
+            known.add(id);
+            out.push(findingFrom(a.kind, a.detail, steps, run.source));
+        }
+    }
+    return out;
+}
+/** The value a field shows on a page, when the field is there and shows one. */
+export function shownValue(page, field) {
+    for (const line of page.tree.split('\n')) {
+        if (controlKey(line) === field) {
+            return VALUE_ATTR.exec(line)?.[1];
+        }
+    }
+    return undefined;
+}
+/** The top-level values of a JSON object body, by bare name. Empty for any other body. */
+function bodyValues(event) {
+    const out = new Map();
+    const text = asString(event.data['requestBody']);
+    if (text === undefined) {
+        return out;
+    }
+    try {
+        const body = JSON.parse(text);
+        if ('object' !== typeof body || null === body || Array.isArray(body)) {
+            return out;
+        }
+        for (const [key, value] of Object.entries(body)) {
+            if ('string' === typeof value || 'number' === typeof value) {
+                out.set(bare(key), String(value));
+            }
+        }
+    }
+    catch {
+        return out;
+    }
+    return out;
+}
+/**
+ * For each field the steps filled: when a write sent a value under the field's name, the field
+ * must show that value after the write. Matched by name only.
+ * ponytail: top-level JSON keys only; a nested or form-encoded body is not read.
+ */
+export function shownVsSent(run, steps) {
+    const sent = run.events.filter((e) => writeKeyOf(e) !== undefined).map(bodyValues);
+    const out = [];
+    for (const step of steps) {
+        if (!('key' in step) || EdgeAction.FILL !== step.action) {
+            continue;
+        }
+        const name = bare(/"([^"]*)"/.exec(step.key)?.[1] ?? '');
+        const value = sent.map((body) => body.get(name)).find((v) => v !== undefined);
+        if (0 === name.length || value === undefined || REDACTED_VALUE === value) {
+            continue;
+        }
+        out.push(...checkShownMatchesSent({
+            field: step.key,
+            sent: value,
+            shown: shownValue(run.after, step.key),
+            steps,
+            ...(run.source === undefined ? {} : { source: run.source }),
+        }));
+    }
+    return out;
+}