@graphty/graph-io 0.3.39 → 0.3.41

package/src/formats/gexf/importer.ts

@@ -1328,20 +1328,15 @@ class GexfReader implements XmlHandler {
     }
 
     /**
-     * Declare one `<attribute id title type>` with its `<default>` and `<options>` (design
-     * sections 5.1, 5.5, 5.6). The edge attribute titled `weightFrom` is the weight and gets no
-     * column; its declaration is recorded in meta.weightOrigin.
-     * @param pending - the attribute as read
+     * Whether an attribute was already declared (warning that the first declaration is kept), and
+     * a warning when values that use it came before its declaration.
+     * @param domain - node or edge
+     * @param id - the attribute id
+     * @param where - the report location
+     * @returns true when the declaration is a duplicate and must be skipped
      */
-    private declareOne(pending: PendingAttribute): void {
-        const { report, sink, options } = this;
-        const { domain, dynamic, attrs } = pending;
-        const id = attrs.get("id");
-        const where = { line: pending.line, element: id ?? null };
-        if (id === undefined) {
-            report.error("validation-error", ATTRIBUTE_ID_CODE, "<attribute> without an id", where);
-            return;
-        }
+    private isDuplicateAttribute(domain: "node" | "edge", id: string, where: IssueLocation): boolean {
+        const { report } = this;
         const tracked = domain === "node" ? this.nodeAttrs : this.edgeAttrs;
         if (tracked.has(id) || (domain === "edge" && this.weightAttr !== null && this.weightAttr.id === id)) {
             report.warning(
@@ -1350,7 +1345,7 @@ class GexfReader implements XmlHandler {
                 `${domain} attribute "${id}" is declared twice; the first declaration is kept`,
                 where,
             );
-            return;
+            return true;
         }
         if (this.unknownAttributes.has(`${domain}:${id}`)) {
             report.warning(
@@ -1360,6 +1355,68 @@ class GexfReader implements XmlHandler {
                 where,
             );
         }
+        return false;
+    }
+
+    /**
+     * Whether an edge attribute becomes THE weight: the first attribute of the weight's title does
+     * (declared here), a later one only warns and stays a plain column.
+     * @param attribute - the attribute's domain, id, display name, title and type
+     * @param attribute.domain - node or edge
+     * @param attribute.id - the attribute id
+     * @param attribute.name - the column name
+     * @param attribute.title - the declared title, or null
+     * @param attribute.type - the declared type, or null
+     * @param where - the report location
+     * @returns true when the attribute was declared as the weight
+     */
+    private claimsWeight(
+        attribute: { domain: "node" | "edge"; id: string; name: string; title: string | null; type: string | null },
+        where: IssueLocation,
+    ): boolean {
+        const { report, sink, options } = this;
+        const { domain, id, name, title, type } = attribute;
+        if (domain !== "edge" || !isWeightField(name, options.weightFrom)) {
+            return false;
+        }
+        if (this.weightAttr !== null) {
+            // the first attribute of that title stays THE weight; this one becomes a plain column
+            report.warning(
+                "validation-error",
+                DUPLICATE_ATTRIBUTE_CODE,
+                `edge attribute "${id}" is also titled ${name}; attribute "${this.weightAttr.id}" is the weight, "${id}" is kept as a column`,
+                where,
+            );
+            return false;
+        }
+        const declared = declareAttribute({ format: GEXF_FORMAT, id, title, type, long: options.long });
+        for (const issue of declared.issues) {
+            report.warning(issue.category, issue.code, issue.message, where);
+        }
+        this.weightAttr = { id, spec: declared.spec, table: INVALID_INDEX as ExtensionHandle };
+        sink.setMeta({ weightOrigin: { format: GEXF_FORMAT, id, title, type, namespace: null } });
+        return true;
+    }
+
+    /**
+     * Declare one `<attribute id title type>` with its `<default>` and `<options>` (design
+     * sections 5.1, 5.5, 5.6). The edge attribute titled `weightFrom` is the weight and gets no
+     * column; its declaration is recorded in meta.weightOrigin.
+     * @param pending - the attribute as read
+     */
+    private declareOne(pending: PendingAttribute): void {
+        const { report, sink, options } = this;
+        const { domain, dynamic, attrs } = pending;
+        const id = attrs.get("id");
+        const where = { line: pending.line, element: id ?? null };
+        if (id === undefined) {
+            report.error("validation-error", ATTRIBUTE_ID_CODE, "<attribute> without an id", where);
+            return;
+        }
+        const tracked = domain === "node" ? this.nodeAttrs : this.edgeAttrs;
+        if (this.isDuplicateAttribute(domain, id, where)) {
+            return;
+        }
         const title = attrs.get("title") ?? null;
         const type = attrs.get("type") ?? null;
         if (type === null) {
@@ -1371,21 +1428,7 @@ class GexfReader implements XmlHandler {
             );
         }
         const name = title !== null && title.length > 0 ? title : id;
-        if (domain === "edge" && this.weightAttr !== null && isWeightField(name, options.weightFrom)) {
-            // the first attribute of that title stays THE weight; this one becomes a plain column
-            report.warning(
-                "validation-error",
-                DUPLICATE_ATTRIBUTE_CODE,
-                `edge attribute "${id}" is also titled ${name}; attribute "${this.weightAttr.id}" is the weight, "${id}" is kept as a column`,
-                where,
-            );
-        } else if (domain === "edge" && isWeightField(name, options.weightFrom)) {
-            const declared = declareAttribute({ format: GEXF_FORMAT, id, title, type, long: options.long });
-            for (const issue of declared.issues) {
-                report.warning(issue.category, issue.code, issue.message, where);
-            }
-            this.weightAttr = { id, spec: declared.spec, table: INVALID_INDEX as ExtensionHandle };
-            sink.setMeta({ weightOrigin: { format: GEXF_FORMAT, id, title, type, namespace: null } });
+        if (this.claimsWeight({ domain, id, name, title, type }, where)) {
             return;
         }
         const declaredNames = domain === "node" ? this.declaredNodeNames : this.declaredEdgeNames;
@@ -1717,6 +1760,15 @@ class GexfReader implements XmlHandler {
                 report.recordError(err, ref.where);
             }
         }
+        this.resolveParentsLists(lists);
+    }
+
+    /**
+     * Resolve the `<parents>` lists read so far into the parents column.
+     * @param lists - the queued `<parents>` lists
+     */
+    private resolveParentsLists(lists: readonly (typeof this.parentsRefs)[number][]): void {
+        const { sink, report } = this;
         for (const ref of lists) {
             const indices: number[] = [];
             for (const id of ref.ids) {
@@ -1763,7 +1815,7 @@ class GexfReader implements XmlHandler {
      * @param line - the line
      */
     private beginEdge(attrs: ReadonlyMap<string, string>, line: number): void {
-        const { report, sink, options } = this;
+        const { report, sink } = this;
         this.checkAbort();
         this.ctx.push(Ctx.Edge);
         this.edge = null;
@@ -1816,18 +1868,7 @@ class GexfReader implements XmlHandler {
         try {
             const source = this.coerceId(sourceText, where);
             const target = this.coerceId(targetText, where);
-            if (!options.addMissingNodes) {
-                if (sink.indexOf(source) === INVALID_INDEX) {
-                    throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${sourceText}"`, {
-                        id: source,
-                    });
-                }
-                if (sink.indexOf(target) === INVALID_INDEX) {
-                    throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${targetText}"`, {
-                        id: target,
-                    });
-                }
-            }
+            this.requireDeclaredEndpoints(source, target, sourceText, targetText);
             const weight = this.xmlWeight(attrs, where);
             const before = sink.edgeCount;
             index = this.resolver.addEdge(source, target, kind, weight, where);
@@ -1846,6 +1887,47 @@ class GexfReader implements XmlHandler {
         frame.mirror = this.resolver.lastMirror;
         frame.xmlWeight = attrs.get("weight") ?? null;
         this.edge = frame;
+        this.writeEdgeColumns(attrs, index, idText, where);
+    }
+
+    /**
+     * Throw when addMissingNodes is off and an endpoint names an undeclared node.
+     * @param source - the coerced source id
+     * @param target - the coerced target id
+     * @param sourceText - the source as written
+     * @param targetText - the target as written
+     */
+    private requireDeclaredEndpoints(source: NodeId, target: NodeId, sourceText: string, targetText: string): void {
+        const { sink, options } = this;
+        if (options.addMissingNodes) {
+            return;
+        }
+        if (sink.indexOf(source) === INVALID_INDEX) {
+            throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${sourceText}"`, {
+                id: source,
+            });
+        }
+        if (sink.indexOf(target) === INVALID_INDEX) {
+            throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${targetText}"`, {
+                id: target,
+            });
+        }
+    }
+
+    /**
+     * Write the id, label, kind and lifetime columns of an added edge; a failure is reported.
+     * @param attrs - the edge's attributes
+     * @param index - the edge's index
+     * @param idText - the edge's id, or undefined
+     * @param where - the edge's location
+     */
+    private writeEdgeColumns(
+        attrs: ReadonlyMap<string, string>,
+        index: number,
+        idText: string | undefined,
+        where: IssueLocation,
+    ): void {
+        const { report, sink } = this;
         try {
             if (idText !== undefined) {
                 this.edgeIdColumn.set(sink, report, index, idText, where);
@@ -2555,35 +2637,18 @@ class GexfReader implements XmlHandler {
                 case "color":
                     columns.color.set(sink, report, index, parseColor(attrs), where);
                     break;
-                case "position": {
-                    const x = vizNumber(attrs, "x");
-                    const y = vizNumber(attrs, "y");
-                    const z = attrs.has("z") ? vizNumber(attrs, "z") : 0;
-                    this.positionColumn ??= new LazyColumn("node", {
-                        ...NODE_DECLS.position,
-                        extra: { ...NODE_DECLS.position.extra, sourceDims: attrs.has("z") ? 3 : 2 },
-                    });
-                    this.positionColumn.set(sink, report, index, [x, y, z], where);
+                case "position":
+                    this.writePosition(attrs, index, where);
                     break;
-                }
                 case "size":
                     this.sizeColumn.set(sink, report, index, vizNumber(attrs, "value"), where);
                     break;
                 case "thickness":
                     this.thicknessColumn.set(sink, report, index, vizNumber(attrs, "value"), where);
                     break;
-                case "shape": {
-                    const value = attrs.get("value");
-                    if (value === undefined) {
-                        throw new GraphFormatError("E_COLUMN_TYPE", "<viz:shape> without a value", { element: name });
-                    }
-                    columns.shape.set(sink, report, index, value, where);
-                    const uri = attrs.get("uri");
-                    if (domain === "node" && uri !== undefined) {
-                        this.shapeUriColumn.set(sink, report, index, uri, where);
-                    }
+                case "shape":
+                    this.writeShape(name, attrs, domain, index, where);
                     break;
-                }
                 default:
                     break;
             }
@@ -2595,6 +2660,51 @@ class GexfReader implements XmlHandler {
         }
     }
 
+    /**
+     * Write a `<viz:position>`.
+     * @param attrs - its attributes
+     * @param index - the node's index
+     * @param where - the node's location
+     */
+    private writePosition(attrs: ReadonlyMap<string, string>, index: number, where: IssueLocation): void {
+        const x = vizNumber(attrs, "x");
+        const y = vizNumber(attrs, "y");
+        const z = attrs.has("z") ? vizNumber(attrs, "z") : 0;
+        this.positionColumn ??= new LazyColumn("node", {
+            ...NODE_DECLS.position,
+            extra: { ...NODE_DECLS.position.extra, sourceDims: attrs.has("z") ? 3 : 2 },
+        });
+        this.positionColumn.set(this.sink, this.report, index, [x, y, z], where);
+    }
+
+    /**
+     * Write a `<viz:shape>` and, on a node, its `uri`.
+     * @param name - the element name as written
+     * @param attrs - its attributes
+     * @param domain - node or edge
+     * @param index - the element's index
+     * @param where - the element's location
+     */
+    private writeShape(
+        name: string,
+        attrs: ReadonlyMap<string, string>,
+        domain: "node" | "edge",
+        index: number,
+        where: IssueLocation,
+    ): void {
+        const { sink, report } = this;
+        const columns = domain === "node" ? this.nodeColumns : this.edgeColumns;
+        const value = attrs.get("value");
+        if (value === undefined) {
+            throw new GraphFormatError("E_COLUMN_TYPE", "<viz:shape> without a value", { element: name });
+        }
+        columns.shape.set(sink, report, index, value, where);
+        const uri = attrs.get("uri");
+        if (domain === "node" && uri !== undefined) {
+            this.shapeUriColumn.set(sink, report, index, uri, where);
+        }
+    }
+
     // ---------------------------------------------------------------- helpers
 
     /**

package/src/formats/gml/exporter.ts

@@ -420,6 +420,20 @@ function note(code: string, message: string, column: string | null = null, count
     return Object.freeze({ code, message, column, count });
 }
 
+/**
+ * Count a kind of json value once per row.
+ * @param seen - the flags already counted for this row
+ * @param flag - the flag of the kind
+ * @param stats - the counters
+ * @param counter - the counter of the kind
+ */
+function countOnce(seen: SeenFlags, flag: keyof SeenFlags, stats: JsonStats, counter: keyof JsonStats): void {
+    if (!seen[flag]) {
+        seen[flag] = true;
+        stats[counter]++;
+    }
+}
+
 /**
  * Inspect a JSON value for what GML cannot write exactly.
  * @param value - the value
@@ -429,24 +443,15 @@ function note(code: string, message: string, column: string | null = null, count
  */
 function inspectJson(value: unknown, stats: JsonStats, inArray: boolean, seen: SeenFlags): void {
     if (value === null) {
-        if (!seen.nulls) {
-            seen.nulls = true;
-            stats.nulls++;
-        }
+        countOnce(seen, "nulls", stats, "nulls");
         return;
     }
     switch (typeof value) {
         case "number":
-            if (!seen.numbers) {
-                seen.numbers = true;
-                stats.numbers++;
-            }
+            countOnce(seen, "numbers", stats, "numbers");
             return;
         case "boolean":
-            if (!seen.booleans) {
-                seen.booleans = true;
-                stats.booleans++;
-            }
+            countOnce(seen, "booleans", stats, "booleans");
             return;
         case "string":
             return;
@@ -454,9 +459,8 @@ function inspectJson(value: unknown, stats: JsonStats, inArray: boolean, seen: S
             break;
     }
     if (Array.isArray(value)) {
-        if (inArray && !seen.nested) {
-            seen.nested = true;
-            stats.nestedArrays++;
+        if (inArray) {
+            countOnce(seen, "nested", stats, "nestedArrays");
         }
         for (const item of value) {
             inspectJson(item, stats, true, seen);
@@ -472,6 +476,29 @@ function inspectJson(value: unknown, stats: JsonStats, inArray: boolean, seen: S
     }
 }
 
+/**
+ * A row count in words.
+ * @param count - the count
+ * @returns the count and the word row, pluralised
+ */
+function rowCount(count: number): string {
+    return `${count} row${plural(count)}`;
+}
+
+/**
+ * Record a note for a counter that is not zero.
+ * @param notes - where to record
+ * @param count - the counter
+ * @param code - the note code
+ * @param text - the note message
+ * @param column - the column name
+ */
+function pushCounted(notes: LossNote[], count: number, code: string, text: string, column: string): void {
+    if (count > 0) {
+        notes.push(note(code, text, column, count));
+    }
+}
+
 /**
  * The GML-specific notes of one table's json columns.
  * @param columns - the written columns
@@ -487,73 +514,42 @@ function jsonNotes(columns: readonly WrittenColumn[], label: string, plan: GmlEx
         }
         const { name } = column.meta;
         const where = `${label} column "${name}"`;
-        if (stats.numbers > 0) {
-            notes.push(
-                note(
-                    RECORD_NUMBER_TYPE_CODE,
-                    `${where} holds numbers in ${stats.numbers} row${plural(stats.numbers)}; GML records cannot keep the int / real distinction`,
-                    name,
-                    stats.numbers,
-                ),
-            );
-        }
-        if (stats.booleans > 0) {
-            notes.push(
-                note(
-                    RECORD_BOOLEAN_CODE,
-                    `${where} holds booleans in ${stats.booleans} row${plural(stats.booleans)}; written as 1 / 0`,
-                    name,
-                    stats.booleans,
-                ),
-            );
-        }
-        if (stats.nulls > 0) {
-            notes.push(
-                note(
-                    RECORD_NULL_CODE,
-                    `${where} holds nulls in ${stats.nulls} row${plural(stats.nulls)}; GML has no null, the key is omitted`,
-                    name,
-                    stats.nulls,
-                ),
-            );
-        }
-        if (stats.arrays > 0) {
-            notes.push(
-                note(
-                    JSON_ARRAY_CODE,
-                    `${where} holds arrays as values in ${stats.arrays} row${plural(stats.arrays)}; written as repeated keys, they re-import as a list`,
-                    name,
-                    stats.arrays,
-                ),
-            );
-        }
-        if (stats.nestedArrays > 0) {
-            notes.push(
-                note(
-                    NESTED_ARRAY_CODE,
-                    `${where} holds arrays nested in arrays in ${stats.nestedArrays} row${plural(stats.nestedArrays)}; GML cannot write them and the save fails`,
-                    name,
-                    stats.nestedArrays,
-                ),
-            );
-        }
-        if (stats.invalidKeys > 0) {
-            notes.push(
-                plan.mangle
-                    ? note(
-                          KEY_MANGLED_CODE,
-                          `${where}: ${stats.invalidKeys} record key${plural(stats.invalidKeys)} ${agree(stats.invalidKeys, "is", "are")} not GML keys and are rewritten`,
-                          name,
-                          stats.invalidKeys,
-                      )
-                    : note(
-                          INVALID_KEY_CODE,
-                          `${where}: ${stats.invalidKeys} record key${plural(stats.invalidKeys)} ${agree(stats.invalidKeys, "is", "are")} not GML keys; the save fails unless sanitizeKeys is "mangle"`,
-                          name,
-                          stats.invalidKeys,
-                      ),
-            );
-        }
+        const counted = (count: number, code: string, text: string): void => {
+            pushCounted(notes, count, code, text, name);
+        };
+        counted(
+            stats.numbers,
+            RECORD_NUMBER_TYPE_CODE,
+            `${where} holds numbers in ${rowCount(stats.numbers)}; GML records cannot keep the int / real distinction`,
+        );
+        counted(
+            stats.booleans,
+            RECORD_BOOLEAN_CODE,
+            `${where} holds booleans in ${rowCount(stats.booleans)}; written as 1 / 0`,
+        );
+        counted(
+            stats.nulls,
+            RECORD_NULL_CODE,
+            `${where} holds nulls in ${rowCount(stats.nulls)}; GML has no null, the key is omitted`,
+        );
+        counted(
+            stats.arrays,
+            JSON_ARRAY_CODE,
+            `${where} holds arrays as values in ${rowCount(stats.arrays)}; written as repeated keys, they re-import as a list`,
+        );
+        counted(
+            stats.nestedArrays,
+            NESTED_ARRAY_CODE,
+            `${where} holds arrays nested in arrays in ${rowCount(stats.nestedArrays)}; GML cannot write them and the save fails`,
+        );
+        const keys = `${stats.invalidKeys} record key${plural(stats.invalidKeys)} ${agree(stats.invalidKeys, "is", "are")} not GML keys`;
+        counted(
+            stats.invalidKeys,
+            plan.mangle ? KEY_MANGLED_CODE : INVALID_KEY_CODE,
+            plan.mangle
+                ? `${where}: ${keys} and are rewritten`
+                : `${where}: ${keys}; the save fails unless sanitizeKeys is "mangle"`,
+        );
     }
 }