claude-git-hooks 2.33.1 → 2.34.0

package/lib/utils/tool-runner.js

@@ -0,0 +1,418 @@
+/**
+ * File: tool-runner.js
+ * Purpose: Generic external tool executor for pre-commit pipeline
+ *
+ * Shared infrastructure for running external tools (linters, formatters)
+ * on staged or user-specified files. Each tool is defined as a ToolDefinition
+ * object with command, args builders, output parser, and install hints.
+ *
+ * Designed for extensibility:
+ * - Linters use this via linter-runner.js (Issue #22)
+ * - Formatters will use this via formatter-runner.js (Issue #26)
+ *
+ * Dependencies:
+ * - which-command: Cross-platform executable resolution
+ * - child_process: Tool execution
+ * - git-operations: Re-staging fixed files
+ * - logger: Debug and error logging
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { which } from './which-command.js';
+import { walkDirectoryTree } from './file-utils.js';
+import logger from './logger.js';
+
+/**
+ * @typedef {Object} ToolDefinition
+ * @property {string} name - Tool display name (e.g., 'eslint')
+ * @property {string} command - Primary command to execute (e.g., 'npx', 'mvn')
+ * @property {function(string[]): string[]} args - Build args for check mode
+ * @property {function(string[]): string[]} [fixArgs] - Build args for auto-fix mode
+ * @property {string} detectCommand - Binary to check via which() (e.g., 'eslint')
+ * @property {string} [detectFallback] - Fallback path to check (e.g., 'node_modules/.bin/eslint')
+ * @property {string} installHint - Install instruction shown when tool is missing
+ * @property {string[]} extensions - File extensions this tool handles
+ * @property {function(string): Object} parseOutput - Parse stdout into structured results
+ * @property {number} [timeout] - Per-tool timeout in ms (default from config)
+ */
+
+/**
+ * @typedef {Object} ToolIssue
+ * @property {string} file - File path
+ * @property {number} [line] - Line number
+ * @property {number} [column] - Column number
+ * @property {string} severity - 'error' or 'warning'
+ * @property {string} message - Issue description
+ * @property {string} [ruleId] - Linter rule identifier
+ */
+
+/**
+ * @typedef {Object} ToolRunResult
+ * @property {string} tool - Tool name
+ * @property {boolean} skipped - Whether tool was skipped (not installed)
+ * @property {string} [skipReason] - Why the tool was skipped
+ * @property {ToolIssue[]} errors - Error-level issues
+ * @property {ToolIssue[]} warnings - Warning-level issues
+ * @property {number} fixedCount - Number of issues auto-fixed
+ * @property {string[]} fixedFiles - Files that were auto-fixed
+ */
+
+/**
+ * Check if a tool is available on the system
+ *
+ * @param {ToolDefinition} toolDef - Tool definition
+ * @returns {{ available: boolean, path: string|null }} Availability info
+ */
+export function isToolAvailable(toolDef) {
+    // Strategy 1: Check detectCommand in PATH (global install)
+    const resolved = which(toolDef.detectCommand);
+    if (resolved) {
+        logger.debug('tool-runner - isToolAvailable', `Found ${toolDef.name} in PATH`, { path: resolved });
+        return { available: true, path: resolved };
+    }
+
+    // Strategy 2: Check project files for the tool as a dependency
+    // Why: local installs (npm install --save-dev) live in node_modules/.bin,
+    // not in PATH. npx resolves them at runtime, so we just need to confirm
+    // the tool is declared in a project file (package.json deps or pom.xml plugin).
+    // Uses walkDirectoryTree (same walker as version-manager) to scan up to 3 levels.
+    if (toolDef.detectInProjectFile) {
+        const found = _detectInProjectFiles(toolDef);
+        if (found) {
+            // Tool is configured but the command binary is missing
+            if (found.configured && !found.available) {
+                logger.debug('tool-runner - isToolAvailable',
+                    `${toolDef.name} configured but '${found.missingCommand}' not in PATH`
+                );
+                return {
+                    available: false,
+                    path: null,
+                    installHint: `${toolDef.name} is configured in your project but '${found.missingCommand}' is not in PATH. Install it and ensure it's accessible from your terminal.`
+                };
+            }
+            return found;
+        }
+    }
+
+    logger.debug('tool-runner - isToolAvailable', `${toolDef.name} not found`);
+    return { available: false, path: null };
+}
+
+/**
+ * Scan project files (package.json, pom.xml) up to 3 levels deep
+ * to detect if a tool is declared as a dependency or plugin.
+ *
+ * @param {ToolDefinition} toolDef - Tool definition with detectInProjectFile
+ * @returns {{ available: boolean, path: string|null } | null} Result or null if not found
+ */
+export function _detectInProjectFiles(toolDef) {
+    const { filename, check } = toolDef.detectInProjectFile;
+    let found = false;
+
+    walkDirectoryTree(process.cwd(), {
+        maxDepth: 3,
+        ignoreSet: new Set([
+            '.git', 'node_modules', 'target', 'build', 'dist',
+            '__pycache__', '.venv', 'vendor', 'out', 'coverage'
+        ]),
+        onFile: (entry, fullPath) => {
+            if (found) return; // short-circuit after first match
+            if (entry.name === filename) {
+                try {
+                    const content = fs.readFileSync(fullPath, 'utf8');
+                    if (check(content)) {
+                        logger.debug('tool-runner - _detectInProjectFiles',
+                            `Found ${toolDef.name} in ${path.relative(process.cwd(), fullPath)}`
+                        );
+                        found = true;
+                    }
+                } catch {
+                    // File read error — skip
+                }
+            }
+        }
+    });
+
+    if (!found) {
+        return null;
+    }
+
+    // Project file declares the tool, but can we actually run the command?
+    // npx-based tools (eslint, etc.) are resolved by npx at runtime — always OK.
+    // Non-npx tools (mvn, sqlfluff, etc.) need the command binary in PATH.
+    if (toolDef.command !== 'npx') {
+        const cmdResolved = which(toolDef.command);
+        if (!cmdResolved) {
+            logger.debug('tool-runner - _detectInProjectFiles',
+                `${toolDef.name} configured in project but '${toolDef.command}' not in PATH`
+            );
+            return {
+                available: false,
+                path: null,
+                configured: true,
+                missingCommand: toolDef.command
+            };
+        }
+    }
+
+    return { available: true, path: toolDef.command };
+}
+
+/**
+ * Filter files by tool's supported extensions
+ *
+ * @param {string[]} files - File paths
+ * @param {ToolDefinition} toolDef - Tool definition
+ * @returns {string[]} Files matching tool's extensions
+ */
+export function filterFilesByTool(files, toolDef) {
+    return files.filter((file) => {
+        const ext = path.extname(file).toLowerCase();
+        return toolDef.extensions.includes(ext);
+    });
+}
+
+/**
+ * Execute a tool on files and parse output
+ *
+ * @param {ToolDefinition} toolDef - Tool definition
+ * @param {string[]} files - Files to process
+ * @param {Object} options - Execution options
+ * @param {number} [options.timeout] - Timeout in ms
+ * @param {string} [options.cwd] - Working directory
+ * @returns {ToolRunResult} Parsed result
+ */
+export function runTool(toolDef, files, options = {}) {
+    const { timeout = toolDef.timeout || 30000, cwd = process.cwd() } = options;
+
+    const args = toolDef.args(files);
+    const fullCommand = [toolDef.command, ...args].join(' ');
+
+    logger.debug('tool-runner - runTool', `Executing ${toolDef.name}`, {
+        command: fullCommand,
+        fileCount: files.length,
+        timeout
+    });
+
+    const result = {
+        tool: toolDef.name,
+        skipped: false,
+        errors: [],
+        warnings: [],
+        fixedCount: 0,
+        fixedFiles: []
+    };
+
+    try {
+        const stdout = execSync(fullCommand, {
+            encoding: 'utf8',
+            timeout,
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        // Exit code 0 = no issues; parse anyway for warnings
+        if (toolDef.parseOutput && stdout.trim()) {
+            const parsed = toolDef.parseOutput(stdout);
+            result.errors = parsed.errors || [];
+            result.warnings = parsed.warnings || [];
+        }
+    } catch (err) {
+        // Many linters exit non-zero when issues are found — this is expected
+        if (err.stdout && toolDef.parseOutput) {
+            const parsed = toolDef.parseOutput(err.stdout);
+            result.errors = parsed.errors || [];
+            result.warnings = parsed.warnings || [];
+        } else if (err.killed) {
+            // Timeout
+            logger.warning(`${toolDef.name} timed out after ${timeout}ms`);
+            result.errors.push({
+                file: '',
+                severity: 'error',
+                message: `${toolDef.name} timed out after ${timeout / 1000}s`
+            });
+        } else {
+            // Genuine execution error
+            const stderr = err.stderr ? err.stderr.toString().trim() : '';
+            logger.debug('tool-runner - runTool', `${toolDef.name} execution error`, {
+                exitCode: err.status,
+                stderr
+            });
+
+            // If no parseable output, treat as tool error
+            if (!err.stdout) {
+                result.errors.push({
+                    file: '',
+                    severity: 'error',
+                    message: `${toolDef.name} failed: ${stderr || err.message}`
+                });
+            }
+        }
+    }
+
+    logger.debug('tool-runner - runTool', `${toolDef.name} complete`, {
+        errors: result.errors.length,
+        warnings: result.warnings.length
+    });
+
+    return result;
+}
+
+/**
+ * Run a tool's auto-fix command, then re-stage fixed files
+ *
+ * @param {ToolDefinition} toolDef - Tool definition (must have fixArgs)
+ * @param {string[]} files - Files to fix
+ * @param {Object} options - Execution options
+ * @param {number} [options.timeout] - Timeout in ms
+ * @param {string} [options.cwd] - Working directory
+ * @param {boolean} [options.restage] - Re-stage fixed files (default: true)
+ * @returns {{ fixedFiles: string[], fixedCount: number }} Fix results
+ */
+export function runToolFix(toolDef, files, options = {}) {
+    const { timeout = toolDef.timeout || 30000, cwd = process.cwd(), restage = true } = options;
+
+    if (!toolDef.fixArgs) {
+        logger.debug('tool-runner - runToolFix', `${toolDef.name} has no fixArgs, skipping`);
+        return { fixedFiles: [], fixedCount: 0 };
+    }
+
+    const args = toolDef.fixArgs(files);
+    const fullCommand = [toolDef.command, ...args].join(' ');
+
+    logger.debug('tool-runner - runToolFix', `Auto-fixing with ${toolDef.name}`, {
+        command: fullCommand,
+        fileCount: files.length
+    });
+
+    try {
+        execSync(fullCommand, {
+            encoding: 'utf8',
+            timeout,
+            cwd,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+    } catch (err) {
+        if (err.killed) {
+            logger.warning(`${toolDef.name} auto-fix timed out`);
+            return { fixedFiles: [], fixedCount: 0 };
+        }
+        // Distinguish "command not found" from "partial fix exited non-zero"
+        // Exit code 1 with stderr containing "not recognized" or "not found" = command missing
+        const stderr = err.stderr ? err.stderr.toString() : '';
+        if (err.status === 1 && !err.stdout && (
+            stderr.includes('not recognized') ||
+            stderr.includes('not found') ||
+            stderr.includes('ENOENT')
+        )) {
+            logger.debug('tool-runner - runToolFix', `${toolDef.name} command not available`, {
+                stderr: stderr.trim()
+            });
+            return { fixedFiles: [], fixedCount: 0 };
+        }
+        // Genuine partial fix — proceed to restage
+        logger.debug('tool-runner - runToolFix', `${toolDef.name} fix exited non-zero`, {
+            exitCode: err.status
+        });
+    }
+
+    // Re-stage the files that were modified by the fix
+    const fixedFiles = [];
+    if (restage) {
+        for (const file of files) {
+            try {
+                execSync(`git add "${file}"`, { cwd, stdio: 'pipe' });
+                fixedFiles.push(file);
+            } catch {
+                // File may not have changed; that's fine
+            }
+        }
+    }
+
+    logger.debug('tool-runner - runToolFix', `${toolDef.name} fix complete`, {
+        restagedFiles: fixedFiles.length
+    });
+
+    return { fixedFiles, fixedCount: fixedFiles.length };
+}
+
+/**
+ * Run a tool with auto-fix: check → fix → re-check
+ *
+ * @param {ToolDefinition} toolDef - Tool definition
+ * @param {string[]} files - Files to process
+ * @param {Object} options - Execution options
+ * @param {boolean} [options.autoFix] - Enable auto-fix (default: false)
+ * @param {number} [options.timeout] - Timeout in ms
+ * @param {string} [options.cwd] - Working directory
+ * @param {boolean} [options.restage] - Re-stage after fix (default: true)
+ * @returns {ToolRunResult} Final result after optional fix
+ */
+export function runToolWithAutoFix(toolDef, files, options = {}) {
+    const { autoFix = false } = options;
+
+    // Step 1: Initial check
+    const initialResult = runTool(toolDef, files, options);
+
+    // Step 2: If any issues (errors or warnings) and autoFix enabled, try to fix
+    const hasIssues = initialResult.errors.length > 0 || initialResult.warnings.length > 0;
+    if (autoFix && toolDef.fixArgs && hasIssues) {
+        logger.info(`🔧 Auto-fixing ${toolDef.name} issues...`);
+
+        const fixResult = runToolFix(toolDef, files, options);
+
+        if (fixResult.fixedCount > 0) {
+            // Step 3: Re-check after fix
+            const recheck = runTool(toolDef, files, options);
+            recheck.fixedCount = fixResult.fixedCount;
+            recheck.fixedFiles = fixResult.fixedFiles;
+            return recheck;
+        }
+    }
+
+    return initialResult;
+}
+
+/**
+ * Display results for a single tool run
+ *
+ * @param {ToolRunResult} result - Tool run result
+ */
+export function displayToolResult(result) {
+    if (result.skipped) {
+        logger.warning(`⚠️  ${result.tool} — skipped`);
+        if (result.skipReason) {
+            logger.info(`      💡 ${result.skipReason}`);
+        }
+        return;
+    }
+
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+        logger.info(`   ✅ ${result.tool} — no issues`);
+        return;
+    }
+
+    if (result.fixedCount > 0) {
+        logger.info(
+            `   🔧 ${result.tool} — auto-fixed ${result.fixedCount} file(s)`
+        );
+    }
+
+    for (const issue of result.errors) {
+        const location = issue.file
+            ? `${issue.file}${issue.line ? `:${issue.line}` : ''}`
+            : '';
+        const rule = issue.ruleId ? ` (${issue.ruleId})` : '';
+        console.log(`   ❌ ${location} ${issue.message}${rule}`);
+    }
+
+    for (const issue of result.warnings) {
+        const location = issue.file
+            ? `${issue.file}${issue.line ? `:${issue.line}` : ''}`
+            : '';
+        const rule = issue.ruleId ? ` (${issue.ruleId})` : '';
+        console.log(`   ⚠️  ${location} ${issue.message}${rule}`);
+    }
+}

package/package.json

@@ -1,69 +1,69 @@
-{
-    "name": "claude-git-hooks",
-    "version": "2.33.1",
-    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
-    "type": "module",
-    "bin": {
-        "claude-hooks": "./bin/claude-hooks"
-    },
-    "scripts": {
-        "test": "npm run test:all",
-        "test:all": "npm run lint && npm run test:smoke && npm run test:unit && npm run test:integration",
-        "test:smoke": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/smoke --maxWorkers=1",
-        "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --forceExit",
-        "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration --maxWorkers=1 --testTimeout=30000 --forceExit",
-        "test:integration:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration/ci-safe.test.js --maxWorkers=1 --testTimeout=30000 --forceExit",
-        "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
-        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-        "lint": "eslint lib/ bin/claude-hooks",
-        "lint:fix": "eslint lib/ bin/claude-hooks --fix",
-        "format": "prettier --write \"lib/**/*.js\" \"bin/**\" \"test/**/*.js\"",
-        "precommit": "npm run lint && npm run test:smoke",
-        "prepublishOnly": "npm run test:all"
-    },
-    "keywords": [
-        "git",
-        "hooks",
-        "claude",
-        "ai",
-        "code-review",
-        "commit-messages",
-        "pre-commit",
-        "automation"
-    ],
-    "author": "Pablo Rovito",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/mscope-S-L/git-hooks.git"
-    },
-    "engines": {
-        "node": ">=16.9.0"
-    },
-    "engineStrict": false,
-    "os": [
-        "darwin",
-        "linux",
-        "win32"
-    ],
-    "preferGlobal": true,
-    "files": [
-        "bin/",
-        "lib/",
-        "templates/",
-        "README.md",
-        "CHANGELOG.md",
-        "CLAUDE.md",
-        "LICENSE"
-    ],
-    "dependencies": {
-        "@octokit/rest": "^21.0.0"
-    },
-    "devDependencies": {
-        "@types/jest": "^29.5.0",
-        "eslint": "^8.57.0",
-        "jest": "^29.7.0",
-        "prettier": "^3.2.0"
-    }
-}
+{
+    "name": "claude-git-hooks",
+    "version": "2.34.0",
+    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
+    "type": "module",
+    "bin": {
+        "claude-hooks": "./bin/claude-hooks"
+    },
+    "scripts": {
+        "test": "npm run test:all",
+        "test:all": "npm run lint && npm run test:smoke && npm run test:unit && npm run test:integration",
+        "test:smoke": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/smoke --maxWorkers=1",
+        "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --forceExit",
+        "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration --maxWorkers=1 --testTimeout=30000 --forceExit",
+        "test:integration:ci": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/integration/ci-safe.test.js --maxWorkers=1 --testTimeout=30000 --forceExit",
+        "test:changed": "node --experimental-vm-modules node_modules/jest/bin/jest.js test/unit --changedSince=main --forceExit",
+        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+        "lint": "eslint lib/ bin/claude-hooks",
+        "lint:fix": "eslint lib/ bin/claude-hooks --fix",
+        "format": "prettier --write \"lib/**/*.js\" \"bin/**\" \"test/**/*.js\"",
+        "precommit": "npm run lint && npm run test:smoke",
+        "prepublishOnly": "npm run test:all"
+    },
+    "keywords": [
+        "git",
+        "hooks",
+        "claude",
+        "ai",
+        "code-review",
+        "commit-messages",
+        "pre-commit",
+        "automation"
+    ],
+    "author": "Pablo Rovito",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mscope-S-L/git-hooks.git"
+    },
+    "engines": {
+        "node": ">=16.9.0"
+    },
+    "engineStrict": false,
+    "os": [
+        "darwin",
+        "linux",
+        "win32"
+    ],
+    "preferGlobal": true,
+    "files": [
+        "bin/",
+        "lib/",
+        "templates/",
+        "README.md",
+        "CHANGELOG.md",
+        "CLAUDE.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "@octokit/rest": "^21.0.0"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.0",
+        "eslint": "^8.57.1",
+        "jest": "^29.7.0",
+        "prettier": "^3.2.0"
+    }
+}

package/templates/config.advanced.example.json

@@ -47,6 +47,14 @@
                 "documentation",
                 "testing"
             ]
+        },
+
+        "linting": {
+            "enabled": true,
+            "autoFix": true,
+            "failOnError": true,
+            "failOnWarning": false,
+            "timeout": 30000
         }
     },
 
@@ -105,6 +113,36 @@
             "description": "Categories for general (review-level) comments",
             "default": "[\"ticket-alignment\", \"scope\", \"style\", \"good-practice\", \"extensibility\", \"observability\", \"documentation\", \"testing\"]",
             "use_case": "Customize which observation types appear in the review body"
+        },
+
+        "linting.enabled": {
+            "description": "Enable/disable linter execution before Claude analysis in pre-commit hook and lint command",
+            "default": "true",
+            "use_case": "Set to false to skip linting entirely"
+        },
+
+        "linting.autoFix": {
+            "description": "Automatically fix linting issues and re-stage files",
+            "default": "true",
+            "use_case": "Set to false to only report issues without fixing"
+        },
+
+        "linting.failOnError": {
+            "description": "Block commit when linter reports errors",
+            "default": "true",
+            "use_case": "Set to false to allow commits with linting errors (not recommended)"
+        },
+
+        "linting.failOnWarning": {
+            "description": "Block commit when linter reports warnings",
+            "default": "false",
+            "use_case": "Set to true for strict projects that treat warnings as errors"
+        },
+
+        "linting.timeout": {
+            "description": "Timeout in milliseconds for each linter execution",
+            "default": "30000",
+            "use_case": "Increase for large projects where linters take longer"
         }
     },