@effected/yaml 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @effected/yaml
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fyaml?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Zero-dependency YAML 1.2 parsing, editing and formatting expressed as Effect schemas and pure functions. Parse a single document or a multi-document stream into plain values or an offset-preserving AST, resolve anchors and aliases, strip comments, compute byte-minimal edits, format, modify by path, walk a document as a `Stream` and decode straight into a validated domain schema.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/yaml
+
+YAML is where untrusted text meets production systems: CI pipeline definitions, Kubernetes manifests and config files that arrive from a pull request, an API payload or a user's home directory. The format is also large enough that a parser has real attack surface. An anchor that references an anchor that references an anchor — the "billion laughs" bomb — is a few hundred bytes of YAML that expands into gigabytes of nodes, and a deeply nested flow collection is a few kilobytes that overflows a recursive-descent parser's stack.
+
+This package treats that as a first-class requirement rather than a footnote. An alias-expansion budget bounds the number of materialized nodes, a depth cap bounds collection nesting on both the parse and the stringify side, and both fire into the typed error channel. Hostile input produces a `YamlParseError` carrying structured `YamlDiagnostic` values with codes and positions; it never produces a `RangeError`, an unhandled defect or an exhausted heap.
+
+The rest follows from the same discipline. Parsing recovers from errors and aggregates every diagnostic into one failure rather than throwing on the first. Modifications are computed as edits against the original bytes, so comments and layout survive a change. Everything is a pure function or a schema: no IO, no services and no runtime dependency other than `effect` — the lexer, CST parser, composer and stringifier are vendored into the package with attribution rather than taken as a dependency. It is the largest package in the repo, and it earns that by owning its engine.
+
+## Install
+
+```bash
+npm install @effected/yaml effect
+```
+
+```bash
+pnpm add @effected/yaml effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is a peer dependency; the package itself adds no other runtime dependencies.
+
+## Quick start
+
+Compose your schema with `Yaml.schema` to decode YAML straight into a validated domain value:
+
+```ts
+import { Yaml } from "@effected/yaml";
+import { Effect, Schema } from "effect";
+
+const Config = Schema.Struct({ port: Schema.Number });
+const ConfigFromYaml = Yaml.schema(Config);
+
+const program = Effect.gen(function* () {
+  return yield* Schema.decodeUnknownEffect(ConfigFromYaml)("port: 3000 # dev server");
+});
+
+Effect.runPromise(program).then(console.log);
+// { port: 3000 }
+```
+
+`Yaml.stringify` goes the other way, failing typed on circular references rather than throwing:
+
+```ts
+import { Yaml } from "@effected/yaml";
+import { Effect } from "effect";
+
+Effect.runPromise(Yaml.stringify({ port: 3000, hosts: ["a", "b"] })).then(console.log);
+// port: 3000
+// hosts:
+// - a
+// - b
+```
+
+## Hostile input fails typed
+
+An alias bomb — nested anchors whose expansion multiplies at every level — is bounded by an expansion budget and surfaces as a `YamlParseError`, not as an out-of-memory kill:
+
+```ts
+import { Yaml } from "@effected/yaml";
+import { Effect } from "effect";
+
+const bomb = [
+  "a: &a [x,x,x,x,x,x,x,x,x]",
+  "b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a]",
+  // ...further levels, each multiplying the one before
+  "z: [*g,*g,*g,*g,*g,*g,*g,*g,*g]",
+].join("\n");
+
+Effect.runPromise(Effect.result(Yaml.parse(bomb))).then(console.log);
+// Failure with YamlParseError, whose `diagnostics` carry:
+// { code: "AliasCountExceeded", message: "Alias expansion exceeded budget of ... nodes" }
+```
+
+Collection nesting past the depth cap behaves the same way, yielding a `NestingDepthExceeded` diagnostic instead of a stack overflow, and `Yaml.stringify` caps the mirror-image recursion when encoding a value back to text. The guarantee is the same everywhere: every fallible entry point carries a real error channel, and nothing reaches your process as a defect.
+
+## Features
+
+- `Yaml.parse` / `Yaml.parseAll` — error-recovery parsing of a single document or a `---`-separated stream into plain values, resolving anchors and aliases and aggregating every diagnostic into one `YamlParseError`.
+- `Yaml.stringify` — serialize a plain value back to YAML, failing typed with `YamlStringifyError` on circular references or on excessively deep nesting.
+- `Yaml.stripComments` — quote-aware comment removal that keeps line numbers stable, or every byte offset stable when given a replacement character.
+- `Yaml.equals` / `Yaml.equalsValue` — semantic equality that ignores comments, whitespace, formatting and mapping key order while keeping sequence order significant.
+- `Yaml.schema` / `Yaml.fromString` / `Yaml.YamlFromString` / `Yaml.allFromString` — string→domain schema factories that decode a single document or a whole stream into a validated Effect `Schema` value.
+- `YamlNode` — an offset-preserving AST (`YamlScalar`, `YamlMap`, `YamlSeq`, `YamlPair`, `YamlAlias`) for locating and reading nodes by position or path.
+- `YamlDocument` — the full parsed AST plus the recovered `errors` and `warnings` arrays, so a partially valid document is still inspectable.
+- `YamlEdit` / `YamlFormat` — compute byte-minimal edit arrays for formatting and path-based modification, so a change preserves every comment and byte you did not touch.
+- `YamlVisitor` — walk a parsed document as a `Stream` of a tagged-enum event union, with `Stream.take` early termination on large inputs.
+- `YamlParseError` / `YamlStringifyError` / `YamlModificationError` — tagged errors carrying structured, positional `YamlDiagnostic` arrays rather than opaque messages.
+
+## License
+
+[MIT](LICENSE)

package/Yaml.js

@@ -0,0 +1,414 @@
+import { AliasExpansionBudgetExceeded, CollectionStyle, ScalarStyle, nodeToJsValue } from "./YamlNode.js";
+import { buildAnchorMap } from "./internal/composer/anchors.js";
+import { composeAllDocuments, composeFirstDocument } from "./internal/composer/document.js";
+import { isFatalCode } from "./internal/diagnostics.js";
+import { StringifyDepthExceeded, StringifyFailure, stringifyValue } from "./internal/stringifier.js";
+import { YamlDiagnostic } from "./YamlDiagnostic.js";
+import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+
+//#region src/Yaml.ts
+/**
+* Options controlling parse behavior. All fields are omissible; absent fields
+* resolve to `strict` `true`, `maxAliasCount` `100` (the alias-based
+* denial-of-service guard) and `uniqueKeys` `true` (duplicate mapping keys
+* are errors).
+*
+* @public
+*/
+var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
+	strict: Schema.optionalKey(Schema.Boolean),
+	maxAliasCount: Schema.optionalKey(Schema.Number),
+	uniqueKeys: Schema.optionalKey(Schema.Boolean)
+}) {};
+/**
+* Options controlling stringify behavior. All fields are omissible; absent
+* fields resolve to `indent` `2`, `lineWidth` `80`, `defaultScalarStyle`
+* `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
+* `finalNewline` `true` and `forceDefaultStyles` `false`.
+*
+* @public
+*/
+var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
+	indent: Schema.optionalKey(Schema.Number),
+	lineWidth: Schema.optionalKey(Schema.Number),
+	defaultScalarStyle: Schema.optionalKey(ScalarStyle),
+	defaultCollectionStyle: Schema.optionalKey(CollectionStyle),
+	sortKeys: Schema.optionalKey(Schema.Boolean),
+	finalNewline: Schema.optionalKey(Schema.Boolean),
+	forceDefaultStyles: Schema.optionalKey(Schema.Boolean)
+}) {};
+/**
+* Error-recovery parse failure: aggregates every fatal {@link YamlDiagnostic}
+* encountered, so a single failure reports the whole batch. Raised by
+* {@link Yaml.parse}, {@link Yaml.parseAll}, `YamlDocument.parse`/`parseAll`
+* and the decode direction of the schema factories.
+*
+* @public
+*/
+var YamlParseError = class extends Schema.TaggedErrorClass()("YamlParseError", {
+	diagnostics: Schema.Array(YamlDiagnostic),
+	input: Schema.String
+}) {
+	get message() {
+		const count = this.diagnostics.length;
+		const summary = this.diagnostics.map((d) => `${d.code} at ${d.line}:${d.character}`).join("; ");
+		return `YAML parse failed with ${count} error${count === 1 ? "" : "s"}: ${summary}`;
+	}
+};
+/**
+* Stringification failure (the circular-reference guard), carrying structured
+* {@link YamlDiagnostic} entries and the offending value. Raised by
+* {@link Yaml.stringify}, `YamlDocument#stringify` and the encode direction of
+* the schema factories.
+*
+* @public
+*/
+var YamlStringifyError = class extends Schema.TaggedErrorClass()("YamlStringifyError", {
+	diagnostics: Schema.Array(YamlDiagnostic),
+	value: Schema.Unknown
+}) {
+	get message() {
+		return `YAML stringify failed: ${this.diagnostics.map((d) => d.message).join("; ")}`;
+	}
+};
+const toParseInput = (options) => options === void 0 ? {} : {
+	strict: options.strict,
+	maxAliasCount: options.maxAliasCount,
+	uniqueKeys: options.uniqueKeys
+};
+const toStringifyInput = (options) => options === void 0 ? {} : {
+	indent: options.indent,
+	lineWidth: options.lineWidth,
+	defaultScalarStyle: options.defaultScalarStyle,
+	defaultCollectionStyle: options.defaultCollectionStyle,
+	sortKeys: options.sortKeys,
+	finalNewline: options.finalNewline,
+	forceDefaultStyles: options.forceDefaultStyles
+};
+const toDiagnostics = (text, records) => records.map((r) => YamlDiagnostic.fromRaw(r, text));
+/**
+* Collect the raw diagnostics that make a composed document a parse failure:
+* every fatal-code error, plus DuplicateKey warnings promoted to errors when
+* `uniqueKeys` is in force (the v3 `parse` contract). Order preserved:
+* fatals first, then promotions.
+*/
+const failureRecords = (doc, uniqueKeys) => {
+	const fatal = doc.errors.filter((e) => isFatalCode(e.code));
+	if (fatal.length > 0) return fatal;
+	return uniqueKeys ? doc.warnings.filter((w) => w.code === "DuplicateKey") : [];
+};
+/**
+* Extract a document's plain-JS value with an alias-expansion budget derived
+* from `maxAliasCount`, materializing a "billion laughs" blow-up as a typed
+* fatal {@link YamlParseError} (`AliasCountExceeded`) instead of letting the
+* heap-exhausting expansion escape as an unhandled defect.
+*/
+const extractDocumentValue = (contents, anchors, maxAliasCount, text) => Effect.try({
+	try: () => nodeToJsValue(contents, anchors, maxAliasCount),
+	catch: (defect) => {
+		if (defect instanceof AliasExpansionBudgetExceeded) return new YamlParseError({
+			diagnostics: [YamlDiagnostic.make({
+				code: "AliasCountExceeded",
+				message: defect.message,
+				offset: 0,
+				length: 0,
+				line: 0,
+				character: 0
+			})],
+			input: text
+		});
+		throw defect;
+	}
+});
+const stringifyOrFail = (value, options) => Effect.try({
+	try: () => stringifyValue(value, toStringifyInput(options)),
+	catch: (defect) => {
+		if (defect instanceof StringifyFailure) return new YamlStringifyError({
+			diagnostics: [YamlDiagnostic.make({
+				code: "CircularReference",
+				message: defect.reason,
+				offset: 0,
+				length: 0,
+				line: 0,
+				character: 0
+			})],
+			value
+		});
+		if (defect instanceof StringifyDepthExceeded) return new YamlStringifyError({
+			diagnostics: [YamlDiagnostic.make({
+				code: "NestingDepthExceeded",
+				message: defect.message,
+				offset: 0,
+				length: 0,
+				line: 0,
+				character: 0
+			})],
+			value
+		});
+		throw defect;
+	}
+});
+/**
+* Static entry points for YAML parsing, stringification, comment stripping,
+* semantic equality and the schema factories. Not instantiable.
+*
+* @remarks
+* `parse`/`parseAll`/`stringify` and the schema factories carry real typed
+* error channels — including the hardening guards (an alias-expansion budget
+* on decode, a nesting-depth cap on encode) that keep malformed or
+* adversarial input on the typed channel instead of surfacing as an unhandled
+* defect. `stripComments`/`equals`/`equalsValue` are pure total functions.
+*
+* @example
+* ```ts
+* import { Yaml } from "@effected/yaml";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const value = yield* Yaml.parse("name: Alice\nage: 30");
+*   return value; // { name: "Alice", age: 30 }
+* });
+* ```
+*
+* @public
+*/
+var Yaml = class Yaml {
+	constructor() {}
+	/**
+	* Parse a single YAML document into a plain JavaScript value, resolving
+	* anchors and aliases. Error-recovery parsing: collects every fatal
+	* diagnostic and fails once with the aggregate {@link YamlParseError}.
+	* Returns `unknown`, never `any`.
+	*
+	* A "billion laughs" alias-expansion blow-up (an alias chain whose
+	* resolved size grows exponentially relative to `maxAliasCount`) also
+	* fails through {@link YamlParseError} with an `AliasCountExceeded`
+	* diagnostic, never as an unhandled defect.
+	*/
+	static parse = Effect.fn("Yaml.parse")(function* (text, options) {
+		const doc = composeFirstDocument(text, toParseInput(options));
+		const failures = failureRecords(doc, options?.uniqueKeys ?? true);
+		if (failures.length > 0) return yield* new YamlParseError({
+			diagnostics: toDiagnostics(text, failures),
+			input: text
+		});
+		const anchors = /* @__PURE__ */ new Map();
+		return yield* extractDocumentValue(doc.contents, anchors, options?.maxAliasCount ?? 100, text);
+	});
+	/**
+	* Parse a multi-document YAML stream into an array of plain JavaScript
+	* values (one per document, in order). Any fatal diagnostic in any
+	* document — or a stream-level directive-placement error — fails the
+	* whole Effect with the aggregate {@link YamlParseError}.
+	*
+	* A "billion laughs" alias-expansion blow-up in any document also fails
+	* through {@link YamlParseError} with an `AliasCountExceeded` diagnostic,
+	* never as an unhandled defect.
+	*/
+	static parseAll = Effect.fn("Yaml.parseAll")(function* (text, options) {
+		const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
+		const uniqueKeys = options?.uniqueKeys ?? true;
+		const failures = [...streamErrors.filter((e) => e.code === "InvalidDirective"), ...documents.flatMap((d) => failureRecords(d, uniqueKeys))];
+		if (failures.length > 0) return yield* new YamlParseError({
+			diagnostics: toDiagnostics(text, failures),
+			input: text
+		});
+		const maxAliasCount = options?.maxAliasCount ?? 100;
+		const values = [];
+		for (const d of documents) {
+			const anchors = buildAnchorMap(d.contents);
+			values.push(yield* extractDocumentValue(d.contents, anchors, maxAliasCount, text));
+		}
+		return values;
+	});
+	/**
+	* Stringify a plain JavaScript value as YAML. Fails with
+	* {@link YamlStringifyError} on circular references (`CircularReference`)
+	* or on a value nested deeper than the stringifier's recursion budget
+	* (`NestingDepthExceeded`) — both surface through the typed error channel
+	* rather than as an unhandled stack-overflow defect.
+	*/
+	static stringify = Effect.fn("Yaml.stringify")(function* (value, options) {
+		return yield* stringifyOrFail(value, options);
+	});
+	/**
+	* Strip comments from YAML text. Without `replaceCh`, comment characters
+	* are removed (line breaks are kept, so line numbers stay stable); with a
+	* `replaceCh` (e.g. `" "`), each comment character is replaced instead,
+	* keeping all offsets stable. Quote-aware: `#` inside quoted scalars is
+	* content, not a comment. Pure and total.
+	*/
+	static stripComments(text, replaceCh) {
+		let result = "";
+		let i = 0;
+		let inComment = false;
+		let inSingleQuote = false;
+		let inDoubleQuote = false;
+		while (i < text.length) {
+			const ch = text[i];
+			if (inComment) {
+				if (ch === "\n") {
+					inComment = false;
+					result += ch;
+				} else if (replaceCh !== void 0) result += replaceCh;
+			} else if (inDoubleQuote) {
+				result += ch;
+				if (ch === "\\" && i + 1 < text.length) {
+					i++;
+					result += text[i];
+				} else if (ch === "\"") inDoubleQuote = false;
+			} else if (inSingleQuote) {
+				result += ch;
+				if (ch === "'" && i + 1 < text.length && text[i + 1] === "'") {
+					i++;
+					result += text[i];
+				} else if (ch === "'") inSingleQuote = false;
+			} else if (ch === "\"") {
+				inDoubleQuote = true;
+				result += ch;
+			} else if (ch === "'") {
+				inSingleQuote = true;
+				result += ch;
+			} else if (ch === "#") {
+				const prev = i > 0 ? text[i - 1] : "\n";
+				if (prev === " " || prev === "	" || prev === "\n" || i === 0) {
+					inComment = true;
+					if (replaceCh !== void 0) result += replaceCh;
+				} else result += ch;
+			} else result += ch;
+			i++;
+		}
+		return result;
+	}
+	/**
+	* Compare two YAML strings for semantic equality: comments, whitespace,
+	* formatting and mapping key order are ignored; sequence order is
+	* significant. Malformed input is never equal to anything — parse errors
+	* (or duplicate keys) on either side yield `false` rather than comparing
+	* recovery-parser artifacts. Pure and total.
+	*/
+	static equals(a, b) {
+		const va = parseForEquality(a);
+		const vb = parseForEquality(b);
+		if (va.malformed || vb.malformed) return false;
+		return deepEqualValues(va.value, vb.value);
+	}
+	/**
+	* Compare a YAML string against an existing JavaScript value with the
+	* same semantics as {@link Yaml.equals}: malformed `text` yields `false`.
+	* Pure and total.
+	*/
+	static equalsValue(text, value) {
+		const v = parseForEquality(text);
+		if (v.malformed) return false;
+		return deepEqualValues(v.value, value);
+	}
+	/**
+	* A `Schema<unknown, string>` decoding a single YAML document with the
+	* given `options` (defaults when omitted) and encoding values back to
+	* YAML text with default stringify options.
+	*
+	* Schema-producing: each call returns a fresh schema whose derivation
+	* caches are not shared across calls. Bind the result to a `const` on hot
+	* paths; for the default-options case use {@link Yaml.YamlFromString}.
+	*/
+	static fromString(options) {
+		return Schema.String.pipe(Schema.decodeTo(Schema.Unknown, SchemaTransformation.transformOrFail({
+			decode: (input) => Yaml.parse(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(input), { message: error.message }))),
+			encode: (value) => stringifyOrFail(value).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(value), { message: error.message })))
+		})));
+	}
+	/**
+	* The zero-config `Schema<unknown, string>` — `Yaml.fromString()` with
+	* default options, pre-bound so the common case needs no memoization
+	* discipline.
+	*/
+	static YamlFromString = Yaml.fromString();
+	/**
+	* A `Schema<ReadonlyArray<unknown>, string>` decoding a multi-document
+	* YAML stream into one value per document, and encoding an array of
+	* values back into a `---`-separated stream.
+	*
+	* Schema-producing: bind the result to a `const` on hot paths (see
+	* {@link Yaml.fromString}).
+	*/
+	static allFromString(options) {
+		return Schema.String.pipe(Schema.decodeTo(Schema.Array(Schema.Unknown), SchemaTransformation.transformOrFail({
+			decode: (input) => Yaml.parseAll(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(input), { message: error.message }))),
+			encode: (values) => Effect.gen(function* () {
+				if (values.length === 0) return "";
+				const parts = [];
+				for (let index = 0; index < values.length; index++) {
+					const yaml = yield* stringifyOrFail(values[index]).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(values), { message: error.message })));
+					parts.push(index > 0 ? `---\n${yaml}` : yaml);
+				}
+				return parts.join("");
+			})
+		})));
+	}
+	/**
+	* Compose {@link Yaml.fromString} with a target schema, yielding a
+	* `Schema<A, string>` that decodes YAML straight into a validated domain
+	* value — the single best consumer-facing feature of the library. The
+	* target's decoding/encoding service requirements flow through.
+	*
+	* Schema-producing: bind the result to a `const` on hot paths (see
+	* {@link Yaml.fromString}).
+	*/
+	static schema(target, options) {
+		return Yaml.fromString(options).pipe(Schema.decodeTo(target));
+	}
+};
+/**
+* Parse for `equals`/`equalsValue`: any recorded error — fatal or not — or a
+* DuplicateKey warning marks the input malformed (never equal to anything).
+*/
+function parseForEquality(text) {
+	const doc = composeFirstDocument(text, {});
+	if (doc.errors.length > 0 || doc.warnings.some((w) => w.code === "DuplicateKey")) return {
+		malformed: true,
+		value: void 0
+	};
+	const anchors = /* @__PURE__ */ new Map();
+	try {
+		return {
+			malformed: false,
+			value: nodeToJsValue(doc.contents, anchors, 100)
+		};
+	} catch (err) {
+		if (err instanceof AliasExpansionBudgetExceeded) return {
+			malformed: true,
+			value: void 0
+		};
+		throw err;
+	}
+}
+/**
+* Deep structural equality over plain values: NaN equals NaN, mapping key
+* order ignored, sequence order significant.
+*/
+function deepEqualValues(a, b) {
+	if (a === b) return true;
+	if (typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b)) return true;
+	if (a === null || b === null) return false;
+	if (typeof a !== typeof b) return false;
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b) || a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!deepEqualValues(a[i], b[i])) return false;
+		return true;
+	}
+	if (Array.isArray(b)) return false;
+	if (typeof a === "object" && typeof b === "object") {
+		const aObj = a;
+		const bObj = b;
+		const aKeys = Object.keys(aObj);
+		const bKeys = Object.keys(bObj);
+		if (aKeys.length !== bKeys.length) return false;
+		for (const key of aKeys) if (!Object.hasOwn(bObj, key) || !deepEqualValues(aObj[key], bObj[key])) return false;
+		return true;
+	}
+	return false;
+}
+
+//#endregion
+export { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions };

package/YamlDiagnostic.js

@@ -0,0 +1,126 @@
+import { YAML_COMPOSE_ERROR_CODES, YAML_LEX_ERROR_CODES, YAML_MODIFY_ERROR_CODES, YAML_PARSE_ERROR_CODES, YAML_STRINGIFY_ERROR_CODES, isFatalCode } from "./internal/diagnostics.js";
+import { Schema } from "effect";
+
+//#region src/YamlDiagnostic.ts
+/**
+* Error codes emitted by the lexer stage.
+*
+* @public
+*/
+const YamlLexErrorCode = Schema.Literals(YAML_LEX_ERROR_CODES);
+/**
+* Error codes emitted by the CST-parser stage.
+*
+* @public
+*/
+const YamlParseErrorCode = Schema.Literals(YAML_PARSE_ERROR_CODES);
+/**
+* Error codes emitted by the composer stage.
+*
+* @public
+*/
+const YamlComposerErrorCode = Schema.Literals(YAML_COMPOSE_ERROR_CODES);
+/**
+* Error codes emitted by the stringifier (the circular-reference guard).
+*
+* @public
+*/
+const YamlStringifyErrorCode = Schema.Literals(YAML_STRINGIFY_ERROR_CODES);
+/**
+* Error codes emitted by `YamlFormat.modify`'s path navigation against an
+* already-composed AST — not raised by the parser/composer/stringifier.
+*
+* @public
+*/
+const YamlModifyErrorCode = Schema.Literals(YAML_MODIFY_ERROR_CODES);
+/**
+* Union of all YAML error codes across all pipeline stages. Stage
+* discrimination lives here (in the code), not in separate error classes.
+*
+* @public
+*/
+const YamlErrorCode = Schema.Union([
+	YamlLexErrorCode,
+	YamlParseErrorCode,
+	YamlComposerErrorCode,
+	YamlStringifyErrorCode,
+	YamlModifyErrorCode
+]);
+/**
+* One structured diagnostic: its {@link (YamlErrorCode:type)}, a
+* human-readable `message`, and its exact position (`offset`/`length`, plus
+* zero-based `line`/`character`). Used for both errors and warnings-as-data;
+* fatality is a property of the code — see {@link YamlDiagnostic.isFatal}.
+*
+* @remarks
+* The five-field positional core (`code`/`offset`/`length`/`line`/`character`)
+* is structurally identical to `@effected/jsonc`'s parse-error detail shape;
+* `message` is this package's additive extra.
+*
+* @public
+*/
+var YamlDiagnostic = class YamlDiagnostic extends Schema.Class("YamlDiagnostic")({
+	code: YamlErrorCode,
+	message: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number,
+	line: Schema.Number,
+	character: Schema.Number
+}) {
+	/**
+	* The single fatal-code predicate: whether diagnostics with this code
+	* abort a parse (vs. being recoverable warnings-as-data). Declared once,
+	* as a property of the code — replacing the v3 source's three
+	* subtly-differing inline fatal lists.
+	*/
+	static isFatal(code) {
+		return isFatalCode(code);
+	}
+	/**
+	* Materialize a raw engine diagnostic record into a `YamlDiagnostic`,
+	* deriving `line`/`character` from `offset` against the source `text`.
+	* Advanced — the parse/stringify entry points call this for you.
+	*/
+	static fromRaw(raw, text) {
+		const { line, character } = lineChar(text, raw.offset);
+		return YamlDiagnostic.make({
+			code: raw.code,
+			message: raw.message,
+			offset: raw.offset,
+			length: raw.length,
+			line,
+			character
+		});
+	}
+};
+/**
+* Compute the zero-based line/character position of `offset` within `text`.
+* Recognizes `\n`, `\r`, `\r\n`, LS and PS as line breaks, matching the
+* jsonc counterpart so positions are codec-generic.
+*/
+function lineChar(text, offset) {
+	let line = 0;
+	let lineStart = 0;
+	const limit = Math.min(offset, text.length);
+	for (let i = 0; i < limit; i++) {
+		const ch = text.charCodeAt(i);
+		if (ch === 10) {
+			line++;
+			lineStart = i + 1;
+		} else if (ch === 13) {
+			if (i + 1 < text.length && text.charCodeAt(i + 1) === 10) i++;
+			line++;
+			lineStart = i + 1;
+		} else if (ch === 8232 || ch === 8233) {
+			line++;
+			lineStart = i + 1;
+		}
+	}
+	return {
+		line,
+		character: offset - lineStart
+	};
+}
+
+//#endregion
+export { YamlComposerErrorCode, YamlDiagnostic, YamlErrorCode, YamlLexErrorCode, YamlModifyErrorCode, YamlParseErrorCode, YamlStringifyErrorCode };