tlc-claude-code 1.6.4 → 1.7.0

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

@@ -0,0 +1,193 @@
+/**
+ * Code Gate Engine
+ *
+ * Core engine that accepts changed files and runs configurable rule sets
+ * against each file, returning pass/fail with detailed findings per file.
+ *
+ * @module code-gate/gate-engine
+ */
+
+const path = require('path');
+
+/**
+ * Severity levels for gate findings.
+ * - block: Commit/push is rejected
+ * - warn: Warning shown but allowed through
+ * - info: Informational, no action needed
+ */
+const SEVERITY = {
+  BLOCK: 'block',
+  WARN: 'warn',
+  INFO: 'info',
+};
+
+/** Deduction points per severity level for scoring */
+const SCORE_DEDUCTIONS = {
+  [SEVERITY.BLOCK]: 25,
+  [SEVERITY.WARN]: 10,
+  [SEVERITY.INFO]: 2,
+};
+
+/**
+ * Create a gate engine instance with configurable rules and options.
+ *
+ * @param {Object} options - Engine options
+ * @param {Array<{id: string, check: Function}>} [options.rules] - Rule set to run
+ * @param {string[]} [options.ignore] - Glob patterns for files to skip
+ * @returns {{ rules: Array, options: Object }}
+ */
+function createGateEngine(options = {}) {
+  return {
+    rules: options.rules || [],
+    options: {
+      ignore: options.ignore || [],
+    },
+  };
+}
+
+/**
+ * Run all configured rules against a set of changed files.
+ *
+ * @param {{ rules: Array, options: Object }} engine - Gate engine instance
+ * @param {Array<{path: string, content: string}>} files - Changed files to check
+ * @returns {Promise<{passed: boolean, findings: Array, summary: Object, duration: number}>}
+ */
+async function runGate(engine, files) {
+  const start = Date.now();
+  const findings = [];
+
+  for (const file of files) {
+    if (shouldIgnore(file.path, engine.options.ignore)) {
+      continue;
+    }
+
+    for (const rule of engine.rules) {
+      try {
+        const ruleFindings = rule.check(file.path, file.content);
+        for (const finding of ruleFindings) {
+          findings.push({ ...finding, file: file.path });
+        }
+      } catch (err) {
+        findings.push({
+          severity: SEVERITY.WARN,
+          rule: rule.id,
+          file: file.path,
+          message: `Rule error: ${err.message}`,
+          fix: 'Check rule configuration',
+        });
+      }
+    }
+  }
+
+  const summary = buildSummary(findings);
+  const passed = summary.block === 0;
+
+  return {
+    passed,
+    findings,
+    summary,
+    duration: Date.now() - start,
+  };
+}
+
+/**
+ * Group findings by file path for reporting.
+ *
+ * @param {Array} findings - Array of finding objects
+ * @returns {Object.<string, Array>} Findings grouped by file
+ */
+function aggregateFindings(findings) {
+  const grouped = {};
+  for (const finding of findings) {
+    const key = finding.file;
+    if (!grouped[key]) {
+      grouped[key] = [];
+    }
+    grouped[key].push(finding);
+  }
+  return grouped;
+}
+
+/**
+ * Calculate a 0-100 quality score from findings.
+ * Starts at 100, deducts per severity. Floors at 0.
+ *
+ * @param {Array<{severity: string}>} findings - Finding objects with severity
+ * @returns {number} Score from 0 to 100
+ */
+function calculateScore(findings) {
+  let score = 100;
+  for (const finding of findings) {
+    const deduction = SCORE_DEDUCTIONS[finding.severity] || 0;
+    score -= deduction;
+  }
+  return Math.max(0, score);
+}
+
+/**
+ * Build summary counts from findings array.
+ *
+ * @param {Array<{severity: string}>} findings
+ * @returns {{ total: number, block: number, warn: number, info: number }}
+ */
+function buildSummary(findings) {
+  const summary = { total: findings.length, block: 0, warn: 0, info: 0 };
+  for (const finding of findings) {
+    if (summary[finding.severity] !== undefined) {
+      summary[finding.severity]++;
+    }
+  }
+  return summary;
+}
+
+/**
+ * Check if a file path matches any ignore pattern.
+ * Supports simple glob matching: *.ext and dir/* patterns.
+ *
+ * @param {string} filePath - File path to check
+ * @param {string[]} patterns - Glob patterns
+ * @returns {boolean} True if file should be ignored
+ */
+function shouldIgnore(filePath, patterns) {
+  for (const pattern of patterns) {
+    if (matchGlob(filePath, pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Simple glob matcher for common patterns.
+ *
+ * @param {string} filePath
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+function matchGlob(filePath, pattern) {
+  // *.ext — match extension anywhere
+  if (pattern.startsWith('*.')) {
+    const ext = pattern.slice(1);
+    return filePath.endsWith(ext);
+  }
+  // **/*.ext — match extension in any directory
+  if (pattern.startsWith('**/')) {
+    const sub = pattern.slice(3);
+    return matchGlob(filePath, sub) || matchGlob(path.basename(filePath), sub);
+  }
+  // dir/* — match files in directory
+  if (pattern.endsWith('/*')) {
+    const dir = pattern.slice(0, -2);
+    return filePath.startsWith(dir + '/') || filePath.startsWith(dir + path.sep);
+  }
+  // Exact match
+  return filePath === pattern;
+}
+
+module.exports = {
+  createGateEngine,
+  runGate,
+  aggregateFindings,
+  calculateScore,
+  SEVERITY,
+};

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