sourcemonkey 0.0.0-stage → 0.5.0

package/lib/script-links.js

@@ -0,0 +1,204 @@
+// Pure helpers for the userscript viewer's link rendering. Kept
+// DOM-free so the URL-detection + tag-classification rules can be
+// unit tested in Node without a Prism-shaped DOM.
+//
+// Two consumers in src/extension/userscript.ts:
+//   - The Details panel renderer (Match / Location / etc.).
+//   - The post-Prism walk over the highlighted code box.
+// Both call the same classifiers so a header line in the body is
+// linkified by the same rules as the corresponding details row.
+// Tags whose value is a single resource reference. The body-linkifier
+// passes the value through file-loader's `resolveScriptResource`,
+// which both linkifies absolute http(s) URLs and resolves relative
+// paths against the script's own URL (the same rule the `@icon`
+// favicon path uses). Anything the resolver rejects falls
+// back to plain text.
+//
+// `@resource` is *not* in this set even though its second token is a
+// URL — its grammar is two args (`<name> <url>`), so it gets its own
+// carve-out in `linkForHeaderTag` (src/extension/userscript.ts) that linkifies
+// only the URL portion. Treating it here would mis-resolve
+// `myCSS https://example.com/x.css` as a single relative path
+// `<parent>/myCSS%20https://...`.
+export const RESOLVABLE_HEADER_TAGS = new Set([
+    'icon', 'iconurl', 'defaulticon', 'icon64', 'icon64url',
+    'require',
+    'updateurl', 'downloadurl',
+    'homepage', 'homepageurl', 'website', 'source',
+    'supporturl',
+]);
+// Tags whose value is shaped like a Chrome `@match` pattern. Formally
+// `@include` and `@exclude` are free-form globs over the whole URL
+// (or `/regex/` literals), but in practice almost every excluded /
+// included pattern is written as a match pattern, and giving the
+// user a click target is more useful than rendering plain text.
+// `matchTargetInfo` returns null for shapes it can't dewildcard
+// (regex literals, `<all_urls>`, host wildcards) and those still
+// fall back to plain text.
+export const MATCH_HEADER_TAGS = new Set([
+    'match', 'exclude', 'include',
+]);
+// Word-boundary anchor keeps `https://…` inside a longer identifier
+// (rare but possible inside a string literal) from being picked up
+// mid-token. The character class excludes whitespace, quotes, angle
+// brackets, and backticks so a URL inside `"…"` or `<…>` stops at
+// the delimiter. `*` is also excluded so a `@match` / `@exclude`
+// pattern like `https://example.com/athletic/*` yields a clickable
+// `https://example.com/athletic/` followed by a literal `*` — `*` is
+// technically a legal URL character but in userscript headers it's
+// always a glob wildcard, and including it in the href produces a
+// link that doesn't navigate anywhere useful.
+const URL_RE = /\b(?:https?|file):\/\/[^\s'"<>`*]+/g;
+// Trailing punctuation that's commonly adjacent to URLs in prose.
+// `)` and `]` are conditional (see peelTrailingPunctuation) so a
+// URL with balanced brackets like `…/Foo_(disambig)` keeps them.
+const ALWAYS_PEEL_RE = /[.,;:!?]+$/;
+export function splitTextByUrls(text) {
+    const out = [];
+    let cursor = 0;
+    for (const m of text.matchAll(URL_RE)) {
+        const start = m.index ?? 0;
+        if (start > cursor) {
+            out.push({ kind: 'text', value: text.slice(cursor, start) });
+        }
+        const { url, trailing } = peelTrailingPunctuation(m[0]);
+        out.push({ kind: 'url', value: url });
+        if (trailing)
+            out.push({ kind: 'text', value: trailing });
+        cursor = start + m[0].length;
+    }
+    if (cursor < text.length) {
+        out.push({ kind: 'text', value: text.slice(cursor) });
+    }
+    return out;
+}
+// Peel trailing prose punctuation off a candidate URL. Closing
+// brackets `)` and `]` only peel when the URL has no matching open
+// bracket — so `(https://example.com/x)` peels the `)` (likely
+// surrounding parens in prose) but `https://en.wikipedia.org/wiki/Foo_(disambig)`
+// keeps it (URL contains its own `(`). Always-peelable chars
+// (`.,;:!?`) come off first.
+function peelTrailingPunctuation(raw) {
+    let url = raw;
+    let trailing = '';
+    // Always-peelable run first; close-brackets one-at-a-time after,
+    // since a single URL might end in `…)?` and we want both gone.
+    let progressed = true;
+    while (progressed) {
+        progressed = false;
+        const m = ALWAYS_PEEL_RE.exec(url);
+        if (m) {
+            trailing = m[0] + trailing;
+            url = url.slice(0, url.length - m[0].length);
+            progressed = true;
+        }
+        const last = url.charAt(url.length - 1);
+        if ((last === ')' && !url.includes('(')) ||
+            (last === ']' && !url.includes('['))) {
+            trailing = last + trailing;
+            url = url.slice(0, url.length - 1);
+            progressed = true;
+        }
+    }
+    return { url, trailing };
+}
+// Trailing-whitespace class includes `\r` so a CRLF-encoded line
+// that reaches us with a stray `\r` at the end still matches. The
+// rest of the SourceMonkey pipeline appears LF-normalised but the
+// regex stays cheap, and the `\r` fallback keeps `parseTagLine`
+// robust against any future input that bypasses normalisation.
+const TAG_LINE_RE = /^([ \t]*\/\/[ \t]*@([A-Za-z][\w-]*)(?::([\w-]+))?[ \t]+)(\S.*?)([ \t\r]*)$/;
+export function parseTagLine(line) {
+    const m = TAG_LINE_RE.exec(line);
+    if (!m)
+        return null;
+    const [, before, tag, locale, value, after] = m;
+    const out = {
+        before,
+        tag: tag.toLowerCase(),
+        value,
+        after,
+    };
+    if (locale)
+        out.locale = locale;
+    return out;
+}
+export function splitResourceValue(value) {
+    const gap = value.search(/[ \t]/);
+    if (gap < 0)
+        return null;
+    const afterGap = value.slice(gap);
+    const gapLen = afterGap.match(/^[ \t]+/)[0].length;
+    const urlStart = gap + gapLen;
+    const rest = value.slice(urlStart);
+    const trail = rest.search(/[ \t]/);
+    const urlEnd = trail < 0 ? value.length : urlStart + trail;
+    const url = value.slice(urlStart, urlEnd);
+    if (!url)
+        return null;
+    return {
+        prefix: value.slice(0, urlStart),
+        url,
+        suffix: value.slice(urlEnd),
+    };
+}
+// Build a click-through URL for one `@connect` value. The
+// body-linkifier wraps the verbatim value text in an anchor pointing
+// here; the anchor's `href` is normalised via the URL parser so the
+// click goes somewhere navigable even when the header value was just
+// a bare host.
+//
+// Rules:
+//   - `*` and `self` → null (no single site to point at).
+//   - `<scheme>://…` → verbatim URL (only http/https accepted).
+//   - `*.example.com` → `https://example.com/` (dewildcarded apex,
+//     matching the same rule `matchTargetInfo` applies for @match
+//     subdomain wildcards).
+//   - bare host (`example.com`, `localhost`, `1.2.3.4`) →
+//     `https://<host>/`.
+//   - Anything that doesn't parse as a URL after that → null.
+//
+// HTTPS is the assumed default for bare hosts even though the
+// userscript may issue HTTP requests via GM_xmlhttpRequest — the
+// click-through is just "visit this site to look it up", and
+// HTTPS is the right default for that.
+export function connectLinkUrl(raw) {
+    const t = raw.trim();
+    if (!t || t === '*')
+        return null;
+    if (t.toLowerCase() === 'self')
+        return null;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(t)) {
+        try {
+            const u = new URL(t);
+            if (u.protocol === 'http:' || u.protocol === 'https:') {
+                return u.toString();
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    let host = t;
+    if (host.startsWith('*.'))
+        host = host.slice(2);
+    if (!host || host.includes('*'))
+        return null;
+    try {
+        return new URL(`https://${host}/`).toString();
+    }
+    catch {
+        return null;
+    }
+}
+// Sentinel line shapes that bracket the metadata block. Used by the
+// body-linkifier to flip its "inside header" state.
+const HEADER_OPEN_RE = /^[ \t]*\/\/[ \t]*==UserScript==[ \t]*$/;
+const HEADER_CLOSE_RE = /^[ \t]*\/\/[ \t]*==\/UserScript==[ \t]*$/;
+export function isHeaderOpenLine(line) {
+    return HEADER_OPEN_RE.test(line);
+}
+export function isHeaderCloseLine(line) {
+    return HEADER_CLOSE_RE.test(line);
+}

package/lib/script-source-url.d.ts

@@ -0,0 +1,8 @@
+export declare const ROOT = "sourcemonkey://SourceMonkey";
+export declare function buildSourceUrl(logLabel: string): string;
+export declare function buildConfigSourceUrl(logLabel: string): string;
+export declare function buildSealSourceUrl(logLabel: string): string;
+export declare const PRELUDE_SOURCE_URL = "sourcemonkey://SourceMonkey/__prelude.js";
+export declare const BRIDGE_SOURCE_URL = "sourcemonkey://SourceMonkey/__bridge.js";
+export declare const GM_RUNTIME_SOURCE_URL = "sourcemonkey://SourceMonkey/__gm-runtime.js";
+export declare function buildRequireSourceUrl(logLabel: string, requireUrl: string): string;

package/lib/script-source-url.js

@@ -0,0 +1,214 @@
+// Canonical `sourcemonkey://SourceMonkey/...` URLs the injector
+// emits as `//# sourceURL=` directives, and that the viewer matches
+// stack-trace refs against.
+//
+// Why this URL shape:
+//
+// - The `sourcemonkey:` scheme is arbitrary — it just has to be
+//   URL-shaped, unique to us (the wrapper's async-error filter
+//   greps stack frames for it), and recognizable in stack traces.
+// - The literal `SourceMonkey` host puts everything we register
+//   under a single top folder in devtools' Sources tree. Devtools
+//   strips the scheme and uses the URL's authority as the first
+//   visible folder; without the host slot, our scripts would
+//   scatter at the top level.
+// - The next folder is the script's human-readable log label
+//   (`bar`, `bar%232`, etc.) — see `script-log-id.ts`. We use the
+//   log label rather than the script's UUID because the UUID is a
+//   debug-grade hash that's useless when you're scanning the tree.
+//   Per-script artifacts (`__config.js`, the main body, each
+//   `@require`) live under that folder so they cluster together
+//   by script.
+// - Page-wide URLs (`__bridge.js`, `__gm-runtime.js`, `__prelude.js`)
+//   live directly under `SourceMonkey/`. The bridge and GM runtime
+//   are true singletons (one chrome.userScripts registration each);
+//   the prelude is inlined per-script but every inclusion uses the
+//   same `__prelude.js` URL so devtools' Sources tree dedups them
+//   into a single visible entry.
+//
+// Why we percent-encode the label: it is a *display* string
+// (`script-log-id.ts` decodes URL-derived filenames so the user sees
+// `My Script.user.js`), and several of the characters that survive
+// that decode would break a URL. A bare `#` is the fragment
+// separator, so the `#N` dedup suffix would split the path; a space
+// or a paren ends the URL run that `stack-link.ts` matches, so a
+// stack-trace ref would stop linkifying to its tab. Everything
+// outside an unreserved-character whitelist is re-encoded — devtools
+// shows the encoded form, same as it always has. The viewer's Log tab
+// decodes it back for display (`displayRefText` in `stack-link.ts`),
+// so the two disagree on purpose: devtools indexes the file under
+// `main%232`, the Log tab reads `main#2` and keeps the wire form in a
+// tooltip.
+// Exported so consumers can recognize our own URLs by the exact prefix
+// rather than by the scheme alone — the scheme is unregistered, so a
+// hostile script can put `sourcemonkey://anything/…` in a log message
+// and have it parsed as a ref.
+export const ROOT = 'sourcemonkey://SourceMonkey';
+// Strip characters that would break out of the `//# sourceURL=<url>`
+// comment these URLs are spliced into. The log label is derived from
+// the on-disk filename (`script-log-id.ts`), which is attacker-
+// controlled for an untrusted script bundle. A JS line terminator
+// (LF/CR/U+2028/U+2029) ends the single-line `//` comment, so anything
+// after it on the line would become live code in the config blob —
+// which runs at document_start, before the script's own gating. Other
+// control chars can't break the comment but have no business in a
+// devtools tree path either; replace the lot with `_`. (The @require
+// URL builder already does per-segment whitelisting; this covers the
+// main/config/prelude labels that don't go through it.)
+function sanitizeLabel(label) {
+    // eslint-disable-next-line no-control-regex
+    return label.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, '_');
+}
+// Percent-encode everything outside the URL unreserved set, so the
+// segment is safe in a path AND carries nothing that would terminate
+// the stack-trace ref pattern in `stack-link.ts`. Applied last, after
+// the `.user.js` / `#N` surgery below has matched against the literal
+// characters.
+// The `u` flag matters: without it the character class matches single
+// UTF-16 code units, so an emoji (surrogate pair — GreasyFork names
+// are full of them) would be handed to encodeURIComponent half at a
+// time and throw URIError on the lone surrogate.
+function encodeSegment(segment) {
+    return segment.replace(/[^A-Za-z0-9._~-]/gu, (c) => {
+        let enc;
+        try {
+            enc = encodeURIComponent(c);
+        }
+        catch {
+            // An UNPAIRED surrogate — `u` makes the class match it as a
+            // single code point, but there's no UTF-8 encoding for it and
+            // encodeURIComponent throws. A manifest entry is user-authored
+            // JSON, so `"\ud800.user.js"` really can reach us. Letting the
+            // throw escape would reject the whole `Promise.all` in
+            // collectActiveSpecs and register NOTHING.
+            return '_';
+        }
+        // encodeURIComponent passes `!'()*` through untouched, and parens
+        // are exactly what would truncate a `at fn (URL:L:C)` frame — so
+        // hex-encode anything it declined to. All such characters are
+        // single-byte ASCII.
+        return enc === c ? `%${c.charCodeAt(0).toString(16).toUpperCase()}` : enc;
+    });
+}
+// Folder name for a script's artifacts. Strips the conventional
+// `.user.js` extension from the log label (the folder sits ABOVE the
+// main-body file, so the `.js` looks misleading on a folder), then
+// encodes what's left — which is where the `#E4` script-number suffix
+// (or an unnumbered script's `#N`) becomes `%23E4`.
+//
+// Examples:
+//   `foo.user.js`       → `foo`
+//   `foo.user.js#E4`    → `foo%23E4`
+//   `foo.user.js#2`     → `foo%232`
+//   `My foo.user.js`    → `My%20foo`
+//   `foo`               → `foo`      (no .user.js to strip)
+function folderForLabel(label) {
+    return encodeSegment(sanitizeLabel(label).replace(/\.user\.js(?=$|#)/, ''));
+}
+// Main-body file basename for a script. Same as the folder but with
+// the suffix dropped and `.user.js` restored — so the file's name
+// reflects the script's natural filename without the disambiguator
+// (each script lives in a different folder anyway).
+//
+// Examples:
+//   `foo.user.js`       → `foo.user.js`
+//   `foo.user.js#E4`    → `foo.user.js`
+//   `foo.user.js#2`     → `foo.user.js`
+//   `foo`               → `foo.user.js`
+function mainBaseForLabel(label) {
+    // Suffix first, extension second. The other order would eat a `#2`
+    // that's part of the name itself (`Chapter #2.user.js`) — which a
+    // decoded `%23` now makes reachable.
+    const base = sanitizeLabel(label).replace(/#E?\d+$/, '').replace(/\.user\.js$/, '');
+    return encodeSegment(base) + '.user.js';
+}
+// Per-script folder root.
+function scriptRoot(logLabel) {
+    return `${ROOT}/${folderForLabel(logLabel)}`;
+}
+// Canonical URL for the main script body.
+export function buildSourceUrl(logLabel) {
+    return `${scriptRoot(logLabel)}/${mainBaseForLabel(logLabel)}`;
+}
+// Canonical URL for the per-script config blob — the tiny {code}
+// entry the injector emits as the first js[] entry.
+export function buildConfigSourceUrl(logLabel) {
+    return `${scriptRoot(logLabel)}/__config.js`;
+}
+// Canonical URL for the per-script parse-failure sentinel — the last
+// js[] entry. Distinct from the config blob's URL on purpose: devtools
+// dedups Sources-tree nodes by URL, which is safe for the prelude only
+// because every copy of it is byte-identical. The sentinel and the
+// config blob are different code, so sharing a URL would show one node
+// whose text matches just one of them.
+export function buildSealSourceUrl(logLabel) {
+    return `${scriptRoot(logLabel)}/__seal.js`;
+}
+// Canonical URL for the prelude. Bytes (WRAPPER_PRELUDE) are
+// byte-identical for every script, so every per-script inclusion
+// tags itself with this same URL — devtools' Sources tree groups
+// the N inclusions into a single visible entry alongside the
+// bridge / GM runtime at the SourceMonkey/ top level. See
+// wrapPreludeEntry in injector.ts.
+export const PRELUDE_SOURCE_URL = `${ROOT}/__prelude.js`;
+// Canonical URL for the page-wide MAIN-world bridge.
+export const BRIDGE_SOURCE_URL = `${ROOT}/__bridge.js`;
+// Canonical URL for the page-wide GM_* runtime.
+export const GM_RUNTIME_SOURCE_URL = `${ROOT}/__gm-runtime.js`;
+// Canonical URL for one of a script's `@require` entries. We map
+// the require's real fetch URL into our synthetic scheme so:
+//   - the entry clusters with its owning script in devtools, and
+//   - stack frames are honest about the fact that we stored a
+//     snapshot of the bytes (we're not re-fetching at run time).
+//
+// Shape: `sourcemonkey://SourceMonkey/<folder>/<host>/<path>` — the
+// original URL's host + path become subfolders so the user can still
+// see the provenance in the Sources tree. Query strings and fragments
+// are dropped (the cached bytes don't depend on them). Two requires
+// on the same script with the same host+path but different `?…`
+// query strings would land at the same synthetic URL. The viewer's
+// tab lookup takes the FIRST match, so a mapped stack frame from the
+// second require opens the first require's tab — the source map picks
+// the right segment, only the tab lookup is ambiguous. Rare in
+// practice; the file-loader already dedups by canonical URL with
+// query, so it'd take two legitimately different `@require` lines
+// pointing at distinct stored copies. Worth revisiting if it ever
+// shows up: including a hash of the query in the path would fix it at
+// the cost of an uglier devtools tree.
+//
+// `file://` requires (resolved local files) use the synthetic host
+// `file` so they land under `<folder>/file/<path>` rather than
+// dropping out of the tree.
+//
+// On a URL we can't parse (shouldn't happen — the file-loader
+// validates before storage) we fall back to `<folder>/require` so we
+// still emit *something* parseable.
+export function buildRequireSourceUrl(logLabel, requireUrl) {
+    let host;
+    let path;
+    try {
+        const u = new URL(requireUrl);
+        host = u.protocol === 'file:' ? 'file' : u.hostname;
+        if (!host)
+            host = u.protocol.replace(/:$/, '');
+        path = u.pathname.replace(/^\/+/, '');
+    }
+    catch {
+        return `${scriptRoot(logLabel)}/require`;
+    }
+    // Sanitize each path segment. `new URL()` above already normalized
+    // `a/../b` to `b`, so the `..` / `.` filter is belt-and-suspenders
+    // — kept in case the input ever reaches us by a path that bypasses
+    // URL parsing (it doesn't today). The real work here is the
+    // per-segment character whitelist, which keeps spaces / special
+    // chars from confusing the devtools tree.
+    const cleanPath = path
+        .split('/')
+        .map((seg) => seg.replace(/[^a-zA-Z0-9._-]/g, '_'))
+        .filter((seg) => seg && seg !== '.' && seg !== '..')
+        .join('/');
+    const safeHost = host.replace(/[^a-zA-Z0-9._-]/g, '_') || 'require';
+    return cleanPath
+        ? `${scriptRoot(logLabel)}/${safeHost}/${cleanPath}`
+        : `${scriptRoot(logLabel)}/${safeHost}/require`;
+}

package/lib/script-world.d.ts

@@ -0,0 +1,6 @@
+import { type ParsedHeader } from './userscript-header.js';
+import type { StoredScript } from './script-build.js';
+export type InjectionWorld = 'MAIN' | 'USER_SCRIPT';
+export declare function resolveWorld(header: ParsedHeader | null | undefined): InjectionWorld;
+export declare function resolveScriptWorld(script: Pick<StoredScript, 'header'>): InjectionWorld;
+export declare function runsSandboxed(script: Pick<StoredScript, 'header'>): boolean;

package/lib/script-world.js

@@ -0,0 +1,65 @@
+// Which execution world a script runs in, from its header. Its own
+// module so the harness can ask without loading the injector.
+import { getValue, getValues } from './userscript-header.js';
+import { resolveGrants } from './gm-api-catalog.js';
+// Decide which execution world a script should run in. Like
+// Tampermonkey and Violentmonkey, every script starts in the page's own
+// world (MAIN) and leaves it only when its header asks:
+//
+//   - `@inject-into page`      → MAIN
+//   - `@inject-into content`   → USER_SCRIPT (isolated)
+//   - `@sandbox raw`           → MAIN
+//   - `@sandbox JavaScript`    → MAIN (TM's choice on Chrome too; only
+//                                Firefox has a separate world for it)
+//   - `@sandbox DOM`           → USER_SCRIPT
+//   - anything else, unset, `@inject-into auto` → MAIN
+//
+// `@inject-into` (VM's) is read first when a script has both.
+//
+// Why the page by default: scripts written against TM and VM read the
+// page's globals (its `$`, an app's state, `customElements`) without
+// `unsafeWindow`, since there they are in the page. In USER_SCRIPT world
+// those read as `undefined` and the script silently breaks. Any script
+// but a `@grant none` one still keeps its writes off the page's
+// `window`: it runs in a sandbox `window` (`runsSandboxed` below).
+//
+// What the page costs a script, and why `@inject-into content` exists:
+// see docs/injection.md, "Execution world".
+//
+// `@inject-into content` with `unsafeWindow` (by grant or by use) gets
+// that world's own `window` as `unsafeWindow`, matching Violentmonkey's
+// content mode, plus a startup-log warning; see `extractStartupLogs`.
+export function resolveWorld(header) {
+    if (!header)
+        return 'MAIN';
+    const injectInto = (getValue(header, 'inject-into') ?? '').trim().toLowerCase();
+    if (injectInto === 'page')
+        return 'MAIN';
+    if (injectInto === 'content')
+        return 'USER_SCRIPT';
+    const sandbox = (getValue(header, 'sandbox') ?? '').trim().toLowerCase();
+    if (sandbox === 'dom')
+        return 'USER_SCRIPT';
+    return 'MAIN';
+}
+// The world for a stored row, the form every production caller uses:
+// the spec build, the match index and the reload-swap world check all
+// have to agree.
+export function resolveScriptWorld(script) {
+    return resolveWorld(script.header);
+}
+// Whether the script's user program runs inside a sandbox `window`
+// (the prelude's `sandbox`): a page-world script, unless it has
+// `@grant none`. A script with no `@grant` line at all is sandboxed
+// too, as Tampermonkey 5.5.0 and Violentmonkey 2.49.0 run it
+// (measured). That's how both run a script in the page: bare names
+// reach the page's globals, but the sandbox `window` shows only the
+// browser's built-ins, and the script's own writes, a `@require`d
+// library's `window.jQuery = …` included, stay off the page's
+// `window`. A `@grant none` script gets the page's `window` itself, as
+// under both. See docs/injection.md, "The sandbox window".
+export function runsSandboxed(script) {
+    if (!script.header || resolveScriptWorld(script) !== 'MAIN')
+        return false;
+    return !resolveGrants(getValues(script.header, 'grant')).hasNone;
+}