@graphty/graph-io 0.3.28 → 0.3.29

package/src/common/export.ts

@@ -318,6 +318,12 @@ export interface CheckExtras {
      * W_WEIGHTS_DROPPED note. Default true.
      */
     readonly weights?: boolean | undefined;
+    /**
+     * The tables the export writes, of "node", "edge" and "graph"; a gap in a table it does not
+     * write is not a loss of this export and gets no note. Default all three. A CSV node table is
+     * `["node"]`, so its notes are about node ids and node columns only.
+     */
+    readonly tables?: readonly ("node" | "edge" | "graph")[] | undefined;
     /**
      * How the format's importer turns id text back into ids ("canonical" for most text formats), so
      * an id that comes back with another type (the text "7" as the number 7) is reported as
@@ -353,60 +359,11 @@ export function checkCapabilities(
     const note = (code: string, message: string, column: string | null = null, count: number | null = null): void => {
         notes.push(Object.freeze({ code, message, column, count }));
     };
+    const tables = extras.tables ?? ["node", "edge", "graph"];
+    const edges = tables.includes("edge");
 
-    // mixed direction (design section 3.6): an expanded snapshot carries the pair / directed roles
-    const mixed = countMixedEdges(snapshot);
-    if (mixed > 0 && !caps.mixedDirection) {
-        if (options.onMixedDirection === "error") {
-            note(
-                LOSS.MIXED_DIRECTION_ERROR,
-                `${mixed} undirected edge${plural(mixed)} in a directed graph, and the format holds one direction per file, so the save fails unless onMixedDirection is "directed" or "undirected"`,
-                null,
-                mixed,
-            );
-        } else {
-            note(
-                LOSS.MIXED_DIRECTION,
-                `${mixed} undirected edge${plural(mixed)} in a directed graph ${agree(mixed, "is", "are")} written as ${options.onMixedDirection} (onMixedDirection), and the format holds one direction per file`,
-                null,
-                mixed,
-            );
-        }
-    }
-
-    if (snapshot.flags.multigraph && !caps.multiEdges) {
-        const parallel = countParallelArcs(snapshot);
-        note(
-            LOSS.MULTI_EDGES,
-            `${parallel} parallel edge${plural(parallel)}; the format has no parallel edges`,
-            null,
-            parallel,
-        );
-    }
-    if (snapshot.selfLoopCount > 0 && !caps.selfLoops) {
-        note(
-            LOSS.SELF_LOOPS,
-            `${snapshot.selfLoopCount} self-loop${plural(snapshot.selfLoopCount)}; the format has no self-loops`,
-            null,
-            snapshot.selfLoopCount,
-        );
-    }
-
-    const edgeIds = snapshot.edges.byRole("id");
-    if (caps.edgeIds === "required" && edgeIds === null && snapshot.edgeCount > 0) {
-        note(
-            LOSS.EDGE_IDS_GENERATED,
-            "the format requires edge ids, and the graph has none; the edges are written with generated ids, which read back as a new edge id column",
-            null,
-            snapshot.edgeCount,
-        );
-    } else if (caps.edgeIds === "none" && edgeIds !== null) {
-        note(
-            LOSS.EDGE_IDS_DROPPED,
-            `edge id column "${edgeIds.meta.name}" cannot be written`,
-            edgeIds.meta.name,
-            snapshot.edgeCount,
-        );
+    if (edges) {
+        checkEdgeStructure(snapshot, caps, options, note);
     }
 
     const unrepresentable = countUnrepresentableIds(snapshot, caps.idCharset);
@@ -455,24 +412,40 @@ export function checkCapabilities(
         }
     }
 
-    checkWeights(snapshot, extras, note);
-    checkColumns(snapshot.nodes, "node", caps, extras, note);
-    checkColumns(snapshot.edges, "edge", caps, extras, note);
-    const graphColumns = snapshot.graph.names();
+    if (edges) {
+        checkWeights(snapshot, extras, note);
+    }
+    if (tables.includes("node")) {
+        checkColumns(snapshot.nodes, "node", caps, extras, note);
+    }
+    if (edges) {
+        checkColumns(snapshot.edges, "edge", caps, extras, note);
+    }
+    const graphColumns = tables.includes("graph") ? snapshot.graph.names() : [];
     if (graphColumns.length > 0) {
         if (caps.graphAttributes) {
             checkColumns(snapshot.graph, "graph", caps, extras, note);
         } else {
-            note(
-                LOSS.GRAPH_ATTRIBUTES,
-                `${graphColumns.length} graph attribute${plural(graphColumns.length)} cannot be written`,
-                null,
-                graphColumns.length,
+            notes.push(
+                Object.freeze({
+                    code: LOSS.GRAPH_ATTRIBUTES,
+                    message: `${graphColumns.length} graph attribute${plural(graphColumns.length)} cannot be written`,
+                    column: null,
+                    count: graphColumns.length,
+                    columns: Object.freeze([...graphColumns]),
+                }),
             );
         }
     }
 
     for (const [name, table] of snapshot.extensions) {
+        // "temporal:node:<column>" is the node table's, "temporal:edge:<column>" the edge table's;
+        // any other extension table is the graph's.
+        const [, kind] = name.split(":");
+        const owner = name.startsWith("temporal:") && (kind === "node" || kind === "edge") ? kind : "graph";
+        if (!tables.includes(owner)) {
+            continue;
+        }
         if (name.startsWith("temporal:")) {
             if (caps.temporal !== "dynamic-values") {
                 note(
@@ -494,6 +467,76 @@ export function checkCapabilities(
     return notes;
 }
 
+/**
+ * The edge-structure checks of checkCapabilities(): direction, parallel edges, self-loops and
+ * edge ids. Skipped for an export that writes no edge table.
+ * @param snapshot - the snapshot about to be exported
+ * @param caps - the exporter's capabilities
+ * @param options - the resolved common export options
+ * @param note - the recorder
+ */
+function checkEdgeStructure(
+    snapshot: GraphSnapshot,
+    caps: ExportCapabilities,
+    options: ResolvedExportOptions,
+    note: NoteFn,
+): void {
+    // mixed direction (design section 3.6): an expanded snapshot carries the pair / directed roles
+    const mixed = countMixedEdges(snapshot);
+    if (mixed > 0 && !caps.mixedDirection) {
+        if (options.onMixedDirection === "error") {
+            note(
+                LOSS.MIXED_DIRECTION_ERROR,
+                `${mixed} undirected edge${plural(mixed)} in a directed graph, and the format holds one direction per file, so the save fails unless onMixedDirection is "directed" or "undirected"`,
+                null,
+                mixed,
+            );
+        } else {
+            note(
+                LOSS.MIXED_DIRECTION,
+                `${mixed} undirected edge${plural(mixed)} in a directed graph ${agree(mixed, "is", "are")} written as ${options.onMixedDirection} (onMixedDirection), and the format holds one direction per file`,
+                null,
+                mixed,
+            );
+        }
+    }
+
+    if (snapshot.flags.multigraph && !caps.multiEdges) {
+        const parallel = countParallelArcs(snapshot);
+        note(
+            LOSS.MULTI_EDGES,
+            `${parallel} parallel edge${plural(parallel)}; the format has no parallel edges`,
+            null,
+            parallel,
+        );
+    }
+    if (snapshot.selfLoopCount > 0 && !caps.selfLoops) {
+        note(
+            LOSS.SELF_LOOPS,
+            `${snapshot.selfLoopCount} self-loop${plural(snapshot.selfLoopCount)}; the format has no self-loops`,
+            null,
+            snapshot.selfLoopCount,
+        );
+    }
+
+    const edgeIds = snapshot.edges.byRole("id");
+    if (caps.edgeIds === "required" && edgeIds === null && snapshot.edgeCount > 0) {
+        note(
+            LOSS.EDGE_IDS_GENERATED,
+            "the format requires edge ids, and the graph has none; the edges are written with generated ids, which read back as a new edge id column",
+            null,
+            snapshot.edgeCount,
+        );
+    } else if (caps.edgeIds === "none" && edgeIds !== null) {
+        note(
+            LOSS.EDGE_IDS_DROPPED,
+            `edge id column "${edgeIds.meta.name}" cannot be written`,
+            edgeIds.meta.name,
+            snapshot.edgeCount,
+        );
+    }
+}
+
 /**
  * The ids a charset cannot hold, as a message phrase.
  * @param charset - the format's id charset

package/src/formats/csv/exporter.ts

@@ -385,13 +385,9 @@ function cellText(column: Column, row: number): string | null {
  * 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
+ * @param notes - receives the note
  */
-function nodeTableNote(
-    names: readonly string[],
-    table: string,
-    note: (code: string, message: string, column?: string | null, count?: number | null) => void,
-): void {
+function nodeTableNote(names: readonly string[], table: string, notes: LossNote[]): void {
     const written = names.length;
     if (written > 0) {
         const shown =
@@ -399,11 +395,14 @@ function nodeTableNote(
                 .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,
+        notes.push(
+            Object.freeze({
+                code: CSV_LOSS.NODE_TABLE,
+                message: `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"`,
+                column: null,
+                count: written,
+                columns: Object.freeze([...names]),
+            }),
         );
     }
 }
@@ -483,7 +482,8 @@ function planExport(
             edgeRows.push(e);
         }
     }
-    if (csv.dialect.type === null || csv.table === "adjacency") {
+    // A node table holds no edge: the direction and mutual notes are the edge table's.
+    if (csv.table !== "nodes" && (csv.dialect.type === null || csv.table === "adjacency")) {
         const where = csv.table === "adjacency" ? "an adjacency table" : "the generic dialect";
         const mixed = countMixedEdges(snapshot);
         if (!snapshot.directed) {
@@ -509,7 +509,7 @@ function planExport(
             0,
         );
     }
-    if (folding.mutualCount > 0) {
+    if (folding.mutualCount > 0 && csv.table !== "nodes") {
         note(
             CSV_LOSS.MUTUAL_EXPANDED,
             `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed rows; the mutual mark is lost`,
@@ -586,7 +586,7 @@ function planExport(
         nodeTableNote(
             [...(nodeLabel === null ? [] : [nodeLabel.meta.name]), ...nodeColumns.map((c) => c.column.meta.name)],
             csv.table,
-            note,
+            notes,
         );
     }
 
@@ -1116,6 +1116,7 @@ function headerlessNotes(plan: Plan): LossNote[] {
             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,
+            columns: Object.freeze([...names]),
         }),
     ];
 }
@@ -1166,7 +1167,10 @@ function headerlessEdgeColumns(plan: Plan): string[] {
 function check(snapshot: GraphSnapshot, options?: CsvExportOptions & CommonExportOptions): readonly LossNote[] {
     const plan = planExport(snapshot, options, true);
     return Object.freeze([
-        ...checkCapabilities(snapshot, CSV_CAPABILITIES, plan.common, { roles: KEPT_ROLES }),
+        ...checkCapabilities(snapshot, CSV_CAPABILITIES, plan.common, {
+            roles: KEPT_ROLES,
+            ...(plan.csv.table === "nodes" ? { tables: ["node"] as const } : {}),
+        }),
         ...plan.notes,
         ...headerlessNotes(plan),
     ]);

package/src/formats/obo/syntax.ts

@@ -6,6 +6,10 @@
  *
  * Every function works on the RAW text (escapes still in place) and unescapes only the pieces it
  * hands back, so an escaped quote, colon, comma, brace or `!` never ends a construct.
+ *
+ * The scanners read characters with charAt(), never `text[i]`: the importer's linear-time tests
+ * count the characters the import reads through the string methods, and an index read is
+ * invisible to them, so a quadratic scan written with it would pass unnoticed.
  */
 
 /** The OBO escapes with a meaning of their own; any other `\x` is `x` (the guides). */
@@ -29,14 +33,14 @@ export function unescapeObo(text: string): string {
     }
     let out = "";
     for (let i = 0; i < text.length; i++) {
-        const ch = text[i];
+        const ch = text.charAt(i);
         if (ch !== "\\") {
             out += ch;
             continue;
         }
         i++;
         if (i < text.length) {
-            const next = text[i];
+            const next = text.charAt(i);
             out += ESCAPES[next] ?? next;
         }
     }
@@ -51,7 +55,7 @@ export function unescapeObo(text: string): string {
  */
 function isEscaped(text: string, index: number): boolean {
     let run = 0;
-    for (let i = index - 1; i >= 0 && text[i] === "\\"; i--) {
+    for (let i = index - 1; i >= 0 && text.charAt(i) === "\\"; i--) {
         run++;
     }
     return run % 2 === 1;
@@ -71,8 +75,8 @@ export function splitFormFeeds(line: string): string[] {
     const pieces: string[] = [];
     let quoted = false;
     let start = 0;
-    for (let i = 0; i < line.length; i += line[i] === "\\" ? 2 : 1) {
-        const ch = line[i];
+    for (let i = 0; i < line.length; i += line.charAt(i) === "\\" ? 2 : 1) {
+        const ch = line.charAt(i);
         if (ch === '"') {
             quoted = !quoted;
         } else if (ch === "\f" && !quoted) {
@@ -110,11 +114,11 @@ interface TagValue {
  */
 export function splitTagValue(line: string): TagValue | null {
     for (let i = 0; i < line.length; i++) {
-        if (line[i] === "\\") {
+        if (line.charAt(i) === "\\") {
             i++;
             continue;
         }
-        if (line[i] === ":") {
+        if (line.charAt(i) === ":") {
             return { tag: unescapeObo(line.slice(0, i).trim()), rest: line.slice(i + 1).trimStart() };
         }
     }
@@ -134,12 +138,12 @@ export function splitTagValue(line: string): TagValue | null {
 export function stripComment(rest: string): string {
     let quoted = false;
     for (let i = 0; i < rest.length; i++) {
-        const ch = rest[i];
+        const ch = rest.charAt(i);
         if (ch === "\\") {
             i++;
             continue;
         }
-        const atStart = i === 0 || rest[i - 1] === " " || rest[i - 1] === "\t";
+        const atStart = i === 0 || rest.charAt(i - 1) === " " || rest.charAt(i - 1) === "\t";
         if (ch === '"' && (quoted || atStart)) {
             quoted = !quoted;
         } else if (ch === "!" && !quoted && atStart) {
@@ -183,7 +187,7 @@ export function splitQualifiers(value: string): QualifiedValue {
     const parsed: Qualifiers[] = [];
     let end = value.length;
     let badBlock: string | null = null;
-    while (end > 0 && value[end - 1] === "}" && !isEscaped(value, end - 1)) {
+    while (end > 0 && value.charAt(end - 1) === "}" && !isEscaped(value, end - 1)) {
         const open = blocks.get(end - 1) ?? -1;
         const block = open < 0 ? null : parseQualifiers(value.slice(open + 1, end - 1));
         if (block === null) {
@@ -192,7 +196,7 @@ export function splitQualifiers(value: string): QualifiedValue {
         }
         parsed.push(block);
         end = open;
-        while (end > 0 && /\s/.test(value[end - 1])) {
+        while (end > 0 && /\s/.test(value.charAt(end - 1))) {
             end--;
         }
     }
@@ -217,7 +221,7 @@ function braceBlocks(value: string): Map<number, number> {
     let quoted = false;
     let open = -1;
     for (let i = 0; i < value.length; i++) {
-        const ch = value[i];
+        const ch = value.charAt(i);
         if (ch === "\\") {
             i++;
             continue;
@@ -244,8 +248,8 @@ function braceBlocks(value: string): Map<number, number> {
 export function unclosedBlock(value: string): number {
     let quoted = false;
     let open = -1;
-    for (let i = 0; i < value.length; i += value[i] === "\\" ? 2 : 1) {
-        const ch = value[i];
+    for (let i = 0; i < value.length; i += value.charAt(i) === "\\" ? 2 : 1) {
+        const ch = value.charAt(i);
         if (ch === "\\") {
             continue;
         }
@@ -297,7 +301,7 @@ export function parseQualifiers(inner: string): Qualifiers | null {
     const n = inner.length;
     let any = false;
     while (i < n) {
-        while (i < n && (inner[i] === " " || inner[i] === "\t" || inner[i] === ",")) {
+        while (i < n && (inner.charAt(i) === " " || inner.charAt(i) === "\t" || inner.charAt(i) === ",")) {
             i++;
         }
         if (i >= n) {
@@ -312,11 +316,11 @@ export function parseQualifiers(inner: string): Qualifiers | null {
             return null;
         }
         i = eq + 1;
-        while (i < n && (inner[i] === " " || inner[i] === "\t")) {
+        while (i < n && (inner.charAt(i) === " " || inner.charAt(i) === "\t")) {
             i++;
         }
         let value: string;
-        if (inner[i] === '"') {
+        if (inner.charAt(i) === '"') {
             const end = closingQuote(inner, i + 1);
             if (end < 0) {
                 return null;
@@ -325,8 +329,8 @@ export function parseQualifiers(inner: string): Qualifiers | null {
             i = end + 1;
         } else {
             let end = i;
-            while (end < n && inner[end] !== ",") {
-                end += inner[end] === "\\" ? 2 : 1;
+            while (end < n && inner.charAt(end) !== ",") {
+                end += inner.charAt(end) === "\\" ? 2 : 1;
             }
             value = unescapeObo(inner.slice(i, end).trim());
             i = end;
@@ -345,9 +349,9 @@ export function parseQualifiers(inner: string): Qualifiers | null {
  */
 function closingQuote(text: string, from: number): number {
     for (let i = from; i < text.length; i++) {
-        if (text[i] === "\\") {
+        if (text.charAt(i) === "\\") {
             i++;
-        } else if (text[i] === '"') {
+        } else if (text.charAt(i) === '"') {
             return i;
         }
     }
@@ -379,7 +383,7 @@ export function tokenize(value: string): Token[] {
     const n = value.length;
     let i = 0;
     while (i < n) {
-        const ch = value[i];
+        const ch = value.charAt(i);
         if (ch === " " || ch === "\t") {
             i++;
             continue;
@@ -390,8 +394,8 @@ export function tokenize(value: string): Token[] {
             // a 1.4 language tag glued to the closing quote ("chat"@fr) is kept with the text, as an
             // unquoted chat@fr is (research-obo.md 4.1: no language is split out)
             let after = stop + 1;
-            if (end >= 0 && value[after] === "@") {
-                while (after < n && value[after] !== " " && value[after] !== "\t") {
+            if (end >= 0 && value.charAt(after) === "@") {
+                while (after < n && value.charAt(after) !== " " && value.charAt(after) !== "\t") {
                     after++;
                 }
             }
@@ -412,8 +416,8 @@ export function tokenize(value: string): Token[] {
             continue;
         }
         let end = i;
-        while (end < n && value[end] !== " " && value[end] !== "\t") {
-            end += value[end] === "\\" ? 2 : 1;
+        while (end < n && value.charAt(end) !== " " && value.charAt(end) !== "\t") {
+            end += value.charAt(end) === "\\" ? 2 : 1;
         }
         tokens.push({ kind: "word", text: unescapeObo(value.slice(i, Math.min(end, n))), unterminated: false });
         i = end;
@@ -430,7 +434,7 @@ export function tokenize(value: string): Token[] {
 function closingBracket(text: string, from: number): number {
     let quoted = false;
     for (let i = from; i < text.length; i++) {
-        const ch = text[i];
+        const ch = text.charAt(i);
         if (ch === "\\") {
             i++;
         } else if (ch === '"') {
@@ -468,9 +472,9 @@ export function parseXref(raw: string): Xref | null {
     const { value, qualifiers } = splitQualifiers(raw.trim());
     let quote = -1;
     for (let i = 0; i < value.length; i++) {
-        if (value[i] === "\\") {
+        if (value.charAt(i) === "\\") {
             i++;
-        } else if (value[i] === '"') {
+        } else if (value.charAt(i) === '"') {
             quote = i;
             break;
         }
@@ -508,7 +512,7 @@ export function parseXrefList(inner: string): Xref[] {
         }
     };
     for (let i = 0; i < inner.length; i++) {
-        const ch = inner[i];
+        const ch = inner.charAt(i);
         if (ch === "\\") {
             i++;
         } else if (ch === '"') {
@@ -538,7 +542,7 @@ export function hasStrayBrace(value: string): boolean {
     let quoted = false;
     let listed = false;
     for (let i = 0; i < value.length; i++) {
-        const ch = value[i];
+        const ch = value.charAt(i);
         if (ch === "\\") {
             i++;
         } else if (ch === '"') {

package/src/types.ts

@@ -368,6 +368,12 @@ export interface LossNote {
     readonly column: string | null;
     /** How many nodes, edges or values are affected, or null when not counted. */
     readonly count: number | null;
+    /**
+     * Every column the note is about, when it is about several and `column` is null: the graph
+     * attributes a format has no place for, or the node columns a CSV edge table leaves for the node
+     * table. Absent on a note about one column or none.
+     */
+    readonly columns?: readonly string[];
 }
 
 /**