@effected/yaml 0.7.0 → 0.9.0

package/internal/stringifier.js

@@ -29,6 +29,27 @@ var StringifyDepthExceeded = class extends Error {
 		this.name = "StringifyDepthExceeded";
 	}
 };
+/**
+* YAML 1.2 §8.1.3 caps an implicit block-mapping key: the `:` indicator must
+* appear at most 1024 characters after the start of the key. A key whose
+* RENDERED form (quotes and escapes count, the source scalar does not) is
+* longer than this must spill to explicit-key form (`? key` / `: value`) or
+* strict parsers reject the output. Matches the reference `yaml` package
+* (`stringifyPair`: `str.length > 1024`, block context only — flow contexts
+* never spill): a rendered key of exactly 1024 characters stays implicit.
+*/
+const IMPLICIT_KEY_MAX_LENGTH = 1024;
+/**
+* Continuation-line padding for explicit-key compact notation. Structurally
+* the width of the `? ` / `: ` indicators — two columns — and deliberately
+* NOT `ctx.indent`: compact continuation lines must align with the first
+* item, which always starts two columns in, so any other pad silently
+* re-nests (or corrupts) the value on reparse once `indent !== 2`. This is a
+* recorded divergence from the reference `yaml` package, which pads these
+* lines with the configured indent and emits output its own strict parser
+* misreads or rejects at indent ≠ 2.
+*/
+const EXPLICIT_COMPACT_PAD = "  ";
 const NULL_RE = /^(?:null|Null|NULL|~)$/;
 const TRUE_RE = /^(?:true|True|TRUE)$/;
 const FALSE_RE = /^(?:false|False|FALSE)$/;
@@ -176,7 +197,9 @@ function renderSingleQuoted(s) {
 * Block literal and block folded styles are always accepted for single-line
 * strings even though the output is unusual.
 */
-function renderString(s, style, indent, ignoreType = false, canonical = false, explicitChomp, parentPosition, quoteStyle = "single") {
+function renderString(s, style, indent, ignoreType = false, canonical = false, explicitChomp, parentPosition, quoteStyle = "single", explicitIndent) {
+	const fidelity = !canonical;
+	const fidelityIndent = fidelity ? explicitIndent : void 0;
 	if (s.includes("\n")) {
 		let hasControl = false;
 		for (let i = 0; i < s.length; i++) {
@@ -192,14 +215,14 @@ function renderString(s, style, indent, ignoreType = false, canonical = false, e
 			if (hasInteriorTrailingWhitespace(s)) return renderDoubleQuoted(s, canonical);
 			if (hasNewlineSpacesTab(s)) return renderDoubleQuoted(s, canonical);
 		}
-		if (style === "block-literal") return renderBlockLiteral(s, indent, explicitChomp, parentPosition);
-		if (style === "block-folded") return renderBlockFolded(s, indent);
+		if (style === "block-literal") return renderBlockLiteral(s, indent, explicitChomp, parentPosition, fidelity, fidelityIndent);
+		if (style === "block-folded") return renderBlockFolded(s, indent, fidelity ? explicitChomp : void 0, fidelityIndent);
 		if (style === "plain" || style === "single-quoted") {
 			if (canonical) {
 				const sq = renderSingleQuotedMultiline(s, indent);
 				if (sq !== null) return sq;
 			}
-			return renderBlockLiteral(s, indent, explicitChomp, parentPosition);
+			return renderBlockLiteral(s, indent, explicitChomp, parentPosition, fidelity, fidelityIndent);
 		}
 		return renderDoubleQuoted(s, canonical);
 	}
@@ -215,8 +238,8 @@ function renderString(s, style, indent, ignoreType = false, canonical = false, e
 			return s;
 		case "single-quoted": return renderSingleQuoted(s);
 		case "double-quoted": return renderDoubleQuoted(s, canonical);
-		case "block-literal": return renderBlockLiteral(s, indent, explicitChomp, parentPosition);
-		case "block-folded": return renderBlockFolded(s, indent);
+		case "block-literal": return renderBlockLiteral(s, indent, explicitChomp, parentPosition, fidelity, fidelityIndent);
+		case "block-folded": return renderBlockFolded(s, indent, fidelity ? explicitChomp : void 0, fidelityIndent);
 	}
 }
 /**
@@ -361,6 +384,18 @@ function stringifyObjectLines(obj, ctx, depth) {
 		const keyStr = renderKey(k);
 		const val = obj[k];
 		const valLines = stringifyLines(val, ctx, depth + 1);
+		if (keyStr.length > IMPLICIT_KEY_MAX_LENGTH) {
+			lines.push(`? ${keyStr}`);
+			if (valLines.length === 1) lines.push(`: ${valLines[0]}`);
+			else if (valLines[0].startsWith("|") || valLines[0].startsWith(">") || typeof val === "string") {
+				lines.push(`: ${valLines[0]}`);
+				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+			} else {
+				lines.push(`: ${valLines[0]}`);
+				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i] === "" ? valLines[i] : `${EXPLICIT_COMPACT_PAD}${valLines[i]}`);
+			}
+			continue;
+		}
 		if (valLines.length === 1 && !isBlockCollection(val, ctx)) lines.push(`${keyStr}: ${valLines[0]}`);
 		else {
 			const first = valLines[0];
@@ -439,8 +474,11 @@ function normalizeNodeTags(node, tagMap) {
 		style: node.style,
 		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
 		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.commentBefore !== void 0 ? { commentBefore: node.commentBefore } : {},
 		...node.comment !== void 0 ? { comment: node.comment } : {},
+		...node.spaceBefore !== void 0 ? { spaceBefore: node.spaceBefore } : {},
 		...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,
@@ -449,13 +487,14 @@ function normalizeNodeTags(node, tagMap) {
 	if (node instanceof YamlMap) return new YamlMap({
 		items: node.items.map((pair) => new YamlPair({
 			key: normalizeNodeTags(pair.key, tagMap),
-			value: pair.value ? normalizeNodeTags(pair.value, tagMap) : null,
-			...pair.comment !== void 0 ? { comment: pair.comment } : {}
+			value: pair.value ? normalizeNodeTags(pair.value, tagMap) : null
 		})),
 		style: node.style,
 		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
 		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.commentBefore !== void 0 ? { commentBefore: node.commentBefore } : {},
 		...node.comment !== void 0 ? { comment: node.comment } : {},
+		...node.spaceBefore !== void 0 ? { spaceBefore: node.spaceBefore } : {},
 		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
 		offset: node.offset,
 		length: node.length
@@ -465,7 +504,9 @@ function normalizeNodeTags(node, tagMap) {
 		style: node.style,
 		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
 		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.commentBefore !== void 0 ? { commentBefore: node.commentBefore } : {},
 		...node.comment !== void 0 ? { comment: node.comment } : {},
+		...node.spaceBefore !== void 0 ? { spaceBefore: node.spaceBefore } : {},
 		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
 		offset: node.offset,
 		length: node.length
@@ -483,6 +524,7 @@ function stripNodeComments(node) {
 		...node.tag !== void 0 ? { tag: node.tag } : {},
 		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
 		...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,
@@ -542,7 +584,7 @@ function stringifyScalarNodeLines(node, ctx) {
 		else lines = ["null"];
 	} else if (typeof val === "boolean") lines = [val ? "true" : "false"];
 	else if (typeof val === "number") lines = [node.raw !== void 0 ? node.raw : renderNumber(val)];
-	else if (typeof val === "string") lines = renderString(val, style, " ".repeat(ctx.indent), !!node.tag, ctx.forceDefaultStyles, node.chomp, ctx.parentPosition, ctx.quoteStyle).split("\n");
+	else if (typeof val === "string") lines = renderString(val, style, " ".repeat(ctx.indent), !!node.tag, ctx.forceDefaultStyles, node.chomp, ctx.parentPosition, ctx.quoteStyle, node.blockIndent).split("\n");
 	else lines = [renderDoubleQuoted(String(val))];
 	if (node.tag) lines[0] = `${node.tag} ${lines[0]}`;
 	if (node.anchor) lines[0] = `&${node.anchor} ${lines[0]}`;
@@ -582,6 +624,138 @@ function stringifyMappingKeyLines(node, ctx, depth) {
 	return stringifyNodeLines(node, ctx, depth);
 }
 /**
+* Undo the capture-side escape on one stored comment line: a spaces-only
+* slice was stored with one extra trailing space so it cannot collide with
+* `""`, the embedded-blank-line encoding (see `rawCommentText`).
+*/
+function unescapeCommentLine(line) {
+	return /^ +$/.test(line) ? line.slice(0, -1) : line;
+}
+/**
+* Render a stored comment block, one output line per stored line. Stored
+* text is the RAW post-`#` slice (reference parity) with spaces-only lines
+* carrying one escape space: `""` is an embedded blank line; any other line
+* renders as `#` + the unescaped slice (`" "` → `#`, `"  "` → `# `).
+*/
+function commentBlockLines(comment) {
+	return comment.split("\n").map((l) => l === "" ? "" : `#${unescapeCommentLine(l)}`);
+}
+/**
+* Splice a trailing comment onto the FIRST line of an already-rendered node —
+* for a block scalar, the header line, which is the one line of the scalar
+* that legally carries a `#` comment.
+*/
+function withHeaderComment(rendered, comment) {
+	const nl = rendered.indexOf("\n");
+	return nl === -1 ? `${rendered}${renderTrailingComment(comment)}` : `${rendered.slice(0, nl)}${renderTrailingComment(comment)}${rendered.slice(nl)}`;
+}
+/**
+* The leading comment block of a mapping entry. Under the node-level comment
+* model it lives on the entry's KEY node, not on the pair.
+*/
+function pairLeading(pair) {
+	return pair.key.commentBefore;
+}
+/**
+* The trailing comment of a mapping entry: it belongs to whichever node owns
+* the entry's last line — the value when there is one, otherwise the key. For
+* a block-scalar value that line is the HEADER line, which is why a block
+* scalar's header comment needs no separate concept.
+*/
+function pairTrailing(pair) {
+	return (pair.value ?? pair.key).comment;
+}
+/** True when a blank line preceded the entry (recorded on its KEY node). */
+function pairSpaceBefore(pair) {
+	return pair.key.spaceBefore;
+}
+/**
+* The trailing comment to place on an entry's own line, given how its value
+* actually rendered.
+*
+* A collection's `comment` field carries its TERMINAL comment run — the
+* own-line comments after its last entry — and the collection emits those
+* itself, after that last entry. Only when the collection renders on a single
+* line (inline flow, `a: {b: 1} # t`) is its `comment` the entry's trailing
+* comment. Reading it unconditionally emits the same comment twice: once on
+* the entry's line and again as the terminal run.
+*/
+function entryTrailing(pair, ctx) {
+	if (pair.key.comment !== void 0) return pair.key.comment;
+	const owner = pair.value ?? pair.key;
+	if (rendersAcrossLines(owner, ctx)) return void 0;
+	return owner.comment;
+}
+/**
+* True when `node` renders across more than one line, so its own `comment` is
+* a terminal run rather than something that can sit on the entry's line.
+*/
+function rendersAcrossLines(node, ctx) {
+	if (!(node instanceof YamlMap || node instanceof YamlSeq)) return false;
+	if (node.items.length === 0) return false;
+	if ((ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : node.style ?? ctx.defaultCollectionStyle) === "block" || node.sourceMultiline === true) return true;
+	if (ctx.forceDefaultStyles) return false;
+	return node instanceof YamlMap ? node.items.some((p) => pairLeading(p) !== void 0 || (p.value ?? p.key).comment !== void 0 || pairSpaceBefore(p) === true) : node.items.some((item) => item.commentBefore !== void 0 || item.comment !== void 0 || item.spaceBefore === true);
+}
+/** Render a trailing comment for appending after content on the same line. */
+function renderTrailingComment(comment) {
+	return ` #${comment.split("\n").map(unescapeCommentLine).join(" ")}`;
+}
+/**
+* Emits the `: value` line(s) of an explicit-key block-mapping entry, in
+* compact notation where the value admits it (first line on the colon line,
+* continuation lines indented to align). Shared by the complex-key branch and
+* the implicit-key length spill; `indentSequences` deliberately does not reach
+* this branch (sequence values always align compactly under `: `).
+*
+* Returns the `lines` index that can safely carry the pair's trailing
+* comment (the line where an inline value ends), or `-1` when no line is
+* safe (a compact block collection or a block-scalar header).
+*/
+function pushExplicitKeyValueLines(lines, valNode, ctx, depth, pad) {
+	if (!valNode) {
+		lines.push(":");
+		return lines.length - 1;
+	}
+	const valLines = stringifyNodeLines(valNode, ctx, depth + 1);
+	const valueLeading = !ctx.forceDefaultStyles ? valNode.commentBefore : void 0;
+	if (valueLeading !== void 0) {
+		const colonIdx = lines.length;
+		lines.push(":");
+		for (const cl of commentBlockLines(valueLeading)) lines.push(cl === "" ? "" : `${pad}${cl}`);
+		for (const vl of valLines) lines.push(vl === "" ? "" : `${pad}${vl}`);
+		return colonIdx;
+	}
+	if (valLines.length === 1) {
+		lines.push(`: ${valLines[0]}`);
+		return lines.length - 1;
+	}
+	const first = valLines[0];
+	const firstStripped = stripScalarMetadataPrefix(first);
+	const isBlockScalarHeader = firstStripped.startsWith("|") || firstStripped.startsWith(">");
+	const isInlineQuoted = valNode instanceof YamlScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""));
+	if (isBlockScalarHeader || isInlineQuoted) {
+		const headerIdx = lines.length;
+		lines.push(`: ${first}`);
+		for (let v = 1; v < valLines.length; v++) lines.push(valLines[v]);
+		return isBlockScalarHeader ? headerIdx : lines.length - 1;
+	}
+	if (first.startsWith("-")) {
+		lines.push(`: ${first}`);
+		for (let v = 1; v < valLines.length; v++) lines.push(valLines[v] === "" ? "" : `${EXPLICIT_COMPACT_PAD}${valLines[v]}`);
+		return -1;
+	}
+	if (valNode instanceof YamlMap && valNode.items.length > 0 && (ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : valNode.style ?? ctx.defaultCollectionStyle) === "block") {
+		lines.push(`: ${first}`);
+		for (let v = 1; v < valLines.length; v++) lines.push(valLines[v] === "" ? "" : `${EXPLICIT_COMPACT_PAD}${valLines[v]}`);
+		return -1;
+	}
+	const colonIdx = lines.length;
+	lines.push(":");
+	for (const vl of valLines) lines.push(vl === "" ? "" : `${pad}${vl}`);
+	return colonIdx;
+}
+/**
 * Stringifies a YamlMap node into lines, using the node's collection style.
 */
 function stringifyMapNodeLines(node, ctx, depth) {
@@ -599,56 +773,73 @@ function stringifyMapNodeLines(node, ctx, depth) {
 		return [line];
 	}
 	if (style === "flow") {
+		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
+		if (!ctx.forceDefaultStyles && (items.some((p) => pairLeading(p) !== void 0 || pairTrailing(p) !== void 0 || pairSpaceBefore(p) === true) || node.comment !== void 0 && node.sourceMultiline === true)) {
+			const flowPad = " ".repeat(ctx.indent);
+			const flowLines = [flowPrefix ? `${flowPrefix} {` : "{"];
+			for (let fi = 0; fi < items.length; fi++) {
+				const pair = items[fi];
+				if (pairSpaceBefore(pair) === true) flowLines.push("");
+				const flowLeading = pairLeading(pair);
+				if (flowLeading !== void 0) for (const cl of commentBlockLines(flowLeading)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
+				const keyStr = pair.key ? stringifyMappingKeyLines(pair.key, ctx, depth + 1).join(" ") : "null";
+				const valStr = pair.value ? stringifyNodeLines(pair.value, ctx, depth + 1).join(" ") : "null";
+				const comma = fi < items.length - 1 ? "," : "";
+				const flowTrailing = pairTrailing(pair);
+				const trailing = flowTrailing !== void 0 ? renderTrailingComment(flowTrailing) : "";
+				flowLines.push(`${flowPad}${keyStr}: ${valStr}${comma}${trailing}`);
+			}
+			if (node.comment !== void 0) for (const cl of commentBlockLines(node.comment)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
+			flowLines.push("}");
+			return flowLines;
+		}
 		let line = `{${items.map((pair) => {
 			return `${pair.key ? stringifyMappingKeyLines(pair.key, ctx, depth + 1).join(" ") : "null"}: ${pair.value ? stringifyNodeLines(pair.value, ctx, depth + 1).join(" ") : "null"}`;
 		}).join(", ")}}`;
-		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
 		if (flowPrefix) line = `${flowPrefix} ${line}`;
 		return [line];
 	}
 	const pad = " ".repeat(ctx.indent);
+	const emitComments = !ctx.forceDefaultStyles;
 	const lines = [];
+	/** Append a pair's trailing comment to `lines[idx]` (flattened to one line); `-1` drops it. */
+	const appendTrailing = (idx, comment) => {
+		if (!emitComments || comment === void 0 || idx < 0 || idx >= lines.length) return;
+		lines[idx] = `${lines[idx]}${renderTrailingComment(comment)}`;
+	};
+	/** A value node's own leading comment block, or undefined. */
+	const valueLeading = (valNode) => emitComments ? valNode.commentBefore : void 0;
 	for (const pair of items) {
+		if (emitComments && pairSpaceBefore(pair) === true) lines.push("");
+		const leading = emitComments ? pairLeading(pair) : void 0;
+		const keyOwnComment = emitComments ? pair.key.comment : void 0;
+		const valueOwnComment = emitComments && pair.value !== null ? pair.value.comment : void 0;
+		if (leading !== void 0) for (const cl of commentBlockLines(leading)) lines.push(cl);
 		const keyIsScalarWithNewline = pair.key instanceof YamlScalar && (typeof pair.key.value === "string" && pair.key.value.includes("\n") || pair.key.style === "block-literal" || pair.key.style === "block-folded");
 		if ((pair.key instanceof YamlMap || pair.key instanceof YamlSeq) && pair.key.items.length > 0 || keyIsScalarWithNewline) {
 			const keyLines = stringifyNodeLines(pair.key, ctx, depth + 1);
 			lines.push(`? ${keyLines[0]}`);
+			const explicitKeyLineIdx = lines.length - 1;
 			const firstTokens = keyLines[0].trim().split(/\s+/).filter(Boolean);
 			const firstIsMetaOnly = firstTokens.length > 0 && firstTokens.every((t) => t.startsWith("&") || t.startsWith("!"));
 			const keyIsBlockScalar = pair.key instanceof YamlScalar && (pair.key.style === "block-literal" || pair.key.style === "block-folded");
-			const contPad = firstIsMetaOnly || keyIsBlockScalar ? "" : pad;
+			const contPad = firstIsMetaOnly || keyIsBlockScalar ? "" : EXPLICIT_COMPACT_PAD;
 			for (let k = 1; k < keyLines.length; k++) lines.push(`${contPad}${keyLines[k]}`);
-			const valNode = pair.value;
-			if (!valNode) lines.push(":");
-			else {
-				const valLines = stringifyNodeLines(valNode, ctx, depth + 1);
-				if (valLines.length === 1) lines.push(`: ${valLines[0]}`);
-				else {
-					const first = valLines[0];
-					const firstStripped = stripScalarMetadataPrefix(first);
-					const isBlockScalarHeader = firstStripped.startsWith("|") || firstStripped.startsWith(">");
-					const isInlineQuoted = valNode instanceof YamlScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""));
-					if (isBlockScalarHeader || isInlineQuoted) {
-						lines.push(`: ${first}`);
-						for (let v = 1; v < valLines.length; v++) lines.push(valLines[v]);
-					} else if (first.startsWith("-")) {
-						lines.push(`: ${first}`);
-						for (let v = 1; v < valLines.length; v++) lines.push(`${pad}${valLines[v]}`);
-					} else if (valNode instanceof YamlMap && valNode.items.length > 0 && (ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : valNode.style ?? ctx.defaultCollectionStyle) === "block") {
-						lines.push(`: ${first}`);
-						for (let v = 1; v < valLines.length; v++) lines.push(`${pad}${valLines[v]}`);
-					} else {
-						lines.push(":");
-						for (const vl of valLines) lines.push(`${pad}${vl}`);
-					}
-				}
-			}
+			const inlineIdx = pushExplicitKeyValueLines(lines, pair.value, ctx, depth, pad);
+			appendTrailing(inlineIdx >= 0 ? inlineIdx : keyLines.length === 1 ? explicitKeyLineIdx : -1, entryTrailing(pair, ctx));
 			continue;
 		}
 		let resolvedKeyStr;
 		if (ctx.forceDefaultStyles && node.style === "flow" && node.sourceMultiline !== true && pair.key instanceof YamlScalar && (pair.key.style === "single-quoted" || pair.key.style === "double-quoted") && typeof pair.key.value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(pair.key.value)) resolvedKeyStr = pair.key.value;
 		else resolvedKeyStr = pair.key ? stringifyMappingKeyLines(pair.key, ctx, depth + 1).join(" ") : "null";
 		const keyStr = resolvedKeyStr;
+		if (keyStr.length > IMPLICIT_KEY_MAX_LENGTH) {
+			lines.push(`? ${keyStr}`);
+			const spillKeyLineIdx = lines.length - 1;
+			const inlineIdx = pushExplicitKeyValueLines(lines, pair.value, ctx, depth, pad);
+			appendTrailing(inlineIdx >= 0 ? inlineIdx : spillKeyLineIdx, entryTrailing(pair, ctx));
+			continue;
+		}
 		const keyIsAnchoredOrTaggedEmpty = pair.key instanceof YamlScalar && pair.key.length === 0 && (pair.key.value === null || pair.key.value === void 0 || pair.key.value === "") && (pair.key.anchor !== void 0 || pair.key.tag !== void 0);
 		const sep = pair.key instanceof YamlAlias || keyIsAnchoredOrTaggedEmpty ? " :" : ":";
 		const valNode = pair.value;
@@ -658,16 +849,20 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			const isRootFlowMap = ctx.parentPosition === void 0 && node.style === "flow" && node.sourceMultiline === true;
 			if (ctx.forceDefaultStyles && isRootFlowMap && isPlainKey && keyIsNonEmpty) lines.push(`${keyStr}${sep} null`);
 			else lines.push(`${keyStr}${sep}`);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 			continue;
 		}
 		const valLines = stringifyNodeLines(valNode, {
 			...ctx,
 			parentPosition: "block-map-value"
 		}, depth + 1);
+		const valLeading = valueLeading(valNode);
 		if (valNode instanceof YamlSeq && valNode.items.length > 0 && (ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : valNode.style ?? ctx.defaultCollectionStyle) === "block") {
 			const seqMeta = buildMetadataPrefix(valNode.tag, valNode.anchor);
 			const startIdx = seqMeta ? 1 : 0;
 			lines.push(seqMeta ? `${keyStr}${sep} ${seqMeta}` : `${keyStr}${sep}`);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
+			if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(ctx.indentSequences ? `${pad}${cl}` : cl);
 			for (let i = startIdx; i < valLines.length; i++) {
 				const vl = valLines[i];
 				lines.push(ctx.indentSequences && vl !== "" ? `${pad}${vl}` : vl);
@@ -676,28 +871,64 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			const mapMeta = buildMetadataPrefix(valNode.tag, valNode.anchor);
 			const startIdx = mapMeta ? 1 : 0;
 			lines.push(mapMeta ? `${keyStr}${sep} ${mapMeta}` : `${keyStr}${sep}`);
-			for (let i = startIdx; i < valLines.length; i++) lines.push(`${pad}${valLines[i]}`);
-		} else if (valLines.length === 1) lines.push(valLines[0] === "" ? `${keyStr}${sep}` : `${keyStr}${sep} ${valLines[0]}`);
-		else {
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
+			if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
+			for (let i = startIdx; i < valLines.length; i++) lines.push(valLines[i] === "" ? "" : `${pad}${valLines[i]}`);
+		} else if (valLines.length === 1 && (valLeading !== void 0 || keyOwnComment !== void 0)) {
+			lines.push(`${keyStr}${sep}`);
+			appendTrailing(lines.length - 1, keyOwnComment);
+			if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
+			lines.push(valLines[0] === "" ? "" : `${pad}${valLines[0]}`);
+			appendTrailing(lines.length - 1, valueOwnComment);
+		} else if (valLines.length === 1) {
+			lines.push(valLines[0] === "" ? `${keyStr}${sep}` : `${keyStr}${sep} ${valLines[0]}`);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
+		} else {
 			const first = valLines[0];
 			const firstStripped = stripScalarMetadataPrefix(first);
 			const isBlockScalarHeader = firstStripped.startsWith("|") || firstStripped.startsWith(">");
 			const isInlineQuoted = valNode instanceof YamlScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""));
 			if (isBlockScalarHeader || isInlineQuoted) {
+				if (valLeading !== void 0) {
+					lines.push(`${keyStr}${sep}`);
+					for (const cl of commentBlockLines(valLeading)) lines.push(cl === "" ? "" : `${pad}${cl}`);
+					const spilledIdx = lines.length;
+					lines.push(`${pad}${first}`);
+					for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+					appendTrailing(isBlockScalarHeader ? spilledIdx : lines.length - 1, entryTrailing(pair, ctx));
+					continue;
+				}
+				const keyComment = !ctx.forceDefaultStyles ? pair.key.comment : void 0;
+				const scalarComment = isBlockScalarHeader && valNode instanceof YamlScalar ? valNode.comment : void 0;
+				if (keyComment !== void 0 && scalarComment !== void 0) {
+					lines.push(`${keyStr}${sep}`);
+					appendTrailing(lines.length - 1, keyComment);
+					const spilledIdx = lines.length;
+					lines.push(`${pad}${first}`);
+					for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+					appendTrailing(spilledIdx, scalarComment);
+					continue;
+				}
+				const headerIdx = lines.length;
 				lines.push(`${keyStr}${sep} ${first}`);
 				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+				appendTrailing(isBlockScalarHeader ? headerIdx : lines.length - 1, entryTrailing(pair, ctx));
 			} else {
 				const mapMeta = valNode instanceof YamlMap && (ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : valNode.style ?? ctx.defaultCollectionStyle) === "block" ? buildMetadataPrefix(valNode.tag, valNode.anchor) : void 0;
 				if (mapMeta) {
 					lines.push(`${keyStr}${sep} ${mapMeta}`);
-					for (let i = 1; i < valLines.length; i++) lines.push(`${pad}${valLines[i]}`);
+					appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
+					for (let i = 1; i < valLines.length; i++) lines.push(valLines[i] === "" ? "" : `${pad}${valLines[i]}`);
 				} else {
 					lines.push(`${keyStr}${sep}`);
-					for (const vl of valLines) lines.push(`${pad}${vl}`);
+					appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
+					if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
+					for (const vl of valLines) lines.push(vl === "" ? "" : `${pad}${vl}`);
 				}
 			}
 		}
 	}
+	if (emitComments && node.comment !== void 0) for (const cl of commentBlockLines(node.comment)) lines.push(cl);
 	const prefix = buildMetadataPrefix(node.tag, node.anchor);
 	if (prefix) lines.unshift(prefix);
 	return lines;
@@ -744,9 +975,32 @@ function stringifySeqNodeLines(node, ctx, depth) {
 		if (emptyPrefix) line = `${emptyPrefix} ${line}`;
 		return [line];
 	}
+	const emitComments = !ctx.forceDefaultStyles;
+	const itemFields = (item) => {
+		if (!emitComments) return void 0;
+		if (item.commentBefore === void 0 && item.comment === void 0 && item.spaceBefore !== true) return void 0;
+		return item;
+	};
 	if (style === "flow") {
-		let line = `[${items.map((item) => stringifyNodeLines(item, ctx, depth + 1).join(" ")).join(", ")}]`;
 		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
+		if (emitComments && (items.some((it) => itemFields(it) !== void 0) || node.comment !== void 0 && node.sourceMultiline === true)) {
+			const flowPad = " ".repeat(ctx.indent);
+			const flowLines = [flowPrefix ? `${flowPrefix} [` : "["];
+			for (let fi = 0; fi < items.length; fi++) {
+				const item = items[fi];
+				const fields = itemFields(item);
+				if (fields?.spaceBefore === true) flowLines.push("");
+				if (fields?.commentBefore !== void 0) for (const cl of commentBlockLines(fields.commentBefore)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
+				const itemStr = stringifyNodeLines(item, ctx, depth + 1).join(" ");
+				const comma = fi < items.length - 1 ? "," : "";
+				const trailing = fields?.comment !== void 0 ? renderTrailingComment(fields.comment) : "";
+				flowLines.push(`${flowPad}${itemStr}${comma}${trailing}`);
+			}
+			if (node.comment !== void 0) for (const cl of commentBlockLines(node.comment)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
+			flowLines.push("]");
+			return flowLines;
+		}
+		let line = `[${items.map((item) => stringifyNodeLines(item, ctx, depth + 1).join(" ")).join(", ")}]`;
 		if (flowPrefix) line = `${flowPrefix} ${line}`;
 		return [line];
 	}
@@ -757,21 +1011,37 @@ function stringifySeqNodeLines(node, ctx, depth) {
 		parentPosition: "block-seq-item"
 	};
 	for (const item of items) {
+		const fields = itemFields(item);
+		if (fields?.spaceBefore === true) lines.push("");
+		if (fields?.commentBefore !== void 0) for (const cl of commentBlockLines(fields.commentBefore)) lines.push(cl);
+		/** Append the item's trailing comment to `lines[idx]`; `-1` drops it. */
+		const appendItemTrailing = (idx) => {
+			if (fields?.comment === void 0 || idx < 0 || idx >= lines.length) return;
+			lines[idx] = `${lines[idx]}${renderTrailingComment(fields.comment)}`;
+		};
 		const itemLines = stringifyNodeLines(item, itemCtx, depth + 1);
-		if (itemLines.length === 1) lines.push(itemLines[0] === "" ? "-" : `- ${itemLines[0]}`);
-		else {
+		if (itemLines.length === 1) {
+			lines.push(itemLines[0] === "" ? "-" : `- ${itemLines[0]}`);
+			appendItemTrailing(lines.length - 1);
+		} else {
 			const first = itemLines[0];
 			const firstStripped = stripScalarMetadataPrefix(first);
 			const itemIsScalar = item instanceof YamlScalar;
-			if (firstStripped.startsWith("|") || firstStripped.startsWith(">") || itemIsScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""))) {
+			const isBlockScalarHeader = firstStripped.startsWith("|") || firstStripped.startsWith(">");
+			if (isBlockScalarHeader || itemIsScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""))) {
+				const headerIdx = lines.length;
 				lines.push(`- ${first}`);
 				for (let i = 1; i < itemLines.length; i++) lines.push(itemLines[i]);
+				appendItemTrailing(isBlockScalarHeader ? headerIdx : lines.length - 1);
 			} else {
 				lines.push(first === "" ? "-" : `- ${first}`);
-				for (let i = 1; i < itemLines.length; i++) lines.push(`${pad}${itemLines[i]}`);
+				const dashLineIdx = lines.length - 1;
+				for (let i = 1; i < itemLines.length; i++) lines.push(itemLines[i] === "" ? "" : `${pad}${itemLines[i]}`);
+				appendItemTrailing(dashLineIdx);
 			}
 		}
 	}
+	if (emitComments && node.comment !== void 0) for (const cl of commentBlockLines(node.comment)) lines.push(cl);
 	const prefix = buildMetadataPrefix(node.tag, node.anchor);
 	if (prefix) lines.unshift(prefix);
 	return lines;
@@ -799,7 +1069,8 @@ function stringifyDocument(doc, options) {
 	const ctx = createContext(options);
 	const finalNewline = options?.finalNewline ?? true;
 	let contents = doc.contents;
-	const docComment = ctx.forceDefaultStyles ? void 0 : doc.comment;
+	const docCommentRaw = ctx.forceDefaultStyles ? void 0 : doc.commentBefore;
+	const docComment = docCommentRaw !== void 0 ? commentBlockLines(docCommentRaw).join("\n") : void 0;
 	if (ctx.forceDefaultStyles && contents) {
 		contents = stripNodeComments(contents);
 		const tagMap = buildTagMap(doc.directives);
@@ -810,16 +1081,31 @@ function stringifyDocument(doc, options) {
 			if (doc.hasDocumentStart) return `---\n${doc.hasDocumentEnd ? "...\n" : ""}`;
 			return "";
 		}
+		if (docComment !== void 0 || doc.comment !== void 0 || doc.hasDocumentStart === true || doc.hasDocumentEnd === true) {
+			const parts = [];
+			if (docComment !== void 0) parts.push(`${docComment}\n`);
+			if (doc.hasDocumentStart) parts.push("---\n");
+			if (doc.hasDocumentEnd) parts.push("...\n");
+			if (doc.comment !== void 0) parts.push(`${commentBlockLines(doc.comment).join("\n")}\n`);
+			const out = parts.join("");
+			return finalNewline ? out : out.replace(/\n$/, "");
+		}
 		return finalNewline ? "null\n" : "null";
 	}
 	const result = stringifyNodeLines(contents, ctx, 0).join("\n");
-	const body = finalNewline ? `${result}\n` : result;
+	const rootHeaderComment = !ctx.forceDefaultStyles && contents instanceof YamlScalar && (contents.style === "block-literal" || contents.style === "block-folded") ? contents.comment : void 0;
+	const rendered = rootHeaderComment === void 0 ? result : withHeaderComment(result, rootHeaderComment);
 	const needsTerminatorForKeepChomp = ctx.forceDefaultStyles && endsWithKeepChomp(result);
 	const needsTerminatorForAnchoredPlainScalar = ctx.forceDefaultStyles && doc.hasDocumentStart && contents instanceof YamlScalar && contents.style === "plain" && contents.anchor !== void 0 && !contents.tag;
 	const looksLikeDirectiveContinuation = contents instanceof YamlScalar && typeof contents.value === "string" && / %[A-Z]/.test(contents.value);
 	const needsTerminatorForMultilinePlainScalar = ctx.forceDefaultStyles && doc.hasDocumentStart && contents instanceof YamlScalar && contents.style === "plain" && contents.sourceMultiline === true && looksLikeDirectiveContinuation;
 	const needsTerminatorForDocStartTab = ctx.forceDefaultStyles && doc.hasDocumentStartTab === true;
-	const docEnd = doc.hasDocumentEnd || needsTerminatorForKeepChomp || needsTerminatorForAnchoredPlainScalar || needsTerminatorForMultilinePlainScalar || needsTerminatorForDocStartTab ? "...\n" : "";
+	const docEndMarker = doc.hasDocumentEnd || needsTerminatorForKeepChomp || needsTerminatorForAnchoredPlainScalar || needsTerminatorForMultilinePlainScalar || needsTerminatorForDocStartTab ? "...\n" : "";
+	const docCommentAfter = ctx.forceDefaultStyles || doc.comment === void 0 ? void 0 : commentBlockLines(doc.comment).join("\n");
+	const docEndFull = docCommentAfter !== void 0 ? `${docEndMarker}${docCommentAfter}\n` : docEndMarker;
+	const body = finalNewline || docEndFull !== "" ? `${rendered}\n` : rendered;
+	const docEnd = finalNewline || docEndFull === "" ? docEndFull : docEndFull.replace(/\n$/, "");
+	const rootLeading = !ctx.forceDefaultStyles && contents !== null && contents.commentBefore !== void 0 ? `${commentBlockLines(contents.commentBefore).join("\n")}\n` : "";
 	if (doc.hasDocumentStart) {
 		const rootTag = contents && "tag" in contents ? contents.tag : void 0;
 		const rootAnchor = contents && "anchor" in contents ? contents.anchor : void 0;
@@ -836,13 +1122,15 @@ function stringifyDocument(doc, options) {
 			if (bodyClean.startsWith(metaLinePrefix)) bodyClean = bodyClean.slice(metaLinePrefix.length);
 			else if (bodyClean.startsWith(metaInlinePrefix)) bodyClean = bodyClean.slice(metaInlinePrefix.length);
 			const docStart = `--- ${metaStr}`;
-			const sep = isCollection ? "\n" : " ";
-			return docComment ? `# ${docComment}\n${docStart}${sep}${bodyClean}${docEnd}` : `${docStart}${sep}${bodyClean}${docEnd}`;
+			const metaBody = rootLeading === "" ? `${isCollection ? "\n" : " "}${bodyClean}` : `\n${rootLeading}${bodyClean}`;
+			return docComment ? `${docComment}\n${docStart}${metaBody}${docEnd}` : `${docStart}${metaBody}${docEnd}`;
 		}
-		if (isScalar) return docComment ? `# ${docComment}\n--- ${body}${docEnd}` : `--- ${body}${docEnd}`;
-		return docComment ? `# ${docComment}\n---\n${body}${docEnd}` : `---\n${body}${docEnd}`;
+		if (isScalar && rootLeading === "") return docComment ? `${docComment}\n--- ${body}${docEnd}` : `--- ${body}${docEnd}`;
+		const afterMarker = `---\n${rootLeading}${body}${docEnd}`;
+		return docComment ? `${docComment}\n${afterMarker}` : afterMarker;
 	}
-	return docComment ? `# ${docComment}\n${body}${docEnd}` : `${body}${docEnd}`;
+	const plain = `${rootLeading}${body}${docEnd}`;
+	return docComment ? `${docComment}\n${plain}` : plain;
 }
 
 //#endregion

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.7.0",
+	"version": "0.9.0",
 	"private": false,
-	"description": "Zero-dependency YAML parsing, editing and formatting as Effect schemas.",
+	"description": "Zero-dependency YAML parsing, editing, formatting and linting as Effect schemas.",
 	"keywords": [
 		"yaml",
 		"parser",
@@ -12,6 +12,7 @@
 		"cst",
 		"editing",
 		"formatting",
+		"linting",
 		"effected"
 	],
 	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/yaml#readme",