@effected/yaml 0.6.1 → 0.8.0

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.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.
+Zero-dependency YAML 1.2 parsing, editing, formatting and linting 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, read and preserve per-node comments, strip comments, compute byte-minimal edits, format, modify by path, walk a document as a `Stream` of AST events or positioned tokens, lint it against a rule catalog with surgical autofix, 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
@@ -106,18 +106,89 @@ Effect.runPromise(Effect.result(Yaml.parse(bomb))).then(console.log);
 
 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.
 
+## Comments survive an edit
+
+A YAML file a human maintains is mostly explanation, and the explanation is the part a round-trip usually loses. `YamlFormat` computes its edits against the original bytes, so changing a value rewrites the value and leaves the header block, the trailing `# LTS`, the blank line and the indentation where they were. Setting `preserveComments: false` is how you ask for the other behavior:
+
+```ts
+import { YamlFormat, YamlFormattingOptions } from "@effected/yaml";
+
+const source = 'node: "20.11.0" # LTS\n\n# why the port\nport: 3000\n';
+
+console.log(YamlFormat.formatToString(source));
+// node: "20.11.0" # LTS
+//
+// # why the port
+// port: 3000
+
+console.log(YamlFormat.formatToString(source, undefined, YamlFormattingOptions.make({ preserveComments: false })));
+// node: "20.11.0"
+// port: 3000
+```
+
+Comments are readable as data too. `YamlScalar`, `YamlMap`, `YamlSeq` and `YamlPair` each carry `commentBefore` (the own-line block above the node), `comment` (strictly the trailing comment on the node's own line) and `spaceBefore` (a blank line came first); `YamlDocument` adds `commentAfter` for a trailing block, and `YamlVisitor` tags every `Comment` event with `placement: "leading" | "trailing"`.
+
+## Lint and autofix
+
+`YamlLint.run` checks a string against a rule catalog and returns positioned diagnostics; `YamlLint.fix` applies the fixes that can be expressed as surgical edits and returns the fixed text. Both are pure and synchronous. This is the lint engine, not a runner — no file discovery, no config-file loading, nothing written to disk:
+
+```ts
+import { YamlLint, YamlLintConfig } from "@effected/yaml";
+import { Result } from "effect";
+
+const source = "# pinned\nname:  demo   \nport: yes\n";
+
+for (const d of YamlLint.run(source, YamlLint.builtins, YamlLintConfig.default)) {
+  console.log(`${d.line}:${d.character} ${d.severity} ${d.rule} ${d.message}`);
+}
+// 1:5 error colon-spacing Too many spaces after ":" (2 > 1)
+// 1:11 error trailing-spaces Trailing whitespace
+// 2:6 error truthy Truthy value "yes" is not in the allowed spellings
+
+const fixed = YamlLint.fix(source, YamlLint.builtins, YamlLintConfig.default);
+console.log(Result.isSuccess(fixed) ? fixed.success : "fatal parse error — not safely fixable");
+// # pinned
+// name: demo
+// port: "yes"
+```
+
+Positions are zero-based throughout, so the first finding above sits on the second line of the source. Fixes route through `YamlEdit.applyAll` rather than a reformat, so an autofix cannot move a comment it was not asked to touch, and a rule whose repair would need reflowing the document ships without a fix at all. `YamlLintConfig.default` and `YamlLintConfig.relaxed` are the presets; compose your own by spreading a preset's `rules` into `YamlLintConfig.make`. Config validation is rule-aware for the built-in catalog — a misspelled option key on a built-in rule or an attempt to switch off the always-on `parse-validity` rule fails schema validation instead of being quietly ignored — while an unknown (custom) rule id passes through with its options treated as opaque, left for the custom rule itself to validate. Custom rules are plain array concatenation — `YamlLint.run(text, [...YamlLint.builtins, myRule], config)` — and configuring `myRule` in that config works precisely because of the pass-through.
+
+## Migrating from Prettier
+
+`YamlFormat.formatToString(text, undefined, options)` replaces a `prettier --write` over YAML files. The option mapping:
+
+| Prettier | `YamlFormattingOptions` |
+| --- | --- |
+| `tabWidth` | `indent` |
+| `singleQuote` | `quoteStyle: "single" \| "double"` |
+| indented block sequences (always on) | `indentSequences: true` |
+| `printWidth` / `proseWrap` | no analog — see below |
+| comments (best-effort) | `preserveComments: true` (the default) |
+
+Two defaults differ from Prettier's output and are worth setting explicitly. The stringify default is `quoteStyle: "single"` for byte-compatibility with the kit's legacy form, so if you ran Prettier with its own default (`singleQuote: false`), set `quoteStyle: "double"`. Likewise `indentSequences` defaults to `false` — the flat legacy form with the `-` markers at the key's column — while Prettier always indented block sequences one level, so an ex-Prettier consumer almost certainly wants `indentSequences: true`.
+
+One expectation to reset when carrying over `singleQuote`: on the format path, `quoteStyle` governs quotes the stringifier *introduces* — it never re-quotes scalars that already carry quotes in your source. Formatting `a: 'x'` with `quoteStyle: "double"` leaves `'x'` untouched; Prettier would have rewritten it to `"x"`. Existing quote styles are source, and the formatter preserves source. If it looks like the option "does nothing" on an already-quoted corpus, this is why — the same class of format-path inertness as `lineWidth` below.
+
+`printWidth` and `proseWrap` have no analog here: `lineWidth` folding is a value-path feature only (`Yaml.stringify` / `Yaml.stringifyResult`), and the option is deliberately inert on the format path by contract — `YamlFormat` never reflows scalar content (the `lineWidth` TSDoc on `YamlStringifyOptions` pins this). Comments, which Prettier handled best-effort, are preserved exactly by default.
+
+Multi-document streams — a Kubernetes manifest, or the two-document `pnpm-lock.yaml` pnpm 11 writes under `configDependencies` — format whole: every document is re-emitted in order with its own `---`/`...` framing and comments, so no document is ever dropped. Document detection is CST-level, so a `---` inside a block scalar or quoted string is content and formats normally. The formatter leaves input byte-identical rather than corrupting it in exactly two cases: a fatal parse error in any document, and a stream carrying `%YAML`/`%TAG` directives (which the emitter cannot re-emit faithfully). Validate a whole stream with `Yaml.parseAllResult`, which fails typed when any document carries a fatal diagnostic; `YamlFormat.modify` stays single-document, since a path names no particular document of a stream.
+
 ## 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.parseResult` / `Yaml.stringifyResult` — the pure synchronous counterparts, returning a `Result` instead of an `Effect` for config-time callers that cannot await; each runs the same engine call as its `Effect` variant, so the two forms cannot diverge, and a fatal diagnostic, a duplicate key, an alias bomb or a circular reference still fails typed rather than throwing.
+- `Yaml.stringify` — serialize a plain value back to YAML, failing typed with `YamlStringifyError` on circular references or on excessively deep nesting; a block-mapping key too long to render on one line spills into explicit-key form (`? key` / `: value`) so strict parsers still accept the output.
+- `Yaml.parseResult` / `Yaml.parseAllResult` / `Yaml.stringifyResult` — the pure synchronous counterparts, returning a `Result` instead of an `Effect` for config-time callers that cannot await; each runs the same engine call as its `Effect` variant, so the two forms cannot diverge, and a fatal diagnostic, a duplicate key, an alias bomb or a circular reference still fails typed rather than throwing. `parseAllResult` doubles as a whole-stream validity check: it fails when any document in the stream is invalid.
 - `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.
+- `YamlNode` — an offset-preserving AST (`YamlScalar`, `YamlMap`, `YamlSeq`, `YamlPair`, `YamlAlias`) for locating and reading nodes by position or path, each collection and scalar carrying its own `commentBefore`, `comment` and `spaceBefore`.
+- `YamlDocument` — the full parsed AST plus the recovered `errors` and `warnings` arrays, so a partially valid document is still inspectable, and the leading and trailing comment blocks as `comment` / `commentAfter`.
+- `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; `preserveComments: false` opts out. `format` handles multi-document streams whole, re-emitting every document and its framing; `modify` is single-document by contract (a path names no particular document of a stream) and fails typed with `MultiDocumentStream` rather than guessing.
+- `YamlVisitor` — walk a parsed document as a `Stream` of a tagged-enum event union, with `Stream.take` early termination on large inputs and a `placement` on every comment event.
+- `YamlToken` / `YamlTokens` — the positioned token stream the lint rules read: `tokenize` is a synchronous `Result` that always succeeds, surfacing lexical problems as `error`-kind tokens, and `stream` derives an Effect `Stream` from the same walk.
+- `YamlLint` — `run`, `fix` and the `builtins` catalog: 14 rules covering parse validity, line length, trailing whitespace, blank lines, end-of-file newline, document markers, duplicate keys, quoting, truthy spellings, comment and colon and hyphen spacing, and indentation.
+- `YamlLintConfig` / `YamlLintRule` / `YamlLintDiagnostic` — the `default` and `relaxed` presets, a config schema validated against the rule catalog, and the model a custom rule implements.
 - `YamlParseError` / `YamlStringifyError` / `YamlModificationError` — tagged errors carrying structured, positional `YamlDiagnostic` arrays rather than opaque messages.
 
 ## License

package/Yaml.js

@@ -1,10 +1,9 @@
 import { AliasExpansionBudgetExceeded, CollectionStyle, QuoteStyle, 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, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
+import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 //#region src/Yaml.ts
 /**
@@ -122,11 +121,13 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 * 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.
+* and the decode direction of the schema factories. The error itself has no
+* `code` field: read the code from the diagnostics —
+* `error.diagnostics[0].code` is the primary failure.
 *
 * @public
 */
-var YamlParseError = class extends Schema.TaggedErrorClass()("YamlParseError", {
+var YamlParseError = class extends Schema.TaggedError()("YamlParseError", {
 	diagnostics: Schema.Array(YamlDiagnostic),
 	input: Schema.String
 }) {
@@ -140,11 +141,12 @@ var YamlParseError = class extends Schema.TaggedErrorClass()("YamlParseError", {
 * 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.
+* the schema factories. The error itself has no `code` field: read the code
+* from the diagnostics — `error.diagnostics[0].code` is the primary failure.
 *
 * @public
 */
-var YamlStringifyError = class extends Schema.TaggedErrorClass()("YamlStringifyError", {
+var YamlStringifyError = class extends Schema.TaggedError()("YamlStringifyError", {
 	diagnostics: Schema.Array(YamlDiagnostic),
 	value: Schema.Unknown
 }) {
@@ -238,6 +240,35 @@ const parseResultImpl = (text, options) => {
 	}
 };
 /**
+* Synchronous multi-document parse returning a `Result`. Mirrors
+* {@link parseResultImpl} over the whole stream: stream-level
+* directive-placement errors and every document's failure records aggregate
+* into one {@link YamlParseError}; each document's value is extracted against
+* its own independent anchor map (anchors are document-scoped in a stream),
+* with the alias-expansion budget materialized as a typed failure.
+*/
+const parseAllResultImpl = (text, options) => {
+	const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
+	const uniqueKeys = options?.uniqueKeys ?? true;
+	const failures = [...streamErrors.filter((e) => isFatalCode(e.code)), ...documents.flatMap((d) => failureRecords(d, uniqueKeys))];
+	if (failures.length > 0) return Result.fail(new YamlParseError({
+		diagnostics: toDiagnostics(text, failures),
+		input: text
+	}));
+	const maxAliasCount = options?.maxAliasCount ?? 100;
+	const values = [];
+	for (const d of documents) {
+		const anchors = /* @__PURE__ */ new Map();
+		try {
+			values.push(nodeToJsValue(d.contents, anchors, maxAliasCount));
+		} catch (defect) {
+			if (defect instanceof AliasExpansionBudgetExceeded) return Result.fail(aliasCountExceededError(defect.message, text));
+			throw defect;
+		}
+	}
+	return Result.succeed(values);
+};
+/**
 * Synchronous stringify returning a `Result`. Mirrors {@link Yaml.stringify}
 * without the Effect wrapper: a circular reference or a value nested past the
 * recursion budget yields a `Failure` carrying a typed {@link YamlStringifyError},
@@ -263,19 +294,6 @@ const failureRecords = (doc, uniqueKeys) => {
 	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 aliasCountExceededError(defect.message, text);
-		throw defect;
-	}
-});
 const stringifyOrFail = (value, options) => Effect.try({
 	try: () => stringifyValue(value, toStringifyInput(options)),
 	catch: (defect) => {
@@ -334,23 +352,11 @@ var Yaml = class Yaml {
 	* A "billion laughs" alias-expansion blow-up in any document also fails
 	* through {@link YamlParseError} with an `AliasCountExceeded` diagnostic,
 	* never as an unhandled defect.
+	*
+	* Defined in terms of {@link Yaml.parseAllResult} — synchronous callers
+	* can use that variant directly.
 	*/
-	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;
-	});
+	static parseAll = Effect.fn("Yaml.parseAll")((text, options) => Effect.fromResult(Yaml.parseAllResult(text, options)));
 	/**
 	* Stringify a plain JavaScript value as YAML. Fails with
 	* {@link YamlStringifyError} on circular references (`CircularReference`)
@@ -406,6 +412,48 @@ var Yaml = class Yaml {
 		return parseResultImpl(text, options);
 	}
 	/**
+	* Synchronous multi-document parse, returning a `Result` instead of an
+	* `Effect` — the {@link Yaml.parseResult} counterpart to
+	* {@link Yaml.parseAll}. Empty input succeeds with `[null]` (the engine
+	* reads `""` as one empty document, exactly as {@link Yaml.parse} yields
+	* `null` for it); a single-document stream succeeds with a one-element
+	* array whose value is exactly what {@link Yaml.parseResult} yields.
+	*
+	* @remarks
+	* This is the package's single multi-document parse path.
+	* {@link Yaml.parseAll} is defined in terms of it (`Effect.fromResult`
+	* behind the named span), so the two variants cannot diverge. Anchors are
+	* document-scoped: each document's aliases resolve against its own anchor
+	* map, never a neighbor's.
+	*
+	* Fails with the aggregate {@link YamlParseError} when **any** document in
+	* the stream carries a fatal diagnostic (or a stream-level
+	* directive-placement error), which makes it a whole-stream validity
+	* check: a `Success` means every document parsed clean. Preserves the
+	* package contract — malformed and adversarial input (including a
+	* "billion laughs" alias bomb in any document) fails typed, never as a
+	* defect; the method never throws.
+	*
+	* @example
+	* ```ts
+	* import { Yaml } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* // Whole-stream validity check: fails if ANY document is invalid.
+	* const result = Yaml.parseAllResult("a: 1\n---\nb: 2\n");
+	* if (Result.isSuccess(result)) {
+	*   result.success; // [{ a: 1 }, { b: 2 }]
+	* } else {
+	*   result.failure; // YamlParseError aggregating every fatal diagnostic
+	* }
+	* ```
+	*
+	* @public
+	*/
+	static parseAllResult(text, options) {
+		return parseAllResultImpl(text, options);
+	}
+	/**
 	* Synchronous stringify, returning a `Result` instead of an `Effect`.
 	* The pure counterpart to {@link Yaml.stringify} for config-time callers
 	* that cannot `await`.
@@ -516,8 +564,8 @@ var Yaml = class Yaml {
 	*/
 	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 })))
+			decode: (input) => Yaml.parse(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, input))),
+			encode: (value) => stringifyOrFail(value).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, value)))
 		})));
 	}
 	/**
@@ -536,12 +584,12 @@ var Yaml = class Yaml {
 	*/
 	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 }))),
+			decode: (input) => Yaml.parseAll(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, input))),
 			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 })));
+					const yaml = yield* stringifyOrFail(values[index]).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, values)));
 					parts.push(index > 0 ? `---\n${yaml}` : yaml);
 				}
 				return parts.join("");

package/YamlDocument.js

@@ -4,7 +4,7 @@ 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";
+import { Effect, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 //#region src/YamlDocument.ts
 /**
@@ -22,8 +22,12 @@ var YamlDirective = class extends Schema.Class("YamlDirective")({
 /**
 * 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`).
+* the {@link YamlDirective} list, the optional document-level comments
+* (`comment` is the LEADING header block, `commentAfter` the trailing block
+* after the content or the `...` marker — the reference `yaml` package calls
+* these `commentBefore`/`comment`; the naming here keeps the pre-existing
+* `comment`-as-header field stable), and the `---`/`...` framing flags
+* (absent flags read as `false`).
 *
 * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
 * synthetic documents.
@@ -36,6 +40,7 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	warnings: Schema.Array(YamlDiagnostic),
 	directives: Schema.Array(YamlDirective),
 	comment: Schema.optionalKey(Schema.String),
+	commentAfter: Schema.optionalKey(Schema.String),
 	hasDocumentStart: Schema.optionalKey(Schema.Boolean),
 	hasDocumentEnd: Schema.optionalKey(Schema.Boolean),
 	hasDocumentStartTab: Schema.optionalKey(Schema.Boolean)
@@ -80,8 +85,8 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	*/
 	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 })))
+			decode: (input) => YamlDocument.parse(input, options).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, input))),
+			encode: (doc) => doc.stringify().pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, doc)))
 		})));
 	}
 	/**
@@ -159,6 +164,18 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };
+/**
+* Materialize a raw engine document into the public class — including
+* documents whose diagnostics are fatal, which `YamlDocument.parse` refuses.
+* The lint layer builds its context through this so linting runs on
+* malformed input; it is NOT a second public parse entry point (not
+* re-exported from the package index).
+*
+* @internal
+*/
+function documentFromRaw(raw, text) {
+	return fromRawDocument(raw, text);
+}
 /** Materialize a raw engine document into the public class. */
 function fromRawDocument(raw, text) {
 	return new YamlDocument({
@@ -170,6 +187,7 @@ function fromRawDocument(raw, text) {
 			parameters: d.parameters
 		})),
 		...raw.comment !== void 0 ? { comment: raw.comment } : {},
+		...raw.commentAfter !== void 0 ? { commentAfter: raw.commentAfter } : {},
 		hasDocumentStart: raw.hasDocumentStart,
 		hasDocumentEnd: raw.hasDocumentEnd,
 		hasDocumentStartTab: raw.hasDocumentStartTab
@@ -183,6 +201,7 @@ function toRawDocument(doc) {
 		warnings: [],
 		directives: doc.directives,
 		...doc.comment !== void 0 ? { comment: doc.comment } : {},
+		...doc.commentAfter !== void 0 ? { commentAfter: doc.commentAfter } : {},
 		hasDocumentStart: doc.hasDocumentStart ?? false,
 		hasDocumentEnd: doc.hasDocumentEnd ?? false,
 		hasDocumentStartTab: doc.hasDocumentStartTab ?? false
@@ -190,4 +209,4 @@ function toRawDocument(doc) {
 }
 
 //#endregion
-export { YamlDirective, YamlDocument };
+export { YamlDirective, YamlDocument, documentFromRaw };