@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/assemblyManager/assemblyManager.js

@@ -1,101 +1,374 @@
 import { addDisposer, getParent, types } from '@jbrowse/mobx-state-tree';
-import { reaction } from 'mobx';
-import assemblyFactory from "./assembly.js";
-import { readConfObject } from "../configuration/index.js";
-import { when } from "../util/index.js";
+import { autorun, untracked, when } from 'mobx';
+import { readConfObject } from '../configuration/index.js';
+import assemblyFactory from './assembly.js';
+import { indexAssemblyNames } from './indexAssemblyNames.js';
+// How long waitForAssembly gives a handler that did NOT return a promise.
+// Nothing about such a handler is observable — it was told a name and said
+// nothing back — so there is no event to wait on and the only choices are a
+// clock or giving up immediately, which would break a fire-and-forget handler
+// that resolves the name a moment later. A handler that returns a promise gets
+// waited on properly and never reaches this.
+const UNDECLARED_HANDLER_GRACE_MS = 10000;
+function isThenable(value) {
+    return typeof value?.then === 'function';
+}
+/**
+ * Per-session record of the `Core-handleUnrecognizedAssembly` reports this
+ * manager has made, and of what the handlers said back.
+ *
+ * Each name is reported once. Handlers resolve a name asynchronously and out of
+ * band — the hubs plugin probes a url and adds a connection — and the assembly
+ * turning up is itself the reactive signal, so there is nothing for a second
+ * report to accomplish. `get` is called from render paths and computeds, so
+ * without this every re-render re-reported, and a handler that answers by
+ * fetching re-fetched: for exactly the names nothing can supply (a session
+ * naming a genome this host has never heard of) that is an unbounded stream of
+ * requests.
+ *
+ * A handler may return a promise, which is its statement that it is working on
+ * the name and that resolution is over when the promise settles. That is what
+ * lets `waitForAssembly` wait on an event rather than on a clock, so the promise
+ * should cover everything the handler does before the session gains anything
+ * observable — for a handler that adds a connection, at least the probe that
+ * decides whether to add one. The value is remembered here, so a later waiter
+ * can await the same attempt the first lookup started.
+ *
+ * Keyed on the session node so replacing the session (`setSession`) starts
+ * over: the connections and session assemblies a handler created for the old
+ * session went with it, so a name it already answered for has to be answerable
+ * again.
+ *
+ * Not observable state: `get` records into this from inside a derivation, where
+ * writing an observable would be a state change inside a computed. A closure
+ * rather than a class, because this is the type of a volatile and so reaches the
+ * inferred root-model type of every product, where a class loses either way —
+ * `private` members are still written into the declaration and then rejected as
+ * inaccessible (TS4094), while a field typed `Map<string, AssemblyReport>` names
+ * a module-local type (TS4058). Neither fires in this package; both fire in
+ * jbrowse-web, the embedded products and the react components. Two methods
+ * closing over the state name nothing but their own signatures.
+ */
+function createUnrecognizedAssemblyReports() {
+    let current;
+    const reports = new Map();
+    return {
+        /**
+         * Report `name` via `fire`, once per session, and keep what came back.
+         * `handlerCount` separates "every handler declined" from "nobody
+         * listening": the folded result is the same either way, and only the first
+         * is worth waiting out.
+         */
+        report(session, name, handlerCount, fire) {
+            if (current !== session) {
+                current = session;
+                reports.clear();
+            }
+            if (reports.has(name)) {
+                return;
+            }
+            const report = { handled: handlerCount > 0 };
+            // recorded before firing: a handler that synchronously reads back through
+            // `get` must not re-enter and report the same name again
+            reports.set(name, report);
+            const result = fire();
+            if (isThenable(result)) {
+                // a rejection is the handler's own to log; here it only means "done"
+                report.claim = Promise.resolve(result).then(() => { }, () => { });
+            }
+        },
+        /** what `report` recorded for `name` under `session`, if anything */
+        reportFor(session, name) {
+            return current === session ? reports.get(name) : undefined;
+        },
+    };
+}
+/**
+ * #stateModel AssemblyManager
+ */
 function assemblyManagerFactory(conf, pm) {
     return types
         .model({
+        /**
+         * #property
+         * this is automatically managed by an autorun which looks in the parent
+         * session.assemblies, session.sessionAssemblies, and
+         * session.temporaryAssemblies
+         */
         assemblies: types.array(assemblyFactory(conf, pm)),
     })
+        .volatile(() => ({
+        /**
+         * #volatile
+         * rate limiter for `get`'s `Core-handleUnrecognizedAssembly` reports, so
+         * each unknown name reaches the extension point once per session
+         */
+        unrecognizedReports: createUnrecognizedAssemblyReports(),
+    }))
         .views(self => ({
+        /**
+         * #getter
+         */
         get assemblyNameMap() {
-            const obj = {};
-            for (const assembly of self.assemblies) {
-                for (const name of assembly.allAliases) {
-                    obj[name] = assembly;
-                }
-            }
-            return obj;
+            return Object.fromEntries(indexAssemblyNames(self.assemblies, a => ({
+                name: a.name,
+                aliases: a.aliases,
+            })));
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         */
         getCanonicalAssemblyName(asmName) {
             return self.assemblyNameMap[asmName]?.name;
         },
-        getCanonicalAssemblyName2(asmName) {
-            return self.assemblyNameMap[asmName]?.name || asmName;
+        /**
+         * #method
+         */
+        getDisplayName(asmName) {
+            return self.assemblyNameMap[asmName]?.displayName || asmName;
         },
+        /**
+         * #method
+         * The assembly `asmName` names, or undefined. Reports a name it doesn't
+         * know to `Core-handleUnrecognizedAssembly` so a plugin can go supply it,
+         * which is a side effect: a caller only asking *whether* the session has
+         * the assembly wants {@link has} instead. Each name is reported at most
+         * once per session, since a handler resolves it out of band and the
+         * assembly turning up is itself the reactive signal.
+         */
         get(asmName) {
             if (asmName) {
                 const assembly = self.assemblyNameMap[asmName];
                 if (assembly) {
                     return assembly;
                 }
-                else if (!this.assemblyNamesList.includes(asmName)) {
-                    pm.evaluateExtensionPoint('Core-handleUnrecognizedAssembly', undefined, {
+                const { session } = getParent(self);
+                if (!this.has(asmName)) {
+                    // Extension point for loading unrecognized assemblies. Allows
+                    // plugins to provide custom logic for assembly resolution.
+                    //
+                    // A handler normally works out of band — adding a connection, say —
+                    // and the assembly turning up is what this manager reacts to, so
+                    // nothing here reads a result. But a handler that returns a promise
+                    // is telling waitForAssembly when it has finished trying, which is
+                    // the difference between waiting on an event and waiting on a
+                    // clock; UnrecognizedAssemblyReports keeps it, and keeps each name
+                    // from being reported more than once per session.
+                    const point = 'Core-handleUnrecognizedAssembly';
+                    self.unrecognizedReports.report(session, asmName, pm.extensionPointCallbackCount(point), () => pm.evaluateExtensionPoint(
+                    /** #extensionPoint Core-handleUnrecognizedAssembly | sync | Supply an assembly config when a referenced assembly is unknown. May return a promise settling when the handler has finished trying, which is what lets waitForAssembly stop waiting without a timeout */
+                    'Core-handleUnrecognizedAssembly', undefined, {
                         assemblyName: asmName,
-                        session: getParent(self).session,
-                    });
+                        session,
+                    }));
                 }
             }
             return undefined;
         },
+        /**
+         * #method
+         * Whether the session knows this assembly. Use this, not `get`, to ask
+         * only whether the assembly is present: `!has(name)` is exactly the
+         * condition under which `get` reports `name` to
+         * `Core-handleUnrecognizedAssembly`, so probing with `get` tells every
+         * installed plugin to go resolve a name that a caller supplying the
+         * assembly itself (a hub connection, MAF row navigation) is about to
+         * create.
+         */
+        // `get` calls this to decide whether to report, so the two can't drift.
+        // (`get` also reports each name at most once per session; the dedupe is a
+        // rate limit on top of this condition, not a second answer to it.)
+        //
+        // Both lookups are load-bearing, and the config one has to cover aliases
+        // as well: assemblyNameMap is keyed by allAliases ([name, ...aliases]) but
+        // only exists once the afterAttach autorun has built the models, while
+        // confByName answers off the configs from the first render.
+        // Screening on the canonical names alone left `vvx` unknown for the whole
+        // startup window even though the config for `volvox` names it — a wrong
+        // "no", which means the caller re-adds an assembly the session already
+        // has, or (the synteny import forms) decides the session has nothing it
+        // can open.
+        //
+        // The map is still asked first, and is not redundant: an assembly whose
+        // config has just left the list still has a model until the autorun
+        // disposes of it.
+        //
+        // Return type annotated because assemblyNameMap is a Record: its index
+        // read is never undefined to the compiler, so `!!` on it infers the
+        // literal `true` and `!has(name)` would be dead code at every call site.
+        has(asmName) {
+            return !!self.assemblyNameMap[asmName] || this.confByName.has(asmName);
+        },
+        /**
+         * #method
+         * The first of `asmNames` that hasn't finished loading — the one a view
+         * blocked on them is waiting for, and whose `statusMessage` /
+         * `statusProgress` its spinner should show. Returns the assembly itself
+         * (a stable reference, so a consuming getter doesn't invalidate on every
+         * read) or undefined once they are all loaded.
+         */
+        loadingAssembly(asmNames) {
+            return asmNames
+                .map(name => this.get(name))
+                .find(asm => !asm?.initialized);
+        },
+        /**
+         * #getter
+         * the canonical name of every configured assembly, read the way the
+         * afterAttach autorun names the models it builds
+         */
         get assemblyNamesList() {
-            return this.assemblyList.map(asm => asm.name);
+            return this.assemblyList.map(asm => readConfObject(asm, 'name'));
         },
+        /**
+         * #getter
+         * Every name the *configs* answer to — each assembly's `name` and its
+         * `aliases` — mapped to its config, which exists before the assembly's
+         * model does. What {@link has} knows before the models exist, and
+         * resolved by the same precedence as `assemblyNameMap`.
+         */
+        get confByName() {
+            return indexAssemblyNames(this.assemblyList, asm => ({
+                name: readConfObject(asm, 'name'),
+                aliases: readConfObject(asm, 'aliases') ?? [],
+            }));
+        },
+        /**
+         * #getter
+         * combined jbrowse.assemblies, session.sessionAssemblies, and
+         * session.temporaryAssemblies
+         */
         get assemblyList() {
             const { jbrowse: { assemblies }, session: { sessionAssemblies = [], temporaryAssemblies = [] } = {}, } = getParent(self);
-            return [
-                ...assemblies,
-                ...sessionAssemblies,
-                ...temporaryAssemblies,
-            ];
+            return [...assemblies, ...sessionAssemblies, ...temporaryAssemblies];
         },
         get rpcManager() {
             return getParent(self).rpcManager;
         },
     }))
         .views(self => ({
+        /**
+         * #method
+         * Wait out whatever might still be about to supply `assemblyName`, and
+         * resolve once nothing is.
+         *
+         * Resolution is a chain of events, not a duration: a handler probes and
+         * adds a connection, the connection fetches a config, the config's
+         * assemblies land in the session. Each link is observable, so each is
+         * waited on rather than guessed at.
+         *
+         * - the handler's own promise, if it returned one, covers the part before
+         *   the session gains anything to watch (the hubs plugin's HEAD probe)
+         * - any connection still fetching could be carrying the assembly, so its
+         *   `loading` flag going false is the next event. Every loading
+         *   connection counts, not just one naming this assembly: a connection
+         *   config need not declare what it will turn out to provide, and waiting
+         *   for one connection too many costs a moment while missing one returns
+         *   the wrong answer.
+         *
+         * A handler that returned nothing gets {@link UNDECLARED_HANDLER_GRACE_MS}
+         * instead, because it left nothing to wait on.
+         */
+        async settleAssemblyResolution(assemblyName) {
+            const { session } = getParent(self);
+            // read through assemblyNameMap, not get(): a predicate `when`
+            // re-evaluates should stay pure, and the report get() would make has
+            // already been made by waitForAssembly
+            const present = () => !!self.assemblyNameMap[assemblyName];
+            if (present()) {
+                return;
+            }
+            const report = self.unrecognizedReports.reportFor(session, assemblyName);
+            if (report?.claim) {
+                await report.claim;
+            }
+            else if (report?.handled) {
+                await when(present, { timeout: UNDECLARED_HANDLER_GRACE_MS }).catch(() => { });
+            }
+            // Nothing left that could still produce it. Both clauses are things
+            // that end on their own, so this needs no bound of its own.
+            const settled = () => 
+            // a config answering to the name, as its name or an alias, is
+            // already in the tree and the afterAttach autorun is about to build
+            // its model
+            !self.confByName.has(assemblyName) &&
+                // a connection mid-fetch could be carrying it. Every loading
+                // connection counts, not just one naming this assembly: a connection
+                // config need not declare what it will turn out to provide, and
+                // waiting for one connection too many costs a moment while missing
+                // one returns the wrong answer.
+                !session?.connectionInstances?.some(conn => conn.loading);
+            if (!present()) {
+                await when(() => present() || settled());
+            }
+        },
+    }))
+        .views(self => ({
+        /**
+         * #method
+         * use this method instead of assemblyManager.get(assemblyName) to get an
+         * assembly with regions loaded
+         */
         async waitForAssembly(assemblyName) {
             if (!assemblyName) {
                 throw new Error('no assembly name supplied to waitForAssembly');
             }
+            // get() rather than a bare map read: an unknown name has to reach
+            // Core-handleUnrecognizedAssembly before there is anything to wait for
             let assembly = self.get(assemblyName);
             if (!assembly) {
-                try {
-                    await when(() => Boolean(self.get(assemblyName)), {
-                        timeout: 10000,
-                    });
-                    assembly = self.get(assemblyName);
-                }
-                catch (e) {
-                }
+                await self.settleAssemblyResolution(assemblyName);
+                assembly = self.get(assemblyName);
             }
             if (!assembly) {
                 return undefined;
             }
+            // load() resolves only after setLoaded (regions + refNameAliases) has
+            // run and rejects on failure, so awaiting the promise is enough: no
+            // extra reactive wait, and no error check, needed
             await assembly.load();
-            await when(() => !!(assembly.regions && assembly.refNameAliases) || !!assembly.error);
-            if (assembly.error) {
-                throw assembly.error;
-            }
             return assembly;
         },
-        async getRefNameMapForAdapter(adapterConf, assemblyName, opts) {
-            if (assemblyName) {
-                const asm = await this.waitForAssembly(assemblyName);
-                return asm?.getRefNameMapForAdapter(adapterConf, opts);
+        /**
+         * #method
+         * {@link waitForAssembly}, but a name that cannot be resolved is an error
+         * rather than an `undefined` for the caller to interpret.
+         *
+         * Use it where a missing assembly produces a wrong result with no error.
+         * A refName map is one case: an empty map means an adapter gets queried
+         * with un-renamed refNames, finds nothing, and the track draws blank.
+         * Throwing here shows the assembly name to the user, who can add the
+         * assembly or fix the track.
+         *
+         * `waitForAssembly` returns only once every handler and connection that
+         * could supply the name has finished, so an unresolved name here is
+         * final and throwing does not race a late load.
+         */
+        async requireAssembly(assemblyName) {
+            const assembly = await this.waitForAssembly(assemblyName);
+            if (!assembly) {
+                throw new Error(`assembly "${assemblyName}" could not be resolved: it is not one of this session's assemblies and nothing supplied it`);
             }
-            return {};
+            return assembly;
         },
-        async getReverseRefNameMapForAdapter(adapterConf, assemblyName, opts) {
+        /**
+         * #method
+         * The refName map for an adapter under `assemblyName`. Throws if the
+         * assembly cannot be resolved — see {@link requireAssembly}. No
+         * `assemblyName` at all is not a failure, just nothing to rename.
+         */
+        async getRefNameMapForAdapter(adapterConf, assemblyName, opts) {
             if (assemblyName) {
-                const asm = await this.waitForAssembly(assemblyName);
-                return asm?.getReverseRefNameMapForAdapter(adapterConf, opts);
+                const asm = await this.requireAssembly(assemblyName);
+                return asm.getRefNameMapForAdapter(adapterConf, opts);
             }
             return {};
         },
+        /**
+         * #method
+         */
         isValidRefName(refName, assemblyName) {
             const assembly = self.get(assemblyName);
             if (assembly) {
@@ -106,23 +379,51 @@ function assemblyManagerFactory(conf, pm) {
     }))
         .actions(self => ({
         afterAttach() {
-            addDisposer(self, reaction(() => self.assemblyList, assemblyConfs => {
-                for (const asm of self.assemblies) {
-                    if (!asm.configuration) {
-                        this.removeAssembly(asm);
-                    }
+            const reconcile = (assemblyConfs) => {
+                // filter() returns a new plain array, so removing from
+                // self.assemblies in the loop below does not skip elements
+                // (removeAssembly splices the live observable array)
+                const orphaned = self.assemblies.filter(a => !a.configuration);
+                for (const asm of orphaned) {
+                    this.removeAssembly(asm);
                 }
+                const built = new Set(self.assemblies.map(a => a.name));
                 for (const conf of assemblyConfs) {
-                    const name = readConfObject(conf, 'name');
-                    if (!self.assemblies.some(a => a.name === name)) {
+                    if (!built.has(readConfObject(conf, 'name'))) {
                         this.addAssembly(conf);
                     }
                 }
-            }, { fireImmediately: true, name: 'assemblyManagerAfterAttach' }));
+            };
+            // also here, because an enclosing action defers the autorun's first
+            // run, and a load waiting on the model would wait for that
+            reconcile(self.assemblyList);
+            addDisposer(self, autorun(() => {
+                const assemblyConfs = self.assemblyList;
+                // eslint-disable-next-line no-restricted-syntax -- self-write: removes from the assemblies it reads
+                untracked(() => {
+                    reconcile(assemblyConfs);
+                });
+            }, { name: 'assemblyManagerAfterAttach' }));
         },
+        /**
+         * #action
+         * private: you would generally want to add to manipulate
+         * jbrowse.assemblies, session.sessionAssemblies, or
+         * session.temporaryAssemblies instead of using this directly
+         */
         removeAssembly(asm) {
             self.assemblies.remove(asm);
         },
+        /**
+         * #action
+         * private: you would generally want to add to manipulate
+         * jbrowse.assemblies, session.sessionAssemblies, or
+         * session.temporaryAssemblies instead of using this directly
+         *
+         * this can take an active instance of an assembly, in which case it is
+         * referred to, or it can take an identifier e.g. assembly name, which is
+         * used as a reference. snapshots cannot be used
+         */
         addAssembly(configuration) {
             self.assemblies.push({ configuration });
         },

package/esm/assemblyManager/expandAssemblyConfigShorthand.d.ts

@@ -0,0 +1,39 @@
+import type PluginManager from '../PluginManager.ts';
+export declare function referenceSequenceTrackId(assemblyName: unknown): string;
+/**
+ * The part of {@link expandAssemblyShorthand} that needs no plugin manager, for
+ * a reader of raw config JSON: the flat `{ name, uri }` form moves onto
+ * `sequence.adapter`, and `sequence.type` and `sequence.trackId` are each
+ * filled in when omitted. Returns `snap` itself when there is nothing to do.
+ */
+export declare function expandAssemblySequence<T>(snap: T): T;
+/**
+ * Expand an assembly snapshot's own shorthands into the `sequence` an assembly
+ * config declares: {@link expandAssemblySequence}, then the sequence adapter's
+ * type guessed from its `uri`.
+ *
+ * This is the assembly config schema's `preProcessSnapshot`, lifted out so a
+ * caller that has to see canonical locations *before* MST builds the tree can
+ * run it too. `localFiles` is that caller: it rewrites `{ uri: <a registered
+ * name> }` location nodes into blobs, and until this has run the only `uri` in
+ * a shorthand assembly is on the assembly itself, where it is not a location
+ * node and must not be rewritten as one. Idempotent, and returns `snap` itself
+ * when there is nothing to expand.
+ */
+export declare function expandAssemblyShorthand<T>(snap: T, pluginManager: PluginManager): T;
+/**
+ * Fill in an assembly `sequence.adapter`'s `type` from its `uri` when the type
+ * is omitted, so `sequence: { adapter: { uri: 'genome.fa.gz' } }` resolves to a
+ * `BgzipFastaAdapter` (and `.fa` → indexed, `.2bit` → `TwoBitAdapter`). Uses the
+ * same `Core-guessAdapterForLocation` extension point the "Add track" flow uses,
+ * so every host describes a custom genome with just a URL and lets jbrowse-core
+ * pick the adapter — no adapter-type table in the Python/R/JS bindings.
+ *
+ * Only the type comes off the guess: the adapter's own `normalizeSnapshot`
+ * expands the `uri` into the location slots it declares, so the shorthand
+ * expands to the same thing here as it does when the config names the type.
+ * A `uri` matching no sequence adapter is left untouched, and the same object
+ * reference comes back when there is nothing to expand, so callers can cheaply
+ * skip a rebuild.
+ */
+export declare function expandAssemblySequenceAdapter(sequence: unknown, pluginManager: PluginManager): unknown;

package/esm/assemblyManager/expandAssemblyConfigShorthand.js

@@ -0,0 +1,114 @@
+import { isPlainObject } from '../util/objectUtils.js';
+import { UNKNOWN } from '../util/tracks.js';
+export function referenceSequenceTrackId(assemblyName) {
+    return `${assemblyName}-ReferenceSequenceTrack`;
+}
+/**
+ * The part of {@link expandAssemblyShorthand} that needs no plugin manager, for
+ * a reader of raw config JSON: the flat `{ name, uri }` form moves onto
+ * `sequence.adapter`, and `sequence.type` and `sequence.trackId` are each
+ * filled in when omitted. Returns `snap` itself when there is nothing to do.
+ */
+export function expandAssemblySequence(snap) {
+    if (!isPlainObject(snap)) {
+        return snap;
+    }
+    const { uri, baseUri, ...rest } = snap;
+    const given = rest.sequence;
+    // baseUri, stamped next to `uri` by addRelativeUris, rides down onto the
+    // adapter so the sequence resolves against the config's location
+    const seq = typeof uri === 'string' &&
+        (given === undefined || (isPlainObject(given) && !given.adapter))
+        ? {
+            ...(isPlainObject(given) ? given : {}),
+            adapter: { uri, ...(baseUri ? { baseUri } : {}) },
+        }
+        : given;
+    if (!isPlainObject(seq) ||
+        (seq === snap.sequence && 'type' in seq && 'trackId' in seq)) {
+        return snap;
+    }
+    return {
+        ...rest,
+        sequence: {
+            type: 'ReferenceSequenceTrack',
+            trackId: referenceSequenceTrackId(snap.name),
+            ...seq,
+        },
+    };
+}
+/**
+ * Expand an assembly snapshot's own shorthands into the `sequence` an assembly
+ * config declares: {@link expandAssemblySequence}, then the sequence adapter's
+ * type guessed from its `uri`.
+ *
+ * This is the assembly config schema's `preProcessSnapshot`, lifted out so a
+ * caller that has to see canonical locations *before* MST builds the tree can
+ * run it too. `localFiles` is that caller: it rewrites `{ uri: <a registered
+ * name> }` location nodes into blobs, and until this has run the only `uri` in
+ * a shorthand assembly is on the assembly itself, where it is not a location
+ * node and must not be rewritten as one. Idempotent, and returns `snap` itself
+ * when there is nothing to expand.
+ */
+export function expandAssemblyShorthand(snap, pluginManager) {
+    const expanded = expandAssemblySequence(snap);
+    if (!isPlainObject(expanded)) {
+        return expanded;
+    }
+    const sequence = expandAssemblySequenceAdapter(expanded.sequence, pluginManager);
+    return sequence === expanded.sequence ? expanded : { ...expanded, sequence };
+}
+/**
+ * Fill in an assembly `sequence.adapter`'s `type` from its `uri` when the type
+ * is omitted, so `sequence: { adapter: { uri: 'genome.fa.gz' } }` resolves to a
+ * `BgzipFastaAdapter` (and `.fa` → indexed, `.2bit` → `TwoBitAdapter`). Uses the
+ * same `Core-guessAdapterForLocation` extension point the "Add track" flow uses,
+ * so every host describes a custom genome with just a URL and lets jbrowse-core
+ * pick the adapter — no adapter-type table in the Python/R/JS bindings.
+ *
+ * Only the type comes off the guess: the adapter's own `normalizeSnapshot`
+ * expands the `uri` into the location slots it declares, so the shorthand
+ * expands to the same thing here as it does when the config names the type.
+ * A `uri` matching no sequence adapter is left untouched, and the same object
+ * reference comes back when there is nothing to expand, so callers can cheaply
+ * skip a rebuild.
+ */
+export function expandAssemblySequenceAdapter(sequence, pluginManager) {
+    const adapter = isPlainObject(sequence) ? sequence.adapter : undefined;
+    if (isPlainObject(sequence) &&
+        isPlainObject(adapter) &&
+        !('type' in adapter) &&
+        typeof adapter.uri === 'string') {
+        const { uri, baseUri, ...extras } = adapter;
+        const guesser = pluginManager.evaluateExtensionPoint('Core-guessAdapterForLocation', () => undefined);
+        // baseUri (stamped next to `uri` by addRelativeUris for hub/relative configs)
+        // rides on the file location so the guessed fastaLocation and its derived
+        // .fai/.gzi siblings all resolve against the config's own location
+        const file = {
+            uri,
+            locationType: 'UriLocation',
+            ...(typeof baseUri === 'string' ? { baseUri } : {}),
+        };
+        const guess = guesser(file, undefined);
+        if (!guess || guess.type === UNKNOWN) {
+            return sequence;
+        }
+        // the type is the only thing the guess is needed for. The adapter's own
+        // normalizeSnapshot expands `uri` and everything riding with it — a 2bit's
+        // `chromSizes`, which the guess has no slot for and MST then dropped
+        // unannounced — so this is not a second place that knows how a sequence
+        // file names its sidecars. An adapter declaring no shorthand keeps the
+        // guess's derived locations.
+        const normalize = pluginManager.hasAdapterType(guess.type)
+            ? pluginManager.getAdapterType(guess.type).normalizeSnapshot
+            : undefined;
+        const shorthand = { ...adapter, type: guess.type };
+        const normalized = normalize?.(shorthand) ?? shorthand;
+        // `uri` is consumed, and it has to GO: localFiles substitutes a blob into a
+        // location node, and an adapter still carrying `uri` reads as one
+        const full = normalized === shorthand ? { ...guess, ...extras } : normalized;
+        const { uri: _consumed, baseUri: _spent, ...expanded } = full;
+        return { ...sequence, adapter: expanded };
+    }
+    return sequence;
+}

package/esm/assemblyManager/geneticCodes.d.ts

@@ -0,0 +1,21 @@
+import type PluginManager from '../PluginManager.ts';
+import type { BaseOptions } from '../data_adapters/BaseAdapter/types.ts';
+import type { FileLocation } from '../util/types/index.ts';
+import type { RefNameAliases } from './refNameMaps.ts';
+/**
+ * NCBI genetic-code (translation table) id for `refName`, taken from the first
+ * of `maps` holding an entry for it, else the standard code (1).
+ *
+ * A map key and `refName` may each independently be a canonical name or an
+ * alias of one: a config generated from NCBI keys by the GFF's RefSeq accession
+ * while the assembly's canonical name is the UCSC-style one, and callers that
+ * pass a feature's own refName rather than the canonical one. Both sides are
+ * resolved through `refNameAliases` (loaded from the chromAlias file) so they
+ * meet. The maps are per-assembly contig lists, so scanning them is cheap.
+ */
+export declare function lookupGeneticCodeId(refName: string, refNameAliases: RefNameAliases | undefined, maps: Record<string, number>[]): number;
+export declare function getGeneticCodesFromFile({ location, pluginManager, opts, }: {
+    location: FileLocation | undefined;
+    pluginManager: PluginManager;
+    opts?: BaseOptions;
+}): Promise<Record<string, number>>;