@graphty/graph-io 0.3.25 → 0.3.26

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

@@ -20,21 +20,30 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareResolved, RENAMED_CODE, ROLE_TAKEN_CODE } from "../../common/attributes.js";
-import { BAD_VALUE_CODE, DANGLING_REFERENCE_CODE, DUPLICATE_ATTRIBUTE_CODE, DUPLICATE_NODE_CODE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MISSING_ID_CODE, OPTION_IGNORED_CODE, UNKNOWN_ELEMENT_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
+import { BAD_VALUE_CODE, DANGLING_REFERENCE_CODE, DUPLICATE_ATTRIBUTE_CODE, DUPLICATE_NODE_CODE, ELEMENT_ISSUE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, INPUT_ISSUE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MISSING_ID_CODE, OPTION_IGNORED_CODE, UNKNOWN_ELEMENT_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
 import { ID_MERGED_CODE, IdCoercer } from "../../common/ids.js";
 import { LineReader, throwIfAborted } from "../../common/input.js";
 import { OBO_NODE_COLUMNS, oboColumnDecl, PLACEHOLDER_COLUMN, SYNONYM_SCOPES } from "../../common/ontology.js";
 import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, SINK_OPTION_CODE, } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
-import { endsWithContinuation, hasStrayBrace, parseXref, parseXrefList, splitQualifiers, splitTagValue, stripComment, tokenize, unescapeObo, } from "./syntax.js";
-/** Issue codes of the OBO importer (design section 4.3). */
+import { endsWithContinuation, hasStrayBrace, parseXref, parseXrefList, splitFormFeeds, splitQualifiers, splitTagValue, stripComment, tokenize, unclosedBlock, unescapeObo, } from "./syntax.js";
+/**
+ * Issue codes of the OBO importer.
+ * @category Built-in formats
+ */
 export const OBO_ISSUE = Object.freeze({
-    /** The input is empty or whitespace (fatal). */
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /** The input is empty or whitespace. 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 or the encoding option chose (fatal). */
+    /**
+     * Some bytes are not valid in the encoding that was chosen (by a byte order mark or the `encoding` option). The
+     * import stops.
+     */
     INVALID_ENCODING: INVALID_ENCODING_CODE,
     /** Bytes that are not UTF-8 were read as windows-1252. */
     ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
@@ -44,9 +53,9 @@ export const OBO_ISSUE = Object.freeze({
     MISSING_ID: MISSING_ID_CODE,
     /** A clause whose value cannot be read (a boolean other than true / false, a relationship with one or three values); the clause is skipped. */
     BAD_VALUE: BAD_VALUE_CODE,
-    /** Two frames with one id were merged (spec 4.1.1). */
+    /** Two frames have the same id, so they were merged into one node. */
     DUPLICATE_NODE: DUPLICATE_NODE_CODE,
-    /** A single-valued tag given twice for one id (a cardinality violation); the first is kept. */
+    /** A tag that may appear once per frame appears twice; the first value is kept. */
     DUPLICATE_ATTRIBUTE: DUPLICATE_ATTRIBUTE_CODE,
     /** An unknown tag (kept in `obo.unrecognized`) or frame type (skipped), once per name. */
     UNKNOWN_ELEMENT: UNKNOWN_ELEMENT_CODE,
@@ -54,6 +63,16 @@ export const OBO_ISSUE = Object.freeze({
     DANGLING_REFERENCE: DANGLING_REFERENCE_CODE,
     /** A line without a colon, an unterminated quote, a def without its xref list, a qualifier block that does not parse, an unescaped brace. */
     SYNTAX: "W_OBO_SYNTAX",
+    /**
+     * Nothing in the input looks like OBO: there is no frame header and no header tag. It may be an HTML page, a JSON
+     * or GML file, or UTF-16 text without a byte order mark. The import stops.
+     */
+    NOT_OBO: "E_OBO_NOT_OBO",
+    /**
+     * The header has no `format-version` (OBO 1.2 and 1.4 require one), or names a version other than 1.0, 1.2 or 1.4.
+     * The file is read accepting the tags of every version.
+     */
+    FORMAT_VERSION: "W_OBO_FORMAT_VERSION",
     /** The frame's `id` is not its first clause; it is used anyway. */
     ID_NOT_FIRST: "W_OBO_ID_NOT_FIRST",
     /** A synonym without a scope in a file that does not say 1.2, or with a scope that is not one of the four. */
@@ -62,7 +81,7 @@ export const OBO_ISSUE = Object.freeze({
     UNDECLARED: "W_OBO_UNDECLARED",
     /** One id for a Term and a Typedef (or an Instance); the Term (the first node frame) is the node. */
     ID_KIND_CLASH: "W_OBO_ID_KIND_CLASH",
-    /** Fewer than two `intersection_of` or `union_of` clauses on a frame. */
+    /** A frame has only one `intersection_of` or `union_of` clause, where OBO needs at least two. */
     CARDINALITY: "W_OBO_CARDINALITY",
     /** An obsolete term with is_a / relationship, or replaced_by / consider on a term that is not obsolete. */
     OBSOLETION: "W_OBO_OBSOLETION",
@@ -70,19 +89,31 @@ export const OBO_ISSUE = Object.freeze({
     DEPRECATED_TAG: "W_OBO_DEPRECATED_TAG",
     /** A backslash line continuation (deprecated in 1.4). */
     DEPRECATED_SYNTAX: "W_OBO_DEPRECATED_SYNTAX",
-    /** A header clause kept in `meta.extra.obo.header` whose meaning is not applied (import, id-mapping, the treat-xrefs macros, owl-axioms). */
+    /**
+     * A header clause whose meaning graph-io does not apply (`import`, `id-mapping`, the `treat-xrefs` macros,
+     * `owl-axioms`); it is kept in `snapshot.meta.extra.obo.header`.
+     */
     HEADER_NOT_APPLIED: "W_OBO_HEADER_NOT_APPLIED",
     /** Obsolete terms and their edges left out under obsolete: "drop". */
     OBSOLETE_DROPPED: "W_OBO_OBSOLETE_DROPPED",
-    /** Two distinct id texts became one number under ids "number". */
+    /**
+     * Two different id texts became the same number because `ids` is "number" (for example, "042" and "42"), so their nodes
+     * were merged.
+     */
     ID_MERGED: ID_MERGED_CODE,
-    /** A vocabulary column renamed `<name>#obo` because the sink already holds the name. */
+    /** An OBO attribute was renamed `<name>#obo` because another attribute already has its name. */
     COLUMN_RENAMED: RENAMED_CODE,
-    /** A vocabulary 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,
-    /** A common option the format has no use for (defaultDirected, weightFrom, nodeIdFrom, ...). */
+    /** 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. */
+    /**
+     * 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 common options the OBO importer reads. */
@@ -97,7 +128,10 @@ const USED_OPTIONS = new Set([
     "signal",
     "onProgress",
     "encoding",
+    "restoreMangledIds",
 ]);
+/** The property_value relation under which the exporter keeps an id it rewrote (`sanitizeIds: "mangle"`). */
+const ORIGINAL_ID = "graphty:originalId";
 const DEFAULTS = { ids: "keep", defaultDirected: true, weightFrom: null };
 /** Frames between two checks of the cancellation signal. */
 const ABORT_CHECK_INTERVAL = 64;
@@ -111,8 +145,11 @@ const DEPRECATED_HEADER = new Map([
     ["typeref", "import"],
     ["version", "data-version"],
 ]);
-/** The 1.0 / 1.2 frame tags read as their 1.4 meaning: tag to [1.4 tag, synonym scope]. */
-const DEPRECATED_TAGS = new Map([
+/**
+ * The 1.0 / 1.2 frame tags read as their 1.4 meaning: tag to [1.4 tag, synonym scope].
+ * @category Plugin helpers
+ */
+export const DEPRECATED_TAGS = new Map([
     ["exact_synonym", ["synonym", "EXACT"]],
     ["narrow_synonym", ["synonym", "NARROW"]],
     ["broad_synonym", ["synonym", "BROAD"]],
@@ -131,8 +168,11 @@ const BUILTIN_RELATIONS = new Set([
     "union_of",
     "intersection_of",
 ]);
-/** Single-valued text tags (first value kept). */
-const TEXT_TAGS = new Set([
+/**
+ * Single-valued text tags (first value kept).
+ * @category Plugin helpers
+ */
+export const TEXT_TAGS = new Set([
     "name",
     "namespace",
     "comment",
@@ -142,10 +182,16 @@ const TEXT_TAGS = new Set([
     "range",
     "inverse_of",
 ]);
-/** Single-valued boolean tags. */
-const BOOL_TAGS = new Set(Object.keys(OBO_NODE_COLUMNS).filter((name) => OBO_NODE_COLUMNS[name].dtype === "bool"));
-/** Tags whose value is one id, collected in a list column. */
-const ID_LIST_TAGS = new Set([
+/**
+ * Single-valued boolean tags.
+ * @category Plugin helpers
+ */
+export const BOOL_TAGS = new Set(Object.keys(OBO_NODE_COLUMNS).filter((name) => OBO_NODE_COLUMNS[name].dtype === "bool"));
+/**
+ * Tags whose value is one id, collected in a list column.
+ * @category Plugin helpers
+ */
+export const ID_LIST_TAGS = new Set([
     "alt_id",
     "subset",
     "replaced_by",
@@ -156,8 +202,80 @@ const ID_LIST_TAGS = new Set([
     "transitive_over",
     "disjoint_over",
 ]);
-/** Tags that only a Typedef frame may carry (elsewhere they are unrecognized). */
-const TYPEDEF_TAGS = new Set([
+/** Header tags the specification allows once (the first is kept). */
+const SINGLE_HEADER_TAGS = new Set([
+    "format-version",
+    "data-version",
+    "version",
+    "date",
+    "saved-by",
+    "auto-generated-by",
+    "default-namespace",
+    "ontology",
+    "default-relationship-id-prefix",
+]);
+/** The format versions the importer knows (it reads their union). */
+const KNOWN_VERSION = /^(GO_)?1\.[024]$/;
+/** Tags whose value is an id, where a qualifier block cut short by a truncated file is dropped. */
+const ID_VALUE_TAGS = new Set([
+    ...ID_LIST_TAGS,
+    "is_a",
+    "instance_of",
+    "relationship",
+    "intersection_of",
+]);
+/** Warnings listed per code before the rest are summed up in one (a file of 50k unknown tags). */
+const MAX_TALLIES_PER_CODE = 100;
+/**
+ * Whether a text holds a control character other than tab, line feed, form feed (a line end in
+ * the 1.4 grammar, text inside quotes) and carriage return.
+ * @param text - the text
+ * @returns true when it does
+ */
+function hasControl(text) {
+    for (const ch of text) {
+        if ((ch < " " && ch !== "\t" && ch !== "\n" && ch !== "\f" && ch !== "\r") || ch === "\x7f") {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether a tag could name an OBO tag: no whitespace, control characters or the punctuation of
+ * other formats (`{`, `"`, `<`, brackets, parentheses).
+ * @param tag - the tag
+ * @returns true for a plausible tag
+ */
+function isTagName(tag) {
+    return tag.length > 0 && !hasControl(tag) && !/[\s{}"<>[\]()]/.test(tag);
+}
+/**
+ * A record with no prototype, so a key named after an Object.prototype member (`__proto__`,
+ * `constructor`, `toString`) is an own key like any other.
+ * @returns the empty record
+ */
+function ownRecord() {
+    return Object.create(null);
+}
+/**
+ * Append a value to the list of a key in a null-prototype record.
+ * @param map - the record
+ * @param key - the key
+ * @param value - the value
+ */
+function append(map, key, value) {
+    if (Object.hasOwn(map, key)) {
+        map[key].push(value);
+    }
+    else {
+        map[key] = [value];
+    }
+}
+/**
+ * Tags that only a Typedef frame may carry (elsewhere they are unrecognized).
+ * @category Plugin helpers
+ */
+export const TYPEDEF_TAGS = new Set([
     "domain",
     "range",
     "inverse_of",
@@ -214,10 +332,17 @@ class OboReader {
      * Create a reader.
      * @param report - the report
      * @param signal - the cancellation signal
+     * @param typedefsAsNodes - whether `[Typedef]` frames are nodes
      */
-    constructor(report, signal) {
+    constructor(report, signal, typedefsAsNodes) {
         /** Header clauses by tag, raw, in order. */
-        this.header = {};
+        this.header = ownRecord();
+        /** Whether any frame header was read. */
+        this.frameSeen = false;
+        /** Header clauses whose tag could be an OBO tag. */
+        this.tagClauses = 0;
+        /** The first line that is not a frame header, a comment or a tag-value line with a plausible tag. */
+        this.firstBadLine = null;
         this.version = null;
         this.defaultNamespace = null;
         this.subsets = new Set();
@@ -237,6 +362,7 @@ class OboReader {
         this.significant = false;
         this.report = report;
         this.signal = signal;
+        this.typedefsAsNodes = typedefsAsNodes;
     }
     /**
      * Read one logical line.
@@ -252,32 +378,71 @@ class OboReader {
         if (t.startsWith("!")) {
             return;
         }
-        const header = /^\[([^\]]*)\]\s*(?:!.*)?$/.exec(t);
-        if (header !== null) {
-            this.startFrame(header[1].trim(), line);
+        if (t.startsWith("[") && this.frameHeader(t, line)) {
             return;
         }
         // the comment goes first, so a colon inside it never makes `foo ! a:b` a tag-value line
         const tv = splitTagValue(stripComment(t));
-        if (tv === null) {
-            this.tally("parse-error", OBO_ISSUE.SYNTAX, "a line without a colon was skipped", "line", line);
+        if (tv === null || tv.tag.length === 0) {
+            this.firstBadLine ?? (this.firstBadLine = line);
+            const what = tv === null ? "a line without a colon was skipped" : "a line without a tag was skipped";
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, what, "line", line);
             return;
         }
         const clause = { tag: tv.tag, value: stripComment(tv.rest), line };
         if (this.frame === null) {
+            if (isTagName(tv.tag)) {
+                this.tagClauses++;
+            }
+            else {
+                this.firstBadLine ?? (this.firstBadLine = line);
+            }
             this.headerClause(clause);
         }
         else {
             this.frame.clauses.push(clause);
         }
     }
+    /**
+     * Start a frame at a line opening with `[`: a well-formed header, or one damaged so that only a
+     * frame header can be meant (a known frame name, or no colon: `[Term`, `[Term] extra`), with a
+     * warning, so the clauses after it never merge into the frame before.
+     * @param t - the trimmed line
+     * @param line - its number
+     * @returns false when the line is not a frame header
+     */
+    frameHeader(t, line) {
+        const close = t.indexOf("]");
+        const name = (close < 0 ? t.slice(1) : t.slice(1, close)).trim();
+        const after = close < 0 ? "" : t.slice(close + 1).trim();
+        const clean = close >= 0 && (after.length === 0 || after.startsWith("!"));
+        if (!clean && !FRAME_KINDS.has(name) && t.includes(":")) {
+            return false;
+        }
+        if (!clean) {
+            const what = close < 0
+                ? "a frame header without its closing ] starts the frame"
+                : "text after a frame header was ignored";
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, what, `[${name}]`, line);
+        }
+        // a known frame name, or a clean header with a name: anything else (`[`, `[{"id": 1}]`, a JSON
+        // array) is read as a damaged header but is no proof the input is OBO
+        const proof = FRAME_KINDS.has(name) || (clean && /^[A-Za-z]/.test(name) && isTagName(name));
+        if (!proof) {
+            this.firstBadLine ?? (this.firstBadLine = line);
+        }
+        this.startFrame(name, line, proof);
+        return true;
+    }
     /**
      * Start a frame, finishing the one before.
      * @param name - the frame type
      * @param line - the header's line
+     * @param proof - whether the header shows the input is OBO
      */
-    startFrame(name, line) {
+    startFrame(name, line, proof) {
         this.finishFrame();
+        this.frameSeen || (this.frameSeen = proof);
         const kind = FRAME_KINDS.has(name) ? name : null;
         if (kind === null) {
             this.tally("validation-error", OBO_ISSUE.UNKNOWN_ELEMENT, "frames of an unknown type are not nodes; kept in meta.extra.obo.unknownFrames", `[${name}]`, line);
@@ -289,9 +454,11 @@ class OboReader {
      * @param clause - the clause
      */
     headerClause(clause) {
-        var _a, _b;
-        ((_a = this.header)[_b = clause.tag] ?? (_a[_b] = [])).push(clause.value);
+        append(this.header, clause.tag, clause.value);
         const { tag } = clause;
+        if (SINGLE_HEADER_TAGS.has(tag) && this.header[tag].length > 1) {
+            this.tally("validation-error", OBO_ISSUE.DUPLICATE_ATTRIBUTE, "a single-valued header tag given twice; the first is kept", tag, clause.line);
+        }
         const tokens = tokenize(splitQualifiers(clause.value).value);
         const first = tokens.length > 0 && tokens[0].kind === "word" ? tokens[0].text : null;
         if (tag === "format-version") {
@@ -300,6 +467,9 @@ class OboReader {
         else if (tag === "default-namespace") {
             this.defaultNamespace ?? (this.defaultNamespace = first);
         }
+        else if ((tag === "subsetdef" || tag === "synonymtypedef") && first === null) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "a declaration whose name is not a word declares nothing", tag, clause.line);
+        }
         else if (tag === "subsetdef" && first !== null) {
             this.subsets.add(first);
         }
@@ -317,7 +487,6 @@ class OboReader {
     }
     /** Finish the frame being read: find its id and merge its clauses into the record of that id. */
     finishFrame() {
-        var _a, _b;
         const { frame } = this;
         this.frame = null;
         if (frame === null) {
@@ -325,9 +494,9 @@ class OboReader {
         }
         if (frame.kind === null) {
             // the guides: an unrecognized frame must survive, so its clauses are kept, raw
-            const clauses = {};
+            const clauses = ownRecord();
             for (const clause of frame.clauses) {
-                (clauses[_a = clause.tag] ?? (clauses[_a] = [])).push(clause.value);
+                append(clauses, clause.tag, clause.value);
             }
             this.unknownFrames.push({ type: frame.name, clauses });
             return;
@@ -337,18 +506,34 @@ class OboReader {
             throwIfAborted(this.signal);
         }
         const idAt = frame.clauses.findIndex((c) => c.tag === "id");
-        const id = idAt < 0 ? "" : unescapeObo(splitQualifiers(frame.clauses[idAt].value).value).trim();
+        const idParts = idAt < 0 ? null : splitQualifiers(frame.clauses[idAt].value);
+        const rawId = idParts === null ? "" : idParts.value.trim();
+        const id = unescapeObo(rawId).trim();
+        // a Typedef is metadata unless typedefs "nodes": it would never have been a node
+        const wouldBeNode = frame.kind !== "Typedef" || this.typedefsAsNodes;
         if (id.length === 0) {
             this.report.error("missing-value", OBO_ISSUE.MISSING_ID, `a [${frame.kind}] frame has no id; it is skipped`, {
                 line: frame.line,
             });
-            this.report.counts.skippedNodes++;
+            if (wouldBeNode) {
+                this.report.counts.skippedNodes++;
+            }
+            return;
+        }
+        if (tokenize(rawId).length > 1 || hasControl(id)) {
+            // a reference cannot name such an id (is_a needs one word), so the frame is refused
+            // rather than made a node no edge can reach
+            this.report.error("validation-error", OBO_ISSUE.BAD_VALUE, `a [${frame.kind}] frame's id ${JSON.stringify(id)} holds unescaped whitespace or a control character; the frame is skipped`, { line: frame.clauses[idAt].line, element: id });
+            if (wouldBeNode) {
+                this.report.counts.skippedNodes++;
+            }
             return;
         }
         if (idAt > 0) {
             this.tally("validation-error", OBO_ISSUE.ID_NOT_FIRST, "the id clause is not the frame's first; it is used", "id", frame.clauses[idAt].line);
         }
-        const record = this.recordFor(frame.kind, id, frame.line);
+        const target = this.recordFor(frame.kind, id, frame.line);
+        this.extraQualifiers(target, "id", id, idParts?.qualifiers ?? null);
         for (let i = 0; i < frame.clauses.length; i++) {
             const clause = frame.clauses[i];
             if (clause.tag === "id") {
@@ -357,10 +542,10 @@ class OboReader {
                 }
                 continue;
             }
-            this.applyClause(record, clause);
+            this.applyClause(target, clause);
         }
-        if (record.kind === "Typedef") {
-            (_b = record.raw).id ?? (_b.id = [id]);
+        if (target.kind === "Typedef" && !Object.hasOwn(target.raw, "id")) {
+            target.raw.id = [id];
         }
     }
     /**
@@ -378,14 +563,11 @@ class OboReader {
                 this.tally("validation-error", OBO_ISSUE.ID_KIND_CLASH, `an id names both a ${existing.kind} and an ${kind}; the ${existing.kind} is the node`, id, line);
             }
             else {
-                this.report.warning("merged", OBO_ISSUE.DUPLICATE_NODE, `two [${kind}] frames have the id ${id}; they are merged (spec 4.1.1)`, {
-                    line,
-                    element: id,
-                });
+                this.tally("merged", OBO_ISSUE.DUPLICATE_NODE, `[${kind}] frames with this id are merged (spec 4.1.1)`, id, line);
             }
             return existing;
         }
-        const record = {
+        const created = {
             id,
             kind,
             line,
@@ -393,10 +575,10 @@ class OboReader {
             lists: new Map(),
             edges: [],
             seen: new Set(),
-            raw: {},
+            raw: ownRecord(),
         };
-        map.set(id, record);
-        return record;
+        map.set(id, created);
+        return created;
     }
     /**
      * A clause's tag (a 1.0 tag read as its current one), the synonym scope that tag implies, its
@@ -412,7 +594,12 @@ class OboReader {
             this.tally("coercion", OBO_ISSUE.DEPRECATED_TAG, `the 1.0 tag is read as ${deprecated[0]}`, tag, clause.line);
             [tag, scope] = deprecated;
         }
-        const split = splitQualifiers(clause.value);
+        let split = splitQualifiers(clause.value);
+        const open = ID_VALUE_TAGS.has(tag) ? unclosedBlock(split.value) : -1;
+        if (open >= 0) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "a qualifier block without its closing brace was dropped", tag, clause.line);
+            split = splitQualifiers(split.value.slice(0, open).trimEnd());
+        }
         const { qualifiers } = split;
         if (split.badBlock !== null) {
             this.tally("parse-error", OBO_ISSUE.SYNTAX, "a closing brace that is not a qualifier block was kept as text", tag, clause.line);
@@ -454,24 +641,23 @@ class OboReader {
      * @param clause - the clause
      */
     applyClause(record, clause) {
-        var _a, _b;
         const key = `${clause.tag}\u0000${clause.value}`;
         if (record.seen.has(key)) {
             return;
         }
         record.seen.add(key);
         if (record.kind === "Typedef") {
-            ((_a = record.raw)[_b = clause.tag] ?? (_a[_b] = [])).push(clause.value);
+            append(record.raw, clause.tag, clause.value);
         }
         const { tag, scope, qualifiers, value } = this.clauseParts(clause);
+        // a control character kept in the value is the shared W_CONTROL_CHARACTER of the text check
         const where = { line: clause.line, element: record.id };
         if (TYPEDEF_TAGS.has(tag) && record.kind !== "Typedef") {
             this.unrecognized(record, clause);
             return;
         }
         if (TEXT_TAGS.has(tag)) {
-            this.single(record, tag, unescapeObo(value).trim(), clause.line);
-            this.extraQualifiers(record, tag, unescapeObo(value).trim(), qualifiers);
+            this.text(record, tag, value, qualifiers, clause.line);
             return;
         }
         if (BOOL_TAGS.has(tag)) {
@@ -553,7 +739,7 @@ class OboReader {
                     return;
                 }
                 this.push(record, "xref", xref.id);
-                this.describe(record, [xref]);
+                this.describe(record, [xref], tag, clause.line);
                 this.extraQualifiers(record, tag, xref.id, qualifiers ?? xref.qualifiers);
                 return;
             }
@@ -564,6 +750,23 @@ class OboReader {
                 this.unrecognized(record, clause);
         }
     }
+    /**
+     * A single-valued text clause (name, comment, ...), warning about a quote that never closes
+     * (stripComment() then keeps a `!` comment after it as text).
+     * @param record - the record
+     * @param tag - the tag
+     * @param value - the raw value
+     * @param qualifiers - its qualifier block
+     * @param line - its line
+     */
+    text(record, tag, value, qualifiers, line) {
+        if (tokenize(value).some((t) => t.kind === "quoted" && t.unterminated)) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "an unterminated quote; the text after it, a comment included, is kept", tag, line);
+        }
+        const text = unescapeObo(value).trim();
+        this.single(record, tag, text, line);
+        this.extraQualifiers(record, tag, text, qualifiers);
+    }
     /**
      * Read a value that must be one word.
      * @param tokens - the value's tokens
@@ -602,8 +805,14 @@ class OboReader {
             this.tally("parse-error", OBO_ISSUE.SYNTAX, "the xref list is missing", tag, line);
             return { text: tokens[0].text, xrefs: [] };
         }
+        if (list.unterminated) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "an xref list without its closing ]; kept as read", tag, line);
+        }
+        if (tokens.length > 2) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "text after the xref list was ignored", tag, line);
+        }
         const xrefs = parseXrefList(list.text);
-        this.describe(record, xrefs);
+        this.describe(record, xrefs, tag, line);
         this.xrefQualifiers(record, tag, xrefs);
         return { text: tokens[0].text, xrefs: xrefs.map((x) => x.id) };
     }
@@ -668,8 +877,16 @@ class OboReader {
         if (words.length > 2 || list === undefined) {
             this.tally("parse-error", OBO_ISSUE.SYNTAX, list === undefined ? "a synonym without its xref list" : "extra words after the synonym type", "synonym", line);
         }
+        const listAt = list === undefined ? -1 : tokens.indexOf(list);
+        const stray = tokens.some((t, k) => k > 0 && (t.kind === "quoted" || (t.kind === "list" && k !== listAt) || (listAt >= 0 && k > listAt)));
+        if (stray) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "a second quoted string, a second xref list or text after the list was ignored", "synonym", line);
+        }
+        if (list?.unterminated === true) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "an xref list without its closing ]; kept as read", "synonym", line);
+        }
         const xrefs = list === undefined ? [] : parseXrefList(list.text);
-        this.describe(record, xrefs);
+        this.describe(record, xrefs, "synonym", line);
         this.xrefQualifiers(record, "synonym", xrefs);
         this.push(record, "synonym", withQualifiers({ text: tokens[0].text, scope, type, xrefs: xrefs.map((x) => x.id) }, qualifiers));
     }
@@ -692,7 +909,14 @@ class OboReader {
             this.report.error("validation-error", OBO_ISSUE.BAD_VALUE, "property_value needs a relation and a value; the clause is skipped", where);
             return;
         }
-        const datatype = tokens.length === 3 ? tokens[2].text : null;
+        if (tokens.some((t) => t.unterminated)) {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "an unterminated quote; the text runs to the end of the line", "property_value", where.line);
+        }
+        let datatype = tokens.length === 3 ? tokens[2].text : null;
+        if (tokens.length === 3 && tokens[2].kind !== "word") {
+            this.tally("parse-error", OBO_ISSUE.SYNTAX, "a datatype that is not a word was ignored", "property_value", where.line);
+            datatype = null;
+        }
         this.push(record, "property_value", withQualifiers({ relation: tokens[0].text, value: tokens[1].text, datatype }, qualifiers));
     }
     /**
@@ -729,17 +953,27 @@ class OboReader {
         }
     }
     /**
-     * Record xref descriptions in `xref.descriptions`.
-     * @param record - the record
+     * Record xref descriptions in `xref.descriptions` (the first description of an id is kept),
+     * warning about a description whose quote never closes.
+     * @param target - the record
      * @param xrefs - the xrefs
+     * @param tag - the clause's tag
+     * @param line - the clause's line
      */
-    describe(record, xrefs) {
-        var _a;
+    describe(target, xrefs, tag, line) {
         for (const xref of xrefs) {
+            if (xref.unterminated) {
+                this.tally("parse-error", OBO_ISSUE.SYNTAX, "an xref description whose quote never closes runs to the end", tag, line);
+            }
             if (xref.description !== null) {
-                const map = (record.values.get("xref.descriptions") ?? {});
-                map[_a = xref.id] ?? (map[_a] = xref.description);
-                record.values.set("xref.descriptions", map);
+                let map = target.values.get("xref.descriptions");
+                if (map === undefined) {
+                    map = ownRecord();
+                    target.values.set("xref.descriptions", map);
+                }
+                if (!Object.hasOwn(map, xref.id)) {
+                    map[xref.id] = xref.description;
+                }
             }
         }
     }
@@ -766,7 +1000,7 @@ class OboReader {
         if (qualifiers === null) {
             return;
         }
-        const map = (record.values.get("obo.qualifiers") ?? {});
+        const map = record.values.get("obo.qualifiers") ?? {};
         (map[tag] ?? (map[tag] = [])).push({ value, qualifiers });
         record.values.set("obo.qualifiers", map);
     }
@@ -776,10 +1010,12 @@ class OboReader {
      * @param clause - the clause
      */
     unrecognized(record, clause) {
-        var _a;
-        const map = (record.values.get("obo.unrecognized") ?? {});
-        (map[_a = clause.tag] ?? (map[_a] = [])).push(unescapeObo(clause.value));
-        record.values.set("obo.unrecognized", map);
+        let map = record.values.get("obo.unrecognized");
+        if (map === undefined) {
+            map = ownRecord();
+            record.values.set("obo.unrecognized", map);
+        }
+        append(map, clause.tag, unescapeObo(clause.value));
         this.tally("validation-error", OBO_ISSUE.UNKNOWN_ELEMENT, "an unknown tag was kept in obo.unrecognized", clause.tag, clause.line);
     }
     /**
@@ -800,16 +1036,60 @@ class OboReader {
             found.count++;
         }
     }
-    /** Record the counted warnings, in the order they were first seen. */
+    /**
+     * Record the counted warnings, in the order they were first seen; past MAX_TALLIES_PER_CODE
+     * of one code, the rest are summed up in one warning.
+     */
     flushTallies() {
+        const listed = new Map();
+        const over = new Map();
         for (const t of this.tallies.values()) {
-            this.report.warning(t.category, t.code, `${t.element}: ${t.what} (${t.count} time(s), first at line ${t.line})`, {
+            const n = (listed.get(t.code) ?? 0) + 1;
+            listed.set(t.code, n);
+            if (n > MAX_TALLIES_PER_CODE) {
+                const rest = over.get(t.code) ?? [];
+                rest.push(t);
+                over.set(t.code, rest);
+                continue;
+            }
+            this.report.warning(t.category, t.code, `${t.element}: ${t.what} (${t.count} time${plural(t.count)}, first at line ${t.line})`, {
                 line: t.line,
                 element: t.element,
             });
         }
+        for (const [code, rest] of over) {
+            this.report.warning(rest[0].category, code, `${rest.length} more element${plural(rest.length)} with this warning, not listed (first: ${rest[0].element}: ${rest[0].what}, line ${rest[0].line})`, { line: rest[0].line });
+        }
         this.tallies.clear();
     }
+    /**
+     * The first line that makes the input not OBO: null unless no frame header and no plausible
+     * header tag was read while some line was neither (an HTML page, a JSON, GML, DOT or CSV file,
+     * UTF-16 read without its BOM). A file of only comments is OBO, if an empty one.
+     * @returns the line, or null
+     */
+    notObo() {
+        return this.frameSeen || this.tagClauses > 0 ? null : this.firstBadLine;
+    }
+    /**
+     * Warn about the header once the file is read: a missing or unknown format-version (the
+     * synonym-scope rule depends on it), a date that is not a real calendar date.
+     */
+    checkHeader() {
+        if (this.version === null) {
+            const empty = this.frameSeen ? "" : " and the file has no frames: nothing was read";
+            this.tally("validation-error", OBO_ISSUE.FORMAT_VERSION, `the header has no format-version (required by 1.2 and 1.4)${empty}; read as the 1.0 / 1.2 / 1.4 union`, "format-version", 1);
+        }
+        else if (!KNOWN_VERSION.test(this.version)) {
+            this.tally("validation-error", OBO_ISSUE.FORMAT_VERSION, `format-version ${JSON.stringify(this.version)} is not 1.0, 1.2 or 1.4; read as 1.4`, "format-version", 1);
+        }
+        const date = this.header.date?.[0];
+        if (date !== undefined &&
+            /^\d{2}:\d{2}:\d{4}\s+\d{2}:\d{2}$/.test(date.trim()) &&
+            oboDate(date.trim()) === null) {
+            this.tally("validation-error", OBO_ISSUE.SYNTAX, "the header date is not a real calendar date; created is null", "date", 1);
+        }
+    }
     /**
      * The header as GraphMeta fields (design 4.2): name from `ontology`, the version, `created` from
      * the `dd:MM:yyyy HH:mm` date, `creator` from `saved-by`.
@@ -863,7 +1143,9 @@ function oboDate(text) {
         return null;
     }
     const [, dd, mm, yyyy, hh, min] = m;
-    if (Number(mm) < 1 || Number(mm) > 12 || Number(dd) < 1 || Number(dd) > 31 || Number(hh) > 23 || Number(min) > 59) {
+    // a real calendar date: 31:02 and 31:04 do not survive the round trip through Date
+    const day = new Date(Date.UTC(Number(yyyy), Number(mm) - 1, Number(dd)));
+    if (Number(mm) < 1 || Number(mm) > 12 || day.getUTCDate() !== Number(dd) || Number(hh) > 23 || Number(min) > 59) {
         return null;
     }
     return `${yyyy}-${mm}-${dd}T${hh}:${min}`;
@@ -946,9 +1228,9 @@ function planGraph(reader, report, addMissingNodes, obo) {
         }
     }
     reader.flushTallies();
-    reportDangling(records, dangling, addMissingNodes, danglingEdges, report);
+    reportDangling(records, dangling, addMissingNodes, danglingEdges, report, new Set(reader.typedefs.keys()));
     if (dropped.size > 0) {
-        report.warning("merged", OBO_ISSUE.OBSOLETE_DROPPED, `${dropped.size} obsolete term(s) and ${droppedEdges} edge(s) to or from them were left out (obsolete: "drop")`, { element: [...dropped][0] });
+        report.warning("merged", OBO_ISSUE.OBSOLETE_DROPPED, `${dropped.size} obsolete term${plural(dropped.size)} and ${droppedEdges} edge${plural(droppedEdges)} to or from them were left out (obsolete: "drop")`, { element: [...dropped][0] });
     }
     return {
         nodes: records.filter((record) => kept.has(record.id)),
@@ -964,8 +1246,9 @@ function planGraph(reader, report, addMissingNodes, obo) {
  * @param addMissingNodes - whether they became placeholder nodes
  * @param droppedEdges - the edges dropped under addMissingNodes false
  * @param report - the report
+ * @param typedefs - the ids of the Typedef frames (kept as metadata, so not nodes)
  */
-function reportDangling(records, dangling, addMissingNodes, droppedEdges, report) {
+function reportDangling(records, dangling, addMissingNodes, droppedEdges, report, typedefs) {
     if (dangling.length === 0) {
         return;
     }
@@ -977,13 +1260,16 @@ function reportDangling(records, dangling, addMissingNodes, droppedEdges, report
     }
     const shown = dangling.slice(0, 5).map((id) => {
         const primary = altOf.get(id);
+        if (typedefs.has(id)) {
+            return `${id} (a Typedef, kept as metadata, not a node)`;
+        }
         return primary === undefined ? id : `${id} (an alt_id of ${primary})`;
     });
     const more = dangling.length > 5 ? `, ... (${dangling.length - 5} more)` : "";
     const action = addMissingNodes
         ? "each became a placeholder node (graphty.placeholder)"
-        : `${droppedEdges} edge(s) to them were dropped (addMissingNodes false)`;
-    report.warning("validation-error", OBO_ISSUE.DANGLING_REFERENCE, `${dangling.length} target(s) no frame declares: ${shown.join(", ")}${more}; ${action}`, { element: dangling[0] });
+        : `${droppedEdges} edge${plural(droppedEdges)} to them ${agree(droppedEdges, "was", "were")} dropped (addMissingNodes false)`;
+    report.warning("validation-error", OBO_ISSUE.DANGLING_REFERENCE, `${dangling.length} target${plural(dangling.length)} no frame declares: ${shown.join(", ")}${more}; ${action}`, { element: dangling[0] });
 }
 /** Pushes ids into a sink: the id coercion rule and the cancellation check. */
 class Pusher {
@@ -994,6 +1280,8 @@ class Pusher {
      * @param options - the resolved common options
      */
     constructor(sink, report, options) {
+        /** The original ids restored under restoreMangledIds, by the id the file wrote. */
+        this.restored = new Map();
         this.since = 0;
         this.sink = sink;
         this.report = report;
@@ -1006,7 +1294,7 @@ class Pusher {
      * @returns the node id
      */
     id(text) {
-        const id = this.coercer.text(text);
+        const id = this.coercer.text(this.restored.get(text) ?? text);
         const merge = this.coercer.lastMerge;
         if (merge !== null) {
             this.report.warning("coercion", OBO_ISSUE.ID_MERGED, `id text ${JSON.stringify(merge.text)} merged with ${JSON.stringify(merge.previousText)} as ${merge.id}`, { element: text });
@@ -1056,6 +1344,9 @@ class Pusher {
 function writeGraph(reader, sink, report, options, obo) {
     const plan = planGraph(reader, report, options.addMissingNodes, obo);
     const push = new Pusher(sink, report, options);
+    if (options.restoreMangledIds) {
+        restoreIds(plan.nodes, push.restored);
+    }
     const namespace = reader.namespaceDefault();
     // columns, declared only when used, in the vocabulary's order
     const used = new Set(["type"]);
@@ -1101,6 +1392,49 @@ function writeGraph(reader, sink, report, options, obo) {
     }
     writeEdges(plan, push, options);
 }
+/**
+ * Take back the ids the exporter rewrote under `sanitizeIds: "mangle"`: a frame's
+ * `property_value: graphty:originalId "..."` names its original id, which replaces the written one
+ * wherever the file names it (the property value itself is dropped). An original that another
+ * frame already uses as its id is not restored.
+ * @param records - the node records
+ * @param restored - receives written id to original id
+ */
+function restoreIds(records, restored) {
+    const taken = new Set(records.map((r) => r.id));
+    for (const record of records) {
+        const values = record.lists.get("property_value");
+        const at = values?.findIndex((v) => v.relation === ORIGINAL_ID) ?? -1;
+        if (values === undefined || at < 0) {
+            continue;
+        }
+        const original = originalText(values[at].value);
+        if (taken.has(original)) {
+            continue;
+        }
+        taken.add(original);
+        restored.set(record.id, original);
+        values.splice(at, 1);
+        if (values.length === 0) {
+            record.lists.delete("property_value");
+        }
+    }
+}
+/**
+ * The original id of a `graphty:originalId` property value: the exporter writes it as JSON text (so
+ * every character survives); a value that is not a JSON string is the id as it stands.
+ * @param value - the property value
+ * @returns the original id
+ */
+function originalText(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === "string" ? parsed : value;
+    }
+    catch {
+        return value;
+    }
+}
 /**
  * Push the planned edges through the direction resolver, with their relation and qualifiers.
  * @param plan - the plan
@@ -1141,6 +1475,54 @@ function writeEdges(plan, push, options) {
         }
     }
 }
+/**
+ * Feed the physical lines to the reader as logical lines: backslash continuations joined (the parts
+ * collected and joined once, so a value continued over many lines costs its length), form feeds
+ * outside quotes split. A backslash inside a `!` comment never continues a line, and a continuation
+ * never swallows a frame header or a blank line.
+ * @param lines - the line reader
+ * @param reader - the OBO reader
+ */
+async function readLines(lines, reader) {
+    const parts = [];
+    let partLine = 0;
+    const feed = (text, line) => {
+        for (const piece of splitFormFeeds(text)) {
+            reader.line(piece, line);
+        }
+    };
+    for await (const physical of lines) {
+        const { line } = lines;
+        if (parts.length > 0) {
+            const head = physical.trimStart();
+            if (head.length === 0 || head.startsWith("[")) {
+                reader.tally("parse-error", OBO_ISSUE.SYNTAX, "a line continuation before a frame header or a blank line was ignored", "\\", partLine);
+                feed(parts.join(""), partLine);
+                parts.length = 0;
+            }
+            else {
+                reader.tally("coercion", OBO_ISSUE.DEPRECATED_SYNTAX, "a backslash line continuation was joined (deprecated in 1.4)", "\\", partLine);
+            }
+        }
+        if (endsWithContinuation(physical) && stripComment(physical) === physical) {
+            parts.push(physical.slice(0, -1));
+            partLine = line;
+            continue;
+        }
+        if (parts.length > 0) {
+            parts.push(physical);
+            feed(parts.join(""), line);
+            parts.length = 0;
+        }
+        else {
+            feed(physical, line);
+        }
+    }
+    if (parts.length > 0) {
+        reader.tally("coercion", OBO_ISSUE.DEPRECATED_SYNTAX, "a backslash line continuation was joined (deprecated in 1.4)", "\\", partLine);
+        feed(parts.join(""), partLine);
+    }
+}
 /**
  * Confidence that a head is OBO (design 1.5): after a BOM, blank lines and `!` comment lines, 0.9
  * when the first significant line is `format-version:` or a `[Term]` / `[Typedef]` / `[Instance]`
@@ -1179,10 +1561,12 @@ function sniffObo(head) {
     return tagLines > 0 ? 0.4 : 0;
 }
 /**
- * The OBO importer plugin (design section 4).
+ * The OBO importer plugin.
+ * @category Built-in formats
  */
 export const oboImporter = Object.freeze({
     format: "obo",
+    options: Object.freeze(["obsolete", "typedefs"]),
     extensions: Object.freeze([".obo"]),
     mimeTypes: Object.freeze(["text/obo", "application/obo"]),
     /**
@@ -1206,33 +1590,20 @@ export const oboImporter = Object.freeze({
         const report = new ImportReportBuilder("obo", resolved.errorLimit);
         reportSinkOptions(sink, options, report, true);
         reportUnusedOptions(options, report, USED_OPTIONS);
-        const reader = new OboReader(report, resolved.signal);
-        const lines = new LineReader(input, report, resolved);
-        let pending = null;
-        for await (const physical of lines) {
-            const { line } = lines;
-            const text = pending === null ? physical : pending + physical;
-            pending = null;
-            if (endsWithContinuation(text)) {
-                reader.tally("coercion", OBO_ISSUE.DEPRECATED_SYNTAX, "a backslash line continuation was joined (deprecated in 1.4)", "\\", line);
-                pending = text.slice(0, -1);
-                continue;
-            }
-            // the 1.4 grammar counts form feed as a line end; LineReader does not
-            for (const piece of text.includes("\f") ? text.split("\f") : [text]) {
-                reader.line(piece, line);
-            }
-        }
-        if (pending !== null) {
-            reader.line(pending, lines.line);
-        }
+        const reader = new OboReader(report, resolved.signal, obo.typedefs === "nodes");
+        await readLines(new LineReader(input, report, resolved), reader);
         reader.finishFrame();
         if (!reader.significant) {
             report.fail(OBO_ISSUE.EMPTY_INPUT, "the input is empty");
         }
+        const notObo = reader.notObo();
+        if (notObo !== null) {
+            report.fail(OBO_ISSUE.NOT_OBO, `the input is not OBO: it has no frame header and no header tag, and line ${notObo} is not a tag-value line`, { line: notObo });
+        }
         throwIfAborted(resolved.signal);
+        reader.checkHeader();
         writeGraph(reader, sink, report, resolved, obo);
-        const typedefs = {};
+        const typedefs = ownRecord();
         for (const [id, record] of reader.typedefs) {
             typedefs[id] = record.raw;
         }