@effected/yaml 0.10.0 → 0.12.0

package/index.d.ts

@@ -175,6 +175,33 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
    * `"double-quoted"` is unaffected.
    */
   readonly quoteStyle: Schema.optionalKey<Schema.Literals<readonly ["single", "double"]>>;
+  /**
+   * 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.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
+   * lenient resolvers set the outer bound) would implicitly resolve to a
+   * non-string: the extended
+   * boolean spellings (`y`/`yes`/`on`/`off` and case variants — the "Norway
+   * problem"), timestamps (`2024-01-15`, `2001-12-15T02:59:43.1Z`, the
+   * space-separated 1.1 forms), sexagesimal numbers (`1:30`,
+   * `190:20:30.15`), underscore-separated numbers (`1_000`) and the
+   * base-2/8/16 integer forms (`0b1010_0111`, `0777`, `0x_FF`). Use it when
+   * emitted output is parsed downstream by a YAML 1.1 consumer and blanket
+   * `defaultScalarStyle` quoting is too noisy.
+   *
+   * Strictly additive: it never un-quotes anything the 1.2 rules require
+   * quoted, strings no 1.1 parser coerces stay plain, and the quote
+   * character stays governed by `quoteStyle`. Scalars carrying an explicit
+   * tag are exempt, exactly like the 1.2 type-conflict check. Applies
+   * wherever the plain fallback renders — values, mapping keys, flow items —
+   * on both the value path ({@link Yaml.stringify},
+   * {@link Yaml.stringifyResult}) and the node path (`YamlDocument#stringify`
+   * and the `YamlFormat` helpers).
+   */
+  readonly quoteCompat: Schema.optionalKey<Schema.Literals<readonly ["yaml-1.1"]>>;
   readonly finalNewline: Schema.optionalKey<Schema.Boolean>;
   readonly forceDefaultStyles: Schema.optionalKey<Schema.Boolean>;
 }>, {}>;
@@ -182,8 +209,9 @@ declare const YamlStringifyOptions_base: Schema.Class<YamlStringifyOptions, Sche
  * Options controlling stringify behavior. All fields are omissible; absent
  * fields resolve to `indent` `2`, `lineWidth` `0`, `defaultScalarStyle`
  * `"plain"`, `defaultCollectionStyle` `"block"`, `sortKeys` `false`,
- * `indentSequences` `false`, `quoteStyle` `"single"`, `finalNewline` `true`
- * and `forceDefaultStyles` `false`.
+ * `indentSequences` `false`, `quoteStyle` `"single"`, `quoteCompat` absent
+ * (no dialect-compat quoting), `finalNewline` `true` and `forceDefaultStyles`
+ * `false`.
  *
  * `lineWidth` controls column-based scalar folding. The default `0` (and any
  * value `<= 0`) never wraps, emitting byte-identical output to the historic
@@ -641,6 +669,27 @@ declare const QuoteStyle: Schema.Literals<readonly ["single", "double"]>;
  * @public
  */
 type QuoteStyle = typeof QuoteStyle.Type;
+/**
+ * Foreign resolution dialects the stringifier's plain-scalar fallback can
+ * defend against: setting the `quoteCompat` field of `YamlStringifyOptions`
+ * to `"yaml-1.1"` additionally quotes every plain scalar a YAML 1.1 parser
+ * (js-yaml, PyYAML, libyaml, and the `yaml` npm package's YAML 1.1 schema,
+ * whose lenient resolvers set the outer bound) would implicitly resolve to a
+ * non-string —
+ * `yes`/`no`/`on`/`off` booleans, ISO 8601 and space-separated timestamps,
+ * sexagesimal `1:30`, underscored `1_000` and base-2/8/16 numbers. Like
+ * `QuoteStyle` it is a stringify-option vocabulary, never a property of a
+ * composed node.
+ *
+ * @public
+ */
+declare const QuoteCompat: Schema.Literals<readonly ["yaml-1.1"]>;
+/**
+ * The union of all quote-compat dialect string literals.
+ *
+ * @public
+ */
+type QuoteCompat = typeof QuoteCompat.Type;
 /**
  * Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
  * Referenced by the {@link YamlScalar} `chomp` field schema.
@@ -1005,18 +1054,36 @@ declare const YamlFormattingOptions_base: Schema.Class<YamlFormattingOptions, Sc
   readonly sortKeys: Schema.optionalKey<Schema.Boolean>;
   readonly indentSequences: Schema.optionalKey<Schema.Boolean>;
   readonly quoteStyle: Schema.optionalKey<Schema.Literals<readonly ["single", "double"]>>;
+  readonly quoteCompat: Schema.optionalKey<Schema.Literals<readonly ["yaml-1.1"]>>;
   readonly finalNewline: Schema.optionalKey<Schema.Boolean>;
   readonly forceDefaultStyles: Schema.optionalKey<Schema.Boolean>;
   readonly preserveComments: Schema.optionalKey<Schema.Boolean>;
   readonly range: Schema.optionalKey<typeof YamlRange>;
+  readonly requoteScalars: Schema.optionalKey<Schema.Boolean>;
 }>, {}>;
 /**
  * Options controlling formatting behavior: every {@link YamlStringifyOptions}
- * field (derived, not hand-duplicated — including `indentSequences` and
- * `quoteStyle`) plus
- * `preserveComments` (default `true`) and `range` (restrict edits to a
+ * 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).
+ * 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
+ * existing scalar's own quote style, and `quoteStyle` governs only quotes the
+ * stringifier introduces. When enabled, a re-quote happens only when it
+ * provably preserves the parsed value: single→double applies proper
+ * double-quote escaping, double→single is skipped whenever the value carries
+ * characters single quotes cannot express (newlines, tabs, control and other
+ * non-printable characters — single-quoted style can escape nothing but
+ * `'`). Plain scalars stay plain, block scalars stay block, and scalars
+ * carrying a tag or anchor — or spanning multiple source lines — are left
+ * untouched. The option exists only where a source quote exists to re-quote:
+ * it is read by {@link YamlFormat.format} / {@link YamlFormat.formatToString}
+ * and is deliberately absent from `Yaml.stringify` (which serializes plain
+ * values) and {@link YamlFormat.modify} (which takes a bare
+ * {@link YamlStringifyOptions}).
  *
  * Construct with the validated `YamlFormattingOptions.make({ ... })` static —
  * the kit convention (never `new`). Call sites that take a
@@ -1122,6 +1189,12 @@ declare class YamlFormat {
    * `{ offset, length }` object as well as a {@link YamlRange} instance, so
    * callers do not need `YamlRange.make(...)` for the common case.
    *
+   * Formatting preserves an existing scalar's own quote style by default —
+   * `quoteStyle` governs only quotes the stringifier introduces. The opt-in
+   * `options.requoteScalars` makes `quoteStyle` apply to already-quoted
+   * source scalars too, re-quoting only where the parsed value is provably
+   * preserved; see {@link YamlFormattingOptions} for the exact skip rules.
+   *
    * A plain `<<` mapping key is preserved unquoted, keeping its merge-key
    * meaning (`tag:yaml.org,2002:merge`) — quoting it to `'<<'` would produce
    * an ordinary string key that merges nothing, changing what the document
@@ -1337,6 +1410,60 @@ interface LintContext {
   readonly tokens: ReadonlyArray<YamlToken>;
   readonly document: YamlDocument;
 }
+declare const StyleVote_base: Schema.Class<StyleVote, Schema.TaggedStruct<"StyleVote", {
+  readonly dimension: Schema.String;
+  readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly line: Schema.Number;
+  readonly character: Schema.Number;
+}>, {}>;
+/**
+ * One categorical style observation (#345): 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
+ * value (`"double"` for `quoteType`, `2` for `spaces`, `false` for
+ * `present`), so the inference resolvers can turn unanimous or dominant
+ * votes into a config entry with no per-rule knowledge — which is what lets
+ * custom rules participate in inference for free. The position points at the
+ * occurrence that voted, so a strict-resolution conflict can name where each
+ * spelling was seen.
+ *
+ * The `_tag` literal is the RUNTIME discriminator between the two
+ * observation kinds: class instances are structurally assignable, so a
+ * custom rule may yield a plain object shaped like a vote, and the evidence
+ * builder must still sort it into the right tally without `instanceof`.
+ * `.make` defaults it — construction sites never pass `_tag`.
+ *
+ * @public
+ */
+declare class StyleVote extends StyleVote_base {}
+declare const StyleFloor_base: Schema.Class<StyleFloor, Schema.TaggedStruct<"StyleFloor", {
+  readonly dimension: Schema.String;
+  readonly value: Schema.Number;
+}>, {}>;
+/**
+ * One measured style floor (#345): 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
+ * never resolved into config options; fabricating a max from the largest
+ * value one happened to see would be lying with a straight face.
+ *
+ * The `_tag` literal discriminates a floor from a {@link StyleVote} at
+ * runtime (see there); `.make` defaults it.
+ *
+ * @public
+ */
+declare class StyleFloor extends StyleFloor_base {}
+/**
+ * What a rule's `infer` hook yields per occurrence: a categorical
+ * {@link StyleVote} or a measured {@link StyleFloor}.
+ *
+ * @public
+ */
+type StyleObservation = StyleVote | StyleFloor;
 /**
  * The public rule interface — built-ins and custom rules are the same
  * shape, and config references either by `id`; there is no privileged
@@ -1347,11 +1474,19 @@ interface LintContext {
  * 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
+ * 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
+ * policy rules, whose only evidence is violations — simply omit the hook and
+ * stay default-driven under every resolver.
+ *
  * @public
  */
 interface YamlRule {
   readonly id: string;
   readonly check: (ctx: LintContext, options: unknown) => Iterable<YamlLintDiagnostic>;
+  readonly infer?: (ctx: LintContext) => Iterable<StyleObservation>;
 }
 //#endregion
 //#region src/YamlLint.d.ts
@@ -1399,6 +1534,118 @@ declare class YamlLintConfig extends YamlLintConfig_base {
   /** The relaxed preset: style rules demoted to warnings. */
   static readonly relaxed: YamlLintConfig;
 }
+declare const StyleVoteTally_base: Schema.Class<StyleVoteTally, Schema.Struct<{
+  readonly rule: Schema.String;
+  readonly dimension: Schema.String;
+  readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>;
+  readonly count: Schema.Number;
+  readonly offset: Schema.Number;
+  readonly length: Schema.Number;
+  readonly line: Schema.Number;
+  readonly character: Schema.Number;
+}>, {}>;
+/**
+ * An accumulated tally of one {@link StyleVote} spelling: how many times a
+ * `value` was voted for a `(rule, dimension)` pair, and the position of the
+ * FIRST occurrence seen (merging keeps the left operand's position, so on a
+ * multi-file merge the first file that exhibited the spelling names it).
+ *
+ * @public
+ */
+declare class StyleVoteTally extends StyleVoteTally_base {}
+declare const StyleFloorTally_base: Schema.Class<StyleFloorTally, Schema.Struct<{
+  readonly rule: Schema.String;
+  readonly dimension: Schema.String;
+  readonly value: Schema.Number;
+}>, {}>;
+/**
+ * An accumulated {@link StyleFloor} for a `(rule, dimension)` pair: the
+ * largest value the observed sources prove the limit is AT LEAST. Merging
+ * takes the maximum. Floors are informational — never resolved into config
+ * options (see {@link StyleFloor}).
+ *
+ * @public
+ */
+declare class StyleFloorTally extends StyleFloorTally_base {}
+declare const StyleEvidence_base: Schema.Class<StyleEvidence, Schema.Struct<{
+  readonly votes: Schema.$Array<typeof StyleVoteTally>;
+  readonly floors: Schema.$Array<typeof StyleFloorTally>;
+}>, {}>;
+/**
+ * Per-dimension style evidence (#345): what the observed sources say about
+ * each inferable `(rule, dimension)` — vote histograms with first-seen
+ * positions, and measured floors.
+ *
+ * Evidence is a MONOID: {@link StyleEvidence.empty} is the identity and
+ * {@link StyleEvidence.combine} is associative, so multi-file inference is
+ * observe-per-file, merge, resolve — and the N-file loop stays the caller's
+ * (no IO enters the package). `combine` normalizes: counts of the same
+ * `(rule, dimension, value)` add, the left operand's first-seen position
+ * wins, floors take the maximum, and the result is canonically sorted — so
+ * every value `observe`/`combine`/`fromObservations` produces is canonical
+ * and the monoid laws hold structurally over them.
+ *
+ * @public
+ */
+declare class StyleEvidence extends StyleEvidence_base {
+  /** The monoid identity: no observations. */
+  static readonly empty: StyleEvidence;
+  /**
+   * Merge two bodies of evidence (associative; {@link StyleEvidence.empty}
+   * is the identity). Vote counts add, the left operand's first-seen
+   * position wins per spelling, floors take the maximum.
+   */
+  static combine(a: StyleEvidence, b: StyleEvidence): StyleEvidence;
+  /**
+   * Build canonical evidence from one rule's raw observations — the
+   * homomorphism from observation lists into the monoid
+   * (`fromObservations(r, [...a, ...b])` equals
+   * `combine(fromObservations(r, a), fromObservations(r, b))`). `observe`
+   * uses it per rule; it is public so custom tooling can construct evidence
+   * without a {@link LintContext}.
+   */
+  static fromObservations(rule: string, observations: Iterable<StyleObservation>): StyleEvidence;
+}
+declare const StyleConflict_base: Schema.Class<StyleConflict, Schema.Struct<{
+  readonly rule: Schema.String;
+  readonly dimension: Schema.String;
+  readonly candidates: Schema.$Array<typeof StyleVoteTally>;
+}>, {}>;
+/**
+ * One strict-resolution conflict: a `(rule, dimension)` whose observed
+ * spellings disagree. `candidates` carries every spelling with its count and
+ * first-seen position, ordered by count descending (dominant first).
+ *
+ * @public
+ */
+declare class StyleConflict extends StyleConflict_base {}
+declare const YamlStyleConflictError_base: Schema.Class<YamlStyleConflictError, Schema.TaggedStruct<"YamlStyleConflictError", {
+  readonly conflicts: Schema.$Array<typeof StyleConflict>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised by strict config inference when observed evidence is not unanimous:
+ * carries every conflicting `(rule, dimension)` as a structured
+ * {@link StyleConflict} — dimension, all spellings, counts and positions —
+ * never a collapsed `reason` string (the structure-preserving-errors house
+ * rule). Unobserved dimensions never conflict: they fall back to the base
+ * config's defaults.
+ *
+ * @public
+ */
+declare class YamlStyleConflictError extends YamlStyleConflictError_base {
+  get message(): string;
+}
+/**
+ * A lenient inference report: the inferred config plus the residual — the
+ * diagnostics that config still produces on the observed text ("here is your
+ * config, and the places that do not match it").
+ *
+ * @public
+ */
+interface YamlLintInference {
+  readonly config: YamlLintConfig;
+  readonly residual: ReadonlyArray<YamlLintDiagnostic>;
+}
 /**
  * Linting statics. Not instantiable.
  *
@@ -1447,6 +1694,52 @@ declare class YamlLint {
    * is dropped (its diagnostic remains reported by {@link YamlLint.run}).
    */
   static fix(text: string, rules: ReadonlyArray<YamlRule>, config: YamlLintConfig): Result.Result<string, YamlParseError>;
+  /**
+   * Observe the style `text` already follows (#345): 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
+   * with {@link StyleEvidence.combine}, and the N-file loop stays the
+   * caller's (no IO enters the package).
+   */
+  static observe(text: string, rules: ReadonlyArray<YamlRule>): StyleEvidence;
+  /**
+   * Strict resolution: every OBSERVED dimension must be unanimous, and the
+   * unanimous picks overlay `base` (default {@link YamlLintConfig.default})
+   * into an exact config. Conflicting evidence fails with
+   * {@link YamlStyleConflictError} naming every conflicting dimension, all
+   * spellings, counts and first-seen positions. Unobserved is NOT
+   * conflicting: a corpus with no comments says nothing about
+   * `comments-spacing`, so that dimension falls back to `base` rather than
+   * failing. A rule `base` sets to `"off"` stays off — an explicit disable
+   * outranks inference.
+   */
+  static resolveStrict(evidence: StyleEvidence, base?: YamlLintConfig): Result.Result<YamlLintConfig, YamlStyleConflictError>;
+  /**
+   * Lenient resolution: the dominant (plurality) spelling per observed
+   * dimension overlays `base` (default {@link YamlLintConfig.default}); a
+   * tie breaks deterministically to the first candidate in canonical
+   * value order. Total — lenient resolution cannot fail; the places that do
+   * not match the inferred config surface as the residual report (run the
+   * lint with the inferred config, or use {@link YamlLint.inferLenient}).
+   */
+  static resolveLenient(evidence: StyleEvidence, base?: YamlLintConfig): YamlLintConfig;
+  /**
+   * Single-text strict inference: `observe` then {@link YamlLint.resolveStrict}
+   * in one step. Multi-file callers observe each file and merge with
+   * {@link StyleEvidence.combine} before resolving.
+   */
+  static inferStrict(text: string, rules: ReadonlyArray<YamlRule>, base?: YamlLintConfig): Result.Result<YamlLintConfig, YamlStyleConflictError>;
+  /**
+   * Single-text lenient inference: `observe`, resolve dominant picks over
+   * `base`, then run the lint with the inferred config — returning the
+   * config AND the residual diagnostics it still produces ("here is your
+   * config, and the places that do not match it"). One context serves both
+   * the observation and the residual run. Multi-file callers compose the
+   * primitives instead: observe each file, {@link StyleEvidence.combine},
+   * {@link YamlLint.resolveLenient}, then {@link YamlLint.run} per file.
+   */
+  static inferLenient(text: string, rules: ReadonlyArray<YamlRule>, base?: YamlLintConfig): YamlLintInference;
 }
 //#endregion
 //#region src/YamlVisitor.d.ts
@@ -2051,5 +2344,5 @@ declare class YamlVisitor {
   static visit(text: string, options?: YamlParseOptions): Stream.Stream<YamlVisitorEvent>;
 }
 //#endregion
-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 };
+export { CollectionStyle, type LintContext, type LintLine, QuoteCompat, QuoteStyle, ScalarChomp, ScalarStyle, StyleConflict, StyleEvidence, StyleFloor, StyleFloorTally, type StyleObservation, StyleVote, StyleVoteTally, Yaml, YamlAlias, type YamlAliasEncoded, type YamlBoundCodec, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlLint, YamlLintConfig, YamlLintDiagnostic, type YamlLintInference, 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, YamlStyleConflictError, YamlToken, YamlTokenKind, YamlTokens, YamlVisitor, YamlVisitorEvent };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,12 +1,12 @@
-import { CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq } from "./YamlNode.js";
+import { CollectionStyle, QuoteCompat, QuoteStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq } from "./YamlNode.js";
 import { YamlComposerErrorCode, YamlDiagnostic, YamlErrorCode, YamlLexErrorCode, YamlModifyErrorCode, YamlParseErrorCode, YamlStringifyErrorCode } from "./YamlDiagnostic.js";
 import { Yaml, YamlParseError, YamlParseOptions, YamlStringifyError, YamlStringifyOptions } from "./Yaml.js";
 import { YamlDirective, YamlDocument } from "./YamlDocument.js";
 import { YamlEdit, YamlRange } from "./YamlEdit.js";
 import { YamlFormat, YamlFormattingOptions, YamlModificationError } from "./YamlFormat.js";
-import { YamlLintDiagnostic, YamlLintSeverity } from "./YamlLintRule.js";
+import { StyleFloor, StyleVote, YamlLintDiagnostic, YamlLintSeverity } from "./YamlLintRule.js";
 import { YamlToken, YamlTokenKind, YamlTokens } from "./YamlToken.js";
-import { YamlLint, YamlLintConfig, YamlLintRuleSetting } from "./YamlLint.js";
+import { StyleConflict, StyleEvidence, StyleFloorTally, StyleVoteTally, YamlLint, YamlLintConfig, YamlLintRuleSetting, YamlStyleConflictError } from "./YamlLint.js";
 import { YamlVisitor, YamlVisitorEvent } from "./YamlVisitor.js";
 
-export { CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, Yaml, YamlAlias, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlLint, YamlLintConfig, YamlLintDiagnostic, YamlLintRuleSetting, YamlLintSeverity, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, YamlRange, YamlScalar, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlToken, YamlTokenKind, YamlTokens, YamlVisitor, YamlVisitorEvent };
+export { CollectionStyle, QuoteCompat, QuoteStyle, ScalarChomp, ScalarStyle, StyleConflict, StyleEvidence, StyleFloor, StyleFloorTally, StyleVote, StyleVoteTally, Yaml, YamlAlias, YamlComposerErrorCode, YamlDiagnostic, YamlDirective, YamlDocument, YamlEdit, YamlErrorCode, YamlFormat, YamlFormattingOptions, YamlLexErrorCode, YamlLint, YamlLintConfig, YamlLintDiagnostic, YamlLintRuleSetting, YamlLintSeverity, YamlMap, YamlModificationError, YamlModifyErrorCode, YamlNode, YamlPair, YamlParseError, YamlParseErrorCode, YamlParseOptions, YamlRange, YamlScalar, YamlSeq, YamlStringifyError, YamlStringifyErrorCode, YamlStringifyOptions, YamlStyleConflictError, YamlToken, YamlTokenKind, YamlTokens, YamlVisitor, YamlVisitorEvent };

package/internal/requote.js

@@ -0,0 +1,48 @@
+import { isControlChar } from "./fold.js";
+import { renderDoubleQuoted, renderSingleQuoted } from "./stringifier.js";
+
+//#region src/internal/requote.ts
+/**
+* True when `value` can be carried by a single-quoted flow scalar on one
+* line. Single-quoted style has exactly one escape (`''`), so any character
+* double-quote escape sequences exist to encode — newline, carriage return,
+* tab, C0 controls, DEL and the C1 range — has no single-quoted spelling and
+* makes the conversion impossible rather than lossy-but-tempting.
+*/
+function isSingleQuotable(value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code === 9 || code === 10 || code === 13) return false;
+		if (isControlChar(code)) return false;
+		if (code === 127 || code >= 128 && code <= 159) return false;
+	}
+	return true;
+}
+/**
+* The replacement raw text that re-quotes `scalar` with `quote`, or
+* `undefined` when no value-preserving replacement exists under `mode`
+* (skipping is always correct; corrupting never is).
+*/
+function requoteScalarText(text, scalar, quote, mode) {
+	if (scalar.tag !== void 0 || scalar.anchor !== void 0) return void 0;
+	if (typeof scalar.value !== "string") return void 0;
+	const raw = text.slice(scalar.offset, scalar.offset + scalar.length);
+	if (raw.includes("\n") || raw.includes("\r")) return void 0;
+	if (mode === "conservative") {
+		const inner = scalar.style === "plain" ? raw : raw.slice(1, -1);
+		if (inner !== scalar.value) return void 0;
+		if (inner.includes(quote)) return void 0;
+		if (quote === "\"" && inner.includes("\\")) return void 0;
+		return `${quote}${inner}${quote}`;
+	}
+	if (quote === "\"") {
+		if (scalar.style !== "single-quoted") return void 0;
+		return renderDoubleQuoted(scalar.value);
+	}
+	if (scalar.style !== "double-quoted") return void 0;
+	if (!isSingleQuotable(scalar.value)) return void 0;
+	return renderSingleQuoted(scalar.value);
+}
+
+//#endregion
+export { requoteScalarText };

package/internal/rules/comments-spacing.js

@@ -1,5 +1,5 @@
 import { YamlEdit } from "../../YamlEdit.js";
-import { YamlLintDiagnostic, YamlLintSeverity } from "../../YamlLintRule.js";
+import { StyleVote, YamlLintDiagnostic, YamlLintSeverity } from "../../YamlLintRule.js";
 import { nonNegativeIntegerOption } from "./util.js";
 import { Schema } from "effect";
 
@@ -14,6 +14,25 @@ const commentsSpacingOptions = Schema.Struct({
 	minSpacesBefore: Schema.optionalKey(nonNegativeIntegerOption),
 	requireSpaceAfter: Schema.optionalKey(Schema.Boolean)
 });
+/**
+* The horizontal whitespace run directly before a comment token, and whether
+* line content precedes it (a TRAILING comment) — shared by the check and
+* the inference hook so the two cannot disagree about what "before" means.
+*/
+const spacingBefore = (ctx, token) => {
+	let i = token.offset - 1;
+	let spaces = 0;
+	while (i >= 0 && (ctx.text[i] === " " || ctx.text[i] === "	")) {
+		spaces++;
+		i--;
+	}
+	return {
+		spaces,
+		hasContentBefore: i >= 0 && ctx.text[i] !== "\n" && ctx.text[i] !== "\r"
+	};
+};
+/** Shebang exemption: `#!` at the very start of the stream. */
+const isShebang = (token) => token.offset === 0 && token.text.startsWith("#!");
 /** Comment spacing: after the `#`, and before a trailing comment's `#`. */
 const commentsSpacing = {
 	id: "comments-spacing",
@@ -24,7 +43,7 @@ const commentsSpacing = {
 		const out = [];
 		for (const token of ctx.tokens) {
 			if (token.kind !== "comment") continue;
-			if (token.offset === 0 && token.text.startsWith("#!")) continue;
+			if (isShebang(token)) continue;
 			if (requireAfter && token.text.length > 1 && !/[ \t]/.test(token.text[1])) out.push(new YamlLintDiagnostic({
 				rule: "comments-spacing",
 				severity: "error",
@@ -39,13 +58,8 @@ const commentsSpacing = {
 					content: " "
 				})
 			}));
-			let i = token.offset - 1;
-			let spaces = 0;
-			while (i >= 0 && (ctx.text[i] === " " || ctx.text[i] === "	")) {
-				spaces++;
-				i--;
-			}
-			if (i >= 0 && ctx.text[i] !== "\n" && ctx.text[i] !== "\r" && spaces < minBefore) out.push(new YamlLintDiagnostic({
+			const { spaces, hasContentBefore } = spacingBefore(ctx, token);
+			if (hasContentBefore && spaces < minBefore) out.push(new YamlLintDiagnostic({
 				rule: "comments-spacing",
 				severity: "error",
 				message: `Too few spaces before comment (${spaces} < ${minBefore})`,
@@ -61,6 +75,31 @@ const commentsSpacing = {
 			}));
 		}
 		return out;
+	},
+	infer: (ctx) => {
+		const out = [];
+		for (const token of ctx.tokens) {
+			if (token.kind !== "comment") continue;
+			if (isShebang(token)) continue;
+			if (token.text.length > 1) out.push(StyleVote.make({
+				dimension: "requireSpaceAfter",
+				value: /[ \t]/.test(token.text[1]),
+				offset: token.offset,
+				length: token.length,
+				line: token.line,
+				character: token.character
+			}));
+			const { spaces, hasContentBefore } = spacingBefore(ctx, token);
+			if (hasContentBefore) out.push(StyleVote.make({
+				dimension: "minSpacesBefore",
+				value: spaces,
+				offset: token.offset - spaces,
+				length: spaces,
+				line: token.line,
+				character: token.character - spaces
+			}));
+		}
+		return out;
 	}
 };
 

package/internal/rules/document-end.js

@@ -1,5 +1,5 @@
 import { YamlEdit } from "../../YamlEdit.js";
-import { YamlLintDiagnostic, YamlLintSeverity } from "../../YamlLintRule.js";
+import { StyleVote, YamlLintDiagnostic, YamlLintSeverity } from "../../YamlLintRule.js";
 import { Schema } from "effect";
 
 //#region src/internal/rules/document-end.ts
@@ -14,31 +14,43 @@ const TRIVIA = /* @__PURE__ */ new Set([
 	"comment",
 	"byte-order-mark"
 ]);
+/** The last non-trivia token: it decides whether the stream ends with `...`. */
+const tailToken = (ctx) => [...ctx.tokens].reverse().find((t) => !TRIVIA.has(t.kind));
+/**
+* The end-of-stream position, shared by the missing-marker diagnostic and
+* the absent-marker vote so the two cannot drift apart. `line`/`character`
+* must agree with `offset` (= text length): when the text ends with a
+* newline, that offset sits at the head of the line AFTER the last content
+* line `buildLines` kept.
+*/
+const endOfStreamPosition = (ctx) => {
+	const lastLine = ctx.lines[ctx.lines.length - 1];
+	const trailingNewline = ctx.text.endsWith("\n");
+	return {
+		offset: ctx.text.length,
+		length: 0,
+		line: (lastLine?.number ?? 0) + (trailingNewline ? 1 : 0),
+		character: trailingNewline ? 0 : lastLine?.text.length ?? 0
+	};
+};
 /** The `...` marker at the tail of the stream. */
 const documentEnd = {
 	id: "document-end",
 	check: (ctx, options) => {
 		const present = options?.present ?? true;
-		const tail = [...ctx.tokens].reverse().find((t) => !TRIVIA.has(t.kind));
+		const tail = tailToken(ctx);
 		const ended = tail?.kind === "document-end";
-		if (present && !ended && ctx.text.trim() !== "") {
-			const lastLine = ctx.lines[ctx.lines.length - 1];
-			const trailingNewline = ctx.text.endsWith("\n");
-			return [new YamlLintDiagnostic({
-				rule: "document-end",
-				severity: "error",
-				message: "Missing \"...\" document end marker",
+		if (present && !ended && ctx.text.trim() !== "") return [new YamlLintDiagnostic({
+			rule: "document-end",
+			severity: "error",
+			message: "Missing \"...\" document end marker",
+			...endOfStreamPosition(ctx),
+			fix: YamlEdit.make({
 				offset: ctx.text.length,
 				length: 0,
-				line: (lastLine?.number ?? 0) + (trailingNewline ? 1 : 0),
-				character: trailingNewline ? 0 : lastLine?.text.length ?? 0,
-				fix: YamlEdit.make({
-					offset: ctx.text.length,
-					length: 0,
-					content: ctx.text.endsWith("\n") ? "...\n" : "\n...\n"
-				})
-			})];
-		}
+				content: ctx.text.endsWith("\n") ? "...\n" : "\n...\n"
+			})
+		})];
 		if (!present && tail !== void 0 && tail.kind === "document-end") {
 			const alone = (ctx.lines[tail.line]?.text ?? "").trim() === "...";
 			const terminator = ctx.text.startsWith("\r\n", tail.offset + tail.length) ? 2 : 1;
@@ -58,6 +70,24 @@ const documentEnd = {
 			})];
 		}
 		return [];
+	},
+	infer: (ctx) => {
+		if (ctx.text.trim() === "") return [];
+		const tail = tailToken(ctx);
+		if (tail === void 0) return [];
+		if (tail.kind === "document-end") return [StyleVote.make({
+			dimension: "present",
+			value: true,
+			offset: tail.offset,
+			length: tail.length,
+			line: tail.line,
+			character: tail.character
+		})];
+		return [StyleVote.make({
+			dimension: "present",
+			value: false,
+			...endOfStreamPosition(ctx)
+		})];
 	}
 };