claude-git-hooks 2.44.0 → 2.51.2

package/lib/config.js

@@ -24,104 +24,23 @@
 import fs from 'fs';
 import path from 'path';
 import logger from './utils/logger.js';
+import { getDefaults, resolveSection } from './utils/config-registry.js';
 
 /**
- * Hardcoded defaults (v3.0.0)
- * These are NOT user-configurable - sensible defaults that work for everyone
+ * Package defaults loaded from lib/defaults.json via config-registry.
+ * These are NOT user-configurable — sensible defaults that work for everyone.
+ * See lib/defaults.json for the full structure and values.
  */
-const HARDCODED = {
-    analysis: {
-        maxFileSize: 1000000, // 1MB - sufficient for most files
-        maxFiles: 30, // Reasonable limit per commit
-        timeout: 360000, // 6 minutes - adequate for Claude API
-        contextLines: 3, // Git default
-        ignoreExtensions: [] // Can be set in advanced config only
-    },
-    commitMessage: {
-        autoKeyword: 'auto', // Standard keyword
-        timeout: 300000, // Use same timeout as analysis
-        taskIdPattern: '([A-Z]{1,3}[-\\s]\\d{3,5})' // Jira/GitHub/Linear pattern
-    },
-    subagents: {
-        enabled: true // Enable by default (faster analysis via orchestration)
-    },
-    templates: {
-        baseDir: '.claude/prompts',
-        analysis: 'CLAUDE_ANALYSIS_PROMPT.md',
-        guidelines: 'CLAUDE_PRE_COMMIT.md',
-        commitMessage: 'COMMIT_MESSAGE.md',
-        analyzeDiff: 'ANALYZE_DIFF.md',
-        resolution: 'CLAUDE_RESOLUTION_PROMPT.md',
-        createGithubPR: 'CREATE_GITHUB_PR.md'
-    },
-    output: {
-        outputDir: '.claude/out',
-        debugFile: '.claude/out/debug-claude-response.json',
-        resolutionFile: '.claude/out/claude_resolution_prompt.md',
-        prAnalysisFile: '.claude/out/pr-analysis.json'
-    },
-    system: {
-        debug: false, // Controlled by --debug flag
-        wslCheckTimeout: 15000 // System behavior
-    },
-    git: {
-        diffFilter: 'ACM' // Standard: Added, Copied, Modified
-    },
-    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'
-        ]
-    },
-    linting: {
-        enabled: true, // Run linters before Claude analysis
-        autoFix: true, // Auto-fix and re-stage
-        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
-    }
-};
+const HARDCODED = getDefaults();
 
 /**
  * Default user-configurable values (v2.8.0)
+ * Derived from the github.pr section of HARDCODED.
  * Only these can be overridden in .claude/config.json
  */
 const defaults = {
-    // GitHub PR configuration (user-specific)
     github: {
-        pr: {
-            defaultBase: 'develop', // Project default branch
-            reviewers: [], // Project reviewers
-            labelRules: {
-                // Labels by preset
-                backend: ['backend', 'java'],
-                frontend: ['frontend', 'react'],
-                fullstack: ['fullstack'],
-                database: ['database', 'sql'],
-                ai: ['ai', 'tooling'],
-                default: []
-            },
-            // Auto-push configuration (v2.11.0)
-            autoPush: true, // Auto-push unpublished branches
-            pushConfirm: true, // Prompt for confirmation before push
-            verifyRemote: true, // Verify remote exists before push
-            showCommits: true // Show commit preview before push
-        }
+        pr: structuredClone(HARDCODED.github.pr)
     }
 };
 
@@ -132,7 +51,7 @@ const defaults = {
  * - v2.8.0: { version: "2.8.0", preset: "...", overrides: {...} }
  * - Legacy: { preset: "...", analysis: {...}, ... } (auto-migrates with warning)
  *
- * Merge priority: HARDCODED < defaults < preset config < user overrides
+ * Merge priority: HARDCODED < remote settings.json < defaults < preset config < user overrides
  *
  * @param {string} baseDir - Base directory to search for config (default: cwd)
  * @returns {Promise<Object>} Merged configuration
@@ -194,8 +113,17 @@ const loadUserConfig = async (baseDir = process.cwd()) => {
         }
     }
 
-    // Merge priority: HARDCODED < defaults < preset < user overrides
-    const baseConfig = deepMerge(HARDCODED, defaults);
+    // Fetch remote settings.json overrides for team-policy sections
+    const remoteSettings = {};
+    const settingsSections = ['analysis', 'commitMessage', 'linting'];
+    const sectionResults = await Promise.all(settingsSections.map((s) => resolveSection(s)));
+    settingsSections.forEach((section, i) => {
+        if (sectionResults[i]) remoteSettings[section] = sectionResults[i];
+    });
+
+    // Merge priority: HARDCODED < remote settings.json < defaults < preset < user overrides
+    const withRemote = deepMerge(HARDCODED, remoteSettings);
+    const baseConfig = deepMerge(withRemote, defaults);
     const withPreset = deepMerge(baseConfig, presetConfig);
     const final = deepMerge(withPreset, userOverrides);
 

package/lib/defaults.json

@@ -0,0 +1,130 @@
+{
+    "analysis": {
+        "maxFileSize": 1000000,
+        "maxFiles": 30,
+        "timeout": 360000,
+        "contextLines": 3,
+        "ignoreExtensions": []
+    },
+    "commitMessage": {
+        "autoKeyword": "auto",
+        "timeout": 300000,
+        "taskIdPattern": "([A-Z]{1,3}[-\\s]\\d{3,5})"
+    },
+    "subagents": {
+        "enabled": true
+    },
+    "templates": {
+        "baseDir": ".claude/prompts",
+        "analysis": "CLAUDE_ANALYSIS_PROMPT.md",
+        "guidelines": "CLAUDE_PRE_COMMIT.md",
+        "commitMessage": "COMMIT_MESSAGE.md",
+        "analyzeDiff": "ANALYZE_DIFF.md",
+        "resolution": "CLAUDE_RESOLUTION_PROMPT.md",
+        "createGithubPR": "CREATE_GITHUB_PR.md"
+    },
+    "output": {
+        "outputDir": ".claude/out",
+        "debugFile": ".claude/out/debug-claude-response.json",
+        "resolutionFile": ".claude/out/claude_resolution_prompt.md",
+        "prAnalysisFile": ".claude/out/pr-analysis.json"
+    },
+    "system": {
+        "debug": false,
+        "wslCheckTimeout": 15000
+    },
+    "git": {
+        "diffFilter": "ACM"
+    },
+    "github": {
+        "enabled": true,
+        "pr": {
+            "defaultBase": "develop",
+            "reviewers": [],
+            "labelRules": {
+                "backend": ["backend", "java"],
+                "frontend": ["frontend", "react"],
+                "fullstack": ["fullstack"],
+                "database": ["database", "sql"],
+                "ai": ["ai", "tooling"],
+                "default": []
+            },
+            "autoPush": true,
+            "pushConfirm": true,
+            "verifyRemote": true,
+            "showCommits": true
+        }
+    },
+    "prAnalysis": {
+        "model": "sonnet",
+        "timeout": 300000,
+        "inlineCategories": ["bug", "security", "performance", "hotspot"],
+        "generalCategories": [
+            "ticket-alignment",
+            "scope",
+            "style",
+            "good-practice",
+            "extensibility",
+            "observability",
+            "documentation",
+            "testing"
+        ]
+    },
+    "linting": {
+        "enabled": true,
+        "autoFix": true,
+        "failOnError": true,
+        "failOnWarning": false,
+        "timeout": 30000
+    },
+    "claude": {
+        "defaultModel": "sonnet"
+    },
+    "models": {
+        "modelMap": {
+            "haiku": "claude-haiku-4-5-20251001",
+            "sonnet": "claude-sonnet-4-6",
+            "opus": "claude-opus-4-6"
+        },
+        "defaults": {
+            "analysis": "sonnet",
+            "orchestrator": "opus",
+            "judge": "sonnet",
+            "prAnalysis": "sonnet",
+            "commitMessage": "sonnet"
+        }
+    },
+    "tools": {
+        "prettier": { "enabled": true, "timeout": 30000 },
+        "eslint": { "enabled": true, "timeout": 30000 },
+        "spotless": { "enabled": true, "timeout": 120000, "perFile": true },
+        "sqlfluff": { "enabled": true, "timeout": 30000 }
+    },
+    "presetLinters": {
+        "frontend": ["prettier", "eslint"],
+        "backend": ["spotless"],
+        "fullstack": ["prettier", "eslint", "spotless"],
+        "database": ["sqlfluff"],
+        "ai": ["prettier", "eslint"],
+        "default": ["prettier", "eslint"]
+    },
+    "judge": {
+        "model": "sonnet",
+        "timeout": 360000
+    },
+    "orchestrator": {
+        "model": "opus",
+        "timeout": 60000,
+        "threshold": 3
+    },
+    "prMetadata": {
+        "timeout": 180000,
+        "maxDiffSize": 50000
+    },
+    "linear": {
+        "hostname": "api.linear.app",
+        "path": "/graphql",
+        "timeout": 10000,
+        "maxRetries": 2
+    }
+}

package/lib/hooks/pre-commit.js

@@ -19,6 +19,7 @@
  * - resolution-prompt: Issue resolution generation
  */
 
+import { join } from 'path';
 import { getStagedFiles, getRepoRoot, getStagedTreeSha } from '../utils/git-operations.js';
 import { writeMarker } from '../utils/hooks-verified-marker.js';
 import { filterFiles } from '../utils/file-operations.js';
@@ -150,6 +151,41 @@ const main = async () => {
             process.exit(0);
         }
 
+        // Library staleness check — non-blocking warning
+        try {
+            const { checkBook } = await import('../../.library/tools/staleness.js');
+            const { getBooksDir } = await import('../../.library/paths.js');
+            const booksDir = getBooksDir();
+            const sourceFiles = validFiles
+                .map(f => (typeof f === 'string' ? f : f.path))
+                .filter(p => p.startsWith('lib/'));
+
+            if (sourceFiles.length > 0) {
+                const staleBooks = [];
+                for (const srcPath of sourceFiles) {
+                    const bookName = `${srcPath.replace(/^lib\/(?:.*\/)?/, '').replace(/\.js$/, '')}.md`;
+                    const bookPath = join(booksDir, bookName);
+                    try {
+                        const result = await checkBook(bookPath, getRepoRoot());
+                        if (result.status === 'stale') {
+                            staleBooks.push(result.book);
+                        }
+                    } catch {
+                        // Book doesn't exist or check failed — skip silently
+                    }
+                }
+                if (staleBooks.length > 0) {
+                    logger.warning(`📚 ${staleBooks.length} library book(s) will become stale after this commit`);
+                    for (const book of staleBooks) {
+                        logger.warning(`   └─ ${book}`);
+                    }
+                    logger.warning('   Run: npm run library:regenerate');
+                }
+            }
+        } catch {
+            logger.warning('📚 Library staleness check unavailable — .library/ tools not found');
+        }
+
         // Step 3: Run linters (fast, deterministic — before Claude analysis)
         // Unfixable lint issues are forwarded to the judge for semantic resolution
         let unfixableLintDetails = [];

package/lib/utils/analysis-engine.js

@@ -35,6 +35,7 @@ import { orchestrateBatches } from './diff-analysis-orchestrator.js';
 import { buildAnalysisPrompt } from './prompt-builder.js';
 import logger from './logger.js';
 import { recordMetric } from './metrics.js';
+import { getDefaultSection, resolveSection } from './config-registry.js';
 
 /**
  * Standard file data schema used throughout the analysis pipeline
@@ -360,7 +361,7 @@ export const displayResults = (result, { silent = false } = {}) => {
 };
 
 // Minimum file count to trigger Opus orchestration instead of sequential analysis
-const ORCHESTRATOR_THRESHOLD = 3;
+const ORCHESTRATOR_THRESHOLD = getDefaultSection('orchestrator').threshold;
 
 /**
  * Runs code analysis on files
@@ -385,12 +386,15 @@ export const runAnalysis = async (filesData, config, options = {}) => {
         return createEmptyResult();
     }
 
-    const useOrchestrator = filesData.length >= ORCHESTRATOR_THRESHOLD;
+    // Resolve orchestrator threshold: remote settings.json > local defaults.json
+    const orchConfig = await resolveSection('orchestrator');
+    const threshold = orchConfig?.threshold || ORCHESTRATOR_THRESHOLD;
+    const useOrchestrator = filesData.length >= threshold;
 
     logger.debug('analysis-engine - runAnalysis', 'Starting analysis', {
         fileCount: filesData.length,
         useOrchestrator,
-        threshold: ORCHESTRATOR_THRESHOLD
+        threshold
     });
 
     let result;

package/lib/utils/claude-client.js

@@ -21,6 +21,7 @@ import path from 'path';
 import os from 'os';
 import logger from './logger.js';
 import config from '../config.js';
+import { getDefaultSection } from './config-registry.js';
 import {
     detectClaudeError,
     formatClaudeError,
@@ -47,14 +48,17 @@ class ClaudeClientError extends Error {
 
 /**
  * Model alias map — resolves shorthand names to full SDK model IDs.
+ * Loaded from lib/defaults.json via config-registry, with env var overrides.
  * Env var overrides match Lumiere contract (CLAUDE_MODEL_HAIKU, CLAUDE_MODEL_SONNET, CLAUDE_MODEL_OPUS).
  * Full model IDs (e.g., 'claude-sonnet-4-6') pass through unchanged.
  */
-const MODEL_ALIASES = {
-    haiku: process.env.CLAUDE_MODEL_HAIKU || 'claude-haiku-4-5-20251001',
-    sonnet: process.env.CLAUDE_MODEL_SONNET || 'claude-sonnet-4-6',
-    opus: process.env.CLAUDE_MODEL_OPUS || 'claude-opus-4-6'
-};
+const _localModelMap = getDefaultSection('models').modelMap;
+const MODEL_ALIASES = Object.fromEntries(
+    Object.entries(_localModelMap).map(([alias, fullId]) => [
+        alias,
+        process.env[`CLAUDE_MODEL_${alias.toUpperCase()}`] || fullId
+    ])
+);
 
 /**
  * Resolves a model alias to a full model ID.

package/lib/utils/config-registry.js

@@ -0,0 +1,257 @@
+/**
+ * File: config-registry.js
+ * Purpose: Unified configuration reader with local defaults + remote overrides
+ *
+ * Design:
+ * - Reads lib/defaults.json synchronously at import time (ships with the package)
+ * - Fetches remote overrides from git-hooks-config via remote-config.js (async, cached)
+ * - Merge priority: local defaults < remote overrides
+ * - Consumers higher in the chain (presets, user .claude/config.json) merge on top separately
+ *
+ * Section-to-remote-file mapping:
+ *   models       → models.json       (root)
+ *   tools        → tools.json        (.tools key)
+ *   prAnalysis   → categories.json   (.inlineCategories, .generalCategories → merged into prAnalysis)
+ *   presetLinters → formatters.json  (.presetTools)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import logger from './logger.js';
+import { fetchRemoteConfig } from './remote-config.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Path to the package defaults file */
+const DEFAULTS_PATH = path.resolve(__dirname, '..', 'defaults.json');
+
+/**
+ * Helper: create a mapping entry that reads a section key from settings.json.
+ * @param {string} sectionKey - Key within settings.json (e.g., 'analysis', 'judge')
+ * @returns {{ file: string, extract: (remote: Object) => Object }}
+ */
+const _settingsEntry = (sectionKey) => ({
+    file: 'settings.json',
+    extract: (remote) => remote?.[sectionKey] || {}
+});
+
+/**
+ * Maps defaults.json section names to remote config files and their extraction logic.
+ * Each entry defines:
+ * - file: the remote JSON filename to fetch
+ * - extract: function that transforms the remote JSON into the shape expected for deep-merge
+ * @type {Object<string, { file: string, extract: (remote: Object) => Object }>}
+ */
+const SECTION_REMOTE_MAP = {
+    models: {
+        file: 'models.json',
+        extract: (remote) => remote
+    },
+    tools: {
+        file: 'tools.json',
+        extract: (remote) => remote?.tools || {}
+    },
+    prAnalysis: {
+        file: 'categories.json',
+        extract: (remote) => {
+            const result = {};
+            if (remote?.inlineCategories) result.inlineCategories = remote.inlineCategories;
+            if (remote?.generalCategories) result.generalCategories = remote.generalCategories;
+            return result;
+        }
+    },
+    presetLinters: {
+        file: 'formatters.json',
+        extract: (remote) => remote?.presetTools || {}
+    },
+    // Team-policy sections — all read from settings.json
+    analysis: _settingsEntry('analysis'),
+    commitMessage: _settingsEntry('commitMessage'),
+    judge: _settingsEntry('judge'),
+    orchestrator: _settingsEntry('orchestrator'),
+    prMetadata: _settingsEntry('prMetadata'),
+    linting: _settingsEntry('linting')
+};
+
+// ── Sync: local defaults (read once at import time) ────────────────────────
+
+let _defaults = null;
+
+/**
+ * Load defaults.json synchronously. Called once at module init.
+ * @returns {Object} Parsed defaults
+ * @throws {Error} If defaults.json is missing or invalid (fatal — package is broken)
+ */
+function _loadDefaults() {
+    if (_defaults !== null) return _defaults;
+
+    try {
+        const raw = fs.readFileSync(DEFAULTS_PATH, 'utf8');
+        _defaults = JSON.parse(raw);
+        logger.debug('config-registry', 'Loaded defaults.json', {
+            sections: Object.keys(_defaults)
+        });
+        return _defaults;
+    } catch (err) {
+        throw new Error(
+            `Failed to load package defaults from ${DEFAULTS_PATH}: ${err.message}. ` +
+                'This indicates a broken installation — reinstall claude-git-hooks.'
+        );
+    }
+}
+
+// Load immediately on import
+_loadDefaults();
+
+/**
+ * Returns the full defaults object (sync, no I/O after init).
+ * @returns {Object} Complete defaults from lib/defaults.json
+ */
+export function getDefaults() {
+    return _defaults;
+}
+
+/**
+ * Returns a single section from defaults (sync).
+ * @param {string} sectionName - Top-level key in defaults.json (e.g., 'models', 'tools', 'judge')
+ * @returns {Object|undefined} The section value, or undefined if not found
+ */
+export function getDefaultSection(sectionName) {
+    return _defaults?.[sectionName];
+}
+
+// ── Async: remote overrides (fetched on demand, cached) ────────────────────
+
+/**
+ * In-memory cache for resolved sections (local + remote merged).
+ * @type {Map<string, Object>}
+ */
+const _resolvedCache = new Map();
+
+/**
+ * Deep-merge two objects (source overrides target).
+ * Arrays are replaced wholesale (not concatenated).
+ * @param {Object} target - Base object
+ * @param {Object} source - Override object
+ * @returns {Object} Merged result
+ */
+function _deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+            result[key] = _deepMerge(target[key] || {}, source[key]);
+        } else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+
+/**
+ * Resolve a config section by merging local defaults with remote overrides.
+ *
+ * If the section has a mapping in SECTION_REMOTE_MAP, the corresponding remote
+ * file is fetched and merged (remote > local). If fetch fails, local defaults
+ * are returned. Results are cached per process.
+ *
+ * @param {string} sectionName - Top-level key in defaults.json
+ * @returns {Promise<Object>} Merged section (local defaults + remote overrides)
+ */
+export async function resolveSection(sectionName) {
+    if (_resolvedCache.has(sectionName)) {
+        return _resolvedCache.get(sectionName);
+    }
+
+    const localSection = getDefaultSection(sectionName);
+    if (localSection === undefined) {
+        logger.debug('config-registry - resolveSection', 'Section not found in defaults', {
+            sectionName
+        });
+        return undefined;
+    }
+
+    const mapping = SECTION_REMOTE_MAP[sectionName];
+    if (!mapping) {
+        // No remote file for this section — return local as-is
+        _resolvedCache.set(sectionName, localSection);
+        return localSection;
+    }
+
+    const remoteData = await fetchRemoteConfig(mapping.file);
+    if (!remoteData) {
+        logger.debug('config-registry - resolveSection', 'Remote unavailable, using local defaults', {
+            sectionName,
+            remoteFile: mapping.file
+        });
+        _resolvedCache.set(sectionName, localSection);
+        return localSection;
+    }
+
+    const remoteOverrides = mapping.extract(remoteData);
+    const merged = _deepMerge(localSection, remoteOverrides);
+
+    logger.debug('config-registry - resolveSection', 'Merged local + remote', {
+        sectionName,
+        remoteFile: mapping.file,
+        localKeys: Object.keys(localSection),
+        remoteKeys: Object.keys(remoteOverrides)
+    });
+
+    _resolvedCache.set(sectionName, merged);
+    return merged;
+}
+
+// ── Convenience resolvers ──────────────────────────────────────────────────
+
+/**
+ * Resolve a model alias to a full model ID, with remote override support.
+ * Priority: env var > remote models.json > local defaults.json
+ *
+ * @param {string} alias - Model alias ('sonnet', 'opus', 'haiku') or full ID
+ * @returns {Promise<string>} Full model ID
+ */
+export async function resolveModelAlias(alias) {
+    const modelsConfig = await resolveSection('models');
+    const modelMap = modelsConfig?.modelMap || {};
+
+    // Env var override (highest priority)
+    const envKey = `CLAUDE_MODEL_${alias.toUpperCase()}`;
+    if (process.env[envKey]) {
+        return process.env[envKey];
+    }
+
+    return modelMap[alias] || alias;
+}
+
+/**
+ * Resolve configuration for a specific linter tool, with remote override support.
+ * Merges local defaults.tools[toolName] with remote tools.json tools[toolName].
+ *
+ * @param {string} toolName - Tool name ('prettier', 'eslint', 'spotless', 'sqlfluff')
+ * @returns {Promise<Object|undefined>} Tool config (enabled, timeout, perFile) or undefined
+ */
+export async function resolveToolConfig(toolName) {
+    const toolsConfig = await resolveSection('tools');
+    return toolsConfig?.[toolName];
+}
+
+// ── Test helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Reset all caches. Test helper — not intended for production use.
+ */
+export function _resetRegistry() {
+    _resolvedCache.clear();
+    _defaults = null;
+    _loadDefaults();
+}
+
+/**
+ * Reset resolved cache only (keeps defaults loaded).
+ * Useful for testing remote merge behavior without re-reading defaults.json.
+ */
+export function _resetResolvedCache() {
+    _resolvedCache.clear();
+}