@monoes/monograph 1.1.0 → 1.2.1

package/dist/src/graph/maintainability.js

@@ -0,0 +1,119 @@
+function gradeFromMi(mi) {
+    if (mi > 85)
+        return 'A';
+    if (mi > 65)
+        return 'B';
+    if (mi > 50)
+        return 'C';
+    if (mi > 25)
+        return 'D';
+    return 'F';
+}
+export function computeMaintainabilityIndex(db) {
+    // Fetch all Function and Method Symbol nodes
+    const nodes = db.prepare(`
+    SELECT id, name, file_path, start_line, end_line, properties
+    FROM nodes
+    WHERE label IN ('Function', 'Method', 'Symbol')
+      AND start_line IS NOT NULL
+      AND end_line IS NOT NULL
+  `).all();
+    if (nodes.length === 0) {
+        return { results: [], averageMi: 100, lowMiCount: 0, criticalCount: 0 };
+    }
+    // ── Batch degree lookup: one query replaces 2×N individual queries ────────
+    // Combine in-degree and out-degree via UNION ALL + GROUP BY in a single pass.
+    const degreeMap = new Map();
+    for (const { node_id, deg } of db.prepare(`
+    SELECT node_id, SUM(cnt) as deg FROM (
+      SELECT target_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY target_id
+      UNION ALL
+      SELECT source_id AS node_id, COUNT(*) AS cnt FROM edges GROUP BY source_id
+    ) GROUP BY node_id
+  `).all()) {
+        degreeMap.set(node_id, deg);
+    }
+    const results = [];
+    const propUpdates = [];
+    for (const node of nodes) {
+        const loc = Math.max(1, node.end_line - node.start_line + 1);
+        const degree = degreeMap.get(node.id) ?? 0;
+        const hvProxy = degree * Math.log2(Math.max(degree, 2));
+        // Maintainability Index formula
+        const rawMi = 171 - 5.2 * Math.log(hvProxy + 1) - 0.23 * (loc / 10) - 16.2 * Math.log(Math.max(1, loc));
+        const mi = Math.max(0, Math.min(100, rawMi));
+        const grade = gradeFromMi(mi);
+        // Stage property update — batched below
+        const props = node.properties ? JSON.parse(node.properties) : {};
+        props.maintainabilityIndex = mi;
+        propUpdates.push({ id: node.id, props: JSON.stringify(props) });
+        results.push({
+            nodeId: node.id,
+            name: node.name,
+            filePath: node.file_path,
+            mi: Math.round(mi * 100) / 100,
+            grade,
+            halsteadVolume: Math.round(hvProxy * 100) / 100,
+            linesOfCode: loc,
+        });
+    }
+    // ── Batch UPDATE all property writes in one transaction ───────────────────
+    const updateStmt = db.prepare('UPDATE nodes SET properties = ? WHERE id = ?');
+    db.transaction((updates) => {
+        for (const { id, props } of updates)
+            updateStmt.run(props, id);
+    })(propUpdates);
+    // Sort by MI ascending (worst first)
+    results.sort((a, b) => a.mi - b.mi);
+    const averageMi = results.length > 0
+        ? results.reduce((sum, r) => sum + r.mi, 0) / results.length
+        : 100;
+    return {
+        results,
+        averageMi: Math.round(averageMi * 100) / 100,
+        lowMiCount: results.filter(r => r.mi < 65).length,
+        criticalCount: results.filter(r => r.mi < 25).length,
+    };
+}
+/**
+ * Format a MaintainabilityReport as structured text with file:line hints for LLM navigation.
+ *
+ * @param report - MaintainabilityReport from computeMaintainabilityIndex()
+ * @param topN - number of worst files to list (default 10)
+ * @returns structured text suitable for LLM consumption
+ */
+export function formatMaintainability(report, topN = 10) {
+    const { results, averageMi, lowMiCount, criticalCount } = report;
+    if (results.length === 0) {
+        return 'maintainability: no Function/Method/Symbol nodes with line info found\n';
+    }
+    const lines = [
+        `maintainability: ${results.length} nodes analysed`,
+        `  avg_mi: ${averageMi}  low(mi<65): ${lowMiCount}  critical(mi<25): ${criticalCount}`,
+        '',
+    ];
+    // results already sorted by MI ascending (worst first)
+    const worst = results.slice(0, topN);
+    if (worst.length > 0) {
+        lines.push(`top_${topN}_worst_mi:`);
+        for (const r of worst) {
+            const loc = r.filePath ? `${r.filePath}:1` : `<unknown>:1`;
+            lines.push(`  - ${r.name}  grade:${r.grade}  mi:${r.mi}`);
+            lines.push(`    file: ${loc}`);
+            lines.push(`    loc: ${r.linesOfCode}  halstead_vol: ${r.halsteadVolume}`);
+        }
+        lines.push('');
+    }
+    const critical = results.filter(r => r.mi < 25);
+    if (critical.length > 0) {
+        lines.push(`critical_nodes(mi<25): ${critical.length}`);
+        for (const r of critical.slice(0, 5)) {
+            const loc = r.filePath ? `${r.filePath}:1` : `<unknown>:1`;
+            lines.push(`  - ${r.name}  file: ${loc}  mi:${r.mi}  grade:${r.grade}`);
+        }
+        if (critical.length > 5)
+            lines.push(`  ... and ${critical.length - 5} more`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=maintainability.js.map

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

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

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

@@ -0,0 +1,51 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+export type MergeConflictStrategy = 
+/** Skip the incoming node/edge if one with the same id already exists (default). */
+'skip'
+/** Replace the existing node/edge with the incoming one. */
+ | 'replace';
+export interface GraphMergeOptions {
+    /** How to handle id collisions. Default: 'skip'. */
+    onConflict?: MergeConflictStrategy;
+}
+export interface GraphMergeResult {
+    nodesAdded: number;
+    nodesSkipped: number;
+    edgesAdded: number;
+    edgesSkipped: number;
+}
+/**
+ * Merge two sets of nodes and edges into a single deduplicated set.
+ *
+ * @param base   - The base graph (nodes + edges).
+ * @param incoming - The graph to merge in.
+ * @param options  - Conflict resolution strategy.
+ * @returns Merged nodes + edges, plus per-type counters.
+ */
+export declare function mergeGraphs(base: {
+    nodes: MonographNode[];
+    edges: MonographEdge[];
+}, incoming: {
+    nodes: MonographNode[];
+    edges: MonographEdge[];
+}, options?: GraphMergeOptions): {
+    nodes: MonographNode[];
+    edges: MonographEdge[];
+} & GraphMergeResult;
+/**
+ * Merge incoming nodes and edges into an existing MonographDb.
+ *
+ * Nodes are inserted via INSERT OR IGNORE (skip) or INSERT OR REPLACE (replace).
+ * Edges are handled the same way.
+ *
+ * @param targetDb  - The destination database.
+ * @param incoming  - The graph data to merge in.
+ * @param options   - Conflict resolution strategy.
+ * @returns Per-type counters.
+ */
+export declare function mergeGraphIntoDb(targetDb: MonographDb, incoming: {
+    nodes: MonographNode[];
+    edges: MonographEdge[];
+}, options?: GraphMergeOptions): GraphMergeResult;
+//# sourceMappingURL=merge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../../src/graph/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,MAAM,qBAAqB;AAC/B,oFAAoF;AAClF,MAAM;AACR,4DAA4D;GAC1D,SAAS,CAAC;AAEd,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE;IAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,EACxD,QAAQ,EAAE;IAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,EAC5D,OAAO,GAAE,iBAAsB,GAC9B;IAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GAAG,gBAAgB,CA+CvE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EACrB,QAAQ,EAAE;IAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,EAC5D,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAsElB"}

package/dist/src/graph/merge.js

@@ -0,0 +1,109 @@
+// ── In-memory merge ────────────────────────────────────────────────────────────
+/**
+ * Merge two sets of nodes and edges into a single deduplicated set.
+ *
+ * @param base   - The base graph (nodes + edges).
+ * @param incoming - The graph to merge in.
+ * @param options  - Conflict resolution strategy.
+ * @returns Merged nodes + edges, plus per-type counters.
+ */
+export function mergeGraphs(base, incoming, options = {}) {
+    const strategy = options.onConflict ?? 'skip';
+    const nodeMap = new Map(base.nodes.map(n => [n.id, n]));
+    const edgeMap = new Map(base.edges.map(e => [e.id, e]));
+    let nodesAdded = 0;
+    let nodesSkipped = 0;
+    let edgesAdded = 0;
+    let edgesSkipped = 0;
+    for (const node of incoming.nodes) {
+        if (nodeMap.has(node.id)) {
+            if (strategy === 'replace') {
+                nodeMap.set(node.id, node);
+                nodesAdded++;
+            }
+            else {
+                nodesSkipped++;
+            }
+        }
+        else {
+            nodeMap.set(node.id, node);
+            nodesAdded++;
+        }
+    }
+    for (const edge of incoming.edges) {
+        if (edgeMap.has(edge.id)) {
+            if (strategy === 'replace') {
+                edgeMap.set(edge.id, edge);
+                edgesAdded++;
+            }
+            else {
+                edgesSkipped++;
+            }
+        }
+        else {
+            edgeMap.set(edge.id, edge);
+            edgesAdded++;
+        }
+    }
+    return {
+        nodes: Array.from(nodeMap.values()),
+        edges: Array.from(edgeMap.values()),
+        nodesAdded,
+        nodesSkipped,
+        edgesAdded,
+        edgesSkipped,
+    };
+}
+// ── DB-backed merge ────────────────────────────────────────────────────────────
+/**
+ * Merge incoming nodes and edges into an existing MonographDb.
+ *
+ * Nodes are inserted via INSERT OR IGNORE (skip) or INSERT OR REPLACE (replace).
+ * Edges are handled the same way.
+ *
+ * @param targetDb  - The destination database.
+ * @param incoming  - The graph data to merge in.
+ * @param options   - Conflict resolution strategy.
+ * @returns Per-type counters.
+ */
+export function mergeGraphIntoDb(targetDb, incoming, options = {}) {
+    const strategy = options.onConflict ?? 'skip';
+    const orClause = strategy === 'replace' ? 'OR REPLACE' : 'OR IGNORE';
+    const insertNode = targetDb.prepare(`INSERT ${orClause} INTO nodes
+       (id, label, name, norm_label, file_path, start_line, end_line, community_id, is_exported, language, properties)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertEdge = targetDb.prepare(`INSERT ${orClause} INTO edges
+       (id, source_id, target_id, relation, confidence, confidence_score, reason, evidence)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    let nodesAdded = 0;
+    let nodesSkipped = 0;
+    let edgesAdded = 0;
+    let edgesSkipped = 0;
+    const nodeExists = targetDb.prepare('SELECT 1 FROM nodes WHERE id = ?');
+    const edgeExists = targetDb.prepare('SELECT 1 FROM edges WHERE id = ?');
+    const mergeAll = targetDb.transaction(() => {
+        for (const n of incoming.nodes) {
+            const exists = !!nodeExists.get(n.id);
+            insertNode.run(n.id, n.label, n.name, n.normLabel, n.filePath ?? null, n.startLine ?? null, n.endLine ?? null, n.communityId ?? null, n.isExported ? 1 : 0, n.language ?? null, n.properties ? JSON.stringify(n.properties) : null);
+            if (exists) {
+                strategy === 'replace' ? nodesAdded++ : nodesSkipped++;
+            }
+            else {
+                nodesAdded++;
+            }
+        }
+        for (const e of incoming.edges) {
+            const exists = !!edgeExists.get(e.id);
+            insertEdge.run(e.id, e.sourceId, e.targetId, e.relation, e.confidence, e.confidenceScore, e.reason ?? null, null);
+            if (exists) {
+                strategy === 'replace' ? edgesAdded++ : edgesSkipped++;
+            }
+            else {
+                edgesAdded++;
+            }
+        }
+    });
+    mergeAll();
+    return { nodesAdded, nodesSkipped, edgesAdded, edgesSkipped };
+}
+//# sourceMappingURL=merge.js.map

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

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

package/dist/src/graph/mirrored-dirs.d.ts

@@ -0,0 +1,32 @@
+import type { MonographDb } from '../storage/db.js';
+import type { CloneFamily } from '../graph/clone-families.js';
+export interface MirroredDirPair {
+    dirA: string;
+    dirB: string;
+    similarity: number;
+    sharedFileNames: string[];
+    uniqueToA: number;
+    uniqueToB: number;
+}
+export interface MirroredDirsReport {
+    pairs: MirroredDirPair[];
+    totalDirsAnalyzed: number;
+}
+/**
+ * Detect directory subtrees that are structural mirrors of each other.
+ * Uses Jaccard similarity of file basenames within each directory.
+ *
+ * @param db - monograph database
+ * @param minSimilarity - minimum Jaccard similarity threshold (default 0.7)
+ */
+export declare function detectMirroredDirs(db: MonographDb, minSimilarity?: number): MirroredDirsReport;
+export interface MirroredDirResult {
+    mirrored: MirroredDirPair[];
+    remaining: CloneFamily[];
+}
+export declare function detectMirroredFamilies(families: CloneFamily[], root: string): MirroredDirResult;
+/**
+ * Format a MirroredDirsReport as structured text for LLM consumption.
+ */
+export declare function formatMirroredDirs(report: MirroredDirsReport): string;
+//# sourceMappingURL=mirrored-dirs.d.ts.map

package/dist/src/graph/mirrored-dirs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirrored-dirs.d.ts","sourceRoot":"","sources":["../../../src/graph/mirrored-dirs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,WAAW,EAAE,aAAa,SAAM,GAAG,kBAAkB,CAmE3F;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,WAAW,EAAE,EACvB,IAAI,EAAE,MAAM,GACX,iBAAiB,CAiFnB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAcrE"}

package/dist/src/graph/mirrored-dirs.js

@@ -0,0 +1,167 @@
+/**
+ * Detect directory subtrees that are structural mirrors of each other.
+ * Uses Jaccard similarity of file basenames within each directory.
+ *
+ * @param db - monograph database
+ * @param minSimilarity - minimum Jaccard similarity threshold (default 0.7)
+ */
+export function detectMirroredDirs(db, minSimilarity = 0.7) {
+    // Query all File nodes with a file_path
+    const rows = db.prepare(`SELECT file_path FROM nodes WHERE label = 'File' AND file_path IS NOT NULL`).all();
+    // Build map: dirPath → Set<basename>
+    const dirMap = new Map();
+    for (const { file_path } of rows) {
+        const lastSlash = Math.max(file_path.lastIndexOf('/'), file_path.lastIndexOf('\\'));
+        if (lastSlash === -1)
+            continue;
+        const dir = file_path.slice(0, lastSlash);
+        const base = file_path.slice(lastSlash + 1);
+        if (!dirMap.has(dir))
+            dirMap.set(dir, new Set());
+        dirMap.get(dir).add(base);
+    }
+    const dirs = [...dirMap.keys()];
+    const pairs = [];
+    // Compare each pair of directories
+    for (let i = 0; i < dirs.length; i++) {
+        for (let j = i + 1; j < dirs.length; j++) {
+            const dirA = dirs[i];
+            const dirB = dirs[j];
+            const setA = dirMap.get(dirA);
+            const setB = dirMap.get(dirB);
+            // Only compare directories that share a parent OR one is a suffix of the other
+            const parentA = dirA.slice(0, Math.max(dirA.lastIndexOf('/'), dirA.lastIndexOf('\\')));
+            const parentB = dirB.slice(0, Math.max(dirB.lastIndexOf('/'), dirB.lastIndexOf('\\')));
+            const relatedDirs = parentA === parentB
+                || dirA.endsWith(dirB)
+                || dirB.endsWith(dirA)
+                || dirA.includes(dirB)
+                || dirB.includes(dirA);
+            if (!relatedDirs)
+                continue;
+            // Compute Jaccard similarity
+            const shared = [];
+            for (const name of setA) {
+                if (setB.has(name))
+                    shared.push(name);
+            }
+            const union = setA.size + setB.size - shared.length;
+            if (union === 0)
+                continue;
+            const similarity = shared.length / union;
+            if (similarity >= minSimilarity) {
+                pairs.push({
+                    dirA,
+                    dirB,
+                    similarity,
+                    sharedFileNames: shared.sort(),
+                    uniqueToA: setA.size - shared.length,
+                    uniqueToB: setB.size - shared.length,
+                });
+            }
+        }
+    }
+    // Sort by similarity descending
+    pairs.sort((a, b) => b.similarity - a.similarity);
+    return {
+        pairs,
+        totalDirsAnalyzed: dirs.length,
+    };
+}
+export function detectMirroredFamilies(families, root) {
+    const normalizedRoot = root.replace(/\\/g, '/').replace(/\/$/, '');
+    function dirOf(filePath) {
+        const normalized = filePath.replace(/\\/g, '/');
+        const rel = normalized.startsWith(normalizedRoot + '/')
+            ? normalized.slice(normalizedRoot.length + 1)
+            : normalized;
+        const lastSlash = rel.lastIndexOf('/');
+        return lastSlash === -1 ? '' : rel.slice(0, lastSlash);
+    }
+    function baseName(filePath) {
+        const normalized = filePath.replace(/\\/g, '/');
+        return normalized.slice(normalized.lastIndexOf('/') + 1);
+    }
+    const mirrored = [];
+    const remainingIndices = new Set(families.map((_, i) => i));
+    for (let i = 0; i < families.length; i++) {
+        for (let j = i + 1; j < families.length; j++) {
+            if (!remainingIndices.has(i) || !remainingIndices.has(j))
+                continue;
+            const fa = families[i];
+            const fb = families[j];
+            // Single pass: extract dir and basename together to avoid two separate .map() iterations
+            let firstDirA;
+            let singleDirA = true;
+            let firstDirB;
+            let singleDirB = true;
+            const namesA = new Set();
+            const namesB = new Set();
+            for (const f of fa.files) {
+                const d = dirOf(f);
+                if (firstDirA === undefined)
+                    firstDirA = d;
+                else if (d !== firstDirA) {
+                    singleDirA = false;
+                }
+                namesA.add(baseName(f));
+            }
+            for (const f of fb.files) {
+                const d = dirOf(f);
+                if (firstDirB === undefined)
+                    firstDirB = d;
+                else if (d !== firstDirB) {
+                    singleDirB = false;
+                }
+                namesB.add(baseName(f));
+            }
+            if (!singleDirA || !singleDirB)
+                continue;
+            const dirA = firstDirA;
+            const dirB = firstDirB;
+            const shared = [];
+            for (const n of namesA) {
+                if (namesB.has(n))
+                    shared.push(n);
+            }
+            const union = namesA.size + namesB.size - shared.length;
+            if (union === 0)
+                continue;
+            const similarity = shared.length / union;
+            if (similarity >= 0.5) {
+                mirrored.push({
+                    dirA,
+                    dirB,
+                    similarity,
+                    sharedFileNames: shared.sort(),
+                    uniqueToA: namesA.size - shared.length,
+                    uniqueToB: namesB.size - shared.length,
+                });
+                remainingIndices.delete(i);
+                remainingIndices.delete(j);
+            }
+        }
+    }
+    mirrored.sort((a, b) => b.similarity - a.similarity);
+    const remaining = [];
+    for (const i of remainingIndices)
+        remaining.push(families[i]);
+    return { mirrored, remaining };
+}
+/**
+ * Format a MirroredDirsReport as structured text for LLM consumption.
+ */
+export function formatMirroredDirs(report) {
+    if (report.pairs.length === 0) {
+        return `No mirrored directories found (${report.totalDirsAnalyzed} dirs analyzed).`;
+    }
+    const lines = [
+        `Mirrored directories: ${report.pairs.length} pair(s) of ${report.totalDirsAnalyzed} analyzed`,
+        '',
+    ];
+    for (const p of report.pairs) {
+        lines.push(`  ${p.dirA} <-> ${p.dirB}  similarity=${(p.similarity * 100).toFixed(0)}%  shared=${p.sharedFileNames.length}  uniqueA=${p.uniqueToA}  uniqueB=${p.uniqueToB}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=mirrored-dirs.js.map

package/dist/src/graph/mirrored-dirs.js.map

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

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

@@ -0,0 +1,24 @@
+export interface AccessedMembers {
+    members: Set<string>;
+    hasNamespaceAccess: boolean;
+}
+export declare function isUnusedImportBinding(importedName: string, accessedMembers: Set<string>): boolean;
+export declare function extractAccessedMembers(usages: string[]): AccessedMembers;
+export declare function markAllExportsReferenced(exports: string[]): Set<string>;
+export declare function markMemberExportsReferenced(exports: string[], accessed: AccessedMembers): Set<string>;
+export interface NarrowingReport {
+    filePath: string;
+    totalExports: number;
+    referencedExports: string[];
+    unusedExports: string[];
+}
+/**
+ * Given a file's exports and the accessed members from all import sites,
+ * return a report of which exports are unused.
+ */
+export declare function filterUnusedExports(filePath: string, exports: string[], accessed: AccessedMembers): NarrowingReport;
+/**
+ * Format narrowing reports as structured text for LLM dead-import diagnostics.
+ */
+export declare function formatNarrowingReport(reports: NarrowingReport[]): string;
+//# sourceMappingURL=narrowing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"narrowing.d.ts","sourceRoot":"","sources":["../../../src/graph/narrowing.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,OAAO,CAET;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAexE;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAEvE;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,eAAe,GACxB,GAAG,CAAC,MAAM,CAAC,CAWb;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,eAAe,GACxB,eAAe,CAYjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAUxE"}

package/dist/src/graph/narrowing.js

@@ -0,0 +1,68 @@
+export function isUnusedImportBinding(importedName, accessedMembers) {
+    return !accessedMembers.has(importedName);
+}
+export function extractAccessedMembers(usages) {
+    const members = new Set();
+    let hasNamespaceAccess = false;
+    for (const usage of usages) {
+        const dotIdx = usage.indexOf('.');
+        if (dotIdx === -1) {
+            hasNamespaceAccess = true;
+        }
+        else {
+            const member = usage.slice(dotIdx + 1);
+            if (member)
+                members.add(member);
+        }
+    }
+    return { members, hasNamespaceAccess };
+}
+export function markAllExportsReferenced(exports) {
+    return new Set(exports);
+}
+export function markMemberExportsReferenced(exports, accessed) {
+    if (accessed.hasNamespaceAccess) {
+        return new Set(exports);
+    }
+    const result = new Set();
+    for (const exp of exports) {
+        if (accessed.members.has(exp)) {
+            result.add(exp);
+        }
+    }
+    return result;
+}
+/**
+ * Given a file's exports and the accessed members from all import sites,
+ * return a report of which exports are unused.
+ */
+export function filterUnusedExports(filePath, exports, accessed) {
+    const referenced = markMemberExportsReferenced(exports, accessed);
+    const unusedExports = [];
+    for (const exp of exports) {
+        if (!referenced.has(exp))
+            unusedExports.push(exp);
+    }
+    return {
+        filePath,
+        totalExports: exports.length,
+        referencedExports: Array.from(referenced),
+        unusedExports,
+    };
+}
+/**
+ * Format narrowing reports as structured text for LLM dead-import diagnostics.
+ */
+export function formatNarrowingReport(reports) {
+    const withUnused = reports.filter(r => r.unusedExports.length > 0);
+    if (withUnused.length === 0)
+        return 'No unused exports found.';
+    const lines = [`Unused exports in ${withUnused.length} file(s):`, ''];
+    for (const r of withUnused) {
+        lines.push(`  ${r.filePath} (${r.unusedExports.length}/${r.totalExports} unused)`);
+        for (const exp of r.unusedExports)
+            lines.push(`    - ${exp}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=narrowing.js.map

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

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

package/dist/src/graph/node-search.d.ts

@@ -0,0 +1,31 @@
+import type { MonographNode, NodeLabel } from '../types.js';
+import type { MonographDb } from '../storage/db.js';
+export interface NodeSearchOptions {
+    /** Filter by node label (e.g. 'Function', 'Class'). */
+    label?: NodeLabel;
+    /** Filter by programming language (case-insensitive). */
+    language?: string;
+    /** Filter by file extension, e.g. '.ts', 'ts' (leading dot optional). */
+    fileExtension?: string;
+    /** Filter by file path substring (case-insensitive). */
+    filePath?: string;
+    /** Only return exported nodes. */
+    isExported?: boolean;
+    /** Only return nodes inside this community. */
+    communityId?: number;
+    /** Maximum number of results (default: no limit). */
+    limit?: number;
+}
+/**
+ * Search nodes by structured property criteria.
+ * All supplied criteria are combined with AND.
+ *
+ * Prepared statements are cached per-DB keyed by the active condition set so
+ * repeated calls with the same filter shape reuse the compiled statement.
+ */
+export declare function searchNodesByProperty(db: MonographDb, options?: NodeSearchOptions): MonographNode[];
+/**
+ * Filter an already-loaded array of nodes in memory.
+ */
+export declare function searchNodesInMemory(nodes: MonographNode[], options?: NodeSearchOptions): MonographNode[];
+//# sourceMappingURL=node-search.d.ts.map