claude-git-hooks 2.66.1 → 2.67.3

package/lib/utils/skill-registry/feedback-writer.js

@@ -0,0 +1,196 @@
+/**
+ * File: skill-registry/feedback-writer.js
+ * Purpose: Option E (bidirectional feedback loop) — take the AI analysis
+ *          findings AFTER Claude returns them and, for each finding the
+ *          AI couldn't classify against the catalogue, append a candidate
+ *          [skill-gap] entry to the appropriate skill's skill-feedback.md.
+ *
+ * How it works (depends on Option E2's catalogue injection in prompt-builder):
+ *   - Claude's analysis prompt now contains the rule catalogue.
+ *   - For each finding, Claude populates `details[].rule` with the matching
+ *     JBE-NNN / UIK-NNN ID — or leaves it empty if nothing matched.
+ *   - We treat empty `rule` as "AI saw something real but couldn't tag it"
+ *     — i.e. the registry has a gap. Those are valuable signal for the
+ *     `automation-skills retro` loop.
+ *
+ * Per the maintainer's `feedback_skill_improvements_user_approval` rule,
+ * we never auto-merge into improvement-registry.md or promote candidates
+ * to rules. We write them to skill-feedback.md as candidates only; the
+ * user reviews and approves via `automation-skills retro` later.
+ *
+ * Dedup: we skip writing if an entry with the same (scope, file, message-hash)
+ * already exists in skill-feedback.md. Prevents the same recurring AI
+ * finding from spamming the doc on every commit.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, extname } from 'path';
+import { createHash } from 'crypto';
+import { SCOPE_BY_EXT } from './parser.js';
+
+const SKILL_PATHS = {
+    backend: 'skills/backend/automation-standards-backend/docs/skill-feedback.md',
+    frontend: 'skills/frontend/automation-standards/docs/skill-feedback.md',
+};
+
+/**
+ * Process the AI's analysis details, write skill-gap candidates as needed.
+ *
+ * @param {object} aiResult - The `result` returned by analysis-engine.runAnalysis
+ *                            (shape: { issues, details: [{file, line, message, severity, rule, type}], ... })
+ * @param {object} context - { skillRoot, branch, repoName }
+ * @returns {{ written: number, skippedDuplicate: number, skippedClassified: number,
+ *             candidatesByScope: { backend?: Array, frontend?: Array } }}
+ */
+export function writeSkillGapCandidates(aiResult, context) {
+    const { skillRoot, branch, repoName } = context;
+    if (!skillRoot) return emptyResult();
+    if (!aiResult || !Array.isArray(aiResult.details)) return emptyResult();
+
+    // Bucket unclassified details by scope.
+    const byScope = { backend: [], frontend: [] };
+    for (const d of aiResult.details) {
+        if (d.rule && /^[A-Z]+-\d{3}$/.test(d.rule)) continue; // already classified
+        if (!d.file || !d.message) continue;                   // can't dedup without these
+        const ext = extname(String(d.file)).toLowerCase();
+        const scope = SCOPE_BY_EXT[ext];
+        if (!scope) continue;                                  // unknown scope, ignore
+        byScope[scope].push(d);
+    }
+
+    const date = today();
+    let written = 0;
+    let skippedDuplicate = 0;
+    let skippedClassified = 0;
+    const candidatesByScope = {};
+
+    // Count classified for the stats output.
+    for (const d of aiResult.details) {
+        if (d.rule && /^[A-Z]+-\d{3}$/.test(d.rule)) skippedClassified++;
+    }
+
+    for (const scope of ['backend', 'frontend']) {
+        const candidates = byScope[scope];
+        if (candidates.length === 0) continue;
+
+        const filePath = join(skillRoot, SKILL_PATHS[scope]);
+        if (!existsSync(filePath)) continue;
+
+        const existing = readFileSync(filePath, 'utf8');
+        const existingHashes = extractExistingHashes(existing);
+
+        const toWrite = [];
+        for (const detail of candidates) {
+            const fp = fingerprint(scope, detail);
+            if (existingHashes.has(fp)) {
+                skippedDuplicate++;
+                continue;
+            }
+            toWrite.push({ detail, fingerprint: fp });
+        }
+
+        if (toWrite.length === 0) continue;
+
+        const entry = composeEntry({
+            date, scope, repoName, branch, candidates: toWrite,
+        });
+
+        appendToFeedback(filePath, entry);
+        written += toWrite.length;
+        candidatesByScope[scope] = toWrite.map((x) => x.detail);
+    }
+
+    return { written, skippedDuplicate, skippedClassified, candidatesByScope };
+}
+
+/**
+ * Fingerprint a detail so repeat reports on the same file/message don't
+ * pile up entries across commits. (scope, file, hash(message-normalised))
+ */
+function fingerprint(scope, detail) {
+    const msg = String(detail.message || '').toLowerCase().replace(/\s+/g, ' ').trim();
+    const file = String(detail.file || '').replace(/\\/g, '/');
+    const hash = createHash('sha1').update(msg).digest('hex').slice(0, 12);
+    return `${scope}::${file}::${hash}`;
+}
+
+/**
+ * Walk the existing skill-feedback.md and collect fingerprints of entries
+ * already present (we embed the fingerprint as an HTML comment so the
+ * dedup is durable even after the file is hand-edited).
+ */
+function extractExistingHashes(content) {
+    const set = new Set();
+    const re = /<!--\s*skill-gap-fp:\s*([^\s>]+)\s*-->/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        set.add(m[1]);
+    }
+    return set;
+}
+
+/**
+ * Compose a single dated entry covering N candidates from the same scope
+ * + branch + commit. Each candidate becomes one bullet.
+ */
+function composeEntry({ date, scope, repoName, branch, candidates }) {
+    const title = '[skill-gap candidates from claude-git-hooks AI analysis]';
+    const ctx = [
+        repoName ? `**Repo:** ${repoName}` : null,
+        branch ? `**Branch:** ${branch}` : null,
+    ].filter(Boolean).join('\n');
+
+    const bullets = candidates.map(({ detail, fingerprint: fp }) => {
+        const file = String(detail.file).replace(/\\/g, '/');
+        const line = detail.line ? `:${detail.line}` : '';
+        const sev = detail.severity ? ` (${detail.severity})` : '';
+        const type = detail.type ? ` [${detail.type}]` : '';
+        const msg = String(detail.message).replace(/\n/g, ' ').slice(0, 300);
+        return `- **[skill-gap]** ${file}${line}${type}${sev} — ${msg} <!-- skill-gap-fp: ${fp} -->`;
+    }).join('\n');
+
+    return `### ${date} — ${title} (${scope})
+
+${ctx}
+
+**Source:** Claude AI analysis flagged these findings, but none matched a JBE/UIK rule in the catalogue. They're recorded here for review during the next \`automation-skills retro\`. If a recurring pattern emerges, file a new registry entry.
+
+**Candidates:**
+
+${bullets}
+
+`;
+}
+
+/**
+ * Append the entry to skill-feedback.md, after the "How to recognize a
+ * skill-caused issue" section and any existing dated entries, but before
+ * "How this compounds" (the footer).
+ */
+function appendToFeedback(filePath, entry) {
+    let content = readFileSync(filePath, 'utf8');
+
+    // Replace the placeholder "(none yet — …)" line if present; otherwise
+    // insert before "## How this compounds".
+    const placeholder = /_\(none yet — the first entry will be appended below\.\)_\n/;
+    if (placeholder.test(content)) {
+        content = content.replace(placeholder, `${entry.trimEnd()  }\n`);
+    } else {
+        const footer = '## How this compounds';
+        const idx = content.indexOf(footer);
+        if (idx === -1) {
+            content = `${content.trimEnd()  }\n\n${  entry}`;
+        } else {
+            content = `${content.slice(0, idx).trimEnd()  }\n\n${  entry  }---\n\n${  content.slice(idx)}`;
+        }
+    }
+    writeFileSync(filePath, content, 'utf8');
+}
+
+function emptyResult() {
+    return { written: 0, skippedDuplicate: 0, skippedClassified: 0, candidatesByScope: {} };
+}
+
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}

package/lib/utils/skill-registry/index.js

@@ -0,0 +1,254 @@
+/**
+ * File: skill-registry/index.js
+ * Purpose: Public API (facade) for the mscope automation-skills integration.
+ *
+ * Integration entry points — consumers should only need these three:
+ *   - runSkillChecks(...)      — freshness + registry load + line-level checks
+ *                                + display + blockOn gating decision.
+ *   - getCatalogueSection(...) — rendered rule catalogue for the analysis
+ *                                prompt (memoized registry load).
+ *   - recordSkillGaps(...)     — append unclassified AI findings to the
+ *                                skill repo's skill-feedback.md.
+ *
+ * Lower-level building blocks remain exported for tests and advanced use:
+ *   - loadRegistry()        — parse the JBE/UIK rule catalogue.
+ *   - runRules(...)         — line-level pre-commit checks against staged files.
+ *   - displayFindings(...)  — formatted console output.
+ *   - checkFreshness()      — non-blocking call to `automation-skills check`.
+ *
+ * Designed so the pre-commit hook can do:
+ *
+ *     import * as skill from '../utils/skill-registry/index.js';
+ *     const check = skill.runSkillChecks(stagedAbsPaths, { repoRoot, config });
+ *     if (check.shouldBlock) process.exit(1);   // exit stays in the hook
+ *
+ * Failure mode is always "silent skip" — if the skill repo isn't found, or
+ * the registry is malformed, the hook continues without these checks. The
+ * mscope skill is a value-add, not a hard dependency of this repo.
+ *
+ * No function in this module calls process.exit() — utils return decisions,
+ * the CLI/hook layer acts on them (repo convention).
+ */
+
+export { resolveSkillRepoRoot, loadRegistry, SCOPE_BY_EXT } from './parser.js';
+export { runRules } from './runner.js';
+
+import { spawnSync } from 'child_process';
+import { loadRegistry } from './parser.js';
+import { runRules } from './runner.js';
+import { renderCatalogue } from './catalogue.js';
+import { writeSkillGapCandidates } from './feedback-writer.js';
+import logger from '../logger.js';
+
+/**
+ * Severity rank used by the blockOn gate. Lower = more severe.
+ * 'never' (or any unknown value) disables gating.
+ */
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
+
+/**
+ * Process-lifetime cache of registry loads, keyed by the workingRepoRoot
+ * used for resolution. Lets runSkillChecks and getCatalogueSection share
+ * a single filesystem pass per commit.
+ */
+const registryCache = new Map();
+
+function loadRegistryCached(workingRepoRoot) {
+    const key = workingRepoRoot || '';
+    if (!registryCache.has(key)) {
+        registryCache.set(key, loadRegistry(null, workingRepoRoot));
+    }
+    return registryCache.get(key);
+}
+
+/**
+ * Test hook — clears the memoized registry. Not for production use.
+ */
+export function _resetRegistryCache() {
+    registryCache.clear();
+}
+
+/**
+ * One-call integration point for the pre-commit hook: freshness warning,
+ * registry load (memoized), rule run, console display, and the blockOn
+ * gating decision.
+ *
+ * Never calls process.exit — returns `shouldBlock` and lets the hook decide.
+ * Throws only on unexpected internal errors (callers wrap in try/catch).
+ *
+ * @param {string[]} absPaths - Absolute paths of staged files to check.
+ * @param {object} options
+ * @param {string} options.repoRoot - Working repo root (for sibling resolution + relative display).
+ * @param {object} options.config - Merged config; reads config.skillRegistry.blockOn.
+ * @returns {{ skillRoot: string|null, rules: Array, findings: Array,
+ *             totalFindings: number, shouldBlock: boolean, triggeringCount: number }}
+ */
+export function runSkillChecks(absPaths, { repoRoot, config } = {}) {
+    const freshness = checkFreshness();
+    if (freshness.status === 'stale') {
+        logger.warning(`📚 mscope skill is behind: installed v${freshness.installed}, latest v${freshness.latest}. Run: automation-skills update`);
+    }
+
+    const { rules, skillRoot } = loadRegistryCached(repoRoot);
+    if (!skillRoot || rules.length === 0) {
+        if (!skillRoot) {
+            logger.debug('skill-registry - runSkillChecks', 'Skill registry not found — skipping skill-driven checks');
+        }
+        return { skillRoot, rules: rules || [], findings: [], totalFindings: 0, shouldBlock: false, triggeringCount: 0 };
+    }
+
+    const result = runRules(rules, absPaths, { repoRoot });
+    displayFindings(result);
+
+    // Optional gating: blockOn = 'critical' | 'high' | 'medium' | 'low' | 'never'
+    // (default: 'never' — warn-only for incremental adoption).
+    const blockOn = config?.skillRegistry?.blockOn || 'never';
+    const threshold = SEVERITY_RANK[blockOn] ?? -1;
+    const triggering = threshold >= 0
+        ? result.findings.filter((f) => (SEVERITY_RANK[f.severity] ?? 99) <= threshold)
+        : [];
+
+    return {
+        skillRoot,
+        rules,
+        findings: result.findings,
+        totalFindings: result.totalFindings,
+        shouldBlock: triggering.length > 0,
+        triggeringCount: triggering.length,
+    };
+}
+
+/**
+ * Rendered `=== PLATFORM ANTIPATTERN CATALOGUE ===` body for injection into
+ * the Claude analysis prompt. Uses the memoized registry load, so calling
+ * this after runSkillChecks costs nothing.
+ *
+ * Never throws — the catalogue is value-add; on any failure returns null.
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot - Working repo root for sibling resolution.
+ * @returns {string|null} Markdown catalogue, or null if unavailable/empty.
+ */
+export function getCatalogueSection({ repoRoot } = {}) {
+    try {
+        const { rules, skillRoot } = loadRegistryCached(repoRoot);
+        if (!skillRoot || rules.length === 0) return null;
+        return renderCatalogue(rules) || null;
+    } catch (err) {
+        logger.debug('skill-registry - getCatalogueSection', 'Catalogue unavailable', { error: err?.message });
+        return null;
+    }
+}
+
+/**
+ * Append skill-gap candidates (AI findings with no catalogue rule ID) to the
+ * skill repo's skill-feedback.md. Thin wrapper over writeSkillGapCandidates;
+ * throws on write failure (caller decides how loud to be).
+ *
+ * @param {object} aiResult - Result from analysis-engine.runAnalysis.
+ * @param {object} context - { skillRoot, branch, repoName }
+ * @returns {{ written: number, skippedDuplicate: number, skippedClassified: number }}
+ */
+export function recordSkillGaps(aiResult, context) {
+    return writeSkillGapCandidates(aiResult, context);
+}
+
+/**
+ * Run `automation-skills check --json` to find out if the installed skill
+ * is behind the latest. Returns:
+ *   { status: 'fresh' | 'stale' | 'unknown', installed, latest }
+ *
+ * Never throws; never blocks the hook. If the CLI isn't installed or the
+ * check fails, returns { status: 'unknown' }.
+ */
+export function checkFreshness({ timeoutMs = 3000 } = {}) {
+    try {
+        const res = spawnSync('automation-skills', ['check', '--json'], {
+            timeout: timeoutMs,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (res.error || (res.status !== 0 && res.status !== 1)) {
+            return { status: 'unknown' };
+        }
+        const line = (res.stdout || '').toString().trim();
+        if (!line) return { status: 'unknown' };
+        const parsed = JSON.parse(line);
+        return {
+            status: parsed.status === 'stale' ? 'stale'
+                : parsed.status === 'fresh' ? 'fresh'
+                    : parsed.status === 'ahead' ? 'ahead'
+                        : 'unknown',
+            installed: parsed.installed,
+            latest: parsed.latest,
+        };
+    } catch {
+        return { status: 'unknown' };
+    }
+}
+
+/**
+ * Print a formatted summary of pre-commit findings (from runRules) to
+ * stdout. Returns nothing.
+ *
+ * Format intentionally mirrors the existing hook's `displayResults` style
+ * so it slots in naturally.
+ *
+ *   📚 mscope skill registry — 2 findings (1 high, 1 medium)
+ *
+ *     [JBE-016] medium  Wildcard import (`import x.*;`)
+ *       file.java:12   import jakarta.persistence.*;
+ *       → see automation-standards-backend/docs/improvement-registry.md#jbe-016
+ */
+export function displayFindings({ totalFindings, findings, bySeverity }) {
+    if (totalFindings === 0) {
+        logger.info('📚 mscope skill registry — no rule violations in staged files.');
+        return;
+    }
+
+    const sev = bySeverity || {};
+    const sevParts = [];
+    if (sev.critical) sevParts.push(`${sev.critical} 🔴 critical`);
+    if (sev.high)     sevParts.push(`${sev.high} 🟠 high`);
+    if (sev.medium)   sevParts.push(`${sev.medium} 🟡 medium`);
+    if (sev.low)      sevParts.push(`${sev.low} 🟢 low`);
+
+    logger.info(`📚 mscope skill registry — ${totalFindings} finding${totalFindings === 1 ? '' : 's'}${ 
+        sevParts.length ? ` (${sevParts.join(', ')})` : ''}`);
+    logger.info('');
+
+    // Group findings by rule for compact output.
+    const byRule = {};
+    for (const f of findings) {
+        (byRule[f.ruleId] ||= { rule: f, occurrences: [] }).occurrences.push(f);
+    }
+    const rulesSorted = Object.keys(byRule).sort((a, b) => {
+        // High severity first, then by rule id.
+        const order = { critical: 0, high: 1, medium: 2, low: 3, unknown: 4 };
+        const sa = order[byRule[a].rule.severity] ?? 99;
+        const sb = order[byRule[b].rule.severity] ?? 99;
+        if (sa !== sb) return sa - sb;
+        return a.localeCompare(b);
+    });
+
+    for (const ruleId of rulesSorted) {
+        const { rule, occurrences } = byRule[ruleId];
+        const sevTag = sevTagFor(rule.severity);
+        logger.info(`  [${ruleId}] ${sevTag} ${rule.title}`);
+        for (const occ of occurrences.slice(0, 5)) {
+            logger.info(`    ${occ.file}:${occ.line}   ${occ.lineText.slice(0, 100)}`);
+        }
+        if (occurrences.length > 5) {
+            logger.info(`    … and ${occurrences.length - 5} more occurrence${occurrences.length - 5 === 1 ? '' : 's'}`);
+        }
+        logger.info(`    → see ${rule.scope}/improvement-registry.md → ${ruleId}`);
+        logger.info('');
+    }
+}
+
+function sevTagFor(sev) {
+    if (sev === 'critical') return '🔴 critical';
+    if (sev === 'high') return '🟠 high';
+    if (sev === 'medium') return '🟡 medium';
+    if (sev === 'low') return '🟢 low';
+    return `⚪ ${  sev}`;
+}