@jbrowse/cli 5.0.0-beta.4 → 5.0.0-beta.8

package/dist/commands/validate/index.js

@@ -19,7 +19,14 @@ Two levels are reported:
            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.`;
+as warnings rather than errors.
+
+The same checks are published as a JSON Schema at
+https://jbrowse.org/jb2/schema/v5/config.json: a "$schema" line naming it at
+the top of a config.json gives an editor completion and validation for every
+slot. This command runs that schema first, then the cross-references a schema
+cannot express — a trackId a session names that no track defines, an assembly
+a track names that none defines.`;
 const examples = [
     '# check the config.json in the current directory',
     '$ jbrowse validate',

package/dist/commands/validate/schemaValidate.js

@@ -0,0 +1,300 @@
+// 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 },
+    });
+    if (pointer === '') {
+        return ajv.getSchema(schemaId) ?? ajv.compile(root);
+    }
+    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) {
+        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 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 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`;
+    }
+    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:');
+}
+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;
+        }
+    }
+    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;
+}
+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) => {
+        const key = `${where}${message}`;
+        if (!covered.has(key)) {
+            covered.add(key);
+            problems.push({ level: 'error', where, message });
+        }
+    };
+    // 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.
+    const unions = errors.filter(e => e.keyword === 'anyOf');
+    const shadowed = (e) => unions.some(u => u !== e &&
+        (e.instancePath === u.instancePath ||
+            e.instancePath.startsWith(`${u.instancePath}/`)));
+    for (const error of errors) {
+        if (shadowed(error) || error.keyword === 'if') {
+            continue;
+        }
+        const where = pathOf(error.instancePath);
+        const parent = error.parentSchema;
+        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(b => refName(b) === 'JexlString');
+                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 (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 'type':
+            case 'enum':
+            case 'const':
+            case 'pattern':
+                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;
+}
+export { schemaId as configSchemaUrl };