@jbrowse/cli 4.3.0 → 5.0.0-beta.10

package/dist/commands/validate/markRules/markVocabulary.js

@@ -0,0 +1,57 @@
+// Generated by scripts/generateMarkRules.ts from plugins/marks/src/LinearMarkDisplay/markVocabulary.ts: do not edit, `pnpm autogen` rewrites it.
+/**
+ * The names a `marks` list is written in and the ones a slot left off reads
+ * as, in a module that imports nothing: the config schema declares its
+ * enumerations and defaults from here, the rule list reads the same constants,
+ * and `jbrowse validate` carries a copy of both.
+ */
+export const MARK_TYPES = [
+    'bar',
+    'point',
+    'rule',
+    'line',
+    'span',
+    'text',
+    'link',
+];
+export const DEFAULT_MARK_TYPE = 'bar';
+/** How a line joins its values: held across each span, or centre to centre. */
+export const LINE_INTERPOLATIONS = ['step', 'linear'];
+export const DEFAULT_LINE_INTERPOLATE = 'step';
+/** The width a line strokes at where its `size` is left unwritten. */
+export const DEFAULT_LINE_WIDTH_PX = 1;
+export const LINK_SHAPES = ['dome', 'arc', 'line'];
+export const DEFAULT_LINK_SHAPE = 'dome';
+/** The stroke a link draws at where its `size` is left unwritten. */
+export const DEFAULT_LINK_STROKE_PX = 2;
+/** The fraction of its row a span fills where its `rowProportion` is left unwritten. */
+export const DEFAULT_ROW_PROPORTION = 1;
+export const SIZE_SCALES = ['linear', 'log'];
+export const MARK_SOURCES = ['features', 'density'];
+export const DEFAULT_MARK_SOURCE = 'features';
+export const DEFAULT_FORMULA_AS = 'value';
+export const DEFAULT_BIN_FIELD = 'start';
+export const DEFAULT_BIN_AS = ['start', 'end'];
+/** What a `bin` over `fields` writes on each piece: the bases of its interval inside its bin. */
+export const BIN_OVERLAP_FIELD = 'overlap';
+export const DEFAULT_COVERAGE_AS = 'coverage';
+export const DEFAULT_FLATTEN_FIELD = 'subfeatures';
+export const DEFAULT_CELLS_FIELD = 'seq';
+/** What a `cells` step writes: `state` on every cell, `base` on a mismatch or an insertion, `match` off a gap, `length` on an insertion. */
+export const CELLS_FIELDS = ['state', 'base', 'match', 'length'];
+export const DEFAULT_PILEUP_AS = 'row';
+export const DEFAULT_PILEUP_FIELDS = ['start', 'end'];
+export const DEFAULT_TEXT_FIELD = 'name';
+export const DEFAULT_X2 = 'end';
+/** What a `mate` step writes on every feature it answers. */
+export const MATE_FIELDS = [
+    'mate.refName',
+    'mate.start',
+    'mate.end',
+    'mate.mateDirection',
+    'mateDirection',
+    'alt',
+    'svType',
+];
+export const AGGREGATE_OPS = ['count', 'sum', 'mean', 'min', 'max'];
+export const DEFAULT_AGGREGATE_OP = 'count';

package/dist/commands/validate/markRules/shapeNameList.js

@@ -0,0 +1,7 @@
+// Generated by scripts/generateMarkRules.ts from packages/core/src/util/shapeNameList.ts: do not edit, `pnpm autogen` rewrites it.
+/** The shape names in range order: what an unlisted `range` hands out. */
+export const SHAPE_NAMES = [
+    'circle',
+    'triangle-down',
+    'diamond',
+];

package/dist/commands/validate/markRules/stepChannels.js

@@ -0,0 +1,55 @@
+// Generated by scripts/generateMarkRules.ts from plugins/marks/src/LinearMarkDisplay/stepChannels.ts: do not edit, `pnpm autogen` rewrites it.
+import { aggregateFieldName } from './markRuleFacts.js';
+import { DEFAULT_AGGREGATE_OP, DEFAULT_COVERAGE_AS, DEFAULT_PILEUP_AS, } from './markVocabulary.js';
+/** The far end a `mate` step writes, as `x2` reads a position on another sequence. */
+export const MATE_X2 = { chrom: 'mate.refName', pos: 'mate.start' };
+function outputOf(step, fallback) {
+    return typeof step.as === 'string' && step.as !== '' ? step.as : fallback;
+}
+/**
+ * What {@link StepChannels} a mark's steps leave it, read over the display's,
+ * the facet's and then the mark's own steps in the order they run. An
+ * `aggregate` or `coverage` makes its features anew, so it clears the row and
+ * the other end a step before it wrote, and an aggregate writing two
+ * summaries names no `y`.
+ */
+export function stepChannels(steps) {
+    let channels = {};
+    for (const step of steps) {
+        switch (step?.type) {
+            case undefined: {
+                break;
+            }
+            case 'coverage': {
+                channels = { y: outputOf(step, DEFAULT_COVERAGE_AS) };
+                break;
+            }
+            case 'aggregate': {
+                const [only, ...rest] = step.ops ?? [];
+                channels =
+                    only && rest.length === 0
+                        ? {
+                            y: aggregateFieldName({
+                                op: only.op ?? DEFAULT_AGGREGATE_OP,
+                                field: only.field,
+                                as: only.as,
+                            }),
+                        }
+                        : {};
+                break;
+            }
+            case 'pileup': {
+                channels = { ...channels, row: outputOf(step, DEFAULT_PILEUP_AS) };
+                break;
+            }
+            case 'mate': {
+                channels = { ...channels, x2: MATE_X2 };
+                break;
+            }
+            default: {
+                break;
+            }
+        }
+    }
+    return channels;
+}

package/dist/commands/validate/schemaValidate.js

@@ -0,0 +1,425 @@
+// Validates a config against the generated JSON Schema and turns each failure
+// into a Problem an author can act on: the path in the config's own spelling,
+// the accepted keys with a did-you-mean, and for a union the errors of the
+// branch the value was written for rather than of every branch.
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { configJsonSchema } from './configSchema.generated.js';
+import { didYouMean } from './suggest.js';
+const root = configJsonSchema;
+const defs = root.$defs;
+const schemaId = root.$id;
+// Every object inside the schema, keyed by identity, to its JSON pointer: ajv
+// reports `parentSchema` as the object and its `schemaPath` relative to the
+// nearest $ref target, and a union branch is re-validated by absolute pointer.
+const pointers = new Map();
+function index(node, pointer) {
+    if (typeof node !== 'object' || node === null) {
+        return;
+    }
+    pointers.set(node, pointer);
+    for (const [key, value] of Object.entries(node)) {
+        index(value, `${pointer}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`);
+    }
+}
+index(root, '');
+let ajv;
+function validatorFor(pointer) {
+    // No meta-validation and no codegen optimization: the schema is generated
+    // and its own test checks it against the draft, and a config is validated
+    // once per process, so the compile is the cost that matters.
+    ajv ??= new Ajv2020({
+        allErrors: true,
+        strict: false,
+        verbose: true,
+        validateSchema: false,
+        code: { optimize: 0 },
+    });
+    const whole = ajv.getSchema(schemaId) ?? ajv.compile(root);
+    if (pointer === '') {
+        return whole;
+    }
+    const fn = ajv.getSchema(`${schemaId}#${pointer}`);
+    if (!fn) {
+        throw new Error(`no schema at ${pointer}`);
+    }
+    return fn;
+}
+function refName(schema) {
+    return typeof schema?.$ref === 'string'
+        ? schema.$ref.replace('#/$defs/', '')
+        : undefined;
+}
+function resolve(schema) {
+    const name = refName(schema);
+    return name ? (defs[name] ?? schema) : schema;
+}
+// The keys an object schema accepts: its own properties plus those of every
+// slot table it intersects through allOf.
+function acceptedKeys(schema) {
+    const own = Object.keys(schema.properties ?? {});
+    const composed = (schema.allOf ?? []).flatMap(branch => Object.keys(resolve(branch).properties ?? {}));
+    return [...new Set([...own, ...composed])];
+}
+function describe(schema) {
+    const name = refName(schema);
+    if (name === 'FileLocation') {
+        return 'a file location ({ "uri": ... } or { "localPath": ... })';
+    }
+    if (name === 'JexlString') {
+        return 'a "jexl:" expression';
+    }
+    if (name === 'CssColor') {
+        return 'a CSS color (a name like "red", "#rrggbb", "rgb()" or "hsl()")';
+    }
+    if (name) {
+        return `a ${name}`;
+    }
+    if (Array.isArray(schema.enum)) {
+        return `one of ${schema.enum.map(v => JSON.stringify(v)).join(', ')}`;
+    }
+    if ('const' in schema) {
+        return JSON.stringify(schema.const);
+    }
+    if (Array.isArray(schema.anyOf)) {
+        return schema.anyOf.map(describe).join(' or ');
+    }
+    switch (schema.type) {
+        case 'array':
+            return schema.items
+                ? `an array of ${describe(schema.items)}`
+                : 'an array';
+        case 'object':
+            return 'an object';
+        case 'string':
+            return 'a string';
+        case 'number':
+        case 'integer':
+            return 'a number';
+        case 'boolean':
+            return 'a boolean';
+        default:
+            return 'a value';
+    }
+}
+function pathOf(instancePath) {
+    return instancePath
+        .split('/')
+        .slice(1)
+        .map(seg => seg.replaceAll('~1', '/').replaceAll('~0', '~'))
+        .map(seg => (/^\d+$/.test(seg) ? `[${seg}]` : `.${seg}`))
+        .join('')
+        .replace(/^\./, '');
+}
+function join(where, key) {
+    return where && key ? `${where}.${key}` : where || key;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function jsonTypeOf(data) {
+    return Array.isArray(data)
+        ? 'array'
+        : data === null
+            ? 'null'
+            : typeof data === 'object'
+                ? 'object'
+                : typeof data;
+}
+function typeOf(data) {
+    return isRecord(data) && typeof data.type === 'string' ? data.type : undefined;
+}
+// Whether an object schema is for this `type`: a def names it as a const or an
+// alias enum, a dispatching union lists it in its hint.
+function admitsType(schema, type) {
+    const prop = schema.properties?.type;
+    const hint = prop?.anyOf?.[0];
+    return [prop, hint].some(p => p &&
+        (p.const === type || (Array.isArray(p.enum) && p.enum.includes(type))));
+}
+const viewNames = new Set(defs.View.properties.type.anyOf[0]
+    .enum);
+// What the message says an unknown key is, by the kind of object it sits on.
+// A session node is instantiated by a state model rather than a config schema,
+// so a slot name written there is dropped just like a misspelling — and the
+// advice differs, because the key is real and there are two right places for
+// it.
+function listed(keys) {
+    return keys.length > 1
+        ? `${keys.slice(0, -1).join(', ')} and ${keys.at(-1)}`
+        : (keys[0] ?? 'nothing');
+}
+function unknownKeyMessage(key, schema, accepted) {
+    const title = typeof schema.title === 'string' ? schema.title : '';
+    const guess = didYouMean(key, accepted);
+    if (key === 'sequenceAdapter' && !title.endsWith('Snapshot')) {
+        return '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';
+    }
+    if (title.endsWith('Snapshot')) {
+        const slots = Object.keys(defs[`${title.replace(/Snapshot$/, '')}Slots`]?.properties);
+        return slots.includes(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`
+            : `unknown display property "${key}"${didYouMean(key, [...accepted, ...slots])} — a session snapshot drops keys the display does not declare, so this setting silently does nothing`;
+    }
+    if (viewNames.has(title)) {
+        const elsewhere = [...viewNames].filter(name => name !== title && acceptedKeys(defs[name]).includes(key));
+        return elsewhere.length
+            ? `"${key}" is a setting of ${elsewhere.join(', ')}, not of ${title}${guess} — a session snapshot drops keys the view does not declare, so this setting silently does nothing`
+            : `unknown view key "${key}"${guess} — a session snapshot drops keys the view does not declare, so this setting silently does nothing`;
+    }
+    if (title === 'Session') {
+        return `unknown session key "${key}"${guess} — a session snapshot drops keys it does not declare, so this setting silently does nothing`;
+    }
+    if (title.endsWith('DisplayDefaults')) {
+        return `no display of this track declares "${key}"${guess}`;
+    }
+    if (title.endsWith('TrackEntry')) {
+        return `"${key}" is neither a config slot nor a property of ${title.replace(/TrackEntry$/, '')}${guess} — the entry's keys are folded onto that display, and one it does not declare silently does nothing`;
+    }
+    if (schema['x-closed'] === true) {
+        return `unknown slot "${key}"${guess} — ${title} takes ${listed(accepted)}, and JBrowse refuses to load it rather than drop a key it does not declare`;
+    }
+    return `unknown slot "${key}"${guess} — JBrowse ignores keys it does not declare, so this setting silently does nothing`;
+}
+function isJexl(value) {
+    return typeof value === 'string' && value.startsWith('jexl:');
+}
+// The keywords a slot declaring no contextVariable fails a `jexl:` string on:
+// a plain string's `not`, a number's `type`, a color's `pattern`, an enum's
+// own, and a union of those
+const REFUSES_CALLBACK = new Set([
+    'not',
+    'type',
+    'pattern',
+    'enum',
+    'const',
+    'anyOf',
+]);
+function refusedCallback(value) {
+    return `takes no "jexl:" callback, and ${JSON.stringify(value)} is one: a slot that takes a callback lists its callback args in the config docs`;
+}
+function isScalar(schema) {
+    const resolved = resolve(schema);
+    return (resolved.properties === undefined &&
+        resolved.items === undefined &&
+        resolved.allOf === undefined &&
+        resolved.type !== 'object' &&
+        resolved.type !== 'array');
+}
+function isJexlBranch(schema) {
+    return refName(schema) === 'JexlString';
+}
+function branchesOf(error) {
+    return error.parentSchema.anyOf;
+}
+// Which branch of a union the value was written for: the one whose `type` it
+// names, else the one it comes closest to satisfying.
+function pickBranch(error, data, errors) {
+    const branches = branchesOf(error);
+    const type = typeOf(data);
+    if (type !== undefined) {
+        const byType = branches.findIndex(b => admitsType(resolve(b), type));
+        if (byType >= 0) {
+            return byType;
+        }
+    }
+    const jsonType = jsonTypeOf(data);
+    const byJsonType = branches.flatMap((b, i) => (b.type ?? resolve(b).type) === jsonType ? [i] : []);
+    if (byJsonType.length === 1) {
+        return byJsonType[0];
+    }
+    if (isRecord(data)) {
+        const tagged = branches.findIndex(b => 'locationType' in data &&
+            admitsLocation(resolve(b), data.locationType));
+        if (tagged >= 0) {
+            return tagged;
+        }
+        const untagged = branches.findIndex(b => 'not' in resolve(b));
+        if (untagged >= 0 && !('locationType' in data)) {
+            return untagged;
+        }
+    }
+    const counts = branches.map((_, i) => {
+        const prefix = `${error.schemaPath}/${i}/`;
+        return errors.filter(e => e.schemaPath.startsWith(prefix) &&
+            e.instancePath.startsWith(error.instancePath)).length;
+    });
+    const structural = branches.map((b, i) => counts[i] === 0 ? Infinity : counts[i]);
+    return structural.indexOf(Math.min(...structural));
+}
+function admitsLocation(schema, locationType) {
+    const prop = schema.properties?.locationType;
+    return prop?.const === locationType;
+}
+// A schema's `requires` entry, which the generator writes as an `if`/`then`
+// annotated with the entry's id, the slot path it requires and its message.
+function requirementOf(error) {
+    const parent = error.parentSchema ?? {};
+    const stated = parent['x-requirement'];
+    return error.keyword === 'if' && isRecord(stated)
+        ? {
+            id: String(stated.id),
+            slot: String(stated.slot),
+            message: String(parent.errorMessage),
+            branch: `${error.schemaPath.replace(/\/if$/, '')}/then/`,
+        }
+        : undefined;
+}
+// Whether a failure is one requirement's: the `if` itself, or an error under
+// its `then` at or beneath the object the `if` judged.
+function statesRequirement(error, errors) {
+    return errors.some(other => {
+        const requirement = requirementOf(other);
+        return (requirement !== undefined &&
+            (other === error ||
+                (error.schemaPath.startsWith(requirement.branch) &&
+                    error.instancePath.startsWith(other.instancePath))));
+    });
+}
+function requiredOnly(branches) {
+    return branches.every(b => Object.keys(b).length === 1 && Array.isArray(b.required));
+}
+// Converts ajv's errors at one validation into Problems, recursing into the
+// chosen branch of each failed union so the author sees one diagnosis rather
+// than one per alternative.
+function explain(data, errors, problems, depth) {
+    const covered = new Set();
+    const emit = (where, message, rule) => {
+        const key = `${where}\0${message}`;
+        if (!covered.has(key)) {
+            covered.add(key);
+            problems.push({
+                level: 'error',
+                where,
+                message,
+                ...(rule ? { rule } : {}),
+            });
+        }
+    };
+    // A union failure explains everything beneath it; the branch is re-validated
+    // on its own so the sub-errors reported for the other branches drop out.
+    // A union nested as another's branch at the same path (`number | "auto"`
+    // inside a slot's `value | jexl:`) is the outer one's to explain, and never
+    // the other way round, or neither is reported.
+    const unions = errors.filter(e => e.keyword === 'anyOf');
+    const isBranchOf = (u, e) => branchesOf(u).some(b => resolve(b) === e.parentSchema);
+    const shadowed = (e) => unions.some(u => u !== e &&
+        (e.instancePath.startsWith(`${u.instancePath}/`) ||
+            (e.instancePath === u.instancePath &&
+                !(e.keyword === 'anyOf' && isBranchOf(e, u)))));
+    for (const error of errors) {
+        if (shadowed(error)) {
+            continue;
+        }
+        const where = pathOf(error.instancePath);
+        const requirement = requirementOf(error);
+        if (requirement) {
+            emit(join(where, requirement.slot), requirement.message, requirement.id);
+        }
+        if (error.keyword === 'if' || statesRequirement(error, errors)) {
+            continue;
+        }
+        const parent = error.parentSchema;
+        if (isJexl(error.data) &&
+            REFUSES_CALLBACK.has(error.keyword) &&
+            !(error.keyword === 'anyOf' && branchesOf(error).some(isJexlBranch))) {
+            emit(where, refusedCallback(error.data));
+            continue;
+        }
+        switch (error.keyword) {
+            case 'additionalProperties':
+            case 'unevaluatedProperties': {
+                const key = String(error.params.additionalProperty ?? error.params.unevaluatedProperty);
+                emit(join(where, key), unknownKeyMessage(key, parent, acceptedKeys(parent)));
+                break;
+            }
+            case 'required':
+                emit(where, `missing "${String(error.params.missingProperty)}"`);
+                break;
+            case 'anyOf': {
+                const branches = branchesOf(error);
+                const value = error.data;
+                if (requiredOnly(branches)) {
+                    emit(where, `needs one of ${branches.map(b => `"${b.required[0]}"`).join(', ')}`);
+                    break;
+                }
+                const jexlBranch = branches.findIndex(isJexlBranch);
+                if (jexlBranch >= 0 && !isJexl(value)) {
+                    const others = branches.filter((_, i) => i !== jexlBranch);
+                    emit(where, `expected ${others.map(describe).join(' or ')} or a "jexl:" expression, got ${JSON.stringify(value)}`);
+                    break;
+                }
+                if (!isRecord(value) &&
+                    !Array.isArray(value) &&
+                    branches.every(isScalar)) {
+                    emit(where, `expected ${branches.map(describe).join(' or ')}, got ${JSON.stringify(value)}`);
+                    break;
+                }
+                if (depth > 8) {
+                    emit(where, `does not match any accepted form`);
+                    break;
+                }
+                const pointer = pointers.get(parent);
+                const branch = pickBranch(error, value, errors);
+                if (pointer === undefined || branch < 0) {
+                    emit(where, 'does not match any accepted form');
+                    break;
+                }
+                const fn = validatorFor(`${pointer}/anyOf/${branch}`);
+                if (!fn(value) && fn.errors?.length) {
+                    const nested = [];
+                    explain(value, fn.errors, nested, depth + 1);
+                    for (const p of nested) {
+                        emit(join(where, p.where).replaceAll('.[', '['), p.message);
+                    }
+                }
+                else {
+                    emit(where, 'does not match any accepted form');
+                }
+                break;
+            }
+            case 'pattern':
+                emit(where, error.schemaPath.endsWith('/CssColor/pattern')
+                    ? `expected ${describe({ $ref: '#/$defs/CssColor' })}, got ${JSON.stringify(error.data)}`
+                    : `expected a string matching /${String(parent.pattern)}/, got ${JSON.stringify(error.data)}`);
+                break;
+            case 'type':
+            case 'enum':
+            case 'const':
+                emit(where, `expected ${describe(parent)}, got ${JSON.stringify(error.data)}`);
+                break;
+            case 'not':
+                emit(where, `must not ${describe(parent.not)}`);
+                break;
+            default:
+                emit(where, error.message ?? error.keyword);
+        }
+    }
+}
+// The problems in `data` against the whole schema, or against one of its
+// definitions by pointer (`/$defs/View` for a session spec's view).
+export function schemaProblems(data, pointer = '') {
+    const validate = validatorFor(pointer);
+    if (validate(data)) {
+        return [];
+    }
+    const problems = [];
+    explain(data, validate.errors ?? [], problems, 0);
+    return problems;
+}
+/**
+ * Whether `data` has the keys and value types the definition at `pointer`
+ * declares, whatever its `requires` entries say of it: the contract a rule
+ * list reads a config under, since a load refuses a key or a type and no
+ * combination of slots.
+ */
+export function hasDeclaredShape(data, pointer) {
+    const validate = validatorFor(pointer);
+    const errors = validate(data) ? [] : (validate.errors ?? []);
+    return errors.every(error => statesRequirement(error, errors));
+}
+/**
+ * The keys core declares directly under `configuration`. A plugin adds its own
+ * beside them, the way `LinearGenomeViewPlugin` is core's.
+ */
+export const rootConfigurationSlots = new Set(Object.keys(defs.RootConfiguration.properties));
+export { schemaId as configSchemaUrl };

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 {};