@graphty/graph-io 0.3.24 → 0.3.26

package/src/formats/xgmml/emit.ts

@@ -12,6 +12,7 @@ import { DirectionResolver, type EdgeKind } from "../../common/direction.js";
 import { IdCoercer } from "../../common/ids.js";
 import { throwIfAborted } from "../../common/input.js";
 import { type ResolvedImportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { type ImportReportBuilder, type IssueLocation } from "../../common/report.js";
 import { parseWeightText } from "../../common/weights.js";
 import { ColumnSet } from "./columns.js";
@@ -43,8 +44,12 @@ import {
     type NodeRec,
     type XgmmlDocument,
 } from "./document.js";
+import { parseScalar } from "./values.js";
 
-/** The XGMML-specific options, resolved. */
+/**
+ * The XGMML-specific options, resolved.
+ * @category Plugin helpers
+ */
 export interface XgmmlSettings {
     /** Resolve missing or unknown endpoints through `"a (pp) b"` edge labels. */
     readonly labelAliases: boolean;
@@ -54,7 +59,10 @@ export interface XgmmlSettings {
     readonly zAs: "column" | "position";
 }
 
-/** What a session adds to the document's own rules. */
+/**
+ * What a session adds to the document's own rules.
+ * @category Plugin helpers
+ */
 export interface EmitExtras {
     /** Ids of nodes the session's group bookkeeping lists as groups. */
     readonly groupNodes?: ReadonlySet<string> | undefined;
@@ -75,9 +83,20 @@ export interface EmitExtras {
      * session): the session records it instead of E_UNKNOWN_PARENT.
      */
     readonly onMissingMember?: ((group: string, member: string) => void) | undefined;
+    /**
+     * A 3.x session: the label of a node or edge is its table's `name` (what Cytoscape shows), in
+     * a label column named `name`; the XGMML `label` attribute is read only when no element of
+     * the table has a `name`.
+     */
+    readonly labelFromName?: boolean | undefined;
+    /** Node ids to read in place of the written ones (ids an exporter mangled, by written id). */
+    readonly restoredIds?: ReadonlyMap<string, string> | undefined;
 }
 
-/** The dialect facts the rules depend on. */
+/**
+ * The dialect facts the rules depend on.
+ * @category Plugin helpers
+ */
 export interface Dialect {
     /** The documentVersion as written, or null. */
     readonly versionText: string | null;
@@ -121,6 +140,7 @@ const ALIAS_SPLIT = /[()]/;
  * @param doc - the document
  * @param report - the report the unparseable-version warning goes to
  * @returns the dialect
+ * @category Plugin helpers
  */
 export function dialectOf(doc: XgmmlDocument, report: ImportReportBuilder): Dialect {
     const { root } = doc;
@@ -133,7 +153,7 @@ export function dialectOf(doc: XgmmlDocument, report: ImportReportBuilder): Dial
     let version = 0;
     if (versionText !== null) {
         version = Number(versionText.trim());
-        if (!Number.isFinite(version) || versionText.trim().length === 0) {
+        if (!Number.isFinite(version) || version < 0 || versionText.trim().length === 0) {
             report.warning(
                 "validation-error",
                 XGMML_ISSUE.DOCUMENT_VERSION,
@@ -160,11 +180,24 @@ export function dialectOf(doc: XgmmlDocument, report: ImportReportBuilder): Dial
  * @param doc - the document
  * @param dialect - its dialect
  * @returns the graphs, in document order
+ * @category Plugin helpers
  */
 export function graphsOf(doc: XgmmlDocument, dialect: Dialect): GraphRec[] {
     return dialect.session ? doc.root.subgraphs.filter((g) => isCyTrue(g.registered)) : [doc.root];
 }
 
+/**
+ * A graphics coordinate as Java's `Double.parseDouble` reads Cytoscape's (no hex, no `_`), and
+ * finite.
+ * @param text - the text
+ * @returns the number, or null when it does not parse or is not finite
+ * @category Plugin helpers
+ */
+export function parseCoordinate(text: string): number | null {
+    const parsed = parseScalar(text, "real", false);
+    return parsed === null || !Number.isFinite(parsed.value) ? null : (parsed.value as number);
+}
+
 /**
  * The id a `#id` reference names, or null for a cross-file or malformed reference.
  * @param href - the xlink:href text
@@ -179,6 +212,7 @@ function localRef(href: string): string | null {
  * @param doc - the document
  * @param graph - the graph (a registered subnetwork), or null for the whole document
  * @returns the declared node and edge records it holds, references resolved, in order
+ * @category Plugin helpers
  */
 export function membersOf(
     doc: XgmmlDocument,
@@ -242,6 +276,7 @@ interface NodeRow {
 
 /**
  * Pushes one graph of a document into a sink.
+ * @category Plugin helpers
  */
 export class XgmmlEmitter {
     private readonly doc: XgmmlDocument;
@@ -311,10 +346,11 @@ export class XgmmlEmitter {
         this.coercer = new IdCoercer(options.ids);
         this.direction = new DirectionResolver(sink, report, options.onMixedDirection);
         const base = { unescape: settings.cytoscapeEscapes, long: options.long };
+        const label = extras.labelFromName === true ? [] : [LABEL_COLUMN];
         this.nodeColumns = new ColumnSet("node", report, {
             ...base,
             reserved: new Set([
-                LABEL_COLUMN,
+                ...label,
                 POSITION_COLUMN,
                 Z_COLUMN,
                 GRAPHICS_COLUMN,
@@ -328,7 +364,7 @@ export class XgmmlEmitter {
         });
         this.edgeColumns = new ColumnSet("edge", report, {
             ...base,
-            reserved: new Set([EDGE_ID_COLUMN, LABEL_COLUMN, GRAPHICS_COLUMN]),
+            reserved: new Set([EDGE_ID_COLUMN, ...label, GRAPHICS_COLUMN]),
         });
         this.graphColumns = new ColumnSet("graph", report, { ...base, reserved: new Set([GRAPHICS_COLUMN]) });
     }
@@ -343,7 +379,7 @@ export class XgmmlEmitter {
             this.report.warning(
                 "validation-error",
                 XGMML_ISSUE.DANGLING_REFERENCE,
-                `${this.prefix()}${members.dangling} xlink:href member reference(s) name no node or edge of the document`,
+                `${this.prefix()}${members.dangling} xlink:href member reference${plural(members.dangling)} ${agree(members.dangling, "names", "name")} no node or edge of the document`,
                 { line: graph?.line ?? null },
             );
         }
@@ -485,15 +521,33 @@ export class XgmmlEmitter {
     private edgeDirection(record: EdgeRec, header: boolean): boolean {
         let directed = this.directions.get(record);
         if (directed === undefined) {
+            const fallback = this.graphDirected(record.graph, header);
             directed =
                 record.directed === null
-                    ? header
-                    : this.flag(record.directed, header, { line: record.line, element: record.id ?? record.label });
+                    ? fallback
+                    : this.flag(record.directed, fallback, { line: record.line, element: record.id ?? record.label });
             this.directions.set(record, directed);
         }
         return directed;
     }
 
+    /**
+     * The default direction of the edges of a graph: the `directed` attribute of the graph or of
+     * the nearest graph it is nested in that has one, else the header.
+     * @param graph - the graph that holds the edge
+     * @param header - the header direction
+     * @returns whether the graph's edges are directed by default
+     */
+    private graphDirected(graph: GraphRec, header: boolean): boolean {
+        for (let g: GraphRec | null = graph; g !== null && g !== this.doc.root; g = g.parent) {
+            const text = g.attrs.get("directed");
+            if (text !== undefined) {
+                return this.flag(text, header, { line: g.line, element: "directed" });
+            }
+        }
+        return header;
+    }
+
     /**
      * The direction the sink starts with: the one every edge has when they all agree (a
      * Cytoscape file writes cy:directed on every edge and may omit the root attribute), else the
@@ -578,6 +632,39 @@ export class XgmmlEmitter {
         }
     }
 
+    /**
+     * The sink id of a node's written id: the restored original, else the written id, coerced.
+     * @param text - the written id
+     * @returns the id
+     */
+    private idOf(text: string): NodeId {
+        return this.coercer.text(this.extras.restoredIds?.get(text) ?? text);
+    }
+
+    /** Per table: the label is the `name` att (labelFromName and some element has one). */
+    private readonly nameLabel = { node: false, edge: false };
+
+    /**
+     * Decide whether a table's label comes from its `name` atts.
+     * @param domain - node or edge
+     * @param records - the table's records
+     */
+    private decideNameLabel(domain: "node" | "edge", records: readonly (NodeRec | EdgeRec)[]): void {
+        this.nameLabel[domain] = this.extras.labelFromName === true && records.some((r) => r.atts.some(isNameAtt));
+    }
+
+    /**
+     * The label of a record: its `name` att, or its XGMML label.
+     * @param record - the node or edge
+     * @returns the label, or undefined
+     */
+    private labelOf(record: NodeRec | EdgeRec): string | undefined {
+        if (this.nameLabel[record.kind]) {
+            return record.atts.find(isNameAtt)?.value ?? undefined;
+        }
+        return record.label ?? undefined;
+    }
+
     /**
      * The coerced id of a node text.
      * @param text - the id text
@@ -585,7 +672,7 @@ export class XgmmlEmitter {
      * @returns the id
      */
     private nodeId(text: string, line: number): NodeId {
-        const id = this.coercer.text(text);
+        const id = this.idOf(text);
         const merge = this.coercer.lastMerge;
         if (merge !== null) {
             this.report.warning(
@@ -645,7 +732,7 @@ export class XgmmlEmitter {
             this.report.warning(
                 "validation-error",
                 XGMML_ISSUE.DANGLING_REFERENCE,
-                `${this.prefix()}${dangling} xlink:href reference(s) name no node or edge of the document`,
+                `${this.prefix()}${dangling} xlink:href reference${plural(dangling)} ${agree(dangling, "names", "name")} no node or edge of the document`,
             );
         }
     }
@@ -660,11 +747,15 @@ export class XgmmlEmitter {
         const positions = new Positions(this, this.dialect.cytoscape ? this.settings.zAs : "position");
         const graphics = new JsonColumn(this, "node", GRAPHICS_COLUMN, XGMML_ORIGIN_NAMESPACE, "graphics");
         const pointers = new Pointers(this, this.groupTest());
+        this.decideNameLabel(
+            "node",
+            this.rowList.flatMap((r) => r.records),
+        );
         for (const row of this.rowList) {
             const where = { line: row.records[0].line, element: row.id };
             const seen = new Set<string>();
             for (const record of row.records) {
-                labels[row.row] ??= record.label ?? undefined;
+                labels[row.row] ??= this.labelOf(record);
                 this.addElementColumns(this.nodeColumns, row.row, record, seen, where);
                 positions.add(row, record);
                 if (record.graphics !== null && Object.keys(record.graphics).length > 0) {
@@ -713,7 +804,11 @@ export class XgmmlEmitter {
             names.add(key);
         }
         for (const att of record.atts) {
-            if (this.skipAtt(record, att) || (merging && att.name !== null && seen.has(att.name))) {
+            if (
+                this.skipAtt(record, att) ||
+                (this.nameLabel[record.kind] && isNameAtt(att)) ||
+                (merging && att.name !== null && seen.has(att.name))
+            ) {
                 continue;
             }
             if (record.kind === "node" && att.name === "__isGroup" && record.nested.length > 0 && isCyTrue(att.value)) {
@@ -740,7 +835,20 @@ export class XgmmlEmitter {
      * @returns true to skip it
      */
     private skipAtt(record: NodeRec | EdgeRec, att: AttRec): boolean {
-        return record.kind === "edge" && record.weight === null && att.name === this.options.weightFrom;
+        if (record.kind !== "edge" || att.name !== this.options.weightFrom) {
+            return false;
+        }
+        if (record.weight === null || att.name !== "weight" || att.children.length > 0) {
+            return record.weight === null;
+        }
+        // weight="2" and <att name="weight" value="3">: the attribute is THE weight
+        this.report.warning(
+            "validation-error",
+            XGMML_ISSUE.DUPLICATE_ATTRIBUTE,
+            `${this.prefix()}an edge has weight="${record.weight}" and a weight att "${att.value ?? ""}"; the weight attribute is the weight and the att is not read`,
+            { line: att.line, element: record.id ?? record.label ?? "weight" },
+        );
+        return true;
     }
 
     /**
@@ -758,7 +866,7 @@ export class XgmmlEmitter {
             return;
         }
         const handle = this.declare(domain, {
-            name: LABEL_COLUMN,
+            name: this.nameLabel[domain] ? "name" : LABEL_COLUMN,
             dtype: "string",
             role: "label",
             nullable: true,
@@ -825,21 +933,23 @@ export class XgmmlEmitter {
     private addEdges(records: readonly EdgeRec[], header: boolean): void {
         const ids = new Set<string>();
         const dedupe = this.dialect.cy2 && this.doc.nodes.some((n) => n.nested.length > 0) ? new Set<string>() : null;
+        let repeats = 0;
+        let firstRepeat: IssueLocation | null = null;
         const labels: (string | undefined)[] = [];
         const edgeIds: (string | undefined)[] = [];
         const graphics: [number, Record<string, unknown>][] = [];
         let row = 0;
+        this.decideNameLabel("edge", records);
         for (const record of records) {
             const where = { line: record.line, element: record.id ?? record.label };
-            const key = record.id ?? record.label;
+            // a repeat has the same id, or without one the same label and endpoints
+            const key =
+                record.id ??
+                (record.label === null ? null : JSON.stringify([record.label, record.source, record.target]));
             if (dedupe !== null && key !== null) {
                 if (dedupe.has(key)) {
-                    this.report.warnOnce(
-                        "merged",
-                        XGMML_ISSUE.GROUP_DUPLICATE_EDGE,
-                        `${this.prefix()}the Cytoscape 2.x writer repeats the edges of a group; each repeat is dropped`,
-                        where,
-                    );
+                    repeats++;
+                    firstRepeat ??= where;
                     continue;
                 }
                 dedupe.add(key);
@@ -850,7 +960,7 @@ export class XgmmlEmitter {
                 continue;
             }
             this.edgeIndex[row] = index;
-            labels[row] = record.label ?? undefined;
+            labels[row] = this.labelOf(record);
             edgeIds[row] = record.id ?? undefined;
             this.addElementColumns(this.edgeColumns, row, record, new Set(), where);
             this.fillInteraction(record, row, where);
@@ -859,6 +969,14 @@ export class XgmmlEmitter {
             }
             row++;
         }
+        if (repeats > 0) {
+            this.report.warning(
+                "merged",
+                XGMML_ISSUE.GROUP_DUPLICATE_EDGE,
+                `${this.prefix()}the Cytoscape 2.x writer repeats the edges of a group; ${repeats} repeat${plural(repeats)} ${agree(repeats, "was", "were")} dropped`,
+                firstRepeat ?? undefined,
+            );
+        }
         this.writeEdgeIds(edgeIds);
         this.writeLabels("edge", labels, (r) => this.edgeIndex[r] ?? -1);
         const column = new JsonColumn(this, "edge", GRAPHICS_COLUMN, XGMML_ORIGIN_NAMESPACE, "graphics");
@@ -938,7 +1056,7 @@ export class XgmmlEmitter {
         if (text === null) {
             return undefined;
         }
-        const weight = parseWeightText(text);
+        const weight = parseWeightText(text, this.report);
         this.weighted ||= weight !== undefined;
         return weight;
     }
@@ -957,21 +1075,24 @@ export class XgmmlEmitter {
         if (text !== null) {
             const row = this.rows.get(text);
             if (row !== undefined && row.index >= 0) {
-                return this.coercer.text(text);
+                return this.idOf(text);
             }
         }
         if (alias !== null) {
             const resolved = this.aliasRow(alias);
             if (resolved !== null) {
                 this.aliasResolved++;
-                return this.coercer.text(resolved.id);
+                return this.idOf(resolved.id);
             }
         }
         if (text === null) {
+            const ambiguous = alias !== null && this.aliasRow(alias) === null && this.labelRows?.get(alias) === null;
             this.report.error(
                 "missing-value",
                 XGMML_ISSUE.MISSING_ENDPOINT,
-                `${this.prefix()}<edge> without a ${side}`,
+                ambiguous
+                    ? `${this.prefix()}<edge> without a ${side}: its label alias "${alias}" is ambiguous (several nodes have that label); the edge is skipped`
+                    : `${this.prefix()}<edge> without a ${side}`,
                 where,
             );
             return null;
@@ -1047,7 +1168,7 @@ export class XgmmlEmitter {
         this.report.warning(
             "coercion",
             XGMML_ISSUE.LABEL_ALIAS,
-            `${this.prefix()}Cytoscape label aliases ("a (pp) b"): ${this.aliasResolved} endpoint(s) resolved, ${this.aliasInteractions} interaction(s) filled from edge labels`,
+            `${this.prefix()}Cytoscape label aliases ("a (pp) b"): ${this.aliasResolved} endpoint${plural(this.aliasResolved)} resolved, ${this.aliasInteractions} interaction${plural(this.aliasInteractions)} filled from edge labels`,
         );
     }
 
@@ -1152,10 +1273,26 @@ export class XgmmlEmitter {
     }
 }
 
+/**
+ * Whether an att is a session table's own `name` cell (a text value; a formula is kept as its text).
+ * @param att - the att
+ * @returns true for the name
+ */
+function isNameAtt(att: AttRec): boolean {
+    return (
+        att.name === "name" &&
+        (att.namespace ?? null) === null &&
+        att.value !== null &&
+        att.children.length === 0 &&
+        (att.cyType ?? "String") === "String"
+    );
+}
+
 /**
  * The three parts of a Cytoscape edge label (`source (interaction) target`).
  * @param label - the label, or null
  * @returns source alias, interaction, target alias; null when the label has another shape
+ * @category Plugin helpers
  */
 export function aliasesOf(label: string | null): [string, string, string] | null {
     if (label === null) {
@@ -1274,8 +1411,8 @@ class Positions {
         if (text === null) {
             return null;
         }
-        const n = Number(text.trim());
-        if (text.trim().length === 0 || !Number.isFinite(n)) {
+        const n = parseCoordinate(text);
+        if (n === null) {
             this.emitter.issues.error(
                 "validation-error",
                 XGMML_ISSUE.BAD_VALUE,
@@ -1388,7 +1525,7 @@ class Pointers {
             this.emitter.issues.warning(
                 "validation-error",
                 XGMML_ISSUE.DANGLING_REFERENCE,
-                `${prefix}${this.dangling} nested-network pointer(s) name no graph of the document`,
+                `${prefix}${this.dangling} nested-network pointer${plural(this.dangling)} ${agree(this.dangling, "names", "name")} no graph of the document`,
             );
         }
         const names = new JsonColumn(
@@ -1406,7 +1543,7 @@ class Pointers {
             this.emitter.issues.warning(
                 "unsupported",
                 XGMML_ISSUE.CROSS_FILE_REFERENCE,
-                `${prefix}${this.crossFile.size} nested-network pointer(s) point into another file; each is kept as text in ${NETWORK_POINTER_COLUMN}`,
+                `${prefix}${this.crossFile.size} nested-network pointer${plural(this.crossFile.size)} ${agree(this.crossFile.size, "points", "point")} into another file; each is kept as text in ${NETWORK_POINTER_COLUMN}`,
             );
             const column = new JsonColumn(
                 this.emitter,
@@ -1432,6 +1569,9 @@ class Containment {
 
     private readonly subgraphs = new Map<number, Record<string, unknown>>();
 
+    /** The nodes that are some node's parent: only those can be an ancestor, so close a cycle. */
+    private readonly groups = new Set<number>();
+
     /**
      * Create the resolver.
      * @param emitter - the emitter
@@ -1482,7 +1622,7 @@ class Containment {
             this.emitter.issues.error(
                 "missing-value",
                 XGMML_ISSUE.UNKNOWN_PARENT,
-                `${this.emitter.prefix()}${unknown} group member(s) name no node of this graph`,
+                `${this.emitter.prefix()}${unknown} group member${plural(unknown)} ${agree(unknown, "names", "name")} no node of this graph`,
             );
         }
     }
@@ -1494,7 +1634,7 @@ class Containment {
      * @param line - the line
      */
     private link(child: number, parent: number, line: number): void {
-        if (child === parent || this.isAncestor(child, parent)) {
+        if (child === parent || (this.groups.has(child) && this.isAncestor(child, parent))) {
             this.emitter.issues.error(
                 "validation-error",
                 XGMML_ISSUE.PARENT_CYCLE,
@@ -1508,6 +1648,7 @@ class Containment {
             list.push(parent);
         }
         this.parents.set(child, list);
+        this.groups.add(parent);
     }
 
     /**

package/src/formats/xgmml/exporter.ts

@@ -11,15 +11,16 @@
  * form. It writes the graph's structure and columns, never styles.
  */
 
-import { type Column, GraphFormatError, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
+import { type Column, GraphFormatError, type GraphSnapshot } from "@graphty/graph-format";
 
 import { type ChildrenCsr, childrenCsr } from "../../children.js";
 import { DictHeuristic } from "../../common/attributes.js";
 import { type PairFolding, pairFolding } from "../../common/direction.js";
 import { escapeXmlAttribute, escapeXmlText } from "../../common/escape.js";
 import { capabilities, checkCapabilities, LOSS } from "../../common/export.js";
-import { formatF32, formatF64 } from "../../common/format.js";
+import { formatF32, formatF64, idText } from "../../common/format.js";
 import { type ResolvedExportOptions, resolveExportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
 import { type ExplicitWeights, explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
 import { xmlIllegalTextNotes } from "../../common/xml.js";
@@ -48,11 +49,18 @@ import {
 } from "./constants.js";
 import { aliasesOf } from "./emit.js";
 
-/** The format-specific options of the XGMML exporter. */
-export interface XgmmlExportOptions {
+/** The two escapes Cytoscape reads back as a newline and a tab, as a message writes them. */
+const LITERAL_ESCAPES = String.raw`\n or \t`;
+
+/**
+ * The format-specific options of the XGMML exporter.
+ * @category Built-in formats
+ */
+export interface XgmmlExportOptions extends CommonExportOptions {
     /**
-     * Write newline and tab in string values as Cytoscape's two-character `\n` and `\t` (what the
-     * Cytoscape writer does) instead of the character references `
` and `	` (default).
+     * Write line breaks and tabs in text values as Cytoscape's two-character `\n` and `\t`, as
+     * Cytoscape does, instead of the XML character references `
` and `	`.
+     * @defaultValue false
      */
     cytoscapeEscapes?: boolean | undefined;
 }
@@ -481,7 +489,7 @@ function attNotes(column: Column, domain: string, note: NoteFn): void {
         if (escapes > 0) {
             note(
                 XGMML_LOSS.BACKSLASH_ESCAPE,
-                `${label}: ${escapes} value(s) hold a literal \\n or \\t, which Cytoscape's escape convention reads back as a newline or tab`,
+                `${label}: ${escapes} value${plural(escapes)} ${agree(escapes, "holds", "hold")} a literal ${LITERAL_ESCAPES}, which Cytoscape's escape convention reads back as a newline or tab`,
                 meta.name,
                 escapes,
             );
@@ -498,7 +506,7 @@ function attNotes(column: Column, domain: string, note: NoteFn): void {
         if (readsAs !== meta.dtype) {
             note(
                 XGMML_LOSS.STORAGE_CLASS_CHANGED,
-                `${label} reads back as ${readsAs} (the cardinality heuristic)`,
+                `${label} reads back as ${readsAs}: the importer stores text with few distinct values as dict and other text as string; the values are the same`,
                 meta.name,
                 null,
             );
@@ -540,7 +548,7 @@ function planExport(snapshot: GraphSnapshot, options: ResolvedExportOptions, esc
     if (folding.mutualCount > 0) {
         note(
             XGMML_LOSS.MUTUAL_EXPANDED,
-            `${folding.mutualCount} mutual pair(s) are written as two directed edges; the mutual mark is lost`,
+            `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two directed edges; the mutual mark is lost`,
             null,
             folding.mutualCount,
         );
@@ -549,7 +557,7 @@ function planExport(snapshot: GraphSnapshot, options: ResolvedExportOptions, esc
     if (numericIds > 0) {
         note(
             XGMML_LOSS.ID_TEXT_TYPE,
-            `${numericIds} numeric node id(s) are written as text and read back as strings`,
+            `${numericIds} numeric node id${plural(numericIds)} ${agree(numericIds, "is", "are")} written as text and read back as strings`,
             null,
             numericIds,
         );
@@ -567,7 +575,7 @@ function planExport(snapshot: GraphSnapshot, options: ResolvedExportOptions, esc
     if (hierarchy.unreachable > 0) {
         note(
             XGMML_LOSS.PARENT_CYCLE,
-            `${hierarchy.unreachable} node(s) whose parent chain never reaches a root are written at the top level and lose their parent`,
+            `${hierarchy.unreachable} node${plural(hierarchy.unreachable)} whose parent chain never reaches a root ${agree(hierarchy.unreachable, "is", "are")} written at the top level and lose their parent`,
             null,
             hierarchy.unreachable,
         );
@@ -596,7 +604,12 @@ function planExport(snapshot: GraphSnapshot, options: ResolvedExportOptions, esc
     const weights = explicitWeights(snapshot);
     for (const column of snapshot.edges) {
         if (column.meta.name === "weight" && column.meta.role === null && !weights.weighted) {
-            note(LOSS.WEIGHT_KEY_CLASH, `edge column "weight" reads back as THE weight`, "weight", null);
+            note(
+                LOSS.WEIGHT_KEY_CLASH,
+                `edge column "weight" reads back as the edge weight, not as a column`,
+                "weight",
+                null,
+            );
         }
     }
     return {
@@ -635,7 +648,7 @@ function interactionNote(snapshot: GraphSnapshot, note: NoteFn): void {
     if (shaped > 0) {
         note(
             XGMML_LOSS.INTERACTION_FROM_LABEL,
-            `${shaped} edge label(s) have Cytoscape's "a (i) b" shape and read back with an "${INTERACTION_COLUMN}" column`,
+            `${shaped} edge label${plural(shaped)} ${agree(shaped, "has", "have")} Cytoscape's "a (i) b" shape and read back with an "${INTERACTION_COLUMN}" column`,
             INTERACTION_COLUMN,
             shaped,
         );
@@ -691,7 +704,7 @@ function positionNotes(position: Column, snapshot: GraphSnapshot, note: NoteFn):
     if (meta.components !== 3) {
         note(
             XGMML_LOSS.POSITION,
-            `position column "${meta.name}" has ${meta.components} component(s) and reads back with 3`,
+            `position column "${meta.name}" has ${meta.components} component${plural(meta.components)} and reads back with 3`,
             meta.name,
             null,
         );
@@ -712,7 +725,7 @@ function positionNotes(position: Column, snapshot: GraphSnapshot, note: NoteFn):
     if (nonFinite > 0) {
         note(
             XGMML_LOSS.POSITION,
-            `${nonFinite} position(s) with a non-finite coordinate are not written`,
+            `${nonFinite} position${plural(nonFinite)} with a non-finite coordinate ${agree(nonFinite, "is", "are")} not written`,
             meta.name,
             nonFinite,
         );
@@ -722,8 +735,8 @@ function positionNotes(position: Column, snapshot: GraphSnapshot, note: NoteFn):
         note(
             XGMML_LOSS.POSITION,
             zColumn === null
-                ? `${depth} position(s) have a z; it is written as graphics z and reads back in the z column (zAs: "position" reads it as a coordinate)`
-                : `${depth} position(s) have a z, but graphics z holds the z column; the position z is lost`,
+                ? `${depth} position${plural(depth)} ${agree(depth, "has", "have")} a z; it is written as graphics z and reads back in the z column (zAs: "position" reads it as a coordinate)`
+                : `${depth} position${plural(depth)} ${agree(depth, "has", "have")} a z, but graphics z holds the z column; the position z is lost`,
             meta.name,
             depth,
         );
@@ -787,15 +800,6 @@ function scalarText(value: unknown): string {
     return JSON.stringify(value) ?? "";
 }
 
-/**
- * The text of an id.
- * @param id - the id
- * @returns the text
- */
-function idText(id: NodeId): string {
-    return typeof id === "number" ? formatF64(id) : id;
-}
-
 /**
  * The XML attributes of one row: the columns that came from XML attributes (`untypedAttribute`).
  * @param writes - the column writes of the table
@@ -1202,9 +1206,13 @@ function planFor(snapshot: GraphSnapshot, options: (XgmmlExportOptions & CommonE
     return plan;
 }
 
-/** The XGMML exporter. */
+/**
+ * The XGMML exporter.
+ * @category Built-in formats
+ */
 export const xgmmlExporter: GraphExporter<XgmmlExportOptions> = Object.freeze({
     format: FORMAT,
+    options: Object.freeze(["cytoscapeEscapes"]),
     capabilities: CAPABILITIES,
     check: (snapshot: GraphSnapshot, options?: XgmmlExportOptions & CommonExportOptions): readonly LossNote[] =>
         Object.freeze(planExport(snapshot, resolveExportOptions(options), resolveEscapes(options)).notes),