code-auditor-mcp 4.1.1 → 5.0.2

package/dist/conventions/conventionMiner.js

@@ -74,7 +74,7 @@ const BUILT_IN_CALLEES = new Set([
 export function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/** Detect whether a string contains non-Latin-script characters (Spec 21 R5.4). */
+/** Detect whether a string contains non-Latin-script characters (Spec 21 R5.4). @param name The string to inspect. @returns True when the string contains non-Latin-script characters. */
 export function hasNonLatinChars(name) {
     // Latin script covers Basic Latin (U+0000–U+007F), Latin-1 Supplement
     // (U+0080–U+00FF), and Latin Extended-A/B (U+0100–U+024F). Allow digits,
@@ -99,7 +99,9 @@ export function hasNonLatinChars(name) {
     return false;
 }
 /** Classify a symbol name into a casing convention. Returns null for
- *  non-Latin, unclassifiable, or ambiguous names. */
+ *  non-Latin, unclassifiable, or ambiguous names.
+ *  @param name The symbol name to classify.
+ *  @returns The casing convention name, or null when unclassifiable. */
 export function detectCase(name) {
     if (!name || name.length === 0)
         return null;
@@ -128,6 +130,8 @@ export function detectCase(name) {
  * Handles: import default, import named, import namespace, import side-effect,
  * require default, require destructured.
  * Multi-line imports supported via {}-accumulation.
+ * @param content The raw file content.
+ * @returns The parsed import statements.
  */
 export function parseFileImports(content) {
     const results = [];
@@ -236,6 +240,9 @@ export function parseFileImports(content) {
 /**
  * Parse the export form for a specific exported function from AST-extracted
  * export data. Returns null if the function isn't found in the export list.
+ * @param functionName The function name to look up.
+ * @param exports The AST-extracted export list.
+ * @returns The export form, or null when the function is not in the list.
  */
 export function detectExportForm(functionName, exports) {
     const match = exports.find(e => e.name === functionName);
@@ -289,6 +296,8 @@ function _detectExportFormFromSource(filePath, functionName, sourceCode) {
  * A string/comment containing `try {` or `if (err)` no longer registers, and a
  * body that mixes two shapes is no longer collapsed to whichever the regex
  * happened to see first.
+ * @param body The function body source (may be null/undefined).
+ * @returns The detected error-handling shape, or null when none is present.
  */
 export function detectErrorHandlingShape(body) {
     if (!body)
@@ -409,8 +418,8 @@ function isErrorPresenceCheck(n) {
 function computeHash(inputs) {
     return crypto.createHash('md5').update(JSON.stringify(inputs)).digest('hex');
 }
-/** Cap the number of conventions per domain. */
-function capPerDomain(conventions, max) {
+/** Cap the number of conventions per domain. @param conventions The conventions to cap. @param max The per-domain maximum. @returns The capped conventions. */
+export function capPerDomain(conventions, max) {
     const byDomain = new Map();
     for (const c of conventions) {
         const list = byDomain.get(c.domain) ?? [];
@@ -433,98 +442,71 @@ function capPerDomain(conventions, max) {
  * and support ≥ minCorpus.
  */
 function mineUsagePairs(db, config) {
-    const conventions = [];
-    // Build per-function call sets
-    const rows = db
-        .prepare(`SELECT f.id, f.name as func_name, f.file_path, f.line_number,
-              f.metadata_json
-       FROM functions f`)
+    const funcs = db
+        .prepare(`SELECT id, name, file_path, line_number FROM functions`)
         .all();
-    // callerId -> Set<calleeName>
-    const callSets = new Map();
-    const callRows = db
+    const calls = db
         .prepare(`SELECT caller_id, callee_name FROM function_calls`)
         .all();
-    for (const cr of callRows) {
-        if (!callSets.has(cr.caller_id))
-            callSets.set(cr.caller_id, new Set());
-        callSets.get(cr.caller_id).add(cr.callee_name);
-    }
-    // Build a set of project-defined function names (antecedents must be
-    // resolvable in the function index — Spec 22 R5.2).
-    const projectSymbols = new Set();
-    for (const r of rows) {
-        projectSymbols.add(r.func_name);
-    }
-    // For each unique callee (potential antecedent), find all callers
-    // antecedentName -> Set<callerId>
-    const antecedentCallers = new Map();
-    for (const cr of callRows) {
-        if (!antecedentCallers.has(cr.callee_name))
-            antecedentCallers.set(cr.callee_name, new Set());
-        antecedentCallers.get(cr.callee_name).add(cr.caller_id);
-    }
-    // For each antecedent A, among A-callers, compute co-occurring calls X.
-    // Skip built-in/stdlib and non-project antecedents (Spec 22 R5.2).
-    for (const [antecedent, callerIds] of antecedentCallers) {
-        // Antecedent must be project-defined and not a built-in
-        if (BUILT_IN_CALLEES.has(antecedent) || !projectSymbols.has(antecedent))
-            continue;
-        const total = callerIds.size;
-        if (total < config.minCorpus)
+    return mineUsagePairsFromFacts(funcs, calls, config);
+}
+/**
+ * The pure import-form miner — byte-identical logic to the legacy `mineImportForm`
+ * DB miner, over a per-file import projection.
+ *
+ * The legacy miner read `SELECT DISTINCT file_path FROM functions` (files that
+ * *have indexed functions*), parsed each file's source with `parseFileImports`,
+ * and reduced the `(source, directory)` histogram to a dominant-form convention.
+ * This pure miner drives off the same distinct file set (the caller derives it
+ * from the `function-index` fact, preserving first-appearance order) and reads
+ * each file's imports from the projection — so a file with imports but no
+ * indexed functions contributes nothing on either path.
+ * @param files The distinct file paths to mine.
+ * @param getImports Callback returning a file's parsed imports.
+ * @param config The convention mining config.
+ * @returns The mined import-form conventions.
+ */
+export function mineImportFormFromFacts(files, getImports, config) {
+    const conventions = [];
+    // (source, directory) -> Map<form, count>
+    const formCounts = new Map();
+    // (source, directory) -> exemplar
+    const exemplars = new Map();
+    for (const file of files) {
+        const imports = getImports(file);
+        if (!imports)
             continue;
-        // Count how many A-callers also call each other function.
-        // Skip built-in consequents — co-occurrence of universal methods is
-        // arithmetic, not convention (Spec 22 R5.2).
-        const coOccurCounts = new Map();
-        for (const cid of callerIds) {
-            const callSet = callSets.get(cid);
-            if (!callSet)
-                continue;
-            for (const callee of callSet) {
-                if (callee === antecedent)
-                    continue;
-                if (BUILT_IN_CALLEES.has(callee))
-                    continue;
-                coOccurCounts.set(callee, (coOccurCounts.get(callee) ?? 0) + 1);
-            }
-        }
-        for (const [consequent, support] of coOccurCounts) {
-            const confidence = support / total;
-            if (confidence >= config.pairConfidence && support >= config.minCorpus) {
-                // Find an exemplar: a function that calls both A and X
-                let exemplarFile = null;
-                let exemplarLine = null;
-                for (const cid of callerIds) {
-                    const cs = callSets.get(cid);
-                    if (cs && cs.has(consequent)) {
-                        const funcRow = rows.find((r) => r.id === cid);
-                        if (funcRow) {
-                            exemplarFile = funcRow.file_path;
-                            exemplarLine = funcRow.line_number;
-                            break;
-                        }
-                    }
-                }
-                conventions.push({
-                    domain: 'usage-pair',
-                    rule_id: 'conventions/usage-pair',
-                    antecedent,
-                    consequent,
-                    pattern: null,
-                    directory: null,
-                    file_path: null,
-                    line: null,
-                    support,
-                    total_cases: total,
-                    confidence: Math.round(confidence * 10000) / 10000,
-                    exemplar_file: exemplarFile,
-                    exemplar_line: exemplarLine,
-                    hash: computeHash([antecedent, consequent, support, total]),
-                });
+        const directory = path.dirname(file) || '.';
+        for (const imp of imports) {
+            const source = imp.source;
+            const form = imp.form;
+            const key = `${source}::${directory}`;
+            if (!formCounts.has(key))
+                formCounts.set(key, new Map());
+            const fc = formCounts.get(key);
+            fc.set(form, (fc.get(form) ?? 0) + 1);
+            // Track exemplar (first one wins; line 0 mirrors the legacy miner)
+            if (!exemplars.has(key)) {
+                exemplars.set(key, { file, line: 0, form });
             }
         }
     }
+    // For each (source, directory) pair, find dominant form
+    for (const [key, fc] of formCounts) {
+        const [source, directory] = key.split('::');
+        const mode = summarizeModes(fc, config);
+        if (!mode)
+            continue;
+        pushModeConvention(conventions, mode, {
+            domain: 'import-form',
+            antecedent: source,
+            consequent: mode.dominant,
+            pattern: minorityLabel(fc, mode.dominant) || null,
+            directory,
+            exemplar: exemplars.get(key),
+            hash: computeHash([source, directory, mode.dominant, mode.maxCount, mode.total]),
+        });
+    }
     return conventions;
 }
 /**
@@ -532,27 +514,25 @@ function mineUsagePairs(db, config) {
  *
  * Per (source, directory) pair, compute the dominant import form. Reads source
  * files from disk to parse import statements, since import form data is not
- * persisted in the functions table.
+ * persisted in the functions table. Thin wrapper over
+ * {@link mineImportFormFromFacts} — it reads the same distinct-file set the pure
+ * miner drives off, parses each source with `parseFileImports`, and projects to
+ * the `{source, form, line}` shape the pure miner consumes.
  */
 function mineImportForm(db, config, projectRoot, getSource) {
-    const conventions = [];
-    // Get unique (file_path, directory) pairs
+    // Get unique file paths (the directory is derived from the path, not queried —
+    // `path.dirname(file) || '.'` is equivalent to the old `dir_part` discriminator).
     const rows = db
-        .prepare(`SELECT DISTINCT file_path,
-              substr(file_path, 1, length(file_path) - length(replace(file_path, '/', '')) - 1) as dir_part
-       FROM functions
-       WHERE file_path IS NOT NULL`)
+        .prepare(`SELECT DISTINCT file_path FROM functions WHERE file_path IS NOT NULL`)
         .all();
-    // Deduplicate files
+    const files = [];
+    const importsByFile = new Map();
     const seen = new Set();
-    // (source, directory) -> Map<form, count>
-    const formCounts = new Map();
-    // (source, directory) -> exemplar
-    const exemplars = new Map();
     for (const row of rows) {
         if (seen.has(row.file_path))
             continue;
         seen.add(row.file_path);
+        files.push(row.file_path);
         const fullPath = projectRoot && !path.isAbsolute(row.file_path)
             ? path.join(projectRoot, row.file_path)
             : row.file_path;
@@ -569,64 +549,9 @@ function mineImportForm(db, config, projectRoot, getSource) {
                 continue;
             }
         }
-        const directory = row.dir_part ? path.dirname(row.file_path) : '.';
-        const imports = parseFileImports(content);
-        for (const imp of imports) {
-            const source = imp.source;
-            const form = imp.form;
-            const key = `${source}::${directory}`;
-            if (!formCounts.has(key))
-                formCounts.set(key, new Map());
-            const fc = formCounts.get(key);
-            fc.set(form, (fc.get(form) ?? 0) + 1);
-            // Track exemplar (first one wins)
-            if (!exemplars.has(key)) {
-                exemplars.set(key, { file: row.file_path, line: 0, form });
-            }
-        }
-    }
-    // For each (source, directory) pair, find dominant form
-    for (const [key, fc] of formCounts) {
-        const [source, directory] = key.split('::');
-        const total = [...fc.values()].reduce((s, c) => s + c, 0);
-        if (total < config.minCorpus)
-            continue;
-        // Find the mode (most common form)
-        let maxCount = 0;
-        let dominantForm = '';
-        for (const [form, count] of fc) {
-            if (count > maxCount) {
-                maxCount = count;
-                dominantForm = form;
-            }
-        }
-        const modeShare = maxCount / total;
-        if (modeShare >= config.modeShare && maxCount >= config.minCorpus) {
-            // List the minority forms (for reference)
-            const minorityForms = [...fc.entries()]
-                .filter(([f]) => f !== dominantForm)
-                .map(([f, c]) => `${f}:${c}`)
-                .join(',');
-            const exemplar = exemplars.get(key);
-            conventions.push({
-                domain: 'import-form',
-                rule_id: 'conventions/import-form',
-                antecedent: source,
-                consequent: dominantForm,
-                pattern: minorityForms || null,
-                directory,
-                file_path: null,
-                line: null,
-                support: maxCount,
-                total_cases: total,
-                confidence: Math.round(modeShare * 10000) / 10000,
-                exemplar_file: exemplar?.file ?? null,
-                exemplar_line: exemplar?.line ?? null,
-                hash: computeHash([source, directory, dominantForm, maxCount, total]),
-            });
-        }
+        importsByFile.set(row.file_path, parseFileImports(content).map((imp) => ({ source: imp.source, form: imp.form, line: imp.line })));
     }
-    return conventions;
+    return mineImportFormFromFacts(files, (fp) => importsByFile.get(fp), config);
 }
 /**
  * Mine `error-handling` conventions.
@@ -636,73 +561,133 @@ function mineImportForm(db, config, projectRoot, getSource) {
  * excluded from the corpus and never flagged as deviants.
  */
 function mineErrorHandling(db, config) {
-    const conventions = [];
-    const rows = db
+    const funcs = db
         .prepare(`SELECT id, name, file_path, line_number, body
        FROM functions
        WHERE body IS NOT NULL`)
         .all();
-    // directory -> Map<shape, count>
-    const dirShapes = new Map();
-    // directory -> exemplar info
-    const dirExemplars = new Map();
-    for (const row of rows) {
-        const body = row.body ?? undefined;
-        const shape = detectErrorHandlingShape(body);
-        if (!shape)
-            continue; // no error handling → skip
-        const directory = path.dirname(row.file_path) || '.';
-        if (!dirShapes.has(directory))
-            dirShapes.set(directory, new Map());
-        const shapes = dirShapes.get(directory);
-        shapes.set(shape, (shapes.get(shape) ?? 0) + 1);
-        if (!dirExemplars.has(directory)) {
-            dirExemplars.set(directory, {
-                file: row.file_path,
-                line: row.line_number,
-                shape,
-            });
+    return mineErrorHandlingFromFacts(funcs, config);
+}
+/**
+ * Join a group's non-dominant forms into a `form:count,form:count` label. The
+ * import-form, export-shape, and error-handling miners all reduce a
+ * `Map<form, count>` to its dominant form plus a minority reference label; this
+ * is the shared label computation.
+ */
+function minorityLabel(counts, dominant) {
+    return [...counts.entries()]
+        .filter(([f]) => f !== dominant)
+        .map(([f, c]) => `${f}:${c}`)
+        .join(',');
+}
+/**
+ * Reduce a group's `Map<form, count>` to its dominant form, or null when the
+ * group is below the corpus minimum or the dominant form does not clear the
+ * mode-share gate. Shared by the import-form, export-shape, and error-handling
+ * miners so the total/dominant/mode-share math lives once.
+ */
+function summarizeModes(counts, config) {
+    const total = [...counts.values()].reduce((s, c) => s + c, 0);
+    if (total < config.minCorpus)
+        return null;
+    let maxCount = 0;
+    let dominant = '';
+    for (const [form, count] of counts) {
+        if (count > maxCount) {
+            maxCount = count;
+            dominant = form;
         }
     }
-    for (const [directory, shapes] of dirShapes) {
-        const total = [...shapes.values()].reduce((s, c) => s + c, 0);
-        if (total < config.minCorpus)
+    const modeShare = maxCount / total;
+    if (modeShare < config.modeShare || maxCount < config.minCorpus)
+        return null;
+    return { dominant, maxCount, total };
+}
+/**
+ * Push one dominant-form convention onto `conventions`. The import-form,
+ * export-shape, and error-handling miners each reduce a group's histogram to a
+ * dominant form and emit a single `Convention` whose `file_path`/`line` are
+ * always null, `confidence` is the mode share rounded to 4 decimals, and the
+ * exemplar anchors are null-coalesced — so that tail lives here once and the
+ * three miners pass only their domain-specific fields.
+ */
+function pushModeConvention(conventions, mode, fields) {
+    conventions.push({
+        domain: fields.domain,
+        rule_id: `conventions/${fields.domain}`,
+        antecedent: fields.antecedent,
+        consequent: fields.consequent,
+        pattern: fields.pattern,
+        directory: fields.directory,
+        file_path: null,
+        line: null,
+        support: mode.maxCount,
+        total_cases: mode.total,
+        confidence: Math.round((mode.maxCount / mode.total) * 10000) / 10000,
+        exemplar_file: fields.exemplar?.file ?? null,
+        exemplar_line: fields.exemplar?.line ?? null,
+        hash: fields.hash,
+    });
+}
+/**
+ * Shared histogram → conventions tail for export-shape mining. `dirForms` is
+ * directory → Map<form, count> and `dirExemplars` directory → first-seen anchor;
+ * both the pure (`mineExportShapeFromFacts`) and DB (`mineExportShape`) miners
+ * build these maps and reduce them through this one function, so the dominant-
+ * form selection and confidence math can never drift between the two paths.
+ */
+function buildExportShapeConventions(dirForms, dirExemplars, config) {
+    const conventions = [];
+    for (const [directory, forms] of dirForms) {
+        const mode = summarizeModes(forms, config);
+        if (!mode)
             continue;
-        let maxCount = 0;
-        let dominantShape = '';
-        for (const [shape, count] of shapes) {
-            if (count > maxCount) {
-                maxCount = count;
-                dominantShape = shape;
-            }
-        }
-        const modeShare = maxCount / total;
-        if (modeShare >= config.modeShare && maxCount >= config.minCorpus) {
-            const minorityShapes = [...shapes.entries()]
-                .filter(([s]) => s !== dominantShape)
-                .map(([s, c]) => `${s}:${c}`)
-                .join(',');
-            const exemplar = dirExemplars.get(directory);
-            conventions.push({
-                domain: 'error-handling',
-                rule_id: 'conventions/error-handling',
-                antecedent: null,
-                consequent: null,
-                pattern: dominantShape,
-                directory,
-                file_path: null,
-                line: null,
-                support: maxCount,
-                total_cases: total,
-                confidence: Math.round(modeShare * 10000) / 10000,
-                exemplar_file: exemplar?.file ?? null,
-                exemplar_line: exemplar?.line ?? null,
-                hash: computeHash([directory, dominantShape, maxCount, total]),
-            });
-        }
+        pushModeConvention(conventions, mode, {
+            domain: 'export-shape',
+            antecedent: null,
+            consequent: null,
+            pattern: mode.dominant,
+            directory,
+            exemplar: dirExemplars.get(directory),
+            hash: computeHash([directory, mode.dominant, mode.maxCount, mode.total]),
+        });
     }
     return conventions;
 }
+/**
+ * Mine `export-shape` conventions from facts — the pure, AST-served path the
+ * phase model runs (`function-index` + `export-form` facts). `getExportForm`
+ * resolves a file's exported `(name, isDefault)` pairs from the `export-form`
+ * fact, which is the AST-extracted exports set (`extractExports`) the legacy
+ * reducer read as `exportsMap`. No source fallback: the phase model always has
+ * the export-form fact, so an absent file simply contributes no row.
+ * @param funcs The function-index rows to mine.
+ * @param config The convention mining config.
+ * @param getExportForm Callback resolving a file's exported (name, isDefault) pairs.
+ * @returns The mined export-shape conventions.
+ */
+export function mineExportShapeFromFacts(funcs, config, getExportForm) {
+    const dirForms = new Map();
+    const dirExemplars = new Map();
+    for (const row of funcs) {
+        const fileExports = getExportForm?.(row.file_path);
+        if (!fileExports)
+            continue;
+        const match = fileExports.find((e) => e.name === row.name);
+        if (!match)
+            continue;
+        const form = match.isDefault ? 'default' : 'named';
+        const directory = path.dirname(row.file_path) || '.';
+        if (!dirForms.has(directory))
+            dirForms.set(directory, new Map());
+        const forms = dirForms.get(directory);
+        forms.set(form, (forms.get(form) ?? 0) + 1);
+        if (!dirExemplars.has(directory)) {
+            dirExemplars.set(directory, { file: row.file_path, line: row.line_number, form });
+        }
+    }
+    return buildExportShapeConventions(dirForms, dirExemplars, config);
+}
 /**
  * Mine `export-shape` conventions.
  *
@@ -711,7 +696,6 @@ function mineErrorHandling(db, config) {
  * form, since it is not stored in the functions table metadata.
  */
 function mineExportShape(db, config, projectRoot, getSource, getExports) {
-    const conventions = [];
     const rows = db
         .prepare(`SELECT id, name, file_path, line_number
        FROM functions
@@ -762,44 +746,7 @@ function mineExportShape(db, config, projectRoot, getSource, getExports) {
             });
         }
     }
-    for (const [directory, forms] of dirForms) {
-        const total = [...forms.values()].reduce((s, c) => s + c, 0);
-        if (total < config.minCorpus)
-            continue;
-        let maxCount = 0;
-        let dominantForm = '';
-        for (const [form, count] of forms) {
-            if (count > maxCount) {
-                maxCount = count;
-                dominantForm = form;
-            }
-        }
-        const modeShare = maxCount / total;
-        if (modeShare >= config.modeShare && maxCount >= config.minCorpus) {
-            const minorityForms = [...forms.entries()]
-                .filter(([f]) => f !== dominantForm)
-                .map(([f, c]) => `${f}:${c}`)
-                .join(',');
-            const exemplar = dirExemplars.get(directory);
-            conventions.push({
-                domain: 'export-shape',
-                rule_id: 'conventions/export-shape',
-                antecedent: null,
-                consequent: null,
-                pattern: dominantForm,
-                directory,
-                file_path: null,
-                line: null,
-                support: maxCount,
-                total_cases: total,
-                confidence: Math.round(modeShare * 10000) / 10000,
-                exemplar_file: exemplar?.file ?? null,
-                exemplar_line: exemplar?.line ?? null,
-                hash: computeHash([directory, dominantForm, maxCount, total]),
-            });
-        }
-    }
-    return conventions;
+    return buildExportShapeConventions(dirForms, dirExemplars, config);
 }
 /**
  * Classify a function into its export kind for naming-convention partitioning.
@@ -832,15 +779,133 @@ function classifyExportKind(row) {
  * minCorpus populations produce nothing.
  */
 function mineNaming(db, config) {
-    const conventions = [];
-    const rows = db
+    const funcs = db
         .prepare(`SELECT id, name, file_path, line_number, entity_type, component_type
        FROM functions
        WHERE is_exported = 1`)
         .all();
+    return mineNamingFromFacts(funcs, config);
+}
+/** The pure usage-pair miner — byte-identical logic to `mineUsagePairs`, over rows. @param funcs The function rows. @param calls The caller→callee call rows. @param config The convention mining config. @returns The mined usage-pair conventions. */
+export function mineUsagePairsFromFacts(funcs, calls, config) {
+    const conventions = [];
+    const callSets = new Map();
+    for (const cr of calls) {
+        if (!callSets.has(cr.caller_id))
+            callSets.set(cr.caller_id, new Set());
+        callSets.get(cr.caller_id).add(cr.callee_name);
+    }
+    const projectSymbols = new Set();
+    for (const r of funcs) {
+        projectSymbols.add(r.name);
+    }
+    const antecedentCallers = new Map();
+    for (const cr of calls) {
+        if (!antecedentCallers.has(cr.callee_name))
+            antecedentCallers.set(cr.callee_name, new Set());
+        antecedentCallers.get(cr.callee_name).add(cr.caller_id);
+    }
+    for (const [antecedent, callerIds] of antecedentCallers) {
+        if (BUILT_IN_CALLEES.has(antecedent) || !projectSymbols.has(antecedent))
+            continue;
+        const total = callerIds.size;
+        if (total < config.minCorpus)
+            continue;
+        const coOccurCounts = new Map();
+        for (const cid of callerIds) {
+            const callSet = callSets.get(cid);
+            if (!callSet)
+                continue;
+            for (const callee of callSet) {
+                if (callee === antecedent)
+                    continue;
+                if (BUILT_IN_CALLEES.has(callee))
+                    continue;
+                coOccurCounts.set(callee, (coOccurCounts.get(callee) ?? 0) + 1);
+            }
+        }
+        for (const [consequent, support] of coOccurCounts) {
+            const confidence = support / total;
+            if (confidence >= config.pairConfidence && support >= config.minCorpus) {
+                let exemplarFile = null;
+                let exemplarLine = null;
+                for (const cid of callerIds) {
+                    const cs = callSets.get(cid);
+                    if (cs && cs.has(consequent)) {
+                        const funcRow = funcs.find((r) => r.id === cid);
+                        if (funcRow) {
+                            exemplarFile = funcRow.file_path;
+                            exemplarLine = funcRow.line_number;
+                            break;
+                        }
+                    }
+                }
+                conventions.push({
+                    domain: 'usage-pair',
+                    rule_id: 'conventions/usage-pair',
+                    antecedent,
+                    consequent,
+                    pattern: null,
+                    directory: null,
+                    file_path: null,
+                    line: null,
+                    support,
+                    total_cases: total,
+                    confidence: Math.round(confidence * 10000) / 10000,
+                    exemplar_file: exemplarFile,
+                    exemplar_line: exemplarLine,
+                    hash: computeHash([antecedent, consequent, support, total]),
+                });
+            }
+        }
+    }
+    return conventions;
+}
+/** The pure error-handling miner — byte-identical logic to `mineErrorHandling`. @param funcs The function rows carrying bodies. @param config The convention mining config. @returns The mined error-handling conventions. */
+export function mineErrorHandlingFromFacts(funcs, config) {
+    const conventions = [];
+    const dirShapes = new Map();
+    const dirExemplars = new Map();
+    for (const row of funcs) {
+        const body = row.body ?? undefined;
+        const shape = detectErrorHandlingShape(body);
+        if (!shape)
+            continue; // no error handling → skip
+        const directory = path.dirname(row.file_path) || '.';
+        if (!dirShapes.has(directory))
+            dirShapes.set(directory, new Map());
+        const shapes = dirShapes.get(directory);
+        shapes.set(shape, (shapes.get(shape) ?? 0) + 1);
+        if (!dirExemplars.has(directory)) {
+            dirExemplars.set(directory, {
+                file: row.file_path,
+                line: row.line_number,
+                shape,
+            });
+        }
+    }
+    for (const [directory, shapes] of dirShapes) {
+        const mode = summarizeModes(shapes, config);
+        if (!mode)
+            continue;
+        pushModeConvention(conventions, mode, {
+            domain: 'error-handling',
+            antecedent: null,
+            consequent: null,
+            pattern: mode.dominant,
+            directory,
+            exemplar: dirExemplars.get(directory),
+            hash: computeHash([directory, mode.dominant, mode.maxCount, mode.total]),
+        });
+    }
+    return conventions;
+}
+/** The pure naming miner — byte-identical logic to `mineNaming`. @param funcs The function rows to classify. @param config The convention mining config. @returns The mined naming conventions. */
+export function mineNamingFromFacts(funcs, config) {
+    const conventions = [];
     const dirKindCases = new Map();
     const dirKindExemplars = new Map();
-    for (const row of rows) {
+    for (const row of funcs) {
         const casing = detectCase(row.name);
         if (!casing)
             continue; // non-Latin or unclassifiable → skip
@@ -919,15 +984,23 @@ export const MINER_VERSION = 2;
  * Compute a content hash of the miner inputs for change detection.
  * Callers can store this in the meta table to skip re-mining when unchanged.
  * Includes MINER_VERSION so that algorithm changes force a re-mine.
+ * @param db The SQLite database to hash inputs from.
+ * @param config The convention mining config.
+ * @returns The computed input hash string.
  */
 export function computeMinerInputHash(db, config) {
     // Hash actual content — not just counts — so two corpora with identical
     // counts but different functions produce different hashes and are mined.
-    const rows = db.prepare('SELECT name, content_hash, COALESCE(body, \'\') as body, COALESCE(signature, \'\') as signature FROM functions ORDER BY name, content_hash').all();
+    // Read the body LENGTH via SQL, not the full body text: the hash only needs
+    // the length (content identity is already carried by `content_hash`), and
+    // loading the whole `body` column here would be an O(total-source) read on
+    // the single-file `changed` hook path — the same cost scoped-DRY introduced
+    // and the whole-table-read guard forbids.
+    const rows = db.prepare('SELECT name, content_hash, LENGTH(COALESCE(body, \'\')) as body_len FROM functions ORDER BY name, content_hash').all();
     const callRows = db.prepare('SELECT fc.callee_name FROM function_calls fc ORDER BY fc.callee_name').all();
     return computeHash([
         MINER_VERSION,
-        rows.map(r => [r.name, r.content_hash, r.signature.length, r.body.length]),
+        rows.map(r => [r.name, r.content_hash, r.body_len]),
         callRows.map(r => r.callee_name),
         config,
     ]);
@@ -939,6 +1012,8 @@ export function computeMinerInputHash(db, config) {
  * @param config       Threshold configuration for the miner.
  * @param projectRoot  Optional project root — required for import-form and
  *                     export-shape mining to resolve file paths.
+ * @param getSource    Optional callback to read a file's source (avoids disk reads).
+ * @param getExports   Optional callback for AST-based export-form detection.
  * @returns Array of mined conventions (uncapped — caller should upsert).
  */
 export function mineConventions(db, config, projectRoot, getSource, getExports) {