@jbrowse/plugin-config 4.3.0 → 5.0.0-beta.10

package/esm/FromConfigSequenceAdapter/FromConfigSequenceAdapter.d.ts

@@ -1,12 +1,25 @@
 import FromConfigAdapter from '../FromConfigAdapter/FromConfigAdapter.ts';
-import type { RegionsAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+import type { BaseOptions, RegionsAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
 import type { Feature } from '@jbrowse/core/util/simpleFeature';
 import type { NoAssemblyRegion } from '@jbrowse/core/util/types';
 export default class FromConfigSequenceAdapter extends FromConfigAdapter implements RegionsAdapter {
+    /**
+     * Fetch features for a certain region
+     * @param region - Region
+     * @returns Observable of Feature objects in the region
+     */
     getFeatures(region: NoAssemblyRegion): import("rxjs").Observable<Feature>;
     getRegions(): Promise<{
+        refName: string;
         start: number;
         end: number;
-        refName: string;
     }[]>;
+    /**
+     * `BaseSequenceAdapter`'s default, which this cannot inherit — it extends
+     * `FromConfigAdapter` — and which anything resolving a sequence SUB-adapter
+     * requires by name: `getSequenceSubAdapter` checks for the method and refuses
+     * an adapter without it, so a GC content track over a from-config assembly
+     * failed with "provides no sequence".
+     */
+    getSequence(region: NoAssemblyRegion, opts?: BaseOptions): Promise<string | undefined>;
 }

package/esm/FromConfigSequenceAdapter/FromConfigSequenceAdapter.js

@@ -1,50 +1,42 @@
 import { ObservableCreate } from '@jbrowse/core/util/rxjs';
 import SimpleFeature from '@jbrowse/core/util/simpleFeature';
-import { firstValueFrom } from 'rxjs';
-import { toArray } from 'rxjs/operators';
-import FromConfigAdapter from "../FromConfigAdapter/FromConfigAdapter.js";
+import FromConfigAdapter, { mergeFeaturesToRegions, } from '../FromConfigAdapter/FromConfigAdapter.js';
 export default class FromConfigSequenceAdapter extends FromConfigAdapter {
+    /**
+     * Fetch features for a certain region
+     * @param region - Region
+     * @returns Observable of Feature objects in the region
+     */
     getFeatures(region) {
-        return ObservableCreate(async (observer) => {
-            const feats = await firstValueFrom(super.getFeatures(region).pipe(toArray()));
-            const feat = feats[0];
-            observer.next(new SimpleFeature({
-                ...feat.toJSON(),
-                uniqueId: `${feat.id()}:${region.start}-${region.end}`,
-                end: region.end,
-                start: region.start,
-                seq: feat
-                    .get('seq')
-                    .slice(Math.max(region.start - feat.get('start'), 0), Math.max(region.end - feat.get('start'), 0)),
-            }));
+        const { refName, start, end } = region;
+        return ObservableCreate(observer => {
+            const feats = this.features.get(refName) ?? [];
+            const feat = feats.find(f => f.get('end') > start && f.get('start') < end);
+            if (feat) {
+                const featStart = feat.get('start');
+                observer.next(new SimpleFeature({
+                    ...feat.toJSON(),
+                    uniqueId: `${feat.id()}:${start}-${end}`,
+                    start,
+                    end,
+                    seq: feat.get('seq').slice(Math.max(start - featStart, 0), Math.max(end - featStart, 0)),
+                }));
+            }
             observer.complete();
         });
     }
     async getRegions() {
-        const regions = [];
-        for (const [refName, features] of this.features) {
-            let currentRegion;
-            for (const feature of features) {
-                if (currentRegion &&
-                    currentRegion.end >= feature.get('start') &&
-                    currentRegion.start <= feature.get('end')) {
-                    currentRegion.end = feature.get('end');
-                }
-                else {
-                    if (currentRegion) {
-                        regions.push(currentRegion);
-                    }
-                    currentRegion = {
-                        refName,
-                        start: feature.get('start'),
-                        end: feature.get('end'),
-                    };
-                }
-            }
-            if (currentRegion) {
-                regions.push(currentRegion);
-            }
-        }
-        return regions;
+        return mergeFeaturesToRegions(this.features);
+    }
+    /**
+     * `BaseSequenceAdapter`'s default, which this cannot inherit — it extends
+     * `FromConfigAdapter` — and which anything resolving a sequence SUB-adapter
+     * requires by name: `getSequenceSubAdapter` checks for the method and refuses
+     * an adapter without it, so a GC content track over a from-config assembly
+     * failed with "provides no sequence".
+     */
+    async getSequence(region, opts) {
+        const features = await this.getFeaturesArray({ ...region, assemblyName: '' }, opts);
+        return features[0]?.get('seq');
     }
 }

package/esm/FromConfigSequenceAdapter/configSchema.d.ts

@@ -1,7 +1,40 @@
+/**
+ * #config FromConfigSequenceAdapter
+ * #trackType ReferenceSequenceTrack
+ * #fileFormat inline | Inline sequence | Each feature's `seq` holds the bases for its region
+ * supplies reference sequence inline in the config; each feature's `seq` holds
+ * the bases for its region
+ *
+ * #example
+ * Used as the adapter of an assembly's `sequence` (a `ReferenceSequenceTrack`):
+ * ```js
+ * {
+ *   type: 'ReferenceSequenceTrack',
+ *   trackId: 'my_refseq',
+ *   adapter: {
+ *     type: 'FromConfigSequenceAdapter',
+ *     features: [
+ *       { uniqueId: 'ctgA', refName: 'ctgA', start: 0, end: 10, seq: 'ATGCATGCAT' },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
 declare const sequenceConfigSchema: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    features: {
-        type: string;
-        defaultValue: never[];
+    type: {
+        type: "string";
+    } & {
+        defaultValue: string;
     };
-}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+    readonly adapterId: {
+        type: "string";
+    } & {
+        defaultValue: string;
+    };
+    readonly features: {
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
+    };
+}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined, true, import("@jbrowse/core/configuration").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
 export default sequenceConfigSchema;

package/esm/FromConfigSequenceAdapter/configSchema.js

@@ -1,12 +1,48 @@
 import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+/**
+ * #config FromConfigSequenceAdapter
+ * #trackType ReferenceSequenceTrack
+ * #fileFormat inline | Inline sequence | Each feature's `seq` holds the bases for its region
+ * supplies reference sequence inline in the config; each feature's `seq` holds
+ * the bases for its region
+ *
+ * #example
+ * Used as the adapter of an assembly's `sequence` (a `ReferenceSequenceTrack`):
+ * ```js
+ * {
+ *   type: 'ReferenceSequenceTrack',
+ *   trackId: 'my_refseq',
+ *   adapter: {
+ *     type: 'FromConfigSequenceAdapter',
+ *     features: [
+ *       { uniqueId: 'ctgA', refName: 'ctgA', start: 0, end: 10, seq: 'ATGCATGCAT' },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
 const sequenceConfigSchema = ConfigurationSchema('FromConfigSequenceAdapter', {
+    /**
+     * #slot
+     * stable identifier used as the adapter cache key; avoids hashing the
+     * (potentially large) features array. optional — falls back to hash.
+     */
+    adapterId: {
+        type: 'string',
+        defaultValue: '',
+    },
+    /**
+     * #slot
+     * one entry per reference sequence, each with a `uniqueId`, `refName`,
+     * `start`, `end`, and a `seq` string holding the bases for that span. The
+     * bases live in the config, so this is for small sequences — a plasmid, a
+     * test contig — not a genome.
+     */
     features: {
         type: 'frozen',
         defaultValue: [],
     },
 }, {
     explicitlyTyped: true,
-    implicitIdentifier: 'adapterId',
 });
 export default sequenceConfigSchema;

package/esm/FromConfigSequenceAdapter/index.js

@@ -1,10 +1,10 @@
 import { AdapterType } from '@jbrowse/core/pluggableElementTypes';
-import configSchema from "./configSchema.js";
+import configSchema from './configSchema.js';
 export default function FromConfigSequenceAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => new AdapterType({
         name: 'FromConfigSequenceAdapter',
         configSchema,
-        getAdapterClass: () => import("./FromConfigSequenceAdapter.js").then(r => r.default),
+        getAdapterClass: () => import('./FromConfigSequenceAdapter.js').then(r => r.default),
         adapterMetadata: {
             hiddenFromGUI: true,
         },

package/esm/NcbiSequenceReportAliasAdapter/NcbiSequenceReportAliasAdapter.d.ts

@@ -1,9 +1,10 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import type { BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-export default class NcbiSequenceReportAliasAdapter extends BaseAdapter implements BaseRefNameAliasAdapter {
-    getRefNameAliases(): Promise<{
+import type { NcbiSequenceReportAliasAdapterConfig } from './configSchema.ts';
+import type { BaseOptions, BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+export default class NcbiSequenceReportAliasAdapter extends BaseAdapter<NcbiSequenceReportAliasAdapterConfig> implements BaseRefNameAliasAdapter {
+    getRefNameAliases(opts?: BaseOptions): Promise<{
         refName: string;
         aliases: string[];
-        override: any;
+        override: boolean;
     }[]>;
 }

package/esm/NcbiSequenceReportAliasAdapter/NcbiSequenceReportAliasAdapter.js

@@ -1,38 +1,42 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { openLocation } from '@jbrowse/core/util/io';
+import { readAliasRows } from '../aliasUtils.js';
+// locate a column by its header name, throwing a column-specific error if a
+// required one is absent
+function requireColumn(header, name) {
+    const idx = header.indexOf(name);
+    if (idx === -1) {
+        throw new Error(`sequence_report.tsv header is missing required column "${name}"`);
+    }
+    return idx;
+}
 export default class NcbiSequenceReportAliasAdapter extends BaseAdapter {
-    async getRefNameAliases() {
-        const loc = this.getConf('location');
-        if (loc.uri === '' || loc.uri === '/path/to/my/sequence_report.tsv') {
+    async getRefNameAliases(opts) {
+        const rows = await readAliasRows(this.getConf('location'), this.pluginManager, opts);
+        if (rows.length === 0) {
             return [];
         }
         const override = this.getConf('useNameOverride');
-        const results = await openLocation(loc, this.pluginManager).readFile('utf8');
-        const lines = results
-            .split(/\n|\r\n|\r/)
-            .filter(f => !!f.trim())
-            .map(row => row.split('\t'));
-        const r = lines[0] || [];
-        const genBankIdx = r.indexOf('GenBank seq accession');
-        const refSeqIdx = r.indexOf('RefSeq seq accession');
-        const ucscIdx = r.indexOf('UCSC style name');
-        const seqNameIdx = r.indexOf('Sequence name');
-        if (genBankIdx === -1 || refSeqIdx === -1 || ucscIdx === -1) {
-            throw new Error('Header line must include "GenBank seq accession", "RefSeq seq accession", "UCSC style name", and "Sequence name"');
-        }
-        return lines
-            .slice(1)
-            .filter(cols => !!cols[ucscIdx] || !!cols[seqNameIdx])
+        const header = rows[0];
+        const dataRows = rows.slice(1);
+        const genBankIdx = requireColumn(header, 'GenBank seq accession');
+        const refSeqIdx = requireColumn(header, 'RefSeq seq accession');
+        const ucscIdx = requireColumn(header, 'UCSC style name');
+        // Sequence name is optional; -1 means absent
+        const seqNameIdx = header.indexOf('Sequence name');
+        const seqName = (cols) => seqNameIdx === -1 ? undefined : cols[seqNameIdx];
+        // refName comes from the UCSC name, falling back to the Sequence name; the
+        // filter guarantees one is present, so every mapped row has a truthy refName
+        return dataRows
+            .filter(cols => !!cols[ucscIdx] || !!seqName(cols))
             .map(cols => ({
-            refName: (cols[ucscIdx] || cols[seqNameIdx]),
+            refName: (cols[ucscIdx] || seqName(cols)),
             aliases: [
                 cols[genBankIdx],
                 cols[refSeqIdx],
                 cols[ucscIdx],
-                cols[seqNameIdx],
+                seqName(cols),
             ].filter((f) => !!f),
             override,
-        }))
-            .filter(f => !!f.refName);
+        }));
     }
 }

package/esm/NcbiSequenceReportAliasAdapter/configSchema.d.ts

@@ -1,15 +1,74 @@
+import type { Instance } from '@jbrowse/mobx-state-tree';
+export declare function normalizeSnapshot(snap: Record<string, unknown>): Record<string, unknown>;
+/**
+ * #config NcbiSequenceReportAliasAdapter
+ * can read "sequence_report.tsv" type files from NCBI
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `refNameAliases` — not on a track. The file ships
+ * beside any RefSeq assembly on NCBI datasets and aliases the RefSeq, GenBank
+ * and UCSC-style names of every sequence at once, so it replaces a
+ * hand-maintained chromAlias table:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * #example keeping the FASTA's own names
+ * With an NCBI FASTA (`NC_000001.11`), the default displays UCSC-style names
+ * (`chr1`) while still fetching bases under the accession. Set
+ * `useNameOverride: false` to display the accessions instead, with `chr1` left
+ * searchable as an alias:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *       useNameOverride: false,
+ *     },
+ *   },
+ * }
+ * ```
+ */
 declare const NcbiSequenceReportAliasAdapterConfigSchema: import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaType<{
-    location: {
-        type: string;
-        defaultValue: {
-            uri: string;
-            locationType: string;
-        };
+    type: {
+        type: "string";
+    } & {
+        defaultValue: string;
     };
-    useNameOverride: {
-        type: string;
+    readonly location: {
+        type: "maybeFileLocation";
+    };
+    readonly useNameOverride: {
+        type: "boolean";
+    } & {
         defaultValue: boolean;
-        description: string;
     };
-}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined>>;
+}, import("@jbrowse/core/configuration/configurationSchema").ConfigurationSchemaOptions<undefined, undefined, true, import("@jbrowse/core/configuration").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;
+export type NcbiSequenceReportAliasAdapterConfig = Instance<typeof NcbiSequenceReportAliasAdapterConfigSchema>;
 export default NcbiSequenceReportAliasAdapterConfigSchema;

package/esm/NcbiSequenceReportAliasAdapter/configSchema.js

@@ -1,13 +1,75 @@
-import { ConfigurationSchema } from '@jbrowse/core/configuration';
-function x() { }
+import { ConfigurationSchema, expandUriShorthand, } from '@jbrowse/core/configuration';
+export function normalizeSnapshot(snap) {
+    return expandUriShorthand(snap, 'location');
+}
+/**
+ * #config NcbiSequenceReportAliasAdapter
+ * can read "sequence_report.tsv" type files from NCBI
+ *
+ * #example
+ * Goes on an ASSEMBLY, under `refNameAliases` — not on a track. The file ships
+ * beside any RefSeq assembly on NCBI datasets and aliases the RefSeq, GenBank
+ * and UCSC-style names of every sequence at once, so it replaces a
+ * hand-maintained chromAlias table:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * #example keeping the FASTA's own names
+ * With an NCBI FASTA (`NC_000001.11`), the default displays UCSC-style names
+ * (`chr1`) while still fetching bases under the accession. Set
+ * `useNameOverride: false` to display the accessions instead, with `chr1` left
+ * searchable as an alias:
+ * ```js
+ * {
+ *   name: 'GCF_000001405.40',
+ *   sequence: {
+ *     type: 'ReferenceSequenceTrack',
+ *     trackId: 'GCF_000001405.40-ReferenceSequenceTrack',
+ *     adapter: {
+ *       type: 'BgzipFastaAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40.fa.gz',
+ *     },
+ *   },
+ *   refNameAliases: {
+ *     adapter: {
+ *       type: 'NcbiSequenceReportAliasAdapter',
+ *       uri: 'https://example.com/GCF_000001405.40_sequence_report.tsv',
+ *       useNameOverride: false,
+ *     },
+ *   },
+ * }
+ * ```
+ */
 const NcbiSequenceReportAliasAdapterConfigSchema = ConfigurationSchema('NcbiSequenceReportAliasAdapter', {
+    /**
+     * #slot
+     * location of the `sequence_report.tsv` NCBI publishes with an assembly. It
+     * carries the RefSeq, GenBank and UCSC-style name of every sequence, so one
+     * file aliases them all without hand-writing a chromAlias table.
+     */
     location: {
-        type: 'fileLocation',
-        defaultValue: {
-            uri: '/path/to/my/sequence_report.tsv',
-            locationType: 'UriLocation',
-        },
+        type: 'maybeFileLocation',
     },
+    /**
+     * #slot
+     */
     useNameOverride: {
         type: 'boolean',
         defaultValue: true,
@@ -15,16 +77,18 @@ const NcbiSequenceReportAliasAdapterConfigSchema = ConfigurationSchema('NcbiSequ
     },
 }, {
     explicitlyTyped: true,
-    preProcessSnapshot: snap => {
-        return snap.uri
-            ? {
-                ...snap,
-                location: {
-                    uri: snap.uri,
-                    baseUri: snap.baseUri,
-                },
-            }
-            : snap;
-    },
+    /**
+     * #preProcessSnapshot
+     *
+     *
+     * preprocessor to allow minimal config:
+     * ```json
+     * {
+     *   "type": "NcbiSequenceReportAliasAdapter",
+     *   "uri": "sequence_report.tsv"
+     * }
+     * ```
+     */
+    preProcessSnapshot: normalizeSnapshot,
 });
 export default NcbiSequenceReportAliasAdapterConfigSchema;

package/esm/NcbiSequenceReportAliasAdapter/index.js

@@ -1,11 +1,12 @@
 import { AdapterType } from '@jbrowse/core/pluggableElementTypes';
-import configSchema from "./configSchema.js";
+import configSchema, { normalizeSnapshot } from './configSchema.js';
 export default function NcbiSequenceReportAliasAdapterF(pluginManager) {
     pluginManager.addAdapterType(() => {
         return new AdapterType({
             name: 'NcbiSequenceReportAliasAdapter',
+            normalizeSnapshot,
             configSchema,
-            getAdapterClass: () => import("./NcbiSequenceReportAliasAdapter.js").then(r => r.default),
+            getAdapterClass: () => import('./NcbiSequenceReportAliasAdapter.js').then(r => r.default),
             adapterMetadata: {
                 hiddenFromGUI: true,
             },

package/esm/RefNameAliasAdapter/RefNameAliasAdapter.d.ts

@@ -1,7 +1,8 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import type { BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-export default class RefNameAliasAdapter extends BaseAdapter implements BaseRefNameAliasAdapter {
-    getRefNameAliases(): Promise<{
+import type { RefNameAliasAdapterConfig } from './configSchema.ts';
+import type { BaseOptions, BaseRefNameAliasAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
+export default class RefNameAliasAdapter extends BaseAdapter<RefNameAliasAdapterConfig> implements BaseRefNameAliasAdapter {
+    getRefNameAliases(opts?: BaseOptions): Promise<{
         refName: string;
         aliases: string[];
     }[]>;

package/esm/RefNameAliasAdapter/RefNameAliasAdapter.js

@@ -1,36 +1,30 @@
 import { BaseAdapter } from '@jbrowse/core/data_adapters/BaseAdapter';
-import { openLocation } from '@jbrowse/core/util/io';
+import { readAliasRows } from '../aliasUtils.js';
+// header lines start with '#'; the leading marker belongs to the first column
+const isComment = (cols) => !!cols[0]?.startsWith('#');
+// column names from a '#'-prefixed header row, with the marker stripped
+const headerNames = (cols) => cols.map((col, i) => (i === 0 ? col.slice(1) : col).trim());
 export default class RefNameAliasAdapter extends BaseAdapter {
-    async getRefNameAliases() {
-        const loc = this.getConf('location');
-        if (loc.uri === '' || loc.uri === '/path/to/my/aliases.txt') {
-            return [];
-        }
-        const results = await openLocation(loc, this.pluginManager).readFile('utf8');
+    async getRefNameAliases(opts) {
+        const rows = await readAliasRows(this.getConf('location'), this.pluginManager, opts);
         const refColumn = this.getConf('refNameColumn');
         const refColumnHeaderName = this.getConf('refNameColumnHeaderName');
-        const lines = results
-            .trim()
-            .split(/\n|\r\n|\r/)
-            .filter(f => !!f);
-        const header = lines.filter(f => f.startsWith('#'));
-        const headerCol = refColumnHeaderName && header.length
-            ? header
-                .at(-1)
-                .slice(1)
-                .split('\t')
-                .map(t => t.trim())
-                .indexOf(refColumnHeaderName)
+        const lastHeader = rows.filter(isComment).at(-1);
+        const headerCol = refColumnHeaderName && lastHeader
+            ? headerNames(lastHeader).indexOf(refColumnHeaderName)
             : refColumn;
-        return lines
-            .filter(f => !f.startsWith('#'))
-            .map(row => {
-            const aliases = row.split('\t');
-            const refName = aliases[headerCol];
-            return {
-                refName: refName,
-                aliases: aliases.filter(f => !!f.trim()),
-            };
+        if (headerCol === -1) {
+            throw new Error(`refNameColumnHeaderName "${refColumnHeaderName}" not found in alias file header`);
+        }
+        return rows
+            .filter(cols => !isComment(cols))
+            .flatMap(cols => {
+            // a blank refName column (short/ragged row, leading tab) would map every
+            // alias to an empty canonical name in buildRefNameMaps; drop such rows
+            const refName = cols[headerCol]?.trim();
+            return refName
+                ? [{ refName, aliases: cols.filter(f => !!f.trim()) }]
+                : [];
         });
     }
 }