sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/help-format.js

@@ -0,0 +1,127 @@
+// Text layout for sm-dev's help, in a markdown-like form: `## headings`,
+// `- ` bullets, `code` spans for whatever is typed or shown as is
+// (commands, flags, IDs), and **bold** spans.
+//
+// Lines are laid out with their markup, then painted. In color (a
+// terminal that has it), code and headings take the looks of sm-dev's
+// other output (STYLES in output-style.ts): code as a command, headings
+// and **bold** spans as headings. Plain, bold is dropped,
+// and a code span keeps its backticks only where they help it read
+// apart from the prose (`keepsBackticks`). A quiet span (`quiet`), for
+// a list's terms and usage lines, has none.
+//
+// Widths are measured as the text will show in the mode it is laid out
+// for, so columns line up and lines wrap to fit either way.
+import { keepsBackticks, styleCodes } from './output-style.js';
+// Starts a line of a code block, after its indent: shown as is, all of
+// it code.
+const CODE_LINE = '\u0001';
+// A quiet code span's ends.
+const QUIET = '\u0003';
+const QUIET_END = '\u0004';
+// A space inside a span, kept while wrapping so the span stays on one
+// line. (Not a no-break space: \s matches that.)
+const KEPT_SPACE = '\u0002';
+/** Text as a code span with no backticks in plain help: a list's term, a usage line. */
+export const quiet = (text) => QUIET + text + QUIET_END;
+// Each span: code first, so `**` in one (a glob) is code, not bold.
+const SPAN = new RegExp(`\`([^\`]*)\`|${QUIET}([^${QUIET_END}]*)${QUIET_END}|\\*\\*([^*]+)\\*\\*`, 'g');
+// Text as it shows, plain or in color, before any color is added.
+function shown(text) {
+    return text.replace(SPAN, (span, code, quieted, bold) => {
+        if (code !== undefined)
+            return color || !keepsBackticks(code) ? code : span;
+        return quieted ?? bold ?? '';
+    });
+}
+// Code and headings, on and off, as the rest of sm-dev's output shows them.
+const [CODE, NO_CODE] = styleCodes('cmd');
+const [BOLD, NO_BOLD] = styleCodes('h');
+// Whether the help being laid out is for color. Set for one rendering
+// by `render`.
+let color = false;
+/** Lays out lines for color or not, then paints them: one string, ending in a newline. */
+export function render(inColor, layout) {
+    const was = color;
+    color = inColor;
+    try {
+        // A blank line once, where pieces laid out apart each bring one, and
+        // none at the end.
+        const lines = layout().filter((line, i, all) => line !== '' || (i > 0 && all[i - 1] !== ''));
+        while (lines.at(-1) === '')
+            lines.pop();
+        return lines.map(paint).join('\n') + '\n';
+    }
+    finally {
+        color = was;
+    }
+}
+/** How wide text shows. */
+export function visibleLength(text) {
+    return shown(text).length;
+}
+/** Text padded with spaces to show `width` wide. */
+export function padTo(text, width) {
+    return text + ' '.repeat(Math.max(0, width - visibleLength(text)));
+}
+function paint(line) {
+    const code = line.indexOf(CODE_LINE);
+    if (code >= 0) {
+        const rest = line.slice(code + 1);
+        return line.slice(0, code) + (color && rest ? CODE + rest + NO_CODE : rest);
+    }
+    if (!color)
+        return shown(line);
+    const spans = line.replace(SPAN, (_span, code, quieted, bold) => (bold !== undefined ? BOLD + bold + NO_BOLD : CODE + (code ?? quieted) + NO_CODE));
+    return line.startsWith('#') ? BOLD + spans + NO_BOLD : spans;
+}
+/** Text wrapped to `width`, by the width it shows. A span is never split. */
+export function wrap(text, width) {
+    const kept = text.replace(SPAN, (span) => span.replace(/ /g, KEPT_SPACE));
+    const lines = [];
+    let line = '';
+    for (const word of kept.split(/\s+/).filter(Boolean)) {
+        if (line && visibleLength(line) + 1 + visibleLength(word) > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    // No last line of one word: the line above gives it one of its own,
+    // where that still fits.
+    const last = lines.length - 1;
+    if (last > 0 && !lines[last].includes(' ') && lines[last - 1].split(' ').length > 2) {
+        const cut = lines[last - 1].lastIndexOf(' ');
+        const moved = `${lines[last - 1].slice(cut + 1)} ${lines[last]}`;
+        if (visibleLength(moved) <= width) {
+            lines[last] = moved;
+            lines[last - 1] = lines[last - 1].slice(0, cut);
+        }
+    }
+    return lines.map((l) => l.replaceAll(KEPT_SPACE, ' '));
+}
+/**
+ * A line of text, wrapped to `width`. A bullet (`- `) or numbered item
+ * (`1. `), after any spaces of its own, wraps under its text. Any other
+ * line starting with spaces is a line of a code block, shown as is, two
+ * spaces further in.
+ */
+export function textLines(text, width) {
+    if (text === '')
+        return [''];
+    const item = /^(\s*)(- |\d+\. )/.exec(text);
+    if (item) {
+        const lead = item[0];
+        return wrap(text.slice(lead.length), width - lead.length)
+            .map((line, i) => (i === 0 ? lead : ' '.repeat(lead.length)) + line);
+    }
+    if (text.startsWith(' ')) {
+        const code = text.trimStart();
+        return [`  ${text.slice(0, text.length - code.length)}${CODE_LINE}${code}`];
+    }
+    return wrap(text, width);
+}

package/lib/harness/host.d.ts

@@ -0,0 +1,352 @@
+import { EventEmitter } from 'node:events';
+import type { Frame } from '@playwright/test';
+import type { GmXhrEvent, GmXhrRequestPayload } from '../gm-xhr-types.js';
+import type { PreparedScript } from './prepare.js';
+import { FrameIds } from './frames.js';
+/** One watched page (a tab), as the host sees it. */
+export interface PageLink {
+    /** The page's current top-level URL. */
+    url(): string;
+}
+export interface TabRecord {
+    scriptId: string;
+    requestId: string;
+    url: string;
+    active: boolean;
+    at: number;
+    closed: boolean;
+}
+export interface MenuCommandRecord {
+    scriptId: string;
+    commandId: string;
+    name: string;
+    at: number;
+    /**
+     * The document that registered it, where it fires: the page's, or one
+     * of its iframes'. Absent where the manager doesn't say.
+     */
+    documentId?: string;
+    /** Registered in one of the page's iframes, not the page itself. */
+    frame?: true;
+    /** Registered in an iframe: its frame id's number (`F3` is 3), when known. */
+    frameNumber?: number;
+}
+export interface NotificationRecord {
+    scriptId: string;
+    /** From an iframe: its frame id's number (`F3` is 3), when known. */
+    frameNumber?: number;
+    requestId: string;
+    text: string;
+    title: string;
+    at: number;
+    /** The last event delivered to the script, if any. */
+    event?: 'clicked' | 'closed';
+}
+export interface DownloadRecord {
+    scriptId: string;
+    /** From an iframe: its frame id's number (`F3` is 3), when known. */
+    frameNumber?: number;
+    requestId: string;
+    url: string;
+    name: string;
+    at: number;
+    outcome?: 'load' | 'error' | 'timeout' | 'abort';
+    /** Where the browser saved it, on `load`. */
+    filename?: string;
+    error?: string;
+}
+export interface XhrRecord {
+    scriptId: string;
+    /** From an iframe: its frame id's number (`F3` is 3), when known. */
+    frameNumber?: number;
+    id: string;
+    url: string;
+    method: string;
+    at: number;
+    /** How it ended, once it has. */
+    outcome?: 'load' | 'error' | 'timeout' | 'abort';
+    /** The HTTP status, on `load`. */
+    status?: number;
+    /** The message the script's `onerror` got, on `error`. */
+    error?: string;
+}
+/**
+ * SourceMonkey asking whether a script may connect to a host its
+ * `@connect` lines don't cover, and the answer once given.
+ */
+export interface ConnectPromptRecord {
+    scriptId: string;
+    /** The script's name. */
+    name: string;
+    promptId: string;
+    host: string;
+    url: string;
+    method: string;
+    at: number;
+    answer?: ConnectChoice;
+    /** Closed without an answer: its requests timed out or were aborted. */
+    closed?: boolean;
+}
+export type ConnectChoice = 'once' | 'cancel' | 'allow' | 'allow-all' | 'deny';
+export interface ScriptReport {
+    scriptId: string;
+    name: string;
+    /** The URL of the document it came from: an iframe's, for `frame`. */
+    url: string;
+    at: number;
+    /** From one of the page's iframes, not the page itself. */
+    frame?: true;
+    /** The extension's id for the document it came from, where it says. */
+    documentId?: string;
+    /** From an iframe: its frame id's number (`F3` is 3), when known. */
+    frameNumber?: number;
+}
+export interface StartReport extends ScriptReport {
+}
+/** What a manager's report gives for a `ScriptReport`; the host adds `at`. */
+export type ReportFields = Omit<ScriptReport, 'at'>;
+export interface ErrorReport extends ScriptReport {
+    message: string;
+    stack: string;
+}
+export interface SkipReport extends ScriptReport {
+    /** Why the script did not run: the header rule, or the extension's reason. */
+    reason: string;
+    /**
+     * The host's own finding that the header's rules miss the URL, rather
+     * than the extension's report, so SourceMonkey's Log has no entry.
+     */
+    ruleMiss?: true;
+}
+/**
+ * A manual script (`@run-at context-menu`) matched a new document,
+ * where it waits to be run rather than starting.
+ */
+export type ManualReport = ScriptReport;
+export interface HostReports {
+    started: StartReport[];
+    errors: ErrorReport[];
+    skipped: SkipReport[];
+    /** Manual scripts waiting in a new document (`ManualReport`). */
+    manual: ManualReport[];
+    /** Every `GM_xmlhttpRequest`, with its outcome once settled. */
+    requests: XhrRecord[];
+    /** Every `GM_openInTab`. */
+    tabs: TabRecord[];
+    /** Menu commands currently registered, in registration order. */
+    menuCommands: MenuCommandRecord[];
+    /** Every `GM_notification`. */
+    notifications: NotificationRecord[];
+    /** Every `GM_download` the extension handled. */
+    downloads: DownloadRecord[];
+    /** Every connection prompt, with its answer once given. */
+    connectPrompts: ConnectPromptRecord[];
+}
+export interface WireWrite {
+    key: string;
+    value?: unknown;
+    deleted?: boolean;
+}
+export interface HostEventMap {
+    start: [StartReport];
+    'script-error': [ErrorReport];
+    skip: [SkipReport];
+    manual: [ManualReport];
+    'value-write': [{
+        scriptId: string;
+        writes: WireWrite[];
+    }];
+    /** A `GM_xmlhttpRequest` settled; the record carries its outcome. */
+    request: [XhrRecord];
+    tab: [TabRecord];
+    'menu-command': [MenuCommandRecord];
+    notification: [NotificationRecord];
+    download: [DownloadRecord];
+    /** A connection prompt opened, or was answered (`answer` set). */
+    'connect-prompt': [ConnectPromptRecord];
+}
+declare let codec: {
+    encodeValue(v: unknown): unknown;
+    decodeValue(v: unknown): unknown;
+} | null;
+export declare function valueCodec(): NonNullable<typeof codec>;
+export type RequestInterceptor = (request: GmXhrRequestPayload, scriptId: string) => GmXhrEvent | null | Promise<GmXhrEvent | null>;
+export declare abstract class HarnessHost extends EventEmitter<HostEventMap> {
+    private readonly scripts;
+    private readonly owners;
+    private readonly values;
+    protected readonly recordPages: WeakMap<object, PageLink>;
+    private readonly reportWaiters;
+    readonly reports: HostReports;
+    private readonly manualByPage;
+    private readonly menuOwners;
+    /** The run's frame ids (`F3`), across all its tabs. */
+    readonly frameIds: FrameIds;
+    /** Register a prepared script as running in `owner`'s tab. */
+    addScript(prepared: PreparedScript, owner: PageLink): void;
+    /** `owner` no longer has the script; forget it once nobody does. */
+    removeScript(scriptId: string, owner: PageLink): void;
+    hasScript(scriptId: string): boolean;
+    /**
+     * 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: PageLink, scriptId: string): boolean;
+    /**
+     * Whether the scripts' manager reports their starts, skips and
+     * errors. Another manager than SourceMonkey doesn't.
+     */
+    get getsReports(): boolean;
+    /**
+     * 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: PageLink, scriptIds: readonly string[], since: number): string[];
+    /**
+     * 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: PageLink, scriptIds: readonly string[], since: number, signal?: AbortSignal): Promise<void>;
+    /** A script's latest start and latest skip from one page's top frame. */
+    lastStartAndSkip(page: PageLink, scriptId: string): {
+        started?: StartReport;
+        skipped?: SkipReport;
+    };
+    /**
+     * 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: PageLink): Map<string, Set<string>>;
+    /**
+     * 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: PageLink, scriptId: string, since: number): boolean;
+    /**
+     * 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.
+     */
+    liveFrameDocuments(_page: PageLink): Promise<Map<string, Frame> | null>;
+    /** The page a record in `reports` came from, if it is still known. */
+    pageOf(record: object): PageLink | undefined;
+    scriptIds(): string[];
+    /**
+     * The ids of the scripts whose rules match `url`; in an iframe
+     * (`inFrame`), leaving out those `@noframes` keeps to the top frame.
+     */
+    scriptsFor(url: string, inFrame: boolean): string[];
+    /**
+     * `text` with each stack frame from a script's injected entry pointed
+     * at the file and line it was written in: a `@require`, or the script
+     * itself. Without this, a script with `@require`s reports lines
+     * counted from the top of the requires.
+     */
+    abstract remapStack(text: string): string;
+    /** A watched page went away. */
+    detachPage(page: PageLink): void;
+    /**
+     * 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: PageLink): string[];
+    private forgetDocumentState;
+    /**
+     * 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.
+     */
+    setValues(scriptId: string, values: Record<string, unknown>): Promise<void>;
+    /** Every value a script has stored, decoded, from the host's copy. */
+    getValues(scriptId: string): Record<string, unknown>;
+    /**
+     * Every value a script has stored, for the run's commands: here the
+     * host's copy; `ExtensionHost` asks the extension.
+     */
+    valuesOf(scriptId: string): Promise<Record<string, unknown>>;
+    /**
+     * Where `eval` finds a script's eval hook in a page (see
+     * src/eval-hook.ts): the key the hooks are kept under, and the id the
+     * script has there. Null for a script that has none.
+     */
+    abstract evalHook(scriptId: string): {
+        key: string;
+        id: string;
+    } | null;
+    getValue(scriptId: string, key: string): unknown;
+    private applyWrites;
+    private storeFor;
+    /**
+     * 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: PageLink, scripts: readonly PreparedScript[]): void;
+    /** A script started in `from`'s current document. */
+    protected recordStart(from: PageLink, fields: ReportFields): void;
+    /** A script threw in `from`. */
+    protected recordError(from: PageLink, fields: ReportFields & {
+        message: string;
+        stack: string;
+    }): void;
+    /** A script didn't run in `from`, for `reason`. */
+    protected recordSkip(from: PageLink, fields: ReportFields & {
+        reason: string;
+    }): void;
+    /**
+     * 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).
+     */
+    protected recordManual(from: PageLink, fields: {
+        scriptId: string;
+        name: string;
+        url: string;
+    }): void;
+    /** A script in `from` wrote values. */
+    protected recordValueWrites(from: PageLink, scriptId: string, writes: WireWrite[], frame?: {
+        frameNumber?: number;
+    }): void;
+    /** A script in `from` registered a menu command. */
+    protected registerMenu(from: PageLink, scriptId: string, commandId: string, name: string, documentId?: string, frame?: {
+        frameNumber?: number;
+    }): void;
+    /** A script in `from` removed a menu command. */
+    protected unregisterMenu(from: PageLink, scriptId: string, commandId: string, documentId?: string): void;
+    /**
+     * 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.
+     */
+    fireMenuCommand(nameOrId: string, scriptId?: string): Promise<boolean>;
+    /**
+     * Fire one entry of `reports.menuCommands` in the page that
+     * registered it. False once that page has moved on.
+     */
+    abstract fireMenuEntry(entry: MenuCommandRecord): Promise<boolean>;
+    /**
+     * Run a manual script in `page`, as its popup "Run this script" does.
+     * Throws with the reason when it can't.
+     */
+    abstract runManualScript(page: PageLink, scriptId: string): Promise<void>;
+    /** Click a shown notification, which runs the script's `onclick`. */
+    abstract clickNotification(requestId: string): Promise<boolean>;
+    /** Close a shown notification, which fires the script's `ondone`. */
+    abstract closeNotification(requestId: string): Promise<boolean>;
+    /** Answer a waiting connection prompt. False when it isn't waiting. */
+    abstract answerConnectPrompt(promptId: string, choice: ConnectChoice): Promise<boolean>;
+    private baseReport;
+    protected nameOf(scriptId: string): string;
+    protected notify<K extends keyof HostEventMap>(event: K, ...args: HostEventMap[K]): void;
+}
+export {};