claude-git-hooks 2.35.3 → 2.44.0

package/lib/commands/lint.js

@@ -8,6 +8,7 @@
  *   claude-hooks lint src/ lib/utils/          # multiple directories
  *   claude-hooks lint file1.js file2.java      # specific files
  *   claude-hooks lint src/ file3.js lib/       # mix of dirs and files
+ *   claude-hooks lint --headless --format json # CI mode with JSON output
  *
  * Path resolution (like git add):
  * - Directories → walk and collect files matching preset extensions
@@ -32,6 +33,28 @@ import { getStagedFiles, getRepoRoot } from '../utils/git-operations.js';
 import { runLinters, displayLintResults } from '../utils/linter-runner.js';
 import logger from '../utils/logger.js';
 
+// ─── JSON Error Helper ────────────────────────────────────────────────────
+
+/**
+ * Emit error JSON to stdout and set exit code
+ * @param {string} message - Error message
+ * @param {number} exitCode - Process exit code (default: 1)
+ * @private
+ */
+function _emitErrorJSON(message, exitCode = 1) {
+    process.stdout.write(`${JSON.stringify({ status: 'error', error: message })}\n`);
+    process.exitCode = exitCode;
+}
+
+/**
+ * Emit JSON result to stdout (does not exit — caller handles exit)
+ * @param {Object} payload - JSON payload
+ * @private
+ */
+function _emitJSON(payload) {
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
 /**
  * Resolve user-provided paths into a flat list of files
  * Handles directories (walked recursively), individual files, and mixtures.
@@ -116,13 +139,34 @@ function _walkForFiles(dir, extSet, files, depth = 0) {
     }
 }
 
+// Known flags that should not be treated as paths
+const KNOWN_FLAGS = new Set(['--headless', '--format']);
+
 /**
  * Main lint command handler
  *
  * @param {string[]} args - CLI arguments (paths and flags)
  */
 export async function runLint(args = []) {
+    // Parse flags
+    const headless = args.includes('--headless');
+    const fmtIdx = args.indexOf('--format');
+    const format = fmtIdx >= 0 ? args[fmtIdx + 1] : null;
+    const isJSON = format === 'json';
+
+    // Disallowed combo: --format json without --headless
+    if (isJSON && !headless) {
+        _emitErrorJSON('--format json requires --headless', 2);
+        return;
+    }
+
+    // Activate JSON mode before any output so info/warning route to stderr
+    if (isJSON) logger.setJSONMode(true);
+
+    const startTime = Date.now();
+
     if (!checkGitRepo()) {
+        if (isJSON) { _emitErrorJSON('Not a git repository'); return; }
         error('Not a git repository');
         process.exit(1);
     }
@@ -134,6 +178,19 @@ export async function runLint(args = []) {
     }
 
     if (config.linting?.enabled === false) {
+        if (isJSON) {
+            _emitJSON({
+                status: 'disabled',
+                preset: config.preset || 'default',
+                fileCount: 0,
+                totalErrors: 0,
+                totalWarnings: 0,
+                durationMs: Date.now() - startTime,
+                tools: []
+            });
+            process.exit(0);
+            return;
+        }
         info('Linting is disabled in configuration');
         return;
     }
@@ -142,8 +199,14 @@ export async function runLint(args = []) {
     const presetName = config.preset || 'default';
     const { metadata } = await loadPreset(presetName);
 
-    // Separate flags from paths
-    const paths = args.filter((a) => !a.startsWith('--'));
+    // Separate flags from paths — filter out known flags and their values
+    const paths = args.filter((a, i) => {
+        if (KNOWN_FLAGS.has(a)) return false;
+        // Skip value immediately after a flag that takes a value
+        if (i > 0 && args[i - 1] === '--format') return false;
+        if (a.startsWith('--')) return false;
+        return true;
+    });
 
     let filesToLint;
 
@@ -153,6 +216,19 @@ export async function runLint(args = []) {
         const stagedFiles = getStagedFiles({ extensions: metadata.fileExtensions });
 
         if (stagedFiles.length === 0) {
+            if (isJSON) {
+                _emitJSON({
+                    status: 'no-files',
+                    preset: presetName,
+                    fileCount: 0,
+                    totalErrors: 0,
+                    totalWarnings: 0,
+                    durationMs: Date.now() - startTime,
+                    tools: []
+                });
+                process.exit(0);
+                return; // guard test-mode fallthrough
+            }
             info('No staged files to lint');
             return;
         }
@@ -163,6 +239,18 @@ export async function runLint(args = []) {
         filesToLint = resolvePaths(paths, metadata.fileExtensions, repoRoot);
 
         if (filesToLint.length === 0) {
+            if (isJSON) {
+                _emitJSON({
+                    status: 'no-files',
+                    preset: presetName,
+                    fileCount: 0,
+                    totalErrors: 0,
+                    totalWarnings: 0,
+                    durationMs: Date.now() - startTime,
+                    tools: []
+                });
+                process.exit(0);
+            }
             info('No matching files found in specified paths');
             return;
         }
@@ -171,12 +259,40 @@ export async function runLint(args = []) {
     info(`🎯 Linting ${filesToLint.length} file(s) with '${metadata.displayName}' preset`);
 
     const lintResult = await runLinters(filesToLint, config, presetName);
-    displayLintResults(lintResult);
 
-    // Exit with error code if linting failed
+    if (!isJSON) {
+        displayLintResults(lintResult);
+    }
+
+    // Determine failure status
     const failOnError = config.linting?.failOnError !== false;
     const failOnWarning = config.linting?.failOnWarning === true;
+    const shouldFail =
+        (failOnError && lintResult.totalErrors > 0) ||
+        (failOnWarning && lintResult.totalWarnings > 0);
 
+    if (isJSON) {
+        _emitJSON({
+            status: shouldFail ? 'fail' : 'pass',
+            preset: presetName,
+            fileCount: filesToLint.length,
+            totalErrors: lintResult.totalErrors,
+            totalWarnings: lintResult.totalWarnings,
+            durationMs: Date.now() - startTime,
+            tools: lintResult.results.map((r) => ({
+                name: r.tool,
+                files: r.files || 0,
+                errors: r.errors.length,
+                warnings: r.warnings.length,
+                fixed: r.fixedCount || 0,
+                issues: [...r.errors, ...r.warnings]
+            }))
+        });
+        process.exit(shouldFail ? 1 : 0);
+        return;
+    }
+
+    // Exit with error code if linting failed
     if (failOnError && lintResult.totalErrors > 0) {
         process.exit(1);
     }

package/lib/config.js

@@ -91,6 +91,9 @@ const HARDCODED = {
         failOnError: true, // Block commit on linting errors
         failOnWarning: false, // Do not block on warnings
         timeout: 30000 // 30s per linter
+    },
+    claude: {
+        defaultModel: 'sonnet' // Fallback model for SDK headless mode
     }
 };
 

package/lib/hooks/pre-commit.js

@@ -19,7 +19,8 @@
  * - resolution-prompt: Issue resolution generation
  */
 
-import { getStagedFiles, getRepoRoot } from '../utils/git-operations.js';
+import { getStagedFiles, getRepoRoot, getStagedTreeSha } from '../utils/git-operations.js';
+import { writeMarker } from '../utils/hooks-verified-marker.js';
 import { filterFiles } from '../utils/file-operations.js';
 import {
     buildFilesData,
@@ -53,6 +54,10 @@ import { runLinters, displayLintResults, lintIssuesToAnalysisDetails } from '../
 const main = async () => {
     const startTime = Date.now();
 
+    // Headless mode: activated by env var for CI/ECS environments (CT-805)
+    // Declared before try/catch so the catch block can show appropriate error messages
+    const isHeadless = process.env.CLAUDE_HOOKS_HEADLESS === '1';
+
     try {
         // Load configuration
         const config = await getConfig();
@@ -194,7 +199,8 @@ const main = async () => {
         // Step 6: Run analysis using shared engine
         const result = await runAnalysis(filesData, config, {
             hook: 'pre-commit',
-            saveDebug: config.system.debug
+            saveDebug: config.system.debug,
+            headless: isHeadless
         });
 
         // Step 7: Display results using shared function
@@ -234,7 +240,7 @@ const main = async () => {
             if (judgeModule) {
                 try {
                     const { judgeAndFix } = judgeModule;
-                    const judgeResult = await judgeAndFix(result, filesData, config);
+                    const judgeResult = await judgeAndFix(result, filesData, config, { headless: isHeadless });
 
                     // Update result with remaining issues (fixed + false positives removed)
                     result.blockingIssues = judgeResult.remainingIssues.filter((i) =>
@@ -341,6 +347,16 @@ const main = async () => {
         console.log(`\n⏱️  Analysis time: ${duration}s`);
         logger.success('Code analysis completed. Quality gate passed.');
 
+        // Write hooks-verified marker for prepare-commit-msg trailer
+        try {
+            const treeSha = getStagedTreeSha();
+            writeMarker(repoRoot, treeSha, version);
+            logger.debug('pre-commit - main', 'Hooks-verified marker written', { treeSha });
+        } catch (markerErr) {
+            // Non-fatal: trailer won't be added but commit still succeeds
+            logger.warning(`Could not write hooks-verified marker: ${markerErr.message}`);
+        }
+
         process.exit(0);
     } catch (error) {
         // Record analysis failure metric
@@ -356,8 +372,13 @@ const main = async () => {
 
         logger.error('pre-commit - main', 'Pre-commit hook failed', error);
 
-        console.error('\nError executing Claude CLI');
-        console.error('Check that Claude CLI is configured correctly');
+        if (isHeadless) {
+            console.error('\nError executing Claude SDK');
+            console.error('Check that ANTHROPIC_API_KEY is set correctly');
+        } else {
+            console.error('\nError executing Claude CLI');
+            console.error('Check that Claude CLI is configured correctly');
+        }
 
         if (error.output) {
             console.error('\nClaude CLI output:');

package/lib/hooks/prepare-commit-msg.js

@@ -18,7 +18,15 @@
  */
 
 import fs from 'fs/promises';
-import { getStagedFiles, getStagedStats, getFileDiff } from '../utils/git-operations.js';
+import {
+    getStagedFiles,
+    getStagedStats,
+    getFileDiff,
+    getRepoRoot,
+    getStagedTreeSha,
+    appendTrailer
+} from '../utils/git-operations.js';
+import { readMarker, consumeMarker, validateMarker } from '../utils/hooks-verified-marker.js';
 import { analyzeCode } from '../utils/claude-client.js';
 import { loadPrompt } from '../utils/prompt-builder.js';
 import { getVersion } from '../utils/package-info.js';
@@ -119,6 +127,9 @@ const main = async () => {
     // Load configuration (includes preset + user overrides)
     const config = await getConfig();
 
+    // Headless mode: activated by env var for CI/ECS environments (CT-805)
+    const isHeadless = process.env.CLAUDE_HOOKS_HEADLESS === '1';
+
     // Enable debug mode from config
     if (config.system.debug) {
         logger.setDebugMode(true);
@@ -134,11 +145,44 @@ const main = async () => {
 
         // Only process normal commits
         // Why: Don't interfere with merge commits, amend, squash, etc.
+        // Marker is NOT consumed here — stays for the next eligible commit
         if (commitSource && commitSource !== 'message') {
             logger.debug('prepare-commit-msg - main', `Skipping: commit source is ${commitSource}`);
             process.exit(0);
         }
 
+        // Hooks-Verified trailer: validate marker now, append trailer at the very end.
+        // Why: The auto-message flow overwrites the commit file, so we can't append
+        // the trailer until the final message is written. We validate+consume the marker
+        // early (before the auto check) and remember the result for later.
+        const repoRoot = getRepoRoot();
+        const marker = readMarker(repoRoot);
+        let shouldAppendTrailer = false;
+
+        if (marker) {
+            let currentTreeSha;
+            try {
+                currentTreeSha = getStagedTreeSha();
+            } catch (err) {
+                logger.debug('prepare-commit-msg - main', 'Could not compute staged tree SHA', {
+                    err: err.message
+                });
+            }
+
+            if (currentTreeSha && validateMarker(marker, currentTreeSha)) {
+                shouldAppendTrailer = true;
+                logger.debug('prepare-commit-msg - main', 'Marker valid; trailer will be appended after message is finalized');
+            } else {
+                logger.debug(
+                    'prepare-commit-msg - main',
+                    'Marker stale (tree mismatch); ignoring'
+                );
+            }
+
+            // Always consume marker (whether matched or not) — no stale carryover
+            consumeMarker(repoRoot);
+        }
+
         // Read current message
         const currentMsg = await fs.readFile(commitMsgFile, 'utf8');
         const firstLine = currentMsg.split('\n')[0].trim();
@@ -147,6 +191,16 @@ const main = async () => {
 
         // Check if message is "auto"
         if (firstLine !== config.commitMessage.autoKeyword) {
+            // Not auto — append trailer to the manual message and exit
+            if (shouldAppendTrailer) {
+                try {
+                    const withTrailer = appendTrailer(currentMsg, 'Hooks-Verified', 'true');
+                    await fs.writeFile(commitMsgFile, withTrailer, 'utf8');
+                    logger.debug('prepare-commit-msg - main', 'Hooks-Verified trailer appended to manual message');
+                } catch (trailerErr) {
+                    logger.warning(`Could not append Hooks-Verified trailer: ${trailerErr.message}`);
+                }
+            }
             logger.debug('prepare-commit-msg - main', 'Not generating: message is not "auto"');
             process.exit(0);
         }
@@ -243,7 +297,8 @@ const main = async () => {
         const response = await analyzeCode(prompt, {
             timeout: config.commitMessage.timeout,
             saveDebug: config.system.debug,
-            telemetryContext
+            telemetryContext,
+            headless: isHeadless
         });
 
         logger.debug('prepare-commit-msg - main', 'Response received', {
@@ -266,6 +321,20 @@ const main = async () => {
         // Write to commit message file
         await fs.writeFile(commitMsgFile, `${message}\n`, 'utf8');
 
+        // Append trailer to the auto-generated message
+        if (shouldAppendTrailer) {
+            try {
+                const generated = await fs.readFile(commitMsgFile, 'utf8');
+                const withTrailer = appendTrailer(generated, 'Hooks-Verified', 'true');
+                await fs.writeFile(commitMsgFile, withTrailer, 'utf8');
+                logger.debug('prepare-commit-msg - main', 'Hooks-Verified trailer appended to auto message');
+            } catch (trailerErr) {
+                logger.warning(
+                    `Could not append Hooks-Verified trailer: ${trailerErr.message}`
+                );
+            }
+        }
+
         // Record commit generation metric
         recordMetric('commit.generated', {
             fileCount: filesData.length,
@@ -292,8 +361,13 @@ const main = async () => {
 
         logger.error('prepare-commit-msg - main', 'Failed to generate commit message', error);
 
-        logger.warning('Could not generate message automatically with Claude');
-        logger.warning('Commit canceled. Run again without "auto" to write manual message');
+        if (isHeadless) {
+            logger.warning('Could not generate message automatically via SDK');
+            logger.warning('Check that ANTHROPIC_API_KEY is set correctly');
+        } else {
+            logger.warning('Could not generate message automatically with Claude');
+            logger.warning('Commit canceled. Run again without "auto" to write manual message');
+        }
 
         process.exit(1);
     }

package/lib/utils/analysis-engine.js

@@ -278,7 +278,8 @@ export const createEmptyResult = () => ({
  *
  * @param {Object} result - Analysis result
  */
-export const displayIssueSummary = (result) => {
+export const displayIssueSummary = (result, { silent = false } = {}) => {
+    if (silent) return;
     const { blocker = 0, critical = 0, major = 0, minor = 0, info = 0 } = result.issues || {};
     const total = blocker + critical + major + minor + info;
 
@@ -296,7 +297,8 @@ export const displayIssueSummary = (result) => {
  *
  * @param {Object} result - Analysis result from Claude
  */
-export const displayResults = (result) => {
+export const displayResults = (result, { silent = false } = {}) => {
+    if (silent) return;
     console.log();
     console.log('╔════════════════════════════════════════════════════════════════════╗');
     console.log('║                     CODE QUALITY ANALYSIS                          ║');
@@ -376,7 +378,7 @@ const ORCHESTRATOR_THRESHOLD = 3;
  * @returns {Promise<Object>} Analysis result
  */
 export const runAnalysis = async (filesData, config, options = {}) => {
-    const { saveDebug = config.system?.debug, hook = 'analysis' } = options;
+    const { saveDebug = config.system?.debug, hook = 'analysis', headless = false, costTracker = null } = options;
 
     if (filesData.length === 0) {
         logger.debug('analysis-engine - runAnalysis', 'No files to analyze');
@@ -396,7 +398,7 @@ export const runAnalysis = async (filesData, config, options = {}) => {
     if (useOrchestrator) {
         // Orchestrated parallel execution: Opus groups files semantically
         const orchestrationStart = Date.now();
-        const orchestration = await orchestrateBatches(filesData);
+        const orchestration = await orchestrateBatches(filesData, { headless });
         const orchestrationTime = Date.now() - orchestrationStart;
 
         const { batches, commonContext } = orchestration;
@@ -442,7 +444,9 @@ export const runAnalysis = async (filesData, config, options = {}) => {
                     timeout: config.analysis?.timeout,
                     model: batch.model,
                     saveDebug: false,
-                    telemetryContext
+                    telemetryContext,
+                    headless,
+                    costTracker
                 });
             })
         );
@@ -489,7 +493,9 @@ export const runAnalysis = async (filesData, config, options = {}) => {
         result = await analyzeCode(prompt, {
             timeout: config.analysis?.timeout,
             saveDebug,
-            telemetryContext
+            telemetryContext,
+            headless,
+            costTracker
         });
     }