@effected/yaml 0.6.1 → 0.8.0

package/index.d.ts

@@ -54,7 +54,7 @@ type YamlStringifyErrorCode = typeof YamlStringifyErrorCode.Type;
  *
  * @public
  */
-declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable"]>;
+declare const YamlModifyErrorCode: Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument"]>;
 /**
  * The union of all modify-stage error code string literals.
  *
@@ -67,7 +67,7 @@ type YamlModifyErrorCode = typeof YamlModifyErrorCode.Type;
  *
  * @public
  */
-declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable"]>]>;
+declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument"]>]>;
 /**
  * The union of all YAML error code string literals.
  *
@@ -75,7 +75,7 @@ declare const YamlErrorCode: Schema.Union<readonly [Schema.Literals<readonly ["U
  */
 type YamlErrorCode = typeof YamlErrorCode.Type;
 declare const YamlDiagnostic_base: Schema.Class<YamlDiagnostic, Schema.Struct<{
-  readonly code: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable"]>]>;
+  readonly code: Schema.Union<readonly [Schema.Literals<readonly ["UnexpectedCharacter", "UnterminatedString", "InvalidEscapeSequence", "InvalidUnicode", "UnterminatedBlockScalar", "UnterminatedFlowCollection", "InvalidDirective", "InvalidTagHandle", "InvalidAnchorName", "UnexpectedByteOrderMark"]>, Schema.Literals<readonly ["InvalidIndentation", "DuplicateKey", "UnexpectedToken", "MissingValue", "MissingKey", "TabIndentation", "InvalidBlockStructure", "MalformedFlowCollection", "NestingDepthExceeded"]>, Schema.Literals<readonly ["UndefinedAlias", "DuplicateAnchor", "CircularAlias", "UnresolvedTag", "InvalidTagValue", "AliasCountExceeded", "InvalidDirective"]>, Schema.Literals<readonly ["CircularReference"]>, Schema.Literals<readonly ["EmptyDocument", "PathNotFound", "InvalidIndex", "NotNavigable", "MultiDocumentStream", "DirectiveCarryingDocument"]>]>;
   readonly message: Schema.String;
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
@@ -238,7 +238,9 @@ declare const YamlParseError_base: Schema.Class<YamlParseError, Schema.TaggedStr
  * Error-recovery parse failure: aggregates every fatal {@link YamlDiagnostic}
  * encountered, so a single failure reports the whole batch. Raised by
  * {@link Yaml.parse}, {@link Yaml.parseAll}, `YamlDocument.parse`/`parseAll`
- * and the decode direction of the schema factories.
+ * and the decode direction of the schema factories. The error itself has no
+ * `code` field: read the code from the diagnostics —
+ * `error.diagnostics[0].code` is the primary failure.
  *
  * @public
  */
@@ -253,7 +255,8 @@ declare const YamlStringifyError_base: Schema.Class<YamlStringifyError, Schema.T
  * Stringification failure (the circular-reference guard), carrying structured
  * {@link YamlDiagnostic} entries and the offending value. Raised by
  * {@link Yaml.stringify}, `YamlDocument#stringify` and the encode direction of
- * the schema factories.
+ * the schema factories. The error itself has no `code` field: read the code
+ * from the diagnostics — `error.diagnostics[0].code` is the primary failure.
  *
  * @public
  */
@@ -326,6 +329,9 @@ declare class Yaml {
    * A "billion laughs" alias-expansion blow-up in any document also fails
    * through {@link YamlParseError} with an `AliasCountExceeded` diagnostic,
    * never as an unhandled defect.
+   *
+   * Defined in terms of {@link Yaml.parseAllResult} — synchronous callers
+   * can use that variant directly.
    */
   static readonly parseAll: (text: string, options?: YamlParseOptions | undefined) => Effect.Effect<readonly unknown[], YamlParseError, never>;
   /**
@@ -378,6 +384,46 @@ declare class Yaml {
    * @public
    */
   static parseResult(text: string, options?: YamlParseOptions): Result.Result<unknown, YamlParseError>;
+  /**
+   * Synchronous multi-document parse, returning a `Result` instead of an
+   * `Effect` — the {@link Yaml.parseResult} counterpart to
+   * {@link Yaml.parseAll}. Empty input succeeds with `[null]` (the engine
+   * reads `""` as one empty document, exactly as {@link Yaml.parse} yields
+   * `null` for it); a single-document stream succeeds with a one-element
+   * array whose value is exactly what {@link Yaml.parseResult} yields.
+   *
+   * @remarks
+   * This is the package's single multi-document parse path.
+   * {@link Yaml.parseAll} is defined in terms of it (`Effect.fromResult`
+   * behind the named span), so the two variants cannot diverge. Anchors are
+   * document-scoped: each document's aliases resolve against its own anchor
+   * map, never a neighbor's.
+   *
+   * Fails with the aggregate {@link YamlParseError} when **any** document in
+   * the stream carries a fatal diagnostic (or a stream-level
+   * directive-placement error), which makes it a whole-stream validity
+   * check: a `Success` means every document parsed clean. Preserves the
+   * package contract — malformed and adversarial input (including a
+   * "billion laughs" alias bomb in any document) fails typed, never as a
+   * defect; the method never throws.
+   *
+   * @example
+   * ```ts
+   * import { Yaml } from "@effected/yaml";
+   * import { Result } from "effect";
+   *
+   * // Whole-stream validity check: fails if ANY document is invalid.
+   * const result = Yaml.parseAllResult("a: 1\n---\nb: 2\n");
+   * if (Result.isSuccess(result)) {
+   *   result.success; // [{ a: 1 }, { b: 2 }]
+   * } else {
+   *   result.failure; // YamlParseError aggregating every fatal diagnostic
+   * }
+   * ```
+   *
+   * @public
+   */
+  static parseAllResult(text: string, options?: YamlParseOptions): Result.Result<ReadonlyArray<unknown>, YamlParseError>;
   /**
    * Synchronous stringify, returning a `Result` instead of an `Effect`.
    * The pure counterpart to {@link Yaml.stringify} for config-time callers
@@ -613,8 +659,11 @@ declare const YamlScalar_base: Schema.Class<YamlScalar, Schema.TaggedStruct<"Yam
   readonly tag: Schema.optionalKey<Schema.String>;
   readonly style: Schema.Literals<readonly ["plain", "single-quoted", "double-quoted", "block-literal", "block-folded"]>;
   readonly anchor: Schema.optionalKey<Schema.String>;
+  readonly commentBefore: Schema.optionalKey<Schema.String>;
   readonly comment: Schema.optionalKey<Schema.String>;
+  readonly spaceBefore: Schema.optionalKey<Schema.Boolean>;
   readonly chomp: Schema.optionalKey<Schema.Literals<readonly ["strip", "clip", "keep"]>>;
+  readonly blockIndent: Schema.optionalKey<Schema.Number>;
   readonly raw: Schema.optionalKey<Schema.String>;
   readonly sourceMultiline: Schema.optionalKey<Schema.Boolean>;
   readonly offset: Schema.Number;
@@ -629,9 +678,17 @@ declare const YamlScalar_base: Schema.Class<YamlScalar, Schema.TaggedStruct<"Yam
  * - `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;
@@ -740,12 +797,20 @@ type YamlNode = YamlScalar | YamlMap | YamlSeq | YamlAlias;
 declare const YamlPair_base: Schema.Class<YamlPair, Schema.TaggedStruct<"YamlPair", {
   readonly key: Schema.suspend<Schema.Codec<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAliasEncoded | YamlMapEncoded | YamlScalarEncoded | YamlSeqEncoded, never, never>>;
   readonly value: Schema.NullOr<Schema.suspend<Schema.Codec<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAliasEncoded | YamlMapEncoded | YamlScalarEncoded | YamlSeqEncoded, never, never>>>;
+  readonly commentBefore: Schema.optionalKey<Schema.String>;
   readonly comment: Schema.optionalKey<Schema.String>;
+  readonly spaceBefore: Schema.optionalKey<Schema.Boolean>;
 }>, {}>;
 /**
  * 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
  */
 declare class YamlPair extends YamlPair_base {}
@@ -754,7 +819,9 @@ declare const YamlMap_base: Schema.Class<YamlMap, Schema.TaggedStruct<"YamlMap",
   readonly tag: Schema.optionalKey<Schema.String>;
   readonly anchor: Schema.optionalKey<Schema.String>;
   readonly style: Schema.Literals<readonly ["block", "flow"]>;
+  readonly commentBefore: Schema.optionalKey<Schema.String>;
   readonly comment: Schema.optionalKey<Schema.String>;
+  readonly spaceBefore: Schema.optionalKey<Schema.Boolean>;
   readonly sourceMultiline: Schema.optionalKey<Schema.Boolean>;
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
@@ -764,6 +831,11 @@ declare const YamlMap_base: Schema.Class<YamlMap, Schema.TaggedStruct<"YamlMap",
  * 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.
  *
@@ -784,7 +856,9 @@ declare const YamlSeq_base: Schema.Class<YamlSeq, Schema.TaggedStruct<"YamlSeq",
   readonly tag: Schema.optionalKey<Schema.String>;
   readonly anchor: Schema.optionalKey<Schema.String>;
   readonly style: Schema.Literals<readonly ["block", "flow"]>;
+  readonly commentBefore: Schema.optionalKey<Schema.String>;
   readonly comment: Schema.optionalKey<Schema.String>;
+  readonly spaceBefore: Schema.optionalKey<Schema.Boolean>;
   readonly sourceMultiline: Schema.optionalKey<Schema.Boolean>;
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
@@ -793,6 +867,12 @@ declare const YamlSeq_base: Schema.Class<YamlSeq, Schema.TaggedStruct<"YamlSeq",
  * 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
  */
 declare class YamlSeq extends YamlSeq_base {
@@ -826,6 +906,7 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
   readonly warnings: Schema.$Array<typeof YamlDiagnostic>;
   readonly directives: Schema.$Array<typeof YamlDirective>;
   readonly comment: Schema.optionalKey<Schema.String>;
+  readonly commentAfter: Schema.optionalKey<Schema.String>;
   readonly hasDocumentStart: Schema.optionalKey<Schema.Boolean>;
   readonly hasDocumentEnd: Schema.optionalKey<Schema.Boolean>;
   readonly hasDocumentStartTab: Schema.optionalKey<Schema.Boolean>;
@@ -833,8 +914,12 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
 /**
  * A parsed YAML document: the root {@link (YamlNode:type)} (or `null` when
  * empty), recovered `errors` and `warnings` as {@link YamlDiagnostic} data,
- * the {@link YamlDirective} list, an optional document-level comment, and the
- * `---`/`...` framing flags (absent flags read as `false`).
+ * the {@link YamlDirective} list, the optional document-level comments
+ * (`comment` is the LEADING header block, `commentAfter` the trailing block
+ * after the content or the `...` marker — the reference `yaml` package calls
+ * these `commentBefore`/`comment`; the naming here keeps the pre-existing
+ * `comment`-as-header field stable), and the `---`/`...` framing flags
+ * (absent flags read as `false`).
  *
  * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
  * synthetic documents.
@@ -950,9 +1035,16 @@ declare const YamlModificationError_base: Schema.Class<YamlModificationError, Sc
 }>, import("effect/Cause").YieldableError>;
 /**
  * Raised when `YamlFormat.modify` cannot navigate the requested path against
- * the composed AST (a structural mismatch) or the source fails to parse.
+ * the composed AST (a structural mismatch), the source fails to parse, the
+ * source is a multi-document stream (`MultiDocumentStream` — a path names no
+ * particular document of a stream, so modify refuses rather than guessing),
+ * or the document carries `%YAML`/`%TAG` directives
+ * (`DirectiveCarryingDocument` — modify does not re-emit directive lines, and
+ * dropping a `%TAG` would orphan the shorthand tags that depend on it).
  * Carries structured {@link YamlDiagnostic} entries — never a collapsed
- * `reason` string (the structure-preserving-errors house rule).
+ * `reason` string (the structure-preserving-errors house rule). The error
+ * itself has no `code` field: read the code from the diagnostics —
+ * `error.diagnostics[0].code` is the primary failure.
  *
  * @public
  */
@@ -971,6 +1063,24 @@ declare class YamlModificationError extends YamlModificationError_base {
  * `diagnostics: ReadonlyArray<YamlDiagnostic>`, never a collapsed `reason`
  * string.
  *
+ * `format`/`formatToString` handle multi-document streams whole — every
+ * document is re-emitted in order with its own framing, never a silently
+ * truncated stream. `modify`/`modifyToString` are **single-document**: a
+ * {@link YamlPath} carries no document index, so which document of a stream
+ * a path names is a rule the format does not define, and a multi-document
+ * stream fails typed with a `MultiDocumentStream` diagnostic rather than
+ * guessing. Parse a stream with {@link Yaml.parseAll} /
+ * `Yaml.parseAllResult`.
+ *
+ * **Directive-carrying input is refused on every path.** The stringifier does
+ * not re-emit `%YAML`/`%TAG` directive lines, and re-emitting a document
+ * without its `%TAG` while keeping the shorthand tags that depend on it
+ * (`!e!foo`) turns a valid file into one no parser can read. So
+ * `format`/`formatToString` leave such input byte-identical (no edits), and
+ * `modify`/`modifyToString` fail typed with a `DirectiveCarryingDocument`
+ * diagnostic. Directive re-emission is unimplemented, not undesired — the
+ * refusal is the floor that stops corruption until it lands.
+ *
  * @public
  */
 declare class YamlFormat {
@@ -981,6 +1091,24 @@ declare class YamlFormat {
    * Pure and total: malformed input (a fatal parse error) yields `[]` rather
    * than corrupting the document.
    *
+   * **Multi-document streams format whole.** Input containing more than one
+   * document (a `---`-separated stream — a Kubernetes manifest, a pnpm 11
+   * `pnpm-lock.yaml` with a config-dependency preamble) formats every
+   * document in order, re-emitting each document's own framing (`---`,
+   * `...`, comment blocks); no document is ever dropped. Document detection
+   * is CST-level, so a `---` inside a block scalar or quoted string is
+   * content, not a document boundary. Two multi-document shapes yield `[]`
+   * (untouched) because they cannot be re-emitted faithfully: a stream with
+   * a fatal diagnostic in any document (the same posture as single-document
+   * input) and a stream carrying `%YAML`/`%TAG` directives.
+   *
+   * **Directive-carrying documents yield `[]` on the single-document path
+   * too.** Directive lines are not re-emitted, and dropping a `%TAG` while
+   * keeping the shorthand tags that depend on it would turn a valid document
+   * into an unparseable one — so a document carrying `%YAML`/`%TAG`
+   * directives is left untouched. Detection is directive-token-level: a
+   * literal `%TAG` inside a scalar is content and formats normally.
+   *
    * @remarks
    * The positional `range` argument takes precedence over
    * `options?.range` when both are given; either accepts a plain
@@ -999,6 +1127,13 @@ declare class YamlFormat {
   /**
    * Format `text` and apply the resulting edits in one step
    * (`YamlEdit.applyAll ∘ format`). Pure and total.
+   *
+   * Inherits the {@link YamlFormat.format} contract: a multi-document stream
+   * is formatted whole — every document re-emitted in order — and input
+   * that cannot be formatted faithfully (a fatal parse error, or any
+   * document — single or in a stream — carrying `%YAML`/`%TAG` directives)
+   * is returned byte-identical — never a truncated first document, never a
+   * document re-emitted without the directive its tags depend on.
    */
   static formatToString(text: string, range?: YamlRangeLike, options?: YamlFormattingOptions): string;
   /**
@@ -1010,6 +1145,23 @@ declare class YamlFormat {
    * {@link YamlModificationError} on a fatal parse error or a structural
    * navigation mismatch.
    *
+   * **Single-document contract.** A `path` carries no document index, so on
+   * a multi-document stream there is no rule for which document it names —
+   * `modify` fails with {@link YamlModificationError} carrying a
+   * `MultiDocumentStream` diagnostic rather than guessing document 1 (and
+   * unlike {@link YamlFormat.format}, which formats a stream whole because
+   * formatting needs no target). Detection is CST-level: a `---` inside a
+   * block scalar or quoted string is content, not a document boundary.
+   *
+   * **Directive-carrying documents are refused.** A document carrying
+   * `%YAML`/`%TAG` directives fails with {@link YamlModificationError}
+   * carrying a `DirectiveCarryingDocument` diagnostic: modify re-emits the
+   * whole document and does not re-emit directive lines, so applying it
+   * would drop the `%TAG` while keeping the shorthand tags that depend on
+   * it — unparseable output. A typed refusal beats silent corruption;
+   * directive re-emission is unimplemented, not undesired. A literal
+   * `%TAG` inside a scalar is content and does not trigger the refusal.
+   *
    * @remarks
    * `options` is a bare {@link YamlStringifyOptions} — it controls only the
    * internal re-stringify step, not a range (there is no range to restrict
@@ -1018,11 +1170,278 @@ declare class YamlFormat {
   static readonly modify: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<readonly YamlEdit[], YamlModificationError, never>;
   /**
    * Modify `text` and apply the resulting edits in one step
-   * (`YamlEdit.applyAll ∘ modify`).
+   * (`YamlEdit.applyAll ∘ modify`). Inherits the {@link YamlFormat.modify}
+   * error channel, including the single-document contract's
+   * `MultiDocumentStream` refusal and the `DirectiveCarryingDocument`
+   * refusal of `%YAML`/`%TAG`-carrying documents.
    */
   static readonly modifyToString: (text: string, path: YamlPath, value: unknown, options?: YamlStringifyOptions | undefined) => Effect.Effect<string, YamlModificationError, never>;
 }
 //#endregion
+//#region src/YamlToken.d.ts
+/**
+ * The 22 lexical token kinds produced by the YAML tokenizer.
+ *
+ * @public
+ */
+declare const YamlTokenKind: Schema.Literals<readonly ["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"]>;
+/**
+ * The union of all lexical token kind string literals.
+ *
+ * @public
+ */
+type YamlTokenKind = typeof YamlTokenKind.Type;
+declare const YamlToken_base: Schema.Class<YamlToken, Schema.Struct<{
+  readonly kind: Schema.Literals<readonly ["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"]>;
+  readonly text: Schema.String;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly line: Schema.Number;
+  readonly character: Schema.Number;
+}>, {}>;
+/**
+ * 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
+ */
+declare class YamlToken extends YamlToken_base {}
+/**
+ * Tokenizer statics. Not instantiable.
+ *
+ * @public
+ */
+declare class YamlTokens {
+  private 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: string): Result.Result<ReadonlyArray<YamlToken>, YamlParseError>;
+  /**
+   * 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: string): Stream.Stream<YamlToken>;
+}
+//#endregion
+//#region src/YamlLintRule.d.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
+ */
+declare const YamlLintSeverity: Schema.Literals<readonly ["error", "warning"]>;
+/**
+ * The union of lint severity string literals.
+ *
+ * @public
+ */
+type YamlLintSeverity = typeof YamlLintSeverity.Type;
+declare const YamlLintDiagnostic_base: Schema.Class<YamlLintDiagnostic, Schema.Struct<{
+  readonly rule: Schema.String;
+  readonly severity: Schema.Literals<readonly ["error", "warning"]>;
+  readonly message: Schema.String;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly line: Schema.Number;
+  readonly character: Schema.Number;
+  readonly fix: Schema.optionalKey<typeof YamlEdit>;
+}>, {}>;
+/**
+ * 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
+ */
+declare class YamlLintDiagnostic extends YamlLintDiagnostic_base {}
+/**
+ * One source line of the linted document: its text (without the line
+ * terminator — the `\n`, and for CRLF input the `\r\n` pair), the offset of
+ * its first character, and its zero-based line number.
+ *
+ * @public
+ */
+interface LintLine {
+  readonly text: string;
+  readonly offset: number;
+  readonly number: number;
+}
+/**
+ * The context handed to every rule. The engine tokenizes ONCE and every rule
+ * shares the one materialized `tokens` array — linting is inherently
+ * multi-pass and random-access (layout rules need lookahead and lookbehind),
+ * so the context is eager by nature; the streaming token form exists for
+ * other consumers.
+ *
+ * `text`, `lines` and `tokens` cover the FULL source; `document` is the
+ * FIRST document of the stream (matching `Yaml.parse` — split the stream
+ * `Yaml.parseAll`-style to lint every document). It is always present,
+ * including for input that does not parse: it is built from the engine's
+ * recovered compose, and its `errors`/`warnings` carry what went wrong (the
+ * `parse-validity` rule reports them).
+ *
+ * @public
+ */
+interface LintContext {
+  readonly text: string;
+  readonly lines: ReadonlyArray<LintLine>;
+  readonly tokens: ReadonlyArray<YamlToken>;
+  readonly document: YamlDocument;
+}
+/**
+ * The public rule interface — built-ins and custom rules are the same
+ * shape, and config references either by `id`; there is no privileged
+ * built-in mechanism a custom rule cannot reach.
+ *
+ * `options` is the validated per-rule options object from the config entry
+ * (or `undefined` when the entry was a bare severity literal); built-in
+ * rules receive options already validated against their exported options
+ * schema, custom rules validate their own.
+ *
+ * @public
+ */
+interface YamlRule {
+  readonly id: string;
+  readonly check: (ctx: LintContext, options: unknown) => Iterable<YamlLintDiagnostic>;
+}
+//#endregion
+//#region src/YamlLint.d.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
+ */
+declare const YamlLintRuleSetting: Schema.Union<readonly [Schema.Literals<readonly ["error", "warning", "off"]>, Schema.$Record<Schema.String, Schema.Unknown>]>;
+/**
+ * The union type of one `rules`-map entry.
+ *
+ * @public
+ */
+type YamlLintRuleSetting = typeof YamlLintRuleSetting.Type;
+declare const YamlLintConfig_base: Schema.Class<YamlLintConfig, Schema.Struct<{
+  readonly rules: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Literals<readonly ["error", "warning", "off"]>, Schema.$Record<Schema.String, Schema.Unknown>]>>;
+}>, {}>;
+/**
+ * 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
+ */
+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).
+   */
+  static readonly default: YamlLintConfig;
+  /** The relaxed preset: style rules demoted to warnings. */
+  static readonly relaxed: YamlLintConfig;
+}
+/**
+ * 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
+ */
+declare class YamlLint {
+  private constructor();
+  /**
+   * The built-in rule catalog. Custom usage is array concatenation:
+   * `YamlLint.run(text, [...YamlLint.builtins, myRule], config)`.
+   */
+  static readonly builtins: ReadonlyArray<YamlRule>;
+  /**
+   * 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: string, rules: ReadonlyArray<YamlRule>, config: YamlLintConfig): ReadonlyArray<YamlLintDiagnostic>;
+  /**
+   * 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: string, rules: ReadonlyArray<YamlRule>, config: YamlLintConfig): Result.Result<string, YamlParseError>;
+}
+//#endregion
 //#region src/YamlVisitor.d.ts
 /**
  * The discriminated union of YAML AST visitor events. Every variant carries
@@ -1091,6 +1510,8 @@ type YamlVisitorEvent = Data.TaggedEnum<{
     readonly path: YamlPath;
     readonly depth: number;
     readonly text: string;
+    /** Where the comment sits relative to its construct: own-line above (`"leading"`) or same-line after (`"trailing"`). */
+    readonly placement: "leading" | "trailing";
   };
   Directive: {
     readonly path: YamlPath;
@@ -1124,6 +1545,7 @@ declare const YamlVisitorEvent: {
     readonly path: YamlPath;
     readonly depth: number;
     readonly text: string;
+    readonly placement: "leading" | "trailing";
   }, {
     readonly _tag: Tag;
   }> | Extract<{
@@ -1219,6 +1641,7 @@ declare const YamlVisitorEvent: {
         readonly path: YamlPath;
         readonly depth: number;
         readonly text: string;
+        readonly placement: "leading" | "trailing";
       }) => any;
       readonly Directive: (args: {
         readonly _tag: "Directive";
@@ -1299,6 +1722,7 @@ declare const YamlVisitorEvent: {
       readonly path: YamlPath;
       readonly depth: number;
       readonly text: string;
+      readonly placement: "leading" | "trailing";
     } | {
       readonly _tag: "Directive";
       readonly path: YamlPath;
@@ -1371,6 +1795,7 @@ declare const YamlVisitorEvent: {
         readonly path: YamlPath;
         readonly depth: number;
         readonly text: string;
+        readonly placement: "leading" | "trailing";
       }) => any;
       readonly Directive: (args: {
         readonly _tag: "Directive";
@@ -1451,6 +1876,7 @@ declare const YamlVisitorEvent: {
       readonly path: YamlPath;
       readonly depth: number;
       readonly text: string;
+      readonly placement: "leading" | "trailing";
     } | {
       readonly _tag: "Directive";
       readonly path: YamlPath;
@@ -1523,6 +1949,7 @@ declare const YamlVisitorEvent: {
     readonly path: YamlPath;
     readonly depth: number;
     readonly text: string;
+    readonly placement: "leading" | "trailing";
   }, "_tag">;
   readonly Directive: Data.TaggedEnum.ConstructorFrom<{
     readonly _tag: "Directive";
@@ -1617,5 +2044,5 @@ declare class YamlVisitor {
   static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
 }
 //#endregion
-export { CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, type YamlAliasEncoded, type YamlBoundCodec, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlMap, type YamlMapEncoded, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, type YamlPath, YamlRange, type YamlRangeLike, YamlScalar, type YamlScalarEncoded, type YamlSegment, YamlSeq, type YamlSeqEncoded, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlVisitor, YamlVisitorEvent };
+export { CollectionStyle, type LintContext, type LintLine, QuoteStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, type YamlAliasEncoded, type YamlBoundCodec, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlLint, YamlLintConfig, YamlLintDiagnostic, YamlLintRuleSetting, YamlLintSeverity, YamlMap, type YamlMapEncoded, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, type YamlPath, YamlRange, type YamlRangeLike, type YamlRule, YamlScalar, type YamlScalarEncoded, type YamlSegment, YamlSeq, type YamlSeqEncoded, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlToken, YamlTokenKind, YamlTokens, YamlVisitor, YamlVisitorEvent };
 //# sourceMappingURL=index.d.ts.map