tlc-claude-code 1.6.4 → 1.7.0

package/server/lib/code-gate/llm-reviewer.test.js

@@ -0,0 +1,161 @@
+/**
+ * LLM Reviewer Tests
+ *
+ * Mandatory LLM code review before every push, using multi-model router.
+ * Collects diff, sends to LLM, parses structured review result.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  createReviewer,
+  buildReviewPrompt,
+  parseReviewResponse,
+  collectDiff,
+  shouldSkipReview,
+  storeReviewResult,
+} = require('./llm-reviewer.js');
+
+describe('LLM Reviewer', () => {
+  describe('createReviewer', () => {
+    it('creates reviewer with default options', () => {
+      const reviewer = createReviewer();
+      expect(reviewer).toBeDefined();
+      expect(reviewer.options.timeout).toBeDefined();
+    });
+
+    it('accepts custom timeout', () => {
+      const reviewer = createReviewer({ timeout: 30000 });
+      expect(reviewer.options.timeout).toBe(30000);
+    });
+  });
+
+  describe('buildReviewPrompt', () => {
+    it('includes diff in prompt', () => {
+      const prompt = buildReviewPrompt('--- a/file.js\n+++ b/file.js\n+const x = 1;', '');
+      expect(prompt).toContain('file.js');
+      expect(prompt).toContain('const x = 1');
+    });
+
+    it('includes coding standards in prompt', () => {
+      const standards = '# Coding Standards\n- No hardcoded URLs';
+      const prompt = buildReviewPrompt('diff content', standards);
+      expect(prompt).toContain('No hardcoded URLs');
+    });
+
+    it('instructs strict review', () => {
+      const prompt = buildReviewPrompt('diff', '');
+      expect(prompt.toLowerCase()).toContain('strict');
+    });
+
+    it('requests structured JSON output', () => {
+      const prompt = buildReviewPrompt('diff', '');
+      expect(prompt).toContain('JSON');
+    });
+  });
+
+  describe('parseReviewResponse', () => {
+    it('parses valid JSON review', () => {
+      const response = JSON.stringify({
+        findings: [
+          { severity: 'high', file: 'src/app.js', line: 10, rule: 'security', message: 'XSS risk', fix: 'Sanitize' },
+        ],
+        summary: 'Found 1 issue',
+      });
+      const result = parseReviewResponse(response);
+      expect(result.findings).toHaveLength(1);
+      expect(result.findings[0].severity).toBe('block'); // high normalizes to block
+    });
+
+    it('handles response with JSON in markdown code block', () => {
+      const response = '```json\n{"findings": [], "summary": "All clear"}\n```';
+      const result = parseReviewResponse(response);
+      expect(result.findings).toEqual([]);
+    });
+
+    it('returns error finding on unparseable response', () => {
+      const result = parseReviewResponse('I could not review this code because...');
+      expect(result.findings).toHaveLength(1);
+      expect(result.findings[0].severity).toBe('warn');
+      expect(result.findings[0].rule).toBe('llm-parse-error');
+    });
+
+    it('normalizes severity levels', () => {
+      const response = JSON.stringify({
+        findings: [
+          { severity: 'critical', file: 'x.js', message: 'Bad', fix: 'Fix' },
+          { severity: 'low', file: 'y.js', message: 'Minor', fix: 'Maybe' },
+        ],
+      });
+      const result = parseReviewResponse(response);
+      // critical and high map to 'block', medium and low map to 'warn'
+      expect(result.findings[0].severity).toBe('block');
+      expect(result.findings[1].severity).toBe('info');
+    });
+  });
+
+  describe('collectDiff', () => {
+    it('returns diff from exec', async () => {
+      const mockExec = vi.fn().mockResolvedValue('diff --git a/file.js\n+line');
+      const diff = await collectDiff({ exec: mockExec });
+      expect(diff).toContain('file.js');
+      expect(mockExec).toHaveBeenCalled();
+    });
+
+    it('returns empty string when no changes', async () => {
+      const mockExec = vi.fn().mockResolvedValue('');
+      const diff = await collectDiff({ exec: mockExec });
+      expect(diff).toBe('');
+    });
+  });
+
+  describe('shouldSkipReview', () => {
+    it('skips docs-only changes', () => {
+      const files = ['README.md', 'docs/guide.md', 'CHANGELOG.md'];
+      expect(shouldSkipReview(files)).toBe(true);
+    });
+
+    it('does not skip code changes', () => {
+      const files = ['src/app.js', 'README.md'];
+      expect(shouldSkipReview(files)).toBe(false);
+    });
+
+    it('does not skip config changes', () => {
+      const files = ['package.json', '.env.example'];
+      expect(shouldSkipReview(files)).toBe(false);
+    });
+  });
+
+  describe('storeReviewResult', () => {
+    it('writes review to .tlc/reviews/{hash}.json', () => {
+      let writtenPath = '';
+      let writtenData = '';
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(true),
+        mkdirSync: vi.fn(),
+        writeFileSync: vi.fn((path, data) => {
+          writtenPath = path;
+          writtenData = data;
+        }),
+      };
+
+      const result = { findings: [], summary: 'Clean' };
+      storeReviewResult('abc123', result, { fs: mockFs });
+
+      expect(writtenPath).toContain('abc123.json');
+      expect(writtenPath).toContain('reviews');
+      const parsed = JSON.parse(writtenData);
+      expect(parsed.summary).toBe('Clean');
+    });
+
+    it('creates reviews directory if missing', () => {
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(false),
+        mkdirSync: vi.fn(),
+        writeFileSync: vi.fn(),
+      };
+
+      storeReviewResult('xyz', { findings: [] }, { fs: mockFs });
+      expect(mockFs.mkdirSync).toHaveBeenCalled();
+    });
+  });
+});

package/server/lib/code-gate/push-gate.js

@@ -0,0 +1,133 @@
+/**
+ * Push Gate
+ *
+ * Wires the static gate engine + LLM reviewer into the pre-push flow.
+ * Runs static first (fast feedback), then LLM if static passes.
+ * Falls back to static-only on LLM timeout.
+ *
+ * @module code-gate/push-gate
+ */
+
+/** Default LLM review timeout in ms */
+const DEFAULT_LLM_TIMEOUT = 60000;
+
+/**
+ * Create a push gate instance.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.llmTimeout] - LLM review timeout in ms
+ * @returns {{ options: Object }}
+ */
+function createPushGate(options = {}) {
+  return {
+    options: {
+      llmTimeout: options.llmTimeout || DEFAULT_LLM_TIMEOUT,
+    },
+  };
+}
+
+/**
+ * Run the full push gate: static analysis then LLM review.
+ *
+ * @param {Object} params
+ * @param {Function} params.staticGate - Static gate runner (returns gate result)
+ * @param {Function} params.llmReview - LLM reviewer (returns review result)
+ * @param {Array} params.files - Changed files
+ * @param {boolean} [params.override] - Team lead override (TLC_GATE_OVERRIDE)
+ * @returns {Promise<Object>} Combined gate result
+ */
+async function runPushGate(params) {
+  const { staticGate, llmReview, files, override = false } = params;
+
+  // Phase 1: Static gate (fast)
+  const staticResult = await staticGate(files);
+
+  // Team lead override
+  if (!staticResult.passed && override) {
+    return {
+      passed: true,
+      overridden: true,
+      staticResult,
+      llmResult: null,
+      findings: staticResult.findings,
+      summary: staticResult.summary,
+    };
+  }
+
+  // Static failure blocks immediately — no LLM call
+  if (!staticResult.passed) {
+    return {
+      passed: false,
+      overridden: false,
+      llmSkipped: true,
+      staticResult,
+      llmResult: null,
+      findings: staticResult.findings,
+      summary: staticResult.summary,
+    };
+  }
+
+  // Phase 2: LLM review (only if static passes)
+  let llmResult = null;
+  let llmSkipped = false;
+
+  try {
+    llmResult = await llmReview(files);
+  } catch {
+    // LLM timeout or error — fall back to static-only
+    llmSkipped = true;
+  }
+
+  // Merge results
+  const merged = mergeResults(staticResult, llmResult);
+
+  return {
+    passed: merged.passed,
+    overridden: false,
+    llmSkipped,
+    staticResult,
+    llmResult,
+    findings: merged.findings,
+    summary: merged.summary,
+  };
+}
+
+/**
+ * Merge static gate result with LLM review result.
+ * Tags each finding with its source for traceability.
+ *
+ * @param {Object} staticResult - Static gate result
+ * @param {Object|null} llmResult - LLM review result (null if skipped)
+ * @returns {{ passed: boolean, findings: Array, summary: Object }}
+ */
+function mergeResults(staticResult, llmResult) {
+  const staticFindings = (staticResult.findings || []).map(f => ({
+    ...f,
+    source: 'static',
+  }));
+
+  const llmFindings = llmResult
+    ? (llmResult.findings || []).map(f => ({ ...f, source: 'llm' }))
+    : [];
+
+  const allFindings = [...staticFindings, ...llmFindings];
+
+  const summary = {
+    total: allFindings.length,
+    block: allFindings.filter(f => f.severity === 'block').length,
+    warn: allFindings.filter(f => f.severity === 'warn').length,
+    info: allFindings.filter(f => f.severity === 'info').length,
+  };
+
+  return {
+    passed: summary.block === 0,
+    findings: allFindings,
+    summary,
+  };
+}
+
+module.exports = {
+  runPushGate,
+  mergeResults,
+  createPushGate,
+};

package/server/lib/code-gate/push-gate.test.js

@@ -0,0 +1,190 @@
+/**
+ * Push Gate Tests
+ *
+ * Wires the static gate engine + LLM reviewer into pre-push hook.
+ * Runs static first, then LLM if static passes.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  runPushGate,
+  mergeResults,
+  createPushGate,
+} = require('./push-gate.js');
+
+describe('Push Gate', () => {
+  describe('createPushGate', () => {
+    it('creates push gate with default options', () => {
+      const gate = createPushGate();
+      expect(gate).toBeDefined();
+      expect(gate.options).toBeDefined();
+    });
+
+    it('accepts custom timeout', () => {
+      const gate = createPushGate({ llmTimeout: 30000 });
+      expect(gate.options.llmTimeout).toBe(30000);
+    });
+  });
+
+  describe('runPushGate', () => {
+    it('runs static gate then LLM review', async () => {
+      const callOrder = [];
+      const mockStaticGate = vi.fn(async () => {
+        callOrder.push('static');
+        return { passed: true, findings: [], summary: { total: 0, block: 0, warn: 0, info: 0 } };
+      });
+      const mockLlmReview = vi.fn(async () => {
+        callOrder.push('llm');
+        return { findings: [], summary: 'Clean' };
+      });
+
+      const result = await runPushGate({
+        staticGate: mockStaticGate,
+        llmReview: mockLlmReview,
+        files: [{ path: 'src/app.js', content: 'code' }],
+      });
+
+      expect(callOrder).toEqual(['static', 'llm']);
+      expect(result.passed).toBe(true);
+    });
+
+    it('blocks immediately on static gate failure', async () => {
+      const mockStaticGate = vi.fn(async () => ({
+        passed: false,
+        findings: [{ severity: 'block', rule: 'r1', file: 'x.js', message: 'Bad', fix: 'Fix' }],
+        summary: { total: 1, block: 1, warn: 0, info: 0 },
+      }));
+      const mockLlmReview = vi.fn();
+
+      const result = await runPushGate({
+        staticGate: mockStaticGate,
+        llmReview: mockLlmReview,
+        files: [],
+      });
+
+      expect(result.passed).toBe(false);
+      expect(mockLlmReview).not.toHaveBeenCalled();
+    });
+
+    it('blocks on LLM review critical findings', async () => {
+      const mockStaticGate = vi.fn(async () => ({
+        passed: true,
+        findings: [],
+        summary: { total: 0, block: 0, warn: 0, info: 0 },
+      }));
+      const mockLlmReview = vi.fn(async () => ({
+        findings: [
+          { severity: 'block', rule: 'logic-error', file: 'x.js', message: 'Bug', fix: 'Fix' },
+        ],
+      }));
+
+      const result = await runPushGate({
+        staticGate: mockStaticGate,
+        llmReview: mockLlmReview,
+        files: [],
+      });
+
+      expect(result.passed).toBe(false);
+    });
+
+    it('handles LLM timeout gracefully', async () => {
+      const mockStaticGate = vi.fn(async () => ({
+        passed: true,
+        findings: [],
+        summary: { total: 0, block: 0, warn: 0, info: 0 },
+      }));
+      const mockLlmReview = vi.fn(async () => {
+        throw new Error('Timeout');
+      });
+
+      const result = await runPushGate({
+        staticGate: mockStaticGate,
+        llmReview: mockLlmReview,
+        files: [],
+      });
+
+      // Falls back to static-only - should pass
+      expect(result.passed).toBe(true);
+      expect(result.llmSkipped).toBe(true);
+    });
+
+    it('passes when both static and LLM pass', async () => {
+      const mockStaticGate = vi.fn(async () => ({
+        passed: true,
+        findings: [{ severity: 'warn', rule: 'r1', file: 'x.js', message: 'Minor', fix: 'Maybe' }],
+        summary: { total: 1, block: 0, warn: 1, info: 0 },
+      }));
+      const mockLlmReview = vi.fn(async () => ({
+        findings: [{ severity: 'info', rule: 'style', file: 'x.js', message: 'Style', fix: 'Format' }],
+      }));
+
+      const result = await runPushGate({
+        staticGate: mockStaticGate,
+        llmReview: mockLlmReview,
+        files: [],
+      });
+
+      expect(result.passed).toBe(true);
+    });
+
+    it('records override when TLC_GATE_OVERRIDE is set', async () => {
+      const mockStaticGate = vi.fn(async () => ({
+        passed: false,
+        findings: [{ severity: 'block', rule: 'r1', file: 'x.js', message: 'Bad', fix: 'Fix' }],
+        summary: { total: 1, block: 1, warn: 0, info: 0 },
+      }));
+
+      const result = await runPushGate({
+        staticGate: mockStaticGate,
+        llmReview: vi.fn(),
+        files: [],
+        override: true,
+      });
+
+      expect(result.passed).toBe(true);
+      expect(result.overridden).toBe(true);
+    });
+  });
+
+  describe('mergeResults', () => {
+    it('combines static and LLM findings', () => {
+      const staticResult = {
+        findings: [{ severity: 'warn', rule: 'r1', file: 'a.js', message: 'A' }],
+        summary: { total: 1, block: 0, warn: 1, info: 0 },
+      };
+      const llmResult = {
+        findings: [{ severity: 'block', rule: 'r2', file: 'b.js', message: 'B' }],
+      };
+
+      const merged = mergeResults(staticResult, llmResult);
+      expect(merged.findings).toHaveLength(2);
+      expect(merged.summary.total).toBe(2);
+      expect(merged.summary.block).toBe(1);
+      expect(merged.summary.warn).toBe(1);
+    });
+
+    it('handles null LLM result', () => {
+      const staticResult = {
+        findings: [{ severity: 'warn', rule: 'r1', file: 'a.js', message: 'A' }],
+        summary: { total: 1, block: 0, warn: 1, info: 0 },
+      };
+
+      const merged = mergeResults(staticResult, null);
+      expect(merged.findings).toHaveLength(1);
+    });
+
+    it('tags findings with source', () => {
+      const staticResult = {
+        findings: [{ severity: 'warn', rule: 'r1', file: 'a.js', message: 'A' }],
+        summary: { total: 1, block: 0, warn: 1, info: 0 },
+      };
+      const llmResult = {
+        findings: [{ severity: 'warn', rule: 'r2', file: 'b.js', message: 'B' }],
+      };
+
+      const merged = mergeResults(staticResult, llmResult);
+      expect(merged.findings[0].source).toBe('static');
+      expect(merged.findings[1].source).toBe('llm');
+    });
+  });
+});

package/server/lib/code-gate/rules/architecture-rules.js

@@ -0,0 +1,228 @@
+/**
+ * Architecture Rules
+ *
+ * Detects single-writer pattern violations, fake API calls,
+ * stale re-export files, and raw API request bypass.
+ *
+ * Derived from 34 real-world bugs in production projects.
+ * See: TLC-BEST-PRACTICES.md, WALL_OF_SHAME.md
+ *
+ * @module code-gate/rules/architecture-rules
+ */
+
+/**
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isTestFile(filePath) {
+  return /\.(test|spec)\.[jt]sx?$/.test(filePath) || filePath.includes('__tests__');
+}
+
+/**
+ * Common plural-to-singular and singular-to-plural mappings.
+ * Used to match table names to service file names.
+ * @param {string} tableName - e.g. "users", "companies"
+ * @returns {string[]} Possible service file stems
+ */
+function tableNameVariants(tableName) {
+  const variants = [tableName];
+  // Plural → singular
+  if (tableName.endsWith('ies')) {
+    variants.push(tableName.slice(0, -3) + 'y'); // companies → company
+  } else if (tableName.endsWith('ses')) {
+    variants.push(tableName.slice(0, -2)); // addresses → address (approx)
+  } else if (tableName.endsWith('s')) {
+    variants.push(tableName.slice(0, -1)); // users → user
+  }
+  // Singular → plural (for reverse matching)
+  if (!tableName.endsWith('s')) {
+    variants.push(tableName + 's');
+  }
+  return variants;
+}
+
+/**
+ * Detect db.insert(X) or db.update(X) outside the service that owns table X.
+ *
+ * The owning service is determined by file name: X.service.* or Xs.service.*
+ * This prevents the #1 architectural anti-pattern from BEST-PRACTICES.md.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array<{severity: string, rule: string, line: number, message: string, fix: string}>}
+ */
+function checkSingleWriter(filePath, content) {
+  if (isTestFile(filePath)) return [];
+  const findings = [];
+  const lines = content.split('\n');
+
+  const dbWritePattern = /\bdb\.(insert|update)\s*\(\s*(\w+)\s*\)/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*')) continue;
+
+    const match = line.match(dbWritePattern);
+    if (match) {
+      const operation = match[1];
+      const tableName = match[2];
+      const variants = tableNameVariants(tableName);
+
+      // Check if current file is the owning service
+      const fileBase = filePath.toLowerCase();
+      const isOwner = variants.some(v =>
+        fileBase.includes(`${v}.service`) || fileBase.includes(`${v}s.service`)
+      );
+
+      if (!isOwner) {
+        findings.push({
+          severity: 'block',
+          rule: 'single-writer',
+          line: i + 1,
+          message: `db.${operation}(${tableName}) outside owning service — violates single-writer pattern`,
+          fix: `Move this write to the ${tableName} service file (e.g. ${variants[0]}.service.ts)`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect setTimeout + resolve patterns that fake API calls.
+ * AI code generators use this to simulate async behavior instead
+ * of making real API calls.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array}
+ */
+function checkFakeApiCalls(filePath, content) {
+  if (isTestFile(filePath)) return [];
+  const findings = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*')) continue;
+
+    // setTimeout(() => resolve(...), number)
+    if (/setTimeout\s*\(\s*\(\)\s*=>\s*resolve\s*\(/.test(line)) {
+      findings.push({
+        severity: 'block',
+        rule: 'no-fake-api',
+        line: i + 1,
+        message: 'Fake API call using setTimeout + resolve — use a real API endpoint',
+        fix: 'Replace with actual API call using fetch() or an API client',
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect files that contain only a re-export statement.
+ * These accumulate as backwards-compatibility shims and become dead code.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array}
+ */
+function checkStaleReexports(filePath, content) {
+  const trimmed = content.trim();
+  if (!trimmed) return [];
+
+  // Strip comments
+  const stripped = trimmed
+    .replace(/\/\/.*$/gm, '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .trim();
+
+  // CommonJS re-export only
+  if (/^module\.exports\s*=\s*require\s*\([^)]+\)\s*;?\s*$/.test(stripped)) {
+    return [{
+      severity: 'warn',
+      rule: 'stale-reexport',
+      line: 1,
+      message: 'File contains only a re-export — likely a deprecated shim',
+      fix: 'Update all imports to point to the new location and delete this file',
+    }];
+  }
+
+  // ESM re-export only
+  if (/^export\s*\{[^}]*\}\s*from\s*['"][^'"]+['"]\s*;?\s*$/.test(stripped)) {
+    return [{
+      severity: 'warn',
+      rule: 'stale-reexport',
+      line: 1,
+      message: 'File contains only a re-export — likely a deprecated shim',
+      fix: 'Update all imports to point to the new location and delete this file',
+    }];
+  }
+
+  return [];
+}
+
+/**
+ * Detect raw apiRequest() or fetch('/api/...') calls in UI components.
+ * When API helpers exist (companiesApi.create, leadsApi.update),
+ * using raw requests bypasses shared logic.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array}
+ */
+function checkRawApiRequests(filePath, content) {
+  if (isTestFile(filePath)) return [];
+
+  // Skip API helper files themselves
+  const fileBase = filePath.toLowerCase();
+  if (fileBase.includes('/api.') || fileBase.includes('/api/') ||
+      fileBase.endsWith('api.ts') || fileBase.endsWith('api.js')) {
+    return [];
+  }
+
+  const findings = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*')) continue;
+
+    // apiRequest("METHOD", "/api/...")
+    if (/apiRequest\s*\(\s*['"`](?:GET|POST|PUT|PATCH|DELETE)['"`]\s*,\s*['"`]\/api\//.test(line)) {
+      findings.push({
+        severity: 'warn',
+        rule: 'no-raw-api',
+        line: i + 1,
+        message: 'Raw apiRequest() call — use entity-specific API helper instead',
+        fix: 'Use the shared API helper (e.g. companiesApi.create()) for type safety and consistency',
+      });
+    }
+
+    // fetch("/api/...")
+    if (/fetch\s*\(\s*['"`]\/api\//.test(line)) {
+      findings.push({
+        severity: 'warn',
+        rule: 'no-raw-api',
+        line: i + 1,
+        message: 'Raw fetch() to /api/ — use entity-specific API helper instead',
+        fix: 'Use the shared API helper for centralized error handling and auth',
+      });
+    }
+  }
+
+  return findings;
+}
+
+module.exports = {
+  checkSingleWriter,
+  checkFakeApiCalls,
+  checkStaleReexports,
+  checkRawApiRequests,
+};