@effected/yaml 0.25.1 → 0.26.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, 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 — inferring the lint config from files you already have — and decode straight into a validated domain schema.
+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 — inferring the lint config from files you already have — and decode straight into a validated domain schema.
 
 > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
 > Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
@@ -25,7 +25,7 @@ YAML is where untrusted text meets production systems: CI pipeline definitions,
 
 This package treats that as a first-class requirement rather than a footnote. An alias-expansion budget bounds the number of materialized nodes, a depth cap bounds collection nesting on both the parse and the stringify side, and both fire into the typed error channel. Hostile input produces a `YamlParseError` carrying structured `YamlDiagnostic` values with codes and positions; it never produces a `RangeError`, an unhandled defect or an exhausted heap.
 
-The rest follows from the same discipline. Parsing recovers from errors and aggregates every diagnostic into one failure rather than throwing on the first. Modifications are computed as edits against the original bytes, so comments and layout survive a change. Everything is a pure function or a schema: no IO, no services and no runtime dependency other than `effect` — the lexer, CST parser, composer and stringifier are vendored into the package with attribution rather than taken as a dependency. It is the largest package in the repo, and it earns that by owning its engine.
+The rest follows from the same discipline. Parsing recovers from errors and aggregates every diagnostic into one failure rather than throwing on the first. Modifications are computed as edits against the original bytes, so comments and layout survive a change. Everything is a pure function or a schema: no IO, no services and no runtime dependency other than `effect` and the dependency-free `@effected/source` (the line index every reported position comes from) — the lexer, CST parser, composer and stringifier are vendored into the package with attribution rather than taken as a dependency. It is the largest package in the repo, and it earns that by owning its engine.
 
 ## Install
 

package/Yaml.js

@@ -2,7 +2,7 @@ import { AliasExpansionBudgetExceeded, CollectionStyle, QuoteCompat, QuoteStyle,
 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 { YamlDiagnostic, lazyLineIndex } from "./YamlDiagnostic.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
 // src/Yaml.ts
@@ -207,7 +207,10 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };
-const toDiagnostics = (text, records) => records.map((r) => YamlDiagnostic.fromRaw(r, text));
+const toDiagnostics = (text, records) => {
+	const index = lazyLineIndex(text);
+	return records.map((r) => YamlDiagnostic.fromRaw(r, index()));
+};
 /**
 * Build the fatal {@link YamlParseError} for an alias-expansion "billion
 * laughs" blow-up. The offending expansion has no source span, so the

package/YamlDiagnostic.js

@@ -1,4 +1,5 @@
 import { YAML_COMPOSE_ERROR_CODES, YAML_LEX_ERROR_CODES, YAML_MODIFY_ERROR_CODES, YAML_PARSE_ERROR_CODES, YAML_STRINGIFY_ERROR_CODES, isFatalCode } from "./internal/diagnostics.js";
+import { LineIndex } from "@effected/source";
 import { Schema } from "effect";
 
 // src/YamlDiagnostic.ts
@@ -56,9 +57,16 @@ const YamlErrorCode = Schema.Union([
 * fatality is a property of the code — see {@link YamlDiagnostic.isFatal}.
 *
 * @remarks
-* The five-field positional core (`code`/`offset`/`length`/`line`/`character`)
-* is structurally identical to `@effected/jsonc`'s parse-error detail shape;
-* `message` is this package's additive extra.
+* Satisfies `@effected/source`'s `SourceDiagnostic<YamlErrorCode>`: the
+* positional core (`code`/`message`/`offset`/`length`/`line`/`character`)
+* the kit's format packages share, so a consumer printing or serving
+* diagnostics (an LSP server, a CLI annotation) is written once against that
+* shape. `line`/`character` are zero-based, `character` in UTF-16 code units,
+* with `\n`, `\r\n` and a bare `\r` as line breaks, YAML 1.2's own
+* `b-break` set: exactly `LineIndex.make(text).positionAt(offset)`. U+2028
+* and U+2029 are not line breaks (YAML 1.2 dropped them, the lexer never
+* treated them as one, and neither does an LSP client), and an offset at the
+* `\n` of a `\r\n` reads as the end of its line.
 *
 * @public
 */
@@ -86,12 +94,20 @@ var YamlDiagnostic = class YamlDiagnostic extends Schema.Class("YamlDiagnostic")
 	* deriving `line`/`character` from `offset` against the source `text`.
 	* Advanced — the parse/stringify entry points call this for you.
 	*
+	* @remarks
+	* Pass a line index already built over the source to materialize many
+	* records without rescanning the text; a string builds one. The
+	* parameter is the structural `SourceIndex`, so an index from any
+	* installed copy of `@effected/source` is accepted. An offset
+	* outside the source clamps into it, as `LineIndex.positionAt` does.
+	*
 	* @param raw - The engine record: `code`, `message`, `offset` and `length`.
-	* @param text - The source text the record's `offset` indexes into.
+	* @param text - The source text the record's `offset` indexes into, or a
+	*   `LineIndex` over it.
 	* @returns The diagnostic with `line` and `character` filled in.
 	*/
 	static fromRaw(raw, text) {
-		const { line, character } = lineChar(text, raw.offset);
+		const { line, character } = (typeof text === "string" ? LineIndex.make(text) : text).positionAt(raw.offset);
 		return YamlDiagnostic.make({
 			code: raw.code,
 			message: raw.message,
@@ -103,32 +119,18 @@ var YamlDiagnostic = class YamlDiagnostic extends Schema.Class("YamlDiagnostic")
 	}
 };
 /**
-* Compute the zero-based line/character position of `offset` within `text`.
-* Recognizes `\n`, `\r`, `\r\n`, LS and PS as line breaks, matching the
-* jsonc counterpart so positions are codec-generic.
+* A line index over `text`, built on first call and shared by every later
+* one: the parse entry points materialize all of a parse's diagnostics
+* against one index, and a parse with none never builds it.
+*
+* @internal
 */
-function lineChar(text, offset) {
-	let line = 0;
-	let lineStart = 0;
-	const limit = Math.min(offset, text.length);
-	for (let i = 0; i < limit; i++) {
-		const ch = text.charCodeAt(i);
-		if (ch === 10) {
-			line++;
-			lineStart = i + 1;
-		} else if (ch === 13) {
-			if (i + 1 < text.length && text.charCodeAt(i + 1) === 10) i++;
-			line++;
-			lineStart = i + 1;
-		} else if (ch === 8232 || ch === 8233) {
-			line++;
-			lineStart = i + 1;
-		}
-	}
-	return {
-		line,
-		character: offset - lineStart
+const lazyLineIndex = (text) => {
+	let index;
+	return () => {
+		index ??= LineIndex.make(text);
+		return index;
 	};
-}
+};
 
-export { YamlComposerErrorCode, YamlDiagnostic, YamlErrorCode, YamlLexErrorCode, YamlModifyErrorCode, YamlParseErrorCode, YamlStringifyErrorCode };
+export { YamlComposerErrorCode, YamlDiagnostic, YamlErrorCode, YamlLexErrorCode, YamlModifyErrorCode, YamlParseErrorCode, YamlStringifyErrorCode, lazyLineIndex };

package/YamlDocument.js

@@ -2,7 +2,7 @@ import { YamlNode } from "./YamlNode.js";
 import { composeAllDocuments, composeFirstDocument } from "./internal/composer/document.js";
 import { isFatalCode } from "./internal/diagnostics.js";
 import { stringifyDocument } from "./internal/stringifier.js";
-import { YamlDiagnostic } from "./YamlDiagnostic.js";
+import { YamlDiagnostic, lazyLineIndex } from "./YamlDiagnostic.js";
 import { YamlParseError, stringifyDefectToError } from "./Yaml.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
@@ -85,12 +85,13 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	*/
 	static parseResult(text, options) {
 		const raw = composeFirstDocument(text, toParseInput(options));
+		const index = lazyLineIndex(text);
 		const fatal = raw.errors.filter((e) => isFatalCode(e.code));
 		if (fatal.length > 0) return Result.fail(new YamlParseError({
-			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
+			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, index())),
 			input: text
 		}));
-		return Result.succeed(fromRawDocument(raw, text));
+		return Result.succeed(fromRawDocument(raw, index));
 	}
 	/**
 	* Parse a single YAML document, keeping the full AST, directives and
@@ -133,12 +134,13 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	*/
 	static parseAllResult(text, options) {
 		const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
+		const index = lazyLineIndex(text);
 		const fatal = [...streamErrors.filter((e) => e.code === "InvalidDirective"), ...documents.flatMap((d) => d.errors.filter((e) => isFatalCode(e.code)))];
 		if (fatal.length > 0) return Result.fail(new YamlParseError({
-			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, text)),
+			diagnostics: fatal.map((e) => YamlDiagnostic.fromRaw(e, index())),
 			input: text
 		}));
-		return Result.succeed(documents.map((raw) => fromRawDocument(raw, text)));
+		return Result.succeed(documents.map((raw) => fromRawDocument(raw, index)));
 	}
 	/**
 	* Parse a multi-document YAML stream into one {@link YamlDocument} per
@@ -285,15 +287,19 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 *
 * @internal
 */
-function documentFromRaw(raw, text) {
-	return fromRawDocument(raw, text);
+function documentFromRaw(raw, index) {
+	return fromRawDocument(raw, index);
 }
-/** Materialize a raw engine document into the public class. */
-function fromRawDocument(raw, text) {
+/**
+* Materialize a raw engine document into the public class. `index` is the
+* parse's one lazily built line index (`lazyLineIndex`), shared by every
+* document of a stream and built only when a diagnostic needs it.
+*/
+function fromRawDocument(raw, index) {
 	return new YamlDocument({
 		contents: raw.contents,
-		errors: raw.errors.map((e) => YamlDiagnostic.fromRaw(e, text)),
-		warnings: raw.warnings.map((w) => YamlDiagnostic.fromRaw(w, text)),
+		errors: raw.errors.map((e) => YamlDiagnostic.fromRaw(e, index())),
+		warnings: raw.warnings.map((w) => YamlDiagnostic.fromRaw(w, index())),
 		directives: raw.directives.map((d) => new YamlDirective({
 			name: d.name,
 			parameters: d.parameters

package/YamlLint.js

@@ -4,8 +4,10 @@ import { YamlParseError } from "./Yaml.js";
 import { documentFromRaw } from "./YamlDocument.js";
 import { YamlEdit } from "./YamlEdit.js";
 import { YamlLintDiagnostic } from "./YamlLintRule.js";
+import { endsWithLineBreak } from "./internal/rules/util.js";
 import { builtinOptionsSchemas, builtinRules } from "./internal/rules/catalog.js";
-import { YamlTokens } from "./YamlToken.js";
+import { tokensOf } from "./YamlToken.js";
+import { LineIndex } from "@effected/source";
 import { Result, Schema } from "effect";
 
 // src/YamlLint.ts
@@ -92,49 +94,38 @@ var YamlLintConfig = class YamlLintConfig extends Schema.Class("YamlLintConfig")
 	} });
 };
 /**
-* 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.
+* Split the indexed text into positioned lines: one per `LineIndex` line,
+* under the same `\n` / `\r\n` / bare `\r` rule the tokens and
+* diagnostics use, so a rule may index `ctx.lines` by any token's or
+* diagnostic's `line`. 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. The final empty
+* segment after a trailing line break is not a line, and empty input has no lines:
+* rules that count blank lines must not see a phantom line.
 */
-const buildLines = (text) => {
-	if (text === "") return [];
+const buildLines = (index) => {
+	if (index.text === "") return [];
+	const count = endsWithLineBreak(index.text) ? index.lineCount - 1 : index.lineCount;
 	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++;
-	}
+	for (let number = 0; number < count; number++) lines.push({
+		text: index.lineText(number),
+		offset: index.lineStart(number),
+		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).
+* Build the eager lint context: index the text once, 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;
-		}
-	});
+	const index = LineIndex.make(text);
 	return {
 		text,
-		lines: buildLines(text),
-		tokens,
-		document: documentFromRaw(composeFirstDocument(text, { uniqueKeys: false }), text)
+		lines: buildLines(index),
+		tokens: tokensOf(index),
+		document: documentFromRaw(composeFirstDocument(text, { uniqueKeys: false }), () => index)
 	};
 };
 /**

package/YamlToken.js

@@ -1,4 +1,5 @@
 import { lexAll } from "./internal/lexer.js";
+import { LineIndex } from "@effected/source";
 import { Result, Schema, Stream } from "effect";
 
 // src/YamlToken.ts
@@ -41,6 +42,13 @@ const YamlTokenKind = Schema.Literals([
 * - `line` / `character` — the zero-based position of the token's start,
 *   matching the `YamlDiagnostic` position vocabulary.
 *
+* @remarks
+* Satisfies `@effected/source`'s `SourceLocation`. `line` / `character` are
+* `LineIndex.make(source).positionAt(offset)`: zero-based, UTF-16 code
+* units, with `\n`, `\r\n` and a bare `\r` as line breaks (YAML 1.2's
+* `b-break`, the set the lexer emits a `newline` token for), so a token and a
+* `YamlDiagnostic` at the same offset always agree.
+*
 * @public
 */
 var YamlToken = class extends Schema.Class("YamlToken")({
@@ -54,30 +62,32 @@ var YamlToken = class extends Schema.Class("YamlToken")({
 /**
 * 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
+* `line`/`character` are DERIVED from each token's offset against the line
+* 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.
+*
+* Takes the caller's index so the lint context builds one index for its
+* tokens and its lines.
+*
+* @internal
 */
-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++;
+const tokensOf = (index) => {
+	const text = index.text;
+	return lexAll(text).map((token) => {
+		const { line, character } = index.positionAt(token.offset);
 		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]
+			character
 		});
 	});
 };
@@ -118,7 +128,7 @@ var YamlTokens = class YamlTokens {
 	* @returns A `Result` succeeding with every token in source order.
 	*/
 	static tokenize(text) {
-		return Result.succeed(promoteAll(text, lexAll(text)));
+		return Result.succeed(tokensOf(LineIndex.make(text)));
 	}
 	/**
 	* Tokenize YAML text as a lazy `Stream` of tokens — the derived form of
@@ -139,4 +149,4 @@ var YamlTokens = class YamlTokens {
 	}
 };
 
-export { YamlToken, YamlTokenKind, YamlTokens };
+export { YamlToken, YamlTokenKind, YamlTokens, tokensOf };

package/YamlVisitor.js

@@ -1,6 +1,6 @@
 import { YamlAlias, YamlMap, YamlScalar, YamlSeq } from "./YamlNode.js";
 import { composeAllDocuments } from "./internal/composer/document.js";
-import { YamlDiagnostic } from "./YamlDiagnostic.js";
+import { YamlDiagnostic, lazyLineIndex } from "./YamlDiagnostic.js";
 import { Data, Stream } from "effect";
 
 // src/YamlVisitor.ts
@@ -58,6 +58,7 @@ var YamlVisitor = class {
 	}
 };
 function* visitGen(text, options) {
+	const index = lazyLineIndex(text);
 	const { documents, streamErrors } = composeAllDocuments(text, {
 		strict: options?.strict,
 		maxAliasCount: options?.maxAliasCount,
@@ -66,11 +67,11 @@ function* visitGen(text, options) {
 	for (const raw of streamErrors) yield YamlVisitorEvent.Error({
 		path: [],
 		depth: 0,
-		diagnostic: YamlDiagnostic.fromRaw(raw, text)
+		diagnostic: YamlDiagnostic.fromRaw(raw, index())
 	});
-	for (const doc of documents) yield* walkDocument(doc, text);
+	for (const doc of documents) yield* walkDocument(doc, index);
 }
-function* walkDocument(doc, text) {
+function* walkDocument(doc, index) {
 	const path = [];
 	const depth = 0;
 	for (const dir of doc.directives) yield YamlVisitorEvent.Directive({
@@ -90,12 +91,12 @@ function* walkDocument(doc, text) {
 	for (const raw of doc.errors) yield YamlVisitorEvent.Error({
 		path,
 		depth,
-		diagnostic: YamlDiagnostic.fromRaw(raw, text)
+		diagnostic: YamlDiagnostic.fromRaw(raw, index())
 	});
 	for (const raw of doc.warnings) yield YamlVisitorEvent.Error({
 		path,
 		depth,
-		diagnostic: YamlDiagnostic.fromRaw(raw, text)
+		diagnostic: YamlDiagnostic.fromRaw(raw, index())
 	});
 	if (doc.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
 		path,