@graphty/graph-io 0.3.25 → 0.3.27

package/dist/gml.js

@@ -1,9 +1,8 @@
-import { t as SYNTAX_CODE, X as pairFolding, V as resolveExportOptions, _ as DictHeuristic, aV as DICT_SAMPLE_ROWS, R as ROLE_TAKEN_CODE$1, P as PRECISION_CODE$1, d as DUPLICATE_NODE_CODE$1, e as MISSING_ENDPOINT_CODE$1, f as MISSING_ID_CODE$1, M as MULTIPLE_GRAPHS_CODE, N as NO_GRAPH_CODE$1, v as resolveImportOptions, w as ImportReportBuilder, z as reportUnusedOptions, aG as readText, y as throwIfAborted, F as reportSinkOptions, K as IdCoercer, J as DirectionResolver, Q as uniqueColumnName, L as declareResolved, af as MIXED_DIRECTION_CODE, D as DIRECTION_FORCED_CODE, a as DIRECTION_REFUSED_CODE, S as SINK_OPTION_CODE, O as OPTION_IGNORED_CODE, I as ID_MERGED_CODE, C as COLUMN_RENAMED_CODE, q as UNKNOWN_ENCODING_CODE, E as ENCODING_FALLBACK_CODE, r as INVALID_ENCODING_CODE, s as INVALID_UTF8_CODE } from "./chunks/report-B1z4WT9e.js";
+import { ak as SYNTAX_CODE, b as plural, a as checkCapabilities, L as LOSS, p as pairFolding, $ as agree, c as capabilities, r as resolveExportOptions, ac as DictHeuristic, aG as formatInteger, bw as formatGmlReal, aE as sanitizeIds, bE as countMixedEdges, e as explicitWeights, bV as DICT_SAMPLE_ROWS, R as ROLE_TAKEN_CODE$1, aj as WIDENED_CODE$1, P as PRECISION_CODE$1, n as DUPLICATE_NODE_CODE$1, s as MISSING_ENDPOINT_CODE$1, t as MISSING_ID_CODE$1, l as MULTIPLE_GRAPHS_CODE, N as NO_GRAPH_CODE$1, al as resolveImportOptions, a8 as ImportReportBuilder, an as reportUnusedOptions, bC as readText, am as throwIfAborted, ao as reportSinkOptions, ap as graphChosen, ar as IdCoercer, aq as DirectionResolver, a0 as uniqueColumnName, C as COLUMN_RENAMED_CODE, as as weightFromValue, bW as reportWeightPrecision, aL as parseWeightText, a1 as declareResolved, M as MIXED_DIRECTION_CODE, D as DIRECTION_FORCED_CODE, d as DIRECTION_REFUSED_CODE, S as SINK_OPTION_CODE, O as OPTION_IGNORED_CODE, I as ID_MERGED_CODE, ae as AMBIGUOUS_GRAPH_NAME_CODE, af as GRAPH_NOT_FOUND_CODE, w as UNKNOWN_ENCODING_CODE, x as ENCODING_FALLBACK_CODE, y as INVALID_ENCODING_CODE, z as INVALID_UTF8_CODE, F as ELEMENT_ISSUE, G as INPUT_ISSUE } from "./chunks/export-CHd4tQE2.js";
 import { GraphFormatError, INVALID_INDEX } from "@graphty/graph-format";
-import { j as decodeGmlString, k as quoteGmlString } from "./chunks/escape-B-tkk_Cl.js";
-import { a as checkCapabilities, L as LOSS, c as capabilities, s as sanitizeIds, d as countMixedEdges } from "./chunks/export-Bh60Dv-n.js";
-import { d as formatInteger, c as formatGmlReal, e as explicitWeights, w as weightFromValue, p as parseWeightText } from "./chunks/weights-Dzba96G3.js";
-import { j as joinText, e as encodeChunks } from "./chunks/writer-C7flM-Ih.js";
+import { k as decodeGmlString, m as quoteGmlString } from "./chunks/escape-D1HPTUrP.js";
+import { j as joinText, e as encodeChunks } from "./chunks/writer-DxjgHwSe.js";
+import { i as importChosenGraph } from "./chunks/choose-DrXtu_96.js";
 const TOKEN_WORD = 0;
 const TOKEN_INT = 1;
 const TOKEN_REAL = 2;
@@ -85,14 +84,20 @@ class GmlTokens {
    * @returns the body with character references decoded
    */
   stringOf(i) {
-    const text = this.textOf(i);
+    let text = this.textOf(i);
+    if (text.includes("\r")) {
+      text = text.replaceAll(/\r\n?/g, "\n");
+    }
     if (text.indexOf("&") < 0) {
       return text;
     }
     const report = this.onUnknownEntity;
-    return decodeGmlString(text, report === null ? void 0 : (entity) => {
-      report(entity, this.line[i]);
-    });
+    return decodeGmlString(
+      text,
+      report === null ? void 0 : (entity) => {
+        report(entity, this.line[i]);
+      }
+    );
   }
   /**
    * Whether a token is a `[` or `]`.
@@ -133,6 +138,7 @@ function tokenizeGml(text) {
   const n = text.length;
   let i = 0;
   let line = 1;
+  let spanningLine = 0;
   while (i < n) {
     const c = text.charCodeAt(i);
     if (c === 10) {
@@ -146,6 +152,8 @@ function tokenizeGml(text) {
       }
     } else if (c === 32 || c === 9 || c === 11 || c === 12) {
       i++;
+    } else if (c === 65279) {
+      i++;
     } else if (c === 35) {
       i = endOfLine(text, i);
     } else if (c === 91) {
@@ -156,11 +164,21 @@ function tokenizeGml(text) {
       i++;
     } else if (c === 34) {
       const close = text.indexOf('"', i + 1);
-      const eol = endOfLine(text, i + 1);
-      if (close < 0 || close > eol) {
-        throw new GmlSyntaxError(SYNTAX_STRING_CODE, `unclosed string at line ${line}`, line);
+      if (close < 0) {
+        const hint = spanningLine === 0 ? "" : `; the string opened at line ${spanningLine} spans lines, so a quote may be missing there`;
+        throw new GmlSyntaxError(SYNTAX_STRING_CODE, `unclosed string opened at line ${line}${hint}`, line);
       }
       tokens.push(TOKEN_STRING, i + 1, close, line);
+      const opened = line;
+      for (let k = i + 1; k < close; k++) {
+        const d = text.codePointAt(k);
+        if (d === 10 || d === 13 && text.codePointAt(k + 1) !== 10) {
+          line++;
+        }
+      }
+      if (line !== opened && spanningLine === 0) {
+        spanningLine = opened;
+      }
       i = close + 1;
     } else {
       let j = i + 1;
@@ -198,8 +216,12 @@ function classifyBare(text, start, end, line) {
   if (REAL_TEXT.test(token) || NON_FINITE_TEXT.test(token)) {
     return TOKEN_REAL;
   }
-  const shown = token.length > 20 ? `${token.slice(0, 20)}...` : token;
-  throw new GmlSyntaxError(SYNTAX_TOKEN_CODE, `cannot tokenize "${shown}" at line ${line}`, line);
+  const hex = (c) => (c.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0");
+  const head = token.length > 20 ? `${token.slice(0, 20)}...` : token;
+  const shown = head.replaceAll(/[^\x20-\x7e]/gu, (c) => String.raw`\u` + hex(c));
+  const odd = /[^\x21-\x7e]/u.exec(token);
+  const note2 = odd === null ? "" : ` (it holds U+${hex(odd[0])}, which GML allows only inside a string)`;
+  throw new GmlSyntaxError(SYNTAX_TOKEN_CODE, `cannot tokenize "${shown}" at line ${line}${note2}`, line);
 }
 function validateStructure(tokens) {
   const { count, kind } = tokens;
@@ -252,7 +274,7 @@ function validateStructure(tokens) {
     const open = stack[stack.length - 1];
     throw new GmlSyntaxError(
       SYNTAX_BRACKET_CODE,
-      `unexpected end of input: ${stack.length} bracket(s) still open, the last opened at line ${tokens.line[open]}`,
+      `unexpected end of input: ${stack.length} bracket${plural(stack.length)} still open, the last opened at line ${tokens.line[open]}`,
       tokens.line[open]
     );
   }
@@ -274,7 +296,7 @@ function numberOfText(text) {
   if (NON_FINITE_TEXT.test(text)) {
     const lower = text.toLowerCase();
     if (lower.endsWith("nan")) {
-      return NaN;
+      return Number.NaN;
     }
     return lower.startsWith("-") ? -Infinity : Infinity;
   }
@@ -284,7 +306,7 @@ function isGmlKey(text) {
   return STRICT_KEY_TEXT.test(text);
 }
 function mangleGmlKey(text) {
-  const body = text.replace(/[^0-9A-Za-z_]/g, "_");
+  const body = text.replaceAll(/\W/g, "_");
   return /^[A-Za-z]/.test(body) ? body : `x${body}`;
 }
 function parseRecord(tokens, open) {
@@ -436,8 +458,11 @@ function isWritten(column) {
   return role === null || !SKIPPED_ROLES.has(role);
 }
 function preferredKey(meta) {
-  const { origin } = meta;
-  return origin !== null && origin.format === "gml" && origin.id !== null ? origin.id : meta.name;
+  const { origin, name } = meta;
+  if (origin?.format !== "gml" || origin.id === null) {
+    return name;
+  }
+  return name === origin.id || name.startsWith(`${origin.id}#`) ? origin.id : name;
 }
 function hasWeights(snapshot) {
   return snapshot.flags.weighted;
@@ -480,7 +505,7 @@ function selectColumns(table, reserved, label, plan, notes, filter = () => true)
         notes.push(
           note(
             code,
-            `${label} column "${column.meta.name}" ${why}; export() will throw unless sanitizeKeys is "mangle"`,
+            `${label} column "${column.meta.name}" ${why}; the save fails unless sanitizeKeys is "mangle"`,
             column.meta.name
           )
         );
@@ -564,7 +589,7 @@ function jsonNotes(columns, label, plan, notes) {
       notes.push(
         note(
           RECORD_NUMBER_TYPE_CODE,
-          `${where} holds numbers in ${stats.numbers} row(s); GML records cannot keep the int / real distinction`,
+          `${where} holds numbers in ${stats.numbers} row${plural(stats.numbers)}; GML records cannot keep the int / real distinction`,
           name,
           stats.numbers
         )
@@ -574,7 +599,7 @@ function jsonNotes(columns, label, plan, notes) {
       notes.push(
         note(
           RECORD_BOOLEAN_CODE,
-          `${where} holds booleans in ${stats.booleans} row(s); written as 1 / 0`,
+          `${where} holds booleans in ${stats.booleans} row${plural(stats.booleans)}; written as 1 / 0`,
           name,
           stats.booleans
         )
@@ -584,7 +609,7 @@ function jsonNotes(columns, label, plan, notes) {
       notes.push(
         note(
           RECORD_NULL_CODE,
-          `${where} holds nulls in ${stats.nulls} row(s); GML has no null, the key is omitted`,
+          `${where} holds nulls in ${stats.nulls} row${plural(stats.nulls)}; GML has no null, the key is omitted`,
           name,
           stats.nulls
         )
@@ -594,7 +619,7 @@ function jsonNotes(columns, label, plan, notes) {
       notes.push(
         note(
           JSON_ARRAY_CODE,
-          `${where} holds arrays as values in ${stats.arrays} row(s); written as repeated keys, they re-import as a list`,
+          `${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
         )
@@ -604,7 +629,7 @@ function jsonNotes(columns, label, plan, notes) {
       notes.push(
         note(
           NESTED_ARRAY_CODE,
-          `${where} holds arrays nested in arrays in ${stats.nestedArrays} row(s); GML cannot write them and export() will throw`,
+          `${where} holds arrays nested in arrays in ${stats.nestedArrays} row${plural(stats.nestedArrays)}; GML cannot write them and the save fails`,
           name,
           stats.nestedArrays
         )
@@ -614,12 +639,12 @@ function jsonNotes(columns, label, plan, notes) {
       notes.push(
         plan.mangle ? note(
           KEY_MANGLED_CODE,
-          `${where}: ${stats.invalidKeys} record key(s) are not GML keys and are rewritten`,
+          `${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(s) are not GML keys; export() will throw unless sanitizeKeys is "mangle"`,
+          `${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
         )
@@ -716,7 +741,7 @@ function graphicsNotes(snapshot, notes) {
     notes.push(
       note(
         GRAPHICS_OVERRIDDEN_CODE,
-        `${overridden} node graphics record(s) have x / y / z keys the position column replaces`,
+        `${overridden} node graphics record${plural(overridden)} ${agree(overridden, "has", "have")} x / y / z keys the position column replaces`,
         "graphics",
         overridden
       )
@@ -726,7 +751,7 @@ function graphicsNotes(snapshot, notes) {
     notes.push(
       note(
         GRAPHICS_CONFLICT_CODE,
-        `${conflicts} node graphics value(s) are not records and cannot hold the position; export() will throw`,
+        `${conflicts} node graphics value${plural(conflicts)} ${agree(conflicts, "is", "are")} not records and cannot hold the position; the save fails`,
         "graphics",
         conflicts
       )
@@ -841,7 +866,7 @@ function check(snapshot, options) {
       notes.push(
         note(
           LOSS.WEIGHT_KEY_CLASH,
-          `edge column "${clash.column.meta.name}" is written under "${plan.weightKey}", the key the importer reads THE weight from; it reads back as the weight, not as a column`,
+          `edge column "${clash.column.meta.name}" is written under "${plan.weightKey}", the key the importer reads edge weights from; it reads back as the weight, not as a column`,
           clash.column.meta.name,
           clash.column.length - clash.column.nullCount
         )
@@ -853,7 +878,7 @@ function check(snapshot, options) {
     notes.push(
       note(
         LOSS.MUTUAL_EXPANDED,
-        `${folding.mutualCount} mutual pair(s) are written as two directed edges; the mutual mark is lost`,
+        `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed edges; the mutual mark is lost`,
         null,
         folding.mutualCount
       )
@@ -1159,7 +1184,7 @@ function contextOf(snapshot, options) {
   if (mixed > 0 && plan.common.onMixedDirection === "error") {
     throw new GraphFormatError(
       "E_DIRECTED",
-      `${mixed} undirected edge(s) in a directed graph; GML has no mixed direction (onMixedDirection: "error")`,
+      `${mixed} undirected edge${plural(mixed)} in a directed graph, and GML holds one direction per file, so the save fails unless onMixedDirection is "directed" or "undirected"`,
       {
         reason: "mixed direction",
         count: mixed
@@ -1319,6 +1344,7 @@ function writeGraphics(w, context, i) {
 }
 const gmlExporter = Object.freeze({
   format: "gml",
+  options: Object.freeze(["sanitizeKeys", "weightKey"]),
   capabilities: GML_CAPABILITIES,
   check,
   /**
@@ -1358,7 +1384,12 @@ const FLAG_TYPE_CODE = "E_GML_FLAG_TYPE";
 const FLAG_VALUE_CODE = "W_GML_FLAG_VALUE";
 const QUOTED_INT = /^\s*[+-]?[0-9]+\s*$/;
 const UNKNOWN_ENTITY_CODE = "W_GML_UNKNOWN_ENTITY";
+const GRAPHICS_CODE = "W_GML_GRAPHICS";
+const NESTED_ELEMENT_CODE = "W_GML_NESTED_ELEMENT";
+const GROUPS_CODE = "W_GML_GROUPS";
+const WIDENED_CODE = WIDENED_CODE$1;
 const PRECISION_CODE = PRECISION_CODE$1;
+const COLUMN_RENAMED_CODE_GML = COLUMN_RENAMED_CODE;
 const ROLE_TAKEN_CODE = ROLE_TAKEN_CODE$1;
 const ID_DROPPED_CODE = "W_GML_ID_DROPPED";
 const FORMAT_DEFAULTS = { ids: "canonical", defaultDirected: false, weightFrom: "value" };
@@ -1380,12 +1411,19 @@ const USED_OPTIONS = /* @__PURE__ */ new Set([
   "weightFrom",
   "weightDtype",
   "restoreMangledIds",
+  "long",
   "errorLimit",
   "signal",
   "onProgress"
 ]);
 const GRAPH_SEQ = -1;
 const TOP_SEQ = -2;
+function isLabel(domain, key) {
+  return roleOf(domain, key) === "label";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function roleOf(domain, key) {
   if (key === "label" && domain !== "graph") {
     return "label";
@@ -1437,6 +1475,7 @@ class GmlImport {
     this.nodeOrdinal = 0;
     this.elementsSinceCheck = 0;
     this.idMap = null;
+    this.skippedIds = /* @__PURE__ */ new Set();
     this.declared = new Uint32Array(64);
     this.touched = [];
     this.graphTouched = [];
@@ -1458,7 +1497,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}`
       );
@@ -1473,10 +1512,14 @@ class GmlImport {
    */
   scan() {
     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;
@@ -1491,6 +1534,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 });
     }
   }
@@ -1576,7 +1626,9 @@ class GmlImport {
    */
   observe(schema, domain, key, v, seq) {
     const t = this.requireTokens();
+    this.noteStructure(domain, key, v);
     let entry = schema.get(key);
+    const graphics = domain === "node" && key === "graphics" && this.positions;
     if (entry === void 0) {
       entry = {
         key,
@@ -1592,13 +1644,17 @@ class GmlImport {
       schema.set(key, entry);
     } else if (entry.lastSeq === seq) {
       entry.list = true;
+      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) {
+        if (raw === LIST_START_MARKER || !isLabel(domain, key) && (raw === EMPTY_LIST_TEXT || raw === EMPTY_TUPLE_TEXT)) {
           entry.list = true;
           return;
         }
@@ -1625,8 +1681,48 @@ 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
+   */
+  noteStructure(domain, key, v) {
+    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 }
+      );
     }
   }
   /**
@@ -1708,16 +1804,26 @@ class GmlImport {
    * @returns the plan
    */
   planOf(domain, entry, top = false) {
-    const kind = kindOf(entry);
+    const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
+    const kind = asText ? "string" : kindOf(entry);
     let scalar = dtypeOfKind(kind, entry);
     if (scalar === "string" && !entry.list && entry.dict !== null && entry.kinds === KIND_STRING && entry.dict.decide() === "dict") {
       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}`
       );
@@ -1743,7 +1849,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) => this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
       const position = {
         ...plan,
@@ -1751,9 +1857,10 @@ class GmlImport {
         dtype: "f64",
         itemDtype: null,
         kind: "real",
+        list: false,
         role: "position"
       };
-      const rest = entry.rest ? { ...plan } : null;
+      const rest = entry.rest ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false } : null;
       return { ...plan, position, rest };
     }
     return plan;
@@ -1766,6 +1873,14 @@ class GmlImport {
   uniqueGraphName(key) {
     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;
   }
   /** Set the graph metadata: source format, creator, version, multigraph flag, weight origin. */
@@ -1930,6 +2045,7 @@ class GmlImport {
     this.checkAbort();
     let index;
     let sinkId;
+    let fileId;
     try {
       let idTok = -1;
       let labelTok = -1;
@@ -1947,7 +2063,7 @@ class GmlImport {
       if (idTok < 0) {
         throw new GraphFormatError("E_INVALID_ID", "node has no id", { reason: "missing id" });
       }
-      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 {
@@ -1967,13 +2083,25 @@ class GmlImport {
             sinkId = fileId;
         }
       }
+      index = sink.addNode(sinkId);
       if (this.idMap !== null) {
+        const before = this.idMap.get(fileId);
+        if (before !== void 0 && 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 !== void 0) {
+        this.skippedIds.add(fileId);
+      }
       return;
     }
     if (this.isDeclared(index)) {
@@ -1989,16 +2117,27 @@ class GmlImport {
     }
     this.beginElement(this.seq++);
     try {
+      const graphics = [];
+      let graphicsPlan = 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 !== void 0) {
+        if (plan !== void 0 && plan.position !== null) {
+          graphicsPlan = plan;
+          graphics.push(p + 1);
+        } else if (plan !== void 0) {
           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;
@@ -2194,7 +2333,18 @@ class GmlImport {
    */
   endpoint(v, key) {
     const id = this.coerceFileId(v, this.fileIdOf(v, key));
-    return this.idMap?.get(id) ?? id;
+    const mapped = this.idMap?.get(id);
+    if (mapped !== void 0) {
+      return mapped;
+    }
+    if (this.skippedIds.has(id)) {
+      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;
   }
   /**
    * The weight of an edge from its weight token.
@@ -2205,11 +2355,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 !== void 0) {
+          reportWeightPrecision(text, weight, this.report);
+        }
+        return weight;
+      }
     }
   }
   /**
@@ -2271,10 +2427,6 @@ class GmlImport {
    * @param v - the value token
    */
   writeNode(plan, index, v) {
-    if (plan.position !== null) {
-      this.writeGraphics(plan, index, v);
-      return;
-    }
     if (plan.list) {
       this.collectItem(plan, v, this.seqNow, this.touched);
       return;
@@ -2305,36 +2457,89 @@ 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") {
+      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
    */
-  writeGraphics(plan, index, v) {
+  writeGraphics(plan, index, vs, where) {
     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 = 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 !== void 0 && 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
+   */
+  writePosition(positionPlan, index, record, where) {
+    const { x, y, z } = record;
+    let rest = 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 : void 0;
     }
-    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
+   */
+  graphicsWarning(kind, what, where) {
+    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}`
+    );
   }
   /**
    * Collect one list item.
@@ -2586,6 +2791,7 @@ function sniffGml(head) {
 }
 const gmlImporter = Object.freeze({
   format: "gml",
+  options: Object.freeze(["dictionaries", "positions"]),
   extensions: Object.freeze([".gml"]),
   mimeTypes: Object.freeze(["text/x-gml", "text/plain"]),
   sniff: sniffGml,
@@ -2597,6 +2803,9 @@ const gmlImporter = Object.freeze({
    * @returns the report
    */
   async import(input, sink, options) {
+    if (graphChosen(options)) {
+      return importChosenGraph(gmlImporter, input, sink, options);
+    }
     const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
     const report = new ImportReportBuilder("gml", resolved.errorLimit);
     reportSinkOptions(sink, options, report);
@@ -2609,7 +2818,7 @@ const gmlImporter = 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)`
       );
     }
     throwIfAborted(resolved.signal);
@@ -2655,20 +2864,32 @@ function tokenize(text, report) {
   }
 }
 const GML_ISSUE = Object.freeze({
-  /** A grammar violation: an untokenisable bare token, an unclosed string or `[`, a stray `]`, a key without a value (fatal). */
+  ...INPUT_ISSUE,
+  ...ELEMENT_ISSUE,
+  /**
+   * The text breaks GML's syntax: a word that is not a key or a value, an unclosed string or `[`, a stray `]`, or a
+   * key without a value. The import stops.
+   */
   SYNTAX: SYNTAX_CODE,
-  /** The input holds 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, a declaration or the encoding option chose (fatal). */
+  /**
+   * Some bytes are not valid in the encoding that was chosen (by a byte order mark, the file's declaration or the
+   * `encoding` option). The import stops.
+   */
   INVALID_ENCODING: INVALID_ENCODING_CODE,
   /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
   ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
   /** A declared encoding the platform cannot decode was ignored. */
   UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
-  /** No `graph [` block (fatal). */
+  /** There is no `graph [` block. The import stops. */
   NO_GRAPH: NO_GRAPH_CODE,
-  /** More than one `graph` block (fatal). */
+  /** The file holds more than one `graph` block and only the first was read. It is not added when `graphIndex` or `graphName` chose the graph. */
   MULTIPLE_GRAPHS: SECOND_GRAPH_CODE,
+  /** `graphIndex` or `graphName` names no graph of the file; the message lists the graphs it holds. The import stops. */
+  GRAPH_NOT_FOUND: GRAPH_NOT_FOUND_CODE,
+  /** `graphName` matches more than one graph; pass `graphIndex`. The import stops. */
+  AMBIGUOUS_GRAPH_NAME: AMBIGUOUS_GRAPH_NAME_CODE,
   /** A node without an `id`. */
   MISSING_ID: MISSING_ID_CODE,
   /** A node without a `label` under nodeIdFrom "label". */
@@ -2677,7 +2898,10 @@ const GML_ISSUE = Object.freeze({
   MISSING_ENDPOINT: MISSING_ENDPOINT_CODE,
   /** A node id, source or target that is neither an integer nor a string. */
   ID_TYPE: ID_TYPE_CODE,
-  /** String node ids, sources or targets (outside the spec's integers), kept under the ids rule; warned once. */
+  /**
+   * Node ids, sources or targets are text, where GML expects integers. They are read under the `ids` option.
+   * Reported once per file.
+   */
   STRING_ID: STRING_ID_CODE,
   /** A node id declared twice (later keys overwrite). */
   DUPLICATE_NODE: DUPLICATE_NODE_CODE,
@@ -2689,41 +2913,74 @@ const GML_ISSUE = Object.freeze({
   FLAG_TYPE: FLAG_TYPE_CODE,
   /** A `directed` / `multigraph` flag outside 0 / 1, or repeated. */
   FLAG_VALUE: FLAG_VALUE_CODE,
-  /** A named entity in a string that no table decodes; kept as written. */
+  /** A named entity no table decodes, or a numeric reference beyond U+10FFFF; kept as written. */
   UNKNOWN_ENTITY: UNKNOWN_ENTITY_CODE,
-  /** An integer beyond 2^53 rounded to f64. */
+  /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
   PRECISION: PRECISION_CODE,
-  /** A column renamed `<name>#<key>` because the sink held the name with another shape. */
+  /** A node's graphics value that cannot give a position as written; kept in the graphics json column. */
+  GRAPHICS: GRAPHICS_CODE,
+  /** A graph, node or edge record nested in a node or edge; kept as json, not read as structure. */
+  NESTED_ELEMENT: NESTED_ELEMENT_CODE,
+  /** YEd's isGroup / gid keys, kept as plain columns; the hierarchy is not read as containment. */
+  GROUPS: GROUPS_CODE,
+  /**
+   * An attribute's type was widened because a later value did not fit: an integer above 2^31 in an integer column,
+   * or two declared types for one attribute.
+   */
+  WIDENED: WIDENED_CODE,
+  /**
+   * 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 declared without its role because the sink already 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,
-  /** Two id texts merged into one number under ids "number". */
+  /** Two different id texts became the same number because `ids` is "number", so their nodes were merged. */
   ID_MERGED: ID_MERGED_CODE,
-  /** A common option the importer has no use for was given. */
+  /** 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-policy option the 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 sink refused the file's 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 mixed file under onMixedDirection "error" (fatal). */
+  /**
+   * The graph has both directed and undirected edges and `onMixedDirection` is "error". An import stops; a save to a
+   * format that holds one direction per file fails with E_DIRECTED. Pass "directed" or "undirected" to read or write
+   * it anyway.
+   */
   MIXED_DIRECTION: MIXED_DIRECTION_CODE,
-  /** Under nodeIdFrom "label" / "index" the integer ids are not kept (a loss note). */
+  /**
+   * Under `nodeIdFrom: "label"` or `"index"` the file's integer ids are not kept. It is listed in `report.lossy`, not
+   * in `report.issues`.
+   */
   ID_DROPPED: ID_DROPPED_CODE
 });
 const GML_LOSS = Object.freeze({
-  /** A json column holds numbers; GML records cannot keep int versus real (design section 8.5). */
+  /** A json column holds numbers; GML records cannot keep int versus real. */
   RECORD_NUMBER_TYPE: RECORD_NUMBER_TYPE_CODE,
   /** A json column holds booleans, written 1 / 0. */
   RECORD_BOOLEAN: RECORD_BOOLEAN_CODE,
   /** A json column holds nulls, omitted. */
   RECORD_NULL: RECORD_NULL_CODE,
-  /** An array inside an array; export() throws. */
+  /** An attribute holds an array inside an array, which GML cannot write; the save fails. */
   NESTED_ARRAY: NESTED_ARRAY_CODE,
   /** A json row that is an array, written as repeated keys. */
   JSON_ARRAY: JSON_ARRAY_CODE,
-  /** A column name or record key outside the GML key grammar. */
+  /**
+   * An attribute name GML cannot use as a key (keys are letters and digits, starting with a letter). The save fails
+   * unless `sanitizeKeys` is "mangle".
+   */
   INVALID_KEY: INVALID_KEY_CODE,
   /** A column named like a structural key. */
   RESERVED_KEY: RESERVED_KEY_CODE,