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 } }
    }

    /// A non-finite reading (`.nan`, `.inf`) has no place in the total order the tie-break and
    /// midpoint math assume (01-storage-format.md § Frontmatter, settled) — it is the same loud
    /// malformed-input rejection as a non-numeric value, not a `.valid(Double.nan)` silently
    /// poisoning every comparison downstream. An `Int` reading is always finite, so only the
    /// `.double` case needs the check.
    public var order: FieldValue<Double> {
        read(FrontmatterKeys.order) { value, _ in
            switch value {
            case let .int(value): Double(value)
            case let .double(value): value.isFinite ? value : nil
            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 exact-integer reading — from an int, a double, or a numeric string —
    /// always coerces: at or above 1 to itself (`"2"`, `2.0` → `2`), below 1 to 1 (**ranges are
    /// part of the sensible reading**, 01-storage-format.md § Frontmatter, settled — the table's
    /// "≥ 1" is a validity bound on the coerced reading, not a gate on which readings are
    /// sensible). Everything else — fractional, non-numeric, bool, a sequence/mapping — has no
    /// integer reading at all and is malformed, rendering as the default 1.
    public var width: FieldValue<Int> {
        read(FrontmatterKeys.width) { value, _ in
            switch value {
            case let .int(value): value >= 1 ? value : 1
            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) }

    /// The object's kind as written — `board`, `lane`, `card` (01-storage-format.md § Frontmatter,
    /// re-ruled 2026-07-29). Lenient like every other string field: any scalar coerces to the text
    /// the author typed, and **the value is never policed** — a reading outside the schema's three
    /// is a perfectly good `.valid` here, and the one consumer that acts on it (the trash's
    /// discriminator, `IntegrityRules.trashKind`) falls through to shape for anything it does not
    /// recognize rather than correcting the file.
    ///
    /// `.missing` — no key, or an explicit null — is what the on-touch backfill answers to.
    public var kind: FieldValue<String> { read(FrontmatterKeys.kind, 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 coerces — below 1 to 1, at or above 1 to the
    /// value itself; a fractional reading, a non-numeric one, or one outside `Int` range on the
    /// high end has no sensible width reading at all. The high-end guard is what makes `Int(value)`
    /// safe below; there is no matching low-end guard because anything below 1 short-circuits to
    /// the literal `1` without ever converting the (possibly enormous negative) double to `Int`.
    private static func exactIntWidth(_ value: Double) -> Int? {
        guard value.truncatingRemainder(dividingBy: 1) == 0, value <= Double(Int.max) else { return nil }
        return value >= 1 ? Int(value) : 1
    }

    /// 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
        }
    }
}