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 — **the document's reading, before any policy**. 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. Structural fields (`schema`, `order`) have no coercion at all at this layer: a value that
/// is not an integer, or not a finite number, is `.malformed` and nothing here decides what that
/// costs. **What it costs is the rulebook's** (`IntegrityRules`): a malformed `schema` refuses the
/// load, while a malformed or missing `order` below the board root reads as append-at-end
/// (re-ruled 2026-07-31) — one shape, two policies, and this type carries neither.
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
    }
}

/// One **lenient** field that had no sensible reading and fell back to its default — the coerce
/// tier's observability record (01-storage-format.md § Frontmatter, ruled 2026-07-29: "A
/// no-sensible-reading fallback logs: field, path, and raw text, carried as coerce-tier entries in the
/// integrity service's Defect stream").
///
/// **Two of the three facts, because this layer only has two.** `FrontmatterFields` is a pure reading
/// of one document's bytes and has no idea which file it came from, so the *path* is attached by the
/// loader, which does (`CoercedFrontmatter`). Threading a path down here to satisfy the record's shape
/// would put filesystem context into the one layer that is deliberately free of it.
public struct CoercedField: Sendable, Equatable {
    /// The frontmatter key, as the schema spells it.
    public let key: String
    /// The value exactly as written — the raw source span, which is the only form worth recording:
    /// this exists so that a shape observed in the wild can later be promoted to a heuristic heal, and
    /// a normalized rendering of a value nobody could read would defeat that.
    public let raw: String

    public init(key: String, raw: String) {
        self.key = key
        self.raw = raw
    }
}

extension FrontmatterDocument {

    // MARK: - The coerce tier's own report

    /// Every **lenient** field in this document that had no sensible reading, in schema order — the
    /// coerce tier's whole observability contribution (01-storage-format.md § Frontmatter, ruled
    /// 2026-07-29: "the family posture: every silent recovery leaves a trace").
    ///
    /// **Read-side only, and nothing branches on it.** The values still render as their defaults —
    /// untitled placeholder, width 1, no color, no icon, no timestamp — the bytes on disk are still
    /// preserved verbatim, and no banner is raised. The list exists so the fallback is *visible*: it is
    /// "the one place where an observed-in-the-wild shape can later be promoted to a heuristic heal or
    /// a notice".
    ///
    /// **The structural fields are absent, and so is `deleted`.** `schema` and `order` are read
    /// through the rulebook rather than here (`IntegrityRules.resolvedSchema`/`resolvedOrder`),
    /// because their readings depend on something this layer cannot see — *which level the file sits
    /// at*: the root's `schema` refuses, a lane's or card's defaults to 1, and `order` below the root
    /// reads as append-at-end (re-ruled 2026-07-31). Those two make their own `CoercedField`s, which
    /// the loader concatenates with this list; they also cover the shape a pure document reading
    /// cannot produce at all — an **absent** key, which has no `rawText` to record. `deleted` is the
    /// odd one out on purpose: its rule is *presence, not validity* (a malformed `deleted` still
    /// deletes — `Lane`/`Card.isDeleted`), so nothing falls back to a default and the migration
    /// reports it under its own defect anyway.
    ///
    /// A document whose fields all read cleanly answers `[]`, which is the overwhelmingly common case
    /// and costs one pass over the lenient fields.
    public var coercedFields: [CoercedField] {
        var found: [CoercedField] = []
        func record(_ key: String, _ field: FieldValue<some Sendable & Equatable>) {
            guard let raw = field.rawText else { return }
            found.append(CoercedField(key: key, raw: raw))
        }
        record(FrontmatterKeys.title, title)
        record(FrontmatterKeys.width, width)
        record(FrontmatterKeys.created, created)
        record(FrontmatterKeys.modified, modified)
        record(FrontmatterKeys.modifiedBy, modifiedBy)
        record(FrontmatterKeys.author, author)
        record(FrontmatterKeys.background, background)
        record(FrontmatterKeys.icon, icon)
        record(FrontmatterKeys.iconColor, iconColor)
        record(FrontmatterKeys.kind, kind)
        return found
    }

    // MARK: - Structural (no coercion here — `IntegrityRules` decides what `.malformed` costs)

    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 `.malformed` here,
    /// never a `.valid(Double.nan)` silently poisoning every comparison downstream. An `Int` reading
    /// is always finite, so only the `.double` case needs the check.
    ///
    /// Below the board root `.malformed` and `.missing` are one reading — append-at-end, coerce-tier
    /// (re-ruled 2026-07-31, `IntegrityRules.resolvedOrder`) — but they stay two shapes here, because
    /// the coerce record wants the text as written and only one of them has any.
    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) }

    /// A comment's self-reported `author` — lenient like every other string field, and **content**
    /// rather than overlay: no app write ever clears it (01-storage-format.md § Enhanced schema; see
    /// `FrontmatterKeys.author`). On any other kind the key is an ordinary unknown one; reading it
    /// here costs the same one pass and keeps the coerce tier's trace complete for the one kind whose
    /// field table names it.
    public var author: FieldValue<String> { read(FrontmatterKeys.author, 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
        }
    }
}