tlc-claude-code 1.6.4 → 1.7.0

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

@@ -0,0 +1,159 @@
+/**
+ * Gate Reporter Tests
+ *
+ * Formats gate results into clear, actionable terminal output
+ * with severity badges, fix suggestions, and summary.
+ */
+import { describe, it, expect } from 'vitest';
+
+const {
+  formatReport,
+  formatSummary,
+  formatFinding,
+  groupByFile,
+} = require('./gate-reporter.js');
+
+describe('Gate Reporter', () => {
+  describe('formatFinding', () => {
+    it('formats a block finding with line number', () => {
+      const finding = {
+        severity: 'block',
+        rule: 'no-eval',
+        file: 'src/app.js',
+        line: 12,
+        message: "eval() is not allowed",
+        fix: 'Use a safe alternative',
+      };
+      const output = formatFinding(finding);
+      expect(output).toContain('[BLOCK]');
+      expect(output).toContain('no-eval');
+      expect(output).toContain('line 12');
+      expect(output).toContain('eval()');
+      expect(output).toContain('Use a safe alternative');
+    });
+
+    it('formats a warn finding', () => {
+      const finding = {
+        severity: 'warn',
+        rule: 'max-function-length',
+        file: 'src/big.js',
+        line: 45,
+        message: 'Function too long',
+        fix: 'Extract helper functions',
+      };
+      const output = formatFinding(finding);
+      expect(output).toContain('[WARN]');
+    });
+
+    it('formats info finding', () => {
+      const finding = {
+        severity: 'info',
+        rule: 'docs-hint',
+        file: 'src/x.js',
+        message: 'Consider adding docs',
+        fix: 'Add JSDoc',
+      };
+      const output = formatFinding(finding);
+      expect(output).toContain('[INFO]');
+    });
+
+    it('handles finding without line number', () => {
+      const finding = {
+        severity: 'block',
+        rule: 'require-test-file',
+        file: 'src/x.js',
+        message: 'No test file found',
+        fix: 'Create test file',
+      };
+      const output = formatFinding(finding);
+      expect(output).not.toContain('line');
+    });
+  });
+
+  describe('groupByFile', () => {
+    it('groups findings by file path', () => {
+      const findings = [
+        { file: 'a.js', rule: 'r1', severity: 'block', message: 'A' },
+        { file: 'b.js', rule: 'r2', severity: 'warn', message: 'B' },
+        { file: 'a.js', rule: 'r3', severity: 'info', message: 'C' },
+      ];
+      const groups = groupByFile(findings);
+      expect(Object.keys(groups)).toHaveLength(2);
+      expect(groups['a.js']).toHaveLength(2);
+      expect(groups['b.js']).toHaveLength(1);
+    });
+  });
+
+  describe('formatSummary', () => {
+    it('shows blocking count and pass status', () => {
+      const summary = { total: 0, block: 0, warn: 0, info: 0 };
+      const output = formatSummary(summary, true);
+      expect(output).toContain('passed');
+    });
+
+    it('shows blocking message when blocked', () => {
+      const summary = { total: 3, block: 2, warn: 1, info: 0 };
+      const output = formatSummary(summary, false);
+      expect(output).toContain('2 blocking');
+      expect(output).toContain('1 warning');
+      expect(output).toContain('blocked');
+    });
+  });
+
+  describe('formatReport', () => {
+    it('formats complete report with header', () => {
+      const result = {
+        passed: false,
+        findings: [
+          { file: 'src/app.js', severity: 'block', rule: 'no-eval', line: 5, message: 'eval found', fix: 'Remove eval' },
+        ],
+        summary: { total: 1, block: 1, warn: 0, info: 0 },
+      };
+      const output = formatReport(result);
+      expect(output).toContain('Code Gate');
+      expect(output).toContain('src/app.js');
+      expect(output).toContain('[BLOCK]');
+      expect(output).toContain('blocked');
+    });
+
+    it('formats all-clear report', () => {
+      const result = {
+        passed: true,
+        findings: [],
+        summary: { total: 0, block: 0, warn: 0, info: 0 },
+      };
+      const output = formatReport(result);
+      expect(output).toContain('passed');
+    });
+
+    it('groups findings by file in report', () => {
+      const result = {
+        passed: false,
+        findings: [
+          { file: 'a.js', severity: 'block', rule: 'r1', message: 'X', fix: 'Y' },
+          { file: 'b.js', severity: 'block', rule: 'r2', message: 'X', fix: 'Y' },
+          { file: 'a.js', severity: 'warn', rule: 'r3', message: 'X', fix: 'Y' },
+        ],
+        summary: { total: 3, block: 2, warn: 1, info: 0 },
+      };
+      const output = formatReport(result);
+      // a.js should appear before its findings
+      const aIndex = output.indexOf('a.js');
+      const bIndex = output.indexOf('b.js');
+      expect(aIndex).toBeGreaterThan(-1);
+      expect(bIndex).toBeGreaterThan(-1);
+    });
+
+    it('includes bypass hint in blocked report', () => {
+      const result = {
+        passed: false,
+        findings: [
+          { file: 'x.js', severity: 'block', rule: 'r1', message: 'Bad', fix: 'Fix' },
+        ],
+        summary: { total: 1, block: 1, warn: 0, info: 0 },
+      };
+      const output = formatReport(result);
+      expect(output).toContain('--no-verify');
+    });
+  });
+});

package/server/lib/code-gate/hooks-generator.js

@@ -0,0 +1,149 @@
+/**
+ * Hooks Generator
+ *
+ * Generates and installs git hooks that run the TLC code gate.
+ * Hooks are portable sh scripts (not bash-specific).
+ *
+ * @module code-gate/hooks-generator
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/** Marker comment to identify TLC-generated hooks */
+const TLC_HOOK_MARKER = '# TLC Code Gate';
+
+/**
+ * Generate a pre-commit hook script.
+ * Runs fast static analysis (< 3s) on staged files.
+ *
+ * @returns {string} Shell script content
+ */
+function generatePreCommitHook() {
+  return `#!/bin/sh
+${TLC_HOOK_MARKER} — pre-commit
+# Runs static code gate on staged files.
+# To bypass: git commit --no-verify (bypass is logged)
+
+# Get the project root
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+
+# Run the TLC gate check on staged files
+if command -v node > /dev/null 2>&1; then
+  node "$PROJECT_ROOT/node_modules/.bin/tlc-gate" check --hook pre-commit
+  EXIT_CODE=$?
+
+  if [ $EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Commit blocked by TLC Code Gate."
+    echo "Fix the issues above or use: git commit --no-verify"
+    exit 1
+  fi
+else
+  echo "Warning: Node.js not found. Skipping TLC Code Gate."
+fi
+
+exit 0
+`;
+}
+
+/**
+ * Generate a pre-push hook script.
+ * Runs full analysis including LLM-powered review.
+ *
+ * @returns {string} Shell script content
+ */
+function generatePrePushHook() {
+  return `#!/bin/sh
+${TLC_HOOK_MARKER} — pre-push
+# Runs full code gate including LLM review before push.
+# To bypass: git push --no-verify (bypass is logged)
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+
+if command -v node > /dev/null 2>&1; then
+  node "$PROJECT_ROOT/node_modules/.bin/tlc-gate" check --hook pre-push --full
+  EXIT_CODE=$?
+
+  if [ $EXIT_CODE -ne 0 ]; then
+    echo ""
+    echo "Push blocked by TLC Code Gate."
+    echo "Fix the issues above or use: git push --no-verify"
+    exit 1
+  fi
+else
+  echo "Warning: Node.js not found. Skipping TLC Code Gate."
+fi
+
+exit 0
+`;
+}
+
+/**
+ * Install git hooks into the project's .git/hooks/ directory.
+ *
+ * @param {string} projectPath - Path to project root
+ * @param {Object} [options] - Options
+ * @param {Object} [options.fs] - File system module (for testing)
+ * @param {string[]} [options.hooks] - Which hooks to install (default: both)
+ * @returns {Promise<{installed: string[]}>}
+ */
+async function installHooks(projectPath, options = {}) {
+  const fsModule = options.fs || fs;
+  const hooks = options.hooks || ['pre-commit', 'pre-push'];
+  const gitDir = path.join(projectPath, '.git');
+
+  if (!fsModule.existsSync(gitDir)) {
+    throw new Error('Not a git repository: .git directory not found');
+  }
+
+  const hooksDir = path.join(gitDir, 'hooks');
+  const installed = [];
+
+  const generators = {
+    'pre-commit': generatePreCommitHook,
+    'pre-push': generatePrePushHook,
+  };
+
+  for (const hookName of hooks) {
+    const generator = generators[hookName];
+    if (!generator) continue;
+
+    const hookPath = path.join(hooksDir, hookName);
+    const content = generator();
+
+    fsModule.writeFileSync(hookPath, content, 'utf-8');
+    fsModule.chmodSync(hookPath, '755');
+    installed.push(hookName);
+  }
+
+  return { installed };
+}
+
+/**
+ * Check if a TLC code gate hook is installed.
+ *
+ * @param {string} projectPath
+ * @param {string} hookName - Hook name (pre-commit, pre-push)
+ * @param {Object} [options]
+ * @param {Object} [options.fs] - File system module
+ * @returns {boolean}
+ */
+function isHookInstalled(projectPath, hookName, options = {}) {
+  const fsModule = options.fs || fs;
+  const hookPath = path.join(projectPath, '.git', 'hooks', hookName);
+
+  if (!fsModule.existsSync(hookPath)) {
+    return false;
+  }
+
+  const content = fsModule.readFileSync(hookPath, 'utf-8');
+  return content.includes(TLC_HOOK_MARKER);
+}
+
+module.exports = {
+  generatePreCommitHook,
+  generatePrePushHook,
+  installHooks,
+  isHookInstalled,
+};

package/server/lib/code-gate/hooks-generator.test.js

@@ -0,0 +1,142 @@
+/**
+ * Hooks Generator Tests
+ *
+ * Generates and installs git hooks that run the code gate.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  generatePreCommitHook,
+  generatePrePushHook,
+  installHooks,
+  isHookInstalled,
+} = require('./hooks-generator.js');
+
+describe('Hooks Generator', () => {
+  describe('generatePreCommitHook', () => {
+    it('generates a valid shell script', () => {
+      const script = generatePreCommitHook();
+      expect(script).toContain('#!/bin/sh');
+    });
+
+    it('includes gate check command', () => {
+      const script = generatePreCommitHook();
+      expect(script).toContain('tlc-gate');
+    });
+
+    it('exits non-zero on gate failure', () => {
+      const script = generatePreCommitHook();
+      expect(script).toContain('exit 1');
+    });
+
+    it('is portable sh, not bash-specific', () => {
+      const script = generatePreCommitHook();
+      expect(script).not.toContain('#!/bin/bash');
+      expect(script).not.toContain('[[');  // bash-specific test syntax
+    });
+
+    it('includes bypass detection', () => {
+      const script = generatePreCommitHook();
+      // The hook should detect if it was bypassed (for audit logging)
+      expect(script).toContain('pre-commit');
+    });
+  });
+
+  describe('generatePrePushHook', () => {
+    it('generates a valid shell script', () => {
+      const script = generatePrePushHook();
+      expect(script).toContain('#!/bin/sh');
+    });
+
+    it('includes both static and LLM review', () => {
+      const script = generatePrePushHook();
+      expect(script).toContain('tlc-gate');
+    });
+
+    it('exits non-zero on gate failure', () => {
+      const script = generatePrePushHook();
+      expect(script).toContain('exit 1');
+    });
+  });
+
+  describe('installHooks', () => {
+    it('writes pre-commit hook to .git/hooks/', async () => {
+      let writtenPath = null;
+      let writtenContent = null;
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(true),
+        writeFileSync: vi.fn((path, content) => {
+          writtenPath = path;
+          writtenContent = content;
+        }),
+        chmodSync: vi.fn(),
+      };
+
+      await installHooks('/project', { fs: mockFs, hooks: ['pre-commit'] });
+      expect(writtenPath).toContain('.git/hooks/pre-commit');
+      expect(writtenContent).toContain('#!/bin/sh');
+    });
+
+    it('makes hook executable', async () => {
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(true),
+        writeFileSync: vi.fn(),
+        chmodSync: vi.fn(),
+      };
+
+      await installHooks('/project', { fs: mockFs, hooks: ['pre-commit'] });
+      expect(mockFs.chmodSync).toHaveBeenCalledWith(
+        expect.stringContaining('pre-commit'),
+        '755'
+      );
+    });
+
+    it('installs both hooks by default', async () => {
+      const written = [];
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(true),
+        writeFileSync: vi.fn((path) => written.push(path)),
+        chmodSync: vi.fn(),
+      };
+
+      await installHooks('/project', { fs: mockFs });
+      expect(written).toHaveLength(2);
+      expect(written.some(p => p.includes('pre-commit'))).toBe(true);
+      expect(written.some(p => p.includes('pre-push'))).toBe(true);
+    });
+
+    it('throws when .git directory missing', async () => {
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(false),
+      };
+
+      await expect(installHooks('/project', { fs: mockFs }))
+        .rejects.toThrow('Not a git repository');
+    });
+  });
+
+  describe('isHookInstalled', () => {
+    it('returns true when TLC hook exists', () => {
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(true),
+        readFileSync: vi.fn().mockReturnValue('#!/bin/sh\n# TLC Code Gate\ntlc-gate check'),
+      };
+      expect(isHookInstalled('/project', 'pre-commit', { fs: mockFs })).toBe(true);
+    });
+
+    it('returns false when no hook file', () => {
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(false),
+      };
+      expect(isHookInstalled('/project', 'pre-commit', { fs: mockFs })).toBe(false);
+    });
+
+    it('returns false when hook is not from TLC', () => {
+      const mockFs = {
+        existsSync: vi.fn().mockReturnValue(true),
+        readFileSync: vi.fn().mockReturnValue('#!/bin/sh\nhusky run'),
+      };
+      expect(isHookInstalled('/project', 'pre-commit', { fs: mockFs })).toBe(false);
+    });
+  });
+});

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

@@ -0,0 +1,176 @@
+/**
+ * LLM Reviewer
+ *
+ * Mandatory LLM-powered code review before every push.
+ * Collects diff, sends to LLM via model router, parses structured result.
+ * Falls back to static-only review if no LLM is available.
+ *
+ * @module code-gate/llm-reviewer
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/** Default timeout for LLM review in milliseconds */
+const DEFAULT_TIMEOUT = 60000;
+
+/** File extensions that are docs-only (skip LLM review) */
+const DOCS_EXTENSIONS = ['.md', '.txt', '.rst', '.adoc'];
+
+/**
+ * Severity mapping from LLM response levels to gate levels.
+ * LLM may use critical/high/medium/low; we normalize to block/warn/info.
+ */
+const SEVERITY_MAP = {
+  critical: 'block',
+  high: 'block',
+  medium: 'warn',
+  low: 'info',
+  block: 'block',
+  warn: 'warn',
+  info: 'info',
+};
+
+/**
+ * Create a reviewer instance with configurable options.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.timeout] - LLM request timeout in ms
+ * @returns {{ options: Object }}
+ */
+function createReviewer(options = {}) {
+  return {
+    options: {
+      timeout: options.timeout || DEFAULT_TIMEOUT,
+    },
+  };
+}
+
+/**
+ * Build the review prompt to send to the LLM.
+ *
+ * @param {string} diff - Git diff content
+ * @param {string} standards - CODING-STANDARDS.md content
+ * @returns {string} Complete review prompt
+ */
+function buildReviewPrompt(diff, standards) {
+  return `You are a strict code reviewer. Review this diff against the project's coding standards.
+
+${standards ? `## Coding Standards\n${standards}\n\n` : ''}## Diff to Review
+\`\`\`
+${diff}
+\`\`\`
+
+## Instructions
+For each issue found, respond with a JSON object:
+\`\`\`json
+{
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "file": "affected file path",
+      "line": 0,
+      "rule": "which standard is violated",
+      "message": "clear description",
+      "fix": "how to fix it"
+    }
+  ],
+  "summary": "brief overall assessment"
+}
+\`\`\`
+
+Be STRICT. Block on: security issues, missing tests, hardcoded secrets, major anti-patterns.
+If the code is clean, return an empty findings array.
+Respond ONLY with the JSON object.`;
+}
+
+/**
+ * Parse the LLM response into a structured review result.
+ * Handles raw JSON, markdown-wrapped JSON, and unparseable responses.
+ *
+ * @param {string} response - Raw LLM response text
+ * @returns {{ findings: Array, summary?: string }}
+ */
+function parseReviewResponse(response) {
+  // Try to extract JSON from markdown code block
+  const codeBlockMatch = response.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+  const jsonStr = codeBlockMatch ? codeBlockMatch[1].trim() : response.trim();
+
+  try {
+    const parsed = JSON.parse(jsonStr);
+    const findings = (parsed.findings || []).map(f => ({
+      ...f,
+      severity: SEVERITY_MAP[f.severity] || 'warn',
+    }));
+    return { findings, summary: parsed.summary };
+  } catch {
+    return {
+      findings: [{
+        severity: 'warn',
+        rule: 'llm-parse-error',
+        file: 'unknown',
+        message: 'Could not parse LLM review response',
+        fix: 'Run review manually with /tlc:review',
+      }],
+      summary: 'Review response could not be parsed',
+    };
+  }
+}
+
+/**
+ * Collect the git diff for review.
+ *
+ * @param {Object} [options]
+ * @param {Function} [options.exec] - Command execution function
+ * @returns {Promise<string>} Diff content
+ */
+async function collectDiff(options = {}) {
+  const exec = options.exec;
+  if (!exec) return '';
+  return await exec('git diff origin/main..HEAD');
+}
+
+/**
+ * Check if the review should be skipped (docs-only changes).
+ *
+ * @param {string[]} files - Changed file paths
+ * @returns {boolean} True if all changes are docs-only
+ */
+function shouldSkipReview(files) {
+  if (files.length === 0) return true;
+  return files.every(f => {
+    const ext = path.extname(f).toLowerCase();
+    return DOCS_EXTENSIONS.includes(ext);
+  });
+}
+
+/**
+ * Store a review result to disk for audit trail.
+ *
+ * @param {string} commitHash - Commit hash as filename
+ * @param {Object} result - Review result to store
+ * @param {Object} [options]
+ * @param {Object} [options.fs] - File system module
+ * @param {string} [options.projectPath] - Project root
+ */
+function storeReviewResult(commitHash, result, options = {}) {
+  const fsModule = options.fs || fs;
+  const projectPath = options.projectPath || process.cwd();
+  const reviewsDir = path.join(projectPath, '.tlc', 'reviews');
+
+  if (!fsModule.existsSync(reviewsDir)) {
+    fsModule.mkdirSync(reviewsDir, { recursive: true });
+  }
+
+  const filePath = path.join(reviewsDir, `${commitHash}.json`);
+  fsModule.writeFileSync(filePath, JSON.stringify(result, null, 2));
+}
+
+module.exports = {
+  createReviewer,
+  buildReviewPrompt,
+  parseReviewResponse,
+  collectDiff,
+  shouldSkipReview,
+  storeReviewResult,
+};