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

package/README.md

@@ -427,6 +427,13 @@ naming a trackId that does not exist, a duplicate trackId. Exits 1.
 Types registered by plugins are not known to this command, so they come through
 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.
+
 Examples:
 
 # check the config.json in the current directory

package/dist/commands/add-track-utils/track-config.js

@@ -56,9 +56,9 @@ export function mergeDisplayDefaults({ configObj, color, height, displayDefaults
 // An unknown track type accepts everything: it is a plugin's, and this manifest
 // is only the core plugins'.
 //
-// The message names the display when the track offers one — which most do, and
-// AlignmentsTrack is the case that matters here, since `--color` is the
-// reachable mistake and LinearAlignmentsDisplay is the only place to go look.
+// The message names the display where the track offers exactly one, and the
+// track otherwise: the keys checked are the union over its displays, so
+// naming one of several would send the reader to look in the wrong place.
 function checkDisplayDefaultKeys(merged, trackType) {
     const { displayTypes, keys } = displayDefaultsForTrackType(trackType);
     if (keys.length === 0) {

package/dist/commands/make-pif/index.js

@@ -125,7 +125,7 @@ export async function run(args) {
         throw new Error(`PIF sort/index pipeline exited with ${describeExit(exit)}`);
     }
     const { stats } = pass;
-    const { samples, rows, skipped } = stats;
+    const { samples, rows, cigarRows, skipped } = stats;
     if (rows === 0) {
         discardPart();
         throw new Error(`No valid PAF rows found in ${file ?? 'stdin'} (${skipped} line(s) had fewer than the 12 mandatory PAF columns). Is this a PAF file?`);
@@ -135,6 +135,11 @@ export async function run(args) {
     if (skipped > 0) {
         console.warn(`Warning: skipped ${skipped} of ${rows + skipped} line(s) with fewer than the 12 mandatory PAF columns`);
     }
+    if (coarseGap !== undefined && cigarRows === 0) {
+        console.warn('Warning: no row carried a CIGAR (cg:Z: or cs:Z:), so the coarse tier repeats ' +
+            'the fine tier and doubles the file for nothing. Rebuild with --no-coarse, ' +
+            'or align with a CIGAR (minimap2 -c) so low zooms have something cheaper to read.');
+    }
     // An all-vs-all PAF that does not state every pair indexes perfectly well and
     // then draws an empty synteny band for each pair the aligner never emitted,
     // which reads as "no homology here" rather than as "never computed". This is

package/dist/commands/make-pif/pif-generator.js

@@ -5,27 +5,31 @@ import { Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { createGunzip } from 'node:zlib';
 import { coarsenCigar, csToCigar, flipCigar, flipCoarseCigar, swapCoarseCigar, swapIndelCigar, } from '@jbrowse/cigar-utils';
+import { version } from '../../version.js';
 // Default gap (bp) of the coarse tier's coarse CIGAR: how far a straight line
 // across one of its runs may be from the alignment's real path. Indels longer
 // than half of it keep their letter; shorter ones fold into the runs. 10kb
 // matches the adapter's default coarseBpPerPxThreshold, so at the zoom where the
 // tier is served the bound is ~1px and a folded indel was sub-pixel anyway.
 export const DEFAULT_COARSE_GAP = 10_000;
+// Generation 2 (2026-09): every row carries `pi:i:`, the input row's index,
+// and the header names the writer.
+export const PIF_FORMAT_VERSION = 2;
 /**
  * The one meta line a PIF carries, sorted first by the C-locale sort and kept
- * by tabix as a header. It states the format generation, the tiers written,
- * the coarse tier's accuracy bound (`--coarse`), and whether every input row
- * had a CIGAR — the facts a reader cannot recover from the rows.
+ * by tabix as a header. It states the format generation, the writer, the
+ * tiers written, the coarse tier's accuracy bound (`--coarse`), and whether
+ * every input row had a CIGAR — the facts a reader cannot recover from the rows.
  */
 export function pifHeader(coarseGap, stats) {
     const cigars = stats.cigarRows === 0
         ? 'none'
-        : stats.cigarRows === stats.rows && stats.unboundedRows === 0
+        : stats.cigarRows === stats.rows
             ? 'all'
             : 'some';
     const tiers = coarseGap === undefined ? 'fine' : 'fine,coarse';
     const bound = coarseGap === undefined ? '' : `\tcoarse:i:${coarseGap}`;
-    return `#pif\tversion:i:1\ttiers:Z:${tiers}${bound}\tcigars:Z:${cigars}\n`;
+    return `#pif\tversion:i:${PIF_FORMAT_VERSION}\twriter:Z:jbrowse-cli/${version}\ttiers:Z:${tiers}${bound}\tcigars:Z:${cigars}\n`;
 }
 function panSNSample(refName) {
     const i = refName.indexOf('#');
@@ -62,33 +66,23 @@ export function missingPairs({ samples, pairs }) {
     }
     return out;
 }
-// The coarse row's `cr:Z:` value, or nothing, and whether withholding it left
-// the row making a claim it cannot keep.
-//
-// `ops` is nothing when the row has no CIGAR, when the fold is a single run
-// (the coordinate columns already say it all), and when the walk does not close
-// on the row's own far corner — clipping ops, a hand-made cg, a cs whose spans
-// don't add up — since the columns are what the fine tier draws and the coarse
-// row must not disagree with them. A fold of several runs with no kept indel is
-// still written: the runs are where a lopsided cluster of small indels bends
-// the path, which a straight ribbon across the row would miss by up to the
-// whole cluster.
-//
-// `unbounded` separates the last of those from the rest. The first two leave a
-// tagless row a reader may take as one run within `--coarse`, and it is one; a
-// walk that misses its own corner leaves a row that reads the same way and is
-// not, so the header has to stop saying `cigars:Z:all` on its account.
+// The coarse row's `cr:Z:` value, or nothing when the row has no CIGAR or the
+// fold is a single run that closes on the coordinate columns, which then say it
+// all. A fold of several runs with no kept indel is still written: a lopsided
+// cluster of small indels bends the path by their sum. So is a fold whose walk
+// misses the row's own far corner (clipping ops, a hand-made cg, a cs whose
+// spans don't add up): the fine tier walks that CIGAR from the start corner
+// without checking, and the coarse tier draws the same path only if it walks
+// the same fold.
 function coarseFold({ cigar, coarseGap, ownLen, mateLen, }) {
-    const coarse = cigar === undefined ? undefined : coarsenCigar(cigar, coarseGap);
-    const closed = coarse !== undefined &&
-        coarse.ownLen === ownLen &&
-        coarse.mateLen === mateLen;
-    return {
-        ops: closed && (coarse.gapCount > 0 || coarse.opCount > 1)
-            ? coarse.ops
-            : undefined,
-        unbounded: cigar !== undefined && !closed,
-    };
+    if (cigar === undefined) {
+        return undefined;
+    }
+    const coarse = coarsenCigar(cigar, coarseGap);
+    const closed = coarse.ownLen === ownLen && coarse.mateLen === mateLen;
+    return !closed || coarse.gapCount > 0 || coarse.opCount > 1
+        ? coarse.ops
+        : undefined;
 }
 // A PIF row carries exactly ONE alignment string — `cg:Z:`, in the orientation
 // of the perspective it is indexed under. A minimap2 `cs:Z:` is folded into that
@@ -135,10 +129,14 @@ function processLine(rawLine, coarseGap, stats) {
     // rest[0]=num_matches, rest[1]=block_len, rest[2]=mapq, rest[3+]=optional tags
     const [c1, l1, s1, e1, strand, c2, l2, s2, e2, ...rest] = parts;
     addPanSNPair(stats, c1, c2);
-    // an incoming cr:Z: (a PIF turned back into PAF, or a tool that adopted the
-    // tag) is dropped from both tiers: the fine tier never carries one, and the
-    // coarse tier writes its own below
-    const { tags, cigarIdx } = foldCsIntoCg(rest.filter(f => !f.startsWith('cr:Z:')));
+    // an incoming cr:Z: or pi:i: (a PIF turned back into PAF, or a tool that
+    // adopted the tags) is dropped: the coarse tier writes its own fold below,
+    // and every row of this alignment gets this pass's row index as `pi`, the
+    // one id its four rows share across perspectives and tiers
+    const { tags, cigarIdx } = foldCsIntoCg([
+        ...rest.filter(f => !f.startsWith('cr:') && !f.startsWith('pi:')),
+        `pi:i:${stats.rows - 1}`,
+    ]);
     const cigar = cigarIdx === -1 ? undefined : tags[cigarIdx].slice(5);
     if (cigar !== undefined) {
         stats.cigarRows++;
@@ -161,15 +159,12 @@ function processLine(rawLine, coarseGap, stats) {
     const coarse = cigarIdx === -1 ? tags : tags.filter((_, i) => i !== cigarIdx);
     // the T row's own axis is the target, as the PAF CIGAR is written; the Q row
     // re-orients it for the query, the way the fine tier's cg is
-    const { ops: cr, unbounded } = coarseFold({
+    const cr = coarseFold({
         cigar,
         coarseGap,
         ownLen: +e2 - +s2,
         mateLen: +e1 - +s1,
     });
-    if (unbounded) {
-        stats.unboundedRows++;
-    }
     const tCr = cr === undefined ? [] : [`cr:Z:${cr}`];
     const qCr = cr === undefined
         ? []
@@ -215,7 +210,6 @@ export async function createPIF(filename, stream, coarseGap) {
         pairs: new Set(),
         rows: 0,
         cigarRows: 0,
-        unboundedRows: 0,
         skipped: 0,
     };
     const transform = makePifTransform(coarseGap, stats);