@effected/yaml 0.7.0 → 0.8.0

package/internal/composer/comments.js

@@ -0,0 +1,187 @@
+import { YamlMap, YamlScalar, YamlSeq } from "../../YamlNode.js";
+
+//#region src/internal/composer/comments.ts
+/** True when there is no line break between `start` and `end` in `text`. */
+function sameLineSpan(text, start, end) {
+	if (start < 0) return false;
+	return !text.slice(Math.max(0, start), Math.max(0, end)).includes("\n");
+}
+/**
+* True when only horizontal whitespace precedes `offset` on its line — i.e.
+* the token at `offset` starts its own line. Purely local, so it stays
+* correct even when a preceding node's span over-extends past line ends.
+*/
+function isOwnLineAt(text, offset) {
+	let i = offset - 1;
+	while (i >= 0) {
+		const ch = text[i];
+		if (ch === " " || ch === "	") {
+			i--;
+			continue;
+		}
+		return ch === "\n" || ch === "\r";
+	}
+	return true;
+}
+/**
+* True when the line immediately above the line containing `offset` is blank
+* (empty or horizontal whitespace only). Purely local — see
+* {@link isOwnLineAt} for why span-based gap checks are not used.
+*/
+function hasBlankLineAbove(text, offset) {
+	return blankLineAboveStart(text, offset) >= 0;
+}
+/**
+* Start offset of the blank line immediately above the line containing
+* `offset`, or `-1` when that line is not blank. The offset form of
+* {@link hasBlankLineAbove}, for callers that must locate the blank line
+* (e.g. to test whether it falls inside a preceding scalar token's span).
+*/
+function blankLineAboveStart(text, offset) {
+	const lineBreak = text.lastIndexOf("\n", Math.max(0, offset - 1));
+	if (lineBreak < 0) return -1;
+	const prevBreak = text.lastIndexOf("\n", lineBreak - 1);
+	return text.slice(prevBreak + 1, lineBreak).trim() === "" ? prevBreak + 1 : -1;
+}
+/**
+* The deepest trailing scalar reached by descending last-child edges from
+* `node` (a map's last pair's value, a seq's last item) — the node whose
+* token span a textually-following blank line could fall inside.
+*/
+function deepestTrailingScalar(node) {
+	let current = node;
+	for (;;) {
+		if (current instanceof YamlScalar) return current;
+		if (current instanceof YamlMap) {
+			const last = current.items[current.items.length - 1];
+			if (last === void 0) return void 0;
+			current = last.value ?? last.key;
+			continue;
+		}
+		if (current instanceof YamlSeq) {
+			const last = current.items[current.items.length - 1];
+			if (last === void 0) return void 0;
+			current = last;
+			continue;
+		}
+		return;
+	}
+}
+/**
+* True when the blank line immediately above `offset` is CONTENT of the
+* preceding keep-chomp block scalar, not a stylistic blank. Under `+`
+* chomping the trailing line breaks are part of the scalar's VALUE (the
+* composer already stores them there), so recording the same blank line as
+* `spaceBefore` (or a leading-blank embed on a terminal comment run) would
+* double-count it: emission renders both the kept newline and the stylistic
+* blank, growing the document on every format pass. Clip/strip scalars are
+* deliberately NOT excluded — their emission drops the trailing blank from
+* the value, so the `spaceBefore` capture is exactly what re-creates it.
+*
+* `prev` is the last composed node before `offset` (a pair's value, a seq
+* item); the check descends to its deepest trailing scalar and requires the
+* blank line to start inside that scalar's token span.
+*/
+function blankAboveIsKeepChompContent(text, offset, prev) {
+	if (prev === void 0) return false;
+	const scalar = deepestTrailingScalar(prev);
+	if (scalar === void 0 || scalar.chomp !== "keep") return false;
+	if (scalar.style !== "block-literal" && scalar.style !== "block-folded") return false;
+	const start = blankLineAboveStart(text, offset);
+	return start >= scalar.offset && start < scalar.offset + scalar.length;
+}
+/**
+* True when the line immediately below the line containing `offset` is blank
+* (empty or horizontal whitespace only) AND is itself followed by another
+* line. Purely local, the mirror of {@link hasBlankLineAbove} — used to embed
+* a blank line AFTER a comment run as a trailing empty line in the stored
+* comment string.
+*/
+function hasBlankLineBelow(text, offset) {
+	const lineEnd = text.indexOf("\n", Math.max(0, offset));
+	if (lineEnd < 0) return false;
+	const nextEnd = text.indexOf("\n", lineEnd + 1);
+	if (nextEnd < 0) return false;
+	return text.slice(lineEnd + 1, nextEnd).trim() === "";
+}
+/**
+* The stored text of a comment token: the RAW post-`#` slice, reference
+* parity with the `yaml` npm package — `# section` stores `" section"`,
+* `#no-space` stores `"no-space"`, `#   aligned` keeps its alignment.
+*
+* The one reserved string is `""`, which encodes an embedded blank line
+* inside a joined comment run — so a spaces-only raw slice stores with ONE
+* extra trailing space and the renderers strip it back off. A bare `#`
+* (raw `""`) stores `" "`, `# ` (raw `" "`) stores `"  "`, and so on; the
+* escape is injective, so every comment spelling roundtrips byte-intact.
+* Raw storage is what makes byte-intact roundtrip possible; trimming would
+* canonicalize every comment to `# text`.
+*/
+function rawCommentText(source) {
+	const raw = source.startsWith("#") ? source.slice(1) : source;
+	return /^ *$/.test(raw) ? `${raw} ` : raw;
+}
+/** Join two optional comment blocks with a newline. */
+function joinComments(a, b) {
+	return a === void 0 ? b : `${a}\n${b}`;
+}
+/** Zero-based column of `offset` within its line. */
+function columnAt(text, offset) {
+	if (offset <= 0) return 0;
+	return offset - (text.lastIndexOf("\n", offset - 1) + 1);
+}
+/**
+* Rebuild `node` with the given comment fields merged in (existing fields are
+* kept unless overridden; `commentBefore`/`comment` join with a newline when
+* both sides are present). Aliases are returned unchanged — they carry no
+* comment fields.
+*/
+function withCommentFields(node, fields) {
+	if (node instanceof YamlScalar) return new YamlScalar({
+		value: node.value,
+		style: node.style,
+		...node.tag !== void 0 ? { tag: node.tag } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...mergedCommentFields(node, fields),
+		...node.chomp !== void 0 ? { chomp: node.chomp } : {},
+		...node.blockIndent !== void 0 ? { blockIndent: node.blockIndent } : {},
+		...node.raw !== void 0 ? { raw: node.raw } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	if (node instanceof YamlMap) return new YamlMap({
+		items: node.items,
+		style: node.style,
+		...node.tag !== void 0 ? { tag: node.tag } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...mergedCommentFields(node, fields),
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	if (node instanceof YamlSeq) return new YamlSeq({
+		items: node.items,
+		style: node.style,
+		...node.tag !== void 0 ? { tag: node.tag } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...mergedCommentFields(node, fields),
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	return node;
+}
+function mergedCommentFields(existing, incoming) {
+	const commentBefore = incoming.commentBefore !== void 0 ? existing.commentBefore !== void 0 ? `${existing.commentBefore}\n${incoming.commentBefore}` : incoming.commentBefore : existing.commentBefore;
+	const comment = incoming.comment !== void 0 ? existing.comment !== void 0 ? `${existing.comment}\n${incoming.comment}` : incoming.comment : existing.comment;
+	const spaceBefore = incoming.spaceBefore ?? existing.spaceBefore;
+	return {
+		...commentBefore !== void 0 ? { commentBefore } : {},
+		...comment !== void 0 ? { comment } : {},
+		...spaceBefore !== void 0 ? { spaceBefore } : {}
+	};
+}
+
+//#endregion
+export { blankAboveIsKeepChompContent, blankLineAboveStart, columnAt, hasBlankLineAbove, hasBlankLineBelow, isOwnLineAt, joinComments, rawCommentText, sameLineSpan, withCommentFields };

package/internal/composer/document.js

@@ -1,7 +1,8 @@
 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 { checkAnchorOnAlias, getAnchorName, makeAlias, registerAnchor } from "./anchors.js";
+import { hasBlankLineAbove, hasBlankLineBelow, rawCommentText } from "./comments.js";
+import { clearMeta, commentProps, 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";
@@ -131,6 +132,9 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 	const directives = [];
 	let contents = null;
 	let documentComment;
+	let documentCommentAfter;
+	let lastLeadingCommentOffset = -1;
+	let sawDocEndMarker = false;
 	const hasDocStart = children.some((c) => c.type === "whitespace" && c.source === "---");
 	let i = 0;
 	const meta = {};
@@ -166,6 +170,7 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 		}
 		if (child.type === "newline" && hasMeta(meta)) sawNewlineSinceMeta = true;
 		if (child.type === "whitespace" || child.type === "newline") {
+			if (child.type === "whitespace" && child.source === "...") sawDocEndMarker = true;
 			if (child.type === "whitespace" && (child.source === "]" || child.source === "}")) state.errors.push({
 				code: "MalformedFlowCollection",
 				message: `Unexpected flow indicator '${child.source}' at document level`,
@@ -175,8 +180,18 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 			i++;
 			continue;
 		}
-		if (child.type === "comment" && contents === null) {
-			documentComment = child.source.startsWith("#") ? child.source.slice(1).trim() : child.source;
+		if (child.type === "comment" && contents === null && !sawDocEndMarker) {
+			const text = rawCommentText(child.source);
+			if (documentComment !== void 0 && hasBlankLineAbove(state.text, child.offset)) documentComment = `${documentComment}\n`;
+			documentComment = documentComment === void 0 ? text : `${documentComment}\n${text}`;
+			lastLeadingCommentOffset = child.offset;
+			i++;
+			continue;
+		}
+		if (child.type === "comment") {
+			const text = rawCommentText(child.source);
+			if (documentCommentAfter !== void 0 && hasBlankLineAbove(state.text, child.offset)) documentCommentAfter = `${documentCommentAfter}\n`;
+			documentCommentAfter = documentCommentAfter === void 0 ? text : `${documentCommentAfter}\n${text}`;
 			i++;
 			continue;
 		}
@@ -395,6 +410,8 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 			break;
 		}
 	}
+	if (documentComment !== void 0 && contents !== null && hasBlankLineBelow(state.text, lastLeadingCommentOffset)) documentComment = `${documentComment}\n`;
+	state.escapedComments.length = 0;
 	return {
 		contents,
 		errors: [...state.errors],
@@ -403,7 +420,8 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 		hasDocumentStart: hasDocStart,
 		hasDocumentEnd: hasDocEnd,
 		hasDocumentStartTab: hasDocStartTab,
-		...documentComment !== void 0 ? { comment: documentComment } : {}
+		...documentComment !== void 0 ? { comment: documentComment } : {},
+		...documentCommentAfter !== void 0 ? { commentAfter: documentCommentAfter } : {}
 	};
 }
 /**
@@ -568,8 +586,9 @@ function decorateSourceMultiline(node, text) {
 			style: node.style,
 			...node.tag !== void 0 ? { tag: node.tag } : {},
 			...node.anchor !== void 0 ? { anchor: node.anchor } : {},
-			...node.comment !== void 0 ? { comment: node.comment } : {},
+			...commentProps(node),
 			...node.chomp !== void 0 ? { chomp: node.chomp } : {},
+			...node.blockIndent !== void 0 ? { blockIndent: node.blockIndent } : {},
 			...node.raw !== void 0 ? { raw: node.raw } : {},
 			sourceMultiline: true,
 			offset: node.offset,
@@ -580,7 +599,7 @@ function decorateSourceMultiline(node, text) {
 		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 } : {}
+			...commentProps(pair)
 		}));
 		const multiline = isSourceMultiline(text, node.offset, node.length);
 		return new YamlMap({
@@ -588,7 +607,7 @@ function decorateSourceMultiline(node, text) {
 			style: node.style,
 			...node.tag !== void 0 ? { tag: node.tag } : {},
 			...node.anchor !== void 0 ? { anchor: node.anchor } : {},
-			...node.comment !== void 0 ? { comment: node.comment } : {},
+			...commentProps(node),
 			...multiline ? { sourceMultiline: true } : {},
 			offset: node.offset,
 			length: node.length
@@ -602,7 +621,7 @@ function decorateSourceMultiline(node, text) {
 			style: node.style,
 			...node.tag !== void 0 ? { tag: node.tag } : {},
 			...node.anchor !== void 0 ? { anchor: node.anchor } : {},
-			...node.comment !== void 0 ? { comment: node.comment } : {},
+			...commentProps(node),
 			...multiline ? { sourceMultiline: true } : {},
 			offset: node.offset,
 			length: node.length
@@ -619,6 +638,7 @@ function decorateDocumentSourceMultiline(doc, text) {
 		warnings: doc.warnings,
 		directives: doc.directives,
 		...doc.comment !== void 0 ? { comment: doc.comment } : {},
+		...doc.commentAfter !== void 0 ? { commentAfter: doc.commentAfter } : {},
 		hasDocumentStart: doc.hasDocumentStart,
 		hasDocumentEnd: doc.hasDocumentEnd,
 		hasDocumentStartTab: doc.hasDocumentStartTab
@@ -641,12 +661,29 @@ const EMPTY_DOCUMENT = {
 * state and therefore appear in the returned document's `errors`.
 */
 function composeFirstDocument(text, options) {
+	return composeFirstDocumentCounted(text, options).document;
+}
+/**
+* {@link composeFirstDocument} plus the CST-level document count of the whole
+* stream, from the single CST parse the compose already performs — no second
+* walk, and correct where a regex on `---` is not (a `---` inside a block
+* scalar or quoted string is content, not a document marker). Callers that
+* must refuse multi-document input (the `YamlFormat` single-document
+* contract) read `documentCount` instead of re-parsing.
+*/
+function composeFirstDocumentCounted(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);
+	if (!doc) return {
+		document: EMPTY_DOCUMENT,
+		documentCount: 0
+	};
+	return {
+		document: decorateDocumentSourceMultiline(composeDocument(doc, state, cstNodes.length > 1, cstNodes[1]), text),
+		documentCount: cstNodes.length
+	};
 }
 /**
 * Compose every document of `text` with full error recovery — v3
@@ -674,4 +711,4 @@ function composeAllDocuments(text, options) {
 }
 
 //#endregion
-export { composeAllDocuments, composeDocument, composeFirstDocument, validateCrossDocumentDirectives };
+export { EMPTY_DOCUMENT, composeAllDocuments, composeDocument, composeFirstDocument, composeFirstDocumentCounted, validateCrossDocumentDirectives };

package/internal/composer/flow.js

@@ -1,5 +1,6 @@
 import { YamlMap, YamlScalar, YamlSeq } from "../../YamlNode.js";
 import { checkAnchorOnAlias, getAnchorName, makeAlias, registerAnchor } from "./anchors.js";
+import { blankLineAboveStart, hasBlankLineAbove, isOwnLineAt, joinComments, rawCommentText, withCommentFields } from "./comments.js";
 import { enterNesting, exitNesting, hasMeta } from "./state.js";
 import { collectMultilineKey, collectMultilinePlainScalar, getScalarStyle, hasValueSepThroughPlainScalars, makeScalar, resolveScalar } from "./scalars.js";
 import { buildPairs, checkDuplicateKeys, checkMultilineImplicitKeys } from "./block.js";
@@ -117,8 +118,9 @@ function composeFlowMapInner(cst, state, meta, parentBlockColumn) {
 	validateFlowContentIndent(cst, state, parentBlockColumn);
 	validateFlowSeparators(children, state, "{", "}");
 	const items = flattenFlowChildren(children.filter((c) => !(c.type === "whitespace" && (c.source === "{" || c.source === "}" || c.source.trim() === ""))), state);
-	buildPairs(items, pairs, state.text);
+	const trailingComment = buildPairs(items, pairs, state.text);
 	if (state.options.uniqueKeys) checkDuplicateKeys(pairs, state);
+	const mapComment = meta?.comment !== void 0 ? trailingComment !== void 0 ? `${meta.comment}\n${trailingComment}` : meta.comment : trailingComment;
 	const map = new YamlMap({
 		items: pairs,
 		style: "flow",
@@ -126,7 +128,7 @@ function composeFlowMapInner(cst, state, meta, parentBlockColumn) {
 		length: cst.length,
 		...meta?.tag !== void 0 ? { tag: meta.tag } : {},
 		...meta?.anchor !== void 0 ? { anchor: meta.anchor } : {},
-		...meta?.comment !== void 0 ? { comment: meta.comment } : {}
+		...mapComment !== void 0 ? { comment: mapComment } : {}
 	});
 	if (meta?.anchor) registerAnchor(map, meta.anchor, state, cst.offset);
 	return map;
@@ -188,7 +190,8 @@ function flattenFlowChildren(children, state) {
 		if (child.type === "comment") {
 			items.push({
 				kind: "comment",
-				comment: child.source.startsWith("#") ? child.source.slice(1).trim() : child.source
+				comment: rawCommentText(child.source),
+				offset: child.offset
 			});
 			continue;
 		}
@@ -370,25 +373,95 @@ function composeFlowSeqInner(cst, state, meta, parentBlockColumn) {
 		current.push(child);
 	}
 	if (current.length > 0) segments.push(current);
+	let seqTrailing;
+	let pending = [];
+	let pendingSpace = false;
+	let lastItemEnd = -1;
+	let pushedIdx = -1;
+	const joinPending = (parts) => {
+		if (parts.length === 0) return void 0;
+		let out = parts[0].text;
+		for (let k = 1; k < parts.length; k++) {
+			const part = parts[k];
+			out += part.blankAbove ? `\n\n${part.text}` : `\n${part.text}`;
+		}
+		return out;
+	};
+	const blankIsBetweenItems = (anchorOffset) => blankLineAboveStart(state.text, anchorOffset) >= lastItemEnd;
+	const acceptOwnLineComment = (cText, cOff) => {
+		const blankAbove = cOff >= 0 && hasBlankLineAbove(state.text, cOff);
+		if (blankAbove && pending.length === 0 && lastItemEnd >= 0 && blankIsBetweenItems(cOff)) pendingSpace = true;
+		pending.push({
+			text: cText,
+			offset: cOff,
+			blankAbove: blankAbove && pending.length > 0
+		});
+	};
+	/** The pending comment fields for the item being pushed, then reset. */
+	const takePendingFields = (anchorOffset) => {
+		let commentBefore = joinPending(pending);
+		if (anchorOffset >= 0 && hasBlankLineAbove(state.text, anchorOffset)) {
+			if (commentBefore !== void 0) commentBefore = `${commentBefore}\n`;
+			else if (!pendingSpace && lastItemEnd >= 0 && blankIsBetweenItems(anchorOffset)) pendingSpace = true;
+		}
+		const fields = {
+			...commentBefore !== void 0 ? { commentBefore } : {},
+			...pendingSpace ? { spaceBefore: true } : {}
+		};
+		pending = [];
+		pendingSpace = false;
+		return fields;
+	};
+	const hasPendingFields = (fields) => fields.commentBefore !== void 0 || fields.spaceBefore === true;
 	for (const segment of segments) if (segment.some((c) => c.type === "whitespace" && c.source === ":")) {
-		const semItems = flattenFlowChildren(segment.filter((c) => !(c.type === "whitespace" && c.source.trim() === "")), state);
+		const content = segment.filter((c) => !(c.type === "whitespace" && c.source.trim() === ""));
+		const semItems = flattenFlowChildren(content, state);
 		const pairs = [];
-		buildPairs(semItems, pairs, state.text);
+		const segTrailing = buildPairs(semItems, pairs, state.text);
 		if (!segment.some((c) => c.type === "whitespace" && c.source === "?")) checkMultilineImplicitKeys(pairs, state, semItems);
 		const firstPair = pairs[0];
 		if (firstPair) {
+			const segFirst = content[0];
+			const fields = takePendingFields(segFirst !== void 0 ? segFirst.offset : -1);
 			const map = new YamlMap({
 				items: pairs,
 				style: "flow",
 				offset: firstPair.key.offset,
-				length: 0
+				length: 0,
+				...fields,
+				...segTrailing !== void 0 ? { comment: segTrailing } : {}
 			});
 			items.push(map);
-		}
+			pushedIdx = items.length - 1;
+			lastItemEnd = map.offset + map.length;
+		} else if (segTrailing !== void 0) seqTrailing = joinComments(seqTrailing, segTrailing);
 	} else {
 		const semItems = flattenFlowChildren(segment.filter((c) => !(c.type === "whitespace" && c.source.trim() === "")), state);
-		for (const si of semItems) if (si.kind === "node" && si.node) items.push(si.node);
+		for (const si of semItems) {
+			if (si.kind === "comment") {
+				const cText = si.comment ?? "";
+				if (!(si.offset === void 0 ? true : isOwnLineAt(state.text, si.offset)) && pushedIdx >= 0) {
+					const prev = items[pushedIdx];
+					if (prev) items[pushedIdx] = withCommentFields(prev, { comment: cText });
+				} else acceptOwnLineComment(cText, si.offset ?? -1);
+				continue;
+			}
+			if (si.kind === "node" && si.node) {
+				const fields = takePendingFields(si.node.length > 0 ? si.node.offset : -1);
+				const node = hasPendingFields(fields) ? withCommentFields(si.node, fields) : si.node;
+				items.push(node);
+				pushedIdx = items.length - 1;
+				lastItemEnd = si.node.offset + si.node.length;
+			}
+		}
+	}
+	if (pending.length > 0) {
+		const joined = joinPending(pending);
+		const first = pending[0];
+		const withLead = joined !== void 0 && first !== void 0 && lastItemEnd >= 0 && first.offset >= 0 && hasBlankLineAbove(state.text, first.offset) ? `\n${joined}` : joined;
+		if (withLead !== void 0) seqTrailing = joinComments(seqTrailing, withLead);
 	}
+	const seqComment = meta?.comment !== void 0 ? seqTrailing !== void 0 ? `${meta.comment}\n${seqTrailing}` : meta.comment : seqTrailing;
 	const seq = new YamlSeq({
 		items,
 		style: "flow",
@@ -396,7 +469,7 @@ function composeFlowSeqInner(cst, state, meta, parentBlockColumn) {
 		length: cst.length,
 		...meta?.tag !== void 0 ? { tag: meta.tag } : {},
 		...meta?.anchor !== void 0 ? { anchor: meta.anchor } : {},
-		...meta?.comment !== void 0 ? { comment: meta.comment } : {}
+		...seqComment !== void 0 ? { comment: seqComment } : {}
 	});
 	if (meta?.anchor) registerAnchor(seq, meta.anchor, state, cst.offset);
 	return seq;

package/internal/composer/scalars.js

@@ -1,5 +1,6 @@
 import { YamlScalar } from "../../YamlNode.js";
 import { registerAnchor } from "./anchors.js";
+import { rawCommentText } from "./comments.js";
 import { lineCol } from "./state.js";
 import { resolveTagHandle } from "./tags.js";
 
@@ -98,13 +99,42 @@ function getScalarStyle(node) {
 */
 function getBlockChomp(node) {
 	if (node.type !== "block-scalar") return void 0;
-	const src = node.source.trimStart();
-	const headerEnd = src.indexOf("\n");
-	const header = headerEnd === -1 ? src : src.slice(0, headerEnd);
-	if (header.includes("+")) return "keep";
-	if (header.includes("-")) return "strip";
+	const indicators = node.source.trimStart().match(/^[|>]([0-9+-]*)/)?.[1] ?? "";
+	if (indicators.includes("+")) return "keep";
+	if (indicators.includes("-")) return "strip";
 	return "clip";
 }
+/**
+* Extracts the EXPLICIT indentation-indicator digit from a block scalar's
+* header (`|2`, `>1+`), or undefined when the header carries none (the
+* reader auto-detects) or the node is not a block scalar. Inspects only the
+* indicator run — see {@link getBlockChomp} for why the rest of the header
+* line (a comment can contain digits) must not be read.
+*/
+function getBlockIndent(node) {
+	if (node.type !== "block-scalar") return void 0;
+	const digit = (node.source.trimStart().match(/^[|>]([0-9+-]*)/)?.[1] ?? "").match(/[1-9]/)?.[0];
+	return digit === void 0 ? void 0 : Number(digit);
+}
+/**
+* The trailing comment on a block scalar's HEADER line (`key: | # c`,
+* `- >-2 # c`) as stored raw-slice text, or `undefined` when the header
+* carries none. The header is the only line of a block scalar that can carry
+* a `#` comment — body lines absorb `#` as content — and the lexer packs the
+* whole scalar (header comment included) into one CST token, so the comment
+* never surfaces as a sibling comment token for the ordinary attribution
+* pass (#341).
+*/
+function blockScalarHeaderComment(cst) {
+	const src = cst.source.trimStart();
+	const nl = src.search(/[\r\n]/);
+	const header = nl < 0 ? src : src.slice(0, nl);
+	const hash = header.indexOf("#");
+	if (hash < 1) return void 0;
+	const before = header[hash - 1];
+	if (before !== " " && before !== "	") return void 0;
+	return rawCommentText(header.slice(hash));
+}
 function getScalarValue(node, fullText) {
 	if (node.type === "block-scalar") return decodeBlockScalar(node.source, fullText, node.offset);
 	const style = getScalarStyle(node);
@@ -790,18 +820,22 @@ function decodeBlockScalar(raw, fullText, nodeOffset) {
 		}
 		if (hadContent || trailingNewlines.length > 0) {
 			if (chomp === "keep") {
-				result += "\n";
+				if (hadContent) result += "\n";
 				for (const _nl of trailingNewlines) result += "\n";
-			} else if (chomp !== "strip") result += "\n";
+			} else if (chomp !== "strip") {
+				if (hadContent) result += "\n";
+			}
 		}
 		value = result;
 	} else {
 		value = lines.join("\n");
 		if (lines.length > 0 || trailingNewlines.length > 0) {
 			if (chomp === "keep") {
-				value += "\n";
+				if (lines.length > 0) value += "\n";
 				for (const _nl of trailingNewlines) value += "\n";
-			} else if (chomp !== "strip") value += "\n";
+			} else if (chomp !== "strip") {
+				if (lines.length > 0) value += "\n";
+			}
 		}
 	}
 	return value;
@@ -860,6 +894,8 @@ function makeScalar(cst, state, meta) {
 	const rawValue = getScalarValue(cst, state.text);
 	const value = resolveScalar(rawValue, style, meta?.tag, state);
 	const chomp = getBlockChomp(cst);
+	const blockIndent = getBlockIndent(cst);
+	const comment = (style === "block-literal" || style === "block-folded" ? blockScalarHeaderComment(cst) : void 0) ?? meta?.comment;
 	const needsRaw = style === "plain" && typeof value !== "string" && value !== void 0 && shouldPreserveRaw(rawValue, value);
 	const scalar = new YamlScalar({
 		value,
@@ -868,8 +904,9 @@ function makeScalar(cst, state, meta) {
 		length: cst.length,
 		...meta?.tag !== void 0 ? { tag: meta.tag } : {},
 		...meta?.anchor !== void 0 ? { anchor: meta.anchor } : {},
-		...meta?.comment !== void 0 ? { comment: meta.comment } : {},
+		...comment !== void 0 ? { comment } : {},
 		...chomp !== void 0 ? { chomp } : {},
+		...blockIndent !== void 0 ? { blockIndent } : {},
 		...needsRaw ? { raw: rawValue } : {}
 	});
 	if (meta?.anchor) registerAnchor(scalar, meta.anchor, state, cst.offset);
@@ -894,4 +931,4 @@ function shouldPreserveRaw(rawValue, value) {
 }
 
 //#endregion
-export { blockMapStartsWithValueSep, classifyPlainNumeric, collectMultilineKey, collectMultilinePlainScalar, findFirstContent, findLastContent, findNextContentChild, findNextContentInList, findNextSignificantChild, findValueSepOffset, foldFlowLines, getBlockChomp, getScalarStyle, getScalarValue, hasBlockMapAfterInList, hasValueSepAfter, hasValueSepAfterInList, hasValueSepBetween, hasValueSepThroughPlainScalars, indexOfChild, makeScalar, resolveScalar, shouldPreserveRaw };
+export { blockMapStartsWithValueSep, classifyPlainNumeric, collectMultilineKey, collectMultilinePlainScalar, findFirstContent, findLastContent, findNextContentChild, findNextContentInList, findNextSignificantChild, findValueSepOffset, foldFlowLines, getBlockChomp, getBlockIndent, getScalarStyle, getScalarValue, hasBlockMapAfterInList, hasValueSepAfter, hasValueSepAfterInList, hasValueSepBetween, hasValueSepThroughPlainScalars, indexOfChild, makeScalar, resolveScalar, shouldPreserveRaw };

package/internal/composer/state.js

@@ -63,6 +63,19 @@ function clearMeta(m) {
 	delete m.tag;
 	delete m.comment;
 }
+/**
+* The comment-fidelity field triple carried by the four public node classes
+* (and `YamlPair`). Conditional-spread helper so AST rebuild sites copy all
+* three without hand-maintaining the list — and never emit an explicit
+* `undefined` into a v4 `optionalKey` field.
+*/
+function commentProps(n) {
+	return {
+		...n.commentBefore !== void 0 ? { commentBefore: n.commentBefore } : {},
+		...n.comment !== void 0 ? { comment: n.comment } : {},
+		...n.spaceBefore !== void 0 ? { spaceBefore: n.spaceBefore } : {}
+	};
+}
 function createState(text, flow, options) {
 	return {
 		text,
@@ -77,7 +90,8 @@ function createState(text, flow, options) {
 		},
 		tagMap: /* @__PURE__ */ new Map(),
 		flow,
-		depth: 0
+		depth: 0,
+		escapedComments: []
 	};
 }
 /**
@@ -114,4 +128,4 @@ function exitNesting(state) {
 }
 
 //#endregion
-export { clearMeta, createState, enterNesting, exitNesting, getLineStarts, hasMeta, hasNonWhitespaceBeforeOnLine, lineCol, lineIndentColumn, sameLine };
+export { clearMeta, commentProps, createState, enterNesting, exitNesting, getLineStarts, hasMeta, hasNonWhitespaceBeforeOnLine, lineCol, lineIndentColumn, sameLine };

package/internal/cst-parser.js

@@ -365,7 +365,8 @@ function parseBlockValue(state, parentIndent, explicitKey = false) {
 		const token = peek(state);
 		if (!token) break;
 		if (token.kind === "whitespace") {
-			nodes.push(...consumeTrivia(state));
+			advance(state);
+			nodes.push(makeLeafNode("whitespace", token, state.text));
 			continue;
 		}
 		if (token.kind === "newline") break;

package/internal/diagnostics.js

@@ -43,14 +43,23 @@ const YAML_COMPOSE_ERROR_CODES = [
 */
 const YAML_STRINGIFY_ERROR_CODES = ["CircularReference"];
 /**
-* Error codes for the modify stage (`YamlFormat.modify`'s path navigation
-* against an already-composed AST). Not raised by the parser/composer.
+* Error codes for the modify stage (`YamlFormat.modify`'s guards and path
+* navigation against an already-composed AST). Not raised by the
+* parser/composer. `MultiDocumentStream` is the single-document-contract
+* refusal: `modify` re-emits exactly one document, so a multi-document
+* stream fails typed rather than silently truncating documents 2..n.
+* `DirectiveCarryingDocument` is the directive refusal: the stringifier does
+* not re-emit `%YAML`/`%TAG` directive lines, and re-emitting a document
+* without its `%TAG` orphans every shorthand tag that depends on it — the
+* output would be unparseable — so modify fails typed rather than corrupting.
 */
 const YAML_MODIFY_ERROR_CODES = [
 	"EmptyDocument",
 	"PathNotFound",
 	"InvalidIndex",
-	"NotNavigable"
+	"NotNavigable",
+	"MultiDocumentStream",
+	"DirectiveCarryingDocument"
 ];
 /**
 * The single source of truth for which diagnostic codes are fatal to a