@effected/yaml 0.10.0 → 0.12.0

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Zero-dependency YAML 1.2 parsing, editing, formatting and linting expressed as Effect schemas and pure functions. Parse a single document or a multi-document stream into plain values or an offset-preserving AST, resolve anchors and aliases, read and preserve per-node comments, strip comments, compute byte-minimal edits, format, modify by path, walk a document as a `Stream` of AST events or positioned tokens, lint it against a rule catalog with surgical autofix, and decode straight into a validated domain schema.
+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
@@ -156,6 +156,23 @@ console.log(Result.isSuccess(fixed) ? fixed.success : "fatal parse error — not
 
 Positions are zero-based throughout, so the first finding above sits on the second line of the source. Fixes route through `YamlEdit.applyAll` rather than a reformat, so an autofix cannot move a comment it was not asked to touch, and a rule whose repair would need reflowing the document ships without a fix at all. `YamlLintConfig.default` and `YamlLintConfig.relaxed` are the presets; compose your own by spreading a preset's `rules` into `YamlLintConfig.make`. Config validation is rule-aware for the built-in catalog — a misspelled option key on a built-in rule or an attempt to switch off the always-on `parse-validity` rule fails schema validation instead of being quietly ignored — while an unknown (custom) rule id passes through with its options treated as opaque, left for the custom rule itself to validate. Custom rules are plain array concatenation — `YamlLint.run(text, [...YamlLint.builtins, myRule], config)` — and configuring `myRule` in that config works precisely because of the pass-through.
 
+A repo with no lint config yet can infer one from what its files already do. `YamlLint.inferLenient` observes a text's style — quote type, indentation width, document markers and the rest — and returns the config the dominant style implies, plus the residual: the diagnostics that config still produces on the same text.
+
+```ts
+import { YamlLint } from "@effected/yaml";
+
+const workflow = ["---", "name: ci", "on:", "  push:", "    branches: ['main']", "jobs:", "  build:", "    runs-on: ubuntu-latest", ""].join("\n");
+
+const { config, residual } = YamlLint.inferLenient(workflow, YamlLint.builtins);
+console.log(config.rules["quoted-strings"], config.rules["document-start"], config.rules.indentation);
+// { quoteType: 'single' } { present: true } { spaces: 2 }
+
+for (const d of residual) console.log(`${d.line}:${d.character} ${d.rule} ${d.message}`);
+// 2:0 truthy Truthy value "on" is not in the allowed spellings
+```
+
+`YamlLint.inferStrict` is the same step in `Result` form: it fails with a structured `YamlStyleConflictError` — naming every conflicting dimension, all observed spellings, counts and positions — when the observed style disagrees with itself, instead of picking a winner. Across many files, compose the primitives instead of the conveniences: `YamlLint.observe` each file, merge the `StyleEvidence` values with `StyleEvidence.combine` (evidence is a monoid, so the order does not matter), then resolve once with `YamlLint.resolveStrict` or `YamlLint.resolveLenient`. Dimensions never observed fall back to the base config rather than failing. Policy rules with no detectable style — `truthy`, `key-duplicates` — stay default-driven, as do `line-length` and `empty-lines`, whose observations are floor-only: the longest line proves the limit is at least that long, not what it should be, so the evidence is carried but never resolved into config. A custom rule participates by implementing the optional `infer` hook on `YamlRule`.
+
 ## Migrating from Prettier
 
 `YamlFormat.formatToString(text, undefined, options)` replaces a `prettier --write` over YAML files. The option mapping:
@@ -163,34 +180,53 @@ Positions are zero-based throughout, so the first finding above sits on the seco
 | Prettier | `YamlFormattingOptions` |
 | --- | --- |
 | `tabWidth` | `indent` |
-| `singleQuote` | `quoteStyle: "single" \| "double"` |
+| `singleQuote` | `quoteStyle: "single" \| "double"` + `requoteScalars: true` |
 | indented block sequences (always on) | `indentSequences: true` |
 | `printWidth` / `proseWrap` | no analog — see below |
 | comments (best-effort) | `preserveComments: true` (the default) |
 
 Two defaults differ from Prettier's output and are worth setting explicitly. The stringify default is `quoteStyle: "single"` for byte-compatibility with the kit's legacy form, so if you ran Prettier with its own default (`singleQuote: false`), set `quoteStyle: "double"`. Likewise `indentSequences` defaults to `false` — the flat legacy form with the `-` markers at the key's column — while Prettier always indented block sequences one level, so an ex-Prettier consumer almost certainly wants `indentSequences: true`.
 
-One expectation to reset when carrying over `singleQuote`: on the format path, `quoteStyle` governs quotes the stringifier *introduces* — it never re-quotes scalars that already carry quotes in your source. Formatting `a: 'x'` with `quoteStyle: "double"` leaves `'x'` untouched; Prettier would have rewritten it to `"x"`. Existing quote styles are source, and the formatter preserves source. If it looks like the option "does nothing" on an already-quoted corpus, this is why — the same class of format-path inertness as `lineWidth` below.
+The `requoteScalars: true` half of the `singleQuote` row is what buys full parity. By default, `quoteStyle` on the format path governs only quotes the stringifier *introduces* — a scalar already quoted in your source keeps its own quote style, so formatting `a: 'x'` with `quoteStyle: "double"` leaves `'x'` untouched, where Prettier would have rewritten it to `"x"`. With `requoteScalars: true` (default `false`), `quoteStyle` applies to already-quoted source scalars too. A re-quote happens only when it provably preserves the parsed value: single→double applies proper double-quote escaping, and double→single is skipped when the value carries characters single quotes cannot express. Plain scalars stay plain, block scalars stay block, and tagged, anchored and multi-line scalars are never touched. One interaction to watch: `quoteStyle` omitted defaults to `"single"`, so `requoteScalars: true` on its own converts `"x"` to `'x'` — an ex-Prettier consumer who ran with `singleQuote: false` wants `quoteStyle: "double"` alongside it.
 
 `printWidth` and `proseWrap` have no analog here: `lineWidth` folding is a value-path feature only (`Yaml.stringify` / `Yaml.stringifyResult`), and the option is deliberately inert on the format path by contract — `YamlFormat` never reflows scalar content (the `lineWidth` TSDoc on `YamlStringifyOptions` pins this). Comments, which Prettier handled best-effort, are preserved exactly by default.
 
 Multi-document streams — a Kubernetes manifest, or the two-document `pnpm-lock.yaml` pnpm 11 writes under `configDependencies` — format whole: every document is re-emitted in order with its own `---`/`...` framing and comments, so no document is ever dropped. Document detection is CST-level, so a `---` inside a block scalar or quoted string is content and formats normally. The formatter leaves input byte-identical rather than corrupting it in exactly two cases: a fatal parse error in any document, and a stream carrying `%YAML`/`%TAG` directives (which the emitter cannot re-emit faithfully). Validate a whole stream with `Yaml.parseAllResult`, which fails typed when any document carries a fatal diagnostic; `YamlFormat.modify` stays single-document, since a path names no particular document of a stream.
 
+## Emitting for a YAML 1.1 consumer
+
+YAML 1.2's Core Schema resolves fewer plain scalars to non-strings than YAML 1.1 does. A plain `on` or `yes` round-trips as a string under this package's own parser but becomes a boolean the moment a YAML 1.1 consumer — js-yaml, PyYAML, libyaml, the `yaml` npm package's YAML 1.1 schema, most CI systems' native YAML support — reads it back: the "Norway problem". `quoteCompat: "yaml-1.1"` closes that gap on the way out, quoting every plain scalar a 1.1 resolver would re-type: the extended booleans (`y`/`yes`/`no`/`on`/`off` and case variants), 1.1 timestamps, sexagesimal numbers (`1:30`), underscore-grouped numbers (`1_000`) and the octal/hex/binary integer forms (`0777`, `0x_FF`, `0b1010_0111`). It is strictly additive — nothing the 1.2 rules already quote loses a quote, and no string outside that list gains one — and composes with `quoteStyle` for the quote character and `lineWidth` for folding:
+
+```ts
+import { Yaml, YamlStringifyOptions } from "@effected/yaml";
+import { Effect } from "effect";
+
+const frontmatter = { node: "on", released: "2024-01-15", port: "yes" };
+const options = YamlStringifyOptions.make({ lineWidth: 0, quoteCompat: "yaml-1.1", quoteStyle: "double" });
+
+Effect.runPromise(Yaml.stringify(frontmatter, options)).then(console.log);
+// node: "on"
+// released: "2024-01-15"
+// port: "yes"
+```
+
+That combination — `lineWidth: 0` (no folding), `quoteCompat: "yaml-1.1"`, `quoteStyle: "double"` — is the shape to reach for when stringifying frontmatter destined for YAML-1.1 tooling: Markdown frontmatter parsers and most static-site generators still resolve on the older rules. The option applies on both the value path (`Yaml.stringify`, `Yaml.stringifyResult`) and the node path (`YamlDocument#stringify`, `YamlFormat`), and scalars carrying an explicit tag are exempt, exactly like the 1.2 type-conflict check it extends.
+
 ## Features
 
 - `Yaml.parse` / `Yaml.parseAll` — error-recovery parsing of a single document or a `---`-separated stream into plain values, resolving anchors and aliases and aggregating every diagnostic into one `YamlParseError`.
-- `Yaml.stringify` — serialize a plain value back to YAML, failing typed with `YamlStringifyError` on circular references or on excessively deep nesting; a block-mapping key too long to render on one line spills into explicit-key form (`? key` / `: value`) so strict parsers still accept the output.
+- `Yaml.stringify` — serialize a plain value back to YAML, failing typed with `YamlStringifyError` on circular references or on excessively deep nesting; a block-mapping key too long to render on one line spills into explicit-key form (`? key` / `: value`) so strict parsers still accept the output; `quoteCompat: "yaml-1.1"` additionally quotes plain scalars a YAML 1.1 resolver would re-type.
 - `Yaml.parseResult` / `Yaml.parseAllResult` / `Yaml.stringifyResult` — the pure synchronous counterparts, returning a `Result` instead of an `Effect` for config-time callers that cannot await; each runs the same engine call as its `Effect` variant, so the two forms cannot diverge, and a fatal diagnostic, a duplicate key, an alias bomb or a circular reference still fails typed rather than throwing. `parseAllResult` doubles as a whole-stream validity check: it fails when any document in the stream is invalid.
 - `Yaml.stripComments` — quote-aware comment removal that keeps line numbers stable, or every byte offset stable when given a replacement character.
 - `Yaml.equals` / `Yaml.equalsValue` — semantic equality that ignores comments, whitespace, formatting and mapping key order while keeping sequence order significant.
 - `Yaml.schema` / `Yaml.fromString` / `Yaml.YamlFromString` / `Yaml.allFromString` — string→domain schema factories that decode a single document or a whole stream into a validated Effect `Schema` value.
 - `YamlNode` — an offset-preserving AST (`YamlScalar`, `YamlMap`, `YamlSeq`, `YamlPair`, `YamlAlias`) for locating and reading nodes by position or path; every node class except `YamlPair` carries its own `commentBefore`, `comment` and `spaceBefore`, and a pair is just its `key` and `value`.
 - `YamlDocument` — the full parsed AST plus the recovered `errors` and `warnings` arrays, so a partially valid document is still inspectable, and the header and trailing comment blocks as `commentBefore` / `comment`, the same two names the node classes use.
-- `YamlEdit` / `YamlFormat` — compute byte-minimal edit arrays for formatting and path-based modification, so a change preserves every comment and byte you did not touch; `preserveComments: false` opts out. `format` handles multi-document streams whole, re-emitting every document and its framing; `modify` is single-document by contract (a path names no particular document of a stream) and fails typed with `MultiDocumentStream` rather than guessing.
+- `YamlEdit` / `YamlFormat` — compute byte-minimal edit arrays for formatting and path-based modification, so a change preserves every comment and byte you did not touch; `preserveComments: false` opts out, and opt-in `requoteScalars` applies `quoteStyle` to scalars already quoted in the source, semantics-preserving or skipped. `format` handles multi-document streams whole, re-emitting every document and its framing; `modify` is single-document by contract (a path names no particular document of a stream) and fails typed with `MultiDocumentStream` rather than guessing.
 - `YamlVisitor` — walk a parsed document as a `Stream` of a tagged-enum event union, with `Stream.take` early termination on large inputs and a `placement` on every comment event.
 - `YamlToken` / `YamlTokens` — the positioned token stream the lint rules read: `tokenize` is a synchronous `Result` that always succeeds, surfacing lexical problems as `error`-kind tokens, and `stream` derives an Effect `Stream` from the same walk.
-- `YamlLint` — `run`, `fix` and the `builtins` catalog: 14 rules covering parse validity, line length, trailing whitespace, blank lines, end-of-file newline, document markers, duplicate keys, quoting, truthy spellings, comment and colon and hyphen spacing, and indentation.
-- `YamlLintConfig` / `YamlLintRule` / `YamlLintDiagnostic` — the `default` and `relaxed` presets, a config schema validated against the rule catalog, and the model a custom rule implements.
+- `YamlLint` — `run`, `fix` and the `builtins` catalog: 14 rules covering parse validity, line length, trailing whitespace, blank lines, end-of-file newline, document markers, duplicate keys, quoting, truthy spellings, comment and colon and hyphen spacing, and indentation. Plus config inference for adopting the linter on an existing corpus: `observe` produces mergeable `StyleEvidence`, `resolveStrict` fails typed with `YamlStyleConflictError` on conflicting spellings, `resolveLenient` picks the dominant style, and `inferStrict` / `inferLenient` do it in one step per text.
+- `YamlLintConfig` / `YamlLintRule` / `YamlLintDiagnostic` — the `default` and `relaxed` presets, a config schema validated against the rule catalog, and the model a custom rule implements, including the optional `infer` hook that lets a custom rule participate in config inference.
 - `YamlParseError` / `YamlStringifyError` / `YamlModificationError` — tagged errors carrying structured, positional `YamlDiagnostic` arrays rather than opaque messages.
 
 ## License

package/Yaml.js

@@ -1,4 +1,4 @@
-import { AliasExpansionBudgetExceeded, CollectionStyle, QuoteStyle, ScalarStyle, nodeToJsValue } from "./YamlNode.js";
+import { AliasExpansionBudgetExceeded, CollectionStyle, QuoteCompat, QuoteStyle, ScalarStyle, nodeToJsValue } from "./YamlNode.js";
 import { composeAllDocuments, composeFirstDocument } from "./internal/composer/document.js";
 import { isFatalCode } from "./internal/diagnostics.js";
 import { StringifyDepthExceeded, StringifyFailure, stringifyValue } from "./internal/stringifier.js";
@@ -35,8 +35,9 @@ var YamlParseOptions = class extends Schema.Class("YamlParseOptions")({
 * 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
@@ -114,6 +115,33 @@ var YamlStringifyOptions = class extends Schema.Class("YamlStringifyOptions")({
 	* `"double-quoted"` is unaffected.
 	*/
 	quoteStyle: Schema.optionalKey(QuoteStyle),
+	/**
+	* 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).
+	*/
+	quoteCompat: Schema.optionalKey(QuoteCompat),
 	finalNewline: Schema.optionalKey(Schema.Boolean),
 	forceDefaultStyles: Schema.optionalKey(Schema.Boolean)
 }) {};
@@ -167,6 +195,7 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	sortKeys: options.sortKeys,
 	indentSequences: options.indentSequences,
 	quoteStyle: options.quoteStyle,
+	quoteCompat: options.quoteCompat,
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };

package/YamlDocument.js

@@ -163,6 +163,8 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	defaultCollectionStyle: options.defaultCollectionStyle,
 	sortKeys: options.sortKeys,
 	indentSequences: options.indentSequences,
+	quoteStyle: options.quoteStyle,
+	quoteCompat: options.quoteCompat,
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };

package/YamlFormat.js

@@ -6,16 +6,33 @@ import { YamlDiagnostic } from "./YamlDiagnostic.js";
 import { YamlStringifyOptions } from "./Yaml.js";
 import { YamlEdit, YamlRange } from "./YamlEdit.js";
 import { computeEdits } from "./internal/diff.js";
+import { requoteScalarText } from "./internal/requote.js";
 import { Effect, Schema } from "effect";
 
 //#region src/YamlFormat.ts
 /**
 * 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
@@ -37,7 +54,8 @@ import { Effect, Schema } from "effect";
 var YamlFormattingOptions = class extends Schema.Class("YamlFormattingOptions")({
 	...YamlStringifyOptions.fields,
 	preserveComments: Schema.optionalKey(Schema.Boolean),
-	range: Schema.optionalKey(YamlRange)
+	range: Schema.optionalKey(YamlRange),
+	requoteScalars: Schema.optionalKey(Schema.Boolean)
 }) {};
 /**
 * Raised when `YamlFormat.modify` cannot navigate the requested path against
@@ -87,6 +105,7 @@ const toStringifyInput = (options) => options === void 0 ? {} : {
 	sortKeys: options.sortKeys,
 	indentSequences: options.indentSequences,
 	quoteStyle: options.quoteStyle,
+	quoteCompat: options.quoteCompat,
 	finalNewline: options.finalNewline,
 	forceDefaultStyles: options.forceDefaultStyles
 };
@@ -104,6 +123,49 @@ function definedFields(fields) {
 	for (const key of Object.keys(fields)) if (fields[key] !== void 0) out[key] = fields[key];
 	return out;
 }
+/**
+* Walk a composed AST and flip the `style` of every scalar the shared
+* escaping-mode helper deems re-quotable to the target quote's style. The
+* stringifier then emits those scalars through the very renderers the helper
+* used to prove the replacement value-preserving, so flip-and-stringify and
+* the helper's replacement text cannot disagree. Everything the helper skips
+* — plain scalars, block scalars, tagged/anchored nodes, multi-line source
+* spans, impossible double→single escapes — keeps its node untouched, and
+* the surrounding diff keeps the edit surgical per scalar span.
+*/
+function requoteNode(node, text, quote) {
+	if (node instanceof YamlScalar) {
+		if (requoteScalarText(text, node, quote, "escaping") === void 0) return node;
+		return YamlScalar.make({
+			value: node.value,
+			style: quote === "\"" ? "double-quoted" : "single-quoted",
+			...definedFields({
+				commentBefore: node.commentBefore,
+				comment: node.comment,
+				spaceBefore: node.spaceBefore,
+				raw: node.raw,
+				sourceMultiline: node.sourceMultiline
+			}),
+			offset: node.offset,
+			length: node.length
+		});
+	}
+	if (node instanceof YamlMap) return rebuildMap(node, node.items.map((pair) => YamlPair.make({
+		key: requoteNode(pair.key, text, quote),
+		value: pair.value === null ? null : requoteNode(pair.value, text, quote)
+	})));
+	if (node instanceof YamlSeq) return rebuildSeq(node, node.items.map((item) => requoteNode(item, text, quote)));
+	return node;
+}
+/** Apply the opt-in re-quoting pass to a composed document's contents. */
+function requoteDocument(doc, text, options) {
+	if (options?.requoteScalars !== true || doc.contents === null) return doc;
+	const quote = (options.quoteStyle ?? "single") === "double" ? "\"" : "'";
+	return {
+		...doc,
+		contents: requoteNode(doc.contents, text, quote)
+	};
+}
 /** Rebuild a composed document for re-emission, stripping comments when asked. */
 function toOutputDocument(doc, preserveComments) {
 	return {
@@ -132,12 +194,12 @@ function toOutputDocument(doc, preserveComments) {
 */
 function formatDocument(text, options) {
 	const { documents, streamErrors } = composeAllDocuments(text, {});
-	if (documents.length > 1) return formatStream(documents, streamErrors, options);
+	if (documents.length > 1) return formatStream(text, documents, streamErrors, options);
 	if (streamErrors.some((e) => isFatalCode(e.code))) return void 0;
 	const doc = documents[0] ?? EMPTY_DOCUMENT;
 	if (doc.errors.some((e) => isFatalCode(e.code))) return void 0;
 	if (doc.directives.length > 0) return void 0;
-	return stringifyDocument(toOutputDocument(doc, options?.preserveComments ?? true), toStringifyInput(options));
+	return stringifyDocument(toOutputDocument(requoteDocument(doc, text, options), options?.preserveComments ?? true), toStringifyInput(options));
 }
 /**
 * Format a multi-document stream: every document is re-emitted in order with
@@ -158,7 +220,7 @@ function formatDocument(text, options) {
 * line while keeping the dependent shorthand tags produced unparseable
 * output (probe-verified downstream against an independent oracle).
 */
-function formatStream(documents, streamErrors, options) {
+function formatStream(text, documents, streamErrors, options) {
 	if (streamErrors.some((e) => isFatalCode(e.code))) return void 0;
 	if (documents.some((d) => d.errors.some((e) => isFatalCode(e.code)))) return void 0;
 	if (documents.some((d) => d.directives.length > 0)) return void 0;
@@ -172,7 +234,7 @@ function formatStream(documents, streamErrors, options) {
 			...base,
 			finalNewline: true
 		} : base;
-		parts.push(stringifyDocument(toOutputDocument(doc, preserveComments), docOptions));
+		parts.push(stringifyDocument(toOutputDocument(requoteDocument(doc, text, options), preserveComments), docOptions));
 	}
 	return parts.join("");
 }
@@ -351,6 +413,12 @@ var YamlFormat = 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

package/YamlLintRule.js

@@ -31,6 +31,55 @@ var YamlLintDiagnostic = class extends Schema.Class("YamlLintDiagnostic")({
 	character: Schema.Number,
 	fix: Schema.optionalKey(YamlEdit)
 }) {};
+/**
+* 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
+*/
+var StyleVote = class extends Schema.TaggedClass()("StyleVote", {
+	dimension: Schema.String,
+	value: Schema.Union([
+		Schema.String,
+		Schema.Number,
+		Schema.Boolean
+	]),
+	offset: Schema.Number,
+	length: Schema.Number,
+	line: Schema.Number,
+	character: 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
+*/
+var StyleFloor = class extends Schema.TaggedClass()("StyleFloor", {
+	dimension: Schema.String,
+	value: Schema.Number
+}) {};
 
 //#endregion
-export { YamlLintDiagnostic, YamlLintSeverity };
+export { StyleFloor, StyleVote, YamlLintDiagnostic, YamlLintSeverity };

package/YamlNode.js

@@ -30,6 +30,21 @@ const CollectionStyle = Schema.Literals(["block", "flow"]);
 */
 const QuoteStyle = Schema.Literals(["single", "double"]);
 /**
+* 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
+*/
+const QuoteCompat = Schema.Literals(["yaml-1.1"]);
+/**
 * Block-scalar chomping indicators (`-` strip, default clip, `+` keep).
 * Referenced by the {@link YamlScalar} `chomp` field schema.
 *
@@ -442,4 +457,4 @@ function nodeToValue(node, anchors, budget, counting = false) {
 }
 
 //#endregion
-export { AliasExpansionBudgetExceeded, CollectionStyle, QuoteStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq, aliasExpansionLimit, nodeToJsValue };
+export { AliasExpansionBudgetExceeded, CollectionStyle, QuoteCompat, QuoteStyle, ScalarChomp, ScalarStyle, YamlAlias, YamlMap, YamlNode, YamlPair, YamlScalar, YamlSeq, aliasExpansionLimit, nodeToJsValue };