@effected/yaml 0.1.0

package/YamlNode.js

@@ -0,0 +1,396 @@
+import { Option, Schema } from "effect";
+
+//#region src/YamlNode.ts
+/**
+* YAML scalar presentation styles.
+*
+* @public
+*/
+const ScalarStyle = Schema.Literals([
+	"plain",
+	"single-quoted",
+	"double-quoted",
+	"block-literal",
+	"block-folded"
+]);
+/**
+* YAML collection presentation styles.
+*
+* @public
+*/
+const CollectionStyle = Schema.Literals(["block", "flow"]);
+/**
+* Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
+* Referenced by the {@link YamlScalar} `chomp` field schema.
+*
+* @public
+*/
+const ScalarChomp = Schema.Literals([
+	"strip",
+	"clip",
+	"keep"
+]);
+/**
+* A YAML scalar AST node, representing a leaf value such as a string,
+* number, boolean, or null.
+*
+* - `value` — the resolved JavaScript value (null, boolean, number, bigint or
+*   string).
+* - `style` — the scalar presentation style in the source document.
+* - `tag` — optional explicit YAML tag (e.g. `!!str`, `!!int`).
+* - `anchor` — optional anchor name for aliasing.
+* - `comment` — optional trailing or leading comment text.
+* - `chomp` — block-scalar chomping indicator, when the scalar is a block
+*   scalar.
+* - `raw` — the raw source text, preserved when it differs from the resolved
+*   value in a way stringification needs to know about.
+* - `sourceMultiline` — `true` when the source span covers two or more lines;
+*   absent on synthetic nodes.
+* - `offset` / `length` — the node's span in the source.
+*
+* @public
+*/
+var YamlScalar = class extends Schema.TaggedClass()("YamlScalar", {
+	value: Schema.Unknown,
+	tag: Schema.optionalKey(Schema.String),
+	style: ScalarStyle,
+	anchor: Schema.optionalKey(Schema.String),
+	comment: Schema.optionalKey(Schema.String),
+	chomp: Schema.optionalKey(ScalarChomp),
+	raw: Schema.optionalKey(Schema.String),
+	sourceMultiline: Schema.optionalKey(Schema.Boolean),
+	offset: Schema.Number,
+	length: Schema.Number
+}) {
+	/**
+	* Navigate to a descendant by path (string segments for mapping keys,
+	* numbers for sequence indices). `Option.none()` when any segment cannot
+	* be resolved. Pure.
+	*/
+	find(path) {
+		return findByPath(this, path);
+	}
+	/**
+	* Find the deepest node whose span contains `offset` (half-open interval),
+	* or `Option.none()` when the offset falls outside this subtree. Pure.
+	*/
+	findAtOffset(offset) {
+		return findDeepestAtOffset(this, offset);
+	}
+	/**
+	* Return the path from this node to the given descendant node (matched by
+	* reference identity), or `Option.none()` when it is not in this subtree.
+	* The inverse of {@link YamlScalar.find}. Pure.
+	*/
+	pathOf(node) {
+		return pathToNode(this, node);
+	}
+	/**
+	* Reconstruct the plain JavaScript value of this subtree. Aliases resolve
+	* through `anchors` (anchors encountered during the walk register
+	* incrementally, so an alias sees the most recent definition at its point
+	* of use); unresolvable aliases yield `null`. Pure and total.
+	*/
+	toValue(anchors) {
+		return nodeToValue(this, anchors, defaultBudget());
+	}
+};
+/**
+* A YAML alias AST node, referencing a previously defined anchor by name
+* (without the leading `*`).
+*
+* @public
+*/
+var YamlAlias = class extends Schema.TaggedClass()("YamlAlias", {
+	name: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number
+}) {
+	/** See `YamlScalar.find`. Pure. */
+	find(path) {
+		return findByPath(this, path);
+	}
+	/** See `YamlScalar.findAtOffset`. Pure. */
+	findAtOffset(offset) {
+		return findDeepestAtOffset(this, offset);
+	}
+	/** See `YamlScalar.pathOf`. Pure. */
+	pathOf(node) {
+		return pathToNode(this, node);
+	}
+	/** See `YamlScalar.toValue`. Pure and total. */
+	toValue(anchors) {
+		return nodeToValue(this, anchors, defaultBudget());
+	}
+};
+/**
+* A discriminated-union schema covering all four YAML AST value node types:
+* {@link YamlScalar}, {@link YamlMap}, {@link YamlSeq} and {@link YamlAlias}.
+* Defined lazily via `Schema.suspend` to break the recursive reference chain
+* `YamlNode → YamlMap → YamlPair → YamlNode`.
+*
+* @remarks
+* Construct member nodes via their `.make(...)` static (e.g.
+* `YamlScalar.make(...)`), never `new YamlScalar(...)` — the internal
+* composer's hot-path `new` construction is the one recorded exception, kept
+* internal to the engine for its allocation-sensitive walk.
+*
+* @public
+*/
+const YamlNode = Schema.suspend(() => Schema.Union([
+	YamlScalar,
+	YamlMap,
+	YamlSeq,
+	YamlAlias
+]));
+/**
+* A YAML key-value pair AST node, representing one entry within a mapping.
+* `value` is `null` when absent (e.g. `key:` with no value).
+*
+* @public
+*/
+var YamlPair = class extends Schema.TaggedClass()("YamlPair", {
+	key: Schema.suspend(() => YamlNode),
+	value: Schema.NullOr(Schema.suspend(() => YamlNode)),
+	comment: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* A YAML mapping AST node, representing a collection of {@link YamlPair}
+* entries.
+*
+* - `style` — the presentation style: `"block"` or `"flow"`.
+* - `sourceMultiline` — `true` when the source span covers two or more lines;
+*   used by the canonical stringifier. Absent on synthetic nodes.
+*
+* @public
+*/
+var YamlMap = class extends Schema.TaggedClass()("YamlMap", {
+	items: Schema.Array(Schema.suspend(() => YamlPair)),
+	tag: Schema.optionalKey(Schema.String),
+	anchor: Schema.optionalKey(Schema.String),
+	style: CollectionStyle,
+	comment: Schema.optionalKey(Schema.String),
+	sourceMultiline: Schema.optionalKey(Schema.Boolean),
+	offset: Schema.Number,
+	length: Schema.Number
+}) {
+	/** See `YamlScalar.find`. Pure. */
+	find(path) {
+		return findByPath(this, path);
+	}
+	/** See `YamlScalar.findAtOffset`. Pure. */
+	findAtOffset(offset) {
+		return findDeepestAtOffset(this, offset);
+	}
+	/** See `YamlScalar.pathOf`. Pure. */
+	pathOf(node) {
+		return pathToNode(this, node);
+	}
+	/** See `YamlScalar.toValue`. Pure and total. */
+	toValue(anchors) {
+		return nodeToValue(this, anchors, defaultBudget());
+	}
+};
+/**
+* A YAML sequence AST node, representing an ordered list of
+* {@link (YamlNode:type)} values.
+*
+* @public
+*/
+var YamlSeq = class extends Schema.TaggedClass()("YamlSeq", {
+	items: Schema.Array(Schema.suspend(() => YamlNode)),
+	tag: Schema.optionalKey(Schema.String),
+	anchor: Schema.optionalKey(Schema.String),
+	style: CollectionStyle,
+	comment: Schema.optionalKey(Schema.String),
+	sourceMultiline: Schema.optionalKey(Schema.Boolean),
+	offset: Schema.Number,
+	length: Schema.Number
+}) {
+	/** See `YamlScalar.find`. Pure. */
+	find(path) {
+		return findByPath(this, path);
+	}
+	/** See `YamlScalar.findAtOffset`. Pure. */
+	findAtOffset(offset) {
+		return findDeepestAtOffset(this, offset);
+	}
+	/** See `YamlScalar.pathOf`. Pure. */
+	pathOf(node) {
+		return pathToNode(this, node);
+	}
+	/** See `YamlScalar.toValue`. Pure and total. */
+	toValue(anchors) {
+		return nodeToValue(this, anchors, defaultBudget());
+	}
+};
+function findByPath(root, path) {
+	let current = root;
+	for (const segment of path) {
+		if (current === null) return Option.none();
+		if (typeof segment === "string") {
+			if (!(current instanceof YamlMap)) return Option.none();
+			const pair = current.items.find((p) => p.key instanceof YamlScalar && typeof p.key.value === "string" && p.key.value === segment);
+			if (!pair || pair.value === null) return Option.none();
+			current = pair.value;
+		} else {
+			if (!(current instanceof YamlSeq)) return Option.none();
+			const item = current.items[segment];
+			if (item === void 0) return Option.none();
+			current = item;
+		}
+	}
+	return current === null ? Option.none() : Option.some(current);
+}
+/**
+* Half-open interval test `[offset, offset + length)` so a cursor positioned
+* immediately after a node is NOT considered inside it.
+*/
+function containsOffset(node, offset) {
+	return offset >= node.offset && offset < node.offset + node.length;
+}
+function findDeepestAtOffset(node, offset) {
+	if (!containsOffset(node, offset)) return Option.none();
+	if (node instanceof YamlMap) for (const pair of node.items) {
+		const keyResult = findDeepestAtOffset(pair.key, offset);
+		if (Option.isSome(keyResult)) return keyResult;
+		if (pair.value !== null) {
+			const valResult = findDeepestAtOffset(pair.value, offset);
+			if (Option.isSome(valResult)) return valResult;
+		}
+	}
+	if (node instanceof YamlSeq) for (const item of node.items) {
+		const itemResult = findDeepestAtOffset(item, offset);
+		if (Option.isSome(itemResult)) return itemResult;
+	}
+	return Option.some(node);
+}
+function pathToNode(root, target) {
+	const path = [];
+	return descendToNode(root, target, path) ? Option.some(path) : Option.none();
+}
+/**
+* Depth-first identity search accumulating mapping-key/sequence-index
+* segments. Only scalar string keys produce navigable segments (matching
+* `find`); descendants reachable only through complex keys are not
+* addressable by path.
+*/
+function descendToNode(node, target, path) {
+	if (node === target) return true;
+	if (node instanceof YamlMap) {
+		for (const pair of node.items) if (pair.key instanceof YamlScalar && typeof pair.key.value === "string") {
+			if (pair.key === target) {
+				path.push(pair.key.value);
+				return true;
+			}
+			if (pair.value !== null) {
+				path.push(pair.key.value);
+				if (descendToNode(pair.value, target, path)) return true;
+				path.pop();
+			}
+		}
+	}
+	if (node instanceof YamlSeq) for (let i = 0; i < node.items.length; i++) {
+		const item = node.items[i];
+		path.push(i);
+		if (descendToNode(item, target, path)) return true;
+		path.pop();
+	}
+	return false;
+}
+/** Set a mapping key as an own data property — `__proto__` included. */
+function setOwnProperty(obj, key, value) {
+	if (key === "__proto__") Object.defineProperty(obj, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+	else obj[key] = value;
+}
+/**
+* Thrown by the value-extraction walk when alias expansion materializes more
+* output nodes than the budget allows — the YAML "billion laughs" guard. A
+* chain of aliases each referencing the previous (`a2: [*a1×10]`, `a3:
+* [*a2×10]`, …) multiplies output size exponentially while the alias-*token*
+* count stays small, so the composer's per-token `maxAliasCount` limit does
+* not catch it; only bounding the expanded node count does.
+*
+* Not re-exported from the package entry point (`index.ts`) — the facade
+* catches it and materializes a fatal `AliasCountExceeded` `YamlParseError`
+* (or, for `Yaml.equals`, treats the input as malformed).
+*/
+var AliasExpansionBudgetExceeded = class extends Error {
+	constructor(limit) {
+		super(`Alias expansion exceeded budget of ${limit} nodes`);
+		this.name = "AliasExpansionBudgetExceeded";
+	}
+};
+/**
+* Multiplier converting a `maxAliasCount` budget into a cap on the number of
+* output nodes materialized *through alias expansion*. Deliberately generous:
+* alias-free content never ticks the counter (see {@link nodeToValue}), so a
+* large but benign document — or a single alias referencing a large alias-free
+* block — stays far under the cap, while an exponential alias chain accumulates
+* across the shared budget and trips it long before the heap is exhausted.
+*/
+const ALIAS_EXPANSION_FACTOR = 1e4;
+/** The output-node cap for a given `maxAliasCount`. */
+function aliasExpansionLimit(maxAliasCount) {
+	return (maxAliasCount + 1) * ALIAS_EXPANSION_FACTOR;
+}
+/** Default cap for a direct `toValue()` call, matching the default `maxAliasCount` of 100. */
+const DEFAULT_ALIAS_EXPANSION_LIMIT = aliasExpansionLimit(100);
+/** A fresh default budget for a direct `toValue()` call. */
+function defaultBudget() {
+	return {
+		count: 0,
+		limit: DEFAULT_ALIAS_EXPANSION_LIMIT
+	};
+}
+/**
+* Value extraction with an explicit alias-expansion budget derived from
+* `maxAliasCount`. The facade drives this so a `maxAliasCount` from parse
+* options bounds the "billion laughs" expansion; throws
+* {@link AliasExpansionBudgetExceeded} when the cap is exceeded. Not
+* re-exported from the package entry point.
+*/
+function nodeToJsValue(node, anchors, maxAliasCount) {
+	return nodeToValue(node, anchors, {
+		count: 0,
+		limit: aliasExpansionLimit(maxAliasCount)
+	});
+}
+function nodeToValue(node, anchors, budget, counting = false) {
+	if (node === null) return null;
+	if (counting && budget !== void 0) {
+		budget.count++;
+		if (budget.count > budget.limit) throw new AliasExpansionBudgetExceeded(budget.limit);
+	}
+	if (anchors !== void 0 && !(node instanceof YamlAlias) && node.anchor !== void 0) anchors.set(node.anchor, node);
+	if (node instanceof YamlScalar) return node.value;
+	if (node instanceof YamlMap) {
+		const result = {};
+		for (const pair of node.items) {
+			let key;
+			if (pair.key instanceof YamlScalar) {
+				if (anchors !== void 0 && pair.key.anchor !== void 0) anchors.set(pair.key.anchor, pair.key);
+				key = String(pair.key.value ?? "");
+			} else if (pair.key instanceof YamlAlias) {
+				const resolved = anchors?.get(pair.key.name);
+				key = resolved !== void 0 ? String(nodeToValue(resolved, anchors, budget, true) ?? "") : "";
+			} else key = "";
+			setOwnProperty(result, key, nodeToValue(pair.value, anchors, budget, counting));
+		}
+		return result;
+	}
+	if (node instanceof YamlSeq) return node.items.map((item) => nodeToValue(item, anchors, budget, counting));
+	if (node instanceof YamlAlias) {
+		const resolved = anchors?.get(node.name);
+		return resolved !== void 0 ? nodeToValue(resolved, anchors, budget, true) : null;
+	}
+	return null;
+}
+
+//#endregion
+export { AliasExpansionBudgetExceeded, CollectionStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq, aliasExpansionLimit, nodeToJsValue };

package/YamlVisitor.js

@@ -0,0 +1,172 @@
+import { YamlAlias, YamlMap, YamlScalar, YamlSeq } from "./YamlNode.js";
+import { composeAllDocuments } from "./internal/composer/document.js";
+import { YamlDiagnostic } from "./YamlDiagnostic.js";
+import { Data, Stream } from "effect";
+
+//#region src/YamlVisitor.ts
+/**
+* Constructors and matchers for the `YamlVisitorEvent` union (e.g.
+* `YamlVisitorEvent.Scalar({ path, depth, value, style })`,
+* `YamlVisitorEvent.$is("MapStart")`).
+*
+* @public
+*/
+const YamlVisitorEvent = Data.taggedEnum();
+/**
+* SAX-style YAML AST visitor statics. Not instantiable.
+*
+* @public
+*/
+var YamlVisitor = class {
+	constructor() {}
+	/**
+	* Create a lazy `Stream` of `YamlVisitorEvent` from YAML text, in document
+	* order. Multi-document streams (separated by `---`) produce a separate
+	* `DocumentStart`/`DocumentEnd` pair per document. Events are produced on
+	* demand, so combining with `Stream.take` allows efficient partial scans
+	* of large documents without materializing the whole event sequence.
+	*
+	* @remarks
+	* Infallible at the type level: diagnostics recorded while composing
+	* (fatal or not, including an exceeded `maxAliasCount`, recorded as
+	* `AliasCountExceeded`) surface as `Error` events inside the stream rather
+	* than failing it.
+	*/
+	static visit(text, options) {
+		return Stream.fromIterable(visitGen(text, options));
+	}
+};
+function* visitGen(text, options) {
+	const { documents, streamErrors } = composeAllDocuments(text, {
+		strict: options?.strict,
+		maxAliasCount: options?.maxAliasCount,
+		uniqueKeys: options?.uniqueKeys
+	});
+	for (const raw of streamErrors) yield YamlVisitorEvent.Error({
+		path: [],
+		depth: 0,
+		diagnostic: YamlDiagnostic.fromRaw(raw, text)
+	});
+	for (const doc of documents) yield* walkDocument(doc, text);
+}
+function* walkDocument(doc, text) {
+	const path = [];
+	const depth = 0;
+	for (const dir of doc.directives) yield YamlVisitorEvent.Directive({
+		path,
+		depth,
+		name: dir.name,
+		parameters: dir.parameters.join(" ")
+	});
+	yield YamlVisitorEvent.DocumentStart({
+		path,
+		depth,
+		directives: doc.directives.map((d) => ({
+			name: d.name,
+			parameters: d.parameters
+		}))
+	});
+	for (const raw of doc.errors) yield YamlVisitorEvent.Error({
+		path,
+		depth,
+		diagnostic: YamlDiagnostic.fromRaw(raw, text)
+	});
+	for (const raw of doc.warnings) yield YamlVisitorEvent.Error({
+		path,
+		depth,
+		diagnostic: YamlDiagnostic.fromRaw(raw, text)
+	});
+	if (doc.comment !== void 0) yield YamlVisitorEvent.Comment({
+		path,
+		depth,
+		text: doc.comment
+	});
+	if (doc.contents !== null) yield* walkNode(doc.contents, path, depth);
+	yield YamlVisitorEvent.DocumentEnd({
+		path,
+		depth
+	});
+}
+function* walkNode(node, path, depth) {
+	if (node instanceof YamlScalar) {
+		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.comment
+		});
+		yield YamlVisitorEvent.Scalar({
+			path,
+			depth,
+			value: node.value,
+			style: node.style,
+			...node.tag !== void 0 ? { tag: node.tag } : {},
+			...node.anchor !== void 0 ? { anchor: node.anchor } : {}
+		});
+	} else if (node instanceof YamlAlias) yield YamlVisitorEvent.Alias({
+		path,
+		depth,
+		name: node.name
+	});
+	else if (node instanceof YamlMap) {
+		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.comment
+		});
+		yield YamlVisitorEvent.MapStart({
+			path,
+			depth,
+			style: node.style,
+			...node.tag !== void 0 ? { tag: node.tag } : {},
+			...node.anchor !== void 0 ? { anchor: node.anchor } : {}
+		});
+		for (const pair of node.items) yield* walkPair(pair, path, depth + 1);
+		yield YamlVisitorEvent.MapEnd({
+			path,
+			depth
+		});
+	} else if (node instanceof YamlSeq) {
+		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.comment
+		});
+		yield YamlVisitorEvent.SeqStart({
+			path,
+			depth,
+			style: node.style,
+			...node.tag !== void 0 ? { tag: node.tag } : {},
+			...node.anchor !== void 0 ? { anchor: node.anchor } : {}
+		});
+		for (let i = 0; i < node.items.length; i++) {
+			const item = node.items[i];
+			yield* walkNode(item, [...path, i], depth + 1);
+		}
+		yield YamlVisitorEvent.SeqEnd({
+			path,
+			depth
+		});
+	}
+}
+function* walkPair(pair, parentPath, depth) {
+	const resolvedKey = pair.key instanceof YamlScalar ? pair.key.value : null;
+	const resolvedValue = pair.value instanceof YamlScalar ? pair.value.value : null;
+	const keySegment = typeof resolvedKey === "string" ? resolvedKey : typeof resolvedKey === "number" ? resolvedKey : String(resolvedKey);
+	const pairPath = [...parentPath, keySegment];
+	if (pair.comment !== void 0) yield YamlVisitorEvent.Comment({
+		path: pairPath,
+		depth,
+		text: pair.comment
+	});
+	yield YamlVisitorEvent.Pair({
+		path: pairPath,
+		depth,
+		key: resolvedKey,
+		value: resolvedValue
+	});
+	yield* walkNode(pair.key, pairPath, depth + 1);
+	if (pair.value !== null) yield* walkNode(pair.value, pairPath, depth + 1);
+}
+
+//#endregion
+export { YamlVisitor, YamlVisitorEvent };