tlc-claude-code 1.6.4 → 1.8.0

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

@@ -0,0 +1,258 @@
+/**
+ * Gate Engine Tests
+ *
+ * The gate engine accepts changed files and runs configurable rule sets
+ * against each file, returning pass/fail with detailed findings.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+
+const {
+  createGateEngine,
+  runGate,
+  aggregateFindings,
+  calculateScore,
+  SEVERITY,
+} = require('./gate-engine.js');
+
+describe('Gate Engine', () => {
+  describe('SEVERITY', () => {
+    it('defines all severity levels', () => {
+      expect(SEVERITY.BLOCK).toBe('block');
+      expect(SEVERITY.WARN).toBe('warn');
+      expect(SEVERITY.INFO).toBe('info');
+    });
+  });
+
+  describe('createGateEngine', () => {
+    it('creates engine with default options', () => {
+      const engine = createGateEngine();
+      expect(engine).toBeDefined();
+      expect(engine.rules).toEqual([]);
+      expect(engine.options).toBeDefined();
+    });
+
+    it('creates engine with custom rules', () => {
+      const mockRule = { id: 'test-rule', check: () => [] };
+      const engine = createGateEngine({ rules: [mockRule] });
+      expect(engine.rules).toHaveLength(1);
+      expect(engine.rules[0].id).toBe('test-rule');
+    });
+
+    it('accepts ignore patterns', () => {
+      const engine = createGateEngine({ ignore: ['*.md', 'dist/*'] });
+      expect(engine.options.ignore).toEqual(['*.md', 'dist/*']);
+    });
+  });
+
+  describe('runGate', () => {
+    let engine;
+
+    beforeEach(() => {
+      engine = createGateEngine();
+    });
+
+    it('returns pass for empty changeset', async () => {
+      const result = await runGate(engine, []);
+      expect(result.passed).toBe(true);
+      expect(result.findings).toEqual([]);
+      expect(result.summary.total).toBe(0);
+    });
+
+    it('runs rules against each file', async () => {
+      const ruleCallCount = { count: 0 };
+      const mockRule = {
+        id: 'counter-rule',
+        check: (file, content) => {
+          ruleCallCount.count++;
+          return [];
+        },
+      };
+      engine = createGateEngine({ rules: [mockRule] });
+
+      const files = [
+        { path: 'src/a.js', content: 'const a = 1;' },
+        { path: 'src/b.js', content: 'const b = 2;' },
+      ];
+
+      await runGate(engine, files);
+      expect(ruleCallCount.count).toBe(2);
+    });
+
+    it('collects findings from all rules', async () => {
+      const rule1 = {
+        id: 'rule-a',
+        check: () => [
+          { severity: 'block', rule: 'rule-a', line: 1, message: 'Issue A', fix: 'Fix A' },
+        ],
+      };
+      const rule2 = {
+        id: 'rule-b',
+        check: () => [
+          { severity: 'warn', rule: 'rule-b', line: 5, message: 'Issue B', fix: 'Fix B' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule1, rule2] });
+
+      const result = await runGate(engine, [{ path: 'src/a.js', content: 'code' }]);
+      expect(result.findings).toHaveLength(2);
+    });
+
+    it('fails when any finding has block severity', async () => {
+      const rule = {
+        id: 'blocker',
+        check: () => [
+          { severity: 'block', rule: 'blocker', line: 1, message: 'Blocked', fix: 'Fix it' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule] });
+
+      const result = await runGate(engine, [{ path: 'src/a.js', content: 'code' }]);
+      expect(result.passed).toBe(false);
+    });
+
+    it('passes when findings are warn-only', async () => {
+      const rule = {
+        id: 'warner',
+        check: () => [
+          { severity: 'warn', rule: 'warner', line: 1, message: 'Warning', fix: 'Maybe fix' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule] });
+
+      const result = await runGate(engine, [{ path: 'src/a.js', content: 'code' }]);
+      expect(result.passed).toBe(true);
+    });
+
+    it('passes when findings are info-only', async () => {
+      const rule = {
+        id: 'informer',
+        check: () => [
+          { severity: 'info', rule: 'informer', line: 1, message: 'FYI', fix: 'Optional' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule] });
+
+      const result = await runGate(engine, [{ path: 'src/a.js', content: 'code' }]);
+      expect(result.passed).toBe(true);
+    });
+
+    it('attaches file path to each finding', async () => {
+      const rule = {
+        id: 'path-test',
+        check: () => [
+          { severity: 'warn', rule: 'path-test', line: 1, message: 'X', fix: 'Y' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule] });
+
+      const result = await runGate(engine, [{ path: 'src/deep/file.js', content: 'x' }]);
+      expect(result.findings[0].file).toBe('src/deep/file.js');
+    });
+
+    it('skips files matching ignore patterns', async () => {
+      const rule = {
+        id: 'skip-test',
+        check: () => [
+          { severity: 'block', rule: 'skip-test', line: 1, message: 'Bad', fix: 'Fix' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule], ignore: ['*.md', '*.json'] });
+
+      const files = [
+        { path: 'README.md', content: '# Hello' },
+        { path: 'package.json', content: '{}' },
+        { path: 'src/app.js', content: 'code' },
+      ];
+
+      const result = await runGate(engine, files);
+      // Only src/app.js should be checked
+      expect(result.findings).toHaveLength(1);
+      expect(result.findings[0].file).toBe('src/app.js');
+    });
+
+    it('includes summary with counts per severity', async () => {
+      const rule = {
+        id: 'multi',
+        check: () => [
+          { severity: 'block', rule: 'multi', line: 1, message: 'A', fix: 'A' },
+          { severity: 'warn', rule: 'multi', line: 2, message: 'B', fix: 'B' },
+          { severity: 'info', rule: 'multi', line: 3, message: 'C', fix: 'C' },
+        ],
+      };
+      engine = createGateEngine({ rules: [rule] });
+
+      const result = await runGate(engine, [{ path: 'x.js', content: '' }]);
+      expect(result.summary.total).toBe(3);
+      expect(result.summary.block).toBe(1);
+      expect(result.summary.warn).toBe(1);
+      expect(result.summary.info).toBe(1);
+    });
+
+    it('handles rule that throws gracefully', async () => {
+      const rule = {
+        id: 'crasher',
+        check: () => { throw new Error('Rule crashed'); },
+      };
+      engine = createGateEngine({ rules: [rule] });
+
+      const result = await runGate(engine, [{ path: 'x.js', content: '' }]);
+      // Should not throw - engine catches rule errors
+      expect(result).toBeDefined();
+      expect(result.findings).toHaveLength(1);
+      expect(result.findings[0].rule).toBe('crasher');
+      expect(result.findings[0].severity).toBe('warn');
+      expect(result.findings[0].message).toContain('Rule crashed');
+    });
+
+    it('measures execution duration', async () => {
+      engine = createGateEngine();
+      const result = await runGate(engine, []);
+      expect(typeof result.duration).toBe('number');
+      expect(result.duration).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('aggregateFindings', () => {
+    it('groups findings by file', () => {
+      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 grouped = aggregateFindings(findings);
+      expect(grouped['a.js']).toHaveLength(2);
+      expect(grouped['b.js']).toHaveLength(1);
+    });
+
+    it('returns empty object for no findings', () => {
+      const grouped = aggregateFindings([]);
+      expect(Object.keys(grouped)).toHaveLength(0);
+    });
+  });
+
+  describe('calculateScore', () => {
+    it('returns 100 for no findings', () => {
+      expect(calculateScore([])).toBe(100);
+    });
+
+    it('deducts points for block findings', () => {
+      const findings = [
+        { severity: 'block' },
+      ];
+      const score = calculateScore(findings);
+      expect(score).toBeLessThan(100);
+      expect(score).toBeGreaterThanOrEqual(0);
+    });
+
+    it('deducts fewer points for warnings', () => {
+      const blockFindings = [{ severity: 'block' }];
+      const warnFindings = [{ severity: 'warn' }];
+      expect(calculateScore(warnFindings)).toBeGreaterThan(calculateScore(blockFindings));
+    });
+
+    it('floors at zero', () => {
+      const manyFindings = Array.from({ length: 50 }, () => ({ severity: 'block' }));
+      expect(calculateScore(manyFindings)).toBe(0);
+    });
+  });
+});

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

@@ -0,0 +1,123 @@
+/**
+ * Gate Reporter
+ *
+ * Formats gate results into clear, actionable terminal output
+ * with severity badges, fix suggestions, and summary line.
+ *
+ * @module code-gate/gate-reporter
+ */
+
+/**
+ * Format a single finding as a readable string.
+ *
+ * @param {Object} finding
+ * @param {string} finding.severity
+ * @param {string} finding.rule
+ * @param {string} finding.file
+ * @param {number} [finding.line]
+ * @param {string} finding.message
+ * @param {string} finding.fix
+ * @returns {string}
+ */
+function formatFinding(finding) {
+  const badge = `[${finding.severity.toUpperCase()}]`;
+  const location = finding.line ? ` (line ${finding.line})` : '';
+  const rule = finding.rule;
+
+  let output = `  ${badge} ${rule}${location}\n`;
+  output += `    ${finding.message}\n`;
+  if (finding.fix) {
+    output += `    Fix: ${finding.fix}\n`;
+  }
+  return output;
+}
+
+/**
+ * Group findings by file path.
+ *
+ * @param {Array} findings
+ * @returns {Object.<string, Array>}
+ */
+function groupByFile(findings) {
+  const groups = {};
+  for (const finding of findings) {
+    const key = finding.file;
+    if (!groups[key]) groups[key] = [];
+    groups[key].push(finding);
+  }
+  return groups;
+}
+
+/**
+ * Format the summary line.
+ *
+ * @param {Object} summary - { total, block, warn, info }
+ * @param {boolean} passed
+ * @returns {string}
+ */
+function formatSummary(summary, passed) {
+  if (passed && summary.total === 0) {
+    return 'All clear — gate passed.';
+  }
+
+  const parts = [];
+  if (summary.block > 0) parts.push(`${summary.block} blocking`);
+  if (summary.warn > 0) parts.push(`${summary.warn} warning${summary.warn > 1 ? 's' : ''}`);
+  if (summary.info > 0) parts.push(`${summary.info} info`);
+
+  const status = passed ? 'passed' : 'blocked';
+  return `Summary: ${parts.join(' | ')} — gate ${status}.`;
+}
+
+/**
+ * Format a complete gate report.
+ *
+ * @param {Object} result - Gate engine result
+ * @param {boolean} result.passed
+ * @param {Array} result.findings
+ * @param {Object} result.summary
+ * @returns {string}
+ */
+function formatReport(result) {
+  const { passed, findings, summary } = result;
+
+  let report = '';
+
+  // Header
+  const status = passed ? 'Passed' : 'Blocked';
+  report += `TLC Code Gate — ${status}\n`;
+  report += '─'.repeat(42) + '\n\n';
+
+  if (findings.length === 0) {
+    report += 'All clear — no issues found.\n\n';
+    report += formatSummary(summary, passed) + '\n';
+    return report;
+  }
+
+  // Group and display findings by file
+  const grouped = groupByFile(findings);
+  for (const [file, fileFindings] of Object.entries(grouped)) {
+    report += `${file}\n`;
+    for (const finding of fileFindings) {
+      report += formatFinding(finding);
+    }
+    report += '\n';
+  }
+
+  // Summary
+  report += formatSummary(summary, passed) + '\n';
+
+  // Bypass hint (only when blocked)
+  if (!passed) {
+    report += 'Fix blocking issues or use --no-verify (logged).\n';
+  }
+
+  return report;
+}
+
+module.exports = {
+  formatReport,
+  formatSummary,
+  formatFinding,
+  groupByFile,
+};

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