tlc-claude-code 1.6.4 → 1.8.0

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/gate-command.js

@@ -0,0 +1,114 @@
+/**
+ * Gate Command
+ *
+ * /tlc:gate command to install, configure, and run the code gate.
+ * Subcommands: install, check, status, config
+ *
+ * @module code-gate/gate-command
+ */
+
+/**
+ * Parse gate command arguments into structured options.
+ *
+ * @param {string} args - Raw argument string
+ * @returns {{ subcommand: string }}
+ */
+function parseGateArgs(args) {
+  const trimmed = (args || '').trim();
+  const subcommand = trimmed.split(/\s+/)[0] || 'check';
+
+  const valid = ['install', 'check', 'status', 'config'];
+  return {
+    subcommand: valid.includes(subcommand) ? subcommand : 'check',
+  };
+}
+
+/**
+ * Create a gate command with injectable dependencies.
+ * This allows testing without real file system or git operations.
+ *
+ * @param {Object} deps - Dependencies
+ * @param {string} deps.projectPath - Project root path
+ * @param {Function} [deps.installHooks] - Hook installer function
+ * @param {Function} [deps.runGate] - Gate engine runner function
+ * @param {Function} [deps.getStagedFiles] - Get staged files function
+ * @param {Function} [deps.loadConfig] - Config loader function
+ * @param {Function} [deps.saveConfig] - Config saver function
+ * @param {Function} [deps.isHookInstalled] - Hook check function
+ * @returns {{ execute: Function }}
+ */
+function createGateCommand(deps) {
+  const {
+    projectPath,
+    installHooks,
+    runGate,
+    getStagedFiles,
+    loadConfig,
+    saveConfig,
+    isHookInstalled,
+  } = deps;
+
+  return {
+    /**
+     * Execute a gate subcommand.
+     *
+     * @param {string} subcommand - install|check|status|config
+     * @param {Object} [options] - Subcommand-specific options
+     * @returns {Promise<Object>} Subcommand result
+     */
+    async execute(subcommand, options = {}) {
+      switch (subcommand) {
+        case 'install':
+          return handleInstall();
+        case 'check':
+          return handleCheck();
+        case 'status':
+          return handleStatus();
+        case 'config':
+          return handleConfig(options);
+        default:
+          return { success: false, error: `Unknown subcommand: ${subcommand}` };
+      }
+    },
+  };
+
+  async function handleInstall() {
+    if (!installHooks) {
+      return { success: false, error: 'Hook installer not available' };
+    }
+    const result = await installHooks(projectPath);
+    return { success: true, installed: result.installed };
+  }
+
+  async function handleCheck() {
+    if (!runGate) {
+      return { success: false, error: 'Gate engine not available' };
+    }
+    const files = getStagedFiles ? await getStagedFiles() : [];
+    return await runGate(files);
+  }
+
+  async function handleStatus() {
+    const config = loadConfig ? loadConfig(projectPath) : {};
+    const hooks = {
+      'pre-commit': isHookInstalled ? isHookInstalled(projectPath, 'pre-commit') : false,
+      'pre-push': isHookInstalled ? isHookInstalled(projectPath, 'pre-push') : false,
+    };
+    return { config, hooks };
+  }
+
+  async function handleConfig(updates) {
+    if (!saveConfig) {
+      return { success: false, error: 'Config saver not available' };
+    }
+    const current = loadConfig ? loadConfig(projectPath) : {};
+    const merged = { ...current, ...updates };
+    saveConfig(merged);
+    return { success: true, config: merged };
+  }
+}
+
+module.exports = {
+  createGateCommand,
+  parseGateArgs,
+};

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

@@ -0,0 +1,111 @@
+/**
+ * Gate Command Tests
+ *
+ * /tlc:gate command to install, configure, and run the code gate.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+const {
+  createGateCommand,
+  parseGateArgs,
+} = require('./gate-command.js');
+
+describe('Gate Command', () => {
+  describe('parseGateArgs', () => {
+    it('parses install subcommand', () => {
+      const args = parseGateArgs('install');
+      expect(args.subcommand).toBe('install');
+    });
+
+    it('parses check subcommand', () => {
+      const args = parseGateArgs('check');
+      expect(args.subcommand).toBe('check');
+    });
+
+    it('parses status subcommand', () => {
+      const args = parseGateArgs('status');
+      expect(args.subcommand).toBe('status');
+    });
+
+    it('defaults to check when no subcommand', () => {
+      const args = parseGateArgs('');
+      expect(args.subcommand).toBe('check');
+    });
+
+    it('parses config subcommand', () => {
+      const args = parseGateArgs('config');
+      expect(args.subcommand).toBe('config');
+    });
+  });
+
+  describe('createGateCommand', () => {
+    it('creates command with injectable dependencies', () => {
+      const cmd = createGateCommand({ projectPath: '/test' });
+      expect(cmd).toBeDefined();
+      expect(cmd.execute).toBeTypeOf('function');
+    });
+
+    it('install subcommand calls hooks installer', async () => {
+      const mockInstallHooks = vi.fn().mockResolvedValue({ installed: ['pre-commit', 'pre-push'] });
+      const cmd = createGateCommand({
+        projectPath: '/test',
+        installHooks: mockInstallHooks,
+      });
+
+      const result = await cmd.execute('install');
+      expect(mockInstallHooks).toHaveBeenCalled();
+      expect(result.success).toBe(true);
+    });
+
+    it('check subcommand runs gate engine', async () => {
+      const mockRunGate = vi.fn().mockResolvedValue({
+        passed: true,
+        findings: [],
+        summary: { total: 0, block: 0, warn: 0, info: 0 },
+      });
+      const mockGetStagedFiles = vi.fn().mockResolvedValue([]);
+      const cmd = createGateCommand({
+        projectPath: '/test',
+        runGate: mockRunGate,
+        getStagedFiles: mockGetStagedFiles,
+      });
+
+      const result = await cmd.execute('check');
+      expect(result.passed).toBe(true);
+    });
+
+    it('status subcommand returns gate configuration', async () => {
+      const mockLoadConfig = vi.fn().mockReturnValue({
+        enabled: true,
+        strictness: 'strict',
+        preCommit: true,
+        prePush: true,
+      });
+      const mockIsInstalled = vi.fn().mockReturnValue(true);
+      const cmd = createGateCommand({
+        projectPath: '/test',
+        loadConfig: mockLoadConfig,
+        isHookInstalled: mockIsInstalled,
+      });
+
+      const result = await cmd.execute('status');
+      expect(result.config).toBeDefined();
+      expect(result.config.strictness).toBe('strict');
+      expect(result.hooks).toBeDefined();
+    });
+
+    it('config subcommand updates .tlc.json', async () => {
+      let savedConfig = null;
+      const mockSaveConfig = vi.fn((config) => { savedConfig = config; });
+      const cmd = createGateCommand({
+        projectPath: '/test',
+        saveConfig: mockSaveConfig,
+        loadConfig: vi.fn().mockReturnValue({ enabled: true, strictness: 'strict' }),
+      });
+
+      const result = await cmd.execute('config', { strictness: 'standard' });
+      expect(mockSaveConfig).toHaveBeenCalled();
+      expect(result.success).toBe(true);
+    });
+  });
+});