@monoes/monograph 1.0.0 → 1.2.0

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

@@ -0,0 +1,132 @@
+/**
+ * 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];
+            const dirsA = new Set(fa.files.map(dirOf));
+            const dirsB = new Set(fb.files.map(dirOf));
+            if (dirsA.size !== 1 || dirsB.size !== 1)
+                continue;
+            const [dirA] = dirsA;
+            const [dirB] = dirsB;
+            if (dirA === dirB)
+                continue;
+            const namesA = new Set(fa.files.map(baseName));
+            const namesB = new Set(fb.files.map(baseName));
+            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);
+    return {
+        mirrored,
+        remaining: [...remainingIndices].map(i => families[i]),
+    };
+}
+//# 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,9 @@
+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>;
+//# 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"}

package/dist/src/graph/narrowing.js

@@ -0,0 +1,35 @@
+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;
+}
+//# 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":"AAKA,MAAM,UAAU,qBAAqB,CACnC,YAAoB,EACpB,eAA4B;IAE5B,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAgB;IACrD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,kBAAkB,GAAG,IAAI,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACvC,IAAI,MAAM;gBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAiB;IACxD,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,OAAiB,EACjB,QAAyB;IAEzB,IAAI,QAAQ,CAAC,kBAAkB,EAAE,CAAC;QAChC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,28 @@
+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.
+ */
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"node-search.d.ts","sourceRoot":"","sources":["../../../src/graph/node-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkCD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,WAAW,EACf,OAAO,GAAE,iBAAsB,GAC9B,aAAa,EAAE,CA8CjB;AAID;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EAAE,EACtB,OAAO,GAAE,iBAAsB,GAC9B,aAAa,EAAE,CAqCjB"}

package/dist/src/graph/node-search.js

@@ -0,0 +1,95 @@
+// ── Row → node mapper (mirrors subgraph.ts) ───────────────────────────────────
+function rowToNode(r) {
+    return {
+        id: r.id,
+        label: r.label,
+        name: r.name,
+        normLabel: r.norm_label ?? r.name.toLowerCase(),
+        filePath: r.file_path ?? undefined,
+        startLine: r.start_line ?? undefined,
+        endLine: r.end_line ?? undefined,
+        communityId: r.community_id ?? undefined,
+        isExported: r.is_exported === 1,
+        language: r.language ?? undefined,
+        properties: r.properties ? JSON.parse(r.properties) : undefined,
+    };
+}
+// ── DB-backed search ───────────────────────────────────────────────────────────
+/**
+ * Search nodes by structured property criteria.
+ * All supplied criteria are combined with AND.
+ */
+export function searchNodesByProperty(db, options = {}) {
+    const conditions = [];
+    const params = [];
+    if (options.label) {
+        conditions.push('label = ?');
+        params.push(options.label);
+    }
+    if (options.language) {
+        conditions.push('LOWER(language) = LOWER(?)');
+        params.push(options.language);
+    }
+    if (options.fileExtension !== undefined) {
+        // Normalise: ensure leading dot
+        const ext = options.fileExtension.startsWith('.')
+            ? options.fileExtension
+            : `.${options.fileExtension}`;
+        conditions.push("file_path LIKE ?");
+        params.push(`%${ext}`);
+    }
+    if (options.filePath !== undefined) {
+        conditions.push("LOWER(file_path) LIKE LOWER(?)");
+        params.push(`%${options.filePath}%`);
+    }
+    if (options.isExported !== undefined) {
+        conditions.push('is_exported = ?');
+        params.push(options.isExported ? 1 : 0);
+    }
+    if (options.communityId !== undefined) {
+        conditions.push('community_id = ?');
+        params.push(options.communityId);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const limitClause = options.limit !== undefined ? `LIMIT ${Number(options.limit)}` : '';
+    const sql = `SELECT id, label, name, norm_label, file_path, start_line, end_line,
+                      community_id, is_exported, language, properties
+               FROM nodes ${where} ${limitClause}`;
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToNode);
+}
+// ── In-memory search ───────────────────────────────────────────────────────────
+/**
+ * Filter an already-loaded array of nodes in memory.
+ */
+export function searchNodesInMemory(nodes, options = {}) {
+    let result = nodes;
+    if (options.label) {
+        result = result.filter(n => n.label === options.label);
+    }
+    if (options.language) {
+        const lang = options.language.toLowerCase();
+        result = result.filter(n => n.language?.toLowerCase() === lang);
+    }
+    if (options.fileExtension !== undefined) {
+        const ext = options.fileExtension.startsWith('.')
+            ? options.fileExtension.toLowerCase()
+            : `.${options.fileExtension.toLowerCase()}`;
+        result = result.filter(n => n.filePath?.toLowerCase().endsWith(ext));
+    }
+    if (options.filePath !== undefined) {
+        const fp = options.filePath.toLowerCase();
+        result = result.filter(n => n.filePath?.toLowerCase().includes(fp));
+    }
+    if (options.isExported !== undefined) {
+        result = result.filter(n => n.isExported === options.isExported);
+    }
+    if (options.communityId !== undefined) {
+        result = result.filter(n => n.communityId === options.communityId);
+    }
+    if (options.limit !== undefined) {
+        result = result.slice(0, options.limit);
+    }
+    return result;
+}
+//# sourceMappingURL=node-search.js.map

package/dist/src/graph/node-search.js.map

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

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

@@ -0,0 +1,42 @@
+export type ReferenceKind = 'Value' | 'Type' | 'Namespace' | 'Unknown';
+export interface ExportSymbol {
+    name: string;
+    isType: boolean;
+    isReExport: boolean;
+    line?: number;
+}
+export interface ReExportEdge {
+    fromFile: string;
+    toFile: string;
+    symbol?: string;
+    isNamespace: boolean;
+}
+export interface SymbolReference {
+    name: string;
+    kind: ReferenceKind;
+    fromFile: string;
+    line?: number;
+}
+export declare const ModuleNodeFlags: {
+    readonly ENTRY_POINT: 1;
+    readonly REACHABLE: 2;
+    readonly RUNTIME_REACHABLE: 4;
+    readonly TEST_REACHABLE: 8;
+    readonly CJS_EXPORTS: 16;
+};
+export interface ModuleNode {
+    fileId: number;
+    filePath: string;
+    flags: number;
+    exports: ExportSymbol[];
+    reExports: ReExportEdge[];
+    references: SymbolReference[];
+}
+export declare function isEntryPoint(node: ModuleNode): boolean;
+export declare function isReachable(node: ModuleNode): boolean;
+export declare function isRuntimeReachable(node: ModuleNode): boolean;
+export declare function isTestReachable(node: ModuleNode): boolean;
+export declare function hasCjsExports(node: ModuleNode): boolean;
+export declare function setFlag(node: ModuleNode, flag: number): void;
+export declare function clearFlag(node: ModuleNode, flag: number): void;
+//# sourceMappingURL=node-types.d.ts.map

package/dist/src/graph/node-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-types.d.ts","sourceRoot":"","sources":["../../../src/graph/node-types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,eAAe;;;;;;CAMlB,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAEtD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAErD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAE5D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAEzD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAEvD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9D"}

package/dist/src/graph/node-types.js

@@ -0,0 +1,29 @@
+export const ModuleNodeFlags = {
+    ENTRY_POINT: 1,
+    REACHABLE: 2,
+    RUNTIME_REACHABLE: 4,
+    TEST_REACHABLE: 8,
+    CJS_EXPORTS: 16,
+};
+export function isEntryPoint(node) {
+    return (node.flags & ModuleNodeFlags.ENTRY_POINT) !== 0;
+}
+export function isReachable(node) {
+    return (node.flags & ModuleNodeFlags.REACHABLE) !== 0;
+}
+export function isRuntimeReachable(node) {
+    return (node.flags & ModuleNodeFlags.RUNTIME_REACHABLE) !== 0;
+}
+export function isTestReachable(node) {
+    return (node.flags & ModuleNodeFlags.TEST_REACHABLE) !== 0;
+}
+export function hasCjsExports(node) {
+    return (node.flags & ModuleNodeFlags.CJS_EXPORTS) !== 0;
+}
+export function setFlag(node, flag) {
+    node.flags |= flag;
+}
+export function clearFlag(node, flag) {
+    node.flags &= ~flag;
+}
+//# sourceMappingURL=node-types.js.map

package/dist/src/graph/node-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-types.js","sourceRoot":"","sources":["../../../src/graph/node-types.ts"],"names":[],"mappings":"AAuBA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,CAAC;IACZ,iBAAiB,EAAE,CAAC;IACpB,cAAc,EAAE,CAAC;IACjB,WAAW,EAAE,EAAE;CACP,CAAC;AAWX,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAgB;IAC9C,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAgB;IAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAgB,EAAE,IAAY;IACpD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAgB,EAAE,IAAY;IACtD,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC;AACtB,CAAC"}

package/dist/src/graph/normalize-id.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Normalized-ID edge reconciliation.
+ *
+ * Mirrors graphify's `_normalize_id` / `norm_to_id` logic:
+ * when an LLM-generated edge endpoint ID does not exactly match any node ID
+ * in the graph, we try a normalized form (lowercase, non-alphanumeric → '_').
+ * This lets edges survive across minor casing / punctuation mismatches between
+ * the AST extractor and the LLM.
+ */
+/**
+ * Normalise an ID string the same way graphify's `_normalize_id` does.
+ *
+ * Replaces all runs of non-alphanumeric characters with a single underscore,
+ * strips leading/trailing underscores, and lowercases the result.
+ *
+ * @example
+ * normalizeId('Session_ValidateToken') // 'session_validatetoken'
+ * normalizeId('My-Class::method')      // 'my_class_method'
+ */
+export declare function normalizeId(id: string): string;
+/**
+ * Build a Map from normalised id → canonical id from a set of known node ids.
+ * Used during edge reconciliation to remap mismatched endpoints.
+ *
+ * @param nodeIds - The authoritative set of node ids.
+ * @returns Map of `normalizeId(id)` → original `id`.
+ */
+export declare function buildNormToIdMap(nodeIds: Iterable<string>): Map<string, string>;
+export interface RawEdge {
+    source: string;
+    target: string;
+    [key: string]: unknown;
+}
+export interface ReconciliationResult {
+    /** Edges whose endpoints were resolved (possibly with normalization). */
+    resolved: RawEdge[];
+    /** Edges that could not be matched even after normalization. */
+    dangling: RawEdge[];
+    /** Number of edges that required normalization to resolve. */
+    remappedCount: number;
+}
+/**
+ * Reconcile a list of raw edges against a known set of node ids.
+ *
+ * For each edge:
+ * 1. If both endpoints are in `nodeIds` → resolved as-is.
+ * 2. If an endpoint is missing, try `normalizeId(endpoint)` lookup.
+ * 3. If still missing → moved to `dangling` (not added to the graph).
+ *
+ * Mutates `source`/`target` fields on resolved edges in-place when remapping.
+ */
+export declare function reconcileEdges(edges: RawEdge[], nodeIds: Set<string>): ReconciliationResult;
+//# sourceMappingURL=normalize-id.d.ts.map

package/dist/src/graph/normalize-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-id.d.ts","sourceRoot":"","sources":["../../../src/graph/normalize-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAK9C;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM/E;AAID,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,gEAAgE;IAChE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GACnB,oBAAoB,CAqCtB"}

package/dist/src/graph/normalize-id.js

@@ -0,0 +1,86 @@
+/**
+ * Normalized-ID edge reconciliation.
+ *
+ * Mirrors graphify's `_normalize_id` / `norm_to_id` logic:
+ * when an LLM-generated edge endpoint ID does not exactly match any node ID
+ * in the graph, we try a normalized form (lowercase, non-alphanumeric → '_').
+ * This lets edges survive across minor casing / punctuation mismatches between
+ * the AST extractor and the LLM.
+ */
+// ── Core normaliser ────────────────────────────────────────────────────────────
+/**
+ * Normalise an ID string the same way graphify's `_normalize_id` does.
+ *
+ * Replaces all runs of non-alphanumeric characters with a single underscore,
+ * strips leading/trailing underscores, and lowercases the result.
+ *
+ * @example
+ * normalizeId('Session_ValidateToken') // 'session_validatetoken'
+ * normalizeId('My-Class::method')      // 'my_class_method'
+ */
+export function normalizeId(id) {
+    return id
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}
+// ── Lookup map builder ─────────────────────────────────────────────────────────
+/**
+ * Build a Map from normalised id → canonical id from a set of known node ids.
+ * Used during edge reconciliation to remap mismatched endpoints.
+ *
+ * @param nodeIds - The authoritative set of node ids.
+ * @returns Map of `normalizeId(id)` → original `id`.
+ */
+export function buildNormToIdMap(nodeIds) {
+    const map = new Map();
+    for (const id of nodeIds) {
+        map.set(normalizeId(id), id);
+    }
+    return map;
+}
+/**
+ * Reconcile a list of raw edges against a known set of node ids.
+ *
+ * For each edge:
+ * 1. If both endpoints are in `nodeIds` → resolved as-is.
+ * 2. If an endpoint is missing, try `normalizeId(endpoint)` lookup.
+ * 3. If still missing → moved to `dangling` (not added to the graph).
+ *
+ * Mutates `source`/`target` fields on resolved edges in-place when remapping.
+ */
+export function reconcileEdges(edges, nodeIds) {
+    const normToId = buildNormToIdMap(nodeIds);
+    const resolved = [];
+    const dangling = [];
+    let remappedCount = 0;
+    for (const edge of edges) {
+        let src = edge.source;
+        let tgt = edge.target;
+        let remapped = false;
+        if (!nodeIds.has(src)) {
+            const canonical = normToId.get(normalizeId(src));
+            if (canonical) {
+                src = canonical;
+                remapped = true;
+            }
+        }
+        if (!nodeIds.has(tgt)) {
+            const canonical = normToId.get(normalizeId(tgt));
+            if (canonical) {
+                tgt = canonical;
+                remapped = true;
+            }
+        }
+        if (nodeIds.has(src) && nodeIds.has(tgt)) {
+            resolved.push({ ...edge, source: src, target: tgt });
+            if (remapped)
+                remappedCount++;
+        }
+        else {
+            dangling.push(edge);
+        }
+    }
+    return { resolved, dangling, remappedCount };
+}
+//# sourceMappingURL=normalize-id.js.map

package/dist/src/graph/normalize-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-id.js","sourceRoot":"","sources":["../../../src/graph/normalize-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kFAAkF;AAElF;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,EAAE;SACN,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,kFAAkF;AAElF;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAyB;IACxD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAmBD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAgB,EAChB,OAAoB;IAEpB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAE3C,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,aAAa,GAAG,CAAC,CAAC;IAEtB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YACjD,IAAI,SAAS,EAAE,CAAC;gBACd,GAAG,GAAG,SAAS,CAAC;gBAChB,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YACjD,IAAI,SAAS,EAAE,CAAC;gBACd,GAAG,GAAG,SAAS,CAAC;gBAChB,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YACrD,IAAI,QAAQ;gBAAE,aAAa,EAAE,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AAC/C,CAAC"}

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

@@ -0,0 +1,22 @@
+import type { MonographDb } from '../storage/db.js';
+export interface PageRankOptions {
+    /** Damping factor (probability of following an edge). Default: 0.85 */
+    dampingFactor?: number;
+    /** Maximum number of power-iteration steps. Default: 100 */
+    maxIterations?: number;
+    /** Convergence threshold (L1 norm delta). Default: 1e-6 */
+    tolerance?: number;
+}
+/**
+ * Compute PageRank scores for all nodes using power iteration.
+ *
+ * Each node's score is initialized to 1/N (so scores sum to 1).
+ * After convergence the scores still sum to ~1 (standard normalized PageRank).
+ * Dangling nodes (out-degree 0) distribute their rank equally to all nodes.
+ *
+ * @param db - The MonographDb instance
+ * @param options - Optional tuning parameters
+ * @returns Map of nodeId → PageRank score
+ */
+export declare function pageRank(db: MonographDb, options?: PageRankOptions): Map<string, number>;
+//# sourceMappingURL=pagerank.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pagerank.d.ts","sourceRoot":"","sources":["../../../src/graph/pagerank.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,GAAE,eAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiE5F"}