claude-git-hooks 2.19.0 → 2.21.0

package/lib/commands/diff-batch-info.js

@@ -0,0 +1,105 @@
+/**
+ * File: diff-batch-info.js
+ * Purpose: Display intelligent diff-analysis orchestration config and speed telemetry
+ *
+ * Shows:
+ * - Orchestration model and threshold
+ * - Default analysis model from config
+ * - Per-model avg analysis times from telemetry
+ * - Avg orchestration overhead
+ * - Overall failure rate
+ */
+
+import { getStatistics } from '../utils/telemetry.js';
+import logger from '../utils/logger.js';
+
+/**
+ * Runs the batch-info command
+ * Why: Surfaces orchestration configuration and speed telemetry so users can
+ * understand the adaptive batch system behavior without needing debug mode.
+ */
+export async function runDiffBatchInfo() {
+    console.log(
+        '\n╔════════════════════════════════════════════════════════════════════╗'
+    );
+    console.log(
+        '║              INTELLIGENT ANALYSIS ORCHESTRATION INFO               ║'
+    );
+    console.log(
+        '╚════════════════════════════════════════════════════════════════════╝\n'
+    );
+
+    console.log('━━━ ORCHESTRATION CONFIGURATION ━━━');
+    console.log('  Orchestration model:     opus (internal, not user-configurable)');
+    console.log('  Orchestrator threshold:  3 files (commits with ≥3 files use intelligent grouping)');
+    console.log();
+
+    console.log('━━━ HOW IT WORKS ━━━');
+    console.log('  < 3 files:  Sequential analysis (single Claude call)');
+    console.log('  ≥ 3 files:  Orchestrator groups files semantically,');
+    console.log('              assigns model per batch, injects shared context');
+    console.log();
+
+    try {
+        const stats = await getStatistics(7);
+
+        if (!stats.enabled) {
+            console.log('  Telemetry is disabled — no speed data available.');
+            console.log(
+                '  To enable, ensure "system.telemetry" is not set to false in .claude/config.json'
+            );
+            console.log();
+            return;
+        }
+
+        if (stats.totalEvents === 0) {
+            console.log('━━━ SPEED TELEMETRY (last 7 days) ━━━');
+            console.log('  No telemetry data yet.');
+            console.log(
+                '  Run an analysis with ≥3 files to start collecting per-model timing data.'
+            );
+            console.log();
+            return;
+        }
+
+        console.log('━━━ SPEED TELEMETRY (last 7 days) ━━━');
+        console.log(`  Total events:       ${stats.totalEvents}`);
+        console.log(`  Successful batches: ${stats.batchSuccesses}`);
+        console.log(`  Failure rate:       ${stats.failureRate}%`);
+        console.log();
+
+        if (Object.keys(stats.avgAnalysisTimeByModel).length > 0) {
+            console.log('  Average analysis time by model:');
+            for (const [model, ms] of Object.entries(stats.avgAnalysisTimeByModel)) {
+                const seconds = (ms / 1000).toFixed(1);
+                console.log(`    ${model.padEnd(8)}: ${seconds}s`);
+            }
+            console.log();
+        }
+
+        if (stats.avgOrchestrationTime > 0) {
+            const orchSeconds = (stats.avgOrchestrationTime / 1000).toFixed(1);
+            console.log(`  Avg orchestration overhead: ${orchSeconds}s`);
+            console.log(
+                '  (Orchestrator call for semantic grouping — one-time per commit)'
+            );
+            console.log();
+        }
+
+        if (Object.keys(stats.successesByHook).length > 0) {
+            console.log('  Successes by hook:');
+            for (const [hook, count] of Object.entries(stats.successesByHook)) {
+                console.log(`    ${hook}: ${count}`);
+            }
+            console.log();
+        }
+    } catch (err) {
+        logger.debug('diff-batch-info - runDiffBatchInfo', 'Failed to load telemetry', err);
+        console.log('  Could not load telemetry data.');
+        console.log();
+    }
+
+    console.log('📂 Telemetry files: .claude/telemetry/');
+    console.log('💡 Use --debug true to see orchestrator decisions in real time');
+    console.log();
+}

package/lib/commands/help.js

@@ -3,7 +3,7 @@
  * Purpose: Help, version display, and AI-powered help commands
  *
  * Features:
- * - Static help text (no args, --help, -h)
+ * - Dynamic help from command registry (no args, --help, -h)
  * - AI help: routes questions to Claude with CLAUDE.md as knowledge base
  * - Report issue: interactive issue creation guided by Claude
  */
@@ -17,6 +17,7 @@ import { loadPrompt } from '../utils/prompt-builder.js';
 import { fetchFileContent, fetchDirectoryListing, createIssue } from '../utils/github-api.js';
 import { promptMenu, promptEditField, promptConfirmation } from '../utils/interactive-ui.js';
 import logger from '../utils/logger.js';
+import { commands } from '../cli-metadata.js';
 
 /**
  * Get claude-hooks source repo coordinates from package.json
@@ -67,56 +68,87 @@ export async function runShowHelp(args = []) {
 }
 
 /**
- * Display static help text
- * Why: Preserved original behavior for --help, -h, and no-args calls
+ * Display help text generated from command registry
+ * Why: Single source of truth — adding a command to cli-metadata.js auto-updates help
  */
 export function showStaticHelp() {
+    const lines = formatCommandLines(commands);
+
     console.log(`
 Claude Git Hooks - Code analysis and automatic messages with Claude CLI
 
 Usage: claude-hooks <command> [options]
 
 Commands:
-  analyze [--unstaged | --all]           Analyze code interactively before committing
-  analyze-diff [base]                    Analyze diff and generate PR metadata
-  bump-version [type] [options]          Bump version with CHANGELOG and Git tag
-    <type>: major | minor | patch        (optional for suffix-only operations)
-    --dry-run                            Preview changes without applying
-    --interactive                        Force file selection menu
-    --no-commit                          Skip automatic commit
-    --no-tag                             Skip Git tag creation
-    --push                               Push tag to remote
-    --remove-suffix                      Remove version suffix (no type required)
-    --set-suffix <value>                 Set/replace version suffix (no type required)
-    --suffix <value>                     Add version suffix (e.g., SNAPSHOT)
-    --update-changelog [branch]          Generate CHANGELOG entry
-  create-pr [base]                       Create PR with auto-generated metadata
-  --debug <true | false | status>        Toggle debug mode
-  disable [hook]                         Disable hooks (all or specific)
-  enable [hook]                          Enable hooks (all or specific)
-  generate-changelog [version]           Generate CHANGELOG entry independently
-    --base-branch <branch>               Compare against branch (default: main)
-    --release                            Mark as released
-  help [question]                        Show help or ask AI a question
-    --report-issue                       Create GitHub issue interactively
-  install [options]                       Install hooks in current repository
-    --force                              Reinstall even if already exist
-    --skip-auth                          Skip Claude authentication check
-  migrate-config                         Migrate legacy config to v2.8.0 format
-  preset current                         Show current active preset
-  presets                                List all available presets
-  --set-preset <name>                    Set the active preset
-  setup-github                           Configure GitHub token for PR creation
-  status                                 Show hook status
-  telemetry [show | clear]               View or clear telemetry data
-  uninstall                              Remove hooks from repository
-  update                                 Update to latest version
-  --version, -v                          Show current version
+${lines}
 
 More information: https://github.com/mscope-S-L/git-hooks
 `);
 }
 
+/**
+ * Format command registry entries into aligned help lines
+ *
+ * @param {Array} cmds - Command entries from cli-metadata.js
+ * @returns {string} Formatted, alphabetically sorted command lines
+ */
+function formatCommandLines(cmds) {
+    const entries = [];
+
+    for (const cmd of cmds) {
+        // Skip version/help aliases (shown via their primary entry)
+        if (cmd.name === 'version') continue;
+
+        // Build display name with args/aliases
+        let name = cmd.name;
+        if (cmd.aliases) {
+            name = `${cmd.name}, ${cmd.aliases.join(', ')}`;
+        }
+        if (cmd.args) {
+            const argLabel = cmd.args.values
+                ? cmd.args.values.join(' | ')
+                : cmd.args.name;
+            name += ` [${argLabel}]`;
+        }
+        if (cmd.subcommands) {
+            name += ` [${cmd.subcommands.join(' | ')}]`;
+        }
+        if (cmd.flags) {
+            name += ' [options]';
+        }
+
+        entries.push({ name, description: cmd.description, flags: cmd.flags });
+    }
+
+    // Sort alphabetically (strip leading -- for comparison)
+    entries.sort((a, b) => {
+        const aKey = a.name.replace(/^--/, '');
+        const bKey = b.name.replace(/^--/, '');
+        return aKey.localeCompare(bKey);
+    });
+
+    // Calculate padding
+    const maxLen = Math.max(...entries.map((e) => e.name.length));
+
+    const lines = [];
+    for (const entry of entries) {
+        const padding = ' '.repeat(maxLen - entry.name.length + 4);
+        lines.push(`  ${entry.name}${padding}${entry.description}`);
+
+        // Add flag lines indented under command
+        if (entry.flags) {
+            const flagEntries = Object.entries(entry.flags).sort(([a], [b]) => a.localeCompare(b));
+            for (const [flag, meta] of flagEntries) {
+                const flagName = meta.takesValue ? `${flag} <value>` : flag;
+                const flagPad = ' '.repeat(maxLen - flagName.length + 2);
+                lines.push(`    ${flagName}${flagPad}${meta.description}`);
+            }
+        }
+    }
+
+    return lines.join('\n');
+}
+
 /**
  * Print AI help response with version source footer
  *

package/lib/commands/install.js

@@ -327,11 +327,6 @@ export function extractLegacySettings(rawConfig) {
         }
     }
 
-    // Subagent batchSize (allowed)
-    if (rawConfig.subagents?.batchSize !== undefined) {
-        allowedOverrides.subagents = { batchSize: rawConfig.subagents.batchSize };
-    }
-
     // Advanced params (preserved with warning in manual migration)
     if (rawConfig.analysis?.ignoreExtensions !== undefined) {
         if (!allowedOverrides.analysis) allowedOverrides.analysis = {};
@@ -343,11 +338,6 @@ export function extractLegacySettings(rawConfig) {
         allowedOverrides.commitMessage.taskIdPattern = rawConfig.commitMessage.taskIdPattern;
     }
 
-    if (rawConfig.subagents?.model !== undefined) {
-        if (!allowedOverrides.subagents) allowedOverrides.subagents = {};
-        allowedOverrides.subagents.model = rawConfig.subagents.model;
-    }
-
     return allowedOverrides;
 }
 

package/lib/commands/setup-linear.js

@@ -0,0 +1,96 @@
+/**
+ * File: setup-linear.js
+ * Purpose: Interactive Linear authentication setup command
+ *
+ * Handles:
+ * - Checking existing token
+ * - Prompting user for new token
+ * - Validating token via Linear API
+ * - Saving token to .claude/settings.local.json
+ */
+
+import { testConnection, loadLinearToken } from '../utils/linear-connector.js';
+import { saveToken } from '../utils/token-store.js';
+import {
+    promptConfirmation,
+    promptEditField,
+    showSuccess,
+    showError,
+    showInfo,
+    showWarning
+} from '../utils/interactive-ui.js';
+import logger from '../utils/logger.js';
+
+/**
+ * Run Linear authentication setup
+ * Why: Interactive flow to configure Linear token for PR analysis enrichment
+ *
+ * @returns {Promise<void>}
+ */
+export async function runSetupLinear() {
+    showInfo('Linear Authentication Setup');
+
+    // Check existing token
+    const existingToken = loadLinearToken();
+    if (existingToken) {
+        showInfo('Existing Linear token found. Validating...');
+
+        const healthy = await testConnection(existingToken);
+        if (healthy) {
+            showSuccess('Linear token is valid and connected.');
+
+            const reconfigure = await promptConfirmation('Configure a different token?', false);
+            if (!reconfigure) {
+                return;
+            }
+        } else {
+            showWarning('Existing token is invalid or expired.');
+        }
+    }
+
+    // Show instructions
+    logger.info('Create a Linear API key:');
+    logger.info('  1. Go to: https://linear.app/settings/api');
+    logger.info('  2. Click "Create key"');
+    logger.info('  3. Give it a label (e.g., "claude-hooks")');
+    logger.info('  4. Copy the key (starts with lin_api_...)');
+
+    // Prompt for token
+    const token = await promptEditField('Paste your Linear API key (lin_api_...)', '');
+
+    if (!token || token.trim() === '') {
+        showWarning('No token provided. Setup cancelled.');
+        return;
+    }
+
+    const trimmedToken = token.trim();
+
+    // Basic format check
+    if (!trimmedToken.startsWith('lin_api_')) {
+        showWarning('Token format looks unusual (expected lin_api_...)');
+        const proceed = await promptConfirmation('Continue anyway?', false);
+        if (!proceed) {
+            return;
+        }
+    }
+
+    // Save token
+    const saveResult = saveToken('linearToken', trimmedToken);
+    if (!saveResult.success) {
+        showError(`Failed to save token: ${saveResult.error}`);
+        return;
+    }
+    showSuccess(`Token saved to ${saveResult.path}`);
+
+    // Validate with Linear API
+    showInfo('Validating token...');
+
+    const healthy = await testConnection(trimmedToken);
+    if (healthy) {
+        showSuccess('Linear connection verified.');
+    } else {
+        showWarning('Token validation failed - may not work correctly');
+    }
+
+    showSuccess('Setup complete! Linear ticket context will be used in: claude-hooks analyze-pr');
+}

package/lib/config.js

@@ -6,9 +6,8 @@
  *
  * v2.8.0 Changes:
  * - Removed 21 redundant parameters (hardcoded sensible defaults)
- * - Only 5 user-configurable parameters remain
- * - Preset can override: subagents.batchSize
- * - User can override: github.pr.*, subagents.batchSize
+ * - Only 4 user-configurable parameters remain
+ * - User can override: github.pr.*
  * - Advanced params moved to config.advanced.example.json
  *
  * User-configurable:
@@ -16,12 +15,10 @@
  * - github.pr.defaultBase
  * - github.pr.reviewers
  * - github.pr.labelRules
- * - subagents.batchSize
  *
  * Advanced (in example file only):
  * - analysis.ignoreExtensions
  * - commitMessage.taskIdPattern
- * - subagents.model
  */
 
 import fs from 'fs';
@@ -35,7 +32,7 @@ import logger from './utils/logger.js';
 const HARDCODED = {
     analysis: {
         maxFileSize: 1000000, // 1MB - sufficient for most files
-        maxFiles: 20, // Reasonable limit per commit
+        maxFiles: 30, // Reasonable limit per commit
         timeout: 300000, // 5 minutes - adequate for Claude API
         contextLines: 3, // Git default
         ignoreExtensions: [] // Can be set in advanced config only
@@ -46,9 +43,7 @@ const HARDCODED = {
         taskIdPattern: '([A-Z]{1,3}[-\\s]\\d{3,5})' // Jira/GitHub/Linear pattern
     },
     subagents: {
-        enabled: true, // Enable by default (faster analysis)
-        model: 'haiku', // Fast and cost-effective
-        batchSize: 3 // Reasonable parallelization
+        enabled: true // Enable by default (faster analysis via orchestration)
     },
     templates: {
         baseDir: '.claude/prompts',
@@ -57,7 +52,6 @@ const HARDCODED = {
         commitMessage: 'COMMIT_MESSAGE.md',
         analyzeDiff: 'ANALYZE_DIFF.md',
         resolution: 'CLAUDE_RESOLUTION_PROMPT.md',
-        subagentInstruction: 'SUBAGENT_INSTRUCTION.md',
         createGithubPR: 'CREATE_GITHUB_PR.md'
     },
     output: {
@@ -76,6 +70,21 @@ const HARDCODED = {
     },
     github: {
         enabled: true // Always enabled
+    },
+    prAnalysis: {
+        model: 'sonnet',
+        timeout: 300000, // 5 minutes
+        inlineCategories: ['bug', 'security', 'performance', 'hotspot'],
+        generalCategories: [
+            'ticket-alignment',
+            'scope',
+            'style',
+            'good-practice',
+            'extensibility',
+            'observability',
+            'documentation',
+            'testing'
+        ]
     }
 };
 
@@ -106,10 +115,6 @@ const defaults = {
         }
     },
 
-    // Subagent configuration (preset can override)
-    subagents: {
-        batchSize: 3 // Files per parallel batch
-    }
 };
 
 /**
@@ -196,8 +201,8 @@ const loadUserConfig = async (baseDir = process.cwd()) => {
 
 /**
  * Extracts only allowed parameters from legacy config
- * v2.8.0 only allows: github.pr.*, subagents.batchSize
- * Advanced: analysis.ignoreExtensions, commitMessage.taskIdPattern, subagents.model
+ * Allowed: github.pr.*
+ * Advanced: analysis.ignoreExtensions, commitMessage.taskIdPattern
  *
  * @param {Object} legacyConfig - Legacy format config
  * @returns {Object} Allowed parameters only
@@ -219,11 +224,6 @@ const extractAllowedParams = (legacyConfig) => {
         }
     }
 
-    // Subagent batchSize (allowed)
-    if (legacyConfig.subagents?.batchSize !== undefined) {
-        allowed.subagents = { batchSize: legacyConfig.subagents.batchSize };
-    }
-
     // Advanced params (allowed but warn)
     if (legacyConfig.analysis?.ignoreExtensions !== undefined) {
         if (!allowed.analysis) allowed.analysis = {};
@@ -237,12 +237,6 @@ const extractAllowedParams = (legacyConfig) => {
         logger.warning('ℹ️  Using advanced parameter: commitMessage.taskIdPattern');
     }
 
-    if (legacyConfig.subagents?.model !== undefined) {
-        if (!allowed.subagents) allowed.subagents = {};
-        allowed.subagents.model = legacyConfig.subagents.model;
-        logger.warning('ℹ️  Using advanced parameter: subagents.model');
-    }
-
     return allowed;
 };
 

package/lib/hooks/pre-commit.js

@@ -21,10 +21,10 @@
 
 import { getStagedFiles, getRepoRoot } from '../utils/git-operations.js';
 import { filterFiles } from '../utils/file-operations.js';
-import { buildFilesData, runAnalysis, displayResults } from '../utils/analysis-engine.js';
+import { buildFilesData, runAnalysis, displayResults, hasAnyIssues } from '../utils/analysis-engine.js';
 import { generateResolutionPrompt, shouldGeneratePrompt } from '../utils/resolution-prompt.js';
 import { loadPreset } from '../utils/preset-loader.js';
-import { getVersion, calculateBatches } from '../utils/package-info.js';
+import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
 import { getConfig } from '../config.js';
 
@@ -145,21 +145,9 @@ const main = async () => {
         // Step 4: Log analysis configuration
         logger.info(`Sending ${filesData.length} files for review...`);
 
-        // Display subagent configuration
-        const subagentsEnabled = config.subagents?.enabled !== false;
-        const subagentModel = config.subagents?.model || 'haiku';
-        const batchSize = config.subagents?.batchSize || 3;
-
-        if (subagentsEnabled && filesData.length >= 3) {
-            const { numBatches, shouldShowBatches } = calculateBatches(filesData.length, batchSize);
-            console.log(
-                `⚡ Batch optimization: ${subagentModel} model, ${batchSize} files per batch`
-            );
-            if (shouldShowBatches) {
-                console.log(
-                    `📊 Analyzing ${filesData.length} files in ${numBatches} batch${numBatches > 1 ? 'es' : ''}`
-                );
-            }
+        // Display analysis routing hint
+        if (filesData.length >= 3) {
+            logger.info('⚡ Intelligent orchestration: grouping files and assigning models');
         }
 
         // Step 5: Run analysis using shared engine
@@ -171,6 +159,44 @@ const main = async () => {
         // Step 6: Display results using shared function
         displayResults(result);
 
+        // Step 6.5: Judge — auto-fix all issues
+        if (config.judge?.enabled !== false && hasAnyIssues(result)) {
+            try {
+                const { judgeAndFix } = await import('../utils/judge.js');
+                const judgeResult = await judgeAndFix(result, filesData, config);
+
+                // Update result with remaining issues (fixed + false positives removed)
+                result.blockingIssues = judgeResult.remainingIssues.filter(
+                    (i) =>
+                        ['blocker', 'critical'].includes(
+                            (i.severity || '').toLowerCase()
+                        )
+                );
+                result.details = judgeResult.remainingIssues;
+
+                // Recalculate quality gate — pass only if ALL issues resolved
+                if (judgeResult.remainingIssues.length === 0) {
+                    result.issues = {
+                        blocker: 0,
+                        critical: 0,
+                        major: 0,
+                        minor: 0,
+                        info: 0
+                    };
+                    result.QUALITY_GATE = 'PASSED';
+                    result.approved = true;
+                } else {
+                    result.QUALITY_GATE = 'FAILED';
+                    result.approved = false;
+                }
+            } catch (err) {
+                logger.warning(`Judge failed: ${err.message}`);
+                logger.warning('Commit blocked — judge could not verify issues');
+                result.QUALITY_GATE = 'FAILED';
+                result.approved = false;
+            }
+        }
+
         // Step 7: Check quality gate
         const qualityGatePassed = result.QUALITY_GATE === 'PASSED';
         const approved = result.approved !== false;

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

@@ -21,7 +21,7 @@ import fs from 'fs/promises';
 import { getStagedFiles, getStagedStats, getFileDiff } from '../utils/git-operations.js';
 import { analyzeCode } from '../utils/claude-client.js';
 import { loadPrompt } from '../utils/prompt-builder.js';
-import { getVersion, calculateBatches } from '../utils/package-info.js';
+import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
 import { getConfig } from '../config.js';
 import { getOrPromptTaskId, formatWithTaskId } from '../utils/task-id.js';
@@ -152,14 +152,7 @@ const main = async () => {
 
         // Display configuration info
         const version = await getVersion();
-        const subagentsEnabled = config.subagents?.enabled || false;
-        const subagentModel = config.subagents?.model || 'haiku';
-        const batchSize = config.subagents?.batchSize || 3;
-
         console.log(`\n🤖 claude-git-hooks v${version}`);
-        if (subagentsEnabled) {
-            console.log(`⚡ Parallel analysis: ${subagentModel} model, batch size ${batchSize}`);
-        }
 
         logger.info('Generating commit message automatically...');
 
@@ -235,28 +228,14 @@ const main = async () => {
 
         logger.debug('prepare-commit-msg - main', 'Prompt built', { promptLength: prompt.length });
 
-        // Calculate batches if subagents enabled and applicable
-        if (subagentsEnabled && filesData.length >= 3) {
-            const { numBatches, shouldShowBatches } = calculateBatches(filesData.length, batchSize);
-            if (shouldShowBatches) {
-                console.log(
-                    `📊 Analyzing ${filesData.length} files in ${numBatches} batch${numBatches > 1 ? 'es' : ''}`
-                );
-            }
-        }
-
         // Generate message with Claude
         logger.info('Sending to Claude...');
 
         // Build telemetry context
         const telemetryContext = {
             fileCount: filesData.length,
-            batchSize: config.subagents?.batchSize || 3,
-            totalBatches:
-                subagentsEnabled && filesData.length >= 3
-                    ? Math.ceil(filesData.length / (config.subagents?.batchSize || 3))
-                    : 1,
-            model: subagentModel,
+            batchSize: filesData.length,
+            totalBatches: 1,
             hook: 'prepare-commit-msg'
         };