claude-git-hooks 2.33.0 → 2.34.0

package/lib/utils/linter-runner.js

@@ -0,0 +1,443 @@
+/**
+ * File: linter-runner.js
+ * Purpose: Linter orchestration and preset-to-linter mapping
+ *
+ * Defines available linter tools and maps them to presets.
+ * Runs applicable linters on a set of files, aggregates results,
+ * and reports with install instructions for missing tools.
+ *
+ * Used by:
+ * - lib/hooks/pre-commit.js (staged files)
+ * - lib/commands/lint.js (user-specified paths)
+ *
+ * Dependencies:
+ * - tool-runner: Generic tool execution infrastructure
+ * - logger: Debug and error logging
+ */
+
+import path from 'path';
+import {
+    isToolAvailable,
+    filterFilesByTool,
+    runToolWithAutoFix,
+    displayToolResult
+} from './tool-runner.js';
+import { getRepoRoot } from './git-operations.js';
+import logger from './logger.js';
+
+/**
+ * Parse ESLint JSON output into structured issues
+ *
+ * @param {string} stdout - ESLint JSON output
+ * @returns {{ errors: Array, warnings: Array }}
+ */
+export function parseEslintOutput(stdout) {
+    const errors = [];
+    const warnings = [];
+
+    try {
+        const results = JSON.parse(stdout);
+
+        for (const fileResult of results) {
+            for (const msg of fileResult.messages || []) {
+                const issue = {
+                    file: fileResult.filePath || '',
+                    line: msg.line,
+                    column: msg.column,
+                    severity: msg.severity === 2 ? 'error' : 'warning',
+                    message: msg.message,
+                    ruleId: msg.ruleId || null
+                };
+
+                if (issue.severity === 'error') {
+                    errors.push(issue);
+                } else {
+                    warnings.push(issue);
+                }
+            }
+        }
+    } catch {
+        // ESLint output wasn't valid JSON — treat as raw error
+        if (stdout.trim()) {
+            errors.push({ file: '', severity: 'error', message: stdout.trim() });
+        }
+    }
+
+    return { errors, warnings };
+}
+
+/**
+ * Parse Spotless Maven output into structured issues
+ * Spotless check outputs file paths that need formatting
+ *
+ * @param {string} stdout - Maven stdout
+ * @returns {{ errors: Array, warnings: Array }}
+ */
+export function parseSpotlessOutput(stdout) {
+    const errors = [];
+    const warnings = [];
+
+    // Spotless outputs lines like "The following files were not formatted:" followed by file paths
+    const lines = stdout.split('\n');
+    let inFileList = false;
+
+    for (const line of lines) {
+        const trimmed = line.trim();
+
+        if (trimmed.includes('The following files were not formatted')) {
+            inFileList = true;
+            continue;
+        }
+
+        if (inFileList && trimmed.length > 0 && !trimmed.startsWith('[')) {
+            errors.push({
+                file: trimmed,
+                severity: 'error',
+                message: 'File is not properly formatted'
+            });
+        }
+
+        // End of file list
+        if (inFileList && (trimmed.startsWith('[') || trimmed === '')) {
+            inFileList = false;
+        }
+    }
+
+    // If no specific files found but exit code was non-zero, generic error
+    if (errors.length === 0 && (stdout.includes('FAILED') || stdout.includes('BUILD FAILURE'))) {
+        errors.push({
+            file: '',
+            severity: 'error',
+            message: 'Spotless check failed — run mvn spotless:apply to fix'
+        });
+    }
+
+    return { errors, warnings };
+}
+
+/**
+ * Parse sqlfluff JSON output into structured issues
+ *
+ * @param {string} stdout - sqlfluff JSON output
+ * @returns {{ errors: Array, warnings: Array }}
+ */
+export function parseSqlfluffOutput(stdout) {
+    const errors = [];
+    const warnings = [];
+
+    try {
+        const results = JSON.parse(stdout);
+
+        for (const fileResult of results) {
+            for (const violation of fileResult.violations || []) {
+                const issue = {
+                    file: fileResult.filepath || '',
+                    line: violation.start_line_no,
+                    column: violation.start_line_pos,
+                    severity: 'warning',
+                    message: violation.description,
+                    ruleId: violation.code || null
+                };
+
+                // sqlfluff L-rules are warnings, PRS/TMP are errors
+                if (violation.code && /^(PRS|TMP)/.test(violation.code)) {
+                    issue.severity = 'error';
+                    errors.push(issue);
+                } else {
+                    warnings.push(issue);
+                }
+            }
+        }
+    } catch {
+        if (stdout.trim()) {
+            errors.push({ file: '', severity: 'error', message: stdout.trim() });
+        }
+    }
+
+    return { errors, warnings };
+}
+
+/**
+ * Convert file paths to Spotless-compatible regex pattern
+ * Spotless -DspotlessFiles accepts a regex matching absolute file paths
+ *
+ * @param {string[]} files - Relative file paths
+ * @returns {string} Regex pattern
+ */
+export function filesToSpotlessRegex(files) {
+    const escaped = files.map((f) =>
+        f.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\//g, '[\\\\/]')
+    );
+    return escaped.join('|');
+}
+
+/**
+ * Available linter tool definitions
+ * @type {Object<string, import('./tool-runner.js').ToolDefinition>}
+ */
+export const LINTER_TOOLS = {
+    eslint: {
+        name: 'eslint',
+        command: 'npx',
+        args: (files) => ['eslint', '--format', 'json', '--no-error-on-unmatched-pattern', ...files],
+        fixArgs: (files) => ['eslint', '--fix', '--no-error-on-unmatched-pattern', ...files],
+        detectCommand: 'eslint',
+        detectInProjectFile: {
+            filename: 'package.json',
+            check: (content) => {
+                const pkg = JSON.parse(content);
+                const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+                return 'eslint' in allDeps;
+            }
+        },
+        installHint: 'npm install --save-dev eslint',
+        extensions: ['.js', '.jsx', '.ts', '.tsx'],
+        parseOutput: parseEslintOutput,
+        timeout: 30000
+    },
+    spotless: {
+        name: 'spotless',
+        command: 'mvn',
+        args: (files) => ['spotless:check', '-q', `-DspotlessFiles=${filesToSpotlessRegex(files)}`],
+        fixArgs: (files) => [
+            'spotless:apply',
+            '-q',
+            `-DspotlessFiles=${filesToSpotlessRegex(files)}`
+        ],
+        detectCommand: 'mvn',
+        detectInProjectFile: {
+            filename: 'pom.xml',
+            check: (content) => content.includes('spotless-maven-plugin')
+        },
+        installHint: 'Add spotless-maven-plugin to pom.xml (see https://github.com/diffplug/spotless)',
+        extensions: ['.java'],
+        parseOutput: parseSpotlessOutput,
+        timeout: 60000
+    },
+    sqlfluff: {
+        name: 'sqlfluff',
+        command: 'sqlfluff',
+        args: (files) => ['lint', '--format', 'json', ...files],
+        fixArgs: (files) => ['fix', '--force', ...files],
+        detectCommand: 'sqlfluff',
+        installHint: 'pip install sqlfluff',
+        extensions: ['.sql'],
+        parseOutput: parseSqlfluffOutput,
+        timeout: 30000
+    }
+};
+
+/**
+ * Preset-to-linter mapping
+ * Each preset lists the linter tool names it uses
+ * @type {Object<string, string[]>}
+ */
+export const PRESET_LINTERS = {
+    frontend: ['eslint'],
+    backend: ['spotless'],
+    fullstack: ['eslint', 'spotless'],
+    database: ['sqlfluff'],
+    ai: ['eslint'],
+    default: ['eslint']
+};
+
+/**
+ * Get linter tool definitions for a preset
+ *
+ * @param {string} presetName - Preset name
+ * @returns {import('./tool-runner.js').ToolDefinition[]} Tool definitions
+ */
+export function getLinterToolsForPreset(presetName) {
+    const toolNames = PRESET_LINTERS[presetName] || PRESET_LINTERS.default;
+    return toolNames.map((name) => LINTER_TOOLS[name]).filter(Boolean);
+}
+
+/**
+ * Run all applicable linters on a set of files
+ *
+ * @param {string[]} files - File paths to lint
+ * @param {Object} config - Configuration object (from config.js)
+ * @param {string} [presetName] - Preset name (default: 'default')
+ * @returns {{ results: ToolRunResult[], totalErrors: number, totalWarnings: number, totalFixed: number }}
+ */
+export function runLinters(files, config, presetName = 'default') {
+    const lintConfig = config.linting || {};
+    const autoFix = lintConfig.autoFix !== false;
+    const timeout = lintConfig.timeout || 30000;
+
+    const tools = getLinterToolsForPreset(presetName);
+    const results = [];
+
+    logger.debug('linter-runner - runLinters', 'Starting linters', {
+        preset: presetName,
+        tools: tools.map((t) => t.name),
+        fileCount: files.length,
+        autoFix
+    });
+
+    for (const toolDef of tools) {
+        // Filter files by tool's extensions
+        const matchingFiles = filterFilesByTool(files, toolDef);
+
+        if (matchingFiles.length === 0) {
+            logger.debug(
+                'linter-runner - runLinters',
+                `No files for ${toolDef.name}, skipping`
+            );
+            continue;
+        }
+
+        // Check tool availability
+        const availability = isToolAvailable(toolDef);
+
+        if (!availability.available) {
+            // Use specific hint from availability check (e.g., "configured but mvn not in PATH")
+            // or fall back to the tool's generic installHint
+            const hint = availability.installHint || `Install with: ${toolDef.installHint}`;
+            results.push({
+                tool: toolDef.name,
+                skipped: true,
+                skipReason: hint,
+                errors: [],
+                warnings: [],
+                fixedCount: 0,
+                fixedFiles: []
+            });
+            continue;
+        }
+
+        // Run tool with optional auto-fix
+        const result = runToolWithAutoFix(toolDef, matchingFiles, {
+            autoFix,
+            timeout,
+            restage: true
+        });
+
+        results.push(result);
+    }
+
+    // Aggregate totals
+    const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+    const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0);
+    const totalFixed = results.reduce((sum, r) => sum + r.fixedCount, 0);
+
+    logger.debug('linter-runner - runLinters', 'Linting complete', {
+        totalErrors,
+        totalWarnings,
+        totalFixed,
+        toolsRun: results.filter((r) => !r.skipped).length,
+        toolsSkipped: results.filter((r) => r.skipped).length
+    });
+
+    return { results, totalErrors, totalWarnings, totalFixed };
+}
+
+/**
+ * Display aggregated lint results
+ *
+ * @param {{ results: ToolRunResult[], totalErrors: number, totalWarnings: number, totalFixed: number }} lintResult
+ */
+export function displayLintResults(lintResult) {
+    const { results, totalErrors, totalWarnings, totalFixed } = lintResult;
+
+    console.log('\n🔍 Linting results:');
+
+    for (const result of results) {
+        displayToolResult(result);
+    }
+
+    if (totalFixed > 0) {
+        console.log(`\n   🔧 Auto-fixed ${totalFixed} file(s) and re-staged`);
+    }
+
+    if (totalErrors > 0) {
+        console.log(`\n   ❌ ${totalErrors} error(s) found`);
+    }
+
+    if (totalWarnings > 0 && totalErrors === 0) {
+        console.log(`\n   ⚠️  ${totalWarnings} warning(s) — commit not blocked`);
+    }
+
+    if (totalErrors === 0 && totalWarnings === 0 && results.every((r) => !r.skipped)) {
+        console.log('   ✅ All linters passed');
+    }
+
+    console.log();
+}
+
+/**
+ * Convert remaining (unfixable) lint issues to Claude analysis detail format
+ * so they can be passed to the judge for semantic fixes.
+ *
+ * @param {{ results: ToolRunResult[], totalErrors: number, totalWarnings: number }} lintResult
+ * @returns {Array<Object>} Issues in Claude analysis detail format
+ */
+export function lintIssuesToAnalysisDetails(lintResult) {
+    const details = [];
+    // Judge expects relative paths — ESLint outputs absolute paths
+    let repoRoot;
+    try {
+        repoRoot = getRepoRoot();
+    } catch {
+        repoRoot = process.cwd();
+    }
+
+    for (const result of lintResult.results) {
+        if (result.skipped) continue;
+
+        for (const issue of [...result.errors, ...result.warnings]) {
+            // Convert absolute paths to relative (judge prepends repoRoot)
+            let filePath = issue.file || '';
+            if (path.isAbsolute(filePath)) {
+                filePath = path.relative(repoRoot, filePath);
+            }
+
+            details.push({
+                severity: issue.severity === 'error' ? 'major' : 'minor',
+                type: 'lint',
+                category: 'lint',
+                file: filePath,
+                line: issue.line || null,
+                message: issue.message,
+                description: `[${result.tool}] ${issue.message}`,
+                rule: issue.ruleId || null,
+                source: 'linter'
+            });
+        }
+    }
+
+    return details;
+}
+
+/**
+ * Check linter availability for a preset and log install instructions
+ * Used during hook installation (informational only, does not block)
+ *
+ * @param {string} presetName - Preset name
+ */
+export function checkLinterAvailability(presetName) {
+    const tools = getLinterToolsForPreset(presetName);
+
+    if (tools.length === 0) {
+        return;
+    }
+
+    console.log(`\n🔍 Checking linter availability for '${presetName}' preset...`);
+
+    for (const toolDef of tools) {
+        const availability = isToolAvailable(toolDef);
+
+        if (availability.available) {
+            console.log(`   ✅ ${toolDef.name} — found`);
+        } else if (availability.installHint) {
+            // Configured in project but command binary missing
+            console.log(`   ⚠️  ${toolDef.name} — skipped`);
+            console.log(`      💡 ${availability.installHint}`);
+        } else {
+            console.log(`   ⚠️  ${toolDef.name} — not found`);
+            console.log(`      💡 Install with: ${toolDef.installHint}`);
+        }
+    }
+
+    console.log('   Linting will skip unavailable tools at commit time.\n');
+}