@graphty/graph-io 0.3.25 → 0.3.26

package/dist/src/formats/cys/importer.js

@@ -9,30 +9,37 @@
  * groups, nested-network pointers); the subnetwork's CyCSV tables give its columns (LOCAL_ATTRS as
  * they are, the SHARED_ATTRS columns `cytables.xml` joins in, HIDDEN and app tables as hidden
  * columns under their namespace); its first view gives positions (y flipped) and the `graphics`
- * column, further views `position@<n>` columns. 2.x: one full XGMML file per network, with
+ * column, further views `position@<n>` columns. A table's `name` is the label (what Cytoscape
+ * shows), in a label column named `name`, and ids an exporter mangled are restored from the node
+ * table's `graphty:originalId` (restoreMangledIds). 2.x: one full XGMML file per network, with
  * selection and hidden state from `cysession.xml`. Everything is resolved by the XGMML emitter, so
  * both readers share every column rule. Styles are not read (issue #706): W_STYLES_NOT_IMPORTED.
  */
 import { GraphFormatError, INVALID_INDEX } from "@graphty/graph-format";
 import { declareResolved } from "../../common/attributes.js";
 import { IdCoercer } from "../../common/ids.js";
-import { decodeEntryName, readBytes, throwIfAborted } from "../../common/input.js";
-import { chooseGraph, reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { decodeEntryName, throwIfAborted } from "../../common/input.js";
+import { chooseGraph, graphChosen, reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { agree, elementCount, plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { startsLikeZip } from "../../common/zip.js";
 import { ImportError, } from "../../types.js";
+import { ORIGINAL_ID_ATTRIBUTE } from "../graphml/constants.js";
 import { XGMML_ISSUE, XGMML_ORIGIN_NAMESPACE } from "../xgmml/constants.js";
 import { isCyTrue, } from "../xgmml/document.js";
-import { dialectOf, membersOf, XgmmlEmitter, } from "../xgmml/emit.js";
+import { dialectOf, membersOf, parseCoordinate, XgmmlEmitter, } from "../xgmml/emit.js";
 import { parseXgmml, resolveSettings } from "../xgmml/importer.js";
 import { CYS_ISSUE, CYTOSCAPE_NAMESPACE, DEFAULT_MAX_UNCOMPRESSED, EXTENSIONS, FORMAT, HIDDEN_COLUMN, META_KEY, MIME_TYPES, SELECTED_COLUMN, VIEW_POSITION_PREFIX, } from "./constants.js";
-import { elementsNamed, listed, openSession, readXmlTree, urlDecode, } from "./session.js";
+import { elementsNamed, entryLabel, listed, openSession, parseXmlTree, readXmlTree, urlDecode, } from "./session.js";
 import { cellAtt, readCyTable, virtualColumnsOf } from "./tables.js";
-/** The per-format defaults: SUIDs as written, edges directed unless they say otherwise, no weight. */
+/**
+ * The per-format defaults: SUIDs as written, edges directed unless they say otherwise, the edge
+ * `weight` column as the weight (as for XGMML, the format of the session's networks).
+ */
 const FORMAT_DEFAULTS = {
     ids: "keep",
     defaultDirected: true,
-    weightFrom: null,
+    weightFrom: "weight",
     addMissingNodes: false,
 };
 /** The common options the session importer reads. */
@@ -46,6 +53,7 @@ const USED_OPTIONS = new Set([
     "weightFrom",
     "weightDtype",
     "long",
+    "restoreMangledIds",
     "errorLimit",
     "signal",
     "onProgress",
@@ -101,24 +109,65 @@ async function prepare(input, sink, options) {
  * @returns the document and its dialect
  */
 async function parseEntry(session, entry, report, inner) {
-    const bytes = await session.read(entry);
-    const scratch = new ImportReportBuilder(FORMAT, Number.MAX_SAFE_INTEGER);
+    return (await parseOptionalEntry(session, entry, report, inner, false));
+}
+/**
+ * Read an XGMML entry, its issues and counts relayed into the import's report (the entry name
+ * in each message), parsing within what is left of the import's error limit. A fatal issue fails
+ * the import, unless the entry is optional (a view): then it is recorded as an error and the
+ * entry is skipped (null).
+ * @param session - the session
+ * @param entry - the entry
+ * @param report - the import's report
+ * @param inner - the options entries are read with
+ * @param optional - whether the import can go on without the entry
+ * @returns the document and its dialect, or null for an optional entry that cannot be read
+ */
+async function parseOptionalEntry(session, entry, report, inner, optional) {
+    const scratch = new ImportReportBuilder(FORMAT, Math.max(0, report.errorLimit - report.errorCount));
     try {
+        // a damaged entry (bad CRC, truncated deflate) fails the scratch report like a parse error
+        const bytes = await session.read(entry, scratch);
         const doc = await parseXgmml(bytes, scratch, inner, undefined);
         const dialect = dialectOf(doc, scratch);
         relay(scratch.issues, report, entry.name);
+        addCounts(scratch, report);
         return { doc, dialect };
     }
     catch (err) {
         if (!(err instanceof ImportError)) {
             throw err;
         }
+        addCounts(scratch, report);
         const { issues } = scratch;
+        if (scratch.truncated) {
+            // the entry reached the import's error limit: relaying its errors aborts the import
+            relay(issues, report, entry.name);
+        }
         const fatal = issues.at(-1);
         relay(issues.slice(0, -1), report, entry.name);
-        return report.fail(fatal?.code ?? CYS_ISSUE.CORRUPT, `${entry.name}: ${fatal?.message ?? err.message}`, {
-            line: fatal?.line ?? null,
-        });
+        const message = `${entryLabel(entry.name)}: ${fatal?.message ?? err.message}`;
+        const where = { line: fatal?.line ?? null };
+        if (fatal?.code === CYS_ISSUE.TOO_LARGE) {
+            // the byte budget is a limit of the whole import, not damage to one entry
+            report.error("unsupported", fatal.code, message);
+            throw report.abort(message, { code: fatal.code });
+        }
+        if (optional) {
+            report.error("parse-error", fatal?.code ?? CYS_ISSUE.CORRUPT, `${message}; the entry is not read`, where);
+            return null;
+        }
+        return report.fail(fatal?.code ?? CYS_ISSUE.CORRUPT, message, where);
+    }
+}
+/**
+ * Add an entry's element counts (the nodes skipped while parsing it) to the import's.
+ * @param from - the entry's report
+ * @param to - the import's report
+ */
+function addCounts(from, to) {
+    for (const key of Object.keys(from.counts)) {
+        to.counts[key] += from.counts[key];
     }
 }
 /**
@@ -131,10 +180,10 @@ function relay(issues, report, entry) {
     for (const issue of issues) {
         const where = { line: issue.line, element: issue.element };
         if (issue.severity === "error") {
-            report.error(issue.category, issue.code, `${entry}: ${issue.message}`, where);
+            report.error(issue.category, issue.code, `${entryLabel(entry)}: ${issue.message}`, where);
         }
         else {
-            report.warning(issue.category, issue.code, `${entry}: ${issue.message}`, where);
+            report.warning(issue.category, issue.code, `${entryLabel(entry)}: ${issue.message}`, where);
         }
     }
 }
@@ -152,13 +201,22 @@ async function networks3(session, report, inner, docs) {
     const choices = [];
     for (const network of layout.networks) {
         const parsed = await parseEntry(session, network, report, inner);
+        if (parsed.dialect.view) {
+            report.fail(XGMML_ISSUE.VIEW_DOCUMENT, `${network.name}: this is a session view file (cy:view), not a network file; it holds no topology`, { line: parsed.doc.root.line });
+        }
         docs.set(network.name, parsed);
         for (const graph of registeredGraphs(parsed)) {
+            if (graph.id === null) {
+                const label = graph.label === null ? "" : ` ("${graph.label}")`;
+                report.error("missing-value", XGMML_ISSUE.MISSING_ID, `${network.name}: a registered subnetwork${label} has no id; its tables and views cannot be found and it is skipped`, { line: graph.line });
+                continue;
+            }
             const members = membersOf(parsed.doc, graph);
             choices.push({
                 era: "3",
                 network,
-                graphId: graph.id ?? "",
+                graph,
+                graphId: graph.id,
                 name: graph.label ?? graph.id,
                 nodes: new Set(members.nodes).size,
                 edges: members.edges.length,
@@ -171,12 +229,17 @@ async function networks3(session, report, inner, docs) {
         !layout.networks.some((n) => n.suid === t.network) &&
         !isGroupTable(t, session, docs));
     if (strayViews.length > 0 || strayTables.length > 0) {
-        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `${strayViews.length + strayTables.length} view(s) or table(s) belong to a network the session does not hold and were not read: ${listed([...strayViews, ...strayTables.map((t) => t.name)])}`);
+        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `${strayViews.length + strayTables.length} view${plural(strayViews.length + strayTables.length)} or table${plural(strayViews.length + strayTables.length)} ${agree(strayViews.length + strayTables.length, "belongs", "belong")} to a network the session does not hold and were not read: ${listed([...strayViews, ...strayTables.map((t) => t.name)])}`);
     }
     if (layout.networkList === null) {
         return choices;
     }
-    const tree = await readXmlTree(await session.read(layout.networkList), layout.networkList.name, report, inner);
+    const tree = await parseXmlTree(await session.read(layout.networkList, report), layout.networkList.name, report, inner);
+    if (typeof tree === "string") {
+        // the list only orders the networks: without it they keep the order of their entries
+        report.warning("unsupported", CYS_ISSUE.ENTRY_SKIPPED, `${layout.networkList.name}: ${tree}; it is not read and the networks are listed in entry order`);
+        return choices;
+    }
     const order = new Map();
     for (const node of elementsNamed(tree, "network")) {
         const id = node.attrs.get("id");
@@ -213,7 +276,9 @@ function isGroupTable(table, session, docs) {
  * @returns the graphs
  */
 function registeredGraphs(parsed) {
-    return parsed.doc.root.subgraphs.filter((g) => isCyTrue(g.registered));
+    const subnetworks = parsed.doc.root.subgraphs.filter((g) => isCyTrue(g.registered));
+    // a registered root with no subnetworks (another tool's network file) is the network itself
+    return subnetworks.length === 0 && isCyTrue(parsed.doc.root.registered) ? [parsed.doc.root] : subnetworks;
 }
 /**
  * Import one registered subnetwork of a 3.x session.
@@ -223,97 +288,72 @@ function registeredGraphs(parsed) {
  * @param parsed - its network file, parsed for this import (its records are filled in)
  */
 async function import3(prepared, choice, sink, parsed) {
-    const { report, inner, session } = prepared;
-    const { layout } = session;
-    const { doc, dialect } = parsed;
-    const graph = doc.root.subgraphs.find((g) => g.id === choice.graphId);
-    const members = membersOf(doc, graph);
+    const { graph } = choice;
+    const members = membersOf(parsed.doc, graph);
     const nodes = byId(members.nodes);
     const edges = byId(members.edges);
-    const cache = new Map();
-    const tableOf = (path) => {
-        let pending = cache.get(path);
-        if (pending === undefined) {
-            const entry = layout.tables.find((t) => t.tablePath === path);
-            pending =
-                entry === undefined
-                    ? Promise.resolve(null)
-                    : session.read(entry).then((bytes) => readCyTable(bytes, path, entry.name, report, inner));
-            cache.set(path, pending);
-        }
-        return pending;
-    };
-    const virtuals = layout.cytables === null ? [] : await readVirtuals(session, layout.cytables, report, inner);
-    // a row of an element the file declares outside this network (a collapsed group's member, a
-    // meta-edge) is Cytoscape's bookkeeping, not a stale row
-    const declared = new Set([
-        ...doc.nodes.flatMap((n) => (n.id === null ? [] : [n.id])),
-        ...doc.edges.flatMap((e) => (e.id === null ? [] : [e.id])),
-    ]);
-    let unmatched = 0;
-    for (const entry of layout.tables.filter((t) => t.network === choice.graphId && t.element !== null)) {
-        throwIfAborted(inner.signal);
-        const table = await tableOf(entry.tablePath);
-        if (table === null) {
-            continue;
-        }
-        const local = entry.namespace === "LOCAL_ATTRS";
-        const shared = entry.namespace === "SHARED_ATTRS";
-        const namespace = local ? null : entry.namespace;
-        const hidden = !local && !shared;
-        const target = (key) => {
-            if (entry.element === "network") {
-                return key === choice.graphId ? graph.atts : undefined;
-            }
-            return (entry.element === "node" ? nodes : edges).get(key)?.atts;
-        };
-        for (const [key, cells] of table.rows) {
-            const atts = target(key);
-            if (atts === undefined) {
-                if (!declared.has(key)) {
-                    unmatched++;
-                }
-                continue;
-            }
-            const line = table.lines.get(key) ?? 0;
-            for (let i = 1; i < table.columns.length && i < cells.length; i++) {
-                const att = cellAtt(table.columns[i], cells[i], line, namespace, hidden);
-                if (att !== null) {
-                    atts.push(att);
-                }
-            }
-        }
-        for (const virtual of await virtualColumnsOf(table, virtuals, tableOf, report)) {
-            // a shared column named like a local one is renamed; the local one keeps the name
-            const owned = table.columns.some((c) => c.name === virtual.column.name);
-            let ns = namespace;
-            if (local) {
-                ns = owned ? "SHARED_ATTRS" : null;
-            }
-            for (const [key, text] of virtual.values) {
-                const att = cellAtt(virtual.column, text, table.lines.get(key) ?? 0, ns, hidden);
-                if (att !== null) {
-                    target(key)?.push(att);
-                }
-            }
-        }
+    // the records are shared by every network of the file: what this import adds is undone after
+    const restore = saveRecords(graph, nodes, edges);
+    try {
+        await fill3(prepared, choice, sink, parsed, nodes, edges);
     }
-    if (unmatched > 0) {
-        report.warning("parse-error", CYS_ISSUE.TABLE_ROW, `${unmatched} table row(s) of network ${choice.graphId} name no node, edge or network of it (stale rows); they are not read`);
+    finally {
+        restore();
     }
-    const views = layout.views.filter((v) => v.network === choice.graphId);
-    let visualStyle = null;
-    const extraViews = [];
-    for (const [i, view] of views.entries()) {
-        const viewDoc = (await parseEntry(session, view, report, inner)).doc;
-        if (i === 0) {
-            visualStyle = viewDoc.root.attrs.get("cy:visualStyle") ?? null;
-            applyView(viewDoc, graph, nodes, edges, report, view.name);
+}
+/**
+ * The state of the records an import fills in (atts, coordinates, graphics), and a function that
+ * puts it back.
+ * @param graph - the subnetwork
+ * @param nodes - its node records
+ * @param edges - its edge records
+ * @returns the restore function
+ */
+function saveRecords(graph, nodes, edges) {
+    const saved = [...nodes.values()].map((n) => ({
+        n,
+        atts: n.atts.length,
+        x: n.x,
+        y: n.y,
+        z: n.z,
+        graphics: n.graphics,
+    }));
+    const savedEdges = [...edges.values()].map((e) => ({ e, atts: e.atts.length, graphics: e.graphics }));
+    const graphAtts = graph.atts.length;
+    const graphGraphics = graph.graphics;
+    return () => {
+        for (const { n, atts, x, y, z, graphics } of saved) {
+            n.atts.length = atts;
+            Object.assign(n, { x, y, z, graphics });
         }
-        else {
-            extraViews.push(viewPositions(viewDoc, prepared.zAs));
+        for (const { e, atts, graphics } of savedEdges) {
+            e.atts.length = atts;
+            e.graphics = graphics;
         }
+        graph.atts.length = graphAtts;
+        graph.graphics = graphGraphics;
+    };
+}
+/**
+ * Fill one subnetwork's records from its tables and views and emit it.
+ * @param prepared - the prepared import
+ * @param choice - the subnetwork
+ * @param sink - the sink
+ * @param parsed - its network file
+ * @param nodes - its node records by id
+ * @param edges - its edge records by id
+ */
+async function fill3(prepared, choice, sink, parsed, nodes, edges) {
+    const { report, inner } = prepared;
+    const { doc, dialect } = parsed;
+    const { graph } = choice;
+    const members = membersOf(doc, graph);
+    const unmatched = await applyTables(prepared, choice, doc, nodes, edges);
+    if (unmatched > 0) {
+        report.warning("parse-error", CYS_ISSUE.TABLE_ROW, `${unmatched} table row${plural(unmatched)} of network ${choice.graphId} ${agree(unmatched, "names", "name")} no node, edge or network in it (left over from deleted elements) and ${agree(unmatched, "is", "are")} not read`);
     }
+    const restoredIds = inner.restoreMangledIds ? restoreIds(members.nodes) : new Map();
+    const { visualStyle, extraViews, extraIds } = await readViews(prepared, choice, nodes, edges);
     const cyMeta = sessionMeta(prepared, {
         collection: doc.root.label ?? choice.network.title,
         network: choice.graphId,
@@ -327,27 +367,212 @@ async function import3(prepared, choice, sink, parsed) {
         entry: choice.network.name,
         graphName: localName(graph) ?? choice.name,
         metaExtra: { [META_KEY]: cyMeta },
-        groupNodes: new Set(members.nodes
-            .filter((n) => n.atts.some((a) => a.name === "__isGroup" && isCyTrue(a.value)))
-            .flatMap((n) => (n.id === null ? [] : [n.id]))),
+        labelFromName: true,
+        restoredIds,
+        groupNodes: groupNodeIds(members.nodes),
         resolvePointer: pointerResolver(prepared, doc),
         onMissingMember: (group, member) => {
-            const record = groups.find((g) => g.group === group);
-            if (record === undefined) {
-                groups.push({ group, members: [member] });
-            }
-            else if (!record.members.includes(member)) {
-                record.members.push(member);
-            }
+            addMissingMember(groups, group, member);
         },
     };
     const settings = { labelAliases: false, cytoscapeEscapes: false, zAs: prepared.zAs };
     new XgmmlEmitter(doc, dialect, sink, report, prepared.inner, settings, extras).emit(graph);
     if (groups.length > 0) {
-        report.warning("unsupported", CYS_ISSUE.COLLAPSED_GROUP, `${groups.length} collapsed group(s) hold ${groups.reduce((n, g) => n + g.members.length, 0)} member(s) that are not in the network; they are listed in meta.extra.cytoscape.groups`);
+        const missing = groups.reduce((n, g) => n + g.members.length, 0);
+        report.warning("unsupported", CYS_ISSUE.COLLAPSED_GROUP, `${groups.length} collapsed group${plural(groups.length)} ${agree(groups.length, "holds", "hold")} ${missing} member${plural(missing)} that are not in the network; they are listed in meta.extra.cytoscape.groups`);
     }
     reportRootOnly(parsed, report, choice.network.name);
-    writeViewPositions(sink, extraViews, views.slice(1).map((v) => v.view), report, prepared.inner);
+    writeViewPositions(sink, extraViews, extraIds, report, prepared.inner, restoredIds);
+}
+/**
+ * The ids of the nodes Cytoscape marks as groups.
+ * @param nodes - the network's node records
+ * @returns their ids
+ */
+function groupNodeIds(nodes) {
+    return new Set(nodes
+        .filter((n) => n.atts.some((a) => a.name === "__isGroup" && isCyTrue(a.value)))
+        .flatMap((n) => (n.id === null ? [] : [n.id])));
+}
+/**
+ * Record a collapsed group's member that is not in the network.
+ * @param groups - the groups with missing members, added to
+ * @param group - the group's id
+ * @param member - the member's id
+ */
+function addMissingMember(groups, group, member) {
+    const record = groups.find((g) => g.group === group);
+    if (record === undefined) {
+        groups.push({ group, members: [member] });
+    }
+    else if (!record.members.includes(member)) {
+        record.members.push(member);
+    }
+}
+/**
+ * Add the cells of a subnetwork's tables to its node, edge and network records.
+ * @param prepared - the prepared import
+ * @param choice - the subnetwork
+ * @param doc - its network file
+ * @param nodes - its node records by id
+ * @param edges - its edge records by id
+ * @returns the number of rows that name no element of the network
+ */
+async function applyTables(prepared, choice, doc, nodes, edges) {
+    const { report, inner, session } = prepared;
+    const { layout } = session;
+    // each network reads its tables into its own report, so a shared table's issues, and a
+    // table that fails the import, land in every network that reads it.
+    // ponytail: a table shared by several networks is inflated and parsed once per network (the
+    // byte budget is charged once); cache the parse and relay its issues if importAll gets slow
+    const tables = new Map();
+    const tableOf = (path) => {
+        let pending = tables.get(path);
+        if (pending === undefined) {
+            const entry = layout.tables.find((t) => t.tablePath === path);
+            pending =
+                entry === undefined
+                    ? Promise.resolve(null)
+                    : session.read(entry, report).then((bytes) => readCyTable(bytes, path, entry.name, report, inner));
+            tables.set(path, pending);
+        }
+        return pending;
+    };
+    const ctx = {
+        choice,
+        graph: choice.graph,
+        nodes,
+        edges,
+        // a row of an element the file declares outside this network (a collapsed group's member, a
+        // meta-edge) is Cytoscape's bookkeeping, not a stale row
+        declared: new Set([
+            ...doc.nodes.flatMap((n) => (n.id === null ? [] : [n.id])),
+            ...doc.edges.flatMap((e) => (e.id === null ? [] : [e.id])),
+        ]),
+        virtuals: layout.cytables === null ? [] : await readVirtuals(session, layout.cytables, report, inner),
+        tableOf,
+        report,
+    };
+    let unmatched = 0;
+    for (const entry of layout.tables.filter((t) => t.network === choice.graphId && t.element !== null)) {
+        throwIfAborted(inner.signal);
+        const table = await tableOf(entry.tablePath);
+        if (table !== null) {
+            unmatched += await applyTable(ctx, entry, table);
+        }
+    }
+    return unmatched;
+}
+/**
+ * Add the cells of one table, and of the shared columns that extend it, to the records.
+ * @param ctx - the shared state
+ * @param entry - the table's entry
+ * @param table - the table
+ * @returns the number of rows that name no element of the network
+ */
+async function applyTable(ctx, entry, table) {
+    const local = entry.namespace === "LOCAL_ATTRS";
+    const namespace = local ? null : entry.namespace;
+    const hidden = !local && entry.namespace !== "SHARED_ATTRS";
+    const target = (key) => {
+        if (entry.element === "network") {
+            return key === ctx.choice.graphId ? ctx.graph.atts : undefined;
+        }
+        return (entry.element === "node" ? ctx.nodes : ctx.edges).get(key)?.atts;
+    };
+    let unmatched = 0;
+    for (const [key, cells] of table.rows) {
+        const atts = target(key);
+        if (atts !== undefined) {
+            atts.push(...rowAtts(table, key, cells, namespace, hidden));
+        }
+        else if (!ctx.declared.has(key)) {
+            unmatched++;
+        }
+    }
+    for (const virtual of await virtualColumnsOf(table, ctx.virtuals, ctx.tableOf, ctx.report)) {
+        // a shared column named like a local one is renamed; the local one keeps the name
+        const owned = table.columns.some((c) => c.name === virtual.column.name);
+        const ns = local ? sharedNamespace(owned) : namespace;
+        for (const [key, text] of virtual.values) {
+            const atts = target(key);
+            if (atts !== undefined) {
+                pushAtt(atts, cellAtt(virtual.column, text, table.lines.get(key) ?? 0, ns, hidden));
+            }
+        }
+    }
+    return unmatched;
+}
+/**
+ * The attributes of one table row's cells (the first cell is the SUID key).
+ * @param table - the table
+ * @param key - the row's key
+ * @param cells - the row's cells
+ * @param namespace - the namespace the attributes are written in, or null
+ * @param hidden - whether the table is one of Cytoscape's hidden ones
+ * @returns the attributes of the cells that hold a value
+ */
+function rowAtts(table, key, cells, namespace, hidden) {
+    const line = table.lines.get(key) ?? 0;
+    const out = [];
+    for (let i = 1; i < table.columns.length && i < cells.length; i++) {
+        pushAtt(out, cellAtt(table.columns[i], cells[i], line, namespace, hidden));
+    }
+    return out;
+}
+/**
+ * The namespace of a shared column in a local table: renamed when a local column has its name.
+ * @param owned - whether a local column has the shared column's name
+ * @returns "SHARED_ATTRS", or null for none
+ */
+function sharedNamespace(owned) {
+    return owned ? "SHARED_ATTRS" : null;
+}
+/**
+ * Add an attribute to a record's list, unless there is none.
+ * @param atts - the record's attributes
+ * @param att - the attribute, or null
+ */
+function pushAtt(atts, att) {
+    if (att !== null) {
+        atts.push(att);
+    }
+}
+/**
+ * Read a subnetwork's views: the first (the lowest view SUID, whatever the order of the entries)
+ * fills the records' coordinates and graphics, each further one gives positions only. A view that
+ * cannot be read is recorded and skipped.
+ * @param prepared - the prepared import
+ * @param choice - the subnetwork
+ * @param nodes - its node records by id
+ * @param edges - its edge records by id
+ * @returns the first view's style, and the positions and SUIDs of the further views
+ */
+async function readViews(prepared, choice, nodes, edges) {
+    const { report, inner, session } = prepared;
+    const views = session.layout.views
+        .filter((v) => v.network === choice.graphId)
+        .sort((a, b) => a.view.length - b.view.length || (a.view < b.view ? -1 : Number(a.view > b.view)));
+    let visualStyle = null;
+    const extraViews = [];
+    const extraIds = [];
+    let first = true;
+    for (const view of views) {
+        const viewDoc = (await parseOptionalEntry(session, view, report, inner, true))?.doc;
+        if (viewDoc === undefined) {
+            continue;
+        }
+        if (first) {
+            first = false;
+            visualStyle = viewDoc.root.attrs.get("cy:visualStyle") ?? null;
+            applyView(viewDoc, choice.graph, nodes, edges, report, view.name);
+        }
+        else {
+            extraViews.push(viewPositions(viewDoc, prepared.zAs, nodes, report, view.name));
+            extraIds.push(view.view);
+        }
+    }
+    return { visualStyle, extraViews, extraIds };
 }
 /**
  * The virtual columns of `tables/cytables.xml`.
@@ -358,9 +583,20 @@ async function import3(prepared, choice, sink, parsed) {
  * @returns the virtual columns in document order
  */
 async function readVirtuals(session, entry, report, inner) {
-    const tree = await readXmlTree(await session.read(entry), entry.name, report, inner);
+    const tree = await parseXmlTree(await session.read(entry, report), entry.name, report, inner);
+    if (typeof tree === "string") {
+        // only the shared columns are lost: every table's own columns are still read
+        report.error("parse-error", CYS_ISSUE.TABLE, `${entryLabel(entry.name)}: ${tree}; its virtual columns are not read`);
+        return [];
+    }
     const out = [];
     for (const node of elementsNamed(tree, "virtualColumn")) {
+        const missing = ["name", "targetTable", "sourceTable", "sourceColumn"].filter((k) => !node.attrs.has(k));
+        if (missing.length > 0) {
+            const named = node.attrs.has("name") ? ` "${node.attrs.get("name") ?? ""}"` : "";
+            report.error("parse-error", CYS_ISSUE.TABLE, `${entryLabel(entry.name)}: a virtual column${named} has no ${missing.join(", ")}; the column is not read`);
+            continue;
+        }
         const a = (key) => node.attrs.get(key) ?? "";
         out.push({
             name: a("name"),
@@ -400,12 +636,14 @@ function byId(records) {
  */
 function applyView(view, graph, nodes, edges, report, entry) {
     let dangling = 0;
+    const seen = new Set();
     for (const node of view.nodes) {
         const target = node.viewId === null ? undefined : nodes.get(node.viewId);
         if (target === undefined) {
             dangling++;
             continue;
         }
+        duplicateViewNode(seen, node, report, entry);
         target.x = node.x;
         target.y = node.y;
         target.z = node.z;
@@ -427,26 +665,71 @@ function applyView(view, graph, nodes, edges, report, entry) {
         graph.graphics = { ...(graph.graphics ?? {}), ...view.root.graphics };
     }
     if (dangling > 0) {
-        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `${entry}: ${dangling} view element(s) name no node or edge of the network; they are not read`);
+        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `${entryLabel(entry)}: ${dangling} view element${plural(dangling)} ${agree(dangling, "names", "name")} no node or edge of the network; they are not read`);
     }
 }
 /**
- * The positions of a further view, by model node id: y flipped to y-up, z in the position only
- * under zAs "position".
+ * W_DUPLICATE_NODE for a view element that repeats a node an earlier one of the view gave.
+ * @param seen - the model node ids seen so far in the view
+ * @param node - the view element
+ * @param report - the report
+ * @param entry - the view entry name
+ */
+function duplicateViewNode(seen, node, report, entry) {
+    const id = node.viewId;
+    if (seen.has(id)) {
+        report.warning("validation-error", XGMML_ISSUE.DUPLICATE_NODE, `${entryLabel(entry)}: the view gives node "${id}" twice; the later element is used`, { line: node.line, element: id });
+    }
+    seen.add(id);
+}
+/**
+ * The positions of a further view, by model node id, read by the first view's rules: y flipped
+ * to y-up, z in the position only under zAs "position", a coordinate that does not parse
+ * E_BAD_VALUE (the position is unset; a bad z is 0), an element naming no node of the network
+ * counted in one W_DANGLING_REFERENCE.
  * @param view - the view document
  * @param zAs - where z goes
+ * @param nodes - the network's node records by id
+ * @param report - the report
+ * @param entry - the view entry name
  * @returns the positions
  */
-function viewPositions(view, zAs) {
+function viewPositions(view, zAs, nodes, report, entry) {
     const out = new Map();
+    const seen = new Set();
+    let dangling = 0;
+    const coordinate = (text, node) => {
+        if (text === null) {
+            return null;
+        }
+        const n = parseCoordinate(text);
+        if (n === null) {
+            report.error("validation-error", XGMML_ISSUE.BAD_VALUE, `${entryLabel(entry)}: graphics coordinate "${text}" is not a number`, {
+                line: node.line,
+                element: node.viewId,
+            });
+        }
+        return n;
+    };
     for (const node of view.nodes) {
-        const x = Number(node.x);
-        const y = Number(node.y);
-        const z = zAs === "position" ? Number(node.z ?? 0) : 0;
-        if (node.viewId !== null && node.x !== null && node.y !== null && Number.isFinite(x) && Number.isFinite(y)) {
-            out.set(node.viewId, [x, y === 0 ? 0 : -y, Number.isFinite(z) ? z : 0]);
+        if (node.viewId === null || !nodes.has(node.viewId)) {
+            dangling++;
+            continue;
+        }
+        duplicateViewNode(seen, node, report, entry);
+        const x = coordinate(node.x, node);
+        const y = coordinate(node.y, node);
+        const z = zAs === "position" ? coordinate(node.z, node) : null;
+        if (x !== null && y !== null) {
+            out.set(node.viewId, [x, y === 0 ? 0 : -y, z ?? 0]);
+        }
+        else {
+            out.delete(node.viewId);
         }
     }
+    if (dangling > 0) {
+        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `${entryLabel(entry)}: ${dangling} view element${plural(dangling)} ${agree(dangling, "names", "name")} no node of the network; they are not read`);
+    }
     return out;
 }
 /**
@@ -456,8 +739,9 @@ function viewPositions(view, zAs) {
  * @param viewIds - each view's SUID
  * @param report - the report
  * @param common - the id rule
+ * @param restoredIds - the original ids of mangled nodes, by written id
  */
-function writeViewPositions(sink, views, viewIds, report, common) {
+function writeViewPositions(sink, views, viewIds, report, common, restoredIds) {
     const coercer = new IdCoercer(common.ids);
     views.forEach((positions, i) => {
         const name = `${VIEW_POSITION_PREFIX}${i + 2}`;
@@ -478,7 +762,7 @@ function writeViewPositions(sink, views, viewIds, report, common) {
         for (const [id, xyz] of positions) {
             let index;
             try {
-                index = sink.indexOf(coercer.text(id));
+                index = sink.indexOf(coercer.text(restoredIds.get(id) ?? id));
             }
             catch {
                 continue; // an id the id rule refuses was refused, and recorded, as a node already
@@ -489,6 +773,26 @@ function writeViewPositions(sink, views, viewIds, report, common) {
         }
     });
 }
+/**
+ * The original ids an exporter's `sanitizeIds: "mangle"` kept in the node table's
+ * `graphty:originalId` column; each such cell is taken out of the node's columns.
+ * @param nodes - the node records, table cells merged in
+ * @returns the original id by written id
+ */
+function restoreIds(nodes) {
+    const out = new Map();
+    for (const node of nodes) {
+        const at = node.atts.findIndex((a) => a.name === ORIGINAL_ID_ATTRIBUTE &&
+            (a.namespace ?? null) === null &&
+            a.value !== null &&
+            a.children.length === 0);
+        if (node.id !== null && at >= 0) {
+            out.set(node.id, node.atts[at].value);
+            node.atts.splice(at, 1);
+        }
+    }
+    return out;
+}
 /**
  * The network's name from its own table (the LOCAL `name` att), else null.
  * @param graph - the subnetwork with its table atts
@@ -556,7 +860,7 @@ function reportRootOnly(parsed, report, entry) {
     const nodes = parsed.doc.nodes.filter((n) => !held.has(n)).length;
     const edges = parsed.doc.edges.filter((e) => !held.has(e)).length;
     if (nodes + edges > 0) {
-        report.warning("unsupported", XGMML_ISSUE.ROOT_ONLY_ELEMENTS, `${entry}: ${nodes} node(s) and ${edges} edge(s) belong to no registered network (group meta-edges, collapsed group members) and were not read`);
+        report.warning("unsupported", XGMML_ISSUE.ROOT_ONLY_ELEMENTS, `${entryLabel(entry)}: ${elementCount(nodes, edges)} ${agree(nodes + edges, "belongs", "belong")} to none of the session's networks (group meta-edges or collapsed group members) and ${agree(nodes + edges, "was", "were")} not read`);
     }
 }
 // ---------------------------------------------------------------------------------------- 2.x
@@ -573,8 +877,11 @@ async function networks2(session, report, inner) {
     if (layout.cysession === null) {
         return report.fail(CYS_ISSUE.NOT_SESSION, "the session has no cysession.xml");
     }
-    const tree = await readXmlTree(await session.read(layout.cysession), layout.cysession.name, report, inner);
+    const tree = await readXmlTree(await session.read(layout.cysession, report), layout.cysession.name, report, inner);
     const documentVersion = tree.attrs.get("documentVersion") ?? "";
+    if (documentVersion.length > 0 && !/^\d+(\.\d+)*$/.test(documentVersion.trim())) {
+        report.warning("validation-error", XGMML_ISSUE.DOCUMENT_VERSION, `${layout.cysession.name}: documentVersion "${documentVersion}" does not parse; the session is read as Cytoscape 2.x`);
+    }
     if (documentVersion.startsWith("3")) {
         report.fail(CYS_ISSUE.VERSION, `cysession.xml has documentVersion ${documentVersion} and no version marker: the 2011 Cytoscape 3.0 pre-release layout, which no released Cytoscape reads`);
     }
@@ -588,16 +895,28 @@ async function networks2(session, report, inner) {
     const missing = [];
     const named = new Set();
     for (const record of elementsNamed(tree, "network")) {
-        const id = record.attrs.get("id") ?? "";
-        const filename = record.attrs.get("filename") ?? `${id}.xgmml`;
-        if (id === "Network Root") {
+        const given = record.attrs.get("id");
+        const filename = record.attrs.get("filename") ?? (given === undefined ? undefined : `${given}.xgmml`);
+        if (given === "Network Root") {
             continue;
         }
+        if (filename === undefined) {
+            sessionRecord(report, layout.cysession.name, "a <network> has neither an id nor a filename; it is not read");
+            continue;
+        }
+        const id = given ?? urlDecode(filename.replace(/\.xgmml$/i, ""));
+        if (given === undefined) {
+            sessionRecord(report, layout.cysession.name, `a <network> for ${filename} has no id; it is named "${id}" after its file`);
+        }
         const file = byDecoded.get(filename);
         if (file === undefined) {
             missing.push(filename);
             continue;
         }
+        if (named.has(file)) {
+            sessionRecord(report, layout.cysession.name, `the <network> "${id}" names ${filename}, which an earlier record already names; it is not read a second time`);
+            continue;
+        }
         named.add(file);
         const parent = record.children.find((c) => c.name === "parent")?.attrs.get("id") ?? null;
         choices.push({
@@ -609,14 +928,24 @@ async function networks2(session, report, inner) {
         });
     }
     if (missing.length > 0) {
-        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `cysession.xml names ${missing.length} network file(s) the session does not hold: ${listed(missing)}`);
+        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `cysession.xml names ${missing.length} network file${plural(missing.length)} the session does not hold: ${listed(missing)}`);
     }
     const unnamed = order.filter((e) => !named.has(e)).map((e) => e.name);
     if (unnamed.length > 0) {
-        report.warning("unsupported", CYS_ISSUE.ENTRY_SKIPPED, `${unnamed.length} network file(s) are not in cysession.xml's network tree and were not read: ${listed(unnamed)}`);
+        report.warning("unsupported", CYS_ISSUE.ENTRY_SKIPPED, `${unnamed.length} network file${plural(unnamed.length)} ${agree(unnamed.length, "is", "are")} not in cysession.xml's network tree and were not read: ${listed(unnamed)}`);
     }
     return choices.sort((a, b) => order.indexOf(a.file) - order.indexOf(b.file));
 }
+/**
+ * W_CYS_SESSION_RECORD: a cysession.xml network record without an id, or one naming a file an
+ * earlier record names.
+ * @param report - the report
+ * @param entry - the cysession.xml entry name
+ * @param message - what is wrong and what is done
+ */
+function sessionRecord(report, entry, message) {
+    report.warning("validation-error", CYS_ISSUE.SESSION_RECORD, `${entryLabel(entry)}: ${message}`);
+}
 /**
  * Import one network of a 2.x session.
  * @param prepared - the prepared import
@@ -626,17 +955,21 @@ async function networks2(session, report, inner) {
 async function import2(prepared, choice, sink) {
     const { report, inner, session } = prepared;
     const { doc, dialect } = await parseEntry(session, choice.file, report, inner);
+    let unmatched = 0;
     for (const [list, column] of [
         ["selectedNodes", SELECTED_COLUMN],
         ["hiddenNodes", HIDDEN_COLUMN],
     ]) {
-        mark(doc.nodes, idsIn(choice.record, list), column);
+        unmatched += mark(doc.nodes, idsIn(choice.record, list), column);
     }
     for (const [list, column] of [
         ["selectedEdges", SELECTED_COLUMN],
         ["hiddenEdges", HIDDEN_COLUMN],
     ]) {
-        mark(doc.edges, idsIn(choice.record, list), column);
+        unmatched += mark(doc.edges, idsIn(choice.record, list), column);
+    }
+    if (unmatched > 0) {
+        report.warning("validation-error", CYS_ISSUE.DANGLING_REFERENCE, `cysession.xml lists ${unmatched} selected or hidden name${plural(unmatched)} that ${choice.file.name} does not hold; they are not read`);
     }
     const cyMeta = sessionMeta(prepared, {
         collection: null,
@@ -677,12 +1010,20 @@ function idsIn(record, list) {
  * @param records - the node or edge records
  * @param ids - the listed names
  * @param column - the column
+ * @returns how many listed names match no record
  */
 function mark(records, ids, column) {
     if (ids.size === 0) {
-        return;
+        return 0;
     }
+    const matched = new Set();
     for (const record of records) {
+        if (record.id !== null && ids.has(record.id)) {
+            matched.add(record.id);
+        }
+        if (record.label !== null && ids.has(record.label)) {
+            matched.add(record.label);
+        }
         if ((record.id !== null && ids.has(record.id)) || (record.label !== null && ids.has(record.label))) {
             record.atts.push({
                 name: column,
@@ -702,6 +1043,7 @@ function mark(records, ids, column) {
             });
         }
     }
+    return ids.size - matched.size;
 }
 /**
  * The session facts of one network, and the once-per-import warnings about what is not read
@@ -718,10 +1060,10 @@ function sessionMeta(prepared, facts) {
     const { layout } = prepared.session;
     const { report } = prepared;
     if (layout.styles.length > 0) {
-        report.warning("unsupported", CYS_ISSUE.STYLES_NOT_IMPORTED, `the session's styles (${layout.styles.map((s) => s.path).join(", ")}) are not applied: style import is issue #706`);
+        report.warning("unsupported", CYS_ISSUE.STYLES_NOT_IMPORTED, `the session's styles (${layout.styles.map((s) => s.path).join(", ")}) are not applied`);
     }
     if (layout.skipped.length > 0) {
-        report.warning("unsupported", CYS_ISSUE.ENTRY_SKIPPED, `${layout.skipped.length} entries hold no graph data and were not read (apps, global tables, properties, images): ${listed(layout.skipped)}`);
+        report.warning("unsupported", CYS_ISSUE.ENTRY_SKIPPED, `${layout.skipped.length} ${layout.skipped.length === 1 ? "entry holds" : "entries hold"} no graph data and ${agree(layout.skipped.length, "was", "were")} not read (apps, global tables, properties, images): ${listed(layout.skipped)}`);
     }
     return {
         sessionVersion: layout.version,
@@ -758,10 +1100,12 @@ async function importChoice(prepared, index, sink) {
 async function importCys(input, sink, options) {
     const prepared = await prepare(input, sink, options);
     const index = chooseGraph(prepared.choices.map((c) => c.name), options, prepared.report);
-    if (prepared.choices.length > 1) {
-        prepared.report.warning("unsupported", CYS_ISSUE.MULTIPLE_GRAPHS, `the session holds ${prepared.choices.length} networks; ${prepared.choices.length - 1} were not read (use importAll, graphIndex or graphName)`);
+    if (prepared.choices.length > 1 && !graphChosen(options)) {
+        prepared.report.warning("unsupported", CYS_ISSUE.MULTIPLE_GRAPHS, `the session holds ${prepared.choices.length} networks; only the first is read (importAllGraphs() reads every one; graphIndex or graphName chooses one)`);
     }
-    return importChoice(prepared, index, sink);
+    const report = await importChoice(prepared, index, sink);
+    prepared.session.done();
+    return report;
 }
 /**
  * Import every network of a session, each into its own sink with its own report.
@@ -771,17 +1115,19 @@ async function importCys(input, sink, options) {
  * @returns one report per network
  */
 async function importAllCys(input, sinkFor, options) {
-    const bytes = (await readBytes(input, { signal: options?.signal ?? null })) ?? input;
-    const first = await prepare(bytes, null, options);
+    // the archive is opened and its network files parsed once: one byte budget, one progress,
+    // and every network's report starts from what reading the session recorded
+    const first = await prepare(input, null, options);
+    const opened = first.report.fork();
     const reports = [];
     for (let i = 0; i < first.choices.length; i++) {
         const sink = sinkFor(i);
-        // every network gets fresh records and a fresh report
-        const prepared = i === 0 ? first : await prepare(bytes, null, options);
+        const prepared = i === 0 ? first : { ...first, report: opened.fork() };
         reportSinkOptions(sink, options, prepared.report, true);
         reportUnusedOptions(options, prepared.report, USED_OPTIONS);
         reports.push(await importChoice(prepared, i, sink));
     }
+    first.session.done();
     return reports;
 }
 /**
@@ -799,8 +1145,18 @@ async function listCysGraphs(input, options) {
         edges: choice.era === "3" ? choice.edges : null,
     }));
 }
-/** A session's marker or folder name in the head of the archive. */
-const SESSION_NAME = /CytoscapeSession|cysession\.xml|\d+\.\d+\.\d+\.version/;
+/**
+ * A session's marker or folder name in the head of the archive, or an entry only a session has
+ * (Cytoscape's app state, a network, view or table file), for a session whose folder was renamed.
+ * The head is decoded whole, so a name can sit anywhere in it.
+ */
+const SESSION_NAMES = [
+    /CytoscapeSession|cysession\.xml/,
+    /(?<!\d)\d+\.\d+\.\d+\.version/,
+    /(?:^|\/)apps\/org\.cytoscape\./,
+    /(?:^|\/)(?:networks|views)\/\d+-[^/]*\.xgmml/,
+    /(?:^|\/)tables\/\d+-[^/]*\/[^/]+\.cytable/,
+];
 /**
  * Confidence that a head of bytes is a Cytoscape session: 0.95 for a zip whose head names the
  * session folder, its version marker or cysession.xml; 0 for any other zip, so an `.xlsx`, a
@@ -808,18 +1164,23 @@ const SESSION_NAME = /CytoscapeSession|cysession\.xml|\d+\.\d+\.\d+\.version/;
  * start after a short stub (a self-extracting archive) within the head.
  * @param head - the first bytes
  * @returns the confidence
+ * @category Plugin helpers
  */
 export function sniffCys(head) {
     for (let at = 0; at + 4 <= head.byteLength; at++) {
         if (startsLikeZip(head.subarray(at))) {
-            return SESSION_NAME.test(decodeEntryName(head.subarray(at))) ? 0.95 : 0;
+            return SESSION_NAMES.some((r) => r.test(decodeEntryName(head.subarray(at)))) ? 0.95 : 0;
         }
     }
     return 0;
 }
-/** The Cytoscape session importer. */
+/**
+ * The Cytoscape session importer.
+ * @category Built-in formats
+ */
 export const cysImporter = Object.freeze({
     format: FORMAT,
+    options: Object.freeze(["maxUncompressedBytes", "zAs"]),
     extensions: EXTENSIONS,
     mimeTypes: MIME_TYPES,
     sniff: sniffCys,