claude-git-hooks 2.20.0 → 2.30.1

package/lib/utils/linear-connector.js

@@ -0,0 +1,284 @@
+/**
+ * File: linear-connector.js
+ * Purpose: Linear API connector for fetching ticket context
+ *
+ * Connection flow (resilient):
+ * 1. testConnection() → verify token and API reachability
+ * 2. fetchTicket(identifier) → get ticket details
+ * 3. On failure: retry → reconnect → graceful degradation
+ *
+ * Token priority (same pattern as github-api.js):
+ * 1. LINEAR_API_TOKEN env var
+ * 2. .claude/settings.local.json → linearToken
+ *
+ * Dependencies:
+ * - https: Node.js built-in HTTP client
+ * - logger: Debug and error logging
+ */
+
+import https from 'https';
+import logger from './logger.js';
+import { loadToken } from './token-store.js';
+
+const LINEAR_HOSTNAME = 'api.linear.app';
+const LINEAR_PATH = '/graphql';
+const LINEAR_TIMEOUT = 10000;
+const MAX_RETRIES = 2;
+
+/**
+ * Custom error for Linear connector failures
+ */
+export class LinearConnectorError extends Error {
+    constructor(message, { cause, context } = {}) {
+        super(message);
+        this.name = 'LinearConnectorError';
+        this.cause = cause;
+        this.context = context;
+    }
+}
+
+/**
+ * Load Linear API token from settings
+ * Delegates to token-store.js for centralized token management.
+ * @returns {string|null} Token or null if not found
+ */
+export const loadLinearToken = () => loadToken('linearToken', ['LINEAR_API_TOKEN']);
+
+/**
+ * Execute a GraphQL query against Linear API
+ * @param {string} token - Linear API token
+ * @param {string} query - GraphQL query
+ * @param {Object} variables - Query variables
+ * @returns {Promise<Object>} Response data
+ */
+const graphqlRequest = (token, query, variables = {}) =>
+    new Promise((resolve, reject) => {
+        const body = JSON.stringify({ query, variables });
+
+        const req = https.request(
+            {
+                hostname: LINEAR_HOSTNAME,
+                path: LINEAR_PATH,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: token,
+                    'Content-Length': Buffer.byteLength(body)
+                },
+                timeout: LINEAR_TIMEOUT
+            },
+            (res) => {
+                let data = '';
+                res.on('data', (chunk) => (data += chunk));
+                res.on('end', () => {
+                    try {
+                        const parsed = JSON.parse(data);
+
+                        if (parsed.errors) {
+                            reject(
+                                new LinearConnectorError(
+                                    `Linear API error: ${parsed.errors[0].message}`,
+                                    {
+                                        context: { errors: parsed.errors }
+                                    }
+                                )
+                            );
+                            return;
+                        }
+
+                        resolve(parsed.data);
+                    } catch (e) {
+                        reject(
+                            new LinearConnectorError('Failed to parse Linear API response', {
+                                cause: e
+                            })
+                        );
+                    }
+                });
+            }
+        );
+
+        req.on('error', (error) => {
+            reject(
+                new LinearConnectorError('Linear API request failed', {
+                    cause: error,
+                    context: { hostname: LINEAR_HOSTNAME }
+                })
+            );
+        });
+
+        req.on('timeout', () => {
+            req.destroy();
+            reject(
+                new LinearConnectorError('Linear API request timed out', {
+                    context: { timeout: LINEAR_TIMEOUT }
+                })
+            );
+        });
+
+        req.write(body);
+        req.end();
+    });
+
+/**
+ * Test Linear API connection health
+ * @param {string} token - Linear API token
+ * @returns {Promise<boolean>} True if connection is healthy
+ */
+export const testConnection = async (token) => {
+    logger.debug('linear-connector - testConnection', 'Testing Linear API connection');
+
+    try {
+        const data = await graphqlRequest(token, '{ viewer { id name } }');
+        const isHealthy = !!data?.viewer?.id;
+
+        logger.debug('linear-connector - testConnection', 'Connection test result', {
+            healthy: isHealthy,
+            user: data?.viewer?.name
+        });
+
+        return isHealthy;
+    } catch (error) {
+        logger.debug('linear-connector - testConnection', 'Connection test failed', {
+            error: error.message
+        });
+        return false;
+    }
+};
+
+/**
+ * Extract team key and issue number from Linear identifier
+ * @param {string} identifier - e.g., "AUT-1234"
+ * @returns {{ teamKey: string, number: number }|null}
+ */
+export const parseLinearIdentifier = (identifier) => {
+    const match = identifier.match(/^([A-Z]+)-(\d+)$/i);
+    if (!match) return null;
+    return { teamKey: match[1].toUpperCase(), number: parseInt(match[2], 10) };
+};
+
+/**
+ * Extract Linear ticket identifier from PR title
+ * @param {string} title - PR title (e.g., "[AUT-1234] feat: add feature")
+ * @returns {string|null} Linear identifier or null
+ */
+export const extractLinearTicketFromTitle = (title) => {
+    if (!title) return null;
+
+    // Match [AUT-1234] pattern at start of title
+    const match = title.match(/^\[([A-Z]+-\d+)\]/i);
+    if (match) {
+        return match[1].toUpperCase();
+    }
+
+    return null;
+};
+
+/**
+ * Fetch a Linear ticket by identifier with retry logic
+ *
+ * Flow: test connection → fetch → retry → reconnect → graceful degradation
+ *
+ * @param {string} identifier - Linear identifier (e.g., "AUT-1234")
+ * @returns {Promise<Object|null>} Ticket data or null on failure
+ */
+export const fetchTicket = async (identifier) => {
+    logger.debug('linear-connector - fetchTicket', 'Fetching Linear ticket', { identifier });
+
+    const token = loadLinearToken();
+    if (!token) {
+        logger.debug('linear-connector - fetchTicket', 'No Linear token configured, skipping');
+        return null;
+    }
+
+    const parsed = parseLinearIdentifier(identifier);
+    if (!parsed) {
+        logger.debug('linear-connector - fetchTicket', 'Invalid identifier format', { identifier });
+        return null;
+    }
+
+    const query = `
+        query FetchTicket($teamKey: String!, $number: Float!) {
+            issues(filter: {
+                team: { key: { eq: $teamKey } }
+                number: { eq: $number }
+            }, first: 1) {
+                nodes {
+                    id
+                    identifier
+                    title
+                    description
+                    priority
+                    state { name }
+                    labels { nodes { name } }
+                    assignee { name }
+                }
+            }
+        }
+    `;
+
+    const variables = { teamKey: parsed.teamKey, number: parsed.number };
+
+    // Step a: Test connection health
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            // Test connection on first attempt
+            if (attempt === 0) {
+                const healthy = await testConnection(token);
+                if (!healthy) {
+                    logger.debug(
+                        'linear-connector - fetchTicket',
+                        'Connection unhealthy, retrying',
+                        { attempt }
+                    );
+                    continue;
+                }
+            }
+
+            // Step b: Fetch ticket
+            const data = await graphqlRequest(token, query, variables);
+            const ticket = data?.issues?.nodes?.[0];
+
+            if (!ticket) {
+                logger.debug('linear-connector - fetchTicket', 'Ticket not found', { identifier });
+                return null;
+            }
+
+            logger.debug('linear-connector - fetchTicket', 'Ticket fetched successfully', {
+                identifier: ticket.identifier,
+                title: ticket.title,
+                state: ticket.state?.name
+            });
+
+            return {
+                id: ticket.id,
+                identifier: ticket.identifier,
+                title: ticket.title,
+                description: ticket.description || '',
+                priority: ticket.priority,
+                state: ticket.state?.name || 'unknown',
+                labels: (ticket.labels?.nodes || []).map((l) => l.name),
+                assignee: ticket.assignee?.name || null
+            };
+        } catch (error) {
+            logger.debug('linear-connector - fetchTicket', `Attempt ${attempt + 1} failed`, {
+                error: error.message,
+                attempt
+            });
+
+            if (attempt < MAX_RETRIES) {
+                // Steps c/d: Retry with reconnection
+                logger.debug('linear-connector - fetchTicket', 'Retrying after connection failure');
+                // Small delay before retry
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+            }
+        }
+    }
+
+    // Graceful degradation
+    logger.warning(
+        'linear-connector - fetchTicket',
+        `Could not fetch Linear ticket ${identifier} after ${MAX_RETRIES + 1} attempts`
+    );
+    return null;
+};

package/lib/utils/package-info.js

@@ -61,4 +61,3 @@ export const getPackageName = async () => {
     const pkg = await getPackageJson();
     return pkg.name;
 };
-

package/lib/utils/pr-statistics.js

@@ -0,0 +1,85 @@
+/**
+ * File: pr-statistics.js
+ * Purpose: Write-only JSONL statistics for PR analyses
+ *
+ * Design: Append-only JSONL file at .claude/statistics/pr/stats.jsonl
+ * No read/query functions (YAGNI).
+ *
+ * Dependencies:
+ * - fs: File system operations
+ * - path: Cross-platform path handling
+ * - logger: Debug logging
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import logger from './logger.js';
+
+/**
+ * Get repository root directory
+ * @returns {string}
+ */
+const getRepoRoot = () => {
+    try {
+        return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    } catch {
+        return process.cwd();
+    }
+};
+
+/**
+ * Record a PR analysis result as a JSONL entry
+ *
+ * @param {Object} data - Analysis data
+ * @param {string} data.url - PR URL
+ * @param {number} data.number - PR number
+ * @param {string} data.repo - Repository full name (owner/repo)
+ * @param {string} data.preset - Preset used
+ * @param {string} data.verdict - Analysis verdict
+ * @param {number} data.totalIssues - Total issues found
+ * @param {Object} data.issuesByCategory - Issues grouped by category
+ * @param {number} data.inlineCount - Number of inline comments
+ * @param {number} data.generalCount - Number of general comments
+ * @param {number} data.commentsPosted - Comments actually posted
+ * @param {number} data.commentsSkipped - Comments skipped by user
+ */
+export const recordPRAnalysis = (data) => {
+    try {
+        const repoRoot = getRepoRoot();
+        const statsDir = path.join(repoRoot, '.claude', 'statistics', 'pr');
+        const statsFile = path.join(statsDir, 'stats.jsonl');
+
+        // Ensure directory exists
+        if (!fs.existsSync(statsDir)) {
+            fs.mkdirSync(statsDir, { recursive: true });
+        }
+
+        const record = {
+            timestamp: new Date().toISOString(),
+            url: data.url,
+            number: data.number,
+            repo: data.repo,
+            preset: data.preset,
+            verdict: data.verdict,
+            totalIssues: data.totalIssues,
+            issuesByCategory: data.issuesByCategory,
+            inlineCount: data.inlineCount,
+            generalCount: data.generalCount,
+            commentsPosted: data.commentsPosted,
+            commentsSkipped: data.commentsSkipped
+        };
+
+        fs.appendFileSync(statsFile, `${JSON.stringify(record)}\n`, 'utf8');
+
+        logger.debug('pr-statistics - recordPRAnalysis', 'Statistics recorded', {
+            statsFile,
+            totalIssues: data.totalIssues
+        });
+    } catch (error) {
+        // Non-fatal: statistics failure should never block the command
+        logger.debug('pr-statistics - recordPRAnalysis', 'Failed to record statistics', {
+            error: error.message
+        });
+    }
+};

package/lib/utils/token-store.js

@@ -0,0 +1,161 @@
+/**
+ * File: token-store.js
+ * Purpose: Abstract utility for storing and loading tokens from .claude/settings.local.json
+ *
+ * Centralizes token persistence for all integrations (GitHub, Linear, etc.)
+ * Single source of truth for settings.local.json read/write operations.
+ *
+ * Token storage: .claude/settings.local.json (gitignored)
+ *
+ * Dependencies:
+ * - fs: File system operations
+ * - path: Cross-platform path handling
+ * - child_process: Git repo root detection
+ * - logger: Debug logging
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import logger from './logger.js';
+
+/**
+ * Get repository root directory
+ * @returns {string} Absolute path to repo root
+ */
+const getRepoRoot = () => {
+    try {
+        return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    } catch {
+        return process.cwd();
+    }
+};
+
+/**
+ * Get the path to settings.local.json
+ * @returns {string} Absolute path
+ */
+const getSettingsPath = () => {
+    const repoRoot = getRepoRoot();
+    return path.join(repoRoot, '.claude', 'settings.local.json');
+};
+
+/**
+ * Load all local settings from .claude/settings.local.json
+ * Why: Gitignored file for sensitive data like tokens
+ *
+ * @returns {Object} Settings object or empty object
+ */
+export const loadLocalSettings = () => {
+    try {
+        const settingsPath = getSettingsPath();
+
+        logger.debug('token-store - loadLocalSettings', 'Checking for settings file', {
+            settingsPath
+        });
+
+        if (fs.existsSync(settingsPath)) {
+            const content = fs.readFileSync(settingsPath, 'utf8');
+            const settings = JSON.parse(content);
+            logger.debug('token-store - loadLocalSettings', 'Settings loaded successfully');
+            return settings;
+        }
+
+        logger.debug('token-store - loadLocalSettings', 'Settings file not found');
+    } catch (error) {
+        logger.debug('token-store - loadLocalSettings', 'Could not load local settings', {
+            error: error.message,
+            stack: error.stack
+        });
+    }
+    return {};
+};
+
+/**
+ * Load a specific token from settings or environment variable
+ *
+ * @param {string} settingsKey - Key in settings.local.json (e.g., 'githubToken', 'linearToken')
+ * @param {string[]} envVars - Environment variable names to check, in priority order
+ * @returns {string|null} Token value or null if not found
+ */
+export const loadToken = (settingsKey, envVars = []) => {
+    // Priority 1: Environment variables (in order)
+    for (const envVar of envVars) {
+        if (process.env[envVar]) {
+            logger.debug('token-store - loadToken', `Using ${envVar} env var`);
+            return process.env[envVar];
+        }
+    }
+
+    // Priority 2: Local settings file
+    const settings = loadLocalSettings();
+    if (settings[settingsKey]) {
+        logger.debug('token-store - loadToken', `Using ${settingsKey} from settings.local.json`);
+        return settings[settingsKey];
+    }
+
+    return null;
+};
+
+/**
+ * Save a token to .claude/settings.local.json
+ *
+ * @param {string} settingsKey - Key in settings.local.json (e.g., 'githubToken', 'linearToken')
+ * @param {string} token - Token value to save
+ * @returns {{ success: boolean, path: string, error?: string }}
+ */
+export const saveToken = (settingsKey, token) => {
+    try {
+        const repoRoot = getRepoRoot();
+        const claudeDir = path.join(repoRoot, '.claude');
+        const settingsPath = path.join(claudeDir, 'settings.local.json');
+
+        logger.debug('token-store - saveToken', 'Saving token', { settingsKey, settingsPath });
+
+        // Ensure .claude directory exists
+        if (!fs.existsSync(claudeDir)) {
+            fs.mkdirSync(claudeDir, { recursive: true });
+        }
+
+        // Load existing settings or create new
+        let settings = {};
+        if (fs.existsSync(settingsPath)) {
+            try {
+                settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            } catch {
+                logger.debug(
+                    'token-store - saveToken',
+                    'Invalid existing settings, starting fresh'
+                );
+                settings = {};
+            }
+        }
+
+        // Update token
+        settings[settingsKey] = token;
+
+        // Add comment if new file
+        if (!settings._comment) {
+            settings._comment = 'Local settings - DO NOT COMMIT. This file is gitignored.';
+        }
+
+        // Save settings with restricted permissions (owner read/write only)
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { mode: 0o600 });
+
+        logger.debug('token-store - saveToken', 'Token saved successfully');
+
+        return { success: true, path: settingsPath };
+    } catch (error) {
+        logger.error('token-store - saveToken', 'Failed to save token', error);
+        return { success: false, path: null, error: error.message };
+    }
+};
+
+/**
+ * Check if a token exists (in env vars or settings)
+ *
+ * @param {string} settingsKey - Key in settings.local.json
+ * @param {string[]} envVars - Environment variable names to check
+ * @returns {boolean}
+ */
+export const hasToken = (settingsKey, envVars = []) => loadToken(settingsKey, envVars) !== null;

package/package.json

@@ -1,69 +1,69 @@
-{
-    "name": "claude-git-hooks",
-    "version": "2.20.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.0",
-        "jest": "^29.7.0",
-        "prettier": "^3.2.0"
-    }
-}
+{
+    "name": "claude-git-hooks",
+    "version": "2.30.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"
+    }
+}