@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/gml/importer.ts

@@ -8,7 +8,7 @@
  * every node block first, then every edge block, so node indices follow the file's node order
  * and forward edge references resolve.
  *
- * Conventions honoured: NetworkX's `_networkx_list_start` marker and `"[]"` empty lists, `&#NN;`
+ * Conventions honored: NetworkX's `_networkx_list_start` marker and `"[]"` empty lists, `&#NN;`
  * character references in strings, `Creator` / `Version` top-level metadata, `directed 0|1` and
  * `multigraph 0|1` graph flags, comments, keys and values on one line or split across lines, and
  * a `graphics [ x y z ]` node record mapped to the `position` role (note 07 section 9) with the
@@ -35,6 +35,7 @@ import {
 } from "@graphty/graph-format";
 
 import { declareResolved, DictHeuristic, uniqueColumnName } from "../../common/attributes.js";
+import { importChosenGraph } from "../../common/choose.js";
 import {
     COLUMN_RENAMED_CODE,
     DUPLICATE_NODE_CODE as SHARED_DUPLICATE_NODE_CODE,
@@ -44,20 +45,29 @@ import {
     NO_GRAPH_CODE as SHARED_NO_GRAPH_CODE,
     PRECISION_CODE as SHARED_PRECISION_CODE,
     ROLE_TAKEN_CODE as SHARED_ROLE_TAKEN_CODE,
+    WIDENED_CODE as SHARED_WIDENED_CODE,
 } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
 import { IdCoercer } from "../../common/ids.js";
 import { readText, throwIfAborted } from "../../common/input.js";
 import {
+    graphChosen,
     type ImportFormatDefaults,
     reportSinkOptions,
     reportUnusedOptions,
     type ResolvedImportOptions,
     resolveImportOptions,
 } from "../../common/options.js";
+import { plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
-import { parseWeightText, weightFromValue } from "../../common/weights.js";
-import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
+import { parseWeightText, reportWeightPrecision, weightFromValue } from "../../common/weights.js";
+import {
+    type CommonImportOptions,
+    type GraphChoiceOptions,
+    type GraphImporter,
+    type ImportInput,
+    type ImportReport,
+} from "../../types.js";
 import {
     EMPTY_LIST_TEXT,
     EMPTY_TUPLE_TEXT,
@@ -76,53 +86,141 @@ import {
     tokenizeGml,
 } from "./syntax.js";
 
-/** The format-specific options of the GML importer. */
-export interface GmlImportOptions {
+/**
+ * The format-specific options of the GML importer.
+ * @category Built-in formats
+ */
+export interface GmlImportOptions extends GraphChoiceOptions, CommonImportOptions {
     /**
-     * Map a node's `graphics [ x y z ]` record to a `position` column with the position role
-     * (default true); false keeps the whole record in the `graphics` json column.
+     * Read a node's `graphics [ x y z ]` record as its position; false keeps the whole record as a
+     * JSON attribute named `graphics`.
+     * @defaultValue true
      */
     positions?: boolean | undefined;
-    /** Apply the dictionary heuristic of design section 5.4 to string columns (default true). */
+    /**
+     * Store a text attribute whose values repeat a lot (fewer distinct values than half the rows)
+     * as a dictionary column, which uses less memory and reads the same. Such a column reports
+     * `meta.dtype` "dict" instead of "string". A column with a role, such as the `label` column,
+     * always stays "string".
+     * @defaultValue true
+     */
     dictionaries?: boolean | undefined;
 }
 
-/** Issue code: the text holds no `graph [ ... ]` block. */
+/**
+ * The text holds no `graph [ ... ]` block.
+ * @category Issue and loss codes
+ */
 export const NO_GRAPH_CODE = SHARED_NO_GRAPH_CODE;
-/** Issue code: the text holds more than one `graph [ ... ]` block; import() reads the first, importAll() every one. */
+/**
+ * The text holds more than one `graph [ ... ]` block; import() reads the first, importAll() every one.
+ * @category Issue and loss codes
+ */
 export const SECOND_GRAPH_CODE = MULTIPLE_GRAPHS_CODE;
-/** Issue code: a node block has no `id` key. */
+/**
+ * A node block has no `id` key.
+ * @category Issue and loss codes
+ */
 export const MISSING_ID_CODE = SHARED_MISSING_ID_CODE;
-/** Issue code: a node block has no `label` key under `nodeIdFrom: "label"`. */
+/**
+ * A node block has no `label` key under `nodeIdFrom: "label"`.
+ * @category Issue and loss codes
+ */
 export const MISSING_LABEL_CODE = "E_GML_MISSING_LABEL";
-/** Issue code: an edge block has no `source` or no `target` key. */
+/**
+ * An edge block has no `source` or no `target` key.
+ * @category Issue and loss codes
+ */
 export const MISSING_ENDPOINT_CODE = SHARED_MISSING_ENDPOINT_CODE;
-/** Issue code: an `id`, `source` or `target` value is neither an integer nor a string. */
+/**
+ * An `id`, `source` or `target` value is neither an integer nor a string.
+ * @category Issue and loss codes
+ */
 export const ID_TYPE_CODE = "E_GML_ID_TYPE";
-/** Issue code: string `id`, `source` or `target` values, outside the GML spec's integer ids; warned once per file. */
+/**
+ * Node ids, sources or targets are text, where GML expects integers. They are read under the `ids` option. Reported
+ * once per file.
+ * @category Issue and loss codes
+ */
 export const STRING_ID_CODE = "W_GML_STRING_ID";
-/** Issue code: a node id (or label under `nodeIdFrom: "label"`) is declared twice; later keys overwrite. */
+/**
+ * A node id (or label under `nodeIdFrom: "label"`) is declared twice; later keys overwrite.
+ * @category Issue and loss codes
+ */
 export const DUPLICATE_NODE_CODE = SHARED_DUPLICATE_NODE_CODE;
-/** Issue code: a structural key (`id`, `source`, `target`) appears twice in one block. */
+/**
+ * A structural key (`id`, `source`, `target`) appears twice in one block.
+ * @category Issue and loss codes
+ */
 export const REPEATED_KEY_CODE = "E_GML_REPEATED_KEY";
-/** Issue code: a `node` or `edge` key whose value is not a `[ ... ]` block. */
+/**
+ * A `node` or `edge` key whose value is not a `[ ... ]` block.
+ * @category Issue and loss codes
+ */
 export const ELEMENT_TYPE_CODE = "E_GML_ELEMENT_TYPE";
-/** Issue code: a `directed` or `multigraph` flag that is not an integer. */
+/**
+ * A `directed` or `multigraph` flag that is not an integer.
+ * @category Issue and loss codes
+ */
 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), one written as a quoted integer, or one repeated. */
+/**
+ * A `directed` / `multigraph` flag that is not 0 or 1 (read as its truth value), one written as a quoted integer, or
+ * one repeated.
+ * @category Issue and loss codes
+ */
 export const FLAG_VALUE_CODE = "W_GML_FLAG_VALUE";
 
 /** A flag written as a quoted integer, surrounding spaces allowed. */
 const QUOTED_INT = /^\s*[+-]?[0-9]+\s*$/;
-/** 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. */
+/**
+ * A named entity in a string that is neither an XML nor an ISO-8859-1 HTML entity, or a numeric reference beyond
+ * U+10FFFF; it is kept as written.
+ * @category Issue and loss codes
+ */
 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). */
+/**
+ * A node's `graphics` value cannot give a position as written (not a record, repeated in the node, or with an x / y /
+ * z that is not one number); the value is kept in the graphics json column. Warned once per kind of problem, naming
+ * the first node.
+ * @category Issue and loss codes
+ */
+export const GRAPHICS_CODE = "W_GML_GRAPHICS";
+/**
+ * A `graph`, `node` or `edge` record inside a node or edge; kept as a json column, not read as structure.
+ * @category Issue and loss codes
+ */
+export const NESTED_ELEMENT_CODE = "W_GML_NESTED_ELEMENT";
+/**
+ * YEd's group keys (`isGroup`, `gid`); kept as plain node columns, the hierarchy is not read as containment.
+ * @category Issue and loss codes
+ */
+export const GROUPS_CODE = "W_GML_GROUPS";
+/**
+ * A key whose values mix numbers and strings; the column is string, the numbers kept as written.
+ * @category Issue and loss codes
+ */
+export const WIDENED_CODE = SHARED_WIDENED_CODE;
+/**
+ * An integer above 2^53 was stored as the nearest JavaScript number, so its last digits may differ. Pass `long:
+ * "string"` to keep every digit as text.
+ * @category Issue and loss codes
+ */
 export const PRECISION_CODE = SHARED_PRECISION_CODE;
-/** Issue code: the sink already holds a column of the name with another declaration; renamed `<name>#<key>`. */
+/**
+ * Two attributes would have had the same name, so this one was renamed `<name>#<key>`.
+ * @category Plugin helpers
+ */
 export const COLUMN_RENAMED_CODE_GML = COLUMN_RENAMED_CODE;
-/** Issue code: the sink already holds a column with the role; the column is declared without it. */
+/**
+ * You read into a graph builder that already has an attribute with this role, so this file's attribute is kept without
+ * the role.
+ * @category Issue and loss codes
+ */
 export const ROLE_TAKEN_CODE = SHARED_ROLE_TAKEN_CODE;
-/** Loss code: under `nodeIdFrom` "label" / "index" the integer `id` keys are not kept. */
+/**
+ * Under `nodeIdFrom` "label" / "index" the integer `id` keys are not kept.
+ * @category Issue and loss codes
+ */
 export const ID_DROPPED_CODE = "W_GML_ID_DROPPED";
 
 const FORMAT_DEFAULTS: ImportFormatDefaults = { ids: "canonical", defaultDirected: false, weightFrom: "value" };
@@ -150,6 +248,7 @@ const USED_OPTIONS: ReadonlySet<keyof CommonImportOptions> = new Set<keyof Commo
     "weightFrom",
     "weightDtype",
     "restoreMangledIds",
+    "long",
     "errorLimit",
     "signal",
     "onProgress",
@@ -220,6 +319,34 @@ interface ColumnPlan {
 /** A table's plans by key. */
 type PlanMap = Map<string, ColumnPlan>;
 
+/** Where a node issue is recorded. */
+interface IssueWhere {
+    readonly line: number;
+    readonly element: string;
+}
+
+/** The table a GML key belongs to. */
+type GmlDomain = "node" | "edge" | "graph";
+
+/**
+ * Whether a key is the label of a node or edge (text, never a NetworkX list marker).
+ * @param domain - the table
+ * @param key - the key
+ * @returns true for a node or edge label
+ */
+function isLabel(domain: GmlDomain, key: string): boolean {
+    return roleOf(domain, key) === "label";
+}
+
+/**
+ * Whether a parsed value is a GML record.
+ * @param value - the value
+ * @returns true for a record object
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * Whether a key gets a role in its table (design section 5.6 applied to GML keys).
  * @param domain - the table
@@ -309,6 +436,9 @@ class GmlImport {
     /** The sink id every file id maps to when they differ (label / index / restored ids), else null. */
     private idMap: Map<NodeId, NodeId> | null = null;
 
+    /** The file ids of node blocks that were skipped: an edge naming one is skipped too, never given a new node. */
+    private readonly skippedIds = new Set<NodeId>();
+
     /** Node indices declared by a node block of this import, for duplicate detection. */
     private declared = new Uint32Array(64);
 
@@ -354,7 +484,7 @@ class GmlImport {
             this.report.warnOnce(
                 "parse-error",
                 UNKNOWN_ENTITY_CODE,
-                `unknown character entity ${entity} is kept as written`,
+                `character entity ${entity} cannot be decoded; it is kept as written`,
                 { line, element: entity },
                 `${UNKNOWN_ENTITY_CODE}:${entity}`,
             );
@@ -371,10 +501,14 @@ class GmlImport {
      */
     private scan(): void {
         const t = this.requireTokens();
+        let scalarGraph = -1;
         for (let p = 0; p < t.count; p = t.nextPair(p)) {
             const key = t.textOf(p);
             const v = p + 1;
             const record = t.kind[v] === TOKEN_OPEN;
+            if (key === "graph" && !record && scalarGraph < 0) {
+                scalarGraph = v;
+            }
             if (key === "graph" && record) {
                 if (this.graphCount++ === this.which) {
                     this.graphOpen = v;
@@ -389,6 +523,13 @@ class GmlImport {
             }
         }
         if (this.graphOpen < 0) {
+            if (scalarGraph >= 0) {
+                this.report.fail(
+                    NO_GRAPH_CODE,
+                    `the graph key at line ${t.line[scalarGraph]} holds ${describeValue(t, scalarGraph)}, not a [ ... ] block; the input contains no graph block`,
+                    { line: t.line[scalarGraph] },
+                );
+            }
             this.report.fail(NO_GRAPH_CODE, "the input contains no graph [ ... ] block", { line: null });
         }
     }
@@ -483,7 +624,9 @@ class GmlImport {
         seq: number,
     ): void {
         const t = this.requireTokens();
+        this.noteStructure(domain, key, v);
         let entry = schema.get(key);
+        const graphics = domain === "node" && key === "graphics" && this.positions;
         if (entry === undefined) {
             entry = {
                 key,
@@ -499,13 +642,22 @@ class GmlImport {
             schema.set(key, entry);
         } else if (entry.lastSeq === seq) {
             entry.list = true;
+            // a repeated graphics record: the extra records go to the json column
+            entry.rest ||= graphics;
         } else {
             entry.lastSeq = seq;
         }
+        if (graphics && t.kind[v] !== TOKEN_OPEN) {
+            entry.rest = true;
+        }
         switch (t.kind[v]) {
             case TOKEN_STRING: {
                 const raw = t.textOf(v);
-                if (raw === LIST_START_MARKER || raw === EMPTY_LIST_TEXT || raw === EMPTY_TUPLE_TEXT) {
+                // a label is text: "[]" there is a label, never NetworkX's empty list
+                if (
+                    raw === LIST_START_MARKER ||
+                    (!isLabel(domain, key) && (raw === EMPTY_LIST_TEXT || raw === EMPTY_TUPLE_TEXT))
+                ) {
                     entry.list = true;
                     return;
                 }
@@ -532,8 +684,49 @@ class GmlImport {
                     this.inspectGraphics(entry, v);
                 }
                 return;
-            default:
+            default: {
                 entry.kinds |= KIND_REAL;
+                const text = t.textOf(v);
+                if (/\d/.test(text) && !Number.isFinite(Number(text))) {
+                    this.report.warnOnce(
+                        "precision",
+                        PRECISION_CODE,
+                        `${domain} key "${key}" holds the real ${text}, beyond the f64 range; it is stored as ${numberOfText(text) > 0 ? "" : "-"}Infinity`,
+                        { line: t.line[v], element: key },
+                        `${PRECISION_CODE}:overflow:${domain}:${key}`,
+                    );
+                }
+            }
+        }
+    }
+
+    /**
+     * Warn about keys of a node or edge whose meaning GML readers give but this import does not:
+     * a nested graph / node / edge record, and yEd's group hierarchy.
+     * @param domain - the table
+     * @param key - the key
+     * @param v - the value token
+     */
+    private noteStructure(domain: "node" | "edge" | "graph", key: string, v: number): void {
+        const t = this.requireTokens();
+        if (domain === "graph") {
+            return;
+        }
+        if ((key === "graph" || key === "node" || key === "edge") && t.kind[v] === TOKEN_OPEN) {
+            this.report.warnOnce(
+                "unsupported",
+                NESTED_ELEMENT_CODE,
+                `a nested ${key} record inside a ${domain} is kept as the json column "${key}"; it is not read as structure`,
+                { line: t.line[v], element: key },
+                `${NESTED_ELEMENT_CODE}:${domain}:${key}`,
+            );
+        } else if (domain === "node" && (key === "isGroup" || key === "gid")) {
+            this.report.warnOnce(
+                "unsupported",
+                GROUPS_CODE,
+                "yEd group keys (isGroup, gid) are kept as plain node columns; the group hierarchy is not read as containment",
+                { line: t.line[v], element: key },
+            );
         }
     }
 
@@ -620,7 +813,9 @@ class GmlImport {
      * @returns the plan
      */
     private planOf(domain: "node" | "edge" | "graph", entry: KeySchema, top = false): ColumnPlan {
-        const kind = kindOf(entry);
+        // long: "string" keeps every digit of an integer key that holds values beyond 2^53, as text
+        const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
+        const kind = asText ? "string" : kindOf(entry);
         let scalar: ScalarDtype = dtypeOfKind(kind, entry);
         if (
             scalar === "string" &&
@@ -631,11 +826,24 @@ class GmlImport {
         ) {
             scalar = "dict";
         }
-        if (entry.unsafe) {
+        if (
+            (entry.kinds & KIND_STRING) !== 0 &&
+            (entry.kinds & (KIND_INT | KIND_REAL)) !== 0 &&
+            (entry.kinds & KIND_RECORD) === 0
+        ) {
+            this.report.warnOnce(
+                "coercion",
+                WIDENED_CODE,
+                `${domain} key "${entry.key}" mixes numbers and strings; the column is string and the numbers are kept as written`,
+                { element: entry.key },
+                `${WIDENED_CODE}:${domain}:${entry.key}`,
+            );
+        }
+        if (entry.unsafe && !asText) {
             this.report.warnOnce(
                 "precision",
                 PRECISION_CODE,
-                `${domain} key "${entry.key}" holds integers beyond 2^53; they are stored as the nearest f64`,
+                `${domain} key "${entry.key}" holds integers beyond 2^53; they are stored as the nearest f64 (pass long: "string" to keep every digit as text)`,
                 { element: entry.key },
                 `${PRECISION_CODE}:${domain}:${entry.key}`,
             );
@@ -661,13 +869,7 @@ class GmlImport {
             items: null,
             seq: Number.NEGATIVE_INFINITY,
         };
-        if (
-            domain === "node" &&
-            entry.key === "graphics" &&
-            entry.position &&
-            entry.kinds === KIND_RECORD &&
-            !entry.list
-        ) {
+        if (domain === "node" && entry.key === "graphics" && this.positions && (entry.kinds & KIND_RECORD) !== 0) {
             const taken = (candidate: string): boolean =>
                 this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
             const position: ColumnPlan = {
@@ -676,9 +878,12 @@ class GmlImport {
                 dtype: "f64",
                 itemDtype: null,
                 kind: "real",
+                list: false,
                 role: "position",
             };
-            const rest: ColumnPlan | null = entry.rest ? { ...plan } : null;
+            const rest: ColumnPlan | null = entry.rest
+                ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false }
+                : null;
             return { ...plan, position, rest };
         }
         return plan;
@@ -692,6 +897,14 @@ class GmlImport {
     private uniqueGraphName(key: string): string {
         const name = uniqueColumnName(key, key, (candidate) => this.graphNames.has(candidate));
         this.graphNames.add(name);
+        if (name !== key) {
+            this.report.warning(
+                "coercion",
+                COLUMN_RENAMED_CODE_GML,
+                `the top-level key "${key}" and a key of the graph block share the graph column name; the top-level value is stored as "${name}"`,
+                { element: key },
+            );
+        }
         return name;
     }
 
@@ -867,6 +1080,7 @@ class GmlImport {
         this.checkAbort();
         let index: number;
         let sinkId: NodeId;
+        let fileId: NodeId | undefined;
         try {
             let idTok = -1;
             let labelTok = -1;
@@ -886,7 +1100,7 @@ class GmlImport {
             }
             // the file id under the ids rule, so `id 1` and `source "1"` meet in idMap (except under
             // "keep", where the integer 1 and the string "1" are different ids by design)
-            const fileId = this.coerceFileId(idTok, this.fileIdOf(idTok, "id"));
+            fileId = this.coerceFileId(idTok, this.fileIdOf(idTok, "id"));
             if (originalTok >= 0) {
                 sinkId = this.restoredId(originalTok);
             } else {
@@ -906,13 +1120,25 @@ class GmlImport {
                         sinkId = fileId;
                 }
             }
+            index = sink.addNode(sinkId);
             if (this.idMap !== null) {
+                const before = this.idMap.get(fileId);
+                if (before !== undefined && before !== sinkId) {
+                    report.warning(
+                        "merged",
+                        DUPLICATE_NODE_CODE,
+                        `file id ${JSON.stringify(fileId)} is declared twice (nodes ${JSON.stringify(before)} and ${JSON.stringify(sinkId)}); edges to it resolve to the later`,
+                        { line, element: String(fileId) },
+                    );
+                }
                 this.idMap.set(fileId, sinkId);
             }
-            index = sink.addNode(sinkId);
         } catch (err) {
             this.recordNodeError(err, line);
             report.counts.skippedNodes++;
+            if (fileId !== undefined) {
+                this.skippedIds.add(fileId);
+            }
             return;
         }
         if (this.isDeclared(index)) {
@@ -928,16 +1154,27 @@ class GmlImport {
         }
         this.beginElement(this.seq++);
         try {
+            const graphics: number[] = [];
+            let graphicsPlan: ColumnPlan | null = null;
             for (let p = open + 1; p < close; p = t.nextPair(p)) {
                 const key = t.textOf(p);
                 if (key === "id" || (key === ORIGINAL_ID_KEY && options.restoreMangledIds)) {
                     continue;
                 }
                 const plan = this.nodePlans.get(key);
-                if (plan !== undefined) {
+                if (plan !== undefined && plan.position !== null) {
+                    graphicsPlan = plan;
+                    graphics.push(p + 1);
+                } else if (plan !== undefined) {
                     this.writeNode(plan, index, p + 1);
                 }
             }
+            if (graphicsPlan !== null) {
+                this.writeGraphics(graphicsPlan, index, graphics, {
+                    line: t.line[graphics[0]],
+                    element: String(sinkId),
+                });
+            }
             this.flushLists("node", index);
         } catch (err) {
             this.touched.length = 0;
@@ -1144,7 +1381,20 @@ class GmlImport {
      */
     private endpoint(v: number, key: string): NodeId {
         const id = this.coerceFileId(v, this.fileIdOf(v, key));
-        return this.idMap?.get(id) ?? id;
+        const mapped = this.idMap?.get(id);
+        if (mapped !== undefined) {
+            return mapped;
+        }
+        if (this.skippedIds.has(id)) {
+            // the node block was skipped: creating the endpoint would bring the node back under
+            // its raw file id (beside label ids under nodeIdFrom "label")
+            throw new GraphFormatError(
+                "E_UNKNOWN_NODE",
+                `${key} ${JSON.stringify(id)} names a node block that was skipped after an error`,
+                { reason: "skipped node", id },
+            );
+        }
+        return id;
     }
 
     /**
@@ -1156,11 +1406,17 @@ class GmlImport {
         const t = this.requireTokens();
         switch (t.kind[v]) {
             case TOKEN_STRING:
-                return parseWeightText(t.stringOf(v));
+                return parseWeightText(t.stringOf(v), this.report);
             case TOKEN_OPEN:
                 throw new GraphFormatError("E_INVALID_WEIGHT", "edge weight is a record", { value: "[...]" });
-            default:
-                return weightFromValue(numberOfText(t.textOf(v)));
+            default: {
+                const text = t.textOf(v);
+                const weight = weightFromValue(numberOfText(text));
+                if (weight !== undefined) {
+                    reportWeightPrecision(text, weight, this.report);
+                }
+                return weight;
+            }
         }
     }
 
@@ -1228,10 +1484,6 @@ class GmlImport {
      * @param v - the value token
      */
     private writeNode(plan: ColumnPlan, index: number, v: number): void {
-        if (plan.position !== null) {
-            this.writeGraphics(plan, index, v);
-            return;
-        }
         if (plan.list) {
             this.collectItem(plan, v, this.seqNow, this.touched);
             return;
@@ -1264,37 +1516,98 @@ class GmlImport {
             this.collectItem(plan, v, seq, this.graphTouched);
             return;
         }
-        this.sink.setGraphValue(plan.name, this.scalarOf(plan, v), graphDecl(plan));
+        const value = this.scalarOf(plan, v);
+        this.sink.setGraphValue(plan.name, value, graphDecl(plan));
+        if (seq === GRAPH_SEQ && plan.key === "name" && typeof value === "string") {
+            // the graph block's `name` is the graph's name too (snapshot.meta.name, and what graphName matches)
+            this.sink.setMeta({ name: value });
+        }
     }
 
     /**
-     * Write a node's graphics record: the position column from x / y / z, the remaining keys to
-     * the json column.
+     * Write a node's graphics values: the position column from the x / y / z of the first record,
+     * everything else (the remaining keys, a value that is not a record, a repeated record) to the
+     * json column, with a warning when the value cannot give a position as written.
      * @param plan - the graphics plan
      * @param index - the node index
-     * @param v - the value token (a record)
+     * @param vs - the value tokens of the node's graphics keys, in order
+     * @param where - the line and the node, for issues
      */
-    private writeGraphics(plan: ColumnPlan, index: number, v: number): void {
+    private writeGraphics(plan: ColumnPlan, index: number, vs: readonly number[], where: IssueWhere): void {
         const t = this.requireTokens();
         const { sink } = this;
-        const record = parseRecord(t, v);
-        const { x, y, z } = record;
+        const values = vs.map((v) => (t.kind[v] === TOKEN_OPEN ? parseRecord(t, v) : this.scalarOf(plan, v)));
+        const first = values[0];
         const positionPlan = plan.position;
-        if (positionPlan !== null && typeof x === "number" && typeof y === "number") {
-            sink.setNodeValue(this.handleOf(positionPlan, "node"), index, [x, y, typeof z === "number" ? z : 0]);
+        let rest: unknown = first;
+        if (isRecord(first) && positionPlan !== null) {
+            rest = this.writePosition(positionPlan, index, first, where);
+        } else if (!isRecord(first)) {
+            this.graphicsWarning("scalar", `node ${where.element}'s graphics is not a record`, where);
+        }
+        if (values.length > 1) {
+            this.graphicsWarning(
+                "repeated",
+                `node ${where.element} has ${values.length} graphics records; the position comes from the first`,
+                where,
+            );
+            rest = values;
+        }
+        if (rest !== undefined && plan.rest !== null) {
+            sink.setNodeValue(this.handleOf(plan.rest, "node"), index, rest);
+        }
+    }
+
+    /**
+     * Write a node's position from the x / y / z of its graphics record, taking them out of it.
+     * @param positionPlan - the position column's plan
+     * @param index - the node index
+     * @param record - the graphics record
+     * @param where - the line and the node, for issues
+     * @returns what is left of the record for the json column, or undefined when nothing is
+     */
+    private writePosition(
+        positionPlan: ColumnPlan,
+        index: number,
+        record: Record<string, unknown>,
+        where: IssueWhere,
+    ): unknown {
+        const { x, y, z } = record;
+        let rest: unknown = record;
+        if (typeof x === "number" && typeof y === "number") {
+            const depth = typeof z === "number" ? z : 0;
+            this.sink.setNodeValue(this.handleOf(positionPlan, "node"), index, [x, y, depth]);
             delete record.x;
             delete record.y;
             if (typeof z === "number") {
                 delete record.z;
             }
-            if (plan.rest !== null && Object.keys(record).length > 0) {
-                sink.setNodeValue(this.handleOf(plan.rest, "node"), index, record);
-            }
-            return;
+            rest = Object.keys(record).length > 0 ? record : undefined;
         }
-        if (plan.rest !== null) {
-            sink.setNodeValue(this.handleOf(plan.rest, "node"), index, record);
+        if ("x" in record || "y" in record || "z" in record) {
+            this.graphicsWarning(
+                "coordinate",
+                `node ${where.element}'s graphics x / y / z is not one number each`,
+                where,
+            );
         }
+        return rest;
+    }
+
+    /**
+     * Warn once per kind of graphics problem.
+     * @param kind - the problem
+     * @param what - the message start, naming the node
+     * @param where - the line and the node
+     */
+    private graphicsWarning(kind: string, what: string, where: IssueWhere): void {
+        this.report.warnOnce(
+            "validation-error",
+            GRAPHICS_CODE,
+            `${what}; the value is kept in the graphics json column (warned once for every such node)`,
+            where,
+            `${GRAPHICS_CODE}:${kind}`,
+        );
     }
 
     /**
@@ -1605,9 +1918,13 @@ function sniffGml(head: Uint8Array): number {
     return 0;
 }
 
-/** The GML importer plugin. */
+/**
+ * The GML importer plugin.
+ * @category Built-in formats
+ */
 export const gmlImporter: GraphImporter<GmlImportOptions> = Object.freeze({
     format: "gml",
+    options: Object.freeze(["dictionaries", "positions"]),
     extensions: Object.freeze([".gml"]),
     mimeTypes: Object.freeze(["text/x-gml", "text/plain"]),
     sniff: sniffGml,
@@ -1623,6 +1940,10 @@ export const gmlImporter: GraphImporter<GmlImportOptions> = Object.freeze({
         sink: GraphSink,
         options?: GmlImportOptions & CommonImportOptions,
     ): Promise<ImportReport> {
+        if (graphChosen(options)) {
+            // the choice is honored here too, not only by the registry
+            return importChosenGraph(gmlImporter, input, sink, options);
+        }
         const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
         const report = new ImportReportBuilder("gml", resolved.errorLimit);
         reportSinkOptions(sink, options, report);
@@ -1635,7 +1956,7 @@ export const gmlImporter: GraphImporter<GmlImportOptions> = Object.freeze({
             report.warning(
                 "unsupported",
                 SECOND_GRAPH_CODE,
-                `the input holds ${gml.graphCount - 1} more graph block(s) after the first; import() reads the first, importAll() reads every one`,
+                `the input holds ${gml.graphCount - 1} more graph block${plural(gml.graphCount - 1)} after the first; the first is read (graphIndex or graphName chooses another; importAllGraphs() reads every one)`,
             );
         }
         // an abort raised during the last few elements (after the last periodic check) still rejects