sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/parse-check-node.js

@@ -0,0 +1,132 @@
+// Node counterpart of `src/extension/parse-sandbox.ts` — the compile-only parse
+// check, run under Node's V8 instead of Chrome's. Used by the development
+// harness (`prepare.ts`), which runs the install pipeline outside a
+// browser for `sm-dev` and the corpus validator.
+//
+// The extension can only do this inside a sandboxed extension page,
+// because MV3's CSP forbids `eval` everywhere else and the location
+// probes need to insert a `<script>`. Node has neither restriction, so
+// the same two-step check (verdict, then location) is a few lines here:
+//
+//   - the verdict comes from `new Function(src)`, byte-for-byte the
+//     call the sandbox makes;
+//   - the location comes from compiling the same text twice more with
+//     `new vm.Script`, which is Node's classic-script compile — the
+//     same thing appending a `<script>` element does in the sandbox.
+//
+// Everything downstream (`selectParseLocation`, `attachParseLocation`)
+// is the extension's own code, so the probe selection rule is shared
+// rather than reimplemented.
+//
+// Caveat worth remembering when reading results: Node's V8 is not
+// Chrome's V8. Both accept the same language, but a very new syntax
+// feature (or a wording change in a `SyntaxError` message) can differ
+// between the two versions. `node --version` pins which one answered.
+import vm from 'node:vm';
+// Mirrors `parse-sandbox.ts` exactly, because the probe text is what
+// the reported positions are relative to: change the framing and the
+// line numbers stop matching the browser's.
+//
+// In the sandbox the sentinel is load-bearing for safety — appending a
+// `<script>` element runs it, and only a guaranteed parse failure stops
+// that. `new vm.Script` compiles without running either way, so here
+// the sentinel is purely about parity. Keeping it means a source that
+// ends mid-construct fails at the same place in both, which is the case
+// `selectParseLocation`'s range check is reading.
+const PROBE_SENTINEL = '\n(';
+const WRAPPER_HEAD = 'function __smParseProbe__() {\n';
+const WRAPPER_TAIL = '\n}';
+// Any name works; it only has to be recognizable in the stack trace we
+// parse the position out of. The `:` is the separator V8 puts before
+// the line number — matched as a literal prefix rather than
+// interpolated into a regex, so a future rename can't turn a character
+// of the name into a wildcard.
+const PROBE_FILENAME = 'sm-parse-probe.js';
+const PROBE_HEAD_PREFIX = `${PROBE_FILENAME}:`;
+/** The verdict, with probes attached when it's a syntax error. */
+export function checkParseNode(source) {
+    try {
+        // eslint-disable-next-line no-new-func
+        new Function(source);
+        return { status: 'ok' };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Only a SyntaxError means "this source is broken". A RangeError
+        // (parser stack overflow on pathologically nested source) means we
+        // couldn't tell — see the long note in parse-sandbox.ts.
+        if (!(err instanceof SyntaxError))
+            return { status: 'unknown', message };
+        return { status: 'syntax-error', message, probes: locate(source) };
+    }
+}
+function locate(source) {
+    try {
+        return {
+            wrapped: runProbe(`${WRAPPER_HEAD}${source}${WRAPPER_TAIL}${PROBE_SENTINEL}`, 1),
+            raw: runProbe(`${source}${PROBE_SENTINEL}`, 0),
+        };
+    }
+    catch {
+        // Locating is a nicety; the verdict is the product.
+        return undefined;
+    }
+}
+// Compile `text` as a classic script and report where it failed.
+// `lineOffset` is how many lines of our own framing precede the source,
+// so the caller gets source coordinates back.
+function runProbe(text, lineOffset) {
+    try {
+        new vm.Script(text, { filename: PROBE_FILENAME });
+    }
+    catch (err) {
+        if (!(err instanceof SyntaxError))
+            return undefined;
+        const at = positionFromStack(err);
+        if (!at)
+            return undefined;
+        return { message: err.message, line: at.line - lineOffset, column: at.column };
+    }
+    // No error at all means the sentinel failed to do its job — and the
+    // source ran. Report no position; `selectParseLocation` then has one
+    // fewer probe to choose from.
+    return undefined;
+}
+// A `vm.Script` SyntaxError carries its position only in the rendered
+// preamble at the top of `err.stack`, which V8 formats as:
+//
+//     sm-parse-probe.js:3
+//     }
+//     ^
+//     (blank)
+//     SyntaxError: Unexpected token '}'
+//         at new Script (node:vm:…)
+//
+// The first line gives the 1-based line; the caret line gives the
+// 1-based column as its first `^`. A stack whose first line isn't the
+// preamble is one we don't recognize, and gets no position at all.
+//
+// **The column is best-effort; the line is not.** V8 clips the rendered
+// frame at ~1020 characters, so for a longer source line the caret line
+// is all spaces with no `^` in it and the true column is simply not in
+// the stack. That is not exotic input here — a minified script, or a
+// minified `@require`, is one enormous line, and bulk-checking real
+// corpora is what this tool is for. Chrome's path reads `event.colno`
+// and has the real column in every case, so this is the one place the
+// Node port is knowingly less precise. We keep the line (exact, and the
+// part that names a file) and fall back to column 1, which
+// `COLUMN_UNKNOWN` marks as a fallback rather than a measurement.
+// Nothing downstream depends on it: `selectParseLocation` compares only
+// lines, so probe choice and the verdict are unaffected.
+const COLUMN_UNKNOWN = 1;
+function positionFromStack(err) {
+    const lines = String(err.stack ?? '').split('\n');
+    const head = lines[0] ?? '';
+    if (!head.startsWith(PROBE_HEAD_PREFIX))
+        return null;
+    const line = Number(head.slice(PROBE_HEAD_PREFIX.length));
+    if (!Number.isInteger(line))
+        return null;
+    const caretIndex = (lines[2] ?? '').indexOf('^');
+    return { line, column: caretIndex >= 0 ? caretIndex + 1 : COLUMN_UNKNOWN };
+}

package/lib/harness/path-args.d.ts

@@ -0,0 +1,22 @@
+export declare const HAS_SCHEME: RegExp;
+/**
+ * Whether a word is a glob: one with a `*` and no `scheme:` in front.
+ * A URL to open always has a scheme or a host with a dot, and no web
+ * page is at a `*`, so `example.com/*` is a glob too (and an error if
+ * it matches no file).
+ */
+export declare function isGlob(word: string): boolean;
+export declare function isDirectory(file: string): boolean;
+/** The `*.user.js` files under `dir`, as paths starting with `spelled`. */
+export declare function walkScripts(dir: string, spelled: string, out: string[]): void;
+/**
+ * What is wrong with a glob, or null. `**` only works as a whole path
+ * part (not `a**` or `**.user.js`), and not as the last one, which
+ * would leave the file name unmatched.
+ */
+export declare function globMistake(pattern: string): string | null;
+/**
+ * The files a glob matches, sorted within each directory, no
+ * directories. The glob must have no globMistake.
+ */
+export declare function globFiles(pattern: string, cwd?: string): string[];

package/lib/harness/path-args.js

@@ -0,0 +1,148 @@
+// Globs and directory searches over the file system, for sm-dev's file
+// arguments (see expandPathArg in checks.ts). `*` matches within one
+// path segment, and a `**` segment matches any number of directories.
+//
+// Synchronous, so the command line can sort its words into scripts and
+// URLs before deciding whether a command goes to a run.
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { quoted } from './output-style.js';
+const SCRIPT_FILE = /\.user\.js$/i;
+// Words with a scheme are URLs, whatever they contain. Two letters or
+// more, so a Windows drive (`C:`) stays a path.
+export const HAS_SCHEME = /^[a-z][a-z0-9+.-]+:/i;
+// Path separators: a backslash only where it is one.
+const SEPARATORS = path.sep === '\\' ? /[/\\]+/ : /\/+/;
+/**
+ * Whether a word is a glob: one with a `*` and no `scheme:` in front.
+ * A URL to open always has a scheme or a host with a dot, and no web
+ * page is at a `*`, so `example.com/*` is a glob too (and an error if
+ * it matches no file).
+ */
+export function isGlob(word) {
+    return word.includes('*') && !HAS_SCHEME.test(word);
+}
+export function isDirectory(file) {
+    try {
+        return statSync(file).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function entriesOf(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    catch {
+        return [];
+    }
+}
+// A directory searched in full, or by `**`: not node_modules, nor
+// hidden ones, which hold copies and tool state rather than sources.
+// Symbolic links to directories aren't followed either, so a link
+// back up the tree can't loop.
+const skipped = (entry) => entry.name === 'node_modules' || entry.name.startsWith('.');
+/** The `*.user.js` files under `dir`, as paths starting with `spelled`. */
+export function walkScripts(dir, spelled, out) {
+    for (const entry of entriesOf(dir)) {
+        if (skipped(entry))
+            continue;
+        const full = path.join(dir, entry.name);
+        const shown = path.join(spelled, entry.name);
+        if (entry.isDirectory())
+            walkScripts(full, shown, out);
+        else if (SCRIPT_FILE.test(entry.name))
+            out.push(shown);
+    }
+}
+// One path segment's pattern: `*` is any run of characters but `/`.
+function segmentRegExp(segment) {
+    const body = segment.split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*');
+    return new RegExp(`^${body}$`);
+}
+/**
+ * What is wrong with a glob, or null. `**` only works as a whole path
+ * part (not `a**` or `**.user.js`), and not as the last one, which
+ * would leave the file name unmatched.
+ */
+export function globMistake(pattern) {
+    // A trailing slash leaves an empty last part, which isn't one.
+    const segments = pattern.split(SEPARATORS).filter(Boolean);
+    if (segments.some((s) => s.includes('**') && s !== '**')) {
+        return `Invalid glob ${quoted(pattern)}. Use ${quoted('**')} only as a whole path part, as in ${quoted('src/**/*.user.js')}.`;
+    }
+    if (segments.at(-1) === '**') {
+        return `Invalid glob ${quoted(pattern)}. It ends in ${quoted('**')}, so it names no files. Add a file name, as in ${quoted(`${pattern.replace(/[/\\]+$/, '')}/*.user.js`)}.`;
+    }
+    return null;
+}
+/**
+ * The files a glob matches, sorted within each directory, no
+ * directories. The glob must have no globMistake.
+ */
+export function globFiles(pattern, cwd = process.cwd()) {
+    if (!pattern.includes('*'))
+        throw new Error('Internal error: globFiles needs a pattern with a *');
+    // `/`, or a drive's root (`C:\\`) on Windows; '' when relative.
+    const root = path.parse(pattern).root;
+    const segments = pattern.slice(root.length).split(SEPARATORS).filter(Boolean);
+    // The part before the first `*` is a plain directory to start from.
+    const firstGlob = segments.findIndex((s) => s.includes('*'));
+    const base = segments.slice(0, firstGlob);
+    const spelledBase = root || base.length > 0 ? path.join(root, ...base) : '';
+    const found = [];
+    const visit = (dir, spelled, rest) => {
+        const [segment, ...after] = rest;
+        const join = (name) => (spelled ? path.join(spelled, name) : name);
+        if (segment === '**') {
+            // Zero directories, then one more, and so on.
+            visit(dir, spelled, after);
+            for (const entry of entriesOf(dir)) {
+                if (!skipped(entry) && entry.isDirectory())
+                    visit(path.join(dir, entry.name), join(entry.name), rest);
+            }
+            return;
+        }
+        if (!segment.includes('*')) {
+            const full = path.join(dir, segment);
+            if (after.length === 0) {
+                if (!isDirectory(full) && statOk(full))
+                    found.push(join(segment));
+            }
+            else if (isDirectory(full)) {
+                visit(full, join(segment), after);
+            }
+            return;
+        }
+        const re = segmentRegExp(segment);
+        for (const entry of entriesOf(dir)) {
+            // A hidden name only for a segment that asks for one.
+            if (entry.name.startsWith('.') && !segment.startsWith('.'))
+                continue;
+            if (!re.test(entry.name))
+                continue;
+            // A link to a directory is followed here, where it was named.
+            const isDir = entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(path.join(dir, entry.name)));
+            if (after.length === 0) {
+                if (!isDir)
+                    found.push(join(entry.name));
+            }
+            else if (isDir) {
+                visit(path.join(dir, entry.name), join(entry.name), after);
+            }
+        }
+    };
+    visit(path.resolve(cwd, spelledBase || '.'), spelledBase, segments.slice(firstGlob));
+    // `**/**` and the like can reach one file twice.
+    return [...new Set(found)];
+}
+function statOk(file) {
+    try {
+        statSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/harness/playwright-chromium.d.ts

@@ -0,0 +1,16 @@
+type Chromium = typeof import('@playwright/test')['chromium'];
+interface Playwright {
+    chromium: Chromium;
+    /** The command that installs the Chromium build it wants. */
+    install: string;
+}
+/** The repo's Playwright when it has one, else sm-dev's own. */
+export declare function loadPlaywright(): Promise<Playwright>;
+/**
+ * Why Playwright's Chromium at `executable` can't start, when it isn't
+ * installed: the Playwright version, the build it wants, the builds
+ * that are installed, and `install`, the command that installs it
+ * (from `loadPlaywright`). Null when it's there.
+ */
+export declare function missingChromium(executable: string, install?: string): string | null;
+export {};

package/lib/harness/playwright-chromium.js

@@ -0,0 +1,86 @@
+// Which Playwright sm-dev drives browsers with, its own Chromium, and
+// what to say when that Chromium isn't installed.
+//
+// - sm-dev uses the Playwright the repo has (`@playwright/test`, an
+//   optional peer dependency), so the fixture and the repo's own specs
+//   share one copy.
+// - With none, as under `npx sm-dev`, it falls back to the
+//   `playwright-core` it depends on itself.
+// - Each Playwright version wants one Chromium build, downloaded apart
+//   from the package (`pnpm install` doesn't fetch it) into a folder
+//   named for the build: `~/.cache/ms-playwright/chromium-1248/`.
+//   Updating Playwright leaves sm-dev wanting a build that isn't there
+//   yet, while the old one still is.
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { quoted } from './output-style.js';
+const REPO_INSTALL = 'pnpm exec playwright install chromium';
+let loaded = null;
+function isNotFound(e) {
+    const code = e?.code;
+    return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
+}
+function packageVersion(name) {
+    try {
+        return createRequire(import.meta.url)(`${name}/package.json`).version;
+    }
+    catch {
+        return null;
+    }
+}
+/** The repo's Playwright when it has one, else sm-dev's own. */
+export function loadPlaywright() {
+    loaded ??= (async () => {
+        try {
+            const { chromium } = await import('@playwright/test');
+            return { chromium, install: REPO_INSTALL };
+        }
+        catch (e) {
+            if (!isNotFound(e))
+                throw e;
+        }
+        const { chromium } = await import('playwright-core');
+        // Pinned to the bundled version: a plain `npx playwright-core`
+        // fetches the newest, which wants a different build.
+        const version = packageVersion('playwright-core');
+        return {
+            chromium: chromium,
+            install: `npx playwright-core${version ? `@${version}` : ''} install chromium`,
+        };
+    })();
+    return loaded;
+}
+function playwrightVersion() {
+    return packageVersion('@playwright/test') ?? packageVersion('playwright-core');
+}
+/**
+ * Why Playwright's Chromium at `executable` can't start, when it isn't
+ * installed: the Playwright version, the build it wants, the builds
+ * that are installed, and `install`, the command that installs it
+ * (from `loadPlaywright`). Null when it's there.
+ */
+export function missingChromium(executable, install = REPO_INSTALL) {
+    if (existsSync(executable))
+        return null;
+    const version = playwrightVersion();
+    const using = version ? `Playwright ${version}` : 'Playwright';
+    // The folder named for the build, above the executable.
+    let dir = path.dirname(executable);
+    while (!/^chromium-\d+$/.test(path.basename(dir)) && path.dirname(dir) !== dir)
+        dir = path.dirname(dir);
+    const build = /^chromium-(\d+)$/.exec(path.basename(dir))?.[1];
+    if (!build)
+        return `${using} needs Chromium at ${executable}, which isn't installed. Install it with ${quoted(install)}.`;
+    let installed = [];
+    try {
+        installed = readdirSync(path.dirname(dir)).map((name) => /^chromium-(\d+)$/.exec(name)?.[1])
+            // The wanted build's folder can be there without its executable,
+            // after an install that was cut off.
+            .filter((b) => !!b && b !== build);
+    }
+    catch { /* No browsers folder yet. */ }
+    const have = installed.length ? `(Installed builds: ${installed.join(', ')}.)` : '(No Chromium builds are installed.)';
+    return `${using} needs Chromium build ${build}, which isn't installed. ${have} `
+        + `Install it with ${quoted(install)}. Run that again after each Playwright update.`;
+}

package/lib/harness/prepare.d.ts

@@ -0,0 +1,168 @@
+import { type StoredScript, type ScriptMatching, type StartupLog } from '../script-build.js';
+import { type DiagnosticLocation } from '../diagnostic-location.js';
+import { type UrlMatchExplanation } from '../url-match.js';
+import type { PushedFile } from '../external-files.js';
+import { type InjectionWorld } from '../script-world.js';
+export type { InjectionWorld };
+export interface PrepareOptions {
+    /** Absolute path of the `.user.js` file. Either this or `text`. */
+    file?: string;
+    /** The script's source, when it isn't read from disk. */
+    text?: string;
+    /**
+     * Where the script lives, as a URL. Relative `@require`s resolve
+     * against it, and only a `file://` script gets local overrides.
+     * Defaults to the file's own URL, or a placeholder `file://` URL
+     * next to `collectionRoot` when only `text` was given.
+     */
+    sourceUrl?: string;
+    /**
+     * The directory the script's repo is rooted at. Searched for local
+     * stand-ins of remote `@require` / `@resource` URLs, so a script deep
+     * in `sites/` can reach a `lib/` at the top. The script's path is
+     * reported relative to it, as the extension would.
+     */
+    collectionRoot?: string;
+    /** Extra directories to search for local stand-ins. */
+    localRoots?: string[];
+    /** Turn local stand-ins off entirely. Default on. */
+    localFiles?: boolean;
+    /**
+     * Tells two loads of the same file apart, so both can run on one
+     * page as two installed copies would: each gets its own script id,
+     * its own storage, and its own wrapper. Without it a second load of
+     * a path replaces the first.
+     */
+    copy?: string;
+    /**
+     * Answers every `fetch` made while preparing (in practice, the
+     * `@require` / `@resource` fetches) in place of the network and
+     * disk, `file://` included. The corpus validator serves
+     * dependencies out of a downloaded tree this way.
+     */
+    fetch?: (url: string) => Promise<Response>;
+}
+/**
+ * Why the syntax check couldn't reach a verdict. The script stays `ok`
+ * (the check fails open, see docs/parse-check.md), so this is a warning:
+ *   - `inconclusive`: V8 threw something other than a SyntaxError.
+ *   - `errored`: composing the text to check threw.
+ */
+export interface ParseCheckNote {
+    kind: 'inconclusive' | 'errored';
+    message: string;
+}
+export interface PreparedScript {
+    /** The row the extension would have stored. */
+    script: StoredScript;
+    status: 'ok' | 'invalid';
+    /** The extension's own message, when `status` is `invalid`. */
+    errorMessage?: string;
+    errorLocation?: DiagnosticLocation;
+    /** `errorMessage` rendered with its location, as the viewer shows it. */
+    diagnostic?: string;
+    /** Non-fatal parse-time notes: an unknown `@grant`, an ignored `@match`. */
+    startupLogs: readonly StartupLog[];
+    /** Set when the syntax check couldn't decide; the script stays `ok`. */
+    parseCheckNote?: ParseCheckNote;
+    /**
+     * The run's id for the script, which the host maps to the extension's
+     * own once it's pushed (`setPushed`). Unset when invalid.
+     */
+    id: string | undefined;
+    world: InjectionWorld;
+    matching: ScriptMatching;
+    /** The `@require` URLs, resolved, with where each was read from. */
+    requires: {
+        url: string;
+        localUrl?: string;
+    }[];
+}
+export declare function prepareScript(opts: PrepareOptions): Promise<PreparedScript>;
+/**
+ * The roots to prepare `file` with, given `collectionRoot` and
+ * `localRoots`. A script outside the root it was given (sm-dev run in
+ * one repo on another's script, or a shared fixture's root) belongs to
+ * the collection whose `script_manifest.json` is nearest above it, as
+ * it would be installed. The given root then joins the local roots, so
+ * its `lib/` still stands in for the `@require`s that name it.
+ */
+export declare function scriptRoots(file: string, collectionRoot: string, localRoots?: string[]): {
+    collectionRoot: string;
+    localRoots: string[];
+};
+/** What a `ParseCheckNote` means for the person reading it. */
+export declare function parseCheckWarning(note: ParseCheckNote): string;
+/**
+ * Every warning from preparing the script, as `<level>: <message>`
+ * with the line each is about: the load-time notes the viewer's Log
+ * tab shows, then (unless `parseCheck` is false) a syntax check that
+ * couldn't decide.
+ */
+export declare function warningLines(prepared: PreparedScript, { parseCheck }?: {
+    parseCheck?: boolean | undefined;
+}): string[];
+export type MatchExplanation = UrlMatchExplanation;
+/** The reason to give when no header rule names a URL at all. */
+export declare const NO_RULE_COVERS_URL = "No @match or @include covers this URL";
+/** The same, for `match` over several URLs, none of which a rule names. */
+export declare const NO_RULE_COVERS_URLS = "No @match or @include covers these URLs";
+/**
+ * Whether the script runs on `url`, and which header rule decided: an
+ * exclude wins over everything, then the first `@match`, then the
+ * first `@include`. Also every rule that matched or excluded it
+ * (`matchedBy`, `excludedBy`). The extension's own matcher, so the
+ * answer is the one the extension would give.
+ */
+export declare function explainMatch(matching: ScriptMatching, url: string): MatchExplanation;
+/** A script path that names nothing, for `start` and the typed `load`. */
+export declare function noSuchFileMessage(input: string): string;
+/** A script path that names a directory, for `start` and the typed `load`. */
+export declare function isDirectoryMessage(input: string, remedy?: string): string;
+/** Why a script has no default page, as `--all` and `newtab all` report it. */
+export declare const NO_DEFAULT_PAGE = "Its @match names no page to open";
+/**
+ * The page a script is opened on when no URL is given: the first one
+ * its `@match` implies. Null when none names a page, as with a
+ * match-everything pattern.
+ */
+export declare function defaultPageUrl(script: PreparedScript): string | null;
+/**
+ * A typed URL with `http://` added when it has no scheme, so
+ * `example.com/x` works. Only a word that starts with a host reads so:
+ * one with a dot, `localhost`, a port (`localhost:8080/x`) or an IPv6
+ * address (`[::1]/x`). Any other is a path, made a `file://` URL: one
+ * starting `/` or `.`, one naming a file that exists in `cwd`, or one
+ * whose first part has no dot (`pages/x.html`), existing or not. `host:port` would
+ * otherwise read as a scheme, so only a scheme followed by `//`, or one
+ * of the kinds that never have it, counts.
+ */
+export declare function withDefaultScheme(url: string, cwd?: string): string;
+/**
+ * A path to show: relative to `cwd` when it's inside it, else
+ * `outside` (by default the full path). Never one climbing out with
+ * `../`, which is harder to read than either.
+ */
+export declare function shownPath(file: string, cwd?: string, outside?: string): string;
+/**
+ * Where a loaded script is, to show beside its name (`shownPath`).
+ * Its `relativePath` stays what identifies it, as in the extension.
+ */
+export declare function preparedScriptPath(script: PreparedScript): string;
+/** The script's `@name`, else the path it was loaded from. */
+export declare function preparedScriptName(script: PreparedScript): string;
+/** Whether the script has `@noframes`, which keeps it to the top frame. */
+export declare function preparedNoframes(script: PreparedScript): boolean;
+/**
+ * Whether `name` picks out this script: the path it was loaded from,
+ * its basename, or its `@name`. How a test or a typed command names
+ * one script among several.
+ */
+export declare function preparedScriptMatches(script: PreparedScript, name: string): boolean;
+/**
+ * The `@require` / `@resource` bodies a run pushes into SourceMonkey with
+ * the script's text, by the ref its header declares: those read from
+ * disk, a relative ref's file or a local stand-in for a remote URL,
+ * which the extension couldn't read itself. Remote ones it fetches.
+ */
+export declare function pushedFiles(prepared: PreparedScript): Record<string, PushedFile>;