@graphty/graph-io 0.3.24 → 0.3.26

package/src/common/direction.ts

@@ -36,15 +36,15 @@ import { type ImportReportBuilder } from "./report.js";
 
 /**
  * The direction of one source edge.
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export type EdgeKind = "directed" | "undirected" | "mutual";
 
 /**
  * Where an edge or header was read, for issues.
- * Consumed by the per-format importers and exporters under src/formats.
  * @public
+ * @category Plugin helpers
  */
 export interface EdgeLocation {
     /** The 1-based line, when known. */
@@ -53,13 +53,24 @@ export interface EdgeLocation {
     readonly element?: string | null | undefined;
 }
 
-/** The name of the bool edge column marking source-directed edges (design section 3.6). */
+/**
+ * The name of the bool edge column that, in a graph with both directed and undirected edges, says
+ * which edges were directed in the file (true) and which were undirected (false).
+ * @category Plugin helpers
+ */
 export const DIRECTED_COLUMN = "graphty.directed";
 
-/** The name of the u32 edge column pairing the halves of an expanded edge (design section 3.6). */
+/**
+ * The name of the edge column that links the two edges an undirected edge is stored as, in a graph
+ * with both directed and undirected edges: each holds the index of the other.
+ * @category Plugin helpers
+ */
 export const PAIR_COLUMN = "graphty.pair";
 
-/** The name of the bool edge column marking GEXF mutual edges (design section 3.6). */
+/**
+ * The name of the bool edge column that marks a GEXF `mutual` edge.
+ * @category Plugin helpers
+ */
 export const MUTUAL_COLUMN = "graphty.mutual";
 
 export { DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, MIXED_DIRECTION_CODE };
@@ -69,8 +80,11 @@ const PAIR_DECL: ColumnDecl = { name: PAIR_COLUMN, dtype: "u32", role: "pair", r
 const MUTUAL_DECL: ColumnDecl = { name: MUTUAL_COLUMN, dtype: "bool", role: "mutual" };
 
 /**
- * Pushes edges into a sink while resolving direction per design section 8.4. One instance per
- * import call; `setHeader()` before the first `addEdge()`.
+ * Adds edges to the sink and handles files whose edges have different directions, the way
+ * `onMixedDirection` asks. Make one per import call, call `setHeader()` once with the direction the
+ * file declares, then `addEdge()` for each edge. In a directed graph an undirected edge is stored as
+ * two edges, one each way, linked so an exporter writes them back as one.
+ * @category Writing a format
  */
 export class DirectionResolver {
     private readonly sink: GraphSink;
@@ -118,20 +132,19 @@ export class DirectionResolver {
     }
 
     /**
-     * Whether the reserved direction columns exist (the sink holds expanded edges).
-     * @returns true once graphty.pair was declared or adopted
+     * Whether the graph holds undirected edges stored as two edges.
+     * @returns true once the first such edge was added
      */
     get expanded(): boolean {
         return this.pairHandle !== INVALID_INDEX;
     }
 
     /**
-     * Rule 1 of design section 8.4: set the sink's direction from the file's header (or the
-     * `defaultDirected` option for a file that declares none) before the first edge. Under the
-     * "directed" / "undirected" policies the policy's direction is used instead and the difference
-     * is reported. A refusal (E_DIRECTED: locked, or a non-empty directed sink for an undirected
-     * header) is recorded as a coercion issue and the sink's direction stands; a non-empty unlocked
-     * undirected sink with a directed header is expanded in place.
+     * Set the graph's direction before the first edge: the direction the file declares, or the
+     * `defaultDirected` option for a file that declares none. Under `onMixedDirection` "directed" or
+     * "undirected" that direction is used instead, with a warning when it differs. When the sink
+     * cannot change direction (a caller's builder that already holds edges or was locked), the
+     * sink's direction stands and a warning is recorded.
      * @param headerDirected - the direction the file declares (or the default)
      * @param where - the line of the header, when known
      */
@@ -141,11 +154,13 @@ export class DirectionResolver {
         if (this.policy === "directed" || this.policy === "undirected") {
             wanted = this.policy === "directed";
             if (wanted !== headerDirected) {
-                this.report.warning(
+                // once: this says it for every edge, so no edge repeats it
+                this.report.warnOnce(
                     "coercion",
                     DIRECTION_FORCED_CODE,
                     `the file declares ${direction(headerDirected)} edges; read as ${direction(wanted)} per onMixedDirection`,
                     { line: where?.line ?? null },
+                    `${DIRECTION_FORCED_CODE}:${direction(headerDirected)}`,
                 );
             }
         }
@@ -188,24 +203,27 @@ export class DirectionResolver {
     }
 
     /**
-     * The mirror half of the edge most recently pushed by addEdge(), when it was expanded into a
-     * pair; INVALID_INDEX otherwise. An importer that learns an edge's weight after pushing it
-     * (a GEXF attvalue) sets it on both halves.
-     * @returns the mirror's logical index, or INVALID_INDEX
+     * The second edge of the edge the last addEdge() call added, when that edge was stored as two;
+     * otherwise INVALID_INDEX (4294967295). An edge attribute or weight you set after addEdge()
+     * belongs on both: set it on the index addEdge() returned and, when this is not INVALID_INDEX,
+     * on this index too.
+     * @returns the second edge's index, or INVALID_INDEX
      */
     get lastMirror(): number {
         return this.mirrorOfLast;
     }
 
     /**
-     * Rule 2 of design section 8.4: push one source edge. An edge whose direction equals the
-     * sink's is one addEdge; one that differs is expanded, forced or refused per the policy.
+     * Add one edge. An edge with the graph's direction is added as it is; one with the other
+     * direction is stored as two edges, given the graph's direction, or refused, as
+     * `onMixedDirection` says. When it is stored as two, the return value is the first and
+     * `lastMirror` the second.
      * @param source - the source id
      * @param target - the target id
      * @param kind - the edge's direction in the file
      * @param weight - the weight, or undefined when the file gives none
      * @param where - the line and element, for issues
-     * @returns the logical index of the (primary) edge
+     * @returns the index of the edge added (the first one, when it was stored as two)
      */
     addEdge(source: NodeId, target: NodeId, kind: EdgeKind, weight?: number, where?: EdgeLocation): number {
         if (!this.headerSet) {
@@ -234,6 +252,7 @@ export class DirectionResolver {
                     DIRECTION_FORCED_CODE,
                     `${kind} edges read as ${direction(sink.directed)} per onMixedDirection`,
                     where,
+                    `${DIRECTION_FORCED_CODE}:${kind}`,
                 );
                 const e = sink.addEdge(source, target, weight);
                 this.track(e);
@@ -263,7 +282,8 @@ export class DirectionResolver {
     }
 
     /**
-     * How many edges were pushed with a direction other than their own under the forcing policies.
+     * How many edges were given a direction other than their own, under `onMixedDirection`
+     * "directed" or "undirected".
      * @returns the count
      */
     get forced(): number {
@@ -407,61 +427,68 @@ function direction(directed: boolean): string {
 // ============================================================ the exporter side
 
 /**
- * The expanded-pair view of a snapshot's logical edges for exporters (design sections 3.6 and
- * 8.5): which edges are the mirror half of an expanded pair (and are folded back into their
- * primary), which were undirected in the source, and which carry the GEXF mutual mark. One
- * implementation for every exporter; the only per-format choice is whether a mutual pair folds
- * back into one edge (`foldMutual`, for formats with a mutual or undirected slot) or is written as
- * two directed edges (the default).
- * Consumed by the per-format exporters under src/formats.
+ * What an exporter needs to know about edge direction, from `pairFolding(snapshot)`. In a graph
+ * with both directed and undirected edges, each undirected edge is stored as two edges, one each
+ * way. `folded(e)` tells you which of the two to skip, so the edge is written once, and
+ * `sourceDirected(e)` whether an edge was directed. A GEXF `mutual` edge is also stored as two
+ * edges; it is written as two directed edges unless you pass `foldMutual: true`.
  * @public
+ * @category Plugin helpers
  */
 export interface PairFolding {
-    /** Whether the snapshot carries expanded pairs at all (the pair role column exists). */
+    /** Whether the graph holds any edge stored as two edges. When false, every method answers as for a plain edge. */
     readonly expanded: boolean;
-    /** The number of mutual primaries (edges with the mutual mark whose mirror exists). */
+    /** How many GEXF mutual edges the graph holds, each counted once. */
     readonly mutualCount: number;
     /**
-     * Whether an edge is the mirror half of a pair the exporter folds (its primary is written).
-     * @param e - the logical edge index
+     * Whether to skip an edge: true for the second of the two edges an undirected edge (or, with
+     * `foldMutual`, a mutual edge) is stored as. Write the first and skip this one.
+     * @param e - the edge index
      * @returns true when the edge must be skipped
      */
     folded(e: number): boolean;
     /**
-     * The other half of an expanded pair.
-     * @param e - the logical edge index
-     * @returns the mate's index, or INVALID_INDEX when the edge is not paired
+     * The other of the two edges an undirected or mutual edge is stored as.
+     * @param e - the edge index
+     * @returns the other edge's index, or INVALID_INDEX (4294967295) for an edge stored once
      */
     mateOf(e: number): number;
     /**
-     * Whether an edge was directed in the source (true for every edge of a snapshot without the
-     * directed role column, and for an undirected snapshot's edges as far as the column says).
-     * @param e - the logical edge index
-     * @returns the source direction
+     * Whether an edge was directed in the file it was read from: false for an undirected edge of a
+     * graph with both kinds. It is true for every edge of a graph without mixed direction, an
+     * undirected graph included, so the direction to write for edge `e` is
+     * `snapshot.directed && sourceDirected(e)`.
+     * @param e - the edge index
+     * @returns whether the edge is directed
      */
     sourceDirected(e: number): boolean;
     /**
-     * Whether an edge is a mutual primary or mirror (the GEXF `mutual` type).
-     * @param e - the logical edge index
+     * Whether an edge is either of the two edges a GEXF `mutual` edge is stored as.
+     * @param e - the edge index
      * @returns true for a mutual edge
      */
     isMutual(e: number): boolean;
 }
 
-/** The per-format choice of pairFolding(). */
+/**
+ * The per-format choice of pairFolding().
+ * @category Plugin helpers
+ */
 export interface PairFoldingOptions {
     /**
-     * Fold a mutual pair back into its primary (a format with a mutual or undirected slot);
-     * false (the default) writes both halves as directed edges, and the caller reports the mark.
+     * Write a GEXF mutual edge once, for a format that can say an edge goes both ways. When false
+     * (the default), `folded()` keeps both of its edges, so it is written as two directed edges.
      */
     readonly foldMutual?: boolean | undefined;
 }
 
 /**
- * Build the pair-folding view of a snapshot (one pass over the role columns).
- * @param snapshot - the snapshot
- * @param options - the per-format choice
- * @returns the view
+ * Read how a snapshot stores edge direction, for an exporter: which edges to skip so each
+ * undirected edge is written once, and which edges were directed.
+ * @param snapshot - the graph to write
+ * @param options - whether a GEXF mutual edge is written once
+ * @returns the answers, per edge
+ * @category Writing a format
  */
 export function pairFolding(snapshot: GraphSnapshot, options: PairFoldingOptions = {}): PairFolding {
     const foldMutual = options.foldMutual ?? false;

package/src/common/escape.ts

@@ -29,6 +29,7 @@ const XML_REPLACEMENTS: Readonly<Record<string, string>> = {
  * surrogate) has no XML spelling at all and is E_COLUMN_TYPE; the exporters' check() counts them.
  * @param text - the text
  * @returns the escaped text
+ * @category Plugin helpers
  */
 export function escapeXmlText(text: string): string {
     if (hasIllegalXmlChar(text)) {
@@ -39,9 +40,10 @@ export function escapeXmlText(text: string): string {
 
 /**
  * Escape text for a double-quoted XML attribute value: `&`, `<`, `>`, `"` and the whitespace
- * characters attribute normalisation would fold; a character XML 1.0 forbids is E_COLUMN_TYPE.
+ * characters attribute normalization would fold; a character XML 1.0 forbids is E_COLUMN_TYPE.
  * @param text - the text
  * @returns the escaped text
+ * @category Plugin helpers
  */
 export function escapeXmlAttribute(text: string): string {
     if (hasIllegalXmlChar(text)) {
@@ -71,6 +73,7 @@ const GML_SPECIAL = /["&]|[^ -~]/gu;
  * A lone surrogate cannot be written and is E_COLUMN_TYPE.
  * @param text - the text
  * @returns the quoted GML string
+ * @category Plugin helpers
  */
 export function quoteGmlString(text: string): string {
     const escaped = text.replace(GML_SPECIAL, (c) => {
@@ -116,18 +119,23 @@ const GML_NAMED: ReadonlyMap<string, string> = (() => {
 /**
  * Decode the character entities of a GML string body (the inverse of quoteGmlString on the text
  * between the quotes): numeric references, the XML entities and the ISO-8859-1 HTML entities. An
- * unknown named entity is left as written and handed to `onUnknown`.
+ * unknown named entity, or a numeric reference beyond U+10FFFF, is left as written and handed to
+ * `onUnknown`.
  * @param body - the text between the quotes
- * @param onUnknown - called with each unknown named entity (`&name;`), when given
+ * @param onUnknown - called with each entity left as written (`&name;`, `&#99999999;`), when given
  * @returns the decoded text
+ * @category Plugin helpers
  */
 export function decodeGmlString(body: string, onUnknown?: (entity: string) => void): string {
     return body.replace(GML_ENTITY, (whole, entity: string) => {
-        if (entity.startsWith("#x")) {
-            return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
-        }
         if (entity.startsWith("#")) {
-            return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+            const code = entity.startsWith("#x") ? Number.parseInt(entity.slice(2), 16) : Number(entity.slice(1));
+            if (code <= 0x10ffff) {
+                return String.fromCodePoint(code);
+            }
+            // beyond Unicode: no character to decode to, kept as written like an unknown name
+            onUnknown?.(whole);
+            return whole;
         }
         const known = GML_NAMED.get(entity);
         if (known === undefined) {
@@ -146,6 +154,7 @@ const DOT_KEYWORDS: ReadonlySet<string> = new Set(["node", "edge", "graph", "dig
  * a digit, or a numeral, and not a keyword (case-insensitive).
  * @param text - the text
  * @returns true when the text can be written bare
+ * @category Plugin helpers
  */
 export function isBareDotId(text: string): boolean {
     if (DOT_KEYWORDS.has(text.toLowerCase())) {
@@ -184,6 +193,7 @@ function isDotIdentifier(text: string): boolean {
  * the closing quote. Every other text is writable; quoteDotId() writes it.
  * @param text - the id, name or value text
  * @returns true when quoteDotId(text) reads back as `text`
+ * @category Plugin helpers
  */
 export function isWritableDotText(text: string): boolean {
     return !text.endsWith("\\") && !text.includes('\\"') && !/\\[\r\n]/.test(text);
@@ -196,6 +206,7 @@ export function isWritableDotText(text: string): boolean {
  * backslash has no DOT spelling (isWritableDotText); the caller refuses it before writing.
  * @param text - the id or label text
  * @returns the DOT ID
+ * @category Plugin helpers
  */
 export function quoteDotId(text: string): string {
     if (isBareDotId(text)) {
@@ -205,29 +216,31 @@ export function quoteDotId(text: string): string {
 }
 
 /**
- * Write a set CSV cell per RFC 4180: quoted with `"` doubled when the text contains the
- * delimiter, a quote, a CR or LF, or leading / trailing whitespace; bare otherwise. The empty
- * string is written as the quoted empty cell `""`, so the importers can tell a set empty string
- * (and an empty-string node id, legal under design section 4.1) from an unset cell, which every
- * exporter writes as nothing between the delimiters.
+ * Write a set CSV cell per RFC 4180: quoted, with the quote character doubled, when the text
+ * contains the delimiter, the quote character, a CR or LF, or leading / trailing whitespace; bare
+ * otherwise. The empty string is written as an empty quoted cell (`""`), so the importers can tell a
+ * set empty string (and an empty-string node id) from an unset cell, which every exporter writes as
+ * nothing between the delimiters.
  * @param text - the cell text of a set cell
  * @param delimiter - the field delimiter (default ",")
+ * @param quote - the quote character (default `"`)
  * @returns the cell as written
+ * @category Plugin helpers
  */
-export function quoteCsvCell(text: string, delimiter = ","): string {
+export function quoteCsvCell(text: string, delimiter = ",", quote = '"'): string {
     if (text.length === 0) {
-        return '""';
+        return quote + quote;
     }
     if (
         !text.includes(delimiter) &&
-        !text.includes('"') &&
+        !text.includes(quote) &&
         !text.includes("\n") &&
         !text.includes("\r") &&
         text === text.trim()
     ) {
         return text;
     }
-    return `"${text.replace(/"/g, '""')}"`;
+    return `${quote}${text.split(quote).join(quote + quote)}${quote}`;
 }
 
 /**
@@ -235,6 +248,7 @@ export function quoteCsvCell(text: string, delimiter = ","): string {
  * labels, so a text containing a double quote, a CR or an LF cannot be written.
  * @param text - the label text
  * @returns true when quotePajekLabel() can write it
+ * @category Plugin helpers
  */
 export function isPajekLabel(text: string): boolean {
     return !text.includes('"') && !text.includes("\n") && !text.includes("\r");
@@ -247,6 +261,7 @@ export function isPajekLabel(text: string): boolean {
  * the exporter's check() counts those.
  * @param text - the label text
  * @returns the label as written
+ * @category Plugin helpers
  */
 export function quotePajekLabel(text: string): string {
     if (!isPajekLabel(text)) {
@@ -255,7 +270,8 @@ export function quotePajekLabel(text: string): string {
             value: text,
         });
     }
-    if (text.length > 0 && !/[\s"]/.test(text) && !text.startsWith("[")) {
+    // a bare `%` token starts a comment for the importer, so such a text is quoted too
+    if (text.length > 0 && !/[\s"]/.test(text) && !text.startsWith("[") && !text.startsWith("%")) {
         return text;
     }
     return `"${text}"`;