@effected/yaml 0.1.0

package/YamlDocument.js

@@ -0,0 +1,181 @@
+import { YamlNode } from "./YamlNode.js";
+import { composeAllDocuments, composeFirstDocument } from "./internal/composer/document.js";
+import { isFatalCode } from "./internal/diagnostics.js";
+import { StringifyDepthExceeded, StringifyFailure, stringifyDocument } from "./internal/stringifier.js";
+import { YamlDiagnostic } from "./YamlDiagnostic.js";
+import { YamlParseError, YamlStringifyError } from "./Yaml.js";
+import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+
+//#region src/YamlDocument.ts
+/**
+* A YAML directive appearing before a document (e.g. `%YAML 1.2` or
+* `%TAG ! tag:example.com,2000:`). `"YAML"` and `"TAG"` are the YAML 1.2
+* spec-defined directives; any other name is a reserved directive preserved
+* for round-trip fidelity.
+*
+* @public
+*/
+var YamlDirective = class extends Schema.Class("YamlDirective")({
+	name: Schema.String,
+	parameters: Schema.Array(Schema.String)
+}) {};
+/**
+* A parsed YAML document: the root {@link (YamlNode:type)} (or `null` when
+* empty), recovered `errors` and `warnings` as {@link YamlDiagnostic} data,
+* the {@link YamlDirective} list, an optional document-level comment, and the
+* `---`/`...` framing flags (absent flags read as `false`).
+*
+* Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
+* synthetic documents.
+*
+* @public
+*/
+var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
+	contents: Schema.NullOr(Schema.suspend(() => YamlNode)),
+	errors: Schema.Array(YamlDiagnostic),
+	warnings: Schema.Array(YamlDiagnostic),
+	directives: Schema.Array(YamlDirective),
+	comment: Schema.optionalKey(Schema.String),
+	hasDocumentStart: Schema.optionalKey(Schema.Boolean),
+	hasDocumentEnd: Schema.optionalKey(Schema.Boolean),
+	hasDocumentStartTab: Schema.optionalKey(Schema.Boolean)
+}) {
+	/**
+	* Parse a single YAML document, keeping the full AST, directives and
+	* recovered diagnostics. Fails with the aggregate {@link YamlParseError}
+	* when any fatal-code diagnostic is present; non-fatal diagnostics are
+	* data on the returned document.
+	*/
+	static parse = Effect.fn("YamlDocument.parse")(function* (text, options) {
+		const raw = composeFirstDocument(text, toParseInput(options));
+		const fatal = raw.errors.filter((e) => isFatalCode(e.code));
+		if (fatal.length > 0) return yield* new YamlParseError({
+			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
+			input: text
+		});
+		return fromRawDocument(raw, text);
+	});
+	/**
+	* Parse a multi-document YAML stream into one {@link YamlDocument} per
+	* document. Any fatal diagnostic in any document — or a stream-level
+	* directive-placement error — fails the whole Effect.
+	*/
+	static parseAll = Effect.fn("YamlDocument.parseAll")(function* (text, options) {
+		const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
+		const fatal = [...streamErrors.filter((e) => e.code === "InvalidDirective"), ...documents.flatMap((d) => d.errors.filter((e) => isFatalCode(e.code)))];
+		if (fatal.length > 0) return yield* new YamlParseError({
+			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
+			input: text
+		});
+		return documents.map((raw) => fromRawDocument(raw, text));
+	});
+	/**
+	* A `Schema<YamlDocument, string>` decoding YAML text into a full
+	* document (AST, directives, diagnostics) and encoding a document back to
+	* YAML text.
+	*
+	* 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.
+	*/
+	static schema(options) {
+		return Schema.String.pipe(Schema.decodeTo(Schema.instanceOf(YamlDocument), SchemaTransformation.transformOrFail({
+			decode: (input) => YamlDocument.parse(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(input), { message: error.message }))),
+			encode: (doc) => doc.stringify().pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue(Option.some(doc), { message: error.message })))
+		})));
+	}
+	/**
+	* Stringify this document (contents, directives and framing) as YAML.
+	* Fails with {@link YamlStringifyError} on circular references introduced
+	* into a synthetic AST (`CircularReference`) or on a synthetic AST nested
+	* deeper than the stringifier's recursion budget (`NestingDepthExceeded`)
+	* — both surface through the typed error channel rather than as an
+	* unhandled stack-overflow defect.
+	*/
+	stringify(options) {
+		return Effect.try({
+			try: () => stringifyDocument(toRawDocument(this), 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: this
+				});
+				if (defect instanceof StringifyDepthExceeded) return new YamlStringifyError({
+					diagnostics: [YamlDiagnostic.make({
+						code: "NestingDepthExceeded",
+						message: defect.message,
+						offset: 0,
+						length: 0,
+						line: 0,
+						character: 0
+					})],
+					value: this
+				});
+				throw defect;
+			}
+		});
+	}
+	/**
+	* Reconstruct the plain JavaScript value of this document's contents,
+	* resolving anchors and aliases. `null` for an empty document. Pure and
+	* total.
+	*/
+	toValue() {
+		if (this.contents === null) return null;
+		const anchors = /* @__PURE__ */ new Map();
+		return this.contents.toValue(anchors);
+	}
+};
+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
+};
+/** Materialize a raw engine document into the public class. */
+function fromRawDocument(raw, text) {
+	return new YamlDocument({
+		contents: raw.contents,
+		errors: raw.errors.map((e) => YamlDiagnostic.fromRaw(e, text)),
+		warnings: raw.warnings.map((w) => YamlDiagnostic.fromRaw(w, text)),
+		directives: raw.directives.map((d) => new YamlDirective({
+			name: d.name,
+			parameters: d.parameters
+		})),
+		...raw.comment !== void 0 ? { comment: raw.comment } : {},
+		hasDocumentStart: raw.hasDocumentStart,
+		hasDocumentEnd: raw.hasDocumentEnd,
+		hasDocumentStartTab: raw.hasDocumentStartTab
+	});
+}
+/** Project the public class back onto the raw shape the engine consumes. */
+function toRawDocument(doc) {
+	return {
+		contents: doc.contents,
+		errors: [],
+		warnings: [],
+		directives: doc.directives,
+		...doc.comment !== void 0 ? { comment: doc.comment } : {},
+		hasDocumentStart: doc.hasDocumentStart ?? false,
+		hasDocumentEnd: doc.hasDocumentEnd ?? false,
+		hasDocumentStartTab: doc.hasDocumentStartTab ?? false
+	};
+}
+
+//#endregion
+export { YamlDirective, YamlDocument };

package/YamlEdit.js

@@ -0,0 +1,45 @@
+import { Schema } from "effect";
+
+//#region src/YamlEdit.ts
+/**
+* A range within a YAML document, expressed as a zero-based character
+* `offset` and a `length` in UTF-16 code units. Pass to `YamlFormat.format`
+* to restrict formatting to a region.
+*
+* @public
+*/
+var YamlRange = class extends Schema.Class("YamlRange")({
+	offset: Schema.Number,
+	length: Schema.Number
+}) {};
+/**
+* A non-mutating text edit: replace the span `[offset, offset + length)` with
+* `content`. Set `length` to `0` to insert, `content` to `""` to delete.
+*
+* @remarks
+* Structurally identical to `@effected/jsonc`'s edit shape (same field names,
+* types and semantics) per the jsonc/yaml parity convention, so consumer code
+* can be written once over "a document codec's Edit/Range/Path".
+*
+* @public
+*/
+var YamlEdit = class extends Schema.Class("YamlEdit")({
+	offset: Schema.Number,
+	length: Schema.Number,
+	content: Schema.String
+}) {
+	/**
+	* Apply `edits` to `text`, producing a new string. Edits are applied in
+	* reverse-offset order so earlier offsets stay valid; the input `edits`
+	* array is not mutated. Pure and total.
+	*/
+	static applyAll(text, edits) {
+		const sorted = [...edits].sort((a, b) => b.offset - a.offset);
+		let result = text;
+		for (const edit of sorted) result = result.substring(0, edit.offset) + edit.content + result.substring(edit.offset + edit.length);
+		return result;
+	}
+};
+
+//#endregion
+export { YamlEdit, YamlRange };

package/YamlFormat.js

@@ -0,0 +1,309 @@
+import { YamlMap, YamlPair, YamlScalar, YamlSeq } from "./YamlNode.js";
+import { composeFirstDocument } from "./internal/composer/document.js";
+import { isFatalCode } from "./internal/diagnostics.js";
+import { stringifyDocument, stripNodeComments } from "./internal/stringifier.js";
+import { YamlDiagnostic } from "./YamlDiagnostic.js";
+import { YamlStringifyOptions } from "./Yaml.js";
+import { YamlEdit, YamlRange } from "./YamlEdit.js";
+import { computeEdits } from "./internal/diff.js";
+import { Effect, Schema } from "effect";
+
+//#region src/YamlFormat.ts
+/**
+* Options controlling formatting behavior: every {@link YamlStringifyOptions}
+* field (derived, not hand-duplicated) plus `preserveComments` (default
+* `true`) and `range` (restrict edits to a region; see the module-level
+* remarks on the `range` parameter vs. this field).
+*
+* @public
+*/
+var YamlFormattingOptions = class extends Schema.Class("YamlFormattingOptions")({
+	...YamlStringifyOptions.fields,
+	preserveComments: Schema.optionalKey(Schema.Boolean),
+	range: Schema.optionalKey(YamlRange)
+}) {};
+/**
+* Raised when `YamlFormat.modify` cannot navigate the requested path against
+* the composed AST (a structural mismatch) or the source fails to parse.
+* Carries structured {@link YamlDiagnostic} entries — never a collapsed
+* `reason` string (the structure-preserving-errors house rule).
+*
+* @public
+*/
+var YamlModificationError = class extends Schema.TaggedErrorClass()("YamlModificationError", {
+	path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
+	diagnostics: Schema.Array(YamlDiagnostic)
+}) {
+	get message() {
+		const summary = this.diagnostics.map((d) => d.message).join("; ");
+		return `Modification failed at path [${this.path.join(", ")}]: ${summary}`;
+	}
+};
+/**
+* Thrown by the pure AST-navigation helpers on a structural mismatch.
+* `modify` catches this and materializes {@link YamlModificationError}.
+*/
+var ModifyFailure = class extends Error {
+	code;
+	offset;
+	length;
+	constructor(code, message, offset, length) {
+		super(message);
+		this.name = "ModifyFailure";
+		this.code = code;
+		this.offset = offset;
+		this.length = length;
+	}
+};
+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
+};
+/** Normalize a `format`-positional range and the options-bag fallback into one plain shape (or `undefined`). */
+function resolveRange(positional, fromOptions) {
+	const range = positional ?? fromOptions;
+	return range === void 0 ? void 0 : {
+		offset: range.offset,
+		length: range.length
+	};
+}
+/** Copy only the defined entries of `fields` — never emits an explicit `undefined` into a v4 `optionalKey` field. */
+function definedFields(fields) {
+	const out = {};
+	for (const key of Object.keys(fields)) if (fields[key] !== void 0) out[key] = fields[key];
+	return out;
+}
+/**
+* Format a document via the parse → stringify round-trip and diff the
+* output against the source, returning `undefined` when the input has a
+* fatal parse error (never corrupt malformed input).
+*/
+function formatDocument(text, options) {
+	const doc = composeFirstDocument(text, {});
+	if (doc.errors.some((e) => isFatalCode(e.code))) return void 0;
+	const preserveComments = options?.preserveComments ?? true;
+	return stringifyDocument({
+		contents: !preserveComments && doc.contents !== null ? stripNodeComments(doc.contents) : doc.contents,
+		errors: doc.errors,
+		warnings: doc.warnings,
+		directives: doc.directives,
+		...preserveComments ? definedFields({ comment: doc.comment }) : {},
+		hasDocumentStart: doc.hasDocumentStart,
+		hasDocumentEnd: doc.hasDocumentEnd,
+		hasDocumentStartTab: doc.hasDocumentStartTab
+	}, toStringifyInput(options));
+}
+/** Convert a plain JS scalar value into a synthetic `YamlScalar` (offset/length are irrelevant — immediately re-stringified). */
+function jsValueToNode(value) {
+	return YamlScalar.make({
+		value,
+		style: "plain",
+		offset: 0,
+		length: 0
+	});
+}
+function modifyDocument(doc, path, value) {
+	if (path.length === 0) return value === void 0 ? null : jsValueToNode(value);
+	if (doc.contents === null) throw new ModifyFailure("EmptyDocument", "Cannot navigate path in empty document", 0, 0);
+	return modifyNode(doc.contents, path, 0, value);
+}
+function modifyNode(node, path, depth, value) {
+	const segment = path[depth];
+	const isLast = depth === path.length - 1;
+	if (node instanceof YamlMap) {
+		const pairIndex = node.items.findIndex((pair) => pair.key instanceof YamlScalar && pair.key.value === segment);
+		if (isLast) {
+			if (value === void 0) {
+				if (pairIndex < 0) return node;
+				const newItems = [...node.items];
+				newItems.splice(pairIndex, 1);
+				return rebuildMap(node, newItems);
+			}
+			const newValueNode = jsValueToNode(value);
+			if (pairIndex >= 0) {
+				const newItems = [...node.items];
+				const oldPair = newItems[pairIndex];
+				newItems[pairIndex] = YamlPair.make({
+					key: oldPair.key,
+					value: newValueNode,
+					...definedFields({ comment: oldPair.comment })
+				});
+				return rebuildMap(node, newItems);
+			}
+			const keyNode = YamlScalar.make({
+				value: String(segment),
+				style: "plain",
+				offset: 0,
+				length: 0
+			});
+			const newPair = YamlPair.make({
+				key: keyNode,
+				value: newValueNode
+			});
+			return rebuildMap(node, [...node.items, newPair]);
+		}
+		if (pairIndex < 0) throw new ModifyFailure("PathNotFound", `Key "${String(segment)}" not found in mapping`, node.offset, node.length);
+		const pair = node.items[pairIndex];
+		if (pair.value === null) throw new ModifyFailure("PathNotFound", `Value at key "${String(segment)}" is null`, node.offset, node.length);
+		const newValue = modifyNode(pair.value, path, depth + 1, value);
+		const newItems = [...node.items];
+		newItems[pairIndex] = YamlPair.make({
+			key: pair.key,
+			value: newValue,
+			...definedFields({ comment: pair.comment })
+		});
+		return rebuildMap(node, newItems);
+	}
+	if (node instanceof YamlSeq) {
+		const idx = typeof segment === "number" ? segment : Number(segment);
+		if (Number.isNaN(idx) || idx < 0) throw new ModifyFailure("InvalidIndex", `Invalid sequence index: ${String(segment)}`, node.offset, node.length);
+		if (isLast) {
+			const newItems = [...node.items];
+			if (value === void 0) {
+				if (idx < newItems.length) newItems.splice(idx, 1);
+			} else if (idx < newItems.length) newItems[idx] = jsValueToNode(value);
+			else newItems.push(jsValueToNode(value));
+			return rebuildSeq(node, newItems);
+		}
+		if (idx >= node.items.length) throw new ModifyFailure("InvalidIndex", `Index ${idx} out of bounds`, node.offset, node.length);
+		const child = node.items[idx];
+		const newChild = modifyNode(child, path, depth + 1, value);
+		const newItems = [...node.items];
+		newItems[idx] = newChild;
+		return rebuildSeq(node, newItems);
+	}
+	throw new ModifyFailure("NotNavigable", `Cannot navigate through ${node._tag} at segment "${String(segment)}"`, node.offset, node.length);
+}
+function rebuildMap(node, items) {
+	return YamlMap.make({
+		items,
+		style: node.style,
+		...definedFields({
+			tag: node.tag,
+			anchor: node.anchor,
+			comment: node.comment,
+			sourceMultiline: node.sourceMultiline
+		}),
+		offset: node.offset,
+		length: node.length
+	});
+}
+function rebuildSeq(node, items) {
+	return YamlSeq.make({
+		items,
+		style: node.style,
+		...definedFields({
+			tag: node.tag,
+			anchor: node.anchor,
+			comment: node.comment,
+			sourceMultiline: node.sourceMultiline
+		}),
+		offset: node.offset,
+		length: node.length
+	});
+}
+/**
+* Formatting and modification statics. Not instantiable.
+*
+* @remarks
+* `format`/`formatToString` are pure and total (edit computation never fails
+* — malformed input yields no edits rather than corrupting the document).
+* `modify`/`modifyToString` carry a real error channel: navigation failures
+* against the composed AST raise {@link YamlModificationError}, which — per
+* the structure-preserving-errors house rule — carries
+* `diagnostics: ReadonlyArray<YamlDiagnostic>`, never a collapsed `reason`
+* string.
+*
+* @public
+*/
+var YamlFormat = class YamlFormat {
+	constructor() {}
+	/**
+	* Compute formatting edits for a YAML document. Non-mutating — apply the
+	* result with `YamlEdit.applyAll` (or use {@link YamlFormat.formatToString}).
+	* Pure and total: malformed input (a fatal parse error) yields `[]` rather
+	* than corrupting the document.
+	*
+	* @remarks
+	* The positional `range` argument takes precedence over
+	* `options?.range` when both are given; either accepts a plain
+	* `{ offset, length }` object as well as a {@link YamlRange} instance, so
+	* callers do not need `YamlRange.make(...)` for the common case.
+	*/
+	static format(text, range, options) {
+		const formatted = formatDocument(text, options);
+		if (formatted === void 0) return [];
+		let edits = computeEdits(text, formatted);
+		const effectiveRange = resolveRange(range, options?.range);
+		if (effectiveRange !== void 0) {
+			const rangeStart = effectiveRange.offset;
+			const rangeEnd = effectiveRange.offset + effectiveRange.length;
+			edits = edits.filter((e) => e.offset >= rangeStart && e.offset + e.length <= rangeEnd);
+		}
+		return edits.map((e) => YamlEdit.make(e));
+	}
+	/**
+	* Format `text` and apply the resulting edits in one step
+	* (`YamlEdit.applyAll ∘ format`). Pure and total.
+	*/
+	static formatToString(text, range, options) {
+		return YamlEdit.applyAll(text, YamlFormat.format(text, range, options));
+	}
+	/**
+	* Compute the edits that insert, replace, or remove a value at `path`.
+	* Passing `value === undefined` removes the target key/element; a missing
+	* insertion target appends after the last pair/element. Only
+	* scalar-compatible values are supported (matching v3 — arbitrary object
+	* graphs are not recursively lowered into AST nodes). Fails with
+	* {@link YamlModificationError} on a fatal parse error or a structural
+	* navigation mismatch.
+	*
+	* @remarks
+	* `options` is a bare {@link YamlStringifyOptions} — it controls only the
+	* internal re-stringify step, not a range (there is no range to restrict
+	* for a path-targeted modification).
+	*/
+	static modify = Effect.fn("YamlFormat.modify")(function* (text, path, value, options) {
+		const doc = composeFirstDocument(text, {});
+		const fatal = doc.errors.filter((e) => isFatalCode(e.code));
+		if (fatal.length > 0) return yield* new YamlModificationError({
+			path,
+			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text))
+		});
+		let newContents;
+		try {
+			newContents = modifyDocument(doc, path, value);
+		} catch (err) {
+			if (!(err instanceof ModifyFailure)) throw err;
+			return yield* new YamlModificationError({
+				path,
+				diagnostics: [YamlDiagnostic.fromRaw({
+					code: err.code,
+					message: err.message,
+					offset: err.offset,
+					length: err.length
+				}, text)]
+			});
+		}
+		return computeEdits(text, stringifyDocument({
+			...doc,
+			contents: newContents
+		}, toStringifyInput(options))).map((e) => YamlEdit.make(e));
+	});
+	/**
+	* Modify `text` and apply the resulting edits in one step
+	* (`YamlEdit.applyAll ∘ modify`).
+	*/
+	static modifyToString = Effect.fn("YamlFormat.modifyToString")(function* (text, path, value, options) {
+		const edits = yield* YamlFormat.modify(text, path, value, options);
+		return YamlEdit.applyAll(text, edits);
+	});
+};
+
+//#endregion
+export { YamlFormat, YamlFormattingOptions, YamlModificationError };