@fuzdev/fuz_ui 0.198.1 → 0.199.0

package/src/lib/mdz_opcodes_to_nodes.ts

@@ -0,0 +1,375 @@
+/**
+ * Converts a stream of mdz opcodes to the `MdzNode[]` tree representation.
+ *
+ * Stack-based replay: `open` pushes a frame, `close` pops and builds the node,
+ * `text`/`void` create leaf nodes, `append_text` extends the last text node,
+ * `revert` undoes an optimistic open and re-parents children.
+ *
+ * The output is identical to `mdz_parse()` from `mdz.ts`, enabling
+ * validation of the streaming parser against the existing fixture suite.
+ *
+ * @module
+ */
+
+import {DEV} from 'esm-env';
+
+import type {MdzNode, MdzTextNode, MdzLinkNode, MdzHeadingNode, MdzCodeNode} from './mdz.js';
+import type {MdzOpcode, MdzNodeId} from './mdz_opcodes.js';
+import {
+	extract_single_tag,
+	mdz_heading_id,
+	mdz_merge_adjacent_text,
+	mdz_push_merging_text,
+} from './mdz_helpers.js';
+
+interface StackFrame {
+	id: MdzNodeId;
+	node_type: string;
+	children: Array<MdzNode>;
+	start: number;
+	// metadata from open opcode
+	level?: number;
+	name?: string;
+	lang?: string | null;
+	// metadata from close opcode (deferred)
+	end?: number;
+	reference?: string;
+	link_type?: 'external' | 'internal';
+	heading_id?: string;
+}
+
+/**
+ * Convert an array of mdz opcodes to the `MdzNode[]` tree.
+ * Produces output identical to `mdz_parse()`.
+ */
+export const mdz_opcodes_to_nodes = (opcodes: Array<MdzOpcode>): Array<MdzNode> => {
+	const root: Array<MdzNode> = [];
+	const stack: Array<StackFrame> = [];
+	// index node IDs to their text content (for append_text and wrap)
+	const text_nodes = new Map<MdzNodeId, MdzTextNode | MdzCodeNode>();
+	// track which children array contains each text node (for wrap)
+	const node_parents = new Map<number, Array<MdzNode>>();
+
+	const target = (): Array<MdzNode> => {
+		return stack.length > 0 ? stack[stack.length - 1]!.children : root;
+	};
+
+	for (const op of opcodes) {
+		switch (op.type) {
+			case 'open': {
+				stack.push({
+					id: op.id,
+					node_type: op.node_type,
+					children: [],
+					start: op.start,
+					level: op.level,
+					name: op.name,
+					lang: op.lang,
+				});
+				break;
+			}
+
+			case 'close': {
+				if (DEV && stack.length === 0) {
+					throw new Error(`mdz_opcodes_to_nodes: close for id ${op.id} but stack is empty`);
+				}
+				const frame = stack.pop();
+				if (!frame) break;
+
+				// discard signal: the parser determined this node and its descendants
+				// should not appear in the tree (e.g. whitespace-only paragraph)
+				if (op.discard) break;
+
+				// apply deferred metadata
+				frame.end = op.end;
+				if (op.reference !== undefined) frame.reference = op.reference;
+				if (op.link_type !== undefined) frame.link_type = op.link_type;
+				if (op.heading_id !== undefined) frame.heading_id = op.heading_id;
+
+				const node = build_node(frame);
+				if (node) target().push(node);
+				break;
+			}
+
+			case 'text': {
+				const node: MdzTextNode | MdzCodeNode =
+					op.text_type === 'Code'
+						? {type: 'Code', content: op.content, start: op.start, end: op.end}
+						: {type: 'Text', content: op.content, start: op.start, end: op.end};
+				text_nodes.set(op.id, node);
+				const dest = target();
+				dest.push(node);
+				node_parents.set(op.id, dest);
+				break;
+			}
+
+			case 'append_text': {
+				if (DEV && !text_nodes.has(op.id)) {
+					throw new Error(`mdz_opcodes_to_nodes: append_text for unknown id ${op.id}`);
+				}
+				const existing = text_nodes.get(op.id);
+				if (existing) {
+					existing.content += op.content;
+					existing.end += op.content.length;
+				}
+				break;
+			}
+
+			case 'trim_text': {
+				if (DEV && !text_nodes.has(op.id)) {
+					throw new Error(`mdz_opcodes_to_nodes: trim_text for unknown id ${op.id}`);
+				}
+				const existing = text_nodes.get(op.id);
+				if (existing) {
+					existing.content = existing.content.slice(0, existing.content.length - op.count);
+					existing.end -= op.count;
+					if (existing.content.length === 0) {
+						const parent = node_parents.get(op.id);
+						if (parent) {
+							const idx = parent.indexOf(existing);
+							if (idx !== -1) parent.splice(idx, 1);
+						}
+						text_nodes.delete(op.id);
+						node_parents.delete(op.id);
+					}
+				}
+				break;
+			}
+
+			case 'void': {
+				target().push({type: 'Hr', start: op.start, end: op.end});
+				break;
+			}
+
+			case 'revert': {
+				// find and remove the reverted node's frame from the stack.
+				// fast path: reverts from #revert_all_optimistic always target the
+				// top of stack, so check that first to avoid splice + array alloc.
+				let reverted_frame: StackFrame | null = null;
+				if (stack.length > 0 && stack[stack.length - 1]!.id === op.id) {
+					reverted_frame = stack.pop()!;
+				} else {
+					for (let i = stack.length - 1; i >= 0; i--) {
+						if (stack[i]!.id === op.id) {
+							reverted_frame = stack.splice(i, 1)[0]!;
+							break;
+						}
+					}
+				}
+
+				if (DEV && !reverted_frame) {
+					throw new Error(`mdz_opcodes_to_nodes: revert for id ${op.id} but not found on stack`);
+				}
+				if (reverted_frame) {
+					if (op.wrap_node_type != null && op.wrap_id != null) {
+						// block-level revert: wrap content in a new container (e.g. Paragraph)
+						// and push it onto the stack so future opcodes flow into it.
+						const wrapper: StackFrame = {
+							id: op.wrap_id,
+							node_type: op.wrap_node_type,
+							children: [],
+							start: op.start,
+						};
+						if (op.replacement_text) {
+							mdz_push_merging_text(wrapper.children, {
+								type: 'Text',
+								content: op.replacement_text,
+								start: op.start,
+								end: op.start + op.replacement_text.length,
+							});
+						}
+						for (const child of reverted_frame.children) {
+							mdz_push_merging_text(wrapper.children, child);
+						}
+						stack.push(wrapper);
+					} else {
+						const dest = target();
+						// Re-parent replacement text and children, coalescing adjacent
+						// Text nodes inline. This reduces deeply nested reverts from
+						// O(n²) array pushes to O(n) string concatenations — each revert
+						// merges into the parent's last text node instead of growing the array.
+						if (op.replacement_text) {
+							mdz_push_merging_text(dest, {
+								type: 'Text',
+								content: op.replacement_text,
+								start: op.start,
+								end: op.start + op.replacement_text.length,
+							});
+						}
+						for (const child of reverted_frame.children) {
+							mdz_push_merging_text(dest, child);
+						}
+					}
+				}
+				break;
+			}
+
+			case 'wrap': {
+				const text_node = text_nodes.get(op.target_id);
+				const parent_children = node_parents.get(op.target_id);
+				if (!text_node || !parent_children) break;
+
+				const idx = parent_children.indexOf(text_node);
+				if (idx === -1) break;
+
+				// handle trailing punctuation trim
+				let trimmed_node: MdzTextNode | null = null;
+				if (op.trim_end && op.trim_end > 0 && op.trim_id != null) {
+					const trimmed_content = text_node.content.slice(text_node.content.length - op.trim_end);
+					text_node.content = text_node.content.slice(0, text_node.content.length - op.trim_end);
+					text_node.end -= op.trim_end;
+					trimmed_node = {
+						type: 'Text',
+						content: trimmed_content,
+						start: text_node.end,
+						end: text_node.end + trimmed_content.length,
+					};
+					text_nodes.set(op.trim_id, trimmed_node);
+					node_parents.set(op.trim_id, parent_children);
+				}
+
+				// create Link wrapping the text node
+				const link: MdzLinkNode = {
+					type: 'Link',
+					reference: op.reference,
+					children: [text_node],
+					link_type: op.link_type,
+					start: op.start,
+					end: op.end,
+				};
+
+				// replace text node with [Link, trimmed?] in parent
+				if (trimmed_node) {
+					parent_children.splice(idx, 1, link as MdzNode, trimmed_node as MdzNode);
+				} else {
+					parent_children[idx] = link;
+				}
+
+				node_parents.delete(op.target_id);
+				break;
+			}
+		}
+	}
+
+	return root;
+};
+
+/**
+ * Build an `MdzNode` from a completed stack frame.
+ */
+const build_node = (frame: StackFrame): MdzNode | null => {
+	switch (frame.node_type) {
+		case 'Paragraph': {
+			const children = mdz_merge_adjacent_text(frame.children);
+			if (children.length === 0) return null;
+
+			// extract single tag (MDX convention)
+			const single_tag = extract_single_tag(children);
+			if (single_tag) return single_tag;
+
+			return {
+				type: 'Paragraph',
+				children,
+				start: children[0]!.start,
+				end: children[children.length - 1]!.end,
+			};
+		}
+
+		case 'Heading': {
+			const children = mdz_merge_adjacent_text(frame.children);
+			const id = frame.heading_id ?? mdz_heading_id(children);
+			return {
+				type: 'Heading',
+				level: frame.level ?? 1,
+				id,
+				children,
+				start: frame.start,
+				end: frame.end!,
+			} as MdzHeadingNode;
+		}
+
+		case 'Bold':
+			return {
+				type: 'Bold',
+				children: mdz_merge_adjacent_text(frame.children),
+				start: frame.start,
+				end: frame.end!,
+			};
+
+		case 'Italic':
+			return {
+				type: 'Italic',
+				children: mdz_merge_adjacent_text(frame.children),
+				start: frame.start,
+				end: frame.end!,
+			};
+
+		case 'Strikethrough':
+			return {
+				type: 'Strikethrough',
+				children: mdz_merge_adjacent_text(frame.children),
+				start: frame.start,
+				end: frame.end!,
+			};
+
+		case 'Link':
+			return {
+				type: 'Link',
+				reference: frame.reference ?? '',
+				children: mdz_merge_adjacent_text(frame.children),
+				link_type: frame.link_type ?? 'internal',
+				start: frame.start,
+				end: frame.end!,
+			};
+
+		case 'Code': {
+			// optimistic inline code container — concatenate children text into leaf MdzCodeNode
+			let content = '';
+			for (const c of frame.children) {
+				if (c.type === 'Text') content += c.content;
+			}
+			return {
+				type: 'Code',
+				content,
+				start: frame.start,
+				end: frame.end!,
+			};
+		}
+
+		case 'Codeblock': {
+			// code block content is in children as text
+			let content = '';
+			for (const c of frame.children) {
+				if (c.type === 'Text') content += c.content;
+			}
+			return {
+				type: 'Codeblock',
+				lang: frame.lang ?? null,
+				content,
+				start: frame.start,
+				end: frame.end!,
+			};
+		}
+
+		case 'Element':
+			return {
+				type: 'Element',
+				name: frame.name ?? '',
+				children: mdz_merge_adjacent_text(frame.children),
+				start: frame.start,
+				end: frame.end!,
+			};
+
+		case 'Component':
+			return {
+				type: 'Component',
+				name: frame.name ?? '',
+				children: mdz_merge_adjacent_text(frame.children),
+				start: frame.start,
+				end: frame.end!,
+			};
+
+		default:
+			return null;
+	}
+};