@graphty/graph-io 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graph-io",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Importers and exporters (GEXF, GraphML, GML, DOT, Pajek, CSV, JSON, Neo4j) for the @graphty/graph-format snapshot",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",

package/src/common/escape.ts

@@ -88,16 +88,40 @@ export function quoteGmlString(text: string): string {
     return `"${escaped}"`;
 }
 
-const GML_ENTITY = /&(#[0-9]+|#x[0-9a-fA-F]+|amp|quot|lt|gt|apos);/g;
-const GML_NAMED: Readonly<Record<string, string>> = { amp: "&", quot: '"', lt: "<", gt: ">", apos: "'" };
+const GML_ENTITY = /&(#[0-9]+|#x[0-9a-fA-F]+|[A-Za-z][A-Za-z0-9]*);/g;
+
+/** The XML entities and the ISO-8859-1 HTML entities (U+00A0..U+00FF), which GML uses for characters above 127. */
+const GML_NAMED: ReadonlyMap<string, string> = (() => {
+    const table = new Map<string, string>([
+        ["amp", "&"],
+        ["quot", '"'],
+        ["lt", "<"],
+        ["gt", ">"],
+        ["apos", "'"],
+    ]);
+    const latin1 = (
+        "nbsp iexcl cent pound curren yen brvbar sect uml copy ordf laquo not shy reg macr deg plusmn sup2 " +
+        "sup3 acute micro para middot cedil sup1 ordm raquo frac14 frac12 frac34 iquest Agrave Aacute Acirc " +
+        "Atilde Auml Aring AElig Ccedil Egrave Eacute Ecirc Euml Igrave Iacute Icirc Iuml ETH Ntilde Ograve " +
+        "Oacute Ocirc Otilde Ouml times Oslash Ugrave Uacute Ucirc Uuml Yacute THORN szlig agrave aacute " +
+        "acirc atilde auml aring aelig ccedil egrave eacute ecirc euml igrave iacute icirc iuml eth ntilde " +
+        "ograve oacute ocirc otilde ouml divide oslash ugrave uacute ucirc uuml yacute thorn yuml"
+    ).split(" ");
+    latin1.forEach((name, i) => {
+        table.set(name, String.fromCharCode(0xa0 + i));
+    });
+    return table;
+})();
 
 /**
  * Decode the character entities of a GML string body (the inverse of quoteGmlString on the text
- * between the quotes). An unknown entity is left as written.
+ * 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`.
  * @param body - the text between the quotes
+ * @param onUnknown - called with each unknown named entity (`&name;`), when given
  * @returns the decoded text
  */
-export function decodeGmlString(body: string): string {
+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));
@@ -105,7 +129,12 @@ export function decodeGmlString(body: string): string {
         if (entity.startsWith("#")) {
             return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
         }
-        return GML_NAMED[entity] ?? whole;
+        const known = GML_NAMED.get(entity);
+        if (known === undefined) {
+            onUnknown?.(whole);
+            return whole;
+        }
+        return known;
     });
 }
 

package/src/formats/gml/importer.ts

@@ -108,6 +108,8 @@ export const ELEMENT_TYPE_CODE = "E_GML_ELEMENT_TYPE";
 export const FLAG_TYPE_CODE = "E_GML_FLAG_TYPE";
 /** Issue code: a `directed` / `multigraph` flag that is not 0 or 1 (read as its truth value), or one repeated. */
 export const FLAG_VALUE_CODE = "W_GML_FLAG_VALUE";
+/** Issue code: a named entity in a string that is neither an XML nor an ISO-8859-1 HTML entity; it is kept as written. */
+export const UNKNOWN_ENTITY_CODE = "W_GML_UNKNOWN_ENTITY";
 /** Issue code: an integer beyond 2^53 stored as the nearest f64 (design section 5.1). */
 export const PRECISION_CODE = SHARED_PRECISION_CODE;
 /** Issue code: the sink already holds a column of the name with another declaration; renamed `<name>#<key>`. */
@@ -342,6 +344,15 @@ class GmlImport {
      */
     run(tokens: GmlTokens): void {
         this.tokens = tokens;
+        tokens.onUnknownEntity = (entity, line) => {
+            this.report.warnOnce(
+                "parse-error",
+                UNKNOWN_ENTITY_CODE,
+                `unknown character entity ${entity} is kept as written`,
+                { line, element: entity },
+                `${UNKNOWN_ENTITY_CODE}:${entity}`,
+            );
+        };
         this.scan();
         this.push();
     }
@@ -438,7 +449,7 @@ class GmlImport {
                     continue;
                 }
             } else {
-                if (key === "source" || key === "target") {
+                if (key === "source" || key === "target" || key === "directed") {
                     continue;
                 }
                 if (key === weightFrom) {
@@ -717,7 +728,7 @@ class GmlImport {
             this.report.error(
                 "validation-error",
                 FLAG_TYPE_CODE,
-                `graph flag "${name}" must be the integer 0 or 1, found ${describeValue(t, v)}`,
+                `flag "${name}" must be the integer 0 or 1, found ${describeValue(t, v)}`,
                 { line: t.line[v], element: name },
             );
             return null;
@@ -727,7 +738,7 @@ class GmlImport {
             this.report.warning(
                 "validation-error",
                 FLAG_VALUE_CODE,
-                `graph flag "${name}" is ${n}; read as ${n !== 0 ? "1" : "0"}`,
+                `flag "${name}" is ${n}; read as ${n !== 0 ? "1" : "0"}`,
                 { line: t.line[v], element: name },
             );
         }
@@ -931,12 +942,15 @@ class GmlImport {
             let sourceTok = -1;
             let targetTok = -1;
             let weightTok = -1;
+            let directedTok = -1;
             for (let p = open + 1; p < close; p = t.nextPair(p)) {
                 const key = t.textOf(p);
                 if (key === "source") {
                     sourceTok = this.structuralToken(sourceTok, p, "source");
                 } else if (key === "target") {
                     targetTok = this.structuralToken(targetTok, p, "target");
+                } else if (key === "directed") {
+                    directedTok = this.structuralToken(directedTok, p, "directed");
                 } else if (key === options.weightFrom) {
                     weightTok = p + 1;
                 }
@@ -952,13 +966,12 @@ class GmlImport {
             const before = sink.edgeCount;
             const sourceNew = sink.indexOf(source) === INVALID_INDEX;
             const targetNew = source !== target && sink.indexOf(target) === INVALID_INDEX;
-            edge = this.requireResolver().addEdge(
-                source,
-                target,
-                this.headerDirected ? "directed" : "undirected",
-                weight,
-                { line, element },
-            );
+            // an edge-level `directed` key overrides the graph's flag for that edge (mixed graphs)
+            const directed = this.readFlag(directedTok, "directed") ?? this.headerDirected;
+            edge = this.requireResolver().addEdge(source, target, directed ? "directed" : "undirected", weight, {
+                line,
+                element,
+            });
             report.counts.edges += sink.edgeCount - before;
             // endpoints the file never declares (addMissingNodes) are nodes of the sink too
             report.counts.nodes += (sourceNew ? 1 : 0) + (targetNew ? 1 : 0);
@@ -971,7 +984,7 @@ class GmlImport {
         try {
             for (let p = open + 1; p < close; p = t.nextPair(p)) {
                 const key = t.textOf(p);
-                if (key === "source" || key === "target" || key === options.weightFrom) {
+                if (key === "source" || key === "target" || key === "directed" || key === options.weightFrom) {
                     continue;
                 }
                 const plan = this.edgePlans.get(key);

package/src/formats/gml/index.ts

@@ -45,6 +45,7 @@ import {
     REPEATED_KEY_CODE,
     ROLE_TAKEN_CODE,
     SECOND_GRAPH_CODE,
+    UNKNOWN_ENTITY_CODE,
 } from "./importer.js";
 
 export { gmlExporter, type GmlExportOptions } from "./exporter.js";
@@ -88,6 +89,8 @@ export const GML_ISSUE = Object.freeze({
     FLAG_TYPE: FLAG_TYPE_CODE,
     /** A `directed` / `multigraph` flag outside 0 / 1, or repeated. */
     FLAG_VALUE: FLAG_VALUE_CODE,
+    /** A named entity in a string that no table decodes; kept as written. */
+    UNKNOWN_ENTITY: UNKNOWN_ENTITY_CODE,
     /** An integer beyond 2^53 rounded to f64. */
     PRECISION: PRECISION_CODE,
     /** A column renamed `<name>#<key>` because the sink held the name with another shape. */

package/src/formats/gml/syntax.ts

@@ -112,6 +112,9 @@ export class GmlTokens {
     /** The number of tokens. */
     count = 0;
 
+    /** Called by stringOf() with each named entity it cannot decode and the token's line, when set. */
+    onUnknownEntity: ((entity: string, line: number) => void) | null = null;
+
     /**
      * Create an empty token list over a text.
      * @param text - the source text
@@ -159,7 +162,12 @@ export class GmlTokens {
      * @returns the body with character references decoded
      */
     stringOf(i: number): string {
-        return decodeGmlString(this.textOf(i));
+        const text = this.textOf(i);
+        if (text.indexOf("&") < 0) {
+            return text;
+        }
+        const report = this.onUnknownEntity;
+        return decodeGmlString(text, report === null ? undefined : (entity) => { report(entity, this.line[i]); });
     }
 
     /**

package/src/formats/graphml/constants.ts

@@ -173,6 +173,10 @@ export const GRAPHML_ISSUE = Object.freeze({
     HYPEREDGE_ENDPOINT: "E_GRAPHML_HYPEREDGE_ENDPOINT",
     /** `<port>` declarations (and their data) are not kept; sourceport / targetport edge attributes are. */
     PORT_DECLARATION: "W_GRAPHML_PORT_DECLARATION",
+    /** A GraphML `parse.*` hint on `<graph>`, `<node>` or `<edge>` the importer does not act on (parse.nodeids, parse.order, ...). */
+    PARSE_HINT_IGNORED: "W_GRAPHML_PARSE_HINT_IGNORED",
+    /** An XML attribute GraphML does not define on `<graph>`, `<node>` or `<edge>`; it is not kept. */
+    UNKNOWN_XML_ATTRIBUTE: "W_GRAPHML_UNKNOWN_XML_ATTRIBUTE",
     /** A `<locator>` element. */
     LOCATOR_DROPPED: "W_GRAPHML_LOCATOR_DROPPED",
     /** A `<desc>` of a node, an edge or a hyperedge. */

package/src/formats/graphml/importer.ts

@@ -83,6 +83,12 @@ import {
 } from "./constants.js";
 import { XmlTreeBuilder } from "./tree.js";
 
+
+/** The XML attributes the importer reads on `<graph>`, `<node>` and `<edge>`; any other is reported. */
+const GRAPH_ATTRIBUTES: ReadonlySet<string> = new Set(["id", "edgedefault", "parse.nodes", "parse.edges"]);
+const NODE_ATTRIBUTES: ReadonlySet<string> = new Set(["id"]);
+const EDGE_ATTRIBUTES: ReadonlySet<string> = new Set(["id", "source", "target", "directed", "sourceport", "targetport"]);
+
 /** The format-specific options of the GraphML importer. */
 export interface GraphmlImportOptions {
     /**
@@ -827,6 +833,39 @@ class GraphmlReader implements XmlHandler {
 
     // ------------------------------------------------------------------ graphs
 
+    /**
+     * Report, once per element kind and attribute name, an XML attribute the importer does not read:
+     * a GraphML `parse.*` hint as ignored, anything else as unknown. Namespace declarations and
+     * `xml:` / `xsi:` attributes are not data and pass silently.
+     * @param kind - the element name
+     * @param attrs - the element's attributes
+     * @param known - the attributes the importer reads on that element
+     * @param line - the line
+     */
+    private reportUnreadAttributes(
+        kind: string,
+        attrs: ReadonlyMap<string, string>,
+        known: ReadonlySet<string>,
+        line: number,
+    ): void {
+        for (const name of attrs.keys()) {
+            if (known.has(name) || name === "xmlns" || /^(xmlns|xml|xsi):/.test(name)) {
+                continue;
+            }
+            const hint = name.startsWith("parse.");
+            const code = hint ? GRAPHML_ISSUE.PARSE_HINT_IGNORED : GRAPHML_ISSUE.UNKNOWN_XML_ATTRIBUTE;
+            this.report.warnOnce(
+                "unsupported",
+                code,
+                hint
+                    ? `the <${kind}> parse hint ${name} is ignored`
+                    : `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`,
+                { line, element: name },
+                `${code}:${kind}:${name}`,
+            );
+        }
+    }
+
     /**
      * Open a `<graph>`: the top-level one sets the sink's direction (rule 1 of design section
      * 8.4); a nested one records its container as the parent of its nodes.
@@ -835,6 +874,7 @@ class GraphmlReader implements XmlHandler {
      * @param parent - the containing node's index, or INVALID_INDEX
      */
     private beginGraph(attrs: ReadonlyMap<string, string>, line: number, parent: number): void {
+        this.reportUnreadAttributes("graph", attrs, GRAPH_ATTRIBUTES, line);
         const top = this.graphs.length === 0;
         const edgedefault = attrs.get("edgedefault");
         let directed: boolean;
@@ -1409,6 +1449,7 @@ class GraphmlReader implements XmlHandler {
      * @param line - the line
      */
     private beginNode(attrs: ReadonlyMap<string, string>, line: number): void {
+        this.reportUnreadAttributes("node", attrs, NODE_ATTRIBUTES, line);
         const graph = this.graphs[this.graphs.length - 1];
         const state: NodeState = {
             id: null,
@@ -1530,6 +1571,7 @@ class GraphmlReader implements XmlHandler {
      * @param line - the line
      */
     private beginEdge(attrs: ReadonlyMap<string, string>, line: number): void {
+        this.reportUnreadAttributes("edge", attrs, EDGE_ATTRIBUTES, line);
         const graph = this.graphs[this.graphs.length - 1];
         const edge: EdgeState = {
             source: null,

package/src/formats/json/importer.ts

@@ -157,6 +157,8 @@ export const JSON_ISSUE = Object.freeze({
     HYPEREDGE_SHAPE: "E_HYPEREDGE_SHAPE",
     /** The nodes have no id key at all; array positions became the ids. */
     POSITIONAL_NODES: "W_POSITIONAL_NODES",
+    /** A node-link / d3 top-level key the importer does not read (the other of edges / links, an unknown key); it is dropped. */
+    UNREAD_KEY: "W_JSON_UNREAD_KEY",
     /** A builder-policy option (addMissingNodes, duplicateEdges, selfLoops, weightDtype) differs from the sink's (the shared W_SINK_OPTION). */
     SINK_OPTION: SINK_OPTION_CODE,
     /** A common option the dialect has no use for (nodeIdFrom outside node-link, long, restoreMangledIds). */
@@ -1120,6 +1122,17 @@ function importNodeLink(ctx: ImportContext, root: JsonRecord, dialect: JsonDiale
     const multigraph = hasKey(root, "multigraph") ? flagOf(root.multigraph, "multigraph", false, report) : null;
     ctx.setHeader(directed);
     ctx.writeGraphDict(root.graph, "graph");
+    for (const key of Object.keys(root)) {
+        if (key !== "nodes" && key !== edgesKey && key !== "directed" && key !== "multigraph" && key !== "graph") {
+            const value = root[key];
+            const what = Array.isArray(value)
+                ? `${String(value.length)} ${value.length === 1 ? "entry" : "entries"}`
+                : describe(value);
+            report.warning("unsupported", JSON_ISSUE.UNREAD_KEY, `top-level key ${key} (${what}) is not read; dropped`, {
+                element: key,
+            });
+        }
+    }
 
     const nodeList = nodes ?? [];
     const edgeList = edges ?? [];

package/src/formats/neo4j/importer.ts

@@ -122,6 +122,12 @@ export const DUPLICATE_NODE_CODE = SHARED_DUPLICATE_NODE_CODE;
 /** Issue code: a node id was declared in two id spaces; the core has one id space and the later row is skipped. */
 export const ID_SPACE_COLLISION_CODE = "E_NEO4J_ID_SPACE_COLLISION";
 
+/**
+ * Issue code: a `:START_ID(Space)` / `:END_ID(Space)` id names a node a node row declared in another
+ * id space; the core has one id space, so the endpoint does not exist in its space and the row is skipped.
+ */
+export const ENDPOINT_SPACE_CODE = "E_NEO4J_ENDPOINT_SPACE";
+
 /** Issue code: two different id cells became one id under `ids: "number"`. */
 export const ID_MERGED_CODE = SHARED_ID_MERGED_CODE;
 
@@ -225,6 +231,9 @@ interface RelationshipSection {
     readonly width: number;
     readonly startCell: number;
     readonly endCell: number;
+    /** The id space of `:START_ID` / `:END_ID` as a registry code, or 0 when the header declares none. */
+    readonly startSpaceCode: number;
+    readonly endSpaceCode: number;
     /** The `:TYPE` cell, or -1. */
     readonly typeCell: number;
     /** The cell of the property named by `weightFrom`, or -1. */
@@ -340,6 +349,15 @@ class NodeRegistry {
         }
         return previous === code ? "duplicate" : "collision";
     }
+
+    /**
+     * The space code a node row declared a node in.
+     * @param index - the node index
+     * @returns the code, or 0 when no node row declared the node
+     */
+    codeAt(index: number): number {
+        return index < this.codes.length ? this.codes[index] : 0;
+    }
 }
 
 /**
@@ -675,7 +693,19 @@ class Neo4jImportSession {
             weightCell = fields.findIndex((field) => field.kind === "PROPERTY" && field.name === weightFrom);
         }
         const properties = this.declareProperties("edge", fields, line, weightCell);
-        return { kind: "relationship", width: fields.length, startCell, endCell, typeCell, weightCell, properties };
+        const { space: startSpace } = fields[startCell];
+        const { space: endSpace } = fields[endCell];
+        return {
+            kind: "relationship",
+            width: fields.length,
+            startCell,
+            endCell,
+            startSpaceCode: startSpace === null ? 0 : this.registry.codeOf(startSpace),
+            endSpaceCode: endSpace === null ? 0 : this.registry.codeOf(endSpace),
+            typeCell,
+            weightCell,
+            properties,
+        };
     }
 
     /**
@@ -944,6 +974,22 @@ class Neo4jImportSession {
             report.counts.skippedEdges++;
             return;
         }
+        let wrongSpace: string | null = null;
+        if (this.wrongSpace(source, section.startSpaceCode)) {
+            wrongSpace = startText;
+        } else if (this.wrongSpace(target, section.endSpaceCode)) {
+            wrongSpace = endText;
+        }
+        if (wrongSpace !== null) {
+            report.error(
+                "missing-value",
+                ENDPOINT_SPACE_CODE,
+                `endpoint ${wrongSpace} is not a node of its declared id space (a node of another id space has that id); the row is skipped`,
+                { line, element },
+            );
+            report.counts.skippedEdges++;
+            return;
+        }
         let weight: number | undefined;
         if (section.weightCell >= 0) {
             try {
@@ -977,6 +1023,26 @@ class Neo4jImportSession {
         report.counts.edges++;
     }
 
+    /**
+     * Whether an endpoint id belongs to a node a node row declared in another id space than the
+     * endpoint's header declares. An endpoint without a declared space, or a node no row declared
+     * yet, is looked up by id alone.
+     * @param id - the endpoint id
+     * @param spaceCode - the endpoint's space code, 0 for none
+     * @returns true when the endpoint resolves to a node of another space
+     */
+    private wrongSpace(id: NodeId, spaceCode: number): boolean {
+        if (spaceCode === 0) {
+            return false;
+        }
+        const index = this.sink.indexOf(id);
+        if (index < 0) {
+            return false;
+        }
+        const declared = this.registry.codeAt(index);
+        return declared !== 0 && declared !== spaceCode;
+    }
+
     /**
      * Coerce an id cell, reporting a merge under `ids: "number"` and an invalid id as an error.
      * @param text - the cell

package/src/formats/neo4j/index.ts

@@ -32,6 +32,7 @@ import {
 import {
     COLUMN_COUNT_CODE,
     DUPLICATE_NODE_CODE,
+    ENDPOINT_SPACE_CODE,
     HEADER_CODE,
     HEADER_OPTION_CODE,
     ID_MERGED_CODE,
@@ -75,6 +76,8 @@ export const NEO4J_ISSUE = Object.freeze({
     DUPLICATE_NODE: DUPLICATE_NODE_CODE,
     /** A node id declared in two id spaces. */
     ID_SPACE_COLLISION: ID_SPACE_COLLISION_CODE,
+    /** A relationship endpoint whose id belongs to a node of another id space; the row is skipped. */
+    ENDPOINT_SPACE: ENDPOINT_SPACE_CODE,
     /** Two id texts merged into one number under ids "number". */
     ID_MERGED: ID_MERGED_CODE,
     /** A header brace option the importer does not apply. */