tlc-claude-code 1.6.4 → 1.8.0

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

@@ -0,0 +1,155 @@
+/**
+ * Structure Rules
+ *
+ * Detects flat folder anti-patterns, files in wrong locations,
+ * and missing test colocation.
+ *
+ * @module code-gate/rules/structure-rules
+ */
+
+const path = require('path');
+
+/** Folder names that indicate flat anti-patterns when at root level */
+const FLAT_FOLDER_PATTERNS = ['services', 'controllers', 'interfaces', 'helpers', 'utils'];
+
+/** Files allowed at project root */
+const ALLOWED_ROOT_FILES = [
+  'index.js', 'index.ts', 'index.mjs',
+  'package.json', 'package-lock.json',
+  'tsconfig.json', 'vitest.config.js', 'vitest.config.ts',
+  'jest.config.js', 'jest.config.ts', '.eslintrc.js',
+];
+
+/** Patterns for allowed root file naming */
+const ALLOWED_ROOT_PATTERNS = [
+  /^\./, // dotfiles
+  /\.config\.[jt]s$/, // config files
+  /\.json$/, // JSON files
+  /\.ya?ml$/, // YAML files
+  /\.md$/, // Markdown
+  /\.lock$/, // Lock files
+];
+
+/**
+ * Detect flat folder anti-patterns (services/, interfaces/, controllers/ at root).
+ *
+ * @param {string} filePath - File path relative to project root
+ * @param {string} content - File content (unused for structure checks)
+ * @returns {Array<{severity: string, rule: string, line: number, message: string, fix: string}>}
+ */
+function checkFlatFolders(filePath, content) {
+  const parts = filePath.split(/[/\\]/);
+
+  // Check if the first or second directory segment is a flat anti-pattern
+  for (let i = 0; i < Math.min(parts.length - 1, 2); i++) {
+    const dir = parts[i];
+    if (FLAT_FOLDER_PATTERNS.includes(dir)) {
+      // Only flag if not inside a module (e.g. src/user/services is fine)
+      const isNested = i >= 2 || (i === 1 && parts[0] === 'src' && parts.length > 3);
+      if (!isNested) {
+        return [{
+          severity: 'warn',
+          rule: 'no-flat-folders',
+          line: 1,
+          message: `File in flat '${dir}/' folder — use module-scoped organization`,
+          fix: `Move to a feature module: src/{feature}/${dir}/${path.basename(filePath)}`,
+        }];
+      }
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Detect loose source files at project root that should be in subdirectories.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array}
+ */
+function checkLooseFiles(filePath, content) {
+  // Only check files at root (no directory separator)
+  if (filePath.includes('/') || filePath.includes('\\')) {
+    return [];
+  }
+
+  // Check against allowed files and patterns
+  if (ALLOWED_ROOT_FILES.includes(filePath)) {
+    return [];
+  }
+  for (const pattern of ALLOWED_ROOT_PATTERNS) {
+    if (pattern.test(filePath)) {
+      return [];
+    }
+  }
+
+  // Only flag JS/TS source files
+  if (!/\.[jt]sx?$/.test(filePath)) {
+    return [];
+  }
+
+  return [{
+    severity: 'warn',
+    rule: 'no-loose-files',
+    line: 1,
+    message: `Source file '${filePath}' at project root`,
+    fix: 'Move into a feature module directory: src/{feature}/',
+  }];
+}
+
+/**
+ * Check that source files have corresponding test files.
+ * Skips test files, config files, and non-JS files.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @param {Object} [options]
+ * @param {string[]} [options.allFiles] - All file paths in the changeset
+ * @returns {Array}
+ */
+function checkTestColocation(filePath, content, options = {}) {
+  // Skip non-JS files
+  if (!/\.[jt]sx?$/.test(filePath)) return [];
+
+  // Skip test files themselves
+  if (/\.(test|spec)\.[jt]sx?$/.test(filePath)) return [];
+
+  // Skip config files
+  if (/\.config\.[jt]sx?$/.test(filePath)) return [];
+
+  // Skip index files and type definitions
+  if (/^index\.[jt]sx?$/.test(path.basename(filePath))) return [];
+  if (/\.d\.ts$/.test(filePath)) return [];
+
+  const allFiles = options.allFiles || [];
+  const base = filePath.replace(/\.[jt]sx?$/, '');
+  const testPatterns = [
+    `${base}.test.js`,
+    `${base}.test.ts`,
+    `${base}.test.jsx`,
+    `${base}.test.tsx`,
+    `${base}.spec.js`,
+    `${base}.spec.ts`,
+  ];
+
+  const hasTest = testPatterns.some(tp => allFiles.includes(tp));
+
+  if (!hasTest) {
+    return [{
+      severity: 'block',
+      rule: 'require-test-file',
+      line: 1,
+      message: `No test file found for '${filePath}'`,
+      fix: `Create test file: ${base}.test.js`,
+    }];
+  }
+
+  return [];
+}
+
+module.exports = {
+  checkFlatFolders,
+  checkLooseFiles,
+  checkTestColocation,
+};

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

@@ -0,0 +1,107 @@
+/**
+ * Structure Rules Tests
+ *
+ * Detects flat folder anti-patterns, files in wrong locations,
+ * and missing test colocation.
+ */
+import { describe, it, expect } from 'vitest';
+
+const {
+  checkFlatFolders,
+  checkLooseFiles,
+  checkTestColocation,
+} = require('./structure-rules.js');
+
+describe('Structure Rules', () => {
+  describe('checkFlatFolders', () => {
+    it('detects services/ folder at root', () => {
+      const findings = checkFlatFolders('services/userService.js', 'code');
+      expect(findings).toHaveLength(1);
+      expect(findings[0].rule).toBe('no-flat-folders');
+      expect(findings[0].severity).toBe('warn');
+    });
+
+    it('detects controllers/ folder', () => {
+      const findings = checkFlatFolders('controllers/userCtrl.js', 'code');
+      expect(findings).toHaveLength(1);
+    });
+
+    it('detects interfaces/ at src root', () => {
+      const findings = checkFlatFolders('src/interfaces/IUser.ts', 'code');
+      expect(findings).toHaveLength(1);
+    });
+
+    it('passes module-scoped paths', () => {
+      const findings = checkFlatFolders('src/user/services/userService.js', 'code');
+      expect(findings).toHaveLength(0);
+    });
+
+    it('passes nested interfaces in module', () => {
+      const findings = checkFlatFolders('src/user/interfaces/IUser.ts', 'code');
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('checkLooseFiles', () => {
+    it('detects .js files in project root', () => {
+      const findings = checkLooseFiles('random-script.js', 'code');
+      expect(findings).toHaveLength(1);
+      expect(findings[0].rule).toBe('no-loose-files');
+      expect(findings[0].severity).toBe('warn');
+    });
+
+    it('allows index.js at root', () => {
+      const findings = checkLooseFiles('index.js', 'code');
+      expect(findings).toHaveLength(0);
+    });
+
+    it('allows config files at root', () => {
+      const findings = checkLooseFiles('vitest.config.js', 'code');
+      expect(findings).toHaveLength(0);
+    });
+
+    it('allows package.json at root', () => {
+      const findings = checkLooseFiles('package.json', '{}');
+      expect(findings).toHaveLength(0);
+    });
+
+    it('passes files in subdirectories', () => {
+      const findings = checkLooseFiles('src/app.js', 'code');
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('checkTestColocation', () => {
+    it('flags source file without test file', () => {
+      const allFiles = ['src/user.js'];
+      const findings = checkTestColocation('src/user.js', 'code', { allFiles });
+      expect(findings).toHaveLength(1);
+      expect(findings[0].rule).toBe('require-test-file');
+      expect(findings[0].severity).toBe('block');
+    });
+
+    it('passes when test file exists', () => {
+      const allFiles = ['src/user.js', 'src/user.test.js'];
+      const findings = checkTestColocation('src/user.js', 'code', { allFiles });
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips check for test files themselves', () => {
+      const allFiles = ['src/user.test.js'];
+      const findings = checkTestColocation('src/user.test.js', 'test code', { allFiles });
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips check for config files', () => {
+      const allFiles = ['vitest.config.js'];
+      const findings = checkTestColocation('vitest.config.js', 'config', { allFiles });
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips check for non-JS files', () => {
+      const allFiles = ['README.md'];
+      const findings = checkTestColocation('README.md', '# readme', { allFiles });
+      expect(findings).toHaveLength(0);
+    });
+  });
+});

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

@@ -0,0 +1,93 @@
+/**
+ * Test Rules
+ *
+ * Detects test files with no assertions, skipped tests,
+ * and other test quality issues.
+ *
+ * @module code-gate/rules/test-rules
+ */
+
+/**
+ * Check if a file is a test file.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isTestFile(filePath) {
+  return /\.(test|spec)\.[jt]sx?$/.test(filePath);
+}
+
+/**
+ * Check for test files that contain no assertions.
+ * Tests without expect(), assert, or should are likely empty stubs.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array<{severity: string, rule: string, line: number, message: string, fix: string}>}
+ */
+function checkEmptyTests(filePath, content) {
+  if (!isTestFile(filePath)) return [];
+
+  const hasAssertion =
+    /\bexpect\s*\(/.test(content) ||
+    /\bassert\b/.test(content) ||
+    /\.should\b/.test(content);
+
+  if (!hasAssertion) {
+    return [{
+      severity: 'block',
+      rule: 'no-empty-tests',
+      line: 1,
+      message: 'Test file contains no assertions',
+      fix: 'Add expect() or assert calls to verify behavior',
+    }];
+  }
+
+  return [];
+}
+
+/**
+ * Check for skipped tests (.skip, xit, xdescribe).
+ * Skipped tests hide regressions.
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {Array}
+ */
+function checkSkippedTests(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 skipPatterns = [
+      { pattern: /\bdescribe\.skip\s*\(/, label: 'describe.skip' },
+      { pattern: /\bit\.skip\s*\(/, label: 'it.skip' },
+      { pattern: /\btest\.skip\s*\(/, label: 'test.skip' },
+      { pattern: /\bxdescribe\s*\(/, label: 'xdescribe' },
+      { pattern: /\bxit\s*\(/, label: 'xit' },
+      { pattern: /\bxtest\s*\(/, label: 'xtest' },
+    ];
+
+    for (const { pattern, label } of skipPatterns) {
+      if (pattern.test(line)) {
+        findings.push({
+          severity: 'warn',
+          rule: 'no-skipped-tests',
+          line: i + 1,
+          message: `Skipped test found: ${label}`,
+          fix: 'Remove .skip or fix the test — skipped tests hide regressions',
+        });
+        break;
+      }
+    }
+  }
+
+  return findings;
+}
+
+module.exports = {
+  checkEmptyTests,
+  checkSkippedTests,
+};

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

@@ -0,0 +1,97 @@
+/**
+ * Test Rules Tests
+ *
+ * Detects test files with no assertions, skipped tests, and
+ * source files without corresponding test files.
+ */
+import { describe, it, expect } from 'vitest';
+
+const {
+  checkEmptyTests,
+  checkSkippedTests,
+} = require('./test-rules.js');
+
+describe('Test Rules', () => {
+  describe('checkEmptyTests', () => {
+    it('detects test file with no assertions', () => {
+      const code = `
+describe('User', () => {
+  it('should work', () => {
+    const user = getUser();
+  });
+});`;
+      const findings = checkEmptyTests('user.test.js', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].rule).toBe('no-empty-tests');
+      expect(findings[0].severity).toBe('block');
+    });
+
+    it('passes test with expect assertion', () => {
+      const code = `
+describe('User', () => {
+  it('should work', () => {
+    expect(getUser()).toBeDefined();
+  });
+});`;
+      const findings = checkEmptyTests('user.test.js', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('passes test with assert assertion', () => {
+      const code = `
+describe('User', () => {
+  it('should work', () => {
+    assert.ok(getUser());
+  });
+});`;
+      const findings = checkEmptyTests('user.test.js', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips non-test files', () => {
+      const code = 'const x = 1;';
+      const findings = checkEmptyTests('app.js', code);
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('checkSkippedTests', () => {
+    it('detects describe.skip', () => {
+      const code = 'describe.skip("User", () => {});';
+      const findings = checkSkippedTests('user.test.js', code);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].rule).toBe('no-skipped-tests');
+      expect(findings[0].severity).toBe('warn');
+    });
+
+    it('detects it.skip', () => {
+      const code = 'it.skip("should work", () => {});';
+      const findings = checkSkippedTests('user.test.js', code);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('detects xdescribe', () => {
+      const code = 'xdescribe("User", () => {});';
+      const findings = checkSkippedTests('user.test.js', code);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('detects xit', () => {
+      const code = 'xit("should work", () => {});';
+      const findings = checkSkippedTests('user.test.js', code);
+      expect(findings).toHaveLength(1);
+    });
+
+    it('passes normal test', () => {
+      const code = 'it("should work", () => { expect(1).toBe(1); });';
+      const findings = checkSkippedTests('user.test.js', code);
+      expect(findings).toHaveLength(0);
+    });
+
+    it('skips non-test files', () => {
+      const code = 'describe.skip("something", () => {});';
+      const findings = checkSkippedTests('app.js', code);
+      expect(findings).toHaveLength(0);
+    });
+  });
+});

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

@@ -0,0 +1,128 @@
+/**
+ * TypeScript Compilation Gate
+ *
+ * Integrates `tsc --noEmit` as an optional check in the push gate.
+ * Catches 7 categories of bugs that compile silently with esbuild/Vite:
+ * - Invented enum values (Bug #4, #33)
+ * - Wrong field names (Bug #7)
+ * - Date type mismatches (Bug #8)
+ * - Undefined variables (Bug #31)
+ * - Accumulated type errors (Bug #32)
+ * - Missing required fields in spreads (Bug #34)
+ *
+ * @module code-gate/typescript-gate
+ */
+
+const path = require('path');
+
+/**
+ * Check if a project has TypeScript configured.
+ *
+ * @param {string} projectPath - Project root
+ * @param {Object} [options]
+ * @param {Object} [options.fs] - File system (injectable)
+ * @returns {boolean}
+ */
+function detectTypeScript(projectPath, options = {}) {
+  const fs = options.fs || require('fs');
+  const tsconfigPath = path.join(projectPath, 'tsconfig.json');
+  return fs.existsSync(tsconfigPath);
+}
+
+/**
+ * Parse tsc --noEmit output into gate findings.
+ * TypeScript error format: file(line,col): error TSxxxx: message
+ *
+ * @param {string} output - Raw tsc output
+ * @returns {Array<{severity: string, rule: string, file: string, line: number, message: string, fix: string}>}
+ */
+function parseTscOutput(output) {
+  if (!output || !output.trim()) return [];
+  const findings = [];
+  const lines = output.split('\n');
+
+  // TS error format: path/file.ts(line,col): error TSxxxx: message
+  const errorPattern = /^(.+?)\((\d+),\d+\):\s*error\s+(TS\d+):\s*(.+)$/;
+
+  for (const line of lines) {
+    const match = line.match(errorPattern);
+    if (match) {
+      const [, file, lineNum, code, message] = match;
+      findings.push({
+        severity: 'block',
+        rule: 'typescript-error',
+        file,
+        line: parseInt(lineNum, 10),
+        message: `${code}: ${message}`,
+        fix: 'Fix the TypeScript type error — tsc --noEmit must pass with zero errors',
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Run tsc --noEmit and return gate-compatible result.
+ *
+ * @param {string} projectPath - Project root
+ * @param {Object} [options]
+ * @param {Function} [options.exec] - Command executor (injectable)
+ * @returns {Promise<{passed: boolean, findings: Array, summary: Object, skipped?: boolean}>}
+ */
+async function runTypeScriptGate(projectPath, options = {}) {
+  const exec = options.exec;
+
+  try {
+    const result = await exec('npx tsc --noEmit', { cwd: projectPath });
+    const output = result.stdout || '';
+    const findings = parseTscOutput(output);
+    const summary = { total: findings.length, block: findings.length, warn: 0, info: 0 };
+
+    return {
+      passed: findings.length === 0,
+      findings,
+      summary,
+    };
+  } catch (err) {
+    // If tsc fails with errors, the output is usually in stdout or stderr
+    if (err.stdout || err.stderr) {
+      const output = err.stdout || err.stderr || '';
+      const findings = parseTscOutput(output);
+      const summary = { total: findings.length, block: findings.length, warn: 0, info: 0 };
+      return {
+        passed: findings.length === 0,
+        findings,
+        summary,
+      };
+    }
+
+    // tsc not installed or other system error — skip gracefully
+    return {
+      passed: true,
+      findings: [],
+      summary: { total: 0, block: 0, warn: 0, info: 0 },
+      skipped: true,
+    };
+  }
+}
+
+/**
+ * Create a TypeScript gate with configurable options.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.enabled=true]
+ * @returns {{ enabled: boolean }}
+ */
+function createTypeScriptGate(options = {}) {
+  return {
+    enabled: options.enabled !== false,
+  };
+}
+
+module.exports = {
+  detectTypeScript,
+  parseTscOutput,
+  runTypeScriptGate,
+  createTypeScriptGate,
+};