Fix review issues: partial index, middleware scope, add timing tests

- Change idx_financing_plans_active to partial index (WHERE active = true)
  to avoid useless B-tree index on low-cardinality boolean column
- Scope timingMiddleware to /api routes only (was globally registered,
  which caused noise from static asset requests)
- Add unit tests for timing middleware (5 tests covering: next() call,
  timing log format, SLOW warning threshold, fast-request path, status code)

Nightshift-Task: perf-regression
Nightshift-Ref: https://github.com/marcus/nightshift

CLAUDE.md

@@ -77,12 +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
 
-**Doc drift check:**
-```bash
-node scripts/doc-drift.js
-```
-Scans `CLAUDE.md` and `PRD.md` for verifiable code references (file paths, API routes, component names) and cross-checks each against the filesystem and source tree. Prints a PASS/FAIL report with doc name and line number. Exits non-zero on any failure — suitable for CI gating.
-
 ## 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=`.
@@ -100,3 +94,16 @@ The default route `/` renders the paycheck-centric main view (`client/src/pages/
 **Financing:** `GET/POST /api/financing`, `PUT/DELETE /api/financing/:id`, `PATCH /api/financing-payments/:id/paid`. Plans track a total amount, payoff due date, and `start_date`. Payment per period is auto-calculated as `(remaining balance) / (remaining periods)`. Split plans (`assigned_paycheck = null`) divide each period's payment across both paychecks. Plans auto-close when fully paid. Financing payments are included in the paycheck remaining balance. `start_date` prevents a plan from appearing on paycheck months before it was created — both virtual previews and `generate` respect this guard.
 
 **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.
+
+## Performance Tooling
+
+**Timing middleware** (`server/src/middleware/timing.js`): Registered early in `app.js`. Logs every request's method, path, status code, and duration. Emits a `[SLOW]` warning for responses exceeding 200 ms.
+
+**Benchmark script** (`scripts/perf-benchmark.js`): Hits `GET /api/paychecks`, `GET /api/financing`, and `GET /api/summary/annual` five times each and reports min/mean/max latency. Exits non-zero if any mean exceeds the threshold (default 500 ms, override via `SLOW_THRESHOLD_MS` env var). Target server URL defaults to `http://localhost:3001` (override via `BENCHMARK_URL`).
+
+```bash
+cd server && npm run perf          # run against localhost:3001
+BENCHMARK_URL=http://localhost:3000 npm run perf
+```
+
+**Performance indexes** (`db/migrations/005_performance_indexes.sql`): Adds indexes on `paychecks(period_year, period_month)`, `paycheck_bills(paycheck_id)`, `actuals(paycheck_id)`, `one_time_expenses(paycheck_id)`, `financing_payments(plan_id)`, and `financing_plans(active)` — applied automatically on server startup.

db/migrations/005_performance_indexes.sql

@@ -0,0 +1,7 @@
+-- Performance indexes for high-traffic query patterns
+CREATE INDEX IF NOT EXISTS idx_paychecks_period ON paychecks(period_year, period_month);
+CREATE INDEX IF NOT EXISTS idx_paycheck_bills_paycheck_id ON paycheck_bills(paycheck_id);
+CREATE INDEX IF NOT EXISTS idx_actuals_paycheck_id ON actuals(paycheck_id);
+CREATE INDEX IF NOT EXISTS idx_one_time_expenses_paycheck_id ON one_time_expenses(paycheck_id);
+CREATE INDEX IF NOT EXISTS idx_financing_payments_plan_id ON financing_payments(plan_id);
+CREATE INDEX IF NOT EXISTS idx_financing_plans_active ON financing_plans(active) WHERE active = true;

scripts/doc-drift.js

@@ -1,203 +0,0 @@
-#!/usr/bin/env node
-/**
- * doc-drift.js — detects documentation drift by cross-checking verifiable
- * code references in CLAUDE.md and PRD.md against the filesystem and source tree.
- *
- * Usage: node scripts/doc-drift.js
- * Exits non-zero if any drift is found.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const ROOT = path.resolve(__dirname, '..');
-const DOCS = ['CLAUDE.md', 'PRD.md'].map(f => path.join(ROOT, f));
-
-// ── Result tracking ──────────────────────────────────────────────────────────
-
-const results = [];
-
-function record(doc, line, kind, ref, pass, reason) {
-  results.push({ doc: path.basename(doc), line, kind, ref, pass, reason });
-}
-
-// ── Extraction helpers ───────────────────────────────────────────────────────
-
-/** Extract all backtick spans from a line (may be multiple). */
-function backtickSpans(line) {
-  const spans = [];
-  const re = /`([^`]+)`/g;
-  let m;
-  while ((m = re.exec(line)) !== null) spans.push(m[1]);
-  return spans;
-}
-
-/** Return true if a span looks like a file/dir path we can verify. */
-function isFilePath(span) {
-  // Must contain a slash and start with a recognisable project prefix.
-  return (
-    /[/\\]/.test(span) &&
-    /^(client|server|db|scripts|docker-compose)/.test(span) &&
-    // Exclude shell commands, URLs, SQL snippets, etc.
-    !/\s/.test(span) &&
-    !span.includes('=') &&
-    !span.startsWith('http')
-  );
-}
-
-/** Return true if a span looks like a component/page reference (*.jsx). */
-function isJsxRef(span) {
-  return /\w+\.jsx$/.test(span) && !/[/]/.test(span); // bare name, no path
-}
-
-/** Extract HTTP API route patterns like `GET /api/paychecks`. */
-function extractApiRoutes(line) {
-  const routes = [];
-  const re = /\b(GET|POST|PUT|DELETE|PATCH)\s+(\/api\/[^\s,`'")\]]+)/g;
-  let m;
-  while ((m = re.exec(line)) !== null) routes.push({ method: m[1], path: m[2] });
-  return routes;
-}
-
-// ── Verification helpers ─────────────────────────────────────────────────────
-
-function fileExists(relPath) {
-  return fs.existsSync(path.join(ROOT, relPath));
-}
-
-/**
- * For API routes: grep server/src/routes/ for the route path string.
- * We look for the path fragment (everything after /api) as a string literal.
- */
-function apiRouteExists(routePath) {
-  // Strip query-string placeholders like ?year=&month=
-  const clean = routePath.replace(/\?.*$/, '').replace(/:id/g, ':id');
-  // Build a grep-friendly pattern: look for the path minus leading /api
-  const fragment = clean.replace(/^\/api/, '');
-  try {
-    const out = execSync(
-      `grep -rE --include="*.js" -l "${clean}|${fragment}" "${path.join(ROOT, 'server/src/routes')}"`,
-      { stdio: ['pipe', 'pipe', 'pipe'] }
-    ).toString().trim();
-    return out.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * For bare *.jsx component names: check that a file with that name exists
- * somewhere under client/src/.
- */
-function jsxComponentExists(name) {
-  try {
-    const out = execSync(
-      `find "${path.join(ROOT, 'client/src')}" -name "${name}" -type f`,
-      { stdio: ['pipe', 'pipe', 'pipe'] }
-    ).toString().trim();
-    return out.length > 0;
-  } catch {
-    return false;
-  }
-}
-
-// ── Main ─────────────────────────────────────────────────────────────────────
-
-for (const docPath of DOCS) {
-  if (!fs.existsSync(docPath)) {
-    console.error(`WARN: doc not found: ${docPath}`);
-    continue;
-  }
-
-  const lines = fs.readFileSync(docPath, 'utf8').split('\n');
-
-  lines.forEach((rawLine, idx) => {
-    const lineNo = idx + 1;
-
-    // 1. Backtick file paths
-    for (const span of backtickSpans(rawLine)) {
-      if (isFilePath(span)) {
-        const exists = fileExists(span);
-        record(
-          docPath,
-          lineNo,
-          'file-path',
-          span,
-          exists,
-          exists ? 'found on filesystem' : `not found: ${span}`
-        );
-        continue;
-      }
-
-      if (isJsxRef(span)) {
-        const exists = jsxComponentExists(span);
-        record(
-          docPath,
-          lineNo,
-          'component',
-          span,
-          exists,
-          exists ? 'found under client/src' : `no file named ${span} in client/src`
-        );
-      }
-    }
-
-    // 2. API routes (inside or outside backticks)
-    for (const { method, path: routePath } of extractApiRoutes(rawLine)) {
-      const ref = `${method} ${routePath}`;
-      const exists = apiRouteExists(routePath);
-      record(
-        docPath,
-        lineNo,
-        'api-route',
-        ref,
-        exists,
-        exists ? 'found in server/src/routes' : `route not found in server/src/routes`
-      );
-    }
-  });
-}
-
-// ── Report ───────────────────────────────────────────────────────────────────
-
-const padDoc  = Math.max(...results.map(r => r.doc.length), 9);
-const padKind = Math.max(...results.map(r => r.kind.length), 9);
-const padRef  = Math.min(60, Math.max(...results.map(r => r.ref.length), 10));
-
-const header = [
-  'STATUS'.padEnd(6),
-  'DOC'.padEnd(padDoc),
-  'LINE'.padStart(4),
-  'KIND'.padEnd(padKind),
-  'REFERENCE',
-].join('  ');
-
-console.log('\n' + header);
-console.log('─'.repeat(header.length + 10));
-
-let failures = 0;
-
-for (const r of results) {
-  const status = r.pass ? 'PASS' : 'FAIL';
-  const ref = r.ref.length > padRef ? r.ref.slice(0, padRef - 1) + '…' : r.ref;
-  const line = [
-    (r.pass ? '\x1b[32m' : '\x1b[31m') + status.padEnd(6) + '\x1b[0m',
-    r.doc.padEnd(padDoc),
-    String(r.line).padStart(4),
-    r.kind.padEnd(padKind),
-    ref,
-  ].join('  ');
-  console.log(line);
-  if (!r.pass) {
-    console.log(`       \x1b[33m↳ ${r.reason}\x1b[0m`);
-    failures++;
-  }
-}
-
-console.log('─'.repeat(header.length + 10));
-console.log(`\n${results.length} references checked — ${failures} failure(s)\n`);
-
-process.exit(failures > 0 ? 1 : 0);

scripts/perf-benchmark.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+'use strict';
+
+const BASE_URL = process.env.BENCHMARK_URL || 'http://localhost:3001';
+const ITERATIONS = 5;
+const MEAN_THRESHOLD_MS = parseInt(process.env.SLOW_THRESHOLD_MS || '500', 10);
+
+const ENDPOINTS = [
+  { label: 'GET /api/paychecks', path: `/api/paychecks?year=${new Date().getFullYear()}&month=${new Date().getMonth() + 1}` },
+  { label: 'GET /api/financing', path: '/api/financing' },
+  { label: 'GET /api/summary/annual', path: `/api/summary/annual?year=${new Date().getFullYear()}` },
+];
+
+async function measureEndpoint(endpoint) {
+  const times = [];
+  for (let i = 0; i < ITERATIONS; i++) {
+    const start = Date.now();
+    const res = await fetch(`${BASE_URL}${endpoint.path}`);
+    const duration = Date.now() - start;
+    if (!res.ok) {
+      console.warn(`  [warn] ${endpoint.label} returned HTTP ${res.status}`);
+    }
+    times.push(duration);
+  }
+  const min = Math.min(...times);
+  const max = Math.max(...times);
+  const mean = Math.round(times.reduce((a, b) => a + b, 0) / times.length);
+  return { min, mean, max };
+}
+
+(async () => {
+  console.log(`Benchmarking ${BASE_URL} (${ITERATIONS} iterations each, threshold ${MEAN_THRESHOLD_MS}ms)\n`);
+
+  let failed = false;
+
+  for (const endpoint of ENDPOINTS) {
+    let stats;
+    try {
+      stats = await measureEndpoint(endpoint);
+    } catch (err) {
+      console.error(`  [error] ${endpoint.label}: ${err.message}`);
+      failed = true;
+      continue;
+    }
+
+    const flag = stats.mean >= MEAN_THRESHOLD_MS ? ' *** SLOW ***' : '';
+    console.log(`${endpoint.label}`);
+    console.log(`  min=${stats.min}ms  mean=${stats.mean}ms  max=${stats.max}ms${flag}`);
+
+    if (stats.mean >= MEAN_THRESHOLD_MS) {
+      failed = true;
+    }
+  }
+
+  console.log('');
+  if (failed) {
+    console.error('FAIL: one or more endpoints exceeded the threshold or errored.');
+    process.exit(1);
+  } else {
+    console.log('PASS: all endpoints within threshold.');
+  }
+})();

server/package.json

@@ -6,7 +6,8 @@
     "start": "node src/index.js",
     "dev": "nodemon src/index.js",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "perf": "node ../scripts/perf-benchmark.js"
   },
   "dependencies": {
     "cors": "^2.8.5",

server/src/__tests__/timing.middleware.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const timingMiddleware = require('../middleware/timing');
+
+function makeResMock() {
+  const listeners = {};
+  return {
+    statusCode: 200,
+    on(event, cb) {
+      listeners[event] = cb;
+    },
+    emit(event) {
+      if (listeners[event]) listeners[event]();
+    },
+  };
+}
+
+describe('timingMiddleware', () => {
+  let consoleSpy;
+  let warnSpy;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    warnSpy.mockRestore();
+    vi.useRealTimers();
+  });
+
+  it('calls next()', () => {
+    const req = { method: 'GET', path: '/api/health' };
+    const res = makeResMock();
+    const next = vi.fn();
+
+    timingMiddleware(req, res, next);
+    expect(next).toHaveBeenCalledOnce();
+  });
+
+  it('logs timing on response finish', () => {
+    const req = { method: 'GET', path: '/api/health' };
+    const res = makeResMock();
+
+    timingMiddleware(req, res, vi.fn());
+    res.emit('finish');
+
+    expect(consoleSpy).toHaveBeenCalledOnce();
+    const msg = consoleSpy.mock.calls[0][0];
+    expect(msg).toMatch(/\[timing\] GET \/api\/health 200 \d+ms/);
+  });
+
+  it('emits SLOW warning when duration exceeds 200ms threshold', () => {
+    vi.useFakeTimers();
+
+    const req = { method: 'POST', path: '/api/paychecks' };
+    const res = makeResMock();
+
+    timingMiddleware(req, res, vi.fn());
+
+    // Advance time past the threshold
+    vi.advanceTimersByTime(250);
+    res.emit('finish');
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    const msg = warnSpy.mock.calls[0][0];
+    expect(msg).toMatch(/\[SLOW\] POST \/api\/paychecks/);
+    expect(consoleSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not emit SLOW warning for fast requests', () => {
+    vi.useFakeTimers();
+
+    const req = { method: 'GET', path: '/api/financing' };
+    const res = makeResMock();
+
+    timingMiddleware(req, res, vi.fn());
+
+    vi.advanceTimersByTime(50);
+    res.emit('finish');
+
+    expect(consoleSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('includes status code in the log message', () => {
+    const req = { method: 'GET', path: '/api/bills' };
+    const res = makeResMock();
+    res.statusCode = 404;
+
+    timingMiddleware(req, res, vi.fn());
+    res.emit('finish');
+
+    const msg = consoleSpy.mock.calls[0][0];
+    expect(msg).toContain('404');
+  });
+});

server/src/app.js

@@ -9,13 +9,14 @@ const actualsRouter = require('./routes/actuals');
 const oneTimeExpensesRouter = require('./routes/one-time-expenses');
 const summaryRouter = require('./routes/summary');
 const { router: financingRouter } = require('./routes/financing');
+const timingMiddleware = require('./middleware/timing');
 
 const app = express();
 
 app.use(cors());
 app.use(express.json());
-
 // API routes
+app.use('/api', timingMiddleware);
 app.use('/api', healthRouter);
 app.use('/api', configRouter);
 app.use('/api', billsRouter);

server/src/middleware/timing.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const SLOW_THRESHOLD_MS = 200;
+
+function timingMiddleware(req, res, next) {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    const msg = `${req.method} ${req.path} ${res.statusCode} ${duration}ms`;
+    if (duration >= SLOW_THRESHOLD_MS) {
+      console.warn(`[SLOW] ${msg}`);
+    } else {
+      console.log(`[timing] ${msg}`);
+    }
+  });
+
+  next();
+}
+
+module.exports = timingMiddleware;