tlc-claude-code 1.6.4 → 1.8.0

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,
+};

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

@@ -0,0 +1,155 @@
+/**
+ * Architecture Rules Tests
+ *
+ * Detects single-writer violations, fake API calls,
+ * stale re-exports, and raw API bypass patterns.
+ */
+import { describe, it, expect } from 'vitest';
+
+const {
+  checkSingleWriter,
+  checkFakeApiCalls,
+  checkStaleReexports,
+  checkRawApiRequests,
+} = require('./architecture-rules.js');
+
+describe('Architecture Rules', () => {
+  describe('checkSingleWriter', () => {
+    it('detects db.insert(users) outside users.service', () => {
+      const findings = checkSingleWriter(
+        'src/leads/leads.service.ts',
+        'const result = await db.insert(users).values(data);'
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0].severity).toBe('block');
+      expect(findings[0].rule).toBe('single-writer');
+      expect(findings[0].message).toContain('users');
+    });
+
+    it('passes when inside correct service file', () => {
+      const findings = checkSingleWriter(
+        'src/users/users.service.ts',
+        'const result = await db.insert(users).values(data);'
+      );
+      expect(findings).toHaveLength(0);
+    });
+
+    it('detects db.update(companies) outside company.service', () => {
+      const findings = checkSingleWriter(
+        'src/api/controller.ts',
+        'await db.update(companies).set({ status: "active" });'
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0].message).toContain('companies');
+    });
+
+    it('handles singular service name for plural table', () => {
+      // company.service.ts should be allowed to write to companies table
+      const findings = checkSingleWriter(
+        'src/company/company.service.ts',
+        'await db.insert(companies).values(data);'
+      );
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips test files', () => {
+      const findings = checkSingleWriter(
+        'src/api/controller.test.ts',
+        'await db.insert(users).values(data);'
+      );
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('checkFakeApiCalls', () => {
+    it('detects setTimeout + resolve mock pattern', () => {
+      const code = `
+        function getUsers() {
+          return new Promise((resolve) => {
+            setTimeout(() => resolve([{ id: 1, name: 'Test' }]), 500);
+          });
+        }
+      `;
+      const findings = checkFakeApiCalls('src/api/users.ts', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].severity).toBe('block');
+      expect(findings[0].rule).toBe('no-fake-api');
+    });
+
+    it('allows real setTimeout with function callback', () => {
+      const code = `
+        setTimeout(() => {
+          refreshDashboard();
+        }, 1000);
+      `;
+      const findings = checkFakeApiCalls('src/ui/dashboard.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips test files', () => {
+      const code = 'setTimeout(() => resolve(mockData), 500);';
+      const findings = checkFakeApiCalls('src/api/users.test.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('checkStaleReexports', () => {
+    it('detects file with only module.exports = require(...)', () => {
+      const code = "module.exports = require('./new-location');";
+      const findings = checkStaleReexports('src/old-module.js', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].severity).toBe('warn');
+      expect(findings[0].rule).toBe('stale-reexport');
+    });
+
+    it('passes file with real logic alongside export', () => {
+      const code = `
+        const helper = require('./utils');
+        function doWork() { return helper.process(); }
+        module.exports = { doWork };
+      `;
+      const findings = checkStaleReexports('src/module.js', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('detects export default re-export', () => {
+      const code = "export { default } from './new-location';";
+      const findings = checkStaleReexports('src/old-module.ts', code);
+      expect(findings).toHaveLength(1);
+    });
+  });
+
+  describe('checkRawApiRequests', () => {
+    it('detects apiRequest("POST", "/api/...")', () => {
+      const code = 'const result = await apiRequest("POST", "/api/companies", data);';
+      const findings = checkRawApiRequests('src/components/form.tsx', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].severity).toBe('warn');
+      expect(findings[0].rule).toBe('no-raw-api');
+    });
+
+    it('detects raw fetch("/api/...")', () => {
+      const code = 'const res = await fetch("/api/leads", { method: "POST" });';
+      const findings = checkRawApiRequests('src/components/leads.tsx', code);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('allows non-API fetch calls', () => {
+      const code = 'const res = await fetch("https://cdn.example.com/data.json");';
+      const findings = checkRawApiRequests('src/utils/loader.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('allows fetch in API helper files', () => {
+      const code = 'const res = await fetch("/api/companies");';
+      const findings = checkRawApiRequests('src/lib/api.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips test files', () => {
+      const code = 'await apiRequest("POST", "/api/test", data);';
+      const findings = checkRawApiRequests('src/components/form.test.tsx', code);
+      expect(findings).toHaveLength(0);
+    });
+  });
+});

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

@@ -0,0 +1,120 @@
+/**
+ * Client-Side Pattern Rules
+ *
+ * Detects Zustand stores without persistence middleware
+ * and Zod schemas using z.date() instead of z.coerce.date().
+ *
+ * Derived from Bug #13 (state lost on refresh) and Bug #12 (date coercion).
+ *
+ * @module code-gate/rules/client-rules
+ */
+
+/**
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isTestFile(filePath) {
+  return /\.(test|spec)\.[jt]sx?$/.test(filePath) || filePath.includes('__tests__');
+}
+
+/** Store names that are intentionally ephemeral (UI state, not data) */
+const EPHEMERAL_PATTERNS = [
+  'ui-store', 'ui.store', 'uiStore',
+  'modal-store', 'modalStore',
+  'toast-store', 'toastStore',
+  'theme-store', 'themeStore',
+];
+
+/**
+ * Detect Zustand create() without persist middleware.
+ * Stores that hold user data should use persist() to survive page refreshes.
+ * UI-only stores (modals, toasts) are exempt.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array<{severity: string, rule: string, line: number, message: string, fix: string}>}
+ */
+function checkZustandPersistence(filePath, content) {
+  if (isTestFile(filePath)) return [];
+
+  // Only check store files
+  if (!filePath.includes('store')) return [];
+
+  // Skip ephemeral stores (UI state)
+  const fileBase = filePath.toLowerCase();
+  if (EPHEMERAL_PATTERNS.some(p => fileBase.includes(p))) return [];
+
+  // Check if file imports/uses zustand create
+  const hasZustandCreate = /\bcreate\s*[<(]/.test(content) &&
+    (content.includes("from 'zustand'") || content.includes('from "zustand"') ||
+     content.includes("require('zustand')") || content.includes('require("zustand")'));
+
+  if (!hasZustandCreate) return [];
+
+  // Check if persist is used
+  const hasPersist = content.includes('persist(') || content.includes('persist<');
+
+  if (!hasPersist) {
+    const findings = [];
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (/\bcreate\s*[<(]/.test(lines[i])) {
+        findings.push({
+          severity: 'warn',
+          rule: 'zustand-needs-persist',
+          line: i + 1,
+          message: 'Zustand store without persist middleware — state lost on page refresh',
+          fix: "Wrap with persist(): create(persist((set) => ({...}), { name: 'store-name' }))",
+        });
+        break;
+      }
+    }
+    return findings;
+  }
+
+  return [];
+}
+
+/**
+ * Detect z.date() in schema files that should use z.coerce.date().
+ * When API clients send ISO strings, z.date() rejects them.
+ * z.coerce.date() handles both Date objects and ISO strings.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array}
+ */
+function checkZodDateCoercion(filePath, content) {
+  if (isTestFile(filePath)) return [];
+
+  // Only check schema-related files
+  const fileBase = filePath.toLowerCase();
+  if (!fileBase.includes('schema') && !fileBase.includes('schemas')) 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;
+
+    // z.date() without coerce
+    if (/z\.date\s*\(/.test(line) && !line.includes('z.coerce.date')) {
+      findings.push({
+        severity: 'warn',
+        rule: 'zod-use-coerce-date',
+        line: i + 1,
+        message: 'z.date() rejects ISO strings from API clients — use z.coerce.date()',
+        fix: 'Replace z.date() with z.coerce.date() to accept both Date objects and ISO strings',
+      });
+    }
+  }
+
+  return findings;
+}
+
+module.exports = {
+  checkZustandPersistence,
+  checkZodDateCoercion,
+};

package/server/lib/code-gate/rules/client-rules.test.js

@@ -0,0 +1,121 @@
+/**
+ * Client-Side Pattern Rules Tests
+ *
+ * Detects Zustand stores without persistence and
+ * Zod schemas with z.date() instead of z.coerce.date().
+ */
+import { describe, it, expect } from 'vitest';
+
+const {
+  checkZustandPersistence,
+  checkZodDateCoercion,
+} = require('./client-rules.js');
+
+describe('Client Rules', () => {
+  describe('checkZustandPersistence', () => {
+    it('detects create() without persist', () => {
+      const code = `
+        import { create } from 'zustand';
+        const useFormStore = create((set) => ({
+          data: null,
+          setData: (data) => set({ data }),
+        }));
+      `;
+      const findings = checkZustandPersistence('src/stores/form-store.ts', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].severity).toBe('warn');
+      expect(findings[0].rule).toBe('zustand-needs-persist');
+    });
+
+    it('passes create(persist(...))', () => {
+      const code = `
+        import { create } from 'zustand';
+        import { persist } from 'zustand/middleware';
+        const useFormStore = create(persist((set) => ({
+          data: null,
+        }), { name: 'form-store' }));
+      `;
+      const findings = checkZustandPersistence('src/stores/form-store.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('allows stores in ephemeral files', () => {
+      const code = `
+        import { create } from 'zustand';
+        const useUIStore = create((set) => ({ open: false }));
+      `;
+      const findings = checkZustandPersistence('src/stores/ui-store.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips test files', () => {
+      const code = `
+        import { create } from 'zustand';
+        const useTestStore = create((set) => ({ x: 1 }));
+      `;
+      const findings = checkZustandPersistence('src/stores/form.test.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('handles create<Type>() generic syntax', () => {
+      const code = `
+        import { create } from 'zustand';
+        interface FormState { data: string | null; }
+        const useFormStore = create<FormState>((set) => ({
+          data: null,
+        }));
+      `;
+      const findings = checkZustandPersistence('src/stores/form-store.ts', code);
+      expect(findings).toHaveLength(1);
+    });
+  });
+
+  describe('checkZodDateCoercion', () => {
+    it('detects z.date() in schema files', () => {
+      const code = `
+        const insertLeadSchema = z.object({
+          name: z.string(),
+          createdAt: z.date(),
+        });
+      `;
+      const findings = checkZodDateCoercion('src/db/schema/leads.ts', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].severity).toBe('warn');
+      expect(findings[0].rule).toBe('zod-use-coerce-date');
+    });
+
+    it('passes z.coerce.date()', () => {
+      const code = `
+        const insertLeadSchema = z.object({
+          name: z.string(),
+          createdAt: z.coerce.date(),
+        });
+      `;
+      const findings = checkZodDateCoercion('src/db/schema/leads.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('allows z.date() in non-schema files', () => {
+      const code = 'const validator = z.date();';
+      const findings = checkZodDateCoercion('src/utils/helpers.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips test files', () => {
+      const code = 'const schema = z.object({ at: z.date() });';
+      const findings = checkZodDateCoercion('src/db/schema/leads.test.ts', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('detects in insertSchema definitions', () => {
+      const code = `
+        export const insertQuoteSchema = z.object({
+          validUntil: z.date(),
+          amount: z.number(),
+        });
+      `;
+      const findings = checkZodDateCoercion('server/schemas/quotes.ts', code);
+      expect(findings).toHaveLength(1);
+    });
+  });
+});