devlensio 1.0.4 → 1.1.1

package/dist/parser/overloads.test.js

@@ -0,0 +1,175 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { parseRepo } from "./index.js";
+function createFakeRepo(files) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devlens-overloads-test-"));
+    for (const [filePath, content] of Object.entries(files)) {
+        const fullPath = path.join(tmpDir, filePath);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, content);
+    }
+    return tmpDir;
+}
+function deleteFakeRepo(repoPath) {
+    fs.rmSync(repoPath, { recursive: true, force: true });
+}
+describe("overload disambiguation (same-name function-likes in one file)", () => {
+    it("keeps the clean unsuffixed id when the name is unique in the file", () => {
+        const repo = createFakeRepo({
+            "src/unique.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const fn = nodes.find((n) => n.name === "formatValue");
+        expect(fn?.id).toBe("src/unique.ts::formatValue");
+        expect(fn?.metadata.isOverloadSignature).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("suffixes each same-name function with its OWN arity (no ordinals)", () => {
+        const repo = createFakeRepo({
+            "src/arity.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+        export function formatValue(v: string, n: number) { return v.repeat(n); }
+        export function formatValue(v: string, n: number, flag: boolean) { return v; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const ids = nodes.filter((n) => n.name === "formatValue").map((n) => n.id).sort();
+        expect(ids).toEqual([
+            "src/arity.ts::formatValue#1",
+            "src/arity.ts::formatValue#2",
+            "src/arity.ts::formatValue#3",
+        ]);
+        deleteFakeRepo(repo);
+    });
+    it("suffixes same-arity different-type overloads with an arity+signature hash", () => {
+        const repo = createFakeRepo({
+            "src/types.ts": `
+        export function decode(input: string, mode: string) { return input; }
+        export function decode(input: number, mode: string) { return String(input); }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const fns = nodes.filter((n) => n.name === "decode");
+        expect(fns.length).toBe(2);
+        const ids = fns.map((n) => n.id).sort();
+        // both share arity 2, differ only by types → distinct sig hashes
+        expect(ids[0]).toMatch(/^src\/types\.ts::decode#2#[0-9a-f]{8}$/);
+        expect(ids[1]).toMatch(/^src\/types\.ts::decode#2#[0-9a-f]{8}$/);
+        expect(ids[0]).not.toBe(ids[1]);
+        // deterministic: same signature → same hash across runs
+        expect(ids).toEqual([...ids].sort());
+        deleteFakeRepo(repo);
+    });
+    it("collapses an overload signature into a signature-identical implementation", () => {
+        const repo = createFakeRepo({
+            "src/collapse.ts": `
+        export function greet(name: string): string;
+        export function greet(name: string) { return "hi " + name; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const greets = nodes.filter((n) => n.name === "greet");
+        expect(greets.length).toBe(1);
+        expect(greets[0].id).toBe("src/collapse.ts::greet");
+        expect(greets[0].rawCode).toContain("return");
+        deleteFakeRepo(repo);
+    });
+    it("keeps an overload signature separate when the implementation has different params", () => {
+        const repo = createFakeRepo({
+            "src/keepboth.ts": `
+        export function parse(input: string): string;
+        export function parse(input: string | number) { return String(input); }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const parses = nodes.filter((n) => n.name === "parse");
+        expect(parses.length).toBe(2);
+        // one of them is the bare signature
+        const sig = parses.find((n) => n.metadata.isOverloadSignature === true);
+        const impl = parses.find((n) => n.metadata.isOverloadSignature === undefined);
+        expect(sig).toBeDefined();
+        expect(impl).toBeDefined();
+        // distinct ids, both arity 1 with different type shapes → hash suffixes
+        expect(sig.id).not.toBe(impl.id);
+        expect(sig.id).toMatch(/^src\/keepboth\.ts::parse#1#[0-9a-f]{8}$/);
+        deleteFakeRepo(repo);
+    });
+    it("suffixes class method overloads with dotted names, not cross-class names", () => {
+        const repo = createFakeRepo({
+            "src/logger.ts": `
+        export class Logger {
+          log(msg: string) { console.log(msg); }
+          log(msg: string, level: number) { console.log(level, msg); }
+        }
+        export class Auditor {
+          log(entry: string) { console.log(entry); }
+        }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const logMethods = nodes.filter((n) => n.type === "METHOD" && n.name.endsWith(".log"));
+        const ids = logMethods.map((n) => n.id).sort();
+        expect(ids).toEqual([
+            "src/logger.ts::Auditor.log", // unique within its class → no suffix
+            "src/logger.ts::Logger.log#1",
+            "src/logger.ts::Logger.log#2",
+        ]);
+        deleteFakeRepo(repo);
+    });
+    it("never changes ids of different-name or different-file nodes", () => {
+        const repo = createFakeRepo({
+            "src/a.ts": `
+        export function helper() { return 1; }
+      `,
+            "src/b.ts": `
+        export function helper() { return 2; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const helpers = nodes.filter((n) => n.name === "helper").map((n) => n.id).sort();
+        expect(helpers).toEqual(["src/a.ts::helper", "src/b.ts::helper"]);
+        deleteFakeRepo(repo);
+    });
+    it("captures callSites with argCount, argTypes and hasSpread", () => {
+        const repo = createFakeRepo({
+            "src/caller.ts": `
+        export function run() {
+          formatValue("abc");
+          formatValue("abc", 3);
+          logAll("a", "b", ...rest);
+        }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const run = nodes.find((n) => n.name === "run");
+        const sites = run?.metadata.callSites;
+        expect(sites).toBeDefined();
+        const byName = new Map(sites.map((s) => [`${s.name}/${s.argCount}`, s]));
+        expect(byName.get("formatValue/1")?.argTypes).toEqual(["string"]);
+        expect(byName.get("formatValue/2")?.argTypes).toEqual(["string", "number"]);
+        expect(byName.get("logAll/3")?.hasSpread).toBe(true);
+        // legacy calls list stays in sync
+        expect(run?.metadata.calls).toContain("formatValue");
+        deleteFakeRepo(repo);
+    });
+    it("does not treat same-name functions in different files as overloads (per-file scope)", () => {
+        const repo = createFakeRepo({
+            "src/x.ts": `
+        export function handle(a: string) { return a; }
+      `,
+            "src/y.ts": `
+        export function handle(a: string, b: string) { return a + b; }
+      `,
+        });
+        const { nodes } = parseRepo(repo);
+        const handlers = nodes.filter((n) => n.name === "handle");
+        expect(handlers.map((n) => n.id).sort()).toEqual([
+            "src/x.ts::handle",
+            "src/y.ts::handle",
+        ]);
+        deleteFakeRepo(repo);
+    });
+});

package/dist/parser/typeUtils.d.ts

@@ -2,6 +2,8 @@ import { SourceFile } from "ts-morph";
 export interface ParamInfo {
     name: string;
     type?: string;
+    isOptional?: boolean;
+    isRest?: boolean;
 }
 export declare function extractParams(node: any): ParamInfo[];
 export declare function extractReturnTypeAnnotation(node: any): string | undefined;

package/dist/parser/typeUtils.js

@@ -3,6 +3,8 @@ export function extractParams(node) {
     return params.map((p) => ({
         name: p.getName(),
         type: p.getTypeNode()?.getText() ?? undefined,
+        isOptional: typeof p.isOptional === "function" ? p.isOptional() : undefined,
+        isRest: typeof p.isRestParameter === "function" ? p.isRestParameter() : undefined,
     }));
 }
 export function extractReturnTypeAnnotation(node) {

package/dist/pipeline/index.d.ts

@@ -1,5 +1,5 @@
 import type { FilterThresholds } from "../scoring/noiseFilter.js";
-import type { CodeNode, CodeEdge, ProjectFingerprint, RouteNode, BackendRouteNode } from "../types.js";
+import type { CodeNode, CodeEdge, ProjectFingerprint, RouteNode, BackendRouteNode, GraphExports } from "../types.js";
 export type { FilterThresholds };
 export interface GitInfo {
     commitHash: string;
@@ -37,6 +37,7 @@ export interface PipelineResult {
     analyzedAt: string;
     fingerprint: ProjectFingerprint;
     routes: (RouteNode | BackendRouteNode)[];
+    exports?: GraphExports;
     nodes: CodeNode[];
     edges: CodeEdge[];
     allNodes: CodeNode[];

package/dist/pipeline/index.js

@@ -251,6 +251,7 @@ export async function analyzePipeline(repoPath, isGithubRepo, options) {
         analyzedAt,
         fingerprint: extractorResult.fingerprint,
         routes: extractorResult.routes ?? [],
+        exports: extractorResult.exports,
         nodes: scoringResult.filteredNodes,
         edges: scoringResult.filteredEdges,
         allNodes,

package/dist/storage/fileStorage.d.ts

@@ -1,5 +1,5 @@
 import type { PipelineResult, PipelineStats } from "../pipeline/index.js";
-import type { CodeNode, CodeEdge } from "../types.js";
+import type { CodeNode, CodeEdge, GraphExports } from "../types.js";
 import type { GraphStorage } from "./interface.js";
 export interface GraphIndexEntry {
     graphId: string;
@@ -44,6 +44,7 @@ export interface CommitData {
     allEdges: CodeEdge[];
     nodeScores: Record<string, number>;
     stats: PipelineStats;
+    exports?: GraphExports;
 }
 export interface NodeDiff {
     added: DiffNode[];

package/dist/storage/fileStorage.js

@@ -14,7 +14,9 @@ import { simpleGit } from "simple-git";
 //
 // Diffs are computed on demand — not stored.
 // GitHub scope is reserved in meta.json for future cloud repo support.
-const STORAGE_DIR = path.join(os.homedir(), ".devlens");
+const STORAGE_DIR = process.env.DEVLENS_STORAGE_DIR
+    ? path.resolve(process.env.DEVLENS_STORAGE_DIR)
+    : path.join(os.homedir(), ".devlens");
 const GRAPHS_DIR = path.join(STORAGE_DIR, "graphs");
 const INDEX_FILE = path.join(STORAGE_DIR, "index.json");
 const SCHEMA_VERSION = "1.0";
@@ -118,6 +120,7 @@ function buildCommitData(result) {
         allEdges: result.allEdges,
         nodeScores: result.nodeScores,
         stats: result.stats,
+        exports: result.exports,
     };
 }
 // ─── Public API ───────────────────────────────────────────────────────────────
@@ -239,6 +242,7 @@ export function getGraph(graphId, commitHash // defaults to latest commit
             allEdges: data.allEdges,
             nodeScores: data.nodeScores,
             stats: data.stats,
+            exports: data.exports,
             isGithubRepo: meta.isGithubRepo,
             gitInfo: {
                 commitHash: data.commitHash,

package/dist/storage/fileStorage.test.d.ts

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

package/dist/storage/fileStorage.test.js

@@ -0,0 +1,112 @@
+// Storage round-trip + back-compat tests for the exports map.
+//
+// STORAGE_DIR is computed from os.homedir() at module load, so these tests
+// point it at a temp dir via DEVLENS_STORAGE_DIR and import the module
+// dynamically AFTER setting the env var — nothing here ever touches the
+// real ~/.devlens.
+import { describe, expect, test } from "bun:test";
+import fs from "fs";
+import os from "os";
+import path from "path";
+const FAKE_STORAGE_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), "devlens-storage-test-"));
+process.env.DEVLENS_STORAGE_DIR = FAKE_STORAGE_ROOT;
+const { saveGraph, getGraph, deleteGraph } = await import("./fileStorage.js");
+function makeNode(id, name) {
+    return {
+        id,
+        name,
+        type: "FUNCTION",
+        filePath: `src/${name}.ts`,
+        startLine: 1,
+        endLine: 2,
+        parentFile: `file::src/${name}.ts`,
+        metadata: {},
+    };
+}
+function makeResult(overrides) {
+    const nodes = [makeNode("src/alpha.ts::alpha", "alpha"), makeNode("src/alpha.ts::alpha#2", "alpha")];
+    const edges = [];
+    return {
+        repoPath: FAKE_STORAGE_ROOT,
+        analyzedAt: "2026-10-07T00:00:00.000Z",
+        fingerprint: { language: "typescript" },
+        routes: [],
+        nodes,
+        edges,
+        allNodes: nodes,
+        allEdges: edges,
+        nodeScores: {},
+        stats: {
+            totalNodesBeforeFilter: nodes.length,
+            totalEdgesBeforeFilter: 0,
+            totalNodesAfterFilter: nodes.length,
+            totalEdgesAfterFilter: 0,
+            removedNodeCount: 0,
+            removedEdgeCount: 0,
+            averageNodeScore: 0,
+            topScoringNodes: [],
+            topScoringFiles: [],
+        },
+        isGithubRepo: false,
+        gitInfo: { commitHash: "abc12345", branch: "main", message: "test", hasGit: true },
+        ...overrides,
+    };
+}
+const MAP = {
+    exports: {
+        ".": {
+            alpha: ["src/alpha.ts::alpha", "src/alpha.ts::alpha#2"],
+            beta: ["src/beta.ts::beta"],
+        },
+        "./server": { serve: ["src/server.ts::serve"] },
+    },
+    ambiguousNames: {},
+};
+describe("exports map persistence (saveGraph -> getGraph)", () => {
+    test("round trip: map survives byte-for-byte, including multi-id groups and order", () => {
+        const result = makeResult({ graphId: "rt-test-graph", exports: MAP });
+        saveGraph(result, { force: true });
+        const loaded = getGraph("rt-test-graph", "abc12345");
+        expect(loaded).toBeDefined();
+        expect(loaded.exports).toBeDefined();
+        // deep identity: shape, keys, values, AND array order within groups
+        expect(loaded.exports).toEqual(MAP);
+        expect(loaded.exports.exports["."].alpha).toEqual(["src/alpha.ts::alpha", "src/alpha.ts::alpha#2"]);
+        expect(loaded.exports.ambiguousNames).toEqual({});
+        deleteGraph("rt-test-graph");
+    });
+    test("legacy artifact without the exports field: loads, yields undefined, no fabricated empty map", () => {
+        const result = makeResult({ graphId: "legacy-test-graph" });
+        delete result.exports;
+        saveGraph(result, { force: true });
+        const commitFile = path.join(FAKE_STORAGE_ROOT, "graphs", "legacy-test-graph", "commits", "abc12345.json");
+        const onDisk = JSON.parse(fs.readFileSync(commitFile, "utf-8"));
+        expect("exports" in onDisk).toBe(false);
+        const loaded = getGraph("legacy-test-graph", "abc12345");
+        expect(loaded).toBeDefined();
+        expect(loaded.exports).toBeUndefined();
+        deleteGraph("legacy-test-graph");
+    });
+    test("degraded input: exports present but EMPTY subpaths load without crash", () => {
+        const emptyMap = { exports: { ".": {} }, ambiguousNames: {} };
+        const result = makeResult({ graphId: "empty-map-graph", exports: emptyMap });
+        saveGraph(result, { force: true });
+        const loaded = getGraph("empty-map-graph", "abc12345");
+        expect(loaded).toBeDefined();
+        expect(loaded.exports).toEqual(emptyMap);
+        deleteGraph("empty-map-graph");
+    });
+    test("degraded input: exports referencing node ids ABSENT from the nodes array load without crash", () => {
+        const danglingMap = {
+            exports: { ".": { ghost: ["src/gone.ts::gone"] } },
+            ambiguousNames: {},
+        };
+        const result = makeResult({ graphId: "dangling-map-graph", exports: danglingMap });
+        saveGraph(result, { force: true });
+        const loaded = getGraph("dangling-map-graph", "abc12345");
+        expect(loaded).toBeDefined();
+        expect(loaded.exports).toEqual(danglingMap);
+        expect(loaded.exports.exports["."].ghost).toEqual(["src/gone.ts::gone"]);
+        deleteGraph("dangling-map-graph");
+    });
+});

package/dist/types.d.ts

@@ -48,6 +48,12 @@ export interface BackendRouteNode {
     };
 }
 export type NodeType = "COMPONENT" | "HOOK" | "FUNCTION" | "STATE_STORE" | "UTILITY" | "FILE" | "GHOST" | "ROUTE" | "TEST" | "STORY" | "THIRD_PARTY" | "CLASS" | "METHOD" | "INTERFACE" | "ENUM" | "STRUCT" | "MODULE" | "TRAIT" | "IMPL_BLOCK" | "PACKAGE";
+export interface CallSite {
+    name: string;
+    argCount: number;
+    argTypes?: string[];
+    hasSpread?: boolean;
+}
 export interface CodeNode {
     id: string;
     name: string;
@@ -77,3 +83,7 @@ export interface CodeEdge {
     type: EdgeType;
     metadata?: Record<string, unknown>;
 }
+export interface GraphExports {
+    exports: Record<string, Record<string, string[]>>;
+    ambiguousNames: Record<string, string[]>;
+}

package/extractors/go/calls.go

@@ -152,8 +152,11 @@ func resolveCall(c CallSite, fn *ParsedFunc, pf *ParsedFile, info *types.Info,
 		if id, ok := l.MethodNodeByPkgTypeName[pkgPath+"::"+c.Receiver+"."+c.Sel]; ok {
 			return id, c.Sel, c.Receiver, callEdge(callerID, id, c.Sel, c.Receiver)
 		}
-		// receiver is a plain variable whose type we can't see — unresolvable
-		// tier (documented; type info covers the exact cases)
+		// receiver is a plain variable whose type we can't see — bare-method-name
+		// candidates across packages, filtered by arity/type shape
+		if id, matchedBy := resolveByCandidates(l.MethodCandidatesByName[c.Sel], c, pf.RelPath); id != "" {
+			return id, c.Sel, "", callEdgeMatched(callerID, id, c.Sel, "", matchedBy)
+		}
 		return "", "", "", nil
 	}
 
@@ -161,6 +164,11 @@ func resolveCall(c CallSite, fn *ParsedFunc, pf *ParsedFile, info *types.Info,
 	if id, ok := l.FuncNodeByPkgName[pkgPath+"::"+c.Str]; ok {
 		return id, "", "", callEdge(callerID, id, "", "")
 	}
+	// same-package miss: bare-name candidates across packages, filtered by
+	// arity/type shape (fire only where resolution previously gave up)
+	if id, matchedBy := resolveByCandidates(l.FuncCandidatesByName[c.Str], c, pf.RelPath); id != "" {
+		return id, "", "", callEdgeMatched(callerID, id, "", "", matchedBy)
+	}
 	return "", "", "", nil
 }
 
@@ -175,6 +183,130 @@ func callEdge(from, to, method, class string) map[string]any {
 	return edgeWithMeta(from, to, EdgeCalls, meta)
 }
 
+// callEdgeMatched — callEdge plus resolution confidence from the arity-aware
+// candidate tier: "arity" (arg count singled out the target), "signature"
+// (arg type agreement decided it), "name" (path proximity fallback).
+func callEdgeMatched(from, to, method, class, matchedBy string) map[string]any {
+	e := callEdge(from, to, method, class)
+	e["metadata"].(map[string]any)["matchedBy"] = matchedBy
+	return e
+}
+
+// ── arity-aware candidate resolution ──
+
+// arityAccepts — Go call compatibility: exact arg count, except a variadic
+// tail accepts any count >= required. Spread calls (f(xs...)) have an
+// unknowable runtime arity — every candidate stays admissible.
+func arityAccepts(cand funcCandidate, argCount int, hasSpread bool) bool {
+	if hasSpread {
+		return true
+	}
+	if cand.Variadic {
+		return argCount >= cand.Required
+	}
+	return argCount == cand.Required
+}
+
+// typeAgrees — loose agreement between a call-site arg tag and a declared
+// param type text; "unknown" tags never match (parity with the TS resolver).
+func typeAgrees(argType, paramType string) bool {
+	if argType == "" || argType == "unknown" || paramType == "" {
+		return false
+	}
+	return paramType == argType || strings.Contains(paramType, argType)
+}
+
+// typeScore — how many argument tags agree with the declared params.
+func typeScore(cand funcCandidate, argTypes []string) int {
+	score := 0
+	for i, at := range argTypes {
+		if i < len(cand.ParamTypes) && typeAgrees(at, cand.ParamTypes[i]) {
+			score++
+		}
+	}
+	return score
+}
+
+// pathProximity — shared leading path segments between two rel paths
+// (mirrors the TS engine's closestByPath tiebreak).
+func pathProximity(candidate, reference string) int {
+	a := strings.Split(candidate, "/")
+	b := strings.Split(reference, "/")
+	score := 0
+	for i := 0; i < len(a) && i < len(b); i++ {
+		if a[i] != b[i] {
+			break
+		}
+		score++
+	}
+	return score
+}
+
+// resolveByCandidates — pick among same-name declarations by argument shape:
+// arity filter first, then arg-type agreement tiebreak, then path proximity.
+// Single-candidate groups return immediately (matchedBy "arity" only when the
+// call shape actually participated). Returns ("", "") when nothing applies.
+func resolveByCandidates(candidates []funcCandidate, c CallSite, callerRel string) (string, string) {
+	if len(candidates) == 0 {
+		return "", ""
+	}
+	if len(candidates) == 1 {
+		// a lone same-name declaration elsewhere — arity still gates it
+		if arityAccepts(candidates[0], c.ArgCount, c.HasSpread) {
+			return candidates[0].ID, "arity"
+		}
+		return "", ""
+	}
+
+	pool := make([]funcCandidate, 0, len(candidates))
+	for _, cand := range candidates {
+		if arityAccepts(cand, c.ArgCount, c.HasSpread) {
+			pool = append(pool, cand)
+		}
+	}
+	if len(pool) == 0 {
+		return "", "" // nothing accepts this shape — stay unresolvable
+	}
+	if len(pool) == 1 {
+		return pool[0].ID, "arity"
+	}
+
+	// type agreement tiebreak — needs usable (non-unknown) arg tags
+	usable := false
+	for _, at := range c.ArgTypes {
+		if at != "unknown" {
+			usable = true
+			break
+		}
+	}
+	if usable {
+		best := pool[0]
+		bestScore := typeScore(pool[0], c.ArgTypes)
+		tie := 1
+		for _, cand := range pool[1:] {
+			s := typeScore(cand, c.ArgTypes)
+			if s > bestScore {
+				best, bestScore, tie = cand, s, 1
+			} else if s == bestScore {
+				tie++
+			}
+		}
+		if bestScore > 0 && tie == 1 {
+			return best.ID, "signature"
+		}
+	}
+
+	// path proximity fallback
+	best := pool[0]
+	bestScore := pathProximity(best.RelPath, callerRel)
+	for _, cand := range pool[1:] {
+		if s := pathProximity(cand.RelPath, callerRel); s > bestScore {
+			best, bestScore = cand, s
+		}
+	}
+	return best.ID, "name"
+}
+
 // receiverDeclaredType — the receiver's type from its DECLARATION: function
 // parameters first (func(c *gin.Context) — the documented handler signature),
 // then package-level typed vars (var DB *gorm.DB). Returns (importPath,

package/extractors/go/contract.go

@@ -89,6 +89,7 @@ type ExtractorResult struct {
 	Nodes       []map[string]any `json:"nodes"`
 	Edges       []map[string]any `json:"edges"`
 	Routes      []map[string]any `json:"routes"`
+	Exports     *ExportsMap      `json:"exports,omitempty"`
 	Stats       Stats            `json:"stats"`
 	Errors      []ExtractorError `json:"errors"`
 }