@effected/yaml 0.18.0 → 0.19.1

package/README.md

@@ -7,10 +7,10 @@
 
 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.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **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
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/Yaml.js

@@ -40,8 +40,7 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 * `false`.
 *
 * `lineWidth` controls column-based scalar folding. The default `0` (and any
-* value `<= 0`) never wraps, emitting byte-identical output to the historic
-* no-fold behavior; a positive value folds long plain, double-quoted and
+* value `<= 0`) never wraps; a positive value folds long plain, double-quoted and
 * block-folded (`>`) scalars at approximately that column, inserting only
 * semantically transparent line breaks. Block-literal (`|`) content is never
 * folded — literal blocks preserve their bytes by definition. Folding is a
@@ -49,15 +48,14 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 * helpers accept these options but do not fold (see `lineWidth`).
 *
 * `indentSequences` controls the presentation of block sequences nested under
-* a mapping key: `false` (the default) emits them at the key's column — the
-* kit's byte-compatible legacy form — while `true` indents them one level,
+* a mapping key: `false` (the default) emits them at the key's column, while
+* `true` indents them one level,
 * matching the `yaml` npm package's default output. Top-level sequences stay
 * at column zero in both modes.
 *
 * `quoteStyle` selects the quote character used when a `plain`-styled scalar
 * (the `defaultScalarStyle` default) turns out to require quoting: `"single"`
-* (the default) emits `'@parcel/watcher'` — the kit's byte-compatible legacy
-* form — while `"double"` emits `"@parcel/watcher"`, matching the `yaml` npm
+* (the default) emits `'@parcel/watcher'`, while `"double"` emits `"@parcel/watcher"`, matching the `yaml` npm
 * package's `singleQuote: false` output. It is a fallback selector only:
 * scalars that need no quoting stay plain, and an explicit
 * `defaultScalarStyle` of `"single-quoted"` or `"double-quoted"` still wins.
@@ -106,7 +104,7 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	indentSequences: Schema.optionalKey(Schema.Boolean),
 	/**
 	* Quote style used when a `plain`-styled scalar requires quoting. Default
-	* `"single"` — the released byte-compatible behavior. `"double"` renders
+	* `"single"`. `"double"` renders
 	* the same scalars double-quoted instead, matching the `yaml` npm
 	* package's `singleQuote: false` output.
 	*
@@ -118,7 +116,7 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	/**
 	* Additionally quote plain scalars a foreign resolution dialect would
 	* coerce to a non-string. Absent (the default) adds no quoting beyond the
-	* YAML 1.2 Core Schema rules — byte-identical to the released output.
+	* YAML 1.2 Core Schema rules.
 	*
 	* `"yaml-1.1"` quotes every plain scalar a YAML 1.1 parser (js-yaml,
 	* PyYAML, libyaml, and the `yaml` npm package's YAML 1.1 schema, whose
@@ -153,6 +151,13 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 * `code` field: read the code from the diagnostics —
 * `error.diagnostics[0].code` is the primary failure.
 *
+* @remarks
+* The `message` renders each diagnostic's position 1-based
+* (`line + 1:character + 1`) for human readers — a CLI printing this string
+* shows the line/column a person counts in their editor. The structured
+* {@link YamlDiagnostic} `line`/`character` fields stay 0-based (LSP
+* convention); the offset applies to the rendered message only.
+*
 * @public
 */
 var YamlParseError = class extends Schema.TaggedError()("YamlParseError", {
@@ -161,7 +166,7 @@ var YamlParseError = class extends Schema.TaggedError()("YamlParseError", {
 }) {
 	get message() {
 		const count = this.diagnostics.length;
-		const summary = this.diagnostics.map((d) => `${d.code} at ${d.line}:${d.character}`).join("; ");
+		const summary = this.diagnostics.map((d) => `${d.code} at ${d.line + 1}:${d.character + 1}`).join("; ");
 		return `YAML parse failed with ${count} error${count === 1 ? "" : "s"}: ${summary}`;
 	}
 };
@@ -315,7 +320,7 @@ const stringifyResultImpl = (value, options) => {
 /**
 * Collect the raw diagnostics that make a composed document a parse failure:
 * every fatal-code error, plus DuplicateKey warnings promoted to errors when
-* `uniqueKeys` is in force (the v3 `parse` contract). Order preserved:
+* `uniqueKeys` is in force. Order preserved:
 * fatals first, then promotions.
 */
 const failureRecords = (doc, uniqueKeys) => {
@@ -370,6 +375,12 @@ var Yaml = class Yaml {
 	*
 	* Defined in terms of {@link Yaml.parseResult} — synchronous callers can
 	* use that variant directly.
+	*
+	* @param text - The YAML source to parse.
+	* @param options - Optional {@link YamlParseOptions}; defaults apply for
+	*   omitted fields.
+	* @returns An `Effect` that succeeds with the decoded value, or fails with
+	*   the aggregate {@link YamlParseError}.
 	*/
 	static parse = Effect.fn("Yaml.parse")((text, options) => Effect.fromResult(Yaml.parseResult(text, options)));
 	/**
@@ -384,6 +395,12 @@ var Yaml = class Yaml {
 	*
 	* Defined in terms of {@link Yaml.parseAllResult} — synchronous callers
 	* can use that variant directly.
+	*
+	* @param text - The YAML stream to parse.
+	* @param options - Optional {@link YamlParseOptions}; defaults apply for
+	*   omitted fields.
+	* @returns An `Effect` that succeeds with one value per document, or fails
+	*   with the aggregate {@link YamlParseError}.
 	*/
 	static parseAll = Effect.fn("Yaml.parseAll")((text, options) => Effect.fromResult(Yaml.parseAllResult(text, options)));
 	/**
@@ -401,6 +418,12 @@ var Yaml = class Yaml {
 	* `"<<"` key on a plain JavaScript object is an ordinary string key that
 	* never carried merge semantics, so emitting it plain would silently turn
 	* ordinary data into a merge directive.
+	*
+	* @param value - The plain JavaScript value to stringify.
+	* @param options - Optional {@link YamlStringifyOptions}; defaults apply for
+	*   omitted fields.
+	* @returns An `Effect` that succeeds with the YAML text, or fails with
+	*   {@link YamlStringifyError}.
 	*/
 	static stringify = Effect.fn("Yaml.stringify")(function* (value, options) {
 		return yield* stringifyOrFail(value, options);
@@ -516,6 +539,11 @@ var Yaml = class Yaml {
 	* `replaceCh` (e.g. `" "`), each comment character is replaced instead,
 	* keeping all offsets stable. Quote-aware: `#` inside quoted scalars is
 	* content, not a comment. Pure and total.
+	*
+	* @param text - The YAML source to strip.
+	* @param replaceCh - Optional single character replacing each stripped
+	*   comment character (offset-preserving).
+	* @returns The text without comments.
 	*/
 	static stripComments(text, replaceCh) {
 		let result = "";
@@ -565,6 +593,10 @@ var Yaml = class Yaml {
 	* significant. Malformed input is never equal to anything — parse errors
 	* (or duplicate keys) on either side yield `false` rather than comparing
 	* recovery-parser artifacts. Pure and total.
+	*
+	* @param a - The first YAML source.
+	* @param b - The second YAML source.
+	* @returns `true` when `a` and `b` decode to structurally equal values.
 	*/
 	static equals(a, b) {
 		const va = parseForEquality(a);
@@ -576,6 +608,11 @@ var Yaml = class Yaml {
 	* Compare a YAML string against an existing JavaScript value with the
 	* same semantics as {@link Yaml.equals}: malformed `text` yields `false`.
 	* Pure and total.
+	*
+	* @param text - The YAML source to decode and compare.
+	* @param value - The plain JavaScript value to compare against.
+	* @returns `true` when `text` decodes to a value structurally equal to
+	*   `value`.
 	*/
 	static equalsValue(text, value) {
 		const v = parseForEquality(text);
@@ -628,11 +665,14 @@ var Yaml = class Yaml {
 	/**
 	* Compose {@link Yaml.fromString} with a target schema, yielding a
 	* `Schema<A, string>` that decodes YAML straight into a validated domain
-	* value — the single best consumer-facing feature of the library. The
-	* target's decoding/encoding service requirements flow through.
+	* value. The target's decoding/encoding service requirements flow through.
 	*
 	* Schema-producing: bind the result to a `const` on hot paths (see
 	* {@link Yaml.fromString}).
+	*
+	* @param target - The domain schema decoded values must satisfy.
+	* @param options - Optional {@link YamlParseOptions} applied on decode.
+	* @returns A `Schema.Codec<T, string>` decoding YAML text straight into `T`.
 	*/
 	static schema(target, options) {
 		return Yaml.fromString(options).pipe(Schema.decodeTo(target));

package/YamlDiagnostic.js

@@ -70,8 +70,10 @@ var YamlDiagnostic = class YamlDiagnostic extends Schema.Class("YamlDiagnostic")
 	/**
 	* The single fatal-code predicate: whether diagnostics with this code
 	* abort a parse (vs. being recoverable warnings-as-data). Declared once,
-	* as a property of the code — replacing the v3 source's three
-	* subtly-differing inline fatal lists.
+	* as a property of the code.
+	*
+	* @param code - The diagnostic code to classify.
+	* @returns `true` when diagnostics with `code` abort a parse.
 	*/
 	static isFatal(code) {
 		return isFatalCode(code);
@@ -80,6 +82,10 @@ var YamlDiagnostic = class YamlDiagnostic extends Schema.Class("YamlDiagnostic")
 	* Materialize a raw engine diagnostic record into a `YamlDiagnostic`,
 	* deriving `line`/`character` from `offset` against the source `text`.
 	* Advanced — the parse/stringify entry points call this for you.
+	*
+	* @param raw - The engine record: `code`, `message`, `offset` and `length`.
+	* @param text - The source text the record's `offset` indexes into.
+	* @returns The diagnostic with `line` and `character` filled in.
 	*/
 	static fromRaw(raw, text) {
 		const { line, character } = lineChar(text, raw.offset);

package/YamlDocument.js

@@ -34,6 +34,17 @@ var YamlDirective = class extends Schema.Class("YamlDirective")({
 * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
 * synthetic documents.
 *
+* @example
+* ```ts
+* import { YamlDocument } from "@effected/yaml";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const doc = yield* YamlDocument.parse("# header\nname: Alice\n");
+*   return doc.errors.length; // 0 — no recovered errors
+* });
+* ```
+*
 * @public
 */
 var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
@@ -52,6 +63,12 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* recovered diagnostics. Fails with the aggregate {@link YamlParseError}
 	* when any fatal-code diagnostic is present; non-fatal diagnostics are
 	* data on the returned document.
+	*
+	* @param text - The YAML source to parse.
+	* @param options - Optional {@link YamlParseOptions}; defaults apply for
+	*   omitted fields.
+	* @returns An `Effect` that succeeds with the {@link YamlDocument}, or fails
+	*   with {@link YamlParseError}.
 	*/
 	static parse = Effect.fn("YamlDocument.parse")(function* (text, options) {
 		const raw = composeFirstDocument(text, toParseInput(options));
@@ -66,6 +83,12 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* Parse a multi-document YAML stream into one {@link YamlDocument} per
 	* document. Any fatal diagnostic in any document — or a stream-level
 	* directive-placement error — fails the whole Effect.
+	*
+	* @param text - The YAML stream to parse.
+	* @param options - Optional {@link YamlParseOptions}; defaults apply for
+	*   omitted fields.
+	* @returns An `Effect` that succeeds with one {@link YamlDocument} per
+	*   document, or fails with {@link YamlParseError}.
 	*/
 	static parseAll = Effect.fn("YamlDocument.parseAll")(function* (text, options) {
 		const { documents, streamErrors } = composeAllDocuments(text, toParseInput(options));
@@ -84,6 +107,9 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* Schema-producing: each call returns a fresh schema whose derivation
 	* caches are not shared across calls; bind the result to a `const` on hot
 	* paths.
+	*
+	* @param options - Optional {@link YamlParseOptions} applied on decode.
+	* @returns A `Schema.Codec<YamlDocument, string>`.
 	*/
 	static schema(options) {
 		return Schema.String.pipe(Schema.decodeTo(Schema.instanceOf(YamlDocument), SchemaTransformation.transformEffect({
@@ -109,6 +135,11 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	* option. Callers that need folding should render the plain value
 	* instead — `Yaml.stringify(doc.toValue(), options)` — at the cost of
 	* the document-level framing and styles this path preserves.
+	*
+	* @param options - Optional {@link YamlStringifyOptions}; defaults apply for
+	*   omitted fields.
+	* @returns An `Effect` that succeeds with the YAML text, or fails with
+	*   {@link YamlStringifyError}.
 	*/
 	stringify(options) {
 		return Effect.try({

package/YamlEdit.js

@@ -17,9 +17,10 @@ var YamlRange = class extends Schema.Class("YamlRange")({
 * `content`. Set `length` to `0` to insert, `content` to `""` to delete.
 *
 * @remarks
-* Structurally identical to `@effected/jsonc`'s edit shape (same field names,
-* types and semantics) per the jsonc/yaml parity convention, so consumer code
-* can be written once over "a document codec's Edit/Range/Path".
+* Structurally identical to the edit shape of `@effected/jsonc`,
+* `@effected/toml` and `@effected/markdown` (same field names, types and
+* semantics), so consumer code can be written once over "a document codec's
+* Edit/Range/Path".
 *
 * @public
 */
@@ -33,6 +34,10 @@ var YamlEdit = class extends Schema.Class("YamlEdit")({
 	* reverse-offset order so earlier offsets stay valid; the input `edits`
 	* array is not mutated. Overlapping edits are a programmer error and throw
 	* as a defect — `YamlFormat` never produces them.
+	*
+	* @param text - The source text to edit.
+	* @param edits - The edits to apply, in any order.
+	* @returns The edited text.
 	*/
 	static applyAll(text, edits) {
 		const sorted = [...edits].sort((a, b) => b.offset - a.offset);

package/YamlFormat.js

@@ -15,8 +15,8 @@ import { Effect, Schema } from "effect";
 * field (derived, not hand-duplicated — including `indentSequences`,
 * `quoteStyle` and `quoteCompat`) plus
 * `preserveComments` (default `true`), `range` (restrict edits to a
-* region; see the module-level remarks on the `range` parameter vs. this
-* field) and `requoteScalars` (default `false`).
+* region; the positional `range` argument of {@link YamlFormat.format} takes
+* precedence over this field) and `requoteScalars` (default `false`).
 *
 * `requoteScalars` makes `quoteStyle` apply to scalars **already quoted in
 * the source** on the format path — by default formatting preserves an
@@ -259,7 +259,7 @@ function formatStream(text, documents, streamErrors, options) {
 * Before this was recursive, a mapping or sequence value fell through to the
 * node stringifier's `String(value)` fallback and landed in the document as
 * the literal text `[object Object]` — a silent corruption that only surfaced
-* on the next read (#642).
+* on the next read.
 *
 * The two conditions with no finite rendering fail typed rather than hanging
 * or overflowing the stack: a cycle raises `CircularReference` and a graph
@@ -472,7 +472,7 @@ function findExistingTarget(contents, path) {
 * resolved type — as does any plain target, so the stringifier's own
 * plain-safety rules decide whether the text needs quotes — under the
 * target's own context, so a flow indicator inside a value spliced into a
-* flow collection is quoted rather than corrupting the collection (#695). A
+* flow collection is quoted rather than corrupting the collection. A
 * rendering that spans lines (folding, block styles) bails out: the fast
 * path never introduces a line break inside the spliced region.
 */
@@ -515,7 +515,7 @@ function regionalRenderPreservesValue(rendered, value, inFlow) {
 	return Object.is(node.value, value);
 }
 /**
-* Attempt the region-confined scalar splice for `modify` (#659): replace
+* Attempt the region-confined scalar splice for `modify`: replace
 * only the target scalar's byte range, re-emitting its original quote
 * character and leaving line endings (and every other byte) elsewhere
 * untouched. Returns the single edit, an empty array for a no-op
@@ -547,7 +547,22 @@ function tryRegionalScalarEdit(text, doc, path, value, options) {
 	}];
 }
 /**
-* Formatting and modification statics. Not instantiable.
+* Formats YAML text and modifies values at a path as byte-minimal edits that
+* preserve comments and layout elsewhere. Not instantiable.
+*
+* @example
+* ```ts
+* import { YamlFormat } from "@effected/yaml";
+* import { Effect } from "effect";
+*
+* const formatted = YamlFormat.formatToString("a:   1\nb:\n    - x\n    - y # c\n");
+* // => "a: 1\nb:\n- x\n- y # c\n"
+*
+* const program = Effect.gen(function* () {
+*   return yield* YamlFormat.modifyToString("port: 3000 # dev\n", ["port"], 8080);
+*   // => "port: 8080 # dev\n"
+* });
+* ```
 *
 * @remarks
 * `format`/`formatToString` are pure and total (edit computation never fails
@@ -573,8 +588,8 @@ function tryRegionalScalarEdit(text, doc, path, value, options) {
 * (`!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.
+* diagnostic. Directive re-emission is unimplemented, and the refusal is what
+* stops the corruption.
 *
 * @public
 */
@@ -604,6 +619,12 @@ var YamlFormat = class YamlFormat {
 	* directives is left untouched. Detection is directive-token-level: a
 	* literal `%TAG` inside a scalar is content and formats normally.
 	*
+	* @param text - The YAML source to format.
+	* @param range - Optional sub-range; only edits fully within it are returned.
+	* @param options - Optional {@link YamlFormattingOptions}.
+	* @returns The edits that bring `text` to canonical shape; apply them with
+	*   `YamlEdit.applyAll`. Empty when the input cannot be formatted faithfully.
+	*
 	* @remarks
 	* The positional `range` argument takes precedence over
 	* `options?.range` when both are given; either accepts a plain
@@ -646,6 +667,12 @@ var YamlFormat = class YamlFormat {
 	* 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.
+	*
+	* @param text - The YAML source to format.
+	* @param range - Optional sub-range; only edits fully within it are applied.
+	* @param options - Optional {@link YamlFormattingOptions}.
+	* @returns The formatted text, or `text` unchanged when it cannot be
+	*   formatted faithfully.
 	*/
 	static formatToString(text, range, options) {
 		return YamlEdit.applyAll(text, YamlFormat.format(text, range, options));
@@ -661,15 +688,12 @@ var YamlFormat = class YamlFormat {
 	* sequence and any other non-null object as a block mapping over its own
 	* enumerable string keys, recursively — the same lowering
 	* {@link Yaml.stringify} applies to the same value, so `modify` and
-	* `stringify` agree on what a given JavaScript value means. (Before
-	* 0.14.0 only scalars were lowered and a mapping or sequence value was
-	* coerced through `String(value)`, writing the literal text
-	* `[object Object]` into the document — see #642.) For a synthesized
+	* `stringify` agree on what a given JavaScript value means. For a synthesized
 	* subtree (an object/array value) only the surrounding document is
 	* preserved byte-for-byte; the subtree carries no comments and takes the
 	* stringifier's styles.
 	*
-	* **Scalar replacement is region-confined and quote-preserving (#659).**
+	* **Scalar replacement is region-confined and quote-preserving.**
 	* When the path resolves to an existing single-line `plain`,
 	* `single-quoted`, or `double-quoted` scalar with no tag or anchor, and
 	* the replacement is a string, number, or boolean, `modify` splices
@@ -710,6 +734,15 @@ var YamlFormat = class YamlFormat {
 	* directive re-emission is unimplemented, not undesired. A literal
 	* `%TAG` inside a scalar is content and does not trigger the refusal.
 	*
+	* @param text - The YAML source to modify.
+	* @param path - The location to insert, replace or remove.
+	* @param value - The JavaScript value to write; `undefined` removes the
+	*   target instead.
+	* @param options - Optional {@link YamlStringifyOptions} for the
+	*   re-stringify step.
+	* @returns An `Effect` that succeeds with the edits to apply (via
+	*   `YamlEdit.applyAll`), or fails with {@link YamlModificationError}.
+	*
 	* @remarks
 	* `options` is a bare {@link YamlStringifyOptions} — it controls only the
 	* internal re-stringify step, not a range (there is no range to restrict
@@ -770,6 +803,15 @@ var YamlFormat = class YamlFormat {
 	* error channel, including the single-document contract's
 	* `MultiDocumentStream` refusal and the `DirectiveCarryingDocument`
 	* refusal of `%YAML`/`%TAG`-carrying documents.
+	*
+	* @param text - The YAML source to modify.
+	* @param path - The location to insert, replace or remove.
+	* @param value - The JavaScript value to write; `undefined` removes the
+	*   target instead.
+	* @param options - Optional {@link YamlStringifyOptions} for the
+	*   re-stringify step.
+	* @returns An `Effect` that succeeds with the modified text, or fails with
+	*   {@link YamlModificationError}.
 	*/
 	static modifyToString = Effect.fn("YamlFormat.modifyToString")(function* (text, path, value, options) {
 		const edits = yield* YamlFormat.modify(text, path, value, options);

package/YamlLintRule.js

@@ -32,7 +32,7 @@ var YamlLintDiagnostic = class extends Schema.Class("YamlLintDiagnostic")({
 	fix: Schema.optionalKey(YamlEdit)
 }) {};
 /**
-* One categorical style observation (#345): a single occurrence of a style
+* One categorical style observation: a single occurrence of a style
 * choice in the source, voting a `value` for an inference `dimension`.
 *
 * The `dimension` IS the rule's option key and the `value` IS that option's
@@ -64,7 +64,7 @@ var StyleVote = class extends Schema.TaggedClass()("StyleVote", {
 	character: Schema.Number
 }) {};
 /**
-* One measured style floor (#345): a value the source PROVES is at least
+* One measured style floor: a value the source PROVES is at least
 * `value`, without proving what the configured limit should be — the longest
 * observed line proves `line-length.max` is at least that long, not what it
 * is. Floors are carried in the evidence for callers that want them and are

package/YamlToken.js

@@ -82,7 +82,9 @@ const promoteAll = (text, tokens) => {
 	});
 };
 /**
-* Tokenizer statics. Not instantiable.
+* Tokenizes YAML text into positioned tokens, as a complete array or a lazy
+* `Stream`, for lint- and editor-class consumers. Never fails on malformed
+* input: lexical errors arrive as `"error"`-kind tokens. Not instantiable.
 *
 * @public
 */
@@ -91,12 +93,11 @@ var YamlTokens = class YamlTokens {
 	/**
 	* 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).
+	* {@link YamlTokens.stream} form is derived from this one).
 	*
 	* @remarks
-	* The failure channel is **reserved** (for future input-hardening guards)
-	* and never fires today: the lexer is total, and lexical errors surface as
+	* The failure channel is **reserved** for 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
@@ -112,6 +113,9 @@ var YamlTokens = class YamlTokens {
 	*   result.success.map((t) => t.kind); // ["scalar", "block-map-start", ...]
 	* }
 	* ```
+	*
+	* @param text - The YAML source to tokenize.
+	* @returns A `Result` succeeding with every token in source order.
 	*/
 	static tokenize(text) {
 		return Result.succeed(promoteAll(text, lexAll(text)));

package/YamlVisitor.js

@@ -13,7 +13,23 @@ import { Data, Stream } from "effect";
 */
 const YamlVisitorEvent = Data.taggedEnum();
 /**
-* SAX-style YAML AST visitor statics. Not instantiable.
+* Walks YAML text as a lazy `Stream` of typed events — documents, collections,
+* pairs, scalars, aliases, comments, directives and recovered errors — in
+* document order. Not instantiable.
+*
+* @example
+* ```ts
+* import { YamlVisitor, YamlVisitorEvent } from "@effected/yaml";
+* import { Effect, Stream } from "effect";
+*
+* // Mapping keys are scalar events too, so keys and values interleave.
+* const scalars = YamlVisitor.visit("a: 1\nb:\n  - x\n").pipe(
+*   Stream.filter(YamlVisitorEvent.$is("Scalar")),
+*   Stream.map((event) => event.value),
+*   Stream.runCollect,
+* );
+* // Effect.runSync(scalars) // => ["a", 1, "b", "x"]
+* ```
 *
 * @public
 */
@@ -31,6 +47,11 @@ var YamlVisitor = class {
 	* (fatal or not, including an exceeded `maxAliasCount`, recorded as
 	* `AliasCountExceeded`) surface as `Error` events inside the stream rather
 	* than failing it.
+	*
+	* @param text - The YAML source to visit.
+	* @param options - Optional {@link YamlParseOptions} controlling composition.
+	* @returns A lazy `Stream` of `YamlVisitorEvent`, infallible at the type
+	*   level.
 	*/
 	static visit(text, options) {
 		return Stream.fromIterable(visitGen(text, options));

package/index.d.ts

@@ -99,14 +99,20 @@ export declare class YamlDiagnostic extends YamlDiagnostic_base {
   /**
    * The single fatal-code predicate: whether diagnostics with this code
    * abort a parse (vs. being recoverable warnings-as-data). Declared once,
-   * as a property of the code — replacing the v3 source's three
-   * subtly-differing inline fatal lists.
+   * as a property of the code.
+   *
+   * @param code - The diagnostic code to classify.
+   * @returns `true` when diagnostics with `code` abort a parse.
    */
   static isFatal(code: YamlErrorCode): boolean;
   /**
    * Materialize a raw engine diagnostic record into a `YamlDiagnostic`,
    * deriving `line`/`character` from `offset` against the source `text`.
    * Advanced — the parse/stringify entry points call this for you.
+   *
+   * @param raw - The engine record: `code`, `message`, `offset` and `length`.
+   * @param text - The source text the record's `offset` indexes into.
+   * @returns The diagnostic with `line` and `character` filled in.
    */
   static fromRaw(raw: {
     readonly code: YamlErrorCode;
@@ -166,7 +172,7 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
   readonly indentSequences: Schema.optionalKey<Schema.Boolean>;
   /**
    * Quote style used when a `plain`-styled scalar requires quoting. Default
-   * `"single"` — the released byte-compatible behavior. `"double"` renders
+   * `"single"`. `"double"` renders
    * the same scalars double-quoted instead, matching the `yaml` npm
    * package's `singleQuote: false` output.
    *
@@ -178,7 +184,7 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
   /**
    * Additionally quote plain scalars a foreign resolution dialect would
    * coerce to a non-string. Absent (the default) adds no quoting beyond the
-   * YAML 1.2 Core Schema rules — byte-identical to the released output.
+   * YAML 1.2 Core Schema rules.
    *
    * `"yaml-1.1"` quotes every plain scalar a YAML 1.1 parser (js-yaml,
    * PyYAML, libyaml, and the `yaml` npm package's YAML 1.1 schema, whose
@@ -214,8 +220,7 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  * `false`.
  *
  * `lineWidth` controls column-based scalar folding. The default `0` (and any
- * value `<= 0`) never wraps, emitting byte-identical output to the historic
- * no-fold behavior; a positive value folds long plain, double-quoted and
+ * value `<= 0`) never wraps; a positive value folds long plain, double-quoted and
  * block-folded (`>`) scalars at approximately that column, inserting only
  * semantically transparent line breaks. Block-literal (`|`) content is never
  * folded — literal blocks preserve their bytes by definition. Folding is a
@@ -223,15 +228,14 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  * helpers accept these options but do not fold (see `lineWidth`).
  *
  * `indentSequences` controls the presentation of block sequences nested under
- * a mapping key: `false` (the default) emits them at the key's column — the
- * kit's byte-compatible legacy form — while `true` indents them one level,
+ * a mapping key: `false` (the default) emits them at the key's column, while
+ * `true` indents them one level,
  * matching the `yaml` npm package's default output. Top-level sequences stay
  * at column zero in both modes.
  *
  * `quoteStyle` selects the quote character used when a `plain`-styled scalar
  * (the `defaultScalarStyle` default) turns out to require quoting: `"single"`
- * (the default) emits `'@parcel/watcher'` — the kit's byte-compatible legacy
- * form — while `"double"` emits `"@parcel/watcher"`, matching the `yaml` npm
+ * (the default) emits `'@parcel/watcher'`, while `"double"` emits `"@parcel/watcher"`, matching the `yaml` npm
  * package's `singleQuote: false` output. It is a fallback selector only:
  * scalars that need no quoting stay plain, and an explicit
  * `defaultScalarStyle` of `"single-quoted"` or `"double-quoted"` still wins.
@@ -270,6 +274,13 @@ declare const YamlParseError_base: Schema.Class<YamlParseError, Schema.TaggedStr
  * `code` field: read the code from the diagnostics —
  * `error.diagnostics[0].code` is the primary failure.
  *
+ * @remarks
+ * The `message` renders each diagnostic's position 1-based
+ * (`line + 1:character + 1`) for human readers — a CLI printing this string
+ * shows the line/column a person counts in their editor. The structured
+ * {@link YamlDiagnostic} `line`/`character` fields stay 0-based (LSP
+ * convention); the offset applies to the rendered message only.
+ *
  * @public
  */
 export declare class YamlParseError extends YamlParseError_base {
@@ -346,6 +357,12 @@ export declare class Yaml {
    *
    * Defined in terms of {@link Yaml.parseResult} — synchronous callers can
    * use that variant directly.
+   *
+   * @param text - The YAML source to parse.
+   * @param options - Optional {@link YamlParseOptions}; defaults apply for
+   *   omitted fields.
+   * @returns An `Effect` that succeeds with the decoded value, or fails with
+   *   the aggregate {@link YamlParseError}.
    */
   static readonly parse: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<unknown, YamlParseError, never>;
   /**
@@ -360,6 +377,12 @@ export declare class Yaml {
    *
    * Defined in terms of {@link Yaml.parseAllResult} — synchronous callers
    * can use that variant directly.
+   *
+   * @param text - The YAML stream to parse.
+   * @param options - Optional {@link YamlParseOptions}; defaults apply for
+   *   omitted fields.
+   * @returns An `Effect` that succeeds with one value per document, or fails
+   *   with the aggregate {@link YamlParseError}.
    */
   static readonly parseAll: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<readonly unknown[], YamlParseError, never>;
   /**
@@ -377,6 +400,12 @@ export declare class Yaml {
    * `"<<"` key on a plain JavaScript object is an ordinary string key that
    * never carried merge semantics, so emitting it plain would silently turn
    * ordinary data into a merge directive.
+   *
+   * @param value - The plain JavaScript value to stringify.
+   * @param options - Optional {@link YamlStringifyOptions}; defaults apply for
+   *   omitted fields.
+   * @returns An `Effect` that succeeds with the YAML text, or fails with
+   *   {@link YamlStringifyError}.
    */
   static readonly stringify: (value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlStringifyError, never>;
   /**
@@ -484,6 +513,11 @@ export declare class Yaml {
    * `replaceCh` (e.g. `" "`), each comment character is replaced instead,
    * keeping all offsets stable. Quote-aware: `#` inside quoted scalars is
    * content, not a comment. Pure and total.
+   *
+   * @param text - The YAML source to strip.
+   * @param replaceCh - Optional single character replacing each stripped
+   *   comment character (offset-preserving).
+   * @returns The text without comments.
    */
   static stripComments(text: string, replaceCh?: string): string;
   /**
@@ -492,12 +526,21 @@ export declare class Yaml {
    * significant. Malformed input is never equal to anything — parse errors
    * (or duplicate keys) on either side yield `false` rather than comparing
    * recovery-parser artifacts. Pure and total.
+   *
+   * @param a - The first YAML source.
+   * @param b - The second YAML source.
+   * @returns `true` when `a` and `b` decode to structurally equal values.
    */
   static equals(a: string, b: string): boolean;
   /**
    * Compare a YAML string against an existing JavaScript value with the
    * same semantics as {@link Yaml.equals}: malformed `text` yields `false`.
    * Pure and total.
+   *
+   * @param text - The YAML source to decode and compare.
+   * @param value - The plain JavaScript value to compare against.
+   * @returns `true` when `text` decodes to a value structurally equal to
+   *   `value`.
    */
   static equalsValue(text: string, value: unknown): boolean;
   /**
@@ -528,11 +571,14 @@ export declare class Yaml {
   /**
    * Compose {@link Yaml.fromString} with a target schema, yielding a
    * `Schema<A, string>` that decodes YAML straight into a validated domain
-   * value — the single best consumer-facing feature of the library. The
-   * target's decoding/encoding service requirements flow through.
+   * value. The target's decoding/encoding service requirements flow through.
    *
    * Schema-producing: bind the result to a `const` on hot paths (see
    * {@link Yaml.fromString}).
+   *
+   * @param target - The domain schema decoded values must satisfy.
+   * @param options - Optional {@link YamlParseOptions} applied on decode.
+   * @returns A `Schema.Codec<T, string>` decoding YAML text straight into `T`.
    */
   static schema<T, E, RD = never, RE = never>(target: Schema.Codec<T, E, RD, RE>, options?: YamlParseOptions): Schema.Codec<T, string, RD, RE>;
   /**
@@ -612,9 +658,10 @@ declare const YamlEdit_base: Schema.Class<YamlEdit, Schema.Struct<{
  * `content`. Set `length` to `0` to insert, `content` to `""` to delete.
  *
  * @remarks
- * Structurally identical to `@effected/jsonc`'s edit shape (same field names,
- * types and semantics) per the jsonc/yaml parity convention, so consumer code
- * can be written once over "a document codec's Edit/Range/Path".
+ * Structurally identical to the edit shape of `@effected/jsonc`,
+ * `@effected/toml` and `@effected/markdown` (same field names, types and
+ * semantics), so consumer code can be written once over "a document codec's
+ * Edit/Range/Path".
  *
  * @public
  */
@@ -624,6 +671,10 @@ export declare class YamlEdit extends YamlEdit_base {
    * reverse-offset order so earlier offsets stay valid; the input `edits`
    * array is not mutated. Overlapping edits are a programmer error and throw
    * as a defect — `YamlFormat` never produces them.
+   *
+   * @param text - The source text to edit.
+   * @param edits - The edits to apply, in any order.
+   * @returns The edited text.
    */
   static applyAll(text: string, edits: ReadonlyArray<YamlEdit>): string;
 }
@@ -980,6 +1031,17 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
  * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
  * synthetic documents.
  *
+ * @example
+ * ```ts
+ * import { YamlDocument } from "@effected/yaml";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const doc = yield* YamlDocument.parse("# header\nname: Alice\n");
+ *   return doc.errors.length; // 0 — no recovered errors
+ * });
+ * ```
+ *
  * @public
  */
 export declare class YamlDocument extends YamlDocument_base {
@@ -988,12 +1050,24 @@ export declare class YamlDocument extends YamlDocument_base {
    * recovered diagnostics. Fails with the aggregate {@link YamlParseError}
    * when any fatal-code diagnostic is present; non-fatal diagnostics are
    * data on the returned document.
+   *
+   * @param text - The YAML source to parse.
+   * @param options - Optional {@link YamlParseOptions}; defaults apply for
+   *   omitted fields.
+   * @returns An `Effect` that succeeds with the {@link YamlDocument}, or fails
+   *   with {@link YamlParseError}.
    */
   static readonly parse: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<YamlDocument, YamlParseError, never>;
   /**
    * Parse a multi-document YAML stream into one {@link YamlDocument} per
    * document. Any fatal diagnostic in any document — or a stream-level
    * directive-placement error — fails the whole Effect.
+   *
+   * @param text - The YAML stream to parse.
+   * @param options - Optional {@link YamlParseOptions}; defaults apply for
+   *   omitted fields.
+   * @returns An `Effect` that succeeds with one {@link YamlDocument} per
+   *   document, or fails with {@link YamlParseError}.
    */
   static readonly parseAll: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<readonly YamlDocument[], YamlParseError, never>;
   /**
@@ -1004,6 +1078,9 @@ export declare class YamlDocument extends YamlDocument_base {
    * Schema-producing: each call returns a fresh schema whose derivation
    * caches are not shared across calls; bind the result to a `const` on hot
    * paths.
+   *
+   * @param options - Optional {@link YamlParseOptions} applied on decode.
+   * @returns A `Schema.Codec<YamlDocument, string>`.
    */
   static schema(options?: YamlParseOptions): Schema.Codec<YamlDocument, string>;
   /**
@@ -1024,6 +1101,11 @@ export declare class YamlDocument extends YamlDocument_base {
    * option. Callers that need folding should render the plain value
    * instead — `Yaml.stringify(doc.toValue(), options)` — at the cost of
    * the document-level framing and styles this path preserves.
+   *
+   * @param options - Optional {@link YamlStringifyOptions}; defaults apply for
+   *   omitted fields.
+   * @returns An `Effect` that succeeds with the YAML text, or fails with
+   *   {@link YamlStringifyError}.
    */
   stringify(options?: YamlStringifyOptions): Effect.Effect<string, YamlStringifyError>;
   /**
@@ -1066,8 +1148,8 @@ declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, Sc
  * field (derived, not hand-duplicated — including `indentSequences`,
  * `quoteStyle` and `quoteCompat`) plus
  * `preserveComments` (default `true`), `range` (restrict edits to a
- * region; see the module-level remarks on the `range` parameter vs. this
- * field) and `requoteScalars` (default `false`).
+ * region; the positional `range` argument of {@link YamlFormat.format} takes
+ * precedence over this field) and `requoteScalars` (default `false`).
  *
  * `requoteScalars` makes `quoteStyle` apply to scalars **already quoted in
  * the source** on the format path — by default formatting preserves an
@@ -1126,7 +1208,22 @@ export declare class YamlModificationError extends YamlModificationError_base {
   get message(): string;
 }
 /**
- * Formatting and modification statics. Not instantiable.
+ * Formats YAML text and modifies values at a path as byte-minimal edits that
+ * preserve comments and layout elsewhere. Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { YamlFormat } from "@effected/yaml";
+ * import { Effect } from "effect";
+ *
+ * const formatted = YamlFormat.formatToString("a:   1\nb:\n    - x\n    - y # c\n");
+ * // => "a: 1\nb:\n- x\n- y # c\n"
+ *
+ * const program = Effect.gen(function* () {
+ *   return yield* YamlFormat.modifyToString("port: 3000 # dev\n", ["port"], 8080);
+ *   // => "port: 8080 # dev\n"
+ * });
+ * ```
  *
  * @remarks
  * `format`/`formatToString` are pure and total (edit computation never fails
@@ -1152,8 +1249,8 @@ export declare class YamlModificationError extends YamlModificationError_base {
  * (`!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.
+ * diagnostic. Directive re-emission is unimplemented, and the refusal is what
+ * stops the corruption.
  *
  * @public
  */
@@ -1183,6 +1280,12 @@ export declare class YamlFormat {
    * directives is left untouched. Detection is directive-token-level: a
    * literal `%TAG` inside a scalar is content and formats normally.
    *
+   * @param text - The YAML source to format.
+   * @param range - Optional sub-range; only edits fully within it are returned.
+   * @param options - Optional {@link YamlFormattingOptions}.
+   * @returns The edits that bring `text` to canonical shape; apply them with
+   *   `YamlEdit.applyAll`. Empty when the input cannot be formatted faithfully.
+   *
    * @remarks
    * The positional `range` argument takes precedence over
    * `options?.range` when both are given; either accepts a plain
@@ -1214,6 +1317,12 @@ export declare class YamlFormat {
    * 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.
+   *
+   * @param text - The YAML source to format.
+   * @param range - Optional sub-range; only edits fully within it are applied.
+   * @param options - Optional {@link YamlFormattingOptions}.
+   * @returns The formatted text, or `text` unchanged when it cannot be
+   *   formatted faithfully.
    */
   static formatToString(text: string, range?: YamlRangeLike, options?: YamlFormattingOptions): string;
   /**
@@ -1227,15 +1336,12 @@ export declare class YamlFormat {
    * sequence and any other non-null object as a block mapping over its own
    * enumerable string keys, recursively — the same lowering
    * {@link Yaml.stringify} applies to the same value, so `modify` and
-   * `stringify` agree on what a given JavaScript value means. (Before
-   * 0.14.0 only scalars were lowered and a mapping or sequence value was
-   * coerced through `String(value)`, writing the literal text
-   * `[object Object]` into the document — see #642.) For a synthesized
+   * `stringify` agree on what a given JavaScript value means. For a synthesized
    * subtree (an object/array value) only the surrounding document is
    * preserved byte-for-byte; the subtree carries no comments and takes the
    * stringifier's styles.
    *
-   * **Scalar replacement is region-confined and quote-preserving (#659).**
+   * **Scalar replacement is region-confined and quote-preserving.**
    * When the path resolves to an existing single-line `plain`,
    * `single-quoted`, or `double-quoted` scalar with no tag or anchor, and
    * the replacement is a string, number, or boolean, `modify` splices
@@ -1276,6 +1382,15 @@ export declare class YamlFormat {
    * directive re-emission is unimplemented, not undesired. A literal
    * `%TAG` inside a scalar is content and does not trigger the refusal.
    *
+   * @param text - The YAML source to modify.
+   * @param path - The location to insert, replace or remove.
+   * @param value - The JavaScript value to write; `undefined` removes the
+   *   target instead.
+   * @param options - Optional {@link YamlStringifyOptions} for the
+   *   re-stringify step.
+   * @returns An `Effect` that succeeds with the edits to apply (via
+   *   `YamlEdit.applyAll`), or fails with {@link YamlModificationError}.
+   *
    * @remarks
    * `options` is a bare {@link YamlStringifyOptions} — it controls only the
    * internal re-stringify step, not a range (there is no range to restrict
@@ -1288,6 +1403,15 @@ export declare class YamlFormat {
    * error channel, including the single-document contract's
    * `MultiDocumentStream` refusal and the `DirectiveCarryingDocument`
    * refusal of `%YAML`/`%TAG`-carrying documents.
+   *
+   * @param text - The YAML source to modify.
+   * @param path - The location to insert, replace or remove.
+   * @param value - The JavaScript value to write; `undefined` removes the
+   *   target instead.
+   * @param options - Optional {@link YamlStringifyOptions} for the
+   *   re-stringify step.
+   * @returns An `Effect` that succeeds with the modified text, or fails with
+   *   {@link YamlModificationError}.
    */
   static readonly modifyToString: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlModificationError, never>;
 }
@@ -1327,7 +1451,9 @@ declare const YamlToken_base: Schema.Class<YamlToken, Schema.Struct<{
  */
 export declare class YamlToken extends YamlToken_base {}
 /**
- * Tokenizer statics. Not instantiable.
+ * Tokenizes YAML text into positioned tokens, as a complete array or a lazy
+ * `Stream`, for lint- and editor-class consumers. Never fails on malformed
+ * input: lexical errors arrive as `"error"`-kind tokens. Not instantiable.
  *
  * @public
  */
@@ -1336,12 +1462,11 @@ export declare class YamlTokens {
   /**
    * 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).
+   * {@link YamlTokens.stream} form is derived from this one).
    *
    * @remarks
-   * The failure channel is **reserved** (for future input-hardening guards)
-   * and never fires today: the lexer is total, and lexical errors surface as
+   * The failure channel is **reserved** for 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
@@ -1357,6 +1482,9 @@ export declare class YamlTokens {
    *   result.success.map((t) => t.kind); // ["scalar", "block-map-start", ...]
    * }
    * ```
+   *
+   * @param text - The YAML source to tokenize.
+   * @returns A `Result` succeeding with every token in source order.
    */
   static tokenize(text: string): Result.Result<ReadonlyArray<YamlToken>, YamlParseError>;
   /**
@@ -1453,7 +1581,7 @@ declare const StyleVote_base: Schema.Class<StyleVote, Schema.TaggedStruct<"Style
   readonly character: Schema.Number;
 }>, {}>;
 /**
- * One categorical style observation (#345): a single occurrence of a style
+ * One categorical style observation: a single occurrence of a style
  * choice in the source, voting a `value` for an inference `dimension`.
  *
  * The `dimension` IS the rule's option key and the `value` IS that option's
@@ -1478,7 +1606,7 @@ declare const StyleFloor_base: Schema.Class<StyleFloor, Schema.TaggedStruct<"Sty
   readonly value: Schema.Number;
 }>, {}>;
 /**
- * One measured style floor (#345): a value the source PROVES is at least
+ * One measured style floor: a value the source PROVES is at least
  * `value`, without proving what the configured limit should be — the longest
  * observed line proves `line-length.max` is at least that long, not what it
  * is. Floors are carried in the evidence for callers that want them and are
@@ -1508,7 +1636,7 @@ type StyleObservation = StyleVote | StyleFloor;
  * rules receive options already validated against their exported options
  * schema, custom rules validate their own.
  *
- * `infer` is the optional config-inference hook (#345): it reports the style
+ * `infer` is the optional config-inference hook: it reports the style
  * the source already follows as per-occurrence {@link StyleObservation}s, so
  * detection logic lives beside the check logic that polices the same
  * dimension (and shares its fixtures). Rules with no detectable style — the
@@ -1560,9 +1688,8 @@ declare const YamlLintConfig_base: Schema.Class<YamlLintConfig, Schema.Struct<{
  */
 export declare class YamlLintConfig extends YamlLintConfig_base {
   /**
-   * 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).
+   * The default preset: the built-in rules at their default settings. The
+   * `quoted-strings` rule defaults to DOUBLE quotes here.
    */
   static readonly default: YamlLintConfig;
   /** The relaxed preset: style rules demoted to warnings. */
@@ -1606,7 +1733,7 @@ declare const StyleEvidence_base: Schema.Class<StyleEvidence, Schema.Struct<{
   readonly floors: Schema.$Array<typeof StyleFloorTally>;
 }>, {}>;
 /**
- * Per-dimension style evidence (#345): what the observed sources say about
+ * Per-dimension style evidence: what the observed sources say about
  * each inferable `(rule, dimension)` — vote histograms with first-seen
  * positions, and measured floors.
  *
@@ -1664,6 +1791,11 @@ declare const YamlStyleConflictError_base: Schema.Class<YamlStyleConflictError,
  * rule). Unobserved dimensions never conflict: they fall back to the base
  * config's defaults.
  *
+ * @remarks
+ * The `message` renders each candidate's first-seen position 1-based
+ * (`line + 1:character + 1`) for human readers; the structured
+ * {@link StyleVoteTally} `line`/`character` fields stay 0-based.
+ *
  * @public
  */
 export declare class YamlStyleConflictError extends YamlStyleConflictError_base {
@@ -1681,7 +1813,25 @@ interface YamlLintInference {
   readonly residual: ReadonlyArray<YamlLintDiagnostic>;
 }
 /**
- * Linting statics. Not instantiable.
+ * Lints YAML text against a rule set, applies the rules' non-overlapping
+ * fixes, and infers a lint config from the style a corpus already follows.
+ * Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { YamlLint, YamlLintConfig } from "@effected/yaml";
+ * import { Result } from "effect";
+ *
+ * const text = "a:   1\nb: 2   \n";
+ *
+ * const diagnostics = YamlLint.run(text, YamlLint.builtins, YamlLintConfig.default);
+ * // => a colon-spacing finding on line 0 and a trailing-spaces finding on line 1 (zero-based)
+ *
+ * const fixed = YamlLint.fix(text, YamlLint.builtins, YamlLintConfig.default);
+ * if (Result.isSuccess(fixed)) {
+ *   fixed.success; // "a: 1\nb: 2\n"
+ * }
+ * ```
  *
  * @remarks
  * Pure and synchronous throughout — the lint engine is the pure half only:
@@ -1712,6 +1862,12 @@ export declare class YamlLint {
    * literal, else `"error"`) overrides what the rule emitted, again except
    * for `parse-validity`, whose bridged engine diagnostics keep the
    * engine's own grading.
+   *
+   * @param text - The YAML source to lint.
+   * @param rules - The rules to run, e.g. {@link YamlLint.builtins}.
+   * @param config - The {@link YamlLintConfig} choosing each rule's severity
+   *   and options.
+   * @returns Every finding, sorted by position.
    */
   static run(text: string, rules: ReadonlyArray<YamlRule>, config: YamlLintConfig): ReadonlyArray<YamlLintDiagnostic>;
   /**
@@ -1726,10 +1882,17 @@ export declare class YamlLint {
    * 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}).
+   *
+   * @param text - The YAML source to fix.
+   * @param rules - The rules to run, e.g. {@link YamlLint.builtins}.
+   * @param config - The {@link YamlLintConfig} choosing each rule's severity
+   *   and options.
+   * @returns A `Result` succeeding with the fixed text, or failing with
+   *   {@link YamlParseError}.
    */
   static fix(text: string, rules: ReadonlyArray<YamlRule>, config: YamlLintConfig): Result.Result<string, YamlParseError>;
   /**
-   * Observe the style `text` already follows (#345): run every rule's
+   * Observe the style `text` already follows: run every rule's
    * optional `infer` hook over one eagerly-built context and merge the
    * observations into canonical {@link StyleEvidence}. Pure and total —
    * strings in, evidence out; observing N files is N `observe` calls merged
@@ -2356,7 +2519,23 @@ export declare const YamlVisitorEvent: {
   }, "_tag">;
 };
 /**
- * SAX-style YAML AST visitor statics. Not instantiable.
+ * Walks YAML text as a lazy `Stream` of typed events — documents, collections,
+ * pairs, scalars, aliases, comments, directives and recovered errors — in
+ * document order. Not instantiable.
+ *
+ * @example
+ * ```ts
+ * import { YamlVisitor, YamlVisitorEvent } from "@effected/yaml";
+ * import { Effect, Stream } from "effect";
+ *
+ * // Mapping keys are scalar events too, so keys and values interleave.
+ * const scalars = YamlVisitor.visit("a: 1\nb:\n  - x\n").pipe(
+ *   Stream.filter(YamlVisitorEvent.$is("Scalar")),
+ *   Stream.map((event) => event.value),
+ *   Stream.runCollect,
+ * );
+ * // Effect.runSync(scalars) // => ["a", 1, "b", "x"]
+ * ```
  *
  * @public
  */
@@ -2374,6 +2553,11 @@ export declare class YamlVisitor {
    * (fatal or not, including an exceeded `maxAliasCount`, recorded as
    * `AliasCountExceeded`) surface as `Error` events inside the stream rather
    * than failing it.
+   *
+   * @param text - The YAML source to visit.
+   * @param options - Optional {@link YamlParseOptions} controlling composition.
+   * @returns A lazy `Stream` of `YamlVisitorEvent`, infallible at the type
+   *   level.
    */
   static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
 }

package/internal/composer/block.js

@@ -66,8 +66,7 @@ function composeBlockMapInner(blockMapCst, state, externalFirstKey, meta) {
 * scope re-attributes it (see `EscapedComment` in `comments.ts`: "it belongs to
 * an outer scope"). The span was the one place that disagreed, reporting an
 * `offset`/`length` whose end lay past a comment the node does not own — so a
-* caller splicing text at the end of the collection inserted AFTER the comment
-* (#642's sibling, #643).
+* caller splicing text at the end of the collection inserted AFTER the comment.
 *
 * The disowned set is the input rather than a re-derived column test, so the
 * span and the comment model cannot drift apart: whatever the partition threw
@@ -534,7 +533,7 @@ function flattenBlockMapChildren(children, state, externalKeyColumn, externalKey
 * Pattern: node, value-sep (no node) produces a key:null pair.
 * Pattern: value-sep, node produces a null:value pair.
 *
-* Comment attribution (#127): a comment on the same line as the end of the
+* Comment attribution: a comment on the same line as the end of the
 * previous pair attaches to it as the trailing `comment`; an own-line
 * comment attaches FORWARD to the next pair as `commentBefore` (consecutive
 * lines join with `\n`); a blank line before a pair (or before its

package/internal/composer/comments.js

@@ -152,7 +152,7 @@ function joinComments(a, b) {
 }
 /**
 * Zero-based column of `offset` within its line. A byte-order mark at the
-* line start occupies no column — the lexer's convention (#694) — so a
+* line start occupies no column — the lexer's convention — so a
 * BOM-prefixed root mapping's content column is `0`, not `1`, and its
 * terminal own-line comment is not mistaken for one escaping a nested map.
 */

package/internal/composer/document.js

@@ -678,9 +678,9 @@ const EMPTY_DOCUMENT = {
 	hasDocumentStartTab: false
 };
 /**
-* Compose the first document of `text` with full error recovery — v3
-* `parseDocument` semantics minus the Effect wrapper and minus fatal-code
-* filtering (the facade applies `isFatalCode` to the returned diagnostics).
+* Compose the first document of `text` with full error recovery, with no
+* fatal-code filtering (the facade applies `isFatalCode` to the returned
+* diagnostics).
 * Cross-document directive-placement errors are validated into the same
 * state and therefore appear in the returned document's `errors`.
 */
@@ -710,12 +710,10 @@ function composeFirstDocumentCounted(text, options) {
 	};
 }
 /**
-* Compose every document of `text` with full error recovery — v3
-* `parseAllDocuments` semantics minus the Effect wrapper and minus
+* Compose every document of `text` with full error recovery, with no
 * fatal-code filtering. Each document is composed with a fresh state; the
 * cross-document directive validation runs in its own state whose errors
-* are returned unfiltered as `streamErrors` (v3 filtered these to
-* `InvalidDirective` before failing — the facade applies that filter).
+* are returned unfiltered as `streamErrors` (the facade applies its filter).
 */
 function composeAllDocuments(text, options) {
 	const cstNodes = parseCSTAll(text);

package/internal/composer/scalars.js

@@ -123,7 +123,7 @@ function getBlockIndent(node) {
 * a `#` comment — body lines absorb `#` as content — and the lexer packs the
 * whole scalar (header comment included) into one CST token, so the comment
 * never surfaces as a sibling comment token for the ordinary attribution
-* pass (#341).
+* pass.
 */
 function blockScalarHeaderComment(cst) {
 	const src = cst.source.trimStart();

package/internal/composer/state.js

@@ -11,7 +11,7 @@ function getLineStarts(text) {
 }
 /**
 * Zero-based line and column of `offset`. A byte-order mark at the line start
-* occupies no column, matching the lexer and `columnAt` (#694), so a
+* occupies no column, matching the lexer and `columnAt`, so a
 * diagnostic's `character` behind a BOM equals the BOM-less document's.
 */
 function lineCol(text, offset) {

package/internal/diagnostics.js

@@ -72,9 +72,8 @@ const YAML_MODIFY_ERROR_CODES = [
 ];
 /**
 * The single source of truth for which diagnostic codes are fatal to a
-* parse (vs. recoverable warnings-as-data). Replaces the v3 source's three
-* subtly-differing inline fatal lists with their union: fatality is a
-* property of the code, declared once.
+* parse (vs. recoverable warnings-as-data): fatality is a property of the
+* code, declared once.
 */
 const FATAL_CODES = /* @__PURE__ */ new Set([
 	"UndefinedAlias",

package/internal/rules/quoted-strings.js

@@ -17,7 +17,7 @@ const quotedStringsOptions = Schema.Struct({
 });
 /**
 * A value-preserving requote/wrap edit, or undefined when none is safe.
-* Delegates to the shared helper's CONSERVATIVE mode (#347) — the shipped
+* Delegates to the shared helper's CONSERVATIVE mode — the shipped
 * fix behavior stays exactly as released; the escaping-capable mode belongs
 * to the format path's opt-in `requoteScalars`, not the lint fix.
 */

package/internal/stringifier.js

@@ -138,7 +138,7 @@ function wouldBeResolved11(s) {
 * `,[]{}` are plain-unsafe anywhere in the scalar (YAML 1.2 §7.3.3,
 * `ns-plain-safe(flow-in)` excludes `c-flow-indicator`), where block context
 * lets them through. Without it a plain `p, q` rendered into `[x, y]` reads
-* back as three items (#695).
+* back as three items.
 */
 function requiresQuoting(s, ignoreType = false, quoteCompat, inFlow = false) {
 	if (s === "") return true;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.18.0",
+	"version": "0.19.1",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing, formatting and linting as Effect schemas.",
 	"keywords": [
@@ -41,7 +41,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.118"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"