@graphty/graph-io 0.0.0 → 0.2.0

package/src/sniff.ts

@@ -0,0 +1,397 @@
+/**
+ * Format detection (design sections 8.2 and 13.1: the registry's `sniff()`, the successor of
+ * graphty-element's `format-detection.ts`): which of the registered importers a file is for, from
+ * any combination of a filename (its extension), a MIME type and the first bytes of the content.
+ *
+ * Every importer declares `extensions`, `mimeTypes` and a `sniff(head)` content confidence in
+ * 0..1 (design section 8.4); this module combines them into one ranked answer so that content
+ * always beats a hint: a `.csv` whose first line is a neo4j-admin header is Neo4j, a `.xml` is
+ * GEXF or GraphML by its root element, a `.txt` holding `graph [` is GML. The confidence of a
+ * candidate is
+ *
+ * - `0.5 + 0.35 * content + 0.1 * [extension matches] + 0.05 * [MIME type matches]` when the
+ *   importer recognises the content (`content > 0`), so a content match always scores at least
+ *   0.5 and at most 1;
+ * - `0.3 * [extension matches] + 0.1 * [MIME type matches]` when the content is absent or the
+ *   importer rejects it, so a hint alone never reaches 0.5;
+ * - nothing (the format is not a candidate) otherwise.
+ *
+ * Ties are broken by the order the importers were registered in, which is why the default
+ * registry lists the common formats first. The JSON dialect is sniffed from the head as a hint
+ * (the importer's detection on the parsed document is authoritative, design section 8.2).
+ */
+
+import { type JsonDialect, sniffJsonDialect } from "./formats/json/dialect.js";
+import { type GraphImporter } from "./types.js";
+
+/** The format names of the eight built-in importers and exporters. */
+export type GraphFormatName = "gexf" | "graphml" | "gml" | "dot" | "pajek" | "csv" | "json" | "neo4j";
+
+/**
+ * The built-in format names in the default registry's order, which is also the tie-break order of
+ * sniffing: the more common format wins an extension two formats claim (`.xml` GraphML before GEXF,
+ * `.csv` CSV before Neo4j) when the content does not decide.
+ */
+export const GRAPH_FORMATS: readonly GraphFormatName[] = Object.freeze([
+    "json",
+    "graphml",
+    "gexf",
+    "csv",
+    "gml",
+    "dot",
+    "pajek",
+    "neo4j",
+]);
+
+/** How many bytes of the input the sniffers look at; the registry reads no more than this before deciding. */
+export const SNIFF_HEAD_BYTES = 8192;
+
+/** What is known about an input before it is read. */
+export interface SniffHints {
+    /** A file name or path; only its extension is used. */
+    readonly filename?: string | null | undefined;
+    /** A MIME type, with or without parameters (`text/csv; charset=utf-8`). */
+    readonly mimeType?: string | null | undefined;
+    /** The first bytes (or characters) of the content. */
+    readonly head?: Uint8Array | string | null | undefined;
+}
+
+/** One ranked candidate of a sniff. */
+export interface SniffResult {
+    /** The importer's format name. */
+    readonly format: string;
+    /** The combined confidence in 0..1 (at least 0.5 when the content was recognised). */
+    readonly confidence: number;
+    /** The importer's own content confidence, 0 when no head was given or it rejected the head. */
+    readonly content: number;
+    /** Whether the filename's extension is one the importer claims. */
+    readonly extension: boolean;
+    /** Whether the MIME type is one the importer claims. */
+    readonly mimeType: boolean;
+    /** For the JSON format: the dialect the head suggests, or null when unknown; always null for other formats. */
+    readonly dialect: JsonDialect | null;
+}
+
+/**
+ * The lower-cased extension of a file name or path, with its dot.
+ * @param filename - the name or path
+ * @returns the extension (`.gexf`), or null when the name has none
+ */
+export function extensionOf(filename: string): string | null {
+    const base = filename.slice(Math.max(filename.lastIndexOf("/"), filename.lastIndexOf("\\")) + 1);
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1) {
+        return null;
+    }
+    return base.slice(dot).toLowerCase();
+}
+
+/**
+ * A MIME type without parameters, lower-cased, for comparison with an importer's list.
+ * @param mimeType - the type as received (`Text/CSV; charset=utf-8`)
+ * @returns the bare type (`text/csv`)
+ */
+export function normalizeMimeType(mimeType: string): string {
+    const semicolon = mimeType.indexOf(";");
+    return (semicolon < 0 ? mimeType : mimeType.slice(0, semicolon)).trim().toLowerCase();
+}
+
+/**
+ * The head as bytes for the importers' sniff functions: at most SNIFF_HEAD_BYTES, a string
+ * encoded as UTF-8.
+ * @param head - the head as given
+ * @returns the bytes
+ */
+export function headBytes(head: Uint8Array | string): Uint8Array {
+    if (typeof head === "string") {
+        return new TextEncoder().encode(head.slice(0, SNIFF_HEAD_BYTES)).subarray(0, SNIFF_HEAD_BYTES);
+    }
+    return head.byteLength > SNIFF_HEAD_BYTES ? head.subarray(0, SNIFF_HEAD_BYTES) : head;
+}
+
+/**
+ * Rank the registered importers for an input by the rule of the module comment: every importer
+ * whose content confidence is positive or whose extension / MIME type matches is a candidate,
+ * ordered by confidence (ties in registration order).
+ * @param hints - what is known about the input
+ * @param importers - the registered importers, in registration order
+ * @returns the candidates, best first; empty when nothing matches
+ */
+export function rankFormats(hints: SniffHints, importers: Iterable<GraphImporter>): readonly SniffResult[] {
+    const extension = typeof hints.filename === "string" ? extensionOf(hints.filename) : null;
+    const mime = typeof hints.mimeType === "string" ? normalizeMimeType(hints.mimeType) : null;
+    const head = hints.head === undefined || hints.head === null ? null : headBytes(hints.head);
+    const candidates: { readonly result: SniffResult; readonly rank: number }[] = [];
+    let rank = 0;
+    for (const importer of importers) {
+        const extensionMatch = extension !== null && importer.extensions.some((e) => e.toLowerCase() === extension);
+        const mimeMatch = mime !== null && importer.mimeTypes.some((m) => m.toLowerCase() === mime);
+        let content = 0;
+        if (head !== null && head.byteLength > 0 && typeof importer.sniff === "function") {
+            content = clamp(importer.sniff(head));
+        }
+        let confidence: number;
+        if (content > 0) {
+            confidence = 0.5 + 0.35 * content + (extensionMatch ? 0.1 : 0) + (mimeMatch ? 0.05 : 0);
+        } else if (extensionMatch || mimeMatch) {
+            confidence = (extensionMatch ? 0.3 : 0) + (mimeMatch ? 0.1 : 0);
+        } else {
+            continue;
+        }
+        const dialect = importer.format === "json" && head !== null ? sniffJsonDialectHead(head) : null;
+        const result: SniffResult = Object.freeze({
+            format: importer.format,
+            confidence: Math.min(1, confidence),
+            content,
+            extension: extensionMatch,
+            mimeType: mimeMatch,
+            dialect,
+        });
+        candidates.push({ result, rank: rank++ });
+    }
+    candidates.sort((a, b) => b.result.confidence - a.result.confidence || a.rank - b.rank);
+    return candidates.map((c) => c.result);
+}
+
+/**
+ * The best candidate of rankFormats(), or null when no importer matches.
+ * @param hints - what is known about the input
+ * @param importers - the registered importers, in registration order
+ * @returns the best candidate, or null
+ */
+export function sniffFormat(hints: SniffHints, importers: Iterable<GraphImporter>): SniffResult | null {
+    const ranked = rankFormats(hints, importers);
+    return ranked.length > 0 ? ranked[0] : null;
+}
+
+/**
+ * The JSON dialect a head suggests. A head that parses as a whole document is classified exactly
+ * (sniffJsonDialect); a truncated head is scanned for its top-level keys, the keys of `graph` and
+ * `options`, and the keys of the first object under `nodes` / `edges` / `links`, and the same
+ * rule is applied to that skeleton. The result is a hint: the importer decides on the parsed
+ * document.
+ * @param head - the first bytes or characters of the document
+ * @returns the dialect, or null when the head is not a JSON graph document
+ */
+export function sniffJsonDialectHead(head: Uint8Array | string): JsonDialect | null {
+    const text = typeof head === "string" ? head : new TextDecoder("utf-8", { fatal: false }).decode(head);
+    const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const trimmed = body.trimStart();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+        return null;
+    }
+    let root: unknown;
+    try {
+        root = JSON.parse(trimmed);
+    } catch {
+        root = skeletonOf(trimmed);
+    }
+    return sniffJsonDialect(root);
+}
+
+/** Where a key was seen while scanning a truncated head. */
+type KeyPath = "" | "graph" | "options" | "nodes[0]" | "edges[0]" | "links[0]";
+
+/**
+ * A partial document rebuilt from the keys a truncated head reveals: every key gets a placeholder
+ * value of the shape the dialect rule tests for (an object for `graph`, `options`, `attributes`
+ * and `data`, an array holding the first element's skeleton for `nodes` / `edges` / `links` /
+ * `graphs`, `true` otherwise), so sniffJsonDialect() can classify it.
+ * @param text - the head, starting with `{` or `[`
+ * @returns the skeleton, or null when the scan finds no key at all
+ */
+function skeletonOf(text: string): unknown {
+    const keys = scanKeys(text);
+    if (text.startsWith("[")) {
+        // a cut array whose first element has not been seen tells nothing (a whole `[]` is Cytoscape)
+        const first = keys.get("nodes[0]");
+        return first === undefined ? null : [objectOf(first)];
+    }
+    const rootKeys = keys.get("");
+    if (rootKeys === undefined) {
+        return null;
+    }
+    const root: Record<string, unknown> = {};
+    for (const key of rootKeys) {
+        switch (key) {
+            case "graph":
+            case "options":
+                root[key] = objectOf(keys.get(key));
+                break;
+            case "graphs":
+                root[key] = [];
+                break;
+            case "nodes":
+            case "edges":
+            case "links": {
+                const first = keys.get(`${key}[0]`);
+                root[key] = first === undefined ? [] : [objectOf(first)];
+                break;
+            }
+            default:
+                root[key] = true;
+                break;
+        }
+    }
+    return root;
+}
+
+/**
+ * An object holding placeholder values for a key set: `{}` for the keys the rule tests with
+ * isJsonObject (`attributes`, `data`), `true` otherwise.
+ * @param names - the keys, possibly undefined
+ * @returns the object
+ */
+function objectOf(names: ReadonlySet<string> | undefined): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    if (names !== undefined) {
+        for (const name of names) {
+            out[name] = name === "attributes" || name === "data" ? {} : true;
+        }
+    }
+    return out;
+}
+
+/**
+ * Scan a (possibly truncated) JSON text for the keys at the paths the dialect rule reads. The
+ * scanner tracks a container stack (the key each object sits under, the index of each array
+ * element) and records a key when it is at one of the watched paths; a head cut inside a string
+ * or a number simply ends the scan. For a top-level array the first element's keys are recorded
+ * under `nodes[0]`.
+ * @param text - the head, starting with `{` or `[`
+ * @returns key sets by path
+ */
+function scanKeys(text: string): Map<KeyPath, Set<string>> {
+    const found = new Map<KeyPath, Set<string>>();
+    // one frame per open container: its kind, the key or index it sits under, and the element index
+    const kinds: ("object" | "array")[] = [];
+    const labels: string[] = [];
+    const counts: number[] = [];
+    let pendingKey: string | null = null;
+    let expectingKey = false;
+    const pathOf = (): KeyPath | null => {
+        const depth = kinds.length;
+        if (depth === 1) {
+            return kinds[0] === "object" ? "" : null;
+        }
+        if (depth === 2 && kinds[0] === "array" && kinds[1] === "object" && labels[1] === "0") {
+            return "nodes[0]";
+        }
+        if (depth === 2 && kinds[0] === "object" && kinds[1] === "object") {
+            return labels[1] === "graph" || labels[1] === "options" ? labels[1] : null;
+        }
+        if (depth === 3 && kinds[0] === "object" && kinds[1] === "array" && kinds[2] === "object") {
+            const section = labels[1];
+            if ((section === "nodes" || section === "edges" || section === "links") && labels[2] === "0") {
+                return `${section}[0]`;
+            }
+        }
+        return null;
+    };
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+        const ch = text[i];
+        if (ch === '"') {
+            const end = scanString(text, i + 1);
+            if (end < 0) {
+                break;
+            }
+            const literal = text.slice(i + 1, end);
+            i = end + 1;
+            if (expectingKey) {
+                pendingKey = decodeKey(literal);
+                expectingKey = false;
+            }
+            continue;
+        }
+        if (ch === "{" || ch === "[") {
+            let label = "";
+            if (kinds.length > 0) {
+                label = kinds[kinds.length - 1] === "object" ? (pendingKey ?? "") : String(counts[counts.length - 1]);
+            }
+            kinds.push(ch === "{" ? "object" : "array");
+            labels.push(label);
+            counts.push(0);
+            expectingKey = ch === "{";
+            pendingKey = null;
+        } else if (ch === "}" || ch === "]") {
+            kinds.pop();
+            labels.pop();
+            counts.pop();
+            expectingKey = false;
+            pendingKey = null;
+        } else if (ch === ":") {
+            if (pendingKey !== null) {
+                const path = pathOf();
+                if (path !== null) {
+                    let set = found.get(path);
+                    if (set === undefined) {
+                        set = new Set();
+                        found.set(path, set);
+                    }
+                    set.add(pendingKey);
+                }
+            }
+        } else if (ch === ",") {
+            const top = kinds.length - 1;
+            if (top >= 0) {
+                counts[top]++;
+                expectingKey = kinds[top] === "object";
+            }
+            pendingKey = null;
+        }
+        i++;
+    }
+    return found;
+}
+
+/**
+ * The index of the closing quote of a JSON string starting after its opening quote.
+ * @param text - the text
+ * @param from - the index after the opening quote
+ * @returns the index of the closing quote, or -1 when the text ends first
+ */
+function scanString(text: string, from: number): number {
+    let i = from;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === '"') {
+            return i;
+        }
+        i++;
+    }
+    return -1;
+}
+
+/**
+ * A key literal decoded when it holds escapes, kept as written otherwise.
+ * @param literal - the text between the quotes
+ * @returns the key
+ */
+function decodeKey(literal: string): string {
+    if (!literal.includes("\\")) {
+        return literal;
+    }
+    try {
+        return JSON.parse(`"${literal}"`) as string;
+    } catch {
+        return literal;
+    }
+}
+
+/**
+ * Coerce a sniff confidence into 0..1 (NaN counts as 0).
+ * @param value - the importer's answer
+ * @returns the clamped value
+ */
+function clamp(value: number): number {
+    if (!(value > 0)) {
+        return 0;
+    }
+    return value > 1 ? 1 : value;
+}

package/src/types.ts

@@ -0,0 +1,262 @@
+/**
+ * The io contract types of @graphty/graph-io (design section 12.4, normative): what every importer
+ * and exporter implements and what every caller of one programs against. They are declared here
+ * rather than in the core because ImportInput and CommonImportOptions reference ReadableStream and
+ * AbortSignal, which need the DOM lib (or @types/node >= 18); the core's public types reference only
+ * ES2020 globals (decision D-IO-TYPES). Every declaration is transcribed verbatim from the design;
+ * the behaviour behind each option is specified in sections 8.4 (import), 8.5 (export) and 8.6
+ * (report and error aggregation).
+ */
+
+import {
+    type Dtype,
+    type DuplicatePolicy,
+    GraphFormatError,
+    type GraphSink,
+    type GraphSnapshot,
+    type IdCoercion,
+} from "@graphty/graph-format";
+
+/**
+ * What an importer reads (design section 8.4): whole text, whole bytes, a byte stream (a browser
+ * `File.stream()`, a fetch body) or an async iterable of text or byte chunks. Bytes are decoded as
+ * UTF-8 with `fatal: true`, so an invalid sequence is a parse-error and never a silent U+FFFD that
+ * could alias two ids.
+ */
+export type ImportInput = string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<string | Uint8Array>;
+
+/**
+ * The options every importer accepts next to its format-specific ones (design section 8.4). The
+ * builder-policy fields (`addMissingNodes`, `duplicateEdges`, `selfLoops`, `weightDtype`) seed the
+ * registry's builder; on a caller's sink they are read back from `sink.options` and every option the
+ * sink cannot honour is reported.
+ */
+export interface CommonImportOptions {
+    /**
+     * Id coercion rule applied before an id reaches the sink (design section 4.1): "canonical" by default for
+     * text-cell formats, "keep" for JSON.
+     */
+    ids?: IdCoercion | undefined;
+    /** Which field becomes the node id; "id" by default; "label" / "index" resolve the GML / Pajek / d3 ambiguity. */
+    nodeIdFrom?: "id" | "label" | "index" | undefined;
+    /** Whether an edge may reference an undeclared node (default true; the GEXF importer defaults false for edges). */
+    addMissingNodes?: boolean | undefined;
+    /** The builder's duplicate-edge policy seed; default "keep". */
+    duplicateEdges?: DuplicatePolicy | undefined;
+    /** The builder's self-loop policy seed; default "keep". */
+    selfLoops?: "keep" | "drop" | "error" | undefined;
+    /** What to do with a file whose edges disagree on direction (design section 3.6); default "expand". */
+    onMixedDirection?: "expand" | "directed" | "undirected" | "error" | undefined;
+    /** The direction assumed for a file that declares none (GEXF: undirected per spec). */
+    defaultDirected?: boolean | undefined;
+    /** The attribute that becomes THE weight (per-format default: "weight", GML "value"); null = unweighted. */
+    weightFrom?: string | null | undefined;
+    /** Weight staging precision; "f64" for every importer by default so 0.1 and 16777217 survive. */
+    weightDtype?: "f32" | "f64" | undefined;
+    /** How a declared `long` column is stored: "f64" (default) or "string" (design section 5.1). */
+    long?: "f64" | "string" | undefined;
+    /** Restore ids mangled by sanitizeIds "mangle" from the graphty:originalId attribute (default true). */
+    restoreMangledIds?: boolean | undefined;
+    /** GraphML / JGF hyperedges: refuse, skip with a report entry (default), or expand to a star / clique. */
+    hyperedges?: "error" | "skip" | "star" | "clique" | undefined;
+    /** Errors tolerated before the importer aborts with E_IMPORT (default 100). */
+    errorLimit?: number | undefined;
+    /** Cancellation; the importer stops between chunks and rejects with the signal's reason. */
+    signal?: AbortSignal | undefined;
+    /** Progress in bytes; `bytesTotal` is known for in-memory input only. */
+    onProgress?: ((bytesDone: number, bytesTotal?: number) => void) | undefined;
+}
+
+/**
+ * An importer plugin (design section 8.4): pushes scalars into the caller's sink in one pass and
+ * never freezes. `Opts` is its format-specific option set; the default `unknown` lets a caller pass
+ * the common options to an importer typed without one.
+ */
+export interface GraphImporter<Opts = unknown> {
+    /** The format name: "gexf", "graphml", "gml", "dot", "pajek", "csv", "json", "neo4j". */
+    readonly format: string;
+    /** File extensions with the leading dot. */
+    readonly extensions: readonly string[];
+    /** MIME types the format is served as. */
+    readonly mimeTypes: readonly string[];
+    /**
+     * Confidence that `head` is this format, for the registry's sniff().
+     * @param head - the first bytes of the input
+     * @returns a confidence in 0..1
+     */
+    sniff?(head: Uint8Array): number;
+    /**
+     * Read `input` into `sink`; per-element errors are aggregated into the report until the error
+     * limit, then the importer throws ImportError with the partial report.
+     * @param input - the text, bytes or stream to read
+     * @param sink - the builder (or a recording sink) to push into
+     * @param options - format-specific and common options
+     * @returns the import report
+     */
+    import(input: ImportInput, sink: GraphSink, options?: Opts & CommonImportOptions): Promise<ImportReport>;
+}
+
+/**
+ * What a format can express without loss (design section 8.5): the fidelity matrix of research
+ * note 07 section 9 as a table, and the acceptance test list for check().
+ */
+export interface ExportCapabilities {
+    /** Directed and undirected edges in one file. */
+    readonly mixedDirection: boolean;
+    /** Parallel edges. */
+    readonly multiEdges: boolean;
+    /** Self-loops. */
+    readonly selfLoops: boolean;
+    /** Whether edge ids are required (generated when absent), optional or unsupported. */
+    readonly edgeIds: "required" | "optional" | "none";
+    /** Which node ids can be written unchanged. */
+    readonly idCharset: "any" | "nmtoken" | "integer" | "dense-1-based";
+    /** The column dtypes the format keeps as declared. */
+    readonly dtypes: readonly Dtype[];
+    /** Multi-component (stride) columns. */
+    readonly components: boolean;
+    /** List columns. */
+    readonly lists: boolean;
+    /** Nested json columns. */
+    readonly json: boolean;
+    /** Declared defaults. */
+    readonly defaults: boolean;
+    /** Declared enumerations (GEXF options). */
+    readonly options: boolean;
+    /** Containment (parent / parents roles). */
+    readonly hierarchy: boolean;
+    /** Temporal support level. */
+    readonly temporal: "none" | "intervals" | "spells" | "dynamic-values";
+    /** Graph-level attributes. */
+    readonly graphAttributes: boolean;
+    /** The position role. */
+    readonly positions: boolean;
+    /** The visual roles (color, size, shape, thickness). */
+    readonly viz: boolean;
+}
+
+/** One thing an exporter cannot represent, reported by check() before anything is written (design section 8.5). */
+export interface LossNote {
+    /** A stable code such as "W_OPEN_INTERVAL". */
+    readonly code: string;
+    /** A plain-ASCII human-readable explanation. */
+    readonly message: string;
+    /** The affected column, or null when the note is not about a column. */
+    readonly column: string | null;
+    /** How many rows or elements are affected, or null when not counted. */
+    readonly count: number | null;
+}
+
+/** The options every exporter accepts next to its format-specific ones (design section 8.5). */
+export interface CommonExportOptions {
+    /** "error" (default): never rename a node; "mangle": rewrite ids the format cannot hold and keep the original. */
+    sanitizeIds?: "error" | "mangle" | undefined;
+    /** For formats without mixed-direction support: refuse (default) or write every edge one way. */
+    onMixedDirection?: "error" | "directed" | "undirected" | undefined;
+}
+
+/**
+ * An exporter plugin (design section 8.5): iterates nodes and logical edges (never arcs) in index
+ * order and reads the role columns of section 3.6 / 3.7 to fold expanded pairs and emit explicit
+ * weights only.
+ */
+export interface GraphExporter<Opts = unknown> {
+    /** The format name. */
+    readonly format: string;
+    /** What the format can express. */
+    readonly capabilities: ExportCapabilities;
+    /**
+     * Pre-flight: what export() would lose, without writing anything.
+     * @param snapshot - the snapshot to check
+     * @param options - format-specific and common options
+     * @returns the loss notes, empty when the export is exact
+     */
+    check(snapshot: GraphSnapshot, options?: Opts & CommonExportOptions): readonly LossNote[];
+    /**
+     * Write the snapshot as UTF-8 chunks.
+     * @param snapshot - the snapshot to write
+     * @param options - format-specific and common options
+     * @returns the encoded chunks
+     */
+    export(snapshot: GraphSnapshot, options?: Opts & CommonExportOptions): AsyncIterable<Uint8Array>;
+    /**
+     * Write the snapshot as one string.
+     * @param snapshot - the snapshot to write
+     * @param options - format-specific and common options
+     * @returns the whole document
+     */
+    exportToString(snapshot: GraphSnapshot, options?: Opts & CommonExportOptions): Promise<string>;
+}
+
+/** The categories of an ImportIssue (design section 8.6). */
+export type IssueCategory =
+    "parse-error" | "missing-value" | "validation-error" | "unsupported" | "precision" | "coercion" | "merged";
+
+/** One problem found while importing (design section 8.6). */
+export interface ImportIssue {
+    /** The category. */
+    readonly category: IssueCategory;
+    /** Errors count toward the error limit; warnings do not. */
+    readonly severity: "error" | "warning";
+    /** A stable code such as "E_UNKNOWN_NODE" or "W_WIDENED". */
+    readonly code: string;
+    /** A plain-ASCII human-readable message. */
+    readonly message: string;
+    /** The 1-based source line, or null when unknown. */
+    readonly line: number | null;
+    /** The element (a node or edge id, an attribute name), or null when unknown. */
+    readonly element: string | null;
+}
+
+/** What an import produced besides the sink's contents (design section 8.6). */
+export interface ImportReport {
+    /** The importer's format name. */
+    readonly format: string;
+    /** Element counts. */
+    readonly counts: {
+        /** Nodes pushed. */
+        readonly nodes: number;
+        /** Logical edges pushed (both halves of an expanded edge count). */
+        readonly edges: number;
+        /** Nodes skipped after an error. */
+        readonly skippedNodes: number;
+        /** Edges skipped after an error. */
+        readonly skippedEdges: number;
+        /** Edges expanded under onMixedDirection "expand" (design section 3.6). */
+        readonly expandedMixed: number;
+    };
+    /** Every issue recorded, in order. */
+    readonly issues: readonly ImportIssue[];
+    /** Issues with severity "error". */
+    readonly errorCount: number;
+    /** Issues with severity "warning". */
+    readonly warningCount: number;
+    /** Whether the error limit was reached and the import aborted. */
+    readonly truncated: boolean;
+    /** What the importer could not represent. */
+    readonly lossy: readonly LossNote[];
+    /** Wall time of the parse phase; the caller's freeze reports separately. */
+    readonly durationMs: number;
+}
+
+/**
+ * The error an importer throws when the error limit is reached or the input cannot be read at all
+ * (design section 8.6): a GraphFormatError with code "E_IMPORT" (reserved in the core's union so
+ * `err.code === "E_IMPORT"` narrows) carrying the partial report.
+ */
+export class ImportError extends GraphFormatError {
+    /** The report as it stood when the import aborted. */
+    readonly report: ImportReport;
+
+    /**
+     * Create an ImportError.
+     * @param message - a plain-ASCII human-readable message
+     * @param report - the partial report
+     * @param details - optional machine-readable context
+     */
+    constructor(message: string, report: ImportReport, details?: Readonly<Record<string, unknown>>) {
+        super("E_IMPORT", message, details);
+        this.name = "ImportError";
+        this.report = report;
+    }
+}