ghagga-core 2.8.0 → 2.9.0

package/dist/doc-validation/index.js

@@ -0,0 +1,9 @@
+/**
+ * Doc-Validation module barrel export.
+ *
+ * Bidirectional code-doc validation that detects stale
+ * documentation references when code symbols change.
+ */
+// ─── Scanner ──────────────────────────────────────────────────
+export { extractChangedSymbols, isDocFile, scanDocsForSymbols } from './scanner.js';
+//# sourceMappingURL=index.js.map

package/dist/doc-validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/doc-validation/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,iEAAiE;AAEjE,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/doc-validation/scanner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Doc-Validation Scanner
+ *
+ * Extracts changed symbol names from unified diffs and scans
+ * documentation files for references to those symbols.
+ *
+ * Pure functions with no side effects.
+ */
+import type { DiffFile } from '../utils/diff.js';
+import type { DocValidationResult } from './types.js';
+/**
+ * Extract changed symbol names from a unified diff string.
+ *
+ * Scans added lines (lines starting with `+`) for function, class,
+ * interface, and type declarations. Returns unique symbol names.
+ *
+ * @param diff - Full unified diff string
+ * @returns Array of unique changed symbol names (filtered by min length)
+ */
+export declare function extractChangedSymbols(diff: string): string[];
+/**
+ * Check if a file path is a documentation file based on extension.
+ */
+export declare function isDocFile(filePath: string): boolean;
+/**
+ * Scan documentation files for references to changed symbols.
+ *
+ * For each doc file, searches line-by-line for symbol references
+ * (backtick-wrapped or plain word boundaries). If the doc file
+ * was NOT in the changed files list, its references are flagged
+ * as stale.
+ *
+ * @param symbols - Changed symbol names to search for
+ * @param allFiles - All files from the diff (used to find doc content and check if updated)
+ * @param changedCodeFiles - Paths of files that were changed in the diff
+ * @param docContents - Optional map of doc file path → content (for docs NOT in the diff)
+ * @returns DocValidationResult with stale references
+ */
+export declare function scanDocsForSymbols(symbols: string[], allFiles: DiffFile[], changedCodeFiles: string[], docContents?: Map<string, string>): DocValidationResult;
+//# sourceMappingURL=scanner.d.ts.map

package/dist/doc-validation/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/doc-validation/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAwCpE;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB5D;AAID;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAInD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,QAAQ,EAAE,EACpB,gBAAgB,EAAE,MAAM,EAAE,EAC1B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,mBAAmB,CAyCrB"}

package/dist/doc-validation/scanner.js

@@ -0,0 +1,163 @@
+/**
+ * Doc-Validation Scanner
+ *
+ * Extracts changed symbol names from unified diffs and scans
+ * documentation files for references to those symbols.
+ *
+ * Pure functions with no side effects.
+ */
+// ─── Constants ────────────────────────────────────────────────
+/** Minimum symbol name length to avoid false positives on common words. */
+const MIN_SYMBOL_LENGTH = 3;
+/**
+ * Regex patterns to extract symbol declarations from diff added lines.
+ *
+ * Matches:
+ *   - `function name(` / `async function name(`
+ *   - `class Name` / `abstract class Name`
+ *   - `interface Name`
+ *   - `type Name`
+ *   - `export function name(`
+ *   - `def name(` (Python)
+ *   - `func name(` / `func (r *Receiver) name(` (Go)
+ */
+const SYMBOL_DECLARATION_PATTERNS = [
+    // TypeScript / JavaScript
+    /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*[(<]/,
+    /(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/,
+    /(?:export\s+)?interface\s+(\w+)/,
+    /(?:export\s+)?type\s+(\w+)\s*[=<{]/,
+    // Arrow function: const name = (...) =>
+    /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\(/,
+    // Python
+    /def\s+(\w+)\s*\(/,
+    /class\s+(\w+)\s*[:(]/,
+    // Go
+    /func\s+(\w+)\s*\(/,
+    /func\s+\([^)]+\)\s+(\w+)\s*\(/,
+];
+/** File extensions considered documentation. */
+const DOC_EXTENSIONS = new Set(['.md', '.mdx', '.rst', '.txt', '.adoc']);
+// ─── Symbol Extraction ───────────────────────────────────────
+/**
+ * Extract changed symbol names from a unified diff string.
+ *
+ * Scans added lines (lines starting with `+`) for function, class,
+ * interface, and type declarations. Returns unique symbol names.
+ *
+ * @param diff - Full unified diff string
+ * @returns Array of unique changed symbol names (filtered by min length)
+ */
+export function extractChangedSymbols(diff) {
+    const symbols = new Set();
+    const lines = diff.split('\n');
+    for (const line of lines) {
+        // Only scan added/modified lines (start with +, but not +++ header)
+        if (!line.startsWith('+') || line.startsWith('+++'))
+            continue;
+        const content = line.slice(1); // Remove the leading +
+        for (const pattern of SYMBOL_DECLARATION_PATTERNS) {
+            const match = pattern.exec(content);
+            if (match?.[1] && match[1].length >= MIN_SYMBOL_LENGTH) {
+                symbols.add(match[1]);
+            }
+        }
+    }
+    return [...symbols];
+}
+// ─── Doc Reference Scanning ──────────────────────────────────
+/**
+ * Check if a file path is a documentation file based on extension.
+ */
+export function isDocFile(filePath) {
+    const lastDot = filePath.lastIndexOf('.');
+    if (lastDot === -1)
+        return false;
+    return DOC_EXTENSIONS.has(filePath.slice(lastDot).toLowerCase());
+}
+/**
+ * Scan documentation files for references to changed symbols.
+ *
+ * For each doc file, searches line-by-line for symbol references
+ * (backtick-wrapped or plain word boundaries). If the doc file
+ * was NOT in the changed files list, its references are flagged
+ * as stale.
+ *
+ * @param symbols - Changed symbol names to search for
+ * @param allFiles - All files from the diff (used to find doc content and check if updated)
+ * @param changedCodeFiles - Paths of files that were changed in the diff
+ * @param docContents - Optional map of doc file path → content (for docs NOT in the diff)
+ * @returns DocValidationResult with stale references
+ */
+export function scanDocsForSymbols(symbols, allFiles, changedCodeFiles, docContents) {
+    if (symbols.length === 0) {
+        return { changedSymbols: [], staleReferences: [], docsScanned: 0 };
+    }
+    const changedSet = new Set(changedCodeFiles);
+    const staleReferences = [];
+    let docsScanned = 0;
+    // Build regex for all symbols (word boundary match)
+    const symbolPatterns = symbols.map((s) => ({
+        symbol: s,
+        regex: new RegExp(`(?:\`${escapeRegex(s)}(?:\\(\\))?\`|\\b${escapeRegex(s)}\\b)`, 'g'),
+    }));
+    // Scan doc files from the diff
+    for (const file of allFiles) {
+        if (!isDocFile(file.path))
+            continue;
+        docsScanned++;
+        // If doc is in the diff (was updated), skip — it's not stale
+        if (changedSet.has(file.path))
+            continue;
+        // This doc was NOT changed — scan for symbol references
+        scanContent(file.path, file.content, symbolPatterns, staleReferences);
+    }
+    // Scan external doc contents (docs not in the diff at all)
+    if (docContents) {
+        for (const [filePath, content] of docContents) {
+            if (!isDocFile(filePath))
+                continue;
+            docsScanned++;
+            scanContent(filePath, content, symbolPatterns, staleReferences);
+        }
+    }
+    return {
+        changedSymbols: symbols,
+        staleReferences,
+        docsScanned,
+    };
+}
+// ─── Helpers ─────────────────────────────────────────────────
+/**
+ * Scan a single document's content for symbol references.
+ */
+function scanContent(filePath, content, symbolPatterns, results) {
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Skip diff header lines
+        if (line.startsWith('diff --git') || line.startsWith('---') || line.startsWith('+++')) {
+            continue;
+        }
+        // Strip diff markers for content matching
+        const cleanLine = line.startsWith('+') || line.startsWith('-') ? line.slice(1) : line;
+        for (const { symbol, regex } of symbolPatterns) {
+            regex.lastIndex = 0; // Reset regex state
+            if (regex.test(cleanLine)) {
+                results.push({
+                    file: filePath,
+                    line: i + 1,
+                    symbol,
+                    context: cleanLine.trim().slice(0, 120),
+                });
+            }
+        }
+    }
+}
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=scanner.js.map

package/dist/doc-validation/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../../src/doc-validation/scanner.ts"],"names":[],"mappings":"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"}

package/dist/doc-validation/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Doc-Validation Types
+ *
+ * Types for the bidirectional code-doc validation module.
+ * Detects stale documentation references when code symbols change.
+ */
+/** A reference to a code symbol found in a documentation file. */
+export interface DocReference {
+    /** Path to the documentation file */
+    file: string;
+    /** 1-based line number where the reference was found */
+    line: number;
+    /** The matched symbol name */
+    symbol: string;
+    /** Surrounding text snippet for context */
+    context: string;
+}
+/** Result of the code-doc validation step. */
+export interface DocValidationResult {
+    /** Symbol names extracted from the diff as changed */
+    changedSymbols: string[];
+    /** Doc references to changed symbols where the doc was NOT updated */
+    staleReferences: DocReference[];
+    /** Number of documentation files scanned */
+    docsScanned: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/doc-validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/doc-validation/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IAEb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IAEf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,sEAAsE;IACtE,eAAe,EAAE,YAAY,EAAE,CAAC;IAEhC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/doc-validation/types.js

@@ -0,0 +1,8 @@
+/**
+ * Doc-Validation Types
+ *
+ * Types for the bidirectional code-doc validation module.
+ * Detects stale documentation references when code symbols change.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/doc-validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/doc-validation/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/embed.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Embedding abstraction layer for GHAGGA intelligence features.
+ *
+ * Provides the shared EmbeddingProvider interface used by:
+ *   - Feature #4: Hybrid search (BM25 + semantic vector search)
+ *   - Feature #12: Semantic ranking of findings
+ *   - Feature #13: Negative example filtering
+ */
+export interface EmbeddingProvider {
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    dimension: number;
+}
+export type EmbeddingProviderFactory = () => EmbeddingProvider | null;
+/**
+ * Cosine similarity between two vectors of equal length.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Serialize a float32 embedding vector to a Buffer for SQLite BLOB storage.
+ */
+export declare function serializeEmbedding(vec: number[]): Buffer;
+/**
+ * Deserialize a Buffer from SQLite BLOB back to a float32 embedding vector.
+ */
+export declare function deserializeEmbedding(buf: Buffer): number[];
+//# sourceMappingURL=embed.d.ts.map

package/dist/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAItE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAWjE;AAID;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAMxD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAO1D"}

package/dist/embed.js

@@ -0,0 +1,47 @@
+/**
+ * Embedding abstraction layer for GHAGGA intelligence features.
+ *
+ * Provides the shared EmbeddingProvider interface used by:
+ *   - Feature #4: Hybrid search (BM25 + semantic vector search)
+ *   - Feature #12: Semantic ranking of findings
+ *   - Feature #13: Negative example filtering
+ */
+// ─── Vector Math ───────────────────────────────────────────────
+/**
+ * Cosine similarity between two vectors of equal length.
+ */
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ─── SQLite Serialization ──────────────────────────────────────
+/**
+ * Serialize a float32 embedding vector to a Buffer for SQLite BLOB storage.
+ */
+export function serializeEmbedding(vec) {
+    const buf = Buffer.allocUnsafe(vec.length * 4);
+    for (let i = 0; i < vec.length; i++) {
+        buf.writeFloatLE(vec[i], i * 4);
+    }
+    return buf;
+}
+/**
+ * Deserialize a Buffer from SQLite BLOB back to a float32 embedding vector.
+ */
+export function deserializeEmbedding(buf) {
+    const len = buf.length / 4;
+    const vec = new Array(len);
+    for (let i = 0; i < len; i++) {
+        vec[i] = buf.readFloatLE(i * 4);
+    }
+    return vec;
+}
+//# sourceMappingURL=embed.js.map

package/dist/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,kEAAkE;AAElE;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACrB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACvB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACzB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,CAAC;AACvC,CAAC;AAED,kEAAkE;AAElE;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAa;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAa,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/enhance/enhance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enhance.d.ts","sourceRoot":"","sources":["../../src/enhance/enhance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,0DAA0D;AAC1D,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAAC,CAuE/D;AA+BD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,EAAE,aAAa,GAC3B,qBAAqB,EAAE,CAmCzB"}
+{"version":3,"file":"enhance.d.ts","sourceRoot":"","sources":["../../src/enhance/enhance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,0DAA0D;AAC1D,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAAC,CAkD/D;AA+BD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,EAAE,aAAa,GAC3B,qBAAqB,EAAE,CAmCzB"}

package/dist/enhance/enhance.js

@@ -4,8 +4,7 @@
  * Calls an LLM to group, prioritize, and filter static analysis findings.
  * Failures are non-blocking — returns empty result on any error.
  */
-import { createModel } from '../providers/index.js';
-import { generateTextWithTimeout } from '../utils/llm-timeout.js';
+import { createOllamaGenerateFn } from '../providers/ollama.js';
 import { buildEnhancePrompt, ENHANCE_SYSTEM_PROMPT, truncateByTokenBudget } from './prompt.js';
 /** Default token budget for the enhance prompt (4K tokens). */
 const DEFAULT_TOKEN_BUDGET = 4000;
@@ -39,35 +38,18 @@ export async function enhanceFindings(input) {
         // Truncate to fit token budget
         const truncated = truncateByTokenBudget(input.findings, DEFAULT_TOKEN_BUDGET);
         const prompt = buildEnhancePrompt(truncated);
-        // Call LLM
-        const model = createModel(input.provider, input.model, input.apiKey);
-        const response = await generateTextWithTimeout({
-            model,
-            system: ENHANCE_SYSTEM_PROMPT,
-            prompt,
-            maxOutputTokens: 2000,
-        }, { provider: input.provider, model: input.model });
-        // Timeout: return empty result (enhance is already non-blocking)
-        if (response === null) {
-            return {
-                result: EMPTY_RESULT,
-                metadata: {
-                    model: input.model,
-                    tokenUsage: { input: 0, output: 0 },
-                    groupCount: 0,
-                    filteredCount: 0,
-                },
-            };
-        }
+        // Use injected generateFn if provided, otherwise fall back to Ollama
+        const generateFn = input.generateFn ?? createOllamaGenerateFn(input.model);
+        const response = await generateFn(ENHANCE_SYSTEM_PROMPT, prompt);
         // Parse response
         const parsed = parseEnhanceResponse(response.text);
         return {
             result: parsed,
             metadata: {
-                model: input.model,
+                model: response.model,
                 tokenUsage: {
-                    input: response.usage?.inputTokens ?? 0,
-                    output: response.usage?.outputTokens ?? 0,
+                    input: response.tokensUsed,
+                    output: 0,
                 },
                 groupCount: parsed.groups.length,
                 filteredCount: parsed.filtered.length,

package/dist/enhance/enhance.js.map

@@ -1 +1 @@
-{"version":3,"file":"enhance.js","sourceRoot":"","sources":["../../src/enhance/enhance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"enhance.js","sourceRoot":"","sources":["../../src/enhance/enhance.ts"],"names":[],"mappings":"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"}

package/dist/enhance/types.d.ts

@@ -9,6 +9,11 @@ export interface EnhanceInput {
     provider: string;
     model: string;
     apiKey: string;
+    /**
+     * Optional backend-agnostic generation function.
+     * When provided, used instead of creating one from provider/model/apiKey.
+     */
+    generateFn?: import('../providers/generate-fn.js').GenerateTextFn;
 }
 /** Compact finding representation for the AI prompt (token-efficient). */
 export interface EnhanceFindingSummary {

package/dist/enhance/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/enhance/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kDAAkD;IAClD,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/enhance/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC;CACnE;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,kDAAkD;IAClD,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/exploitability/analyzer.d.ts

@@ -72,4 +72,46 @@ export declare function checkReachability(graph: DependencyGraph, entryPoints: s
  * @returns The same findings array with exploitability fields added to CVE findings
  */
 export declare function analyzeExploitability(findings: ReviewFinding[], graph: DependencyGraph | null): ReviewFinding[];
+/**
+ * Callback to read a file's content by path.
+ * Returns null if the file cannot be read.
+ */
+export type FileReader = (filePath: string) => Promise<string | null>;
+/**
+ * Extract imported symbol names from file content for a given package.
+ *
+ * @param content - File source content
+ * @param packageName - External package to search for
+ * @returns Array of imported symbol names (deduplicated)
+ */
+export declare function extractImportedSymbols(content: string, packageName: string): string[];
+/**
+ * Detect which of the given symbols are actually called in file content.
+ *
+ * Uses regex to find function-call-like patterns: `symbol(`, `symbol.`, `symbol[`
+ * Excludes matches inside comments (single-line // and multi-line).
+ *
+ * @param content - File source content
+ * @param symbols - Symbol names to search for
+ * @returns Array of symbols that appear to be used (called/accessed)
+ */
+export declare function detectSymbolCalls(content: string, symbols: string[]): string[];
+/**
+ * Analyze function-level usage of vulnerable packages in CVE findings.
+ *
+ * For each Trivy CVE finding that has import sites (from exploitability analysis),
+ * reads the importing files, extracts the imported symbols, and checks if those
+ * symbols are actually called.
+ *
+ * Degrades gracefully:
+ * - No graph → skips analysis (no usageLabel set)
+ * - No import sites → labels as not-in-use
+ * - Namespace imports → labels as imported-not-called (can't determine specific usage)
+ *
+ * @param findings - Review findings (already enriched with exploitability)
+ * @param graph - The project's dependency graph (null if unavailable)
+ * @param readFile - Callback to read file content by path
+ * @returns The same findings array with usage fields added to CVE findings
+ */
+export declare function analyzeUsage(findings: ReviewFinding[], graph: DependencyGraph | null, readFile: FileReader): Promise<ReviewFinding[]>;
 //# sourceMappingURL=analyzer.d.ts.map

package/dist/exploitability/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/exploitability/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAgBjD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAyBpF;AAID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBzF;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAsBhE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,MAAM,EAAE,GACpB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA8CvB;AAoDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,aAAa,EAAE,EACzB,KAAK,EAAE,eAAe,GAAG,IAAI,GAC5B,aAAa,EAAE,CAqFjB"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/exploitability/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAqBjD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAyBpF;AAID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBzF;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAsBhE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,MAAM,EAAE,GACpB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA8CvB;AAoDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,aAAa,EAAE,EACzB,KAAK,EAAE,eAAe,GAAG,IAAI,GAC5B,aAAa,EAAE,CAqFjB;AAID;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA4CtE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAmCrF;AAID;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAkC9E;AAWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,KAAK,EAAE,eAAe,GAAG,IAAI,EAC7B,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,aAAa,EAAE,CAAC,CAqG1B"}