import Foundation

/// Structural failures parsing an `index.md`. Everything here is fail-fast material
/// (01-storage-format.md § Malformed input); lenient field problems never surface as errors.
public enum FrontmatterError: Error, Equatable, Sendable, CustomStringConvertible {
    case missingOpeningDelimiter
    case missingClosingDelimiter
    /// `line` is 1-based within the whole file, not within the YAML block.
    case unparseableYAML(message: String, line: Int?)
    case frontmatterNotAMapping

    public var description: String {
        switch self {
        case .missingOpeningDelimiter:
            "File does not start with a '---' frontmatter delimiter"
        case .missingClosingDelimiter:
            "Frontmatter is never closed by a '---' delimiter"
        case let .unparseableYAML(message, line):
            line.map { "Unparseable YAML at line \($0): \(message)" } ?? "Unparseable YAML: \(message)"
        case .frontmatterNotAMapping:
            "Frontmatter is not a YAML mapping"
        }
    }
}