claude-git-hooks 2.61.2 → 2.67.3

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

@@ -0,0 +1,311 @@
+/**
+ * File: skill-registry/parser.js
+ * Purpose: Parse @mscope/automation-skills improvement-registry.md files into
+ *          a structured rule index that the pre-commit hook can run grep
+ *          patterns against.
+ *
+ * Why this exists: the mscope skill repo
+ * (https://github.com/mscope-S-L/automation-skills) maintains canonical
+ * antipattern catalogues (JBE-NNN for backend, UIK-NNN/STR-NNN/etc. for
+ * frontend). Each registry entry includes a `Verify:` grep command that
+ * detects the antipattern. We parse those entries here so the pre-commit
+ * hook can run them against staged files automatically — turning the
+ * skill from descriptive (lives in docs) into prescriptive (blocks bad
+ * commits with the documented rule ID + fix).
+ *
+ * Skill repo location resolution (in order):
+ *   1. CLAUDE_HOOKS_SKILL_REPO env var
+ *   2. AUTOMATION_SKILLS_REPO env var (matches the skill repo's own convention)
+ *   3. ~/.claude/skills/automation-standards/.installed-version → walks back
+ *      to find the source clone (when installed via `automation-skills install`)
+ *   4. Returns null — the caller decides whether to skip silently or warn
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+
+const SKILL_PATHS = [
+    {
+        key: 'backend',
+        relPath: 'skills/backend/automation-standards-backend/docs/improvement-registry.md',
+    },
+    {
+        key: 'frontend',
+        relPath: 'skills/frontend/automation-standards/docs/improvement-registry.md',
+    },
+];
+
+/**
+ * Single source of truth for file-extension → skill-scope mapping.
+ * Adding a new extension here propagates to every consumer (runner,
+ * feedback-writer, future modules). Avoids the duplicate-map drift the
+ * reviewer flagged on the v1 PR.
+ */
+export const SCOPE_BY_EXT = Object.freeze({
+    // Backend (Java + SQL — both owned by the backend skill)
+    '.java': 'backend',
+    '.sql': 'backend',
+    // Frontend (React / styling)
+    '.jsx': 'frontend',
+    '.tsx': 'frontend',
+    '.js': 'frontend',
+    '.ts': 'frontend',
+    '.css': 'frontend',
+    '.scss': 'frontend',
+});
+
+/**
+ * Resolve the skill repo root.
+ *
+ * Resolution order:
+ *   1. `CLAUDE_HOOKS_SKILL_REPO` env var (most explicit per-machine override).
+ *   2. `AUTOMATION_SKILLS_REPO` env var (matches the skill repo's own
+ *      CLI convention; lets a teammate set one variable for both repos).
+ *   3. Sibling of the working repo: if the hook is running on a commit in
+ *      e.g. `<parent>/mscope-gateway/`, check `<parent>/automation-skills/`.
+ *      This is the mscope canonical layout (all repos as siblings under one
+ *      parent, folder name matching the GitHub repo name) and requires no
+ *      env-var setup for teammates following convention.
+ *   4. Return null — silent skip in the hook. The skill is value-add,
+ *      not a hard dep of claude-git-hooks.
+ *
+ * No hardcoded absolute paths and no homedir-relative guesses (those
+ * leaked personal layouts and never matched on the canonical mscope
+ * `<parent>/mscope-*` setup — see PR #180 review comment 4).
+ *
+ * @param {string} [workingRepoRoot] - Absolute path of the repo whose
+ *   commit triggered the hook (passed from pre-commit.js).
+ * @returns {string|null} Absolute path of the skill repo, or null.
+ */
+export function resolveSkillRepoRoot(workingRepoRoot = null) {
+    const candidates = [
+        process.env.CLAUDE_HOOKS_SKILL_REPO,
+        process.env.AUTOMATION_SKILLS_REPO,
+    ].filter(Boolean);
+
+    for (const c of candidates) {
+        if (isSkillRepoRoot(c)) return c;
+    }
+
+    if (workingRepoRoot) {
+        const parent = dirname(workingRepoRoot);
+        const guess = join(parent, 'automation-skills');
+        if (isSkillRepoRoot(guess)) return guess;
+    }
+
+    return null;
+}
+
+function isSkillRepoRoot(dir) {
+    if (!dir) return false;
+    try {
+        const pkgPath = join(dir, 'package.json');
+        if (!existsSync(pkgPath)) return false;
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.name === '@mscope/automation-skills';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Load all rule entries from both registries. Returns:
+ *   [
+ *     { id: 'JBE-001', severity: 'high', symptom: '…',
+ *       fix: '…', verify: 'grep -rn …', scope: 'backend', skillRel: '…' },
+ *     …
+ *   ]
+ * If the skill repo isn't found, returns []. Caller can decide how to surface.
+ */
+export function loadRegistry(skillRepoRoot = null, workingRepoRoot = null) {
+    const root = skillRepoRoot || resolveSkillRepoRoot(workingRepoRoot);
+    if (!root) return { rules: [], skillRoot: null };
+
+    const rules = [];
+    for (const { key, relPath } of SKILL_PATHS) {
+        const fullPath = join(root, relPath);
+        if (!existsSync(fullPath)) continue;
+        const content = readFileSync(fullPath, 'utf8');
+        const parsed = parseRegistryMarkdown(content, key, relPath);
+        rules.push(...parsed);
+    }
+    return { rules, skillRoot: root };
+}
+
+/**
+ * Parse a single registry markdown file. Returns an array of rule objects.
+ * Each registry entry follows the shape:
+ *
+ *   ### <RULE-ID> — <title>
+ *   **Severity:** <emoji + label>
+ *   **Symptom:** <description or fenced code>
+ *   **Fix:** <description or fenced code>
+ *   **Verify:** <inline command, or fenced code with `grep -rn …`>
+ *   **Seen in:** …
+ *   **Established in:** …
+ *
+ *   ---
+ *
+ * The parser is lenient — missing fields default to null. Entries without a
+ * usable Verify command are still indexed (so other features can reference
+ * them by ID) but won't fire pre-commit alarms.
+ */
+export function parseRegistryMarkdown(content, scope, sourceRel) {
+    const sections = content.split(/^### /m).slice(1);
+    const out = [];
+    for (const sec of sections) {
+        const newlineIdx = sec.indexOf('\n');
+        const header = newlineIdx === -1 ? sec : sec.slice(0, newlineIdx);
+        const body = newlineIdx === -1 ? '' : sec.slice(newlineIdx + 1);
+        // Header: "<RULE-ID> — <title>" or "<RULE-ID>: <title>" or "<RULE-ID> - <title>"
+        const idMatch = header.match(/^([A-Z][A-Z0-9]{1,7}-\d{3})\s*[—:–-]\s*(.+?)\s*$/);
+        if (!idMatch) continue;
+        const id = idMatch[1];
+        const title = idMatch[2];
+
+        const fields = extractFields(body);
+        if (!fields) continue;
+
+        const verifies = parseVerifyField(fields.verify);
+
+        out.push({
+            id,
+            title,
+            severity: classifySeverity(fields.severity),
+            severityRaw: fields.severity || '',
+            symptom: fields.symptom || null,
+            fix: fields.fix || null,
+            verifies,
+            seenIn: fields.seenIn || null,
+            establishedIn: fields.establishedIn || null,
+            knownEdgeCases: fields.knownEdgeCases || null,
+            scope,
+            source: sourceRel,
+        });
+    }
+    return out;
+}
+
+/**
+ * Extract the standard fields (Severity / Symptom / Fix / Verify / Seen in
+ * / Established in / Known edge cases) from a registry-entry body.
+ *
+ * Each field can be a single line OR span multiple lines including fenced
+ * code blocks. We slice on `**FieldName:**` boundaries.
+ */
+function extractFields(body) {
+    const FIELD_ORDER = [
+        ['severity', /\*\*Severity:\*\*/i],
+        ['symptom', /\*\*Symptom:\*\*/i],
+        ['fix', /\*\*Fix:\*\*/i],
+        ['verify', /\*\*Verify:\*\*/i],
+        ['seenIn', /\*\*Seen in:\*\*/i],
+        ['establishedIn', /\*\*Established in:\*\*/i],
+        ['knownEdgeCases', /\*\*Known edge cases:\*\*/i],
+    ];
+
+    // Find each field's start position; the field value runs to the next
+    // field start (or to a `---` divider / end of body).
+    const found = [];
+    for (const [name, re] of FIELD_ORDER) {
+        const m = body.match(re);
+        if (m) found.push({ name, start: m.index, headerEnd: m.index + m[0].length });
+    }
+    if (found.length === 0) return null;
+    found.sort((a, b) => a.start - b.start);
+
+    const dividerIdx = body.search(/^---\s*$/m);
+    const out = {};
+    for (let i = 0; i < found.length; i++) {
+        const cur = found[i];
+        const next = found[i + 1];
+        const stopAt = next
+            ? next.start
+            : dividerIdx >= 0 && dividerIdx > cur.start
+                ? dividerIdx
+                : body.length;
+        out[cur.name] = body.slice(cur.headerEnd, stopAt).trim();
+    }
+    return out;
+}
+
+/**
+ * Extract one-or-more runnable grep/find commands from a Verify field value.
+ *
+ * Verify field shapes seen in the registry:
+ *   - Inline: `**Verify:** grep -rn "printStackTrace()" src/main/java/`
+ *   - Fenced bash:
+ *       ```bash
+ *       grep -l "ALTER TABLE" BBDD/*.sql | xargs grep -L "IF NOT EXISTS"
+ *       ```
+ *   - Prose ("manual review") — returns []
+ *
+ * Returns an array of { command, kind } where kind ∈ { 'grep', 'find', 'other' }.
+ * Multi-command (piped) verifies are kept as a single entry — the runner shells out.
+ */
+function parseVerifyField(raw) {
+    if (!raw) return [];
+    const out = [];
+
+    // Fenced code blocks first.
+    const fenceRe = /```(?:[a-z]*)?\n([\s\S]*?)\n```/g;
+    let m;
+    while ((m = fenceRe.exec(raw)) !== null) {
+        const block = m[1];
+        for (const line of block.split('\n')) {
+            const cmd = line.trim();
+            if (isRunnableCommand(cmd)) out.push(toRule(cmd));
+        }
+    }
+
+    // Inline backtick command (single-line `cmd`).
+    const inlineRe = /`([^`\n]+)`/g;
+    while ((m = inlineRe.exec(raw)) !== null) {
+        const cmd = m[1].trim();
+        if (isRunnableCommand(cmd)) out.push(toRule(cmd));
+    }
+
+    // Plain (no backticks) — a single line beginning with grep/find/rg.
+    if (out.length === 0) {
+        for (const line of raw.split('\n')) {
+            const t = line.trim().replace(/^[-*]\s*/, '');
+            if (isRunnableCommand(t)) out.push(toRule(t));
+        }
+    }
+
+    return dedupe(out);
+}
+
+function isRunnableCommand(s) {
+    if (!s) return false;
+    if (s.length < 5 || s.length > 800) return false;
+    return /^(grep|rg|find|git\s+grep)\b/.test(s);
+}
+
+function toRule(command) {
+    let kind = 'other';
+    if (/^grep\b/.test(command)) kind = 'grep';
+    else if (/^rg\b/.test(command)) kind = 'grep';
+    else if (/^find\b/.test(command)) kind = 'find';
+    else if (/^git\s+grep\b/.test(command)) kind = 'grep';
+    return { command, kind };
+}
+
+function dedupe(arr) {
+    const seen = new Set();
+    return arr.filter((x) => {
+        if (seen.has(x.command)) return false;
+        seen.add(x.command);
+        return true;
+    });
+}
+
+function classifySeverity(raw) {
+    if (!raw) return 'unknown';
+    const lower = raw.toLowerCase();
+    if (lower.includes('critical') || lower.includes('🔴')) return 'critical';
+    if (lower.includes('high') || lower.includes('🟠')) return 'high';
+    if (lower.includes('medium') || lower.includes('🟡')) return 'medium';
+    if (lower.includes('low') || lower.includes('🟢')) return 'low';
+    return 'unknown';
+}

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

@@ -0,0 +1,81 @@
+/**
+ * File: skill-registry/resume.js
+ * Purpose: Lessons-learned handover — invokes `automation-skills resume`
+ *          so the developer can record what they learned on the branch to
+ *          the mscope skill repo's implementation-history.md.
+ *
+ * Invoked from create-pr (knowledge-capture step, alongside gotcha
+ * solicitation) at the natural "branch done, about to publish" moment.
+ * The mscope `automation-skills resume` command analyses
+ * `git log <trunk>..HEAD`, prompts interactively for lessons, and appends
+ * them to the skill repo. We hand over stdio so the prompt works.
+ *
+ * Branch preconditions (feature branch, commits ahead of trunk) are
+ * guaranteed by the create-pr context, so no git validation happens here.
+ *
+ * Never throws and never blocks the caller's flow — the integration is
+ * value-add, not a hard dependency. The CLI not being installed is a
+ * silent skip (callers can check isResumeCliAvailable() first to decide
+ * whether to announce the handover).
+ */
+
+import { spawnSync } from 'child_process';
+import logger from '../logger.js';
+
+/** Process-lifetime cache of the CLI availability probe. */
+let _cliAvailable = null;
+
+/**
+ * Test hook — clears the memoized CLI availability. Not for production use.
+ */
+export function _resetCliAvailabilityCache() {
+    _cliAvailable = null;
+}
+
+/**
+ * Probe whether the `automation-skills` CLI is reachable on PATH (memoized
+ * for the process lifetime — one spawn per run). Lets callers announce the
+ * interactive handover only when it will actually happen.
+ *
+ * @returns {boolean}
+ */
+export function isResumeCliAvailable() {
+    if (_cliAvailable !== null) return _cliAvailable;
+    const res = spawnSync('automation-skills', ['--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    _cliAvailable = !res.error && res.status === 0;
+    return _cliAvailable;
+}
+
+/**
+ * Hand control to `automation-skills resume [skill] [--trunk <branch>]`
+ * with inherited stdio (interactive prompt).
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot - Working repo root (cwd for the subcommand).
+ * @param {string|null} options.skill - Optional skill hint (frontend|backend|fe|be).
+ * @param {string|null} options.trunk - Optional trunk override passed through.
+ * @returns {{ ran: boolean, reason?: string, exitCode?: number }}
+ */
+export function runResumeFlow({ repoRoot, skill = null, trunk = null } = {}) {
+    if (!isResumeCliAvailable()) {
+        logger.debug('skill-registry - runResumeFlow', 'automation-skills CLI not on PATH — skipping lessons capture');
+        return { ran: false, reason: 'cli-missing' };
+    }
+
+    const resumeArgs = ['resume'];
+    if (skill) resumeArgs.push(skill);
+    if (trunk) resumeArgs.push('--trunk', trunk);
+
+    const proc = spawnSync('automation-skills', resumeArgs, {
+        stdio: 'inherit',
+        cwd: repoRoot,
+    });
+
+    if (proc.error) {
+        logger.debug('skill-registry - runResumeFlow', 'resume spawn failed', { error: proc.error.message });
+        return { ran: false, reason: 'spawn-error' };
+    }
+    return { ran: true, exitCode: proc.status ?? 0 };
+}

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

@@ -0,0 +1,265 @@
+/**
+ * File: skill-registry/runner.js
+ * Purpose: Run the parsed skill-registry's Verify patterns against a set of
+ *          staged files. Returns structured findings the pre-commit hook
+ *          can surface alongside (or instead of) AI analysis.
+ *
+ * Design:
+ *   - Inputs: array of rules from parser.js + array of staged absolute file paths.
+ *   - For each staged file:
+ *       1. Read its content.
+ *       2. Pick the rules whose scope matches the file's language (backend
+ *          rules for .java, frontend for .jsx/.tsx/.js/.css, SQL rules for
+ *          .sql — eventually; for now we map by scope tag).
+ *       3. For each rule with an extractable regex from its Verify command,
+ *          search the file and emit findings with line numbers.
+ *   - Returns: { totalFindings, byFile: { path → [findings] }, bySeverity: {…} }
+ *
+ * NOT done here:
+ *   - File-level greps (e.g. "files that DON'T contain X" / inverted verifies):
+ *     those need a different model (whole-repo audit, not pre-commit).
+ *   - Cross-file dependencies (verifies that pipe through xargs).
+ *   - The deny-list / allow-list around which rules block vs warn — caller
+ *     decides via the severity field on each rule.
+ */
+
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+import { SCOPE_BY_EXT } from './parser.js';
+
+/**
+ * Run all applicable rules against a set of staged files.
+ * @param {Array<object>} rules - From parser.loadRegistry().rules
+ * @param {Array<string>} stagedAbsPaths - Absolute file paths
+ * @param {object} [options]
+ * @param {string} [options.repoRoot] - For displaying relative paths in output
+ * @returns {{ totalFindings: number, findings: Array, byFile: object, bySeverity: object }}
+ */
+export function runRules(rules, stagedAbsPaths, options = {}) {
+    const repoRoot = options.repoRoot || '';
+    const findings = [];
+
+    // Precompile each rule's matchers once.
+    const compiled = compileRules(rules);
+
+    for (const absPath of stagedAbsPaths) {
+        const ext = extname(absPath).toLowerCase();
+        const scope = SCOPE_BY_EXT[ext];
+        if (!scope) continue;
+
+        // Skip binary / very large files defensively.
+        let content;
+        try {
+            content = readFileSync(absPath, 'utf8');
+            if (content.length > 1_000_000) continue; // 1MB cap
+        } catch {
+            continue;
+        }
+
+        const applicable = compiled.filter((r) => r.scope === scope);
+        if (applicable.length === 0) continue;
+
+        const lines = content.split('\n');
+        for (const rule of applicable) {
+            for (const matcher of rule.matchers) {
+                // Try matching each line; collect line numbers.
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    if (matcher.exclude && matcher.exclude.test(line)) continue;
+                    if (matcher.regex.test(line)) {
+                        // Reset lastIndex for global regexes; we only need the first hit per line.
+                        matcher.regex.lastIndex = 0;
+                        findings.push({
+                            ruleId: rule.id,
+                            severity: rule.severity,
+                            title: rule.title,
+                            scope: rule.scope,
+                            file: repoRoot ? relativizePath(absPath, repoRoot) : absPath,
+                            absPath,
+                            line: i + 1,
+                            lineText: line.trim().slice(0, 200),
+                            // Lightweight pointer back to the registry entry for the UI.
+                            registryRef: `${rule.scope}/improvement-registry.md → ${rule.id}`,
+                        });
+                    } else {
+                        matcher.regex.lastIndex = 0;
+                    }
+                }
+            }
+        }
+    }
+
+    return summarize(findings);
+}
+
+/**
+ * Convert each rule's verify commands into JS RegExp matchers we can run
+ * line-by-line. Rules where the verify can't be extracted are skipped (they
+ * remain in the registry for other features like `lookup`).
+ */
+function compileRules(rules) {
+    const out = [];
+    for (const rule of rules) {
+        const matchers = [];
+        for (const v of rule.verifies) {
+            const m = extractMatcher(v.command);
+            if (m) matchers.push(m);
+        }
+        if (matchers.length > 0) {
+            out.push({
+                id: rule.id,
+                severity: rule.severity,
+                title: rule.title,
+                scope: rule.scope,
+                matchers,
+            });
+        }
+    }
+    return out;
+}
+
+/**
+ * Extract a regex + optional exclude regex from a Verify grep command.
+ *
+ * Supported shapes (covers ~50 of the 95 current registry entries):
+ *   grep -rn "PATTERN" path
+ *   grep -rEn "REGEX" path
+ *   grep -rn "PATTERN" path --include=*.ext
+ *   grep -rn "PATTERN" path | grep -v "EXCLUDE"
+ *   grep -rEn "REGEX1" path | grep -E "REGEX2"          (we treat the pipe as AND)
+ *   rg "PATTERN" path
+ *
+ * Returns { regex, exclude } or null if the command doesn't fit the supported shapes.
+ */
+function extractMatcher(command) {
+    if (!command) return null;
+
+    // Strip quoted strings before checking for shell control characters —
+    // a literal `;` inside the grep regex (e.g. `^import .*\.\*;`) must
+    // not trip our reject heuristic.
+    const outsideQuotes = command
+        .replace(/"[^"]*"/g, '"_"')
+        .replace(/'[^']*'/g, "'_'");
+
+    if (/xargs/.test(outsideQuotes)) return null;
+    // Shell control outside quotes (||, &&, ;, $(), backticks for command sub) → file-level / audit-style.
+    if (/\|\||&&|;|\$\(|`/.test(outsideQuotes)) return null;
+    if (/\s\|\s/.test(outsideQuotes) && !/\|\s+grep/.test(outsideQuotes)) return null;
+
+    // Split on the (optional) `| grep` pipe. We support: first grep matches,
+    // pipe-through grep further filters (positive or `-v` excludes).
+    const segments = command.split(/\s\|\s/).map((s) => s.trim());
+    const primary = segments[0];
+
+    const tokens = tokenizeGrepInvocation(primary);
+    if (!tokens) return null;
+
+    // Reject FILE-LEVEL grep modes (list filenames only) — those are
+    // whole-repo audits, not line-level pre-commit checks.
+    // -l → list matching filenames only
+    // -L → list NON-matching filenames only (inverted file presence)
+    // We accept `-ln`/`-rln`/`-Ln` because `n` is line numbers (still file-level).
+    if (tokens.flags.includes('l') || tokens.flags.includes('L')) return null;
+
+    const isExtended = tokens.flags.includes('E');
+    let pattern;
+    try {
+        pattern = isExtended ? tokens.pattern : escapeForRegex(tokens.pattern);
+    } catch {
+        return null;
+    }
+
+    let regex;
+    try {
+        regex = new RegExp(pattern);
+    } catch {
+        return null;
+    }
+
+    // Optional exclude from a `| grep -v "X"` follow-up.
+    let exclude = null;
+    for (const seg of segments.slice(1)) {
+        const t = tokenizeGrepInvocation(seg);
+        if (!t) continue;
+        if (t.flags.includes('v')) {
+            try {
+                const excPat = t.flags.includes('E') ? t.pattern : escapeForRegex(t.pattern);
+                exclude = new RegExp(excPat);
+            } catch {
+                /* leave exclude null */
+            }
+        }
+        // Non-inverted secondary grep == narrowing AND. We could AND it with
+        // primary but in practice the registry uses this for file-list filtering
+        // (e.g. JBE-004 piping into `grep -A 1`), which is whole-file context
+        // not single-line. Conservative: skip.
+    }
+
+    return { regex, exclude };
+}
+
+/**
+ * Tokenize a single `grep ...` invocation into { flags, pattern, paths }.
+ *
+ * The pattern is the FIRST positional argument after the flags.
+ * Patterns may be quoted with " or ' or backticks; flags can be combined or split.
+ *
+ * Returns null if we can't recognise the shape (in which case the rule's
+ * verify just doesn't fire — silently skipped).
+ */
+function tokenizeGrepInvocation(s) {
+    const trimmed = s.trim();
+    // Must start with grep / rg / git grep
+    let rest;
+    if (/^grep\s/.test(trimmed)) rest = trimmed.slice(5).trim();
+    else if (/^rg\s/.test(trimmed)) rest = trimmed.slice(3).trim();
+    else if (/^git\s+grep\s/.test(trimmed)) rest = trimmed.replace(/^git\s+grep\s/, '').trim();
+    else return null;
+
+    const flags = [];
+    while (rest.startsWith('-')) {
+        // Stop at '--' (separator)
+        if (rest.startsWith('-- ')) {
+            rest = rest.slice(3).trim();
+            break;
+        }
+        const m = rest.match(/^-(-?)([A-Za-z]+)(=(\S+))?\s*/);
+        if (!m) break;
+        const isLong = m[1] === '-';
+        if (isLong) {
+            flags.push(m[2]);
+        } else {
+            for (const ch of m[2]) flags.push(ch);
+        }
+        rest = rest.slice(m[0].length);
+    }
+
+    // First positional: the pattern. Strip surrounding quotes if any.
+    const patMatch = rest.match(/^("([^"]*)"|'([^']*)'|(\S+))/);
+    if (!patMatch) return null;
+    const pattern = patMatch[2] ?? patMatch[3] ?? patMatch[4];
+
+    return { flags, pattern };
+}
+
+function escapeForRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function relativizePath(abs, root) {
+    const r = root.replace(/[\\/]+$/, '');
+    if (abs.startsWith(r)) {
+        return abs.slice(r.length + 1).replace(/\\/g, '/');
+    }
+    return abs.replace(/\\/g, '/');
+}
+
+function summarize(findings) {
+    const byFile = {};
+    const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+    for (const f of findings) {
+        (byFile[f.file] ||= []).push(f);
+        bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+    }
+    return { totalFindings: findings.length, findings, byFile, bySeverity };
+}