@effected/yaml 0.1.0

package/internal/stringifier.js

@@ -0,0 +1,797 @@
+import { YamlAlias, YamlMap, YamlPair, YamlScalar, YamlSeq } from "../YamlNode.js";
+import { hasInteriorTrailingWhitespace, hasNewlineSpacesTab, isControlChar, renderBlockFolded, renderBlockLiteral, renderSingleQuotedMultiline } from "./fold.js";
+
+//#region src/internal/stringifier.ts
+/**
+* Thrown by the stringifier on its failure paths (circular references). The
+* facade catches this and materializes the public stringify error.
+*/
+var StringifyFailure = class extends Error {
+	reason;
+	constructor(reason) {
+		super(reason);
+		this.name = "StringifyFailure";
+		this.reason = reason;
+	}
+};
+/**
+* Thrown by the value-stringifier trio when its mutual recursion exceeds
+* {@link MAX_NESTING_DEPTH}. A deeply-nested acyclic value (e.g. a 50 000-deep
+* array) would otherwise overflow the call stack as an unhandled `RangeError`
+* defect; the facade catches this and materializes a fatal
+* `YamlStringifyError` (a `NestingDepthExceeded` diagnostic), keeping the
+* failure on the typed error channel — the stringify mirror of the composer's
+* nesting-depth guard.
+*/
+var StringifyDepthExceeded = class extends Error {
+	constructor() {
+		super(`Nesting depth exceeded maximum of ${256}`);
+		this.name = "StringifyDepthExceeded";
+	}
+};
+const NULL_RE = /^(?:null|Null|NULL|~)$/;
+const TRUE_RE = /^(?:true|True|TRUE)$/;
+const FALSE_RE = /^(?:false|False|FALSE)$/;
+const INT_RE = /^[-+]?[0-9]+$/;
+const OCT_RE = /^0o[0-7]+$/;
+const HEX_RE = /^0x[\dA-Fa-f]+$/;
+const FLOAT_RE = /^[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?$/;
+const INF_RE = /^[-+]?\.(?:inf|Inf|INF)$/;
+const NAN_RE = /^\.(?:nan|NaN|NAN)$/;
+/**
+* YAML indicator characters that require quoting when appearing in plain scalars.
+*/
+const INDICATOR_CHARS = /* @__PURE__ */ new Set([
+	":",
+	"#",
+	"{",
+	"}",
+	"[",
+	"]",
+	",",
+	"&",
+	"*",
+	"?",
+	"|",
+	"-",
+	"<",
+	">",
+	"=",
+	"!",
+	"%",
+	"@",
+	"`",
+	"\"",
+	"'"
+]);
+/**
+* Returns true if a string value would be mis-resolved as a non-string YAML type.
+*
+* Tests against all YAML 1.2 Core Schema type patterns (null, bool, int, float,
+* inf, nan). Any string matching these patterns must be quoted to preserve its
+* string identity during a parse round-trip.
+*/
+function wouldBeResolved(s) {
+	if (s === "") return true;
+	if (NULL_RE.test(s)) return true;
+	if (TRUE_RE.test(s)) return true;
+	if (FALSE_RE.test(s)) return true;
+	if (OCT_RE.test(s)) return true;
+	if (HEX_RE.test(s)) return true;
+	if (INT_RE.test(s)) return true;
+	if (INF_RE.test(s)) return true;
+	if (NAN_RE.test(s)) return true;
+	if (FLOAT_RE.test(s)) return true;
+	return false;
+}
+/**
+* Returns true if a string requires quoting to be safely represented as a plain scalar.
+*
+* Checks multiple conditions beyond type-conflict detection: empty strings,
+* embedded newlines, leading indicator characters or whitespace, and inline
+* comment/mapping-value patterns (`: `, ` #`). This is the single gate that
+* decides whether a plain scalar is safe or must be wrapped in quotes.
+*/
+function requiresQuoting(s, ignoreType = false) {
+	if (s === "") return true;
+	if (s.includes("\n")) return true;
+	if (!ignoreType && wouldBeResolved(s)) return true;
+	const first = s[0];
+	if (first === " " || first === "	") return true;
+	if (first !== void 0 && INDICATOR_CHARS.has(first)) if (first === ":" || first === "?" || first === "-") {
+		const second = s[1];
+		if (s.length === 1 || second === " " || second === "	") return true;
+	} else return true;
+	if (s.startsWith("---") || s.startsWith("...")) return true;
+	if (s.includes(": ") || s.includes(":	") || s.endsWith(":")) return true;
+	if (s.includes(" #") || s.includes("	#")) return true;
+	const last = s[s.length - 1];
+	if (last === " " || last === "	") return true;
+	for (let i = 0; i < s.length; i++) if (isControlChar(s.charCodeAt(i))) return true;
+	return false;
+}
+/**
+* Returns true if the string contains any non-ASCII character (code point \> 0x7E).
+*/
+function hasNonAscii(s) {
+	for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 126) return true;
+	return false;
+}
+/**
+* Renders a string scalar using double-quote style.
+*
+* When `canonical` is true, non-ASCII characters are escaped as `\uXXXX`
+* (or `\UXXXXXXXX` for supplementary plane) and C0 control characters use
+* named escapes where YAML 1.2 defines them (`\b`, `\0`, `\a`, `\v`, `\e`).
+*/
+function renderDoubleQuoted(s, canonical = false) {
+	let escaped = s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+	let result = "";
+	for (let i = 0; i < escaped.length; i++) {
+		const code = escaped.charCodeAt(i);
+		if (isControlChar(code)) if (code === 0) result += "\\0";
+		else if (code === 7) result += "\\a";
+		else if (code === 8) result += "\\b";
+		else if (code === 11) result += "\\v";
+		else if (code === 12) result += "\\f";
+		else if (code === 27) result += "\\e";
+		else result += `\\x${code.toString(16).padStart(2, "0")}`;
+		else if (canonical && code > 126) {
+			if (code >= 55296 && code <= 56319 && i + 1 < escaped.length) {
+				const low = escaped.charCodeAt(i + 1);
+				if (low >= 56320 && low <= 57343) {
+					const cp = (code - 55296) * 1024 + (low - 56320) + 65536;
+					result += `\\U${cp.toString(16).toUpperCase().padStart(8, "0")}`;
+					i++;
+					continue;
+				}
+			}
+			result += `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+		} else result += escaped[i];
+	}
+	escaped = result;
+	return `"${escaped}"`;
+}
+/**
+* Renders a string scalar using single-quote style.
+*/
+function renderSingleQuoted(s) {
+	return `'${s.replace(/'/g, "''")}'`;
+}
+/**
+* Renders a string value as a YAML scalar using the requested style.
+* Falls back to double-quoted if the requested style is unsafe for the value.
+*
+* Multi-line strings are routed to block styles regardless of the requested
+* style (except double-quoted). For single-line strings, plain style delegates
+* to {@link requiresQuoting} and falls back to double-quoted when the value
+* would be ambiguous. 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) {
+	if (s.includes("\n")) {
+		let hasControl = false;
+		for (let i = 0; i < s.length; i++) {
+			const code = s.charCodeAt(i);
+			if (isControlChar(code) || code === 13) {
+				hasControl = true;
+				break;
+			}
+		}
+		if (hasControl) return renderDoubleQuoted(s, canonical);
+		if (/^[\n ]*$/.test(s) && style !== "block-literal" && style !== "block-folded") return renderDoubleQuoted(s, canonical);
+		if (canonical && (style === "block-literal" || style === "block-folded")) {
+			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 === "plain" || style === "single-quoted") {
+			if (canonical) {
+				const sq = renderSingleQuotedMultiline(s, indent);
+				if (sq !== null) return sq;
+			}
+			return renderBlockLiteral(s, indent, explicitChomp, parentPosition);
+		}
+		return renderDoubleQuoted(s, canonical);
+	}
+	if (canonical && hasNonAscii(s)) return renderDoubleQuoted(s, true);
+	if (s === "" && (style === "block-literal" || style === "block-folded")) return renderDoubleQuoted(s, canonical);
+	switch (style) {
+		case "plain":
+			if (requiresQuoting(s, ignoreType)) {
+				if (s.includes("	") || s.includes("\r")) return renderDoubleQuoted(s, canonical);
+				for (let i = 0; i < s.length; i++) if (isControlChar(s.charCodeAt(i))) return renderDoubleQuoted(s, canonical);
+				return renderSingleQuoted(s);
+			}
+			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);
+	}
+}
+/**
+* Returns true if the rendered text ends with an open-ended block scalar
+* (`|+` or `>+` keep-chomp). Such scalars consume any trailing blank lines
+* up to the next document marker, so an explicit `...` is required for the
+* reader to know where the value ends.
+*
+* Detects the most recent `|` or `>` indicator on a header line (matching
+* the form `|<digits>?<chomp>?$` after optional indent and node prefixes)
+* and returns true when the chomp indicator is `+`.
+*/
+function endsWithKeepChomp(rendered) {
+	const match = rendered.match(/[|>][1-9]?[+-]?$|[|>][1-9]?[+-]?(?=\n)/g);
+	if (!match) return false;
+	return match[match.length - 1].includes("+");
+}
+/**
+* Renders a number value as a YAML scalar string.
+*
+* Maps JavaScript special number values to their YAML 1.2 Core Schema
+* equivalents: `NaN` becomes `.nan`, positive infinity becomes `.inf`,
+* and negative infinity becomes `-.inf`. All other numbers use
+* `String(n)` which produces valid YAML integer or float literals.
+*/
+function renderNumber(n) {
+	if (Number.isNaN(n)) return ".nan";
+	if (n === Number.POSITIVE_INFINITY) return ".inf";
+	if (n === Number.NEGATIVE_INFINITY) return "-.inf";
+	return String(n);
+}
+/**
+* Detects circular references by tracking the object ancestor chain.
+*/
+function detectCircular(value, seen) {
+	if (value !== null && typeof value === "object") {
+		if (seen.has(value)) throw new StringifyFailure("Circular reference detected");
+	}
+}
+/** Resolves optional stringify options into a fully-defaulted context. */
+function createContext(options) {
+	return {
+		indent: options?.indent ?? 2,
+		lineWidth: options?.lineWidth ?? 80,
+		defaultScalarStyle: options?.defaultScalarStyle ?? "plain",
+		defaultCollectionStyle: options?.defaultCollectionStyle ?? "block",
+		sortKeys: options?.sortKeys ?? false,
+		forceDefaultStyles: options?.forceDefaultStyles ?? false,
+		seen: /* @__PURE__ */ new Set()
+	};
+}
+/**
+* Recursively stringifies a JavaScript value into YAML lines.
+*
+* Returns an array of lines with NO leading indentation — the caller is
+* responsible for prepending the appropriate indentation prefix to each line.
+* This avoids double-indentation when embedding nested collections.
+*/
+function stringifyLines(value, ctx, depth) {
+	if (depth > 256) throw new StringifyDepthExceeded();
+	if (value === null || value === void 0) return ["null"];
+	if (typeof value === "boolean") return [value ? "true" : "false"];
+	if (typeof value === "number") return [renderNumber(value)];
+	if (typeof value === "bigint") return [value.toString()];
+	if (typeof value === "string") return renderString(value, ctx.defaultScalarStyle, " ".repeat(ctx.indent), false, ctx.forceDefaultStyles).split("\n");
+	if (Array.isArray(value)) {
+		detectCircular(value, ctx.seen);
+		ctx.seen.add(value);
+		try {
+			return stringifyArrayLines(value, ctx, depth);
+		} finally {
+			ctx.seen.delete(value);
+		}
+	}
+	if (typeof value === "object" && value !== null) {
+		detectCircular(value, ctx.seen);
+		ctx.seen.add(value);
+		try {
+			return stringifyObjectLines(value, ctx, depth);
+		} finally {
+			ctx.seen.delete(value);
+		}
+	}
+	return [renderDoubleQuoted(String(value))];
+}
+/**
+* Stringifies a JavaScript array into YAML sequence lines (no leading indent).
+*/
+function stringifyArrayLines(arr, ctx, depth) {
+	if (arr.length === 0) return ["[]"];
+	if (ctx.defaultCollectionStyle === "flow") return [`[${arr.map((item) => stringifyLines(item, ctx, depth + 1).join(" ")).join(", ")}]`];
+	const pad = " ".repeat(ctx.indent);
+	const lines = [];
+	for (const item of arr) {
+		const itemLines = stringifyLines(item, ctx, depth + 1);
+		if (itemLines.length === 1) lines.push(`- ${itemLines[0]}`);
+		else {
+			const first = itemLines[0];
+			if (first.startsWith("|") || first.startsWith(">")) {
+				lines.push(`- ${first}`);
+				for (let i = 1; i < itemLines.length; i++) lines.push(itemLines[i]);
+			} else {
+				lines.push(`- ${itemLines[0]}`);
+				for (let i = 1; i < itemLines.length; i++) lines.push(`${pad}${itemLines[i]}`);
+			}
+		}
+	}
+	return lines;
+}
+/**
+* Returns true when a value is a non-empty block collection (object or array
+* with block style). Such values must never be placed inline after a key colon
+* in a block mapping — they must always start on the next line.
+*/
+function isBlockCollection(value, ctx) {
+	if (ctx.defaultCollectionStyle === "flow") return false;
+	if (Array.isArray(value) && value.length > 0) return true;
+	if (value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0) return true;
+	return false;
+}
+/**
+* Stringifies a JavaScript object into YAML mapping lines (no leading indent).
+*/
+function stringifyObjectLines(obj, ctx, depth) {
+	const keys = Object.keys(obj);
+	if (keys.length === 0) return ["{}"];
+	if (ctx.sortKeys) keys.sort();
+	if (ctx.defaultCollectionStyle === "flow") return [`{${keys.map((k) => {
+		return `${renderString(k, "plain", "")}: ${stringifyLines(obj[k], ctx, depth + 1).join(" ")}`;
+	}).join(", ")}}`];
+	const renderKey = (k) => k.includes("\n") ? renderDoubleQuoted(k, ctx.forceDefaultStyles) : renderString(k, "plain", "");
+	const pad = " ".repeat(ctx.indent);
+	const lines = [];
+	for (const k of keys) {
+		const keyStr = renderKey(k);
+		const val = obj[k];
+		const valLines = stringifyLines(val, ctx, depth + 1);
+		if (valLines.length === 1 && !isBlockCollection(val, ctx)) lines.push(`${keyStr}: ${valLines[0]}`);
+		else {
+			const first = valLines[0];
+			if (first.startsWith("|") || first.startsWith(">")) {
+				lines.push(`${keyStr}: ${first}`);
+				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+			} else if (Array.isArray(val) && val.length > 0) {
+				lines.push(`${keyStr}:`);
+				for (const vl of valLines) lines.push(vl);
+			} else {
+				lines.push(`${keyStr}:`);
+				for (const vl of valLines) lines.push(`${pad}${vl}`);
+			}
+		}
+	}
+	return lines;
+}
+/** Standard YAML 1.2 secondary tag prefix. */
+const YAML_TAG_PREFIX = "tag:yaml.org,2002:";
+/**
+* Build a tag resolution map from document directives.
+* Maps tag handles (e.g., "!!", "!e!") to their URI prefixes.
+*/
+function buildTagMap(directives) {
+	const map = /* @__PURE__ */ new Map();
+	for (const d of directives) if (d.name === "TAG" && d.parameters.length >= 2) map.set(d.parameters[0], d.parameters[1]);
+	return map;
+}
+/**
+* Normalize a tag for canonical output.
+*
+* - Resolves custom handles using the tag map from directives
+* - Abbreviates `tag:yaml.org,2002:XXX` URIs to `!!XXX`
+* - Simplifies verbatim `!<!XXX>` to `!XXX`
+* - Expands non-standard `!!` redefinitions to verbatim form
+*/
+function normalizeTag(tag, tagMap) {
+	if (tag.startsWith("!<") && tag.endsWith(">")) {
+		const uri = tag.slice(2, -1);
+		if (uri.startsWith(YAML_TAG_PREFIX)) return `!!${uri.slice(18)}`;
+		if (uri.startsWith("!")) return uri;
+		return tag;
+	}
+	if (tag.startsWith("!!")) {
+		const customPrefix = tagMap.get("!!");
+		if (customPrefix && customPrefix !== YAML_TAG_PREFIX) return `!<${customPrefix}${tag.slice(2)}>`;
+		return tag;
+	}
+	const namedMatch = tag.match(/^(![\w-]*!)(.*)$/);
+	if (namedMatch) {
+		const handle = namedMatch[1];
+		const suffix = namedMatch[2] ?? "";
+		const prefix = tagMap.get(handle);
+		if (prefix) {
+			const uri = prefix + suffix;
+			if (uri.startsWith(YAML_TAG_PREFIX)) return `!!${uri.slice(18)}`;
+			return `!<${uri}>`;
+		}
+	}
+	if (tag.startsWith("!") && tag.length > 1 && !tag.startsWith("!!")) {
+		const prefix = tagMap.get("!");
+		if (prefix) {
+			const uri = prefix + tag.slice(1);
+			if (uri.startsWith(YAML_TAG_PREFIX)) return `!!${uri.slice(18)}`;
+			return `!<${uri}>`;
+		}
+	}
+	return tag;
+}
+/**
+* Recursively normalizes tags on all AST nodes using document directives.
+*/
+function normalizeNodeTags(node, tagMap) {
+	if (node instanceof YamlScalar) return new YamlScalar({
+		value: node.value,
+		style: node.style,
+		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
+		...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 } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	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 } : {}
+		})),
+		style: node.style,
+		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.comment !== void 0 ? { comment: node.comment } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	if (node instanceof YamlSeq) return new YamlSeq({
+		items: node.items.map((item) => normalizeNodeTags(item, tagMap)),
+		style: node.style,
+		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.comment !== void 0 ? { comment: node.comment } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	return node;
+}
+/**
+* Recursively strips all comment fields from AST nodes.
+* Used when forceDefaultStyles is true to produce canonical output.
+*/
+function stripNodeComments(node) {
+	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 } : {},
+		...node.chomp !== void 0 ? { chomp: node.chomp } : {},
+		...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.map((pair) => new YamlPair({
+			key: stripNodeComments(pair.key),
+			value: pair.value ? stripNodeComments(pair.value) : null
+		})),
+		style: node.style,
+		...node.tag !== void 0 ? { tag: node.tag } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	if (node instanceof YamlSeq) return new YamlSeq({
+		items: node.items.map(stripNodeComments),
+		style: node.style,
+		...node.tag !== void 0 ? { tag: node.tag } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	});
+	return node;
+}
+/**
+* Stringifies a YAML AST node into lines (no leading indent), respecting
+* style metadata from the node.
+*/
+function stringifyNodeLines(node, ctx, depth) {
+	if (depth > 256) throw new StringifyDepthExceeded();
+	if (node instanceof YamlScalar) return stringifyScalarNodeLines(node, ctx);
+	if (node instanceof YamlMap) return stringifyMapNodeLines(node, ctx, depth);
+	if (node instanceof YamlSeq) return stringifySeqNodeLines(node, ctx, depth);
+	if (node instanceof YamlAlias) return [`*${node.name}`];
+	return ["null"];
+}
+/**
+* Stringifies a YamlScalar node into lines, using the node's style metadata.
+*/
+function stringifyScalarNodeLines(node, ctx) {
+	const style = node.style ?? ctx.defaultScalarStyle;
+	const val = node.value;
+	const isEmpty = node.length === 0 && (val === null || val === void 0 || val === "");
+	if (isEmpty && (node.tag || node.anchor)) {
+		const parts = [];
+		if (node.tag) parts.push(node.tag);
+		if (node.anchor) parts.push(`&${node.anchor}`);
+		return [parts.join(" ")];
+	}
+	let lines;
+	if (val === null || val === void 0) if (isEmpty) lines = [""];
+	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).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]}`;
+	return lines;
+}
+/**
+* Stringifies a YamlMap node into lines, using the node's collection style.
+*/
+function stringifyMapNodeLines(node, ctx, depth) {
+	const style = ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : node.style ?? ctx.defaultCollectionStyle;
+	let items = [...node.items];
+	if (ctx.sortKeys) items = items.sort((a, b) => {
+		const ka = a.key instanceof YamlScalar ? String(a.key.value) : "";
+		const kb = b.key instanceof YamlScalar ? String(b.key.value) : "";
+		return ka < kb ? -1 : ka > kb ? 1 : 0;
+	});
+	if (items.length === 0) {
+		let line = "{}";
+		const emptyPrefix = buildMetadataPrefix(node.tag, node.anchor);
+		if (emptyPrefix) line = `${emptyPrefix} ${line}`;
+		return [line];
+	}
+	if (style === "flow") {
+		let line = `{${items.map((pair) => {
+			return `${pair.key ? stringifyNodeLines(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 lines = [];
+	for (const pair of items) {
+		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 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;
+			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}`);
+					}
+				}
+			}
+			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 ? stringifyNodeLines(pair.key, ctx, depth + 1).join(" ") : "null";
+		const keyStr = resolvedKeyStr;
+		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;
+		if (!valNode) {
+			const isPlainKey = pair.key instanceof YamlScalar && pair.key.style === "plain";
+			const keyIsNonEmpty = pair.key instanceof YamlScalar && pair.key.length > 0;
+			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}`);
+			continue;
+		}
+		const valLines = stringifyNodeLines(valNode, {
+			...ctx,
+			parentPosition: "block-map-value"
+		}, depth + 1);
+		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}`);
+			for (let i = startIdx; i < valLines.length; i++) lines.push(valLines[i]);
+		} else if (valNode instanceof YamlMap && valNode.items.length > 0 && (ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : valNode.style ?? ctx.defaultCollectionStyle) === "block") {
+			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 {
+			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(`${keyStr}${sep} ${first}`);
+				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+			} 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]}`);
+				} else {
+					lines.push(`${keyStr}${sep}`);
+					for (const vl of valLines) lines.push(`${pad}${vl}`);
+				}
+			}
+		}
+	}
+	const prefix = buildMetadataPrefix(node.tag, node.anchor);
+	if (prefix) lines.unshift(prefix);
+	return lines;
+}
+/**
+* Builds a metadata prefix string from tag and anchor.
+* Returns the combined prefix or undefined if neither is present.
+*/
+function buildMetadataPrefix(tag, anchor) {
+	if (!tag && !anchor) return void 0;
+	const parts = [];
+	if (anchor) parts.push(`&${anchor}`);
+	if (tag) parts.push(tag);
+	return parts.join(" ");
+}
+/**
+* Strips a leading run of `&anchor`/`!tag` metadata tokens (each followed by
+* whitespace) from a rendered scalar line and returns the remainder. Used to
+* detect quoted/block scalar style after the optional metadata prefix that
+* `stringifyScalarNodeLines` may prepend to the first output line.
+*/
+function stripScalarMetadataPrefix(line) {
+	let i = 0;
+	while (i < line.length) {
+		const ch = line[i];
+		if (ch !== "&" && ch !== "!") break;
+		let j = i + 1;
+		while (j < line.length && line[j] !== " " && line[j] !== "	") j++;
+		if (j >= line.length || j === i + 1) break;
+		while (j < line.length && (line[j] === " " || line[j] === "	")) j++;
+		i = j;
+	}
+	return line.slice(i);
+}
+/**
+* Stringifies a YamlSeq node into lines, using the node's collection style.
+*/
+function stringifySeqNodeLines(node, ctx, depth) {
+	const style = ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : node.style ?? ctx.defaultCollectionStyle;
+	const items = [...node.items];
+	if (items.length === 0) {
+		let line = "[]";
+		const emptyPrefix = buildMetadataPrefix(node.tag, node.anchor);
+		if (emptyPrefix) line = `${emptyPrefix} ${line}`;
+		return [line];
+	}
+	if (style === "flow") {
+		let line = `[${items.map((item) => stringifyNodeLines(item, ctx, depth + 1).join(" ")).join(", ")}]`;
+		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
+		if (flowPrefix) line = `${flowPrefix} ${line}`;
+		return [line];
+	}
+	const pad = " ".repeat(ctx.indent);
+	const lines = [];
+	const itemCtx = {
+		...ctx,
+		parentPosition: "block-seq-item"
+	};
+	for (const item of items) {
+		const itemLines = stringifyNodeLines(item, itemCtx, depth + 1);
+		if (itemLines.length === 1) lines.push(itemLines[0] === "" ? "-" : `- ${itemLines[0]}`);
+		else {
+			const first = itemLines[0];
+			const firstStripped = stripScalarMetadataPrefix(first);
+			const itemIsScalar = item instanceof YamlScalar;
+			if (firstStripped.startsWith("|") || firstStripped.startsWith(">") || itemIsScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""))) {
+				lines.push(`- ${first}`);
+				for (let i = 1; i < itemLines.length; i++) lines.push(itemLines[i]);
+			} else {
+				lines.push(first === "" ? "-" : `- ${first}`);
+				for (let i = 1; i < itemLines.length; i++) lines.push(`${pad}${itemLines[i]}`);
+			}
+		}
+	}
+	const prefix = buildMetadataPrefix(node.tag, node.anchor);
+	if (prefix) lines.unshift(prefix);
+	return lines;
+}
+/**
+* Converts a JavaScript value into a YAML text string.
+*
+* Handles all primitive types, arrays, and plain objects. Special numbers
+* (`Infinity`, `-Infinity`, `NaN`) are rendered as `.inf`, `-.inf`, and
+* `.nan` respectively. Circular references throw {@link StringifyFailure}.
+*/
+function stringifyValue(value, options) {
+	const result = stringifyLines(value, createContext(options), 0).join("\n");
+	return options?.finalNewline ?? true ? `${result}\n` : result;
+}
+/**
+* Converts a composed YAML document AST into a YAML text string, preserving
+* the style metadata encoded in each AST node.
+*
+* Scalar nodes use their `style` field to control rendering; collection
+* nodes use their `style` field (`"block"` or `"flow"`). Nodes without an
+* explicit style fall back to the defaults in `options`.
+*/
+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;
+	if (ctx.forceDefaultStyles && contents) {
+		contents = stripNodeComments(contents);
+		const tagMap = buildTagMap(doc.directives);
+		contents = normalizeNodeTags(contents, tagMap);
+	}
+	if (contents === null) {
+		if (ctx.forceDefaultStyles) {
+			if (doc.hasDocumentStart) return `---\n${doc.hasDocumentEnd ? "...\n" : ""}`;
+			return "";
+		}
+		return finalNewline ? "null\n" : "null";
+	}
+	const result = stringifyNodeLines(contents, ctx, 0).join("\n");
+	const body = finalNewline ? `${result}\n` : result;
+	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" : "";
+	if (doc.hasDocumentStart) {
+		const rootTag = contents && "tag" in contents ? contents.tag : void 0;
+		const rootAnchor = contents && "anchor" in contents ? contents.anchor : void 0;
+		const isCollection = contents instanceof YamlMap || contents instanceof YamlSeq;
+		const isScalar = contents instanceof YamlScalar;
+		if (rootTag || rootAnchor) {
+			const metaParts = [];
+			if (rootAnchor) metaParts.push(`&${rootAnchor}`);
+			if (rootTag) metaParts.push(rootTag);
+			const metaStr = metaParts.join(" ");
+			let bodyClean = body;
+			const metaLinePrefix = `${metaStr}\n`;
+			const metaInlinePrefix = `${metaStr} `;
+			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}`;
+		}
+		if (isScalar) return docComment ? `# ${docComment}\n--- ${body}${docEnd}` : `--- ${body}${docEnd}`;
+		return docComment ? `# ${docComment}\n---\n${body}${docEnd}` : `---\n${body}${docEnd}`;
+	}
+	return docComment ? `# ${docComment}\n${body}${docEnd}` : `${body}${docEnd}`;
+}
+
+//#endregion
+export { StringifyDepthExceeded, StringifyFailure, stringifyDocument, stringifyValue, stripNodeComments };