@graphty/graph-io 0.3.24 → 0.3.26

package/dist/src/formats/cx2/importer.js

@@ -20,47 +20,66 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareResolved, uniqueColumnName } from "../../common/attributes.js";
-import { ASPECT_ORDER_CODE, BAD_ASPECT_BLOCK_CODE, BAD_DEFAULT_CODE, BAD_VALUE_CODE, COLUMN_RENAMED_CODE, COUNT_MISMATCH_CODE, DANGLING_REFERENCE_CODE, DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, DUPLICATE_ATTRIBUTE_CODE, DUPLICATE_EDGE_ID_CODE, DUPLICATE_NODE_CODE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, ID_MERGED_CODE, ID_TEXT_TYPE_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MISSING_ENDPOINT_CODE, MISSING_ID_CODE, OPTION_IGNORED_CODE, PRECISION_CODE, ROLE_TAKEN_CODE, SINK_OPTION_CODE, STATUS_FAILED_CODE, STATUS_WARNING_CODE, STYLES_NOT_IMPORTED_CODE, SYNTAX_CODE, TOO_LARGE_CODE, UNKNOWN_ATTR_TYPE_CODE, UNKNOWN_ELEMENT_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
+import { ASPECT_ORDER_CODE, BAD_ASPECT_BLOCK_CODE, BAD_DEFAULT_CODE, BAD_VALUE_CODE, COLUMN_RENAMED_CODE, COUNT_MISMATCH_CODE, DANGLING_REFERENCE_CODE, DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, DUPLICATE_ATTRIBUTE_CODE, DUPLICATE_EDGE_ID_CODE, DUPLICATE_NODE_CODE, ELEMENT_ISSUE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, ID_MERGED_CODE, ID_TEXT_TYPE_CODE, INPUT_ISSUE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, JSON_NONSTANDARD_NUMBER_CODE, MISSING_ENDPOINT_CODE, MISSING_ID_CODE, MULTI_ASPECT_FRAGMENT_CODE, OPTION_IGNORED_CODE, PRECISION_CODE, ROLE_TAKEN_CODE, SINGLE_OBJECT_ASPECT_CODE, SINK_OPTION_CODE, STATUS_FAILED_CODE, STATUS_WARNING_CODE, STYLES_NOT_IMPORTED_CODE, SYNTAX_CODE, TOO_LARGE_CODE, UNKNOWN_ATTR_TYPE_CODE, UNKNOWN_ELEMENT_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
 import { IdCoercer } from "../../common/ids.js";
 import { textChunks, throwIfAborted } from "../../common/input.js";
-import { cxId, CxStructure, declareFresh, ExactInteger, flipY, inexactLiteral, isRecord, JsonScanError, plainJson, positionDecl, reportTooDeep, scanAspects, zDecl, } from "../../common/json-elements.js";
+import { cxId, CxStructure, declareFresh, ExactInteger, fitsF32, flipY, headText, inexactLiteral, isRecord, JsonScanError, keptPrecision, plainJson, positionDecl, reportSharedBlock, reportTooDeep, scanAspects, setOwn, zDecl, } from "../../common/json-elements.js";
 import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { weightFromValue } from "../../common/weights.js";
-/** The format name. */
+/**
+ * The format name.
+ * @category Plugin helpers
+ */
 export const CX2_FORMAT = "cx2";
-/** The node attribute the exporter's `sanitizeIds: "mangle"` keeps an original id in. */
+/**
+ * The node attribute the exporter's `sanitizeIds: "mangle"` keeps an original id in.
+ * @category Plugin helpers
+ */
 export const ORIGINAL_ID_ATTRIBUTE = "graphty:originalId";
-/** The origin namespace of the per-element visual property columns. */
+/**
+ * The origin namespace of the per-element visual property columns.
+ * @category Plugin helpers
+ */
 export const BYPASS_NAMESPACE = "cx2.bypass";
 /**
- * The issue codes the CX2 importer records (design section 1.3), by name: the codes shared with
- * the other importers (src/common/codes.ts) and the CX2-specific ones. A key is the code without
+ * The issue codes the CX2 importer records, by name: the codes shared with
+ * the other importers and the CX2-specific ones. A key is the code without
  * its severity and format prefixes.
+ * @category Built-in formats
  */
 export const CX2_ISSUE = Object.freeze({
-    /** The input is empty (fatal). */
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /** The input is empty. The import stops. */
     EMPTY_INPUT: EMPTY_INPUT_CODE,
-    /** The text is not JSON (fatal). */
+    /** The text is not valid JSON. The import stops. */
     SYNTAX: SYNTAX_CODE,
-    /** Invalid UTF-8 (fatal). */
+    /** The input is not valid UTF-8. The import stops. */
     INVALID_UTF8: INVALID_UTF8_CODE,
-    /** Invalid bytes in the encoding a BOM or the encoding option chose (fatal). */
+    /**
+     * Some bytes are not valid in the encoding that was chosen (by a byte order mark or the `encoding` option). The
+     * import stops.
+     */
     INVALID_ENCODING: INVALID_ENCODING_CODE,
     /** Bytes that are not UTF-8 were read as windows-1252. */
     ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
     /** An encoding the platform cannot decode was ignored. */
     UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
-    /** The document is not an array or does not start with a descriptor holding CXVersion (fatal). */
+    /**
+     * The document is not a JSON array, or its first element is not the CX2 descriptor with `CXVersion`. The import
+     * stops.
+     */
     NO_DESCRIPTOR: "E_CX2_NO_DESCRIPTOR",
-    /** CXVersion names a major version other than 2 (fatal); "1.x" says the file is CX1. */
+    /** `CXVersion` names a version other than 2 ("1.x" means the file is CX1; read it as `cx`). The import stops. */
     VERSION: "E_CX2_VERSION",
     /** CXVersion is a 2.x other than "2.0" (or not a string); the document is read. */
     MINOR_VERSION: "W_CX2_MINOR_VERSION",
     /** The document has no status block, or a malformed one. */
     NO_STATUS: "E_CX2_NO_STATUS",
-    /** The producer marked the document as failed (fatal). */
+    /** The program that wrote the file marked it as failed, so it is incomplete. The import stops. */
     STATUS_FAILED: STATUS_FAILED_CODE,
     /** The producer marked the document as successful with an error text. */
     STATUS_WARNING: STATUS_WARNING_CODE,
@@ -84,9 +103,18 @@ export const CX2_ISSUE = Object.freeze({
     ALIAS_BYPASSED: "W_CX2_ALIAS_BYPASSED",
     /** A CX1 cartesianLayout aspect next to node coordinates; kept, not applied. */
     LEGACY_LAYOUT: "W_CX2_LEGACY_LAYOUT",
-    /** The file's style rules are not applied (issue #706). */
+    /** An aspect CX2 defines as an array of elements written as one object; read as one element. */
+    SINGLE_OBJECT_ASPECT: SINGLE_OBJECT_ASPECT_CODE,
+    /** A member holding several aspects; each array-valued key is read as its own block. */
+    MULTI_ASPECT_FRAGMENT: MULTI_ASPECT_FRAGMENT_CODE,
+    /** The bare tokens NaN / Infinity / -Infinity (Python's json writes them), read as numbers. */
+    JSON_NONSTANDARD_NUMBER: JSON_NONSTANDARD_NUMBER_CODE,
+    /** The file's style rules are not applied; they are kept so a CX2 export writes them back. */
     STYLES_NOT_IMPORTED: STYLES_NOT_IMPORTED_CODE,
-    /** A member of the top-level array that is not a one-key aspect block, or an element that is not an object. */
+    /**
+     * A member of the file's top-level array that is not a block with one key (`{"nodes": [...]}`), or an element of a
+     * block that is not an object. It is skipped; the rest of the file is read.
+     */
     BAD_ASPECT_BLOCK: BAD_ASPECT_BLOCK_CODE,
     /** An aspect out of its place (after the post-metadata or the status, a third metaData, late declarations). */
     ASPECT_ORDER: ASPECT_ORDER_CODE,
@@ -118,25 +146,37 @@ export const CX2_ISSUE = Object.freeze({
     INVALID_WEIGHT: "E_INVALID_WEIGHT",
     /** An id spelled as a string or a non-integer literal; read as the integer. */
     ID_TEXT_TYPE: ID_TEXT_TYPE_CODE,
-    /** An integer beyond 2^53: an id kept as its digits, a value stored as the nearest f64. */
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
     PRECISION: PRECISION_CODE,
     /** Two id texts merged under `ids: "number"`. */
     ID_MERGED: ID_MERGED_CODE,
     /** An element key CX2 does not define. */
     UNKNOWN_ELEMENT: UNKNOWN_ELEMENT_CODE,
-    /** A column renamed because its name was taken. */
+    /**
+     * An attribute was renamed `<name>#<suffix>` because another attribute already has its name, for example
+     * two attributes declared with the same name.
+     */
     COLUMN_RENAMED: COLUMN_RENAMED_CODE,
-    /** A column that lost its role because another column holds it. */
+    /**
+     * You read into a graph builder that already has an id, label or position attribute, so this file's one is kept as
+     * a plain attribute.
+     */
     ROLE_TAKEN: ROLE_TAKEN_CODE,
-    /** The sink refused the direction. */
+    /**
+     * You read into a graph builder whose direction is already set, or which already holds edges, so the file is read
+     * with the builder's direction instead of its own.
+     */
     DIRECTION_REFUSED: DIRECTION_REFUSED_CODE,
-    /** Edges forced to the policy's direction. */
+    /** Edges of the other direction were read with the direction `onMixedDirection` chose. */
     DIRECTION_FORCED: DIRECTION_FORCED_CODE,
-    /** A common option CX2 has no use for. */
+    /** You set an option this format does not use; it had no effect. The message names the option. */
     OPTION_IGNORED: OPTION_IGNORED_CODE,
-    /** A builder option the caller's sink does not honour. */
+    /**
+     * You read into your own graph builder, which was created with a different `addMissingNodes`, `duplicateEdges`,
+     * `selfLoops` or `weightDtype` than the option you passed; the builder's setting applies.
+     */
     SINK_OPTION: SINK_OPTION_CODE,
-    /** The input is beyond a size limit (fatal). */
+    /** The input is larger than graph-io's size limit. The import stops. */
     TOO_LARGE: TOO_LARGE_CODE,
 });
 const USED_OPTIONS = new Set([
@@ -177,26 +217,38 @@ const STYLE_ASPECTS = [
 ];
 /** The aspects the stream structure owns; never kept as opaque. */
 const STRUCTURE_ASPECTS = new Set(["metaData", "status"]);
+/** The aspects CX2 defines as an array of elements, which a reader expects in that form. */
+const ARRAY_ASPECTS = new Set([
+    "nodes",
+    "edges",
+    "attributeDeclarations",
+    "networkAttributes",
+    "nodeBypasses",
+    "edgeBypasses",
+    "status",
+    "metaData",
+]);
 /** The type spellings CX2 defines, plus the Python spellings ndex2 writes. */
-const SCALARS = {
-    string: "string",
-    long: "long",
-    integer: "integer",
-    double: "double",
-    boolean: "boolean",
-    str: "string",
-    int: "integer",
-    bool: "boolean",
-    float: "double",
-};
+const SCALARS = new Map([
+    ["string", "string"],
+    ["long", "long"],
+    ["integer", "integer"],
+    ["double", "double"],
+    ["boolean", "boolean"],
+    ["str", "string"],
+    ["int", "integer"],
+    ["bool", "boolean"],
+    ["float", "double"],
+]);
 /**
  * Resolve a declared type text.
  * @param d - the `d` value
  * @returns the type, or null when CX2 does not define it
+ * @category Plugin helpers
  */
 export function cx2Type(d) {
     const list = d.startsWith("list_of_");
-    const scalar = SCALARS[list ? d.slice("list_of_".length) : d];
+    const scalar = SCALARS.get(list ? d.slice("list_of_".length) : d);
     if (scalar === undefined) {
         return null;
     }
@@ -246,6 +298,7 @@ function convertScalar(value, scalar, long, onPrecision) {
             return typeof value === "boolean" ? value : BAD;
         case "double":
             if (value instanceof ExactInteger) {
+                onPrecision(value.digits);
                 return Number(value.digits);
             }
             return typeof value === "number" ? value : BAD;
@@ -316,15 +369,16 @@ function shown(value) {
  * The inexact-literal bits of an element.
  * @param text - the element's JSON text
  * @param keys - the id keys to check, bit 1, 2, 4 in order
+ * @param depth - the depth of the element's own keys in the text (2: a member's single object)
  * @returns the bits
  */
-function inexactBits(text, keys) {
+function inexactBits(text, keys, depth = 1) {
     if (!/[0-9][.eE]/.test(text)) {
         return 0;
     }
     let bits = 0;
     keys.forEach((key, i) => {
-        if (inexactLiteral(text, key)) {
+        if (inexactLiteral(text, key, depth)) {
             bits |= 1 << i;
         }
     });
@@ -355,22 +409,24 @@ async function readDocument(input, report, options) {
     let descriptor = false;
     let elementsSeen = false;
     let sinceCheck = 0;
-    const collect = (aspect, value, text, line, exact) => {
+    const opaquePrecision = keptPrecision(report, "meta.extra.cx2.opaque");
+    const collect = (aspect, value, text, line, exact, depth = 1) => {
         structure.element(aspect, value, line);
         switch (aspect) {
             case "nodes":
                 elementsSeen = true;
-                doc.nodes.push({ value, line, inexact: inexactBits(text, ["id"]) });
+                doc.nodes.push({ value, line, inexact: inexactBits(text, ["id"], depth) });
                 return;
             case "edges":
                 elementsSeen = true;
-                doc.edges.push({ value, line, inexact: inexactBits(text, ["id", "s", "t"]) });
+                doc.edges.push({ value, line, inexact: inexactBits(text, ["id", "s", "t"], depth) });
                 return;
             case "attributeDeclarations":
                 if (elementsSeen) {
                     report.warnOnce("validation-error", ASPECT_ORDER_CODE, "attributeDeclarations comes after the elements it types; the declarations are applied to them", { line, element: aspect }, `${ASPECT_ORDER_CODE}:declarations`);
                 }
-                doc.declarations.push({ value: plainJson(value), line, inexact: 0 });
+                // not plainJson(): a long default beyond 2^53 keeps its digits for long: "string"
+                doc.declarations.push({ value, line, inexact: 0 });
                 return;
             case "networkAttributes":
                 elementsSeen = true;
@@ -392,18 +448,18 @@ async function readDocument(input, report, options) {
                 if (!doc.opaque.has(aspect)) {
                     doc.opaque.set(aspect, []);
                 }
-                doc.opaque.get(aspect)?.push(exact ? plainJson(value, () => undefined) : value);
+                doc.opaque.get(aspect)?.push(exact ? plainJson(value, opaquePrecision) : value);
         }
     };
     try {
-        for await (const event of scanAspects(textChunks(input, report, options))) {
+        for await (const event of scanAspects(textChunks(input, report, options), report)) {
             if (++sinceCheck >= ABORT_CHECK_INTERVAL) {
                 sinceCheck = 0;
                 throwIfAborted(options.signal);
             }
             switch (event.kind) {
                 case "root":
-                    report.fail(CX2_ISSUE.NO_DESCRIPTOR, `a CX2 document is a JSON array; found ${isRecord(event.value) ? "an object" : shown(event.value)}`, { line: event.line });
+                    report.fail(CX2_ISSUE.NO_DESCRIPTOR, `a CX2 document is a JSON array; found ${event.object ? "an object" : shown(event.value)}`, { line: event.line });
                     break;
                 case "member":
                     if (!descriptor) {
@@ -412,10 +468,11 @@ async function readDocument(input, report, options) {
                         break;
                     }
                     memberAspect(event.value, event.line, structure, report, (aspect, value) => {
-                        collect(aspect, value, JSON.stringify(value) ?? "", event.line, event.exact);
+                        collect(aspect, value, event.text, event.line, event.exact, 2);
                     });
                     break;
                 case "block":
+                    reportSharedBlock(report, event);
                     if (!descriptor) {
                         report.fail(CX2_ISSUE.NO_DESCRIPTOR, `the document starts with a "${event.aspect}" block, not a descriptor with CXVersion${event.aspect === "numberVerification" || event.aspect === "metaData" ? "; this looks like CX version 1 (read it with the cx importer)" : ""}`, { line: event.line });
                     }
@@ -431,7 +488,7 @@ async function readDocument(input, report, options) {
                     }
                     break;
                 case "extraKeys":
-                    report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `the "${event.aspect}" block holds more keys (${event.keys.join(", ")}); an aspect block has one key, the others are skipped`, { line: event.line, element: event.aspect });
+                    report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `the "${event.aspect}" block holds more keys (${event.keys.join(", ")}) whose values are not arrays; an aspect block has one key, the others are skipped`, { line: event.line, element: event.aspect });
                     break;
                 default:
                     break;
@@ -463,7 +520,8 @@ function readDescriptor(value, line, doc, report) {
     }
     const raw = value.CXVersion;
     const text = typeof raw === "string" || typeof raw === "number" ? String(raw) : "";
-    const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(text);
+    // the major version: "2.0", "2.1", "2.0.1", "2.1-beta", " 2.0" are all CX2
+    const match = /^\s*(\d+)(?=$|[.\s-])/.exec(text);
     const major = match === null ? NaN : Number(match[1]);
     if (major === 1) {
         report.fail(CX2_ISSUE.VERSION, `CXVersion ${shown(raw)} is CX version 1, a different document shape; read it with the cx importer`, { line, element: "CXVersion" });
@@ -504,6 +562,9 @@ function readDescriptor(value, line, doc, report) {
 function memberAspect(value, line, structure, report, collect) {
     const keys = isRecord(value) ? Object.keys(value) : [];
     if (isRecord(value) && keys.length === 1 && isRecord(value[keys[0]])) {
+        if (ARRAY_ASPECTS.has(keys[0])) {
+            report.warning("validation-error", CX2_ISSUE.SINGLE_OBJECT_ASPECT, `the "${keys[0]}" aspect is one object, not an array of elements; read as one element`, { line, element: keys[0] });
+        }
         structure.block(keys[0], line);
         collect(keys[0], value[keys[0]]);
         return;
@@ -596,7 +657,20 @@ class DeclarationTable {
     }
 }
 /** The domain key of attributeDeclarations for each table. */
-const DECLARATION_KEYS = { nodes: "node", edges: "edge", networkAttributes: "network" };
+const DECLARATION_KEYS = new Map([
+    ["nodes", "node"],
+    ["edges", "edge"],
+    ["networkAttributes", "network"],
+]);
+/**
+ * Whether an object has an own property (never one of Object.prototype, as `in` would find).
+ * @param record - the object
+ * @param key - the key
+ * @returns true for an own property
+ */
+function hasOwn(record, key) {
+    return Object.hasOwn(record, key);
+}
 // ============================================================ the build
 /** Reads a collected document into a sink. */
 class Cx2Reader {
@@ -619,6 +693,8 @@ class Cx2Reader {
         this.nodeRows = new Map();
         /** CX node id -> the id the sink holds it under (differs when a mangled id is restored). */
         this.sinkIds = new Map();
+        /** The original ids restored so far: a second node with one keeps its CX id. */
+        this.restored = new Set();
         /** CX edge id -> sink edge index. */
         this.edgeRows = new Map();
         this.positionHandle = INVALID_INDEX;
@@ -651,7 +727,7 @@ class Cx2Reader {
         }
         this.readLegacyLayout();
         if (this.positioned.size > 0 && this.positioned.size < this.nodeRows.size) {
-            report.warnOnce("missing-value", CX2_ISSUE.PARTIAL_LAYOUT, `${this.nodeRows.size - this.positioned.size} of ${this.nodeRows.size} node(s) have no coordinates; their positions are unset`, { element: "nodes" });
+            report.warnOnce("missing-value", CX2_ISSUE.PARTIAL_LAYOUT, `${this.nodeRows.size - this.positioned.size} of ${this.nodeRows.size} node${plural(this.nodeRows.size)} ${agree(this.nodeRows.size - this.positioned.size, "has", "have")} no coordinates; their positions are unset`, { element: "nodes" });
         }
         for (const held of doc.edges) {
             this.readEdge(held);
@@ -660,7 +736,7 @@ class Cx2Reader {
         this.readBypasses("node", doc.nodeBypasses);
         this.readBypasses("edge", doc.edgeBypasses);
         for (const [kind, count] of this.dangling) {
-            report.warning("validation-error", DANGLING_REFERENCE_CODE, `${count} ${kind} name(s) no element; ignored`, { element: kind });
+            report.warning("validation-error", DANGLING_REFERENCE_CODE, `${count} ${kind}${plural(count)} ${agree(count, "names", "name")} no element; ignored`, { element: kind });
         }
         this.checkAspects();
         this.setMeta();
@@ -678,9 +754,12 @@ class Cx2Reader {
                 continue;
             }
             for (const [key, table] of Object.entries(held.value)) {
-                const domain = DECLARATION_KEYS[key];
+                const domain = DECLARATION_KEYS.get(key);
                 if (domain === undefined) {
-                    this.decls.other[key] = table;
+                    report.warning("unsupported", UNKNOWN_ELEMENT_CODE, `attributeDeclarations holds the table "${key}", which CX2 does not define; kept in meta.extra.cx2.declarations, not applied`, { line: held.line, element: key });
+                    setOwn(this.decls.other, key, plainJson(table, (digits) => {
+                        this.precision(key, digits);
+                    }));
                     continue;
                 }
                 if (!isRecord(table)) {
@@ -713,7 +792,10 @@ class Cx2Reader {
             }
             for (const [key, raw] of Object.entries(value.v)) {
                 const resolved = table.resolve(key);
-                if ((resolved !== null && resolved.decl.type !== null) || raw === null || raw === undefined) {
+                if (key === "" ||
+                    (resolved !== null && resolved.decl.type !== null) ||
+                    raw === null ||
+                    raw === undefined) {
                     continue;
                 }
                 const name = resolved?.decl.name ?? key;
@@ -760,6 +842,10 @@ class Cx2Reader {
         const { report } = this;
         const table = this.decls[domain];
         const where = { line, element: name };
+        if (name === "") {
+            report.error("validation-error", BAD_VALUE_CODE, `a ${domain} attribute declaration has an empty name; ignored`, where);
+            return;
+        }
         if (!isRecord(raw)) {
             report.error("validation-error", BAD_VALUE_CODE, `the declaration of "${name}" is not an object; ignored`, where);
             return;
@@ -782,6 +868,9 @@ class Cx2Reader {
             }
             return;
         }
+        if (raw.a !== undefined && raw.a !== null && typeof raw.a !== "string") {
+            report.error("validation-error", BAD_VALUE_CODE, `the alias ${shown(raw.a)} of "${name}" is not a string; ignored`, where);
+        }
         let alias = typeof raw.a === "string" ? raw.a : null;
         let hasDefault = raw.v !== undefined && raw.v !== null;
         if (domain === "network" && (raw.a !== undefined || raw.v !== undefined)) {
@@ -817,7 +906,9 @@ class Cx2Reader {
      * @returns the default, or BAD when dropped
      */
     convertDefault(name, value, type, where) {
-        const converted = convertValue(value, type, this.options.long, () => undefined);
+        const converted = convertValue(value, type, this.options.long, (digits) => {
+            this.precision(name, digits);
+        });
         if (converted !== BAD) {
             return converted;
         }
@@ -922,28 +1013,29 @@ class Cx2Reader {
      * @param raw - the parsed id
      * @param inexact - whether the literal was not a plain integer
      * @param element - the element name for issues
+     * @param line - the element's line
      * @param edgeId - whether this is an edge's own id (stored in the f64 id column, not kept as digits)
      * @returns the id, or null when it was reported
      */
-    idOf(raw, inexact, element, edgeId = false) {
+    idOf(raw, inexact, element, line, edgeId = false) {
         let id;
         try {
             const parsed = cxId(raw, inexact);
             if (parsed.note === "text") {
-                this.report.warnOnce("coercion", ID_TEXT_TYPE_CODE, `${element}: the id ${shown(raw)} is not written as an integer; read as ${String(parsed.id)}`, { element });
+                this.report.warnOnce("coercion", ID_TEXT_TYPE_CODE, `${element}: the id ${shown(raw)} is not written as an integer; read as ${String(parsed.id)}`, { line, element });
             }
             else if (parsed.note === "precision" && edgeId) {
                 // the edge is told apart by its digits, but the id column is f64
-                this.report.warnOnce("precision", PRECISION_CODE, `${element}: the edge id ${String(parsed.id)} is beyond 2^53; the id column holds the nearest double`, { element }, `${PRECISION_CODE}:edge`);
+                this.report.warnOnce("precision", PRECISION_CODE, `${element}: the edge id ${String(parsed.id)} is beyond 2^53; the id column holds the nearest double`, { line, element }, `${PRECISION_CODE}:edge`);
             }
             else if (parsed.note === "precision") {
                 this.idType = "mixed";
-                this.report.warnOnce("precision", PRECISION_CODE, `${element}: the id ${String(parsed.id)} is beyond 2^53; kept as its digits (a string id)`, { element });
+                this.report.warnOnce("precision", PRECISION_CODE, `${element}: the id ${String(parsed.id)} is beyond 2^53; kept as its digits (a string id)`, { line, element });
             }
             id = this.options.ids === "keep" ? parsed.id : this.coercer.value(parsed.id);
         }
         catch (err) {
-            this.report.recordError(err, { element });
+            this.report.recordError(err, { line, element });
             return null;
         }
         return id;
@@ -995,7 +1087,7 @@ class Cx2Reader {
             return;
         }
         const element = `node ${shown(value.id)}`;
-        const cx = this.idOf(value.id, (held.inexact & 1) !== 0, element);
+        const cx = this.idOf(value.id, (held.inexact & 1) !== 0, element, line);
         if (cx === null) {
             report.counts.skippedNodes++;
             return;
@@ -1012,7 +1104,14 @@ class Cx2Reader {
             report.warning("merged", DUPLICATE_NODE_CODE, `${element} is declared more than once; its attributes are merged (the later values win)`, { line, element });
         }
         else {
-            const original = this.originalIdOf(attrs);
+            let original = this.originalIdOf(attrs, element, line);
+            if (original !== null && this.restored.has(original)) {
+                report.warning("merged", DUPLICATE_NODE_CODE, `${element}: its original id ${shown(original)} is already another node's; it keeps its CX id`, { line, element });
+                original = null;
+            }
+            if (original !== null) {
+                this.restored.add(original);
+            }
             this.idTypeOf(original ?? cx);
             try {
                 row = sink.addNode(original ?? cx);
@@ -1034,14 +1133,19 @@ class Cx2Reader {
     /**
      * The original id the exporter's `sanitizeIds: "mangle"` kept, when it is to be restored.
      * @param attrs - the node's v
+     * @param element - the element name for issues
+     * @param line - its line
      * @returns the original id, or null
      */
-    originalIdOf(attrs) {
+    originalIdOf(attrs, element, line) {
         if (attrs === null || !this.options.restoreMangledIds) {
             return null;
         }
         const alias = this.decls.node.byName.get(ORIGINAL_ID_ATTRIBUTE)?.alias ?? null;
         const raw = attrs[ORIGINAL_ID_ATTRIBUTE] ?? (alias === null ? undefined : attrs[alias]);
+        if (raw !== undefined && raw !== null && typeof raw !== "string") {
+            this.report.error("validation-error", BAD_VALUE_CODE, `${element}: ${ORIGINAL_ID_ATTRIBUTE} is ${shown(raw)}, not a string; the node keeps its CX id`, { line, element });
+        }
         return typeof raw === "string" ? raw : null;
     }
     /**
@@ -1085,7 +1189,10 @@ class Cx2Reader {
             // the specification requires x and y with z
             this.report.warnOnce("missing-value", CX2_ISSUE.PARTIAL_LAYOUT, `${element} has z without x and y; ${this.zAs === "column" ? "z is kept in the z column" : "with no position, z is dropped"}`, { line, element }, `${CX2_ISSUE.PARTIAL_LAYOUT}:z`);
         }
-        if (x !== null && y !== null) {
+        if (x !== null && y !== null && (!fitsF32(x) || !fitsF32(y))) {
+            this.report.error("validation-error", BAD_VALUE_CODE, `${element}: the coordinates ${String(x)}, ${String(y)} are beyond what the f32 position column holds; the position is unset`, { line, element });
+        }
+        else if (x !== null && y !== null) {
             this.setPosition(row, x, y, z);
         }
         if (z !== null && this.zAs === "column") {
@@ -1120,9 +1227,12 @@ class Cx2Reader {
         }
         if (this.positioned.size > 0) {
             this.doc.opaque.set("cartesianLayout", cartesianLayout.map((h) => plainJson(h.value)));
-            this.report.warning("unsupported", CX2_ISSUE.LEGACY_LAYOUT, `a CX1 cartesianLayout aspect (${cartesianLayout.length} element(s)) next to node coordinates; the node coordinates are used, the aspect is kept in meta.extra.cx2`, { element: "cartesianLayout" });
+            this.report.warning("unsupported", CX2_ISSUE.LEGACY_LAYOUT, `a CX1 cartesianLayout aspect (${cartesianLayout.length} element${plural(cartesianLayout.length)}) next to node coordinates; the node coordinates are used, the aspect is kept in meta.extra.cx2`, { element: "cartesianLayout" });
             return;
         }
+        // the first view named is the layout; a CX1 file with several views keeps the others
+        let view;
+        const seen = new Set();
         for (const held of cartesianLayout) {
             const entry = held.value;
             if (!isRecord(entry) || typeof entry.x !== "number" || typeof entry.y !== "number") {
@@ -1134,6 +1244,16 @@ class Cx2Reader {
                 this.dangle("cartesianLayout entry");
                 continue;
             }
+            view ?? (view = entry.view ?? null);
+            if ((entry.view ?? null) !== view) {
+                this.doc.opaque.set("cartesianLayout", cartesianLayout.map((h) => plainJson(h.value)));
+                this.report.warnOnce("validation-error", DUPLICATE_ATTRIBUTE_CODE, `the cartesianLayout aspect names several views; view ${shown(view)} is read, the aspect is kept in meta.extra.cx2`, { line: held.line, element: "cartesianLayout" }, `${DUPLICATE_ATTRIBUTE_CODE}:layout:view`);
+                continue;
+            }
+            if (seen.has(row)) {
+                this.report.warnOnce("validation-error", DUPLICATE_ATTRIBUTE_CODE, `node ${shown(entry.node)} has two cartesianLayout entries; the later wins`, { line: held.line, element: "cartesianLayout" }, `${DUPLICATE_ATTRIBUTE_CODE}:layout`);
+            }
+            seen.add(row);
             const z = typeof entry.z === "number" ? entry.z : null;
             this.setPosition(row, entry.x, entry.y, z);
             if (z !== null && this.zAs === "column") {
@@ -1180,6 +1300,10 @@ class Cx2Reader {
         const table = this.decls[domain];
         for (const key of Object.keys(attrs)) {
             const value = attrs[key];
+            if (key === "") {
+                report.error("validation-error", BAD_VALUE_CODE, `${element}: v holds an attribute with an empty name; skipped`, { line, element });
+                continue;
+            }
             const resolved = table.resolve(key);
             const name = resolved?.decl.name ?? key;
             if (domain === "node" && this.options.restoreMangledIds && name === ORIGINAL_ID_ATTRIBUTE) {
@@ -1195,7 +1319,7 @@ class Cx2Reader {
                 !resolved.viaAlias &&
                 resolved.decl.alias !== null &&
                 resolved.decl.alias !== key) {
-                if (resolved.decl.alias in attrs) {
+                if (hasOwn(attrs, resolved.decl.alias)) {
                     report.warning("validation-error", DUPLICATE_ATTRIBUTE_CODE, `${element}: "${name}" is given under its alias and its full name; the alias wins`, { line, element });
                     continue;
                 }
@@ -1274,9 +1398,9 @@ class Cx2Reader {
                 return;
             }
         }
-        const id = this.idOf(value.id, (held.inexact & 1) !== 0, element, true);
-        const s = id === null ? null : this.idOf(value.s, (held.inexact & 2) !== 0, element);
-        const t = s === null ? null : this.idOf(value.t, (held.inexact & 4) !== 0, element);
+        const id = this.idOf(value.id, (held.inexact & 1) !== 0, element, line, true);
+        const s = id === null ? null : this.idOf(value.s, (held.inexact & 2) !== 0, element, line);
+        const t = s === null ? null : this.idOf(value.t, (held.inexact & 4) !== 0, element, line);
         if (id === null || s === null || t === null) {
             report.counts.skippedEdges++;
             return;
@@ -1293,6 +1417,12 @@ class Cx2Reader {
             return;
         }
         const attrs = isRecord(value.v) ? value.v : null;
+        if (value.v !== undefined && value.v !== null && attrs === null) {
+            report.error("validation-error", BAD_VALUE_CODE, `${element}: v is ${shown(value.v)}, not an object`, {
+                line,
+                element,
+            });
+        }
         let weight;
         const weightKey = this.weightKey(attrs);
         try {
@@ -1334,10 +1464,10 @@ class Cx2Reader {
             return null;
         }
         const alias = this.decls.edge.byName.get(weightFrom)?.alias ?? null;
-        if (alias !== null && alias in attrs) {
+        if (alias !== null && hasOwn(attrs, alias)) {
             return alias;
         }
-        return weightFrom in attrs ? weightFrom : null;
+        return hasOwn(attrs, weightFrom) ? weightFrom : null;
     }
     /**
      * The sink id of an edge endpoint: a known node, or a node created under addMissingNodes.
@@ -1455,13 +1585,27 @@ class Cx2Reader {
                 if (raw === null || raw === undefined) {
                     continue;
                 }
+                if (property === "") {
+                    this.report.error("validation-error", BAD_VALUE_CODE, `a ${domain}Bypasses element holds a visual property with an empty name; skipped`, { line, element: `${domain}Bypasses` });
+                    continue;
+                }
                 let column = columns.get(property);
                 if (column === undefined) {
-                    column = { rows: [], values: [] };
+                    column = { rows: [], values: [], at: new Map() };
                     columns.set(property, column);
                 }
-                column.rows.push(row);
-                column.values.push(plainJson(raw));
+                const plain = plainJson(raw);
+                const index = column.at.get(row);
+                if (index === undefined) {
+                    column.at.set(row, column.rows.length);
+                    column.rows.push(row);
+                    column.values.push(plain);
+                    continue;
+                }
+                if (JSON.stringify(column.values[index]) !== JSON.stringify(plain)) {
+                    this.report.warnOnce("validation-error", DUPLICATE_ATTRIBUTE_CODE, `a ${domain} has the visual property "${property}" in two ${domain}Bypasses elements; the later wins`, { line, element: property }, `${DUPLICATE_ATTRIBUTE_CODE}:bypass:${domain}:${property}`);
+                }
+                column.values[index] = plain;
             }
         }
         for (const [property, { rows: targets, values }] of columns) {
@@ -1496,7 +1640,7 @@ class Cx2Reader {
             }
         }
         if (styles.length > 0) {
-            report.warning("unsupported", STYLES_NOT_IMPORTED_CODE, `the file's style rules are not applied (${styles.join("; ")}); they are kept in meta.extra.cx2.opaque (style import is issue #706)`, { element: STYLE_ASPECTS.filter((a) => doc.opaque.has(a)).join(",") });
+            report.warning("unsupported", STYLES_NOT_IMPORTED_CODE, `the file's style rules are not applied (${styles.join("; ")}); they are kept in meta.extra.cx2.opaque`, { element: STYLE_ASPECTS.filter((a) => doc.opaque.has(a)).join(",") });
         }
         for (const aspect of SINGLE_ELEMENT_ASPECTS.slice(1)) {
             const count = doc.opaque.get(aspect)?.length ?? 0;
@@ -1590,14 +1734,15 @@ function describeStyle(aspect, elements) {
         const defaults = isRecord(first.default)
             ? Object.values(first.default).reduce((n, v) => n + (isRecord(v) ? Object.keys(v).length : 0), 0)
             : 0;
-        return `visualProperties: ${defaults} default(s), ${count("nodeMapping")} node mapping(s), ${count("edgeMapping")} edge mapping(s)`;
+        return `visualProperties: ${defaults} default${plural(defaults)}, ${count("nodeMapping")} node mapping${plural(count("nodeMapping"))}, ${count("edgeMapping")} edge mapping${plural(count("edgeMapping"))}`;
     }
-    return `${aspect}: ${elements.length} element(s)`;
+    return `${aspect}: ${elements.length} element${plural(elements.length)}`;
 }
 /**
  * Resolve the zAs option.
  * @param value - the option
  * @returns the mode; E_UNSUPPORTED for any other value
+ * @category Plugin helpers
  */
 export function zAsOption(value) {
     if (value === undefined) {
@@ -1612,10 +1757,12 @@ export function zAsOption(value) {
     });
 }
 /**
- * The CX2 importer plugin (design section 1.3).
+ * The CX2 importer plugin.
+ * @category Built-in formats
  */
 export const cx2Importer = Object.freeze({
     format: CX2_FORMAT,
+    options: Object.freeze(["zAs"]),
     extensions: Object.freeze([".cx2"]),
     mimeTypes: Object.freeze(["application/json"]),
     /**
@@ -1625,7 +1772,7 @@ export const cx2Importer = Object.freeze({
      * @returns the confidence
      */
     sniff(head) {
-        const text = new TextDecoder("utf-8").decode(head.subarray(0, 1024)).replace(/^\uFEFF/, "");
+        const text = headText(head);
         return /^\s*\[\s*\{(?:\s*"[^"]*"\s*:\s*(?:true|false|"[^"]*"|[0-9.]+)\s*,)*\s*"CXVersion"\s*:/.test(text)
             ? 0.97
             : 0;