@graphty/graph-io 0.3.40 → 0.3.42

package/src/formats/dot/tokenizer.ts

@@ -87,6 +87,16 @@ function isDigit(c: number): boolean {
     return c >= 48 && c <= 57;
 }
 
+/**
+ * Whether a code unit is a blank between tokens: space, tab, vertical tab, form feed, or a U+FEFF
+ * after the start (concatenated files), which the shared text check reports.
+ * @param c - the code unit
+ * @returns true for a blank
+ */
+function isBlank(c: number): boolean {
+    return c === 0x20 || c === 0x09 || c === 0x0b || c === 0x0c || c === BOM_CODE;
+}
+
 /**
  * A pull lexer over one DOT document with arbitrary lookahead.
  * @category Plugin helpers
@@ -247,40 +257,68 @@ export class DotTokenizer {
                 this.pos = i + 1;
                 return { kind: "id", text: out, quoted: true, html: false, line };
             }
-            if (c === 0x5c) {
-                const d = text.charCodeAt(i + 1);
-                if (d === 0x22) {
-                    out += `${text.slice(segment, i)}"`;
-                    i += 2;
-                    segment = i;
-                    continue;
-                }
-                if (d === 0x5c) {
-                    // Graphviz's scanner consumes a backslash pair as one unit (both kept), so the
-                    // second backslash never escapes a closing quote: "x\\" is the text x\\
-                    i += 2;
-                    continue;
-                }
-                if (d === 0x0a || d === 0x0d) {
-                    out += text.slice(segment, i);
-                    i += d === 0x0d && text.charCodeAt(i + 2) === 0x0a ? 3 : 2;
-                    this.line++;
-                    segment = i;
-                    continue;
-                }
-                i++;
-                continue;
-            }
-            if (c === 0x0a || c === 0x0d) {
-                if (c === 0x0d && text.charCodeAt(i + 1) === 0x0a) {
-                    i++;
+            if (c === 0x5c && this.isQuotedSplice(i)) {
+                out += text.slice(segment, i);
+                if (text.codePointAt(i + 1) === 0x22) {
+                    out += '"';
                 }
-                this.line++;
+                i = this.quotedSpliceEnd(i);
+                segment = i;
+            } else {
+                i = this.quotedStep(i, c);
             }
-            i++;
         }
     }
 
+    /**
+     * Whether the backslash at `i` inside a quoted string starts a sequence that changes the decoded
+     * text: `\"` (an escaped quote) or a backslash before a line break (a line continuation).
+     * @param i - the offset of the backslash
+     * @returns true for an escaped quote or a line continuation
+     */
+    private isQuotedSplice(i: number): boolean {
+        const d = this.text.codePointAt(i + 1);
+        return d === 0x22 || d === 0x0a || d === 0x0d;
+    }
+
+    /**
+     * The offset just past an escaped quote or a line continuation, counting the line a
+     * continuation ends.
+     * @param i - the offset of the backslash
+     * @returns the offset after the sequence
+     */
+    private quotedSpliceEnd(i: number): number {
+        const { text } = this;
+        const d = text.charCodeAt(i + 1);
+        if (d === 0x22) {
+            return i + 2;
+        }
+        this.line++;
+        return d === 0x0d && text.codePointAt(i + 2) === 0x0a ? i + 3 : i + 2;
+    }
+
+    /**
+     * Step over one unit of a quoted string kept as written: a backslash pair (consumed as one unit,
+     * as Graphviz's scanner does, so the second backslash never escapes a closing quote: "x\\" is
+     * the text x\\), a lone backslash, a raw line break (counted) or any other character.
+     * @param i - the offset of the unit
+     * @param c - the code unit at `i`
+     * @returns the offset after the unit
+     */
+    private quotedStep(i: number, c: number): number {
+        const { text } = this;
+        if (c === 0x5c) {
+            return text.codePointAt(i + 1) === 0x5c ? i + 2 : i + 1;
+        }
+        if (c === 0x0a) {
+            this.line++;
+        } else if (c === 0x0d) {
+            this.line++;
+            return text.codePointAt(i + 1) === 0x0a ? i + 2 : i + 1;
+        }
+        return i + 1;
+    }
+
     /**
      * Lex an HTML string starting at the opening angle bracket: the text up to the matching
      * closing bracket, brackets balanced, kept verbatim including the outer pair.
@@ -313,51 +351,63 @@ export class DotTokenizer {
      */
     private skipTrivia(): void {
         const { text } = this;
-        for (;;) {
-            if (this.pos >= text.length) {
-                return;
-            }
+        while (this.pos < text.length) {
             const c = text.charCodeAt(this.pos);
-            if (c === 0x0a) {
-                this.line++;
-                this.pos++;
-                this.skipPreprocessorLine();
-                continue;
-            }
-            if (c === 0x0d) {
-                this.line++;
-                this.pos += text.charCodeAt(this.pos + 1) === 0x0a ? 2 : 1;
-                this.skipPreprocessorLine();
-                continue;
-            }
-            if (c === 0x20 || c === 0x09 || c === 0x0b || c === 0x0c) {
-                this.pos++;
-                continue;
-            }
-            if (c === BOM_CODE) {
-                // a U+FEFF after the start (concatenated files) is whitespace; the shared text check reports it
+            if (isBlank(c)) {
                 this.pos++;
-                continue;
-            }
-            if (c === 0x2f) {
-                const d = text.charCodeAt(this.pos + 1);
-                if (d === 0x2f) {
-                    this.skipToLineEnd();
-                    continue;
-                }
-                if (d === 0x2a) {
-                    this.skipBlockComment();
-                    continue;
-                }
-            }
-            if (c === 0x23 && this.pos === 0) {
-                this.skipToLineEnd();
-                continue;
+            } else if (!this.skipBreakOrComment(c)) {
+                return;
             }
-            return;
         }
     }
 
+    /**
+     * Skip one line break, comment or leading `#` line at the current position.
+     * @param c - the code unit at the current position
+     * @returns false when the current position starts a token
+     */
+    private skipBreakOrComment(c: number): boolean {
+        if (c === 0x0a || c === 0x0d) {
+            this.skipLineBreak(c);
+            return true;
+        }
+        if (c === 0x2f) {
+            return this.skipComment();
+        }
+        if (c === 0x23 && this.pos === 0) {
+            this.skipToLineEnd();
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Consume the line break at the current position (CR LF as one) and a `#` line after it.
+     * @param c - the code unit at the current position, LF or CR
+     */
+    private skipLineBreak(c: number): void {
+        this.line++;
+        this.pos += c === 0x0d && this.text.codePointAt(this.pos + 1) === 0x0a ? 2 : 1;
+        this.skipPreprocessorLine();
+    }
+
+    /**
+     * Skip a `//` or block comment starting at the current `/`.
+     * @returns false when the `/` starts no comment
+     */
+    private skipComment(): boolean {
+        const d = this.text.codePointAt(this.pos + 1);
+        if (d === 0x2f) {
+            this.skipToLineEnd();
+            return true;
+        }
+        if (d === 0x2a) {
+            this.skipBlockComment();
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Discard a `#` line when one starts at the current position (the start of a line).
      */

package/src/formats/gexf/exporter.ts

@@ -1247,6 +1247,27 @@ function lifetimeAttrs(roles: RoleColumns, row: number, plan: ExportPlan): strin
     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` /
@@ -1276,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`;
 }
@@ -1676,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") {
@@ -1701,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"),
@@ -1724,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`;
 }
 

package/src/formats/gexf/importer.ts

@@ -1328,20 +1328,15 @@ class GexfReader implements XmlHandler {
     }
 
     /**
-     * Declare one `<attribute id title type>` with its `<default>` and `<options>` (design
-     * sections 5.1, 5.5, 5.6). The edge attribute titled `weightFrom` is the weight and gets no
-     * column; its declaration is recorded in meta.weightOrigin.
-     * @param pending - the attribute as read
+     * Whether an attribute was already declared (warning that the first declaration is kept), and
+     * a warning when values that use it came before its declaration.
+     * @param domain - node or edge
+     * @param id - the attribute id
+     * @param where - the report location
+     * @returns true when the declaration is a duplicate and must be skipped
      */
-    private declareOne(pending: PendingAttribute): void {
-        const { report, sink, options } = this;
-        const { domain, dynamic, attrs } = pending;
-        const id = attrs.get("id");
-        const where = { line: pending.line, element: id ?? null };
-        if (id === undefined) {
-            report.error("validation-error", ATTRIBUTE_ID_CODE, "<attribute> without an id", where);
-            return;
-        }
+    private isDuplicateAttribute(domain: "node" | "edge", id: string, where: IssueLocation): boolean {
+        const { report } = this;
         const tracked = domain === "node" ? this.nodeAttrs : this.edgeAttrs;
         if (tracked.has(id) || (domain === "edge" && this.weightAttr !== null && this.weightAttr.id === id)) {
             report.warning(
@@ -1350,7 +1345,7 @@ class GexfReader implements XmlHandler {
                 `${domain} attribute "${id}" is declared twice; the first declaration is kept`,
                 where,
             );
-            return;
+            return true;
         }
         if (this.unknownAttributes.has(`${domain}:${id}`)) {
             report.warning(
@@ -1360,6 +1355,68 @@ class GexfReader implements XmlHandler {
                 where,
             );
         }
+        return false;
+    }
+
+    /**
+     * Whether an edge attribute becomes THE weight: the first attribute of the weight's title does
+     * (declared here), a later one only warns and stays a plain column.
+     * @param attribute - the attribute's domain, id, display name, title and type
+     * @param attribute.domain - node or edge
+     * @param attribute.id - the attribute id
+     * @param attribute.name - the column name
+     * @param attribute.title - the declared title, or null
+     * @param attribute.type - the declared type, or null
+     * @param where - the report location
+     * @returns true when the attribute was declared as the weight
+     */
+    private claimsWeight(
+        attribute: { domain: "node" | "edge"; id: string; name: string; title: string | null; type: string | null },
+        where: IssueLocation,
+    ): boolean {
+        const { report, sink, options } = this;
+        const { domain, id, name, title, type } = attribute;
+        if (domain !== "edge" || !isWeightField(name, options.weightFrom)) {
+            return false;
+        }
+        if (this.weightAttr !== null) {
+            // the first attribute of that title stays THE weight; this one becomes a plain column
+            report.warning(
+                "validation-error",
+                DUPLICATE_ATTRIBUTE_CODE,
+                `edge attribute "${id}" is also titled ${name}; attribute "${this.weightAttr.id}" is the weight, "${id}" is kept as a column`,
+                where,
+            );
+            return false;
+        }
+        const declared = declareAttribute({ format: GEXF_FORMAT, id, title, type, long: options.long });
+        for (const issue of declared.issues) {
+            report.warning(issue.category, issue.code, issue.message, where);
+        }
+        this.weightAttr = { id, spec: declared.spec, table: INVALID_INDEX as ExtensionHandle };
+        sink.setMeta({ weightOrigin: { format: GEXF_FORMAT, id, title, type, namespace: null } });
+        return true;
+    }
+
+    /**
+     * Declare one `<attribute id title type>` with its `<default>` and `<options>` (design
+     * sections 5.1, 5.5, 5.6). The edge attribute titled `weightFrom` is the weight and gets no
+     * column; its declaration is recorded in meta.weightOrigin.
+     * @param pending - the attribute as read
+     */
+    private declareOne(pending: PendingAttribute): void {
+        const { report, sink, options } = this;
+        const { domain, dynamic, attrs } = pending;
+        const id = attrs.get("id");
+        const where = { line: pending.line, element: id ?? null };
+        if (id === undefined) {
+            report.error("validation-error", ATTRIBUTE_ID_CODE, "<attribute> without an id", where);
+            return;
+        }
+        const tracked = domain === "node" ? this.nodeAttrs : this.edgeAttrs;
+        if (this.isDuplicateAttribute(domain, id, where)) {
+            return;
+        }
         const title = attrs.get("title") ?? null;
         const type = attrs.get("type") ?? null;
         if (type === null) {
@@ -1371,21 +1428,7 @@ class GexfReader implements XmlHandler {
             );
         }
         const name = title !== null && title.length > 0 ? title : id;
-        if (domain === "edge" && this.weightAttr !== null && isWeightField(name, options.weightFrom)) {
-            // the first attribute of that title stays THE weight; this one becomes a plain column
-            report.warning(
-                "validation-error",
-                DUPLICATE_ATTRIBUTE_CODE,
-                `edge attribute "${id}" is also titled ${name}; attribute "${this.weightAttr.id}" is the weight, "${id}" is kept as a column`,
-                where,
-            );
-        } else if (domain === "edge" && isWeightField(name, options.weightFrom)) {
-            const declared = declareAttribute({ format: GEXF_FORMAT, id, title, type, long: options.long });
-            for (const issue of declared.issues) {
-                report.warning(issue.category, issue.code, issue.message, where);
-            }
-            this.weightAttr = { id, spec: declared.spec, table: INVALID_INDEX as ExtensionHandle };
-            sink.setMeta({ weightOrigin: { format: GEXF_FORMAT, id, title, type, namespace: null } });
+        if (this.claimsWeight({ domain, id, name, title, type }, where)) {
             return;
         }
         const declaredNames = domain === "node" ? this.declaredNodeNames : this.declaredEdgeNames;
@@ -1717,6 +1760,15 @@ class GexfReader implements XmlHandler {
                 report.recordError(err, ref.where);
             }
         }
+        this.resolveParentsLists(lists);
+    }
+
+    /**
+     * Resolve the `<parents>` lists read so far into the parents column.
+     * @param lists - the queued `<parents>` lists
+     */
+    private resolveParentsLists(lists: readonly (typeof this.parentsRefs)[number][]): void {
+        const { sink, report } = this;
         for (const ref of lists) {
             const indices: number[] = [];
             for (const id of ref.ids) {
@@ -1763,7 +1815,7 @@ class GexfReader implements XmlHandler {
      * @param line - the line
      */
     private beginEdge(attrs: ReadonlyMap<string, string>, line: number): void {
-        const { report, sink, options } = this;
+        const { report, sink } = this;
         this.checkAbort();
         this.ctx.push(Ctx.Edge);
         this.edge = null;
@@ -1816,18 +1868,7 @@ class GexfReader implements XmlHandler {
         try {
             const source = this.coerceId(sourceText, where);
             const target = this.coerceId(targetText, where);
-            if (!options.addMissingNodes) {
-                if (sink.indexOf(source) === INVALID_INDEX) {
-                    throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${sourceText}"`, {
-                        id: source,
-                    });
-                }
-                if (sink.indexOf(target) === INVALID_INDEX) {
-                    throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${targetText}"`, {
-                        id: target,
-                    });
-                }
-            }
+            this.requireDeclaredEndpoints(source, target, sourceText, targetText);
             const weight = this.xmlWeight(attrs, where);
             const before = sink.edgeCount;
             index = this.resolver.addEdge(source, target, kind, weight, where);
@@ -1846,6 +1887,47 @@ class GexfReader implements XmlHandler {
         frame.mirror = this.resolver.lastMirror;
         frame.xmlWeight = attrs.get("weight") ?? null;
         this.edge = frame;
+        this.writeEdgeColumns(attrs, index, idText, where);
+    }
+
+    /**
+     * Throw when addMissingNodes is off and an endpoint names an undeclared node.
+     * @param source - the coerced source id
+     * @param target - the coerced target id
+     * @param sourceText - the source as written
+     * @param targetText - the target as written
+     */
+    private requireDeclaredEndpoints(source: NodeId, target: NodeId, sourceText: string, targetText: string): void {
+        const { sink, options } = this;
+        if (options.addMissingNodes) {
+            return;
+        }
+        if (sink.indexOf(source) === INVALID_INDEX) {
+            throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${sourceText}"`, {
+                id: source,
+            });
+        }
+        if (sink.indexOf(target) === INVALID_INDEX) {
+            throw new GraphFormatError("E_UNKNOWN_NODE", `edge references undeclared node "${targetText}"`, {
+                id: target,
+            });
+        }
+    }
+
+    /**
+     * Write the id, label, kind and lifetime columns of an added edge; a failure is reported.
+     * @param attrs - the edge's attributes
+     * @param index - the edge's index
+     * @param idText - the edge's id, or undefined
+     * @param where - the edge's location
+     */
+    private writeEdgeColumns(
+        attrs: ReadonlyMap<string, string>,
+        index: number,
+        idText: string | undefined,
+        where: IssueLocation,
+    ): void {
+        const { report, sink } = this;
         try {
             if (idText !== undefined) {
                 this.edgeIdColumn.set(sink, report, index, idText, where);
@@ -2555,35 +2637,18 @@ class GexfReader implements XmlHandler {
                 case "color":
                     columns.color.set(sink, report, index, parseColor(attrs), where);
                     break;
-                case "position": {
-                    const x = vizNumber(attrs, "x");
-                    const y = vizNumber(attrs, "y");
-                    const z = attrs.has("z") ? vizNumber(attrs, "z") : 0;
-                    this.positionColumn ??= new LazyColumn("node", {
-                        ...NODE_DECLS.position,
-                        extra: { ...NODE_DECLS.position.extra, sourceDims: attrs.has("z") ? 3 : 2 },
-                    });
-                    this.positionColumn.set(sink, report, index, [x, y, z], where);
+                case "position":
+                    this.writePosition(attrs, index, where);
                     break;
-                }
                 case "size":
                     this.sizeColumn.set(sink, report, index, vizNumber(attrs, "value"), where);
                     break;
                 case "thickness":
                     this.thicknessColumn.set(sink, report, index, vizNumber(attrs, "value"), where);
                     break;
-                case "shape": {
-                    const value = attrs.get("value");
-                    if (value === undefined) {
-                        throw new GraphFormatError("E_COLUMN_TYPE", "<viz:shape> without a value", { element: name });
-                    }
-                    columns.shape.set(sink, report, index, value, where);
-                    const uri = attrs.get("uri");
-                    if (domain === "node" && uri !== undefined) {
-                        this.shapeUriColumn.set(sink, report, index, uri, where);
-                    }
+                case "shape":
+                    this.writeShape(name, attrs, domain, index, where);
                     break;
-                }
                 default:
                     break;
             }
@@ -2595,6 +2660,51 @@ class GexfReader implements XmlHandler {
         }
     }
 
+    /**
+     * Write a `<viz:position>`.
+     * @param attrs - its attributes
+     * @param index - the node's index
+     * @param where - the node's location
+     */
+    private writePosition(attrs: ReadonlyMap<string, string>, index: number, where: IssueLocation): void {
+        const x = vizNumber(attrs, "x");
+        const y = vizNumber(attrs, "y");
+        const z = attrs.has("z") ? vizNumber(attrs, "z") : 0;
+        this.positionColumn ??= new LazyColumn("node", {
+            ...NODE_DECLS.position,
+            extra: { ...NODE_DECLS.position.extra, sourceDims: attrs.has("z") ? 3 : 2 },
+        });
+        this.positionColumn.set(this.sink, this.report, index, [x, y, z], where);
+    }
+
+    /**
+     * Write a `<viz:shape>` and, on a node, its `uri`.
+     * @param name - the element name as written
+     * @param attrs - its attributes
+     * @param domain - node or edge
+     * @param index - the element's index
+     * @param where - the element's location
+     */
+    private writeShape(
+        name: string,
+        attrs: ReadonlyMap<string, string>,
+        domain: "node" | "edge",
+        index: number,
+        where: IssueLocation,
+    ): void {
+        const { sink, report } = this;
+        const columns = domain === "node" ? this.nodeColumns : this.edgeColumns;
+        const value = attrs.get("value");
+        if (value === undefined) {
+            throw new GraphFormatError("E_COLUMN_TYPE", "<viz:shape> without a value", { element: name });
+        }
+        columns.shape.set(sink, report, index, value, where);
+        const uri = attrs.get("uri");
+        if (domain === "node" && uri !== undefined) {
+            this.shapeUriColumn.set(sink, report, index, uri, where);
+        }
+    }
+
     // ---------------------------------------------------------------- helpers
 
     /**