claude-git-hooks 2.20.0 → 2.21.0

package/lib/utils/linear-connector.js

@@ -0,0 +1,287 @@
+/**
+ * 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/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,159 @@
+/**
+ * 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,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.20.0",
+    "version": "2.21.0",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {

package/templates/ANALYZE_PR.md

@@ -0,0 +1,79 @@
+# PR Analysis
+
+You are a senior code reviewer analyzing a Pull Request. Your goal is to identify issues, suggest improvements, and provide structured feedback.
+
+## PR Context
+
+**Title:** {{PR_TITLE}}
+
+**Description:**
+{{PR_BODY}}
+
+## Ticket Context
+
+{{TICKET_CONTEXT}}
+
+## Changed Files
+
+{{PR_FILES}}
+
+## Diff
+
+{{PR_DIFF}}
+
+## Preset Guidelines
+
+{{PRESET_GUIDELINES}}
+
+## Category Definitions
+
+### Inline Categories (attached to specific file:line)
+{{INLINE_CATEGORIES}}
+
+### General Categories (review-level observations)
+{{GENERAL_CATEGORIES}}
+
+## Instructions
+
+1. Review the PR diff thoroughly, considering the ticket context and preset guidelines.
+2. Classify each finding into EXACTLY one of the categories listed above. Use ONLY the exact category values listed — do not invent new categories.
+3. For code-level issues (bugs, security vulnerabilities, performance problems, complex hotspots), create **inline comments** with the exact file path and line number from the diff.
+4. For review-level observations (scope creep, style consistency, missing tests, documentation gaps, ticket alignment), create **general comments**.
+5. Assign severity: `critical`, `major`, `minor`, or `info`.
+6. For inline comments, include a `suggestion` field with the recommended fix when applicable.
+
+## Output Format
+
+Return a JSON object with this exact structure:
+
+```json
+{
+    "verdict": "approve" | "request-changes" | "comment",
+    "summary": "Brief overall assessment (1-2 sentences)",
+    "inlineComments": [
+        {
+            "path": "src/file.js",
+            "line": 42,
+            "side": "RIGHT",
+            "category": "<inline category>",
+            "severity": "critical|major|minor|info",
+            "body": "Description of the issue",
+            "suggestion": "Recommended fix (optional)"
+        }
+    ],
+    "generalComments": [
+        {
+            "category": "<general category>",
+            "severity": "critical|major|minor|info",
+            "body": "Description of the observation"
+        }
+    ]
+}
+```
+
+IMPORTANT:
+- Use ONLY the exact category values from the lists above
+- `line` must reference a line number visible in the diff (added or context lines)
+- `side` should be "RIGHT" for added/modified lines, "LEFT" for removed lines
+- If no issues found, return verdict "approve" with empty arrays
+- Be strict but fair — only flag genuine issues, not style preferences unless the preset guidelines explicitly require them

package/templates/config.advanced.example.json

@@ -31,6 +31,22 @@
         "judge": {
             "enabled": true,
             "model": "opus"
+        },
+
+        "prAnalysis": {
+            "model": "sonnet",
+            "timeout": 300000,
+            "inlineCategories": ["bug", "security", "performance", "hotspot"],
+            "generalCategories": [
+                "ticket-alignment",
+                "scope",
+                "style",
+                "good-practice",
+                "extensibility",
+                "observability",
+                "documentation",
+                "testing"
+            ]
         }
     },
 
@@ -61,9 +77,34 @@
 
         "judge.model": {
             "description": "Model for the judge LLM call",
-            "default": "opus",
-            "examples": ["opus", "sonnet", "haiku"],
-            "use_case": "Use a cheaper model for faster/cheaper judge passes"
+            "default": "sonnet",
+            "examples": ["sonnet", "opus", "haiku"],
+            "use_case": "Override the default sonnet model for judge passes"
+        },
+
+        "prAnalysis.model": {
+            "description": "Claude model for PR analysis",
+            "default": "sonnet",
+            "examples": ["sonnet", "opus", "haiku"],
+            "use_case": "Use a more capable model for deeper analysis or a cheaper one for speed"
+        },
+
+        "prAnalysis.timeout": {
+            "description": "Timeout in milliseconds for the PR analysis Claude call",
+            "default": "300000",
+            "use_case": "Increase for very large PRs"
+        },
+
+        "prAnalysis.inlineCategories": {
+            "description": "Categories for inline (file:line) comments",
+            "default": "[\"bug\", \"security\", \"performance\", \"hotspot\"]",
+            "use_case": "Customize which issue types generate inline PR comments"
+        },
+
+        "prAnalysis.generalCategories": {
+            "description": "Categories for general (review-level) comments",
+            "default": "[\"ticket-alignment\", \"scope\", \"style\", \"good-practice\", \"extensibility\", \"observability\", \"documentation\", \"testing\"]",
+            "use_case": "Customize which observation types appear in the review body"
         }
     },
 

package/templates/settings.local.example.json

@@ -1,4 +1,5 @@
 {
   "_comment": "This file stores local settings that should NOT be committed. Copy to .claude/settings.local.json",
-  "githubToken": "ghp_your_token_here"
+  "githubToken": "ghp_your_token_here",
+  "linearToken": "lin_api_your_token_here"
 }