test(compatibility): document unsupported yaml gaps

This commit is contained in:
Mihaela Mihaljevic 2026-06-05 13:29:22 +02:00
parent ec457d61e8
commit 84a2de9ea1
9 changed files with 281 additions and 3 deletions

View File

@ -69,6 +69,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Add a fixture-backed collection and anchor compatibility corpus with exact
parsed values, parse errors, duplicate-key validation diagnostics, and pinned
unsupported merge-key behavior.
- Add executable unsupported-gap fixtures for multi-document streams, complex
mapping keys, unsupported directives, unsupported built-in tags, merge-key
fallback behavior, and direct value-tree validation.
### Changed

View File

@ -74,7 +74,7 @@ flowchart TB
Epic11["#11 YAML Compatibility Corpus"]:::epic
Scalar24["#24 Scalar and Tag Corpus"]:::done
Collection25["#25 Collection and Anchor Corpus"]:::done
Gaps27["#27 Unsupported YAML Gaps"]:::todo
Gaps27["#27 Unsupported YAML Gaps"]:::done
Literal19["#19 Literal Block Emission"]:::todo
Downstream26["#26 Downstream Document Fixtures"]:::todo
Epic11 --> Scalar24
@ -98,7 +98,9 @@ recognizes anchors, aliases, tags, flow collections, and block scalar styles fro
scanner tokens, and the public value parser composes those events into
`PureYAML.Model.Value`. Full tag-specific collection semantics, multi-document
streams, merge keys, directives beyond the selected compatibility subset, and
custom decoding are planned work.
custom decoding are planned work. Unsupported gaps are pinned by executable
tests so they produce exact errors or exact fallback value trees instead of
silent parser drift.
## Attribution

View File

@ -14,6 +14,8 @@ public extension PureYAML.Parsing {
case invalidTaggedScalar(tag: String, value: String, line: Int, column: Int)
case unterminatedTag(line: Int)
case unterminatedQuotedString(line: Int)
case unsupportedDirective(name: String, line: Int)
case unsupportedMultiDocumentStream(line: Int)
case undefinedAlias(anchor: String, line: Int, column: Int)
case unexpectedEvent(expected: String, actual: String, line: Int, column: Int)
case unexpectedToken(expected: String, actual: String, line: Int, column: Int)
@ -46,6 +48,10 @@ public extension PureYAML.Parsing {
"unterminated tag at line \(line)"
case let .unterminatedQuotedString(line):
"unterminated quoted string at line \(line)"
case let .unsupportedDirective(name, line):
"unsupported directive '\(name)' at line \(line)"
case let .unsupportedMultiDocumentStream(line):
"multi-document streams are not supported at line \(line)"
case let .undefinedAlias(anchor, line, column):
"undefined alias '\(anchor)' at line \(line), column \(column)"
case let .unexpectedEvent(expected, actual, line, column):

View File

@ -7,14 +7,28 @@ extension PureYAML.Parsing.Scanner {
try scanDirective(&state)
return true
}
if state.reader.peek() == "#" {
return false
}
if startsWith("---", state.reader), isIndicatorBoundary(state.reader.peek(offset: 3)) {
guard !state.hasDocumentContent, !state.hasDocumentStartMarker, !state.isDocumentClosed else {
throw PureYAML.Parsing.ParseError.unsupportedMultiDocumentStream(line: state.reader.mark.line)
}
state.hasDocumentStartMarker = true
skipLine(&state)
return true
}
if startsWith("...", state.reader), isIndicatorBoundary(state.reader.peek(offset: 3)) {
guard !state.isDocumentClosed else {
throw PureYAML.Parsing.ParseError.unsupportedMultiDocumentStream(line: state.reader.mark.line)
}
state.isDocumentClosed = true
skipLine(&state)
return true
}
guard !state.isDocumentClosed else {
throw PureYAML.Parsing.ParseError.unsupportedMultiDocumentStream(line: state.reader.mark.line)
}
return false
}
@ -27,6 +41,9 @@ extension PureYAML.Parsing.Scanner {
guard let name = parts.first else {
return
}
guard !state.hasDocumentContent, !state.hasDocumentStartMarker, !state.isDocumentClosed else {
throw PureYAML.Parsing.ParseError.unsupportedDirective(name: name, line: start.line)
}
switch name {
case "%YAML":
guard parts.indices.contains(1), parts[1] == "1.1" || parts[1] == "1.2" else {
@ -38,7 +55,7 @@ extension PureYAML.Parsing.Scanner {
}
state.tagHandles[parts[1]] = parts[2]
default:
return
throw PureYAML.Parsing.ParseError.unsupportedDirective(name: name, line: start.line)
}
}
}

View File

@ -43,6 +43,9 @@ extension PureYAML.Parsing.Scanner {
var tokens: [PureYAML.Parsing.Token] = []
var indentation: [Int] = [0]
var isAtLineStart = true
var hasDocumentContent = false
var hasDocumentStartMarker = false
var isDocumentClosed = false
var flowDepth = 0
var tagHandles = [
"!": "!",
@ -52,6 +55,7 @@ extension PureYAML.Parsing.Scanner {
mutating func append(_ kind: PureYAML.Parsing.TokenKind) {
let mark = reader.mark
tokens.append(PureYAML.Parsing.Token(kind: kind, mark: mark, endMark: mark))
markDocumentContentIfNeeded(kind)
}
mutating func append(
@ -60,6 +64,16 @@ extension PureYAML.Parsing.Scanner {
endMark: PureYAML.Parsing.Mark,
) {
tokens.append(PureYAML.Parsing.Token(kind: kind, mark: mark, endMark: endMark))
markDocumentContentIfNeeded(kind)
}
mutating func markDocumentContentIfNeeded(_ kind: PureYAML.Parsing.TokenKind) {
switch kind {
case .comment, .dedent, .indent, .streamEnd, .streamStart:
return
default:
hasDocumentContent = true
}
}
}
}

View File

@ -41,6 +41,51 @@ struct ParsingCompatibilityTests {
}
}
@Test(
"Reports exact unsupported YAML gap errors",
arguments: UnsupportedYAMLGapsFixtures.parseErrors,
)
func test_unsupportedYAMLGapParseErrors(testCase: UnsupportedYAMLGapsFixtures.ParseErrorCase) {
expectParseError(testCase.yaml, testCase.expected)
#expect(testCase.expected.description == testCase.expectedDescription)
}
@Test(
"Keeps unsupported YAML gaps as exact fallback values",
arguments: UnsupportedYAMLGapsFixtures.fallbackValues,
)
func test_unsupportedYAMLGapFallbackValues(testCase: UnsupportedYAMLGapsFixtures.FallbackValueCase) throws {
let value = try PureYAML.parse(testCase.yaml)
#expect(value == testCase.expected)
expectAbsentRootKeys(testCase.absentRootKeys, in: value)
#expect(PureYAML.Validation.Validator().collect(value) == PureYAML.Validation.Result())
}
@Test("Validates direct values for gaps ordinary loaders may collapse")
func test_directUnsupportedGapValueValidation() {
let value = UnsupportedYAMLGapsFixtures.directPreservedValue
let result = PureYAML.Validation.Validator().collect(value)
guard case let .mapping(mapping) = value else {
recordIssue("expected direct mapping value")
return
}
#expect(mapping.pairs.map(\.key) == ["<<", "title", "title"])
#expect(mapping["<<"] == .mapping(.init([
.init(key: "enabled", value: .bool(true)),
])))
#expect(result.issues == UnsupportedYAMLGapsFixtures.directPreservedIssues)
#expect(result.issues.map(\.description) == [
"error: Duplicate mapping key 'title' at $.title",
])
expectValidationError(value) { collection in
#expect(collection.issues == UnsupportedYAMLGapsFixtures.directPreservedIssues)
#expect(collection.description == "error: Duplicate mapping key 'title' at $.title")
}
}
@Test("Pins merge keys as unsupported unflattened mappings")
func test_mergeKeysRemainUnflattenedUntilExplicitlySupported() throws {
let root = try requireMapping(PureYAML.parse(

View File

@ -244,6 +244,8 @@ struct ParsingTests {
#expect(PureYAML.Parsing.ParseError.unterminatedTag(line: 8).description == "unterminated tag at line 8")
#expect(PureYAML.Parsing.ParseError.unterminatedQuotedString(line: 9).description == "unterminated quoted string at line 9")
#expect(PureYAML.Parsing.ParseError.incompatibleYAMLDirective(line: 10).description == "incompatible YAML directive at line 10")
#expect(PureYAML.Parsing.ParseError.unsupportedDirective(name: "%FOO", line: 10).description == "unsupported directive '%FOO' at line 10")
#expect(PureYAML.Parsing.ParseError.unsupportedMultiDocumentStream(line: 10).description == "multi-document streams are not supported at line 10")
#expect(PureYAML.Parsing.ParseError.expectedNode(line: 10, column: 2).description == "expected a YAML node at line 10, column 2")
#expect(PureYAML.Parsing.ParseError.expectedScalarKey(line: 11, column: 3).description == "expected a scalar mapping key at line 11, column 3")
#expect(PureYAML.Parsing.ParseError.undefinedAlias(anchor: "item", line: 12, column: 4).description == "undefined alias 'item' at line 12, column 4")

View File

@ -206,6 +206,10 @@ struct ScannerTests {
expectScannerError("alias: *", .expectedAliasName(line: 1))
expectScannerError("tag: !<tag:example.com,2026:thing", .unterminatedTag(line: 1))
expectScannerError("%YAML 1.3\n---\nvalue: yes", .incompatibleYAMLDirective(line: 1))
expectScannerError("%FOO bar\nvalue: yes", .unsupportedDirective(name: "%FOO", line: 1))
expectScannerError("---\n%TAG !e! tag:example.com,2026:", .unsupportedDirective(name: "%TAG", line: 2))
expectScannerError("---\n- one\n---\n- two", .unsupportedMultiDocumentStream(line: 3))
expectScannerError("value: one\n...\nvalue: two", .unsupportedMultiDocumentStream(line: 3))
}
}

View File

@ -0,0 +1,185 @@
@testable import PureYAML
enum UnsupportedYAMLGapsFixtures {
struct ParseErrorCase: CustomStringConvertible {
var name: String
var yaml: String
var expected: PureYAML.Parsing.ParseError
var expectedDescription: String
var description: String {
name
}
}
struct FallbackValueCase: CustomStringConvertible {
var name: String
var yaml: String
var expected: PureYAML.Model.Value
var absentRootKeys: [String]
var description: String {
name
}
init(
name: String,
yaml: String,
expected: PureYAML.Model.Value,
absentRootKeys: [String] = ["missing"],
) {
self.name = name
self.yaml = yaml
self.expected = expected
self.absentRootKeys = absentRootKeys
}
}
static let parseErrors: [ParseErrorCase] = [
ParseErrorCase(
name: "second document start marker",
yaml: """
---
- Mark McGwire
---
- Sammy Sosa
""",
expected: .unsupportedMultiDocumentStream(line: 3),
expectedDescription: "multi-document streams are not supported at line 3",
),
ParseErrorCase(
name: "content after explicit document end",
yaml: """
name: First
...
name: Second
""",
expected: .unsupportedMultiDocumentStream(line: 3),
expectedDescription: "multi-document streams are not supported at line 3",
),
ParseErrorCase(
name: "flow sequence mapping key",
yaml: """
? [Detroit Tigers, Chicago Cubs]
:
- 2001-07-23
""",
expected: .expectedScalarKey(line: 1, column: 3),
expectedDescription: "expected a scalar mapping key at line 1, column 3",
),
ParseErrorCase(
name: "flow mapping key",
yaml: """
? {name: Example}
: value
""",
expected: .expectedScalarKey(line: 1, column: 3),
expectedDescription: "expected a scalar mapping key at line 1, column 3",
),
ParseErrorCase(
name: "unknown directive",
yaml: """
%FOO bar
value: one
""",
expected: .unsupportedDirective(name: "%FOO", line: 1),
expectedDescription: "unsupported directive '%FOO' at line 1",
),
ParseErrorCase(
name: "tag directive after content",
yaml: """
value: one
%TAG !e! tag:example.com,2026:
""",
expected: .unsupportedDirective(name: "%TAG", line: 2),
expectedDescription: "unsupported directive '%TAG' at line 2",
),
ParseErrorCase(
name: "tag directive after document start",
yaml: """
---
%TAG !e! tag:example.com,2026:
value: !e!thing one
""",
expected: .unsupportedDirective(name: "%TAG", line: 2),
expectedDescription: "unsupported directive '%TAG' at line 2",
),
]
static let fallbackValues: [FallbackValueCase] = [
FallbackValueCase(
name: "unsupported built-in tags remain value trees",
yaml: """
date: !!timestamp 2001-01-23
payload: !!binary |
YWJj
set: !!set {a: null}
omap: !!omap [{a: 1}, {b: 2}]
""",
expected: .mapping(.init([
.init(key: "date", value: .string("2001-01-23")),
.init(key: "payload", value: .string("YWJj\n")),
.init(key: "set", value: .mapping(.init([
.init(key: "a", value: .null),
]))),
.init(key: "omap", value: .sequence([
.mapping(.init([
.init(key: "a", value: .int(1)),
])),
.mapping(.init([
.init(key: "b", value: .int(2)),
])),
])),
])),
),
FallbackValueCase(
name: "merge key remains ordinary mapping entry",
yaml: """
defaults: &defaults {enabled: true, retries: 3}
service:
<<: *defaults
name: API
""",
expected: .mapping(.init([
.init(key: "defaults", value: .mapping(.init([
.init(key: "enabled", value: .bool(true)),
.init(key: "retries", value: .int(3)),
]))),
.init(key: "service", value: .mapping(.init([
.init(key: "<<", value: .mapping(.init([
.init(key: "enabled", value: .bool(true)),
.init(key: "retries", value: .int(3)),
]))),
.init(key: "name", value: .string("API")),
]))),
])),
),
FallbackValueCase(
name: "comments after explicit document end stay non-content",
yaml: """
name: First
...
# trailing comment
""",
expected: .mapping(.init([
.init(key: "name", value: .string("First")),
])),
),
]
static let directPreservedValue = PureYAML.Model.Value.mapping(.init([
.init(key: "<<", value: .mapping(.init([
.init(key: "enabled", value: .bool(true)),
]))),
.init(key: "title", value: .string("First")),
.init(key: "title", value: .string("Second")),
]))
static let directPreservedIssues: [PureYAML.Validation.Issue] = [
.init(
severity: .error,
reason: "Duplicate mapping key 'title'",
path: .init([.key("title")]),
),
]
}