rzen
4085dd7a46
Duplicates: Yams' duplicate-key error is disarmed by placeholder- renaming first occurrences and re-composing (line count preserved, so span layout stays exact); reads take the last occurrence, set() rewrites the winner and clears earlier twins, remove() clears all. Top-level only — nested duplicates stay YAML errors (doc updated). Re-splice: an inline comment on a rewritten scalar line survives, with quote-aware detection so a # inside quotes is never a comment. +31 tests (118 total). Claude-Session: https://claude.ai/code/session_018BjQRYBR6jQja3jCRi5S3A
469 lines
21 KiB
Swift
469 lines
21 KiB
Swift
import Foundation
|
|
import Yams
|
|
|
|
/// One `index.md`: YAML frontmatter between `---` delimiters, then the Markdown body.
|
|
///
|
|
/// The document keeps the file's raw text and edits it by line span, so anything the caller
|
|
/// does not touch is byte-identical on the way out — including unknown keys, their order,
|
|
/// comments, blank lines, and the body. YAML is used to *validate and read*, never to write.
|
|
public struct FrontmatterDocument: Sendable, Equatable {
|
|
/// A contiguous run of frontmatter lines. `key == nil` is a preamble/orphan run of
|
|
/// comments or blank lines. `tail` is the trailing comment/blank lines the run picked up —
|
|
/// held separately so `set`/`remove` never disturb them.
|
|
private struct Span: Sendable, Equatable {
|
|
var key: String?
|
|
var value: String
|
|
var tail: String
|
|
|
|
var text: String { value + tail }
|
|
}
|
|
|
|
private struct KeyedValue: Sendable, Equatable {
|
|
var key: String
|
|
var value: YAMLValue
|
|
}
|
|
|
|
private var openingDelimiter: String
|
|
private var closingDelimiter: String
|
|
private var spans: [Span]
|
|
private var values: [KeyedValue]
|
|
|
|
/// Everything after the closing delimiter line, verbatim.
|
|
public var body: String
|
|
|
|
/// An empty document, for files the app is creating rather than rewriting.
|
|
public init(body: String = "") {
|
|
openingDelimiter = "---\n"
|
|
closingDelimiter = "---\n"
|
|
spans = []
|
|
values = []
|
|
self.body = body
|
|
}
|
|
|
|
private init(openingDelimiter: String, closingDelimiter: String, spans: [Span], values: [KeyedValue], body: String) {
|
|
self.openingDelimiter = openingDelimiter
|
|
self.closingDelimiter = closingDelimiter
|
|
self.spans = spans
|
|
self.values = values
|
|
self.body = body
|
|
}
|
|
|
|
// MARK: - Parsing
|
|
|
|
/// Reads a file. YAML is composed to validate and interpret it; the text itself is retained
|
|
/// verbatim, so the parse only decides how the document *reads*, never how it is written.
|
|
///
|
|
/// **Duplicate top-level keys: last one wins** (01-storage-format.md § Frontmatter) — a
|
|
/// deliberate divergence from strict YAML, which rejects the file outright. The key's last
|
|
/// occurrence supplies the value, earlier twins are invisible to every read, and each
|
|
/// occurrence still keeps its own span, so the file round-trips byte-identically. `keys` and
|
|
/// `fields` present that effective view: one entry per key, at the position of the occurrence
|
|
/// that won (`a`, `b`, `a` reads as `b`, `a`) — which is also the order the file itself ends
|
|
/// up in once `set` collapses the twins. A duplicate *nested* inside a value's own mapping is
|
|
/// out of scope: it stays `unparseableYAML`, as does everything else libYAML rejects.
|
|
public static func parse(_ text: String) throws(FrontmatterError) -> FrontmatterDocument {
|
|
let lines = Self.lines(of: text)
|
|
guard let first = lines.first, Self.isDelimiter(first) else { throw .missingOpeningDelimiter }
|
|
guard let closingIndex = lines.dropFirst().firstIndex(where: Self.isDelimiter) else {
|
|
throw .missingClosingDelimiter
|
|
}
|
|
|
|
let yamlLines = Array(lines[1 ..< closingIndex])
|
|
let (node, placeholders) = try Self.composeToleratingDuplicateKeys(yamlLines)
|
|
|
|
let mapping: Node.Mapping
|
|
switch node {
|
|
case .none:
|
|
mapping = Node.Mapping([])
|
|
case let .some(root):
|
|
if let rootMapping = root.mapping {
|
|
mapping = rootMapping
|
|
} else if Resolver.default.resolveTag(of: root) == .null {
|
|
mapping = Node.Mapping([])
|
|
} else {
|
|
throw .frontmatterNotAMapping
|
|
}
|
|
}
|
|
|
|
let keys = mapping.map { pair in pair.key.string.map { placeholders[$0] ?? $0 } }
|
|
|
|
return FrontmatterDocument(
|
|
openingDelimiter: first,
|
|
closingDelimiter: lines[closingIndex],
|
|
spans: Self.makeSpans(lines: yamlLines, keys: keys),
|
|
values: Self.lastWinsValues(keys: keys, mapping: mapping),
|
|
body: lines[(closingIndex + 1)...].joined()
|
|
)
|
|
}
|
|
|
|
/// Composes the YAML block, tolerating repeated top-level keys.
|
|
///
|
|
/// libYAML refuses a mapping with a duplicated key, but its error is informative enough to
|
|
/// disarm: it names the duplicated keys and marks the *first* occurrence of one of them. That
|
|
/// occurrence's key is renamed to a placeholder and the block re-composed, until nothing is
|
|
/// duplicated. Renaming leaves the line count — and therefore every subsequent mark, and the
|
|
/// whole span layout — identical to the original, so the composed mapping still lines up with
|
|
/// the file's lines one for one; the returned table maps each placeholder back to the key it
|
|
/// stands for. Anything that is not a duplicate at column 0 (a nested duplicate included) is
|
|
/// reported as `unparseableYAML`, unchanged.
|
|
private static func composeToleratingDuplicateKeys(
|
|
_ lines: [String]
|
|
) throws(FrontmatterError) -> (node: Node?, placeholders: [String: String]) {
|
|
var work = lines
|
|
var placeholders: [String: String] = [:]
|
|
let prefix = Self.placeholderPrefix(avoiding: lines.joined())
|
|
|
|
while true {
|
|
do {
|
|
return (try Yams.compose(yaml: work.joined()), placeholders)
|
|
} catch let error as YamlError {
|
|
guard case let .duplicatedKeysInMapping(duplicates, context) = error else {
|
|
throw FrontmatterError.unparseableYAML(message: "\(error)", line: Self.fileLine(of: error))
|
|
}
|
|
// Marks are 1-based and count only the YAML block, which the rename never resizes.
|
|
let index = context.mark.line - 1
|
|
guard placeholders.count < lines.count, work.indices.contains(index),
|
|
let key = duplicates.first(where: { Self.lineStartsKey(work[index], key: $0) })
|
|
else {
|
|
throw FrontmatterError.unparseableYAML(message: "\(error)", line: Self.fileLine(of: error))
|
|
}
|
|
let placeholder = prefix + String(placeholders.count)
|
|
let line = work[index]
|
|
placeholders[placeholder] = key
|
|
work[index] = placeholder + String(line.dropFirst(Self.keyText(of: line, key: key).count))
|
|
} catch {
|
|
throw FrontmatterError.unparseableYAML(message: "\(error)", line: nil)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// A key stem that appears nowhere in the file, so a renamed duplicate can never collide with
|
|
/// a key the author actually wrote.
|
|
private static func placeholderPrefix(avoiding text: String) -> String {
|
|
var prefix = "__lanework_duplicate_"
|
|
while text.contains(prefix) { prefix += "_" }
|
|
return prefix
|
|
}
|
|
|
|
/// One entry per distinct key, carrying the *last* occurrence's value and sitting where that
|
|
/// occurrence sits — the last-wins reading of a file with repeated keys.
|
|
private static func lastWinsValues(keys: [String?], mapping: Node.Mapping) -> [KeyedValue] {
|
|
var values: [KeyedValue] = []
|
|
for (key, pair) in zip(keys, mapping) {
|
|
guard let key else { continue }
|
|
values.removeAll { $0.key == key }
|
|
values.append(KeyedValue(key: key, value: YAMLValue(pair.value)))
|
|
}
|
|
return values
|
|
}
|
|
|
|
public func serialized() -> String {
|
|
openingDelimiter + spans.map(\.text).joined() + closingDelimiter + body
|
|
}
|
|
|
|
// MARK: - Generic access
|
|
|
|
/// Top-level keys in document order — the effective, last-wins view: a key written twice
|
|
/// appears once, where its winning (last) occurrence sits (see `parse`).
|
|
public var keys: [String] { values.map(\.key) }
|
|
|
|
public var fields: [FrontmatterField] {
|
|
values.map { FrontmatterField(key: $0.key, value: $0.value, rawValue: rawValue(for: $0.key) ?? $0.value.description) }
|
|
}
|
|
|
|
/// Every key the schema does not own — reserved names (`labels`, `due`, `template`, …) and
|
|
/// agent overlays alike. Preserved verbatim and never interpreted.
|
|
public var unknownFields: [FrontmatterField] {
|
|
fields.filter { !FrontmatterKeys.schemaOwned.contains($0.key) }
|
|
}
|
|
|
|
public func contains(_ key: String) -> Bool {
|
|
values.contains { $0.key == key }
|
|
}
|
|
|
|
public func value(for key: String) -> YAMLValue? {
|
|
values.first { $0.key == key }?.value
|
|
}
|
|
|
|
/// The key's value text exactly as written, minus the `key:` header and surrounding
|
|
/// whitespace. Read from the winning (last) occurrence, like every other read.
|
|
public func rawValue(for key: String) -> String? {
|
|
spans.last { $0.key == key }.map { Self.valueText(of: $0.value, key: key) }
|
|
}
|
|
|
|
// MARK: - Surgical edits
|
|
|
|
/// Rewrites only this key's value lines. A new key is appended before the closing delimiter.
|
|
///
|
|
/// Two rules from 01-storage-format.md § Frontmatter land here:
|
|
///
|
|
/// - **Duplicates collapse.** The winning (last) occurrence is rewritten and every earlier
|
|
/// twin is deleted in the same call — the app owns the keys it writes, and a stale twin left
|
|
/// behind would resurrect itself the moment the winner were removed.
|
|
/// - **Comments survive.** Comments on their own lines are never touched, and an inline
|
|
/// comment trailing the rewritten value line is re-spliced after the new value at its
|
|
/// original distance (`order: 3072 # keep at top` → `order: 4096 # keep at top`). That
|
|
/// re-splice is best-effort — see `inlineComment(of:keyText:)`.
|
|
public mutating func set(_ key: String, to value: FrontmatterValue) {
|
|
if let index = spans.lastIndex(where: { $0.key == key }) {
|
|
spans[index].value = Self.rewritten(spans[index].value, key: key, to: value)
|
|
for twin in (0 ..< index).reversed() where spans[twin].key == key { clearSpan(at: twin) }
|
|
} else {
|
|
spans.append(Span(key: key, value: "\(FrontmatterValue.emitScalar(key)): \(value.yamlText)\n", tail: ""))
|
|
}
|
|
|
|
let parsed = KeyedValue(key: key, value: value.parsedValue)
|
|
if let index = values.firstIndex(where: { $0.key == key }) {
|
|
values[index] = parsed
|
|
} else {
|
|
values.append(parsed)
|
|
}
|
|
}
|
|
|
|
/// Deletes the key's value lines — *every* occurrence of it, so a removed key cannot be
|
|
/// resurrected by an earlier twin. Trailing comments and blank lines survive: they read as
|
|
/// belonging to whatever follows, and losing user text is worse than an orphaned comment.
|
|
public mutating func remove(_ key: String) {
|
|
for index in spans.indices.reversed() where spans[index].key == key { clearSpan(at: index) }
|
|
values.removeAll { $0.key == key }
|
|
}
|
|
|
|
/// Drops one span's value lines, keeping its trailing comments and blank lines.
|
|
private mutating func clearSpan(at index: Int) {
|
|
if spans[index].tail.isEmpty {
|
|
spans.remove(at: index)
|
|
} else {
|
|
spans[index] = Span(key: nil, value: "", tail: spans[index].tail)
|
|
}
|
|
}
|
|
|
|
// MARK: - Line splitting
|
|
|
|
private static func lines(of text: String) -> [String] {
|
|
let parts = text.components(separatedBy: "\n")
|
|
var lines = parts.dropLast().map { $0 + "\n" }
|
|
if let last = parts.last, !last.isEmpty { lines.append(last) }
|
|
return lines
|
|
}
|
|
|
|
private static func isDelimiter(_ line: String) -> Bool {
|
|
var trimmed = Substring(line)
|
|
while let last = trimmed.last, last.isWhitespace { trimmed = trimmed.dropLast() }
|
|
return trimmed == "---"
|
|
}
|
|
|
|
/// Splits the YAML block into per-key spans. A line only starts a span when it opens the key
|
|
/// the parser expects next, so an unindented value continuation (multi-line flow collections)
|
|
/// can never be mistaken for a key. `keys` lists every top-level occurrence, duplicates
|
|
/// included, so each twin gets its own span and the block still serializes back verbatim.
|
|
private static func makeSpans(lines: [String], keys: [String?]) -> [Span] {
|
|
var spans: [Span] = []
|
|
var current: Span?
|
|
var preamble = ""
|
|
var expected = 0
|
|
|
|
func flush() {
|
|
if let current {
|
|
spans.append(current)
|
|
} else if !preamble.isEmpty {
|
|
spans.append(Span(key: nil, value: "", tail: preamble))
|
|
}
|
|
}
|
|
|
|
for line in lines {
|
|
if expected < keys.count, let key = keys[expected], lineStartsKey(line, key: key) {
|
|
flush()
|
|
preamble = ""
|
|
current = Span(key: key, value: line, tail: "")
|
|
expected += 1
|
|
} else if var span = current {
|
|
if isTailLine(line) {
|
|
span.tail += line
|
|
} else {
|
|
span.value += span.tail + line
|
|
span.tail = ""
|
|
}
|
|
current = span
|
|
} else {
|
|
preamble += line
|
|
}
|
|
}
|
|
flush()
|
|
return spans
|
|
}
|
|
|
|
private static func isTailLine(_ line: String) -> Bool {
|
|
line.hasPrefix("#") || line.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
|
|
}
|
|
|
|
private static func keyCandidates(_ key: String) -> [String] {
|
|
[key, "\"\(key)\"", "'\(key)'"]
|
|
}
|
|
|
|
private static func lineStartsKey(_ line: String, key: String) -> Bool {
|
|
for candidate in keyCandidates(key) {
|
|
let prefix = candidate + ":"
|
|
guard line.hasPrefix(prefix) else { continue }
|
|
let rest = line.dropFirst(prefix.count)
|
|
if rest.isEmpty || rest.first?.isWhitespace == true { return true }
|
|
}
|
|
return false
|
|
}
|
|
|
|
private static func keyText(of spanValue: String, key: String) -> String {
|
|
keyCandidates(key).first { spanValue.hasPrefix($0 + ":") } ?? FrontmatterValue.emitScalar(key)
|
|
}
|
|
|
|
// MARK: - Rewriting a value line
|
|
|
|
/// The replacement text for a span's value lines: `key: newValue`, plus whatever inline
|
|
/// comment the old lines carried, ending the way they ended (a CRLF file stays CRLF).
|
|
private static func rewritten(_ spanValue: String, key: String, to value: FrontmatterValue) -> String {
|
|
let keyText = Self.keyText(of: spanValue, key: key)
|
|
let (comment, terminator) = Self.inlineComment(of: spanValue, keyText: keyText)
|
|
return "\(keyText): \(value.yamlText)\(comment)\(terminator)"
|
|
}
|
|
|
|
/// The trailing inline comment on a span, its leading whitespace included so it re-splices at
|
|
/// the distance the author left, along with the line's own terminator.
|
|
///
|
|
/// **Best-effort by design** (01-storage-format.md § Frontmatter). Guaranteed for the
|
|
/// realistic case — a value written on one line as a plain, single-quoted, or double-quoted
|
|
/// scalar — where YAML's own rule decides: `#` opens a comment only when preceded by
|
|
/// whitespace and not inside a quoted scalar, so the `#` in `title: "a # b"` is value text and
|
|
/// survives as part of the old value rather than being re-spliced. Pathological shapes lose
|
|
/// the comment instead of making the editor guess: a value spanning several lines (block
|
|
/// scalar, multi-line flow collection) is not scanned at all, and neither is a single-line
|
|
/// flow collection whose quotes do not balance.
|
|
private static func inlineComment(of spanValue: String, keyText: String) -> (comment: String, terminator: String) {
|
|
// A CRLF pair is one `Character`, so both endings have to be named explicitly.
|
|
var characters = Array(spanValue)
|
|
var terminator = "\n"
|
|
if characters.last == "\r\n" {
|
|
characters.removeLast()
|
|
terminator = "\r\n"
|
|
} else if characters.last == "\n" {
|
|
characters.removeLast()
|
|
}
|
|
// Only a value written on a single line is scanned; anything taller keeps no comment.
|
|
guard !characters.contains(where: { $0 == "\n" || $0 == "\r\n" }) else { return ("", terminator) }
|
|
let header = Array(keyText + ":")
|
|
guard characters.starts(with: header) else { return ("", terminator) }
|
|
|
|
var valueStart = header.count
|
|
while valueStart < characters.count, isSpaceOrTab(characters[valueStart]) { valueStart += 1 }
|
|
guard let hash = commentIndex(in: characters, valueStart: valueStart) else { return ("", terminator) }
|
|
|
|
var start = hash
|
|
while start > 0, isSpaceOrTab(characters[start - 1]) { start -= 1 }
|
|
return (String(characters[start...]), terminator)
|
|
}
|
|
|
|
/// Where this line's comment begins, or nil if it has none. The value's opening character
|
|
/// says how much of the line is off limits: a quoted scalar is skipped whole, a flow
|
|
/// collection is scanned with its quotes tracked, and a plain scalar cannot contain ` #` at
|
|
/// all — that sequence is exactly what ends it.
|
|
private static func commentIndex(in characters: [Character], valueStart: Int) -> Int? {
|
|
guard valueStart < characters.count else { return nil }
|
|
var index = valueStart
|
|
switch characters[valueStart] {
|
|
case "\"", "'":
|
|
guard let end = endOfQuoted(characters, from: valueStart) else { return nil }
|
|
index = end
|
|
case "[", "{":
|
|
return flowCommentIndex(characters, from: valueStart)
|
|
default:
|
|
break
|
|
}
|
|
while index < characters.count {
|
|
if characters[index] == "#", index > 0, isSpaceOrTab(characters[index - 1]) { return index }
|
|
index += 1
|
|
}
|
|
return nil
|
|
}
|
|
|
|
/// One past the closing quote of the quoted scalar starting at `start`, or nil if it does not
|
|
/// close on this line. `\"` escapes inside double quotes, `''` inside single ones.
|
|
private static func endOfQuoted(_ characters: [Character], from start: Int) -> Int? {
|
|
let quote = characters[start]
|
|
var index = start + 1
|
|
while index < characters.count {
|
|
if quote == "\"", characters[index] == "\\" {
|
|
index += 2
|
|
continue
|
|
}
|
|
if characters[index] == quote {
|
|
if quote == "'", index + 1 < characters.count, characters[index + 1] == "'" {
|
|
index += 2
|
|
continue
|
|
}
|
|
return index + 1
|
|
}
|
|
index += 1
|
|
}
|
|
return nil
|
|
}
|
|
|
|
/// A flow collection on one line: a quote here really does open a quoted scalar, so a `#`
|
|
/// inside one is value text.
|
|
private static func flowCommentIndex(_ characters: [Character], from start: Int) -> Int? {
|
|
var index = start
|
|
while index < characters.count {
|
|
switch characters[index] {
|
|
case "\"", "'":
|
|
guard let end = endOfQuoted(characters, from: index) else { return nil }
|
|
index = end
|
|
case "#" where index > 0 && isSpaceOrTab(characters[index - 1]):
|
|
return index
|
|
default:
|
|
index += 1
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
private static func isSpaceOrTab(_ character: Character) -> Bool {
|
|
character == " " || character == "\t"
|
|
}
|
|
|
|
private static func valueText(of spanValue: String, key: String) -> String {
|
|
let header = keyText(of: spanValue, key: key) + ":"
|
|
guard spanValue.hasPrefix(header) else {
|
|
return spanValue.trimmingCharacters(in: .whitespacesAndNewlines)
|
|
}
|
|
return spanValue.dropFirst(header.count).trimmingCharacters(in: .whitespacesAndNewlines)
|
|
}
|
|
|
|
private static func fileLine(of error: YamlError) -> Int? {
|
|
// +1 for the opening delimiter line, which is not part of the YAML handed to Yams.
|
|
switch error {
|
|
case let .scanner(_, _, mark, _), let .parser(_, _, mark, _), let .composer(_, _, mark, _):
|
|
mark.line + 1
|
|
case let .duplicatedKeysInMapping(_, context):
|
|
context.mark.line + 1
|
|
default:
|
|
nil
|
|
}
|
|
}
|
|
}
|
|
|
|
/// The keys the schema owns (01-storage-format.md § Frontmatter). Everything else is an
|
|
/// unknown key: round-tripped untouched, never interpreted.
|
|
public enum FrontmatterKeys {
|
|
public static let schema = "schema"
|
|
public static let title = "title"
|
|
public static let order = "order"
|
|
public static let width = "width"
|
|
public static let created = "created"
|
|
public static let modified = "modified"
|
|
public static let modifiedBy = "modified-by"
|
|
public static let deleted = "deleted"
|
|
public static let background = "background"
|
|
public static let icon = "icon"
|
|
public static let iconColor = "iconColor"
|
|
|
|
public static let schemaOwned: Set<String> = [
|
|
schema, title, order, width, created, modified, modifiedBy, deleted, background, icon, iconColor
|
|
]
|
|
}
|