Add POST /api/semantic-diff endpoint for AI-powered code change explanations

Uses Anthropic claude-sonnet-4-6 server-side to explain the semantic meaning of code diffs in the budget app domain (paychecks, bills, financing, actuals). Input validation rejects empty or oversized (>50KB) diffs. Tests mock the Anthropic client via direct method replacement (same pattern as db.pool.query). Nightshift-Task: semantic-diff Nightshift-Ref: https://github.com/marcus/nightshift
2026-03-20 01:53:45 -04:00
20 changed files with 295 additions and 309 deletions
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -24,22 +24,7 @@
      "Bash(npm run:*)",
      "Bash(/home/christian/.nvm/versions/node/v24.14.0/bin/npm run:*)",
      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npm run build 2>&1)",
-      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npx vite build 2>&1)",
-      "Bash(sqlite3 /home/christian/projects/budget/.todos/issues.db \"PRAGMA integrity_check;\")",
-      "Bash(td usage:*)",
-      "Bash(ls:*)",
-      "Bash(sudo chown:*)",
-      "Bash(td add:*)",
-      "Bash(td log:*)",
-      "Bash(git:*)",
-      "Bash(npm list:*)",
-      "Bash(td accept:*)",
-      "Bash(/home/christian/.nvm/versions/node/v24.14.0/bin/npm test:*)",
-      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npm test)",
-      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npm --prefix /home/christian/projects/budget/server test 2>&1)",
-      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npm --prefix /home/christian/projects/budget/client test 2>&1)",
-      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npm --prefix /home/christian/projects/budget/client test)",
-      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npm --prefix /home/christian/projects/budget/client test -- --reporter=verbose)"
+      "Bash(PATH=\"/home/christian/.nvm/versions/node/v24.14.0/bin:$PATH\" npx vite build 2>&1)"
    ]
  }
 }
--- a/.gitignore
+++ b/.gitignore
@@ -41,5 +41,3 @@ Thumbs.db

 # Coverage
 coverage/
-# Nightshift plan artifacts (keep out of version control)
-.nightshift-plan
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,8 +77,6 @@ cd client && npm run test:watch
 - Export pure functions (validators, formatters, etc.) for direct testing
 - Run `npm test` in both `server/` and `client/` before committing

-**Callback prop naming convention:** React callback props follow `on[Noun][Verb]` (e.g., `onBillPaidToggle`, `onPaycheckAmountSave`, `onPaycheckGenerate`). Event handler functions in the parent component use the `handle[Action]` prefix (e.g., `handleAmountSave`, `handleBillPaidToggle`).
-
 ## Application Structure

 The default route `/` renders the paycheck-centric main view (`client/src/pages/PaycheckView.jsx`). It shows the current month's two paychecks side-by-side with bills, paid status, one-time expenses, and remaining balance. Month navigation (prev/next) fetches data via `GET /api/paychecks?year=&month=`.
@@ -97,86 +95,4 @@ The default route `/` renders the paycheck-centric main view (`client/src/pages/

 **Migrations:** SQL files in `db/migrations/` are applied in filename order on server startup. Add new migrations as `00N_description.sql` — they run once and are tracked in the `migrations` table.

-## Database Schema
-
-Full DDL lives in `db/migrations/`. Key tables:
-
-| Table | Description |
-|---|---|
-| `config` | Key/value store for app settings (paycheck days, gross/net amounts). |
-| `bills` | Bill definitions: name, amount, due day, assigned paycheck, category, active flag. |
-| `paychecks` | One row per paycheck per period (year + month + paycheck_number 1 or 2). |
-| `paycheck_bills` | Junction between a paycheck instance and its bills; tracks paid status and amount_override. |
-| `one_time_expenses` | Ad-hoc expenses attached to a specific paycheck instance. |
-| `financing_plans` | Financing plans: total amount, due date, start_date, optional assigned_paycheck. |
-| `financing_payments` | One payment record per plan per paycheck; tracks paid status. |
-| `expense_categories` | Lookup table for variable-expense categories (Groceries, Gas, Dining, …). |
-| `actuals` | Actual spending log entries linked to a paycheck, category, or bill. |
-| `migrations` | Internal table tracking which migration files have been applied. |
-
-## API Endpoints
-
-All routes are prefixed with `/api`.
-
-### Paychecks
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/paychecks?year=&month=` | Return both paychecks for a month. Returns virtual data (id: null) when no DB record exists. |
-| `POST` | `/paychecks/generate?year=&month=` | Upsert paycheck records and sync bills/financing for the month. |
-| `GET` | `/paychecks/months` | List all months that have generated paycheck records, newest first. |
-| `PATCH` | `/paychecks/:id` | Update gross and net for a specific paycheck. |
-| `PATCH` | `/paycheck-bills/:id/paid` | Toggle paid status; locks amount_override on pay. |
-| `PATCH` | `/paycheck-bills/:id/amount` | Set amount_override for a variable-amount bill. |
-
-### Bills
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/bills` | List all bills ordered by assigned_paycheck, name. |
-| `POST` | `/bills` | Create a bill. |
-| `GET` | `/bills/:id` | Fetch a single bill. |
-| `PUT` | `/bills/:id` | Replace a bill's fields. |
-| `DELETE` | `/bills/:id` | Hard-delete a bill. |
-| `PATCH` | `/bills/:id/toggle` | Toggle the active flag. |
-
-### Config
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/config` | Return all config values as a flat object with numeric values. |
-| `PUT` | `/config` | Upsert one or more config keys. Unknown keys are silently ignored. |
-
-### One-Time Expenses
-| Method | Path | Description |
-|---|---|---|
-| `POST` | `/one-time-expenses` | Add a one-time expense to a paycheck. |
-| `DELETE` | `/one-time-expenses/:id` | Remove a one-time expense. |
-| `PATCH` | `/one-time-expenses/:id/paid` | Toggle paid status. |
-
-### Financing
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/financing` | List all financing plans with enriched progress fields. |
-| `POST` | `/financing` | Create a financing plan. |
-| `GET` | `/financing/:id` | Fetch a plan with its full payment history. |
-| `PUT` | `/financing/:id` | Update a financing plan. |
-| `DELETE` | `/financing/:id` | Delete a financing plan and its payments. |
-| `PATCH` | `/financing-payments/:id/paid` | Toggle a payment's paid status; auto-closes the plan when fully paid. |
-
-### Actuals & Categories
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/expense-categories` | List all expense categories. |
-| `POST` | `/expense-categories` | Create a new expense category. |
-| `GET` | `/actuals?paycheckId=` | List actual spending entries for a paycheck. |
-| `POST` | `/actuals` | Log an actual spending entry. |
-| `DELETE` | `/actuals/:id` | Remove an actual spending entry. |
-
-### Summary
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/summary/monthly?year=&month=` | Spending breakdown and category totals for a single month. |
-| `GET` | `/summary/annual?year=` | Income vs. spending, surplus/deficit trend, and stacked variable spending for a full year. |
-
-### Health
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/health` | Returns `{ ok: true }`. Used by Docker healthcheck. |
+**Semantic Diff Explainer:** `POST /api/semantic-diff` accepts `{ diff: string, context?: string }` and returns `{ explanation: string }`. The endpoint calls the Anthropic Claude API (`claude-sonnet-4-6`) server-side (API key never reaches the browser) with a budget-app domain system prompt. Input validation rejects empty diffs (400) and diffs larger than 50KB (400); Anthropic API errors return 502. Requires `ANTHROPIC_API_KEY` in the server environment. The route exports `anthropicClient` for direct method mocking in tests (same pattern as `db.pool.query`).
--- a/client/src/ThemeContext.jsx
+++ b/client/src/ThemeContext.jsx
@@ -2,18 +2,6 @@ import { createContext, useContext, useEffect, useState } from 'react';

 const ThemeContext = createContext(null);

-/**
- * Provides light/dark theme state to the component tree.
- *
- * On mount, the active theme is read from `localStorage`; if absent it
- * falls back to the OS `prefers-color-scheme` media query. The chosen
- * theme is applied as a `data-theme` attribute on `<html>` and persisted
- * to `localStorage` whenever it changes.
- *
- * Exposes `{ theme, toggle }` via {@link useTheme}.
- *
- * @param {{ children: React.ReactNode }} props
- */
 export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState(() => {
    const stored = localStorage.getItem('theme');
@@ -37,13 +25,6 @@ export function ThemeProvider({ children }) {
  );
 }

-/**
- * Returns the current theme context provided by {@link ThemeProvider}.
- *
- * @returns {{ theme: 'light'|'dark', toggle: () => void }}
- *   - `theme`  — the active color scheme name
- *   - `toggle` — flips between `'light'` and `'dark'`
- */
 export function useTheme() {
  return useContext(ThemeContext);
 }
--- a/client/src/pages/AnnualOverview.jsx
+++ b/client/src/pages/AnnualOverview.jsx
@@ -3,10 +3,32 @@ import {
  BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, Legend,
  Cell, ResponsiveContainer, ReferenceLine,
 } from 'recharts';
-import { MONTH_NAMES, PALETTE, fmt, formatCurrencyShort } from '../utils/formatting.js';
+
+const MONTH_NAMES = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];

 const MONTH_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

+const PALETTE = ['#3b82f6', '#8b5cf6', '#ec4899', '#f97316', '#22c55e', '#14b8a6', '#eab308', '#64748b'];
+
+function fmt(value) {
+  if (value == null) return '—';
+  const num = Number(value);
+  if (isNaN(num)) return '—';
+  const abs = Math.abs(num).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+  return num < 0 ? `-$${abs}` : `$${abs}`;
+}
+
+function formatCurrencyShort(value) {
+  if (value == null || isNaN(value)) return '';
+  const abs = Math.abs(value);
+  const sign = value < 0 ? '-' : '';
+  if (abs >= 1000) return `${sign}$${(abs / 1000).toFixed(1)}k`;
+  return `${sign}$${abs.toFixed(0)}`;
+}
+
 function surplusClass(value) {
  if (value == null || isNaN(Number(value))) return '';
  return Number(value) >= 0 ? 'text-success' : 'text-danger';
--- a/client/src/pages/Bills.jsx
+++ b/client/src/pages/Bills.jsx
@@ -1,5 +1,4 @@
 import { useState, useEffect } from 'react';
-import { formatCurrency, ordinal } from '../utils/formatting.js';

 const CATEGORIES = [
  'Housing', 'Utilities', 'Subscriptions', 'Insurance',
@@ -15,6 +14,19 @@ const EMPTY_FORM = {
  variable_amount: false,
 };

+function formatCurrency(value) {
+  const num = parseFloat(value);
+  if (isNaN(num)) return '$0.00';
+  return num.toLocaleString('en-US', { style: 'currency', currency: 'USD' });
+}
+
+function ordinal(n) {
+  const int = parseInt(n, 10);
+  if (isNaN(int)) return n;
+  const suffix = ['th', 'st', 'nd', 'rd'];
+  const v = int % 100;
+  return int + (suffix[(v - 20) % 10] || suffix[v] || suffix[0]);
+}

 function Bills() {
  const [bills, setBills] = useState([]);
--- a/client/src/pages/Financing.jsx
+++ b/client/src/pages/Financing.jsx
@@ -1,5 +1,9 @@
 import { useState, useEffect } from 'react';
-import { fmt } from '../utils/formatting.js';
+
+function fmt(value) {
+  const num = parseFloat(value) || 0;
+  return '$' + num.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}

 function ProgressBar({ paid, total }) {
  const pct = total > 0 ? Math.min(100, (paid / total) * 100) : 0;
--- a/client/src/pages/MonthlySummary.jsx
+++ b/client/src/pages/MonthlySummary.jsx
@@ -3,7 +3,25 @@ import {
  PieChart, Pie, Cell, Tooltip, Legend, ResponsiveContainer,
  BarChart, Bar, XAxis, YAxis, CartesianGrid,
 } from 'recharts';
-import { MONTH_NAMES, PALETTE, formatCurrency, formatCurrencyShort } from '../utils/formatting.js';
+
+const MONTH_NAMES = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];
+
+function formatCurrency(value) {
+  const num = parseFloat(value) || 0;
+  return '$' + num.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+
+function formatCurrencyShort(value) {
+  const num = parseFloat(value) || 0;
+  if (Math.abs(num) >= 1000) return '$' + (num / 1000).toFixed(1) + 'k';
+  return '$' + num.toFixed(0);
+}
+
+// Accessible palette that works in light and dark
+const PALETTE = ['#3b82f6', '#8b5cf6', '#ec4899', '#f97316', '#22c55e', '#14b8a6', '#eab308', '#64748b'];

 function StatCard({ label, value, valueClass }) {
  return (
--- a/client/src/pages/PaycheckView.jsx
+++ b/client/src/pages/PaycheckView.jsx
@@ -1,5 +1,20 @@
 import { useState, useEffect } from 'react';
-import { MONTH_NAMES, formatCurrency, ordinal } from '../utils/formatting.js';
+
+const MONTH_NAMES = [
+  'January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December',
+];
+
+function ordinal(n) {
+  const s = ['th', 'st', 'nd', 'rd'];
+  const v = n % 100;
+  return n + (s[(v - 20) % 10] || s[v] || s[0]);
+}
+
+function formatCurrency(value) {
+  const num = parseFloat(value) || 0;
+  return '$' + num.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}

 function formatPayDate(dateStr) {
  const [year, month, day] = dateStr.split('-').map(Number);
@@ -14,7 +29,7 @@ export { ordinal, formatCurrency, formatPayDate };

 // ─── PaycheckColumn ───────────────────────────────────────────────────────────

-function PaycheckColumn({ paycheck, onBillPaidToggle, categories, onOtePaidToggle, onOteDelete, onOteAdd, onPaycheckGenerate, onPaycheckAmountSave, onBillAmountSave, onFinancingPaidToggle }) {
+function PaycheckColumn({ paycheck, onBillPaidToggle, categories, onOtePaidToggle, onOteDelete, onOteAdd, onGenerate, onAmountSave, onBillAmountSave, onFinancingPaidToggle }) {
  const [newOteName, setNewOteName] = useState('');
  const [newOteAmount, setNewOteAmount] = useState('');
  const [actuals, setActuals] = useState([]);
@@ -80,7 +95,7 @@ function PaycheckColumn({ paycheck, onBillPaidToggle, categories, onOtePaidToggl
      // Lazy generate if this is a virtual paycheck
      let paycheckId = paycheck.id;
      if (!paycheckId) {
-        const generated = await onPaycheckGenerate();
+        const generated = await onGenerate();
        paycheckId = generated.find(p => p.paycheck_number === paycheck.paycheck_number).id;
      }

@@ -136,7 +151,7 @@ function PaycheckColumn({ paycheck, onBillPaidToggle, categories, onOtePaidToggl
    setAmountSaving(true);
    setAmountError(null);
    try {
-      await onPaycheckAmountSave(paycheck.paycheck_number, parseFloat(editGross) || 0, parseFloat(editNet) || 0);
+      await onAmountSave(paycheck.paycheck_number, parseFloat(editGross) || 0, parseFloat(editNet) || 0);
      setEditingAmounts(false);
    } catch (err) {
      setAmountError(err.message);
@@ -740,8 +755,8 @@ function PaycheckView() {
            onOteDelete={handleOteDelete}
            onOteAdd={handleOteAdd}
            categories={categories}
-            onPaycheckGenerate={generateMonth}
-            onPaycheckAmountSave={handleAmountSave}
+            onGenerate={generateMonth}
+            onAmountSave={handleAmountSave}
            onBillAmountSave={handleBillAmountSave}
            onFinancingPaidToggle={handleFinancingPaidToggle}
          />
@@ -752,8 +767,8 @@ function PaycheckView() {
            onOteDelete={handleOteDelete}
            onOteAdd={handleOteAdd}
            categories={categories}
-            onPaycheckGenerate={generateMonth}
-            onPaycheckAmountSave={handleAmountSave}
+            onGenerate={generateMonth}
+            onAmountSave={handleAmountSave}
            onBillAmountSave={handleBillAmountSave}
            onFinancingPaidToggle={handleFinancingPaidToggle}
          />
--- a/client/src/utils/formatting.js
+++ b/client/src/utils/formatting.js
@@ -1,34 +0,0 @@
-export const MONTH_NAMES = [
-  'January', 'February', 'March', 'April', 'May', 'June',
-  'July', 'August', 'September', 'October', 'November', 'December',
-];
-
-// Accessible palette that works in light and dark
-export const PALETTE = ['#3b82f6', '#8b5cf6', '#ec4899', '#f97316', '#22c55e', '#14b8a6', '#eab308', '#64748b'];
-
-export function formatCurrency(value) {
-  const num = parseFloat(value) || 0;
-  return '$' + num.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-}
-
-export function formatCurrencyShort(value) {
-  if (value == null || isNaN(value)) return '';
-  const abs = Math.abs(value);
-  const sign = value < 0 ? '-' : '';
-  if (abs >= 1000) return `${sign}$${(abs / 1000).toFixed(1)}k`;
-  return `${sign}$${abs.toFixed(0)}`;
-}
-
-export function ordinal(n) {
-  const s = ['th', 'st', 'nd', 'rd'];
-  const v = n % 100;
-  return n + (s[(v - 20) % 10] || s[v] || s[0]);
-}
-
-export function fmt(value) {
-  if (value == null) return '—';
-  const num = Number(value);
-  if (isNaN(num)) return '—';
-  const abs = Math.abs(num).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-  return num < 0 ? `-$${abs}` : `$${abs}`;
-}
--- a/server/package-lock.json
+++ b/server/package-lock.json
@@ -8,6 +8,7 @@
      "name": "budget-server",
      "version": "1.0.0",
      "dependencies": {
+        "@anthropic-ai/sdk": "^0.80.0",
        "cors": "^2.8.5",
        "dotenv": "^16.4.5",
        "express": "^4.19.2",
@@ -19,6 +20,35 @@
        "vitest": "^4.1.0"
      }
    },
+    "node_modules/@anthropic-ai/sdk": {
+      "version": "0.80.0",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.80.0.tgz",
+      "integrity": "sha512-WeXLn7zNVk3yjeshn+xZHvld6AoFUOR3Sep6pSoHho5YbSi6HwcirqgPA5ccFuW8QTVJAAU7N8uQQC6Wa9TG+g==",
+      "license": "MIT",
+      "dependencies": {
+        "json-schema-to-ts": "^3.1.1"
+      },
+      "bin": {
+        "anthropic-ai-sdk": "bin/cli"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "zod": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz",
+      "integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
    "node_modules/@emnapi/core": {
      "version": "1.9.1",
      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.1.tgz",
@@ -1382,6 +1412,19 @@
        "node": ">=0.12.0"
      }
    },
+    "node_modules/json-schema-to-ts": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz",
+      "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.18.3",
+        "ts-algebra": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
    "node_modules/lightningcss": {
      "version": "1.32.0",
      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
@@ -2623,6 +2666,12 @@
        "nodetouch": "bin/nodetouch.js"
      }
    },
+    "node_modules/ts-algebra": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz",
+      "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==",
+      "license": "MIT"
+    },
    "node_modules/tslib": {
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
--- a/server/package.json
+++ b/server/package.json
@@ -9,6 +9,7 @@
    "test:watch": "vitest"
  },
  "dependencies": {
+    "@anthropic-ai/sdk": "^0.80.0",
    "cors": "^2.8.5",
    "dotenv": "^16.4.5",
    "express": "^4.19.2",
--- a/server/src/tests/semantic-diff.test.js
+++ b/server/src/tests/semantic-diff.test.js
@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import request from 'supertest';
+import app from '../app.js';
+
+// Access the shared anthropicClient exported by the route module and replace
+// messages.create directly — same pattern as db.pool.query mocking in this codebase.
+const semanticDiffRoute = require('../routes/semantic-diff.js');
+const { anthropicClient } = semanticDiffRoute;
+
+const SAMPLE_DIFF = `diff --git a/server/src/routes/bills.js b/server/src/routes/bills.js
+--- a/server/src/routes/bills.js
+++ b/server/src/routes/bills.js
+@@ -10,7 +10,7 @@
+-  const amount = req.body.amount;
+  const amount = parseFloat(req.body.amount);
+`;
+
+describe('POST /api/semantic-diff', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns 400 when diff is missing', async () => {
+    const res = await request(app).post('/api/semantic-diff').send({});
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/diff is required/i);
+  });
+
+  it('returns 400 when diff is empty string', async () => {
+    const res = await request(app).post('/api/semantic-diff').send({ diff: '   ' });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/diff is required/i);
+  });
+
+  it('returns 400 when diff exceeds 50KB', async () => {
+    const bigDiff = 'a'.repeat(51 * 1024);
+    const res = await request(app).post('/api/semantic-diff').send({ diff: bigDiff });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/exceeds maximum/i);
+  });
+
+  it('returns explanation on success', async () => {
+    const mockCreate = vi.spyOn(anthropicClient.messages, 'create').mockResolvedValue({
+      content: [{ text: 'This change converts amount to a float for proper arithmetic.' }],
+    });
+
+    const res = await request(app).post('/api/semantic-diff').send({ diff: SAMPLE_DIFF });
+    expect(res.status).toBe(200);
+    expect(res.body.explanation).toBe('This change converts amount to a float for proper arithmetic.');
+    expect(mockCreate).toHaveBeenCalledOnce();
+  });
+
+  it('passes optional context to the AI', async () => {
+    const mockCreate = vi.spyOn(anthropicClient.messages, 'create').mockResolvedValue({
+      content: [{ text: 'Explanation with context.' }],
+    });
+
+    await request(app)
+      .post('/api/semantic-diff')
+      .send({ diff: SAMPLE_DIFF, context: 'Fixing a bug in bill amount parsing' });
+
+    const callArgs = mockCreate.mock.calls[0][0];
+    expect(callArgs.messages[0].content).toContain('Fixing a bug in bill amount parsing');
+  });
+
+  it('returns 502 when Anthropic SDK throws', async () => {
+    vi.spyOn(anthropicClient.messages, 'create').mockRejectedValue(new Error('API unavailable'));
+
+    const res = await request(app).post('/api/semantic-diff').send({ diff: SAMPLE_DIFF });
+    expect(res.status).toBe(502);
+    expect(res.body.error).toMatch(/failed to get explanation/i);
+  });
+});
--- a/server/src/app.js
+++ b/server/src/app.js
@@ -9,6 +9,7 @@ const actualsRouter = require('./routes/actuals');
 const oneTimeExpensesRouter = require('./routes/one-time-expenses');
 const summaryRouter = require('./routes/summary');
 const { router: financingRouter } = require('./routes/financing');
+const semanticDiffRouter = require('./routes/semantic-diff');

 const app = express();

@@ -24,6 +25,7 @@ app.use('/api', actualsRouter);
 app.use('/api', oneTimeExpensesRouter);
 app.use('/api', summaryRouter);
 app.use('/api', financingRouter);
+app.use('/api', semanticDiffRouter);

 // Serve static client files in production
 const clientDist = path.join(__dirname, '../../client/dist');
--- a/server/src/constants.js
+++ b/server/src/constants.js
@@ -1,12 +0,0 @@
-'use strict';
-
-const CONFIG_KEYS = [
-  'paycheck1_day',
-  'paycheck2_day',
-  'paycheck1_gross',
-  'paycheck1_net',
-  'paycheck2_gross',
-  'paycheck2_net',
-];
-
-module.exports = { CONFIG_KEYS };
--- a/server/src/routes/bills.js
+++ b/server/src/routes/bills.js
@@ -2,20 +2,6 @@ const express = require('express');
 const router = express.Router();
 const { pool } = require('../db');

-/**
- * Validate the request body for bill create/update operations.
- *
- * Checks that all required fields are present and within acceptable ranges.
- * Amount is optional when `variable_amount` is true (defaults to 0 on save).
- *
- * @param {object} body - Request body.
- * @param {string}        body.name              - Bill name (non-empty).
- * @param {number|string} [body.amount]           - Bill amount; required when variable_amount is falsy.
- * @param {number|string} body.due_day            - Day of month (1–31).
- * @param {number|string} body.assigned_paycheck  - Which paycheck: 1 or 2.
- * @param {boolean}       [body.variable_amount]  - Whether the bill amount varies each month.
- * @returns {string|null} Validation error message, or null when valid.
- */
 function validateBillFields(body) {
  const { name, amount, due_day, assigned_paycheck, variable_amount } = body;
  if (!name || name.toString().trim() === '') {
--- a/server/src/routes/config.js
+++ b/server/src/routes/config.js
@@ -1,29 +1,21 @@
 const express = require('express');
 const router = express.Router();
 const { pool } = require('../db');
-const { CONFIG_KEYS } = require('../constants');
+
+const CONFIG_KEYS = [
+  'paycheck1_day',
+  'paycheck2_day',
+  'paycheck1_gross',
+  'paycheck1_net',
+  'paycheck2_gross',
+  'paycheck2_net',
+];

 const DEFAULTS = {
  paycheck1_day: 1,
  paycheck2_day: 15,
 };

-/**
- * Fetch all application config values from the database.
- *
- * Reads all known `CONFIG_KEYS` from the `config` table and coerces values
- * to numbers. Keys missing from the DB fall back to hard-coded `DEFAULTS`
- * (paycheck1_day = 1, paycheck2_day = 15); keys with no default are null.
- *
- * @returns {Promise<{
- *   paycheck1_day: number|null,
- *   paycheck2_day: number|null,
- *   paycheck1_gross: number|null,
- *   paycheck1_net: number|null,
- *   paycheck2_gross: number|null,
- *   paycheck2_net: number|null
- * }>}
- */
 async function getAllConfig() {
  const result = await pool.query(
    'SELECT key, value FROM config WHERE key = ANY($1)',
--- a/server/src/routes/financing.js
+++ b/server/src/routes/financing.js
@@ -4,20 +4,9 @@ const { pool } = require('../db');

 // ─── Helpers ──────────────────────────────────────────────────────────────────

-/**
- * Count the number of payment periods remaining for a plan, starting from
- * (and including) the given year/month.
- *
- * Each calendar month contributes 1 period for single-paycheck plans
- * (`assigned_paycheck` = 1 or 2) or 2 periods for split plans
- * (`assigned_paycheck` = null). Always returns at least 1 to prevent
- * division-by-zero in {@link calcPaymentAmount}.
- *
- * @param {{ due_date: string, assigned_paycheck: number|null }} plan
- * @param {number} year  - Current year.
- * @param {number} month - Current month (1–12).
- * @returns {number} Number of remaining payment periods (≥ 1).
- */
+// Count how many payment periods remain for a plan starting from (year, month),
+// including that month. Each month contributes 1 or 2 periods depending on
+// whether the plan is split across both paychecks (assigned_paycheck = null).
 function remainingPeriods(plan, year, month) {
  const due = new Date(plan.due_date);
  const dueYear  = due.getFullYear();
@@ -30,18 +19,7 @@ function remainingPeriods(plan, year, month) {
  return monthsLeft * perMonth;
 }

-/**
- * Calculate the payment amount due for a single period.
- *
- * Formula: `(total_amount - paid_so_far) / remainingPeriods(plan, year, month)`.
- * Returns 0 when the plan is already fully paid.
- *
- * @param {import('pg').PoolClient} client - Active DB client (read-only query).
- * @param {{ id: number, total_amount: number|string, due_date: string, assigned_paycheck: number|null }} plan
- * @param {number} year  - Current year for period calculation.
- * @param {number} month - Current month (1–12) for period calculation.
- * @returns {Promise<number>} Payment amount rounded to 2 decimal places, or 0.
- */
+// Calculate the payment amount for one period.
 async function calcPaymentAmount(client, plan, year, month) {
  const { rows } = await client.query(
    `SELECT COALESCE(SUM(fp.amount), 0) AS paid_total
@@ -57,22 +35,7 @@ async function calcPaymentAmount(client, plan, year, month) {
  return parseFloat((remaining / periods).toFixed(2));
 }

-/**
- * Enrich a raw `financing_plans` row with computed progress fields.
- *
- * Aggregates payment records to derive `paid_total`, `remaining`,
- * `paid_count`, `total_count`, and `overdue`. Used by every route that
- * returns a plan to the client.
- *
- * @param {import('pg').Pool} pool - DB pool (runs a single SELECT).
- * @param {object} plan - Raw row from the `financing_plans` table.
- * @returns {Promise<object>} Plan object extended with:
- *   - `paid_total`  {number} — sum of paid payment amounts
- *   - `remaining`   {number} — total_amount minus paid_total (≥ 0)
- *   - `paid_count`  {number} — number of paid financing_payments rows
- *   - `total_count` {number} — total financing_payments rows for the plan
- *   - `overdue`     {boolean} — true when active, remaining > 0, and due_date is in the past
- */
+// Enrich a plan row with computed progress fields.
 async function enrichPlan(pool, plan) {
  const { rows } = await pool.query(
    `SELECT
--- a/server/src/routes/paychecks.js
+++ b/server/src/routes/paychecks.js
@@ -2,7 +2,15 @@ const express = require('express');
 const router = express.Router();
 const { pool } = require('../db');
 const { calcPaymentAmount } = require('./financing');
-const { CONFIG_KEYS } = require('../constants');
+
+const CONFIG_KEYS = [
+  'paycheck1_day',
+  'paycheck2_day',
+  'paycheck1_gross',
+  'paycheck1_net',
+  'paycheck2_gross',
+  'paycheck2_net',
+];

 const CONFIG_DEFAULTS = {
  paycheck1_day: 1,
@@ -35,29 +43,9 @@ function pad2(n) {
  return String(n).padStart(2, '0');
 }

-/**
- * Build virtual (unsaved) paycheck data from config + active bills.
- *
- * Returns the same shape as {@link fetchPaychecksForMonth} but with
- * `id: null` and `paycheck_bill_id: null` — nothing is written to the DB.
- * Financing payment previews are included with `financing_payment_id: null`.
- * Plans whose `start_date` is after the requested period are excluded.
- *
- * @param {number} year  - Full four-digit year (e.g. 2025).
- * @param {number} month - Month number 1–12.
- * @returns {Promise<Array<{
- *   id: null,
- *   period_year: number,
- *   period_month: number,
- *   paycheck_number: 1|2,
- *   pay_date: string,
- *   gross: number,
- *   net: number,
- *   bills: Array<object>,
- *   one_time_expenses: [],
- *   financing: Array<object>
- * }>>}
- */
+// Build virtual (unsaved) paycheck data from config + active bills.
+// Returns the same shape as fetchPaychecksForMonth but with id: null
+// and paycheck_bill_id: null — nothing is written to the DB.
 async function buildVirtualPaychecks(year, month) {
  const config = await getConfig();
  const paychecks = [];
@@ -149,19 +137,8 @@ async function buildVirtualPaychecks(year, month) {
  return paychecks;
 }

-/**
- * Generate (upsert) paycheck records for the given year/month.
- *
- * Inserts or updates both `paychecks` rows, syncs `paycheck_bills` for all
- * active bills, and inserts `financing_payments` for active plans that have
- * started by this period. All writes run inside a single transaction.
- * Split financing plans (assigned_paycheck = null) get half the per-period
- * amount on each paycheck.
- *
- * @param {number} year  - Full four-digit year.
- * @param {number} month - Month number 1–12.
- * @returns {Promise<number[]>} Two-element array of paycheck IDs `[id1, id2]`.
- */
+// Generate (upsert) paycheck records for the given year/month.
+// Returns the two paycheck IDs.
 async function generatePaychecks(year, month) {
  const config = await getConfig();

@@ -244,25 +221,7 @@ async function generatePaychecks(year, month) {
  }
 }

-/**
- * Fetch both persisted paycheck records for a month with full bill,
- * one-time-expense, and financing-payment data joined in.
- *
- * @param {number} year  - Full four-digit year.
- * @param {number} month - Month number 1–12.
- * @returns {Promise<Array<{
- *   id: number,
- *   period_year: number,
- *   period_month: number,
- *   paycheck_number: 1|2,
- *   pay_date: string,
- *   gross: number,
- *   net: number,
- *   bills: Array<object>,
- *   one_time_expenses: Array<object>,
- *   financing: Array<object>
- * }>>} Empty array when no DB records exist for the given month.
- */
+// Fetch both paycheck records for a month with full bill and one_time_expense data.
 async function fetchPaychecksForMonth(year, month) {
  const pcResult = await pool.query(
    `SELECT id, period_year, period_month, paycheck_number, pay_date, gross, net
--- a/server/src/routes/semantic-diff.js
+++ b/server/src/routes/semantic-diff.js
@@ -0,0 +1,56 @@
+const express = require('express');
+const Anthropic = require('@anthropic-ai/sdk');
+
+const router = express.Router();
+
+// Exported so tests can replace client.messages.create without real API calls
+const anthropicClient = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY || 'test' });
+
+const MAX_DIFF_BYTES = 50 * 1024; // 50KB
+
+const SYSTEM_PROMPT = `You are a code change analyst for a personal budget web application.
+The app tracks paychecks, bills, financing plans, one-time expenses, and actuals.
+Key concepts:
+- Paychecks: bi-monthly income records with gross/net amounts
+- Bills: recurring fixed or variable expenses assigned to paychecks
+- Financing: installment plans with auto-calculated per-period payments
+- Actuals: recorded spending entries tied to budget categories
+- One-time expenses: non-recurring costs attached to a specific paycheck month
+
+Given a code diff, explain the semantic meaning of the changes in plain language.
+Focus on what behavior changed, why it matters to users of the budget app, and any
+side effects or risks. Be concise but thorough.`;
+
+router.post('/semantic-diff', async (req, res) => {
+  const { diff, context } = req.body;
+
+  if (!diff || typeof diff !== 'string' || diff.trim().length === 0) {
+    return res.status(400).json({ error: 'diff is required and must be a non-empty string' });
+  }
+
+  if (Buffer.byteLength(diff, 'utf8') > MAX_DIFF_BYTES) {
+    return res.status(400).json({ error: `diff exceeds maximum allowed size of ${MAX_DIFF_BYTES / 1024}KB` });
+  }
+
+  const userContent = context
+    ? `Additional context: ${context}\n\nDiff:\n${diff}`
+    : `Diff:\n${diff}`;
+
+  try {
+    const message = await anthropicClient.messages.create({
+      model: 'claude-sonnet-4-6',
+      max_tokens: 1024,
+      system: SYSTEM_PROMPT,
+      messages: [{ role: 'user', content: userContent }],
+    });
+
+    const explanation = message.content[0].text;
+    return res.json({ explanation });
+  } catch (err) {
+    console.error('Anthropic API error:', err);
+    return res.status(502).json({ error: 'Failed to get explanation from AI service' });
+  }
+});
+
+module.exports = router;
+module.exports.anthropicClient = anthropicClient;