sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/file-changes.js

@@ -0,0 +1,346 @@
+// Noticing, at paint time, that a local file a page is naming has
+// changed on disk — deleted, or edited — before any refresh has run
+// and updated the stored row. And, for a directory collection, that
+// files have appeared which a refresh would pick up.
+//
+// Every surface that shows a `file://` path paints from storage, and
+// storage only learns about the disk when the next refresh lists a
+// directory. Until then the viewer's Location row, its Local overrides
+// row, the versions table and the collections page all describe the
+// file as it was last read. This module lets them say otherwise: a
+// row tags the element carrying the path (`tagLocalFile`: the path,
+// the size and mtime the row was read at, and the tooltips to use),
+// and `markFileChanges` probes the disk and adds a chip beside each
+// one that has gone or changed.
+//
+// See docs/file-changes.md.
+import { baseName, collectionCanonicalUrl, isFileUrl, isLocalDirectoryCollection, isManifestCollection, listDirectory, locationFsPath, parentDir, } from '../file-locations.js';
+import { dlog } from '../debug-log.js';
+import { pendingSummary } from '../script-display.js';
+// Probe `files` against their directory listings — one listing per
+// distinct parent directory, rather than a read per file: a table can
+// name many files in one folder, and a listing is one small read
+// however many rows it settles.
+//
+// Conservative by construction. A file is reported missing only when
+// its directory listed successfully and the name is not in it, and
+// modified only when the listing supplies a size and mtime that differ
+// from the stored ones. A listing that fails — the directory itself is
+// gone, file access is off, a transient read error — settles nothing:
+// its files come back `unknown`. That is the right way round for every
+// caller: a chip that says "deleted" about a file that is there would
+// be worse than no chip, and the delete dialog acts on the answer.
+//
+// `maxAgeMs` lets a caller that re-probes on every repaint reuse a
+// listing read moments ago: the collections page repaints on every
+// storage write, an enable toggle included, and nothing about the disk
+// changed for that. A listing older than `maxAgeMs` is read again.
+//
+// A remembered listing is only ever trusted for the answer "present":
+// a listing that agrees with the row is right whatever its age, but
+// one that disagrees may simply predate the refresh that just updated
+// the row (the refresh lists through its own cache, not this memo), so
+// a folder with any other answer is listed again before it is given.
+// The common case — nothing changed — pays no extra read; a change
+// costs one, and the fresh listing replaces the memo.
+//
+// Answers one state per input, in input order — not per path: the same
+// file can be held by several rows (one collection per copy), each
+// read at a different time with a different stat, and each is its own
+// question.
+export async function probeFiles(files, maxAgeMs = 0) {
+    const byDir = new Map();
+    files.forEach((file, i) => {
+        const dir = parentDir(file.path);
+        const list = byDir.get(dir);
+        if (list)
+            list.push(i);
+        else
+            byDir.set(dir, [i]);
+    });
+    const states = new Array(files.length).fill('unknown');
+    const cache = new Map();
+    await Promise.all([...byDir].map(async ([dir, indexes]) => {
+        let listed = await listedDir(dir, cache, maxAgeMs);
+        if (listed?.remembered && indexes.some((i) => stateOf(files[i], listed) !== 'present')) {
+            listed = await listedDir(dir, cache, 0);
+        }
+        if (!listed)
+            return;
+        for (const i of indexes)
+            states[i] = stateOf(files[i], listed);
+    }));
+    return states;
+}
+function stateOf(file, listed) {
+    const entry = listed.files.get(baseName(file.path));
+    if (!entry)
+        return 'missing';
+    // The same test the refresh uses to decide whether to re-read the
+    // file (`canSkip` in script-store.ts), so a `modified` chip predicts
+    // exactly what a refresh will do. Equality on mtime, not ordering:
+    // the value is an opaque listing timestamp.
+    if (file.size !== undefined && file.mtime !== undefined
+        && entry.size !== undefined && entry.mtime !== undefined
+        && (entry.size !== file.size || entry.mtime !== file.mtime)) {
+        return 'modified';
+    }
+    return 'present';
+}
+// The subset of `paths` that are no longer on disk. The delete dialog's
+// question; a convenience over `probeFiles`.
+export async function missingFiles(paths) {
+    const files = [...paths].map((path) => ({ path }));
+    const states = await probeFiles(files);
+    return new Set(files.filter((_, i) => states[i] === 'missing').map((f) => f.path));
+}
+// `.user.js` files on disk in a directory collection that no row
+// accounts for — what a refresh would add. Looks in the collection's
+// root and in every directory a known script sits in, which is where
+// new files land in practice; a new subdirectory with nothing known in
+// it is not seen until a refresh scans it (docs/file-changes.md).
+//
+// Returns paths relative to the collection root, so they read the way
+// the rows do.
+export async function newScriptFiles(collectionPath, knownRelativePaths, maxAgeMs = 0) {
+    const root = locationFsPath(collectionPath).replace(/\/+$/, '');
+    const known = new Set(knownRelativePaths);
+    const dirs = new Set([root]);
+    for (const rel of known)
+        dirs.add(parentDir(`${root}/${rel}`));
+    const out = [];
+    const cache = new Map();
+    await Promise.all([...dirs].map(async (dir) => {
+        const listed = await listedDir(dir, cache, maxAgeMs);
+        if (!listed)
+            return;
+        const prefix = dir === root ? '' : `${dir.slice(root.length + 1)}/`;
+        for (const name of listed.files.keys()) {
+            if (!name.endsWith('.user.js'))
+                continue;
+            const rel = prefix + name;
+            if (!known.has(rel))
+                out.push(rel);
+        }
+    }));
+    return out.sort();
+}
+// Recent successful listings, kept for `maxAgeMs`. Failures are not
+// remembered: the next probe retries. Bounded by the number of
+// folders a page names.
+const recentListings = new Map();
+// The listing for `dir`, or null when it could not be read (logged,
+// not thrown: callers treat it as "nothing known").
+async function listedDir(dir, cache, maxAgeMs) {
+    const recent = recentListings.get(dir);
+    if (recent && Date.now() - recent.at < maxAgeMs)
+        return { ...recent.listed, remembered: true };
+    try {
+        const entries = await listDirectory(dir, cache);
+        const files = new Map();
+        for (const e of entries) {
+            if (!e.isDir)
+                files.set(e.name, { size: e.size, mtime: e.mtime });
+        }
+        const listed = { files, remembered: false };
+        recentListings.set(dir, { at: Date.now(), listed });
+        return listed;
+    }
+    catch (err) {
+        dlog(`[SourceMonkey] could not list ${dir} to check for file changes: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+// The tag for a script's own file, or null when the script isn't a
+// local file. One builder for every surface that shows one (the
+// viewer's Location row, the versions table, the collections page), so
+// they can't disagree on the path, the stat, or the wording.
+export function scriptFileTag(script, collectionPath) {
+    if (!isFileUrl(script.fileUrl))
+        return null;
+    const tag = {
+        fsPath: locationFsPath(script.fileUrl),
+        missingHint: scriptFileMissingHint(collectionPath),
+        modifiedHint: SCRIPT_FILE_MODIFIED_HINT,
+    };
+    // Both or neither: a row with a size but no listing mtime (its
+    // folder didn't list when it was read) can't be compared, and a lone
+    // size would miss same-size edits — worse than saying nothing.
+    if (script.size != null && script.fsMtime !== undefined) {
+        tag.size = script.size;
+        tag.mtime = script.fsMtime;
+    }
+    return tag;
+}
+// Tag an element as naming a local file, for `markFileChanges`.
+export function tagLocalFile(el, tag) {
+    el.dataset.fsPath = tag.fsPath;
+    if (tag.size !== undefined)
+        el.dataset.fsSize = String(tag.size);
+    if (tag.mtime !== undefined)
+        el.dataset.fsMtime = String(tag.mtime);
+    el.dataset.missingHint = tag.missingHint;
+    if (tag.modifiedHint)
+        el.dataset.modifiedHint = tag.modifiedHint;
+}
+export const FILE_CHIP_CLASS = 'file-change-chip';
+// Probe every tagged element under `root` and put a chip after each
+// one whose file is gone or changed. Safe to call after every repaint:
+// an earlier chip is removed first, so a file that came back (or was
+// re-read) loses its chip, and an element that left the document
+// before the probe returns is simply annotated where nobody can see
+// it. Resolves with the state of every tagged element, for a caller
+// that wants to summarize.
+//
+// Async and deliberately not awaited by renders: the probe is a disk
+// read, and a synchronous paint must not wait on it.
+export async function markFileChanges(root, maxAgeMs = 0) {
+    const tagged = [...root.querySelectorAll('[data-fs-path]')];
+    const states = new Map();
+    if (tagged.length === 0)
+        return states;
+    const probed = await probeFiles(tagged.map((el) => ({
+        path: el.dataset.fsPath,
+        size: el.dataset.fsSize === undefined ? undefined : Number(el.dataset.fsSize),
+        mtime: el.dataset.fsMtime === undefined ? undefined : Number(el.dataset.fsMtime),
+    })), maxAgeMs);
+    tagged.forEach((el, i) => states.set(el, probed[i]));
+    for (const el of tagged) {
+        // The chip follows the path — and a copy button that directly
+        // follows the path, since that button belongs beside the text it
+        // copies (the viewer's Location and Local overrides rows).
+        let anchor = el;
+        if (anchor.nextElementSibling?.classList.contains('copy-btn'))
+            anchor = anchor.nextElementSibling;
+        const prior = anchor.nextElementSibling;
+        if (prior?.classList.contains(FILE_CHIP_CLASS))
+            prior.remove();
+        const state = states.get(el);
+        const hint = state === 'missing'
+            ? el.dataset.missingHint
+            : state === 'modified' ? el.dataset.modifiedHint : undefined;
+        // A modified file with no hint is one this surface doesn't report
+        // edits for.
+        if (!hint)
+            continue;
+        const chip = document.createElement('span');
+        chip.className = `${FILE_CHIP_CLASS} ${FILE_CHIP_CLASS}-${state}`;
+        chip.textContent = state === 'missing' ? 'deleted' : 'modified';
+        chip.title = hint;
+        anchor.after(chip);
+    }
+    return states;
+}
+// ---------- Wording ----------
+//
+// The hints, in one place so the surfaces that name the same file agree
+// on what its deletion means. Keyed by the collection the row sits in,
+// because that is what decides what happens next:
+//
+// - A directory collection mirrors the disk, so the next refresh drops
+//   the row.
+// - A manifest entry is the manifest's to keep or drop: the row stays,
+//   running from its last copy, until the entry leaves the manifest.
+// - A file added on its own is the user's: the row stays until they
+//   remove it (the trash can on its row).
+export function scriptFileMissingHint(collectionPath) {
+    if (isLocalDirectoryCollection(collectionPath)) {
+        return 'This file has been deleted. The next refresh will remove this script.';
+    }
+    if (isManifestCollection(collectionPath)) {
+        return 'This file has been deleted. The last copy of the script keeps running '
+            + 'until the entry is removed from the manifest.';
+    }
+    return 'This file has been deleted. The last copy of the script keeps running until you remove it.';
+}
+// An edited script file: the same for every collection kind, since a
+// refresh re-reads it wherever it sits.
+export const SCRIPT_FILE_MODIFIED_HINT = 'This file has changed on disk. The next refresh will load the new version.';
+// A local stand-in for a `@require` / `@resource`. Deleted: the
+// declared URL is still there, so the next refresh loads it from
+// there instead. Edited: the next refresh (opportunistic ones
+// included — a stand-in is re-read every pass) picks it up.
+export const STAND_IN_MISSING_HINT = 'This file has been deleted. The next refresh will reload the remote version.';
+// The same words as for a script file: the outcome is the same.
+export const STAND_IN_MODIFIED_HINT = SCRIPT_FILE_MODIFIED_HINT;
+// A file sm-dev pushed with a scratch script: a snapshot no refresh
+// rereads. It has no stored mtime, so only a deletion can be told.
+export const PUSHED_FILE_MISSING_HINT = 'This file has been deleted since sm-dev pushed it. The script still runs the snapshot it pushed.';
+// The tag for a stand-in, given its path and the stored entry. The
+// entry's `size` is the bytes read, which is the file's size; with the
+// listing mtime recorded beside it, an edit can be told apart.
+// `pushed` is for a snapshot sm-dev pushed.
+export function standInTag(fsPath, entry, pushed = false) {
+    const tag = {
+        fsPath,
+        missingHint: pushed ? PUSHED_FILE_MISSING_HINT : STAND_IN_MISSING_HINT,
+        ...(pushed ? {} : { modifiedHint: STAND_IN_MODIFIED_HINT }),
+    };
+    if (entry.size !== undefined && entry.fsMtime !== undefined) {
+        tag.size = entry.size;
+        tag.mtime = entry.fsMtime;
+    }
+    return tag;
+}
+// Counts a directory or `file://` manifest collection's changes on
+// disk: its rows' probed `files`, plus the new files a directory holds,
+// or whether the manifest file changed (`manifest`: its path and the
+// stat its last scan recorded). Null for any other collection.
+export async function pendingOnDisk(collectionPath, manifest, files, maxAgeMs = 0) {
+    const isDirectory = isLocalDirectoryCollection(collectionPath);
+    if (!isDirectory && !(isManifestCollection(collectionPath) && manifest))
+        return null;
+    const counts = { modified: 0, deleted: 0, added: 0 };
+    for (const f of files) {
+        if (f.state === 'missing')
+            counts.deleted += 1;
+        else if (f.state === 'modified')
+            counts.modified += 1;
+    }
+    if (isDirectory) {
+        const root = locationFsPath(collectionPath).replace(/\/+$/, '');
+        const known = files.map((f) => f.fsPath.slice(root.length + 1));
+        counts.added = (await newScriptFiles(collectionPath, known, maxAgeMs)).length;
+    }
+    else {
+        const [state] = await probeFiles([manifest], maxAgeMs);
+        if (state === 'modified')
+            counts.manifest = true;
+    }
+    return counts;
+}
+// The manifest file to probe for a `file://` manifest collection, with
+// the stat its last scan recorded; null for any other.
+export function manifestToProbe(collection) {
+    if (!isManifestCollection(collection.path) || !isFileUrl(collectionCanonicalUrl(collection.path)))
+        return null;
+    return { path: locationFsPath(collection.path), size: collection.manifestSize, mtime: collection.manifestMtime };
+}
+// The tooltip of a collection's "refresh pending" chip: the summary, and
+// what to do. Empty when nothing differs.
+export function refreshPendingHint(counts) {
+    const summary = pendingSummary(counts);
+    return summary ? `${summary} on disk. Refresh to load.` : '';
+}
+export const REFRESH_PENDING_CHIP_CLASS = `${FILE_CHIP_CLASS} ${FILE_CHIP_CLASS}-pending`;
+// Put a "refresh pending" chip at the end of `nameEl` (a collection's
+// display name), or remove the one there, to match `hint` (empty =
+// nothing pending). Inside the name rather than after it: the heading
+// is a two-column grid (bubble, name), where a third child would start
+// a new row.
+export function syncRefreshPendingChip(nameEl, hint) {
+    const existing = nameEl.querySelector(`:scope > .${FILE_CHIP_CLASS}-pending`);
+    if (!hint) {
+        existing?.remove();
+        return;
+    }
+    if (existing) {
+        existing.title = hint;
+        return;
+    }
+    const chip = document.createElement('span');
+    chip.className = REFRESH_PENDING_CHIP_CLASS;
+    chip.textContent = 'refresh pending';
+    chip.title = hint;
+    nameEl.appendChild(chip);
+}

package/dist/extension/frame-info.js

@@ -0,0 +1,85 @@
+// Where a message from injected code came from: one of a page's
+// iframes or a page's own (top-level) frame, and which page. See
+// docs/frames.md.
+//
+// `sender.frameId > 0` alone can't tell: Chrome numbers a prerendered
+// page's top frame like an iframe (its `frameType` is `outermost_frame`,
+// which `MessageSender` doesn't carry). So a document with a frame id
+// other than 0 is looked up with `chrome.webNavigation.getFrame`, and
+// walked up through its parents to the page's document.
+//
+// Answers are cached by document id, which Chrome never reuses. A
+// document's place doesn't change, but whether it is still in the tab
+// does, so `live` is asked afresh when the caller needs it.
+// Bounded: an entry per document of every frame that ever messaged us.
+const CACHE_CAP = 1000;
+const cache = new Map();
+function remember(documentId, placed) {
+    if (cache.size >= CACHE_CAP)
+        cache.delete(cache.keys().next().value);
+    cache.set(documentId, placed);
+}
+// The frame `documentId` is, or null when Chrome no longer has it (it
+// answers null, or refuses). `documentId` isn't in our @types/chrome
+// version of `GetFrameDetails`, hence the cast.
+async function getFrame(tabId, documentId) {
+    try {
+        const details = { tabId, documentId };
+        return (await chrome.webNavigation.getFrame(details));
+    }
+    catch {
+        return null;
+    }
+}
+// Frames nest, but not this deep in practice; the bound keeps a
+// misbehaving answer from looping.
+const MAX_DEPTH = 32;
+/**
+ * Where `sender`'s document is. `checkLive` asks Chrome whether it is
+ * still in the tab even when its place is cached.
+ */
+export async function frameInfo(sender, checkLive = false) {
+    const tabId = sender.tab?.id;
+    const documentId = sender.documentId ?? '';
+    const frameId = sender.frameId;
+    if (frameId === 0)
+        return { subframe: false, topDocId: documentId, live: true };
+    // Nothing to look up with: by the frame id, as before.
+    if (tabId == null || !documentId || typeof frameId !== 'number') {
+        return { subframe: typeof frameId === 'number' && frameId > 0, topDocId: '', live: true };
+    }
+    const cached = cache.get(documentId);
+    if (cached && !checkLive)
+        return { ...cached, live: true };
+    const frame = await getFrame(tabId, documentId);
+    if (!frame)
+        return { ...(cached ?? { subframe: true, topDocId: '' }), live: false };
+    if (cached)
+        return { ...cached, live: true };
+    let placed;
+    if (frame.parentFrameId === -1) {
+        placed = { subframe: false, topDocId: documentId, topUrl: frame.url };
+    }
+    else {
+        placed = { subframe: true, topDocId: '' };
+        let parent = frame.parentDocumentId;
+        for (let depth = 0; parent && depth < MAX_DEPTH; depth++) {
+            const up = cache.get(parent);
+            if (up && !up.subframe) {
+                placed = { subframe: true, topDocId: up.topDocId, topUrl: up.topUrl };
+                break;
+            }
+            const next = await getFrame(tabId, parent);
+            if (!next)
+                break;
+            if (next.parentFrameId === -1) {
+                placed = { subframe: true, topDocId: parent, topUrl: next.url };
+                break;
+            }
+            parent = next.parentDocumentId;
+        }
+    }
+    if (placed.topDocId)
+        remember(documentId, placed);
+    return { ...placed, live: true };
+}