@monoes/monograph 1.1.0 → 1.2.1

package/dist/src/graph/risk-profile.js

@@ -0,0 +1,135 @@
+const LOC_BINS = [
+    { label: '1-10 lines', min: 1, max: 10 },
+    { label: '11-25 lines', min: 11, max: 25 },
+    { label: '26-50 lines', min: 26, max: 50 },
+    { label: '51-100 lines', min: 51, max: 100 },
+    { label: '101-250 lines', min: 101, max: 250 },
+    { label: '250+ lines', min: 251, max: Infinity },
+];
+const PARAM_BINS = [
+    { label: '0-2 params', min: 0, max: 2 },
+    { label: '3-5 params', min: 3, max: 5 },
+    { label: '6-8 params', min: 6, max: 8 },
+    { label: '9+ params', min: 9, max: Infinity },
+];
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.floor(sorted.length * p);
+    return sorted[Math.min(idx, sorted.length - 1)];
+}
+export function computeRiskProfile(db) {
+    // Push paramCount extraction to SQL with json_extract to avoid per-row JSON.parse
+    const rows = db.prepare(`
+    SELECT
+      start_line,
+      end_line,
+      CAST(json_extract(properties, '$.paramCount') AS INTEGER) AS param_count
+    FROM nodes
+    WHERE label IN ('Function', 'Method')
+      AND start_line IS NOT NULL
+      AND end_line IS NOT NULL
+  `).all();
+    // ── Single-pass: compute LOC, assign to bins, accumulate risk summary ─────
+    const locBinCounts = new Array(LOC_BINS.length).fill(0);
+    const paramBinCounts = new Array(PARAM_BINS.length).fill(0);
+    const sortedLocs = [];
+    let largeFunction = 0;
+    let longParamList = 0;
+    let highRisk = 0;
+    for (const row of rows) {
+        const loc = row.end_line - row.start_line + 1;
+        if (loc < 1)
+            continue;
+        sortedLocs.push(loc);
+        // Assign to LOC bin in O(bins) rather than O(N×bins) via filter
+        for (let i = 0; i < LOC_BINS.length; i++) {
+            const bin = LOC_BINS[i];
+            if (loc >= bin.min && loc <= bin.max) {
+                locBinCounts[i]++;
+                break;
+            }
+        }
+        const pc = row.param_count ?? 0;
+        for (let i = 0; i < PARAM_BINS.length; i++) {
+            const bin = PARAM_BINS[i];
+            if (pc >= bin.min && pc <= bin.max) {
+                paramBinCounts[i]++;
+                break;
+            }
+        }
+        const large = loc > 100;
+        const longParam = pc > 5;
+        if (large)
+            largeFunction++;
+        if (longParam)
+            longParamList++;
+        if (large && longParam)
+            highRisk++;
+    }
+    const total = sortedLocs.length;
+    // ── Build bin result arrays ───────────────────────────────────────────────
+    const functionSizeDistribution = LOC_BINS.map((bin, i) => ({
+        label: bin.label,
+        min: bin.min,
+        max: bin.max === Infinity ? 999999 : bin.max,
+        count: locBinCounts[i],
+        percentage: total > 0 ? Math.round((locBinCounts[i] / total) * 1000) / 10 : 0,
+    }));
+    const paramCountDistribution = PARAM_BINS.map((bin, i) => ({
+        label: bin.label,
+        min: bin.min,
+        max: bin.max === Infinity ? 999999 : bin.max,
+        count: paramBinCounts[i],
+        percentage: total > 0 ? Math.round((paramBinCounts[i] / total) * 1000) / 10 : 0,
+    }));
+    // ── Percentiles ────────────────────────────────────────────────────────────
+    sortedLocs.sort((a, b) => a - b);
+    const p50loc = percentile(sortedLocs, 0.50);
+    const p90loc = percentile(sortedLocs, 0.90);
+    const p95loc = percentile(sortedLocs, 0.95);
+    return {
+        functionSizeDistribution,
+        paramCountDistribution,
+        riskSummary: { largeFunction, longParamList, highRisk },
+        p50loc,
+        p90loc,
+        p95loc,
+    };
+}
+/**
+ * Format a RiskProfileReport as structured text with distribution tables for LLM navigation.
+ *
+ * @param report - RiskProfileReport from computeRiskProfile()
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatRiskProfile(report) {
+    const { functionSizeDistribution, paramCountDistribution, riskSummary, p50loc, p90loc, p95loc } = report;
+    const total = functionSizeDistribution.reduce((s, b) => s + b.count, 0);
+    if (total === 0) {
+        return 'risk_profile: no Function/Method nodes with line info found\n';
+    }
+    const lines = [
+        `risk_profile: ${total} functions analysed`,
+        `  p50_loc: ${p50loc}  p90_loc: ${p90loc}  p95_loc: ${p95loc}`,
+        `  large_functions(loc>100): ${riskSummary.largeFunction}  long_param_list(params>5): ${riskSummary.longParamList}  high_risk(both): ${riskSummary.highRisk}`,
+        '',
+        'function_size_distribution:',
+    ];
+    for (const bin of functionSizeDistribution) {
+        const bar = '#'.repeat(Math.round(bin.percentage / 5)); // 1 char per 5%
+        lines.push(`  ${bin.label.padEnd(15)}  ${String(bin.count).padStart(5)}  (${String(bin.percentage).padStart(5)}%)  ${bar}`);
+    }
+    lines.push('');
+    lines.push('param_count_distribution:');
+    for (const bin of paramCountDistribution) {
+        const bar = '#'.repeat(Math.round(bin.percentage / 5));
+        lines.push(`  ${bin.label.padEnd(15)}  ${String(bin.count).padStart(5)}  (${String(bin.percentage).padStart(5)}%)  ${bar}`);
+    }
+    if (riskSummary.highRisk > 0) {
+        lines.push('');
+        lines.push(`high_risk_note: ${riskSummary.highRisk} function(s) have both loc>100 AND params>5 — prime refactor candidates`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=risk-profile.js.map

package/dist/src/graph/risk-profile.js.map

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

package/dist/src/graph/shingle-filter.d.ts

@@ -0,0 +1,6 @@
+export interface ShingleFilter {
+    add(id: string, tokens: string[]): void;
+    candidates(tokens: string[], topK?: number): string[];
+}
+export declare function createShingleFilter(k?: number, numHashes?: number): ShingleFilter;
+//# sourceMappingURL=shingle-filter.d.ts.map

package/dist/src/graph/shingle-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shingle-filter.d.ts","sourceRoot":"","sources":["../../../src/graph/shingle-filter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACvD;AAwDD,wBAAgB,mBAAmB,CAAC,CAAC,SAAI,EAAE,SAAS,SAAM,GAAG,aAAa,CAyFzE"}

package/dist/src/graph/shingle-filter.js

@@ -0,0 +1,129 @@
+/**
+ * Generate k-shingles (k-grams) from a token array.
+ * Each shingle is the concatenation of k consecutive tokens joined by a space.
+ */
+function kShingles(tokens, k) {
+    if (tokens.length < k)
+        return [tokens.join(' ')];
+    const shingles = [];
+    for (let i = 0; i <= tokens.length - k; i++) {
+        shingles.push(tokens.slice(i, i + k).join(' '));
+    }
+    return shingles;
+}
+/**
+ * Simple string hash that produces a non-negative 32-bit integer.
+ * Uses a djb2-style hash.
+ */
+function hashString(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5) + h) ^ s.charCodeAt(i);
+        h = h >>> 0; // keep unsigned 32-bit
+    }
+    return h;
+}
+const MINHASH_PRIME = BigInt(4294967311); // first prime > 2^32
+/**
+ * Compute a MinHash signature for a set of shingles using
+ * numHashes linear hash functions: h_i(x) = (a_i * x + b_i) % prime.
+ *
+ * @param seedsA  Precomputed BigInt a-coefficients (length numHashes)
+ * @param seedsB  Precomputed BigInt b-constants   (length numHashes)
+ */
+function minHashSignature(shingles, numHashes, seedsA, seedsB) {
+    const sig = new Uint32Array(numHashes).fill(0xffffffff);
+    for (const shingle of shingles) {
+        const x = BigInt(hashString(shingle));
+        for (let i = 0; i < numHashes; i++) {
+            // Precomputed seeds avoid recomputing the same (a, b) per shingle per call.
+            const hashVal = Number((seedsA[i] * x + seedsB[i]) % MINHASH_PRIME) >>> 0;
+            if (hashVal < sig[i])
+                sig[i] = hashVal;
+        }
+    }
+    return sig;
+}
+export function createShingleFilter(k = 5, numHashes = 128) {
+    // Each entry: { sig: Uint32Array }
+    const index = new Map();
+    // LSH: split numHashes into bands of rows
+    // Standard LSH: numBands * numRows = numHashes, threshold ≈ (1/numBands)^(1/numRows)
+    // We target threshold ~0.5: solve (1/b)^(1/r) = 0.5 with b*r = numHashes
+    // A reasonable split is sqrt(numHashes) bands of sqrt(numHashes) rows each.
+    const numBands = Math.round(Math.sqrt(numHashes));
+    const numRows = Math.floor(numHashes / numBands);
+    // Precompute MinHash seeds once per filter instance to avoid recomputing
+    // (a, b) inside the hot inner loop of minHashSignature().
+    const seedsA = new BigInt64Array(numHashes);
+    const seedsB = new BigInt64Array(numHashes);
+    for (let i = 0; i < numHashes; i++) {
+        seedsA[i] = BigInt(((i * 2654435761 + 0x9e3779b9) >>> 0));
+        seedsB[i] = BigInt(((i * 2246822519 + 0x85ebca6b) >>> 0));
+    }
+    function getBandKey(band, sig) {
+        const parts = [];
+        for (let r = 0; r < numRows; r++) {
+            const idx = band * numRows + r;
+            if (idx < numHashes)
+                parts.push(sig[idx]);
+        }
+        return `b${band}:${parts.join(',')}`;
+    }
+    // Band bucket → list of candidate IDs
+    const bandBuckets = new Map();
+    return {
+        add(id, tokens) {
+            const shingles = kShingles(tokens, k);
+            const sig = minHashSignature(shingles, numHashes, seedsA, seedsB);
+            index.set(id, sig);
+            // Insert into LSH band buckets
+            for (let band = 0; band < numBands; band++) {
+                const key = getBandKey(band, sig);
+                const bucket = bandBuckets.get(key);
+                if (bucket) {
+                    bucket.push(id);
+                }
+                else {
+                    bandBuckets.set(key, [id]);
+                }
+            }
+        },
+        candidates(tokens, topK = 10) {
+            const shingles = kShingles(tokens, k);
+            const querySig = minHashSignature(shingles, numHashes, seedsA, seedsB);
+            // Collect candidate IDs via LSH band matching.
+            // Use getBandKey() consistently — eliminates the duplicate inline computation.
+            const candidateScores = new Map();
+            for (let band = 0; band < numBands; band++) {
+                const queryKey = getBandKey(band, querySig);
+                const bucket = bandBuckets.get(queryKey);
+                if (bucket) {
+                    for (const id of bucket) {
+                        candidateScores.set(id, (candidateScores.get(id) ?? 0) + 1);
+                    }
+                }
+            }
+            if (candidateScores.size === 0)
+                return [];
+            // Compute Jaccard estimate from signature agreement for ranked results
+            const ranked = [...candidateScores.keys()].map(id => {
+                const sig = index.get(id);
+                let matches = 0;
+                for (let i = 0; i < numHashes; i++) {
+                    if (sig[i] === querySig[i])
+                        matches++;
+                }
+                const jaccardEst = matches / numHashes;
+                return { id, jaccardEst };
+            });
+            // Filter by estimated Jaccard > 0.5 and return topK
+            return ranked
+                .filter(r => r.jaccardEst > 0.5)
+                .sort((a, b) => b.jaccardEst - a.jaccardEst)
+                .slice(0, topK)
+                .map(r => r.id);
+        },
+    };
+}
+//# sourceMappingURL=shingle-filter.js.map

package/dist/src/graph/shingle-filter.js.map

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

package/dist/src/graph/statistics.d.ts

@@ -0,0 +1,45 @@
+import type { MonographDb } from '../storage/db.js';
+/**
+ * Evict the cached graph for a given DB instance (call after writes).
+ */
+export declare function invalidateGraphCache(db: MonographDb): void;
+/**
+ * Graph density: ratio of actual edges to maximum possible directed edges.
+ * For a directed graph with n nodes: max = n * (n - 1).
+ * Ignores self-loops.
+ */
+export declare function graphDensity(db: MonographDb): number;
+/**
+ * Average local clustering coefficient across all nodes.
+ * For a directed graph, the local clustering coefficient of node v is:
+ *   (triangles through v) / (directed_pairs through v)
+ * where directed_pairs = k_in * k_out - mutual_pairs
+ * We use the undirected approximation: treat edges as undirected, count triangles.
+ */
+export declare function clusteringCoefficient(db: MonographDb): number;
+export interface PathStats {
+    /** Average shortest path length across all reachable pairs (i ≠ j). */
+    averagePathLength: number;
+    /** Maximum shortest path length (diameter) across all reachable pairs. */
+    diameter: number;
+}
+/**
+ * Compute both average path length and graph diameter in a single BFS pass.
+ * Unreachable pairs are excluded from averagePathLength.
+ */
+export declare function pathStats(db: MonographDb): PathStats;
+/**
+ * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
+ * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ *
+ * @deprecated Prefer `pathStats(db).averagePathLength` to share BFS with `graphDiameter`.
+ */
+export declare function averagePathLength(db: MonographDb): number;
+/**
+ * Graph diameter: the maximum shortest path length across all reachable node pairs.
+ * Returns 0 for empty or single-node graphs.
+ *
+ * @deprecated Prefer `pathStats(db).diameter` to share BFS with `averagePathLength`.
+ */
+export declare function graphDiameter(db: MonographDb): number;
+//# sourceMappingURL=statistics.d.ts.map

package/dist/src/graph/statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../../../src/graph/statistics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA0BpD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAWpD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAsC7D;AAMD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,SAAS,CAuBpD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAErD"}

package/dist/src/graph/statistics.js

@@ -0,0 +1,134 @@
+import { bfsFromNode } from 'graphology-traversal/bfs.js';
+import { loadGraphFromDb } from './loader.js';
+// ---------------------------------------------------------------------------
+// Module-level graph cache — avoids reloading the full graph on every call
+// when multiple statistics functions are invoked in the same request cycle.
+// TTL: 5 seconds; keyed by DB file path (better-sqlite3 exposes .name).
+// ---------------------------------------------------------------------------
+const GRAPH_CACHE_TTL_MS = 5_000;
+const _graphCache = new Map();
+function getGraph(db) {
+    const key = db.name ?? '__default__';
+    const now = Date.now();
+    const cached = _graphCache.get(key);
+    if (cached && now < cached.expiresAt)
+        return cached.graph;
+    const graph = loadGraphFromDb(db);
+    _graphCache.set(key, { graph, expiresAt: now + GRAPH_CACHE_TTL_MS });
+    return graph;
+}
+/**
+ * Evict the cached graph for a given DB instance (call after writes).
+ */
+export function invalidateGraphCache(db) {
+    const key = db.name ?? '__default__';
+    _graphCache.delete(key);
+}
+/**
+ * Graph density: ratio of actual edges to maximum possible directed edges.
+ * For a directed graph with n nodes: max = n * (n - 1).
+ * Ignores self-loops.
+ */
+export function graphDensity(db) {
+    const graph = getGraph(db);
+    const n = graph.order;
+    if (n < 2)
+        return 0;
+    const maxEdges = n * (n - 1);
+    // Use simple directed edge count (deduplicate multi-edges for density)
+    const seen = new Set();
+    graph.forEachEdge((_, _attr, src, tgt) => {
+        if (src !== tgt)
+            seen.add(`${src}→${tgt}`);
+    });
+    return seen.size / maxEdges;
+}
+/**
+ * Average local clustering coefficient across all nodes.
+ * For a directed graph, the local clustering coefficient of node v is:
+ *   (triangles through v) / (directed_pairs through v)
+ * where directed_pairs = k_in * k_out - mutual_pairs
+ * We use the undirected approximation: treat edges as undirected, count triangles.
+ */
+export function clusteringCoefficient(db) {
+    const graph = getGraph(db);
+    if (graph.order === 0)
+        return 0;
+    // Build undirected adjacency sets
+    const neighbors = new Map();
+    graph.forEachNode(node => neighbors.set(node, new Set()));
+    graph.forEachEdge((_, _attr, src, tgt) => {
+        if (src !== tgt) {
+            neighbors.get(src).add(tgt);
+            neighbors.get(tgt).add(src);
+        }
+    });
+    let totalCoeff = 0;
+    let countWithNeighbors = 0;
+    for (const [node, nbrs] of neighbors) {
+        const k = nbrs.size;
+        if (k < 2)
+            continue;
+        let triangles = 0;
+        const nbList = [...nbrs];
+        for (let i = 0; i < nbList.length; i++) {
+            for (let j = i + 1; j < nbList.length; j++) {
+                if (neighbors.get(nbList[i])?.has(nbList[j])) {
+                    triangles++;
+                }
+            }
+        }
+        const possible = (k * (k - 1)) / 2;
+        totalCoeff += triangles / possible;
+        countWithNeighbors++;
+    }
+    if (countWithNeighbors === 0)
+        return 0;
+    return totalCoeff / countWithNeighbors;
+}
+/**
+ * Compute both average path length and graph diameter in a single BFS pass.
+ * Unreachable pairs are excluded from averagePathLength.
+ */
+export function pathStats(db) {
+    const graph = getGraph(db);
+    const nodes = graph.nodes();
+    if (nodes.length < 2)
+        return { averagePathLength: 0, diameter: 0 };
+    let totalLength = 0;
+    let reachablePairs = 0;
+    let maxDist = 0;
+    for (const source of nodes) {
+        bfsFromNode(graph, source, (node, _attr, depth) => {
+            if (node !== source && depth > 0) {
+                totalLength += depth;
+                reachablePairs++;
+                if (depth > maxDist)
+                    maxDist = depth;
+            }
+        });
+    }
+    return {
+        averagePathLength: reachablePairs === 0 ? 0 : totalLength / reachablePairs,
+        diameter: maxDist,
+    };
+}
+/**
+ * Average shortest path length across all reachable node pairs (i, j) where i ≠ j.
+ * Computed using BFS from each node. Unreachable pairs are excluded from the average.
+ *
+ * @deprecated Prefer `pathStats(db).averagePathLength` to share BFS with `graphDiameter`.
+ */
+export function averagePathLength(db) {
+    return pathStats(db).averagePathLength;
+}
+/**
+ * Graph diameter: the maximum shortest path length across all reachable node pairs.
+ * Returns 0 for empty or single-node graphs.
+ *
+ * @deprecated Prefer `pathStats(db).diameter` to share BFS with `averagePathLength`.
+ */
+export function graphDiameter(db) {
+    return pathStats(db).diameter;
+}
+//# sourceMappingURL=statistics.js.map

package/dist/src/graph/statistics.js.map

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

package/dist/src/graph/stats.d.ts

@@ -0,0 +1,40 @@
+import type Database from 'better-sqlite3';
+export type RiskBin = 'low' | 'medium' | 'high' | 'critical';
+export interface RiskProfile {
+    low: number;
+    medium: number;
+    high: number;
+    critical: number;
+    lowPct: number;
+    mediumPct: number;
+    highPct: number;
+    criticalPct: number;
+}
+export interface CouplingProfile {
+    p50FanIn: number;
+    p75FanIn: number;
+    p90FanIn: number;
+    p95FanIn: number;
+    couplingHighPct: number;
+    fanInProfile: RiskProfile;
+    fanOutProfile: RiskProfile;
+    totalFiles: number;
+}
+export interface GraphStatsSummary {
+    nodeCount: number;
+    edgeCount: number;
+    communityCount: number;
+    fileCount: number;
+    couplingProfile: CouplingProfile;
+}
+/**
+ * Compute full coupling profile from SQLite.
+ */
+export declare function computeCouplingProfile(db: Database.Database): CouplingProfile;
+/**
+ * Quick stats summary (extends existing stats from monograph_stats MCP tool).
+ */
+export declare function computeGraphStats(db: Database.Database): GraphStatsSummary;
+/** Format a GraphStatsSummary as structured text for LLM consumption. */
+export declare function formatGraphStats(s: GraphStatsSummary): string;
+//# sourceMappingURL=stats.d.ts.map

package/dist/src/graph/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/graph/stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAwB3C,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,WAAW,CAAC;IAC1B,aAAa,EAAE,WAAW,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,eAAe,CAAC;CAClC;AA8BD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,eAAe,CA8B7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,iBAAiB,CAkB1E;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAY7D"}

package/dist/src/graph/stats.js

@@ -0,0 +1,120 @@
+// Per-DB prepared statement cache to avoid re-parsing SQL on repeated calls
+const stmtCache = new WeakMap();
+function stmt(db, sql) {
+    let dbCache = stmtCache.get(db);
+    if (!dbCache) {
+        dbCache = new Map();
+        stmtCache.set(db, dbCache);
+    }
+    let s = dbCache.get(sql);
+    if (!s) {
+        s = db.prepare(sql);
+        dbCache.set(sql, s);
+    }
+    return s;
+}
+/** Binary search: returns index of first element > value in a sorted ascending array. */
+function upperBound(sorted, value) {
+    let lo = 0, hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] <= value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.floor((p / 100) * sorted.length);
+    return sorted[Math.min(idx, sorted.length - 1)];
+}
+function buildRiskProfile(values) {
+    const total = values.length;
+    let low = 0, medium = 0, high = 0, critical = 0;
+    for (const v of values) {
+        if (v < 5)
+            low++;
+        else if (v <= 15)
+            medium++;
+        else if (v <= 30)
+            high++;
+        else
+            critical++;
+    }
+    const pct = (n) => total > 0 ? Math.round((n / total) * 100) : 0;
+    return {
+        low,
+        medium,
+        high,
+        critical,
+        lowPct: pct(low),
+        mediumPct: pct(medium),
+        highPct: pct(high),
+        criticalPct: pct(critical),
+    };
+}
+/**
+ * Compute full coupling profile from SQLite.
+ */
+export function computeCouplingProfile(db) {
+    const fanInRows = stmt(db, 'SELECT target_id, COUNT(*) as c FROM edges GROUP BY target_id')
+        .all();
+    const fanOutRows = stmt(db, 'SELECT source_id, COUNT(*) as c FROM edges GROUP BY source_id')
+        .all();
+    const totalFiles = stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+        .get().n;
+    const fanInValues = fanInRows.map(r => r.c).sort((a, b) => a - b);
+    const fanOutValues = fanOutRows.map(r => r.c).sort((a, b) => a - b);
+    const p95FanIn = percentile(fanInValues, 95);
+    // Use binary search instead of O(N) filter to count elements above p95 threshold
+    const couplingHighCount = fanInValues.length - upperBound(fanInValues, p95FanIn);
+    const couplingHighPct = fanInValues.length > 0
+        ? Math.round((couplingHighCount / fanInValues.length) * 100)
+        : 0;
+    return {
+        p50FanIn: percentile(fanInValues, 50),
+        p75FanIn: percentile(fanInValues, 75),
+        p90FanIn: percentile(fanInValues, 90),
+        p95FanIn,
+        couplingHighPct,
+        fanInProfile: buildRiskProfile(fanInValues),
+        fanOutProfile: buildRiskProfile(fanOutValues),
+        totalFiles,
+    };
+}
+/**
+ * Quick stats summary (extends existing stats from monograph_stats MCP tool).
+ */
+export function computeGraphStats(db) {
+    const nodeCount = stmt(db, 'SELECT COUNT(*) as n FROM nodes').get().n;
+    const edgeCount = stmt(db, 'SELECT COUNT(*) as n FROM edges').get().n;
+    const communityCount = stmt(db, "SELECT COUNT(DISTINCT community_id) as n FROM nodes WHERE community_id IS NOT NULL").get().n;
+    const fileCount = stmt(db, "SELECT COUNT(*) as n FROM nodes WHERE label = 'File'")
+        .get().n;
+    const couplingProfile = computeCouplingProfile(db);
+    return {
+        nodeCount,
+        edgeCount,
+        communityCount,
+        fileCount,
+        couplingProfile,
+    };
+}
+/** Format a GraphStatsSummary as structured text for LLM consumption. */
+export function formatGraphStats(s) {
+    const cp = s.couplingProfile;
+    const lines = [
+        `Graph Stats`,
+        `  Nodes: ${s.nodeCount}  Edges: ${s.edgeCount}  Communities: ${s.communityCount}  Files: ${s.fileCount}`,
+        `Coupling Profile (${cp.totalFiles} files)`,
+        `  Fan-in p50/p75/p90/p95: ${cp.p50FanIn}/${cp.p75FanIn}/${cp.p90FanIn}/${cp.p95FanIn}`,
+        `  High-coupling (>p95): ${cp.couplingHighPct}%`,
+        `Fan-in Risk: low=${cp.fanInProfile.low}(${cp.fanInProfile.lowPct}%) med=${cp.fanInProfile.medium}(${cp.fanInProfile.mediumPct}%) high=${cp.fanInProfile.high}(${cp.fanInProfile.highPct}%) crit=${cp.fanInProfile.critical}(${cp.fanInProfile.criticalPct}%)`,
+        `Fan-out Risk: low=${cp.fanOutProfile.low}(${cp.fanOutProfile.lowPct}%) med=${cp.fanOutProfile.medium}(${cp.fanOutProfile.mediumPct}%) high=${cp.fanOutProfile.high}(${cp.fanOutProfile.highPct}%) crit=${cp.fanOutProfile.critical}(${cp.fanOutProfile.criticalPct}%)`,
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=stats.js.map