decisium 0.0.0-stage → 0.1.2

package/dist/cassette.js

@@ -0,0 +1,298 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { capabilities, NotYet, PAGE, plausible } from "./decision.js";
+export const RECORD_MODES = ["none", "new", "all"];
+/** Replay-only mode and a Step whose recorded resolution is missing or no longer holds. */
+export class UiChanged extends Error {
+    reason; // for people
+    constructor(reason) { super(`UI_CHANGED: ${reason}`); this.reason = reason; }
+}
+/** Nearest ancestor with a name, e.g. `list "Issues"`; "" at the top. */
+const containerOf = (el) => {
+    for (let p = el.parent; p; p = p.parent)
+        if (p.name)
+            return `${p.role} "${p.name}"`;
+    return "";
+};
+const same = (el, r) => el.role === r.role && el.name === r.name && containerOf(el) === r.container;
+const NEAR_MAX = 200; // a longer text is kept as its start and a hash, so the cassette stays readable
+/** `el`'s and its ancestors' texts, closest first. */
+const texts = (el) => {
+    const out = [];
+    for (let p = el; p; p = p.parent) {
+        const t = p.text.trim().replace(/\s+/g, " ");
+        if (t)
+            out.push(t.length <= NEAR_MAX ? t : `${t.slice(0, 80)}… [${createHash("sha256").update(t).digest("hex").slice(0, 8)}]`);
+    }
+    return out;
+};
+export function resolve(el, among) {
+    const r = { role: el.role, name: el.name, container: containerOf(el) };
+    const peers = among.filter(e => e !== el && same(e, r));
+    if (!peers.length)
+        return r;
+    const near = texts(el).find(t => !peers.some(p => texts(p).includes(t)));
+    if (near)
+        return { ...r, near };
+    const all = among.filter(e => same(e, r));
+    return { ...r, nth: all.indexOf(el), of: all.length };
+}
+/** The element a Resolution names on this Observation, or why none does: exactly one must match all of it. */
+export function find(r, among) {
+    const peers = among.filter(e => same(e, r) && (r.near === undefined || texts(e).includes(r.near)));
+    if (r.of !== undefined && peers.length === r.of)
+        return peers[r.nth];
+    if (r.of === undefined && peers.length === 1)
+        return peers[0];
+    return `${describe(r)} matches ${peers.length} elements now, needs ${r.of ?? "exactly 1"}`;
+}
+export const describe = (t) => typeof t === "string" ? t
+    : `${t.role}${t.name ? ` "${t.name}"` : ""}${t.container ? ` in ${t.container}` : ""}${t.near ? ` near "${t.near}"` : ""}${t.of ? ` (#${t.nth + 1} of ${t.of} identical)` : ""}`;
+/** A live answer for the cassette: refs (looked up in `among`) become Resolutions. */
+const store = (p, among = []) => plausible(p).map(k => {
+    const el = among.find(e => e.ref === k);
+    return [el ? resolve(el, among) : k, p.probabilities[k]];
+});
+/** A Resolution that names no single element on this Observation: the only miss a later Observation can fix. */
+class NotOnPage {
+    why;
+    constructor(why) { this.why = why; }
+}
+/** A recorded answer on this Observation; throws NotOnPage when a Resolution no longer names exactly one element. */
+const load = (a, among = []) => {
+    const probabilities = Object.fromEntries(a.map(([t, v]) => {
+        if (typeof t === "string")
+            return [t, v];
+        const el = find(t, among);
+        if (typeof el === "string")
+            throw new NotOnPage(el);
+        return [el.ref, v];
+    }));
+    return { choice: Object.keys(probabilities)[0], probabilities };
+};
+/**
+ * A Step's cassette key: scenario and label, plus which occurrence of that label it is in the scenario, so adding or
+ * removing other Steps keeps every other key.
+ */
+export function stepKey(scenario, labels, i) {
+    const n = labels.slice(0, i).filter(l => l === labels[i]).length + 1;
+    return `${scenario}: ${labels[i]}${n > 1 ? ` (#${n})` : ""}`;
+}
+/** Recorded resolutions per Step, in `<test>.cassette.json`. Steps are keyed by scenario, text and occurrence (stepKey). */
+export class Cassette {
+    #file;
+    #dirty = false;
+    replayed = 0;
+    recorded = 0;
+    healed = 0;
+    path;
+    model;
+    mode;
+    #run;
+    /**
+     * `run`: id of this run. Parallel workers each open the feature's cassette; a file last saved by this run holds
+     * another worker's scenarios, so it is not stale for `all`.
+     */
+    constructor(path, model, mode, run) {
+        this.path = path;
+        this.model = model;
+        this.mode = mode;
+        this.#run = run;
+        const { file: old, thisRun } = this.#read();
+        this.#file = { model, run, entries: this.#keep(old, thisRun) ?? {} };
+        if (old && !this.#keep(old, thisRun) && mode !== "none")
+            this.#dirty = true; // replay-only never rewrites
+    }
+    #read() {
+        try {
+            if (!existsSync(this.path))
+                return { thisRun: false };
+            const file = JSON.parse(readFileSync(this.path, "utf8"));
+            return { file, thisRun: this.#run !== undefined && file.run === this.#run };
+        }
+        catch (err) {
+            throw new Error(`Cannot read cassette ${this.path}: ${err.message}. Delete it to record again.`);
+        }
+    }
+    /** Entries of a file on disk worth keeping: same model, and in `all` mode only those recorded in this run. */
+    #keep(file, thisRun) {
+        return file && file.model === this.model && (this.mode !== "all" || thisRun) ? file.entries : undefined;
+    }
+    /**
+     * The Decider for one Step: replays its recorded resolutions while each still matches exactly one element, else
+     * (from the first that does not) asks `live`. Call `done` when the Step ends.
+     */
+    step(key, live, log = () => { }) {
+        const old = this.mode === "all" ? undefined : this.#file.entries[key];
+        const now = {};
+        let broken; // why replay stopped
+        let turn = 0;
+        const replayOnly = this.mode === "none";
+        /** `wait`: replay-only waits for a loading page to show the element (NotYet); live mode just asks Jev, who can answer "wait". */
+        const fail = (why, wait = false) => {
+            if (replayOnly && old && wait)
+                throw new NotYet(new UiChanged(`the recorded resolution no longer holds: ${why}`));
+            if (replayOnly)
+                throw new UiChanged(old ? `the recorded resolution no longer holds: ${why}` : "this step has no recorded resolution: it is new or was reworded after the cassette was recorded, and replay-only mode does not call Jev");
+            if (old && !broken)
+                log(`  (cassette: healing, ${why})`);
+            broken ??= why;
+        };
+        /**
+         * Replay is the live question without Jev: a recorded answer is used only while the question would offer it now
+         * (`get` throws why not). Only an element not on the page yet is waited for; any other miss is final.
+         */
+        const replay = (get) => {
+            if (broken || !old) {
+                if (!broken)
+                    fail("missing");
+                return undefined;
+            }
+            try {
+                return get(old);
+            }
+            catch (why) {
+                if (why instanceof NotOnPage)
+                    fail(why.why, true);
+                else if (typeof why === "string")
+                    fail(why);
+                else
+                    throw why;
+                return undefined;
+            }
+        };
+        /** Actions the answer's top target can do now (none known: undefined); the runner reads only these. */
+        const can = (a, obs, keys) => {
+            const top = a.target.choice === PAGE ? PAGE : obs.elements.find(e => e.ref === a.target.choice);
+            return top ? capabilities(top, obs, keys) : undefined;
+        };
+        return {
+            turn: async (step, obs, recent, attempt, keys) => {
+                const i = turn; // advanced only once answered: a NotYet retries the same recorded turn
+                const r = replay(e => {
+                    const t = e.turns?.[i];
+                    if (!t)
+                        throw `recorded ${e.turns?.length ?? 0} turns, this is turn ${i + 1}`;
+                    if ("dialog" in t)
+                        throw `turn ${i + 1} answered a browser dialog when recorded`;
+                    const gone = t.target.find(([k]) => typeof k === "string" && k !== "none" && k !== PAGE);
+                    if (gone)
+                        throw `recorded answer "${gone[0]}" is not offered now`;
+                    const a = { done: t.done, target: load(t.target, obs.elements), action: t.action && load(t.action) };
+                    // The recorded action must still be one the recorded target can do (a key the Step names, Enter in a focused field).
+                    const ok = can(a, obs, keys ?? []);
+                    if (ok && a.action && !Object.keys(a.action.probabilities).some(k => ok.includes(k)))
+                        throw `recorded action "${a.action.choice}" is not offered now`;
+                    return a;
+                });
+                turn = i + 1;
+                const a = r ?? await live.turn(step, obs, recent, attempt, keys);
+                // Store the action restricted to what the target can do: Jev's top action may be one it cannot (task 0067).
+                const ok = can(a, obs, keys ?? []);
+                const action = a.action && ok ? { ...a.action, probabilities: Object.fromEntries(Object.entries(a.action.probabilities).filter(([k]) => ok.includes(k))) } : a.action;
+                (now.turns ??= [])[i] = { done: a.done, target: store(a.target, obs.elements), action: action && store(action) };
+                return a;
+            },
+            value: async (step, obs, el, candidates) => {
+                const i = turn - 1;
+                const r = replay(e => {
+                    const t = e.turns?.[i];
+                    const v = t && "value" in t ? t.value : undefined;
+                    const gone = v?.find(([k]) => k !== "none" && !candidates.includes(k));
+                    if (!v)
+                        throw "no recorded value";
+                    if (gone)
+                        throw `recorded value "${gone[0]}" is not offered now`;
+                    return load(v);
+                });
+                const a = r ?? await live.value(step, obs, el, candidates);
+                now.turns[i].value = store(a);
+                return a;
+            },
+            drop: async (step, obs, source) => {
+                const i = turn - 1;
+                const among = [...new Set([...obs.readable, ...obs.areas])];
+                const r = replay(e => {
+                    const t = e.turns?.[i];
+                    const d = t && "drop" in t ? t.drop : undefined;
+                    if (!d)
+                        throw "no recorded drop target";
+                    return load(d, among);
+                });
+                const a = r ?? await live.drop(step, obs, source);
+                now.turns[i].drop = store(a, among);
+                return a;
+            },
+            dialog: async (step, obs, answers) => {
+                const i = turn;
+                const r = replay(e => {
+                    const t = e.turns?.[i];
+                    if (!t || !("dialog" in t))
+                        throw `turn ${i + 1} did not answer a browser dialog when recorded`;
+                    const gone = t.dialog.find(([k]) => !answers.includes(k));
+                    if (gone)
+                        throw `recorded dialog answer "${gone[0]}" is not offered now`;
+                    return load(t.dialog);
+                });
+                turn = i + 1;
+                const a = r ?? await live.dialog(step, obs, answers);
+                (now.turns ??= [])[i] = { dialog: store(a) };
+                return a;
+            },
+            assess: async (step, obs, judged) => {
+                // A judged check is Jev's verdict, and verdicts are never stored.
+                if (judged) {
+                    broken ??= "judged";
+                    return live.assess(step, obs, judged);
+                }
+                const r = replay((e) => {
+                    if (!e.check)
+                        throw "no recorded check";
+                    return { kind: e.check.kind, state: e.check.state, subject: load(e.check.subject, obs.readable), area: load(e.check.area, obs.areas) };
+                });
+                const a = r ?? await live.assess(step, obs, judged);
+                now.check = { kind: a.kind, state: a.state, subject: store(a.subject, obs.readable), area: store(a.area, obs.areas) };
+                return a;
+            },
+            recall: async (step, earlier) => {
+                const r = replay(e => {
+                    if (!e.recall)
+                        throw "no recorded recall";
+                    const gone = e.recall.find(([k]) => k !== "none" && !(k in earlier));
+                    if (gone)
+                        throw `recorded earlier value "${gone[0]}" is not in this scenario now`;
+                    return load(e.recall);
+                });
+                const a = r ?? await live.recall(step, earlier);
+                now.recall = store(a);
+                return a;
+            },
+            /** `keep`: the Step reached an outcome from its answers (not an error), so they are written back. */
+            done: (keep) => {
+                if (!broken && old) {
+                    this.replayed++;
+                    return "replayed";
+                }
+                if (!keep || broken === "judged" || replayOnly)
+                    return; // replayOnly: a Step that asked Jev nothing ("I press Escape")
+                this.#file.entries[key] = now;
+                this.#dirty = true;
+                if (old) {
+                    this.healed++;
+                    log(`  (cassette: healed, written back)`);
+                    return "healed";
+                }
+                this.recorded++;
+                return "recorded";
+            },
+        };
+    }
+    save() {
+        if (!this.#dirty)
+            return;
+        const { file, thisRun } = this.#read(); // another worker may have saved scenarios of this feature since
+        this.#file.entries = { ...this.#keep(file, thisRun), ...this.#file.entries };
+        writeFileSync(this.path + ".tmp", JSON.stringify(this.#file, null, 2) + "\n");
+        renameSync(this.path + ".tmp", this.path); // atomic: a crash mid-save never leaves half a cassette
+    }
+}

package/dist/change.d.ts

@@ -0,0 +1,6 @@
+import type { Observation } from "./observation.ts";
+/**
+ * The changes from `before` to `after`, nearest to `acted` (the ref acted on in `before`) first, capped at 300
+ * characters; "no visible change" when there are none. Both Observations are already masked, so secrets stay masked.
+ */
+export declare function changes(before: Observation, after: Observation, acted?: string): string;

package/dist/change.js

@@ -0,0 +1,134 @@
+const MAX = 300;
+const PAGE = new Set(["url", "title", "tabs", "dialog", "download", "clipboard"]);
+const ITEMS = 5;
+/** Icon-font glyphs (private use) and zero-width characters print as nothing: `value "" -> ""` (OrangeHRM). */
+const clean = (s) => s.replace(/[\u200b-\u200d\ufeff\ue000-\uf8ff]/g, "").replace(/\s+/g, " ").trim();
+const short = (s, n = 40) => (s.length > n ? s.slice(0, n) + "…" : s);
+/** Containers (nodes with children): their value is their descendants' text, so it does not tell them apart. */
+const containers = new WeakSet();
+/** What tells a node apart: its name, or for a nameless one (a list item) its text. */
+const ident = (e) => clean(e.name) || (e.secret || containers.has(e) ? "" : clean(e.value));
+const label = (e) => `${e.role}${ident(e) ? ` "${short(ident(e))}"` : ""}`;
+const where = (e) => { let p = e.parent; while (p && !p.name)
+    p = p.parent; return p ? label(p) : "the page"; };
+/** Two long texts shown around where they first differ, so a clipped "A…" -> "A…" still says what changed. */
+function values(a, b) {
+    let i = 0;
+    while (i < a.length && a[i] === b[i])
+        i++;
+    const from = Math.max(0, i - 15);
+    const cut = (s) => `"${from ? "…" : ""}${short(s.slice(from), 40)}"`;
+    return `${cut(a)} -> ${cut(b)}`;
+}
+/** States that flip with focus and hover, not with what an action did. */
+const state = (e) => e.state.replace(/\s*\[(cursor=\w+|active)\]/g, "").trim();
+/** Nearest named ancestor: refs change between Observations, so nodes are matched by role, name and this. */
+const anc = (e) => { let p = e.parent; while (p && !p.name)
+    p = p.parent; return p ? `${p.role}|${p.name}` : ""; };
+/** Every node of `obs` once, in snapshot order (readable first: it holds the page pseudo-elements). */
+const all = (obs) => [...new Set([...obs.readable, ...obs.elements, ...obs.areas])];
+/** Nodes that can be told apart: unnamed, valueless wrappers only match by position and churn when a menu opens. */
+const told = (e) => !!(clean(e.name) || clean(e.value)) || e.role === "row" || e.role === "listitem";
+/** First text of a list item or table row, for a reorder entry. */
+const itemText = (e) => short(e.cells?.[0]?.name || e.cells?.[0]?.value || e.name || e.value || e.text.trim(), 20);
+/** Items (direct ref'd children) of each container, by the container's match key; rowgroups hold the rows. */
+function sequences(obs, keyOf) {
+    const out = new Map();
+    for (const e of all(obs))
+        if (e.parent && (e.role === "row" || e.role === "listitem")) {
+            const k = keyOf.get(e.parent);
+            out.set(k, [...out.get(k) ?? [], e]);
+        }
+    return out;
+}
+function keys(obs) {
+    for (const a of obs.areas)
+        containers.add(a);
+    const seen = new Map();
+    const keyOf = new Map();
+    for (const e of all(obs)) {
+        const base = `${e.role}|${ident(e)}|${anc(e)}`;
+        const n = seen.get(base) ?? 0;
+        seen.set(base, n + 1);
+        keyOf.set(e, `${base}#${n}`);
+    }
+    return keyOf;
+}
+/**
+ * The changes from `before` to `after`, nearest to `acted` (the ref acted on in `before`) first, capped at 300
+ * characters; "no visible change" when there are none. Both Observations are already masked, so secrets stay masked.
+ */
+export function changes(before, after, acted) {
+    const kb = keys(before), ka = keys(after);
+    const byKey = new Map([...kb].map(([e, k]) => [k, e]));
+    // `keys`: match keys of the entry's node and its ancestors; `text` of a container: dropped when an entry inside it says more.
+    const entries = [];
+    const chain = (e, keyOf) => { const out = []; for (let p = e; p; p = p.parent)
+        out.push(keyOf.get(p) ?? ""); return out; };
+    const order = all(after);
+    // The page's own pseudo-elements (url, title, ...) come first: a navigation is the strongest evidence.
+    const pos = (e) => (PAGE.has(e.ref) ? -Infinity : order.indexOf(e));
+    const matched = new Set();
+    for (const [e, k] of ka) {
+        const old = byKey.get(k);
+        if (!old || !told(e))
+            continue;
+        matched.add(old);
+        const what = [];
+        if (clean(old.value) !== clean(e.value))
+            what.push(`value ${values(clean(old.value), clean(e.value))}`);
+        if (state(old) !== state(e))
+            what.push(`${state(old) || "[no state]"} -> ${state(e) || "[no state]"}`);
+        // A container whose own state did not change only repeats what changed inside it (whole-page text, task 0066).
+        const container = containers.has(e) && state(old) === state(e) ? k : undefined;
+        if (what.length)
+            entries.push({ at: pos(e), text: `${label(e)} ${what.join(", ")}`, keys: chain(e, ka), container });
+    }
+    // Unmatched: the same node under another named ancestor moved (a drag between lists); a name change pairs by role,
+    // ancestor and position among the unmatched; the rest appeared or went.
+    const gone = [...kb.keys()].filter(e => told(e) && !matched.has(e));
+    const added = [...ka].filter(([e, k]) => told(e) && !byKey.has(k)).map(([e]) => e);
+    for (const e of added) {
+        const m = gone.findIndex(o => o.role === e.role && ident(o) === ident(e) && ident(e));
+        if (m >= 0) {
+            entries.push({ at: pos(e), text: `${label(e)} moved from ${where(gone.splice(m, 1)[0])} to ${where(e)}`, keys: chain(e, ka) });
+            continue;
+        }
+        const i = gone.findIndex(o => o.role === e.role && anc(o) === anc(e));
+        const old = i >= 0 ? gone.splice(i, 1)[0] : undefined;
+        entries.push({ at: pos(e), text: !old ? `appeared: ${label(e)}`
+                : clean(old.name) || clean(e.name) ? `${label(old)} -> "${short(ident(e))}"` : `${e.role} value ${values(ident(old), ident(e))}`, keys: chain(e, ka) });
+    }
+    // Placed where they were: a deleted file listed last read as an afterthought (task 0066: done 0.55 -> 0.95 first).
+    // The acted-on control and its siblings going away (a menu closing after its item was clicked) go last.
+    const old = all(before);
+    const acting = old.find(e => e.ref === acted);
+    for (const o of gone)
+        entries.push({ at: acting && (o === acting || o.parent === acting.parent) ? Infinity : old.indexOf(o), text: `gone: ${label(o)}`, keys: chain(o, kb), container: containers.has(o) ? kb.get(o) : undefined });
+    // Reordered rows or items: same items, other order.
+    const sb = sequences(before, kb), sa = sequences(after, ka);
+    for (const [k, items] of sa) {
+        const was = sb.get(k)?.map(itemText), now = items.map(itemText);
+        if (!was || was.join("\n") === now.join("\n") || [...was].sort().join("\n") !== [...now].sort().join("\n"))
+            continue;
+        const container = items[0].parent;
+        entries.push({ at: pos(container), text: `${label(container)} reordered: ${was.slice(0, ITEMS).join(", ")} -> ${now.slice(0, ITEMS).join(", ")}`, keys: chain(container, ka) });
+    }
+    const said = entries.filter(x => !x.container || !entries.some(y => y !== x && y.keys.slice(1).includes(x.container)));
+    entries.splice(0, entries.length, ...said);
+    if (!entries.length)
+        return "no visible change";
+    // shortcut: gone entries are placed by their index in `before`, the rest by `after`; close enough while most of
+    // the page stays, measure if a large insertion reorders entries badly.
+    const at = acting ? pos(order.find(e => ka.get(e) === kb.get(acting)) ?? acting) : -1;
+    const dist = (x) => (x === -Infinity ? -1 : at < 0 ? x : Math.abs(x - at));
+    entries.sort((a, b) => dist(a.at) - dist(b.at));
+    let out = "";
+    for (const { text } of entries) {
+        const next = out ? `${out}; ${text}` : text;
+        if (next.length > MAX)
+            return `changed: ${out}; …`;
+        out = next;
+    }
+    return `changed: ${out}`;
+}

package/dist/check.d.ts

@@ -0,0 +1,27 @@
+import { type Assessment, type Pick } from "./decision.ts";
+import { type Observation } from "./observation.ts";
+import type { StepOutcome } from "./runner.ts";
+export interface Expectation {
+    values: string[];
+    table?: string[][];
+    list?: boolean;
+    exact?: boolean;
+    recall?: Pick;
+}
+/**
+ * Whole-word, case/space-insensitive containment: "1 week" must not match "11 weeks". Only a neighbour of the same kind
+ * (letter next to letter, digit next to digit) joins words: snapshots drop line breaks ("1815<br>London" -> "1815London").
+ */
+export declare function containsValue(actual: string, expected: string): boolean;
+type Reading = {
+    outcome: StepOutcome;
+    reason?: string;
+    inapplicable?: true;
+    marginal?: string[];
+};
+export type Verdict = Reading & {
+    details: string[];
+};
+/** Pure Check verdict; diagnostics are returned for the runner to log, never emitted here. */
+export declare function verdict(a: Assessment, obs: Observation, expectation: Expectation): Verdict;
+export {};