@monoes/monograph 1.1.0 → 1.2.1

package/dist/src/analysis/churn-trend.js

@@ -0,0 +1,73 @@
+const ACCELERATING_RATIO = 1.5;
+const COOLING_RATIO = 0.67;
+export function computeChurnTrend(timestampsEpochSec) {
+    if (timestampsEpochSec.length < 2)
+        return 'stable';
+    // Single pass: compute min, max, and partition counts simultaneously (O(N) vs O(4N) before)
+    let minTs = timestampsEpochSec[0];
+    let maxTs = timestampsEpochSec[0];
+    for (let i = 1; i < timestampsEpochSec.length; i++) {
+        const ts = timestampsEpochSec[i];
+        if (ts < minTs)
+            minTs = ts;
+        if (ts > maxTs)
+            maxTs = ts;
+    }
+    if (maxTs === minTs)
+        return 'stable';
+    const midpoint = minTs + (maxTs - minTs) / 2;
+    let recent = 0, older = 0;
+    for (const ts of timestampsEpochSec) {
+        if (ts > midpoint)
+            recent++;
+        else
+            older++;
+    }
+    if (older < 1)
+        return 'stable';
+    const ratio = recent / older;
+    if (ratio > ACCELERATING_RATIO)
+        return 'accelerating';
+    if (ratio < COOLING_RATIO)
+        return 'cooling';
+    return 'stable';
+}
+export function churnTrendLabel(trend) {
+    return trend === 'accelerating' ? '↑ accelerating' : trend === 'cooling' ? '↓ cooling' : '→ stable';
+}
+export function churnTrendFromFileSeries(fileTimestamps) {
+    // Avoid allocating an intermediate flat array — inline the min/max/count logic
+    if (fileTimestamps.length === 0)
+        return 'stable';
+    let minTs = Infinity, maxTs = -Infinity, total = 0;
+    for (const series of fileTimestamps) {
+        for (const ts of series) {
+            if (ts < minTs)
+                minTs = ts;
+            if (ts > maxTs)
+                maxTs = ts;
+            total++;
+        }
+    }
+    if (total < 2 || maxTs === minTs)
+        return 'stable';
+    const midpoint = minTs + (maxTs - minTs) / 2;
+    let recent = 0, older = 0;
+    for (const series of fileTimestamps) {
+        for (const ts of series) {
+            if (ts > midpoint)
+                recent++;
+            else
+                older++;
+        }
+    }
+    if (older < 1)
+        return 'stable';
+    const ratio = recent / older;
+    if (ratio > ACCELERATING_RATIO)
+        return 'accelerating';
+    if (ratio < COOLING_RATIO)
+        return 'cooling';
+    return 'stable';
+}
+//# sourceMappingURL=churn-trend.js.map

package/dist/src/analysis/churn-trend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"churn-trend.js","sourceRoot":"","sources":["../../../src/analysis/churn-trend.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B,MAAM,UAAU,iBAAiB,CAAC,kBAA4B;IAC5D,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACnD,4FAA4F;IAC5F,IAAI,KAAK,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,KAAK,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnD,MAAM,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,EAAE,GAAG,KAAK;YAAE,KAAK,GAAG,EAAE,CAAC;QAC3B,IAAI,EAAE,GAAG,KAAK;YAAE,KAAK,GAAG,EAAE,CAAC;IAC7B,CAAC;IACD,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IACrC,MAAM,QAAQ,GAAG,KAAK,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;IAC1B,KAAK,MAAM,EAAE,IAAI,kBAAkB,EAAE,CAAC;QACpC,IAAI,EAAE,GAAG,QAAQ;YAAE,MAAM,EAAE,CAAC;;YAAM,KAAK,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/B,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC7B,IAAI,KAAK,GAAG,kBAAkB;QAAE,OAAO,cAAc,CAAC;IACtD,IAAI,KAAK,GAAG,aAAa;QAAE,OAAO,SAAS,CAAC;IAC5C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,OAAO,KAAK,KAAK,cAAc,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC;AACtG,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,cAA0B;IACjE,+EAA+E;IAC/E,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,IAAI,KAAK,GAAG,QAAQ,EAAE,KAAK,GAAG,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC;IACnD,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QACpC,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,EAAE,GAAG,KAAK;gBAAE,KAAK,GAAG,EAAE,CAAC;YAC3B,IAAI,EAAE,GAAG,KAAK;gBAAE,KAAK,GAAG,EAAE,CAAC;YAC3B,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IAClD,MAAM,QAAQ,GAAG,KAAK,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC;IAC1B,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QACpC,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,EAAE,GAAG,QAAQ;gBAAE,MAAM,EAAE,CAAC;;gBAAM,KAAK,EAAE,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/B,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC7B,IAAI,KAAK,GAAG,kBAAkB;QAAE,OAAO,cAAc,CAAC;IACtD,IAAI,KAAK,GAAG,aAAa;QAAE,OAAO,SAAS,CAAC;IAC5C,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/analysis/churn.d.ts

@@ -0,0 +1,26 @@
+export type ChurnTrend = 'accelerating' | 'stable' | 'cooling';
+export interface SinceDuration {
+    raw: string;
+    days: number;
+}
+export interface AuthorContribution {
+    authorIdx: number;
+    weightedCommits: number;
+}
+export interface FileChurn {
+    path: string;
+    totalCommits: number;
+    weightedCommits: number;
+    authors: AuthorContribution[];
+    trend: ChurnTrend;
+}
+export interface ChurnResult {
+    files: FileChurn[];
+    authorPool: string[];
+    since: SinceDuration;
+}
+export declare function parseSince(s: string): SinceDuration;
+export declare function computeRecencyWeight(ageDays: number): number;
+export declare function classifyChurnTrend(recentWeighted: number, olderWeighted: number): ChurnTrend;
+export declare function analyzeChurn(root: string, since: SinceDuration | string): Promise<ChurnResult>;
+//# sourceMappingURL=churn.d.ts.map

package/dist/src/analysis/churn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"churn.d.ts","sourceRoot":"","sources":["../../../src/analysis/churn.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAyBnD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,UAAU,CAQ5F;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,aAAa,GAAG,MAAM,GAC5B,OAAO,CAAC,WAAW,CAAC,CA6ItB"}

package/dist/src/analysis/churn.js

@@ -0,0 +1,164 @@
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+export function parseSince(s) {
+    const dMatch = s.match(/^(\d+)d$/);
+    if (dMatch)
+        return { raw: s, days: parseInt(dMatch[1], 10) };
+    const wMatch = s.match(/^(\d+)w$/);
+    if (wMatch)
+        return { raw: s, days: parseInt(wMatch[1], 10) * 7 };
+    const mMatch = s.match(/^(\d+)m$/);
+    if (mMatch)
+        return { raw: s, days: parseInt(mMatch[1], 10) * 30 };
+    const yMatch = s.match(/^(\d+)y$/);
+    if (yMatch)
+        return { raw: s, days: parseInt(yMatch[1], 10) * 365 };
+    // ISO date string
+    const parsed = Date.parse(s);
+    if (!isNaN(parsed)) {
+        const days = Math.ceil((Date.now() - parsed) / 86400000);
+        return { raw: s, days };
+    }
+    // Fallback: try to parse as plain number of days
+    const num = parseInt(s, 10);
+    if (!isNaN(num))
+        return { raw: s, days: num };
+    return { raw: s, days: 30 };
+}
+export function computeRecencyWeight(ageDays) {
+    return Math.exp(-Math.LN2 * ageDays / 90);
+}
+export function classifyChurnTrend(recentWeighted, olderWeighted) {
+    if (olderWeighted === 0) {
+        return recentWeighted > 0 ? 'accelerating' : 'stable';
+    }
+    const ratio = recentWeighted / olderWeighted;
+    if (ratio > 1.5)
+        return 'accelerating';
+    if (ratio < 0.67)
+        return 'cooling';
+    return 'stable';
+}
+export async function analyzeChurn(root, since) {
+    const sinceDuration = typeof since === 'string' ? parseSince(since) : since;
+    // Cache lookup
+    const cacheDir = join(root, '.monograph', 'cache');
+    let treeHash = '';
+    try {
+        treeHash = execSync('git rev-parse HEAD', { cwd: root }).toString().trim();
+        const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}.json`);
+        if (existsSync(cacheFile)) {
+            try {
+                const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
+                return cached;
+            }
+            catch {
+                // cache corrupt, recompute
+            }
+        }
+    }
+    catch {
+        // git not available or no commits
+    }
+    // Build since date string for git log
+    const sinceDate = new Date(Date.now() - sinceDuration.days * 86400000);
+    const sinceDateStr = sinceDate.toISOString().slice(0, 10);
+    // Get all commits with file paths
+    let logOutput = '';
+    try {
+        logOutput = execSync(`git log --after="${sinceDateStr}" --name-only --format="%ae|%ai"`, { cwd: root, maxBuffer: 50 * 1024 * 1024 }).toString();
+    }
+    catch {
+        return { files: [], authorPool: [], since: sinceDuration };
+    }
+    const now = Date.now();
+    // Parse log output into per-file commit lists: { email, dateStr }[]
+    const fileCommits = new Map();
+    const authorIndexMap = new Map();
+    const authorPool = [];
+    const lines = logOutput.split('\n');
+    let currentEmail = '';
+    let currentDateStr = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.includes('|')) {
+            // Header line: email|date
+            const pipeIdx = trimmed.indexOf('|');
+            currentEmail = trimmed.slice(0, pipeIdx).trim();
+            currentDateStr = trimmed.slice(pipeIdx + 1).trim();
+        }
+        else {
+            // File path line
+            const filePath = trimmed;
+            if (!fileCommits.has(filePath)) {
+                fileCommits.set(filePath, []);
+            }
+            fileCommits.get(filePath).push({ email: currentEmail, dateStr: currentDateStr });
+        }
+    }
+    // Build FileChurn entries
+    const files = [];
+    for (const [path, commits] of fileCommits) {
+        if (commits.length === 0)
+            continue;
+        // Sort commits by date descending (newest first)
+        const sortedCommits = commits.slice().sort((a, b) => {
+            return Date.parse(b.dateStr) - Date.parse(a.dateStr);
+        });
+        // Compute weighted commits per author and trend
+        const authorWeights = new Map();
+        let totalWeighted = 0;
+        // Split into two halves for trend analysis
+        const midpoint = Math.floor(sortedCommits.length / 2);
+        let recentWeighted = 0;
+        let olderWeighted = 0;
+        for (let i = 0; i < sortedCommits.length; i++) {
+            const commit = sortedCommits[i];
+            const commitDate = Date.parse(commit.dateStr);
+            const ageDays = (now - commitDate) / 86400000;
+            const weight = computeRecencyWeight(ageDays);
+            // Author index
+            if (!authorIndexMap.has(commit.email)) {
+                authorIndexMap.set(commit.email, authorPool.length);
+                authorPool.push(commit.email);
+            }
+            const authorIdx = authorIndexMap.get(commit.email);
+            const existing = authorWeights.get(authorIdx) ?? 0;
+            authorWeights.set(authorIdx, existing + weight);
+            totalWeighted += weight;
+            // recent = first half (newest), older = second half
+            if (i < midpoint) {
+                recentWeighted += weight;
+            }
+            else {
+                olderWeighted += weight;
+            }
+        }
+        const trend = classifyChurnTrend(recentWeighted, olderWeighted);
+        const authors = Array.from(authorWeights.entries()).map(([authorIdx, weightedCommits]) => ({ authorIdx, weightedCommits }));
+        files.push({
+            path,
+            totalCommits: commits.length,
+            weightedCommits: totalWeighted,
+            authors,
+            trend,
+        });
+    }
+    const result = { files, authorPool, since: sinceDuration };
+    // Write cache
+    if (treeHash) {
+        try {
+            mkdirSync(cacheDir, { recursive: true });
+            const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}.json`);
+            writeFileSync(cacheFile, JSON.stringify(result), 'utf8');
+        }
+        catch {
+            // cache write failure is non-fatal
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=churn.js.map

package/dist/src/analysis/churn.js.map

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

package/dist/src/analysis/cluster-quality.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cluster quality metrics: silhouette score and modularity score.
+ *
+ * References:
+ *  - Silhouette: Rousseeuw (1987) — (b-a)/max(a,b) averaged over all nodes
+ *  - Modularity: Newman & Girvan (2004) — Q = Σ[e_ii - a_i²]
+ */
+export type Edge = {
+    sourceId: string;
+    targetId: string;
+};
+/**
+ * Compute the average silhouette score for the partitioning.
+ * Returns a value in [-1, 1] where higher is better.
+ *
+ * Precomputes the communityMembers map once (O(N)) before the per-node loop,
+ * reducing overall complexity from O(N²) to O(N + K*N) where K = community count.
+ */
+export declare function silhouetteScore(memberships: Map<string, number>, edges: Edge[]): number;
+/**
+ * Compute Newman–Girvan modularity Q.
+ *
+ * Q = (1/2m) * Σ_{ij} [A_ij - k_i*k_j/(2m)] * δ(c_i, c_j)
+ *
+ * where m = total edge count, k_i = degree of node i, A_ij = adjacency.
+ * Returns a value in (-0.5, 1].
+ */
+export declare function modularityScore(memberships: Map<string, number>, edges: Edge[]): number;
+//# sourceMappingURL=cluster-quality.d.ts.map

package/dist/src/analysis/cluster-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-quality.d.ts","sourceRoot":"","sources":["../../../src/analysis/cluster-quality.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,IAAI,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AA2D1D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,KAAK,EAAE,IAAI,EAAE,GACZ,MAAM,CAoBR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,KAAK,EAAE,IAAI,EAAE,GACZ,MAAM,CAgCR"}

package/dist/src/analysis/cluster-quality.js

@@ -0,0 +1,124 @@
+/**
+ * Cluster quality metrics: silhouette score and modularity score.
+ *
+ * References:
+ *  - Silhouette: Rousseeuw (1987) — (b-a)/max(a,b) averaged over all nodes
+ *  - Modularity: Newman & Girvan (2004) — Q = Σ[e_ii - a_i²]
+ */
+/**
+ * Build an adjacency map from an edge list (undirected).
+ */
+function buildAdjacency(edges) {
+    const adj = new Map();
+    for (const { sourceId, targetId } of edges) {
+        if (!adj.has(sourceId))
+            adj.set(sourceId, new Set());
+        if (!adj.has(targetId))
+            adj.set(targetId, new Set());
+        adj.get(sourceId).add(targetId);
+        adj.get(targetId).add(sourceId);
+    }
+    return adj;
+}
+/**
+ * Average hop-distance proxy: fraction of community members NOT adjacent to node.
+ * For graph-based silhouette we use the complement of the adjacency fraction
+ * as a distance (0 = neighbor, 1 = no edge).
+ *
+ * a(i) = mean distance to other nodes in same community
+ * b(i) = min mean distance to any other community
+ * silhouette(i) = (b(i) - a(i)) / max(a(i), b(i))
+ *
+ * @param communityMembers - precomputed communityId → nodeId[] map (excludes self)
+ */
+function nodeSilhouette(nodeId, community, communityMembers, adj) {
+    const neighbors = adj.get(nodeId) ?? new Set();
+    const sameMembers = (communityMembers.get(community) ?? []).filter(n => n !== nodeId);
+    if (sameMembers.length === 0)
+        return 0; // singleton community
+    // a(i): mean distance to same community (1 = not neighbor, 0 = neighbor)
+    const a = sameMembers.reduce((sum, nid) => sum + (neighbors.has(nid) ? 0 : 1), 0) /
+        sameMembers.length;
+    // b(i): minimum mean distance to any other community
+    let b = Infinity;
+    for (const [cid, members] of communityMembers) {
+        if (cid === community || members.length === 0)
+            continue;
+        const meanDist = members.reduce((sum, nid) => sum + (neighbors.has(nid) ? 0 : 1), 0) /
+            members.length;
+        if (meanDist < b)
+            b = meanDist;
+    }
+    if (!isFinite(b))
+        return 0; // only one community exists
+    const denom = Math.max(a, b);
+    if (denom === 0)
+        return 0;
+    return (b - a) / denom;
+}
+/**
+ * Compute the average silhouette score for the partitioning.
+ * Returns a value in [-1, 1] where higher is better.
+ *
+ * Precomputes the communityMembers map once (O(N)) before the per-node loop,
+ * reducing overall complexity from O(N²) to O(N + K*N) where K = community count.
+ */
+export function silhouetteScore(memberships, edges) {
+    if (memberships.size === 0)
+        return 0;
+    const adj = buildAdjacency(edges);
+    // Precompute communityId → nodeId[] once to avoid O(N) re-scan per node
+    const communityMembers = new Map();
+    for (const [nid, cid] of memberships) {
+        let members = communityMembers.get(cid);
+        if (!members) {
+            members = [];
+            communityMembers.set(cid, members);
+        }
+        members.push(nid);
+    }
+    let total = 0;
+    for (const [nodeId, community] of memberships) {
+        total += nodeSilhouette(nodeId, community, communityMembers, adj);
+    }
+    return total / memberships.size;
+}
+/**
+ * Compute Newman–Girvan modularity Q.
+ *
+ * Q = (1/2m) * Σ_{ij} [A_ij - k_i*k_j/(2m)] * δ(c_i, c_j)
+ *
+ * where m = total edge count, k_i = degree of node i, A_ij = adjacency.
+ * Returns a value in (-0.5, 1].
+ */
+export function modularityScore(memberships, edges) {
+    const adj = buildAdjacency(edges);
+    // Degree map (undirected) — use adj to count undirected edges correctly
+    const degree = new Map();
+    for (const [nodeId, neighbors] of adj) {
+        degree.set(nodeId, neighbors.size);
+    }
+    // m_undirected: each undirected edge is counted once in adj (both directions added)
+    // so sum of degrees = 2 * m_undirected
+    const totalDegree = [...degree.values()].reduce((s, d) => s + d, 0);
+    const m = totalDegree / 2;
+    if (m === 0)
+        return 0;
+    const twoM = 2 * m;
+    let Q = 0;
+    const nodes = [...memberships.keys()];
+    for (let i = 0; i < nodes.length; i++) {
+        const u = nodes[i];
+        for (let j = i + 1; j < nodes.length; j++) {
+            const v = nodes[j];
+            if (memberships.get(u) !== memberships.get(v))
+                continue;
+            const aij = adj.get(u)?.has(v) ? 1 : 0;
+            const ki = degree.get(u) ?? 0;
+            const kj = degree.get(v) ?? 0;
+            Q += aij - (ki * kj) / twoM;
+        }
+    }
+    return Q / m; // normalise by m (equivalent to 1/(2m) summed both directions)
+}
+//# sourceMappingURL=cluster-quality.js.map

package/dist/src/analysis/cluster-quality.js.map

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

package/dist/src/analysis/combined.d.ts

@@ -0,0 +1,13 @@
+import type { MonographDb } from '../storage/db.js';
+export type AnalysisKind = 'dead-code' | 'duplication' | 'health';
+export interface CombinedOptions {
+    only?: AnalysisKind[];
+    skip?: AnalysisKind[];
+}
+export interface CombinedResult {
+    analyses: Set<AnalysisKind>;
+    ranAt: string;
+}
+export declare function resolveAnalyses(opts: CombinedOptions): Set<AnalysisKind>;
+export declare function runCombined(db: MonographDb, opts: CombinedOptions): Promise<CombinedResult>;
+//# sourceMappingURL=combined.d.ts.map

package/dist/src/analysis/combined.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combined.d.ts","sourceRoot":"","sources":["../../../src/analysis/combined.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,GAAG,CAAC,YAAY,CAAC,CAexE;AAED,wBAAsB,WAAW,CAC/B,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,cAAc,CAAC,CAIzB"}

package/dist/src/analysis/combined.js

@@ -0,0 +1,19 @@
+export function resolveAnalyses(opts) {
+    let result = new Set(['dead-code', 'duplication', 'health']);
+    if (opts.skip) {
+        for (const kind of opts.skip) {
+            result.delete(kind);
+        }
+    }
+    if (opts.only && opts.only.length > 0) {
+        const onlySet = new Set(opts.only);
+        result = new Set([...result].filter((k) => onlySet.has(k)));
+    }
+    return result;
+}
+export async function runCombined(db, opts) {
+    const analyses = resolveAnalyses(opts);
+    const ranAt = new Date().toISOString();
+    return { analyses, ranAt };
+}
+//# sourceMappingURL=combined.js.map

package/dist/src/analysis/combined.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"combined.js","sourceRoot":"","sources":["../../../src/analysis/combined.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,eAAe,CAAC,IAAqB;IACnD,IAAI,MAAM,GAAG,IAAI,GAAG,CAAe,CAAC,WAAW,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE3E,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAe,EACf,IAAqB;IAErB,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC"}

package/dist/src/analysis/corpus-health.d.ts

@@ -0,0 +1,14 @@
+export declare const CORPUS_WARN_MIN_WORDS = 50000;
+export declare const CORPUS_WARN_MAX_WORDS = 500000;
+export declare const CORPUS_WARN_MAX_FILES = 200;
+export interface CorpusStats {
+    wordCount: number;
+    fileCount: number;
+}
+export interface CorpusHealthResult {
+    healthy: boolean;
+    warnings: string[];
+    stats: CorpusStats;
+}
+export declare function checkCorpusHealth(stats: CorpusStats): CorpusHealthResult;
+//# sourceMappingURL=corpus-health.d.ts.map

package/dist/src/analysis/corpus-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-health.d.ts","sourceRoot":"","sources":["../../../src/analysis/corpus-health.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAC5C,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAC7C,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,kBAAkB,CAyBxE"}

package/dist/src/analysis/corpus-health.js

@@ -0,0 +1,20 @@
+export const CORPUS_WARN_MIN_WORDS = 50_000;
+export const CORPUS_WARN_MAX_WORDS = 500_000;
+export const CORPUS_WARN_MAX_FILES = 200;
+export function checkCorpusHealth(stats) {
+    const warnings = [];
+    if (stats.wordCount < CORPUS_WARN_MIN_WORDS) {
+        warnings.push(`Corpus too small: ${stats.wordCount.toLocaleString()} words (min ${CORPUS_WARN_MIN_WORDS.toLocaleString()}). ` +
+            `Results may be low-quality on toy projects.`);
+    }
+    if (stats.wordCount > CORPUS_WARN_MAX_WORDS) {
+        warnings.push(`Corpus too large: ${stats.wordCount.toLocaleString()} words (max ${CORPUS_WARN_MAX_WORDS.toLocaleString()}). ` +
+            `Consider using --code-only or filtering to a subset.`);
+    }
+    if (stats.fileCount > CORPUS_WARN_MAX_FILES) {
+        warnings.push(`Too many files: ${stats.fileCount} (max ${CORPUS_WARN_MAX_FILES}). ` +
+            `Consider using --ignore patterns to exclude generated or vendor files.`);
+    }
+    return { healthy: warnings.length === 0, warnings, stats };
+}
+//# sourceMappingURL=corpus-health.js.map

package/dist/src/analysis/corpus-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-health.js","sourceRoot":"","sources":["../../../src/analysis/corpus-health.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAazC,MAAM,UAAU,iBAAiB,CAAC,KAAkB;IAClD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,KAAK,CAAC,SAAS,GAAG,qBAAqB,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CACX,qBAAqB,KAAK,CAAC,SAAS,CAAC,cAAc,EAAE,eAAe,qBAAqB,CAAC,cAAc,EAAE,KAAK;YAC/G,6CAA6C,CAC9C,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,SAAS,GAAG,qBAAqB,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CACX,qBAAqB,KAAK,CAAC,SAAS,CAAC,cAAc,EAAE,eAAe,qBAAqB,CAAC,cAAc,EAAE,KAAK;YAC/G,sDAAsD,CACvD,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,SAAS,GAAG,qBAAqB,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CACX,mBAAmB,KAAK,CAAC,SAAS,SAAS,qBAAqB,KAAK;YACrE,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC7D,CAAC"}

package/dist/src/analysis/coverage-gaps.d.ts

@@ -0,0 +1,26 @@
+import type { MonographDb } from '../storage/db.js';
+export interface UntestedFile {
+    nodeId: string;
+    filePath: string;
+    reachabilityRole: string;
+    inDegree: number;
+    reason: string;
+}
+export interface UntestedExport {
+    nodeId: string;
+    name: string;
+    filePath: string | null;
+    startLine: number | null;
+    exportType: string;
+}
+export interface CoverageGapsResult {
+    untestedFiles: UntestedFile[];
+    untestedExports: UntestedExport[];
+    fileCoveragePct: number;
+    exportCoveragePct: number;
+    summary: string;
+}
+export declare function computeCoverageGaps(db: MonographDb): CoverageGapsResult;
+/** Format CoverageGapsResult as structured text with file:line hints for LLM navigation. */
+export declare function formatCoverageGaps(result: CoverageGapsResult, topN?: number): string;
+//# sourceMappingURL=coverage-gaps.d.ts.map

package/dist/src/analysis/coverage-gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gaps.d.ts","sourceRoot":"","sources":["../../../src/analysis/coverage-gaps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAyBD,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,kBAAkB,CA4JvE;AAED,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,SAAK,GAAG,MAAM,CAqChF"}