@graphty/graph-io 0.3.25 → 0.3.27

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

@@ -17,38 +17,59 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareResolved, RENAMED_CODE, ROLE_TAKEN_CODE, uniqueColumnName } from "../../common/attributes.js";
-import { DUPLICATE_NODE_CODE, ENCODING_FALLBACK_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MULTIPLE_GRAPHS_CODE, OPTION_IGNORED_CODE, SYNTAX_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
+import { importChosenGraph } from "../../common/choose.js";
+import { AMBIGUOUS_GRAPH_NAME_CODE, DUPLICATE_ATTRIBUTE_CODE, DUPLICATE_NODE_CODE, ELEMENT_ISSUE, ENCODING_FALLBACK_CODE, GRAPH_NOT_FOUND_CODE, INPUT_ISSUE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MULTIPLE_GRAPHS_CODE, OPTION_IGNORED_CODE, PRECISION_CODE, SYNTAX_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
+import { survivesF32 } from "../../common/format.js";
 import { coerceIdText, ID_MERGED_CODE, IdCoercer } from "../../common/ids.js";
 import { LineReader, throwIfAborted } from "../../common/input.js";
-import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, SINK_OPTION_CODE, } from "../../common/options.js";
+import { graphChosen, reportSinkOptions, reportUnusedOptions, resolveImportOptions, SINK_OPTION_CODE, } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { isNumericText, TextCellWriter, WIDENING_UNSUPPORTED_CODE } from "../../common/text.js";
 import { isWeightField, parseWeightText } from "../../common/weights.js";
-import { decodeCharacterReferences, isCommentOrBlank, isIntervalToken, isSectionLine, isShapeKeyword, isVertexNumber, LABEL_COLUMN, ORIGINAL_ID_KEY, parseIntervals, parseSectionHeader, PARTITION_COLUMN, POSITION_COLUMN, RELATION_COLUMN, SHAPE_COLUMN, SPELLS_COLUMN, tokenize, VALUE_COLUMN, VALUE_FIELD, VECTOR_COLUMN, } from "./syntax.js";
-/** Issue codes of the Pajek importer. */
+import { decodeCharacterReferences, isCommentOrBlank, isIntervalToken, isProjectObject, isSectionLine, isShapeKeyword, isVertexNumber, LABEL_COLUMN, ORIGINAL_ID_KEY, parseIntervals, parseSectionHeader, PARTITION_COLUMN, POSITION_COLUMN, RELATION_COLUMN, SHAPE_COLUMN, SPELLS_COLUMN, tokenize, VALUE_COLUMN, VALUE_FIELD, VECTOR_COLUMN, } from "./syntax.js";
+/**
+ * Issue codes of the Pajek importer.
+ * @category Built-in formats
+ */
 export const PAJEK_ISSUE = Object.freeze({
-    /** The input holds invalid UTF-8 (fatal). */
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /** 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,
-    /** Fatal: no `*Vertices` section (an empty file, or not a Pajek network). */
+    /** There is no `*Vertices` section: the file is empty or not a Pajek network. The import stops. */
     NO_VERTICES: "E_PAJEK_NO_VERTICES",
-    /** Fatal: `*Vertices` without a vertex count, one the sink cannot hold, or a first-mode count outside 0..N. */
+    /**
+     * `*Vertices` without a vertex count, with a count too large to hold, or with a first-mode count outside 0 to N;
+     * the import stops.
+     */
     VERTICES_COUNT: "E_PAJEK_VERTICES_COUNT",
-    /** A project file holds several networks; import() reads the first, importAll() reads every one. */
+    /**
+     * 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 data line before the first section header. */
     OUTSIDE_SECTION: "E_PAJEK_OUTSIDE_SECTION",
     /** A section header the importer cannot parse. */
     SYNTAX: SYNTAX_CODE,
     /** A double quote not closed before the end of the line. */
     UNTERMINATED_QUOTE: "E_PAJEK_UNTERMINATED_QUOTE",
-    /** A vertex line the grammar does not accept. */
+    /** A vertex line that is not in Pajek's vertex syntax; the vertex is skipped. */
     VERTEX_LINE: "E_PAJEK_VERTEX_LINE",
     /** A vertex number outside the declared range. */
     VERTEX_RANGE: "E_PAJEK_VERTEX_RANGE",
@@ -56,9 +77,12 @@ export const PAJEK_ISSUE = Object.freeze({
     VERTEX_COUNT: "W_PAJEK_VERTEX_COUNT",
     /** A second line for the same vertex; the later values overwrite. */
     DUPLICATE_NODE: DUPLICATE_NODE_CODE,
-    /** A line (arc, edge, list, matrix row, partition or vector value) the grammar does not accept. */
+    /**
+     * A line that is not in Pajek's syntax for its section (an arc, edge, list, matrix row, partition or vector
+     * value); it is skipped.
+     */
     LINE: "E_PAJEK_LINE",
-    /** A line endpoint outside the declared vertex range (the core's code, forwarded). */
+    /** An edge names a vertex number outside the range `*Vertices` declared; the edge is skipped. */
     UNKNOWN_NODE: "E_UNKNOWN_NODE",
     /** A malformed time interval token. */
     INTERVAL: "E_PAJEK_INTERVAL",
@@ -70,32 +94,57 @@ export const PAJEK_ISSUE = Object.freeze({
     OBJECT_COUNT: "E_PAJEK_OBJECT_COUNT",
     /** A project-file section (`*Events`, `*Permutation`, ...) the importer does not read; its lines are skipped. */
     UNSUPPORTED_SECTION: "W_PAJEK_UNSUPPORTED_SECTION",
-    /** Tokens after a section header the grammar does not account for. */
+    /** A section header has extra words Pajek does not define; they are ignored. */
     HEADER_EXTRA: "W_PAJEK_HEADER_EXTRA",
     /** The file declares vertices but no line section. */
     NO_LINES: "W_PAJEK_NO_LINES",
-    /** Vertex numbering starts at 0 rather than 1. */
+    /** Vertex numbering starts at 0 rather than 1, found by `firstVertex: "auto"` (passing `firstVertex: 0` says so and gives no warning). */
     ZERO_BASED: "W_PAJEK_ZERO_BASED",
     /** Vertex lines mix two and three coordinates. */
     COORD_DIMS: "W_PAJEK_COORD_DIMS",
     /** Two vertices share a label under nodeIdFrom "label" and became one node. */
     LABEL_MERGED: "W_PAJEK_LABEL_MERGED",
-    /** Two distinct label texts became one numeric id under ids "number". */
+    /** Two different labels became the same number because `ids` is "number", so their vertices were merged. */
     ID_MERGED: ID_MERGED_CODE,
-    /** A parameter column of `2.0`-style text kept at the value-inferred dtype (the sink cannot widen). */
+    /**
+     * 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,
-    /** A structural column (label, position, shape, spells, relation) renamed `<name>#<id>` because the name was taken (design section 5.6). */
+    /** A structural column (label, position, shape, spells, relation) renamed `<name>#<id>` because the name was taken. */
     COLUMN_RENAMED: RENAMED_CODE,
-    /** A structural 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 vertices carry the same `graphty_originalId` under restoreMangledIds and became one node. */
     ORIGINAL_ID_MERGED: "W_PAJEK_ORIGINAL_ID_MERGED",
     /** A vertex line's `graphty_originalId` came after a later vertex's line had created it under its number. */
     ORIGINAL_ID_UNRESTORED: "W_PAJEK_ORIGINAL_ID_UNRESTORED",
-    /** A common option the importer has no use for (weightFrom naming a parameter and restoreMangledIds are honoured; long, hyperedges are not). */
+    /** 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 caller passed that the caller's sink does not use (the shared W_SINK_OPTION). */
+    /**
+     * 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,
+    /** A double quote inside a token (a CSV-style doubled quote, a quote mid-word): removed and the parts joined. */
+    QUOTE_IN_TOKEN: "W_PAJEK_QUOTE_IN_TOKEN",
+    /** The same parameter twice on one line; the later value stands. */
+    DUPLICATE_ATTRIBUTE: DUPLICATE_ATTRIBUTE_CODE,
+    /** A character reference beyond U+10FFFF in a label; kept as written. */
+    REFERENCE_RANGE: "W_PAJEK_REFERENCE_RANGE",
+    /** A line of a two-mode network whose endpoints are both in one mode. */
+    TWO_MODE_LINE: "W_PAJEK_TWO_MODE_LINE",
+    /** A bare non-integer number read as a vertex label before two coordinates (`1 0.1 0.2 0.3`); it may be an x y z line without a label. */
+    NUMERIC_LABEL: "W_PAJEK_NUMERIC_LABEL",
+    /** A relation number given a second name by a later `*Arcs :k "name"` header. */
+    RELATION_RENAMED: "W_PAJEK_RELATION_RENAMED",
+    /** A negative vertex number in an adjacency list, read as its absolute value. */
+    NEGATIVE_LIST_ENTRY: "W_PAJEK_NEGATIVE_LIST_ENTRY",
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
+    PRECISION: PRECISION_CODE,
 });
 /** The common options the Pajek importer reads (the rest is reported by reportUnusedOptions). */
 const USED_OPTIONS = new Set([
@@ -117,6 +166,9 @@ const DEFAULTS = { ids: "canonical", defaultDirected: true, weightFrom: VALUE_FI
 /** Lines between two checks of the cancellation signal (a whole string input is one chunk). */
 const ABORT_CHECK_INTERVAL = 64;
 const FIRST_VERTEX_VALUES = new Set([0, 1, "auto"]);
+/** A numeral that is not a finite number (`1e999`, `NaN`, `Infinity`): never a parameter key. */
+const NUMERAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+const NON_FINITE_WORD = /^[+-]?(?:nan|inf|infinity)$/i;
 const LABEL_DECL = {
     name: LABEL_COLUMN,
     dtype: "string",
@@ -214,6 +266,8 @@ class PajekParser {
         this.relation = null;
         /** `*Vertices N`; -1 before the header. */
         this.vertexCount = -1;
+        /** The line of the `*Vertices` header. */
+        this.verticesLine = 0;
         /** The first-mode count of a two-mode network, or null. */
         this.firstMode = null;
         this.networkName = null;
@@ -232,6 +286,10 @@ class PajekParser {
         this.objects = [];
         /** Set when the previous line was a project-object header, whose `*Vertices N` line comes next. */
         this.objectHeader = false;
+        /** The first unsupported section keyword, for the message of a file without `*Vertices`. */
+        this.firstUnsupported = null;
+        /** Vertex lines skipped because their number is outside the declared range (not lines of declared vertices). */
+        this.outOfRange = 0;
         /** Node index per vertex position (vertex number minus base). */
         this.indexOfPos = new Uint32Array(0);
         /**
@@ -302,7 +360,7 @@ class PajekParser {
                     this.matrixLine(text, line);
                     return false;
                 case "object":
-                    this.objectLine(text);
+                    this.objectLine(text, line);
                     return false;
                 case "skip":
                     return false;
@@ -327,7 +385,10 @@ class PajekParser {
      */
     finish() {
         if (this.vertexCount < 0) {
-            this.report.fail(PAJEK_ISSUE.NO_VERTICES, "not a Pajek network: no *Vertices section found");
+            const seen = this.firstUnsupported === null
+                ? ""
+                : ` (the file has the unrecognised section *${this.firstUnsupported})`;
+            this.report.fail(PAJEK_ISSUE.NO_VERTICES, `not a Pajek network: no *Vertices section found${seen}`);
         }
         this.endSection();
         this.finishVertices();
@@ -341,7 +402,7 @@ class PajekParser {
         }
         const objects = this.writeObjects();
         if (this.coercer.mergeCount > 0) {
-            this.report.warning("coercion", PAJEK_ISSUE.ID_MERGED, `${this.coercer.mergeCount} label(s) merged into an id another label already produced under ids "number"`);
+            this.report.warning("coercion", PAJEK_ISSUE.ID_MERGED, `${this.coercer.mergeCount} label${plural(this.coercer.mergeCount)} merged into an id another label already produced under ids "number"`);
         }
         const pajek = {
             ...(this.firstMode === null ? {} : { firstMode: this.firstMode }),
@@ -383,7 +444,7 @@ class PajekParser {
             }
             const declared = object.count ?? object.values.length;
             if (declared !== this.vertexCount || object.values.length !== declared) {
-                this.report.error("validation-error", PAJEK_ISSUE.OBJECT_COUNT, `*${partition ? "Partition" : "Vector"} "${object.name}" declares ${declared} vertices and holds ${object.values.length} value(s); the network has ${this.vertexCount}`, where);
+                this.report.error("validation-error", PAJEK_ISSUE.OBJECT_COUNT, `*${partition ? "Partition" : "Vector"} "${object.name}" declares ${declared} vertices and holds ${object.values.length} value${plural(object.values.length)}; the network has ${this.vertexCount}`, where);
             }
             written.push({ kind: object.kind, name: object.name, column: decl.name });
         }
@@ -405,7 +466,7 @@ class PajekParser {
             throw new LineError("parse-error", PAJEK_ISSUE.SYNTAX, `cannot read the section header "${text}"`);
         }
         if (h.extra.length > 0) {
-            this.report.warning("validation-error", PAJEK_ISSUE.HEADER_EXTRA, `ignored ${h.extra.length} unexpected token(s) after *${h.keyword}: ${h.extra.join(" ")}`, { line });
+            this.report.warning("validation-error", PAJEK_ISSUE.HEADER_EXTRA, `ignored ${h.extra.length} unexpected token${plural(h.extra.length)} after *${h.keyword}: ${h.extra.join(" ")}`, { line });
         }
         switch (h.kind) {
             case "network":
@@ -453,7 +514,9 @@ class PajekParser {
                 return;
             case "unsupported":
                 this.section = "skip";
-                this.objectHeader = true;
+                // only a project object's next line is its own `*Vertices N`
+                this.objectHeader = isProjectObject(h.keyword);
+                this.firstUnsupported ?? (this.firstUnsupported = h.keyword);
                 this.report.warning("unsupported", PAJEK_ISSUE.UNSUPPORTED_SECTION, `the *${h.keyword} section is not supported; its lines are skipped`, { line });
                 return;
             default: {
@@ -478,8 +541,9 @@ class PajekParser {
             this.report.fail(PAJEK_ISSUE.VERTICES_COUNT, `*Vertices ${h.count} ${h.secondCount}: the first-mode count is not within 0..${h.count}`, { line });
         }
         try {
-            // the declared count must be reservable (the sink is the authority on what it can hold,
-            // E_TOO_LARGE beyond MAX_COUNT) before any vertex is materialised
+            // the declared count must be reservable (the sink is the authority on what it can hold;
+            // the builder refuses more than its id map holds with E_TOO_LARGE) before any vertex
+            // or per-vertex table is allocated
             this.sink.reserve(h.count);
         }
         catch (err) {
@@ -489,6 +553,7 @@ class PajekParser {
             });
         }
         this.vertexCount = h.count;
+        this.verticesLine = line;
         if (h.secondCount !== null) {
             this.firstMode = h.secondCount;
         }
@@ -525,7 +590,12 @@ class PajekParser {
         this.kind = kind;
         this.relation = h.relation === null ? null : (h.name ?? String(h.relation));
         if (h.relation !== null) {
-            this.relationNames.set(h.relation, this.relation ?? String(h.relation));
+            const name = this.relation ?? String(h.relation);
+            const before = this.relationNames.get(h.relation);
+            if (before !== undefined && before !== name) {
+                this.report.warning("validation-error", PAJEK_ISSUE.RELATION_RENAMED, `relation ${h.relation} was named ${JSON.stringify(before)} and is now named ${JSON.stringify(name)}; its lines carry the name of their own section`, { line, element: String(h.relation) });
+            }
+            this.relationNames.set(h.relation, name);
         }
     }
     /**
@@ -534,7 +604,7 @@ class PajekParser {
     endSection() {
         const rows = this.firstMode ?? this.vertexCount;
         if (this.section === "matrix" && this.matrixRows !== rows) {
-            this.report.error("validation-error", PAJEK_ISSUE.MATRIX_ROWS, `*Matrix has ${this.matrixRows} row(s); *Vertices declares ${rows}`);
+            this.report.error("validation-error", PAJEK_ISSUE.MATRIX_ROWS, `*Matrix has ${this.matrixRows} row${plural(this.matrixRows)}; *Vertices declares ${rows}`);
         }
         this.section = "none";
     }
@@ -548,7 +618,8 @@ class PajekParser {
     setBase(base, line) {
         this.base = base;
         this.baseKnown = true;
-        if (base === 0) {
+        // the caller who passed firstVertex: 0 knows the numbering; the warning is for a guess
+        if (base === 0 && this.firstVertex === "auto") {
             this.report.warning("coercion", PAJEK_ISSUE.ZERO_BASED, "vertex numbering starts at 0; Pajek numbers vertices from 1", { line });
         }
     }
@@ -563,12 +634,29 @@ class PajekParser {
         }
         this.nodesCreated = true;
         const n = this.vertexCount;
-        const { sink } = this;
         for (let pos = 0; pos < n; pos++) {
-            this.indexOfPos[pos] = sink.addNode(this.idOfNumber(pos + this.base));
+            this.indexOfPos[pos] = this.addNode(this.idOfNumber(pos + this.base));
         }
         this.report.counts.nodes += n;
     }
+    /**
+     * Add a vertex to the sink. A sink that cannot hold the declared vertex set (the builder's
+     * E_TOO_LARGE id map limit) makes the file unreadable, so its refusal is fatal; any other
+     * error passes to the caller.
+     * @param id - the vertex id
+     * @returns the node index
+     */
+    addNode(id) {
+        try {
+            return this.sink.addNode(id);
+        }
+        catch (err) {
+            if (!(err instanceof GraphFormatError) || err.code !== "E_TOO_LARGE") {
+                throw err;
+            }
+            return this.report.fail(PAJEK_ISSUE.VERTICES_COUNT, `*Vertices ${this.vertexCount}: the sink cannot hold that many (${err.message})`, { line: this.verticesLine });
+        }
+    }
     /**
      * The id of a vertex number under nodeIdFrom "id" (the number coerced by the ids rule) or
      * "index" (the position).
@@ -624,9 +712,9 @@ class PajekParser {
             }
         }
         // a partial list: fewer lines than declared, counting the lines skipped after an error
-        const lines = this.seenCount + this.report.counts.skippedNodes;
+        const lines = this.seenCount + this.report.counts.skippedNodes - this.outOfRange;
         if (this.seenCount > 0 && lines < n) {
-            this.report.warning("validation-error", PAJEK_ISSUE.VERTEX_COUNT, `*Vertices declares ${n} vertices but ${lines} vertex line(s) were read; the others have no label`);
+            this.report.warning("validation-error", PAJEK_ISSUE.VERTEX_COUNT, `*Vertices declares ${n} vertices but ${lines} vertex line${plural(lines)} ${agree(lines, "was", "were")} read; the others have no label`);
         }
     }
     /**
@@ -635,7 +723,7 @@ class PajekParser {
      * @param line - the line number
      */
     vertexLine(text, line) {
-        const tokens = this.tokens(text, "node");
+        const tokens = this.tokens(text, "node", line);
         if (!isVertexNumber(tokens[0])) {
             this.report.counts.skippedNodes++;
             throw new LineError("parse-error", PAJEK_ISSUE.VERTEX_LINE, `a vertex line starts with a vertex number, not "${tokens[0]}"`);
@@ -647,13 +735,14 @@ class PajekParser {
         const pos = k - this.base;
         if (pos < 0 || pos >= this.vertexCount) {
             this.report.counts.skippedNodes++;
+            this.outOfRange++;
             throw new LineError("validation-error", PAJEK_ISSUE.VERTEX_RANGE, `vertex ${k} is outside ${this.base}..${this.base + this.vertexCount - 1}`);
         }
         // parse everything before writing anything
         let i = 1;
         let label = null;
         if (tokens.length > 1 && !startsWithCoordinates(text, tokens)) {
-            label = decodeCharacterReferences(tokens[1]);
+            label = this.labelOf(tokens[1], k, line);
             i = 2;
         }
         let x = 0;
@@ -675,12 +764,13 @@ class PajekParser {
             this.report.counts.skippedNodes++;
             throw new LineError("parse-error", PAJEK_ISSUE.VERTEX_LINE, `vertex ${k}: a single coordinate "${tokens[i]}"; coordinates are x y [z]`);
         }
+        this.checkCoordinates(text, tokens, i, dims === 2 && label !== null, k, line);
         let shape = null;
         if (i < tokens.length && isShapeKeyword(tokens[i])) {
             shape = tokens[i].toLowerCase();
             i++;
         }
-        const extras = this.extras(tokens, i, "node");
+        const extras = this.extras(tokens, i, "node", line);
         const restored = this.restoredId(extras);
         this.createNodes();
         // write
@@ -727,14 +817,7 @@ class PajekParser {
             sink.setNodeValue(this.labelHandle, index, label);
         }
         if (dims > 0) {
-            if (this.positionHandle === INVALID_INDEX) {
-                this.coordDims = dims;
-                this.positionHandle = declareResolved(sink, "node", positionDecl(dims), this.report, { line }).handle;
-            }
-            else if (dims !== this.coordDims) {
-                this.report.warnOnce("validation-error", PAJEK_ISSUE.COORD_DIMS, `vertex lines mix ${this.coordDims} and ${dims} coordinates; the position column records sourceDims ${this.coordDims}`, { line, element: String(k) });
-            }
-            sink.setNodeValue(this.positionHandle, index, [x, y, z]);
+            this.writePosition(index, dims, [x, y, z], k, line);
         }
         if (shape !== null) {
             if (this.shapeHandle === INVALID_INDEX && this.nodeParams.has(SHAPE_COLUMN)) {
@@ -758,6 +841,65 @@ class PajekParser {
             sink.setNodeValue(this.nodeSpellsHandle, index, extras.spells);
         }
     }
+    /**
+     * A vertex label as written, its character references decoded.
+     * @param token - the label token
+     * @param k - the vertex number
+     * @param line - the line number
+     * @returns the label
+     */
+    labelOf(token, k, line) {
+        return decodeCharacterReferences(token, (reference) => {
+            this.report.warnOnce("validation-error", PAJEK_ISSUE.REFERENCE_RANGE, `character reference ${reference} is beyond U+10FFFF; it is kept as written`, { line, element: String(k) }, `${PAJEK_ISSUE.REFERENCE_RANGE}:${reference}`);
+        });
+    }
+    /**
+     * Check the token after a vertex line's coordinates (or where they would stand): a numeral the
+     * number range cannot hold is a broken coordinate, never a parameter named "1e999" or "NaN";
+     * and a bare non-integer label before two coordinates may be the x of an x y z line.
+     * @param text - the line
+     * @param tokens - its tokens
+     * @param i - the index after the coordinates
+     * @param labelAndXy - whether the line was read as a label and two coordinates
+     * @param k - the vertex number
+     * @param line - the line number
+     */
+    checkCoordinates(text, tokens, i, labelAndXy, k, line) {
+        if (i < tokens.length &&
+            (NUMERAL.test(tokens[i]) || NON_FINITE_WORD.test(tokens[i])) &&
+            !isNumericText(tokens[i])) {
+            this.report.counts.skippedNodes++;
+            throw new LineError("parse-error", PAJEK_ISSUE.VERTEX_LINE, `vertex ${k}: coordinate "${tokens[i]}" is not a finite number`);
+        }
+        const label = tokens[1];
+        if (labelAndXy &&
+            isNumericText(label) &&
+            !Number.isInteger(Number(label)) &&
+            !quotedAfterNumber(text, tokens)) {
+            this.report.warnOnce("validation-error", PAJEK_ISSUE.NUMERIC_LABEL, `vertex ${k}: "${label} ${tokens[2]} ${tokens[3]}" is read as the label ${label} and x y; quote the label, or it may be meant as x y z`, { line, element: String(k) });
+        }
+    }
+    /**
+     * Write a vertex's coordinates into the position column (f32 x 3), declared on first use.
+     * @param index - the node index
+     * @param dims - 2 or 3, the coordinates the line gave
+     * @param point - x, y, z (0 when absent)
+     * @param k - the vertex number
+     * @param line - the line number
+     */
+    writePosition(index, dims, point, k, line) {
+        if (this.positionHandle === INVALID_INDEX) {
+            this.coordDims = dims;
+            this.positionHandle = declareResolved(this.sink, "node", positionDecl(dims), this.report, { line }).handle;
+        }
+        else if (dims !== this.coordDims) {
+            this.report.warnOnce("validation-error", PAJEK_ISSUE.COORD_DIMS, `vertex lines mix ${this.coordDims} and ${dims} coordinates; the position column records sourceDims ${this.coordDims}`, { line, element: String(k) });
+        }
+        if (!point.every(survivesF32)) {
+            this.report.warnOnce("precision", PAJEK_ISSUE.PRECISION, `vertex ${k} has a coordinate the f32 position column rounds (warned once)`, { line, element: String(k) }, `${PAJEK_ISSUE.PRECISION}:position`);
+        }
+        this.sink.setNodeValue(this.positionHandle, index, point);
+    }
     /**
      * Whether a `graphty_originalId` parameter is restored as the vertex id: restoreMangledIds
      * under nodeIdFrom "id" (under "label" / "index" the parameter stays an ordinary column).
@@ -775,7 +917,7 @@ class PajekParser {
     numberedNode(ids, pos) {
         const id = this.idOfNumber(pos + this.base);
         ids[pos] = id;
-        this.indexOfPos[pos] = this.sink.addNode(id);
+        this.indexOfPos[pos] = this.addNode(id);
         this.report.counts.nodes++;
     }
     /**
@@ -812,7 +954,7 @@ class PajekParser {
     deferredNode(ids, pos, k, text, line, from) {
         const id = text === null ? this.idOfNumber(k) : this.coercer.text(text);
         const before = this.sink.indexOf(id);
-        const index = this.sink.addNode(id);
+        const index = this.addNode(id);
         ids[pos] = id;
         this.indexOfPos[pos] = index;
         this.report.counts.nodes++;
@@ -830,7 +972,7 @@ class PajekParser {
      * @param line - the line number
      */
     edgeLine(text, line) {
-        let tokens = this.tokens(text, "edge");
+        let tokens = this.tokens(text, "edge", line);
         // a `k:` prefix puts this one line in relation k
         let { relation } = this;
         const prefix = RELATION_PREFIX.exec(tokens[0]);
@@ -851,7 +993,7 @@ class PajekParser {
             valueText = tokens[i];
             i++;
         }
-        const extras = this.extras(tokens, i, "edge");
+        const extras = this.extras(tokens, i, "edge", line);
         const { weightFrom } = this.options;
         let weight;
         let valueIsWeight = false;
@@ -883,13 +1025,16 @@ class PajekParser {
      * @param line - the line number
      */
     listLine(text, line) {
-        const tokens = this.tokens(text, "edge");
+        const tokens = this.tokens(text, "edge", line);
         for (const token of tokens) {
             if (!LIST_VERTEX.test(token)) {
                 this.report.counts.skippedEdges++;
                 throw new LineError("parse-error", PAJEK_ISSUE.LINE, `an adjacency list holds vertex numbers only, not "${token}"`);
             }
         }
+        if (tokens.some((token) => token.startsWith("-"))) {
+            this.report.warnOnce("coercion", PAJEK_ISSUE.NEGATIVE_LIST_ENTRY, "an adjacency list holds a negative vertex number; it is read as its absolute value and the sign is dropped", { line });
+        }
         const u = this.endpoint(Math.abs(Number(tokens[0])));
         for (let i = 1; i < tokens.length; i++) {
             const v = this.endpoint(Math.abs(Number(tokens[i])));
@@ -905,17 +1050,17 @@ class PajekParser {
      * @param line - the line number
      */
     matrixLine(text, line) {
-        const tokens = this.tokens(text, "edge");
+        const tokens = this.tokens(text, "edge", line);
         const row = this.matrixRows;
         this.matrixRows++;
         const offset = this.firstMode ?? 0;
         const rows = this.firstMode ?? this.vertexCount;
         const columns = this.vertexCount - offset;
         if (row >= rows) {
-            throw new LineError("validation-error", PAJEK_ISSUE.MATRIX_ROWS, `*Matrix row ${row + 1} is beyond the ${rows} declared row(s)`);
+            throw new LineError("validation-error", PAJEK_ISSUE.MATRIX_ROWS, `*Matrix row ${row + 1} is beyond the ${rows} declared row${plural(rows)}`);
         }
         if (tokens.length < columns) {
-            throw new LineError("parse-error", PAJEK_ISSUE.LINE, `*Matrix row ${row + 1} has ${tokens.length} value(s); the matrix has ${columns} column(s)`);
+            throw new LineError("parse-error", PAJEK_ISSUE.LINE, `*Matrix row ${row + 1} has ${tokens.length} value${plural(tokens.length)}; the matrix has ${columns} column${plural(columns)}`);
         }
         for (let j = 0; j < columns; j++) {
             if (!isNumericText(tokens[j])) {
@@ -923,7 +1068,7 @@ class PajekParser {
             }
         }
         if (tokens.length > columns) {
-            this.report.warnOnce("validation-error", PAJEK_ISSUE.MATRIX_EXTRA, `*Matrix row ${row + 1} has ${tokens.length} value(s) for ${columns} column(s); the extra values are ignored`, { line });
+            this.report.warnOnce("validation-error", PAJEK_ISSUE.MATRIX_EXTRA, `*Matrix row ${row + 1} has ${tokens.length} value${plural(tokens.length)} for ${columns} column${plural(columns)}; the extra values are ignored`, { line });
         }
         for (let j = 0; j < columns; j++) {
             const value = Number(tokens[j]);
@@ -938,10 +1083,11 @@ class PajekParser {
      * A value line of a `*Partition` (integers) or `*Vector` (numbers): the values of the next
      * vertices, usually one per line.
      * @param text - the line
+     * @param line - the line number
      */
-    objectLine(text) {
+    objectLine(text, line) {
         const object = this.objects[this.objects.length - 1];
-        const tokens = this.tokens(text, "node");
+        const tokens = this.tokens(text, "node", line);
         for (const token of tokens) {
             if (!isNumericText(token) || (object.kind === "partition" && !isI32(Number(token)))) {
                 // keep the later values on their vertices
@@ -967,6 +1113,9 @@ class PajekParser {
             this.directionSet = true;
             this.resolver.setHeader(this.kind === "directed", { line });
         }
+        if (this.firstMode !== null && u < this.firstMode === v < this.firstMode) {
+            this.report.warnOnce("validation-error", PAJEK_ISSUE.TWO_MODE_LINE, `a line of the two-mode network joins two vertices of the ${u < this.firstMode ? "first" : "second"} mode`, { line });
+        }
         const before = sink.edgeCount;
         const e = this.resolver.addEdge(this.idAt(u), this.idAt(v), this.kind, weight, { line });
         this.report.counts.edges += sink.edgeCount - before;
@@ -1027,7 +1176,7 @@ class PajekParser {
      */
     weightOf(text) {
         try {
-            return parseWeightText(text);
+            return parseWeightText(text, this.report);
         }
         catch (err) {
             this.report.counts.skippedEdges++;
@@ -1039,10 +1188,15 @@ class PajekParser {
      * Tokenize a data line.
      * @param text - the line
      * @param domain - what is skipped on an unterminated quote
+     * @param line - the line number
      * @returns the tokens (at least one: blank lines never reach here)
      */
-    tokens(text, domain) {
-        const tokens = tokenize(text);
+    tokens(text, domain, line) {
+        const notes = { oddQuote: false };
+        const tokens = tokenize(text, notes);
+        if (notes.oddQuote) {
+            this.report.warnOnce("coercion", PAJEK_ISSUE.QUOTE_IN_TOKEN, "a double quote inside a token is removed and the parts joined (Pajek has no escape for a quote)", { line });
+        }
         if (tokens === null) {
             if (domain === "node") {
                 this.report.counts.skippedNodes++;
@@ -1060,22 +1214,16 @@ class PajekParser {
      * @param tokens - the row's tokens
      * @param start - the first token to read
      * @param domain - what is skipped when the row is malformed
+     * @param line - the line number
      * @returns the parsed extras
      */
-    extras(tokens, start, domain) {
+    extras(tokens, start, domain, line) {
         const extras = { keys: [], values: [], spells: null };
+        const seen = new Set();
         for (let i = start; i < tokens.length;) {
             const token = tokens[i];
-            if (isIntervalToken(token)) {
-                try {
-                    const spells = parseIntervals(token);
-                    // an empty `[]` is no spell at all
-                    extras.spells = spells.length === 0 ? null : spells;
-                }
-                catch (err) {
-                    this.skip(domain);
-                    throw new LineError("validation-error", PAJEK_ISSUE.INTERVAL, err instanceof Error ? err.message : String(err));
-                }
+            if (token.startsWith("[")) {
+                extras.spells = this.intervals(token, domain);
                 i++;
                 continue;
             }
@@ -1083,12 +1231,36 @@ class PajekParser {
                 this.skip(domain);
                 throw new LineError("parse-error", domain === "node" ? PAJEK_ISSUE.VERTEX_LINE : PAJEK_ISSUE.LINE, `parameter "${token}" has no value`);
             }
+            if (seen.has(token)) {
+                this.report.warning("merged", PAJEK_ISSUE.DUPLICATE_ATTRIBUTE, `parameter ${JSON.stringify(token)} is given twice on one line; the later value ${JSON.stringify(tokens[i + 1])} stands`, { line, element: token });
+            }
+            seen.add(token);
             extras.keys.push(token);
             extras.values.push(tokens[i + 1]);
             i += 2;
         }
         return extras;
     }
+    /**
+     * The spells of a row's interval token; a malformed one skips the row.
+     * @param token - the token, starting with "["
+     * @param domain - what is skipped when the token is malformed
+     * @returns the spells, or null for an empty `[]`, which is no spell at all
+     */
+    intervals(token, domain) {
+        if (!isIntervalToken(token)) {
+            this.skip(domain);
+            throw new LineError("validation-error", PAJEK_ISSUE.INTERVAL, `time interval ${token} is not closed by "]"`);
+        }
+        try {
+            const spells = parseIntervals(token);
+            return spells.length === 0 ? null : spells;
+        }
+        catch (err) {
+            this.skip(domain);
+            throw new LineError("validation-error", PAJEK_ISSUE.INTERVAL, err instanceof Error ? err.message : String(err));
+        }
+    }
     /**
      * Count a skipped element.
      * @param domain - node or edge
@@ -1135,7 +1307,7 @@ class PajekParser {
  * @returns true when tokens[1] is the first coordinate
  */
 function startsWithCoordinates(text, tokens) {
-    if (text.trimStart().slice(tokens[0].length).trimStart().startsWith('"')) {
+    if (quotedAfterNumber(text, tokens)) {
         return false;
     }
     let run = 0;
@@ -1144,6 +1316,15 @@ function startsWithCoordinates(text, tokens) {
     }
     return run === 2;
 }
+/**
+ * Whether the token after a row's vertex number is written in quotes.
+ * @param text - the line
+ * @param tokens - its tokens
+ * @returns true when the second token was quoted
+ */
+function quotedAfterNumber(text, tokens) {
+    return text.trimStart().slice(tokens[0].length).trimStart().startsWith('"');
+}
 /**
  * Resolve the firstVertex option.
  * @param value - the caller's value
@@ -1161,24 +1342,41 @@ function firstVertexOption(value) {
         found: value,
     });
 }
-const HEAD_PATTERN = /^\s*\*(vertices|network)\b/i;
-/** The Pajek NET importer. */
+/**
+ * The section a Pajek network starts with, after blank lines and `%` comment lines.
+ * @param text - the head of the input
+ * @returns "vertices" or "network" (lower case), or null when the text starts otherwise
+ */
+function headSection(text) {
+    let rest = text.trimStart();
+    while (rest.startsWith("%")) {
+        const end = rest.search(/[\r\n]/);
+        rest = end < 0 ? "" : rest.slice(end).trimStart();
+    }
+    return /^\*(vertices|network)\b/i.exec(rest)?.[1].toLowerCase() ?? null;
+}
+/**
+ * The Pajek NET importer.
+ * @category Built-in formats
+ */
 export const pajekImporter = Object.freeze({
     format: "pajek",
+    options: Object.freeze(["firstVertex"]),
     extensions: Object.freeze([".net", ".paj"]),
     mimeTypes: Object.freeze(["text/x-pajek", "text/plain"]),
     /**
-     * Confidence that the input is a Pajek network: it starts with `*Vertices` (or `*Network`).
+     * Confidence that the input is a Pajek network: it starts with `*Vertices` (or `*Network`),
+     * after any `%` comment lines.
      * @param head - the first bytes
      * @returns 0.9 for a `*Vertices` start, 0.8 for `*Network`, 0 otherwise
      */
     sniff(head) {
-        const text = new TextDecoder("utf-8").decode(head.subarray(0, Math.min(head.byteLength, 512)));
-        const match = HEAD_PATTERN.exec(text.startsWith(String.fromCharCode(0xfeff)) ? text.slice(1) : text);
-        if (match === null) {
+        const text = new TextDecoder("utf-8").decode(head);
+        const section = headSection(text.startsWith("\ufeff") ? text.slice(1) : text);
+        if (section === null) {
             return 0;
         }
-        return match[1].toLowerCase() === "vertices" ? 0.9 : 0.8;
+        return section === "vertices" ? 0.9 : 0.8;
     },
     /**
      * Read a Pajek network into the sink.
@@ -1188,6 +1386,10 @@ export const pajekImporter = Object.freeze({
      * @returns the report
      */
     async import(input, sink, options) {
+        if (graphChosen(options)) {
+            // the choice is honored here too, not only by the registry
+            return importChosenGraph(pajekImporter, input, sink, options);
+        }
         const resolved = resolveImportOptions(options, DEFAULTS);
         const firstVertex = firstVertexOption(options?.firstVertex);
         const report = new ImportReportBuilder("pajek", resolved.errorLimit);
@@ -1199,7 +1401,8 @@ export const pajekImporter = Object.freeze({
         let rest = null;
         let restLine = 0;
         let sinceCheck = 0;
-        for await (const text of reader) {
+        for await (const raw of reader) {
+            const text = withoutStrayBom(raw);
             if (rest !== null) {
                 rest.line(text);
             }
@@ -1215,7 +1418,8 @@ export const pajekImporter = Object.freeze({
         }
         parser.finish();
         if (rest !== null) {
-            report.warning("unsupported", PAJEK_ISSUE.MULTIPLE_GRAPHS, `the project file holds ${rest.count} more network(s) after the first; import() reads the first, importAll() reads every one`, { line: restLine });
+            const objects = rest.objects > 0 ? `; ${rest.objects} *Partition / *Vector object(s) after them are not read` : "";
+            report.warning("unsupported", PAJEK_ISSUE.MULTIPLE_GRAPHS, `the project file holds ${rest.count} more network${plural(rest.count)} after the first; the first is read (graphIndex or graphName chooses another; importAllGraphs() reads every one)${objects}`, { line: restLine });
         }
         throwIfAborted(resolved.signal);
         return report.finish();
@@ -1244,7 +1448,8 @@ export const pajekImporter = Object.freeze({
         // decoding issues belong to the file, so they go to the first network's report
         const reader = new LineReader(input, reports[0], resolved);
         let sinceCheck = 0;
-        for await (const text of reader) {
+        for await (const raw of reader) {
+            const text = withoutStrayBom(raw);
             if (parser.line(text, reader.line)) {
                 parser.finish();
                 reports.push(new ImportReportBuilder("pajek", resolved.errorLimit));
@@ -1261,6 +1466,15 @@ export const pajekImporter = Object.freeze({
         return reports.map((r) => r.finish());
     },
 });
+/**
+ * A line without the U+FEFF that starts it: a BOM left at the start of a later line by
+ * concatenated files (the decoder removes only the first; the shared text check reports it).
+ * @param text - the line
+ * @returns the line without a leading U+FEFF
+ */
+function withoutStrayBom(text) {
+    return text.codePointAt(0) === 0xfeff ? text.slice(1) : text;
+}
 /**
  * Counts the networks of the rest of a project file by their headers alone, with the parser's
  * rule: a network starts at `*Network` after a named or populated one, or at a `*Vertices` after a
@@ -1271,6 +1485,8 @@ class NetworkCounter {
     constructor() {
         /** Networks started so far (the first header fed opens the first). */
         this.count = 0;
+        /** `*Partition` / `*Vector` objects seen; import() does not read them. */
+        this.objects = 0;
         this.named = false;
         this.populated = false;
         this.afterObjectHeader = false;
@@ -1293,8 +1509,12 @@ class NetworkCounter {
             return;
         }
         const { kind } = h;
-        if (kind === "partition" || kind === "vector" || kind === "unsupported") {
+        if (kind === "partition" || kind === "vector") {
             this.afterObjectHeader = true;
+            this.objects++;
+        }
+        else if (kind === "unsupported") {
+            this.afterObjectHeader = isProjectObject(h.keyword);
         }
         else if (kind === "network") {
             if (this.count === 0 || this.named || this.populated) {