@jbrowse/cli 4.3.0 → 5.0.0-beta.1

package/dist/commands/validate/displayDefaultKeys.js

@@ -0,0 +1,28 @@
+import { configManifest } from './configManifest.generated.js';
+// `displayDefaults: {color: 'green'}` is a track-level shorthand
+// (expandTrackConfigShorthand.ts) routing each key to whichever of the track's
+// display types declares it, so the keys a track accepts are the union of those
+// displays' slots rather than the track's own.
+export function displayDefaultKeys(trackEntry, manifest) {
+    return (trackEntry.displayTypes ?? []).flatMap(name => manifest.displays[name]?.slots.map(slot => slot.name) ?? []);
+}
+// The same set for a track type named rather than resolved — add-track knows
+// the type it is writing, not a manifest entry. The display types come back
+// alongside, because most tracks offer exactly one and naming it is the whole
+// difference between a message someone can act on and one they cannot: an
+// AlignmentsTrack has only LinearAlignmentsDisplay, so "no AlignmentsTrack
+// display declares color" sends the reader looking for the other displays.
+//
+// Both empty for a type the manifest does not carry (a plugin's), which no
+// check here can speak to.
+export function displayDefaultsForTrackType(trackType, manifest = configManifest) {
+    const entry = lookup(manifest.tracks, trackType);
+    return {
+        displayTypes: entry?.displayTypes ?? [],
+        keys: entry ? displayDefaultKeys(entry, manifest) : [],
+    };
+}
+function lookup(group, typeName) {
+    return (group[typeName] ??
+        Object.values(group).find(entry => entry.aliases?.includes(typeName)));
+}

package/dist/commands/validate/index.js

@@ -0,0 +1,97 @@
+import { parseArgs } from 'node:util';
+import { printHelp, readConfigFile } from '../../utils.js';
+import { validateConfig } from './validateConfig.js';
+const description = 'Check a JBrowse configuration for errors, including the ones JBrowse itself accepts silently';
+const notes = `A config key JBrowse does not recognize is ignored rather than reported, so a
+misspelled slot leaves the track loading normally with the setting doing
+nothing. That is what this command is mainly for.
+
+Two levels are reported:
+
+  error    JBrowse accepts it and silently does the wrong thing — an unknown
+           slot, a track naming an assembly the config never defines, a
+           defaultSession naming a trackId that does not exist, a duplicate
+           trackId. Exits 1.
+
+  warning  JBrowse will complain by itself on load, or handles it — a type name
+           the core plugins do not register (expected if one of your plugins
+           registers it), or a legacy key a migration rewrites. Never fails
+           the run.
+
+Types registered by plugins are not known to this command, so they come through
+as warnings rather than errors.`;
+const examples = [
+    '# check the config.json in the current directory',
+    '$ jbrowse validate',
+    '',
+    '# check a specific config or saved session',
+    '$ jbrowse validate /path/to/config.json',
+    '$ jbrowse validate mysession.jbrowse',
+    '',
+    '# machine-readable output',
+    '$ jbrowse validate config.json --json',
+];
+const options = {
+    json: {
+        type: 'boolean',
+        description: 'Output the findings as JSON instead of text',
+    },
+    quiet: {
+        type: 'boolean',
+        short: 'q',
+        description: 'Only print errors, suppressing warnings and notes',
+    },
+    help: { type: 'boolean', short: 'h', description: 'Show help' },
+};
+function format({ level, where, message }) {
+    return where ? `${level}: ${where}: ${message}` : `${level}: ${message}`;
+}
+export async function run(args) {
+    const { values: flags, positionals } = parseArgs({
+        options,
+        args,
+        allowPositionals: true,
+    });
+    if (flags.help) {
+        printHelp({
+            description,
+            examples,
+            notes,
+            usage: 'jbrowse validate [config.json] [options]',
+            options,
+        });
+        return;
+    }
+    const file = positionals[0] ?? 'config.json';
+    // readConfigFile, not readJsonFile: running from the wrong directory is the
+    // most common way this fails, and it says which path it looked at.
+    const config = await readConfigFile(file);
+    const result = validateConfig(config);
+    if (flags.json) {
+        console.log(JSON.stringify({ file, ok: result.errorCount === 0, ...result }, null, 2));
+    }
+    else {
+        const shown = flags.quiet
+            ? result.problems.filter(p => p.level === 'error')
+            : result.problems;
+        if (!flags.quiet) {
+            for (const note of result.notes) {
+                console.log(`note: ${note}`);
+            }
+        }
+        for (const problem of shown) {
+            console.log(format(problem));
+        }
+        if (result.problems.length === 0) {
+            console.log(`${file} looks good`);
+        }
+        else {
+            console.log(`\n${result.errorCount} error(s), ${result.warningCount} warning(s) in ${file}`);
+        }
+    }
+    if (result.errorCount > 0) {
+        // Non-zero so this can gate a deploy. Thrown rather than process.exit so it
+        // goes through the same error path as every other command.
+        throw new Error(`${result.errorCount} error(s) found in ${file}`);
+    }
+}

package/dist/commands/validate/suggest.js

@@ -0,0 +1,35 @@
+// "did you mean" for a mistyped identifier, shared by the validator and by
+// add-track's up-front check on the settings it is about to write.
+function editDistance(a, b) {
+    // Two rolling rows rather than the full matrix; these are short identifiers
+    // and this runs once per unknown key.
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+// The nearest candidate, if it is near enough to be worth naming. The threshold
+// scales with length so `uri` doesn't match every other three-letter slot while
+// a longer typo still resolves.
+export function suggest(word, candidates) {
+    const limit = Math.max(2, Math.floor(word.length / 3));
+    let best;
+    let bestScore = Infinity;
+    for (const candidate of candidates) {
+        const score = editDistance(word.toLowerCase(), candidate.toLowerCase());
+        if (score < bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return bestScore <= limit ? best : undefined;
+}
+export function didYouMean(word, candidates) {
+    const hit = suggest(word, candidates);
+    return hit ? ` — did you mean "${hit}"?` : '';
+}

package/dist/commands/validate/types.js

@@ -0,0 +1,6 @@
+// Shape of the generated config manifest (configManifest.generated.ts), which
+// scripts/generateConfigManifest.ts reads out of the live ConfigurationSchema
+// objects. Declared here rather than inferred from the generated file so the
+// generator and the validator agree on a contract, and a generator change that
+// drops a field is a type error rather than a silent behaviour change.
+export {};

package/dist/commands/validate/validateConfig.js

@@ -0,0 +1,457 @@
+// Checks a JBrowse config (or a saved session file) against the generated
+// config-slot manifest.
+//
+// Why this exists at all, given MST type-checks a config on load: **MST models
+// ignore snapshot keys they do not declare**. Write `bamLocatoin`, or a
+// `renderers: {...}` block from an older config, and nothing anywhere reports
+// it — the track loads, appears, and the setting silently does nothing. That is
+// the check no other layer performs, and it is the mistake config authors
+// (human or agent) make most.
+//
+// Pure: no filesystem, no process exit. The command wrapper owns both.
+import { configManifest } from './configManifest.generated.js';
+import { displayDefaultKeys } from './displayDefaultKeys.js';
+import { didYouMean } from './suggest.js';
+// ------------------------------------------------------------------ reporting
+class Report {
+    problems = [];
+    notes = [];
+    error(where, message) {
+        this.problems.push({ level: 'error', where, message });
+    }
+    warn(where, message) {
+        this.problems.push({ level: 'warning', where, message });
+    }
+    note(message) {
+        this.notes.push(message);
+    }
+    result() {
+        return {
+            problems: this.problems,
+            notes: this.notes,
+            errorCount: this.problems.filter(p => p.level === 'error').length,
+            warningCount: this.problems.filter(p => p.level === 'warning').length,
+        };
+    }
+}
+// ------------------------------------------------------------------- checking
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Keys a schema entry accepts as input: what it declares, plus the shorthands
+// normalizeSnapshot expands — an adapter written with `uri` never mentions
+// `bamLocation`, and both forms are correct.
+function acceptedKeys(entry) {
+    return [...entry.slots.map(s => s.name), ...(entry.shorthandKeys ?? [])];
+}
+// A key JBrowse fills in for itself, so writing one by hand is an anti-pattern
+// whether or not the schema happens to declare a slot for it. Both halves get a
+// message that says so, because the generic ones send the author looking for a
+// typo in a key that is spelled correctly.
+//
+// `sequenceAdapter` is the standing case, and it is now uniform:
+// `getFeatureAdapter` and `CoreGetRefNames` prime every feature adapter's
+// `sequenceAdapterConfig` from the assembly the track is displayed against, and
+// `getSequenceSubAdapter` is what every adapter that reads a sequence resolves
+// through. So no track has to carry one — three grape/peach/volvox configs were
+// copying their own assembly's FASTA urls into a GC track, and two hg002 tracks
+// carried one on a `CramAdapter`, which declares no such slot at all.
+//
+// Two levels, and the split is this validator's own rule: an undeclared key does
+// nothing where it is written (error), a declared one works and is simply the
+// wrong way round (warning).
+const SELF_SUPPLIED = {
+    sequenceAdapter: {
+        undeclared: 'JBrowse takes the sequence from the assembly the track is displayed against, and this adapter declares no `sequenceAdapter` slot, so the one written here is never read — delete it',
+        declared: '`sequenceAdapter` is set by hand. JBrowse takes the sequence from the assembly the track is displayed against, so this is only needed to read some OTHER sequence — and it pins the track to that source even when the assembly changes. Delete it unless that is what you meant',
+    },
+};
+function checkSlots(obj, entry, where, report) {
+    const accepted = acceptedKeys(entry);
+    const legacyKeys = entry.legacyKeys ?? [];
+    for (const key of Object.keys(obj)) {
+        if (accepted.includes(key)) {
+            const selfSupplied = SELF_SUPPLIED[key];
+            if (selfSupplied) {
+                report.warn(`${where}.${key}`, selfSupplied.declared);
+            }
+            continue;
+        }
+        // JSON has no comments, so people reach for a `_comment` key. MST drops it
+        // like any other undeclared key, which is what the author wanted — calling
+        // that "silently does nothing" is true and useless, and a validator that
+        // cries wolf on a deliberate annotation is one an author learns to ignore.
+        if (/^_+comment/i.test(key)) {
+            continue;
+        }
+        // A legacy key is consumed by the schema's own preProcessSnapshot and
+        // lifted into current slots, so the config does load — but it is stale, and
+        // whether every setting inside it survived the lift is worth a look.
+        if (legacyKeys.includes(key)) {
+            report.warn(`${where}.${key}`, `"${key}" is a legacy key that a migration rewrites into current slots — the config loads, but check the settings inside it landed`);
+            continue;
+        }
+        report.error(`${where}.${key}`, SELF_SUPPLIED[key]?.undeclared ??
+            `unknown slot "${key}"${didYouMean(key, accepted)} — JBrowse ignores keys it does not declare, so this setting silently does nothing`);
+    }
+    // Recurse into sub-schemas the config actually filled in. One it omits is
+    // fine: the sub-schema supplies its own defaults.
+    for (const slot of entry.slots) {
+        const value = obj[slot.name];
+        if (slot.subSlots && isRecord(value)) {
+            checkSlots(value, { slots: slot.subSlots }, `${where}.${slot.name}`, report);
+        }
+    }
+}
+// Resolves a `type` against one of the manifest's groups.
+//
+// An unrecognized type is a WARNING, never an error, and the line is drawn
+// there deliberately:
+//
+//   error   = JBrowse accepts the config and silently does the wrong thing
+//   warning = JBrowse will complain by itself when the config loads
+//
+// An unknown type is loud — MST throws "Unknown track type" on load, so the
+// author finds out either way. It is also frequently not wrong: a plugin
+// registers types this manifest never saw. An unknown *slot* has neither
+// property, which is why that one is the error.
+function resolveType(obj, group, groupLabel, where, report) {
+    const typeName = obj.type;
+    if (typeof typeName !== 'string') {
+        report.error(where, `missing "type" — expected one of the ${groupLabel} types`);
+        return undefined;
+    }
+    const canonical = typeName in group
+        ? typeName
+        : // An old type name a current type still answers to. baseTrackConfig
+            // canonicalizes it before validation and sessionMigrations restores the
+            // settings that made the old type distinct, so this is supported config
+            // — check it against the type that absorbed it.
+            Object.keys(group).find(name => group[name].aliases?.includes(typeName));
+    const entry = canonical === undefined ? undefined : group[canonical];
+    if (entry && canonical !== undefined) {
+        return { ...entry, canonicalName: canonical };
+    }
+    report.warn(where, `${groupLabel} type "${typeName}" is not registered by the core plugins${didYouMean(typeName, Object.keys(group))} — it may come from a plugin`);
+    return undefined;
+}
+function checkAdapter(adapter, manifest, where, report) {
+    if (!isRecord(adapter)) {
+        report.error(where, 'missing "adapter"');
+        return;
+    }
+    const entry = resolveType(adapter, manifest.adapters, 'adapter', `${where}.type`, report);
+    if (entry) {
+        checkSlots(adapter, entry, where, report);
+    }
+}
+// A pluggable sub-object written inline: resolve its type against `group`, then
+// check its own slots. `connections`, `aggregateTextSearchAdapters` and a
+// track's `textSearching.textSearchAdapter` are all this shape, and none of
+// them was opened at all — a Trix path typo is a search that returns nothing,
+// which is the class of mistake this command exists to catch.
+function checkPluggable(obj, group, groupLabel, where, report) {
+    if (!isRecord(obj)) {
+        report.error(where, `${groupLabel} must be an object`);
+        return;
+    }
+    const entry = resolveType(obj, group, groupLabel, `${where}.type`, report);
+    if (entry) {
+        checkSlots(obj, entry, where, report);
+    }
+}
+function checkDisplayDefaults(defaults, trackEntry, manifest, where, report) {
+    if (!isRecord(defaults)) {
+        report.error(where, 'displayDefaults must be an object of display settings');
+        return;
+    }
+    const accepted = displayDefaultKeys(trackEntry, manifest);
+    if (accepted.length === 0) {
+        return;
+    }
+    for (const key of Object.keys(defaults)) {
+        if (!accepted.includes(key)) {
+            report.error(`${where}.${key}`, `no display of this track declares "${key}"${didYouMean(key, accepted)}`);
+        }
+    }
+}
+function checkTrack(track, index, manifest, report, ctx) {
+    const where = `tracks[${index}]`;
+    // The loose form: a data file and no adapter. JBrowse infers the track type
+    // and adapter from the file's extension at load, so neither is required
+    // here, and neither can be checked against the manifest without the format
+    // plugins' guessers — the keys written beside `uri` still are.
+    const loose = typeof track.uri === 'string' && !('adapter' in track);
+    const entry = loose && track.type === undefined
+        ? undefined
+        : resolveType(track, manifest.tracks, 'track', `${where}.type`, report);
+    const trackId = track.trackId;
+    if (typeof trackId !== 'string' || !trackId) {
+        report.error(`${where}.trackId`, 'missing "trackId"');
+    }
+    else if (ctx.seenTrackIds.has(trackId)) {
+        report.error(`${where}.trackId`, `duplicate trackId "${trackId}" — a later track with the same id shadows the earlier one`);
+    }
+    else {
+        ctx.seenTrackIds.add(trackId);
+    }
+    const names = track.assemblyNames;
+    if (!Array.isArray(names) || names.length === 0) {
+        if (!loose || ctx.assemblyCount !== 1) {
+            report.error(`${where}.assemblyNames`, 'missing "assemblyNames"');
+        }
+    }
+    else {
+        for (const name of names) {
+            if (typeof name === 'string' && !ctx.assemblyNames.has(name)) {
+                // The connection caveat leads and the spelling guess trails, because a
+                // connection needn't be in this file to supply the assembly — the one
+                // that supplies test_data/volvox's `volvox_del2` is added at runtime,
+                // and `did you mean "volvox_del"?` called a working config a typo.
+                report.error(`${where}.assemblyNames`, `assembly "${name}" is not defined in this config, and no connection here supplies one — though a connection added at runtime can${didYouMean(name, [...ctx.assemblyNames])}`);
+            }
+        }
+    }
+    if (entry) {
+        // displayDefaults is a shorthand no track schema declares, so it is
+        // exempted from the track's own slot check and validated on its own terms.
+        checkSlots(track, {
+            ...entry,
+            shorthandKeys: [
+                ...(entry.shorthandKeys ?? []),
+                'displayDefaults',
+                ...(loose ? ['uri', 'index'] : []),
+            ],
+        }, where, report);
+        if (track.displayDefaults !== undefined) {
+            checkDisplayDefaults(track.displayDefaults, entry, manifest, `${where}.displayDefaults`, report);
+        }
+    }
+    if (!loose) {
+        checkAdapter(track.adapter, manifest, `${where}.adapter`, report);
+    }
+    const textSearching = track.textSearching;
+    if (isRecord(textSearching) &&
+        textSearching.textSearchAdapter !== undefined) {
+        checkPluggable(textSearching.textSearchAdapter, manifest.textSearchAdapters, 'text search adapter', `${where}.textSearching.textSearchAdapter`, report);
+    }
+    if (Array.isArray(track.displays)) {
+        for (const [i, display] of track.displays.entries()) {
+            if (!isRecord(display)) {
+                continue;
+            }
+            const displayWhere = `${where}.displays[${i}]`;
+            const displayEntry = resolveType(display, manifest.displays, 'display', `${displayWhere}.type`, report);
+            if (displayEntry) {
+                checkSlots(display, displayEntry, displayWhere, report);
+            }
+        }
+    }
+}
+function checkAssembly(assembly, index, manifest, report) {
+    const where = `assemblies[${index}]`;
+    if (typeof assembly.name !== 'string' || !assembly.name) {
+        report.error(`${where}.name`, 'missing assembly "name"');
+    }
+    // An assembly has three levels of shorthand, all filled in by
+    // assemblyConfigSchema's preProcessSnapshot, and this used to reject every one
+    // of them — including `{ name, uri }`, which the cookbook calls the smallest
+    // possible config:
+    //
+    //   1. `{ name, uri }`                          -> sequence: { adapter: { uri } }
+    //   2. `sequence: { adapter: { uri } }`         -> adapter type from the extension
+    //   3. sequence with no type/trackId            -> ReferenceSequenceTrack, derived id
+    //
+    // Only (2) can't be checked here, and deliberately: the type is guessed
+    // through the `Core-guessAdapterForLocation` extension point, and this command
+    // loads no plugins on purpose. A `uri` is therefore taken as enough — saying
+    // nothing about an adapter we can't name beats calling a working config broken.
+    const sequence = assembly.sequence ??
+        (typeof assembly.uri === 'string'
+            ? { adapter: { uri: assembly.uri } }
+            : undefined);
+    if (!isRecord(sequence)) {
+        report.error(`${where}.sequence`, 'missing "sequence" track (or a `uri` naming the sequence file)');
+        return;
+    }
+    if (isRecord(sequence.adapter) && !('type' in sequence.adapter)) {
+        if (typeof sequence.adapter.uri !== 'string') {
+            report.error(`${where}.sequence.adapter`, 'adapter has neither a "type" nor a "uri" to infer one from');
+        }
+        return;
+    }
+    checkAdapter(sequence.adapter, manifest, `${where}.sequence.adapter`, report);
+}
+// A display node written inside a session — `views[].tracks[].displays[]` — is
+// instantiated by the display's STATE MODEL, not by its config schema. Almost
+// every track-menu setting is a config slot now, and a slot name here is dropped
+// exactly like a misspelling: the session loads, the track appears, the setting
+// does nothing. That is the same silent failure the slot checks above exist for,
+// on the surface people hand-write most, and it is why a whole class of these
+// sat unnoticed in this repo's own fixtures.
+//
+// The advice differs from the unknown-slot case, so the messages do too — a slot
+// is real, it is just in the wrong place, and there are two right places for it.
+function checkSessionDisplay(display, manifest, where, report) {
+    const entry = resolveType(display, manifest.displays, 'display', `${where}.type`, report);
+    // A display type the manifest doesn't know (a plugin's) has already been
+    // reported as a warning by resolveType; its props are unknowable here.
+    if (!entry?.stateModelProps) {
+        return;
+    }
+    const props = entry.stateModelProps;
+    const slots = entry.slots.map(slot => slot.name);
+    const migrated = new Set([
+        ...(manifest.migratedDisplayKeys['*'] ?? []),
+        ...(manifest.migratedDisplayKeys[entry.canonicalName] ?? []),
+    ]);
+    for (const key of Object.keys(display)) {
+        if (props.includes(key)) {
+            continue;
+        }
+        if (migrated.has(key)) {
+            report.warn(`${where}.${key}`, `"${key}" is a legacy display-instance key that a session migration lifts onto the config slot replacing it — it still works, but writing the current slot is clearer`);
+        }
+        else if (slots.includes(key)) {
+            report.error(`${where}.${key}`, `"${key}" is a config slot, not a display property, so a session snapshot drops it and the setting silently does nothing — put it on the track's "displays" entry under "tracks", or in a "trackConfigDeltas" entry, instead`);
+        }
+        else {
+            report.error(`${where}.${key}`, `unknown display property "${key}"${didYouMean(key, [...props, ...slots])} — a session snapshot drops keys the display does not declare, so this setting silently does nothing`);
+        }
+    }
+}
+// Walks the tracks of a view and its sub-views (a synteny view holds a row of
+// LGVs, each with tracks of its own).
+function checkSessionViewTracks(view, manifest, where, report) {
+    if (!isRecord(view)) {
+        return;
+    }
+    if (Array.isArray(view.tracks)) {
+        for (const [i, track] of view.tracks.entries()) {
+            if (!isRecord(track) || !Array.isArray(track.displays)) {
+                continue;
+            }
+            for (const [j, display] of track.displays.entries()) {
+                if (isRecord(display)) {
+                    checkSessionDisplay(display, manifest, `${where}.tracks[${i}].displays[${j}]`, report);
+                }
+            }
+        }
+    }
+    if (Array.isArray(view.views)) {
+        for (const [i, sub] of view.views.entries()) {
+            checkSessionViewTracks(sub, manifest, `${where}.views[${i}]`, report);
+        }
+    }
+}
+// A view's `init` names tracks and an assembly by id. Nothing validates those at
+// load: a trackId that does not exist simply fails to open, which reads as a
+// rendering bug rather than a typo.
+function checkSession(session, manifest, report, ctx) {
+    if (!isRecord(session) || !Array.isArray(session.views)) {
+        return;
+    }
+    for (const [i, view] of session.views.entries()) {
+        checkSessionViewTracks(view, manifest, `defaultSession.views[${i}]`, report);
+    }
+    for (const [i, view] of session.views.entries()) {
+        if (!isRecord(view) || !isRecord(view.init)) {
+            continue;
+        }
+        const init = view.init;
+        const where = `defaultSession.views[${i}].init`;
+        if (typeof init.assembly === 'string' &&
+            !ctx.assemblyNames.has(init.assembly)) {
+            report.error(`${where}.assembly`, `assembly "${init.assembly}" is not defined in this config${didYouMean(init.assembly, [...ctx.assemblyNames])}`);
+        }
+        if (Array.isArray(init.tracks)) {
+            // A LinearSyntenyView's `tracks` is one array PER LEVEL (`[[a], [b]]`) —
+            // the multi-way form — so flatten one level before reading entries.
+            // Treating those inner arrays as track entries reported every genome row
+            // of every synteny demo as a track with no trackId.
+            const entries = init.tracks.flatMap((t) => Array.isArray(t) ? t : [t]);
+            for (const [j, entry] of entries.entries()) {
+                const trackId = typeof entry === 'string'
+                    ? entry
+                    : isRecord(entry)
+                        ? entry.trackId
+                        : undefined;
+                if (typeof trackId !== 'string') {
+                    report.error(`${where}.tracks[${j}]`, 'track entry has no trackId');
+                }
+                else if (!ctx.seenTrackIds.has(trackId) &&
+                    !ctx.sequenceTrackIds.has(trackId)) {
+                    report.error(`${where}.tracks[${j}]`, `trackId "${trackId}" is not defined in this config${didYouMean(trackId, [...ctx.seenTrackIds, ...ctx.sequenceTrackIds])}`);
+                }
+            }
+        }
+    }
+}
+export function validateConfig(config, manifest = configManifest) {
+    const report = new Report();
+    if (!isRecord(config)) {
+        report.error('', 'config is not a JSON object');
+        return report.result();
+    }
+    if (Array.isArray(config.plugins) && config.plugins.length > 0) {
+        report.note(`config declares ${config.plugins.length} plugin(s); the types and slots they register are not in the manifest and cannot be checked`);
+    }
+    const assemblies = (Array.isArray(config.assemblies)
+        ? config.assemblies
+        : isRecord(config.assembly)
+            ? [config.assembly]
+            : []).filter(isRecord);
+    if (assemblies.length === 0) {
+        report.error('assemblies', 'no assemblies — a config needs at least one');
+    }
+    const connections = Array.isArray(config.connections)
+        ? config.connections
+        : [];
+    const ctx = {
+        // An assembly's `aliases` are usable wherever its name is — a track can say
+        // `assemblyNames: ['vvx']` against an assembly named volvox that lists vvx
+        // as an alias. Leaving them out reports working configs as broken.
+        assemblyNames: new Set(assemblies
+            .flatMap(a => [a.name, ...(Array.isArray(a.aliases) ? a.aliases : [])])
+            .filter((n) => typeof n === 'string')),
+        assemblyCount: assemblies.length,
+        seenTrackIds: new Set(),
+        // Each assembly's ReferenceSequenceTrack is a real track a session may show
+        // by id (`init.tracks: ['hg38-ReferenceSequenceTrack']`); it just lives on
+        // the assembly rather than in `tracks`, and collecting only `tracks`
+        // reported every such reference as undefined. Both the written trackId and
+        // the one the `{name, uri}` shorthand derives, since a config using the
+        // shorthand still gets the derived id at runtime.
+        sequenceTrackIds: new Set(assemblies.flatMap(a => {
+            const declared = isRecord(a.sequence) ? a.sequence.trackId : undefined;
+            return [
+                ...(typeof declared === 'string' ? [declared] : []),
+                ...(typeof a.name === 'string'
+                    ? [`${a.name}-ReferenceSequenceTrack`]
+                    : []),
+            ];
+        })),
+    };
+    for (const [i, assembly] of assemblies.entries()) {
+        checkAssembly(assembly, i, manifest, report);
+    }
+    const tracks = Array.isArray(config.tracks)
+        ? config.tracks.filter(isRecord)
+        : [];
+    for (const [i, track] of tracks.entries()) {
+        checkTrack(track, i, manifest, report, ctx);
+    }
+    for (const [i, connection] of connections.entries()) {
+        checkPluggable(connection, manifest.connections, 'connection', `connections[${i}]`, report);
+    }
+    const aggregate = Array.isArray(config.aggregateTextSearchAdapters)
+        ? config.aggregateTextSearchAdapters
+        : [];
+    for (const [i, adapter] of aggregate.entries()) {
+        checkPluggable(adapter, manifest.textSearchAdapters, 'text search adapter', `aggregateTextSearchAdapters[${i}]`, report);
+    }
+    // Tracks are registered before the session is checked, so a session may
+    // reference any track in the file regardless of declaration order.
+    checkSession(config.defaultSession, manifest, report, ctx);
+    return report.result();
+}