@graphty/graph-io 0.3.24 → 0.3.26

package/dist/src/formats/dot/importer.d.ts

@@ -27,50 +27,72 @@
  *   as the DOT grammar says).
  *
  * The whole text is read first (design section 8.4 allows it for DOT). A grammar violation is
- * fatal, as it is for Graphviz itself: the import aborts with ImportError (code E_DOT_SYNTAX)
+ * fatal, as it is for Graphviz itself: the import aborts with ImportError (issue code E_SYNTAX)
  * carrying the partial report. Errors the sink raises for one element are recorded and the element
  * is skipped (section 8.6).
  */
-import { type GraphImporter } from "../../types.js";
-/** The DOT importer's format-specific options. */
-export interface DotImportOptions {
+import { type CommonImportOptions, type GraphChoiceOptions, type GraphImporter } from "../../types.js";
+/**
+ * The DOT importer's format-specific options.
+ * @category Built-in formats
+ */
+export interface DotImportOptions extends GraphChoiceOptions, CommonImportOptions {
     /**
      * What an edge operator that contradicts the graph keyword means (`--` in a digraph, `->` in a
-     * graph; a syntax error for Graphviz): "operator" (default) reads the edge with the operator's
-     * direction and resolves it per onMixedDirection, with a warning; "header" reads it with the
-     * graph's direction, with a warning; "error" aborts the import as Graphviz does.
+     * graph; Graphviz refuses such a file): "operator" reads the edge with the operator's
+     * direction, so the graph has both directions and `onMixedDirection` decides, with a warning;
+     * "header" reads it with the graph's direction, with a warning; "error" stops the import with an
+     * ImportError whose `issue.code` is E_SYNTAX, as Graphviz does.
+     * @defaultValue "operator"
      */
     mismatchedEdgeOperator?: "operator" | "header" | "error" | undefined;
     /**
-     * Map a node's `pos` to a `pos` column with the position role and a trailing `!` to `pin`
-     * (default true); false keeps `pos` as the text the file wrote, like any other attribute.
+     * Read a node's `pos` attribute as its position (a trailing `!` becomes a `pin` attribute);
+     * false keeps `pos` as the text the file wrote, like any other attribute.
+     * @defaultValue true
      */
     positions?: boolean | undefined;
 }
 /**
- * The issue codes the DOT importer records (design section 8.6), by name: the codes shared with
- * the other importers (src/common/codes.ts) and the DOT-specific ones. A key is the code without
+ * The issue codes the DOT importer records, by name: the codes shared with
+ * the other importers and the DOT-specific ones. A key is the code without
  * its severity and format prefixes.
+ * @category Built-in formats
  */
 export declare const DOT_ISSUE: Readonly<{
-    /** A grammar violation; fatal. */
+    /** The text breaks DOT's syntax; the message says where. The import stops. */
     SYNTAX: "E_SYNTAX";
-    /** The input holds no graph at all (empty or only comments); fatal. */
+    /** The input holds no graph: it is empty or only comments. The import stops. */
     EMPTY_INPUT: "E_EMPTY_INPUT";
-    /** The input holds invalid UTF-8 (fatal). */
+    /** The input is not valid UTF-8. The import stops. */
     INVALID_UTF8: "E_INVALID_UTF8";
-    /** 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: "E_INVALID_ENCODING";
     /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
     ENCODING_FALLBACK: "W_ENCODING_FALLBACK";
     /** A declared encoding the platform cannot decode was ignored. */
     UNKNOWN_ENCODING: "W_UNKNOWN_ENCODING";
-    /** Subgraphs or braces nested deeper than the parser's limit; fatal. */
+    /** A declared encoding the byte order mark contradicts (the mark wins). */
+    ENCODING_CONFLICT: "W_ENCODING_CONFLICT";
+    /** Subgraphs or braces are nested deeper than graph-io reads. The import stops. */
     NESTING: "E_DOT_NESTING";
-    /** An edge operator contradicting the graph keyword (warning under "operator" / "header"). */
+    /**
+     * An edge operator contradicting the graph keyword, read under mismatchedEdgeOperator "operator" or "header".
+     * Under "error" the import stops with E_SYNTAX instead.
+     */
     EDGE_OPERATOR: "W_DOT_EDGE_OPERATOR";
-    /** A second graph in the same input; only the first is read. */
+    /**
+     * The file holds several graphs and only the first was read. It is not added when `graphIndex` or `graphName` chose the graph.
+     * `importAllGraphs()` reads every one.
+     */
     MULTIPLE_GRAPHS: "W_MULTIPLE_GRAPHS";
+    /** `graphIndex` or `graphName` names no graph of the file; the message lists the graphs it holds. The import stops. */
+    GRAPH_NOT_FOUND: "E_GRAPH_NOT_FOUND";
+    /** `graphName` matches more than one graph; pass `graphIndex`. The import stops. */
+    AMBIGUOUS_GRAPH_NAME: "E_AMBIGUOUS_GRAPH_NAME";
     /** A badly delimited numeral (`1e3`) split into two tokens, as Graphviz does with a warning. */
     NUMERAL_AMBIGUITY: "W_DOT_NUMERAL_AMBIGUITY";
     /** Attributes of a subgraph that is not a cluster (rank=same and the like) cannot be represented. */
@@ -81,33 +103,73 @@ export declare const DOT_ISSUE: Readonly<{
     CLUSTER_NODE_MERGED: "W_DOT_CLUSTER_NODE_MERGED";
     /** A node mentioned in two unrelated clusters keeps the first. */
     CLUSTER_CONFLICT: "W_DOT_CLUSTER_CONFLICT";
-    /** A node `pos` that is not a point; the value was dropped. */
+    /** A node's `pos` is not a point, or is too large for a 32-bit float position; the value was dropped. */
     BAD_POS: "W_DOT_BAD_POS";
+    /** Node `pos` values mix two and three coordinates; the position column records the first's. */
+    POS_DIMS: "W_DOT_POS_DIMS";
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
+    PRECISION: "W_PRECISION";
+    /** The same attribute twice in one statement's attribute lists; the last value stands, as in Graphviz. */
+    DUPLICATE_ATTRIBUTE: "W_DUPLICATE_ATTRIBUTE";
+    /** The second part of a port (`a:p:zz`) is not a compass point; kept as written, as Graphviz warns. */
+    COMPASS_POINT: "W_DOT_COMPASS_POINT";
+    /** A `charset` attribute beyond the head the decoder reads it from; the input was decoded without it. */
+    LATE_CHARSET: "W_DOT_LATE_CHARSET";
     /** A parallel edge merged into an earlier one under `strict`. */
     STRICT_MERGED: "W_DOT_STRICT_MERGED";
     /** An edge merged into an earlier one with the same endpoints and `key`. */
     KEY_MERGED: "W_DOT_KEY_MERGED";
-    /** A role (label, id, position, ...) was already taken in the caller's sink; the column was declared without 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: "W_ROLE_TAKEN";
-    /** A column of another shape exists in the caller's sink under a name the importer declares; renamed `<name>#<id>`. */
+    /**
+     * An attribute was renamed `<name>#<suffix>` because another attribute already has its name, for example
+     * two attributes declared with the same name.
+     */
     COLUMN_RENAMED: "W_COLUMN_RENAMED";
-    /** A common option the format has no use for was given a non-default value. */
+    /** You set an option this format does not use; it had no effect. The message names the option. */
     OPTION_IGNORED: "W_OPTION_IGNORED";
-    /** Two distinct id texts merged under ids: "number". */
+    /** Two different id texts became the same number because `ids` is "number", so their nodes were merged. */
     ID_MERGED: "W_ID_MERGED";
-    /** 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: "W_SINK_OPTION";
-    /** 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: "W_DIRECTION_REFUSED";
-    /** Edges forced to the policy's direction. */
+    /** Edges of the other direction were read with the direction `onMixedDirection` chose. */
     DIRECTION_FORCED: "W_DIRECTION_FORCED";
-    /** 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: "E_MIXED_DIRECTION";
-    /** A text column the sink could not widen to the dtype its cells imply. */
+    /**
+     * Your graph builder cannot change an attribute's type after its first value, so a text column keeps the type of
+     * its first values.
+     */
     WIDENING_UNSUPPORTED: "W_WIDENING_UNSUPPORTED";
+    INVALID_ID: "E_INVALID_ID";
+    UNKNOWN_NODE: "E_UNKNOWN_NODE";
+    INVALID_WEIGHT: "E_INVALID_WEIGHT";
+    DUPLICATE_EDGE: "E_DUPLICATE_EDGE";
+    SELF_LOOP: "E_SELF_LOOP";
+    DUPLICATE_EDGE_ID: "E_DUPLICATE_EDGE_ID";
+    TOO_LARGE: "E_TOO_LARGE";
+    CONTROL_CHARACTER: "W_CONTROL_CHARACTER";
+    FOREIGN_FORMAT: "E_FOREIGN_FORMAT";
+    ISSUES_SUPPRESSED: "W_ISSUES_SUPPRESSED";
 }>;
 /**
- * The importer plugin for DOT / Graphviz text (design section 12.4).
+ * The importer plugin for DOT / Graphviz text.
+ * @category Built-in formats
  */
 export declare const dotImporter: GraphImporter<DotImportOptions>;
 //# sourceMappingURL=importer.d.ts.map

package/dist/src/formats/dot/importer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../../../../src/formats/dot/importer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAyCH,OAAO,EAA4B,KAAK,aAAa,EAAuC,MAAM,gBAAgB,CAAC;AAenH,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACrE;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS;IAClB,kCAAkC;;IAElC,uEAAuE;;IAEvE,6CAA6C;;IAE7C,+FAA+F;;IAE/F,kFAAkF;;IAElF,kEAAkE;;IAElE,wEAAwE;;IAExE,8FAA8F;;IAE9F,gEAAgE;;IAEhE,gGAAgG;;IAEhG,qGAAqG;;IAErG,iEAAiE;;IAEjE,uFAAuF;;IAEvF,kEAAkE;;IAElE,+DAA+D;;IAE/D,iEAAiE;;IAEjE,4EAA4E;;IAE5E,oHAAoH;;IAEpH,uHAAuH;;IAEvH,+EAA+E;;IAE/E,wDAAwD;;IAExD,wDAAwD;;IAExD,6CAA6C;;IAE7C,8CAA8C;;IAE9C,2DAA2D;;IAE3D,2EAA2E;;EAE7E,CAAC;AA8EH;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAwGtD,CAAC"}
+{"version":3,"file":"importer.d.ts","sourceRoot":"","sources":["../../../../src/formats/dot/importer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAoDH,OAAO,EACH,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAGrB,MAAM,gBAAgB,CAAC;AAexB;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB,EAAE,mBAAmB;IAC7E;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACrE;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS;IAGlB,8EAA8E;;IAE9E,gFAAgF;;IAEhF,sDAAsD;;IAEtD;;;OAGG;;IAEH,kFAAkF;;IAElF,kEAAkE;;IAElE,2EAA2E;;IAE3E,mFAAmF;;IAEnF;;;OAGG;;IAEH;;;OAGG;;IAEH,uHAAuH;;IAEvH,oFAAoF;;IAEpF,gGAAgG;;IAEhG,qGAAqG;;IAErG,iEAAiE;;IAEjE,uFAAuF;;IAEvF,kEAAkE;;IAElE,yGAAyG;;IAEzG,gGAAgG;;IAEhG,gHAAgH;;IAEhH,0GAA0G;;IAE1G,uGAAuG;;IAEvG,yGAAyG;;IAGzG,iEAAiE;;IAEjE,4EAA4E;;IAE5E;;;OAGG;;IAEH;;;OAGG;;IAEH,kGAAkG;;IAElG,2GAA2G;;IAE3G;;;OAGG;;IAEH;;;OAGG;;IAEH,0FAA0F;;IAE1F;;;;OAIG;;IAEH;;;OAGG;;;;;;;;;;;;EAEL,CAAC;AAuFH;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAoHtD,CAAC"}

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

@@ -27,46 +27,67 @@
  *   as the DOT grammar says).
  *
  * The whole text is read first (design section 8.4 allows it for DOT). A grammar violation is
- * fatal, as it is for Graphviz itself: the import aborts with ImportError (code E_DOT_SYNTAX)
+ * fatal, as it is for Graphviz itself: the import aborts with ImportError (issue code E_SYNTAX)
  * carrying the partial report. Errors the sink raises for one element are recorded and the element
  * is skipped (section 8.6).
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareResolved } from "../../common/attributes.js";
-import { COLUMN_RENAMED_CODE, DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, ID_MERGED_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MIXED_DIRECTION_CODE, MULTIPLE_GRAPHS_CODE, OPTION_IGNORED_CODE, ROLE_TAKEN_CODE, SINK_OPTION_CODE, SYNTAX_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
+import { importChosenGraph } from "../../common/choose.js";
+import { AMBIGUOUS_GRAPH_NAME_CODE, COLUMN_RENAMED_CODE, DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, DUPLICATE_ATTRIBUTE_CODE, ELEMENT_ISSUE, EMPTY_INPUT_CODE, ENCODING_CONFLICT_CODE, ENCODING_FALLBACK_CODE, GRAPH_NOT_FOUND_CODE, ID_MERGED_CODE, INPUT_ISSUE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MIXED_DIRECTION_CODE, MULTIPLE_GRAPHS_CODE, OPTION_IGNORED_CODE, PRECISION_CODE, ROLE_TAKEN_CODE, SINK_OPTION_CODE, SYNTAX_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
+import { survivesF32 } from "../../common/format.js";
 import { IdCoercer } from "../../common/ids.js";
-import { readText, throwIfAborted } from "../../common/input.js";
-import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { canonicalEncoding, readText, throwIfAborted } from "../../common/input.js";
+import { graphChosen, reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { inferTextDtype, parseTextCell, TextCellWriter, WIDENING_UNSUPPORTED_CODE } from "../../common/text.js";
 import { parseWeightText } from "../../common/weights.js";
 import { CLUSTER_COLUMN, DOT_FORMAT, DOT_ORIGIN, KEY_ATTRIBUTE, LABEL_ATTRIBUTE, PARENT_COLUMN, PIN_ATTRIBUTE, POS_ATTRIBUTE, SOURCE_PORT_COLUMN, TARGET_PORT_COLUMN, } from "./names.js";
 import { DotSyntaxError, DotTokenizer } from "./tokenizer.js";
 /**
- * The issue codes the DOT importer records (design section 8.6), by name: the codes shared with
- * the other importers (src/common/codes.ts) and the DOT-specific ones. A key is the code without
+ * The issue codes the DOT importer records, by name: the codes shared with
+ * the other importers and the DOT-specific ones. A key is the code without
  * its severity and format prefixes.
+ * @category Built-in formats
  */
 export const DOT_ISSUE = Object.freeze({
-    /** A grammar violation; fatal. */
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /** The text breaks DOT's syntax; the message says where. The import stops. */
     SYNTAX: SYNTAX_CODE,
-    /** The input holds no graph at all (empty or only comments); fatal. */
+    /** The input holds no graph: it is empty or only comments. The import stops. */
     EMPTY_INPUT: EMPTY_INPUT_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,
-    /** Subgraphs or braces nested deeper than the parser's limit; fatal. */
+    /** A declared encoding the byte order mark contradicts (the mark wins). */
+    ENCODING_CONFLICT: ENCODING_CONFLICT_CODE,
+    /** Subgraphs or braces are nested deeper than graph-io reads. The import stops. */
     NESTING: "E_DOT_NESTING",
-    /** An edge operator contradicting the graph keyword (warning under "operator" / "header"). */
+    /**
+     * An edge operator contradicting the graph keyword, read under mismatchedEdgeOperator "operator" or "header".
+     * Under "error" the import stops with E_SYNTAX instead.
+     */
     EDGE_OPERATOR: "W_DOT_EDGE_OPERATOR",
-    /** A second graph in the same input; only the first is read. */
+    /**
+     * The file holds several graphs and only the first was read. It is not added when `graphIndex` or `graphName` chose the graph.
+     * `importAllGraphs()` reads every one.
+     */
     MULTIPLE_GRAPHS: MULTIPLE_GRAPHS_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 badly delimited numeral (`1e3`) split into two tokens, as Graphviz does with a warning. */
     NUMERAL_AMBIGUITY: "W_DOT_NUMERAL_AMBIGUITY",
     /** Attributes of a subgraph that is not a cluster (rank=same and the like) cannot be represented. */
@@ -77,29 +98,58 @@ export const DOT_ISSUE = Object.freeze({
     CLUSTER_NODE_MERGED: "W_DOT_CLUSTER_NODE_MERGED",
     /** A node mentioned in two unrelated clusters keeps the first. */
     CLUSTER_CONFLICT: "W_DOT_CLUSTER_CONFLICT",
-    /** A node `pos` that is not a point; the value was dropped. */
+    /** A node's `pos` is not a point, or is too large for a 32-bit float position; the value was dropped. */
     BAD_POS: "W_DOT_BAD_POS",
+    /** Node `pos` values mix two and three coordinates; the position column records the first's. */
+    POS_DIMS: "W_DOT_POS_DIMS",
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
+    PRECISION: PRECISION_CODE,
+    /** The same attribute twice in one statement's attribute lists; the last value stands, as in Graphviz. */
+    DUPLICATE_ATTRIBUTE: DUPLICATE_ATTRIBUTE_CODE,
+    /** The second part of a port (`a:p:zz`) is not a compass point; kept as written, as Graphviz warns. */
+    COMPASS_POINT: "W_DOT_COMPASS_POINT",
+    /** A `charset` attribute beyond the head the decoder reads it from; the input was decoded without it. */
+    LATE_CHARSET: "W_DOT_LATE_CHARSET",
     /** A parallel edge merged into an earlier one under `strict`. */
     STRICT_MERGED: "W_DOT_STRICT_MERGED",
     /** An edge merged into an earlier one with the same endpoints and `key`. */
     KEY_MERGED: "W_DOT_KEY_MERGED",
-    /** A role (label, id, position, ...) was already taken in the caller's sink; the column was declared without 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,
-    /** A column of another shape exists in the caller's sink under a name the importer declares; renamed `<name>#<id>`. */
+    /**
+     * 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 common option the format has no use for was given a non-default value. */
+    /** You set an option this format does not use; it had no effect. The message names the option. */
     OPTION_IGNORED: OPTION_IGNORED_CODE,
-    /** Two distinct id texts merged 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 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,
-    /** A text column the sink could not widen to the dtype its cells imply. */
+    /**
+     * Your graph builder cannot change an attribute's type after its first value, so a text column keeps the type of
+     * its first values.
+     */
     WIDENING_UNSUPPORTED: WIDENING_UNSUPPORTED_CODE,
 });
 /** The common options the DOT importer reads (the rest is reported by reportUnusedOptions). */
@@ -129,12 +179,22 @@ const MAX_ANCESTOR_WALK = 4096;
  */
 const DOT_HEADER = /^\s*(strict\s+)?(di)?graph(?=[\s{"/]|$)(?!\s*\[)/i;
 const TRUE_TEXTS = new Set(["true", "yes", "1"]);
-const POINT_TEXT = /^\s*([-+]?[0-9]*\.?[0-9]+(?:[eE][-+]?[0-9]+)?)\s*,\s*([-+]?[0-9]*\.?[0-9]+(?:[eE][-+]?[0-9]+)?)(?:\s*,\s*([-+]?[0-9]*\.?[0-9]+(?:[eE][-+]?[0-9]+)?))?\s*(!?)\s*$/;
+const COMPASS_POINTS = new Set(["n", "ne", "e", "se", "s", "sw", "w", "nw", "c", "_"]);
 /**
- * The importer plugin for DOT / Graphviz text (design section 12.4).
+ * A DOT number: digits with an optional fraction, or a bare fraction (`.5`), then an exponent.
+ * Written so each digit has exactly one way to match; `[0-9]*\.?[0-9]+` took quadratic time on a
+ * long run of digits.
+ */
+const POINT_NUMBER = String.raw `[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][-+]?\d+)?`;
+/** A point "x,y[,z][!]". The `!` and its trailing space are one optional group, so spaces cannot split two ways. */
+const POINT_TEXT = new RegExp(String.raw `^\s*(${POINT_NUMBER})\s*,\s*(${POINT_NUMBER})(?:\s*,\s*(${POINT_NUMBER}))?\s*(?:(!)\s*)?$`);
+/**
+ * The importer plugin for DOT / Graphviz text.
+ * @category Built-in formats
  */
 export const dotImporter = Object.freeze({
     format: DOT_FORMAT,
+    options: Object.freeze(["mismatchedEdgeOperator", "positions"]),
     extensions: EXTENSIONS,
     mimeTypes: MIME_TYPES,
     /**
@@ -159,6 +219,10 @@ export const dotImporter = Object.freeze({
      * @returns the import report; ImportError (E_IMPORT) on a syntax error or beyond the error limit
      */
     async import(input, sink, options) {
+        if (graphChosen(options)) {
+            // the choice is honored here too, not only by the registry
+            return importChosenGraph(dotImporter, input, sink, options);
+        }
         const resolved = resolveImportOptions(options, {
             ids: "canonical",
             defaultDirected: true,
@@ -168,14 +232,22 @@ export const dotImporter = Object.freeze({
         const report = new ImportReportBuilder(DOT_FORMAT, resolved.errorLimit);
         reportUnusedOptions(options, report, USED_OPTIONS);
         reportSinkOptions(sink, options, report);
-        const text = await readText(input, report, { ...resolved, declaredEncoding: dotCharset });
+        const head = {};
+        const text = await readText(input, report, {
+            ...resolved,
+            declaredEncoding: (h) => (head.charset = dotCharset(h)),
+            declarationBytes: CHARSET_HEAD_BYTES,
+        });
         const reports = { current: report };
         const lexer = dotLexer(text, reports);
         const first = guard(report, () => lexer.next());
-        const trailing = parseGraph(new DotParser(lexer, sink, report, resolved, mismatch, options?.positions !== false), report, first);
+        const parser = new DotParser(lexer, sink, report, resolved, mismatch, options?.positions !== false);
+        parser.headCharset = head.charset;
+        const trailing = parseGraph(parser, report, first);
         if (trailing.kind !== "eof") {
+            // anything after the graph must be graphs too: Graphviz refuses the file otherwise
             const skipped = guard(report, () => countGraphs(lexer, trailing));
-            report.warning("unsupported", MULTIPLE_GRAPHS_CODE, `the input holds ${skipped} more graph(s) after the first; import() reads the first, importAll() reads every one`, { line: trailing.line });
+            report.warning("unsupported", MULTIPLE_GRAPHS_CODE, `the input holds ${skipped} more graph${plural(skipped)} after the first; the first is read (graphIndex or graphName chooses another; importAllGraphs() reads every one)`, { line: trailing.line });
         }
         // an abort raised during the last few statements (after the last periodic check) still rejects
         throwIfAborted(resolved.signal);
@@ -197,7 +269,12 @@ export const dotImporter = Object.freeze({
         const mismatch = mismatchOption(options?.mismatchedEdgeOperator);
         const first = new ImportReportBuilder(DOT_FORMAT, resolved.errorLimit);
         reportUnusedOptions(options, first, USED_OPTIONS);
-        const text = await readText(input, first, { ...resolved, declaredEncoding: dotCharset });
+        const head = {};
+        const text = await readText(input, first, {
+            ...resolved,
+            declaredEncoding: (h) => (head.charset = dotCharset(h)),
+            declarationBytes: CHARSET_HEAD_BYTES,
+        });
         const reports = { current: first };
         const lexer = dotLexer(text, reports);
         const done = [];
@@ -207,7 +284,9 @@ export const dotImporter = Object.freeze({
             reports.current = report;
             const sink = sinkFor(done.length);
             reportSinkOptions(sink, options, report);
-            token = parseGraph(new DotParser(lexer, sink, report, resolved, mismatch, options?.positions !== false), report, token);
+            const parser = new DotParser(lexer, sink, report, resolved, mismatch, options?.positions !== false);
+            parser.headCharset = head.charset;
+            token = parseGraph(parser, report, token);
             throwIfAborted(resolved.signal);
             done.push(report.finish());
         } while (token.kind !== "eof");
@@ -268,6 +347,9 @@ function countGraphs(lexer, first) {
         if (isKeyword(token, "strict")) {
             token = lexer.next();
         }
+        if (isPunct(token, "}")) {
+            throw new DotSyntaxError('unexpected "}" after the end of the graph: no "{" is open', token.line);
+        }
         if (!isKeyword(token, "graph") && !isKeyword(token, "digraph")) {
             throw new DotSyntaxError(`expected "graph" or "digraph", found ${describeToken(token)}`, token.line);
         }
@@ -295,18 +377,49 @@ function countGraphs(lexer, first) {
     }
     return count;
 }
-/** A `charset` attribute assignment (Graphviz's declaration of the input encoding). */
-const DOT_CHARSET = /\bcharset\s*=\s*"?([A-Za-z][A-Za-z0-9._-]*)/i;
+/** How many leading bytes the `charset` search sees: a license comment may come before the graph. */
+const CHARSET_HEAD_BYTES = 64 * 1024;
 /**
  * The encoding a DOT file declares with the graph attribute `charset` (Graphviz reads UTF-8,
  * Latin1 and Big-5), for the shared byte decoder; Graphviz's spellings `latin-1` and `big-5` are
- * mapped to the WHATWG labels.
+ * mapped to the WHATWG labels. Only a graph-level assignment counts (`charset=...` as a statement
+ * or inside `graph [...]`), never one in a comment, a quoted value or a node / edge attribute list.
  * @param head - the start of the file, decoded as windows-1252
  * @returns the declared label, or null
  */
 function dotCharset(head) {
-    const match = DOT_CHARSET.exec(head);
-    return match === null ? null : match[1].replace(/^(latin|big)-/i, "$1");
+    const lexer = new DotTokenizer(head);
+    // the attribute list an open `[` belongs to: the graph's (`graph [`) or a node's / an edge's
+    let list = null;
+    let previous = null;
+    try {
+        let token = lexer.next();
+        while (token.kind !== "eof") {
+            if (isPunct(token, "[")) {
+                list = previous !== null && isKeyword(previous, "graph") ? "graph" : "other";
+            }
+            else if (isPunct(token, "]")) {
+                list = null;
+            }
+            else if (list !== "other" && isKeyword(token, "charset")) {
+                const equals = lexer.next();
+                const value = isPunct(equals, "=") ? lexer.next() : equals;
+                if (value !== equals && value.kind === "id") {
+                    return value.text.replace(/^(latin|big)-/i, "$1");
+                }
+                token = value;
+            }
+            previous = token;
+            token = lexer.next();
+        }
+    }
+    catch (err) {
+        // the head ends inside a comment or a string: nothing further is seen
+        if (!(err instanceof DotSyntaxError)) {
+            throw err;
+        }
+    }
+    return null;
 }
 /**
  * Resolve the mismatchedEdgeOperator option.
@@ -435,6 +548,14 @@ class DotParser {
         this.targetPortHandle = INVALID_INDEX;
         /** The current subgraph nesting depth. */
         this.depth = 0;
+        /** The coordinate count of the first `pos`, or 0 before one. */
+        this.posDims = 0;
+        /**
+         * What the decoder's look at the head found for `charset`: a label, null for none, undefined
+         * when it never looked (text input, a BOM, the encoding option). A `charset` assignment read
+         * when the head had none came too late to decode by.
+         */
+        this.headCharset = undefined;
         /** The inferred attribute columns by name, per domain (the 5.1 text grammar per column). */
         this.nodeWriters = new Map();
         this.edgeWriters = new Map();
@@ -627,7 +748,11 @@ class DotParser {
         let { text } = this.identifier();
         if (isPunct(lexer.peek(), ":")) {
             lexer.next();
-            text += `:${this.identifier().text}`;
+            const compass = this.identifier();
+            text += `:${compass.text}`;
+            if (!COMPASS_POINTS.has(compass.text)) {
+                this.report.warning("validation-error", DOT_ISSUE.COMPASS_POINT, `port ${JSON.stringify(text)}: ${JSON.stringify(compass.text)} is not a compass point (n, ne, e, se, s, sw, w, nw, c, _); the port is kept as written`, { line: compass.line, element: text });
+            }
         }
         return text;
     }
@@ -853,6 +978,7 @@ class DotParser {
     attributeList() {
         const { lexer } = this;
         const out = [];
+        const names = new Set();
         while (isPunct(lexer.peek(), "[")) {
             lexer.next();
             for (;;) {
@@ -871,6 +997,10 @@ class DotParser {
                     throw new DotSyntaxError(`expected "=" after attribute name ${JSON.stringify(name.text)}, found ${describeToken(eq)}`, eq.line);
                 }
                 const value = this.identifier();
+                if (names.has(name.text)) {
+                    this.report.warning("merged", DOT_ISSUE.DUPLICATE_ATTRIBUTE, `attribute ${JSON.stringify(name.text)} is set twice in one statement; the last value ${JSON.stringify(value.text)} stands`, { line: name.line, element: name.text });
+                }
+                names.add(name.text);
                 out.push({ name: name.text, value: value.text, line: name.line });
             }
         }
@@ -957,7 +1087,7 @@ class DotParser {
                 this.report.warnOnce("coercion", DOT_ISSUE.EDGE_OPERATOR, `${message}; read with the graph's direction (mismatchedEdgeOperator: "header")`, { line: op.line });
                 return this.directed ? "directed" : "undirected";
             case "operator":
-                this.report.warnOnce("coercion", DOT_ISSUE.EDGE_OPERATOR, `${message}; read with the operator's direction and resolved per onMixedDirection`, { line: op.line });
+                this.report.warnOnce("coercion", DOT_ISSUE.EDGE_OPERATOR, `${message}; read with the operator's direction, and onMixedDirection decides how the mixed graph is stored`, { line: op.line });
                 return operatorDirected ? "directed" : "undirected";
             default: {
                 const name = this.mismatch;
@@ -1046,7 +1176,7 @@ class DotParser {
         const weightText = weightFrom === null ? undefined : effective.get(weightFrom);
         if (weightText !== undefined) {
             try {
-                weight = parseWeightText(weightText);
+                weight = parseWeightText(weightText, this.report);
             }
             catch (err) {
                 this.report.recordError(err, where);
@@ -1200,6 +1330,12 @@ class DotParser {
      * @param attribute - the attribute
      */
     setGraphAttribute(attribute) {
+        if (attribute.name.toLowerCase() === "charset" && this.headCharset === null) {
+            const canonical = canonicalEncoding(attribute.value);
+            if (canonical !== "utf-8") {
+                this.report.warning("unsupported", DOT_ISSUE.LATE_CHARSET, `charset ${JSON.stringify(attribute.value)} is declared beyond the first 1024 bytes, after the input was decoded without it; pass the encoding option to decode it as declared`, { line: attribute.line, element: attribute.name });
+            }
+        }
         try {
             if (attribute.name === LABEL_ATTRIBUTE) {
                 this.sink.setGraphValue(attribute.name, attribute.value, { dtype: "string", origin: DOT_ORIGIN });
@@ -1233,7 +1369,22 @@ class DotParser {
         const y = Number(match[2]);
         const z = match[3] === undefined ? 0 : Number(match[3]);
         const dims = match[3] === undefined ? 2 : 3;
-        this.sink.setNodeValue(this.positionColumn(dims), index, [x, y, z]);
+        const point = [x, y, z];
+        if (point.some((v) => !Number.isFinite(Math.fround(v)))) {
+            // the position column is f32: a half-infinite point would be a half-valid position
+            this.report.warning("validation-error", DOT_ISSUE.BAD_POS, `pos ${JSON.stringify(text)} is beyond the f32 range of the position column; dropped`, { line, element });
+            return;
+        }
+        if (!point.every(survivesF32)) {
+            this.report.warnOnce("precision", DOT_ISSUE.PRECISION, `pos ${JSON.stringify(text)} has a coordinate the f32 position column rounds (warned once; positions=false keeps pos as written)`, { line, element }, `${DOT_ISSUE.PRECISION}:pos`);
+        }
+        if (this.posDims === 0) {
+            this.posDims = dims;
+        }
+        else if (dims !== this.posDims) {
+            this.report.warnOnce("validation-error", DOT_ISSUE.POS_DIMS, `pos values mix ${this.posDims} and ${dims} coordinates; the position column records sourceDims ${this.posDims}`, { line, element });
+        }
+        this.sink.setNodeValue(this.positionColumn(dims), index, point);
         if (match[4] === "!") {
             this.sink.setNodeValue(PIN_ATTRIBUTE, index, true);
         }