@effected/yaml 0.7.0 → 0.8.0

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

package/YamlToken.js

@@ -0,0 +1,139 @@
+import { lexAll } from "./internal/lexer.js";
+import { Result, Schema, Stream } from "effect";
+
+//#region src/YamlToken.ts
+/**
+* The 22 lexical token kinds produced by the YAML tokenizer.
+*
+* @public
+*/
+const YamlTokenKind = Schema.Literals([
+	"document-start",
+	"document-end",
+	"directive",
+	"tag",
+	"anchor",
+	"alias",
+	"scalar",
+	"block-map-start",
+	"block-map-key",
+	"block-map-value",
+	"block-seq-start",
+	"block-seq-entry",
+	"flow-map-start",
+	"flow-map-end",
+	"flow-seq-start",
+	"flow-seq-end",
+	"flow-separator",
+	"newline",
+	"whitespace",
+	"comment",
+	"byte-order-mark",
+	"error"
+]);
+/**
+* A single positioned YAML lexical token.
+*
+* - `kind` — the {@link (YamlTokenKind:type)}.
+* - `text` — the raw source slice the token covers; the position-fidelity
+*   invariant is `source.slice(offset, offset + length) === text`.
+* - `offset` / `length` — the token's span in UTF-16 code units.
+* - `line` / `character` — the zero-based position of the token's start,
+*   matching the `YamlDiagnostic` position vocabulary.
+*
+* @public
+*/
+var YamlToken = class extends Schema.Class("YamlToken")({
+	kind: YamlTokenKind,
+	text: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number,
+	line: Schema.Number,
+	character: Schema.Number
+}) {};
+/**
+* Promote the internal lexer tokens to the public shape.
+*
+* `line`/`character` are DERIVED from each token's offset against a
+* line-start index rather than copied from the internal token: the internal
+* `column` is a CST-parser vocabulary that carries the construct's INDENT on
+* the synthetic `block-map-start`/`block-seq-start` markers, not the token's
+* own position — the public surface promises the position. `text` is the RAW
+* source slice for the same reason: the internal `value` is the PROCESSED
+* form on quoted scalars (content without the quotes), while the public
+* contract is byte fidelity — the corpus conformance suite pins the tokens
+* tiling the source exactly.
+*/
+const promoteAll = (text, tokens) => {
+	const lineStarts = [0];
+	for (let i = 0; i < text.length; i++) if (text[i] === "\n") lineStarts.push(i + 1);
+	let line = 0;
+	return tokens.map((token) => {
+		if (token.offset < lineStarts[line]) line = 0;
+		while (line + 1 < lineStarts.length && lineStarts[line + 1] <= token.offset) line++;
+		return new YamlToken({
+			kind: token.kind,
+			text: text.slice(token.offset, token.offset + token.length),
+			offset: token.offset,
+			length: token.length,
+			line,
+			character: token.offset - lineStarts[line]
+		});
+	});
+};
+/**
+* Tokenizer statics. Not instantiable.
+*
+* @public
+*/
+var YamlTokens = class YamlTokens {
+	constructor() {}
+	/**
+	* Tokenize YAML text into the full positioned token array — the sync
+	* `Result` primitive (tokenizing is a pure batch transform; the
+	* {@link YamlTokens.stream} form is derived from this one, per the kit's
+	* sync-primitive policy).
+	*
+	* @remarks
+	* The failure channel is **reserved** (for future input-hardening guards)
+	* and never fires today: the lexer is total, and lexical errors surface as
+	* `"error"`-kind tokens **in the success array** so that linting can run
+	* on malformed input — the `parse-validity` lint rule exists precisely for
+	* documents that do not parse. Do not "fix" this method to fail on
+	* `"error"` tokens; that would make malformed documents unlintable.
+	*
+	* @example
+	* ```ts
+	* import { YamlTokens } from "@effected/yaml";
+	* import { Result } from "effect";
+	*
+	* const result = YamlTokens.tokenize("a: 1\n");
+	* if (Result.isSuccess(result)) {
+	*   result.success.map((t) => t.kind); // ["scalar", "block-map-start", ...]
+	* }
+	* ```
+	*/
+	static tokenize(text) {
+		return Result.succeed(promoteAll(text, lexAll(text)));
+	}
+	/**
+	* Tokenize YAML text as a lazy `Stream` of tokens — the derived form of
+	* {@link YamlTokens.tokenize} for genuinely incremental (SAX-style)
+	* consumers, parallel to `YamlVisitor.visit`.
+	*
+	* @remarks
+	* Derived from the sync primitive, so it shares its contract: lexical
+	* errors arrive as `"error"`-kind tokens in the stream, never as a stream
+	* failure. (The primitive's reserved failure channel would surface as a
+	* defect here; it never fires today.)
+	*/
+	static stream(text) {
+		return Stream.suspend(() => Result.match(YamlTokens.tokenize(text), {
+			onSuccess: (tokens) => Stream.fromIterable(tokens),
+			onFailure: (error) => Stream.die(error)
+		}));
+	}
+};
+
+//#endregion
+export { YamlToken, YamlTokenKind, YamlTokens };

package/YamlVisitor.js

@@ -79,9 +79,16 @@ function* walkDocument(doc, text) {
 	if (doc.comment !== void 0) yield YamlVisitorEvent.Comment({
 		path,
 		depth,
-		text: doc.comment
+		text: doc.comment,
+		placement: "leading"
 	});
 	if (doc.contents !== null) yield* walkNode(doc.contents, path, depth);
+	if (doc.commentAfter !== void 0) yield YamlVisitorEvent.Comment({
+		path,
+		depth,
+		text: doc.commentAfter,
+		placement: "trailing"
+	});
 	yield YamlVisitorEvent.DocumentEnd({
 		path,
 		depth
@@ -89,10 +96,17 @@ function* walkDocument(doc, text) {
 }
 function* walkNode(node, path, depth) {
 	if (node instanceof YamlScalar) {
+		if (node.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.commentBefore,
+			placement: "leading"
+		});
 		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
 			path,
 			depth,
-			text: node.comment
+			text: node.comment,
+			placement: "trailing"
 		});
 		yield YamlVisitorEvent.Scalar({
 			path,
@@ -108,10 +122,17 @@ function* walkNode(node, path, depth) {
 		name: node.name
 	});
 	else if (node instanceof YamlMap) {
+		if (node.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.commentBefore,
+			placement: "leading"
+		});
 		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
 			path,
 			depth,
-			text: node.comment
+			text: node.comment,
+			placement: "trailing"
 		});
 		yield YamlVisitorEvent.MapStart({
 			path,
@@ -126,10 +147,17 @@ function* walkNode(node, path, depth) {
 			depth
 		});
 	} else if (node instanceof YamlSeq) {
+		if (node.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.commentBefore,
+			placement: "leading"
+		});
 		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
 			path,
 			depth,
-			text: node.comment
+			text: node.comment,
+			placement: "trailing"
 		});
 		yield YamlVisitorEvent.SeqStart({
 			path,
@@ -153,10 +181,17 @@ function* walkPair(pair, parentPath, depth) {
 	const resolvedValue = pair.value instanceof YamlScalar ? pair.value.value : null;
 	const keySegment = typeof resolvedKey === "string" ? resolvedKey : typeof resolvedKey === "number" ? resolvedKey : String(resolvedKey);
 	const pairPath = [...parentPath, keySegment];
+	if (pair.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
+		path: pairPath,
+		depth,
+		text: pair.commentBefore,
+		placement: "leading"
+	});
 	if (pair.comment !== void 0) yield YamlVisitorEvent.Comment({
 		path: pairPath,
 		depth,
-		text: pair.comment
+		text: pair.comment,
+		placement: "trailing"
 	});
 	yield YamlVisitorEvent.Pair({
 		path: pairPath,