Fix grep portability bug and document doc-drift script in CLAUDE.md

- Use grep -rE (ERE) instead of BRE \| alternation for BSD/macOS compat
- Add doc-drift section to CLAUDE.md Testing section with usage and purpose

Nightshift-Task: doc-drift
Nightshift-Ref: https://github.com/marcus/nightshift

CLAUDE.md

@@ -77,6 +77,12 @@ 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=`.
@@ -94,5 +100,3 @@ 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.
-
-**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`).

scripts/doc-drift.js

@@ -0,0 +1,203 @@
+#!/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);

server/package-lock.json

@@ -8,7 +8,6 @@
       "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",
@@ -20,35 +19,6 @@
         "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",
@@ -1412,19 +1382,6 @@
         "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",
@@ -2666,12 +2623,6 @@
         "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",

server/package.json

@@ -9,7 +9,6 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.80.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.5",
     "express": "^4.19.2",

server/src/__tests__/semantic-diff.test.js

@@ -1,73 +0,0 @@
-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);
-  });
-});

server/src/app.js

@@ -9,7 +9,6 @@ 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();
 
@@ -25,7 +24,6 @@ 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');

server/src/routes/semantic-diff.js

@@ -1,56 +0,0 @@
-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;