@graphty/graph-io 0.3.43 → 0.3.44

package/src/formats/graphml/importer.ts

@@ -61,6 +61,7 @@ import {
     xmlDeclaredEncoding,
     XmlEmptyInputError,
     type XmlHandler,
+    XmlNestingError,
     XmlSyntaxError,
 } from "../../common/xml.js";
 import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
@@ -85,8 +86,37 @@ import {
     TARGET_PORT_COLUMN,
     XSI_NAMESPACE,
 } from "./constants.js";
-import { XmlTreeBuilder } from "./tree.js";
-import { graphicsDecl, graphicsValues } from "./yfiles.js";
+import { graphmlStyles } from "./styles-plain.js";
+import { writeXmlTree, XmlTreeBuilder } from "./tree.js";
+import { graphicsDecl, graphicsValues, yfilesPositions } from "./yfiles.js";
+
+/**
+ * Whether an XML attribute is not data and passes silently: a namespace declaration, an `xml:` or
+ * `xsi:` attribute, or a namespace URI where one is allowed.
+ * @param kind - the element name
+ * @param name - the attribute's name
+ * @returns true when it is never reported
+ */
+function isPassedAttribute(kind: string, name: string): boolean {
+    return name === "xmlns" || /^(xmlns|xml|xsi):/.test(name) || isAttributeUri(kind, name);
+}
+
+/**
+ * The warning for an attribute the importer does not read.
+ * @param kind - the element name
+ * @param name - the attribute's name
+ * @param hint - whether it is a `parse.*` hint
+ * @returns the message
+ */
+function unreadAttributeMessage(kind: string, name: string, hint: boolean): string {
+    if (hint) {
+        return `the <${kind}> parse hint ${name} is ignored`;
+    }
+    if (SCHEMA_ATTRIBUTES.has(name)) {
+        return `the <${kind}> attribute ${name} is not kept`;
+    }
+    return `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`;
+}
 
 /** The XML attributes the importer reads on each element; any other is reported (once per element and name). */
 const GRAPH_ATTRIBUTES: ReadonlySet<string> = new Set(["id", "edgedefault", "parse.nodes", "parse.edges"]);
@@ -106,6 +136,30 @@ const ENDPOINT_ATTRIBUTES: ReadonlySet<string> = new Set(["node", "type"]);
 const PORT_ATTRIBUTES: ReadonlySet<string> = new Set(["name"]);
 const NO_ATTRIBUTES: ReadonlySet<string> = new Set();
 
+/**
+ * Whether a `<key>` attribute is yFiles 3's `attr.uri` (in whatever prefix the file binds to yWorks' namespace).
+ * @param kind - the element name
+ * @param name - the attribute name as written
+ * @returns true for `<prefix>:attr.uri` on a key
+ */
+function isAttributeUri(kind: string, name: string): boolean {
+    return kind === "key" && name.endsWith(":attr.uri");
+}
+
+/**
+ * The `<prefix>:attr.uri` of a key, or null.
+ * @param attrs - the key's attributes
+ * @returns the URI
+ */
+function attributeUri(attrs: ReadonlyMap<string, string>): string | null {
+    for (const [name, value] of attrs) {
+        if (isAttributeUri("key", name) && value.length > 0) {
+            return value;
+        }
+    }
+    return null;
+}
+
 /** Attributes the GraphML schema defines that the importer does not keep: reported as not kept, not as foreign. */
 const SCHEMA_ATTRIBUTES: ReadonlySet<string> = new Set(["id", "port", "parse.order", "parse.nodeids", "parse.edgeids"]);
 
@@ -133,7 +187,10 @@ export interface GraphmlImportOptions extends CommonImportOptions {
      * `yfiles.borderWidth`, `yfiles.label` and `yfiles.shape` for nodes, and the line color, width
      * and arrows for edges. The report's `lossy` list then holds W_GRAPHML_YFILES_JSON, because the
      * XML comes back with the same structure but not byte for byte. "skip" leaves the graphics out,
-     * with a W_GRAPHML_YFILES_SKIPPED warning per key.
+     * with a W_GRAPHML_YFILES_SKIPPED warning per key. The `yfiles.*` columns are deprecated and
+     * kept as they are, not fixed: read a file's styles with `styles: true` instead. In the next
+     * major version they leave the import result, together with the rule that a target arrow makes
+     * an edge directed and the label role of `yfiles.label`.
      * @defaultValue "json"
      */
     yfiles?: "json" | "skip" | undefined;
@@ -1127,31 +1184,40 @@ class GraphmlReader implements XmlHandler {
         line: number,
     ): void {
         for (const name of attrs.keys()) {
-            if (known.has(name) || name === "xmlns" || /^(xmlns|xml|xsi):/.test(name)) {
-                continue;
-            }
-            const hint = name.startsWith("parse.");
-            const code = hint ? GRAPHML_ISSUE.PARSE_HINT_IGNORED : GRAPHML_ISSUE.UNKNOWN_XML_ATTRIBUTE;
-            let names = this.unknownNames.get(kind);
-            if (names === undefined) {
-                names = new Set();
-                this.unknownNames.set(kind, names);
-            }
-            if (names.has(name)) {
-                continue;
-            }
-            if (names.size >= MAX_UNKNOWN_ATTRIBUTE_NAMES && !hint) {
-                this.unknownOverflow.set(kind, (this.unknownOverflow.get(kind) ?? 0) + 1);
-            }
-            names.add(name);
-            if (names.size > MAX_UNKNOWN_ATTRIBUTE_NAMES && !hint) {
-                continue;
+            if (!known.has(name) && !isPassedAttribute(kind, name)) {
+                this.reportUnreadAttribute(kind, name, line);
             }
-            const message = unreadAttributeMessage(kind, name, hint);
-            this.report.warning("unsupported", code, message, { line, element: name });
         }
     }
 
+    /**
+     * Report one attribute reportUnreadAttributes() found, unless its name was reported for this
+     * element kind already or the kind is past MAX_UNKNOWN_ATTRIBUTE_NAMES names (then it is counted).
+     * @param kind - the element name
+     * @param name - the attribute's name
+     * @param line - the line
+     */
+    private reportUnreadAttribute(kind: string, name: string, line: number): void {
+        const hint = name.startsWith("parse.");
+        let names = this.unknownNames.get(kind);
+        if (names === undefined) {
+            names = new Set();
+            this.unknownNames.set(kind, names);
+        }
+        if (names.has(name)) {
+            return;
+        }
+        if (names.size >= MAX_UNKNOWN_ATTRIBUTE_NAMES && !hint) {
+            this.unknownOverflow.set(kind, (this.unknownOverflow.get(kind) ?? 0) + 1);
+        }
+        names.add(name);
+        if (names.size > MAX_UNKNOWN_ATTRIBUTE_NAMES && !hint) {
+            return;
+        }
+        const code = hint ? GRAPHML_ISSUE.PARSE_HINT_IGNORED : GRAPHML_ISSUE.UNKNOWN_XML_ATTRIBUTE;
+        this.report.warning("unsupported", code, unreadAttributeMessage(kind, name, hint), { line, element: name });
+    }
+
     /**
      * Open a `<graph>`: the top-level one sets the sink's direction (rule 1 of design section
      * 8.4); a nested one records its container as the parent of its nodes.
@@ -1314,6 +1380,10 @@ class GraphmlReader implements XmlHandler {
             case "all":
                 domains = ["graph", "node", "edge"];
                 break;
+            case "graphml":
+                // data on the <graphml> root (yEd's resources, yFiles 3's shared data) is read as graph data
+                domains = ["graph"];
+                break;
             case "graph":
             case "node":
             case "edge":
@@ -1339,12 +1409,14 @@ class GraphmlReader implements XmlHandler {
                 );
                 domains = [];
         }
+        // `name` / `type` without the `attr.` prefix are written by some tools; the spec's spelling wins
+        const attrType = attrs.get("attr.type") ?? attrs.get("type") ?? null;
         this.pendingKey = {
             id,
-            // `name` / `type` without the `attr.` prefix are written by some tools; the spec's spelling wins
             attrName: attrs.get("attr.name") ?? attrs.get("name") ?? null,
-            attrType: attrs.get("attr.type") ?? attrs.get("type") ?? null,
-            yfilesType: attrs.get("yfiles.type") ?? null,
+            attrType,
+            // yFiles 3 declares its untyped keys with `y:attr.uri` instead of `yfiles.type`: their data is nested XML
+            yfilesType: attrs.get("yfiles.type") ?? (attrType === null ? attributeUri(attrs) : null),
             domains,
             line,
             desc: "",
@@ -1878,6 +1950,19 @@ class GraphmlReader implements XmlHandler {
             }
             return value;
         }
+        if (typeof value !== "string" && target.spec.declared === "") {
+            // an untyped key states no type the elements contradict: keep them as their XML text
+            this.report.warnOnce(
+                "validation-error",
+                GRAPHML_ISSUE.DATA_STRUCTURED,
+                `<data> of the untyped attribute "${target.name}" holds elements; they are kept as XML text`,
+                { line: where.line, element: target.name },
+                `${GRAPHML_ISSUE.DATA_STRUCTURED}:${target.name}`,
+            );
+            const parts: string[] = [];
+            writeXmlTree(value, "", parts);
+            return parts.join("").trim();
+        }
         if (typeof value !== "string") {
             this.report.error(
                 "validation-error",
@@ -2668,7 +2753,11 @@ async function importGraphml(
             report.fail(GRAPHML_ISSUE.EMPTY_INPUT, "the input is empty (no markup at all)", { line: err.line });
         }
         if (err instanceof XmlSyntaxError) {
-            report.fail(GRAPHML_ISSUE.XML_SYNTAX, err.message, { line: err.line });
+            report.fail(
+                err instanceof XmlNestingError ? GRAPHML_ISSUE.XML_NESTING : GRAPHML_ISSUE.XML_SYNTAX,
+                err.message,
+                { line: err.line },
+            );
         }
         throw err;
     }
@@ -2687,6 +2776,8 @@ export const graphmlImporter: GraphImporter<GraphmlImportOptions> = Object.freez
     extensions: EXTENSIONS,
     mimeTypes: MIME_TYPES,
     sniff: sniffGraphml,
+    styles: graphmlStyles,
+    positions: yfilesPositions,
     import: importGraphml,
 });
 
@@ -2719,20 +2810,3 @@ function unknownElementMessage(name: string): string {
         ? `element <${name}> is not allowed at this place in a GraphML file and was skipped`
         : `element <${name}> is not GraphML and was skipped`;
 }
-
-/**
- * The warning text for an attribute the importer does not keep.
- * @param kind - the element name
- * @param name - the attribute name
- * @param hint - whether the attribute is a `parse.*` hint
- * @returns the message
- */
-function unreadAttributeMessage(kind: string, name: string, hint: boolean): string {
-    if (hint) {
-        return `the <${kind}> parse hint ${name} is ignored`;
-    }
-    if (SCHEMA_ATTRIBUTES.has(name)) {
-        return `the <${kind}> attribute ${name} is not kept`;
-    }
-    return `the <${kind}> attribute ${name} is not a GraphML attribute; it is not kept`;
-}

package/src/formats/graphml/index.ts

@@ -7,3 +7,4 @@
 export { GRAPHML_ISSUE, GRAPHML_LOSS } from "./constants.js";
 export { graphmlExporter, type GraphmlExportOptions } from "./exporter.js";
 export { graphmlImporter, type GraphmlImportOptions } from "./importer.js";
+export { GRAPHML_STYLE_CAPABILITIES } from "./styles-yed.js";

package/src/formats/graphml/styles-plain.ts

@@ -0,0 +1,236 @@
+/**
+ * GraphML styles: which program wrote the file, and its styles read the way that program draws them. yEd and
+ * yFiles 3 keep their graphics in nested XML (styles-yed.ts, styles-yfiles3.ts); Gephi writes plain `r`, `g`, `b`
+ * and `size` keys; Cytoscape's GraphML export writes no visual properties at all and is recognized by its `SUID`
+ * and `shared name` keys. A GraphML file from any other writer has no styles: a key named like a style (`color`)
+ * stays data, and no program's defaults are added.
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import { canonColor } from "../../styles/canon/color.js";
+import { canonNumber } from "../../styles/canon/number.js";
+import { canonText } from "../../styles/canon/text.js";
+import { blockStyles, parseStyleBlock, STYLE_BLOCK_NAME } from "../../styles/io/block.js";
+import { StyleNotes } from "../../styles/notes.js";
+import { styleFingerprint } from "../../styles/plan/features.js";
+import { plainCell, resolveStyles } from "../../styles/plan/resolve.js";
+import type { ImporterStyles, StyleReadContext, StyleTarget, StyleValue } from "../../styles/types.js";
+import { gephiRules } from "../gexf/styles.js";
+import {
+    exactFromBlock,
+    readYedStyles,
+    type ValueColumns,
+    valueColumns,
+    type YedRead,
+    yfilesColumns,
+} from "./styles-yed.js";
+import { readYfiles3Styles } from "./styles-yfiles3.js";
+
+/** Gephi's color and size keys. */
+const GEPHI_COLUMNS: readonly string[] = ["r", "g", "b", "size"];
+
+/**
+ * Whether a table has Gephi's `r`, `g` and `b` columns.
+ * @param table - the node or edge table
+ * @returns true when all three are there
+ */
+function hasRgb(table: GraphSnapshot["nodes"]): boolean {
+    return table.has("r") && table.has("g") && table.has("b");
+}
+
+/**
+ * Gephi's styles: `r`, `g`, `b` as the fill of a node and the color of an edge, `size` as a node's width and
+ * height, and `label` as the label.
+ * @param snapshot - the graph
+ * @param notes - where problems are noted
+ * @param context - the work budget
+ * @returns the values
+ */
+function readGephi(
+    snapshot: GraphSnapshot,
+    notes: StyleNotes,
+    context: StyleReadContext,
+): { node: ValueColumns; edge: ValueColumns } {
+    const read = (target: StyleTarget): ValueColumns => {
+        const table = target === "node" ? snapshot.nodes : snapshot.edges;
+        const n = target === "node" ? snapshot.nodeCount : snapshot.edgeCount;
+        const out = valueColumns(n);
+        const has = { rgb: hasRgb(table), size: target === "node" && table.has("size"), label: table.has("label") };
+        for (let i = 0; i < n; i++) {
+            context.budget.spend(target, 1);
+            const at = (property: string): Parameters<typeof canonNumber>[1] => ({
+                notes,
+                target,
+                property,
+                element: i,
+                budget: context.budget,
+            });
+            readGephiRow(
+                table,
+                target,
+                i,
+                has,
+                (property, value) => {
+                    out.put(i, property, value);
+                },
+                at,
+            );
+        }
+        return out.values;
+    };
+    return { node: read("node"), edge: read("edge") };
+}
+
+/**
+ * Reads one Gephi element.
+ * @param table - the node or edge table
+ * @param target - nodes or edges
+ * @param i - the element
+ * @param has - which of Gephi's columns the table has
+ * @param has.rgb - the `r`, `g` and `b` columns
+ * @param has.size - a node `size` column
+ * @param has.label - a `label` column
+ * @param put - receives the values
+ * @param at - the sites
+ */
+function readGephiRow(
+    table: GraphSnapshot["nodes"],
+    target: StyleTarget,
+    i: number,
+    has: { readonly rgb: boolean; readonly size: boolean; readonly label: boolean },
+    put: (property: string, value: StyleValue | null) => void,
+    at: (property: string) => Parameters<typeof canonNumber>[1],
+): void {
+    if (has.rgb) {
+        const [r, g, b] = ["r", "g", "b"].map((c) => plainCell(table.value(c, i)));
+        if (r !== null && g !== null && b !== null) {
+            const property = target === "node" ? "fill" : "color";
+            put(property, canonColor({ r, g, b }, "gephi", at(property))?.color ?? null);
+        }
+    }
+    if (has.size) {
+        const v = canonNumber(plainCell(table.value("size", i)), at("width"));
+        put("width", v);
+        put("height", v);
+    }
+    if (has.label) {
+        put("label", canonText(plainCell(table.value("label", i)), at("label")));
+    }
+}
+
+/**
+ * For a file graphty wrote: the yEd values that are only what the writer writes for the `graphty.styles` block's own
+ * values read as the block's values (see exactFromBlock()). A block that does not parse or describes another graph
+ * changes nothing; graph-io then ignores it with a note.
+ * @param snapshot - the graph
+ * @param yed - the values read from the yEd graphics, changed in place
+ */
+function exactFromGraphtyBlock(snapshot: GraphSnapshot, yed: YedRead): void {
+    const text = snapshot.graph.has(STYLE_BLOCK_NAME) ? plainCell(snapshot.graph.value(STYLE_BLOCK_NAME, 0)) : null;
+    if (typeof text !== "string") {
+        return;
+    }
+    const parsed = parseStyleBlock(text, styleFingerprint(snapshot));
+    const ex = parsed.ok ? blockStyles(parsed.block, snapshot, "graphml") : null;
+    if (ex === null) {
+        return;
+    }
+    exactFromBlock(
+        yed,
+        (target, property) => resolveStyles(ex, target, property as never, snapshot),
+        { node: snapshot.nodeCount, edge: snapshot.edgeCount },
+        new StyleNotes(),
+    );
+}
+
+/**
+ * The styles of a GraphML file, read the way the program that wrote it draws them, with that program's defaults
+ * beneath: yEd's and yFiles 3's nested graphics, Gephi's `r`, `g`, `b` and `size` keys, or, for Cytoscape's export,
+ * Cytoscape's default style with each node labeled by its `name`. A file from any other writer has none.
+ * @param snapshot - the graph the import built
+ * @param context - the work budget
+ * @returns the styles, or null when no writer with styles is recognized
+ */
+export function graphmlStyles(snapshot: GraphSnapshot, context: StyleReadContext): ImporterStyles | null {
+    const notes = new StyleNotes();
+    const readFrom = { node: yfilesColumns(snapshot.nodes), edge: yfilesColumns(snapshot.edges) };
+    const yfiles3 = readYfiles3Styles(snapshot, notes, context.budget);
+    if (yfiles3 !== null) {
+        return {
+            canonical: true,
+            dialect: "yfiles3",
+            tool: "yfiles3",
+            units: "px",
+            node: { values: yfiles3.node },
+            edge: { values: yfiles3.edge },
+            notes: notes.list(),
+            readFrom,
+        };
+    }
+    const yed = readYedStyles(snapshot, notes, context.budget);
+    if (yed !== null) {
+        exactFromGraphtyBlock(snapshot, yed);
+        return {
+            canonical: true,
+            dialect: "yed",
+            tool: "yed",
+            units: "px",
+            node: { values: yed.node },
+            edge: { values: yed.edge },
+            notes: notes.list(),
+            opacityInColor: true,
+            readFrom,
+        };
+    }
+    if (hasRgb(snapshot.nodes)) {
+        const gephi = readGephi(snapshot, notes, context);
+        const { rules, columns } = gephiRules(
+            snapshot,
+            gephi.node.fill,
+            gephi.edge.color,
+            context.budget,
+            gephi.edge.width,
+        );
+        const used = (table: GraphSnapshot["nodes"]): string[] => GEPHI_COLUMNS.filter((c) => table.has(c));
+        return {
+            canonical: true,
+            dialect: "gephi",
+            tool: "gephi",
+            units: "relative",
+            node: { values: gephi.node },
+            edge: { values: gephi.edge, rules, columns },
+            notes: notes.list(),
+            readFrom: { node: used(snapshot.nodes), edge: used(snapshot.edges) },
+        };
+    }
+    if (snapshot.nodes.has("SUID") && snapshot.nodes.has("shared name")) {
+        // Cytoscape writes no visual properties into GraphML; its default style labels each node with its name
+        const label = valueColumns(snapshot.nodeCount);
+        if (snapshot.nodes.has("name")) {
+            for (let i = 0; i < snapshot.nodeCount; i++) {
+                label.put(
+                    i,
+                    "label",
+                    canonText(plainCell(snapshot.nodes.value("name", i)), {
+                        notes,
+                        target: "node",
+                        property: "label",
+                        element: i,
+                        budget: context.budget,
+                    }),
+                );
+            }
+        }
+        return {
+            canonical: true,
+            dialect: "cytoscape",
+            tool: "cytoscape",
+            units: "px",
+            node: { values: label.values },
+            edge: { values: {} },
+            notes: notes.list(),
+        };
+    }
+    return null;
+}