sourcemonkey 0.0.0-stage → 0.5.0

package/dist/userscript-header.js

@@ -0,0 +1,248 @@
+// Parser for the Tampermonkey-style metadata block at the top of a
+// userscript:
+//
+//   // ==UserScript==
+//   // @name        Hello
+//   // @match       https://example.com/*
+//   // @grant       none
+//   // ==/UserScript==
+//
+// We return a flat list of `{tag, locale?, value}` entries in source
+// order so callers can decide which tags are single-valued (@name,
+// @version) and which can repeat (@match, @grant, @require, …) without
+// the parser baking that policy in. Tag names are lowercased so lookups
+// are case-insensitive; locales like `@name:de` are kept on the side.
+// Every line-terminator shape the metadata-block scanner recognizes.
+// One definition so "which line is this tag on?" is counted by exactly
+// the rule the block is split by — count and split disagreeing is how
+// every header diagnostic in a DOS or classic-Mac file ends up one line
+// off.
+//
+// Deliberately NOT the same set as `countLines` in composed-source.ts,
+// which adds U+2028/U+2029 because V8 treats them as terminators. Those
+// can't appear in a metadata line anyway (`TAG_LINE`'s `.` doesn't
+// match them), and widening the split here would change what this
+// long-standing parser considers a line.
+const LINE_BREAK = /\r\n|\r|\n/;
+const LINE_BREAK_G = /\r\n|\r|\n/g;
+function countLineBreaks(text) {
+    return text.match(LINE_BREAK_G)?.length ?? 0;
+}
+// A marker line is `//`, optional spaces or tabs, then the marker, with
+// anything before or after it on the line, as VM matches it. GreasyFork
+// serves scripts opening with `/// ==UserScript==` or closing with
+// `// ==/UserScript==////`, and TM and VM both install them. Each match
+// takes the whole line, so text after a closing marker (part of that
+// comment) stays in the header rather than starting the body.
+//
+// `[^\r\n]` and a lookbehind rather than `/m` with `.`, `^` and `$`:
+// those also break at U+2028/U+2029, which `LINE_BREAK` deliberately
+// doesn't treat as line breaks.
+const BLOCK_START = /(?<![^\r\n])[^\r\n]*?\/\/[ \t]*==UserScript==[^\r\n]*/;
+const BLOCK_END = /(?<![^\r\n])[^\r\n]*?\/\/[ \t]*==\/UserScript==[^\r\n]*/;
+// Strip a single leading UTF-8 BOM. Most fetch paths (`response.text()`,
+// `TextDecoder`) drop it for us, but the page-context `file://` XHR path
+// (`directories.ts`) hands back `xhr.responseText` with the BOM intact.
+// The marker regexes would take it as text before the `//` on line 1,
+// leaving it in `headerText` (and GM_info's metadata string) rather than
+// dropped. The BOM only ever appears at file position 0.
+function stripLeadingBom(source) {
+    return source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+}
+// The ways the split can fail, as the text a user reads.
+//
+// Named constants rather than inline literals because these strings are
+// both the message and the value something compares against — today the
+// corpus validator, which groups failures by message. A reworded
+// literal would silently stop matching.
+//
+// Phrased to read correctly in all three places they appear: alone in
+// the viewer's message bar, alone in the Log tab, and after the
+// preview's `This file cannot be installed: ` prefix. Capitalized and
+// unpunctuated per docs/diagnostics.md#wording; that still rules out a
+// bare fragment like `No metadata block`, which needs a subject.
+export const NO_METADATA_BLOCK = 'No // ==UserScript== metadata block, so this is not a userscript';
+// The fix is phrased as a need rather than an instruction ("it needs",
+// not "add"): this message carries a location, so it renders as
+// `… — add a … line (in f.user.js, line 1)`, where the parenthetical
+// reads as *where to add it*. Line 1 is where the block opened.
+export const UNTERMINATED_METADATA_BLOCK = 'The // ==UserScript== metadata block is never closed and needs a // ==/UserScript== line';
+// A file with no userscript block but a `/* ==UserStyle==` one is a
+// user style (CSS for a style manager extension, not a userscript).
+// GreasyFork lists them alongside userscripts, so naming what the file
+// is beats calling it "not a userscript".
+export const USERSTYLE_NOT_SUPPORTED = 'This is a user style (a /* ==UserStyle== block), not a userscript. User styles need a user style manager extension.';
+const USERSTYLE_START = /\/\*[ \t]*==UserStyle==/;
+// Split a userscript source into the (rare) text above the metadata
+// block, the raw metadata block itself, and the body text.
+//
+// Failure modes:
+//   - no `==UserScript==` line          → NO_METADATA_BLOCK, or
+//     USERSTYLE_NOT_SUPPORTED when there's a `/* ==UserStyle==` instead
+//   - open marker but no matching close → UNTERMINATED_METADATA_BLOCK
+// In every case we return leadingText = '', headerText = '', and
+// bodyText = the whole source so callers always have something to
+// display.
+export function splitHeaderBody(source) {
+    source = stripLeadingBom(source);
+    const startMatch = BLOCK_START.exec(source);
+    if (!startMatch) {
+        const error = USERSTYLE_START.test(source) ? USERSTYLE_NOT_SUPPORTED : NO_METADATA_BLOCK;
+        return { leadingText: '', headerText: '', bodyText: source, error };
+    }
+    const headerStartLine = countLineBreaks(source.slice(0, startMatch.index)) + 1;
+    const afterStart = source.slice(startMatch.index + startMatch[0].length);
+    const endMatch = BLOCK_END.exec(afterStart);
+    if (!endMatch) {
+        return {
+            leadingText: '',
+            headerText: '',
+            bodyText: source,
+            error: UNTERMINATED_METADATA_BLOCK,
+            headerStartLine,
+        };
+    }
+    const blockEnd = startMatch.index + startMatch[0].length + endMatch.index + endMatch[0].length;
+    // Skip a single trailing newline after the closing marker so bodyText
+    // doesn't start with a stray blank line.
+    let bodyStart = blockEnd;
+    if (source[bodyStart] === '\r')
+        bodyStart++;
+    if (source[bodyStart] === '\n')
+        bodyStart++;
+    return {
+        leadingText: source.slice(0, startMatch.index),
+        headerText: source.slice(startMatch.index, blockEnd),
+        bodyText: source.slice(bodyStart),
+        headerStartLine,
+    };
+}
+// One metadata line: `// @tag[:locale][ value]`. The value group is
+// `.*\S` so trailing whitespace is excluded; the whole value group is
+// optional so flag tags like `@noframes` parse with value = "".
+const TAG_LINE = /^[ \t]*\/\/[ \t]*@([A-Za-z][\w-]*)(?::([\w-]+))?(?:[ \t]+(.*\S))?[ \t]*$/;
+// Reassemble the original on-disk source from the three parts
+// produced by `splitHeaderBody`. The reassembly is line-for-line
+// faithful so that an error reported on injected line N also points
+// at line N of this reconstructed string (which is what the viewer
+// shows in the main tab).
+//
+// The `'\n'` between `headerText` and `bodyText` restores the line
+// break `splitHeaderBody` skipped past the closing marker; with no
+// metadata block, both `leadingText` and `headerText` are empty so
+// the body is returned verbatim.
+export function joinFullSource(leadingText, headerText, bodyText) {
+    if (!headerText)
+        return leadingText + bodyText;
+    return leadingText + headerText + '\n' + bodyText;
+}
+// Parse the metadata block. Returns null if there is no
+// `==UserScript==` / `==/UserScript==` pair.
+export function parseHeader(source) {
+    source = stripLeadingBom(source);
+    const startMatch = BLOCK_START.exec(source);
+    if (!startMatch)
+        return null;
+    const afterStart = source.slice(startMatch.index + startMatch[0].length);
+    const endMatch = BLOCK_END.exec(afterStart);
+    if (!endMatch)
+        return null;
+    const block = afterStart.slice(0, endMatch.index);
+    const startLine = countLineBreaks(source.slice(0, startMatch.index)) + 1;
+    const tags = [];
+    // Split on every line-terminator shape — `\r\n` (DOS), `\n` (Unix),
+    // and bare `\r` (classic Mac). `splitHeaderBody`'s marker regexes
+    // stop at all three too, so we keep parity here.
+    //
+    // `block` begins with the terminator that ended the `==UserScript==`
+    // line, so element 0 is always the empty remainder of that line and
+    // element i is `startLine + i` — no off-by-one correction needed.
+    for (const [i, rawLine] of block.split(LINE_BREAK).entries()) {
+        const m = TAG_LINE.exec(rawLine);
+        if (!m)
+            continue;
+        const [, tag, locale, value] = m;
+        const entry = {
+            tag: tag.toLowerCase(),
+            value: value ?? '',
+            line: startLine + i,
+        };
+        if (locale)
+            entry.locale = locale;
+        tags.push(entry);
+    }
+    return { tags, startLine };
+}
+// First non-localized value for `tag`, or undefined.
+export function getValue(header, tag) {
+    const t = tag.toLowerCase();
+    for (const e of header.tags) {
+        if (e.tag === t && e.locale === undefined)
+            return e.value;
+    }
+    return undefined;
+}
+// All non-localized values for `tag`, in source order.
+export function getValues(header, tag) {
+    const t = tag.toLowerCase();
+    const out = [];
+    for (const e of header.tags) {
+        if (e.tag === t && e.locale === undefined)
+            out.push(e.value);
+    }
+    return out;
+}
+// Map of locale → value for tags like `@name:de`. Excludes the
+// unlocalized form.
+export function getLocalized(header, tag) {
+    const t = tag.toLowerCase();
+    const out = {};
+    for (const e of header.tags) {
+        if (e.tag === t && e.locale !== undefined)
+            out[e.locale] = e.value;
+    }
+    return out;
+}
+// True if the tag appears at all (useful for flag-style tags like
+// `@noframes` or `@unwrap`).
+export function hasTag(header, tag) {
+    const t = tag.toLowerCase();
+    return header.tags.some((e) => e.tag === t);
+}
+// The `@run-at` values that pick a point in the page load. Anything
+// else (a typo) runs at `document-idle`: see `normalizeDeclaredRunAt`
+// in injector.ts. The exception is `context-menu`, which makes the
+// script manual instead (see `CONTEXT_MENU_RUN_AT`).
+export const SUPPORTED_RUN_AT = [
+    'document-start',
+    'document-body',
+    'document-end',
+    'document-idle',
+];
+// The script's declared `@run-at` when it is one we don't honor, so
+// the caller can say it runs at `document-idle` instead. Undefined when
+// the tag is absent, blank, supported, or `context-menu`.
+export function unsupportedRunAt(header) {
+    if (!header)
+        return undefined;
+    const value = (getValue(header, 'run-at') ?? '').trim();
+    if (value === '' || SUPPORTED_RUN_AT.includes(value.toLowerCase()))
+        return undefined;
+    if (value.toLowerCase() === CONTEXT_MENU_RUN_AT)
+        return undefined;
+    return value;
+}
+// Tampermonkey's `@run-at context-menu`: don't run on page load, run
+// from a right-click menu item instead. We call these manual scripts:
+// they match pages as usual, but run only when the person picks "Run
+// this script" in the popup (or sm-dev fires it). See
+// docs/manual-scripts.md.
+export const CONTEXT_MENU_RUN_AT = 'context-menu';
+// The command that runs a manual script now: first in its popup row,
+// and in sm-dev's `menu`.
+export const RUN_SCRIPT_LABEL = 'Run this script';
+export function isContextMenuRunAt(header) {
+    if (!header)
+        return false;
+    return (getValue(header, 'run-at') ?? '').trim().toLowerCase() === CONTEXT_MENU_RUN_AT;
+}