@effected/yaml 0.6.1 → 0.8.0

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,13 +41,20 @@ 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
 */
-var YamlModificationError = class extends Schema.TaggedErrorClass()("YamlModificationError", {
+var YamlModificationError = class extends Schema.TaggedError()("YamlModificationError", {
 	path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
 	diagnostics: Schema.Array(YamlDiagnostic)
 }) {
@@ -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({
+			comment: doc.comment,
+			commentAfter: doc.commentAfter
+		}) : {},
 		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) {
@@ -151,7 +209,11 @@ function modifyNode(node, path, depth, value) {
 				newItems[pairIndex] = YamlPair.make({
 					key: oldPair.key,
 					value: newValueNode,
-					...definedFields({ comment: oldPair.comment })
+					...definedFields({
+						commentBefore: oldPair.commentBefore,
+						comment: oldPair.comment,
+						spaceBefore: oldPair.spaceBefore
+					})
 				});
 				return rebuildMap(node, newItems);
 			}
@@ -175,7 +237,11 @@ function modifyNode(node, path, depth, value) {
 		newItems[pairIndex] = YamlPair.make({
 			key: pair.key,
 			value: newValue,
-			...definedFields({ comment: pair.comment })
+			...definedFields({
+				commentBefore: pair.commentBefore,
+				comment: pair.comment,
+				spaceBefore: pair.spaceBefore
+			})
 		});
 		return rebuildMap(node, newItems);
 	}
@@ -206,7 +272,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 +288,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 +309,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 +337,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 +384,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 +404,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 +475,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);

package/YamlLint.js

@@ -0,0 +1,239 @@
+import { composeFirstDocument } from "./internal/composer/document.js";
+import { isFatalCode } from "./internal/diagnostics.js";
+import { YamlParseError } from "./Yaml.js";
+import { documentFromRaw } from "./YamlDocument.js";
+import { YamlEdit } from "./YamlEdit.js";
+import { YamlLintDiagnostic } from "./YamlLintRule.js";
+import { builtinOptionsSchemas, builtinRules } from "./internal/rules/catalog.js";
+import { YamlTokens } from "./YamlToken.js";
+import { Result, Schema } from "effect";
+
+//#region src/YamlLint.ts
+/**
+* One entry of the config `rules` map: a bare severity literal (the common
+* case), `"off"` to disable, or a typed per-rule options object (the tuning
+* case; may carry its own `severity`).
+*
+* @public
+*/
+const YamlLintRuleSetting = Schema.Union([Schema.Literals([
+	"error",
+	"warning",
+	"off"
+]), Schema.Record(Schema.String, Schema.Unknown)]);
+/** Rule-aware validation of the config `rules` map (undefined = valid). */
+const validateRulesMap = (rules) => {
+	for (const [id, entry] of Object.entries(rules)) {
+		if (id === "parse-validity") {
+			if (entry === "off" || entry === "warning") return `Rule "parse-validity" is always-on and cannot be set to "${entry}"`;
+			if (typeof entry === "object") return `Rule "parse-validity" accepts no options`;
+			continue;
+		}
+		if (typeof entry === "object") {
+			const optionsSchema = builtinOptionsSchemas.get(id);
+			if (optionsSchema !== void 0) {
+				const decoded = Schema.decodeUnknownResult(optionsSchema, { onExcessProperty: "error" })(entry);
+				if (Result.isFailure(decoded)) return `Invalid options for rule "${id}": ${String(decoded.failure)}`;
+			}
+		}
+	}
+};
+/**
+* The lint configuration: a `rules` map keying rule ids (built-in or custom)
+* to a severity literal or a typed per-rule options object.
+*
+* Validation is rule-aware for the built-in catalog — a mistyped option on a
+* built-in rule fails schema validation with a typed error naming the rule,
+* and any attempt to demote or disable the always-on `parse-validity` rule
+* is rejected. Custom rule ids are accepted with a bare severity or an
+* opaque options object the custom rule validates itself.
+*
+* Presets ship as the statics {@link YamlLintConfig.default} and
+* {@link YamlLintConfig.relaxed} — composing one is object spread over a
+* static, not an `extends` string resolution step (this package owns no
+* config-file loader).
+*
+* @public
+*/
+var YamlLintConfig = class YamlLintConfig extends Schema.Class("YamlLintConfig")({ rules: Schema.Record(Schema.String, YamlLintRuleSetting).pipe(Schema.check(Schema.makeFilter(validateRulesMap))) }) {
+	/**
+	* The default preset. Rule entries accrete as built-ins land; the
+	* `quoted-strings` rule defaults to DOUBLE quotes here (the one taste
+	* call the design pins).
+	*/
+	static default = YamlLintConfig.make({ rules: {
+		"line-length": "error",
+		"trailing-spaces": "error",
+		"empty-lines": "error",
+		"eof-newline": "error",
+		"key-duplicates": "error",
+		"quoted-strings": { quoteType: "double" },
+		truthy: "error",
+		"comments-spacing": "error",
+		"colon-spacing": "error",
+		"hyphen-spacing": "error",
+		indentation: "error"
+	} });
+	/** The relaxed preset: style rules demoted to warnings. */
+	static relaxed = YamlLintConfig.make({ rules: {
+		"line-length": "warning",
+		"trailing-spaces": "warning",
+		"empty-lines": "warning",
+		"eof-newline": "warning",
+		"key-duplicates": "error",
+		"quoted-strings": {
+			quoteType: "double",
+			severity: "warning"
+		},
+		truthy: "warning",
+		"comments-spacing": "warning",
+		"colon-spacing": "warning",
+		"hyphen-spacing": "warning",
+		indentation: "warning"
+	} });
+};
+/**
+* Split `text` into positioned lines. Line text excludes the terminator
+* whole — for CRLF input the `\r` is part of the terminator and is stripped
+* too, so every rule sees the same line content regardless of line-ending
+* style. Empty input has no lines: rules that count blank lines must not see
+* a phantom first line.
+*/
+const buildLines = (text) => {
+	if (text === "") return [];
+	const lines = [];
+	let offset = 0;
+	let number = 0;
+	while (offset <= text.length) {
+		const nl = text.indexOf("\n", offset);
+		const end = nl === -1 ? text.length : nl > offset && text[nl - 1] === "\r" ? nl - 1 : nl;
+		if (offset === text.length && number > 0) break;
+		lines.push({
+			text: text.slice(offset, end),
+			offset,
+			number
+		});
+		if (nl === -1) break;
+		offset = nl + 1;
+		number++;
+	}
+	return lines;
+};
+/**
+* Build the eager lint context: tokenize once, compose once (through the
+* RECOVERED path, so the context exists for malformed input too — the
+* `parse-validity` rule reports what went wrong).
+*/
+const buildContext = (text) => {
+	const tokens = Result.match(YamlTokens.tokenize(text), {
+		onSuccess: (value) => value,
+		onFailure: (error) => {
+			throw error;
+		}
+	});
+	return {
+		text,
+		lines: buildLines(text),
+		tokens,
+		document: documentFromRaw(composeFirstDocument(text, { uniqueKeys: false }), text)
+	};
+};
+/** Resolve the effective severity of a configured entry. */
+const resolveSeverity = (entry) => {
+	if (entry === "error" || entry === "warning") return entry;
+	if (typeof entry === "object" && (entry.severity === "error" || entry.severity === "warning")) return entry.severity;
+	return "error";
+};
+const byPosition = (a, b) => a.offset - b.offset || a.length - b.length || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0);
+/**
+* The rule loop shared by `run` and `fix` over one already-built context —
+* `fix` must not tokenize and compose the same input twice.
+*/
+const runRules = (ctx, rules, config) => {
+	const out = [];
+	for (const rule of rules) {
+		const alwaysOn = rule.id === "parse-validity";
+		const entry = alwaysOn ? "error" : config.rules[rule.id];
+		if (entry === void 0 || entry === "off") continue;
+		const severity = resolveSeverity(entry);
+		const options = typeof entry === "object" ? entry : void 0;
+		for (const diagnostic of rule.check(ctx, options)) out.push(alwaysOn || diagnostic.severity === severity ? diagnostic : new YamlLintDiagnostic({
+			...diagnostic,
+			severity
+		}));
+	}
+	return out.sort(byPosition);
+};
+/**
+* Linting statics. Not instantiable.
+*
+* @remarks
+* Pure and synchronous throughout — the lint engine is the pure half only:
+* strings in, diagnostics or a fixed string out. File discovery, config-file
+* loading and autofix-to-disk belong to a consumer's tier, not here.
+*
+* @public
+*/
+var YamlLint = class {
+	constructor() {}
+	/**
+	* The built-in rule catalog. Custom usage is array concatenation:
+	* `YamlLint.run(text, [...YamlLint.builtins, myRule], config)`.
+	*/
+	static builtins = builtinRules;
+	/**
+	* Run `rules` over `text` under `config`, returning every finding sorted
+	* by position.
+	*
+	* Document-driven rules see the FIRST document of the stream (matching
+	* `Yaml.parse`; split the stream `Yaml.parseAll`-style to lint every
+	* document), while token- and line-driven rules cover the full source —
+	* see {@link LintContext}.
+	*
+	* A rule runs when its config entry is a severity or an options object;
+	* `"off"` and absent entries skip it — except `parse-validity`, which is
+	* always-on. The resolved severity (explicit-in-options, else the bare
+	* literal, else `"error"`) overrides what the rule emitted, again except
+	* for `parse-validity`, whose bridged engine diagnostics keep the
+	* engine's own grading.
+	*/
+	static run(text, rules, config) {
+		return runRules(buildContext(text), rules, config);
+	}
+	/**
+	* Run `rules` and apply every non-overlapping surgical fix, returning the
+	* fixed text. Fails with {@link YamlParseError} when the FIRST document
+	* of the stream has a fatal parse error — a document the engine cannot
+	* compose is not safely fixable. The gate matches `Yaml.parse`'s scope:
+	* later documents of a multi-document stream are not composed (split the
+	* stream `Yaml.parseAll`-style to lint every document), though token- and
+	* line-driven fixes still cover the full source. Fixes route exclusively through `YamlEdit.applyAll` (never a
+	* reformat), so applying them is comment-safe by construction; when two
+	* fixes overlap — or start at the same offset — the earlier one in
+	* {@link YamlLint.run} order (position, then rule id) wins and the later
+	* is dropped (its diagnostic remains reported by {@link YamlLint.run}).
+	*/
+	static fix(text, rules, config) {
+		const ctx = buildContext(text);
+		const fatal = ctx.document.errors.filter((e) => isFatalCode(e.code));
+		if (fatal.length > 0) return Result.fail(new YamlParseError({
+			diagnostics: fatal,
+			input: text
+		}));
+		const fixes = [];
+		let lastEnd = -1;
+		let lastOffset = -1;
+		for (const diagnostic of runRules(ctx, rules, config)) {
+			const fix = diagnostic.fix;
+			if (fix === void 0) continue;
+			if (fix.offset < lastEnd || fix.offset === lastOffset) continue;
+			fixes.push(fix);
+			lastEnd = fix.offset + fix.length;
+			lastOffset = fix.offset;
+		}
+		return Result.succeed(YamlEdit.applyAll(text, fixes));
+	}
+};
+
+//#endregion
+export { YamlLint, YamlLintConfig, YamlLintRuleSetting };

package/YamlLintRule.js

@@ -0,0 +1,36 @@
+import { YamlEdit } from "./YamlEdit.js";
+import { Schema } from "effect";
+
+//#region src/YamlLintRule.ts
+/**
+* Lint diagnostic severities. `"off"` is a config-level disable only and
+* never reaches a diagnostic — a rule set to `"off"` is not run.
+*
+* @public
+*/
+const YamlLintSeverity = Schema.Literals(["error", "warning"]);
+/**
+* A single lint finding: the reporting rule, its severity, a positioned span
+* and optionally a surgical fix.
+*
+* Deliberately separate from the engine's `YamlDiagnostic`: that type is the
+* lexer/parser/composer/stringifier error-code union and the single source
+* of truth for engine fatality — it carries no severity and no fix, and
+* lint-layer concerns must not pollute it. The `parse-validity` rule bridges
+* the two by mapping engine diagnostics into this shape.
+*
+* @public
+*/
+var YamlLintDiagnostic = class extends Schema.Class("YamlLintDiagnostic")({
+	rule: Schema.String,
+	severity: YamlLintSeverity,
+	message: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number,
+	line: Schema.Number,
+	character: Schema.Number,
+	fix: Schema.optionalKey(YamlEdit)
+}) {};
+
+//#endregion
+export { YamlLintDiagnostic, YamlLintSeverity };

package/YamlNode.js

@@ -49,9 +49,17 @@ const ScalarChomp = Schema.Literals([
 * - `style` — the scalar presentation style in the source document.
 * - `tag` — optional explicit YAML tag (e.g. `!!str`, `!!int`).
 * - `anchor` — optional anchor name for aliasing.
-* - `comment` — optional trailing or leading comment text.
+* - `commentBefore` — own-line comment text directly above the node
+*   (multiple consecutive comment lines join with `\n`).
+* - `comment` — trailing comment text on the node's line (strictly trailing;
+*   own-line comments live on `commentBefore`).
+* - `spaceBefore` — `true` when a blank line precedes the node (and its
+*   `commentBefore` block, when present) in the source.
 * - `chomp` — block-scalar chomping indicator, when the scalar is a block
 *   scalar.
+* - `blockIndent` — the EXPLICIT indentation-indicator digit from a block
+*   scalar's header (`|2`, `>1+`), when the source spelled one; absent when
+*   the header let the reader auto-detect the indent.
 * - `raw` — the raw source text, preserved when it differs from the resolved
 *   value in a way stringification needs to know about.
 * - `sourceMultiline` — `true` when the source span covers two or more lines;
@@ -65,8 +73,11 @@ var YamlScalar = class extends Schema.TaggedClass()("YamlScalar", {
 	tag: Schema.optionalKey(Schema.String),
 	style: ScalarStyle,
 	anchor: Schema.optionalKey(Schema.String),
+	commentBefore: Schema.optionalKey(Schema.String),
 	comment: Schema.optionalKey(Schema.String),
+	spaceBefore: Schema.optionalKey(Schema.Boolean),
 	chomp: Schema.optionalKey(ScalarChomp),
+	blockIndent: Schema.optionalKey(Schema.Number),
 	raw: Schema.optionalKey(Schema.String),
 	sourceMultiline: Schema.optionalKey(Schema.Boolean),
 	offset: Schema.Number,
@@ -157,18 +168,31 @@ const YamlNode = Schema.suspend(() => Schema.Union([
 * A YAML key-value pair AST node, representing one entry within a mapping.
 * `value` is `null` when absent (e.g. `key:` with no value).
 *
+* - `commentBefore` — own-line comment text directly above the pair's key
+*   (multiple consecutive comment lines join with `\n`).
+* - `comment` — trailing comment text on the pair's line (strictly trailing).
+* - `spaceBefore` — `true` when a blank line precedes the pair (and its
+*   `commentBefore` block, when present) in the source.
+*
 * @public
 */
 var YamlPair = class extends Schema.TaggedClass()("YamlPair", {
 	key: Schema.suspend(() => YamlNode),
 	value: Schema.NullOr(Schema.suspend(() => YamlNode)),
-	comment: Schema.optionalKey(Schema.String)
+	commentBefore: Schema.optionalKey(Schema.String),
+	comment: Schema.optionalKey(Schema.String),
+	spaceBefore: Schema.optionalKey(Schema.Boolean)
 }) {};
 /**
 * A YAML mapping AST node, representing a collection of {@link YamlPair}
 * entries.
 *
 * - `style` — the presentation style: `"block"` or `"flow"`.
+* - `commentBefore` — own-line comment text directly above the mapping.
+* - `comment` — trailing comment text: own-line comment lines after the
+*   mapping's last entry (still at the mapping's item indent), or a same-line
+*   trailing comment for a flow mapping.
+* - `spaceBefore` — `true` when a blank line precedes the mapping.
 * - `sourceMultiline` — `true` when the source span covers two or more lines;
 *   used by the canonical stringifier. Absent on synthetic nodes.
 *
@@ -179,7 +203,9 @@ var YamlMap = class extends Schema.TaggedClass()("YamlMap", {
 	tag: Schema.optionalKey(Schema.String),
 	anchor: Schema.optionalKey(Schema.String),
 	style: CollectionStyle,
+	commentBefore: Schema.optionalKey(Schema.String),
 	comment: Schema.optionalKey(Schema.String),
+	spaceBefore: Schema.optionalKey(Schema.Boolean),
 	sourceMultiline: Schema.optionalKey(Schema.Boolean),
 	offset: Schema.Number,
 	length: Schema.Number
@@ -205,6 +231,12 @@ var YamlMap = class extends Schema.TaggedClass()("YamlMap", {
 * A YAML sequence AST node, representing an ordered list of
 * {@link (YamlNode:type)} values.
 *
+* - `commentBefore` — own-line comment text directly above the sequence.
+* - `comment` — trailing comment text: own-line comment lines after the
+*   sequence's last item (still at the sequence's item indent), or a
+*   same-line trailing comment for a flow sequence.
+* - `spaceBefore` — `true` when a blank line precedes the sequence.
+*
 * @public
 */
 var YamlSeq = class extends Schema.TaggedClass()("YamlSeq", {
@@ -212,7 +244,9 @@ var YamlSeq = class extends Schema.TaggedClass()("YamlSeq", {
 	tag: Schema.optionalKey(Schema.String),
 	anchor: Schema.optionalKey(Schema.String),
 	style: CollectionStyle,
+	commentBefore: Schema.optionalKey(Schema.String),
 	comment: Schema.optionalKey(Schema.String),
+	spaceBefore: Schema.optionalKey(Schema.Boolean),
 	sourceMultiline: Schema.optionalKey(Schema.Boolean),
 	offset: Schema.Number,
 	length: Schema.Number