@graphty/graph-io 0.3.42 → 0.3.44

package/src/common/json-elements.ts

@@ -106,6 +106,28 @@ interface RewrittenNumbers {
     readonly reviveExact: (key: string, value: unknown) => unknown;
 }
 
+/**
+ * Every JSON string literal of a text, quotes included, in one left-to-right pass (a regex over
+ * untrusted text would scan again from every quote of an unterminated string). An unterminated
+ * literal at the end is left out.
+ * @param text - the document text
+ * @yields each literal
+ */
+function* stringLiterals(text: string): Generator<string> {
+    let i = text.indexOf('"');
+    while (i >= 0) {
+        let j = i + 1;
+        while (j < text.length && text[j] !== '"') {
+            j += text[j] === "\\" ? 2 : 1;
+        }
+        if (j >= text.length) {
+            return;
+        }
+        yield text.slice(i, j + 1);
+        i = text.indexOf('"', j + 1);
+    }
+}
+
 /**
  * The sentinel prefix of one rewrite: SENTINEL with a colon, or a numbered variant when the document
  * already holds that one. A string can only decode to a NUL by escaping it (`\u0000`), so when the
@@ -118,7 +140,7 @@ function sentinelFor(text: string): string {
     let haystack = text;
     if (/\\u0000/i.test(text)) {
         const decoded: string[] = [];
-        for (const [literal] of text.matchAll(/"(?:[^"\\]|\\.)*"/g)) {
+        for (const literal of stringLiterals(text)) {
             if (literal.includes("\\")) {
                 decoded.push(decodeString(literal));
             }
@@ -427,6 +449,126 @@ function closingQuote(text: string, from: number): number {
     return text.length;
 }
 
+/**
+ * The keys of one object of a valid JSON text in the order the text writes them (a repeated key at its first place),
+ * found by a path of keys and array indices from the root. `JSON.parse` gives an object's integer-like keys first, in
+ * numeric order, whatever order the text has; this gives the text's.
+ * @param text - a text JSON.parse accepted (non-standard number tokens included)
+ * @param path - the keys and array indices leading to the object (a repeated key leads to its last value, as
+ *     JSON.parse reads it)
+ * @returns the keys, or null when the path does not lead to an object
+ * @category Plugin helpers
+ */
+export function keysInTextOrder(text: string, path: readonly (string | number)[]): string[] | null {
+    let at = skipJsonSpace(text, 0);
+    for (const step of path) {
+        let next = -1;
+        if (typeof step === "number" && text.codePointAt(at) === 91) {
+            let index = 0;
+            forEachJsonEntry(text, at, false, (_key, value) => {
+                if (index++ === step) {
+                    next = value;
+                }
+            });
+        } else if (typeof step === "string" && text.codePointAt(at) === 123) {
+            forEachJsonEntry(text, at, true, (key, value) => {
+                if (key === step) {
+                    next = value;
+                }
+            });
+        }
+        if (next < 0) {
+            return null;
+        }
+        at = next;
+    }
+    if (text.codePointAt(at) !== 123) {
+        return null;
+    }
+    const keys = new Set<string>();
+    forEachJsonEntry(text, at, true, (key) => keys.add(key as string));
+    return [...keys];
+}
+
+/**
+ * Call back with each member of an object (its key and the offset of its value) or each element of an array.
+ * @param text - the text
+ * @param open - the offset of the opening brace or bracket
+ * @param object - whether it is an object
+ * @param visit - called per member or element
+ */
+function forEachJsonEntry(
+    text: string,
+    open: number,
+    object: boolean,
+    visit: (key: string | null, value: number) => void,
+): void {
+    let i = skipJsonSpace(text, open + 1);
+    const close = object ? 125 : 93;
+    while (i < text.length && text.codePointAt(i) !== close) {
+        let key: string | null = null;
+        if (object) {
+            const end = closingQuote(text, i + 1);
+            key = JSON.parse(text.slice(i, end + 1)) as string;
+            // past the colon
+            i = skipJsonSpace(text, skipJsonSpace(text, end + 1) + 1);
+        }
+        visit(key, i);
+        i = skipJsonSpace(text, skipJsonValue(text, i));
+        if (text.codePointAt(i) === 44) {
+            i = skipJsonSpace(text, i + 1);
+        }
+    }
+}
+
+/**
+ * The offset after the JSON value that starts at an offset.
+ * @param text - the text
+ * @param at - the value's first character
+ * @returns the offset after it
+ */
+function skipJsonValue(text: string, at: number): number {
+    const c = text.codePointAt(at);
+    if (c === 34) {
+        return closingQuote(text, at + 1) + 1;
+    }
+    if (c !== 123 && c !== 91) {
+        let i = at;
+        while (i < text.length && !endsScalar(text.codePointAt(i) ?? 32)) {
+            i++;
+        }
+        return i;
+    }
+    let depth = 0;
+    let i = at;
+    while (i < text.length) {
+        const d = text.codePointAt(i);
+        if (d === 34) {
+            i = closingQuote(text, i + 1);
+        } else if (d === 123 || d === 91) {
+            depth++;
+        } else if ((d === 125 || d === 93) && --depth === 0) {
+            return i + 1;
+        }
+        i++;
+    }
+    return text.length;
+}
+
+/**
+ * The offset of the first character at or after an offset that is not JSON whitespace.
+ * @param text - the text
+ * @param from - the offset
+ * @returns the offset
+ */
+function skipJsonSpace(text: string, from: number): number {
+    let i = from;
+    while (i < text.length && isSpace(text.codePointAt(i))) {
+        i++;
+    }
+    return i;
+}
+
 /**
  * Whether the string that ends before an offset is an object key: a colon follows after whitespace.
  * @param text - the text
@@ -634,7 +776,7 @@ function duplicateKey(text: string): string | null {
             const start = i;
             i = stringEnd(text, i + 1);
             const keys = stack.at(-1) ?? null;
-            if (keys !== null && text[skipSpace(text, i + 1)] === ":") {
+            if (keys !== null && text[skipJsonSpace(text, i + 1)] === ":") {
                 const key = JSON.parse(text.slice(start, i + 1)) as string;
                 if (keys.has(key)) {
                     return key;
@@ -661,20 +803,6 @@ function stringEnd(text: string, from: number): number {
     return i;
 }
 
-/**
- * The index of the first character at or after `from` that is not JSON whitespace.
- * @param text - the text
- * @param from - the first index
- * @returns the index (text.length at the end)
- */
-function skipSpace(text: string, from: number): number {
-    let i = from;
-    while (i < text.length && isSpace(text.codePointAt(i))) {
-        i++;
-    }
-    return i;
-}
-
 /** A key followed by its colon, for the cheap duplicate-key check. */
 const KEY_COLON = /"\s*:/g;
 
@@ -857,6 +985,11 @@ class ChunkCursor {
     /** The line number of buf's first character. */
     private linesBefore = 1;
 
+    /** The last position line() counted to in buf, and the line breaks before it: line() counts on from there. */
+    private countedTo = 0;
+
+    private countedLines = 0;
+
     private parts: string[] | null = null;
 
     private captureStart = 0;
@@ -882,6 +1015,8 @@ class ChunkCursor {
             this.captureStart = 0;
         }
         this.linesBefore += countNewlines(this.buf, 0, this.buf.length);
+        this.countedTo = 0;
+        this.countedLines = 0;
         const endsWithCr = this.buf.endsWith("\r");
         for (;;) {
             const next = await this.iterator.next();
@@ -907,7 +1042,15 @@ class ChunkCursor {
      * @returns the line
      */
     line(): number {
-        return this.linesBefore + countNewlines(this.buf, 0, Math.min(this.pos, this.buf.length));
+        // counted on from the last call, so reading every element of a one-chunk document stays linear
+        const to = Math.min(this.pos, this.buf.length);
+        if (to < this.countedTo) {
+            this.countedTo = 0;
+            this.countedLines = 0;
+        }
+        this.countedLines += countNewlines(this.buf, this.countedTo, to);
+        this.countedTo = to;
+        return this.linesBefore + this.countedLines;
     }
 
     /**
@@ -1062,18 +1205,13 @@ class ChunkCursor {
  * @returns the count
  */
 function countNewlines(text: string, from: number, to: number): number {
+    // one pass over the slice only: an indexOf() past `to` made each call cost the whole rest of the text
     let count = 0;
-    let i = text.indexOf("\n", from);
-    while (i >= 0 && i < to) {
-        count++;
-        i = text.indexOf("\n", i + 1);
-    }
-    i = text.indexOf("\r", from);
-    while (i >= 0 && i < to) {
-        if (text[i + 1] !== "\n") {
+    for (let i = from; i < to; i++) {
+        const c = text.codePointAt(i);
+        if (c === 10 || (c === 13 && text.codePointAt(i + 1) !== 10)) {
             count++;
         }
-        i = text.indexOf("\r", i + 1);
     }
     return count;
 }
@@ -1622,9 +1760,9 @@ export function inexactLiteral(text: string, key: string, keyDepth = 1): boolean
             const start = i;
             i = stringEnd(text, i + 1);
             // the key itself (a string at depth 1 followed by a colon), not a value spelled like it
-            const colon = skipSpace(text, i + 1);
+            const colon = skipJsonSpace(text, i + 1);
             if (depth === keyDepth && text.startsWith(quoted, start) && text[colon] === ":") {
-                return inexactNumberAt(text, skipSpace(text, colon + 1));
+                return inexactNumberAt(text, skipJsonSpace(text, colon + 1));
             }
         }
         i++;
@@ -1708,16 +1846,9 @@ export function headText(head: Uint8Array): string {
     return new TextDecoder(encoding).decode(head).replace(/^\uFEFF/, "");
 }
 
-/**
- * Cytoscape's screen y (growing downward) as graph-io's y (growing upward), and back: a negation
- * that never yields -0.
- * @param y - the coordinate
- * @returns the flipped coordinate
- * @category Plugin helpers
- */
-export function flipY(y: number): number {
-    return y === 0 ? 0 : -y;
-}
+// Cytoscape's screen y (growing downward) as graph-io's y (growing upward), and back: the one
+// shared flip lives with the other position conversions.
+export { flipY } from "../positions/convert.js";
 
 // ============================================================ stream structure shared by CX1 and CX2
 

package/src/common/notes.ts

@@ -0,0 +1,94 @@
+/**
+ * The note collector file positions use (and file styles, after their rebase): one note per code
+ * (and optional property), never one per element, with at most 8 distinct samples of 80
+ * characters, a total count and the element indexes the note covers.
+ */
+
+/** At most this many samples per note. */
+const MAX_SAMPLES = 8;
+/** A sample is cut to this many characters. */
+const MAX_SAMPLE_LENGTH = 80;
+
+/** One occurrence (or `count` occurrences) of a condition. */
+interface NoteReport {
+    /** An example of the offending value. */
+    readonly sample?: unknown;
+    /** The element the report is about, by index. */
+    readonly element?: number;
+    /** How many occurrences the report stands for; defaults to 1. */
+    readonly count?: number;
+}
+
+/** A collected note, before a module shapes it into its own note type. */
+interface CollectedNote<C extends string> {
+    readonly code: C;
+    readonly property: string | null;
+    readonly count: number;
+    readonly samples: readonly string[];
+    readonly elements: readonly number[] | { readonly count: number };
+}
+
+interface Collecting<C extends string> {
+    readonly code: C;
+    readonly property: string | null;
+    count: number;
+    readonly samples: string[];
+    readonly elements: Set<number>;
+    unindexed: boolean;
+}
+
+/** Collects notes, aggregated per (code, property), in the order their conditions first occur. */
+export class NoteCollector<C extends string> {
+    readonly #notes = new Map<string, Collecting<C>>();
+
+    /**
+     * Record a condition.
+     * @param code - the condition
+     * @param report - a sample, the element index and a count
+     * @param property - what the note is about, or null
+     */
+    add(code: C, report: NoteReport = {}, property: string | null = null): void {
+        const key = `${code}\u0000${property ?? ""}`;
+        let note = this.#notes.get(key);
+        if (note === undefined) {
+            note = { code, property, count: 0, samples: [], elements: new Set(), unindexed: false };
+            this.#notes.set(key, note);
+        }
+        note.count += report.count ?? 1;
+        if (report.element === undefined) {
+            note.unindexed = true;
+        } else {
+            note.elements.add(report.element);
+        }
+        if (report.sample !== undefined && note.samples.length < MAX_SAMPLES) {
+            const sample = sampleText(report.sample);
+            if (!note.samples.includes(sample)) {
+                note.samples.push(sample);
+            }
+        }
+    }
+
+    /**
+     * The collected notes.
+     * @returns one note per (code, property)
+     */
+    list(): CollectedNote<C>[] {
+        return Array.from(this.#notes.values(), (n) => ({
+            code: n.code,
+            property: n.property,
+            count: n.count,
+            samples: [...n.samples],
+            elements: n.unindexed ? { count: n.count } : Array.from(n.elements).sort((a, b) => a - b),
+        }));
+    }
+}
+
+/**
+ * A sample as at most 80 characters of text.
+ * @param value - the sample
+ * @returns the text
+ */
+function sampleText(value: unknown): string {
+    const text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+    return text.length > MAX_SAMPLE_LENGTH ? `${text.slice(0, MAX_SAMPLE_LENGTH - 3)}...` : text;
+}

package/src/common/report.ts

@@ -23,6 +23,23 @@ import { agree, plural } from "./plural.js";
  */
 export const MAX_WARNINGS_PER_CODE = 1000;
 
+/** What each finished report's import kept for its styles: per report object, so imports running at once never mix. */
+const KEPT_FOR_STYLES = new WeakMap<ImportReport, unknown>();
+
+/** The value of a builder that kept nothing. */
+const NOTHING_KEPT: unique symbol = Symbol("nothing kept");
+
+/**
+ * What the import that produced a report passed to `ImportReportBuilder.keepForStyles()`, or undefined when it kept
+ * nothing. graph-io passes it to the same importer's `styles()` as `context.kept`.
+ * @param report - a report an importer's `import()` returned
+ * @returns the kept value
+ * @category Writing a format
+ */
+export function keptForStyles(report: ImportReport): unknown {
+    return KEPT_FOR_STYLES.get(report);
+}
+
 /**
  * Where an issue was found: the 1-based line and the element (id or attribute name) when known.
  * @public
@@ -119,6 +136,8 @@ export class ImportReportBuilder {
 
     private truncatedFlag = false;
 
+    private kept: unknown = NOTHING_KEPT;
+
     private readonly startedAt: number;
 
     /**
@@ -277,6 +296,19 @@ export class ImportReportBuilder {
         throw err;
     }
 
+    /**
+     * Keep style data that is not per element (a stylesheet, a groups object, a legend, the file's default styles)
+     * for this import's `styles()`: graph-io passes it back as `context.kept` when styles are requested. Kept per
+     * report, never on the importer object, so imports running at once each get their own. A later call replaces
+     * the value.
+     * @param value - anything the importer's `styles()` needs
+     * @returns this builder
+     */
+    keepForStyles(value: unknown): this {
+        this.kept = value;
+        return this;
+    }
+
     /**
      * A builder that starts from everything this one recorded so far: issues, counts, loss notes,
      * the warnOnce keys, the error and warning counts and the truncation flag. For an importer that
@@ -297,6 +329,7 @@ export class ImportReportBuilder {
         copy.errors = this.errors;
         copy.warnings = this.warnings;
         copy.truncatedFlag = this.truncatedFlag;
+        copy.kept = this.kept;
         return copy;
     }
 
@@ -378,6 +411,9 @@ export class ImportReportBuilder {
         this.counts.expandedMixed += counts.expandedMixed;
         this.lossList.push(...report.lossy);
         this.truncatedFlag ||= report.truncated;
+        if (this.kept === NOTHING_KEPT && KEPT_FOR_STYLES.has(report)) {
+            this.kept = KEPT_FOR_STYLES.get(report);
+        }
         return this;
     }
 
@@ -403,7 +439,7 @@ export class ImportReportBuilder {
                 );
             }
         }
-        return Object.freeze({
+        const report: ImportReport = Object.freeze({
             format: this.format,
             counts: Object.freeze({ nodes, edges, skippedNodes, skippedEdges, expandedMixed }),
             issues: Object.freeze([...this.issueList, ...suppressed]),
@@ -413,6 +449,10 @@ export class ImportReportBuilder {
             lossy: Object.freeze([...this.lossList]),
             durationMs: now() - this.startedAt,
         });
+        if (this.kept !== NOTHING_KEPT) {
+            KEPT_FOR_STYLES.set(report, this.kept);
+        }
+        return report;
     }
 }
 

package/src/common/units.ts

@@ -0,0 +1,42 @@
+/**
+ * The length units and tool names that file positions (and, after their rebase, file styles)
+ * share. Loads in Node and imports nothing.
+ */
+
+/**
+ * The unit a file's lengths are in. "px": screen pixels or typographic points (1 pt counts as
+ * 1 px). "file": the file's own unit, with no known screen size (Pajek's unit square, NetworkX
+ * coordinates, Graphviz input inches).
+ * @category Positions
+ */
+export type LengthUnit = "px" | "file";
+
+/**
+ * The tool that wrote a file, when the file says. An open union: a tool graph-io does not know is
+ * kept as its lowercase name.
+ * @category Positions
+ */
+export type GraphTool = "yed" | "cytoscape" | "gephi" | "graphviz" | "pajek" | "networkx" | "tulip" | (string & {}); // NOSONAR(S4335): the open union keeps the known names in editor completion
+
+/** Creator texts that name a known tool, first match wins. */
+const TOOLS: readonly (readonly [RegExp, GraphTool])[] = [
+    [/yfiles|yed/i, "yed"],
+    [/cytoscape/i, "cytoscape"],
+    [/gephi/i, "gephi"],
+    [/graphviz/i, "graphviz"],
+    [/pajek/i, "pajek"],
+    [/networkx/i, "networkx"],
+    [/tulip/i, "tulip"],
+];
+
+/**
+ * The tool a file's creator text names ("yFiles", "Gephi 0.7", "NetworkX 3.1"), or null.
+ * @param creator - the creator text (`snapshot.meta.creator`)
+ * @returns the tool, or null when the text names none graph-io knows
+ */
+export function toolOf(creator: string | null | undefined): GraphTool | null {
+    if (creator === null || creator === undefined) {
+        return null;
+    }
+    return TOOLS.find(([pattern]) => pattern.test(creator))?.[1] ?? null;
+}

package/src/common/xml.ts

@@ -90,6 +90,29 @@ export class XmlSyntaxError extends Error {
     }
 }
 
+/**
+ * The most elements open at once that the XML tokenizer reads; a deeper document stops with an `XmlNestingError`.
+ * @category Plugin helpers
+ */
+export const MAX_XML_DEPTH = 100_000;
+
+/**
+ * Elements are nested deeper than `MAX_XML_DEPTH`: an importer reports it as E_XML_NESTING rather than as a syntax
+ * error.
+ * @category Plugin helpers
+ */
+export class XmlNestingError extends XmlSyntaxError {
+    /**
+     * Create the error.
+     * @param name - the element that opened one level too many
+     * @param line - the 1-based line
+     */
+    constructor(name: string, line: number) {
+        super(`<${name}> is nested more than ${String(MAX_XML_DEPTH)} elements deep`, line);
+        this.name = "XmlNestingError";
+    }
+}
+
 /**
  * The input holds no markup at all (empty, whitespace only, a byte order mark only): an importer
  * reports it as E_EMPTY_INPUT rather than as a syntax error.
@@ -350,17 +373,31 @@ export function isXmlName(text: string): boolean {
     if (text.length === 0) {
         return false;
     }
-    let first = true;
-    for (const ch of text) {
-        const cp = ch.codePointAt(0);
-        if (cp === undefined || (first ? !isNameStart(cp) : !isNameChar(cp))) {
+    // by index, with the ASCII tables for the common case as readName() does: a string iterator and the code point
+    // classes per character cost a second in a 5,000-node GraphML file, which checks every end tag
+    for (let i = 0; i < text.length;) {
+        const cp = text.codePointAt(i) ?? 0;
+        if (!isNameCodePoint(cp, i === 0)) {
             return false;
         }
-        first = false;
+        i += cp > 0xffff ? 2 : 1;
     }
     return true;
 }
 
+/**
+ * Whether a code point may stand in an XML Name, at its start or after it.
+ * @param cp - the code point
+ * @param first - whether it starts the name
+ * @returns true for a NameStartChar (first) or a NameChar
+ */
+function isNameCodePoint(cp: number, first: boolean): boolean {
+    if (cp < 0x80) {
+        return (first ? ASCII_NAME_START[cp] : ASCII_NAME_CHAR[cp]) === 1;
+    }
+    return first ? isNameStart(cp) : isNameChar(cp);
+}
+
 /**
  * Whether a code point is a legal XML 1.0 character.
  * @param cp - the code point
@@ -1517,6 +1554,9 @@ export class XmlTokenizer {
                 }
             }
         }
+        if (this.stack.length >= MAX_XML_DEPTH) {
+            throw new XmlNestingError(name, this.line);
+        }
         this.stack.push(name);
         this.handler.start(name, attrs, this.line, this.namespaceOf(name));
     }