@jbrowse/cli 4.3.0 → 5.0.0-beta.2

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 key a defaultSession view or display does not declare, 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, such as a view
+           nesting its settings under "init". 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 {};