@effected/yaml 0.7.0 → 0.9.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,91 @@ 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. Every node class — `YamlScalar`, `YamlMap`, `YamlSeq` and `YamlAlias` — carries `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). `YamlPair` carries none of them: an entry is its `key` and its `value`, and the comments live on those two nodes. `YamlDocument` uses the same two names as the nodes do, `commentBefore` for a header block sitting ahead of a `---` marker and `comment` for the trailing block, and `YamlVisitor` tags every `Comment` event with `placement: "leading" | "trailing"`.
+
+Which node a comment lands on follows one rule. An own-line comment above an entry leads that entry's key node, setting `commentBefore` and — when a blank line came first — `spaceBefore`. A trailing comment belongs to the last node on its line: in `a: 1 # t` the value ends the line, so `# t` is the value's `comment`; in `push: # only main` the value renders below, so the comment is the key's. Two slots per entry rather than one is what lets `push: # only main` and an own-line comment above the value both round-trip byte-intact, instead of one spelling being rewritten into the other. A header block with no `---` marker to separate it from the item stream leads the first entry's key by the same rule; one after the marker leads the root node.
+
+## 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; every node class except `YamlPair` carries its own `commentBefore`, `comment` and `spaceBefore`, and a pair is just its `key` and `value`.
+- `YamlDocument` — the full parsed AST plus the recovered `errors` and `warnings` arrays, so a partially valid document is still inspectable, and the header and trailing comment blocks as `commentBefore` / `comment`, the same two names the node classes use.
+- `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,5 +1,4 @@
 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";
@@ -122,7 +121,9 @@ 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
 */
@@ -140,7 +141,8 @@ var YamlParseError = class extends Schema.TaggedError()("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
 */
@@ -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`.

package/YamlDocument.js

@@ -22,9 +22,15 @@ 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
+* the {@link YamlDirective} list, the optional document-level comments and the
 * `---`/`...` framing flags (absent flags read as `false`).
 *
+* `commentBefore` is a header block sitting AHEAD of a `---` marker; `comment`
+* is the trailing block after the content or the `...` marker. A header with
+* no marker, or one after the marker, belongs to the content rather than the
+* document — it leads the root node, or the first entry when there is no
+* marker to separate it from the item stream.
+*
 * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
 * synthetic documents.
 *
@@ -35,6 +41,7 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	errors: Schema.Array(YamlDiagnostic),
 	warnings: Schema.Array(YamlDiagnostic),
 	directives: Schema.Array(YamlDirective),
+	commentBefore: Schema.optionalKey(Schema.String),
 	comment: Schema.optionalKey(Schema.String),
 	hasDocumentStart: Schema.optionalKey(Schema.Boolean),
 	hasDocumentEnd: Schema.optionalKey(Schema.Boolean),
@@ -159,6 +166,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({
@@ -169,6 +188,7 @@ function fromRawDocument(raw, text) {
 			name: d.name,
 			parameters: d.parameters
 		})),
+		...raw.commentBefore !== void 0 ? { commentBefore: raw.commentBefore } : {},
 		...raw.comment !== void 0 ? { comment: raw.comment } : {},
 		hasDocumentStart: raw.hasDocumentStart,
 		hasDocumentEnd: raw.hasDocumentEnd,
@@ -182,6 +202,7 @@ function toRawDocument(doc) {
 		errors: [],
 		warnings: [],
 		directives: doc.directives,
+		...doc.commentBefore !== void 0 ? { commentBefore: doc.commentBefore } : {},
 		...doc.comment !== void 0 ? { comment: doc.comment } : {},
 		hasDocumentStart: doc.hasDocumentStart ?? false,
 		hasDocumentEnd: doc.hasDocumentEnd ?? false,
@@ -190,4 +211,4 @@ function toRawDocument(doc) {
 }
 
 //#endregion
-export { YamlDirective, YamlDocument };
+export { YamlDirective, YamlDocument, documentFromRaw };

package/YamlFormat.js

@@ -1,5 +1,5 @@
 import { YamlMap, YamlPair, YamlScalar, YamlSeq } from "./YamlNode.js";
-import { composeFirstDocument } from "./internal/composer/document.js";
+import { EMPTY_DOCUMENT, composeAllDocuments, composeFirstDocumentCounted } from "./internal/composer/document.js";
 import { isFatalCode } from "./internal/diagnostics.js";
 import { stringifyDocument, stripNodeComments } from "./internal/stringifier.js";
 import { YamlDiagnostic } from "./YamlDiagnostic.js";
@@ -41,9 +41,16 @@ var YamlFormattingOptions = class extends Schema.Class("YamlFormattingOptions")(
 }) {};
 /**
 * Raised when `YamlFormat.modify` cannot navigate the requested path against
-* the composed AST (a structural mismatch) or the source fails to parse.
+* the composed AST (a structural mismatch), the source fails to parse, the
+* source is a multi-document stream (`MultiDocumentStream` — a path names no
+* particular document of a stream, so modify refuses rather than guessing),
+* or the document carries `%YAML`/`%TAG` directives
+* (`DirectiveCarryingDocument` — modify does not re-emit directive lines, and
+* dropping a `%TAG` would orphan the shorthand tags that depend on it).
 * Carries structured {@link YamlDiagnostic} entries — never a collapsed
-* `reason` string (the structure-preserving-errors house rule).
+* `reason` string (the structure-preserving-errors house rule). The error
+* itself has no `code` field: read the code from the diagnostics —
+* `error.diagnostics[0].code` is the primary failure.
 *
 * @public
 */
@@ -97,26 +104,77 @@ function definedFields(fields) {
 	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;
-	const outputDoc = {
+/** Rebuild a composed document for re-emission, stripping comments when asked. */
+function toOutputDocument(doc, preserveComments) {
+	return {
 		contents: !preserveComments && doc.contents !== null ? stripNodeComments(doc.contents) : doc.contents,
 		errors: doc.errors,
 		warnings: doc.warnings,
 		directives: doc.directives,
-		...preserveComments ? definedFields({ comment: doc.comment }) : {},
+		...preserveComments ? definedFields({
+			commentBefore: doc.commentBefore,
+			comment: doc.comment
+		}) : {},
 		hasDocumentStart: doc.hasDocumentStart,
 		hasDocumentEnd: doc.hasDocumentEnd,
 		hasDocumentStartTab: doc.hasDocumentStartTab
 	};
-	return stringifyDocument(outputDoc, toStringifyInput(options));
+}
+/**
+* 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) or carries
+* `%YAML`/`%TAG` directives — `stringifyDocument` does not re-emit
+* directive lines, and dropping a `%TAG` while keeping the shorthand tags
+* that depend on it would turn a valid document into an unparseable one.
+* A multi-document stream routes to {@link formatStream}, which formats
+* every document and shares the same directive refusal.
+*/
+function formatDocument(text, options) {
+	const { documents, streamErrors } = composeAllDocuments(text, {});
+	if (documents.length > 1) return formatStream(documents, streamErrors, options);
+	if (streamErrors.some((e) => isFatalCode(e.code))) return void 0;
+	const doc = documents[0] ?? EMPTY_DOCUMENT;
+	if (doc.errors.some((e) => isFatalCode(e.code))) return void 0;
+	if (doc.directives.length > 0) return void 0;
+	return stringifyDocument(toOutputDocument(doc, options?.preserveComments ?? true), toStringifyInput(options));
+}
+/**
+* Format a multi-document stream: every document is re-emitted in order with
+* its own framing (`---`, `...`, leading/trailing comment blocks — all of
+* which `stringifyDocument` renders per document), so no document is ever
+* dropped. Receives the documents and stream errors from the ONE
+* composition {@link formatDocument} already performed. Returns `undefined`
+* — no edits — when the stream cannot be re-emitted faithfully:
+*
+* - any document (or the stream itself) carries a fatal diagnostic, the same
+*   posture as the single-document path;
+* - any document carries `%YAML`/`%TAG` directives — `stringifyDocument`
+*   does not re-emit directive lines, and dropping a `%TAG` would change
+*   what the re-emitted document means.
+*
+* The single-document path ({@link formatDocument}) shares the directive
+* refusal: re-emitting a directive-carrying document without its directive
+* line while keeping the dependent shorthand tags produced unparseable
+* output (probe-verified downstream against an independent oracle).
+*/
+function formatStream(documents, streamErrors, options) {
+	if (streamErrors.some((e) => isFatalCode(e.code))) return void 0;
+	if (documents.some((d) => d.errors.some((e) => isFatalCode(e.code)))) return void 0;
+	if (documents.some((d) => d.directives.length > 0)) return void 0;
+	const preserveComments = options?.preserveComments ?? true;
+	const base = toStringifyInput(options);
+	const parts = [];
+	for (let i = 0; i < documents.length; i++) {
+		const doc = documents[i];
+		if (i > 0 && !doc.hasDocumentStart && !documents[i - 1].hasDocumentEnd) return void 0;
+		const docOptions = i < documents.length - 1 ? {
+			...base,
+			finalNewline: true
+		} : base;
+		parts.push(stringifyDocument(toOutputDocument(doc, preserveComments), docOptions));
+	}
+	return parts.join("");
 }
 /** Convert a plain JS scalar value into a synthetic `YamlScalar` (offset/length are irrelevant — immediately re-stringified). */
 function jsValueToNode(value) {
@@ -150,8 +208,7 @@ function modifyNode(node, path, depth, value) {
 				const oldPair = newItems[pairIndex];
 				newItems[pairIndex] = YamlPair.make({
 					key: oldPair.key,
-					value: newValueNode,
-					...definedFields({ comment: oldPair.comment })
+					value: newValueNode
 				});
 				return rebuildMap(node, newItems);
 			}
@@ -174,8 +231,7 @@ function modifyNode(node, path, depth, value) {
 		const newItems = [...node.items];
 		newItems[pairIndex] = YamlPair.make({
 			key: pair.key,
-			value: newValue,
-			...definedFields({ comment: pair.comment })
+			value: newValue
 		});
 		return rebuildMap(node, newItems);
 	}
@@ -206,7 +262,9 @@ function rebuildMap(node, items) {
 		...definedFields({
 			tag: node.tag,
 			anchor: node.anchor,
+			commentBefore: node.commentBefore,
 			comment: node.comment,
+			spaceBefore: node.spaceBefore,
 			sourceMultiline: node.sourceMultiline
 		}),
 		offset: node.offset,
@@ -220,7 +278,9 @@ function rebuildSeq(node, items) {
 		...definedFields({
 			tag: node.tag,
 			anchor: node.anchor,
+			commentBefore: node.commentBefore,
 			comment: node.comment,
+			spaceBefore: node.spaceBefore,
 			sourceMultiline: node.sourceMultiline
 		}),
 		offset: node.offset,
@@ -239,6 +299,24 @@ function rebuildSeq(node, items) {
 * `diagnostics: ReadonlyArray<YamlDiagnostic>`, never a collapsed `reason`
 * string.
 *
+* `format`/`formatToString` handle multi-document streams whole — every
+* document is re-emitted in order with its own framing, never a silently
+* truncated stream. `modify`/`modifyToString` are **single-document**: a
+* {@link YamlPath} carries no document index, so which document of a stream
+* a path names is a rule the format does not define, and a multi-document
+* stream fails typed with a `MultiDocumentStream` diagnostic rather than
+* guessing. Parse a stream with {@link Yaml.parseAll} /
+* `Yaml.parseAllResult`.
+*
+* **Directive-carrying input is refused on every path.** The stringifier does
+* not re-emit `%YAML`/`%TAG` directive lines, and re-emitting a document
+* without its `%TAG` while keeping the shorthand tags that depend on it
+* (`!e!foo`) turns a valid file into one no parser can read. So
+* `format`/`formatToString` leave such input byte-identical (no edits), and
+* `modify`/`modifyToString` fail typed with a `DirectiveCarryingDocument`
+* diagnostic. Directive re-emission is unimplemented, not undesired — the
+* refusal is the floor that stops corruption until it lands.
+*
 * @public
 */
 var YamlFormat = class YamlFormat {
@@ -249,6 +327,24 @@ var YamlFormat = class YamlFormat {
 	* Pure and total: malformed input (a fatal parse error) yields `[]` rather
 	* than corrupting the document.
 	*
+	* **Multi-document streams format whole.** Input containing more than one
+	* document (a `---`-separated stream — a Kubernetes manifest, a pnpm 11
+	* `pnpm-lock.yaml` with a config-dependency preamble) formats every
+	* document in order, re-emitting each document's own framing (`---`,
+	* `...`, comment blocks); no document is ever dropped. Document detection
+	* is CST-level, so a `---` inside a block scalar or quoted string is
+	* content, not a document boundary. Two multi-document shapes yield `[]`
+	* (untouched) because they cannot be re-emitted faithfully: a stream with
+	* a fatal diagnostic in any document (the same posture as single-document
+	* input) and a stream carrying `%YAML`/`%TAG` directives.
+	*
+	* **Directive-carrying documents yield `[]` on the single-document path
+	* too.** Directive lines are not re-emitted, and dropping a `%TAG` while
+	* keeping the shorthand tags that depend on it would turn a valid document
+	* into an unparseable one — so a document carrying `%YAML`/`%TAG`
+	* directives is left untouched. Detection is directive-token-level: a
+	* literal `%TAG` inside a scalar is content and formats normally.
+	*
 	* @remarks
 	* The positional `range` argument takes precedence over
 	* `options?.range` when both are given; either accepts a plain
@@ -278,6 +374,13 @@ var YamlFormat = class YamlFormat {
 	/**
 	* Format `text` and apply the resulting edits in one step
 	* (`YamlEdit.applyAll ∘ format`). Pure and total.
+	*
+	* Inherits the {@link YamlFormat.format} contract: a multi-document stream
+	* is formatted whole — every document re-emitted in order — and input
+	* that cannot be formatted faithfully (a fatal parse error, or any
+	* document — single or in a stream — carrying `%YAML`/`%TAG` directives)
+	* is returned byte-identical — never a truncated first document, never a
+	* document re-emitted without the directive its tags depend on.
 	*/
 	static formatToString(text, range, options) {
 		return YamlEdit.applyAll(text, YamlFormat.format(text, range, options));
@@ -291,18 +394,53 @@ var YamlFormat = class YamlFormat {
 	* {@link YamlModificationError} on a fatal parse error or a structural
 	* navigation mismatch.
 	*
+	* **Single-document contract.** A `path` carries no document index, so on
+	* a multi-document stream there is no rule for which document it names —
+	* `modify` fails with {@link YamlModificationError} carrying a
+	* `MultiDocumentStream` diagnostic rather than guessing document 1 (and
+	* unlike {@link YamlFormat.format}, which formats a stream whole because
+	* formatting needs no target). Detection is CST-level: a `---` inside a
+	* block scalar or quoted string is content, not a document boundary.
+	*
+	* **Directive-carrying documents are refused.** A document carrying
+	* `%YAML`/`%TAG` directives fails with {@link YamlModificationError}
+	* carrying a `DirectiveCarryingDocument` diagnostic: modify re-emits the
+	* whole document and does not re-emit directive lines, so applying it
+	* would drop the `%TAG` while keeping the shorthand tags that depend on
+	* it — unparseable output. A typed refusal beats silent corruption;
+	* directive re-emission is unimplemented, not undesired. A literal
+	* `%TAG` inside a scalar is content and does not trigger the refusal.
+	*
 	* @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 { document: doc, documentCount } = composeFirstDocumentCounted(text, {});
+		if (documentCount > 1) return yield* new YamlModificationError({
+			path,
+			diagnostics: [YamlDiagnostic.fromRaw({
+				code: "MultiDocumentStream",
+				message: `Cannot modify a multi-document stream (${documentCount} documents): modify re-emits exactly one document`,
+				offset: 0,
+				length: 0
+			}, 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))
 		});
+		if (doc.directives.length > 0) return yield* new YamlModificationError({
+			path,
+			diagnostics: [YamlDiagnostic.fromRaw({
+				code: "DirectiveCarryingDocument",
+				message: "Cannot modify a document carrying %YAML/%TAG directives: modify does not re-emit directive lines, and dropping a %TAG orphans the shorthand tags that depend on it",
+				offset: 0,
+				length: 0
+			}, text)]
+		});
 		let newContents;
 		try {
 			newContents = modifyDocument(doc, path, value);
@@ -327,7 +465,10 @@ var YamlFormat = class YamlFormat {
 	});
 	/**
 	* Modify `text` and apply the resulting edits in one step
-	* (`YamlEdit.applyAll ∘ modify`).
+	* (`YamlEdit.applyAll ∘ modify`). Inherits the {@link YamlFormat.modify}
+	* error channel, including the single-document contract's
+	* `MultiDocumentStream` refusal and the `DirectiveCarryingDocument`
+	* refusal of `%YAML`/`%TAG`-carrying documents.
 	*/
 	static modifyToString = Effect.fn("YamlFormat.modifyToString")(function* (text, path, value, options) {
 		const edits = yield* YamlFormat.modify(text, path, value, options);