claude-git-hooks 2.35.2 → 2.35.3

package/CHANGELOG.md

@@ -5,6 +5,21 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.35.3] - 2026-04-22
+
+### ✨ Added
+- Code Knowledge Library (`.library/`) with 25 reference books covering source modules — structured documentation with call signatures, I/O behavior, cross-references, and gotchas per module (#125-#131)
+- By-code index for navigating from source file paths to their reference books (`by-code/utils.md`, `by-code/commands.md`, `by-code/hooks.md`)
+- By-domain index with curated reading lists for four business workflows: commit pipeline, release management, PR analysis, and GitHub integration (`by-domain/`)
+- By-task-type index with step-by-step reading sequences for development tasks, starting with add-new-command guide (`by-task-type/`)
+- Dependency graph generator tool and path resolver for library infrastructure (`tools/`)
+- Book schema and token measurement infrastructure with calibration notes and category completeness validation
+- Classification report and category completeness report validating all 66 source modules against the 8-category taxonomy
+
+### 🐛 Fixed
+- Spotless linting timeouts and cmd.exe per-file mode on Windows — resolves batch-mode failures when Spotless wrapper is a `.cmd`/`.bat` file (#124, #125)
+
+
 ## [2.35.2] - 2026-04-13
 
 ### ✨ Added

package/CLAUDE.md

@@ -217,18 +217,19 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 | Orchestrator threshold | 3 files | Commits with ≥3 files use Opus orchestration        |
 | Orchestrator model     | opus    | Internal constant — not user-configurable           |
 | Orchestrator timeout   | 60s     | Lightweight call (file overview only)               |
-| Analysis timeout       | 300s    | Per-batch timeout                                   |
+| Analysis timeout       | 360s    | Per-batch timeout                                   |
 | Commit msg timeout     | 300s    | Message generation timeout                          |
 | PR metadata timeout    | 180s    | Engine default (reads config)                       |
 | Judge model            | sonnet  | Default, configurable via `config.judge.model`      |
-| Judge timeout          | 120s    | Per-judge call timeout                              |
+| Judge timeout          | 360s    | Per-judge call timeout                              |
 | PR analysis model      | sonnet  | Default, configurable via `config.prAnalysis.model` |
 | PR analysis timeout    | 300s    | Per-analysis Claude call                            |
 | Linting enabled        | true    | Runs linters before Claude analysis                 |
 | Linting auto-fix       | true    | Auto-fix and re-stage files                         |
 | Linting fail on error  | true    | Block commit on linting errors                      |
 | Linting fail on warn   | false   | Do not block on warnings                            |
-| Linting timeout        | 30s     | Per-linter timeout                                  |
+| Linting timeout        | 30s     | Per-linter timeout (tool-specific overrides if higher) |
+| Spotless timeout       | 120s    | Per-invocation; overrides config default             |
 
 **Judge behavior (v2.20.0):**
 
@@ -379,6 +380,10 @@ git commit
     → for each tool (formatters first, then linters):
         isToolAvailable() → not found? warn + install hint → skip
         filterFilesByTool() → matching files
+        → timeout = max(config.linting.timeout, toolDef.timeout)
+        → perFile tools (Spotless): resolve command path
+            .cmd/.bat → per-file mode (cmd.exe pipe safety)
+            otherwise → batch mode (single JVM startup)
         runToolWithAutoFix() → check → auto-fix → re-stage → re-check
     → unfixable issues forwarded to judge
   ↓
@@ -1350,7 +1355,7 @@ Recurring patterns validated across 15+ automation sessions. Apply these in new
     - Enables centralized output control and debug mode
 
 9. **DO NOT execute Claude CLI without timeout**
-    - Always configure timeout (default: 150s analysis, 180s commit msg)
+    - Always configure timeout (default: 360s analysis, 300s commit msg)
     - Timeout configurable in `.claude/config.json`
 
 10. **DO NOT ignore platform-specific issues**

package/lib/config.js

@@ -33,7 +33,7 @@ const HARDCODED = {
     analysis: {
         maxFileSize: 1000000, // 1MB - sufficient for most files
         maxFiles: 30, // Reasonable limit per commit
-        timeout: 300000, // 5 minutes - adequate for Claude API
+        timeout: 360000, // 6 minutes - adequate for Claude API
         contextLines: 3, // Git default
         ignoreExtensions: [] // Can be set in advanced config only
     },

package/lib/utils/judge.js

@@ -28,7 +28,7 @@ import logger from './logger.js';
 import { recordMetric } from './metrics.js';
 
 const JUDGE_DEFAULT_MODEL = 'sonnet';
-const JUDGE_TIMEOUT = 180000;
+const JUDGE_TIMEOUT = 360000;
 
 /**
  * Applies a single search/replace fix to a file and stages it

package/lib/utils/linter-runner.js

@@ -25,6 +25,7 @@ import {
     displayToolResult
 } from './tool-runner.js';
 import { getRepoRoot } from './git-operations.js';
+import { which } from './which-command.js';
 import { fetchRemoteConfig } from './remote-config.js';
 import logger from './logger.js';
 
@@ -324,7 +325,7 @@ export const LINTER_TOOLS = {
         installHint: 'Add spotless-maven-plugin to pom.xml (see https://github.com/diffplug/spotless)',
         extensions: ['.java'],
         parseOutput: parseSpotlessOutput,
-        timeout: 60000,
+        timeout: 120000,
         // Run per-file to avoid | (pipe) in regex on Windows.
         // filesToSpotlessRegex joins files with | for regex alternation.
         // cmd.exe interprets | as a pipe at every expansion level —
@@ -474,9 +475,13 @@ export async function runLinters(files, config, presetName = 'default') {
             }
         }
 
+        // Use the higher of config timeout and tool-specific timeout.
+        // Spotless (120s) should not be silently capped to the config default (30s).
+        const effectiveTimeout = Math.max(timeout, effectiveToolDef.timeout || 0);
+
         const toolOpts = {
             autoFix,
-            timeout,
+            timeout: effectiveTimeout,
             restage: true,
             localBin: availability.localBin,
             toolCwd: availability.configDir
@@ -487,9 +492,29 @@ export async function runLinters(files, config, presetName = 'default') {
         // ^ escaping is consumed at the first parse, and %VAR% expansion in batch
         // scripts (mvn.cmd) re-exposes unescaped | to a second parse.
         // Running per-file ensures each invocation has a single-file regex (no |).
-        if (effectiveToolDef.perFile && matchingFiles.length > 1) {
+        //
+        // However, per-file mode is ONLY needed when the command routes through
+        // cmd.exe (.cmd/.bat files). Direct executables and bash scripts (e.g.,
+        // mvnw) pass args to the process directly — | is never interpreted as a pipe.
+        // Batch mode avoids N separate JVM startups, which is critical for Spotless
+        // on Windows/WSL where each startup adds significant overhead.
+        let needsPerFile = effectiveToolDef.perFile && matchingFiles.length > 1;
+        if (needsPerFile) {
+            const resolvedCmd = effectiveToolDef.command.includes(path.sep)
+                ? effectiveToolDef.command
+                : (which(effectiveToolDef.command) || effectiveToolDef.command);
+            if (!/\.(cmd|bat)$/i.test(resolvedCmd)) {
+                needsPerFile = false;
+                logger.debug('linter-runner - runLinters',
+                    `${effectiveToolDef.name} command bypasses cmd.exe, using batch mode`,
+                    { command: resolvedCmd });
+            }
+        }
+
+        if (needsPerFile) {
             logger.debug('linter-runner - runLinters',
-                `Running ${effectiveToolDef.name} per-file`, { fileCount: matchingFiles.length });
+                `Running ${effectiveToolDef.name} per-file (cmd.exe path)`,
+                { fileCount: matchingFiles.length });
 
             const perFileResults = matchingFiles.map((file) =>
                 runToolWithAutoFix(effectiveToolDef, [file], toolOpts)

package/lib/utils/tool-runner.js

@@ -461,8 +461,9 @@ export function runTool(toolDef, files, options = {}) {
             const parsed = toolDef.parseOutput(err.stdout);
             result.errors = parsed.errors || [];
             result.warnings = parsed.warnings || [];
-        } else if (err.killed) {
-            // Timeout
+        } else if (err.killed || err.code === 'ETIMEDOUT') {
+            // Timeout — err.killed for Node.js timeout, ETIMEDOUT for OS-level
+            // spawn timeout (common on Windows when cmd.exe → JVM startup is slow)
             logger.warning(`${toolDef.name} timed out after ${timeout}ms`);
             result.errors.push({
                 file: '',
@@ -543,7 +544,7 @@ export function runToolFix(toolDef, files, options = {}) {
     try {
         execFileSync(exec.command, exec.args, execOptions);
     } catch (err) {
-        if (err.killed) {
+        if (err.killed || err.code === 'ETIMEDOUT') {
             logger.warning(`${toolDef.name} auto-fix timed out`);
             return { fixedFiles: [], fixedCount: 0 };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.35.2",
+    "version": "2.35.3",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {

package/templates/CUSTOMIZATION_GUIDE.md

@@ -284,7 +284,7 @@ cd python-django
     "analysis": {
         "maxFileSize": 1000000,
         "maxFiles": 12,
-        "timeout": 180000
+        "timeout": 360000
     },
     "subagents": {
         "enabled": true,
@@ -308,7 +308,7 @@ cd python-django
   analysis: {
     maxFileSize: 1000000,  // 1MB
     maxFiles: 30,
-    timeout: 180000        // 3 minutes
+    timeout: 360000        // 6 minutes
   },
   subagents: {
     enabled: true,