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

package/dist/commands/validate/schemaValidate.js

@@ -34,8 +34,9 @@ function validatorFor(pointer) {
         validateSchema: false,
         code: { optimize: 0 },
     });
+    const whole = ajv.getSchema(schemaId) ?? ajv.compile(root);
     if (pointer === '') {
-        return ajv.getSchema(schemaId) ?? ajv.compile(root);
+        return whole;
     }
     const fn = ajv.getSchema(`${schemaId}#${pointer}`);
     if (!fn) {
@@ -56,7 +57,7 @@ function resolve(schema) {
 // 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));
+    const composed = (schema.allOf ?? []).flatMap(branch => Object.keys(resolve(branch).properties ?? {}));
     return [...new Set([...own, ...composed])];
 }
 function describe(schema) {
@@ -67,6 +68,9 @@ function describe(schema) {
     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}`;
     }
@@ -112,6 +116,15 @@ function join(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;
 }
@@ -130,9 +143,23 @@ const viewNames = new Set(defs.View.properties.type.anyOf[0]
 // 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');
+}
+// The keys Vega-Lite and GenomeSpy spell otherwise, by the schema that
+// declares this spelling
+const SPELLED_HERE = {
+    Mark: { mark: 'shape' },
+    MarkEncoding: { shape: 'glyph' },
+};
 function unknownKeyMessage(key, schema, accepted) {
     const title = typeof schema.title === 'string' ? schema.title : '';
-    const guess = didYouMean(key, accepted);
+    const here = SPELLED_HERE[title]?.[key];
+    const guess = here
+        ? ` — Vega-Lite's "${key}" is spelled "${here}" here`
+        : 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';
     }
@@ -157,11 +184,39 @@ function unknownKeyMessage(key, schema, accepted) {
     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;
 }
@@ -176,6 +231,11 @@ function pickBranch(error, data, errors) {
             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));
@@ -199,6 +259,31 @@ 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));
 }
@@ -207,25 +292,48 @@ function requiredOnly(branches) {
 // than one per alternative.
 function explain(data, errors, problems, depth) {
     const covered = new Set();
-    const emit = (where, message) => {
-        const key = `${where}${message}`;
+    const emit = (where, message, rule) => {
+        const key = `${where}\0${message}`;
         if (!covered.has(key)) {
             covered.add(key);
-            problems.push({ level: 'error', where, message });
+            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 === u.instancePath ||
-            e.instancePath.startsWith(`${u.instancePath}/`)));
+        (e.instancePath.startsWith(`${u.instancePath}/`) ||
+            (e.instancePath === u.instancePath &&
+                !(e.keyword === 'anyOf' && isBranchOf(e, u)))));
     for (const error of errors) {
-        if (shadowed(error) || error.keyword === 'if') {
+        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': {
@@ -243,12 +351,18 @@ function explain(data, errors, problems, depth) {
                     emit(where, `needs one of ${branches.map(b => `"${b.required[0]}"`).join(', ')}`);
                     break;
                 }
-                const jexlBranch = branches.findIndex(b => refName(b) === 'JexlString');
+                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;
@@ -272,10 +386,14 @@ function explain(data, errors, problems, depth) {
                 }
                 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':
-            case 'pattern':
                 emit(where, `expected ${describe(parent)}, got ${JSON.stringify(error.data)}`);
                 break;
             case 'not':
@@ -297,4 +415,20 @@ export function schemaProblems(data, pointer = '') {
     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/validateConfig.js

@@ -9,7 +9,11 @@
 //
 // Pure: no filesystem, no process exit. The command wrapper owns both.
 import { configManifest } from './configManifest.generated.js';
-import { schemaProblems } from './schemaValidate.js';
+import { displayDefaultsForTrackType } from './displayDefaultKeys.js';
+import { isRecord, liftToSnapshot } from './liftConfig.js';
+import { colorProblems, fieldScaleOf } from './markRules/colorScale.js';
+import { markProblems } from './markRules/markProblems.js';
+import { hasDeclaredShape, rootConfigurationSlots, schemaProblems, } from './schemaValidate.js';
 import { didYouMean } from './suggest.js';
 class Report {
     problems = [];
@@ -32,9 +36,6 @@ class Report {
         };
     }
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 // A declared `sequenceAdapter` works and is simply the wrong way round: every
 // feature adapter takes its sequence from the assembly the track is displayed
 // against, so a hand-written one pins the track to that source. An undeclared
@@ -213,7 +214,13 @@ function checkViewReferences(view, where, report, ctx) {
         if (typeof trackId === 'string' &&
             !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])}`);
+            const message = `trackId "${trackId}" is not defined in this config${didYouMean(trackId, [...ctx.seenTrackIds, ...ctx.sequenceTrackIds])}`;
+            if (ctx.declaresPlugins) {
+                report.warn(`${where}.tracks[${j}]`, `${message} — a plugin it declares may create it`);
+            }
+            else {
+                report.error(`${where}.tracks[${j}]`, message);
+            }
         }
     }
 }
@@ -255,16 +262,142 @@ function checkSession(session, manifest, report, ctx) {
         }
     }
 }
+const MARK_DISPLAY = 'LinearMarkDisplay';
+const SLOTS_POINTER = `/$defs/${MARK_DISPLAY}Slots/properties`;
+// The rule list reads a config snapshot, which is what a file is once the
+// schema passes its keys and types and the manifest's lifts are applied. An
+// entry the schema refuses is the schema's to report, and stands as a gap so
+// its siblings keep their indices and their own reports.
+function declaredEntries(lifted, display, slot) {
+    const list = lifted[slot];
+    const written = display[slot];
+    return Array.isArray(list) && Array.isArray(written)
+        ? list.map((entry, i) => hasDeclaredShape(written[i], `${SLOTS_POINTER}/${slot}/items`)
+            ? entry
+            : undefined)
+        : [];
+}
+function slotPath(slot) {
+    return slot.replaceAll(/\.(\d+)(?=\.|$)/g, '[$1]');
+}
+// A mark display's own entry, whose marks may come from `displayDefaults`, or
+// a `displayDefaults` holding marks. A mark is a record with a `transform` of
+// its own, so an untyped node counts only by its `marks`.
+function holdsMarkRules(node) {
+    return node.type === MARK_DISPLAY
+        ? Array.isArray(node.marks) || Array.isArray(node.transform)
+        : node.type === undefined && Array.isArray(node.marks);
+}
+// What the marks of one display say together that it cannot draw as written:
+// the rule list the display shows in its corner notice, copied from the plugin
+// (`markRules/`). A single mark's `requires` is the schema's to report.
+function checkMarkDisplay(display, manifest, where, report) {
+    const slots = manifest.displays[MARK_DISPLAY]?.slots;
+    const lifted = liftToSnapshot(display, slots ?? []);
+    if (!slots || !isRecord(lifted)) {
+        return;
+    }
+    const { facet } = lifted;
+    for (const { level, rule, mark, slot, message } of markProblems(declaredEntries(lifted, display, 'marks'), isRecord(facet) ? facet : undefined, declaredEntries(lifted, display, 'transform'))) {
+        report.problems.push({
+            level,
+            where: `${where}${mark === undefined ? '' : `.marks[${mark}]`}.${slotPath(slot)}`,
+            message,
+            rule,
+        });
+    }
+}
+// The display's own colour rules, with its schema's fieldScale standing in
+// for the plugin code the CLI does not run
+function checkColorSlots(display, slots, where, report) {
+    const lifted = liftToSnapshot(display, slots);
+    if (!isRecord(lifted)) {
+        return;
+    }
+    for (const { name, fieldScale, subSlots = [] } of slots) {
+        const written = lifted[name];
+        if (!fieldScale || !isRecord(written)) {
+            continue;
+        }
+        const declared = new Set(subSlots.map(slot => slot.name));
+        const color = Object.fromEntries(Object.entries(written).filter(([key]) => declared.has(key)));
+        const field = typeof color.field === 'string' ? color.field : '';
+        for (const problem of colorProblems({
+            field,
+            scale: typeof color.scale === 'string' ? color.scale : undefined,
+            domain: Array.isArray(color.domain) ? color.domain : undefined,
+            range: Array.isArray(color.range) ? color.range : undefined,
+            domainMin: typeof color.domainMin === 'number' ? color.domainMin : undefined,
+            domainMax: typeof color.domainMax === 'number' ? color.domainMax : undefined,
+        }, fieldScaleOf(fieldScale, field))) {
+            const at = `${where}.${name}.${problem.slot}`;
+            if (!report.problems.some(p => p.where === at && p.rule === problem.rule)) {
+                report.problems.push({
+                    level: 'warning',
+                    where: at,
+                    message: problem.message,
+                    rule: problem.rule,
+                });
+            }
+        }
+    }
+}
+// A marks list sits wherever a config takes the mark display's slots: a
+// track's `displays` entry, its `displayDefaults`, a session's inline track
+// entry. No other type declares `marks`, so the walk is over the whole file,
+// past a place where the schema refused the key: a session display node
+// drops it.
+function checkMarkDisplays(node, manifest, where, report) {
+    if (Array.isArray(node)) {
+        for (const [i, item] of node.entries()) {
+            checkMarkDisplays(item, manifest, `${where}[${i}]`, report);
+        }
+    }
+    else if (isRecord(node)) {
+        const colorSlots = typeof node.type === 'string'
+            ? manifest.displays[node.type]?.slots
+            : undefined;
+        if (colorSlots) {
+            checkColorSlots(node, colorSlots, where, report);
+        }
+        if (typeof node.type === 'string' && isRecord(node.displayDefaults)) {
+            for (const display of displayDefaultsForTrackType(node.type, manifest)
+                .displayTypes) {
+                checkColorSlots(node.displayDefaults, manifest.displays[display]?.slots ?? [], `${where}.displayDefaults`, report);
+            }
+        }
+        if (holdsMarkRules(node) &&
+            !report.problems.some(p => p.where === `${where}.marks`)) {
+            checkMarkDisplay(node, manifest, where, report);
+        }
+        for (const [key, member] of Object.entries(node)) {
+            checkMarkDisplays(member, manifest, where ? `${where}.${key}` : key, report);
+        }
+    }
+}
 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) {
+    const declaresPlugins = Array.isArray(config.plugins) && config.plugins.length > 0;
+    if (declaresPlugins) {
         report.note(`config declares ${config.plugins.length} plugin(s); the types and slots they register are not in the schema and cannot be checked`);
     }
-    report.problems.push(...schemaProblems(config));
+    const { configuration } = config;
+    const pluginSlots = declaresPlugins && isRecord(configuration)
+        ? Object.keys(configuration).filter(k => !rootConfigurationSlots.has(k))
+        : [];
+    for (const key of pluginSlots) {
+        report.warn(`configuration.${key}`, `core declares no "${key}" slot${didYouMean(key, [...rootConfigurationSlots])} — a plugin this config declares may`);
+    }
+    report.problems.push(...schemaProblems(pluginSlots.length && isRecord(configuration)
+        ? {
+            ...config,
+            configuration: Object.fromEntries(Object.entries(configuration).filter(([k]) => !pluginSlots.includes(k))),
+        }
+        : config));
     const assemblies = (Array.isArray(config.assemblies)
         ? config.assemblies
         : isRecord(config.assembly)
@@ -280,6 +413,7 @@ export function validateConfig(config, manifest = configManifest) {
             .filter((n) => typeof n === 'string')),
         assemblyCount: assemblies.length,
         seenTrackIds: new Set(),
+        declaresPlugins,
         // 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 => {
@@ -316,5 +450,6 @@ export function validateConfig(config, manifest = configManifest) {
     // 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);
+    checkMarkDisplays(config, manifest, '', report);
     return report.result();
 }

package/dist/version.js

@@ -1 +1 @@
-export const version = '5.0.0-beta.8';
+export const version = '5.0.0-beta.9';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/cli",
-  "version": "5.0.0-beta.8",
+  "version": "5.0.0-beta.9",
   "type": "module",
   "description": "A command line tool for working with JBrowse 2",
   "keywords": [
@@ -32,9 +32,9 @@
     "ixixx": "^3.0.13",
     "serve-handler": "^6.1.7",
     "tmp": "^0.2.7",
-    "@jbrowse/add-track-core": "^5.0.0-beta.8",
-    "@jbrowse/cigar-utils": "^5.0.0-beta.8",
-    "@jbrowse/text-indexing-core": "^5.0.0-beta.8"
+    "@jbrowse/add-track-core": "^5.0.0-beta.9",
+    "@jbrowse/text-indexing-core": "^5.0.0-beta.9",
+    "@jbrowse/cigar-utils": "^5.0.0-beta.9"
   },
   "publishConfig": {
     "access": "public"