lanework/Kanban/Storage/FrontmatterFields.swift

import Foundation
import Yams

/// One top-level frontmatter entry: what YAML made of it plus the text as written.
public struct FrontmatterField: Sendable, Equatable {
    public let key: String
    public let value: YAMLValue
    public let rawValue: String
}

/// The result of reading a typed field. `malformed` is what keeps strict fields (`schema`,
/// `order`) from being silently coerced — they fail the load instead. Lenient fields (colors,
/// icons, `width`) coerce where a sensible reading exists (01-storage-format.md § Frontmatter)
/// and only fall back to `.malformed` — rendered as the field's default — when none does.
public enum FieldValue<Value: Sendable & Equatable>: Sendable, Equatable {
    case missing
    case valid(Value)
    case malformed(raw: String)

    public var value: Value? {
        if case let .valid(value) = self { return value }
        return nil
    }

    public var isMissing: Bool {
        if case .missing = self { return true }
        return false
    }

    public var isMalformed: Bool {
        if case .malformed = self { return true }
        return false
    }

    /// The value as written, for a malformed field.
    public var rawText: String? {
        if case let .malformed(raw) = self { return raw }
        return nil
    }
}

extension FrontmatterDocument {
    // MARK: - Strict (structure — the loader fails fast on `.malformed`)

    public var schema: FieldValue<Int> {
        read(FrontmatterKeys.schema) { value, _ in if case let .int(value) = value { value } else { nil } }
    }

    public var order: FieldValue<Double> {
        read(FrontmatterKeys.order) { value, _ in
            switch value {
            case let .int(value): Double(value)
            case let .double(value): value
            default: nil
            }
        }
    }

    // MARK: - Lenient (coerce where a sensible reading exists, else malformed → UI default)

    /// Any scalar coerces to the text the author typed — a quoted string's own text (quotes and
    /// escapes already resolved by the parser), or an unquoted scalar's exact source span
    /// (`title: 2048` reads as `"2048"`). Only a sequence or mapping — no scalar reading exists
    /// — is malformed.
    public var title: FieldValue<String> { read(FrontmatterKeys.title, Self.string) }
    public var background: FieldValue<String> { read(FrontmatterKeys.background, Self.string) }
    public var icon: FieldValue<String> { read(FrontmatterKeys.icon, Self.string) }
    public var iconColor: FieldValue<String> { read(FrontmatterKeys.iconColor, Self.string) }

    /// Width multiplier. An int stays; a string or double with an exact integer reading ≥ 1
    /// coerces (`"2"`, `2.0` → `2`). Everything else — zero, negative, fractional, non-numeric,
    /// bool, a sequence/mapping — is malformed and renders as the default 1.
    public var width: FieldValue<Int> {
        read(FrontmatterKeys.width) { value, _ in
            switch value {
            case let .int(value): value >= 1 ? value : nil
            case let .double(value): Self.exactIntWidth(value)
            case let .string(text): Double(text).flatMap(Self.exactIntWidth)
            default: nil
            }
        }
    }

    public var created: FieldValue<Date> { read(FrontmatterKeys.created) { value, _ in Self.date(value) } }
    public var modified: FieldValue<Date> { read(FrontmatterKeys.modified) { value, _ in Self.date(value) } }
    public var deleted: FieldValue<Date> { read(FrontmatterKeys.deleted) { value, _ in Self.date(value) } }

    /// Schema-owned, not an unknown key: the app clears it on every app-mediated write.
    public var modifiedBy: FieldValue<String> { read(FrontmatterKeys.modifiedBy, Self.string) }

    // MARK: -

    private func read<Value>(_ key: String, _ transform: (YAMLValue, String) -> Value?) -> FieldValue<Value> {
        guard let value = value(for: key) else { return .missing }
        if case .null = value { return .missing }
        let raw = rawValue(for: key) ?? value.description
        if let typed = transform(value, raw) { return .valid(typed) }
        return .malformed(raw: raw)
    }

    /// A quoted string reads as its own (already-unquoted, already-unescaped) text; any other
    /// scalar reads as its raw source span — what the author typed. Only a sequence/mapping has
    /// no sensible string reading.
    private static func string(_ value: YAMLValue, raw: String) -> String? {
        switch value {
        case let .string(text): text
        case .int, .double, .bool, .date: raw
        default: nil
        }
    }

    /// An integer-valued double or numeric string ≥ 1 coerces; anything else (fractional,
    /// non-numeric, out of `Int` range) has no sensible width reading.
    private static func exactIntWidth(_ value: Double) -> Int? {
        guard value.truncatingRemainder(dividingBy: 1) == 0, value >= 1, value <= Double(Int.max) else { return nil }
        return Int(value)
    }

    /// A quoted timestamp reads the same as an unquoted one — same YAML 1.1 timestamp grammar,
    /// a superset of ISO-8601. Anything that isn't a valid timestamp either way has no sensible
    /// date reading and is malformed; per the tombstone rule (`Lane`/`Card.isDeleted`), a
    /// malformed `deleted` still deletes — presence, not validity, is what counts.
    private static func date(_ value: YAMLValue) -> Date? {
        switch value {
        case let .date(date): date
        case let .string(text): Date.construct(from: Node.Scalar(text))
        default: nil
        }
    }
}