sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/host.js

@@ -0,0 +1,423 @@
+// What a run (and the spec fixture) knows of its scripts: a record of
+// what they reported and did in its tabs, a copy of their stored
+// values, and their menu commands. The extension runs the scripts;
+// `ExtensionHost` (extension-host.ts) fills this from its events, and
+// the run's commands, waits and output read it.
+//
+// - Every record remembers the page (tab) it came from, kept off the
+//   records themselves so they stay plain data a test can compare.
+// - Menu commands belong to a page's current document: a new document
+//   registers its own.
+// - A script's values here are a copy, kept up to date from the
+//   extension's events, for reads that can't wait on a round trip.
+import { EventEmitter } from 'node:events';
+import { WRAPPER_GM_RUNTIME } from '../generated-wrappers.js';
+import { CHANNEL_KEY_PLACEHOLDER } from '../channel-placeholder.js';
+import { NO_RULE_COVERS_URL, explainMatch, preparedNoframes, preparedScriptName } from './prepare.js';
+import { FrameIds } from './frames.js';
+// The runtime's own stored-value codec, loaded once under Node the way
+// the unit tests do, so a test reading `GM_setValue` output gets the
+// value the script stored rather than its wire envelope.
+let codec = null;
+export function valueCodec() {
+    if (codec)
+        return codec;
+    const window = Object.create(globalThis);
+    window.addEventListener = () => { };
+    const document = { visibilityState: 'visible' };
+    new Function('window', 'document', WRAPPER_GM_RUNTIME)(window, document);
+    // The runtime puts itself in the registry its gate hands out; loaded
+    // as is, its key is the placeholder.
+    const gate = document.__smGate;
+    codec = gate(CHANNEL_KEY_PLACEHOLDER).gm.storage;
+    return codec;
+}
+// Abstract: the actions on the page go through whatever runs the
+// scripts (`ExtensionHost`).
+export class HarnessHost extends EventEmitter {
+    scripts = new Map();
+    // Which watched pages hold each script. A script stays known while
+    // any page still has it.
+    owners = new Map();
+    // scriptId -> key -> value in wire form, as the extension stores it.
+    values = new Map();
+    // Which page each record came from, for telling tabs apart.
+    recordPages = new WeakMap();
+    // `untilReported`'s waits, checked on each start, skip and error.
+    // Not emitter listeners: `reload all` over many tabs would pass
+    // Node's listener limit, which prints a warning.
+    reportWaiters = new Set();
+    reports = {
+        started: [], errors: [], skipped: [], manual: [], requests: [], tabs: [], menuCommands: [], notifications: [], downloads: [],
+        connectPrompts: [],
+    };
+    // The manual scripts that match each page's current document, which
+    // can be run there.
+    manualByPage = new Map();
+    // Each menu command's page; dropped when that page loads a new
+    // document or goes away.
+    menuOwners = new Map();
+    /** The run's frame ids (`F3`), across all its tabs. */
+    frameIds = new FrameIds();
+    /** Register a prepared script as running in `owner`'s tab. */
+    addScript(prepared, owner) {
+        if (!prepared.id)
+            throw new Error(`Cannot host an invalid script: ${prepared.diagnostic}`);
+        const id = prepared.id;
+        this.scripts.set(id, prepared);
+        let set = this.owners.get(id);
+        if (!set) {
+            set = new Set();
+            this.owners.set(id, set);
+        }
+        set.add(owner);
+        if (!this.values.has(id))
+            this.values.set(id, new Map());
+    }
+    /** `owner` no longer has the script; forget it once nobody does. */
+    removeScript(scriptId, owner) {
+        const set = this.owners.get(scriptId);
+        if (!set)
+            return;
+        set.delete(owner);
+        if (set.size > 0)
+            return;
+        this.owners.delete(scriptId);
+        this.scripts.delete(scriptId);
+    }
+    hasScript(scriptId) {
+        return this.scripts.has(scriptId);
+    }
+    /**
+     * Whether a script is running in a page's current top-frame document:
+     * its last word from there is a start rather than a skip. For its
+     * iframes, see `frameRuns`.
+     */
+    isRunning(page, scriptId) {
+        const { started, skipped } = this.lastStartAndSkip(page, scriptId);
+        return started !== undefined && (!skipped || started.at >= skipped.at);
+    }
+    /**
+     * Whether the scripts' manager reports their starts, skips and
+     * errors. Another manager than SourceMonkey doesn't.
+     */
+    get getsReports() {
+        return true;
+    }
+    /**
+     * Of `scriptIds`, the ones with no word from `page` since `since`:
+     * not yet started, skipped or thrown there, nor waiting to be run.
+     */
+    unreported(page, scriptIds, since) {
+        // Nothing to wait for from a manager that never reports.
+        if (!this.getsReports)
+            return [];
+        const { started, skipped, errors, manual } = this.reports;
+        const reported = (id) => [started, skipped, errors, manual]
+            .some((records) => records.some((r) => r.scriptId === id && r.at >= since && this.recordPages.get(r) === page));
+        return scriptIds.filter((id) => !reported(id));
+    }
+    /**
+     * Resolves once each of `scriptIds` has had its word from `page`
+     * since `since` (see `unreported`). Every script the extension runs
+     * in a new document gives one, so this is when a load's scripts are
+     * done starting. Never rejects. Stops waiting, unresolved, on
+     * `signal`, for a page that goes away first.
+     */
+    untilReported(page, scriptIds, since, signal) {
+        if (this.unreported(page, scriptIds, since).length === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            if (signal?.aborted)
+                return;
+            const stop = () => {
+                this.reportWaiters.delete(check);
+                signal?.removeEventListener('abort', stop);
+            };
+            const check = () => {
+                if (this.unreported(page, scriptIds, since).length > 0)
+                    return;
+                stop();
+                resolve();
+            };
+            this.reportWaiters.add(check);
+            signal?.addEventListener('abort', stop);
+        });
+    }
+    /** A script's latest start and latest skip from one page's top frame. */
+    lastStartAndSkip(page, scriptId) {
+        const mine = (records) => records.filter((r) => r.scriptId === scriptId && !r.frame && this.recordPages.get(r) === page).at(-1);
+        return { started: mine(this.reports.started), skipped: mine(this.reports.skipped) };
+    }
+    /**
+     * The scripts running in each iframe document of a page that reported
+     * any, by the extension's document id: those whose last word from
+     * there is a start. Documents since gone are included; the caller
+     * knows which are live (`liveFrameDocuments`).
+     */
+    frameRuns(page) {
+        const last = new Map();
+        const words = [
+            ...this.reports.started.map((r) => ({ r, running: true })),
+            ...this.reports.skipped.map((r) => ({ r, running: false })),
+        ].filter(({ r }) => r.frame && r.documentId && this.recordPages.get(r) === page)
+            .sort((a, b) => a.r.at - b.r.at);
+        for (const { r, running } of words) {
+            let scripts = last.get(r.documentId);
+            if (!scripts)
+                last.set(r.documentId, scripts = new Map());
+            scripts.set(r.scriptId, running);
+        }
+        return new Map([...last].map(([doc, scripts]) => [doc, new Set([...scripts].filter(([, on]) => on).map(([id]) => id))]));
+    }
+    /**
+     * Whether a script started in any iframe document of a page since
+     * `since` (when its top document began), and wasn't skipped there
+     * after. Documents since gone count too: for picking the tabs to
+     * reload, one too many is better than one missed.
+     */
+    ranInFrames(page, scriptId, since) {
+        const started = new Set(this.reports.started
+            .filter((r) => r.frame && r.documentId && r.scriptId === scriptId && r.at >= since && this.recordPages.get(r) === page)
+            .map((r) => r.documentId));
+        return [...started].some((doc) => this.frameRuns(page).get(doc)?.has(scriptId));
+    }
+    /**
+     * A page's live iframe documents, by the extension's id, each with
+     * its Playwright frame. Null where the manager can't say; throws when
+     * the extension is too old to report on frames.
+     */
+    async liveFrameDocuments(_page) {
+        return null;
+    }
+    /** The page a record in `reports` came from, if it is still known. */
+    pageOf(record) {
+        return this.recordPages.get(record);
+    }
+    scriptIds() {
+        return [...this.scripts.keys()];
+    }
+    /**
+     * The ids of the scripts whose rules match `url`; in an iframe
+     * (`inFrame`), leaving out those `@noframes` keeps to the top frame.
+     */
+    scriptsFor(url, inFrame) {
+        return [...this.scripts].filter(([, s]) => explainMatch(s.matching, url).matches && !(inFrame && preparedNoframes(s))).map(([id]) => id);
+    }
+    /** A watched page went away. */
+    detachPage(page) {
+        this.forgetDocumentState(page);
+    }
+    /**
+     * The manual scripts that can be run in `page`'s current document, at
+     * its URL now: one the page moved away from in place (pushState) can't.
+     */
+    manualScripts(page) {
+        const url = page.url();
+        return [...this.manualByPage.get(page) ?? []].filter((id) => {
+            const script = this.scripts.get(id);
+            return script !== undefined && explainMatch(script.matching, url).matches;
+        });
+    }
+    // What belongs to one document of a page: its menu commands, which a
+    // new document registers again, and the manual scripts it matches.
+    forgetDocumentState(page) {
+        this.manualByPage.delete(page);
+        for (const [record, owner] of this.menuOwners) {
+            if (owner !== page)
+                continue;
+            this.menuOwners.delete(record);
+            const i = this.reports.menuCommands.indexOf(record);
+            if (i >= 0)
+                this.reports.menuCommands.splice(i, 1);
+        }
+    }
+    // ---------- Stored values ----------
+    /**
+     * Values written by the run or the test, as another tab of the script
+     * would. Here only the host's copy; `ExtensionHost` writes them into
+     * the extension too.
+     */
+    async setValues(scriptId, values) {
+        const { encodeValue } = valueCodec();
+        this.applyWrites(scriptId, Object.entries(values).map(([key, v]) => (v === undefined ? { key, deleted: true } : { key, value: encodeValue(v) })));
+    }
+    /** Every value a script has stored, decoded, from the host's copy. */
+    getValues(scriptId) {
+        const { decodeValue } = valueCodec();
+        const out = {};
+        for (const [k, v] of this.storeFor(scriptId))
+            out[k] = decodeValue(v);
+        return out;
+    }
+    /**
+     * Every value a script has stored, for the run's commands: here the
+     * host's copy; `ExtensionHost` asks the extension.
+     */
+    async valuesOf(scriptId) {
+        return this.getValues(scriptId);
+    }
+    getValue(scriptId, key) {
+        const store = this.storeFor(scriptId);
+        return store.has(key) ? valueCodec().decodeValue(store.get(key)) : undefined;
+    }
+    // Writes into the host's copy; last write wins per key.
+    applyWrites(scriptId, writes) {
+        const store = this.storeFor(scriptId);
+        for (const w of writes) {
+            if (typeof w?.key !== 'string')
+                continue;
+            if (w.deleted)
+                store.delete(w.key);
+            else
+                store.set(w.key, w.value);
+        }
+    }
+    storeFor(scriptId) {
+        let store = this.values.get(scriptId);
+        if (!store) {
+            store = new Map();
+            this.values.set(scriptId, store);
+        }
+        return store;
+    }
+    // ---------- Navigation ----------
+    /**
+     * A watched page loaded a new document. The extension skips a script
+     * whose rules miss the URL silently, so the host records the miss for
+     * the developer: which rule kept the script off this URL. `scripts`
+     * are the ones the page's tab runs.
+     */
+    noteNavigation(page, scripts) {
+        this.forgetDocumentState(page);
+        const url = page.url();
+        for (const script of scripts) {
+            const id = script.id ?? '';
+            const verdict = explainMatch(script.matching, url);
+            if (verdict.matches)
+                continue;
+            const report = {
+                scriptId: id,
+                name: preparedScriptName(script),
+                url,
+                at: Date.now(),
+                reason: verdict.rule ?? NO_RULE_COVERS_URL,
+                ruleMiss: true,
+            };
+            this.recordPages.set(report, page);
+            this.reports.skipped.push(report);
+            this.notify('skip', report);
+        }
+    }
+    // ---------- What the scripts reported ----------
+    /** A script started in `from`'s current document. */
+    recordStart(from, fields) {
+        const report = this.baseReport(from, fields);
+        this.reports.started.push(report);
+        this.notify('start', report);
+    }
+    /** A script threw in `from`. */
+    recordError(from, fields) {
+        const report = this.baseReport(from, { ...fields, stack: this.remapStack(fields.stack) });
+        this.reports.errors.push(report);
+        this.notify('script-error', report);
+    }
+    /** A script didn't run in `from`, for `reason`. */
+    recordSkip(from, fields) {
+        const report = this.baseReport(from, fields);
+        this.reports.skipped.push(report);
+        this.notify('skip', report);
+    }
+    /**
+     * A manual script can be run in `from`'s document, where it waits to
+     * be run. Once per document: the extension says it again on each
+     * navigation, a pushState included, and a back/forward restore
+     * (which `forgetDocumentState` has cleared it for).
+     */
+    recordManual(from, fields) {
+        let set = this.manualByPage.get(from);
+        if (set?.has(fields.scriptId))
+            return;
+        if (!set) {
+            set = new Set();
+            this.manualByPage.set(from, set);
+        }
+        set.add(fields.scriptId);
+        const report = this.baseReport(from, fields);
+        this.reports.manual.push(report);
+        this.notify('manual', report);
+    }
+    /** A script in `from` wrote values. */
+    recordValueWrites(from, scriptId, writes, frame = {}) {
+        if (!this.scripts.has(scriptId))
+            return;
+        this.applyWrites(scriptId, writes);
+        const write = { scriptId, writes, ...frame };
+        this.recordPages.set(write, from);
+        this.notify('value-write', write);
+    }
+    /** A script in `from` registered a menu command. */
+    registerMenu(from, scriptId, commandId, name, documentId, frame) {
+        if (!this.scripts.has(scriptId) || !commandId)
+            return;
+        const record = {
+            scriptId, commandId, name, at: Date.now(), ...(documentId ? { documentId } : {}),
+            ...(frame ? { frame: true, ...(frame.frameNumber !== undefined ? { frameNumber: frame.frameNumber } : {}) } : {}),
+        };
+        // Re-registering an id replaces the entry in place, as the worker's
+        // registry does. Per document: two frames can use the same id.
+        const i = this.reports.menuCommands.findIndex((m) => m.scriptId === scriptId && m.commandId === commandId && m.documentId === documentId && this.menuOwners.get(m) === from);
+        if (i >= 0) {
+            this.menuOwners.delete(this.reports.menuCommands[i]);
+            this.reports.menuCommands[i] = record;
+        }
+        else {
+            this.reports.menuCommands.push(record);
+        }
+        this.menuOwners.set(record, from);
+        this.recordPages.set(record, from);
+        this.notify('menu-command', record);
+    }
+    /** A script in `from` removed a menu command. */
+    unregisterMenu(from, scriptId, commandId, documentId) {
+        const i = this.reports.menuCommands.findIndex((m) => m.scriptId === scriptId && m.commandId === commandId && m.documentId === documentId && this.menuOwners.get(m) === from);
+        if (i < 0)
+            return;
+        this.menuOwners.delete(this.reports.menuCommands[i]);
+        this.reports.menuCommands.splice(i, 1);
+    }
+    // ---------- What a test or command can do ----------
+    /**
+     * Invoke a registered menu command by its name, or by id, on the page
+     * that registered it. The extension runs all the script's
+     * registrations of that caption in the tab, as its menu does.
+     */
+    async fireMenuCommand(nameOrId, scriptId) {
+        const entry = [...this.reports.menuCommands].reverse().find((m) => (scriptId === undefined || m.scriptId === scriptId) && (m.name === nameOrId || m.commandId === nameOrId));
+        return entry ? this.fireMenuEntry(entry) : false;
+    }
+    // ---------- Helpers ----------
+    baseReport(from, fields) {
+        const report = { ...fields, name: fields.name || this.nameOf(fields.scriptId), at: Date.now() };
+        this.recordPages.set(report, from);
+        return report;
+    }
+    nameOf(scriptId) {
+        const script = this.scripts.get(scriptId);
+        return script ? preparedScriptName(script) : scriptId;
+    }
+    // Every event goes out through here. A test's listener that throws
+    // is the test's own failure: it must not cost the host its records.
+    notify(event, ...args) {
+        try {
+            this.emit(event, ...args);
+        }
+        catch {
+            // Dropped on purpose; see above.
+        }
+        if (event === 'start' || event === 'skip' || event === 'script-error' || event === 'manual') {
+            for (const check of [...this.reportWaiters])
+                check();
+        }
+    }
+}

package/lib/harness/index.d.ts

@@ -0,0 +1,8 @@
+export { prepareScript, explainMatch, type PrepareOptions, type PreparedScript, type MatchExplanation, type InjectionWorld, } from './prepare.js';
+export type { StoredScript, ScriptMatching, StartupLog } from '../script-build.js';
+export type { DiagnosticLocation } from '../diagnostic-location.js';
+export { checkParseNode } from './parse-check-node.js';
+export { HarnessHost, type PageLink, type HostReports, type HostEventMap, type StartReport, type ErrorReport, type SkipReport, type XhrRecord, type TabRecord, type MenuCommandRecord, type NotificationRecord, type DownloadRecord, type RequestInterceptor, } from './host.js';
+export { ExtensionHost } from './extension-host.js';
+export { attachPage, PageAttachment, type InjectOptions } from './page-watch.js';
+export { test, expect, type GmApi, type ReportsApi, type LoadOptions, type HarnessFixtures } from './fixture.js';

package/lib/harness/index.js

@@ -0,0 +1,10 @@
+// Public entry point of the development harness: what another repo
+// gets from `import … from 'sourcemonkey/harness'`. See
+// docs/harness-guide.md for the user-facing description and
+// docs/harness-design.md for the design.
+export { prepareScript, explainMatch, } from './prepare.js';
+export { checkParseNode } from './parse-check-node.js';
+export { HarnessHost, } from './host.js';
+export { ExtensionHost } from './extension-host.js';
+export { attachPage, PageAttachment } from './page-watch.js';
+export { test, expect } from './fixture.js';

package/lib/harness/input-file.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The text of `file`, which is `shown` in messages. Throws an Error
+ * saying why it couldn't be read, or that it is empty: nothing, or
+ * only whitespace unless `blankOk` (text to type may be just that).
+ */
+export declare function readInputFile(file: string, shown: string, { blankOk }?: {
+    blankOk?: boolean | undefined;
+}): string;
+/** The JSON value in `file`, else an Error as `readInputFile` throws. */
+export declare function readJsonFile(file: string, shown: string): unknown;
+/**
+ * Why a file couldn't be written, or null for a failure with no
+ * common cause. Playwright's own writes (a screenshot) only name the
+ * code in their message, hence the match.
+ */
+export declare function writeProblem(err: unknown): string | null;
+/** An error's message as a sentence to follow a `: `. */
+export declare function errorSentence(err: unknown): string;

package/lib/harness/input-file.js

@@ -0,0 +1,61 @@
+// Files named on a command line for what they hold (`eval --file`,
+// `set --file`, `type --file`, `start --values-file`): read whole, with what went wrong
+// in plain words for an `ERROR:` line.
+import { readFileSync } from 'node:fs';
+/**
+ * The text of `file`, which is `shown` in messages. Throws an Error
+ * saying why it couldn't be read, or that it is empty: nothing, or
+ * only whitespace unless `blankOk` (text to type may be just that).
+ */
+export function readInputFile(file, shown, { blankOk = false } = {}) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Couldn't read ${shown}: ${readProblem(err)}`);
+    }
+    if (blankOk ? !text : !text.trim())
+        throw new Error(`The file ${shown} is empty`);
+    return text;
+}
+/** The JSON value in `file`, else an Error as `readInputFile` throws. */
+export function readJsonFile(file, shown) {
+    const text = readInputFile(file, shown);
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`The file ${shown} is not JSON: ${err.message}`);
+    }
+}
+// Why a file couldn't be read.
+function readProblem(err) {
+    if (err.code === 'ENOENT')
+        return 'The file does not exist';
+    if (err.code === 'EISDIR')
+        return 'It\'s a folder';
+    if (err.code === 'EACCES')
+        return 'Permission was refused';
+    return errorSentence(err);
+}
+/**
+ * Why a file couldn't be written, or null for a failure with no
+ * common cause. Playwright's own writes (a screenshot) only name the
+ * code in their message, hence the match.
+ */
+export function writeProblem(err) {
+    const code = err.code ?? /\b(ENOENT|EACCES|EISDIR)\b/.exec(err.message)?.[1];
+    if (code === 'ENOENT')
+        return 'Its folder doesn\'t exist';
+    if (code === 'EACCES')
+        return 'Permission was refused';
+    if (code === 'EISDIR')
+        return 'It\'s a folder';
+    return null;
+}
+/** An error's message as a sentence to follow a `: `. */
+export function errorSentence(err) {
+    const first = err.message.split('\n')[0].replace(/\.$/, '');
+    return first.charAt(0).toUpperCase() + first.slice(1);
+}