tlc-claude-code 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc": "./bin/tlc.js",

package/server/lib/code-gate/first-commit-audit.js

@@ -0,0 +1,138 @@
+/**
+ * First-Commit Audit Hook
+ *
+ * Auto-runs architectural audit on first commit to catch
+ * AI-generated code issues before they accumulate.
+ * The "2-hour audit on day 1 saves 10 days" lesson.
+ *
+ * @module code-gate/first-commit-audit
+ */
+
+const path = require('path');
+const defaultFs = require('fs').promises;
+
+/** Marker file path relative to project root */
+const MARKER_FILE = '.tlc/first-audit-done';
+
+/** Fix suggestions by audit issue type */
+const FIX_SUGGESTIONS = {
+  'hardcoded-url': 'Extract to environment variable using process.env',
+  'hardcoded-port': 'Extract port to environment variable',
+  'flat-folder': 'Reorganize into entity-based folder structure (src/{entity}/)',
+  'inline-interface': 'Extract interface to separate types file',
+  'magic-string': 'Replace with named constant',
+  'flat-seeds': 'Move seeds into per-entity seed folders',
+  'missing-jsdoc': 'Add JSDoc comment to exported function',
+  'deep-import': 'Use path aliases or restructure to reduce nesting',
+  'missing': 'Create required standards file',
+};
+
+/**
+ * Check if the first audit has already run
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Object} options.fs - File system module
+ * @returns {Promise<boolean>} True if marker exists
+ */
+async function hasFirstAuditRun(projectPath, options = {}) {
+  const fsModule = options.fs || defaultFs;
+  const markerPath = path.join(projectPath, MARKER_FILE);
+  try {
+    await fsModule.access(markerPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Convert audit results to gate findings
+ * @param {Object} auditResults - Results from auditProject()
+ * @returns {Array<Object>} Gate findings with severity: warn
+ */
+function convertAuditToFindings(auditResults) {
+  const findings = [];
+
+  const categories = [
+    'standardsFiles', 'flatFolders', 'inlineInterfaces',
+    'hardcodedUrls', 'magicStrings', 'seedOrganization',
+    'jsDocCoverage', 'importStyle',
+  ];
+
+  for (const category of categories) {
+    const result = auditResults[category];
+    if (!result || !result.issues) continue;
+
+    for (const issue of result.issues) {
+      findings.push({
+        severity: 'warn',
+        rule: `first-audit/${issue.type}`,
+        file: issue.file || issue.folder || 'project',
+        line: 0,
+        message: `First-commit audit: ${issue.type}${issue.value ? ` (${issue.value})` : ''}`,
+        fix: FIX_SUGGESTIONS[issue.type] || 'Review and fix manually',
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Run the first-commit audit
+ * @param {string} projectPath - Path to project root
+ * @param {Object} options - Injectable dependencies
+ * @param {Object} options.fs - File system module
+ * @param {Function} options.auditProject - Audit function from audit-checker
+ * @param {Object} options.config - Gate config
+ * @returns {Promise<Object>} Result with findings or skipped flag
+ */
+async function runFirstCommitAudit(projectPath, options = {}) {
+  const fsModule = options.fs || defaultFs;
+  const { auditProject, config } = options;
+
+  // Check if disabled via config
+  if (config && config.firstCommitAudit === false) {
+    return { skipped: true, reason: 'disabled' };
+  }
+
+  // Check if already run
+  const alreadyRun = await hasFirstAuditRun(projectPath, { fs: fsModule });
+  if (alreadyRun) {
+    return { skipped: true, reason: 'already-run' };
+  }
+
+  // Run audit
+  const auditResults = await auditProject(projectPath, { fs: fsModule });
+  const findings = convertAuditToFindings(auditResults);
+
+  // Create marker file
+  const markerPath = path.join(projectPath, MARKER_FILE);
+  const markerDir = path.dirname(markerPath);
+  await fsModule.mkdir(markerDir, { recursive: true });
+  await fsModule.writeFile(markerPath, `First audit completed at ${new Date().toISOString()}\n`);
+
+  return {
+    skipped: false,
+    findings,
+    auditResults,
+  };
+}
+
+/**
+ * Create a first-commit audit instance with dependencies
+ * @param {Object} deps - Injectable dependencies
+ * @returns {Object} Audit instance with run method
+ */
+function createFirstCommitAudit(deps = {}) {
+  return {
+    run: (projectPath, config) => runFirstCommitAudit(projectPath, { ...deps, config }),
+  };
+}
+
+module.exports = {
+  createFirstCommitAudit,
+  hasFirstAuditRun,
+  convertAuditToFindings,
+  runFirstCommitAudit,
+};

package/server/lib/code-gate/first-commit-audit.test.js

@@ -0,0 +1,203 @@
+/**
+ * First-Commit Audit Hook Tests
+ *
+ * Auto-runs architectural audit on first commit to catch
+ * AI-generated code issues before they accumulate.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  createFirstCommitAudit,
+  hasFirstAuditRun,
+  convertAuditToFindings,
+  runFirstCommitAudit,
+} = require('./first-commit-audit.js');
+
+describe('First-Commit Audit Hook', () => {
+  describe('hasFirstAuditRun', () => {
+    it('returns false when no marker exists', async () => {
+      const mockFs = {
+        access: vi.fn().mockRejectedValue(new Error('ENOENT')),
+      };
+      const result = await hasFirstAuditRun('/project', { fs: mockFs });
+      expect(result).toBe(false);
+    });
+
+    it('returns true when marker exists', async () => {
+      const mockFs = {
+        access: vi.fn().mockResolvedValue(undefined),
+      };
+      const result = await hasFirstAuditRun('/project', { fs: mockFs });
+      expect(result).toBe(true);
+    });
+  });
+
+  describe('convertAuditToFindings', () => {
+    it('converts audit issues to gate findings with severity warn', () => {
+      const auditResults = {
+        hardcodedUrls: {
+          passed: false,
+          issues: [
+            { type: 'hardcoded-url', file: 'src/api.js', value: 'http://localhost:3000' },
+          ],
+        },
+        flatFolders: {
+          passed: false,
+          issues: [
+            { type: 'flat-folder', folder: 'services' },
+          ],
+        },
+        summary: { totalIssues: 2, passed: false },
+      };
+
+      const findings = convertAuditToFindings(auditResults);
+      expect(findings).toHaveLength(2);
+      expect(findings[0].severity).toBe('warn');
+      expect(findings[1].severity).toBe('warn');
+    });
+
+    it('returns correct severity for all findings', () => {
+      const auditResults = {
+        magicStrings: {
+          passed: false,
+          issues: [
+            { type: 'magic-string', file: 'src/auth.js', value: 'admin' },
+          ],
+        },
+        summary: { totalIssues: 1, passed: false },
+      };
+
+      const findings = convertAuditToFindings(auditResults);
+      expect(findings.every(f => f.severity === 'warn')).toBe(true);
+    });
+
+    it('includes fix suggestions from audit', () => {
+      const auditResults = {
+        hardcodedUrls: {
+          passed: false,
+          issues: [
+            { type: 'hardcoded-url', file: 'src/api.js', value: 'http://localhost:3000' },
+          ],
+        },
+        summary: { totalIssues: 1, passed: false },
+      };
+
+      const findings = convertAuditToFindings(auditResults);
+      expect(findings[0].fix).toBeDefined();
+      expect(findings[0].fix.length).toBeGreaterThan(0);
+    });
+
+    it('returns empty array for clean audit', () => {
+      const auditResults = {
+        hardcodedUrls: { passed: true, issues: [] },
+        flatFolders: { passed: true, issues: [] },
+        summary: { totalIssues: 0, passed: true },
+      };
+
+      const findings = convertAuditToFindings(auditResults);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('handles multiple issues from same category', () => {
+      const auditResults = {
+        hardcodedUrls: {
+          passed: false,
+          issues: [
+            { type: 'hardcoded-url', file: 'src/api.js', value: 'http://localhost:3000' },
+            { type: 'hardcoded-url', file: 'src/config.js', value: 'http://localhost:5000' },
+            { type: 'hardcoded-port', file: 'src/server.js', value: '8080' },
+          ],
+        },
+        summary: { totalIssues: 3, passed: false },
+      };
+
+      const findings = convertAuditToFindings(auditResults);
+      expect(findings).toHaveLength(3);
+    });
+  });
+
+  describe('runFirstCommitAudit', () => {
+    it('runs audit when no marker exists', async () => {
+      const mockFs = {
+        access: vi.fn().mockRejectedValue(new Error('ENOENT')),
+        mkdir: vi.fn().mockResolvedValue(undefined),
+        writeFile: vi.fn().mockResolvedValue(undefined),
+      };
+      const mockAuditProject = vi.fn().mockResolvedValue({
+        hardcodedUrls: { passed: true, issues: [] },
+        summary: { totalIssues: 0, passed: true },
+      });
+
+      const result = await runFirstCommitAudit('/project', {
+        fs: mockFs,
+        auditProject: mockAuditProject,
+      });
+
+      expect(mockAuditProject).toHaveBeenCalledWith('/project', { fs: mockFs });
+      expect(result.findings).toBeDefined();
+    });
+
+    it('skips audit when marker exists', async () => {
+      const mockFs = {
+        access: vi.fn().mockResolvedValue(undefined),
+      };
+      const mockAuditProject = vi.fn();
+
+      const result = await runFirstCommitAudit('/project', {
+        fs: mockFs,
+        auditProject: mockAuditProject,
+      });
+
+      expect(mockAuditProject).not.toHaveBeenCalled();
+      expect(result.skipped).toBe(true);
+    });
+
+    it('creates marker after successful run', async () => {
+      const mockFs = {
+        access: vi.fn().mockRejectedValue(new Error('ENOENT')),
+        mkdir: vi.fn().mockResolvedValue(undefined),
+        writeFile: vi.fn().mockResolvedValue(undefined),
+      };
+      const mockAuditProject = vi.fn().mockResolvedValue({
+        summary: { totalIssues: 0, passed: true },
+      });
+
+      await runFirstCommitAudit('/project', {
+        fs: mockFs,
+        auditProject: mockAuditProject,
+      });
+
+      expect(mockFs.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining('first-audit-done'),
+        expect.any(String)
+      );
+    });
+
+    it('respects enabled/disabled config', async () => {
+      const mockFs = {
+        access: vi.fn().mockRejectedValue(new Error('ENOENT')),
+      };
+      const mockAuditProject = vi.fn();
+
+      const result = await runFirstCommitAudit('/project', {
+        fs: mockFs,
+        auditProject: mockAuditProject,
+        config: { firstCommitAudit: false },
+      });
+
+      expect(mockAuditProject).not.toHaveBeenCalled();
+      expect(result.skipped).toBe(true);
+    });
+  });
+
+  describe('createFirstCommitAudit', () => {
+    it('works with injectable dependencies', () => {
+      const audit = createFirstCommitAudit({
+        fs: {},
+        auditProject: vi.fn(),
+      });
+      expect(audit).toBeDefined();
+      expect(audit.run).toBeDefined();
+    });
+  });
+});

package/server/lib/code-gate/multi-model-reviewer.js

@@ -0,0 +1,172 @@
+/**
+ * Multi-Model Reviewer
+ *
+ * Sends code reviews to 2+ LLM models and aggregates findings.
+ * Different models catch different bugs — consensus scoring
+ * highlights issues multiple models agree on.
+ *
+ * @module code-gate/multi-model-reviewer
+ */
+
+/** Severity priority for conflict resolution (higher wins) */
+const SEVERITY_PRIORITY = { block: 3, warn: 2, info: 1 };
+
+/**
+ * Send diff to multiple models in parallel
+ * @param {string} diff - Git diff content
+ * @param {string[]} models - List of model names
+ * @param {Object} options - Options
+ * @param {Function} options.reviewFn - Function(diff, model) => { findings, summary }
+ * @param {number} options.timeout - Per-model timeout in ms
+ * @returns {Promise<Array>} Results from successful models
+ */
+async function sendToModels(diff, models, options = {}) {
+  const { reviewFn, timeout } = options;
+  const results = [];
+
+  const promises = models.map(async (model) => {
+    try {
+      let reviewPromise = reviewFn(diff, model);
+
+      // Apply per-model timeout if specified
+      if (timeout) {
+        reviewPromise = Promise.race([
+          reviewPromise,
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error(`Timeout for ${model}`)), timeout)
+          ),
+        ]);
+      }
+
+      const result = await reviewPromise;
+      return { model, ...result };
+    } catch {
+      return null; // Model failed, will be filtered out
+    }
+  });
+
+  const settled = await Promise.all(promises);
+  for (const result of settled) {
+    if (result) results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Aggregate and deduplicate findings from multiple models
+ * @param {Array} modelResults - Results from sendToModels
+ * @returns {Object} Aggregated result with deduplicated findings
+ */
+function aggregateFindings(modelResults) {
+  // Collect all findings with model attribution
+  const allFindings = [];
+
+  for (const result of modelResults) {
+    for (const finding of (result.findings || [])) {
+      allFindings.push({
+        ...finding,
+        flaggedBy: [result.model],
+      });
+    }
+  }
+
+  // Deduplicate
+  const deduped = deduplicateFindings(allFindings);
+
+  return {
+    findings: deduped,
+    modelCount: modelResults.length,
+  };
+}
+
+/**
+ * Deduplicate findings by file+line+rule, merging flaggedBy lists
+ * @param {Array} findings - All findings with flaggedBy
+ * @returns {Array} Deduplicated findings
+ */
+function deduplicateFindings(findings) {
+  const map = new Map();
+
+  for (const finding of findings) {
+    const key = `${finding.file}:${finding.line}:${finding.rule}`;
+
+    if (map.has(key)) {
+      const existing = map.get(key);
+      // Merge flaggedBy
+      for (const model of finding.flaggedBy) {
+        if (!existing.flaggedBy.includes(model)) {
+          existing.flaggedBy.push(model);
+        }
+      }
+      // Higher severity wins
+      const existingPriority = SEVERITY_PRIORITY[existing.severity] || 0;
+      const newPriority = SEVERITY_PRIORITY[finding.severity] || 0;
+      if (newPriority > existingPriority) {
+        existing.severity = finding.severity;
+        existing.message = finding.message;
+      }
+    } else {
+      map.set(key, { ...finding });
+    }
+  }
+
+  return Array.from(map.values());
+}
+
+/**
+ * Calculate consensus percentage for a finding
+ * @param {Object} finding - Finding with flaggedBy array
+ * @param {number} totalModels - Total models queried
+ * @returns {number} Consensus percentage (0-100)
+ */
+function calculateConsensus(finding, totalModels) {
+  if (totalModels === 0) return 0;
+  return (finding.flaggedBy.length / totalModels) * 100;
+}
+
+/**
+ * Merge summaries from all model results
+ * @param {Array} modelResults - Results with model and summary fields
+ * @returns {string} Merged summary
+ */
+function mergeSummaries(modelResults) {
+  return modelResults
+    .filter(r => r.summary)
+    .map(r => `[${r.model}]: ${r.summary}`)
+    .join('\n');
+}
+
+/**
+ * Create a multi-model reviewer instance
+ * @param {Object} options - Configuration
+ * @param {string[]} options.models - Model names to use
+ * @param {Function} options.reviewFn - Review function
+ * @param {number} options.timeout - Per-model timeout
+ * @returns {Object} Reviewer instance
+ */
+function createMultiModelReviewer(options = {}) {
+  const { models = [], reviewFn, timeout } = options;
+
+  return {
+    models,
+    review: async (diff) => {
+      const results = await sendToModels(diff, models, { reviewFn, timeout });
+      if (results.length === 0) {
+        return { findings: [], summary: 'All models failed — static-only fallback', modelCount: 0 };
+      }
+      const aggregated = aggregateFindings(results);
+      const summary = mergeSummaries(results);
+      return { ...aggregated, summary };
+    },
+  };
+}
+
+module.exports = {
+  createMultiModelReviewer,
+  sendToModels,
+  aggregateFindings,
+  deduplicateFindings,
+  calculateConsensus,
+  mergeSummaries,
+};