claude-git-hooks 2.30.2 → 2.33.0

package/lib/utils/label-resolver.js

@@ -0,0 +1,232 @@
+/**
+ * File: label-resolver.js
+ * Purpose: Resolves labels for a PR based on remote config + local fallback
+ *
+ * Design:
+ * - Fetches label rules from remote config repo (labels.json)
+ * - Falls back to local config when remote is unavailable
+ * - Five rule types applied in order: preset, size, quality, strategy, default
+ * - Each rule type independently enabled/disabled via remote config
+ * - Returns deduplicated, sorted array of label strings
+ * - Does NOT import config.js — receives local fallback via context (dependency injection)
+ */
+
+import logger from './logger.js';
+import { fetchRemoteConfig } from './remote-config.js';
+
+/** Default size thresholds when remote config is unavailable */
+const DEFAULT_SIZE_THRESHOLDS = { S: 10, M: 50, L: 100 };
+
+/**
+ * Resolve labels for a PR based on remote config + local fallback.
+ *
+ * @param {Object} context - Label resolution context
+ * @param {string} [context.preset] - Active preset name (e.g. 'backend')
+ * @param {number} [context.fileCount] - Number of changed files
+ * @param {string} [context.mergeStrategy] - 'squash' | 'merge-commit' | 'unknown'
+ * @param {Object} [context.analysisResult] - Quality analysis flags
+ * @param {boolean} [context.analysisResult.breakingChanges] - Has breaking changes
+ * @param {boolean} [context.analysisResult.hasSecurityIssues] - Has security issues
+ * @param {boolean} [context.analysisResult.hasPerformanceIssues] - Has performance issues
+ * @param {Object} [context.localLabelRules] - Fallback label rules from local config
+ * @returns {Promise<string[]>} Deduplicated, sorted array of label strings
+ */
+export async function resolveLabels(context = {}) {
+    const {
+        preset,
+        fileCount,
+        mergeStrategy,
+        analysisResult,
+        localLabelRules
+    } = context;
+
+    logger.debug('label-resolver - resolveLabels', 'Starting label resolution', {
+        preset,
+        fileCount,
+        mergeStrategy,
+        hasAnalysisResult: !!analysisResult,
+        hasLocalRules: !!localLabelRules
+    });
+
+    // Fetch remote config (null if unavailable)
+    const remoteConfig = await fetchRemoteConfig('labels.json');
+
+    logger.debug('label-resolver - resolveLabels', 'Remote config result', {
+        hasRemoteConfig: remoteConfig !== null
+    });
+
+    const labels = [];
+
+    // 1. Preset labels
+    _applyPresetLabels(labels, preset, remoteConfig, localLabelRules);
+
+    // 2. Size labels
+    _applySizeLabels(labels, fileCount, remoteConfig);
+
+    // 3. Quality labels
+    _applyQualityLabels(labels, analysisResult, remoteConfig);
+
+    // 4. Strategy labels
+    _applyStrategyLabels(labels, mergeStrategy);
+
+    // 5. Default labels (only when remote is available)
+    _applyDefaultLabels(labels, remoteConfig);
+
+    // Deduplicate and sort
+    const result = [...new Set(labels)].sort();
+
+    logger.debug('label-resolver - resolveLabels', 'Labels resolved', {
+        count: result.length,
+        labels: result
+    });
+
+    return result;
+}
+
+/**
+ * Apply preset-specific labels.
+ * Priority: remote presetLabels → local fallback rules.
+ *
+ * @param {string[]} labels - Mutable labels array
+ * @param {string|undefined} preset - Active preset name
+ * @param {Object|null} remoteConfig - Remote labels.json config
+ * @param {Object|undefined} localLabelRules - Local fallback rules
+ */
+function _applyPresetLabels(labels, preset, remoteConfig, localLabelRules) {
+    if (!preset) return;
+
+    // Try remote first
+    const remotePresetLabels = remoteConfig?.presetLabels?.[preset];
+    if (Array.isArray(remotePresetLabels) && remotePresetLabels.length > 0) {
+        logger.debug('label-resolver - _applyPresetLabels', 'Using remote preset labels', {
+            preset,
+            labels: remotePresetLabels
+        });
+        labels.push(...remotePresetLabels);
+        return;
+    }
+
+    // Fall back to local
+    const localPresetLabels = localLabelRules?.[preset];
+    if (Array.isArray(localPresetLabels) && localPresetLabels.length > 0) {
+        logger.debug('label-resolver - _applyPresetLabels', 'Using local fallback preset labels', {
+            preset,
+            labels: localPresetLabels
+        });
+        labels.push(...localPresetLabels);
+    }
+}
+
+/**
+ * Apply size labels based on file count and thresholds.
+ *
+ * @param {string[]} labels - Mutable labels array
+ * @param {number|undefined} fileCount - Number of changed files
+ * @param {Object|null} remoteConfig - Remote labels.json config
+ */
+function _applySizeLabels(labels, fileCount, remoteConfig) {
+    if (fileCount === undefined || fileCount === null) return;
+
+    // Check if disabled in remote config
+    if (remoteConfig?.sizeLabels?.enabled === false) {
+        logger.debug('label-resolver - _applySizeLabels', 'Size labels disabled via remote config');
+        return;
+    }
+
+    const thresholds = remoteConfig?.sizeLabels?.thresholds || DEFAULT_SIZE_THRESHOLDS;
+    const { S, M, L } = thresholds;
+
+    let sizeLabel;
+    if (fileCount < S) {
+        sizeLabel = 'size:S';
+    } else if (fileCount < M) {
+        sizeLabel = 'size:M';
+    } else if (fileCount < L) {
+        sizeLabel = 'size:L';
+    } else {
+        sizeLabel = 'size:XL';
+    }
+
+    logger.debug('label-resolver - _applySizeLabels', 'Size label applied', {
+        fileCount,
+        thresholds,
+        sizeLabel
+    });
+
+    labels.push(sizeLabel);
+}
+
+/**
+ * Apply quality labels based on analysis result flags.
+ *
+ * @param {string[]} labels - Mutable labels array
+ * @param {Object|undefined} analysisResult - Quality analysis flags
+ * @param {Object|null} remoteConfig - Remote labels.json config
+ */
+function _applyQualityLabels(labels, analysisResult, remoteConfig) {
+    if (!analysisResult) return;
+
+    // Check if disabled globally
+    if (remoteConfig?.qualityLabels?.enabled === false) {
+        logger.debug('label-resolver - _applyQualityLabels', 'Quality labels disabled via remote config');
+        return;
+    }
+
+    const qualityConfig = remoteConfig?.qualityLabels;
+
+    if (analysisResult.breakingChanges && qualityConfig?.breakingChange !== false) {
+        labels.push('breaking-change');
+    }
+
+    if (analysisResult.hasSecurityIssues && qualityConfig?.security !== false) {
+        labels.push('security');
+    }
+
+    if (analysisResult.hasPerformanceIssues && qualityConfig?.performance !== false) {
+        labels.push('performance');
+    }
+
+    logger.debug('label-resolver - _applyQualityLabels', 'Quality labels applied', {
+        breakingChanges: analysisResult.breakingChanges,
+        security: analysisResult.hasSecurityIssues,
+        performance: analysisResult.hasPerformanceIssues
+    });
+}
+
+/**
+ * Apply merge strategy label.
+ *
+ * @param {string[]} labels - Mutable labels array
+ * @param {string|undefined} mergeStrategy - 'squash' | 'merge-commit' | 'unknown'
+ */
+function _applyStrategyLabels(labels, mergeStrategy) {
+    if (!mergeStrategy || mergeStrategy === 'unknown') return;
+
+    const strategyLabel = `merge-strategy:${mergeStrategy}`;
+    labels.push(strategyLabel);
+
+    logger.debug('label-resolver - _applyStrategyLabels', 'Strategy label applied', {
+        mergeStrategy,
+        strategyLabel
+    });
+}
+
+/**
+ * Apply default labels from remote config.
+ * Only applied when remote config is available.
+ *
+ * @param {string[]} labels - Mutable labels array
+ * @param {Object|null} remoteConfig - Remote labels.json config
+ */
+function _applyDefaultLabels(labels, remoteConfig) {
+    if (!remoteConfig) return;
+
+    const defaultLabels = remoteConfig.defaultLabels;
+    if (!Array.isArray(defaultLabels) || defaultLabels.length === 0) return;
+
+    logger.debug('label-resolver - _applyDefaultLabels', 'Default labels applied', {
+        defaultLabels
+    });
+
+    labels.push(...defaultLabels);
+}

package/lib/utils/metrics.js

@@ -0,0 +1,185 @@
+/**
+ * File: metrics.js
+ * Purpose: Centralized metrics collection for code quality observability
+ *
+ * Design principles:
+ * - ALWAYS ON: No opt-in/opt-out toggle
+ * - LOCAL ONLY: Data never leaves user's machine
+ * - FIRE-AND-FORGET: All errors swallowed, never blocks callers
+ * - STRUCTURED LOGS: JSONL format with typed events
+ * - AUTO-ROTATION: 90-day retention for quality trend analysis
+ *
+ * Event schema:
+ * {
+ *   id: "1703612345678-001-a3f",
+ *   timestamp: "2026-03-20T10:30:00.000Z",
+ *   type: "analysis.completed",
+ *   repoId: "owner/repo",
+ *   data: { ... }
+ * }
+ *
+ * Dependencies:
+ * - fs/promises: File operations
+ * - logger: Debug logging
+ * - git-operations: getRepoRoot
+ * - github-client: parseGitHubRepo (lazy, cached)
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import logger from './logger.js';
+import { getRepoRoot } from './git-operations.js';
+
+/**
+ * Counter for generating unique IDs within the same millisecond
+ */
+let eventCounter = 0;
+
+/**
+ * Cached repoId: undefined = not resolved, null = failed, string = resolved
+ */
+let cachedRepoId;
+
+/**
+ * Generate unique event ID
+ * Format: timestamp-counter-random (e.g., 1703612345678-001-a3f)
+ *
+ * @returns {string} Unique event ID
+ */
+const generateEventId = () => {
+    const timestamp = Date.now();
+    const counter = String(eventCounter++).padStart(3, '0');
+    const random = Math.random().toString(36).substring(2, 5);
+
+    if (eventCounter > 999) {
+        eventCounter = 0;
+    }
+
+    return `${timestamp}-${counter}-${random}`;
+};
+
+/**
+ * Get metrics directory path
+ * @returns {string} Metrics directory path under repo root
+ */
+const getMetricsDir = () => {
+    try {
+        return path.join(getRepoRoot(), '.claude', 'metrics');
+    } catch {
+        return path.join(process.cwd(), '.claude', 'metrics');
+    }
+};
+
+/**
+ * Get current metrics log file path (date-stamped)
+ * @returns {string} Current log file path
+ */
+const getCurrentLogFile = () => {
+    const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    return path.join(getMetricsDir(), `events-${date}.jsonl`);
+};
+
+/**
+ * Resolve repository identifier from git remote URL
+ * Uses dynamic import() to avoid circular deps. Cached per-process.
+ *
+ * @returns {Promise<string|null>} Repository full name (owner/repo) or null
+ */
+export const getRepoId = async () => {
+    if (cachedRepoId !== undefined) {
+        return cachedRepoId;
+    }
+
+    try {
+        const { parseGitHubRepo } = await import('./github-client.js');
+        const repo = parseGitHubRepo();
+        cachedRepoId = repo.fullName;
+    } catch {
+        cachedRepoId = null;
+    }
+
+    return cachedRepoId;
+};
+
+/**
+ * Record a metric event
+ * Fire-and-forget: never throws, never blocks
+ *
+ * @param {string} eventType - Event type (e.g., 'analysis.completed', 'judge.completed')
+ * @param {Object} data - Event-specific data
+ * @returns {Promise<void>}
+ */
+export const recordMetric = async (eventType, data = {}) => {
+    try {
+        const dir = getMetricsDir();
+        await fs.mkdir(dir, { recursive: true });
+
+        const repoId = await getRepoId();
+
+        const event = {
+            id: generateEventId(),
+            timestamp: new Date().toISOString(),
+            type: eventType,
+            repoId,
+            data
+        };
+
+        const logFile = getCurrentLogFile();
+        await fs.appendFile(logFile, `${JSON.stringify(event)}\n`, 'utf8');
+
+        logger.debug('metrics - recordMetric', `Event logged: ${eventType}`);
+    } catch (error) {
+        // Fire-and-forget: never throw
+        logger.debug('metrics - recordMetric', 'Failed to record metric', error);
+    }
+};
+
+/**
+ * Rotate old metrics files
+ * Deletes files older than maxDays (default: 90)
+ *
+ * @param {number} maxDays - Keep files newer than this many days
+ * @returns {Promise<void>}
+ */
+export const rotateMetrics = async (maxDays = 90) => {
+    try {
+        const dir = getMetricsDir();
+        const files = await fs.readdir(dir);
+
+        const logFiles = files.filter((f) => f.endsWith('.jsonl'));
+
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - maxDays);
+        const cutoffStr = cutoffDate.toISOString().split('T')[0];
+
+        for (const file of logFiles) {
+            const match = file.match(/events-(\d{4}-\d{2}-\d{2})\.jsonl/);
+            if (match && match[1] < cutoffStr) {
+                await fs.unlink(path.join(dir, file));
+                logger.debug('metrics - rotateMetrics', `Deleted old metrics file: ${file}`);
+            }
+        }
+    } catch (error) {
+        logger.debug('metrics - rotateMetrics', 'Failed to rotate metrics', error);
+    }
+};
+
+/**
+ * Clear all metrics data
+ * @returns {Promise<void>}
+ */
+export const clearMetrics = async () => {
+    try {
+        const dir = getMetricsDir();
+        const files = await fs.readdir(dir);
+        const logFiles = files.filter((f) => f.endsWith('.jsonl'));
+
+        for (const file of logFiles) {
+            await fs.unlink(path.join(dir, file));
+        }
+
+        logger.debug('metrics - clearMetrics', `Cleared ${logFiles.length} metrics files`);
+    } catch (error) {
+        logger.debug('metrics - clearMetrics', 'Failed to clear metrics', error);
+    }
+};

package/lib/utils/pr-statistics.js

@@ -15,6 +15,7 @@ import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
 import logger from './logger.js';
+import { recordMetric } from './metrics.js';
 
 /**
  * Get repository root directory
@@ -72,6 +73,20 @@ export const recordPRAnalysis = (data) => {
 
         fs.appendFileSync(statsFile, `${JSON.stringify(record)}\n`, 'utf8');
 
+        // Dual-write to unified metrics
+        recordMetric('pr.analyzed', {
+            url: data.url,
+            number: data.number,
+            repo: data.repo,
+            preset: data.preset,
+            verdict: data.verdict,
+            totalIssues: data.totalIssues,
+            commentsPosted: data.commentsPosted,
+            commentsSkipped: data.commentsSkipped
+        }).catch((err) => {
+            logger.debug('pr-statistics - recordPRAnalysis', 'Metrics write failed', err);
+        });
+
         logger.debug('pr-statistics - recordPRAnalysis', 'Statistics recorded', {
             statsFile,
             totalIssues: data.totalIssues

package/lib/utils/remote-config.js

@@ -0,0 +1,102 @@
+/**
+ * File: remote-config.js
+ * Purpose: Generic fetcher for JSON config files from the centralized config repo
+ *
+ * Design:
+ * - Fetches JSON files from mscope-S-L/git-hooks-config via GitHub API
+ * - In-memory cache per process (Map<string, Object|null>) — stores null for failures (no retry)
+ * - Graceful degradation: any error → warn + return null (callers decide fallback)
+ * - No schema validation (callers validate their own shape)
+ * - Debug logging at every step
+ */
+
+import logger from './logger.js';
+import { fetchFileContent } from './github-api.js';
+
+/** @type {string} Owner of the centralized config repository */
+export const CONFIG_REPO_OWNER = 'mscope-S-L';
+
+/** @type {string} Name of the centralized config repository */
+export const CONFIG_REPO_NAME = 'git-hooks-config';
+
+/**
+ * In-memory cache: fileName → parsed Object (or null on failure).
+ * Persists for the lifetime of the process — avoids repeated API calls.
+ * Null entries are cached intentionally: a failed fetch won't succeed on retry
+ * within the same CLI invocation.
+ * @type {Map<string, Object|null>}
+ */
+const _cache = new Map();
+
+/**
+ * Fetch and parse a JSON config file from the centralized config repo.
+ *
+ * @param {string} fileName - File path within the config repo (e.g. 'labels.json')
+ * @returns {Promise<Object|null>} Parsed JSON object, or null on any failure
+ */
+export async function fetchRemoteConfig(fileName) {
+    logger.debug('remote-config - fetchRemoteConfig', 'Request received', { fileName });
+
+    // Cache hit (includes cached nulls)
+    if (_cache.has(fileName)) {
+        const cached = _cache.get(fileName);
+        logger.debug('remote-config - fetchRemoteConfig', 'Cache hit', {
+            fileName,
+            hasValue: cached !== null
+        });
+        return cached;
+    }
+
+    // Fetch from GitHub
+    let content;
+    try {
+        content = await fetchFileContent(CONFIG_REPO_OWNER, CONFIG_REPO_NAME, fileName);
+    } catch (err) {
+        logger.warning(`Could not fetch remote config '${fileName}': ${err.message}`);
+        logger.debug('remote-config - fetchRemoteConfig', 'fetchFileContent threw', {
+            fileName,
+            error: err.message
+        });
+        _cache.set(fileName, null);
+        return null;
+    }
+
+    if (content === null || content === undefined) {
+        logger.warning(`Remote config '${fileName}' not found in ${CONFIG_REPO_OWNER}/${CONFIG_REPO_NAME}`);
+        logger.debug('remote-config - fetchRemoteConfig', 'fetchFileContent returned null', {
+            fileName
+        });
+        _cache.set(fileName, null);
+        return null;
+    }
+
+    // Parse JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    } catch (err) {
+        logger.warning(`Remote config '${fileName}' contains invalid JSON: ${err.message}`);
+        logger.debug('remote-config - fetchRemoteConfig', 'JSON.parse failed', {
+            fileName,
+            error: err.message,
+            contentPreview: String(content).substring(0, 100)
+        });
+        _cache.set(fileName, null);
+        return null;
+    }
+
+    logger.debug('remote-config - fetchRemoteConfig', 'Successfully fetched and parsed', {
+        fileName,
+        keys: Object.keys(parsed)
+    });
+
+    _cache.set(fileName, parsed);
+    return parsed;
+}
+
+/**
+ * Clear the in-memory cache. Test helper — not intended for production use.
+ */
+export function _clearCache() {
+    _cache.clear();
+}

package/lib/utils/reviewer-selector.js

@@ -0,0 +1,154 @@
+/**
+ * File: reviewer-selector.js
+ * Purpose: Team-based reviewer selection for Pull Requests
+ *
+ * Resolves team members via GitHub Teams API, excludes the PR author
+ * and excluded reviewers (from remote config.json + local config),
+ * and returns eligible reviewers. Falls back to config-based reviewers
+ * if team resolution fails.
+ *
+ * Exclusion sources (merged, deduplicated):
+ * 1. Remote: config.json → general.github.pr.excludeReviewers (all repos)
+ * 2. Remote: config.json → {repoFullName}.github.pr.excludeReviewers (repo-specific)
+ * 3. Local: config.github.pr.excludeReviewers (per-repo override)
+ * 4. PR author (always excluded)
+ *
+ * Merge priority: remote general < remote repo-specific < local overrides
+ *
+ * Design: teamSlug is an explicit parameter (default: 'automation').
+ * Future auto-detection (e.g. from repos.listTeams) can be plugged in
+ * by the caller without changing this module.
+ */
+
+import logger from './logger.js';
+import { listTeamMembers } from './github-api.js';
+import { fetchRemoteConfig } from './remote-config.js';
+
+/** Default team slug — single place to change when auto-detection is added */
+const DEFAULT_TEAM = 'automation';
+
+/**
+ * Build the merged exclusion set from remote config.json + local config.
+ *
+ * @param {string} repoFullName - Full repo name (e.g. 'mscope-S-L/git-hooks')
+ * @param {string[]} localExclude - Local excludeReviewers array from config
+ * @returns {Promise<Set<string>>} Set of usernames to exclude
+ */
+export async function _buildExclusionSet(repoFullName, localExclude = []) {
+    const excluded = new Set();
+
+    // Remote config: general + repo-specific
+    try {
+        const remoteConfig = await fetchRemoteConfig('config.json');
+        if (remoteConfig) {
+            const generalExclude =
+                remoteConfig.general?.github?.pr?.excludeReviewers || [];
+            const repoExclude =
+                remoteConfig[repoFullName]?.github?.pr?.excludeReviewers || [];
+
+            generalExclude.forEach((u) => excluded.add(u));
+            repoExclude.forEach((u) => excluded.add(u));
+
+            logger.debug('reviewer-selector - _buildExclusionSet', 'Remote exclusions loaded', {
+                generalCount: generalExclude.length,
+                repoSpecificCount: repoExclude.length,
+                repoFullName
+            });
+        }
+    } catch (err) {
+        logger.debug('reviewer-selector - _buildExclusionSet', 'Remote config fetch failed', {
+            error: err.message
+        });
+    }
+
+    // Local overrides (highest priority, additive)
+    localExclude.forEach((u) => excluded.add(u));
+
+    logger.debug('reviewer-selector - _buildExclusionSet', 'Final exclusion set', {
+        count: excluded.size,
+        users: [...excluded]
+    });
+
+    return excluded;
+}
+
+/**
+ * Select reviewers for a Pull Request from a GitHub team
+ *
+ * @param {Object} options
+ * @param {string} options.org - GitHub organization (e.g. 'mscope-S-L')
+ * @param {string} options.repoFullName - Full repo name (e.g. 'mscope-S-L/git-hooks')
+ * @param {string} [options.teamSlug='automation'] - Team slug to resolve members from
+ * @param {string} options.prAuthor - PR author login (excluded from selection)
+ * @param {string[]} [options.configReviewers=[]] - Fallback reviewers from config
+ * @param {string[]} [options.excludeReviewers=[]] - Local exclude list from config
+ * @returns {Promise<string[]>} Selected reviewer logins
+ */
+export async function selectReviewers({
+    org,
+    repoFullName,
+    teamSlug = DEFAULT_TEAM,
+    prAuthor,
+    configReviewers = [],
+    excludeReviewers = []
+}) {
+    logger.debug('reviewer-selector - selectReviewers', 'Starting reviewer selection', {
+        org,
+        repoFullName,
+        teamSlug,
+        prAuthor,
+        configReviewersCount: configReviewers.length,
+        localExcludeCount: excludeReviewers.length
+    });
+
+    // Build merged exclusion set (remote general + remote repo-specific + local)
+    const exclusionSet = await _buildExclusionSet(repoFullName, excludeReviewers);
+    // Always exclude the PR author
+    exclusionSet.add(prAuthor);
+
+    // Try team-based resolution
+    try {
+        const members = await listTeamMembers(org, teamSlug);
+        const eligible = members
+            .map((m) => m.login)
+            .filter((login) => !exclusionSet.has(login));
+
+        logger.debug('reviewer-selector - selectReviewers', 'Team members resolved', {
+            teamSlug,
+            totalMembers: members.length,
+            eligibleCount: eligible.length,
+            excludedCount: members.length - eligible.length
+        });
+
+        if (eligible.length > 0) {
+            logger.info(
+                `📋 Found ${eligible.length} reviewer(s) from team '${teamSlug}': ${eligible.join(', ')}`
+            );
+            return eligible;
+        }
+
+        logger.debug(
+            'reviewer-selector - selectReviewers',
+            'No eligible team members, falling back to config'
+        );
+    } catch (err) {
+        logger.warning(
+            `⚠️  Could not resolve team '${teamSlug}': ${err.message}. Falling back to config reviewers.`
+        );
+        logger.debug('reviewer-selector - selectReviewers', 'Team resolution failed', {
+            error: err.message,
+            teamSlug
+        });
+    }
+
+    // Fallback: config-based reviewers
+    const fallback = configReviewers.filter((r) => !exclusionSet.has(r));
+
+    if (fallback.length > 0) {
+        logger.info(`📋 Found ${fallback.length} reviewer(s) from config: ${fallback.join(', ')}`);
+    } else {
+        logger.info('📋 Found 0 reviewer(s): none');
+    }
+
+    return fallback;
+}