devlensio 1.1.0 → 1.1.1

package/dist/extractors/runner.js

@@ -167,6 +167,7 @@ export async function runInlineExtractor(input, onStep) {
         nodes: allNodes,
         edges: allEdges,
         routes,
+        exports: parserResult.exports,
         stats,
         errors: [],
     };

package/dist/extractors/types.d.ts

@@ -1,4 +1,4 @@
-import { Language, BackendRouteNode, CodeEdge, CodeNode, ProjectFingerprint, RouteNode } from "../types.js";
+import { Language, BackendRouteNode, CodeEdge, CodeNode, ProjectFingerprint, RouteNode, GraphExports } from "../types.js";
 export interface ExtractorOptions {
     includeThirdPartyLibs?: string[];
 }
@@ -20,6 +20,7 @@ export interface ExtractorResult {
     nodes: CodeNode[];
     edges: CodeEdge[];
     routes?: (RouteNode | BackendRouteNode)[];
+    exports?: GraphExports;
     stats: ExtractorStats;
     errors: ExtractorError[];
 }

package/dist/parser/exportsMap.d.ts

@@ -0,0 +1,9 @@
+import type { Project } from "ts-morph";
+import type { CodeNode, GraphExports } from "../types.js";
+export declare function buildExportsMap(project: Project, repoPath: string, nodes: CodeNode[]): GraphExports | undefined;
+export declare function validateExportsMap(map: GraphExports, nodeIds: Set<string>): string[];
+export declare function exportsMapStats(map: GraphExports): {
+    subpaths: number;
+    names: number;
+    ambiguous: number;
+};

package/dist/parser/exportsMap.js

@@ -0,0 +1,349 @@
+// Exports Map builder — the flattened export surface of the repo, shipped in
+// the graph artifact for future cross-repo linking (see docs/EXPORTS_MAP.md).
+//
+// Architecture notes:
+//   - Must live in the parser because binding resolution needs the ts-morph
+//     Project created inside parseRepo(); a second Project would double parse
+//     cost. parseRepo() calls buildExportsMap() after the node loop, so the
+//     map is validated against the FINAL node list (only surviving, deduped,
+//     overload-suffixed ids can appear as values).
+//   - Values are ALWAYS arrays of proper nodeIds — never bare names. The
+//     cloud joins against them in one hash lookup; no second resolution step.
+//   - Overloads: multiple nodes sharing one base id (path::name) are an
+//     overload group — emitted as a plain array. Distinct base ids under one
+//     exported name are a TRUE ambiguity — also flagged in ambiguousNames.
+//   - TS resolves `export *` conflicts by EXCLUDING the name from the module's
+//     exports (same as the JS spec), so star re-exports need no special code.
+//   - Anything without a node representation (plain consts, interfaces,
+//     type aliases, anonymous defaults, namespace re-exports) is OMITTED —
+//     never fabricate an id that won't exist in the nodes array.
+//   - package.json "exports" conditions: v1 resolves one condition per subpath
+//     (import → default → require); "types"-only subpaths are skipped; wildcard
+//     patterns are skipped. Entry targets pointing into dist/build are mapped
+//     back to src/ so ids stay in the same coordinate system as the nodes.
+//   - Failures never break analysis: any error yields an absent map.
+import path from "path";
+import fs from "fs";
+const ENTRY_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+const INDEX_NAMES = ["index.ts", "index.tsx", "index.js", "index.jsx"];
+export function buildExportsMap(project, repoPath, nodes) {
+    try {
+        const pkgPath = path.join(repoPath, "package.json");
+        if (!fs.existsSync(pkgPath))
+            return undefined;
+        let pkg;
+        try {
+            pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        }
+        catch {
+            return undefined;
+        }
+        const entries = resolveEntryPoints(pkg, repoPath, project);
+        if (entries.length === 0)
+            return undefined;
+        const nodeIndex = buildNodeIndex(nodes);
+        const starCache = new Map();
+        const exports = {};
+        const ambiguousNames = {};
+        for (const entry of entries) {
+            let decls;
+            try {
+                decls = entry.file.getExportedDeclarations();
+            }
+            catch {
+                continue;
+            }
+            const explicitNames = explicitExportNames(entry.file);
+            const entryPath = entry.file.getFilePath();
+            const stars = starContributors(entry.file, starCache);
+            const perPath = {};
+            const ambiguous = [];
+            for (const [name, declList] of decls) {
+                const isExplicit = explicitNames.has(name) || declList.some((d) => d.getSourceFile().getFilePath() === entryPath);
+                if (!isExplicit) {
+                    const contributors = stars.get(name);
+                    if (contributors && contributors.size > 1) {
+                        ambiguous.push(name);
+                        continue;
+                    }
+                }
+                const resolved = [];
+                for (const decl of declList) {
+                    const hit = resolveDeclarationToNode(decl, repoPath, nodeIndex);
+                    if (hit)
+                        resolved.push(hit);
+                }
+                const ids = [...new Set(resolved.map((r) => r.id))].sort();
+                if (ids.length === 0)
+                    continue;
+                const bases = [...new Set(resolved.map((r) => r.base))];
+                if (bases.length > 1)
+                    ambiguous.push(name);
+                perPath[name] = ids;
+            }
+            if (Object.keys(perPath).length > 0)
+                exports[entry.subpath] = perPath;
+            if (ambiguous.length > 0)
+                ambiguousNames[entry.subpath] = ambiguous;
+        }
+        if (Object.keys(exports).length === 0)
+            return undefined;
+        return { exports, ambiguousNames };
+    }
+    catch {
+        return undefined;
+    }
+}
+function explicitExportNames(sf) {
+    const names = new Set();
+    for (const ed of sf.getExportDeclarations()) {
+        for (const spec of ed.getNamedExports())
+            names.add(spec.getName());
+    }
+    return names;
+}
+function starContributors(sf, cache) {
+    const key = sf.getFilePath();
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const result = new Map();
+    const seen = new Set([key]);
+    const stack = [sf];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const ed of current.getExportDeclarations()) {
+            if (ed.getNamedExports().length > 0)
+                continue;
+            const target = ed.getModuleSpecifierSourceFile();
+            if (!target || seen.has(target.getFilePath()))
+                continue;
+            seen.add(target.getFilePath());
+            const targetPath = target.getFilePath();
+            let targetDecls;
+            try {
+                targetDecls = target.getExportedDeclarations();
+            }
+            catch {
+                continue;
+            }
+            for (const [name, declList] of targetDecls) {
+                const isLocal = declList.some((d) => d.getSourceFile().getFilePath() === targetPath);
+                if (isLocal) {
+                    if (!result.has(name))
+                        result.set(name, new Set());
+                    result.get(name).add(targetPath);
+                }
+                else {
+                    const deeper = starContributors(target, cache);
+                    const contributors = deeper.get(name);
+                    if (contributors) {
+                        if (!result.has(name))
+                            result.set(name, new Set());
+                        for (const f of contributors)
+                            result.get(name).add(f);
+                    }
+                }
+            }
+            stack.push(target);
+        }
+    }
+    cache.set(key, result);
+    return result;
+}
+function buildNodeIndex(nodes) {
+    const index = new Map();
+    for (const node of nodes) {
+        const base = `${node.filePath}::${node.name}`;
+        if (!index.has(base))
+            index.set(base, []);
+        index.get(base).push(node);
+    }
+    return index;
+}
+function resolveEntryPoints(pkg, repoPath, project) {
+    const entries = [];
+    if (pkg.exports !== undefined) {
+        const normalized = normalizeExportsField(pkg.exports);
+        for (const [subpath, target] of normalized) {
+            const file = resolveTargetFile(repoPath, target, project);
+            if (file)
+                entries.push({ subpath, file });
+        }
+        return entries;
+    }
+    const fallback = pkg.main ?? pkg.module;
+    if (fallback) {
+        const file = resolveTargetFile(repoPath, fallback, project);
+        if (file)
+            entries.push({ subpath: ".", file });
+    }
+    else {
+        for (const candidate of INDEX_NAMES.map((n) => path.join("src", n)).concat(INDEX_NAMES)) {
+            const file = resolveTargetFile(repoPath, candidate, project);
+            if (file) {
+                entries.push({ subpath: ".", file });
+                break;
+            }
+        }
+    }
+    return entries;
+}
+function normalizeExportsField(field) {
+    const out = [];
+    if (typeof field === "string") {
+        out.push([".", field]);
+        return out;
+    }
+    if (typeof field !== "object" || field === null)
+        return out;
+    for (const [subpath, value] of Object.entries(field)) {
+        if (subpath.includes("*"))
+            continue;
+        if (typeof value === "string") {
+            out.push([subpath, value]);
+            continue;
+        }
+        if (typeof value !== "object" || value === null)
+            continue;
+        const conditions = value;
+        const chosen = (typeof conditions.import === "string" && conditions.import) ||
+            (typeof conditions.default === "string" && conditions.default) ||
+            (typeof conditions.require === "string" && conditions.require);
+        if (typeof chosen === "string" && chosen)
+            out.push([subpath, chosen]);
+    }
+    return out;
+}
+function resolveTargetFile(repoPath, target, project) {
+    if (typeof target !== "string" || !target)
+        return undefined;
+    let rel = target.replace(/^\.\//, "").split(/[?#]/)[0];
+    if (rel.endsWith(".d.ts"))
+        return undefined;
+    const candidates = [rel];
+    const distMatch = rel.match(/^(dist|build)(\/|$)/);
+    if (distMatch) {
+        candidates.push("src" + rel.slice(distMatch[1].length));
+    }
+    for (const candidate of candidates) {
+        const stem = candidate.replace(/\.[^.]+$/, "");
+        const tries = new Set([candidate]);
+        for (const ext of ENTRY_EXTENSIONS)
+            tries.add(stem + ext);
+        for (const idx of INDEX_NAMES)
+            tries.add(path.posix.join(candidate, idx));
+        for (const tryPath of tries) {
+            if (tryPath.endsWith(".d.ts"))
+                continue;
+            const abs = path.resolve(repoPath, tryPath);
+            if (!fs.existsSync(abs) || fs.statSync(abs).isDirectory())
+                continue;
+            const sf = project.getSourceFile(abs);
+            if (sf)
+                return sf;
+        }
+    }
+    return undefined;
+}
+function resolveDeclarationToNode(decl, repoPath, nodeIndex) {
+    const name = declarationName(decl);
+    if (!name)
+        return undefined;
+    const relPath = path.relative(repoPath, decl.getSourceFile().getFilePath()).replace(/\\/g, "/");
+    const base = `${relPath}::${name}`;
+    const candidates = nodeIndex.get(base);
+    if (!candidates || candidates.length === 0)
+        return undefined;
+    if (candidates.length === 1)
+        return { id: candidates[0].id, base };
+    const match = matchOverloadedNode(decl, candidates);
+    return match ? { id: match.id, base } : undefined;
+}
+function declarationName(decl) {
+    const getName = decl.getName;
+    if (typeof getName === "function") {
+        try {
+            const own = getName.call(decl);
+            if (typeof own === "string" && own.length > 0)
+                return own;
+        }
+        catch {
+            // fall through to symbol
+        }
+    }
+    const sym = decl.getSymbol()?.getName();
+    if (sym && sym !== "default" && !sym.startsWith("__"))
+        return sym;
+    return undefined;
+}
+function matchOverloadedNode(decl, candidates) {
+    const paramTypes = declarationParamTypes(decl);
+    if (paramTypes === undefined)
+        return undefined;
+    const declKey = signatureKeyFromTypes(paramTypes);
+    const matches = candidates.filter((node) => {
+        const params = node.metadata?.parameters;
+        if (!Array.isArray(params))
+            return false;
+        return signatureKeyFromNodeParams(params) === declKey;
+    });
+    return matches.length >= 1 ? matches[0] : undefined;
+}
+function declarationParamTypes(decl) {
+    const anyDecl = decl;
+    if (typeof anyDecl.getParameters !== "function")
+        return undefined;
+    try {
+        const params = anyDecl.getParameters();
+        if (!Array.isArray(params))
+            return undefined;
+        return params.map((p) => {
+            const t = p.getTypeNode?.()?.getText() ?? "unknown";
+            if (p.isRest?.())
+                return `...${t}`;
+            if (p.isOptional?.())
+                return `${t}?`;
+            return t;
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function signatureKeyFromTypes(types) {
+    return `(${types.join(",")})`;
+}
+function signatureKeyFromNodeParams(params) {
+    return `(${params
+        .map((p) => {
+        const t = typeof p?.type === "string" && p.type.length > 0 ? p.type : "unknown";
+        if (p?.isRest)
+            return `...${t}`;
+        if (p?.isOptional)
+            return `${t}?`;
+        return t;
+    })
+        .join(",")})`;
+}
+export function validateExportsMap(map, nodeIds) {
+    const dangling = [];
+    for (const perPath of Object.values(map.exports)) {
+        for (const ids of Object.values(perPath)) {
+            for (const id of ids) {
+                if (!nodeIds.has(id))
+                    dangling.push(id);
+            }
+        }
+    }
+    return [...new Set(dangling)];
+}
+export function exportsMapStats(map) {
+    let names = 0;
+    let ambiguous = 0;
+    for (const perPath of Object.values(map.exports))
+        names += Object.keys(perPath).length;
+    for (const list of Object.values(map.ambiguousNames))
+        ambiguous += list.length;
+    return { subpaths: Object.keys(map.exports).length, names, ambiguous };
+}

package/dist/parser/exportsMap.test.d.ts

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

package/dist/parser/exportsMap.test.js

@@ -0,0 +1,324 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { parseRepo } from "./index.js";
+import { buildLookupMaps } from "../graph/buildLookup.js";
+import { detectImportEdges } from "../graph/edges/importEdges.js";
+import { detectCallEdges } from "../graph/edges/callEdges.js";
+function createFakeRepo(files) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devlens-exports-map-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("exports map (cross-repo linkage)", () => {
+    it("returns undefined when the repo has no package.json", () => {
+        const repo = createFakeRepo({
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+        });
+        const result = parseRepo(repo);
+        expect(result.exports).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("maps direct exports to single-element arrays of proper nodeIds", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { alpha } from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports).toBeDefined();
+        expect(exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        expect(exports.ambiguousNames).toEqual({});
+        deleteFakeRepo(repo);
+    });
+    it("flattens chained re-exports to the final definition node", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { beta } from './helpers';\n`,
+            "src/helpers.ts": `export { beta } from './dateUtils';\n`,
+            "src/dateUtils.ts": `export function beta(d: string) { return d; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["beta"]).toEqual(["src/dateUtils.ts::beta"]);
+        deleteFakeRepo(repo);
+    });
+    it("keys the map by the name the importer sees when aliases are involved", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { formatDate as fmtDate } from './dateUtils';\n`,
+            "src/dateUtils.ts": `export function formatDate(d: string) { return d; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["fmtDate"]).toEqual(["src/dateUtils.ts::formatDate"]);
+        expect(exports.exports["."]["formatDate"]).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("handles the name-swap case via bindings, never by string matching", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `
+        export { formatDate as fmtDate } from './dateUtils';
+        export { fmtDate as formatDate } from './misc';
+      `,
+            "src/dateUtils.ts": `export function formatDate(d: string) { return d; }\n`,
+            "src/misc.ts": `export function fmtDate(x: number) { return x; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["fmtDate"]).toEqual(["src/dateUtils.ts::formatDate"]);
+        expect(exports.exports["."]["formatDate"]).toEqual(["src/misc.ts::fmtDate"]);
+        expect(exports.ambiguousNames).toEqual({});
+        deleteFakeRepo(repo);
+    });
+    it("emits one map key per package.json exports subpath", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({
+                name: "fakepkg",
+                exports: {
+                    ".": "./src/index.ts",
+                    "./server": "./src/server/index.ts",
+                },
+            }),
+            "src/index.ts": `export { alpha } from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+            "src/server/index.ts": `export { serve } from './serve';\n`,
+            "src/server/serve.ts": `export function serve() { return 2; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        expect(exports.exports["./server"]["serve"]).toEqual(["src/server/serve.ts::serve"]);
+        deleteFakeRepo(repo);
+    });
+    it("resolves dist entry targets back to src (same coordinate system as nodes)", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({
+                name: "fakepkg",
+                exports: { ".": { import: "./dist/index.js", types: "./dist/index.d.ts" } },
+            }),
+            "src/index.ts": `export { alpha } from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        deleteFakeRepo(repo);
+    });
+    it("falls back to main/module when the exports field is absent", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./dist/index.js" }),
+            "src/index.ts": `export { alpha } from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        deleteFakeRepo(repo);
+    });
+    it("emits distinct #arity suffixed nodeIds for same-name different-arity exports", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { formatValue } from './arity';\n`,
+            "src/arity.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+        export function formatValue(v: string, n: number) { return v.repeat(n); }
+      `,
+        });
+        const { exports } = parseRepo(repo);
+        const ids = exports.exports["."]["formatValue"].sort();
+        expect(ids).toEqual(["src/arity.ts::formatValue#1", "src/arity.ts::formatValue#2"]);
+        expect(exports.ambiguousNames["."]).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("emits distinct sig8-suffixed nodeIds for same-arity different-type exports", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { decode } from './types';\n`,
+            "src/types.ts": `
+        export function decode(input: string, mode: string) { return input; }
+        export function decode(input: number, mode: string) { return String(input); }
+      `,
+        });
+        const { exports } = parseRepo(repo);
+        const ids = exports.exports["."]["decode"].sort();
+        expect(ids.length).toBe(2);
+        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]);
+        deleteFakeRepo(repo);
+    });
+    it("excludes star re-export conflicts per the JS module spec (name absent, not guessed)", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export * from './a';\nexport * from './b';\n`,
+            "src/a.ts": `export function clash() { return 1; }\nexport function onlyA() { return 2; }\n`,
+            "src/b.ts": `export function clash() { return 3; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["clash"]).toBeUndefined();
+        expect(exports.exports["."]["onlyA"]).toEqual(["src/a.ts::onlyA"]);
+        expect(exports.ambiguousNames["."]).toEqual(["clash"]);
+        deleteFakeRepo(repo);
+    });
+    it("resolves star re-exports like named ones", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export * from './barrel';\n`,
+            "src/barrel.ts": `export * from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        deleteFakeRepo(repo);
+    });
+    it("maps named default exports and omits anonymous ones", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `
+        export { default as named } from './named';
+        export { default as anon } from './anon';
+      `,
+            "src/named.ts": `export default function loader() { return 1; }\n`,
+            "src/anon.ts": `export default () => 2;\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["named"]).toEqual(["src/named.ts::loader"]);
+        expect(exports.exports["."]["anon"]).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("omits exports that have no node representation (consts, types, interfaces)", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export * from './mixed';\n`,
+            "src/mixed.ts": `
+        export const config = { a: 1 };
+        export type Maybe = string | null;
+        export interface Opts { a: number }
+        export function run(o: Opts) { return o.a; }
+      `,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["run"]).toEqual(["src/mixed.ts::run"]);
+        expect(exports.exports["."]["config"]).toBeUndefined();
+        expect(exports.exports["."]["Maybe"]).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("survives re-export cycles without hanging and omits the undefined name", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { gone } from './a';\n`,
+            "src/a.ts": `export { gone } from './b';\n`,
+            "src/b.ts": `export { gone } from './a';\n`,
+        });
+        const { exports } = parseRepo(repo);
+        const gone = exports ? exports.exports["."]?.["gone"] : undefined;
+        expect(gone).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("maps exported classes and exported const arrow functions to their nodes", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export * from './things';\n`,
+            "src/things.ts": `
+        export class Widget { render() { return 1; } }
+        export const handler = () => 2;
+      `,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["Widget"]).toEqual(["src/things.ts::Widget"]);
+        expect(exports.exports["."]["handler"]).toEqual(["src/things.ts::handler"]);
+        deleteFakeRepo(repo);
+    });
+    it("never references a nodeId that is absent from the nodes array", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export * from './a';\nexport { beta } from './b';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+            "src/b.ts": `export function beta() { return 2; }\n`,
+        });
+        const result = parseRepo(repo);
+        const nodeIds = new Set(result.nodes.map((n) => n.id));
+        for (const perPath of Object.values(result.exports.exports)) {
+            for (const ids of Object.values(perPath)) {
+                for (const id of ids)
+                    expect(nodeIds.has(id)).toBe(true);
+            }
+        }
+        deleteFakeRepo(repo);
+    });
+    it("resolves one condition per subpath: import beats require and types", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({
+                name: "fakepkg",
+                exports: {
+                    ".": { import: "./src/index.ts", require: "./src/legacy.ts", types: "./src/index.d.ts" },
+                    "./legacy": { require: "./src/legacy.ts" },
+                    "./types-only": { types: "./src/index.d.ts" },
+                },
+            }),
+            "src/index.ts": `export { alpha } from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+            "src/legacy.ts": `export function alpha() { return 2; }\n`,
+            "src/index.d.ts": `export declare function alpha(): number;\n`,
+        });
+        const { exports } = parseRepo(repo);
+        expect(exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        expect(exports.exports["./legacy"]["alpha"]).toEqual(["src/legacy.ts::alpha"]);
+        expect(exports.exports["./types-only"]).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("skips unparseable files and still builds the map from valid ones", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { alpha } from './a';\n`,
+            "src/a.ts": `export function alpha() { return 1; }\n`,
+            "src/broken.ts": `export function broken( {\n`,
+        });
+        const result = parseRepo(repo);
+        expect(result.exports).toBeDefined();
+        expect(result.exports.exports["."]["alpha"]).toEqual(["src/a.ts::alpha"]);
+        expect(result.exports.exports["."]["broken"]).toBeUndefined();
+        deleteFakeRepo(repo);
+    });
+    it("call-site narrowing picks within an exported overload group (map ids = edge targets)", () => {
+        const repo = createFakeRepo({
+            "package.json": JSON.stringify({ name: "fakepkg", main: "./src/index.ts" }),
+            "src/index.ts": `export { formatValue } from './overloads';\n`,
+            "src/overloads.ts": `
+        export function formatValue(v: string) { return v.trim(); }
+        export function formatValue(v: string, n: number) { return v.repeat(n); }
+      `,
+            "src/caller.ts": `
+        import { formatValue } from './index';
+        export function useOne() { return formatValue("x"); }
+        export function useTwo() { return formatValue("x", 3); }
+      `,
+        });
+        const parsed = parseRepo(repo);
+        const lookup = buildLookupMaps(parsed.nodes);
+        detectImportEdges(lookup, repo);
+        const callResult = detectCallEdges(parsed.nodes, lookup);
+        const { exports } = parsed;
+        const group = exports.exports["."]["formatValue"];
+        expect(group.length).toBe(2);
+        const targets = callResult.edges
+            .filter((e) => e.type === "CALLS" && e.from === "src/caller.ts::useOne")
+            .map((e) => e.to);
+        expect(targets.length).toBe(1);
+        expect(group).toContain(targets[0]);
+        const targetsTwo = callResult.edges
+            .filter((e) => e.type === "CALLS" && e.from === "src/caller.ts::useTwo")
+            .map((e) => e.to);
+        expect(targetsTwo.length).toBe(1);
+        expect(group).toContain(targetsTwo[0]);
+        expect(targets[0]).not.toBe(targetsTwo[0]);
+        // every narrowed target is a real node the map points at — no phantom ids
+        const nodeIds = new Set(parsed.nodes.map((n) => n.id));
+        for (const t of [...targets, ...targetsTwo])
+            expect(nodeIds.has(t)).toBe(true);
+        deleteFakeRepo(repo);
+    });
+});

package/dist/parser/index.d.ts

@@ -1,6 +1,7 @@
-import type { CodeNode } from "../types.js";
+import type { CodeNode, GraphExports } from "../types.js";
 export interface ParserResult {
     nodes: CodeNode[];
+    exports?: GraphExports;
     stats: {
         totalFiles: number;
         totalNodes: number;

package/dist/parser/index.js

@@ -9,6 +9,7 @@ import { extractObjectMethods } from "./extractors/objectMethods.js";
 import { extractClasses } from "./extractors/classes.js";
 import { detectFileDirective } from "./directives.js";
 import { applyOverloadDisambiguation } from "./overloads.js";
+import { buildExportsMap, validateExportsMap, exportsMapStats } from "./exportsMap.js";
 import { createHash } from "crypto";
 // Directories to skip entirely while walking
 const IGNORE_DIRS = [
@@ -164,8 +165,40 @@ export function parseRepo(repoPath) {
     const storeCount = allNodes.filter((n) => n.type === "STATE_STORE").length;
     const classCount = allNodes.filter((n) => n.type === "CLASS").length;
     const methodCount = allNodes.filter((n) => n.type === "METHOD").length;
+    let exports;
+    try {
+        const built = buildExportsMap(project, repoPath, allNodes);
+        if (built) {
+            const dangling = validateExportsMap(built, new Set(allNodes.map((n) => n.id)));
+            if (dangling.length > 0) {
+                console.warn(`Exports map: dropping ${dangling.length} dangling nodeId references`);
+                for (const perPath of Object.values(built.exports)) {
+                    for (const [name, ids] of Object.entries(perPath)) {
+                        const filtered = ids.filter((id) => !dangling.includes(id));
+                        if (filtered.length > 0)
+                            perPath[name] = filtered;
+                        else
+                            delete perPath[name];
+                    }
+                }
+                for (const [subpath, perPath] of Object.entries(built.exports)) {
+                    if (Object.keys(perPath).length === 0)
+                        delete built.exports[subpath];
+                }
+            }
+            if (Object.keys(built.exports).length > 0) {
+                exports = built;
+                const s = exportsMapStats(built);
+                console.log(`  Exports map: ${s.names} names across ${s.subpaths} subpath(s), ${s.ambiguous} ambiguous`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`Exports map build failed — continuing without it: ${err}`);
+    }
     return {
         nodes: allNodes,
+        exports,
         stats: {
             totalFiles: sourceFiles.length,
             totalNodes: allNodes.length,

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

@@ -83,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlensio",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Codebase intelligence engine for TypeScript/JavaScript/React/Next.js, Python, Java, Go, and Rust repositories.",
   "type": "module",
   "main": "./dist/index.js",