devlensio 1.0.3 → 1.1.0

package/dist/graph/edges/callEdges.js

@@ -1,8 +1,89 @@
 import { closestByPath } from "./utils.js";
+// Arity compatibility: a candidate matches when the call provides at least all
+// required (non-optional, non-rest) params, and does not exceed the declared
+// count unless the candidate declares a rest parameter. Candidates without
+// parameters metadata are permissive (unknown shape).
+function arityMatches(candidate, argCount) {
+    const parameters = candidate.metadata?.parameters;
+    const params = candidate.metadata?.params;
+    if (!params && !parameters)
+        return true;
+    const total = parameters?.length ?? params?.length ?? 0;
+    const hasRest = parameters?.some((p) => p.isRest) ?? false;
+    const required = parameters
+        ? parameters.filter((p) => !p.isOptional && !p.isRest).length
+        : total;
+    return argCount >= required && (hasRest || argCount <= total);
+}
+// Loose type agreement between a call-site arg type tag and a declared param
+// type text. Both sides are cheap/heuristic (no type checker), so this scores
+// rather than gates: unknown tags never match, text containment counts.
+function typeAgrees(argType, paramType) {
+    if (!argType || argType === "unknown" || !paramType)
+        return false;
+    const p = paramType.trim();
+    return p === argType || p.includes(argType);
+}
+function typeScore(candidate, argTypes) {
+    const parameters = candidate.metadata?.parameters;
+    if (!parameters)
+        return 0;
+    let score = 0;
+    for (let i = 0; i < argTypes.length; i++) {
+        if (parameters[i] && typeAgrees(argTypes[i], parameters[i].type))
+            score++;
+    }
+    return score;
+}
+// Picks the right overload among same-name candidates using the call site's
+// argument shape. Ladder:
+//   1. no usable call shape (USES edges, spread calls, missing callSites)
+//      → legacy closestByPath behavior
+//   2. arity filter — survivors whose declared params accept argCount
+//   3. type tiebreak — among arity survivors, prefer the candidate with the
+//      highest arg-type agreement (handles same arity, different types)
+//   4. still ambiguous → closestByPath among survivors
+function resolveOverloadTarget(candidates, caller, callSite) {
+    if (candidates.length === 1)
+        return { target: candidates[0], matchedBy: "name" };
+    const usableShape = callSite
+        && typeof callSite.argCount === "number"
+        && !callSite.hasSpread;
+    if (!usableShape)
+        return { target: closestByPath(candidates, caller.filePath), matchedBy: "name" };
+    let pool = candidates.filter((c) => arityMatches(c, callSite.argCount));
+    if (pool.length === 0)
+        pool = candidates; // nothing accepts this arity — keep all
+    if (pool.length === 1)
+        return { target: pool[0], matchedBy: "arity" };
+    const argTypes = callSite.argTypes ?? [];
+    if (argTypes.some((t) => t && t !== "unknown")) {
+        let best = pool[0];
+        let bestScore = typeScore(pool[0], argTypes);
+        let tieAtBest = 1;
+        for (let i = 1; i < pool.length; i++) {
+            const s = typeScore(pool[i], argTypes);
+            if (s > bestScore) {
+                best = pool[i];
+                bestScore = s;
+                tieAtBest = 1;
+            }
+            else if (s === bestScore)
+                tieAtBest++;
+        }
+        if (bestScore > 0 && tieAtBest === 1) {
+            return { target: best, matchedBy: "signature" };
+        }
+    }
+    return { target: closestByPath(pool, caller.filePath), matchedBy: "name" };
+}
 export function detectCallEdges(nodes, lookupMp) {
     const edges = [];
     // Dedup for THIRD_PARTY CALLS edges — one per (caller, target) pair
     const createdThirdPartyEdges = new Set();
+    // Dedup for local CALLS/USES edges — overload call sites can resolve to
+    // the same target through different (name, arity) pairs
+    const createdLocalEdges = new Set();
     // Accumulate resolved calls per node — written back to metadata after edge loop
     const resolvedCallsMap = new Map();
     // Lazily-created method nodes for default/namespace import member-access calls
@@ -34,7 +115,16 @@ export function detectCallEdges(nodes, lookupMp) {
         if (!hasPrimary && !hasHooks)
             continue;
         // ── Primary names: both third-party and local edges ──────────────
-        for (const calledName of (primaryNames ?? [])) {
+        // Structured callSites carry the argument shape for overload-aware
+        // resolution; fall back to bare calls/uses strings when absent.
+        const callSites = node.metadata.callSites;
+        // Each (name, arity) call site iterates separately — a caller that
+        // invokes two overloads of one name gets two edges.
+        const primaryCallSites = (callSites && callSites.length > 0)
+            ? callSites
+            : (primaryNames ?? []).map((name) => ({ name, argCount: -1 }));
+        for (const callSite of primaryCallSites) {
+            const calledName = callSite.name;
             // ── Third-party guard ─────────────────────────────────────────
             // The alias map is keyed by node.filePath (relative) and populated
             // by importEdges.ts (which runs first).
@@ -120,16 +210,18 @@ export function detectCallEdges(nodes, lookupMp) {
             }
             if (!targets || targets.length === 0)
                 continue;
-            const target = targets.length === 1
-                ? targets[0]
-                : closestByPath(targets, node.filePath);
+            const { target, matchedBy } = resolveOverloadTarget(targets, node, callSite.argCount >= 0 ? callSite : undefined);
             if (target.id === node.id)
                 continue; // skip self-reference
+            const localEdgeKey = `${node.id}→${target.id}:${edgeType}`;
+            if (createdLocalEdges.has(localEdgeKey))
+                continue;
+            createdLocalEdges.add(localEdgeKey);
             edges.push({
                 from: node.id,
                 to: target.id,
                 type: edgeType,
-                metadata: { calledName: resolvedName },
+                metadata: { calledName: resolvedName, matchedBy },
             });
             if (!resolvedCallsMap.has(node.id))
                 resolvedCallsMap.set(node.id, []);

package/dist/graph/edges/callEdges.test.js

@@ -198,3 +198,157 @@ describe("detectCallEdges with class methods", () => {
         deleteFakeRepo(repo);
     });
 });
+// ─── Overload-aware resolution (same-name candidates in one file) ─────────────
+describe("detectCallEdges with overloads", () => {
+    // Arity disambiguates same-name functions in one file
+    it("routes each call to the overload matching its argument count", () => {
+        const repo = createFakeRepo({
+            "src/fmt.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+        export function formatValue(v: string, n: number) { return v.repeat(n); }
+        export function caller() {
+          formatValue("a");
+          formatValue("a", 3);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "formatValue");
+        const targets = callEdges.map((e) => e.to).sort();
+        expect(targets).toEqual([
+            "src/fmt.ts::formatValue#1",
+            "src/fmt.ts::formatValue#2",
+        ]);
+        // resolution confidence recorded on the edge
+        expect(callEdges.every((e) => e.metadata?.matchedBy === "arity")).toBe(true);
+        deleteFakeRepo(repo);
+    });
+    // Same arity, different param types — literal arg types break the tie
+    it("resolves same-arity overloads via argument type tags", () => {
+        const repo = createFakeRepo({
+            "src/dec.ts": `
+        export function decode(input: string, mode: string) { return input; }
+        export function decode(input: number, mode: string) { return String(input); }
+        export function caller() {
+          decode("abc", "utf8");
+          decode(42, "utf8");
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "decode");
+        // first call (string literal) → string overload; second (number literal) → number overload
+        const stringTargets = callEdges.filter((e) => e.metadata?.matchedBy === "signature").map((e) => e.to).sort();
+        expect(stringTargets.length).toBe(2);
+        expect(stringTargets[0]).not.toBe(stringTargets[1]);
+        deleteFakeRepo(repo);
+    });
+    // A caller can invoke two overloads of one name — two distinct edges
+    it("emits one edge per overload call site, not one per name", () => {
+        const repo = createFakeRepo({
+            "src/multi.ts": `
+        export function send(x: string) { return x; }
+        export function send(x: string, y: string) { return x + y; }
+        export function client() {
+          send("a");
+          send("a", "b");
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "send");
+        expect(callEdges.length).toBe(2);
+        expect(new Set(callEdges.map((e) => e.to)).size).toBe(2);
+        deleteFakeRepo(repo);
+    });
+    // Spread calls have unknowable arity — must NOT confidently pick an overload
+    it("falls back to path proximity for spread calls", () => {
+        const repo = createFakeRepo({
+            "src/spread.ts": `
+        export function combine(a: string) { return a; }
+        export function combine(a: string, b: string) { return a + b; }
+        export function caller(...args: string[]) {
+          return combine(...args);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "combine");
+        expect(callEdges.length).toBe(1);
+        expect(callEdges[0].metadata?.matchedBy).toBe("name");
+        deleteFakeRepo(repo);
+    });
+    // Optional params: a 1-arg call may hit a 2-param overload with optional 2nd
+    it("lets optional parameters accept shorter calls via arity fallback", () => {
+        const repo = createFakeRepo({
+            "src/opt.ts": `
+        export function render(template: string, opts?: object) { return template; }
+        export function render(template: string, opts: object, mode: string) { return template; }
+        export function caller() {
+          render("t");
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "render");
+        // 1-arg call: renderStrict requires 3 → excluded; render (optional) → match
+        expect(callEdges.length).toBe(1);
+        expect(callEdges[0].to).toBe("src/opt.ts::render#2");
+        deleteFakeRepo(repo);
+    });
+    // Rest params accept any extra arguments
+    it("lets rest parameters accept longer calls", () => {
+        const repo = createFakeRepo({
+            "src/rest.ts": `
+        export function sum(first: number, ...rest: number[]) { return first; }
+        export function pair(a: number, b: number) { return a; }
+        export function caller() {
+          sum(1, 2, 3, 4);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "sum");
+        expect(callEdges.length).toBe(1);
+        expect(callEdges[0].to).toContain("sum");
+        deleteFakeRepo(repo);
+    });
+    // Legacy behavior preserved when no overload shape exists
+    it("still resolves plain single-candidate calls without callSites metadata", () => {
+        const repo = createFakeRepo({
+            "src/plain.ts": `
+        export function helper(x: number) { return x; }
+        export function caller() { return helper(1); }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        expect(edges).toContainEqual(expect.objectContaining({
+            from: "src/plain.ts::caller",
+            to: "src/plain.ts::helper",
+            type: "CALLS",
+        }));
+        deleteFakeRepo(repo);
+    });
+    // Class method overloads resolve through dotted names
+    it("resolves class method overloads by arity through dotted names", () => {
+        const repo = createFakeRepo({
+            "src/svc.ts": `
+        export class Repo {
+          find(id: string) { return id; }
+          find(id: string, depth: number) { return id; }
+        }
+        export function caller() {
+          Repo.find("a");
+          Repo.find("a", 2);
+        }
+      `,
+        });
+        const { edges } = detectCalls(repo);
+        const callEdges = edges.filter((e) => e.type === "CALLS" && e.metadata?.calledName === "Repo.find");
+        expect(callEdges.map((e) => e.to).sort()).toEqual([
+            "src/svc.ts::Repo.find#1",
+            "src/svc.ts::Repo.find#2",
+        ]);
+        deleteFakeRepo(repo);
+    });
+});

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export * from "./pipeline/index.js";
 export * from "./config/types.js";
 export { queue } from "./jobs/index.js";
 export { storage } from "./storage/index.js";
-export { resolveConfig, initConfig, maskConfig, writeConfig, resolveAllProviders, setActiveProvider, removeProvider as removeProviderConfig, } from "./config/index.js";
+export { resolveConfig, hasSummarizationConfigured, initConfig, maskConfig, writeConfig, resolveAllProviders, setActiveProvider, removeProvider as removeProviderConfig, } from "./config/index.js";
 export type { AllProvidersResult } from "./config/index.js";
 export { readPackageDependencies, categorizeLibrary } from "./graph/thirdPartyLibs.js";
 export { analyzePipeline } from "./pipeline/index.js";

package/dist/index.js

@@ -11,7 +11,7 @@ export * from "./config/types.js";
 export { queue } from "./jobs/index.js";
 export { storage } from "./storage/index.js";
 // Config helpers
-export { resolveConfig, initConfig, maskConfig, writeConfig, resolveAllProviders, setActiveProvider, removeProvider as removeProviderConfig, } from "./config/index.js";
+export { resolveConfig, hasSummarizationConfigured, initConfig, maskConfig, writeConfig, resolveAllProviders, setActiveProvider, removeProvider as removeProviderConfig, } from "./config/index.js";
 // Pre-scan helpers
 export { readPackageDependencies, categorizeLibrary } from "./graph/thirdPartyLibs.js";
 // Pipeline & analysis

package/dist/jobs/queue/memory.js

@@ -116,7 +116,18 @@ export class InMemoryQueue {
             this._markCancelled(jobId, true);
             return true;
         }
-        // Running or paused — signal the runner
+        // Paused: NO runner loop is active (the summarizer returned at the
+        // pause checkpoint), so a cancelRequested flag would sit forever —
+        // resumeJob() even clears it. Mark cancelled right here. The
+        // checkpoint file stays on disk (cleanedUp=false), so a later
+        // summarize resumes from where it stopped.
+        if (job.status === "paused") {
+            job.cancelRequested = true;
+            job.pauseRequested = false;
+            this._markCancelled(jobId, false);
+            return true;
+        }
+        // Running — signal the runner (checked between batches)
         job.cancelRequested = true;
         job.pauseRequested = false; // clear pause signal if both were set
         console.log(`🚫 Cancel requested for job ${jobId}`);

package/dist/parser/extractors/classes.js

@@ -17,7 +17,7 @@
 // Out of scope (deliberate): INTERFACE / ENUM / STRUCT nodes for JS/TS.
 import { SyntaxKind } from "ts-morph";
 import { detectFunctionDirective } from "../directives.js";
-import { extractFunctionCalls, extractHookCalls, extractApiCalls, hasErrorHandling, extractThrowStatements, } from "./functions.js";
+import { extractCallsWithSites, hasErrorHandling, extractThrowStatements, } from "./functions.js";
 import { extractParams, extractReturnTypeAnnotation, extractBareTypeNames, extractReferencedInterfaces, } from "../typeUtils.js";
 // React lifecycle methods (incl. render) — flagged so consumers can tell
 // framework-registered callbacks apart from ordinary methods.
@@ -79,6 +79,12 @@ function rewriteThisCalls(calls, className, methodNames) {
         return `${className}.${rest.replace(/^#/, "")}`;
     });
 }
+// Same rewrite as rewriteThisCalls but for structured CallSite records —
+// the name must match the dotted METHOD node names for overload-aware
+// resolution in callEdges.
+function rewriteThisCallSites(callSites, className, methodNames) {
+    return callSites.map((cs) => ({ ...cs, name: rewriteThisCalls([cs.name], className, methodNames)[0] }));
+}
 function extractDecoratorNames(cls) {
     if (typeof cls.getDecorators !== "function")
         return [];
@@ -96,9 +102,8 @@ function buildMethodNode(file, className, methodName, method, methodNameSet, fil
     const filePath = file.getFilePath();
     const dotted = `${className}.${methodName}`;
     const typedParams = extractParams(method);
-    const calls = extractFunctionCalls(method);
-    const hookCalls = extractHookCalls(method);
-    const apiCalls = extractApiCalls(method);
+    const { calls, callSites: rawSites, hookCalls, apiCalls } = extractCallsWithSites(method);
+    const callSites = rewriteThisCallSites(rawSites, className, methodNameSet);
     const isAsync = typeof method.isAsync === "function" && method.isAsync();
     const hasErrors = hasErrorHandling(method);
     const throws = extractThrowStatements(method);
@@ -106,6 +111,7 @@ function buildMethodNode(file, className, methodName, method, methodNameSet, fil
     const returnType = extractReturnTypeAnnotation(method);
     const bareTypeNames = extractBareTypeNames([...typedParams.map((p) => p.type), returnType]);
     const referencedTypes = extractReferencedInterfaces(file, bareTypeNames);
+    const isOverloadSignature = typeof method.getBody === "function" ? !method.getBody() : false;
     return {
         id: makeId(filePath, dotted),
         name: dotted,
@@ -121,6 +127,8 @@ function buildMethodNode(file, className, methodName, method, methodNameSet, fil
             returnType,
             referencedTypes,
             calls: rewriteThisCalls(calls, className, methodNameSet),
+            callSites,
+            ...(isOverloadSignature && { isOverloadSignature: true }),
             hookCalls,
             apiCalls,
             isAsync,
@@ -216,9 +224,20 @@ export function extractClasses(file, fileDirective = null) {
             if (isHashPrivate)
                 node.metadata.isPrivate = true;
             nodes.push(node);
+            // Overload signatures — getMethods() returns only implementations;
+            // signatures hang off getOverloads() and become body-less METHOD nodes.
+            for (const overload of m.getOverloads?.() ?? []) {
+                const ovNode = buildMethodNode(file, name, methodName, overload, methodNameSet, fileDirective);
+                if (isHashPrivate)
+                    ovNode.metadata.isPrivate = true;
+                nodes.push(ovNode);
+            }
         }
         for (const c of cls.getConstructors()) {
             nodes.push(buildMethodNode(file, name, "constructor", c, methodNameSet, fileDirective));
+            for (const overload of c.getOverloads?.() ?? []) {
+                nodes.push(buildMethodNode(file, name, "constructor", overload, methodNameSet, fileDirective));
+            }
         }
         for (const acc of cls.getGetAccessors()) {
             const accName = acc.getName();

package/dist/parser/extractors/functions.d.ts

@@ -1,10 +1,17 @@
 import { SourceFile } from "ts-morph";
-import type { CodeNode } from "../../types.js";
+import type { CallSite, CodeNode } from "../../types.js";
 import { type RenderingBoundary } from "../directives.js";
 export declare const JS_BUILTINS: Set<string>;
+export interface ExtractedCallData {
+    calls: string[];
+    callSites: CallSite[];
+    hookCalls: string[];
+    apiCalls: string[];
+    dependencyNames: string[];
+    contextRefs: string[];
+}
+export declare function extractCallsWithSites(node: any): ExtractedCallData;
 export declare function extractFunctionCalls(node: any): string[];
-export declare function extractHookCalls(node: any): string[];
-export declare function extractApiCalls(node: any): string[];
 export declare function hasErrorHandling(node: any): boolean;
 export declare function extractThrowStatements(node: any): boolean;
 export declare function extractFunctions(file: SourceFile, fileDirective?: RenderingBoundary): CodeNode[];