sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/script-enablement.js

@@ -0,0 +1,285 @@
+// The enable toggles that keep one copy of each script active: its own
+// flag and its collection's both on, so it fires on the pages it
+// matches.
+//
+// The collections page's, the viewer's and the toolbar popup's enable
+// controls, and sm-dev's `collection enable`, go through here, all in
+// the service worker (worker-ops.ts), so they apply the same rules:
+//   - Turning a copy on turns its other active copies off.
+//   - Turning a collection on does the same for each copy it activates.
+//   - Turning a collection off brings back the copies its own copies
+//     displaced, when nothing has changed them since.
+//   - "Enable all" in a collection turns on one copy per script.
+// Ctrl/Cmd-click (`solo`) opts out and changes only what was clicked.
+//
+// Each one finds which copies are related (from the worker's index,
+// row-cache.ts, or a read of every row where there is none), then
+// decides which of those to change inside the write lock, from their
+// stored state at that moment (`writeEnablementFrom`).
+//
+// The viewer works out the same single-script rule through
+// `enableChanges` (script-identity.ts) itself, to paint its rows before
+// the write lands. Its versions table writes through `enableWithin`
+// here. Installs, moves and sm-dev's `script enable` use
+// `turnOffOtherCopies` there.
+//
+// Design: docs/script-enablement.md.
+import { isSmDevCollection } from './directories.js';
+import { getAllScriptMetas, getCollections, getScriptMeta, getScriptMetas, isCollectionEnabled, isScriptEnabled, writeEnablement, writeEnablementFrom, } from './script-store.js';
+import { allRelatedRows, enableChanges, findRelatedVersions, isActive, otherActiveCopies, relatedCopyIds, } from './script-identity.js';
+import { compareInCollection, preferredCopy } from './copy-preference.js';
+import { sameScript } from './script-keys.js';
+import { effectiveDisplayName } from './collection-display.js';
+import { getValue } from '../userscript-header.js';
+import { startPhaseTimer } from '../phase-timing.js';
+import { scriptIdsInCollection } from './row-cache.js';
+// The ids of `scripts` and every copy related to any of them, marked on
+// `timer` as `find copies`.
+async function scopeOf(scripts, timer) {
+    const ids = await relatedCopyIds(scripts);
+    timer.mark('find copies', `${ids.size} script(s)`);
+    return ids;
+}
+// A collection, if the index lists it, and every script row naming it
+// (listed by it or not), marked on `timer` as `read collection`.
+async function collectionRows(id, timer) {
+    const collection = (await getCollections()).find((c) => c.id === id);
+    let scripts = [];
+    if (collection) {
+        const ids = await scriptIdsInCollection(id);
+        scripts = ids
+            ? await getScriptMetas(ids)
+            : (await getAllScriptMetas()).filter((s) => s.collectionId === id);
+    }
+    timer.mark('read collection', `${scripts.length} script(s)`);
+    return { collection, scripts };
+}
+// Every installed copy related to `script` (same location or same
+// `@namespace` + `@name`), itself included, among `snap`'s rows.
+function relatedRows(snap, script) {
+    return allRelatedRows(findRelatedVersions({
+        ...snap, location: script.fileUrl, header: script.header ?? null,
+    }));
+}
+// What `copy-preference.ts` orders a copy by.
+export function copyFacts(script, collection, times) {
+    return {
+        enabled: isScriptEnabled(script),
+        collectionOn: collection ? isCollectionEnabled(collection) : true,
+        collectionName: collection ? effectiveDisplayName(collection) : '',
+        activeSince: times?.activeSince,
+        inactiveSince: times?.inactiveSince,
+        version: (script.header ? getValue(script.header, 'version')?.trim() : '') || null,
+        location: script.fileUrl,
+    };
+}
+// Turn one copy on or off. On, without `solo`, turns its other active
+// copies off in the same write, when that makes it active. Ticked under
+// a disabled collection it isn't active, so it displaces nothing. Off
+// changes only this copy: nothing is promoted in its place.
+//
+// Returns the copy as stored after the write, and every row the write
+// changed (the copies it turned off among them).
+export async function setScriptEnabledExclusive(id, enabled, solo = false) {
+    const timer = startPhaseTimer(enabled ? 'enable script' : 'disable script');
+    let written;
+    if (enabled && !solo) {
+        const script = await getScriptMeta(id);
+        written = await enableWithin(id, script ? await scopeOf([script], timer) : [id], timer);
+    }
+    else {
+        let clicked = null;
+        const result = await writeEnablementFrom({ scriptIds: [id] }, (fresh) => {
+            clicked = fresh.scripts.find((s) => s.id === id) ?? null;
+            return { scripts: [{ id, enabled }] };
+        }, timer);
+        written = { ...result, clicked };
+        timer.note('1 change(s)');
+    }
+    timer.done();
+    // Nothing written when it was already in that state, and then the row
+    // as read inside the lock is the stored one. Not read again here: an
+    // await after the lock would let a later click's result reach the
+    // caller first.
+    const script = written.scripts.find((s) => s.id === id) ?? written.clicked;
+    return { script, changed: written.scripts };
+}
+// Turn copy `id` on, and every other active copy in `scope` off,
+// planned inside the write lock from those rows as stored then. `scope`
+// is the copies the caller counts as this one's: every copy related to
+// it, or for the viewer's versions table, every copy the table shows
+// (related to the script on screen, which the clicked one may not be in
+// both ways). For a caller that already knows them, so it needs no read
+// of its own.
+//
+// `clicked` is the copy as stored after the write.
+export async function enableWithin(id, scope, timer) {
+    let count = 0;
+    let clicked = null;
+    const written = await writeEnablementFrom({ scriptIds: scope }, (fresh) => {
+        let changes = [{ id, enabled: true }];
+        const script = fresh.scripts.find((s) => s.id === id);
+        clicked = script ?? null;
+        const collection = fresh.collections.find((c) => c.id === script?.collectionId);
+        if (script && (!collection || isCollectionEnabled(collection))) {
+            changes = enableChanges(id, true, asRows(fresh))
+                .map((c) => ({ id: c.scriptId, enabled: c.enabled }));
+        }
+        count = changes.length;
+        return { scripts: changes };
+    }, timer);
+    timer.note(`${count} change(s)`);
+    return { ...written, clicked: written.scripts.find((s) => s.id === id) ?? clicked };
+}
+// Every row in `rows` as a related copy, without filtering by location
+// or identity again: the caller already chose them. `enableChanges` reads
+// only the row and its collection, not how it matched.
+function asRows(rows) {
+    const byId = new Map(rows.collections.map((c) => [c.id, c]));
+    return rows.scripts.map((script) => ({
+        script,
+        collection: byId.get(script.collectionId) ?? null,
+        sameLocation: false,
+        sameIdentity: false,
+    }));
+}
+// Turn a collection on or off.
+//   - On, without `solo`: each of its copies that becomes active turns
+//     off its other active copies elsewhere. Two copies inside the
+//     collection are both left as their own boxes say.
+//   - Off, without `solo`: each of its active copies that displaced
+//     others (they went inactive at the moment it became active, and
+//     haven't been active since) brings them back, unless another copy
+//     of that script is still active.
+//
+// Returns the collection as written and every script row whose flag
+// changed (none of them in this collection).
+export async function setCollectionEnabledExclusive(id, enabled, solo = false) {
+    const timer = startPhaseTimer(enabled ? 'enable collection' : 'disable collection');
+    const { collection, scripts } = await collectionRows(id, timer);
+    let written;
+    let count = 0;
+    if (!collection || solo || isSmDevCollection(collection.path)) {
+        written = await writeEnablement({ collection: { id, enabled } }, timer);
+    }
+    else {
+        const scope = await scopeOf(scripts, timer);
+        written = await writeEnablementFrom({ scriptIds: scope, collectionIds: [id] }, (fresh) => {
+            const current = fresh.collections.find((c) => c.id === id);
+            let changes = [];
+            if (current && isCollectionEnabled(current) !== enabled) {
+                const own = fresh.scripts.filter((s) => s.collectionId === id && isScriptEnabled(s));
+                changes = enabled ? displacedBy(fresh, own) : restoredFor(fresh, id, own);
+            }
+            count = changes.length;
+            return { collection: { id, enabled }, scripts: changes };
+        }, timer);
+    }
+    timer.note(`${count} other cop${count === 1 ? 'y' : 'ies'} changed`);
+    timer.done();
+    return written;
+}
+// The copies outside the collection that `starting` (its copies about to
+// become active) switch off. One that landed `invalid` does too, as
+// `turnOffOtherCopies` explains.
+function displacedBy(snap, starting) {
+    const off = new Set();
+    const startingCollections = new Set(starting.map((s) => s.collectionId));
+    for (const script of starting) {
+        for (const other of otherActiveCopies(relatedRows(snap, script), script.id)) {
+            if (!startingCollections.has(other.script.collectionId))
+                off.add(other.script.id);
+        }
+    }
+    return [...off].map((sid) => ({ id: sid, enabled: false }));
+}
+// The copies to bring back when collection `id` turns off and
+// `stopping` (its active copies) go inactive.
+function restoredFor(snap, id, stopping) {
+    const on = new Set();
+    for (const script of stopping) {
+        const activeSince = snap.times[script.id]?.activeSince;
+        if (activeSince === undefined)
+            continue;
+        const rows = relatedRows(snap, script).filter((r) => r.script.collectionId !== id);
+        // Another copy is still active: bringing one back would make two.
+        // An sm-dev run's copies don't count, as everywhere.
+        if (rows.some((r) => isActive(r) && !(r.collection && isSmDevCollection(r.collection.path))))
+            continue;
+        for (const r of rows) {
+            if (!isScriptEnabled(r.script)
+                && snap.times[r.script.id]?.inactiveSince === activeSince
+                && (r.collection ? isCollectionEnabled(r.collection) : true)
+                && !(r.collection && isSmDevCollection(r.collection.path)))
+                on.add(r.script.id);
+        }
+    }
+    return [...on].map((sid) => ({ id: sid, enabled: true }));
+}
+// The collections page's bulk toggle.
+//   - Off: every script in the collection off.
+//   - On: one copy per script on, the first by `compareInCollection`,
+//     and any other copy of it in the collection off. Without `solo`,
+//     each copy turned on also turns off its other active copies
+//     elsewhere, when the collection is on. With `solo`, every script.
+//
+// Returns every script row whose flag changed, here and elsewhere.
+export async function setAllScriptsEnabled(collectionId, enabled, solo = false) {
+    const timer = startPhaseTimer(enabled ? 'enable all' : 'disable all');
+    const { collection, scripts } = await collectionRows(collectionId, timer);
+    if (!collection) {
+        timer.note('collection gone');
+        timer.done();
+        return [];
+    }
+    if (!enabled || solo || isSmDevCollection(collection.path)) {
+        const written = await writeEnablement({ scripts: scripts.map((s) => ({ id: s.id, enabled })) }, timer);
+        timer.note(`${scripts.length} script(s)`);
+        timer.done();
+        return written.scripts;
+    }
+    let count = 0;
+    const written = await writeEnablementFrom({ scriptIds: await scopeOf(scripts, timer), collectionIds: [collectionId] }, (fresh) => {
+        const current = fresh.collections.find((c) => c.id === collectionId);
+        if (!current)
+            return null;
+        const w = enableAllWrite(fresh, current);
+        count = w.scripts.length;
+        return w;
+    }, timer);
+    timer.note(`${count} change(s)`);
+    timer.done();
+    return written.scripts;
+}
+// What "Enable all" writes for `collection`, from `snap`.
+function enableAllWrite(snap, collection) {
+    const scripts = snap.scripts.filter((s) => s.collectionId === collection.id);
+    const picks = pickOnePerScript(scripts, collection, snap.times);
+    const changes = scripts.map((s) => ({ id: s.id, enabled: picks.has(s.id) }));
+    // A pick that was already active and now displaces copies is stamped
+    // as becoming active now, so turning this collection off brings them
+    // back (`turnOffOtherCopies` does the same).
+    const started = [];
+    if (isCollectionEnabled(collection)) {
+        for (const pick of scripts.filter((s) => picks.has(s.id))) {
+            const off = displacedBy(snap, [pick]);
+            const sameCollectionOff = scripts.filter((s) => !picks.has(s.id) && isScriptEnabled(s) && sameScript(s, pick));
+            if (isScriptEnabled(pick) && (off.length > 0 || sameCollectionOff.length > 0))
+                started.push(pick.id);
+            changes.push(...off);
+        }
+    }
+    return { scripts: changes, started };
+}
+// One id per script among `scripts` (all in `collection`): the first by
+// `compareInCollection` among each copy and the copies it shares a
+// location or `@namespace` + `@name` with (`sameScript`).
+export function pickOnePerScript(scripts, collection, times) {
+    const picks = new Set();
+    for (const s of scripts) {
+        const group = scripts.filter((o) => sameScript(o, s));
+        if (preferredCopy(group, (c) => copyFacts(c, collection, times[c.id]), compareInCollection) === s)
+            picks.add(s.id);
+    }
+    return picks;
+}

package/dist/extension/script-identity.js

@@ -0,0 +1,310 @@
+// Finding *other versions of the same script* that are already
+// installed.
+//
+// Two independent notions of "the same script" live here, and they
+// answer different questions:
+//
+//   - **Same location** — the canonicalized *absolute* URL matches.
+//     This is literally the same file / URL, so whatever is at the
+//     other end is the same bytes we would fetch.
+//
+//     The key is `fileUrl`, not `relativePath`. A script inside a
+//     directory, manifest, or repo collection stores a path relative to
+//     its collection root, which shares no text with the full URL the
+//     same script carries when installed on its own — so comparing
+//     `relativePath` (what the preview page did) can never match a
+//     collection copy against a single-file copy. `fileUrl` is the
+//     absolute form the load pipeline already builds for every collection
+//     kind (`scriptFileUrl` in directories.ts), so it is the one
+//     spelling all collection kinds agree on.
+//
+//     Display is unaffected: a collection copy still *shows* its
+//     relative path, which is what the user recognizes. Only the
+//     comparison uses the absolute form.
+//
+//   - **Same identity** — `@namespace` + `@name` match. This is the
+//     userscript ecosystem's conventional unique ID: Greasemonkey
+//     documents `@namespace` as the value that, "combined with the
+//     name, forms a unique identifier", and both Tampermonkey and
+//     Violentmonkey key their install-vs-update decision on the pair.
+//     It catches the same script mirrored to a second host, vendored
+//     into a repo, or edited into a local copy — cases where the
+//     locations have nothing in common.
+//
+// SourceMonkey's own record identity stays what it was: a random UUID
+// per stored row, kept stable across refreshes by `relativePath` (see
+// [docs/storage.md]). Nothing here mints or rewrites an id — this
+// module only *finds relatives* of a script so the UI can offer to
+// jump between them.
+//
+// See [docs/script-identity.md].
+import { containerKindForSingleFileInput, containerPath, isContainerCollection, isScratchUrl, isSmDevCollection, isSingleFileInput, } from './directories.js';
+import { getAllScriptMetas, getCollections, getScriptMeta, getScriptMetas, isScriptEnabled, isCollectionEnabled, writeEnablementFrom, } from './script-store.js';
+import { CONTAINER_DISPLAY_NAMES, effectiveDisplayName } from './collection-display.js';
+import { getValues } from '../userscript-header.js';
+import { identityKey, locationKey } from './script-keys.js';
+import { startPhaseTimer } from '../phase-timing.js';
+import { relatedScriptIds } from './row-cache.js';
+// `identityKey` and `locationKey` live in script-keys.ts, so the store
+// can use them too; re-exported here, where the rest of the lookup is.
+export { identityKey, locationKey } from './script-keys.js';
+export function findRelatedVersions(q) {
+    const loc = locationKey(q.location);
+    const identity = identityKey(q.header);
+    const collectionById = new Map(q.collections.map((s) => [s.id, s]));
+    const sameLocation = [];
+    const sameIdentity = [];
+    for (const script of q.scripts) {
+        const atLocation = locationKey(script.fileUrl) === loc;
+        const isIdentity = identity !== null && identityKey(script.header) === identity;
+        if (!atLocation && !isIdentity)
+            continue;
+        const rel = {
+            script,
+            collection: collectionById.get(script.collectionId) ?? null,
+            sameLocation: atLocation,
+            sameIdentity: isIdentity,
+        };
+        // Location is the stronger claim, so a row that matches both is
+        // only listed once, under location.
+        (atLocation ? sameLocation : sameIdentity).push(rel);
+    }
+    const byName = (a, b) => collectionSortKey(a).localeCompare(collectionSortKey(b))
+        || a.script.relativePath.localeCompare(b.script.relativePath);
+    sameLocation.sort(byName);
+    sameIdentity.sort(byName);
+    return {
+        sameLocation,
+        sameIdentity,
+        installOptions: installOptionsFor(loc, sameLocation, q.collections),
+    };
+}
+// The containers a single-file install of `loc` could land in, in the
+// order the dropdown lists them: the built-in default for the
+// location's scheme first (offered as not-yet-existing when it has no
+// row), then every other container in page order. Each is marked
+// `installed` when one of the same-location rows already sits in it.
+// The caller appends its own "New collection…" entry.
+//
+// `current` names the collection the script is in now — the move
+// dropdown's caller. That entry is still listed, marked `isCurrent`
+// so the dropdown can label it *(current)*, disable it and pre-select
+// it. Listing it rather than dropping it keeps one list shape for
+// every script, and makes the opening selection somewhere the script
+// already is, so nothing moves without a deliberate pick.
+export function installOptionsFor(loc, sameLocation, collections, current) {
+    // A run's script stays in its sm-dev test collection, and nothing else
+    // goes into one.
+    if (!isSingleFileInput(loc) || isScratchUrl(loc))
+        return undefined;
+    const kind = containerKindForSingleFileInput(loc);
+    const defaultPath = containerPath(kind);
+    const holding = new Set();
+    for (const r of sameLocation) {
+        if (r.collection)
+            holding.add(r.collection.id);
+    }
+    const containers = collections.filter((c) => isContainerCollection(c.path) && !isSmDevCollection(c.path));
+    const def = containers.find((c) => c.path === defaultPath) ?? null;
+    const options = [{
+            collection: def,
+            path: defaultPath,
+            label: def ? effectiveDisplayName(def) : CONTAINER_DISPLAY_NAMES[kind],
+            installed: def ? holding.has(def.id) : false,
+            // A default that doesn't exist yet is created enabled.
+            collectionOff: def ? !isCollectionEnabled(def) : false,
+            isDefault: true,
+            // `def?.id === current` alone would be `undefined === undefined`
+            // for an install (no current) whose default has no row yet.
+            isCurrent: current !== undefined && def?.id === current,
+        }];
+    for (const c of containers) {
+        if (c.path === defaultPath)
+            continue;
+        options.push({
+            collection: c,
+            path: c.path,
+            label: effectiveDisplayName(c),
+            installed: holding.has(c.id),
+            collectionOff: !isCollectionEnabled(c),
+            isDefault: false,
+            isCurrent: c.id === current,
+        });
+    }
+    return options;
+}
+// One click's worth of enable/disable writes: the copy that was
+// clicked, plus — when it is being turned ON — every other copy that
+// is currently active. Pass an empty `rows` to opt out.
+//
+// Disabling is never exclusive: it leaves none active, which is an
+// ordinary thing to want, and there is no other copy that should be
+// promoted in its place.
+//
+// Nor is enabling one of an sm-dev run's scripts: the run keeps its
+// scripts off other tabs itself, so they don't compete.
+export function enableChanges(scriptId, enabled, rows) {
+    const changes = [{ scriptId, enabled }];
+    if (!enabled)
+        return changes;
+    const own = rows.find((r) => r.script.id === scriptId);
+    if (own && inRunCollection(own))
+        return changes;
+    for (const other of otherActiveCopies(rows, scriptId)) {
+        changes.push({ scriptId: other.script.id, enabled: false });
+    }
+    return changes;
+}
+// Whether a row is active: its own flag AND its collection's, so it
+// fires on the pages it matches. `turnOffOtherCopies` asks it of the
+// copy being enabled too: that copy has to be active itself before it
+// is worth switching the others off.
+export function isActive(rel) {
+    if (!isScriptEnabled(rel.script))
+        return false;
+    return rel.collection ? isCollectionEnabled(rel.collection) : true;
+}
+// The copies an exclusive enable of `keepId` has to switch off: every
+// OTHER row that is currently active.
+//
+// Shared by both checkboxes the viewer puts on screen — the panel row's
+// and the controls row's — so "enabling one copy turns the rest off"
+// means the same thing wherever it is clicked.
+//
+// The exclusions, all deliberate:
+//   - **Rows that aren't active already.** Nothing to gain by
+//     rewriting a value they effectively hold.
+//   - **Rows under a disabled collection.** Not competing with the copy
+//     being enabled, and their own checkbox renders disabled — so a
+//     flip made here could not be undone from the panel at all, and
+//     would silently destroy the user's stored intent for whenever
+//     they re-enable that collection.
+//   - **An sm-dev run's scripts.** Only their run changes them, and it
+//     keeps them off other tabs itself.
+export function otherActiveCopies(rows, keepId) {
+    return rows.filter((r) => r.script.id !== keepId && isActive(r) && !inRunCollection(r));
+}
+function inRunCollection(rel) {
+    return rel.collection !== null && isSmDevCollection(rel.collection.path);
+}
+// A copy that just became active follows the same exclusive rule as
+// the panel's checkboxes: it is the one wanted active, and leaving an
+// older copy of the same script on means both register and both run on
+// every page they match. Returns the copies it turned off.
+//
+// For a copy that is newly active: an install, a local copy, a move
+// into an enabled collection, and sm-dev's `script enable`. With no
+// other copy active, it does nothing. Skipped when the copy's
+// collection is disabled, so it isn't active itself.
+//
+// A copy that landed `invalid` still takes over: it is the one asked
+// for, and leaving a working copy on beside it would make two enabled
+// copies. Nothing runs until it is fixed, and then it runs without
+// another click.
+//
+// A run's test collection is left out both ways, as by `enableChanges`.
+export async function turnOffOtherCopies(scriptId) {
+    const timer = startPhaseTimer('turn off other copies');
+    const copy = await getScriptMeta(scriptId);
+    let related = [];
+    if (copy) {
+        const ids = await relatedCopyIds([copy]);
+        timer.mark('find copies', `${ids.size} script(s)`);
+        const [scripts, collections] = await Promise.all([getScriptMetas([...ids]), getCollections()]);
+        timer.mark('read copies');
+        related = relatedRowsOf(scripts, collections, copy);
+    }
+    let off = [];
+    // Skipped when this read shows nothing to turn off, the usual case
+    // after an install or a move, so it doesn't take the lock for nothing.
+    if (copy && otherActiveCopies(related, scriptId).length > 0) {
+        // Which copies are related comes from this read; which of them are
+        // active is decided again inside the write lock (`writeEnablementFrom`).
+        const scope = related.map((r) => r.script.id);
+        await writeEnablementFrom({ scriptIds: [scriptId, ...scope] }, (fresh) => {
+            const own = fresh.scripts.find((s) => s.id === scriptId);
+            if (!own)
+                return null;
+            const rows = relatedRowsOf(fresh.scripts, fresh.collections, own);
+            const ownRow = rows.find((r) => r.script.id === scriptId);
+            if (!ownRow || !isActive(ownRow) || inRunCollection(ownRow))
+                return null;
+            const others = otherActiveCopies(rows, scriptId);
+            if (others.length === 0)
+                return null;
+            off = others.map((r) => r.script);
+            // `started`: the copy became active in an earlier write, but it is
+            // stamped as becoming active now, the moment the copies it
+            // displaces go inactive (docs/script-enablement.md).
+            return { scripts: off.map((s) => ({ id: s.id, enabled: false })), started: [scriptId] };
+        }, timer);
+    }
+    timer.note(`${off.length} cop${off.length === 1 ? 'y' : 'ies'} turned off`);
+    timer.done();
+    return off;
+}
+// The ids of every stored copy related to any of `scripts`, themselves
+// included: from the worker's index (row-cache.ts), or where there is
+// none, a read of every row. Exactly the related ones, either way: the
+// index keys are the ones `findRelatedVersions` compares, and a caller
+// may act on every id (`enableWithin` turns off any active one).
+export async function relatedCopyIds(scripts) {
+    const indexed = await relatedScriptIds(scripts);
+    if (indexed)
+        return indexed;
+    const [all, collections] = await Promise.all([getAllScriptMetas(), getCollections()]);
+    const ids = new Set();
+    for (const script of scripts) {
+        ids.add(script.id);
+        for (const r of relatedRowsOf(all, collections, script))
+            ids.add(r.script.id);
+    }
+    return ids;
+}
+// Every copy related to `copy`, itself included. Compared by the STORED
+// row's location and header: what the rest of the store is compared
+// against, and for a github blob URL the resolved raw one.
+function relatedRowsOf(scripts, collections, copy) {
+    return allRelatedRows(findRelatedVersions({ scripts, collections, location: copy.fileUrl, header: copy.header ?? null }));
+}
+// Every related row in one list, in the order the panel draws them.
+// The exclusive rule spans both sections: the point is that one copy
+// of this script runs, not one copy per section.
+export function allRelatedRows(related) {
+    return [...related.sameLocation, ...related.sameIdentity];
+}
+// Sorts by the name the row will actually show. Using the raw
+// `displayName` would leave any collection without one — directory and
+// manifest collections, which only get an inferred name — sorted under
+// a string the user never sees, so the table would look unsorted.
+function collectionSortKey(r) {
+    return r.collection ? effectiveDisplayName(r.collection) : '';
+}
+// What the panel's Compare column compares: a copy's own source text
+// plus every `@require` body it loaded, in declaration order. Built
+// from the hashes the store already keeps for each (`contentHash` on
+// the row and on each require entry), so it is string assembly, not
+// hashing — and it is comparable across pages: a preview's download
+// gets the same shape from its text hash and the parse check's
+// requires.
+//
+// Requires are part of it because they are part of what runs: two
+// copies with the same body but a library that moved on behave
+// differently. `@resource` is not: it is data the script reads, not
+// code that runs.
+//
+// `undefined` when there is no content to compare: the row never
+// loaded, or its header declares `@require`s and none is stored — a
+// dependency that would not load leaves the list empty, and a preview
+// has none until its parse check lands. A body-only answer there would
+// call a broken copy DIFFERENT from a healthy twin with the same text,
+// or two broken copies SAME.
+export function contentFingerprint(script) {
+    if (!script.contentHash)
+        return undefined;
+    const requires = script.requires ?? [];
+    const declared = script.header ? getValues(script.header, 'require').length > 0 : false;
+    if (declared && requires.length === 0)
+        return undefined;
+    return [script.contentHash, ...requires.map((r) => r.contentHash)].join('\n');
+}

package/dist/extension/script-keys.js

@@ -0,0 +1,54 @@
+// The two keys that say whether two installed rows are copies of one
+// script: the same `@namespace` + `@name`, or the same absolute
+// location. Kept apart from script-identity.ts (which finds the copies)
+// so the store can use them without importing that module, which
+// imports the store. See [docs/script-identity.md].
+import { canonicalCollectionInput } from './directories.js';
+import { getValue } from '../userscript-header.js';
+// The ecosystem identity key: `@namespace` and `@name`, trimmed and
+// joined by a separator that can't occur in either.
+//
+// `null` when there is no `@name` — with nothing to key on we decline
+// to match rather than fold every nameless script together. A missing
+// `@namespace` is NOT the same case: the empty namespace is a real
+// (if unwise) value, and two scripts that both omit it and share a
+// name are treated as the same script, which is exactly what TM and
+// VM do. That is the convention's known weak spot, not ours to fix
+// unilaterally.
+//
+// Comparison is exact after trimming — no case folding, no URL
+// normalization of the namespace. `HTTP://Example.com/` and
+// `http://example.com/` are different namespaces to every other
+// manager, and quietly disagreeing would make our "same script"
+// answer differ from the one the user sees in Tampermonkey.
+//
+// Spelled as an escape, never as a literal NUL byte: a raw NUL makes
+// grep treat the whole source file as binary and print nothing for
+// every match in it.
+const IDENTITY_SEP = '\u0000';
+export function identityKey(header) {
+    if (!header)
+        return null;
+    const name = getValue(header, 'name')?.trim();
+    if (!name)
+        return null;
+    const namespace = getValue(header, 'namespace')?.trim() ?? '';
+    return `${namespace}${IDENTITY_SEP}${name}`;
+}
+// The location key: the one true spelling of an absolute script
+// location. `canonicalCollectionInput` is the same helper
+// `addCollection` uses, so a `file://` URL and the bare path spelling
+// of the same file collapse together — which is what lets a directory
+// collection's `fileUrl` (always a `file://` URL) match a container
+// row's bare path, and what makes a capture's URL match a row stored
+// before canonicalization existed.
+export function locationKey(absoluteUrl) {
+    return canonicalCollectionInput(absoluteUrl);
+}
+// Whether two rows are copies of one script, by either key.
+export function sameScript(a, b) {
+    if (locationKey(a.fileUrl) === locationKey(b.fileUrl))
+        return true;
+    const ia = identityKey(a.header ?? null);
+    return ia !== null && ia === identityKey(b.header ?? null);
+}