sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/prism-userscript.js

@@ -0,0 +1,53 @@
+"use strict";
+// Prism grammar extension for the `// ==UserScript== … //
+// ==/UserScript==` metadata block.
+//
+// Importing this module is what installs the grammar — it runs the
+// `insertBefore` at load. It lives next to the code that depends on it
+// (`code-tabs.ts` calls `Prism.highlightElement`, `code-links.ts` keys
+// its header linkification off the token classes below), so a page
+// that reuses the tabbed code view can't end up with the extension
+// silently missing.
+//
+// The outer token keeps the `comment` alias so any non-tag line inside
+// the block still reads as comment-grey. Inner tokens use existing
+// Prism theme classes via `alias`:
+//   - markers (`==UserScript==`, `==/UserScript==`, sans `//`) → `bold`
+//   - `@tag` names → `constant` (matches identifier color in the body)
+//   - values after the tag → `string` (matches string-literal color)
+// Order inside matters: `header-tag-value` must run before
+// `header-tag-name`, because the value's lookbehind needs the `@tag`
+// substring to still be present in the unconsumed text when it scans.
+Prism.languages.insertBefore('javascript', 'comment', {
+    'userscript-header': {
+        // Trailing `[ \t]*\r?\n?` swallows whitespace + the line-terminating
+        // newline after `==/UserScript==` (CRLF and LF). We need the
+        // newline inside the span because we render the span as
+        // `display: block` for the tinted band, and a newline left in
+        // the text node *after* the block would render as an extra blank
+        // line on top of the block break the browser already inserts.
+        pattern: /\/\/[ \t]*==UserScript==[\s\S]*?\/\/[ \t]*==\/UserScript==[ \t]*\r?\n?/,
+        alias: 'comment',
+        inside: {
+            'header-marker': {
+                pattern: /(\/\/[ \t]*)==\/?UserScript==/,
+                lookbehind: true,
+                alias: 'bold',
+            },
+            'header-tag-value': {
+                // `[^\r\n]*` (not `[^\n]*`) so a CRLF file doesn't sweep the
+                // line-terminating `\r` into the value span, which would
+                // leak a trailing `\r` into anchor hrefs / `matchTargetInfo`
+                // input downstream.
+                pattern: /(\/\/[ \t]*@[A-Za-z][\w-]*(?::[\w-]+)?[ \t]+)\S[^\r\n]*/,
+                lookbehind: true,
+                alias: 'string',
+            },
+            'header-tag-name': {
+                pattern: /(\/\/[ \t]*)@[A-Za-z][\w-]*(?::[\w-]+)?/,
+                lookbehind: true,
+                alias: 'constant',
+            },
+        },
+    },
+});

package/dist/extension/refresh-error.js

@@ -0,0 +1,136 @@
+// Per-collection record of a refresh that could not be SAVED.
+//
+// A distinct failure from `scanError`, and the distinction is the point:
+//
+//   - `scanError` (on the collection row) means we couldn't list the
+//     collection. Nothing was fetched, every script row is left exactly
+//     as it was, and the reason is written next to the collection it
+//     belongs to.
+//   - This map means the listing and every fetch SUCCEEDED and the
+//     write at the end is what failed. The scripts on disk and the rows
+//     in storage now disagree, and nothing in `chrome.storage.local`
+//     records that — because the write to `chrome.storage.local` is
+//     precisely what didn't work.
+//
+// The motivating case is an exhausted `chrome.storage.local` quota
+// (10 MB, shared by the whole extension — see [docs/storage.md]). A
+// collection large enough to blow the budget fails at the write on
+// every refresh, and before this map the user got a Refresh button that
+// went busy, came back, and said nothing at all.
+//
+// Why `chrome.storage.session`:
+//   - It is a SEPARATE quota from `chrome.storage.local`, so it still
+//     has room in the exact situation this exists to report. (A
+//     rejected write also consumes nothing, so the budget the failed
+//     refresh would have needed is still free either way — but not
+//     sharing the failing bucket is what makes that reliable rather
+//     than merely likely.)
+//   - The lifetime is right. "Your last refresh didn't save" describes
+//     this session's attempt, not a property of the collection. A new
+//     browser session re-refreshes from scratch, and a stale banner
+//     about a write that a later run may well have completed would be
+//     worse than none.
+//   - It outlives the service worker, which MV3 evicts freely.
+//
+// Shaped as one map key rather than a key per collection for the same
+// reason as `injector-rejections` (`src/extension/script-rejection.ts`): the set
+// is small, the readers want all of it, and a single key means one
+// `storage.onChanged` event rather than a fan-out.
+import { assertWorkerContext } from '../run-context.js';
+// Session-storage key holding the whole `RefreshErrorMap`.
+export const REFRESH_ERRORS_KEY = 'refresh-errors';
+// The one sentence for a refresh that couldn't be saved, shared by the
+// two surfaces that report the failure itself: the collection's section
+// message on the collections page, and the Log row fanned out to every
+// script under it (from either refresh entry point). One message per
+// problem, so those can't drift.
+//
+// The page banner deliberately does NOT render this. It reports the
+// aggregate — that some collection failed, and how full storage is —
+// which is a different statement from what happened to one collection.
+//
+// Names the consequence rather than the mechanism: what matters to the
+// reader is that the scripts they can see are not the scripts that are
+// stored, and that retrying is the action.
+export function describeRefreshError(reason) {
+    return `This collection was read but could not be saved, so its scripts are unchanged: ${reason}`;
+}
+// Coerce an unknown storage value into a RefreshErrorMap, dropping any
+// entry whose reason isn't a string. Used for both the direct read and
+// the `storage.onChanged` newValue, so the two paths can't disagree
+// about what a well-formed record looks like.
+export function coerceRefreshErrorMap(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const out = {};
+    for (const [id, message] of Object.entries(value)) {
+        if (typeof message === 'string')
+            out[id] = message;
+    }
+    return out;
+}
+// Every collection whose last refresh failed to save. Empty on a
+// healthy profile, which is the overwhelmingly common case.
+export async function readRefreshErrors() {
+    try {
+        const got = await chrome.storage.session.get(REFRESH_ERRORS_KEY);
+        return coerceRefreshErrorMap(got[REFRESH_ERRORS_KEY]);
+    }
+    catch {
+        // Session storage being unavailable must not turn a reportable
+        // failure into a thrown one — the caller is already handling an
+        // error. Worst case the page doesn't show the banner.
+        return {};
+    }
+}
+// Record (or clear, with `reason: null`) one collection's write failure.
+//
+// Never throws. Every call site is already on a failure path or a
+// success path that must not be derailed by bookkeeping, so a session
+// write that fails leaves the map as it was and says so only to the
+// console.
+//
+// Skips the write when nothing changes, so the overwhelmingly common
+// case — a healthy refresh clearing an error that was never set — costs
+// one read and no `storage.onChanged` fan-out to the open pages.
+export async function setRefreshError(collectionId, reason) {
+    assertWorkerContext('write storage');
+    try {
+        const prior = await readRefreshErrors();
+        if (reason === null && !(collectionId in prior))
+            return;
+        if (reason !== null && prior[collectionId] === reason)
+            return;
+        const next = { ...prior };
+        if (reason === null)
+            delete next[collectionId];
+        else
+            next[collectionId] = reason;
+        await chrome.storage.session.set({ [REFRESH_ERRORS_KEY]: next });
+    }
+    catch (err) {
+        console.info('[SourceMonkey] could not record a refresh error', err);
+    }
+}
+// Drop entries for collections that no longer exist, so a removed
+// collection can't leave a banner counting a section that isn't on the
+// page. Called after a removal rather than on a timer; `liveIds` is the
+// authoritative set.
+export async function pruneRefreshErrors(liveIds) {
+    assertWorkerContext('write storage');
+    try {
+        const prior = await readRefreshErrors();
+        const live = new Set(liveIds);
+        const next = {};
+        for (const [id, reason] of Object.entries(prior)) {
+            if (live.has(id))
+                next[id] = reason;
+        }
+        if (Object.keys(next).length === Object.keys(prior).length)
+            return;
+        await chrome.storage.session.set({ [REFRESH_ERRORS_KEY]: next });
+    }
+    catch (err) {
+        console.info('[SourceMonkey] could not prune refresh errors', err);
+    }
+}

package/dist/extension/refresh-targets.js

@@ -0,0 +1,160 @@
+// Which collections / scripts a targeted refresh should touch.
+//
+// The collections page's `?refresh` does a full Refresh All, which
+// re-reads every http(s) and GitHub collection too — slow, and pointless
+// when the thing that changed was a file on disk. The two narrower
+// triggers (`?refresh_local`, `?refresh_file=<path>`) pick their targets
+// with the pure helpers here, so the selection logic is testable without
+// a page.
+//
+// Local collections come in two shapes and each needs its own treatment:
+//   - A scanned collection (a directory, or a local `script_manifest.json`)
+//     refreshes as a WHOLE, because only a re-scan notices files that
+//     were added, renamed, or deleted.
+//   - A container (`container:*`) has no directory of its own — each
+//     script row carries its own absolute location, and a container may
+//     hold web scripts alongside local ones — so its local rows are
+//     selected individually.
+//
+// "Local" is decided by where the COLLECTION lives, not by where its
+// rows point. So an http(s) manifest listing a `file://` entry is never
+// selected (refreshing it would mean re-reading the manifest over the
+// network, which is the cost these triggers exist to avoid), and a
+// local manifest listing http(s) entries refreshes them along with the
+// rest of its collection. See TODO.md.
+import { isContainerCollection, isFileUrl, isManifestCollection, isNonPosixFileUrl, locationFsPath, parentDir, } from '../file-locations.js';
+import { inferCollectionType } from './collection-display.js';
+// True for collections that can hold content on the local disk —
+// scanned directories, local manifests, and every container (whose
+// rows are then filtered one by one). Shares `inferCollectionType` with
+// the UI's type bubble so "local" means the same thing the user sees on
+// the page.
+export function isLocalCollection(collection) {
+    return inferCollectionType(collection.path) === 'file';
+}
+// Absolute filesystem path for a `file://` URL or a raw path, with any
+// trailing slash removed so directory and file spellings compare the
+// same way. Non-local inputs (http(s) URLs, the synthetic
+// `container:*` paths) have no filesystem form — they come back as-is
+// and simply fail every comparison below.
+export function toFsPath(input) {
+    const p = locationFsPath(input.trim());
+    return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
+// True when `child` is `parent` itself or sits somewhere beneath it.
+// The `/` boundary check keeps `/a/scripts-old` from reading as a child
+// of `/a/scripts`. An empty `parent` is nobody's ancestor — without the
+// guard its `base` would be `/`, which every absolute path is under.
+function isAtOrUnder(child, parent) {
+    if (parent === '')
+        return false;
+    if (child === parent)
+        return true;
+    const base = parent === '/' ? '/' : parent + '/';
+    return child.startsWith(base);
+}
+// True when the two paths refer to the same place or one contains the
+// other. Both directions matter: a `?refresh_file=/a/b/x.user.js` has to
+// find the `/a/b` collection that scans it, and a
+// `?refresh_file=/a` (the user pointing at a whole tree) has to find the
+// `/a/b` collections inside it.
+export function pathsOverlap(a, b) {
+    return isAtOrUnder(a, b) || isAtOrUnder(b, a);
+}
+// Directory a scanned collection covers: the manifest's own directory
+// for a manifest collection, the path itself otherwise.
+function collectionScanDir(path) {
+    const fs = toFsPath(path);
+    return isManifestCollection(path) ? parentDir(fs) : fs;
+}
+// Every local collection, refreshed whole — except containers, whose
+// local rows are picked out individually so their web rows aren't
+// refetched. Used by `?refresh_local`.
+export function localRefreshTargets(entries) {
+    const collectionIds = [];
+    const scripts = [];
+    for (const { collection, scripts: rows } of entries) {
+        if (!isLocalCollection(collection))
+            continue;
+        if (isContainerCollection(collection.path)) {
+            for (const s of rows) {
+                if (isFileUrl(s.fileUrl))
+                    scripts.push({ id: s.id, collectionId: collection.id });
+            }
+            continue;
+        }
+        collectionIds.push(collection.id);
+    }
+    return { collectionIds, scripts };
+}
+// Local collections and scripts touching `target` — a file or directory
+// path (raw or `file://`). Used by `?refresh_file=<path>`.
+//
+// A scanned collection is selected when its directory overlaps the
+// target, so a rename or a brand-new file in that directory is picked
+// up even though no existing row points at it. It's also selected when
+// one of its rows points at the target even if the directory test
+// missed — a manifest may list entries outside its own directory.
+export function pathRefreshTargets(entries, targetPath) {
+    const target = toFsPath(targetPath);
+    const collectionIds = [];
+    const scriptTargets = [];
+    for (const { collection, scripts } of entries) {
+        if (!isLocalCollection(collection))
+            continue;
+        const matchingScripts = scripts.filter((s) => scriptMatchesPath(s, target));
+        if (isContainerCollection(collection.path)) {
+            // No directory to re-scan: the container's rows ARE its contents,
+            // so refresh exactly the ones that point at the target.
+            for (const s of matchingScripts) {
+                scriptTargets.push({ id: s.id, collectionId: collection.id });
+            }
+            continue;
+        }
+        if (pathsOverlap(collectionScanDir(collection.path), target) || matchingScripts.length > 0) {
+            collectionIds.push(collection.id);
+        }
+    }
+    return { collectionIds, scripts: scriptTargets };
+}
+// True when a stored row's file is the target or lives under it. Only
+// local rows can match — a container holds http(s) and GitHub scripts
+// alongside the local ones.
+function scriptMatchesPath(script, target) {
+    if (!isFileUrl(script.fileUrl))
+        return false;
+    return isAtOrUnder(toFsPath(script.fileUrl), target);
+}
+// What every `?refresh_file=` rejection leads with, so the line on the
+// page says which action didn't happen before it says why. The tail is
+// a message in its own right, hence its capital.
+export const REFRESH_FAILED_PREFIX = 'Refresh failed: ';
+// Shapes `?refresh_file=` accepts, as the tail of "Refresh path …".
+// Narrower than `LOCATION_SHAPES`: the trigger exists for files on
+// local disk, so an http(s) URL has nothing to refresh against.
+export const REFRESH_PATH_SHAPES = 'must be a file:// URL, or an absolute path starting with /';
+// Why a `?refresh_file=` value can't be used, or null when it can.
+// Rejects the shapes `toFsPath` would mangle rather than comparing a
+// path that points somewhere other than what was asked for:
+//   - Windows drive-letter and UNC `file://` URLs (`locationFsPath`
+//     drops the host — the same hazard `canonicalCollectionInput`
+//     sidesteps), and
+//   - anything resolving to bare `/`, which would overlap every local
+//     collection. `isValidLocationShape` refuses the root in the Add
+//     field for the same reason, and the two shouldn't disagree.
+export function refreshPathProblem(input) {
+    const value = input.trim();
+    if (!value.startsWith('/') && !isFileUrl(value)) {
+        // Every rejection echoes the value: the caller here is usually a
+        // tool that built the URL, and the path it actually sent is the
+        // thing that needs fixing.
+        return `Refresh path ${REFRESH_PATH_SHAPES}: ${value}`;
+    }
+    if (isFileUrl(value) && isNonPosixFileUrl(value)) {
+        return `Refresh path must be a POSIX file:// URL, without a host: ${value}`;
+    }
+    if (toFsPath(value).length <= 1) {
+        return `Refresh path must name something below the filesystem root: ${value}`;
+    }
+    return null;
+}