@effected/yaml 0.1.0

package/internal/composer/document.js

@@ -0,0 +1,677 @@
+import { YamlAlias, YamlMap, YamlPair, YamlScalar, YamlSeq } from "../../YamlNode.js";
+import { checkAnchorOnAlias, getAnchorName, makeAlias, registerAnchor } from "./anchors.js";
+import { parseCSTAll } from "../cst-parser.js";
+import { clearMeta, createState, hasMeta, sameLine } from "./state.js";
+import { parseDirective, validateTagHandlesInDocument } from "./tags.js";
+import { collectMultilinePlainScalar, findNextContentChild, getScalarStyle, hasBlockMapAfterInList, hasValueSepAfter, indexOfChild, makeScalar, resolveScalar } from "./scalars.js";
+import { composeBlockMap, composeBlockSeq, composeFlatBlockMap } from "./block.js";
+import { composeFlowMap, composeFlowSeq } from "./flow.js";
+
+//#region src/internal/composer/document.ts
+/** The flow-composer dispatch wired into every state this module creates. */
+const FLOW = {
+	composeFlowMap,
+	composeFlowSeq
+};
+/**
+* SY6V: at document level, an anchor or tag must not be followed by a
+* block-sequence entry indicator "-" on the same line. The anchor/tag
+* applies to the next node, but a "-" on the same line means the parser
+* is interpreting it as a sequence start without proper structure.
+*/
+function validateAnchorTagNotFollowedBySeqDashOnSameLine(meta, children, idx, state) {
+	for (let j = idx + 1; j < children.length; j++) {
+		const c = children[j];
+		if (!c) continue;
+		if (c.type === "newline") return;
+		if (c.type === "whitespace") {
+			if (c.source === "-" && sameLine(state.text, meta.offset, c.offset)) {
+				state.errors.push({
+					code: "UnexpectedToken",
+					message: "Block sequence entry indicator '-' cannot follow an anchor or tag on the same line",
+					offset: c.offset,
+					length: c.length
+				});
+				return;
+			}
+			continue;
+		}
+		if (c.type === "block-seq" && c.length === 0) continue;
+		return;
+	}
+}
+/**
+* Validate that document markers (--- and ...) are not followed by content
+* on the same line. YAML 1.2 §9.1.4/§9.2 require these markers to be on
+* their own line (followed only by whitespace/comments).
+*
+* Checks within a single document's children AND across document boundaries
+* (e.g. `... invalid` where `...` ends doc 1 and `invalid` starts doc 2).
+*/
+function checkDocumentMarkerSameLine(children, state, nextDocChildren) {
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		if (!child) continue;
+		if (child.type !== "whitespace") continue;
+		if (child.source !== "...") continue;
+		let found = false;
+		for (let j = i + 1; j < children.length; j++) {
+			const next = children[j];
+			if (!next) continue;
+			if (next.type === "newline") break;
+			if (next.type === "whitespace" && next.source.trim() === "") continue;
+			if (next.type === "comment") break;
+			if (sameLine(state.text, child.offset, next.offset)) state.errors.push({
+				code: "UnexpectedToken",
+				message: "Content on same line as document-end marker",
+				offset: next.offset,
+				length: next.length
+			});
+			found = true;
+			break;
+		}
+		if (!found && nextDocChildren) for (const next of nextDocChildren) {
+			if (!next) continue;
+			if (next.type === "newline") break;
+			if (next.type === "whitespace" && next.source.trim() === "") continue;
+			if (sameLine(state.text, child.offset, next.offset)) state.errors.push({
+				code: "UnexpectedToken",
+				message: "Content on same line as document-end marker",
+				offset: next.offset,
+				length: next.length
+			});
+			break;
+		}
+	}
+}
+/**
+* Check for trailing content after a complete value at document level.
+* After a flow collection or scalar at the top level, only trivia and
+* document markers should follow. Skips if next meaningful content is ":"
+* (the flow collection is being used as a mapping key).
+*/
+function checkTrailingContentAfterDocValue(children, startIdx, state, allowMappingKey = true) {
+	for (let j = startIdx; j < children.length; j++) {
+		const next = children[j];
+		if (!next) continue;
+		if (next.type === "newline" || next.type === "comment") continue;
+		if (next.type === "whitespace") {
+			if (next.source === "---" || next.source === "...") break;
+			if (next.source === ":") break;
+			if (next.source.trim() === "") continue;
+		}
+		if (allowMappingKey && (next.type === "flow-scalar" || next.type === "block-scalar" || next.type === "flow-map" || next.type === "flow-seq")) {
+			const afterNode = findNextContentChild(children, j + 1);
+			if (hasValueSepAfter(children, j + 1) || afterNode !== null && afterNode.type === "block-map") break;
+		}
+		if (next.type === "flow-scalar" || next.type === "block-scalar" || next.type === "block-map" || next.type === "block-seq" || next.type === "flow-map" || next.type === "flow-seq" || next.type === "anchor" || next.type === "tag" || next.type === "alias") state.errors.push({
+			code: "UnexpectedToken",
+			message: "Trailing content after document value",
+			offset: next.offset,
+			length: next.length
+		});
+		break;
+	}
+}
+function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst) {
+	const spanEnd = Math.min(cst.offset + cst.length, state.text.length);
+	for (let ci = cst.offset; ci < spanEnd; ci++) {
+		const cc = state.text.charCodeAt(ci);
+		if (cc < 32 && cc !== 9 && cc !== 10 && cc !== 13) {
+			state.errors.push({
+				code: "UnexpectedCharacter",
+				message: `Unescaped control character U+${cc.toString(16).toUpperCase().padStart(4, "0")}`,
+				offset: ci,
+				length: 1
+			});
+			break;
+		}
+	}
+	const children = cst.children ?? [];
+	const directives = [];
+	let contents = null;
+	let documentComment;
+	const hasDocStart = children.some((c) => c.type === "whitespace" && c.source === "---");
+	let i = 0;
+	const meta = {};
+	const outerMeta = {};
+	let sawNewlineSinceMeta = false;
+	const commitMetaAcrossNewline = () => {
+		if (sawNewlineSinceMeta && hasMeta(meta)) {
+			if (meta.tag !== void 0) outerMeta.tag = meta.tag;
+			if (meta.anchor !== void 0) outerMeta.anchor = meta.anchor;
+			if (meta.comment !== void 0) outerMeta.comment = meta.comment;
+			clearMeta(meta);
+		}
+		sawNewlineSinceMeta = false;
+	};
+	while (i < children.length) {
+		const child = children[i];
+		if (!child) {
+			i++;
+			continue;
+		}
+		if (child.type === "directive") {
+			const directive = parseDirective(child.source);
+			if (directive) {
+				directives.push(directive);
+				if (directive.name === "TAG" && directive.parameters.length >= 2) {
+					const handle = directive.parameters[0];
+					const prefix = directive.parameters[1];
+					if (handle && prefix) state.tagMap.set(handle, prefix);
+				}
+			}
+			i++;
+			continue;
+		}
+		if (child.type === "newline" && hasMeta(meta)) sawNewlineSinceMeta = true;
+		if (child.type === "whitespace" || child.type === "newline") {
+			if (child.type === "whitespace" && (child.source === "]" || child.source === "}")) state.errors.push({
+				code: "MalformedFlowCollection",
+				message: `Unexpected flow indicator '${child.source}' at document level`,
+				offset: child.offset,
+				length: child.length
+			});
+			i++;
+			continue;
+		}
+		if (child.type === "comment" && contents === null) {
+			documentComment = child.source.startsWith("#") ? child.source.slice(1).trim() : child.source;
+			i++;
+			continue;
+		}
+		if (child.type === "error") {
+			state.errors.push({
+				code: "UnexpectedToken",
+				message: `Unexpected content: ${child.source.trim() || "(empty)"}`,
+				offset: child.offset,
+				length: child.length
+			});
+			i++;
+			continue;
+		}
+		if (child.type === "anchor") {
+			validateAnchorTagNotFollowedBySeqDashOnSameLine(child, children, i, state);
+			commitMetaAcrossNewline();
+			meta.anchor = getAnchorName(child, state.text);
+			i++;
+			continue;
+		}
+		if (child.type === "tag") {
+			validateAnchorTagNotFollowedBySeqDashOnSameLine(child, children, i, state);
+			commitMetaAcrossNewline();
+			meta.tag = child.source;
+			i++;
+			continue;
+		}
+		if (child.type === "flow-scalar" || child.type === "block-scalar") {
+			const nextContent = findNextContentChild(children, i + 1);
+			if (nextContent && nextContent.type === "block-map") {
+				if (hasDocStart) {
+					const docStartChild = children.find((c) => c.type === "whitespace" && c.source === "---");
+					if (docStartChild && sameLine(state.text, docStartChild.offset, child.offset)) state.errors.push({
+						code: "UnexpectedToken",
+						message: "Mapping cannot start on document-start (---) line",
+						offset: child.offset,
+						length: child.length
+					});
+				}
+				let mapMeta;
+				let keyMeta;
+				if (hasMeta(outerMeta)) {
+					mapMeta = { ...outerMeta };
+					keyMeta = hasMeta(meta) ? { ...meta } : void 0;
+				} else if (hasDocStart && hasMeta(meta)) {
+					mapMeta = { ...meta };
+					keyMeta = void 0;
+				} else keyMeta = hasMeta(meta) ? { ...meta } : void 0;
+				const key = makeScalar(child, state, keyMeta);
+				clearMeta(meta);
+				clearMeta(outerMeta);
+				sawNewlineSinceMeta = false;
+				contents = composeBlockMap(nextContent, state, key, mapMeta);
+				i = indexOfChild(children, nextContent) + 1;
+				continue;
+			}
+			if (hasValueSepAfter(children, i + 1)) {
+				let mapMeta;
+				let keyMeta;
+				if (hasMeta(outerMeta)) {
+					mapMeta = { ...outerMeta };
+					keyMeta = hasMeta(meta) ? { ...meta } : void 0;
+				} else if (hasDocStart && hasMeta(meta)) {
+					mapMeta = { ...meta };
+					keyMeta = void 0;
+				} else keyMeta = hasMeta(meta) ? { ...meta } : void 0;
+				const key = makeScalar(child, state, keyMeta);
+				clearMeta(meta);
+				clearMeta(outerMeta);
+				sawNewlineSinceMeta = false;
+				contents = composeFlatBlockMap(children, i + 1, cst, state, key, mapMeta);
+				break;
+			}
+			if (child.type === "flow-scalar" && getScalarStyle(child) === "plain") {
+				const { value, nextIdx, partsCount, endOffset } = collectMultilinePlainScalar(children, i, void 0, state.text);
+				const combined = { ...outerMeta };
+				if (meta.tag !== void 0) combined.tag = meta.tag;
+				if (meta.anchor !== void 0) combined.anchor = meta.anchor;
+				const resolved = resolveScalar(value, "plain", combined.tag, state);
+				const scalarLength = partsCount > 1 ? endOffset - child.offset : child.length;
+				contents = new YamlScalar({
+					value: resolved,
+					style: "plain",
+					offset: child.offset,
+					length: scalarLength,
+					...combined.tag !== void 0 ? { tag: combined.tag } : {},
+					...combined.anchor !== void 0 ? { anchor: combined.anchor } : {}
+				});
+				if (combined.anchor) registerAnchor(contents, combined.anchor, state, child.offset);
+				clearMeta(meta);
+				clearMeta(outerMeta);
+				sawNewlineSinceMeta = false;
+				if (partsCount > 1) {
+					const nextContent2 = findNextContentChild(children, nextIdx);
+					if (nextContent2) {
+						if (nextContent2.type === "flow-scalar" && hasValueSepAfter(children, indexOfChild(children, nextContent2) + 1) || nextContent2.type === "block-map" || nextContent2.type === "flow-scalar" && hasBlockMapAfterInList(children, indexOfChild(children, nextContent2) + 1)) state.errors.push({
+							code: "UnexpectedToken",
+							message: "Trailing content after document value",
+							offset: nextContent2.offset,
+							length: nextContent2.length
+						});
+					}
+				} else checkTrailingContentAfterDocValue(children, nextIdx, state, false);
+				i = nextIdx;
+				continue;
+			}
+			const combined = { ...outerMeta };
+			if (meta.tag !== void 0) combined.tag = meta.tag;
+			if (meta.anchor !== void 0) combined.anchor = meta.anchor;
+			contents = makeScalar(child, state, hasMeta(combined) ? combined : void 0);
+			clearMeta(meta);
+			clearMeta(outerMeta);
+			sawNewlineSinceMeta = false;
+			i++;
+			continue;
+		}
+		if (child.type === "block-map") {
+			const combined = { ...outerMeta };
+			if (meta.tag !== void 0) combined.tag = meta.tag;
+			if (meta.anchor !== void 0) combined.anchor = meta.anchor;
+			contents = composeBlockMap(child, state, void 0, hasMeta(combined) ? combined : void 0);
+			clearMeta(meta);
+			clearMeta(outerMeta);
+			sawNewlineSinceMeta = false;
+			i++;
+			continue;
+		}
+		if (child.type === "block-seq") {
+			const isRootSeq = contents === null;
+			const combined = { ...outerMeta };
+			if (meta.tag !== void 0) combined.tag = meta.tag;
+			if (meta.anchor !== void 0) combined.anchor = meta.anchor;
+			contents = composeBlockSeq(child, state, hasMeta(combined) ? combined : void 0);
+			clearMeta(meta);
+			clearMeta(outerMeta);
+			sawNewlineSinceMeta = false;
+			i++;
+			if (isRootSeq) checkTrailingContentAfterDocValue(children, i, state, false);
+			continue;
+		}
+		if (child.type === "flow-map") {
+			const nextAfterFlowMap0 = findNextContentChild(children, i + 1);
+			const flowIsKey = !!nextAfterFlowMap0 && nextAfterFlowMap0.type === "block-map";
+			let flowMeta;
+			let mapMeta;
+			if (flowIsKey && hasMeta(outerMeta)) {
+				mapMeta = { ...outerMeta };
+				flowMeta = hasMeta(meta) ? { ...meta } : void 0;
+			} else {
+				const combined = { ...outerMeta };
+				if (meta.tag !== void 0) combined.tag = meta.tag;
+				if (meta.anchor !== void 0) combined.anchor = meta.anchor;
+				flowMeta = hasMeta(combined) ? combined : void 0;
+			}
+			const flowMap = composeFlowMap(child, state, flowMeta);
+			clearMeta(meta);
+			clearMeta(outerMeta);
+			sawNewlineSinceMeta = false;
+			i++;
+			if (flowIsKey && nextAfterFlowMap0) {
+				contents = composeBlockMap(nextAfterFlowMap0, state, flowMap, mapMeta);
+				while (i < children.length && children[i] !== nextAfterFlowMap0) i++;
+				i++;
+			} else {
+				contents = flowMap;
+				checkTrailingContentAfterDocValue(children, i, state);
+			}
+			continue;
+		}
+		if (child.type === "flow-seq") {
+			const nextAfterFlowSeq0 = findNextContentChild(children, i + 1);
+			const flowIsKey = !!nextAfterFlowSeq0 && nextAfterFlowSeq0.type === "block-map";
+			let flowMeta;
+			let mapMeta;
+			if (flowIsKey && hasMeta(outerMeta)) {
+				mapMeta = { ...outerMeta };
+				flowMeta = hasMeta(meta) ? { ...meta } : void 0;
+			} else {
+				const combined = { ...outerMeta };
+				if (meta.tag !== void 0) combined.tag = meta.tag;
+				if (meta.anchor !== void 0) combined.anchor = meta.anchor;
+				flowMeta = hasMeta(combined) ? combined : void 0;
+			}
+			const flowSeq = composeFlowSeq(child, state, flowMeta);
+			clearMeta(meta);
+			clearMeta(outerMeta);
+			sawNewlineSinceMeta = false;
+			i++;
+			const nextAfterFlowSeq = findNextContentChild(children, i);
+			if (nextAfterFlowSeq && nextAfterFlowSeq.type === "block-map") {
+				contents = composeBlockMap(nextAfterFlowSeq, state, flowSeq, mapMeta);
+				while (i < children.length && children[i] !== nextAfterFlowSeq) i++;
+				i++;
+			} else {
+				contents = flowSeq;
+				checkTrailingContentAfterDocValue(children, i, state);
+			}
+			continue;
+		}
+		if (child.type === "alias") {
+			checkAnchorOnAlias(meta, child, state);
+			contents = makeAlias(child, state);
+			i++;
+			continue;
+		}
+		i++;
+	}
+	validateDirectives(directives, cst, state, hasSubsequentDocuments);
+	checkDocumentMarkerSameLine(children, state, nextDocCst?.children);
+	const hasDocEnd = children.some((c) => c.type === "whitespace" && c.source === "...");
+	let hasDocStartTab = false;
+	for (let ci = 0; ci < children.length; ci++) {
+		const c = children[ci];
+		if (c && c.type === "whitespace" && c.source === "---") {
+			if (state.text[c.offset + c.length] === "	") hasDocStartTab = true;
+			break;
+		}
+	}
+	return {
+		contents,
+		errors: [...state.errors],
+		warnings: [...state.warnings],
+		directives,
+		hasDocumentStart: hasDocStart,
+		hasDocumentEnd: hasDocEnd,
+		hasDocumentStartTab: hasDocStartTab,
+		...documentComment !== void 0 ? { comment: documentComment } : {}
+	};
+}
+/**
+* Validate YAML directive rules within a single document's CST.
+* Pushes errors into state.errors for any violations found.
+*/
+function validateDirectives(directives, cst, state, hasSubsequentDocuments = false) {
+	const children = cst.children ?? [];
+	if (directives.filter((d) => d.name === "YAML").length > 1) {
+		let directiveCount = 0;
+		for (const child of children) if (child.type === "directive" && child.source.trim().startsWith("%YAML")) {
+			directiveCount++;
+			if (directiveCount === 2) {
+				state.errors.push({
+					code: "InvalidDirective",
+					message: "Duplicate %YAML directive",
+					offset: child.offset,
+					length: child.length
+				});
+				break;
+			}
+		}
+	}
+	for (const child of children) {
+		if (child.type !== "directive") continue;
+		const src = child.source.trim();
+		if (!src.startsWith("%YAML")) continue;
+		const hashIdx = src.indexOf("#");
+		if (hashIdx > 0) {
+			const before = src[hashIdx - 1];
+			if (before !== " " && before !== "	") {
+				state.errors.push({
+					code: "InvalidDirective",
+					message: "Comment in directive requires preceding whitespace",
+					offset: child.offset,
+					length: child.length
+				});
+				continue;
+			}
+		}
+		const params = (hashIdx > 0 ? src.slice(0, hashIdx).trimEnd() : src).slice(1).split(/\s+/).slice(1);
+		if (params.length !== 1) state.errors.push({
+			code: "InvalidDirective",
+			message: params.length === 0 ? "%YAML directive requires a version parameter" : `%YAML directive has extra parameters: ${params.slice(1).join(" ")}`,
+			offset: child.offset,
+			length: child.length
+		});
+	}
+	let hasDirective = false;
+	let hasDocumentStart = false;
+	for (const child of children) {
+		if (child.type === "directive") hasDirective = true;
+		if (child.type === "whitespace" && child.source === "---") hasDocumentStart = true;
+	}
+	if (hasDirective && !hasDocumentStart) {
+		for (const child of children) if (child.type === "directive") {
+			state.errors.push({
+				code: "InvalidDirective",
+				message: "Directive must be followed by a document-start marker (---)",
+				offset: child.offset,
+				length: child.length
+			});
+			break;
+		}
+	}
+	if (hasSubsequentDocuments) {
+		let hasContent = false;
+		for (const child of children) {
+			if (child.type === "flow-scalar" || child.type === "block-scalar" || child.type === "block-map" || child.type === "block-seq" || child.type === "flow-map" || child.type === "flow-seq" || child.type === "alias" || child.type === "anchor" || child.type === "tag") hasContent = true;
+			if (child.type === "directive" && hasContent) state.errors.push({
+				code: "InvalidDirective",
+				message: "Directive after content requires a document-end marker (...) first",
+				offset: child.offset,
+				length: child.length
+			});
+			if (hasContent && child.children) {
+				const nested = findNestedDirective(child);
+				if (nested) state.errors.push({
+					code: "InvalidDirective",
+					message: "Directive after content requires a document-end marker (...) first",
+					offset: nested.offset,
+					length: nested.length
+				});
+			}
+		}
+	}
+}
+/** Recursively find the first directive node within a CST subtree. */
+function findNestedDirective(node) {
+	if (node.type === "directive") return node;
+	if (node.children) for (const child of node.children) {
+		const found = findNestedDirective(child);
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* Validate directive placement across a multi-document CST stream.
+*
+* YAML 1.2 requires that directives appearing between documents must be
+* preceded by a document-end marker (`...`). This function checks each
+* CST document node after the first: if it contains directives, the
+* preceding document must have ended with `...`.
+*/
+function validateCrossDocumentDirectives(cstNodes, state) {
+	for (let docIdx = 1; docIdx < cstNodes.length; docIdx++) {
+		const cst = cstNodes[docIdx];
+		if (!cst) continue;
+		const children = cst.children ?? [];
+		validateTagHandlesInDocument(cst, state);
+		if (!children.some((c) => c.type === "directive")) continue;
+		const prevCst = cstNodes[docIdx - 1];
+		if (!prevCst) continue;
+		const prevChildren = prevCst.children ?? [];
+		let prevEndedWithDocEnd = false;
+		for (let i = prevChildren.length - 1; i >= 0; i--) {
+			const c = prevChildren[i];
+			if (!c) continue;
+			if (c.source === "...") {
+				prevEndedWithDocEnd = true;
+				break;
+			}
+			if (c.type === "newline" || c.type === "whitespace" || c.type === "comment") continue;
+			break;
+		}
+		if (!prevEndedWithDocEnd) {
+			for (const child of children) if (child.type === "directive") {
+				state.errors.push({
+					code: "InvalidDirective",
+					message: "Directive between documents requires a document-end marker (...) after the previous document",
+					offset: child.offset,
+					length: child.length
+				});
+				break;
+			}
+		}
+	}
+}
+/**
+* Walk the AST and stamp `sourceMultiline: true` on every YamlScalar/Map/Seq
+* whose source span (offset..offset+length in `text`) contains a newline.
+*
+* The composer uses this single post-pass instead of threading the flag
+* through dozens of construction sites. Nodes whose span is single-line are
+* returned unchanged (no copy) to avoid unnecessary allocation.
+*/
+function isSourceMultiline(text, offset, length) {
+	if (length <= 0) return false;
+	const end = Math.min(offset + length, text.length);
+	for (let i = offset; i < end; i++) {
+		const ch = text.charCodeAt(i);
+		if (ch === 10 || ch === 13) return true;
+	}
+	return false;
+}
+function decorateSourceMultiline(node, text) {
+	if (node === null || node instanceof YamlAlias) return node;
+	if (node instanceof YamlScalar) {
+		if (!isSourceMultiline(text, node.offset, node.length)) return node;
+		return new YamlScalar({
+			value: node.value,
+			style: node.style,
+			...node.tag !== void 0 ? { tag: node.tag } : {},
+			...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+			...node.comment !== void 0 ? { comment: node.comment } : {},
+			...node.chomp !== void 0 ? { chomp: node.chomp } : {},
+			...node.raw !== void 0 ? { raw: node.raw } : {},
+			sourceMultiline: true,
+			offset: node.offset,
+			length: node.length
+		});
+	}
+	if (node instanceof YamlMap) {
+		const newItems = node.items.map((pair) => new YamlPair({
+			key: decorateSourceMultiline(pair.key, text) ?? pair.key,
+			value: pair.value === null ? null : decorateSourceMultiline(pair.value, text),
+			...pair.comment !== void 0 ? { comment: pair.comment } : {}
+		}));
+		const multiline = isSourceMultiline(text, node.offset, node.length);
+		return new YamlMap({
+			items: newItems,
+			style: node.style,
+			...node.tag !== void 0 ? { tag: node.tag } : {},
+			...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+			...node.comment !== void 0 ? { comment: node.comment } : {},
+			...multiline ? { sourceMultiline: true } : {},
+			offset: node.offset,
+			length: node.length
+		});
+	}
+	if (node instanceof YamlSeq) {
+		const newItems = node.items.map((item) => decorateSourceMultiline(item, text) ?? item);
+		const multiline = isSourceMultiline(text, node.offset, node.length);
+		return new YamlSeq({
+			items: newItems,
+			style: node.style,
+			...node.tag !== void 0 ? { tag: node.tag } : {},
+			...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+			...node.comment !== void 0 ? { comment: node.comment } : {},
+			...multiline ? { sourceMultiline: true } : {},
+			offset: node.offset,
+			length: node.length
+		});
+	}
+	return node;
+}
+function decorateDocumentSourceMultiline(doc, text) {
+	const decorated = decorateSourceMultiline(doc.contents ?? null, text);
+	if (decorated === doc.contents) return doc;
+	return {
+		contents: decorated,
+		errors: doc.errors,
+		warnings: doc.warnings,
+		directives: doc.directives,
+		...doc.comment !== void 0 ? { comment: doc.comment } : {},
+		hasDocumentStart: doc.hasDocumentStart,
+		hasDocumentEnd: doc.hasDocumentEnd,
+		hasDocumentStartTab: doc.hasDocumentStartTab
+	};
+}
+const EMPTY_DOCUMENT = {
+	contents: null,
+	errors: [],
+	warnings: [],
+	directives: [],
+	hasDocumentStart: false,
+	hasDocumentEnd: false,
+	hasDocumentStartTab: false
+};
+/**
+* Compose the first document of `text` with full error recovery — v3
+* `parseDocument` semantics minus the Effect wrapper and minus fatal-code
+* filtering (the facade applies `isFatalCode` to the returned diagnostics).
+* Cross-document directive-placement errors are validated into the same
+* state and therefore appear in the returned document's `errors`.
+*/
+function composeFirstDocument(text, options) {
+	const cstNodes = parseCSTAll(text);
+	const state = createState(text, FLOW, options);
+	validateCrossDocumentDirectives(cstNodes, state);
+	const doc = cstNodes[0];
+	if (!doc) return EMPTY_DOCUMENT;
+	return decorateDocumentSourceMultiline(composeDocument(doc, state, cstNodes.length > 1, cstNodes[1]), text);
+}
+/**
+* Compose every document of `text` with full error recovery — v3
+* `parseAllDocuments` semantics minus the Effect wrapper and minus
+* fatal-code filtering. Each document is composed with a fresh state; the
+* cross-document directive validation runs in its own state whose errors
+* are returned unfiltered as `streamErrors` (v3 filtered these to
+* `InvalidDirective` before failing — the facade applies that filter).
+*/
+function composeAllDocuments(text, options) {
+	const cstNodes = parseCSTAll(text);
+	const documents = [];
+	const crossDocState = createState(text, FLOW, options);
+	validateCrossDocumentDirectives(cstNodes, crossDocState);
+	for (let i = 0; i < cstNodes.length; i++) {
+		const cst = cstNodes[i];
+		if (!cst) continue;
+		const doc = composeDocument(cst, createState(text, FLOW, options), i < cstNodes.length - 1, cstNodes[i + 1]);
+		documents.push(decorateDocumentSourceMultiline(doc, text));
+	}
+	return {
+		documents,
+		streamErrors: crossDocState.errors
+	};
+}
+
+//#endregion
+export { composeAllDocuments, composeDocument, composeFirstDocument, validateCrossDocumentDirectives };