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

package/dist/commands/validate/index.js

@@ -8,16 +8,25 @@ 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.
+  error    JBrowse silently does the wrong thing, or refuses to load it — 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.
 
+A LinearMarkDisplay loads whenever its keys and value types are right and says
+what it cannot draw in a corner notice rather than refusing the track.
+This command runs the display's own rule list over every "marks" list in the
+file: an error where a mark draws nothing, never draws or a step cannot run,
+and a warning where a slot waits unread or the marks draw in an arrangement
+the author may not have meant. With --json each finding carries the stable
+"rule" id of the rule that made it.
+
 Types registered by plugins are not known to this command, so they come through
 as warnings rather than errors.
 

package/dist/commands/validate/liftConfig.js

@@ -0,0 +1,29 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function liftSlot(member, slot) {
+    if (slot.subSlots) {
+        const { subSlots, shorthand } = slot;
+        const lift = (item) => liftToSnapshot(typeof item === 'string' && shorthand !== undefined
+            ? { [shorthand]: item }
+            : item, subSlots);
+        return Array.isArray(member) ? member.map(lift) : lift(member);
+    }
+    const list = slot.liftsString && typeof member === 'string' ? [member] : member;
+    return slot.liftsNumbers && Array.isArray(list) ? list.map(String) : list;
+}
+/**
+ * A config object as its schema holds it once loaded, defaults still left off:
+ * a bare string lifted into a sub-schema's `shorthand` slot or into a list of
+ * one, and a number in a list of strings carried as a string. Which slot lifts
+ * what is the manifest's record of the live schemas, so a rule list written
+ * against a config snapshot reads a file the way it reads the app's.
+ */
+export function liftToSnapshot(value, slots) {
+    return isRecord(value)
+        ? Object.fromEntries(Object.entries(value).map(([key, member]) => {
+            const slot = slots.find(s => s.name === key);
+            return [key, slot ? liftSlot(member, slot) : member];
+        }))
+        : value;
+}

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

@@ -0,0 +1,27 @@
+// Generated by scripts/generateMarkRules.ts from plugins/marks/src/LinearMarkDisplay/autoBin.ts: do not edit, `pnpm autogen` rewrites it.
+/** The `step` value a `bin` step writes to follow the view's zoom. */
+export const AUTO_BIN = 'auto';
+/**
+ * How wide an automatic bin aims to be on screen. Four pixels is a bar the eye
+ * reads as a bar rather than a hairline, and it keeps a screenful of a
+ * 1000px-wide view at ~250 instances.
+ */
+export const AUTO_BIN_TARGET_PX = 4;
+const LADDER = [1, 2, 5];
+/**
+ * The bin width an `auto` step resolves to at this zoom: the target width in bp
+ * ({@link AUTO_BIN_TARGET_PX} pixels' worth), snapped up to the next 1/2/5
+ * rung — 1, 2, 5, 10, 20, 50, 100 bp and so on, the ladder an axis picks its
+ * ticks from. Snapping stops most zoom steps from refetching: every bp/px
+ * inside a rung resolves to one width, so a zoom step within a rung refetches nothing
+ * and one across it refetches at the width the new zoom asks for.
+ */
+export function autoBinStep(bpPerPx) {
+    const target = Math.max(1, bpPerPx * AUTO_BIN_TARGET_PX);
+    const decade = 10 ** Math.floor(Math.log10(target));
+    return (LADDER.find(m => m * decade >= target) ?? 10) * decade;
+}
+/** A `bin` step's declared width in bp, with `auto` resolved at this zoom. */
+export function binStepWidth(step, bpPerPx) {
+    return step === AUTO_BIN ? autoBinStep(bpPerPx) : Number(step);
+}

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

@@ -0,0 +1,81 @@
+// Generated by scripts/generateMarkRules.ts from packages/display-kit/src/colorScale.ts: do not edit, `pnpm autogen` rewrites it.
+/**
+ * The scales a colour object paints through, in a module that imports
+ * nothing: `jbrowse validate` carries a copy of it, so the validator and the
+ * displays read one statement.
+ */
+/** How a colour object maps its `field`; `none` paints `value`. */
+export const COLOR_SCALES = [
+    'none',
+    'categorical',
+    'linear',
+    'log',
+    'threshold',
+];
+/** What a field paints through under `scales` while `scale` is unset. */
+export function fieldScaleOf(scales, field) {
+    return ((Object.hasOwn(scales, field) ? scales[field] : scales['*']) ??
+        'categorical');
+}
+/**
+ * The scale a colour object paints through: `none` while no `field` is
+ * named, else its own `scale`, or `fieldScale` where that is unset.
+ */
+export function paintedScale({ scale, field }, fieldScale) {
+    return field ? (scale ?? fieldScale) : 'none';
+}
+function pinned(entry) {
+    return entry !== '' && Number.isFinite(Number(entry));
+}
+/**
+ * What a colour object's slots say together that no single slot can refuse,
+ * since the config editor writes one slot at a time (ADR-133). A display shows
+ * these as a notice and draws what it can. `fieldScale` is the scale a named
+ * field paints through when `scale` is unset.
+ */
+export function colorProblems(color, fieldScale) {
+    const { domain = [], range = [], domainMin, domainMax } = color;
+    const scale = paintedScale({ scale: color.scale, field: color.field ?? '' }, fieldScale);
+    const problems = [];
+    if (scale === 'threshold') {
+        if (domain.some((cut, i) => !pinned(cut) || Number(cut) <= Number(domain[i - 1]))) {
+            problems.push({
+                rule: 'threshold-cuts',
+                slot: 'domain',
+                message: 'threshold cuts are distinct numbers, read in ascending order, with the range running from the lowest interval; a repeated cut leaves an interval no value falls in',
+            });
+        }
+        if (domain.length > 0 &&
+            range.length > 0 &&
+            range.length !== domain.length + 1) {
+            problems.push({
+                rule: 'threshold-range',
+                slot: 'range',
+                message: `${domain.length} threshold ${domain.length === 1 ? 'cut makes' : 'cuts make'} ${domain.length + 1} intervals, one colour each, and range lists ${range.length}: a missing colour comes from the default palette and an extra one is never read`,
+            });
+        }
+    }
+    if (scale === 'linear' || scale === 'log') {
+        if (domain.length > 0) {
+            problems.push({
+                rule: 'ramp-domain',
+                slot: 'domain',
+                message: "a linear or log scale reads no domain, which is a categorical scale's order and a threshold scale's cuts; a ramp's ends are domainMin and domainMax where the colour has them",
+            });
+        }
+        if (domainMin !== undefined &&
+            domainMax !== undefined &&
+            domainMin > domainMax) {
+            problems.push({
+                rule: 'ramp-ends',
+                slot: 'domainMax',
+                message: 'domainMax is below domainMin: the ramp spans the two either way, and reverse is what turns it round',
+            });
+        }
+    }
+    return problems;
+}
+/** `colorProblems` as the lines a display's corner notice lists, under the setting's own name. */
+export function colorNotices(color, fieldScale, name = 'color') {
+    return colorProblems(color, fieldScale).map(({ slot, message }) => `${name}.${slot}: ${message}`);
+}

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

@@ -0,0 +1,23 @@
+/** The `jexl:` prefix marks a config value as a deferred callback expression. */
+export const JEXL_PREFIX = 'jexl:';
+export function isJexl(str) {
+    return typeof str === 'string' && str.startsWith(JEXL_PREFIX);
+}
+/** Add the `jexl:` prefix unless the string already carries it. */
+export function ensureJexlPrefix(code) {
+    return isJexl(code) ? code : `${JEXL_PREFIX}${code}`;
+}
+/**
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
+ *
+ * @param str - string of code like `jexl:...`
+ * @param jexl - the instance whose registered functions the expression may call
+ *   (`pluginManager.jexl` on eval paths)
+ */
+export function stringToJexlExpression(str, jexl) {
+    if (!isJexl(str)) {
+        throw new Error('string does not appear to be in jexl format');
+    }
+    return jexl.compile(str.slice(JEXL_PREFIX.length));
+}

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

@@ -0,0 +1,253 @@
+// Generated by scripts/generateMarkRules.ts from plugins/marks/src/LinearMarkDisplay/markProblems.ts: do not edit, `pnpm autogen` rewrites it.
+import { AUTO_BIN } from './autoBin.js';
+import { colorProblems, isJexl, paintedScale } from './markRuleFacts.js';
+import { DEFAULT_AGGREGATE_OP, DEFAULT_BIN_AS, DEFAULT_COVERAGE_AS, DEFAULT_FORMULA_AS, DEFAULT_MARK_SHAPE, DEFAULT_PILEUP_AS, DEFAULT_PILEUP_FIELDS, } from './markVocabulary.js';
+import { SHAPE_SPECS, rampResolvesPerRegion, readsValue } from './shapeSpecs.js';
+/**
+ * The level of every rule of the list, by the stable id a report and a test
+ * refer to it by. A single mark's combination that a JSON schema can state is
+ * the mark schema's `requires` and is not restated here.
+ */
+export const MARK_RULES = {
+    'unread-channel': 'warning',
+    'span-density-source': 'warning',
+    'threshold-cuts': 'warning',
+    'threshold-range': 'warning',
+    'ramp-domain': 'warning',
+    'ramp-ends': 'warning',
+    'unpinned-span-ramp': 'warning',
+    'empty-zoom-range': 'error',
+    'step-expression': 'error',
+    'bin-width': 'error',
+    'step-pair': 'warning',
+    'op-field': 'error',
+    'step-field-expression': 'error',
+    'unwritten-y': 'error',
+    'value-beside-rows': 'warning',
+    'two-packings': 'warning',
+    'second-density-mark': 'warning',
+};
+function found(rule, slot, message) {
+    return { rule, level: MARK_RULES[rule], slot, message };
+}
+function shapeOf(mark) {
+    return mark.shape ?? DEFAULT_MARK_SHAPE;
+}
+function stepsOf(mark) {
+    return mark.transform ?? [];
+}
+function rampColor(mark) {
+    const color = mark.encoding?.color ?? {};
+    const painted = paintedScale({ scale: color.scale, field: color.field ?? '' }, 'categorical');
+    return painted === 'linear' || painted === 'log' ? color : undefined;
+}
+function drawTogether(a, b) {
+    const upper = (m) => m.maxBpPerPx || Infinity;
+    const lower = (m) => m.minBpPerPx ?? 0;
+    return lower(a) < upper(b) && lower(b) < upper(a);
+}
+// The field names a step reads, by the slot each is written in.
+function fieldRefs(step) {
+    const list = (slot, refs = []) => refs.map((ref, k) => [`${slot}.${k}`, ref]);
+    switch (step.type) {
+        case 'bin':
+        case 'flatten':
+            return [['field', step.field]];
+        case 'pileup':
+            return list('fields', step.fields);
+        case 'aggregate':
+            return [
+                ...list('groupby', step.groupby),
+                ...(step.ops ?? []).map((o, k) => [
+                    `ops.${k}.field`,
+                    o.field,
+                ]),
+            ];
+        default:
+            return [];
+    }
+}
+// A slot naming two fields, and the default it reads as when it names another
+// number of them.
+function pairSlot(step) {
+    return step.type === 'bin'
+        ? { slot: 'as', names: step.as, fallback: DEFAULT_BIN_AS }
+        : step.type === 'pileup'
+            ? { slot: 'fields', names: step.fields, fallback: DEFAULT_PILEUP_FIELDS }
+            : undefined;
+}
+function packs(mark) {
+    return stepsOf(mark).some(s => s.type === 'pileup');
+}
+function banded(mark) {
+    return packs(mark) || !!mark.encoding?.row;
+}
+// The fields the last step that makes its features from nothing leaves behind,
+// with what the steps after it add; undefined where no step does, and every
+// field of the file is still there.
+function madeFields(mark) {
+    const steps = stepsOf(mark);
+    const made = steps.findLastIndex(s => s.type === 'aggregate' || s.type === 'coverage');
+    const last = steps[made];
+    if (!last) {
+        return undefined;
+    }
+    const fields = new Set(['refName', 'start', 'end']);
+    if (last.type === 'coverage') {
+        fields.add(last.as ?? DEFAULT_COVERAGE_AS);
+    }
+    else if (last.type === 'aggregate') {
+        const bin = steps
+            .slice(0, made)
+            .findLast((s) => s.type === 'bin');
+        const edges = bin?.as ?? DEFAULT_BIN_AS;
+        for (const field of last.groupby?.length
+            ? last.groupby
+            : edges.length === 2
+                ? edges
+                : []) {
+            fields.add(field);
+        }
+        for (const { op = DEFAULT_AGGREGATE_OP, field, as } of last.ops ?? []) {
+            fields.add(as || (op === 'count' || !field ? op : `${op}_${field}`));
+        }
+    }
+    for (const step of steps.slice(made + 1)) {
+        if (step.type === 'formula') {
+            fields.add(step.as ?? DEFAULT_FORMULA_AS);
+        }
+        else if (step.type === 'pileup') {
+            fields.add(step.as ?? DEFAULT_PILEUP_AS);
+        }
+        else if (step.type === 'flatten' && step.index) {
+            fields.add(step.index);
+        }
+    }
+    return fields;
+}
+// What a list of steps cannot run as written, whether a mark's or the display's
+function stepProblems(steps) {
+    const problems = [];
+    for (const [i, step] of steps.entries()) {
+        if (!step) {
+            continue;
+        }
+        const { type } = step;
+        if ((type === 'filter' || type === 'formula') && !isJexl(step.expr ?? '')) {
+            problems.push(found('step-expression', `transform.${i}.expr`, `a ${type} reads a jexl: expression`));
+        }
+        if (type === 'bin' &&
+            step.step !== undefined &&
+            step.step !== AUTO_BIN &&
+            !(Number(step.step) > 0)) {
+            problems.push(found('bin-width', `transform.${i}.step`, 'a bin is a positive width in bp'));
+        }
+        const pair = pairSlot(step);
+        if (pair?.names && pair.names.length !== 2) {
+            problems.push(found('step-pair', `transform.${i}.${pair.slot}`, `a ${type} reads two field names from ${pair.slot} and this names ${pair.names.length}, so it reads ${pair.fallback.join(' and ')}`));
+        }
+        if (type === 'aggregate') {
+            for (const [k, { op = DEFAULT_AGGREGATE_OP, field }] of (step.ops ?? []).entries()) {
+                if (op !== 'count' && !field) {
+                    problems.push(found('op-field', `transform.${i}.ops.${k}.field`, `${op} reads a field and names none`));
+                }
+            }
+        }
+        for (const [slot, ref] of fieldRefs(step)) {
+            if (ref && isJexl(ref)) {
+                problems.push(found('step-field-expression', `transform.${i}.${slot}`, `the ${type} step reads a field name or a dotted path; a formula step in front computes one`));
+            }
+        }
+    }
+    return problems;
+}
+function ownProblems(mark) {
+    const shape = shapeOf(mark);
+    const problems = [];
+    const y = mark.encoding?.y;
+    const channels = new Set(['x', 'x2', ...SHAPE_SPECS[shape].channels]);
+    for (const channel of Object.keys(mark.encoding ?? {})) {
+        if (!channels.has(channel)) {
+            problems.push(found('unread-channel', `encoding.${channel}`, `a ${shape} does not read ${channel}`));
+        }
+    }
+    if (!readsValue(shape) && mark.source === 'density') {
+        problems.push(found('span-density-source', 'source', `a ${shape} does not draw the density sidecar`));
+    }
+    const color = mark.encoding?.color ?? {};
+    for (const { rule, slot, message } of colorProblems(color, 'categorical')) {
+        problems.push(found(rule, `encoding.color.${slot}`, message));
+    }
+    const ramp = rampColor(mark);
+    if (ramp) {
+        const { domainMin, domainMax } = ramp;
+        if (rampResolvesPerRegion(shape) &&
+            (domainMin === undefined || domainMax === undefined)) {
+            problems.push(found('unpinned-span-ramp', `encoding.color.${domainMin === undefined ? 'domainMin' : 'domainMax'}`, "a span's ramp resolves an open end against each region's own extremes, so its colours agree across regions only with domainMin and domainMax both pinned"));
+        }
+    }
+    const { minBpPerPx = 0, maxBpPerPx = 0 } = mark;
+    if (minBpPerPx > 0 && maxBpPerPx > 0 && minBpPerPx >= maxBpPerPx) {
+        problems.push(found('empty-zoom-range', 'minBpPerPx', `never draws: minBpPerPx ${minBpPerPx} is not below maxBpPerPx ${maxBpPerPx}`));
+    }
+    problems.push(...stepProblems(stepsOf(mark)));
+    const fields = madeFields(mark);
+    if (fields && y && !isJexl(y) && !fields.has(y)) {
+        problems.push(found('unwritten-y', 'encoding.y', `reads "${y}", which its steps do not write; they leave ${[...fields].join(', ')}`));
+    }
+    return problems;
+}
+/**
+ * The problems of a `marks` list as a config snapshot holds it: shorthands
+ * lifted, defaults left off. `facet` is the display's facet as written, naming
+ * the field its sections stack by; under one, a rowless mark stands on each
+ * section's first row by design. `transform` is the display's own steps,
+ * checked as a mark's are and reported with no mark. An `undefined` mark or
+ * step is one the caller could not read, such as one a file's schema refuses:
+ * it keeps its index, so the others are reported where they are, and is
+ * checked for nothing. A file's own spelling goes through the schema's lift
+ * first, which `jbrowse validate` does from the generated manifest.
+ */
+export function markProblems(marks, facet, transform = []) {
+    const faceted = typeof facet?.field === 'string' && facet.field !== '';
+    const problems = [
+        ...stepProblems(transform),
+        ...marks.flatMap((mark, i) => mark ? ownProblems(mark).map(p => ({ mark: i, ...p })) : []),
+    ];
+    for (const [i, mark] of marks.entries()) {
+        for (const [j, other] of marks.entries()) {
+            if (i === j || !mark || !other || !drawTogether(mark, other)) {
+                continue;
+            }
+            if (!faceted &&
+                shapeOf(mark) !== 'span' &&
+                !banded(mark) &&
+                banded(other)) {
+                problems.push({
+                    mark: i,
+                    ...found('value-beside-rows', 'encoding.row', `stands in the first of the rows mark ${j} bands the plot into, its axis repeated per row`),
+                });
+            }
+            if (i > j && packs(mark) && packs(other)) {
+                problems.push({
+                    mark: i,
+                    ...found('two-packings', 'transform', `packs rows of its own, as mark ${j} does, and the two share row numbers; one pileup in the display's transform packs them together, ${faceted ? 'though across every section at once, leaving each section the rows the others fill' : "with each mark's encoding.row naming the field the pileup writes"}`),
+                });
+            }
+            if (i > j && mark.source === 'density' && other.source === 'density') {
+                problems.push({
+                    mark: i,
+                    ...found('second-density-mark', 'source', `mark ${j} already stands in for the density sidecar here`),
+                });
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * A problem as one line of a notice: `mark 0 encoding.y: …`, or
+ * `transform.0.step: …` for the display's own step.
+ */
+export function problemText({ mark, slot, message }) {
+    return `${mark === undefined ? '' : `mark ${mark} `}${slot}: ${message}`;
+}

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

@@ -0,0 +1,3 @@
+// Generated by scripts/generateMarkRules.ts from plugins/marks/src/LinearMarkDisplay/markRuleFacts.ts: do not edit, `pnpm autogen` rewrites it.
+export { isJexl } from './jexlStrings.js';
+export { colorProblems, paintedScale } from './colorScale.js';

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

@@ -0,0 +1,20 @@
+// 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_SHAPES = ['bar', 'point', 'span'];
+export const DEFAULT_MARK_SHAPE = 'bar';
+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'];
+export const DEFAULT_COVERAGE_AS = 'coverage';
+export const DEFAULT_FLATTEN_FIELD = 'subfeatures';
+export const DEFAULT_PILEUP_AS = 'row';
+export const DEFAULT_PILEUP_FIELDS = ['start', 'end'];
+export const AGGREGATE_OPS = ['count', 'sum', 'mean', 'min', 'max'];
+export const DEFAULT_AGGREGATE_OP = 'count';

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

@@ -0,0 +1,41 @@
+/**
+ * What each shape reads: the one statement the lane request, the rule list and
+ * the model's value tests derive theirs from.
+ *
+ * Its own module, reaching only the vocabulary beside it: the rule list reads
+ * it and `jbrowse validate` carries a copy, and markList.ts takes render-core's
+ * marks barrel — shader sources included — which the examples sites' eager
+ * budget then pays for. `layerRequests` in model.ts is where each lane is
+ * checked to be one the encoder fills.
+ */
+export const SHAPE_SPECS = {
+    bar: { channels: ['y', 'row', 'color'], ramp: 'display' },
+    point: { channels: ['y', 'row', 'color', 'glyph'], ramp: 'display' },
+    span: { channels: ['row', 'color'], ramp: 'worker' },
+};
+function specOf(shape) {
+    return SHAPE_SPECS[shape];
+}
+/** Whether a shape stands at a `y` value, so a mark of it naming none draws nothing. */
+export function readsValue(shape) {
+    return specOf(shape).channels.includes('y');
+}
+/** Whether a shape's ramp colour resolves per region, in the worker. */
+export function rampResolvesPerRegion(shape) {
+    return specOf(shape).ramp === 'worker';
+}
+/**
+ * The lanes a mark asks the worker to fill: its shape's channels, a ramp's raw
+ * values beside the colour where the display resolves the ramp, and the hit
+ * index. The encoder fills whichever of `color` and `colorValue` the colour
+ * declaration calls for.
+ */
+export function markLanes(shape) {
+    const spec = specOf(shape);
+    return [
+        ...spec.channels.flatMap((channel) => channel === 'color' && spec.ramp === 'display'
+            ? [channel, 'colorValue']
+            : [channel]),
+        'index',
+    ];
+}