sourcemonkey 0.0.0-stage → 0.5.0

package/dist/markup-response.js

@@ -0,0 +1,126 @@
+// Recognizing an HTML page served where JavaScript was expected.
+//
+// The failure this catches is a *soft* one: the request succeeded, the
+// status was 200, and the bytes are a perfectly good web page — just
+// not the script we asked for. Left alone it flows onward and is
+// reported as a syntax error in the user's script, which blames the
+// wrong file. The classic shapes:
+//   - a forge's file-browser page (`github.com/<o>/<r>/blob/…`) instead
+//     of the raw bytes;
+//   - a login / SSO wall or captive portal answering at 200;
+//   - a `@require` URL that has rotted into a 200-with-error-page;
+//   - a local *directory* whose name matches the ref — Chrome answers
+//     `file://` directory reads with a generated HTML listing.
+//
+// Two independent tests, because each catches what the other misses:
+//   - `isMarkupContentType` — the server told us. Free, and right even
+//     when the body is unreadable.
+//   - `looksLikeMarkup` — the bytes tell us. Needed when there is no
+//     Content-Type at all (the `file://` XHR leg often has none) or the
+//     server mislabels HTML as `text/plain`.
+//
+// Deliberately NOT applied to `@resource` (an HTML resource is a
+// legitimate thing to fetch and hand to `GM_getResourceText`), to
+// `@icon` (already gated on `image/*`), or to `file://` directory
+// listings (which are HTML *by design* — see `parseListing` in
+// directories.ts). The rule is "this text is about to be treated as
+// JavaScript", not "this text arrived over the network".
+//
+// See [docs/requires.md] "Markup gate" for the two tests written up
+// together, plus [docs/install-capture.md] and [docs/diagnostics.md].
+// True for the Content-Type families that mean markup. A denylist, not
+// an allowlist: `application/octet-stream` and friends are common and
+// legitimate for JavaScript (GitHub serves every release asset that
+// way), so only the types that can't be a script are rejected.
+// `text/html-sandboxed` is caught by the prefix and deserves to be;
+// XHTML is spelled `application/xhtml+xml`, so it needs its own clause
+// to match the same intent.
+//
+// `application/json` is deliberately absent: a JSON error envelope at
+// 200 is a real soft-failure shape, but so is a legitimate JS module
+// served by a mislabelling host, and the eval-side try/catch already
+// contains the damage.
+//
+// Trims defensively so the rule holds for a caller that hands over a
+// raw header rather than the lowercased/trimmed one every producer in
+// file-loader.ts passes.
+export function isMarkupContentType(contentType) {
+    const type = contentType.trim().toLowerCase();
+    return type.startsWith('text/html') || type.startsWith('application/xhtml');
+}
+// True when the text itself is a markup document: the first thing in
+// it, past any BOM and leading whitespace, is `<`.
+//
+// Why the FIRST character and not "does it contain HTML" — a forge's
+// blob page embeds the file's own lines, metadata block and all, so a
+// search anywhere in the body finds `// ==UserScript==` and concludes
+// the page IS the script. Position is the only reliable signal, and it
+// is exactly the signal a served `.js` file gives: JavaScript starts
+// with code or a comment, never with a tag.
+//
+// The check is on the leading character, not on the metadata block's
+// position, because a script may legitimately carry leading text — a
+// license banner above the block is common, is preserved
+// (`leadingText`, userscript-header.ts), and must keep working.
+//
+// Known false positive, accepted: `<!--` at the very top of a file is
+// valid JavaScript (Annex B HTML-like comments), so a script opening
+// with one is called markup. That spelling belongs to 1990s inline
+// `<script>` blocks and does not occur in userscripts.
+export function looksLikeMarkup(text) {
+    // A leading BOM needs no special handling: ECMAScript's `WhiteSpace`
+    // production includes U+FEFF, so `\s` matches it here exactly as
+    // `trim` would. (`userscript-header.ts` strips one explicitly for a
+    // different reason — a `/m` regex's `^` won't match past it.)
+    //
+    // Anchored regex rather than `trimStart().startsWith('<')`: the
+    // rejected inputs are whole web pages, and trimming one allocates a
+    // second copy of it to look at a single character.
+    return /^\s*</.test(text);
+}
+// The one wording for "we got a web page instead of JavaScript",
+// shared by every caller so the same problem never gets two spellings.
+//
+// `localUrl` splits it into two sentences on purpose: blaming the
+// server when the bytes came off local disk would be a flatly wrong
+// diagnosis, and the common way to hit the local case is a directory
+// whose name matches the ref.
+//
+// `contentType` is the *evidence*, not decoration — pass it only when
+// the header is what proved this, and leave it out when the body did.
+// A parenthetical reading `(Content-Type "text/plain")` next to a
+// claim that the response is HTML reads as a contradiction.
+//
+// `expected` names what we wanted instead. Almost always JavaScript,
+// but the same fetcher reads collection manifests, and telling someone
+// their manifest isn't JavaScript names the wrong thing.
+export function markupResponseMessage(opts = {}) {
+    const evidence = opts.contentType ? ` (Content-Type "${opts.contentType}")` : '';
+    const expected = opts.expected ?? 'JavaScript';
+    return opts.localUrl
+        ? `${LOCAL_MARKUP_PREFIX}${opts.localUrl}${LOCAL_MARKUP_MIDDLE}${expected}${evidence}; a folder with that name would look like this`
+        : `${REMOTE_MARKUP_PREFIX}${expected}${evidence}; the link may be dead or behind a login`;
+}
+const REMOTE_MARKUP_PREFIX = 'The server returned an HTML page, not ';
+const LOCAL_MARKUP_PREFIX = 'The local file ';
+const LOCAL_MARKUP_MIDDLE = ' is an HTML page, not ';
+// Did this text come out of `markupResponseMessage`? For the corpus
+// validator, which tags each invalid script with why it failed.
+export function isMarkupResponseMessage(text) {
+    return text.startsWith(REMOTE_MARKUP_PREFIX)
+        || (text.startsWith(LOCAL_MARKUP_PREFIX) && text.includes(LOCAL_MARKUP_MIDDLE));
+}
+// Thrown by the script-text fetchers so a caller can tell this apart
+// from every other read failure without matching on wording (which
+// docs/diagnostics.md forbids, and which would go stale the first time
+// the message is reworded).
+//
+// The preview is the caller that cares: for a captured navigation,
+// "this is a web page" is not an error to report but a sign the
+// capture should never have fired, so it continues to the page instead.
+export class MarkupResponseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MarkupResponseError';
+    }
+}

package/dist/match-targets.js

@@ -0,0 +1,305 @@
+// Pure helpers for converting a Chrome `@match` pattern into a
+// "target" the rest of the app can act on: the pattern's representative
+// origin and a click-through / page URL (the same URL serves both
+// purposes — favicon HTML discovery and open-in-new-tab click).
+//
+// Used by:
+//   - site-icon.ts — takes `representativeMatches(matching)` (the
+//     first few distinct sites) to drive favicon discovery (origin
+//     caching, page URL for HTML probe, click target) — one icon per
+//     site.
+//   - script-details.ts / code-links.ts — call `matchTargetInfo(pattern)`
+//     per-pattern when linkifying `@match`/`@exclude`/`@include` values,
+//     falling back to `sameDirLinkUrl` for patterns that name no site.
+//
+// No fetching, no DOM, no chrome.storage — that all lives in the
+// modules that consume these primitives.
+import { canonicalMatchPatterns } from './url-match.js';
+// Pure regex rewrite, no fetching — imported so the same-directory
+// fallback below points a github-hosted script's neighbour at the
+// github.com page instead of its raw bytes.
+import { githubRawToBlobUrl } from './github-urls.js';
+// Pull a Chrome match pattern apart and dewildcard its host. Returns
+// null when the pattern can't identify a single site (`<all_urls>`,
+// host of `*`, non-http(s) schemes, embedded `*` after dewildcard,
+// or syntactically invalid).
+//
+// Port handling: an explicit `:port` in the pattern is preserved
+// verbatim. The favicon almost certainly is served from the same
+// port the page is on (`localhost:3000`, a dev server, etc.), and
+// the cache key needs to include the port to avoid collisions
+// between two different servers sharing a hostname on different
+// ports. Patterns without a port stay portless — the icon resolver
+// will hit the default port, which is the right behavior for the
+// common case.
+function parseMatchPattern(pattern) {
+    if (pattern === '<all_urls>')
+        return null;
+    // Read the pattern the way the matcher and the registration do — a
+    // scheme-less `*.example.com/*` names a site, and should get an icon
+    // and a click-through like any other. An expansion only varies the
+    // scheme, and this picks one representative origin, so prefer a form
+    // that isn't `http://`: `*` is read as https below, and a port-pinned
+    // `*://host:8443/*` (which canonicalizes to the http + https pair)
+    // must keep pointing at the https member — fetching the icon over
+    // http would fail on a TLS-only port.
+    const canonical = canonicalMatchPatterns(pattern);
+    const preferred = canonical.find((p) => !p.startsWith('http://')) ?? canonical[0] ?? pattern;
+    const parts = /^(\*|https?|file|ftp):\/\/([^/]*)(\/.*)?$/i.exec(preferred);
+    if (!parts)
+        return null;
+    const [, rawScheme, rawHost] = parts;
+    const scheme = rawScheme === '*' ? 'https' : rawScheme.toLowerCase();
+    if (scheme !== 'http' && scheme !== 'https')
+        return null;
+    // Split host:port so the host-wildcard rules apply only to the
+    // host portion. A numeric port is preserved verbatim. A `:*` port
+    // (any port) covers the default one, so the icon comes from there.
+    const colon = rawHost.lastIndexOf(':');
+    const hasPort = colon > 0 && /^(\d+|\*)$/.test(rawHost.slice(colon + 1));
+    const port = hasPort && rawHost.slice(colon + 1) !== '*' ? rawHost.slice(colon) : '';
+    let host = (hasPort ? rawHost.slice(0, colon) : rawHost).toLowerCase();
+    if (host === '*' || host === '')
+        return null;
+    if (host.startsWith('*.'))
+        host = host.slice(2);
+    if (!host || host.includes('*'))
+        return null;
+    // `.tld` means "any public suffix" (see url-match.ts); `.com` is
+    // the one most such sites answer on, so the icon and link use it.
+    if (host.endsWith('.tld'))
+        host = host.slice(0, -4) + '.com';
+    // The host slot has to hold a host we could actually navigate to.
+    // Worth checking since the scheme-less reading above will supply a
+    // scheme for any text at all (`not a pattern` → `*://not a pattern`),
+    // and this origin becomes a fetch and an href.
+    try {
+        new URL(`${scheme}://${host}${port}/`);
+    }
+    catch {
+        return null;
+    }
+    return { scheme, host: host + port, path: parts[3] ?? '/' };
+}
+export function originFromMatchPattern(pattern) {
+    const p = parseMatchPattern(pattern);
+    return p ? `${p.scheme}://${p.host}` : null;
+}
+// Iterate `matching.matches` and return the first origin we can
+// extract. Input is `@match`-only by construction (`@include` /
+// `@exclude` live in separate fields on `UrlMatching`); we'd skip
+// them here anyway since they're free-form globs/regexes over the
+// whole URL, not URL templates.
+export function representativeOrigin(matching) {
+    return representativeMatch(matching)?.origin ?? null;
+}
+// Like representativeOrigin, but also yields a representative URL —
+// the page to fetch for icon discovery AND the click-through target.
+// Built segment-aware (see `linkPathFromMatchPath`):
+//   https://example.com/*              → /
+//   https://example.com/app/home/*     → /app/home/
+//   https://example.com/posts/*/edit   → /posts/
+//   https://example.com/foo/bar*       → /foo/bar
+export function representativeMatch(matching) {
+    return representativeMatches(matching, 1)[0] ?? null;
+}
+// How many distinct sites a script's icon slot shows by default — the
+// collections-table limit, where the slot sits in a column beside the
+// name. The viewer heading has room for more and passes its own.
+export const MAX_SITE_ICONS = 3;
+// The first `limit` DISTINCT sites named by `matching.matches`, in
+// header order. Two patterns are the same site when their hosts match
+// after dropping a leading `www.`; the scheme is ignored, so
+// `http://www.example.com/*` and `https://example.com/*` yield one
+// entry (the first seen). Ports still distinguish — `localhost:3000`
+// and `localhost:8080` are different servers with different icons.
+export function representativeMatches(matching, limit = MAX_SITE_ICONS) {
+    const out = [];
+    const seen = new Set();
+    for (const m of matching.matches) {
+        if (out.length >= limit)
+            break;
+        const got = matchTargetInfo(m);
+        if (!got)
+            continue;
+        const key = siteKey(got.origin);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(got);
+    }
+    return out;
+}
+// Identity of a site for the purpose of "one icon per site": the
+// host[:port] with a leading `www.` removed and the scheme dropped.
+function siteKey(origin) {
+    const host = origin.slice(origin.indexOf('://') + 3).toLowerCase();
+    return host.startsWith('www.') ? host.slice(4) : host;
+}
+// Per-pattern variant of `representativeMatch`. The linkifier calls
+// this once per `@match`/`@exclude`/`@include` value rather than
+// taking the first usable one.
+export function matchTargetInfo(pattern) {
+    const p = parseMatchPattern(pattern);
+    if (!p)
+        return null;
+    const origin = `${p.scheme}://${p.host}`;
+    const linkUrl = origin + linkPathFromMatchPath(p.path);
+    return { origin, linkUrl };
+}
+// Fallback for patterns that name no site: link to a page sitting in
+// the same directory as the script itself. Full rule, worked examples
+// and rationale in docs/script-viewer.md#same-directory-fallback; in
+// short, a pattern with no host whose literal trailing directories
+// (and any literal text ending a wildcard directory, like `*gm-menu`)
+// match the tail of the script's own directory D links to D + its
+// filename.
+//
+// It exists for the site-less patterns a script uses to name the page
+// it ships beside, such as:
+//
+//   @match *://*/gm-menu/gm-menu.html
+//   @match *://*/*gm-menu/gm-menu.html
+//   @match file:///*/gm-menu/gm-menu.html
+//
+// None yields a target above (the `*://` ones have a host of `*`, the
+// other a `file:` scheme), so their rows rendered as plain text even
+// though the page is sitting next to the script we're viewing.
+//
+// Two properties worth keeping in mind when editing:
+//   - The result is D plus one literal filename, so no pattern can
+//     walk out of the script's own directory.
+//   - Existence is never checked, so a script linkifies identically
+//     whether it was loaded from disk or from a server.
+export function sameDirLinkUrl(pattern, scriptUrl) {
+    if (!scriptUrl)
+        return null;
+    // Only the schemes a site-less pattern is written with. Anchoring
+    // the scheme (rather than accepting any `x://`) keeps
+    // `/^https?:\/\/x/`-style regex literals — legal in `@include` /
+    // `@exclude` — out of here, and `https?\*?` admits the
+    // `http*://` shorthand those tags are often written with.
+    const parts = /^(?:\*|https?\*?|file):\/\/([^/]*)(\/.*)$/i.exec(pattern.trim());
+    if (!parts)
+        return null;
+    const [, host, path] = parts;
+    if (host !== '' && host !== '*')
+        return null;
+    const segments = path.split('/').slice(1);
+    const filename = segments.pop() ?? '';
+    // A query or fragment means the page is parametrised, not a plain
+    // file next door — and `?` is legal in a `@match` path glob
+    // (`ol.php?type=precip*`), so it has to be rejected explicitly
+    // rather than left to the extension check.
+    if (!filename || /[*?#]/.test(filename) || !/\.[A-Za-z0-9]+$/.test(filename))
+        return null;
+    // Everything at or before the last wildcard segment is absorbed by
+    // that wildcard; what follows has to be matched literally.
+    // (A hand-rolled findLastIndex — the project's lib target predates it.)
+    let lastWildcard = -1;
+    segments.forEach((seg, i) => {
+        if (seg.includes('*'))
+            lastWildcard = i;
+    });
+    const literalDirs = segments.slice(lastWildcard + 1);
+    // The text after that segment's last `*` (`gm-menu` in `*gm-menu`)
+    // still has to end the directory the wildcard stands in for.
+    const wildSuffix = lastWildcard < 0
+        ? ''
+        : segments[lastWildcard].slice(segments[lastWildcard].lastIndexOf('*') + 1);
+    if (literalDirs.length === 0 && !wildSuffix)
+        return null;
+    if (literalDirs.some((s) => s === ''))
+        return null;
+    const dir = scriptDirUrl(scriptUrl);
+    if (!dir)
+        return null;
+    const dirSegments = dir.pathname.split('/').filter(Boolean).map(decodeSegment);
+    const needed = literalDirs.length + (wildSuffix ? 1 : 0);
+    if (dirSegments.length < needed)
+        return null;
+    const tail = dirSegments.slice(dirSegments.length - literalDirs.length);
+    if (tail.some((seg, i) => seg !== decodeSegment(literalDirs[i])))
+        return null;
+    if (wildSuffix
+        && !dirSegments[dirSegments.length - needed].endsWith(decodeSegment(wildSuffix))) {
+        return null;
+    }
+    // Resolved through the URL parser rather than concatenated, so a
+    // filename carrying a space or other raw character is escaped the
+    // same way the directory around it already is. Safe against
+    // traversal: the checks above leave a filename with no `/`.
+    let href;
+    try {
+        href = new URL(filename, dir).href;
+    }
+    catch {
+        return null;
+    }
+    // Same reasoning as `collectionClickUrl`: a github collection fetches
+    // `raw.githubusercontent.com`, which serves HTML as `text/plain`, so
+    // the raw neighbour of a script is a plaintext dump. Humans clicking
+    // want the github.com page — the same URL the Location row shows.
+    return githubRawToBlobUrl(href) ?? href;
+}
+// The script's parent directory as a URL ending in `/`. Only the
+// schemes a script can be loaded from — the href becomes an anchor.
+function scriptDirUrl(scriptUrl) {
+    try {
+        const dir = new URL('.', scriptUrl);
+        if (!['http:', 'https:', 'file:'].includes(dir.protocol))
+            return null;
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
+// A directory read off a URL is percent-encoded; the same directory
+// written into a `@match` pattern usually isn't. Compare both decoded
+// so `my dir` and `my%20dir` are the same segment.
+function decodeSegment(seg) {
+    try {
+        return decodeURIComponent(seg);
+    }
+    catch {
+        return seg;
+    }
+}
+// Build the click-through path for a `@match` pattern. Walk segments
+// left-to-right and stop at the first one containing a `*`:
+//
+//   - Last segment, `*` at the end with a non-empty literal prefix
+//     (`foo*`, `ol.php?type=precip*`): keep the literal prefix
+//     verbatim. The user is targeting one specific page parametrised
+//     on the tail, so the prefix typically is the real URL minus a
+//     fragment and navigating to it works.
+//   - Otherwise (whole-segment wildcard, mid-segment wildcard, or
+//     wildcard segment followed by more path): trim back to the last
+//     clean directory boundary — a partial prefix in the middle of a
+//     path isn't likely to navigate, but the parent directory often
+//     does.
+//
+// Pure-literal paths (no `*` anywhere) pass through unchanged.
+export function linkPathFromMatchPath(path) {
+    const segments = path.split('/');
+    const kept = [];
+    for (let i = 1; i < segments.length; i++) {
+        const seg = segments[i];
+        const star = seg.indexOf('*');
+        if (star < 0) {
+            kept.push(seg);
+            continue;
+        }
+        const isLastSegment = i === segments.length - 1;
+        const starAtSegmentEnd = star === seg.length - 1;
+        if (isLastSegment && starAtSegmentEnd && star > 0) {
+            kept.push(seg.slice(0, star));
+            return '/' + kept.join('/');
+        }
+        // Trailing slash when we kept at least one full segment; bare `/`
+        // when the wildcard segment was the first one.
+        return '/' + (kept.length ? kept.join('/') + '/' : '');
+    }
+    return '/' + kept.join('/');
+}

package/dist/menu-captions.js

@@ -0,0 +1,22 @@
+// Which of a script's menu commands show, shared by the worker's
+// registry (`gm-menu.ts`) and sm-dev's `menu` listing.
+//
+// As in TM: a script's commands with one caption show once in a tab,
+// however many times it registered that caption (each with its own id)
+// and in however many of the tab's frames. Picking the entry runs all of
+// them (`menuCommandGroup` in `gm-menu.ts`). Every registration is kept,
+// so unregistering one leaves the entry for the rest. The entry shows
+// the caption's first registration, so the menu doesn't reorder.
+//
+// `key` says which commands share an entry: the caller's list may hold
+// several scripts' commands, which never merge.
+export function visibleCommands(list, key) {
+    const seen = new Set();
+    return list.filter((command) => {
+        const k = key(command);
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}

package/dist/offscreen.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>SourceMonkey offscreen host</title>
+</head>
+<body>
+<!--
+  Offscreen document: the extension's only way to get a DOM without a
+  visible tab. It exists solely to embed the sandboxed parse page and
+  relay messages to it, because the two halves each lack something the
+  other has:
+
+    - The service worker can call `chrome.*` but has no DOM, so it
+      cannot host an iframe — and its CSP forbids `eval`.
+    - The sandboxed page may use `eval` (so it can compile) but has an
+      opaque origin and no `chrome.*`, so the service worker cannot
+      message it directly.
+
+  This document has both a DOM and `chrome.runtime`, so it bridges
+  them: `chrome.runtime.onMessage` in, `postMessage` to the iframe,
+  and back.
+
+  The iframe is `src`-loaded rather than `srcdoc` so it resolves to the
+  URL declared in the manifest's `sandbox.pages` list — a srcdoc frame
+  would inherit this document's CSP and lose the `'unsafe-eval'` that
+  is the entire point.
+-->
+<!--
+  The `sandbox` attribute is belt-and-braces. The page is already
+  sandboxed by the manifest's `sandbox.pages` key; if that key were
+  ever dropped in an edit, this attribute keeps the frame from
+  silently becoming a fully privileged extension page with `chrome.*`
+  available to whatever it compiles.
+-->
+<iframe id="parse-sandbox" src="parse-sandbox.html" sandbox="allow-scripts"></iframe>
+<script type="module" src="extension/offscreen.js"></script>
+</body>
+</html>