sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/prepare.js

@@ -0,0 +1,364 @@
+// The development harness's front door: a userscript on disk (or as
+// text) in, a checked script out.
+//
+// This runs SourceMonkey's real install pipeline under Node — the same
+// functions the extension calls when it installs or refreshes a script:
+//
+//   1. `buildScriptFromText` splits the metadata block, parses and
+//      validates the header, and derives the matching rules.
+//   2. `applyFiles` resolves and fetches every `@require` / `@resource`,
+//      with the same local-file overrides the extension applies to a
+//      script loaded from disk (a `@require https://…/lib/x.js` reads
+//      the local `lib/x.js` when one sits under a search root).
+//   3. The parse check compiles the composed program without running
+//      it, so a syntax error is reported against the file and line it
+//      was written in — under Node's V8 rather than Chrome's, which is
+//      the one piece that differs (see parse-check-node.ts).
+//
+// The extension itself builds what runs (sm-dev pushes the script's
+// text); this is for checking a script up front and reading it back.
+//
+// Nothing here touches `chrome.*`. The two globals the pipeline reaches
+// for are replaced once per process: `fetch`, which Node doesn't
+// implement for `file://` URLs, and the parse checker, which the
+// extension installs from a sandboxed page.
+import { statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { applyFiles, buildScriptFromText, setParseChecker, } from '../script-build.js';
+import { attachParseLocation } from '../parse-location.js';
+import { describeDiagnostic } from '../diagnostic-location.js';
+import { setConfiguredLocalRoots } from '../local-file-overrides.js';
+import { explainUrlMatch } from '../url-match.js';
+import { hasTag } from '../userscript-header.js';
+import { scriptBasename } from '../script-display.js';
+import { representativeMatch } from '../match-targets.js';
+import { bytesToBase64, sha256Hex } from '../bytes.js';
+import { buildParseCheckSource } from '../composed-source.js';
+import { resolveScriptWorld } from '../script-world.js';
+import { checkParseNode } from './parse-check-node.js';
+import { MANIFEST_FILENAME } from '../collection-scan.js';
+import { WARNING_LEVEL } from './output-style.js';
+// ---------- The two process-wide seams ----------
+let seamsInstalled = false;
+// Per-call state the seams read. Safe as module state only because
+// `prepareScript` serializes calls.
+let fetchOverride;
+let parseCheckNote;
+// `file-loader.ts` reads every dependency through the global `fetch`,
+// which Node doesn't implement for `file://`. Wrap it once; http(s)
+// passes straight through to the real one.
+function installNodeSeams() {
+    if (seamsInstalled)
+        return;
+    seamsInstalled = true;
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = async (input, init) => {
+        const url = typeof input === 'string' ? input
+            : input instanceof URL ? input.href
+                : input.url;
+        if (fetchOverride)
+            return fetchOverride(url);
+        if (!url.startsWith('file:'))
+            return realFetch(input, init);
+        let body;
+        try {
+            const buf = await readFile(fileURLToPath(url));
+            body = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+        }
+        catch {
+            return new Response(null, { status: 404 });
+        }
+        // No Content-Type, as Chrome's own `file://` fetch has none: the
+        // loader's markup sniff is the gate for local files either way, and
+        // a header invented here would make the stored row differ from the
+        // extension's.
+        return new Response(body, {
+            status: 200,
+            headers: { 'content-length': String(body.byteLength) },
+        });
+    };
+    // Same two steps the extension's checkers perform: compose the exact
+    // text the injected entry compiles, then map the reported position
+    // back to the file it was written in. Only the compile is Node's.
+    //
+    // The pipeline swallows a check that couldn't decide (it fails
+    // open), so the note is kept here for `validate` to show.
+    setParseChecker(async (script) => {
+        let checked;
+        try {
+            checked = buildParseCheckSource(script);
+        }
+        catch (err) {
+            parseCheckNote = { kind: 'errored', message: String(err?.message ?? err) };
+            throw err;
+        }
+        const verdict = attachParseLocation(checkParseNode(checked.text), checked);
+        if (verdict?.status === 'unknown')
+            parseCheckNote = { kind: 'inconclusive', message: verdict.message ?? '' };
+        return verdict;
+    });
+}
+// ---------- Preparing ----------
+// Calls are serialized: the override resolver's configured roots and
+// the parse checker are process-wide, and two overlapping prepares with
+// different `localRoots` would otherwise read each other's. A spec that
+// prepares several scripts with `Promise.all` still gets each one
+// resolved against its own roots.
+let chain = Promise.resolve();
+export function prepareScript(opts) {
+    const run = chain.then(async () => {
+        fetchOverride = opts.fetch;
+        parseCheckNote = undefined;
+        try {
+            return await prepareScriptNow(opts);
+        }
+        finally {
+            fetchOverride = undefined;
+        }
+    });
+    chain = run.catch(() => undefined);
+    return run;
+}
+/**
+ * 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 function scriptRoots(file, collectionRoot, localRoots = []) {
+    const abs = path.resolve(file);
+    const root = path.resolve(collectionRoot);
+    if (isUnder(abs, root))
+        return { collectionRoot, localRoots };
+    for (let dir = path.dirname(abs); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+        if (statSync(path.join(dir, MANIFEST_FILENAME), { throwIfNoEntry: false })?.isFile()) {
+            return { collectionRoot: dir, localRoots: [...localRoots, root] };
+        }
+    }
+    return { collectionRoot, localRoots };
+}
+async function prepareScriptNow(given) {
+    const opts = given.file && given.collectionRoot
+        ? { ...given, ...scriptRoots(given.file, given.collectionRoot, given.localRoots) }
+        : given;
+    installNodeSeams();
+    if (!opts.file && opts.text === undefined) {
+        throw new Error('Pass prepareScript a file or text');
+    }
+    const text = opts.text ?? await readFile(opts.file, 'utf8');
+    const sourceUrl = opts.sourceUrl
+        ?? (opts.file ? pathToFileURL(path.resolve(opts.file)).toString()
+            : pathToFileURL(path.join(opts.collectionRoot ?? process.cwd(), 'pushed.user.js')).toString());
+    const relativePath = relativePathFor(opts, sourceUrl);
+    const now = Date.now();
+    // The configured roots are process-wide state in the override
+    // resolver (the extension reads them from storage once), so they are
+    // set on every call; `prepareScript` serializes calls for the same
+    // reason.
+    setConfiguredLocalRoots((opts.localRoots ?? []).map(dirUrl));
+    const built = await buildScriptFromText({
+        // Stable across re-prepares of the same file, so the host keeps
+        // that script's values and records under one key, and distinct for
+        // two scripts sharing a basename, so the host tells them apart.
+        id: `harness-${scriptBasename(relativePath)}-${(await sha256Hex(sourceUrl + (opts.copy ?? ''))).slice(0, 12)}`,
+        collectionId: 'harness',
+        relativePath,
+        fileUrl: sourceUrl,
+        text,
+        now,
+    });
+    // A fresh install: no prior row, every dependency refetched. The
+    // collection root joins the search roots the way it does for a
+    // directory collection in the extension.
+    const script = await applyFiles(built, undefined, 'all', new Map(), now, {
+        enabled: opts.localFiles !== false,
+        collectionPath: opts.collectionRoot ? dirUrl(opts.collectionRoot) : undefined,
+    });
+    const out = {
+        script,
+        status: script.status,
+        startupLogs: script.startupLogs ?? [],
+        ...(parseCheckNote && { parseCheckNote }),
+        id: script.status === 'ok' ? script.id : undefined,
+        world: resolveScriptWorld(script),
+        matching: script.matching,
+        requires: (script.requires ?? []).map((r) => ({ url: r.url, localUrl: r.localUrl })),
+    };
+    if (script.errorMessage) {
+        out.errorMessage = script.errorMessage;
+        out.errorLocation = script.errorLocation;
+        out.diagnostic = describeDiagnostic(script.errorMessage, script.errorLocation);
+    }
+    return out;
+}
+// The path the extension would store for this script: relative to the
+// collection root when it sits under one, else just its name. The
+// diagnostics, the composed-source segments, and `GM_info` all carry
+// it, so sm-dev's output reads the same as the extension's Log tab.
+function relativePathFor(opts, sourceUrl) {
+    if (!opts.file)
+        return scriptBasename(sourceUrl);
+    const file = path.resolve(opts.file);
+    if (opts.collectionRoot) {
+        const root = path.resolve(opts.collectionRoot);
+        if (file !== root && isUnder(file, root))
+            return path.relative(root, file).split(path.sep).join('/');
+    }
+    return path.basename(file);
+}
+// Whether `file` is `dir` or inside it. Not by a `..` prefix alone,
+// which a child named `..cache` also has.
+function isUnder(file, dir) {
+    const rel = path.relative(dir, file);
+    return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+// A directory as the `file://` URL the override resolver wants, with
+// the trailing slash it keys on.
+function dirUrl(dir) {
+    const url = pathToFileURL(path.resolve(dir)).toString();
+    return url.endsWith('/') ? url : url + '/';
+}
+/** What a `ParseCheckNote` means for the person reading it. */
+export function parseCheckWarning(note) {
+    const why = note.message ? ` (${note.message})` : '';
+    return `The syntax check could not finish${why}, so syntax errors were not checked. The script still loads.`;
+}
+/**
+ * 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 function warningLines(prepared, { parseCheck = true } = {}) {
+    const lines = prepared.startupLogs.map((l) => `${l.level}: ${describeDiagnostic(l.message, l.location)}`);
+    if (parseCheck && prepared.parseCheckNote)
+        lines.push(`${WARNING_LEVEL}${parseCheckWarning(prepared.parseCheckNote)}`);
+    return lines;
+}
+/** The reason to give when no header rule names a URL at all. */
+export 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 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 function explainMatch(matching, url) {
+    return explainUrlMatch(url, matching);
+}
+/** A script path that names nothing, for `start` and the typed `load`. */
+export function noSuchFileMessage(input) {
+    return `No such file or directory: ${input}`;
+}
+/** A script path that names a directory, for `start` and the typed `load`. */
+export function isDirectoryMessage(input, remedy = 'Name a .user.js file.') {
+    return `${input} is a directory. ${remedy}`;
+}
+/** Why a script has no default page, as `--all` and `newtab all` report it. */
+export 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 function defaultPageUrl(script) {
+    return representativeMatch(script.matching)?.linkUrl ?? 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 function withDefaultScheme(url, cwd = process.cwd()) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url))
+        return url;
+    if (/^(about|blob|data|file|javascript|mailto|view-source):/i.test(url))
+        return url;
+    if (/^[./]/.test(url) || isLocalPath(url, cwd))
+        return pathToFileURL(path.resolve(cwd, url)).toString();
+    return `http://${url}`;
+}
+// A scheme-less word that is a file in `cwd`, or doesn't start with a
+// host. A web address's host has a dot, except `localhost`; and a
+// directory is rarely named with one, so a first part with a dot reads
+// as a host even when a repo has a folder by that name (`example.com/`).
+function isLocalPath(input, cwd) {
+    try {
+        if (statSync(path.resolve(cwd, input)).isFile())
+            return true;
+    }
+    catch {
+        // Not a file here; the first part decides.
+    }
+    const first = input.split('/')[0];
+    return !(first.includes('.') || /^localhost$/i.test(first) || /:\d+$/.test(first) || first.startsWith('['));
+}
+/**
+ * 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 function shownPath(file, cwd = process.cwd(), outside = file) {
+    const relative = path.relative(cwd, file);
+    const inside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    return inside ? relative : outside;
+}
+/**
+ * Where a loaded script is, to show beside its name (`shownPath`).
+ * Its `relativePath` stays what identifies it, as in the extension.
+ */
+export function preparedScriptPath(script) {
+    const url = script.script.fileUrl;
+    return url.startsWith('file:') ? shownPath(fileURLToPath(url)) : script.script.relativePath;
+}
+/** The script's `@name`, else the path it was loaded from. */
+export function preparedScriptName(script) {
+    const tags = script.script.header?.tags ?? [];
+    const name = tags.find((t) => t.tag === 'name' && !t.locale)?.value;
+    return name || script.script.relativePath;
+}
+/** Whether the script has `@noframes`, which keeps it to the top frame. */
+export function preparedNoframes(script) {
+    return script.script.header ? hasTag(script.script.header, 'noframes') : false;
+}
+/**
+ * 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 function preparedScriptMatches(script, name) {
+    return script.script.relativePath === name
+        || path.basename(script.script.relativePath) === name
+        || script.script.header?.tags.some((t) => t.tag === 'name' && !t.locale && t.value === name) === true;
+}
+/**
+ * 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 function pushedFiles(prepared) {
+    const out = {};
+    const add = (ref, file, bytesBase64) => {
+        if (!file.localUrl && !file.url.startsWith('file:'))
+            return;
+        out[ref] = { url: file.url, ...(file.localUrl ? { localUrl: file.localUrl } : {}), bytesBase64, contentType: file.contentType ?? '' };
+    };
+    for (const r of prepared.script.requires ?? [])
+        add(r.ref, r, bytesToBase64(new TextEncoder().encode(r.source)));
+    for (const r of prepared.script.resources ?? [])
+        add(r.ref, r, r.bytesBase64);
+    return out;
+}

package/lib/harness/prompt-editor.d.ts

@@ -0,0 +1,17 @@
+import readline from 'node:readline';
+/** How to color the prompts (`> `, `... `) and the typed text, at a terminal that has color. */
+export interface PromptPaint {
+    prompt: (text: string) => string;
+    text: (text: string) => string;
+}
+export interface PromptEditor {
+    /** Empties the buffer, as Ctrl-C and Esc do. */
+    clear(): void;
+}
+/**
+ * Makes `rl` edit several lines as one buffer. `complete` says whether
+ * a buffer is ready to send, rather than inside an unclosed block.
+ * `cleared` gets the text of a buffer emptied by `clear`. `paint`
+ * colors the prompts and the typed text as they are drawn.
+ */
+export declare function editMultiLine(rl: readline.Interface, continuation: string, complete: (text: string) => boolean, cleared?: (text: string) => void, paint?: PromptPaint): PromptEditor;