@graphty/graph-io 0.3.39 → 0.3.41

package/src/formats/cx/importer.ts

@@ -773,12 +773,13 @@ function checkNumberVerification(value: unknown, count: number, report: ImportRe
     const raw = isRecord(value) ? value.longNumber : undefined;
     const digits = raw instanceof ExactInteger ? raw.digits : String(raw);
     if (count > 1 || !NUMBER_VERIFICATION_VALUES.has(digits)) {
+        const held = raw === undefined ? null : digits;
         report.warning(
             "validation-error",
             CX_ISSUE.NUMBER_VERIFICATION,
             count > 1
                 ? "a second numberVerification element; ignored"
-                : `numberVerification holds ${shown(raw === undefined ? null : digits)}, not 281474976710655`,
+                : `numberVerification holds ${shown(held)}, not 281474976710655`,
             { line, element: "numberVerification" },
         );
     }
@@ -993,10 +994,12 @@ async function readDocument(
                         break;
                     }
                     countMember(event.block, null);
+                    const what =
+                        keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value);
                     report.error(
                         "parse-error",
                         BAD_ASPECT_BLOCK_CODE,
-                        `a member of the document is ${keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value)}, not a one-key aspect fragment; skipped`,
+                        `a member of the document is ${what}, not a one-key aspect fragment; skipped`,
                         { line: event.line, element: keys[0] ?? null },
                     );
                     break;
@@ -1361,6 +1364,26 @@ function memberCount(members: ReadonlySet<NodeId> | null, total: number): number
 
 // ============================================================ the build
 
+/** The cyVisualProperties of a graph's view, gathered before they are written. */
+interface VisualCollection {
+    /** per domain, per property: the [row, text] cells */
+    columns: Record<"node" | "edge", Map<string, [number, string][]>>;
+    /** the network values by property */
+    network: Map<string, string>;
+    defaults: number;
+    mappings: number;
+    dependencies: number;
+}
+
+/**
+ * A visual property value as text: a string as it is, anything else as JSON.
+ * @param raw - the value
+ * @returns its text
+ */
+function visualText(raw: unknown): string {
+    return typeof raw === "string" ? raw : JSON.stringify(raw);
+}
+
 /** One attribute column of the graph being built. */
 interface AttributeColumn {
     readonly name: string;
@@ -2849,57 +2872,99 @@ class CxReader {
      * applied.
      */
     private readVisualProperties(): void {
-        const entries = aspect(this.doc, "cyVisualProperties");
         // Cytoscape's table-cell styles: a visual property aspect graph-io keeps but does not read
         const tableStyles = TABLE_STYLE_ASPECTS.reduce((n, name) => n + (this.doc.kept.get(name)?.length ?? 0), 0);
         // the graph's own view (its first): the one its positions come from; the others stay in meta.extra.cx
         const views = new Set(this.plan.views.slice(0, 1));
-        const columns = { node: new Map<string, [number, string][]>(), edge: new Map<string, [number, string][]>() };
-        const network = new Map<string, string>();
-        let defaults = 0;
-        let mappings = 0;
-        let dependencies = 0;
-        for (const { value } of entries) {
-            if (!isRecord(value)) {
-                continue;
-            }
-            const view = value.view === undefined || value.view === null ? null : refId(value.view);
-            if (view !== null && views.size > 0 && !views.has(view)) {
-                continue;
+        const visual: VisualCollection = {
+            columns: { node: new Map(), edge: new Map() },
+            network: new Map(),
+            defaults: 0,
+            mappings: 0,
+            dependencies: 0,
+        };
+        for (const { value } of aspect(this.doc, "cyVisualProperties")) {
+            if (isRecord(value)) {
+                this.collectVisualEntry(value, views, visual);
             }
-            const properties = isRecord(value.properties) ? value.properties : {};
-            mappings += isRecord(value.mappings) ? Object.keys(value.mappings).length : 0;
-            dependencies += isRecord(value.dependencies) ? Object.keys(value.dependencies).length : 0;
-            switch (value.properties_of) {
-                case "nodes":
-                case "edges": {
-                    const domain = value.properties_of === "nodes" ? "node" : "edge";
-                    const target = refId(value.applies_to);
-                    const rows = domain === "node" ? this.nodeRows : this.edgeRows;
-                    const row = target === null ? undefined : rows.get(target);
-                    if (row === undefined) {
-                        if (target === null || !(domain === "node" ? this.rootNodes : this.rootEdges).has(target)) {
-                            this.dangle(`${domain} visual property entry`);
-                        }
-                        continue;
-                    }
-                    for (const [property, raw] of Object.entries(properties)) {
-                        const list = columns[domain].get(property) ?? [];
-                        list.push([row, typeof raw === "string" ? raw : JSON.stringify(raw)]);
-                        columns[domain].set(property, list);
-                    }
-                    break;
+        }
+        this.writeBypassColumns(visual.columns);
+        this.writeBypassNetwork(visual.network);
+        this.reportStyleRules(visual, tableStyles);
+    }
+
+    /**
+     * File one cyVisualProperties element of this graph's view into the collection: per-element and
+     * network values by property, defaults, mappings and dependencies counted.
+     * @param value - the element
+     * @param views - the views read (empty: every view)
+     * @param visual - the collection to add to
+     */
+    private collectVisualEntry(
+        value: Record<string, unknown>,
+        views: ReadonlySet<NodeId>,
+        visual: VisualCollection,
+    ): void {
+        const view = value.view === undefined || value.view === null ? null : refId(value.view);
+        if (view !== null && views.size > 0 && !views.has(view)) {
+            return;
+        }
+        const properties = isRecord(value.properties) ? value.properties : {};
+        visual.mappings += isRecord(value.mappings) ? Object.keys(value.mappings).length : 0;
+        visual.dependencies += isRecord(value.dependencies) ? Object.keys(value.dependencies).length : 0;
+        switch (value.properties_of) {
+            case "nodes":
+                this.collectElementProperties("node", value.applies_to, properties, visual.columns);
+                break;
+            case "edges":
+                this.collectElementProperties("edge", value.applies_to, properties, visual.columns);
+                break;
+            case "network":
+                for (const [property, raw] of Object.entries(properties)) {
+                    visual.network.set(property, visualText(raw));
                 }
-                case "network":
-                    for (const [property, raw] of Object.entries(properties)) {
-                        network.set(property, typeof raw === "string" ? raw : JSON.stringify(raw));
-                    }
-                    break;
-                default:
-                    defaults += Object.keys(properties).length;
-                    break;
+                break;
+            default:
+                visual.defaults += Object.keys(properties).length;
+                break;
+        }
+    }
+
+    /**
+     * File the visual values of one node or edge under its row; an element not in this graph is
+     * skipped, and reported dangling when it is in no graph of the file.
+     * @param domain - node or edge
+     * @param appliesTo - the element's applies_to
+     * @param properties - its visual properties
+     * @param columns - the per-property cells to add to
+     */
+    private collectElementProperties(
+        domain: "node" | "edge",
+        appliesTo: unknown,
+        properties: Record<string, unknown>,
+        columns: VisualCollection["columns"],
+    ): void {
+        const target = refId(appliesTo);
+        const rows = domain === "node" ? this.nodeRows : this.edgeRows;
+        const row = target === null ? undefined : rows.get(target);
+        if (row === undefined) {
+            if (target === null || !(domain === "node" ? this.rootNodes : this.rootEdges).has(target)) {
+                this.dangle(`${domain} visual property entry`);
             }
+            return;
         }
+        for (const [property, raw] of Object.entries(properties)) {
+            const list = columns[domain].get(property) ?? [];
+            list.push([row, visualText(raw)]);
+            columns[domain].set(property, list);
+        }
+    }
+
+    /**
+     * Write the collected per-element visual values as string columns in the cx.bypass namespace.
+     * @param columns - the per-property cells of each domain
+     */
+    private writeBypassColumns(columns: VisualCollection["columns"]): void {
         for (const domain of ["node", "edge"] as const) {
             for (const [property, cells] of columns[domain]) {
                 const handle = declareFresh(
@@ -2922,6 +2987,13 @@ class CxReader {
                 }
             }
         }
+    }
+
+    /**
+     * Write the network visual values as graph values in the cx.bypass namespace.
+     * @param network - the value of each property
+     */
+    private writeBypassNetwork(network: ReadonlyMap<string, string>): void {
         for (const [property, text] of network) {
             try {
                 this.sink.setGraphValue(property, text, {
@@ -2932,20 +3004,30 @@ class CxReader {
                 this.report.recordError(err, { element: property });
             }
         }
-        if (defaults + mappings + dependencies + tableStyles > 0) {
-            const parts = [
-                `cyVisualProperties: ${defaults} default${plural(defaults)}, ${mappings} mapping${plural(mappings)}, ${dependencies} dependenc(ies)`,
-            ];
-            if (tableStyles > 0) {
-                parts.push(`${tableStyles} table style element${plural(tableStyles)}`);
-            }
-            this.report.warning(
-                "unsupported",
-                STYLES_NOT_IMPORTED_CODE,
-                `the file's style rules are not applied (${parts.join("; ")}); they are kept in meta.extra.cx`,
-                { element: "cyVisualProperties" },
-            );
+    }
+
+    /**
+     * Warn that the style rules (defaults, mappings, dependencies, table styles) are kept, not applied.
+     * @param visual - the counted rules
+     * @param tableStyles - the number of table style elements
+     */
+    private reportStyleRules(visual: VisualCollection, tableStyles: number): void {
+        const { defaults, mappings, dependencies } = visual;
+        if (defaults + mappings + dependencies + tableStyles === 0) {
+            return;
         }
+        const parts = [
+            `cyVisualProperties: ${defaults} default${plural(defaults)}, ${mappings} mapping${plural(mappings)}, ${dependencies} dependenc(ies)`,
+        ];
+        if (tableStyles > 0) {
+            parts.push(`${tableStyles} table style element${plural(tableStyles)}`);
+        }
+        this.report.warning(
+            "unsupported",
+            STYLES_NOT_IMPORTED_CODE,
+            `the file's style rules are not applied (${parts.join("; ")}); they are kept in meta.extra.cx`,
+            { element: "cyVisualProperties" },
+        );
     }
 
     /**

package/src/formats/cx2/exporter.ts

@@ -304,9 +304,10 @@ function capabilityNotes(
             continue;
         }
         if (gen.code === LOSS.JSON) {
+            const what = gen.column === null ? "a column" : `column "${gen.column}"`;
             note(
                 CX2_LOSS.JSON_AS_STRING,
-                `${gen.column === null ? "a column" : `column "${gen.column}"`} holds nested values; written as a string attribute holding their JSON text`,
+                `${what} holds nested values; written as a string attribute holding their JSON text`,
                 gen.column,
                 gen.count,
             );

package/src/formats/cx2/importer.ts

@@ -688,6 +688,25 @@ async function readDocument(
     return doc;
 }
 
+/**
+ * Fail the import: the first member of the array is not a descriptor.
+ * @param value - the member
+ * @param line - its line
+ * @param report - the report
+ * @returns never: the import fails
+ */
+function failNoDescriptor(value: unknown, line: number, report: ImportReportBuilder): never {
+    const keys = isRecord(value) ? Object.keys(value) : [];
+    const keyList = keys.length > 0 ? ` (keys: ${keys.join(", ")})` : "";
+    return report.fail(
+        CX2_ISSUE.NO_DESCRIPTOR,
+        `the first member of the array is not a descriptor with CXVersion${keyList}`,
+        {
+            line,
+        },
+    );
+}
+
 /**
  * Check the descriptor, the first member of the array.
  * @param value - the member
@@ -697,12 +716,7 @@ async function readDocument(
  */
 function readDescriptor(value: unknown, line: number, doc: Cx2Document, report: ImportReportBuilder): void {
     if (!isRecord(value) || !("CXVersion" in value)) {
-        const keys = isRecord(value) ? Object.keys(value) : [];
-        report.fail(
-            CX2_ISSUE.NO_DESCRIPTOR,
-            `the first member of the array is not a descriptor with CXVersion${keys.length > 0 ? ` (keys: ${keys.join(", ")})` : ""}`,
-            { line },
-        );
+        failNoDescriptor(value, line, report);
     }
     const raw = value.CXVersion;
     const text = typeof raw === "string" || typeof raw === "number" ? String(raw) : "";
@@ -779,10 +793,11 @@ function memberAspect(
         collect(keys[0], value[keys[0]]);
         return;
     }
+    const what = keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value);
     report.error(
         "parse-error",
         BAD_ASPECT_BLOCK_CODE,
-        `a member of the document is ${keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value)}, not a one-key aspect block; skipped`,
+        `a member of the document is ${what}, not a one-key aspect block; skipped`,
         { line, element: keys[0] ?? null },
     );
 }
@@ -1325,10 +1340,11 @@ class Cx2Reader {
             }
             const other = table.byName.get(alias) ?? table.byAlias.get(alias);
             if (other !== undefined) {
+                const clash = other.name === alias ? "an attribute's name" : `the alias of "${other.name}"`;
                 this.report.error(
                     "validation-error",
                     CX2_ISSUE.ALIAS_CONFLICT,
-                    `the alias "${alias}" of the ${domain} attribute "${decl.name}" is also ${other.name === alias ? "an attribute's name" : `the alias of "${other.name}"`}; the alias is ignored`,
+                    `the alias "${alias}" of the ${domain} attribute "${decl.name}" is also ${clash}; the alias is ignored`,
                     { element: decl.name },
                 );
                 decl.alias = null;
@@ -2259,6 +2275,14 @@ class Cx2Reader {
                 }
             }
         }
+        this.checkStatus();
+        structure.checkCounts();
+    }
+
+    /** The status block: present, and exactly one well-formed element. */
+    private checkStatus(): void {
+        const { report } = this;
+        const { structure } = this.doc;
         if (!structure.hasStatus) {
             report.error("validation-error", CX2_ISSUE.NO_STATUS, "the document ends without a status block", {
                 element: "status",
@@ -2266,14 +2290,14 @@ class Cx2Reader {
         } else if (!structure.statusWellFormed() || structure.counts.get("status") !== 1) {
             // the specification: exactly one status aspect holding exactly one element
             const count = structure.counts.get("status") ?? 0;
+            const found = count === 1 ? shown(structure.status) : `${count} elements`;
             report.error(
                 "validation-error",
                 CX2_ISSUE.NO_STATUS,
-                `the status is malformed (${count === 1 ? shown(structure.status) : `${count} elements`}): a document ends with one status block holding one object with a boolean success`,
+                `the status is malformed (${found}): a document ends with one status block holding one object with a boolean success`,
                 { element: "status" },
             );
         }
-        structure.checkCounts();
     }
 
     /** Record the metadata: source format and version, name, description, id type, the kept aspects. */

package/src/formats/cys/tables.ts

@@ -217,24 +217,25 @@ export function cellAtt(
     namespace: string | null,
     hidden: boolean,
 ): AttRec | null {
+    const cell = { line, namespace, hidden };
     if (text.startsWith("=")) {
-        return att(column.name, column.list ? "List" : column.type, null, text, line, namespace, hidden, true);
+        return att(column.name, column.list ? "List" : column.type, null, text, true, cell);
     }
     if (!column.list) {
         if (text.length === 0 && column.type !== "String") {
             return null;
         }
-        return att(column.name, column.type, null, text, line, namespace, hidden, false);
+        return att(column.name, column.type, null, text, false, cell);
     }
     if (text.length === 0 && column.type !== "String") {
         return null;
     }
-    const list = att(column.name, "List", column.type, null, line, namespace, hidden, false);
+    const list = att(column.name, "List", column.type, null, false, cell);
     for (const item of javaSplitLines(text)) {
         if (item.length === 0 && column.type !== "String") {
             continue;
         }
-        list.children.push(att(column.name, column.type, null, item, line, namespace, hidden, false));
+        list.children.push(att(column.name, column.type, null, item, false, cell));
     }
     return list;
 }
@@ -262,10 +263,11 @@ function javaSplitLines(text: string): string[] {
  * @param cyType - the Cytoscape type
  * @param elementType - a list's item type, or null
  * @param value - the value, or null
- * @param line - the line
- * @param namespace - the table namespace, or null
- * @param hidden - a hidden column
  * @param equation - the value is a formula
+ * @param cell - where the cell sits
+ * @param cell.line - the line
+ * @param cell.namespace - the table namespace, or null
+ * @param cell.hidden - a hidden column
  * @returns the record
  */
 function att(
@@ -273,11 +275,10 @@ function att(
     cyType: string,
     elementType: string | null,
     value: string | null,
-    line: number,
-    namespace: string | null,
-    hidden: boolean,
     equation: boolean,
+    cell: { readonly line: number; readonly namespace: string | null; readonly hidden: boolean },
 ): AttRec {
+    const { line, namespace, hidden } = cell;
     return {
         name,
         type: null,

package/src/formats/gexf/exporter.ts

@@ -1225,7 +1225,8 @@ function lifetimeAttrs(roles: RoleColumns, row: number, plan: ExportPlan): strin
         const text = timeText(column, roles.companions.get(column.meta.name) ?? null, row, timeFormat);
         // GEXF 1.2: `startopen` / `endopen` hold the time of a non-inclusive bound (dynamics.xsd
         // time-type) and replace `start` / `end`
-        out += ` ${open ? `${name}open` : name}="${escapeXmlAttribute(text)}"`;
+        const attribute = open ? `${name}open` : name;
+        out += ` ${attribute}="${escapeXmlAttribute(text)}"`;
     };
     if (roles.timestamp?.isSet(row)) {
         if (version === "1.3" && plan.timeRepresentation === "timestamp") {
@@ -1240,11 +1241,33 @@ function lifetimeAttrs(roles: RoleColumns, row: number, plan: ExportPlan): strin
     }
     if (version === "1.3" && roles.timestamps?.isSet(row)) {
         const items = listItems(roles.timestamps, row).map((t) => formatTimeValue(t as number, timeFormat));
-        out += ` timestamps="${escapeXmlAttribute(`<[${items.join(", ")}]>`)}"`;
+        const stamps = `<[${items.join(", ")}]>`;
+        out += ` timestamps="${escapeXmlAttribute(stamps)}"`;
     }
     return out;
 }
 
+/**
+ * The `start` and `end` attributes of one `<spell>`.
+ * @param s - the start, or a non-finite value for an unbounded start
+ * @param e - the end, or a non-finite value for an unbounded end
+ * @param open - the open-bound bits
+ * @param plan - the plan
+ * @returns the attribute text, each with a leading space
+ */
+function spellBounds(s: number, e: number, open: number, plan: ExportPlan): string {
+    let attrs = "";
+    if (Number.isFinite(s)) {
+        const name = (open & OPEN_START) === 0 ? "start" : "startopen";
+        attrs += ` ${name}="${escapeXmlAttribute(formatTimeValue(s, plan.timeFormat))}"`;
+    }
+    if (Number.isFinite(e)) {
+        const name = (open & OPEN_END) === 0 ? "end" : "endopen";
+        attrs += ` ${name}="${escapeXmlAttribute(formatTimeValue(e, plan.timeFormat))}"`;
+    }
+    return attrs;
+}
+
 /**
  * The `<spells>` element of one element: its spells column, plus (1.2) its timestamps as [t, t].
  * In 1.2 a spell whose spells.open bits mark a bound open writes that bound as `startopen` /
@@ -1274,16 +1297,7 @@ function spellsElement(roles: RoleColumns, row: number, plan: ExportPlan, indent
     }
     let out = `${indent}<spells>\n`;
     for (const [s, e, open] of pairs) {
-        let attrs = "";
-        if (Number.isFinite(s)) {
-            const name = (open & OPEN_START) === 0 ? "start" : "startopen";
-            attrs += ` ${name}="${escapeXmlAttribute(formatTimeValue(s, plan.timeFormat))}"`;
-        }
-        if (Number.isFinite(e)) {
-            const name = (open & OPEN_END) === 0 ? "end" : "endopen";
-            attrs += ` ${name}="${escapeXmlAttribute(formatTimeValue(e, plan.timeFormat))}"`;
-        }
-        out += `${indent}  <spell${attrs}/>\n`;
+        out += `${indent}  <spell${spellBounds(s, e, open, plan)}/>\n`;
     }
     return `${out}${indent}</spells>\n`;
 }
@@ -1674,23 +1688,12 @@ function metaElement(meta: GraphSnapshot["meta"]): string {
 }
 
 /**
- * The `<graph>` start tag with its header attributes.
+ * The `idtype` attribute of the `<graph>` tag.
  * @param snapshot - the snapshot
- * @param plan - the plan
- * @returns the line
+ * @returns the attribute text with a leading space, or an empty string
  */
-function graphStart(snapshot: GraphSnapshot, plan: ExportPlan): string {
-    const { meta } = snapshot;
-    let attrs = ` defaultedgetype="${defaultEdgeType(snapshot)}"`;
-    let mode = meta.mode ?? "static";
-    if (plan.temporal && mode === "static") {
-        mode = "dynamic";
-    }
-    if (plan.version === "1.2" && mode === "slice") {
-        mode = "dynamic";
-    }
-    attrs += ` mode="${mode}"`;
-    let { idType } = meta;
+function graphIdTypeAttr(snapshot: GraphSnapshot): string {
+    let { idType } = snapshot.meta;
     if (idType === null) {
         const { kind } = snapshot.ids;
         if (kind === "string") {
@@ -1699,17 +1702,16 @@ function graphStart(snapshot: GraphSnapshot, plan: ExportPlan): string {
             idType = "integer";
         }
     }
-    if (idType === "integer" || idType === "string") {
-        attrs += ` idtype="${idType}"`;
-    }
-    if (plan.timeFormat !== null) {
-        attrs += ` timeformat="${plan.timeFormat}"`;
-    } else if (plan.temporal) {
-        attrs += ' timeformat="double"';
-    }
-    if (plan.version === "1.3" && plan.timeRepresentation !== null) {
-        attrs += ` timerepresentation="${plan.timeRepresentation}"`;
-    }
+    return idType === "integer" || idType === "string" ? ` idtype="${idType}"` : "";
+}
+
+/**
+ * The `start`, `end` and `timestamp` attributes of the `<graph>` tag.
+ * @param snapshot - the snapshot
+ * @param plan - the plan
+ * @returns the attribute text with leading spaces, or an empty string
+ */
+function graphHeaderAttrs(snapshot: GraphSnapshot, plan: ExportPlan): string {
     const timestamp = graphExtraText(snapshot, "timestamp");
     const header: Record<string, string | null> = {
         start: graphExtraText(snapshot, "start"),
@@ -1722,11 +1724,42 @@ function graphStart(snapshot: GraphSnapshot, plan: ExportPlan): string {
         header.end ??= timestamp;
         header.timestamp = null;
     }
+    let attrs = "";
     for (const [key, value] of Object.entries(header)) {
         if (value !== null) {
             attrs += ` ${key}="${escapeXmlAttribute(value)}"`;
         }
     }
+    return attrs;
+}
+
+/**
+ * The `<graph>` start tag with its header attributes.
+ * @param snapshot - the snapshot
+ * @param plan - the plan
+ * @returns the line
+ */
+function graphStart(snapshot: GraphSnapshot, plan: ExportPlan): string {
+    const { meta } = snapshot;
+    let attrs = ` defaultedgetype="${defaultEdgeType(snapshot)}"`;
+    let mode = meta.mode ?? "static";
+    if (plan.temporal && mode === "static") {
+        mode = "dynamic";
+    }
+    if (plan.version === "1.2" && mode === "slice") {
+        mode = "dynamic";
+    }
+    attrs += ` mode="${mode}"`;
+    attrs += graphIdTypeAttr(snapshot);
+    if (plan.timeFormat !== null) {
+        attrs += ` timeformat="${plan.timeFormat}"`;
+    } else if (plan.temporal) {
+        attrs += ' timeformat="double"';
+    }
+    if (plan.version === "1.3" && plan.timeRepresentation !== null) {
+        attrs += ` timerepresentation="${plan.timeRepresentation}"`;
+    }
+    attrs += graphHeaderAttrs(snapshot, plan);
     return `  <graph${attrs}>\n`;
 }