# frozen_string_literal: true

class Assistant::Function::GetStatementCoverage < Assistant::Function
  include Assistant::Function::StatementVaultSupport

  class << self
    def name
      "get_statement_coverage"
    end

    def description
      <<~INSTRUCTIONS
        Report, month by month, which statements the family actually holds for an
        account in a given year — the document-coverage map behind the numbers.

        Each month comes back with one status:

        - `covered` — a linked statement covers the month and reconciles
        - `mismatched` — a statement covers it, but its balances disagree with the ledger
        - `missing` — no statement on record; the month's figures have no document behind them
        - `ambiguous` — a statement was suggested for this account but nobody has confirmed the link
        - `duplicate` — two or more linked statements overlap the same month
        - `not_expected` — outside the account's expected statement range

        Use it before asserting anything about a period: "no statement on record"
        is a legitimate and necessary answer, and is very different from "the
        balance was zero". Use it to tell the user exactly which documents to go
        find.

        Example:

        ```
        get_statement_coverage({ account_id: "abc123-def456", year: 2026 })
        ```
      INSTRUCTIONS
    end
  end

  def strict_mode?
    false
  end

  def params_schema
    build_schema(
      required: [ "account_id" ],
      properties: {
        account_id: {
          type: "string",
          description: "UUID of the account to report coverage for."
        },
        year: {
          type: "integer",
          description: "Calendar year. Defaults to the most recent year with expected statements."
        }
      }
    )
  end

  def call(params = {})
    return not_a_statement_manager unless statement_manager?

    account_id = params["account_id"].to_s
    return error("invalid_account_id", "account_id must be a UUID.") unless valid_uuid?(account_id)

    account = family.accounts.accessible_by(user).find_by(id: account_id)
    return error("account_not_found", "No accessible account found with that ID.") unless account

    coverage = AccountStatement::Coverage.for_year(account, params["year"])

    {
      success: true,
      account: account_ref(account),
      year: coverage.selected_year,
      available_years: coverage.available_years,
      summary: coverage.summary_counts,
      months: coverage.months.map { |month| month_payload(month) }
    }
  end

  private
    def month_payload(month)
      {
        month: month.date.strftime("%Y-%m"),
        status: month.status,
        statement_ids: month.statements.map(&:id),
        unconfirmed_statement_ids: month.ambiguous_statements.map(&:id)
      }.compact_blank
    end
end