@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/csv/exporter.ts

@@ -4,7 +4,7 @@
  * <attributes>` in the generic one) or, with `table: "nodes"`, the node table (`Id,Label,
  * <attributes>`), RFC 4180 quoted, one row per logical edge with expanded pairs folded back
  * through the `pair` role column; or, with `table: "adjacency"`, an adjacency table: a node and its
- * neighbours per row (`id:weight` for an explicit weight), no header, no attribute columns.
+ * neighbors per row (`id:weight` for an explicit weight), no header, no attribute columns.
  *
  * What survives a re-import exactly: ids (as text under the canonical rule), topology and
  * orientation, explicit weights (blank cells for defaulted ones), the per-row direction of the
@@ -18,7 +18,7 @@
  *
  * The adjacency table keeps ids, the node order, isolated nodes, the edge order, orientation and
  * explicit weights: consecutive edges with the same source share a row, a node the rows would
- * otherwise introduce out of index order gets a row of its own first, and a neighbour id holding a
+ * otherwise introduce out of index order gets a row of its own first, and a neighbor id holding a
  * colon is written `id:` when it has no weight so the importer does not read its tail as one.
  */
 
@@ -31,7 +31,8 @@ import { capabilities, checkCapabilities, countMixedEdges, LOSS } from "../../co
 import { formatDecimal, formatInteger } from "../../common/format.js";
 import { canonicalId } from "../../common/ids.js";
 import { joinListText } from "../../common/lists.js";
-import { type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
+import { otherFormatDialect, type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { inferTextDtype, type TextDtype } from "../../common/text.js";
 import { type ExplicitWeights, explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
@@ -39,31 +40,59 @@ import { type CommonExportOptions, type ExportCapabilities, type GraphExporter,
 import { EDGE_ID_NAMES, findColumn, LABEL_NAMES } from "./header.js";
 import { DELIMITER_CANDIDATES } from "./records.js";
 
-/** The format-specific options of the CSV exporter. */
-export interface CsvExportOptions {
+/**
+ * The format-specific options of the CSV exporter.
+ * @category Built-in formats
+ */
+export interface CsvExportOptions extends CommonExportOptions {
     /**
-     * The header spelling: "gephi" (default) writes `Source,Target,Type,...,Weight` with the per-row
-     * direction; "generic" writes `source,target,...,weight` and no direction column.
+     * The header spelling: "gephi" writes `Source,Target,Type,...,Weight`, with each edge's
+     * direction in `Type`; "generic" writes `source,target,...,weight` and no direction column. A JSON
+     * dialect name, from an options object shared with JSON saves, is ignored.
+     * @defaultValue "gephi"
      */
     dialect?: "gephi" | "generic" | undefined;
     /**
-     * Which table to write: the edge table (default), the node table, or an adjacency table (a node
-     * and its neighbours per row; read back with the importer's `table: "adjacency"`).
+     * Which table to write. "edges": one edge per row, with the edge attributes; isolated nodes and
+     * node attributes are not in it. "nodes": one node per row, with the node attributes and no
+     * edges. "adjacency": a node and its neighbors per row, which keeps every node and the node
+     * order but no attributes (read it back with `table: "adjacency"`). To keep both nodes and
+     * edges, write the node table and the edge table to two files and read them back with the
+     * `nodes` import option.
+     * @defaultValue "edges"
      */
     table?: "edges" | "nodes" | "adjacency" | undefined;
-    /** The field delimiter; "," by default. */
+    /**
+     * The field delimiter.
+     * @defaultValue ","
+     */
     delimiter?: string | undefined;
-    /** The line terminator; "\n" by default. */
+    /**
+     * The line terminator.
+     * @defaultValue "\n"
+     */
     newline?: "\n" | "\r\n" | undefined;
-    /** Whether to write the header row; true by default (an adjacency table never has one). */
+    /**
+     * Whether to write the header row (an adjacency table never has one). A file without a header is
+     * read back by position: source, target, weight, then unnamed columns. checkExport() returns
+     * W_CSV_HEADERLESS when the table has other columns; for a plain headerless edge list, pass
+     * `dialect: "generic"` and write a graph whose edges have only weights.
+     * @defaultValue true
+     */
     header?: boolean | undefined;
 }
 
-/** The CSV loss-note codes of check(); the shared ones are LOSS's. */
+/**
+ * The CSV loss-note codes of check(); the shared ones are LOSS's.
+ * @category Built-in formats
+ */
 export const CSV_LOSS = Object.freeze({
-    /** Two node ids share one text (a number and a string); export() throws E_INVALID_ID. */
+    /**
+     * Two node ids would be written as the same text (the number 5 and the text "5"); the save fails with
+     * E_INVALID_ID.
+     */
     ID_TEXT_COLLISION: LOSS.ID_TEXT_COLLISION,
-    /** Ids whose text reads back as the other type under the canonical rule. */
+    /** Ids that read back as a different type, such as the text "7" as the number 7. */
     ID_TEXT_TYPE: LOSS.ID_TEXT_TYPE,
     /**
      * The generic dialect has no direction column; an undirected or mixed graph reads back as
@@ -75,29 +104,54 @@ export const CSV_LOSS = Object.freeze({
     MUTUAL_EXPANDED: LOSS.MUTUAL_EXPANDED,
     /** An attribute column named like a reserved header is not written. */
     RESERVED_NAME: "W_CSV_RESERVED_NAME",
-    /** A column without a role that the importer gives one back by its name. */
+    /**
+     * An attribute without a role is written where the format keeps a role (for example, a `name` column as the label), and
+     * reads back with that role.
+     */
     ROLE_ASSUMED: LOSS.ROLE_ASSUMED,
-    /** A role column (id, label) whose name the importer does not recognise; the role is lost. */
+    /** A role column (id, label) whose name the importer does not recognize; the role is lost. */
     ROLE_NAME: "W_CSV_ROLE_NAME",
-    /** A role column (id, label) that is not string / dict reads back as string. */
+    /** An id or label attribute that is not text reads back as text. */
     TEXT_ROLE: "W_CSV_TEXT_ROLE",
     /** NaN / Infinity in a numeric column read back as text. */
     NONFINITE: "W_CSV_NONFINITE",
-    /** A text column whose every value reads back as a number or boolean. */
+    /**
+     * A text value that reads back as a number or a boolean, because the format does not record that it was text (the
+     * text "42" reads back as the number 42).
+     */
     TEXT_INFERRED: LOSS.TEXT_INFERRED,
-    /** A dict column whose cardinality makes the importer read it back as string, or the reverse. */
+    /**
+     * A text attribute reads back as a dictionary attribute, or the reverse, because the importer chooses by how often
+     * its values repeat. The values are the same.
+     */
     STORAGE_CLASS_CHANGED: LOSS.STORAGE_CLASS,
     /** Node attributes are written by a `table: "nodes"` export only. */
     NODE_TABLE: "W_CSV_NODE_TABLE",
-    /** The edge table carries no node without an edge: isolated nodes vanish on re-import. */
+    /**
+     * The edge table has no row for a node without edges, so isolated nodes are missing when the file is read back.
+     * Write the node table too (`table: "nodes"`).
+     */
     ISOLATED_NODES: "W_CSV_ISOLATED_NODES",
-    /** The edge table lists nodes by first appearance; the node order (and indices) change on re-import. */
+    /**
+     * The edge table lists nodes in the order they first appear in an edge, so the node order changes when the file is
+     * read back.
+     */
     NODE_ORDER: "W_CSV_NODE_ORDER",
     /** An adjacency table holds no edge column but the weight: edge ids, labels and attributes are not written. */
     EDGE_COLUMNS: "W_CSV_EDGE_COLUMNS",
+    /**
+     * `header: false` with columns a file without a header cannot name: graph-io reads such a file by position
+     * (source, target, weight, then columns it names column4, column5, ...), so these columns read back under other
+     * names or in the wrong place (for example, an edge id in the weight's place). Write the header, or write only source,
+     * target and weight with `dialect: "generic"`.
+     */
+    HEADERLESS: "W_CSV_HEADERLESS",
 });
 
-/** What the CSV format keeps as declared. */
+/**
+ * What the CSV format keeps as declared.
+ * @category Built-in formats
+ */
 export const CSV_CAPABILITIES: ExportCapabilities = capabilities({
     mixedDirection: true,
     multiEdges: true,
@@ -190,7 +244,12 @@ function resolveCsvExportOptions(
     options: (CsvExportOptions & CommonExportOptions) | undefined,
 ): ResolvedCsvExportOptions {
     const o: CsvExportOptions = options ?? {};
-    if (o.dialect !== undefined && o.dialect !== "gephi" && o.dialect !== "generic") {
+    if (
+        o.dialect !== undefined &&
+        o.dialect !== "gephi" &&
+        o.dialect !== "generic" &&
+        !otherFormatDialect("csv", o.dialect)
+    ) {
         throw new GraphFormatError("E_UNSUPPORTED", 'option dialect: expected "gephi" or "generic"', {
             option: "dialect",
             found: o.dialect,
@@ -235,7 +294,8 @@ function resolveCsvExportOptions(
         });
     }
     return {
-        dialect: DIALECTS[o.dialect ?? "gephi"],
+        // another format's dialect (a JSON "d3" in a shared options object) leaves CSV's default
+        dialect: DIALECTS[o.dialect === "generic" ? "generic" : "gephi"],
         table: o.table ?? "edges",
         delimiter: o.delimiter ?? ",",
         newline: o.newline ?? "\n",
@@ -321,6 +381,33 @@ function cellText(column: Column, row: number): string | null {
  * @param values - whether to scan the values for notes
  * @returns the plan
  */
+/**
+ * W_CSV_NODE_TABLE: the node columns an edge-table or adjacency export leaves for a second, node-table export.
+ * @param names - the node columns, label first
+ * @param table - the table being written ("edges" or "adjacency")
+ * @param note - the recorder
+ */
+function nodeTableNote(
+    names: readonly string[],
+    table: string,
+    note: (code: string, message: string, column?: string | null, count?: number | null) => void,
+): void {
+    const written = names.length;
+    if (written > 0) {
+        const shown =
+            names
+                .slice(0, 3)
+                .map((n) => JSON.stringify(n))
+                .join(", ") + (written > 3 ? ", ..." : "");
+        note(
+            CSV_LOSS.NODE_TABLE,
+            `the ${table === "adjacency" ? "adjacency" : "edge"} table has no room for node attributes: ${written} node column${plural(written)} (${shown}) ${agree(written, "is", "are")} written only by a second export with table: "nodes"`,
+            null,
+            written,
+        );
+    }
+}
+
 /**
  * The id notes: text collisions are fatal (export() throws E_INVALID_ID); type changes under the
  * canonical re-read are reported.
@@ -348,7 +435,7 @@ function idNotes(
         if (collisions > 0) {
             note(
                 CSV_LOSS.ID_TEXT_COLLISION,
-                `${collisions} node id(s) share their text with another id (a number and a string); export() will throw E_INVALID_ID`,
+                `${collisions} node id${plural(collisions)} ${agree(collisions, "shares", "share")} their text with another id (a number and a string); the save fails with E_INVALID_ID`,
                 null,
                 collisions,
             );
@@ -365,7 +452,7 @@ function idNotes(
         if (changed > 0) {
             note(
                 CSV_LOSS.ID_TEXT_TYPE,
-                `${changed} node id(s) read back as the other type under ids: "canonical" (a string "1" becomes 1, a number 1.5 becomes "1.5")`,
+                `${changed} node id${plural(changed)} ${agree(changed, "reads", "read")} back as the other type under ids: "canonical" (a string "1" becomes 1, a number 1.5 becomes "1.5")`,
                 null,
                 changed,
             );
@@ -402,14 +489,14 @@ function planExport(
         if (!snapshot.directed) {
             note(
                 CSV_LOSS.DIRECTION_DROPPED,
-                `${where} has no direction column; ${snapshot.edgeCount} undirected edge(s) read back as directed unless the importer is told otherwise`,
+                `${where} has no direction column; ${snapshot.edgeCount} undirected edge${plural(snapshot.edgeCount)} ${agree(snapshot.edgeCount, "reads", "read")} back as directed unless the importer is told otherwise`,
                 null,
                 snapshot.edgeCount,
             );
         } else if (mixed > 0) {
             note(
                 CSV_LOSS.DIRECTION_DROPPED,
-                `${where} has no direction column; ${mixed} undirected edge(s) of a mixed graph read back as one directed edge each`,
+                `${where} has no direction column; ${mixed} undirected edge${plural(mixed)} of a mixed graph read back as one directed edge each`,
                 null,
                 mixed,
             );
@@ -425,7 +512,7 @@ function planExport(
     if (folding.mutualCount > 0) {
         note(
             CSV_LOSS.MUTUAL_EXPANDED,
-            `${folding.mutualCount} mutual pair(s) are written as two directed rows; the mutual mark is lost`,
+            `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed rows; the mutual mark is lost`,
             null,
             folding.mutualCount,
         );
@@ -457,7 +544,7 @@ function planExport(
         if (dropped > 0) {
             note(
                 CSV_LOSS.EDGE_COLUMNS,
-                `${dropped} edge column(s) are not written: an adjacency table holds the weight only`,
+                `${dropped} edge column${plural(dropped)} ${agree(dropped, "is", "are")} not written: an adjacency table holds the weight only`,
                 null,
                 dropped,
             );
@@ -496,15 +583,11 @@ function planExport(
             }
         }
     } else {
-        const written = nodeColumns.length + (nodeLabel === null ? 0 : 1);
-        if (written > 0) {
-            note(
-                CSV_LOSS.NODE_TABLE,
-                `${written} node column(s) are written by a table: "nodes" export only`,
-                null,
-                written,
-            );
-        }
+        nodeTableNote(
+            [...(nodeLabel === null ? [] : [nodeLabel.meta.name]), ...nodeColumns.map((c) => c.column.meta.name)],
+            csv.table,
+            note,
+        );
     }
 
     return {
@@ -563,7 +646,7 @@ function noteNodeCoverage(
     if (isolated > 0) {
         note(
             CSV_LOSS.ISOLATED_NODES,
-            `${isolated} node(s) have no edge and cannot be written by the edge table; write the node table (table: "nodes") to keep them`,
+            `${isolated} node${plural(isolated)} ${agree(isolated, "has", "have")} no edge and cannot be written by the edge table; write the node table (table: "nodes") to keep them`,
             null,
             isolated,
         );
@@ -571,7 +654,7 @@ function noteNodeCoverage(
     if (reordered > 0) {
         note(
             CSV_LOSS.NODE_ORDER,
-            `${reordered} node(s) are first mentioned by an edge row out of index order; a re-import numbers nodes by first appearance`,
+            `${reordered} node${plural(reordered)} ${agree(reordered, "is", "are")} first mentioned by an edge row out of index order; a re-import numbers nodes by first appearance`,
             null,
             reordered,
         );
@@ -746,7 +829,12 @@ function checkValues(
             }
         }
         if (nonFinite > 0) {
-            note(CSV_LOSS.NONFINITE, `${label}: ${nonFinite} non-finite value(s) read back as text`, name, nonFinite);
+            note(
+                CSV_LOSS.NONFINITE,
+                `${label}: ${nonFinite} non-finite value${plural(nonFinite)} ${agree(nonFinite, "reads", "read")} back as text`,
+                name,
+                nonFinite,
+            );
         }
         return;
     }
@@ -810,10 +898,10 @@ function typeText(snapshot: GraphSnapshot, plan: Plan, e: number): string {
 }
 
 /**
- * A neighbour cell of the adjacency table: `id:weight` for an explicit weight; `id:` for an id
+ * A neighbor cell of the adjacency table: `id:weight` for an explicit weight; `id:` for an id
  * holding a colon without one, so the importer does not read the id's tail as a weight; `id`
  * otherwise.
- * @param id - the neighbour's id text
+ * @param id - the neighbor's id text
  * @param weight - the weight text, or null
  * @returns the cell text (unquoted)
  */
@@ -1006,6 +1094,68 @@ function prepare(snapshot: GraphSnapshot, options: (CsvExportOptions & CommonExp
     return plan;
 }
 
+/**
+ * The note of a table written without its header: a headerless file is read by position (source, target, weight,
+ * then unnamed columns; a node table: id, then unnamed columns), so any other column reads back elsewhere or unnamed.
+ * @param plan - the export plan
+ * @returns the note, or nothing when the header is written or the positions match
+ */
+function headerlessNotes(plan: Plan): LossNote[] {
+    const { csv } = plan;
+    if (csv.header || csv.table === "adjacency") {
+        return [];
+    }
+    const names = csv.table === "nodes" ? headerlessNodeColumns(plan) : headerlessEdgeColumns(plan);
+    if (names.length === 0) {
+        return [];
+    }
+    const shown = names.map((n) => JSON.stringify(n)).join(", ");
+    return [
+        Object.freeze({
+            code: CSV_LOSS.HEADERLESS,
+            message: `without a header the file is read back by position (${csv.table === "nodes" ? "id" : "source, target, weight"}, then unnamed columns), so ${names.length === 1 ? "the column" : "the columns"} ${shown} ${agree(names.length, "reads", "read")} back unnamed or in another column's place; write the header, or for an edge list pass dialect: "generic" and write only source, target and weight`,
+            column: null,
+            count: names.length,
+        }),
+    ];
+}
+
+/**
+ * The node columns a headerless node table does not read back by position: every one after the id.
+ * @param plan - the export plan
+ * @returns their names
+ */
+function headerlessNodeColumns(plan: Plan): string[] {
+    const label = plan.nodeLabel === null ? [] : [plan.nodeLabel.meta.name];
+    return [...label, ...plan.nodeColumns.map((c) => c.header)];
+}
+
+/**
+ * The edge columns a headerless edge list does not read back by position: every one after the
+ * endpoints and the weight, and the weight when another column comes before it.
+ * @param plan - the export plan
+ * @returns their names
+ */
+function headerlessEdgeColumns(plan: Plan): string[] {
+    const { dialect } = plan.csv;
+    const names: string[] = [];
+    if (dialect.type !== null) {
+        names.push(dialect.type);
+    }
+    if (plan.edgeId !== null) {
+        names.push(plan.edgeId.meta.name);
+    }
+    if (plan.edgeLabel !== null) {
+        names.push(plan.edgeLabel.meta.name);
+    }
+    // a weight right after the target is where a headerless read expects it
+    if (plan.weights.weighted && names.length > 0) {
+        names.push(dialect.weight);
+    }
+    names.push(...plan.edgeColumns.map((c) => c.header));
+    return names;
+}
+
 /**
  * Pre-flight: what a CSV export would lose. The generic notes describe the snapshot as a whole
  * against the format; the CSV notes concern the table selected by `table`.
@@ -1018,12 +1168,17 @@ function check(snapshot: GraphSnapshot, options?: CsvExportOptions & CommonExpor
     return Object.freeze([
         ...checkCapabilities(snapshot, CSV_CAPABILITIES, plan.common, { roles: KEPT_ROLES }),
         ...plan.notes,
+        ...headerlessNotes(plan),
     ]);
 }
 
-/** The CSV / TSV exporter plugin (subpath `@graphty/graph-io/csv`). */
+/**
+ * The CSV / TSV exporter plugin (subpath `@graphty/graph-io/csv`).
+ * @category Built-in formats
+ */
 export const csvExporter: GraphExporter<CsvExportOptions> = Object.freeze({
     format: "csv",
+    options: Object.freeze(["delimiter", "dialect", "header", "newline", "table"]),
     capabilities: CSV_CAPABILITIES,
     check,
     export(snapshot: GraphSnapshot, options?: CsvExportOptions & CommonExportOptions): AsyncIterable<Uint8Array> {

package/src/formats/csv/header.ts

@@ -1,7 +1,7 @@
 /**
  * Header handling of the CSV importer: whether the first row is a header, which columns hold the
  * endpoints, the weight, the Gephi per-row `Type`, the edge id and the label (by name lists and
- * by position), and the synthesised names of a headerless file (`column1`, `column2`, ...).
+ * by position), and the synthesized names of a headerless file (`column1`, `column2`, ...).
  *
  * Name resolution is exact first, then case-insensitive, over a candidate list in priority order,
  * so `source` / `Source` / `SOURCE`, `src`, `from` all resolve without configuration; the Gephi
@@ -11,12 +11,19 @@
 
 import { GraphFormatError } from "@graphty/graph-format";
 
+import { plural } from "../../common/plural.js";
 import { inferTextDtype } from "../../common/text.js";
 
-/** A column named by header text or by 0-based position. */
+/**
+ * A column named by header text or by 0-based position.
+ * @category Built-in formats
+ */
 export type CsvColumnRef = string | number;
 
-/** Header candidates of the source endpoint, in priority order (matched exactly, then case-insensitively). */
+/**
+ * Header candidates of the source endpoint, in priority order (matched exactly, then case-insensitively).
+ * @category Plugin helpers
+ */
 export const SOURCE_NAMES: readonly string[] = Object.freeze([
     "source",
     "src",
@@ -29,7 +36,10 @@ export const SOURCE_NAMES: readonly string[] = Object.freeze([
     ":start_id",
 ]);
 
-/** Header candidates of the target endpoint. */
+/**
+ * Header candidates of the target endpoint.
+ * @category Plugin helpers
+ */
 export const TARGET_NAMES: readonly string[] = Object.freeze([
     "target",
     "dst",
@@ -43,16 +53,28 @@ export const TARGET_NAMES: readonly string[] = Object.freeze([
     ":end_id",
 ]);
 
-/** Header candidates of a node table's id column. */
+/**
+ * Header candidates of a node table's id column.
+ * @category Plugin helpers
+ */
 export const ID_NAMES: readonly string[] = Object.freeze(["id", "node", "name", "key"]);
 
-/** Header candidates of a label column (node or edge). */
+/**
+ * Header candidates of a label column (node or edge).
+ * @category Plugin helpers
+ */
 export const LABEL_NAMES: readonly string[] = Object.freeze(["label"]);
 
-/** Header candidates of an edge id column. */
+/**
+ * Header candidates of an edge id column.
+ * @category Plugin helpers
+ */
 export const EDGE_ID_NAMES: readonly string[] = Object.freeze(["id"]);
 
-/** The Gephi per-row direction column. */
+/**
+ * The Gephi per-row direction column.
+ * @category Plugin helpers
+ */
 export const TYPE_NAME = "Type";
 
 /** Every name that marks a first row as a header when the caller leaves detection to the importer. */
@@ -72,6 +94,7 @@ const HEADER_MARKERS: ReadonlySet<string> = new Set([
  * @param names - the header names
  * @param candidates - the names to look for, in priority order
  * @returns the column index, or -1
+ * @category Plugin helpers
  */
 export function findColumn(names: readonly string[], candidates: readonly string[]): number {
     for (const candidate of candidates) {
@@ -96,13 +119,14 @@ export function findColumn(names: readonly string[], candidates: readonly string
  * @param ref - the option value
  * @param option - the option name, for the error
  * @returns the column index
+ * @category Plugin helpers
  */
 export function resolveColumnRef(names: readonly string[], ref: CsvColumnRef, option: string): number {
     if (typeof ref === "number") {
         if (!Number.isInteger(ref) || ref < 0 || ref >= names.length) {
             throw new GraphFormatError(
                 "E_UNSUPPORTED",
-                `option ${option}: column ${ref} does not exist (the file has ${names.length} column(s))`,
+                `option ${option}: column ${ref} does not exist (the file has ${names.length} column${plural(names.length)})`,
                 { option, found: ref, columns: names.length },
             );
         }
@@ -124,21 +148,34 @@ export function resolveColumnRef(names: readonly string[], ref: CsvColumnRef, op
  * is when any cell is a known column name (source, target, id, label, weight, type...), or when
  * every cell is non-numeric text while the second row has a numeric cell (`u,v` over `1,2`);
  * a first row with a numeric cell is data, and so is one that looks exactly like the rows below it.
+ * A two-column row holding a known name is still data when its second cell is the second row's
+ * first cell and it does not name both endpoints: a header names columns, while an edge list whose
+ * ids happen to be such words (`key,lock` over `lock,door`) chains its ids from row to row.
  * @param first - the first row
  * @param second - the second row, or null when the file has one row
  * @returns true when the first row is a header
+ * @category Plugin helpers
  */
 export function looksLikeHeader(first: readonly string[], second: readonly string[] | null): boolean {
     let allText = true;
+    let marker = false;
     for (const cell of first) {
         const text = cell.trim();
         if (HEADER_MARKERS.has(text.toLowerCase())) {
-            return true;
+            marker = true;
         }
         if (text.length === 0 || inferTextDtype(text) !== "string") {
             allText = false;
         }
     }
+    if (marker) {
+        const names = headerNames(first);
+        if (second === null || (findColumn(names, SOURCE_NAMES) >= 0 && findColumn(names, TARGET_NAMES) >= 0)) {
+            return true;
+        }
+        const chained = first.length === 2 && second.length >= 1 && first[1].trim() === second[0].trim();
+        return !chained || first[1].trim().length === 0;
+    }
     if (!allText || second === null) {
         return false;
     }
@@ -146,9 +183,10 @@ export function looksLikeHeader(first: readonly string[], second: readonly strin
 }
 
 /**
- * The synthesised header of a headerless file: `column1` ... `columnN`.
+ * The synthesized header of a headerless file: `column1` ... `columnN`.
  * @param width - the number of cells of the first row
  * @returns the names
+ * @category Plugin helpers
  */
 export function positionalNames(width: number): string[] {
     const names: string[] = [];
@@ -163,6 +201,7 @@ export function positionalNames(width: number): string[] {
  * empty cell named by its position so every column has a name.
  * @param cells - the header row
  * @returns the names
+ * @category Plugin helpers
  */
 export function headerNames(cells: readonly string[]): string[] {
     return cells.map((cell, i) => {