import Foundation

// MARK: - Authorship

/// Which of the three classes a commit is — the axis the message engine is allowed to know about.
///
/// The composer receives it because 06-history-undo.md ▸ Commit messages gives one rule that turns
/// on it (the root commit's fixed subject) and one that deliberately does not: "**Foreign commits
/// speak the same vocabulary.** Origin lives in the author field (structural attribution), not in
/// message prose — a foreign move reads 'Move card …' exactly like an app-mediated one". The
/// composer card therefore gets the fact and is expected to ignore it for phrasing; having it means
/// it never has to be plumbed later, and having it *named* means the rule about not using it has
/// something to point at.
public enum CommitAuthorship: Sendable, Equatable {
    /// The user acting through the app.
    case user
    /// A scheduled heal's own commit (ruled 2026-07-29).
    case heal
    /// Everything else, carrying the author it will be committed under.
    case foreign(GitIdentity)
}

// MARK: - The request

/// Everything the message engine is handed for one commit.
///
/// **A struct rather than an argument list**, because the point of this seam is that the semantic
/// composer — the next card — plugs into it without reshaping the engine: it can start reading
/// `snapshot` and HEAD's tree the day it lands, and any input it turns out to need joins this type
/// rather than every call site.
public struct CommitMessageRequest: Sendable {

    /// The board this is a commit in — and, for the composer card, where HEAD's tree is read from
    /// for the last-committed half of its diff.
    public let boardRoot: URL

    /// **The changed-path list** (06 ▸ Commit messages ▸ Non-snapshot files commit too: "beside the
    /// snapshot diff it receives the changed-path list, and non-snapshot paths compose *path-shaped
    /// events*"), narrowed to the paths *this* commit stages.
    public let changedPaths: [GitChangedPath]

    /// Which class this commit is.
    public let authorship: CommitAuthorship

    /// Whether this is the repository's first commit — the one commit with a subject of its own
    /// ("Initial board state", 06 ▸ Rules ▸ Abnormal repo states).
    public let isRootCommit: Bool

    /// The board as the app last read it, or `nil` where no store is attached (a storeless
    /// committer, a test). The current half of the composer's "last-committed vs. current" diff; the
    /// other half is HEAD's tree, which the composer reads for itself.
    public let snapshot: BoardModel?

    public init(
        boardRoot: URL,
        changedPaths: [GitChangedPath],
        authorship: CommitAuthorship,
        isRootCommit: Bool,
        snapshot: BoardModel?
    ) {
        self.boardRoot = boardRoot
        self.changedPaths = changedPaths
        self.authorship = authorship
        self.isRootCommit = isRootCommit
        self.snapshot = snapshot
    }
}

// MARK: - The seam

/// **What a commit says** (06-history-undo.md ▸ Commit messages).
///
/// The real implementation is the next card's: "a pure, testable function" composing from a
/// structural diff of two board snapshots, with the whole Add/Delete/Move/Rename/Edit vocabulary,
/// plural folding, path-shaped events for non-snapshot files, and the trash pair. None of that
/// exists yet; what exists is this protocol, so that arriving card is one type conforming here
/// rather than a change to the engine that calls it.
///
/// `Sendable` because composition runs off the main actor, inside the same detached task that stages
/// and commits — the message has to be in hand before `git_commit_create` is called, and none of the
/// work is main-actor work.
public protocol CommitMessageComposing: Sendable {
    func message(for request: CommitMessageRequest) -> String
}

// MARK: - The interim

/// **The placeholder message**, deliberately the *fallback* 06 already names rather than an
/// invention: "genuinely mixed windows fall back to 'Update board'".
///
/// So the trail an interim build writes is a trail the composer card only ever makes *more*
/// specific — no message written today becomes wrong tomorrow, and the root commit's subject is
/// already the settled one.
public struct InterimCommitMessage: CommitMessageComposing {

    /// 06's own mixed-window fallback.
    public static let fallbackSubject = "Update board"

    public init() {}

    public func message(for request: CommitMessageRequest) -> String {
        request.isRootCommit ? GitRepository.initialCommitSubject : Self.fallbackSubject
    }
}