import { getDb } from "./db";
import { getBudgetVsActualData } from "./budgetService";
import type {
  MonthlyTrendItem,
  CategoryBreakdownItem,
  CategoryOverTimeData,
  CategoryOverTimeItem,
  HighlightsData,
  HighlightMover,
  CategoryDelta,
  CategoryZoomData,
  CategoryZoomChild,
  CategoryZoomEvolutionPoint,
  MonthBalance,
  RecentTransaction,
  CartesSnapshot,
  CartesKpi,
  CartesSparklinePoint,
  CartesTopMover,
  CartesMonthFlow,
  CartesBudgetAdherence,
  CartesBudgetWorstOverrun,
  CartesSeasonality,
  CartesSeasonalityYear,
} from "../shared/types";

export async function getMonthlyTrends(
  dateFrom?: string,
  dateTo?: string,
  sourceId?: number,
): Promise<MonthlyTrendItem[]> {
  const db = await getDb();

  const whereClauses: string[] = [];
  const params: unknown[] = [];
  let paramIndex = 1;

  if (dateFrom) {
    whereClauses.push(`date >= $${paramIndex}`);
    params.push(dateFrom);
    paramIndex++;
  }
  if (dateTo) {
    whereClauses.push(`date <= $${paramIndex}`);
    params.push(dateTo);
    paramIndex++;
  }
  if (sourceId != null) {
    whereClauses.push(`source_id = $${paramIndex}`);
    params.push(sourceId);
    paramIndex++;
  }

  const whereSQL =
    whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";

  return db.select<MonthlyTrendItem[]>(
    `SELECT
       strftime('%Y-%m', date) AS month,
       COALESCE(SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END), 0) AS income,
       ABS(COALESCE(SUM(CASE WHEN amount < 0 THEN amount ELSE 0 END), 0)) AS expenses
     FROM transactions
     ${whereSQL}
     GROUP BY month
     ORDER BY month ASC`,
    params
  );
}

export async function getCategoryOverTime(
  dateFrom?: string,
  dateTo?: string,
  topN: number = 50,
  sourceId?: number,
  typeFilter?: "expense" | "income" | "transfer",
): Promise<CategoryOverTimeData> {
  const db = await getDb();

  const whereClauses: string[] = [];
  const params: unknown[] = [];
  let paramIndex = 1;

  if (typeFilter) {
    whereClauses.push(`COALESCE(c.type, 'expense') = $${paramIndex}`);
    params.push(typeFilter);
    paramIndex++;
  }

  if (dateFrom) {
    whereClauses.push(`t.date >= $${paramIndex}`);
    params.push(dateFrom);
    paramIndex++;
  }
  if (dateTo) {
    whereClauses.push(`t.date <= $${paramIndex}`);
    params.push(dateTo);
    paramIndex++;
  }
  if (sourceId != null) {
    whereClauses.push(`t.source_id = $${paramIndex}`);
    params.push(sourceId);
    paramIndex++;
  }

  const whereSQL = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";

  // Get top N categories by total spend
  const topCategories = await db.select<CategoryBreakdownItem[]>(
    `SELECT
       t.category_id,
       COALESCE(c.name, 'Uncategorized') AS category_name,
       COALESCE(c.color, '#9ca3af') AS category_color,
       ABS(SUM(t.amount)) AS total
     FROM transactions t
     LEFT JOIN categories c ON t.category_id = c.id
     ${whereSQL}
     GROUP BY t.category_id
     ORDER BY total DESC
     LIMIT $${paramIndex}`,
    [...params, topN]
  );

  const topCategoryIds = new Set(topCategories.map((c) => c.category_id));
  const colors: Record<string, string> = {};
  const categoryIds: Record<string, number | null> = {};
  for (const cat of topCategories) {
    colors[cat.category_name] = cat.category_color;
    categoryIds[cat.category_name] = cat.category_id;
  }

  // Get monthly breakdown for all categories
  const monthlyRows = await db.select<
    Array<{
      month: string;
      category_id: number | null;
      category_name: string;
      total: number;
    }>
  >(
    `SELECT
       strftime('%Y-%m', t.date) AS month,
       t.category_id,
       COALESCE(c.name, 'Uncategorized') AS category_name,
       ABS(SUM(t.amount)) AS total
     FROM transactions t
     LEFT JOIN categories c ON t.category_id = c.id
     ${whereSQL}
     GROUP BY month, t.category_id
     ORDER BY month ASC`,
    params
  );

  // Build pivot data
  const monthMap = new Map<string, CategoryOverTimeItem>();
  let hasOther = false;

  for (const row of monthlyRows) {
    if (!monthMap.has(row.month)) {
      monthMap.set(row.month, { month: row.month });
    }
    const item = monthMap.get(row.month)!;

    if (topCategoryIds.has(row.category_id)) {
      item[row.category_name] = ((item[row.category_name] as number) || 0) + row.total;
    } else {
      item["Other"] = ((item["Other"] as number) || 0) + row.total;
      hasOther = true;
    }
  }

  if (hasOther) {
    colors["Other"] = "#9ca3af";
  }

  const categories = topCategories.map((c) => c.category_name);
  if (hasOther) {
    categories.push("Other");
  }

  return {
    categories,
    data: Array.from(monthMap.values()),
    colors,
    categoryIds,
  };
}

// --- Highlights (Issue #71) ---

/**
 * Shifts a YYYY-MM-DD date string by `months` months and returns the first day
 * of the resulting month as YYYY-MM-01. Used to compute the start of the
 * 12-month sparkline window relative to the reference date.
 */
function shiftMonthStart(refIso: string, months: number): string {
  const [y, m] = refIso.split("-").map(Number);
  const d = new Date(Date.UTC(y, m - 1 + months, 1));
  const yy = d.getUTCFullYear();
  const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
  return `${yy}-${mm}-01`;
}

function shiftDate(refIso: string, days: number): string {
  const [y, m, d] = refIso.split("-").map(Number);
  const dt = new Date(Date.UTC(y, m - 1, d + days));
  const yy = dt.getUTCFullYear();
  const mm = String(dt.getUTCMonth() + 1).padStart(2, "0");
  const dd = String(dt.getUTCDate()).padStart(2, "0");
  return `${yy}-${mm}-${dd}`;
}

function monthEnd(yyyyMm: string): string {
  const [y, m] = yyyyMm.split("-").map(Number);
  const d = new Date(Date.UTC(y, m, 0)); // day 0 of next month = last day of this month
  const dd = String(d.getUTCDate()).padStart(2, "0");
  return `${yyyyMm}-${dd}`;
}

/**
 * Returns the dashboard "highlights" snapshot for the reports hub:
 *   - net balance for the reference month
 *   - YTD net balance
 *   - last 12 months of net balances (for sparkline)
 *   - top movers (biggest change in spending vs previous month)
 *   - top transactions (biggest absolute amounts in last `windowDays` days)
 *
 * All SQL is parameterised. `referenceDate` defaults to today and is overridable
 * from tests for deterministic fixtures.
 */
export async function getHighlights(
  windowDays: number = 30,
  referenceDate?: string,
  topMoversLimit: number = 5,
  topTransactionsLimit: number = 10,
): Promise<HighlightsData> {
  const db = await getDb();

  const refIso = referenceDate ?? (() => {
    const t = new Date();
    return `${t.getFullYear()}-${String(t.getMonth() + 1).padStart(2, "0")}-${String(t.getDate()).padStart(2, "0")}`;
  })();
  const currentMonth = refIso.slice(0, 7); // YYYY-MM
  const currentYear = refIso.slice(0, 4);
  const yearStart = `${currentYear}-01-01`;
  const currentMonthStart = `${currentMonth}-01`;
  const currentMonthEnd = monthEnd(currentMonth);
  const previousMonthStart = shiftMonthStart(refIso, -1);
  const previousMonth = previousMonthStart.slice(0, 7);
  const previousMonthEnd = monthEnd(previousMonth);
  const sparklineStart = shiftMonthStart(refIso, -11); // 11 months back + current = 12
  const recentWindowStart = shiftDate(refIso, -(windowDays - 1));

  // 1. Net balance for current month
  const currentBalanceRows = await db.select<Array<{ net: number | null }>>(
    `SELECT COALESCE(SUM(amount), 0) AS net
       FROM transactions
      WHERE date >= $1 AND date <= $2`,
    [currentMonthStart, currentMonthEnd],
  );
  const netBalanceCurrent = Number(currentBalanceRows[0]?.net ?? 0);

  // 2. YTD balance
  const ytdRows = await db.select<Array<{ net: number | null }>>(
    `SELECT COALESCE(SUM(amount), 0) AS net
       FROM transactions
      WHERE date >= $1 AND date <= $2`,
    [yearStart, refIso],
  );
  const netBalanceYtd = Number(ytdRows[0]?.net ?? 0);

  // 3. 12-month sparkline series
  const seriesRows = await db.select<Array<{ month: string; net: number | null }>>(
    `SELECT strftime('%Y-%m', date) AS month, COALESCE(SUM(amount), 0) AS net
       FROM transactions
      WHERE date >= $1 AND date <= $2
      GROUP BY month
      ORDER BY month ASC`,
    [sparklineStart, currentMonthEnd],
  );
  const seriesMap = new Map(seriesRows.map((r) => [r.month, Number(r.net ?? 0)]));
  const monthlyBalanceSeries: MonthBalance[] = [];
  for (let i = 11; i >= 0; i--) {
    const monthKey = shiftMonthStart(refIso, -i).slice(0, 7);
    monthlyBalanceSeries.push({ month: monthKey, netBalance: seriesMap.get(monthKey) ?? 0 });
  }

  // 4. Top movers — expense-side only (amount < 0), compare current vs previous month
  const moversRows = await db.select<
    Array<{
      category_id: number | null;
      category_name: string;
      category_color: string;
      current_total: number | null;
      previous_total: number | null;
    }>
  >(
    `SELECT
        t.category_id,
        COALESCE(c.name, 'Uncategorized') AS category_name,
        COALESCE(c.color, '#9ca3af')      AS category_color,
        COALESCE(SUM(CASE WHEN t.date >= $1 AND t.date <= $2 THEN ABS(t.amount) ELSE 0 END), 0) AS current_total,
        COALESCE(SUM(CASE WHEN t.date >= $3 AND t.date <= $4 THEN ABS(t.amount) ELSE 0 END), 0) AS previous_total
      FROM transactions t
      LEFT JOIN categories c ON t.category_id = c.id
      WHERE t.amount < 0
        AND (
          (t.date >= $1 AND t.date <= $2)
          OR (t.date >= $3 AND t.date <= $4)
        )
      GROUP BY t.category_id, category_name, category_color
      ORDER BY ABS(current_total - previous_total) DESC
      LIMIT $5`,
    [currentMonthStart, currentMonthEnd, previousMonthStart, previousMonthEnd, topMoversLimit],
  );
  const topMovers: HighlightMover[] = moversRows.map((r) => {
    const current = Number(r.current_total ?? 0);
    const previous = Number(r.previous_total ?? 0);
    const deltaAbs = current - previous;
    const deltaPct = previous === 0 ? null : (deltaAbs / previous) * 100;
    // Highlights only exposes a monthly view, so the cumulative block mirrors
    // the monthly values — keeps the CategoryDelta shape uniform for
    // downstream consumers that never read the cumulative block.
    return {
      categoryId: r.category_id,
      categoryName: r.category_name,
      categoryColor: r.category_color,
      previousAmount: previous,
      currentAmount: current,
      deltaAbs,
      deltaPct,
      cumulativePreviousAmount: previous,
      cumulativeCurrentAmount: current,
      cumulativeDeltaAbs: deltaAbs,
      cumulativeDeltaPct: deltaPct,
    };
  });

  // 5. Top transactions within the recent window
  const recentRows = await db.select<RecentTransaction[]>(
    `SELECT
        t.id,
        t.date,
        t.description,
        t.amount,
        c.name  AS category_name,
        c.color AS category_color
       FROM transactions t
       LEFT JOIN categories c ON t.category_id = c.id
      WHERE t.date >= $1 AND t.date <= $2
      ORDER BY ABS(t.amount) DESC
      LIMIT $3`,
    [recentWindowStart, refIso, topTransactionsLimit],
  );

  return {
    currentMonth,
    netBalanceCurrent,
    netBalanceYtd,
    monthlyBalanceSeries,
    topMovers,
    topTransactions: recentRows,
  };
}

// --- Compare (Issue #73) ---

interface RawDeltaRow {
  category_id: number | null;
  category_name: string;
  category_color: string;
  month_current_total: number | null;
  month_previous_total: number | null;
  cumulative_current_total: number | null;
  cumulative_previous_total: number | null;
}

function rowsToDeltas(rows: RawDeltaRow[]): CategoryDelta[] {
  return rows.map((r) => {
    const monthCurrent = Number(r.month_current_total ?? 0);
    const monthPrevious = Number(r.month_previous_total ?? 0);
    const monthDeltaAbs = monthCurrent - monthPrevious;
    const monthDeltaPct = monthPrevious === 0 ? null : (monthDeltaAbs / monthPrevious) * 100;

    const cumCurrent = Number(r.cumulative_current_total ?? 0);
    const cumPrevious = Number(r.cumulative_previous_total ?? 0);
    const cumDeltaAbs = cumCurrent - cumPrevious;
    const cumDeltaPct = cumPrevious === 0 ? null : (cumDeltaAbs / cumPrevious) * 100;

    return {
      categoryId: r.category_id,
      categoryName: r.category_name,
      categoryColor: r.category_color,
      // Monthly block (primary — also the legacy field set).
      previousAmount: monthPrevious,
      currentAmount: monthCurrent,
      deltaAbs: monthDeltaAbs,
      deltaPct: monthDeltaPct,
      // Cumulative YTD block.
      cumulativePreviousAmount: cumPrevious,
      cumulativeCurrentAmount: cumCurrent,
      cumulativeDeltaAbs: cumDeltaAbs,
      cumulativeDeltaPct: cumDeltaPct,
    };
  });
}

function monthBoundaries(year: number, month: number): { start: string; end: string } {
  const mm = String(month).padStart(2, "0");
  const endDate = new Date(Date.UTC(year, month, 0));
  const dd = String(endDate.getUTCDate()).padStart(2, "0");
  return { start: `${year}-${mm}-01`, end: `${year}-${mm}-${dd}` };
}

function previousMonth(year: number, month: number): { year: number; month: number } {
  if (month === 1) return { year: year - 1, month: 12 };
  return { year, month: month - 1 };
}

/**
 * Month-over-month expense delta by category. Returns both a monthly view
 * (reference month vs immediately-previous month) and a cumulative YTD view
 * (Jan→refMonth of refYear vs Jan→prevMonth of refYear — i.e. "cumulative
 * progress through end of last month" vs "cumulative progress through end of
 * this month"). All SQL parameterised.
 */
export async function getCompareMonthOverMonth(
  year: number,
  month: number,
): Promise<CategoryDelta[]> {
  const db = await getDb();
  const { start: curStart, end: curEnd } = monthBoundaries(year, month);
  const prev = previousMonth(year, month);
  const { start: prevStart, end: prevEnd } = monthBoundaries(prev.year, prev.month);

  // Cumulative window: from Jan 1st of the reference year up to the end of
  // the month we care about. For MoM, the "previous" cumulative window ends
  // at the end of the previous month within the SAME year — so Jan only has
  // no cumulative-previous (empty window). We still bound the previous-year
  // handling: when month === 1 the previous month is in year - 1, so the
  // cumulative-previous window sits entirely in year - 1 (Jan → Dec).
  const cumCurrentStart = `${year}-01-01`;
  const cumCurrentEnd = curEnd;
  const cumPreviousStart = `${prev.year}-01-01`;
  const cumPreviousEnd = prevEnd;

  const rows = await db.select<RawDeltaRow[]>(
    `SELECT
        t.category_id,
        COALESCE(c.name, 'Uncategorized') AS category_name,
        COALESCE(c.color, '#9ca3af')      AS category_color,
        COALESCE(SUM(CASE WHEN t.date >= $1 AND t.date <= $2 THEN ABS(t.amount) ELSE 0 END), 0) AS month_current_total,
        COALESCE(SUM(CASE WHEN t.date >= $3 AND t.date <= $4 THEN ABS(t.amount) ELSE 0 END), 0) AS month_previous_total,
        COALESCE(SUM(CASE WHEN t.date >= $5 AND t.date <= $6 THEN ABS(t.amount) ELSE 0 END), 0) AS cumulative_current_total,
        COALESCE(SUM(CASE WHEN t.date >= $7 AND t.date <= $8 THEN ABS(t.amount) ELSE 0 END), 0) AS cumulative_previous_total
      FROM transactions t
      LEFT JOIN categories c ON t.category_id = c.id
      WHERE t.amount < 0
        AND (
          (t.date >= $1 AND t.date <= $2)
          OR (t.date >= $3 AND t.date <= $4)
          OR (t.date >= $5 AND t.date <= $6)
          OR (t.date >= $7 AND t.date <= $8)
        )
      GROUP BY t.category_id, category_name, category_color
      ORDER BY ABS(month_current_total - month_previous_total) DESC`,
    [
      curStart, curEnd,
      prevStart, prevEnd,
      cumCurrentStart, cumCurrentEnd,
      cumPreviousStart, cumPreviousEnd,
    ],
  );
  return rowsToDeltas(rows);
}

/**
 * Year-over-year expense delta by category. Returns both a monthly view
 * (reference month vs same month of the previous year) and a cumulative YTD
 * view (Jan→refMonth of refYear vs Jan→refMonth of refYear - 1). Uses the
 * reference year's December as the "current month" when no explicit
 * reference month is provided; callers typically pass the user's chosen
 * reference month. All SQL parameterised.
 */
export async function getCompareYearOverYear(
  year: number,
  month: number = 12,
): Promise<CategoryDelta[]> {
  const db = await getDb();
  const { start: curMonthStart, end: curMonthEnd } = monthBoundaries(year, month);
  const { start: prevMonthStart, end: prevMonthEnd } = monthBoundaries(year - 1, month);

  const cumCurrentStart = `${year}-01-01`;
  const cumCurrentEnd = curMonthEnd;
  const cumPreviousStart = `${year - 1}-01-01`;
  const cumPreviousEnd = prevMonthEnd;

  const rows = await db.select<RawDeltaRow[]>(
    `SELECT
        t.category_id,
        COALESCE(c.name, 'Uncategorized') AS category_name,
        COALESCE(c.color, '#9ca3af')      AS category_color,
        COALESCE(SUM(CASE WHEN t.date >= $1 AND t.date <= $2 THEN ABS(t.amount) ELSE 0 END), 0) AS month_current_total,
        COALESCE(SUM(CASE WHEN t.date >= $3 AND t.date <= $4 THEN ABS(t.amount) ELSE 0 END), 0) AS month_previous_total,
        COALESCE(SUM(CASE WHEN t.date >= $5 AND t.date <= $6 THEN ABS(t.amount) ELSE 0 END), 0) AS cumulative_current_total,
        COALESCE(SUM(CASE WHEN t.date >= $7 AND t.date <= $8 THEN ABS(t.amount) ELSE 0 END), 0) AS cumulative_previous_total
      FROM transactions t
      LEFT JOIN categories c ON t.category_id = c.id
      WHERE t.amount < 0
        AND (
          (t.date >= $1 AND t.date <= $2)
          OR (t.date >= $3 AND t.date <= $4)
          OR (t.date >= $5 AND t.date <= $6)
          OR (t.date >= $7 AND t.date <= $8)
        )
      GROUP BY t.category_id, category_name, category_color
      ORDER BY ABS(month_current_total - month_previous_total) DESC`,
    [
      curMonthStart, curMonthEnd,
      prevMonthStart, prevMonthEnd,
      cumCurrentStart, cumCurrentEnd,
      cumPreviousStart, cumPreviousEnd,
    ],
  );
  return rowsToDeltas(rows);
}

// --- Category zoom (Issue #74) ---

/**
 * Recursive CTE fragment bounded to `depth < 5` so a corrupted `parent_id`
 * loop (A → B → A) can never spin forever. The depth budget is intentionally
 * low: real category trees rarely exceed 3 levels.
 */
const CATEGORY_TREE_CTE = `
  WITH RECURSIVE cat_tree(id, depth) AS (
    SELECT id, 0 FROM categories WHERE id = $1
    UNION ALL
    SELECT c.id, ct.depth + 1
      FROM categories c
      JOIN cat_tree ct ON c.parent_id = ct.id
     WHERE ct.depth < 5
  )
`;

/**
 * Returns the zoom-on-category report for the given category id.
 *
 * When `includeSubcategories` is true the recursive CTE walks down the
 * category tree (capped at 5 levels) and aggregates matching rows. When
 * false, only direct transactions on `categoryId` are considered. Every
 * query is parameterised; the category id is never interpolated.
 */
export async function getCategoryZoom(
  categoryId: number,
  dateFrom: string,
  dateTo: string,
  includeSubcategories: boolean = true,
): Promise<CategoryZoomData> {
  const db = await getDb();

  const categoryFilter = includeSubcategories
    ? `${CATEGORY_TREE_CTE}
       SELECT t.id, t.date, t.description, t.amount, t.category_id
         FROM transactions t
        WHERE t.category_id IN (SELECT id FROM cat_tree)
          AND t.date >= $2 AND t.date <= $3`
    : `SELECT t.id, t.date, t.description, t.amount, t.category_id
         FROM transactions t
        WHERE t.category_id = $1
          AND t.date >= $2 AND t.date <= $3`;

  // 1. Transactions (with join for display)
  const txRows = await db.select<RecentTransaction[]>(
    `${includeSubcategories ? CATEGORY_TREE_CTE : ""}
     SELECT t.id, t.date, t.description, t.amount, c.name AS category_name, c.color AS category_color
       FROM transactions t
       LEFT JOIN categories c ON t.category_id = c.id
      WHERE ${includeSubcategories
        ? "t.category_id IN (SELECT id FROM cat_tree)"
        : "t.category_id = $1"}
        AND t.date >= $2 AND t.date <= $3
      ORDER BY ABS(t.amount) DESC
      LIMIT 500`,
    [categoryId, dateFrom, dateTo],
  );

  // 2. Rollup total (sum of absolute amounts of matching rows)
  const totalRows = await db.select<Array<{ rollup: number | null }>>(
    `${categoryFilter.replace("SELECT t.id, t.date, t.description, t.amount, t.category_id", "SELECT COALESCE(SUM(ABS(t.amount)), 0) AS rollup")}`,
    [categoryId, dateFrom, dateTo],
  );
  const rollupTotal = Number(totalRows[0]?.rollup ?? 0);

  // 3. Breakdown by direct child (only meaningful when includeSubcategories is true)
  const byChild: CategoryZoomChild[] = [];
  if (includeSubcategories) {
    const childRows = await db.select<
      Array<{ child_id: number; child_name: string; child_color: string; total: number | null }>
    >(
      `SELECT child.id AS child_id,
              child.name AS child_name,
              COALESCE(child.color, '#9ca3af') AS child_color,
              COALESCE(SUM(ABS(t.amount)), 0) AS total
         FROM categories child
         LEFT JOIN transactions t ON t.category_id = child.id
          AND t.date >= $2 AND t.date <= $3
        WHERE child.parent_id = $1
        GROUP BY child.id, child.name, child.color
        ORDER BY total DESC`,
      [categoryId, dateFrom, dateTo],
    );
    for (const r of childRows) {
      byChild.push({
        categoryId: r.child_id,
        categoryName: r.child_name,
        categoryColor: r.child_color,
        total: Number(r.total ?? 0),
      });
    }
  }

  // 4. Monthly evolution across the window
  const evolutionRows = await db.select<Array<{ month: string; total: number | null }>>(
    `${includeSubcategories ? CATEGORY_TREE_CTE : ""}
     SELECT strftime('%Y-%m', t.date) AS month,
            COALESCE(SUM(ABS(t.amount)), 0) AS total
       FROM transactions t
      WHERE ${includeSubcategories
        ? "t.category_id IN (SELECT id FROM cat_tree)"
        : "t.category_id = $1"}
        AND t.date >= $2 AND t.date <= $3
      GROUP BY month
      ORDER BY month ASC`,
    [categoryId, dateFrom, dateTo],
  );
  const monthlyEvolution: CategoryZoomEvolutionPoint[] = evolutionRows.map((r) => ({
    month: r.month,
    total: Number(r.total ?? 0),
  }));

  return {
    rollupTotal,
    byChild,
    monthlyEvolution,
    transactions: txRows,
  };
}

// --- Cartes dashboard (Issue #97) ---

/**
 * Signed month shift. Exported for unit tests.
 *   shiftMonth(2026, 1, -1) -> { year: 2025, month: 12 }
 *   shiftMonth(2026, 4, -24) -> { year: 2024, month: 4 }
 */
export function shiftMonth(
  year: number,
  month: number,
  offset: number,
): { year: number; month: number } {
  const total = year * 12 + (month - 1) + offset;
  return {
    year: Math.floor(total / 12),
    month: (total % 12) + 1,
  };
}

function monthKey(year: number, month: number): string {
  return `${year}-${String(month).padStart(2, "0")}`;
}

function extractDelta(
  current: number | null,
  previous: number | null,
): { abs: number | null; pct: number | null } {
  if (current === null || previous === null) return { abs: null, pct: null };
  const abs = current - previous;
  const pct = previous === 0 ? null : (abs / previous) * 100;
  return { abs, pct };
}

function buildKpi(
  sparkline: CartesSparklinePoint[],
  current: number | null,
  previousMonth: number | null,
  previousYear: number | null,
): CartesKpi {
  const mom = extractDelta(current, previousMonth);
  const yoy = extractDelta(current, previousYear);
  return {
    current,
    previousMonth,
    previousYear,
    deltaMoMAbs: mom.abs,
    deltaMoMPct: mom.pct,
    deltaYoYAbs: yoy.abs,
    deltaYoYPct: yoy.pct,
    sparkline,
  };
}

interface RawMonthFlow {
  month: string;
  income: number | null;
  expenses: number | null;
}

async function fetchMonthlyFlows(
  dateFrom: string,
  dateTo: string,
): Promise<RawMonthFlow[]> {
  const db = await getDb();
  return db.select<RawMonthFlow[]>(
    `SELECT
        strftime('%Y-%m', date) AS month,
        COALESCE(SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END), 0) AS income,
        ABS(COALESCE(SUM(CASE WHEN amount < 0 THEN amount ELSE 0 END), 0)) AS expenses
      FROM transactions
      WHERE date >= $1 AND date <= $2
      GROUP BY month
      ORDER BY month ASC`,
    [dateFrom, dateTo],
  );
}

interface RawSeasonalityRow {
  year: number;
  amount: number | null;
}

async function fetchSeasonality(
  month: number,
  yearFrom: number,
  yearTo: number,
): Promise<RawSeasonalityRow[]> {
  const db = await getDb();
  const mm = String(month).padStart(2, "0");
  return db.select<RawSeasonalityRow[]>(
    `SELECT
        CAST(strftime('%Y', date) AS INTEGER) AS year,
        ABS(COALESCE(SUM(CASE WHEN amount < 0 THEN amount ELSE 0 END), 0)) AS amount
      FROM transactions
      WHERE strftime('%m', date) = $1
        AND CAST(strftime('%Y', date) AS INTEGER) >= $2
        AND CAST(strftime('%Y', date) AS INTEGER) <= $3
      GROUP BY year
      ORDER BY year DESC`,
    [mm, yearFrom, yearTo],
  );
}

/**
 * Cartes dashboard snapshot. Single entry point that returns every widget's
 * data for the Cartes report, computed against a reference (year, month).
 *
 * Layout (all concurrent):
 *   1. 25-month expense/income series (covers ref, MoM, YoY, 12-month flow,
 *      13-month sparklines without any extra round trips).
 *   2. Month-over-month category deltas for top movers (existing service).
 *   3. Year-over-year category deltas to seed the savings-rate YoY lookup
 *      via the monthly series instead of re-querying.
 *   4. Budget vs actual for the reference month.
 *   5. Seasonality: same calendar month across the two prior years.
 */
export async function getCartesSnapshot(
  referenceYear: number,
  referenceMonth: number,
): Promise<CartesSnapshot> {
  // Date window: 25 months back from the reference to cover YoY + a 13-month
  // sparkline. Start = 24 months before ref = (ref - 24 months) = month offset -24.
  const windowStart = shiftMonth(referenceYear, referenceMonth, -24);
  const { start: windowStartIso } = monthBoundaries(windowStart.year, windowStart.month);
  const { end: refEnd } = monthBoundaries(referenceYear, referenceMonth);

  // Seasonality range: previous 2 years for the same calendar month.
  const [seasonalityRows, flowRows, momRows, budgetRows] = await Promise.all([
    fetchSeasonality(referenceMonth, referenceYear - 2, referenceYear - 1),
    fetchMonthlyFlows(windowStartIso, refEnd),
    getCompareMonthOverMonth(referenceYear, referenceMonth),
    getBudgetVsActualData(referenceYear, referenceMonth),
  ]);

  // Index the flow rows by month for O(1) lookup, then fill missing months
  // with zeroes so downstream consumers get a contiguous series.
  const flowByMonth = new Map<string, { income: number; expenses: number }>();
  for (const r of flowRows) {
    flowByMonth.set(r.month, {
      income: Number(r.income ?? 0),
      expenses: Number(r.expenses ?? 0),
    });
  }

  const buildSeries = (count: number): CartesMonthFlow[] => {
    const series: CartesMonthFlow[] = [];
    for (let i = count - 1; i >= 0; i--) {
      const { year: y, month: m } = shiftMonth(referenceYear, referenceMonth, -i);
      const key = monthKey(y, m);
      const row = flowByMonth.get(key);
      const income = row?.income ?? 0;
      const expenses = row?.expenses ?? 0;
      series.push({ month: key, income, expenses, net: income - expenses });
    }
    return series;
  };

  // 13-month sparklines for each KPI (reference month + 12 prior).
  const sparkSeries = buildSeries(13);
  const incomeSpark: CartesSparklinePoint[] = sparkSeries.map((p) => ({
    month: p.month,
    value: p.income,
  }));
  const expensesSpark: CartesSparklinePoint[] = sparkSeries.map((p) => ({
    month: p.month,
    value: p.expenses,
  }));
  const netSpark: CartesSparklinePoint[] = sparkSeries.map((p) => ({
    month: p.month,
    value: p.net,
  }));
  const savingsSpark: CartesSparklinePoint[] = sparkSeries.map((p) => ({
    month: p.month,
    value: p.income > 0 ? (p.net / p.income) * 100 : 0,
  }));

  // Compute MoM / YoY values directly from `flowByMonth` (which preserves the
  // "missing" distinction). The sparkline fills gaps with zero for display,
  // but deltas must remain null when the comparison month has no data.
  const refKey = monthKey(referenceYear, referenceMonth);
  const momMeta = shiftMonth(referenceYear, referenceMonth, -1);
  const momKey = monthKey(momMeta.year, momMeta.month);
  const yoyMeta = { year: referenceYear - 1, month: referenceMonth };
  const yoyKey = monthKey(yoyMeta.year, yoyMeta.month);

  const refRow = flowByMonth.get(refKey);
  const refIncome = refRow?.income ?? 0;
  const refExpenses = refRow?.expenses ?? 0;
  const refNet = refIncome - refExpenses;
  // Savings rate is undefined when income is zero — expose as null rather than
  // rendering a misleading "0 %" in the UI.
  const refSavings = refIncome > 0 ? (refNet / refIncome) * 100 : null;

  const momRow = flowByMonth.get(momKey);
  const momIncome = momRow ? momRow.income : null;
  const momExpenses = momRow ? momRow.expenses : null;
  const momNet = momRow ? momRow.income - momRow.expenses : null;
  const momSavings =
    momRow && momRow.income > 0 ? ((momRow.income - momRow.expenses) / momRow.income) * 100 : null;

  const yoyRow = flowByMonth.get(yoyKey);
  const yoyIncome = yoyRow ? yoyRow.income : null;
  const yoyExpenses = yoyRow ? yoyRow.expenses : null;
  const yoyNet = yoyRow ? yoyRow.income - yoyRow.expenses : null;
  const yoySavings =
    yoyRow && yoyRow.income > 0 ? ((yoyRow.income - yoyRow.expenses) / yoyRow.income) * 100 : null;

  const incomeKpi = buildKpi(incomeSpark, refIncome, momIncome, yoyIncome);
  const expensesKpi = buildKpi(expensesSpark, refExpenses, momExpenses, yoyExpenses);
  const netKpi = buildKpi(netSpark, refNet, momNet, yoyNet);
  const savingsKpi = buildKpi(savingsSpark, refSavings, momSavings, yoySavings);

  // 12-month income vs expenses series for the overlay chart.
  const flow12Months = buildSeries(12);

  // Top movers: biggest MoM increases / decreases. `momRows` are sorted by
  // absolute delta already; filter out near-zero noise and split by sign.
  const significantMovers = momRows.filter(
    (r) => r.deltaAbs !== 0 && (r.previousAmount > 0 || r.currentAmount > 0),
  );
  // Project the richer CategoryDelta shape down to the narrower CartesTopMover
  // shape so the Cartes dashboard keeps its stable contract regardless of how
  // many views (monthly / cumulative) the Compare service exposes.
  const toCartesMover = (r: CategoryDelta): CartesTopMover => ({
    categoryId: r.categoryId,
    categoryName: r.categoryName,
    categoryColor: r.categoryColor,
    previousAmount: r.previousAmount,
    currentAmount: r.currentAmount,
    deltaAbs: r.deltaAbs,
    deltaPct: r.deltaPct,
  });
  const topMoversUp: CartesTopMover[] = significantMovers
    .filter((r) => r.deltaAbs > 0)
    .sort((a, b) => b.deltaAbs - a.deltaAbs)
    .slice(0, 5)
    .map(toCartesMover);
  const topMoversDown: CartesTopMover[] = significantMovers
    .filter((r) => r.deltaAbs < 0)
    .sort((a, b) => a.deltaAbs - b.deltaAbs)
    .slice(0, 5)
    .map(toCartesMover);

  // Budget adherence — only expense categories with a non-zero budget count.
  // monthActual is signed from transactions; expense categories have
  // monthActual <= 0, so we compare on absolute values.
  const budgetedExpenseRows = budgetRows.filter(
    (r) => r.category_type === "expense" && r.monthBudget > 0 && !r.is_parent,
  );
  const budgetsInTarget = budgetedExpenseRows.filter(
    (r) => Math.abs(r.monthActual) <= r.monthBudget,
  ).length;

  const overruns: CartesBudgetWorstOverrun[] = budgetedExpenseRows
    .map((r) => {
      const actual = Math.abs(r.monthActual);
      const overrunAbs = actual - r.monthBudget;
      const overrunPct = r.monthBudget > 0 ? (overrunAbs / r.monthBudget) * 100 : null;
      return {
        categoryId: r.category_id,
        categoryName: r.category_name,
        categoryColor: r.category_color,
        budget: r.monthBudget,
        actual,
        overrunAbs,
        overrunPct,
      };
    })
    .filter((r) => r.overrunAbs > 0)
    .sort((a, b) => b.overrunAbs - a.overrunAbs)
    .slice(0, 3);

  const budgetAdherence: CartesBudgetAdherence = {
    categoriesInTarget: budgetsInTarget,
    categoriesTotal: budgetedExpenseRows.length,
    worstOverruns: overruns,
  };

  // Seasonality — average of the same calendar month across the previous
  // two years. If no data, average stays null.
  const historicalYears: CartesSeasonalityYear[] = seasonalityRows.map((r) => ({
    year: Number(r.year),
    amount: Number(r.amount ?? 0),
  }));
  const historicalAverage = historicalYears.length
    ? historicalYears.reduce((sum, r) => sum + r.amount, 0) / historicalYears.length
    : null;
  // `refExpenses` is always a concrete number (never null) — unlike
  // `savingsKpi.current` which is nullable when income is zero.
  const referenceAmount = refExpenses;
  const deviationPct =
    historicalAverage !== null && historicalAverage > 0
      ? ((referenceAmount - historicalAverage) / historicalAverage) * 100
      : null;

  const seasonality: CartesSeasonality = {
    referenceAmount,
    historicalYears,
    historicalAverage,
    deviationPct,
  };

  return {
    referenceYear,
    referenceMonth,
    kpis: {
      income: incomeKpi,
      expenses: expensesKpi,
      net: netKpi,
      savingsRate: savingsKpi,
    },
    flow12Months,
    topMoversUp,
    topMoversDown,
    budgetAdherence,
    seasonality,
  };
}