devlensio 0.2.0

package/dist/pipeline/index.js

@@ -0,0 +1,249 @@
+import path from "path";
+import { createHash } from "crypto";
+import { execSync } from "child_process";
+import { analyzeFingerprint } from "../fingerprint/index.js";
+import { analyzeFilesystem } from "../filesystem/index.js";
+import { parseRepo } from "../parser/index.js";
+import { detectEdges } from "../graph/index.js";
+import { buildThirdPartyNodes } from "../graph/thirdPartyLibs.js";
+import { scoreAndFilter } from "../scoring/index.js";
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+// Deterministic graphId — same repo always produces same id
+// This ensures multiple analyses of the same repo go into the same folder
+function generateGraphId(repoPath, isGithubRepo) {
+    const normalized = isGithubRepo
+        ? repoPath.toLowerCase().trim() // normalize GitHub URL
+        : path.resolve(repoPath).toLowerCase(); // normalize local path
+    return createHash("sha256")
+        .update(normalized)
+        .digest("hex")
+        .slice(0, 16);
+}
+// Gets current git state of the repo
+// Falls back gracefully if git is not initialized
+function getGitInfo(repoPath) {
+    try {
+        const commitHash = execSync("git rev-parse HEAD", { cwd: repoPath })
+            .toString().trim();
+        const branch = execSync("git rev-parse --abbrev-ref HEAD", { cwd: repoPath })
+            .toString().trim();
+        const message = execSync("git log -1 --pretty=%s", { cwd: repoPath })
+            .toString().trim();
+        return { commitHash, branch, message, hasGit: true };
+    }
+    catch {
+        // No git, or no commits yet — use timestamp as version key
+        return {
+            commitHash: Date.now().toString(),
+            branch: "unknown",
+            message: "no git history",
+            hasGit: false,
+        };
+    }
+}
+function buildStats(scoringResult, allNodes) {
+    const topScoringFiles = allNodes
+        .filter((n) => n.type === "FILE")
+        .map((n) => ({
+        name: n.name,
+        score: scoringResult.nodeScores.get(n.id) ?? 0,
+        filePath: n.filePath,
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 10);
+    return {
+        ...scoringResult.stats,
+        topScoringFiles,
+    };
+}
+function mapToRecord(map) {
+    const record = {};
+    for (const [k, v] of map)
+        record[k] = v;
+    return record;
+}
+//  routesToCodeNodes 
+//
+// Converts RouteNode[] / BackendRouteNode[] into ROUTE CodeNodes so they
+// participate in the graph as first-class nodes.
+//
+// Route-specific fields go into metadata — CodeNode schema stays clean.
+// IDs follow the same filePath::name convention as all other nodes so
+// the lookup maps in buildLookupMaps() work without any changes.
+//
+// Naming convention:
+//   Next.js page/layout/API:  "GET /api/users"  → id = "app/api/users/route.ts::GET /api/users"
+//   Backend (Express etc.):   "POST /users"      → id = "src/routes/users.ts::POST /users"
+function routesToCodeNodes(routes, repoPath) {
+    const nodes = [];
+    for (const route of routes) {
+        // Make filePath relative — same as parser does for all other nodes
+        const relativeFilePath = path.relative(repoPath, route.filePath).replace(/\\/g, "/");
+        if (route.type === "BACKEND_ROUTE") {
+            // Each backend route = one node per HTTP method + path combination
+            const name = `${route.httpMethod} ${route.urlPath}`;
+            const id = `${relativeFilePath}::${name}`;
+            // create synthetic function type nodes for the inline handlers
+            let inlineHandlerId;
+            if (route.inlineHandler) {
+                inlineHandlerId = `${relativeFilePath}::${name}::handler`;
+                nodes.push({
+                    id: inlineHandlerId,
+                    name: `${name} handler`,
+                    type: "FUNCTION",
+                    filePath: relativeFilePath,
+                    startLine: route.inlineHandler.startLine,
+                    endLine: route.inlineHandler.endLine,
+                    rawCode: route.inlineHandler.rawCode,
+                    codeHash: createHash("sha256").update(route.inlineHandler.rawCode).digest("hex").slice(0, 16),
+                    parentFile: `file::${relativeFilePath}`,
+                    metadata: {
+                        isHttpHandler: true,
+                        httpMethod: route.httpMethod,
+                        isInlineHandler: true,
+                    },
+                });
+            }
+            nodes.push({
+                id,
+                name,
+                type: "ROUTE",
+                filePath: relativeFilePath,
+                startLine: 1,
+                endLine: 1,
+                parentFile: `file::${relativeFilePath}`,
+                metadata: {
+                    urlPath: route.urlPath,
+                    httpMethod: route.httpMethod,
+                    isDynamic: route.isDynamic,
+                    params: route.params ?? [],
+                    framework: route.framework,
+                    handlerName: route.handlerName, // used by routeEdges to resolve handler
+                    routeKind: "backend",
+                },
+            });
+        }
+        else {
+            // Next.js RouteNode — one node per HTTP method for API routes,
+            // one node for page/layout/etc.
+            const httpMethods = route.httpMethods && route.httpMethods.length > 0
+                ? route.httpMethods
+                : route.type === "API_ROUTE"
+                    ? ["GET", "PUT", "POST", "DELETE", "PATCH"] // fallback — we'll refine via routeEdges handler lookup
+                    : [null]; // non-API routes (PAGE, LAYOUT etc.) have no method
+            for (const method of httpMethods) {
+                const name = method
+                    ? `${method} ${route.urlPath}`
+                    : route.urlPath;
+                const id = `${relativeFilePath}::${name}`;
+                nodes.push({
+                    id,
+                    name,
+                    type: "ROUTE",
+                    filePath: relativeFilePath,
+                    startLine: 1,
+                    endLine: 1,
+                    parentFile: `file::${relativeFilePath}`,
+                    metadata: {
+                        urlPath: route.urlPath,
+                        httpMethod: method ?? null,
+                        isDynamic: route.isDynamic,
+                        isCatchAll: route.isCatchAll,
+                        isGroupRoute: route.isGroupRoute,
+                        params: route.params ?? [],
+                        routeNodeType: route.type, // PAGE | LAYOUT | API_ROUTE | etc.
+                        layoutPath: route.layoutPath,
+                        framework: "nextjs",
+                        routeKind: "nextjs",
+                    },
+                });
+            }
+        }
+    }
+    return nodes;
+}
+// ─── analyzePipeline ──────────────────────────────────────────────────────────
+export async function analyzePipeline(repoPath, isGithubRepo, options) {
+    const absoluteRepoPath = path.resolve(repoPath);
+    const graphId = generateGraphId(repoPath, isGithubRepo); // stable, deterministic ID based on repo path
+    const gitInfo = getGitInfo(absoluteRepoPath);
+    const analyzedAt = new Date().toISOString();
+    console.log(`\n🔍 devlens — analyzing ${absoluteRepoPath}`);
+    console.log(`   Graph ID:   ${graphId}`);
+    console.log(`   Commit:     ${gitInfo.commitHash} (${gitInfo.branch})`);
+    console.log(`   Message:    ${gitInfo.message}`);
+    // ── Step 1: Fingerprint ───────────────────────────────────────
+    console.log("\n[1/5] Fingerprinting project...");
+    const fingerprint = analyzeFingerprint(absoluteRepoPath);
+    console.log(`  Framework: ${fingerprint.framework}  |  Language: ${fingerprint.language}  |  Type: ${fingerprint.projectType}`);
+    // ── Step 2: Filesystem / routes ───────────────────────────────
+    console.log("\n[2/5] Analyzing filesystem routes...");
+    const routes = analyzeFilesystem(absoluteRepoPath, fingerprint);
+    console.log(`  Routes found: ${routes.length}`);
+    // Convert routes -> CodeNodes so they join the graph as nodes as well
+    // It is important to add here before the detection of the edges
+    let routeNodes = routesToCodeNodes(routes, absoluteRepoPath);
+    console.log(`  Route nodes created: ${routeNodes.length}`);
+    // ── Step 3: Parse source files into nodes ─────────────────────
+    console.log("\n[3/5] Parsing source files...");
+    const parserResult = parseRepo(absoluteRepoPath);
+    console.log(`  Files: ${parserResult.stats.totalFiles}  |  Nodes: ${parserResult.stats.totalNodes}  |  Skipped: ${parserResult.stats.skippedFiles}`);
+    // ── Step 3.5: Build third-party nodes ────────────────────────
+    const thirdPartyNodes = options?.includedThirdPartyLibs?.length
+        ? buildThirdPartyNodes(absoluteRepoPath, options.includedThirdPartyLibs)
+        : [];
+    if (thirdPartyNodes.length) {
+        console.log(`  Third-party nodes: ${thirdPartyNodes.length}`);
+    }
+    // ── Step 4: Detect edges ──────────────────────────────────────
+    console.log("\n[4/5] Detecting edges...");
+    const edgeResult = detectEdges([...parserResult.nodes, ...routeNodes, ...thirdPartyNodes], routes, absoluteRepoPath, fingerprint);
+    // filter API_ROUTE nodes without handlers - because at the time of converting routes to code nodes, POST and GET both possibilties are taken for the API_ROUTE nodes, however it is possible that only one of them is being used for that route. Meaning only one handler and for the second method undefined handler.
+    routeNodes = routeNodes.filter(routeNode => {
+        if (routeNode.metadata.routeNodeType === "API_ROUTE") {
+            const hasHandler = edgeResult.edges.some(edge => edge.type === "HANDLES" && edge.from === routeNode.id);
+            return hasHandler;
+        }
+        return true;
+    });
+    const allNodes = [...parserResult.nodes, ...routeNodes, ...thirdPartyNodes, ...edgeResult.ghostNodes];
+    const allEdges = edgeResult.edges;
+    // ── Step 5: Score and filter ──────────────────────────────────
+    console.log("\n[5/5] Scoring and filtering...");
+    const scoringResult = scoreAndFilter(allNodes, allEdges, options?.thresholds);
+    const nodeScores = mapToRecord(scoringResult.nodeScores);
+    const stats = buildStats(scoringResult, allNodes);
+    // Embed score directly onto every node — allNodes and filteredNodes both.
+    // nodeScores map stays for diffCommits and refilterPipeline which need it,
+    // but consumers (frontend, Neo4j, summarizer) get score on the node itself.
+    for (const node of allNodes) {
+        node.score = nodeScores[node.id] ?? 0;
+    }
+    console.log(`\n✅ Analysis complete — graph ${graphId} @ commit ${gitInfo.commitHash}`);
+    return {
+        graphId,
+        repoPath: absoluteRepoPath,
+        analyzedAt,
+        fingerprint,
+        routes,
+        nodes: scoringResult.filteredNodes,
+        edges: scoringResult.filteredEdges,
+        allNodes,
+        allEdges,
+        nodeScores,
+        stats,
+        isGithubRepo,
+        gitInfo,
+    };
+}
+// ─── refilterPipeline ─────────────────────────────────────────────────────────
+export function refilterPipeline(stored, thresholds) {
+    const existingScores = new Map(Object.entries(stored.nodeScores));
+    const scoringResult = scoreAndFilter(stored.allNodes, stored.allEdges, thresholds, existingScores);
+    const stats = buildStats(scoringResult, stored.allNodes);
+    return {
+        nodes: scoringResult.filteredNodes,
+        edges: scoringResult.filteredEdges,
+        stats,
+    };
+}

package/dist/scoring/connectionCounter.d.ts

@@ -0,0 +1,28 @@
+import type { CodeNode, CodeEdge } from "../types.js";
+export interface ConnectionProfile {
+    incomingCalls: number;
+    outgoingCalls: number;
+    incomingReads: number;
+    incomingWrites: number;
+    incomingProps: number;
+    outgoingProps: number;
+    importedBy: number;
+}
+export interface ConnectionMaxima {
+    maxIncomingCalls: number;
+    maxOutgoingCalls: number;
+    maxIncomingReads: number;
+    maxIncomingWrites: number;
+    maxIncomingProps: number;
+    maxOutgoingProps: number;
+    maxImportedBy: number;
+    p75IncomingCalls: number;
+    p75OutgoingCalls: number;
+    p75IncomingReads: number;
+    p75IncomingProps: number;
+}
+export interface ConnectionCountResult {
+    profiles: Map<string, ConnectionProfile>;
+    maxima: ConnectionMaxima;
+}
+export declare function countConnections(nodes: CodeNode[], edges: CodeEdge[]): ConnectionCountResult;

package/dist/scoring/connectionCounter.js

@@ -0,0 +1,134 @@
+function emptyProfile() {
+    return {
+        incomingCalls: 0,
+        outgoingCalls: 0,
+        incomingReads: 0,
+        incomingWrites: 0,
+        incomingProps: 0,
+        outgoingProps: 0,
+        importedBy: 0,
+    };
+}
+// Computes the 75th percentile of a number array
+function percentile75(values) {
+    if (values.length === 0)
+        return 1;
+    // Build frequency map — O(n)
+    // key: connection count value, value: how many nodes have that count
+    const freq = new Map();
+    for (const v of values) {
+        freq.set(v, (freq.get(v) ?? 0) + 1);
+    }
+    // Sort only the UNIQUE keys — O(k log k) where k << n
+    // In practice k is tiny — most codebases have counts 1-20
+    // even if they have 500+ nodes
+    const uniqueKeys = Array.from(freq.keys()).sort((a, b) => a - b);
+    // Walk cumulative count until we reach the 75th percentile position
+    const target = Math.floor(values.length * 0.75);
+    let cumulative = 0;
+    for (const key of uniqueKeys) {
+        cumulative += freq.get(key);
+        if (cumulative >= target) {
+            return Math.max(1, key);
+        }
+    }
+    // Fallback — return the largest value
+    return Math.max(1, uniqueKeys[uniqueKeys.length - 1]);
+}
+export function countConnections(nodes, edges) {
+    const profiles = new Map();
+    // Initialize a profile for every node
+    for (const node of nodes) {
+        profiles.set(node.id, emptyProfile());
+    }
+    // ─── Pass 1 — Count edges ──────────────────────────────────────
+    for (const edge of edges) {
+        const fromProfile = profiles.get(edge.from);
+        const toProfile = profiles.get(edge.to);
+        switch (edge.type) {
+            case "CALLS":
+                if (fromProfile)
+                    fromProfile.outgoingCalls += 1;
+                if (toProfile)
+                    toProfile.incomingCalls += 1;
+                break;
+            case "READS_FROM":
+                if (toProfile)
+                    toProfile.incomingReads += 1;
+                break;
+            case "WRITES_TO":
+                if (toProfile)
+                    toProfile.incomingWrites += 1;
+                break;
+            case "PROP_PASS":
+                if (fromProfile)
+                    fromProfile.outgoingProps += 1;
+                if (toProfile)
+                    toProfile.incomingProps += 1;
+                break;
+            case "IMPORTS":
+                if (toProfile)
+                    toProfile.importedBy += 1;
+                break;
+        }
+    }
+    // ─── Pass 2 — Find true maxima ────────────────────────────────
+    let maxIncomingCalls = 1;
+    let maxOutgoingCalls = 1;
+    let maxIncomingReads = 1;
+    let maxIncomingWrites = 1;
+    let maxIncomingProps = 1;
+    let maxOutgoingProps = 1;
+    let maxImportedBy = 1;
+    for (const profile of profiles.values()) {
+        if (profile.incomingCalls > maxIncomingCalls)
+            maxIncomingCalls = profile.incomingCalls;
+        if (profile.outgoingCalls > maxOutgoingCalls)
+            maxOutgoingCalls = profile.outgoingCalls;
+        if (profile.incomingReads > maxIncomingReads)
+            maxIncomingReads = profile.incomingReads;
+        if (profile.incomingWrites > maxIncomingWrites)
+            maxIncomingWrites = profile.incomingWrites;
+        if (profile.incomingProps > maxIncomingProps)
+            maxIncomingProps = profile.incomingProps;
+        if (profile.outgoingProps > maxOutgoingProps)
+            maxOutgoingProps = profile.outgoingProps;
+        if (profile.importedBy > maxImportedBy)
+            maxImportedBy = profile.importedBy;
+    }
+    // ─── Pass 3 — Compute 75th percentiles ────────────────────────
+    // Collect all non-zero values per signal type
+    // We only include non-zero values so nodes with no connections
+    // don't drag the percentile down to zero
+    const allIncomingCalls = [];
+    const allOutgoingCalls = [];
+    const allIncomingReads = [];
+    const allIncomingProps = [];
+    for (const profile of profiles.values()) {
+        if (profile.incomingCalls > 0)
+            allIncomingCalls.push(profile.incomingCalls);
+        if (profile.outgoingCalls > 0)
+            allOutgoingCalls.push(profile.outgoingCalls);
+        if (profile.incomingReads > 0)
+            allIncomingReads.push(profile.incomingReads);
+        if (profile.incomingProps > 0)
+            allIncomingProps.push(profile.incomingProps);
+    }
+    return {
+        profiles,
+        maxima: {
+            maxIncomingCalls,
+            maxOutgoingCalls,
+            maxIncomingReads,
+            maxIncomingWrites,
+            maxIncomingProps,
+            maxOutgoingProps,
+            maxImportedBy,
+            // 75th percentile — used for normalization in nodeScorer
+            p75IncomingCalls: percentile75(allIncomingCalls),
+            p75OutgoingCalls: percentile75(allOutgoingCalls),
+            p75IncomingReads: percentile75(allIncomingReads),
+            p75IncomingProps: percentile75(allIncomingProps),
+        },
+    };
+}

package/dist/scoring/fileScorer.d.ts

@@ -0,0 +1,2 @@
+import type { CodeNode } from "../types.js";
+export declare function scoreFile(fileNode: CodeNode, children: CodeNode[], nodeScores: Map<string, number>, importedBy: number): number;

package/dist/scoring/fileScorer.js

@@ -0,0 +1,44 @@
+// ─── Internal Gravity (G_int) ──────────────────────────────────────────────
+// Formula: Σ(S²) / ΣS
+// Favors one high scorer over many averages
+function calcInternalGravity(childScores) {
+    if (childScores.length === 0)
+        return 0;
+    const sumOfSquares = childScores.reduce((acc, s) => acc + s * s, 0);
+    const sumOfScores = childScores.reduce((acc, s) => acc + s, 0);
+    if (sumOfScores === 0)
+        return 0;
+    return sumOfSquares / sumOfScores;
+}
+// ─── Reputation Boost (R_ext) ─────────────────────────────────────────────
+// Formula: (10 - G_int) × (1 - 1/log10(importedBy + 10))
+// Log-scaled import popularity
+function calcReputationBoost(gInt, importedBy) {
+    const gap = 10 - gInt;
+    const multiplier = 1 - (1 / Math.log10(importedBy + 10));
+    return gap * multiplier;
+}
+// ─── Best Child Floor ──────────────────────────────────────────────────────
+// fileScore >= bestChild × 0.90 (dilution protection)
+const BEST_CHILD_FLOOR_RATIO = 0.90;
+// ─── File Score: gravity + floor + reputation ───────────────────────────────
+export function scoreFile(fileNode, children, nodeScores, importedBy) {
+    if (fileNode.type !== "FILE")
+        return 0;
+    // Empty files (types/barrels): reputation only
+    if (children.length === 0) {
+        const gInt = 0;
+        const rExt = calcReputationBoost(gInt, importedBy);
+        return Math.min(10, Math.max(0, rExt));
+    }
+    const childScores = children.map((n) => nodeScores.get(n.id) ?? 0);
+    // 1. Internal gravity
+    const gInt = calcInternalGravity(childScores);
+    // 2. Apply best-child floor
+    const maxChildScore = Math.max(...childScores);
+    const floor = maxChildScore * BEST_CHILD_FLOOR_RATIO;
+    const adjustedGInt = Math.max(gInt, floor);
+    // 3. Reputation boost
+    const rExt = calcReputationBoost(adjustedGInt, importedBy);
+    return Math.min(10, Math.max(0, adjustedGInt + rExt));
+}

package/dist/scoring/index.d.ts

@@ -0,0 +1,22 @@
+import type { CodeNode, CodeEdge } from "../types.js";
+import { type FilterThresholds } from "./noiseFilter.js";
+export interface ScoringResult {
+    filteredNodes: CodeNode[];
+    filteredEdges: CodeEdge[];
+    nodeScores: Map<string, number>;
+    stats: {
+        totalNodesBeforeFilter: number;
+        totalEdgesBeforeFilter: number;
+        totalNodesAfterFilter: number;
+        totalEdgesAfterFilter: number;
+        removedNodeCount: number;
+        removedEdgeCount: number;
+        averageNodeScore: number;
+        topScoringNodes: {
+            name: string;
+            score: number;
+            type: string;
+        }[];
+    };
+}
+export declare function scoreAndFilter(nodes: CodeNode[], edges: CodeEdge[], thresholds?: FilterThresholds, existingScores?: Map<string, number>): ScoringResult;

package/dist/scoring/index.js

@@ -0,0 +1,130 @@
+import { countConnections } from "./connectionCounter.js";
+import { scoreNode } from "./nodeScorer.js";
+import { scoreFile } from "./fileScorer.js";
+import { filterNoise } from "./noiseFilter.js";
+export function scoreAndFilter(nodes, edges, thresholds, existingScores // when provided, skip Passes 1-4
+) {
+    let nodeScores;
+    if (existingScores) {
+        // Re-filter only — reuse scores from a previous analysis run
+        nodeScores = existingScores;
+    }
+    else {
+        console.log(`\n📊 Scoring ${nodes.length} nodes...`);
+        // Pass 1 + 2 — Count connections and find maxima
+        const { profiles, maxima } = countConnections(nodes, edges);
+        //  Build childrenByFile map — O(n)
+        // Maps fileNode.id → all child nodes in that file
+        const childrenByFile = new Map();
+        for (const node of nodes) {
+            if (node.type === "FILE")
+                continue;
+            if (!node.parentFile)
+                continue;
+            if (!childrenByFile.has(node.parentFile)) {
+                childrenByFile.set(node.parentFile, []);
+            }
+            childrenByFile.get(node.parentFile).push(node);
+        }
+        // Pass 3 — Score all non-FILE nodes
+        nodeScores = new Map();
+        for (const node of nodes) {
+            if (node.type === "FILE")
+                continue; // scored in pass 4
+            const profile = profiles.get(node.id) ?? {
+                incomingCalls: 0,
+                outgoingCalls: 0,
+                incomingReads: 0,
+                incomingWrites: 0,
+                incomingProps: 0,
+                outgoingProps: 0,
+                importedBy: 0,
+            };
+            const score = scoreNode(node, profile, maxima);
+            nodeScores.set(node.id, score);
+        }
+        // ─── Pass 4 — Score FILE nodes using child scores ─────────────
+        for (const node of nodes) {
+            if (node.type !== "FILE")
+                continue;
+            const children = childrenByFile.get(node.id) ?? [];
+            const profile = profiles.get(node.id) ?? {
+                incomingCalls: 0,
+                outgoingCalls: 0,
+                incomingReads: 0,
+                incomingWrites: 0,
+                incomingProps: 0,
+                outgoingProps: 0,
+                importedBy: 0,
+            };
+            const score = scoreFile(node, children, nodeScores, profile.importedBy);
+            nodeScores.set(node.id, score);
+        }
+    }
+    // Pass 4.5 — Score ROUTE nodes from their handler 
+    //
+    // A route's significance is entirely determined by the handler it
+    // delegates to. We find the HANDLES edge from each route node and
+    // assign it the handler's score directly.
+    //
+    // If a route has multiple HANDLES edges (shouldn't happen but
+    // defensive) we take the max. If no handler is resolved, the
+    // route keeps its base type bonus score.
+    // Build a quick lookup: routeNodeId → handler scores via HANDLES edges
+    const handlesEdges = edges.filter(e => e.type === "HANDLES");
+    for (const node of nodes) {
+        if (node.type !== "ROUTE")
+            continue;
+        const handlerScores = handlesEdges
+            .filter(e => e.from === node.id)
+            .map(e => nodeScores.get(e.to) ?? 0);
+        if (handlerScores.length === 0)
+            continue;
+        const handlerScore = Math.max(...handlerScores);
+        nodeScores.set(node.id, handlerScore);
+    }
+    // ─── Pass 5 — Filter noise
+    const filterResult = filterNoise(nodes, edges, nodeScores, thresholds);
+    // ─── Build stats ──────────────────────────────────────────────
+    const allScores = Array.from(nodeScores.values());
+    const averageScore = allScores.length > 0
+        ? allScores.reduce((a, b) => a + b, 0) / allScores.length
+        : 0;
+    // Top 10 scoring nodes — useful for UI and debugging
+    const topScoringNodes = nodes
+        .filter((n) => n.type !== "FILE")
+        .map((n) => ({
+        name: n.name,
+        type: n.type,
+        score: nodeScores.get(n.id) ?? 0,
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 10);
+    // ─── Log summary ──────────────────────────────────────────────
+    console.log(`  Nodes before filter: ${nodes.length}`);
+    console.log(`  Nodes after filter:  ${filterResult.nodes.length}`);
+    console.log(`  Edges before filter: ${edges.length}`);
+    console.log(`  Edges after filter:  ${filterResult.edges.length}`);
+    console.log(`  Removed nodes:       ${filterResult.removedNodeCount}`);
+    console.log(`  Removed edges:       ${filterResult.removedEdgeCount}`);
+    console.log(`  Average score:       ${averageScore.toFixed(2)}`);
+    console.log(`\n  🏆 Top scoring nodes:`);
+    for (const n of topScoringNodes) {
+        console.log(`    ${n.score.toFixed(2).padStart(5)}  [${n.type}]  ${n.name}`);
+    }
+    return {
+        filteredNodes: filterResult.nodes,
+        filteredEdges: filterResult.edges,
+        nodeScores,
+        stats: {
+            totalNodesBeforeFilter: nodes.length,
+            totalEdgesBeforeFilter: edges.length,
+            totalNodesAfterFilter: filterResult.nodes.length,
+            totalEdgesAfterFilter: filterResult.edges.length,
+            removedNodeCount: filterResult.removedNodeCount,
+            removedEdgeCount: filterResult.removedEdgeCount,
+            averageNodeScore: parseFloat(averageScore.toFixed(2)),
+            topScoringNodes,
+        },
+    };
+}

package/dist/scoring/index.test.d.ts

@@ -0,0 +1 @@
+export {};