Add compat option

docs/03_options.md

@@ -71,13 +71,14 @@ The `!!value` and `!!yaml` types are not supported.
 
 Used by: `parse()`, `parseDocument()`, `parseAllDocuments()`, `stringify()`, `new Composer()`, `new Document()`, and `doc.setSchema()`
 
-| Name             | Type                                                   | Default                                  | Description                                                                                                                                                             |
-| ---------------- | ------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| customTags       | `Tag[] ⎮ function`                                     |                                          | Array of [additional tags](#custom-data-types) to include in the schema                                                                                                 |
-| merge            | `boolean`                                              | 1.1:&nbsp;`true` 1.2:&nbsp;`false`       | Enable support for `<<` merge keys. Default value depends on YAML version.                                                                                              |
-| resolveKnownTags | `boolean`                                              | `true`                                   | When using the `'core'` schema, support parsing values with these explicit [YAML 1.1 tags]: `!!binary`, `!!omap`, `!!pairs`, `!!set`, `!!timestamp`. By default `true`. |
-| schema           | `'core' ⎮ 'failsafe' ⎮` `'json' ⎮ 'yaml-1.1' ⎮ string` | 1.1:&nbsp;`'yaml-1.1` 1.2:&nbsp;`'core'` | The base schema to use. Default value depends on YAML version. If using a custom value, `customTags` must be an array of tags.                                          |
-| sortMapEntries   | `boolean ⎮` `(a, b: Pair) => number`                   | `false`                                  | When stringifying, sort map entries. If `true`, sort by comparing key values using the native less-than `<` operator.                                                   |
+| Name             | Type                                 | Default                                  | Description                                                                                                                                                                                                         |
+| ---------------- | ------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| compat           | `string ⎮ Tag[] ⎮ null`              | `null`                                   | When parsing, warn about compatibility issues with the given schema. When stringifying, use scalar styles that are parsed correctly by the `compat` schema as well as the actual schema.                            |
+| customTags       | `Tag[] ⎮ function`                   |                                          | Array of [additional tags](#custom-data-types) to include in the schema                                                                                                                                             |
+| merge            | `boolean`                            | 1.1:&nbsp;`true` 1.2:&nbsp;`false`       | Enable support for `<<` merge keys. Default value depends on YAML version.                                                                                                                                          |
+| resolveKnownTags | `boolean`                            | `true`                                   | When using the `'core'` schema, support parsing values with these explicit [YAML 1.1 tags]: `!!binary`, `!!omap`, `!!pairs`, `!!set`, `!!timestamp`. By default `true`.                                             |
+| schema           | `string`                             | 1.1:&nbsp;`'yaml-1.1` 1.2:&nbsp;`'core'` | The base schema to use. Default value depends on YAML version. Built-in support is provided for `'core'`, `'failsafe'`, `'json'`, and `'yaml-1.1'`. If using another value, `customTags` must be an array of tags. |
+| sortMapEntries   | `boolean ⎮` `(a, b: Pair) => number` | `false`                                  | When stringifying, sort map entries. If `true`, sort by comparing key values using the native less-than `<` operator.                                                                                               |
 
 [yaml 1.1 tags]: https://yaml.org/type/
 

src/compose/compose-scalar.ts

@@ -27,7 +27,9 @@ export function composeScalar(
   const tag =
     tagToken && tagName
       ? findScalarTagByName(ctx.schema, value, tagName, tagToken, onError)
-      : findScalarTagByTest(ctx.schema, value, token.type === 'scalar')
+      : token.type === 'scalar'
+      ? findScalarTagByTest(ctx, value, token, onError)
+      : ctx.schema[SCALAR]
 
   let scalar: Scalar
   try {
@@ -84,11 +86,28 @@ function findScalarTagByName(
   return schema[SCALAR]
 }
 
-function findScalarTagByTest(schema: Schema, value: string, apply: boolean) {
-  if (apply) {
-    for (const tag of schema.tags) {
-      if (tag.default && tag.test?.test(value)) return tag
+function findScalarTagByTest(
+  { directives, schema }: ComposeContext,
+  value: string,
+  token: FlowScalar,
+  onError: ComposeErrorHandler
+) {
+  const tag =
+    (schema.tags.find(
+      tag => tag.default && tag.test?.test(value)
+    ) as ScalarTag) || schema[SCALAR]
+
+  if (schema.compat) {
+    const compat =
+      schema.compat.find(tag => tag.default && tag.test?.test(value)) ||
+      schema[SCALAR]
+    if (tag.tag !== compat.tag) {
+      const ts = directives.tagString(tag.tag)
+      const cs = directives.tagString(compat.tag)
+      const msg = `Value may be parsed as either ${ts} or ${cs}`
+      onError(token, 'TAG_RESOLVE_FAILED', msg, true)
     }
   }
-  return schema[SCALAR]
+
+  return tag
 }

src/compose/resolve-block-map.ts

@@ -6,6 +6,7 @@ import type { ComposeContext, ComposeNode } from './compose-node.js'
 import type { ComposeErrorHandler } from './composer.js'
 import { resolveProps } from './resolve-props.js'
 import { containsNewline } from './util-contains-newline.js'
+import { flowIndentCheck } from './util-flow-indent-check.js'
 import { mapIncludes } from './util-map-includes.js'
 
 const startColMsg = 'All mapping items must start at the same column'
@@ -64,6 +65,7 @@ export function resolveBlockMap(
     const keyNode = key
       ? composeNode(ctx, key, keyProps, onError)
       : composeEmptyNode(ctx, keyStart, start, null, keyProps, onError)
+    if (ctx.schema.compat) flowIndentCheck(bm.indent, key, onError)
 
     if (mapIncludes(ctx, map.items, keyNode))
       onError(keyStart, 'DUPLICATE_KEY', 'Map keys must be unique')
@@ -100,6 +102,7 @@ export function resolveBlockMap(
       const valueNode = value
         ? composeNode(ctx, value, valueProps, onError)
         : composeEmptyNode(ctx, offset, sep, null, valueProps, onError)
+      if (ctx.schema.compat) flowIndentCheck(bm.indent, value, onError)
       offset = valueNode.range[2]
       const pair = new Pair(keyNode, valueNode)
       if (ctx.options.keepSourceTokens) pair.srcToken = collItem

src/compose/resolve-block-seq.ts

@@ -3,6 +3,7 @@ import type { BlockSequence } from '../parse/cst.js'
 import type { ComposeContext, ComposeNode } from './compose-node.js'
 import type { ComposeErrorHandler } from './composer.js'
 import { resolveProps } from './resolve-props.js'
+import { flowIndentCheck } from './util-flow-indent-check.js'
 
 export function resolveBlockSeq(
   { composeNode, composeEmptyNode }: ComposeNode,
@@ -40,6 +41,7 @@ export function resolveBlockSeq(
     const node = value
       ? composeNode(ctx, value, props, onError)
       : composeEmptyNode(ctx, offset, start, null, props, onError)
+    if (ctx.schema.compat) flowIndentCheck(bs.indent, value, onError)
     offset = node.range[2]
     seq.items.push(node)
   }

src/compose/util-flow-indent-check.ts

@@ -0,0 +1,21 @@
+import { Token } from '../parse/cst'
+import { ComposeErrorHandler } from './composer'
+import { containsNewline } from './util-contains-newline'
+
+export function flowIndentCheck(
+  indent: number,
+  fc: Token | null | undefined,
+  onError: ComposeErrorHandler
+) {
+  if (fc?.type === 'flow-collection') {
+    const end = fc.end[0]
+    if (
+      end.indent === indent &&
+      (end.source === ']' || end.source === '}') &&
+      containsNewline(fc)
+    ) {
+      const msg = 'Flow end indicator should be more indented than parent'
+      onError(end, 'BAD_INDENT', msg, true)
+    }
+  }
+}

src/options.ts

@@ -85,6 +85,15 @@ export type DocumentOptions = {
 }
 
 export type SchemaOptions = {
+  /**
+   * When parsing, warn about compatibility issues with the given schema.
+   * When stringifying, use scalar styles that are parsed correctly
+   * by the `compat` schema as well as the actual schema.
+   *
+   * Default: `null`
+   */
+  compat?: string | Tags | null
+
   /**
    * Array of additional tags to include in the schema, or a function that may
    * modify the schema's base tag array.

src/schema/Schema.ts

@@ -11,6 +11,7 @@ const sortMapEntriesByKey = (a: Pair<any>, b: Pair<any>) =>
   a.key < b.key ? -1 : a.key > b.key ? 1 : 0
 
 export class Schema {
+  compat: Array<CollectionTag | ScalarTag> | null
   knownTags: Record<string, CollectionTag | ScalarTag>
   merge: boolean
   name: string
@@ -23,12 +24,18 @@ export class Schema {
   [SEQ]: CollectionTag
 
   constructor({
+    compat,
     customTags,
     merge,
     resolveKnownTags,
     schema,
     sortMapEntries
   }: SchemaOptions) {
+    this.compat = Array.isArray(compat)
+      ? getTags(compat, 'compat')
+      : compat
+      ? getTags(null, compat)
+      : null
     this.merge = !!merge
     this.name = schema || 'core'
     this.knownTags = resolveKnownTags ? coreKnownTags : {}

src/stringify/stringifyString.ts

@@ -6,6 +6,7 @@ import {
   FOLD_FLOW,
   FOLD_QUOTED
 } from './foldFlowLines.js'
+import type { CollectionTag, ScalarTag } from '../schema/types.js'
 import type { StringifyContext } from './stringify.js'
 
 interface StringifyScalar {
@@ -306,14 +307,10 @@ function plainString(
   // booleans get parsed with those types in v1.2 (e.g. '42', 'true' & '0.9e-3'),
   // and others in v1.1.
   if (actualString) {
-    for (const tag of ctx.doc.schema.tags) {
-      if (
-        tag.default &&
-        tag.tag !== 'tag:yaml.org,2002:str' &&
-        tag.test?.test(str)
-      )
-        return quotedString(value, ctx)
-    }
+    const test = (tag: CollectionTag | ScalarTag) =>
+      tag.default && tag.tag !== 'tag:yaml.org,2002:str' && tag.test?.test(str)
+    const { compat, tags } = ctx.doc.schema
+    if (tags.some(test) || compat?.some(test)) return quotedString(value, ctx)
   }
   return implicitKey
     ? str

tests/compat.ts

@@ -0,0 +1,87 @@
+import { parseDocument, stringify } from 'yaml'
+
+describe('composer compatibility warnings', () => {
+  test('disabled by default', () => {
+    let doc = parseDocument('x: true\ny: off\n')
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toHaveLength(0)
+    expect(doc.toJS()).toEqual({ x: true, y: 'off' })
+
+    doc = parseDocument('x: true\ny: off\n', { version: '1.1' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toHaveLength(0)
+    expect(doc.toJS()).toEqual({ x: true, true: false })
+  })
+
+  test("schema: 'core', compat: 'yaml-1.1'", () => {
+    const doc = parseDocument('x: true\ny: off\n', { compat: 'yaml-1.1' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toMatchObject([
+      { code: 'TAG_RESOLVE_FAILED', pos: [8, 9] },
+      { code: 'TAG_RESOLVE_FAILED', pos: [11, 14] }
+    ])
+    expect(doc.toJS()).toEqual({ x: true, y: 'off' })
+  })
+
+  test("schema: 'yaml-1.1', compat: 'core'", () => {
+    const doc = parseDocument('x: true\ny: off\n', {
+      schema: 'yaml-1.1',
+      compat: 'core'
+    })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toMatchObject([
+      { code: 'TAG_RESOLVE_FAILED', pos: [8, 9] },
+      { code: 'TAG_RESOLVE_FAILED', pos: [11, 14] }
+    ])
+    expect(doc.toJS()).toEqual({ x: true, true: false })
+  })
+
+  test('single-line flow collection', () => {
+    const doc = parseDocument('foo: { x: 42 }\n', { compat: 'core' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toHaveLength(0)
+  })
+
+  test('flow collection with end at parent map indent', () => {
+    let doc = parseDocument('x: {\n  y: 42\n}', { compat: 'core' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toMatchObject([{ code: 'BAD_INDENT', pos: [13, 14] }])
+
+    doc = parseDocument('x:\n {\n  y: 42\n }', { compat: 'core' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toHaveLength(0)
+  })
+
+  test('flow collection with end at parent seq indent', () => {
+    let doc = parseDocument('- {\n  y: 42\n}', { compat: 'core' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toMatchObject([{ code: 'BAD_INDENT', pos: [12, 13] }])
+
+    doc = parseDocument('- {\n  y: 42\n }', { compat: 'core' })
+    expect(doc.errors).toHaveLength(0)
+    expect(doc.warnings).toHaveLength(0)
+  })
+})
+
+describe('stringify compatible values', () => {
+  test('disabled by default', () => {
+    let res = stringify({ x: true, y: 'off' })
+    expect(res).toBe('x: true\ny: off\n')
+
+    res = stringify({ x: true, y: 'off' }, { version: '1.1' })
+    expect(res).toBe('x: true\n"y": "off"\n')
+  })
+
+  test("schema: 'core', compat: 'yaml-1.1'", () => {
+    const res = stringify({ x: true, y: 'off' }, { compat: 'yaml-1.1' })
+    expect(res).toBe('x: true\n"y": "off"\n')
+  })
+
+  test("schema: 'yaml-1.1', compat: 'json'", () => {
+    const res = stringify(
+      { x: true, y: 'off' },
+      { schema: 'yaml-1.1', compat: 'json' }
+    )
+    expect(res).toBe('"x": true\n"y": "off"\n')
+  })
+})