devlensio 1.0.3 → 1.1.0

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/summarizer/providers/index.js

@@ -12,13 +12,13 @@ export function createLLMClient(config) {
     const effectiveBase = baseUrl ?? entry?.baseUrl;
     switch (provider) {
         case "openai": {
-            if (needsKey && !apiKey)
-                throw new Error(`Provider "${providerName}" requires an API key`);
-            return new OpenAIClient(apiKey ?? "ollama", model, effectiveBase, providerName);
+            if (!apiKey)
+                throw new Error(`No API key configured for "${providerName}" — run "devlens init" to set one up.`);
+            return new OpenAIClient(apiKey, model, effectiveBase, providerName);
         }
         case "anthropic": {
             if (!apiKey)
-                throw new Error(`Provider "${providerName}" requires an API key`);
+                throw new Error(`No API key configured for "${providerName}" — run "devlens init" to set one up.`);
             return new AnthropicClient(apiKey, model, effectiveBase, providerName);
         }
         default:

package/dist/summarizer/providers/openai.js

@@ -26,7 +26,7 @@ function parseResponse(raw) {
         tokensUsed: 0,
     };
 }
-// Also used as the base for OpenRouter and Ollama —
+// Also used as the base for other OpenAI-compatible providers —
 // both expose OpenAI-compatible APIs, just with a different baseURL.
 export class OpenAIClient {
     constructor(apiKey, model, baseURL, providerName) {

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;

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"`
 }

package/extractors/go/exports.go

@@ -0,0 +1,107 @@
+// exports.go — the flattened public surface of a Go module, shipped in the
+// ExtractorResult for cross-repo linking (docs/EXPORTS_MAP.md).
+//
+// Go-specific concerns:
+//   - Export = capitalized identifier (token.IsExported); Go has no
+//     package.json "door" — every package is importable, so the map is keyed
+//     by package: subpath "." for the module-root package, "./rel/dir" for
+//     the rest (mirrors the TS multi-door shape).
+//   - The map key is the name an importer writes: plain funcs/structs/
+//     interfaces/enums use their bare name; exported methods of exported
+//     types use "Type.Method" (that is what consumer code writes).
+//   - Go has no overloads → values are always single-element arrays.
+//   - Test files are excluded (their symbols are not importable surface).
+//   - Same-name duplicates within a package cannot compile, but if the
+//     walker ever yields them, all ids are emitted rather than guessing.
+//   - Requires go.mod: without a module path the consumer-side join key
+//     ([mod]/importPath) is undefined, so no map is emitted.
+package main
+
+import (
+	"go/token"
+	"sort"
+	"strings"
+)
+
+type ExportsMap struct {
+	Exports        map[string]map[string][]string `json:"exports"`
+	AmbiguousNames map[string][]string            `json:"ambiguousNames"`
+}
+
+func buildExportsMap(pr *parsedRepo) *ExportsMap {
+	if pr.mod == nil || !pr.mod.HasMod || pr.mod.ModulePath == "" {
+		return nil
+	}
+
+	exports := map[string]map[string][]string{}
+	ambiguous := map[string][]string{}
+
+	for _, pkg := range pr.packages {
+		rel := strings.TrimPrefix(pkg.ImportPath, pr.mod.ModulePath)
+		rel = strings.TrimPrefix(rel, "/")
+		subpath := "."
+		if rel != "" && rel != "." {
+			subpath = "./" + rel
+		}
+
+		perPath := map[string][]string{}
+		for _, pf := range pkg.Files {
+			if pf.IsTest {
+				continue
+			}
+			for _, fn := range pf.Funcs {
+				if fn.IsTest {
+					continue
+				}
+				if fn.IsMethod {
+					if !token.IsExported(fn.RecvType) || !token.IsExported(fn.Name) {
+						continue
+					}
+					addExport(perPath, fn.RecvType+"."+fn.Name, methodNodeID(pf.RelPath, fn))
+				} else {
+					if !token.IsExported(fn.Name) {
+						continue
+					}
+					addExport(perPath, fn.Name, funcNodeID(pf.RelPath, fn.Name))
+				}
+			}
+			for _, st := range pf.Structs {
+				if !token.IsExported(st.Name) {
+					continue
+				}
+				addExport(perPath, st.Name, structNodeID(pf.RelPath, st.Name))
+			}
+			for _, it := range pf.Interfaces {
+				if !token.IsExported(it.Name) {
+					continue
+				}
+				addExport(perPath, it.Name, interfaceNodeID(pf.RelPath, it.Name))
+			}
+			for _, en := range pf.numericEnums {
+				if !token.IsExported(en.TypeName) {
+					continue
+				}
+				addExport(perPath, en.TypeName, structNodeID(pf.RelPath, en.TypeName))
+			}
+		}
+
+		if len(perPath) > 0 {
+			exports[subpath] = perPath
+		}
+	}
+
+	if len(exports) == 0 {
+		return nil
+	}
+	return &ExportsMap{Exports: exports, AmbiguousNames: ambiguous}
+}
+
+func addExport(perPath map[string][]string, name, id string) {
+	for _, existing := range perPath[name] {
+		if existing == id {
+			return
+		}
+	}
+	perPath[name] = append(perPath[name], id)
+	sort.Strings(perPath[name])
+}

package/extractors/go/exports_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestBuildExportsMapPublicSurface(t *testing.T) {
+	repo := parseRepo("tests/fixtures/plainfix", parseGoMod("tests/fixtures/plainfix"), func(string, string) {})
+	m := buildExportsMap(repo)
+	if m == nil {
+		t.Fatal("expected exports map for a module with go.mod")
+	}
+
+	perPath, ok := m.Exports["."]
+	if !ok {
+		t.Fatalf("expected root package subpath '.', got subpaths %v", keys(m.Exports))
+	}
+
+	expectIds(perPath, t, "Shape", []string{"shapes.go::Shape"})
+	expectIds(perPath, t, "Circle", []string{"shapes.go::Circle"})
+	expectIds(perPath, t, "Circle.Area", []string{"shapes.go::Circle.Area"})
+	expectIds(perPath, t, "Circle.Perimeter", []string{"shapes.go::Circle.Perimeter"})
+	expectIds(perPath, t, "Square.Scale", []string{"shapes.go::Square.Scale"})
+	expectIds(perPath, t, "Color", []string{"shapes.go::Color"})
+
+	if len(m.AmbiguousNames) != 0 {
+		t.Fatalf("expected no ambiguous names, got %v", m.AmbiguousNames)
+	}
+}
+
+func TestBuildExportsMapRequiresGoMod(t *testing.T) {
+	repo := parseRepo("tests/fixtures/plainfix", &modFile{}, func(string, string) {})
+	if m := buildExportsMap(repo); m != nil {
+		t.Fatal("expected no exports map without a module path")
+	}
+}
+
+func expectIds(perPath map[string][]string, t *testing.T, name string, want []string) {
+	t.Helper()
+	got, ok := perPath[name]
+	if !ok {
+		t.Fatalf("expected exported name %q in map, got keys %v", name, keysOf(perPath))
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("%s: got %v, want %v", name, got, want)
+	}
+}
+
+func keys(m map[string]map[string][]string) []string {
+	out := []string{}
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+
+func keysOf(m map[string][]string) []string {
+	out := []string{}
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

package/extractors/go/extractor.go

@@ -109,6 +109,7 @@ func runExtractor(repoPath string, opts *Options) *ExtractorResult {
 	result.Nodes = nodes
 	result.Edges = allEdges
 	result.Routes = routes
+	result.Exports = buildExportsMap(parsed)
 	result.Stats = Stats{
 		TotalFiles:   len(parsed.files),
 		TotalNodes:   len(nodes),