@snevins/repo-mapper 1.0.3 → 1.1.0

package/dist/index.js

@@ -1,26 +1,61 @@
 #!/usr/bin/env node
-import { writeFile, stat } from "node:fs/promises";
-import { resolve, relative } from "node:path";
-import { parseCliArgs } from "./cli.js";
+import { writeFile, stat, readFile } from "node:fs/promises";
+import { resolve, relative, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCliArgs, HelpRequestedError, VersionRequestedError } from "./cli.js";
 import { loadCache, getCachedTags, setCacheEntry, saveCache } from "./cache.js";
-import { discoverFiles, DEFAULT_IGNORED_PATTERNS } from "./files.js";
+import { discoverFiles, DEFAULT_IGNORED_PATTERNS, isTestOrScriptPath } from "./files.js";
+import { getExtensionsForLanguage } from "./languages.js";
 import { initParser, parseFile, shutdownParser } from "./parser.js";
-import { buildFileGraph } from "./graph.js";
+import { buildFileGraph, buildImportGraph } from "./graph.js";
 import { computePageRank } from "./pagerank.js";
-import { buildPersonalization, rankDefinitions } from "./ranking.js";
+import { buildFocusPersonalization, buildEntrypointPersonalization, rankDefinitions, adjustFileRanks, combineRanks } from "./ranking.js";
+import { computeFileDegrees } from "./graph.js";
 import { fitToTokenBudget } from "./output.js";
+import { detectDuplicates } from "./dedup.js";
 async function main() {
     const args = parseCliArgs(process.argv.slice(2));
     const { options } = args;
     // Determine root directory (first path or cwd)
     const firstPath = args.paths[0];
     const rootDir = firstPath !== undefined ? resolve(firstPath) : process.cwd();
-    // Resolve focus files to relative paths
-    const focusFiles = options.focus.map((f) => relative(rootDir, resolve(f)));
-    const focusSet = new Set(focusFiles);
+    // Resolve focus files to relative paths (resolve relative to rootDir, not CWD)
+    const focusFiles = options.focus.map((f) => relative(rootDir, resolve(rootDir, f)));
+    // Validate focus files exist
+    const validFocusFiles = [];
+    for (const relPath of focusFiles) {
+        const absPath = join(rootDir, relPath);
+        try {
+            await stat(absPath);
+            validFocusFiles.push(relPath);
+        }
+        catch {
+            console.error(`Warning: Focus file "${relPath}" does not exist, ignoring`);
+        }
+    }
+    const focusSet = new Set(validFocusFiles);
     if (options.verbose) {
         console.error(`Root: ${rootDir}`);
-        console.error(`Focus files: ${String(focusFiles.length)}`);
+        console.error(`Focus files: ${String(validFocusFiles.length)}`);
+    }
+    // Build extensions filter from --type flags
+    let extensions;
+    if (options.type.length > 0) {
+        extensions = new Set();
+        for (const langId of options.type) {
+            const langExts = getExtensionsForLanguage(langId);
+            if (!langExts) {
+                console.error(`Warning: Unknown language type "${langId}", ignoring`);
+                continue;
+            }
+            for (const ext of langExts) {
+                extensions.add(ext);
+            }
+        }
+        if (extensions.size === 0) {
+            console.error("Error: No valid language types specified");
+            process.exit(1);
+        }
     }
     // 1. Discover files (apply ignore patterns unless --no-ignore)
     const ignoredPatterns = options.noIgnore
@@ -28,8 +63,11 @@ async function main() {
         : [...DEFAULT_IGNORED_PATTERNS, ...options.ignore]; // defaults + custom
     const discoveryResult = await discoverFiles({
         rootDir,
+        extensions,
         ignoredPatterns: ignoredPatterns.length > 0 ? ignoredPatterns : undefined,
+        includePatterns: options.include.length > 0 ? options.include : undefined,
         maxFiles: options.maxFiles,
+        ignoredDirs: undefined,
     });
     const files = discoveryResult.files;
     if (discoveryResult.wasLimited) {
@@ -88,21 +126,73 @@ async function main() {
         console.error(`Cache: ${String(cacheHits)} hits, ${String(cacheMisses)} misses`);
         console.error(`Parsed ${String(defs.length)} definitions, ${String(refs.length)} references`);
     }
-    // 3. Build graph
-    const graph = buildFileGraph(allTags);
-    // 4. Compute PageRank
-    const personalization = focusFiles.length > 0
-        ? buildPersonalization(focusFiles)
-        : undefined;
-    const fileRanks = computePageRank(graph, { personalization });
-    // 5. Rank definitions (exclude focus files)
-    const rankedDefs = rankDefinitions(graph, fileRanks, focusSet);
+    // 3. Build graphs (downweight edges from test/script files)
+    // Two-stage ranking: import graph for structure, ref graph for density
+    const TEST_WEIGHT = 0.2;
+    const edgeWeightMultiplier = (path) => isTestOrScriptPath(path) ? TEST_WEIGHT : 1.0;
+    // Import graph: binary edges (1 per file→file connection) for structural importance
+    const importGraph = buildImportGraph(allTags, { edgeWeightMultiplier });
+    // Ref graph: weighted edges (ref counts) for density and definition ranking
+    const refGraph = buildFileGraph(allTags, { edgeWeightMultiplier });
+    // 4. Two-phase PageRank
+    // Phase 1: Compute structural importance from import graph
+    let personalization;
+    if (validFocusFiles.length > 0) {
+        personalization = buildFocusPersonalization(validFocusFiles, refGraph);
+    }
+    else {
+        // Auto-detect entrypoints for default personalization
+        const entrypointMap = buildEntrypointPersonalization(importGraph.nodes);
+        personalization = entrypointMap.size > 0 ? entrypointMap : undefined;
+    }
+    const structuralRanks = computePageRank(importGraph, { personalization });
+    // Phase 2: Combine structural rank with reference density
+    const rawFileRanks = combineRanks(structuralRanks, refGraph);
+    // 5. Detect duplicate files (copy-pasted code)
+    const tagsByFile = new Map();
+    for (const tag of allTags) {
+        const existing = tagsByFile.get(tag.relPath);
+        if (existing) {
+            existing.push(tag);
+        }
+        else {
+            tagsByFile.set(tag.relPath, [tag]);
+        }
+    }
+    const duplicates = detectDuplicates(tagsByFile);
+    if (options.verbose && duplicates.size > 0) {
+        // Count unique duplicate groups
+        const uniqueGroups = new Set([...duplicates.values()].map((g) => g.fingerprint));
+        console.error(`Detected ${String(uniqueGroups.size)} duplicate file group(s)`);
+    }
+    // 6. Apply architecture-aware adjustments (utility penalty, entry boost, diversity, duplicates)
+    const degrees = computeFileDegrees(refGraph);
+    const fileRanks = adjustFileRanks(rawFileRanks, degrees, refGraph.nodes, duplicates);
+    // 7. Rank definitions (exclude focus files)
+    const rankedDefs = rankDefinitions(refGraph, fileRanks, focusSet);
     if (options.verbose) {
         console.error(`Ranked ${String(rankedDefs.length)} definitions`);
     }
-    // 6. Fit to token budget and format output
-    const output = fitToTokenBudget(rankedDefs, graph, fileRanks, options.tokens, focusFiles.length > 0 ? focusFiles : undefined);
-    // 7. Write output
+    // Warn if focus file results are dominated by utility paths
+    if (validFocusFiles.length > 0 && rankedDefs.length >= 2) {
+        const UTILITY_PATTERNS = ["utils/", "lib/", "common/", "shared/", "helpers/"];
+        const topN = rankedDefs.slice(0, Math.min(3, rankedDefs.length));
+        const utilityCount = topN.filter((d) => UTILITY_PATTERNS.some((p) => d.file.includes(p))).length;
+        if (utilityCount >= 2) {
+            console.error(`Tip: Top results are utility files. Try subdirectory scoping instead: ` +
+                `repo-mapper ./path/to/module -t ${String(options.tokens)}`);
+        }
+    }
+    // Warn if output is suspiciously sparse with large token budget
+    const SPARSE_THRESHOLD = 5;
+    const LARGE_BUDGET_THRESHOLD = 1000;
+    if (options.tokens >= LARGE_BUDGET_THRESHOLD && rankedDefs.length < SPARSE_THRESHOLD) {
+        console.error(`Warning: Output is sparse (${String(rankedDefs.length)} definitions) with ${String(options.tokens)} token budget. ` +
+            `This may indicate overly broad ignore patterns or missing language support.`);
+    }
+    // 8. Fit to token budget and format output
+    const output = fitToTokenBudget(rankedDefs, refGraph, fileRanks, options.tokens, validFocusFiles.length > 0 ? validFocusFiles : undefined);
+    // 9. Write output
     if (options.output) {
         await writeFile(options.output, output);
         if (options.verbose) {
@@ -113,18 +203,50 @@ async function main() {
         console.log(output);
     }
 }
-main().catch((err) => {
+const USAGE = `Usage: repo-mapper [paths...] [options]
+
+Options:
+  -h, --help              Show this help message
+  -V, --version           Show version number
+  -t, --tokens <n>        Max tokens (default: 2000)
+  -f, --focus <file>      Focus file (repeatable)
+  -o, --output <file>     Output file
+  -r, --refresh           Ignore cache
+  -v, --verbose           Verbose output
+  --ignore <pattern>      Add ignore pattern (repeatable)
+  --include <pattern>     Only include files matching pattern (repeatable)
+  --no-ignore             Disable default ignore patterns
+  --max-files <n>         Max files to process (default: 10000, 0=unlimited)
+  --type <lang>           Filter by language: ts, js, python, go, rust, solidity (repeatable)
+
+Examples:
+  repo-mapper .                     # Map current directory
+  repo-mapper ./src -t 3000         # Map src/ with larger budget
+  repo-mapper . -f src/api.ts       # Bias ranking toward api.ts
+  repo-mapper . --type ts           # Only TypeScript files
+  repo-mapper . -v                  # Show progress info`;
+async function getVersion() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const packagePath = join(__dirname, "..", "package.json");
+    const content = await readFile(packagePath, "utf-8");
+    const pkg = JSON.parse(content);
+    return pkg.version;
+}
+main().catch(async (err) => {
+    // --help or -h: print usage and exit success
+    if (err instanceof HelpRequestedError) {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    // --version or -V: print version and exit success
+    if (err instanceof VersionRequestedError) {
+        const version = await getVersion();
+        console.log(version);
+        process.exit(0);
+    }
+    // Other errors: print error + usage and exit failure
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`Error: ${message}`);
-    console.error("\nUsage: repo-mapper [paths...] [options]");
-    console.error("Options:");
-    console.error("  -t, --tokens <n>      Max tokens (default: 1024)");
-    console.error("  -f, --focus <file>    Focus file (repeatable)");
-    console.error("  -o, --output <file>   Output file");
-    console.error("  -r, --refresh         Ignore cache");
-    console.error("  -v, --verbose         Verbose output");
-    console.error("  --ignore <pattern>    Add ignore pattern (repeatable)");
-    console.error("  --no-ignore           Disable default ignore patterns");
-    console.error("  --max-files <n>       Max files to process (default: 10000, 0=unlimited)");
+    console.error(`Error: ${message}\n`);
+    console.error(USAGE);
     process.exit(1);
 });

package/dist/languages.d.ts

@@ -38,3 +38,8 @@ export declare function isTreeSitterSupported(ext: string): boolean;
  * If no config provided, uses TS/JS builtins as default.
  */
 export declare function isBuiltin(name: string, config?: LanguageConfig): boolean;
+/**
+ * Get file extensions for a language ID or alias.
+ * Returns undefined for unknown languages.
+ */
+export declare function getExtensionsForLanguage(langId: string): ReadonlySet<string> | undefined;

package/dist/languages.js

@@ -607,3 +607,24 @@ export function isBuiltin(name, config) {
     const builtins = config?.builtins ?? TS_JS_BUILTINS;
     return builtins.has(name);
 }
+/**
+ * Short aliases for common language IDs.
+ */
+const LANG_ALIASES = {
+    ts: "typescript",
+    js: "javascript",
+    py: "python",
+    rs: "rust",
+    sol: "solidity",
+};
+/**
+ * Get file extensions for a language ID or alias.
+ * Returns undefined for unknown languages.
+ */
+export function getExtensionsForLanguage(langId) {
+    const normalized = LANG_ALIASES[langId] ?? langId;
+    const config = LANGUAGE_REGISTRY[normalized];
+    if (!config)
+        return undefined;
+    return new Set(config.extensions);
+}

package/dist/output.d.ts

@@ -1,11 +1,17 @@
 import type { RankedDefinition, FileGraph } from "./types.js";
 /**
- * Format output per spec §3.5.
- * Files sorted by PageRank descending.
+ * Get module name (first path segment) from a file path.
+ * Returns "(root)" for files in the root directory.
+ */
+export declare function getModuleName(path: string): string;
+/**
+ * Format output per spec §3.5, grouped by module.
+ * Modules sorted by highest-ranked file descending.
+ * Files within module sorted by PageRank descending.
  * Definitions within file sorted by line ascending.
  * Line numbers right-aligned to max width.
  */
-export declare function formatOutput(defs: readonly RankedDefinition[], graph: FileGraph, fileRanks: ReadonlyMap<string, number>, focusFiles?: readonly string[]): string;
+export declare function formatOutput(defs: readonly RankedDefinition[], graph: FileGraph, fileRanks: ReadonlyMap<string, number>, focusFiles?: readonly string[], maxFilesPerModule?: number): string;
 /**
  * Fit ranked definitions to token budget using binary search.
  * Returns the largest output that fits within the budget.
@@ -16,4 +22,4 @@ export declare function formatOutput(defs: readonly RankedDefinition[], graph: F
  * 3. If tokens ≤ budget, try more; else try fewer
  * 4. Return best fit
  */
-export declare function fitToTokenBudget(defs: readonly RankedDefinition[], graph: FileGraph, fileRanks: ReadonlyMap<string, number>, tokenBudget: number, focusFiles?: readonly string[]): string;
+export declare function fitToTokenBudget(defs: readonly RankedDefinition[], graph: FileGraph, fileRanks: ReadonlyMap<string, number>, tokenBudget: number, focusFiles?: readonly string[], maxFilesPerModule?: number): string;

package/dist/output.js

@@ -1,11 +1,63 @@
 import { estimateTokens } from "./tokens.js";
+/**
+ * Max definitions per unique name in output to prevent repetition.
+ */
+const MAX_DEFS_PER_NAME = 2;
+/**
+ * Default max files per module to spread budget across modules.
+ */
+const MAX_FILES_PER_MODULE = 5;
+/**
+ * Top K files globally guaranteed inclusion regardless of per-module limits.
+ */
+const GLOBAL_TOP_K = 50;
+/**
+ * Get module name (first path segment) from a file path.
+ * Returns "(root)" for files in the root directory.
+ */
+export function getModuleName(path) {
+    const slash = path.indexOf("/");
+    return slash === -1 ? "(root)" : path.slice(0, slash);
+}
+/**
+ * Compute percentile rank (0-100) for a file based on position in sorted ranks.
+ * Higher rank value = higher percentile.
+ */
+function computePercentile(rank, sortedRanks) {
+    if (sortedRanks.length === 0)
+        return 100;
+    if (sortedRanks.length === 1)
+        return 100;
+    // Count how many ranks are below this one
+    let countBelow = 0;
+    for (const r of sortedRanks) {
+        if (r < rank)
+            countBelow++;
+    }
+    // Percentile = (countBelow / (n-1)) * 100, rounded
+    return Math.round((countBelow / (sortedRanks.length - 1)) * 100);
+}
+/**
+ * Compute percentile as decimal (0.0 to 1.0)
+ */
+function formatRankDisplay(rank, sortedRanks) {
+    const percentile = computePercentile(rank, sortedRanks);
+    return (percentile / 100).toFixed(1);
+}
 /**
  * Resolve RankedDefinitions to their Tags by looking up in graph.defsByName.
  * Returns only definitions that can be found.
+ * Applies diversity cap to limit repetition of same-named definitions.
  */
 function resolveDefs(defs, graph) {
     const result = [];
+    const nameCounts = new Map();
     for (const def of defs) {
+        // Check diversity cap before processing
+        const currentCount = nameCounts.get(def.ident) ?? 0;
+        if (currentCount >= MAX_DEFS_PER_NAME) {
+            continue;
+        }
         const tags = graph.defsByName.get(def.ident);
         if (!tags)
             continue;
@@ -13,6 +65,7 @@ function resolveDefs(defs, graph) {
         if (!tag)
             continue;
         result.push({ file: def.file, tag, rank: def.rank });
+        nameCounts.set(def.ident, currentCount + 1);
     }
     return result;
 }
@@ -29,52 +82,131 @@ function groupByFile(defs) {
     return groups;
 }
 /**
- * Format output per spec §3.5.
- * Files sorted by PageRank descending.
+ * Group files by module (first path segment).
+ */
+function groupByModule(files) {
+    const modules = new Map();
+    for (const file of files) {
+        const mod = getModuleName(file);
+        const existing = modules.get(mod) ?? [];
+        existing.push(file);
+        modules.set(mod, existing);
+    }
+    return modules;
+}
+/**
+ * Limit files per module, keeping top N by rank.
+ * Global top-K files are always included regardless of per-module limits.
+ * Returns set of allowed files and count of omitted per module.
+ */
+function limitFilesPerModule(moduleGroups, fileRanks, maxPerModule, globalTopK = GLOBAL_TOP_K) {
+    if (maxPerModule <= 0 && globalTopK <= 0) {
+        // No limits - return all files
+        const allFiles = new Set();
+        for (const files of moduleGroups.values()) {
+            for (const f of files)
+                allFiles.add(f);
+        }
+        return { allowedFiles: allFiles, omittedByModule: new Map() };
+    }
+    // Get all files sorted by global rank
+    const allFilesList = [...moduleGroups.values()].flat();
+    const sortedGlobally = [...allFilesList].sort((a, b) => (fileRanks.get(b) ?? 0) - (fileRanks.get(a) ?? 0));
+    // Guarantee top-K files globally
+    const guaranteedFiles = new Set(sortedGlobally.slice(0, globalTopK));
+    const allowedFiles = new Set();
+    const omittedByModule = new Map();
+    for (const [mod, files] of moduleGroups) {
+        let keptNonGuaranteed = 0;
+        let omitted = 0;
+        for (const f of files) {
+            const isGuaranteed = guaranteedFiles.has(f);
+            const underLimit = maxPerModule <= 0 || keptNonGuaranteed < maxPerModule;
+            if (isGuaranteed || underLimit) {
+                allowedFiles.add(f);
+                if (!isGuaranteed)
+                    keptNonGuaranteed++;
+            }
+            else {
+                omitted++;
+            }
+        }
+        if (omitted > 0)
+            omittedByModule.set(mod, omitted);
+    }
+    return { allowedFiles, omittedByModule };
+}
+/**
+ * Format output per spec §3.5, grouped by module.
+ * Modules sorted by highest-ranked file descending.
+ * Files within module sorted by PageRank descending.
  * Definitions within file sorted by line ascending.
  * Line numbers right-aligned to max width.
  */
-export function formatOutput(defs, graph, fileRanks, focusFiles) {
+export function formatOutput(defs, graph, fileRanks, focusFiles, maxFilesPerModule = MAX_FILES_PER_MODULE) {
     const resolved = resolveDefs(defs, graph);
     if (resolved.length === 0 && (!focusFiles || focusFiles.length === 0)) {
         return "";
     }
-    const groups = groupByFile(resolved);
+    const fileGroups = groupByFile(resolved);
     // Sort files by PageRank descending
-    const sortedFiles = [...groups.keys()].sort((a, b) => {
+    const sortedFiles = [...fileGroups.keys()].sort((a, b) => {
         const rankA = fileRanks.get(a) ?? 0;
         const rankB = fileRanks.get(b) ?? 0;
         if (rankB !== rankA)
             return rankB - rankA;
         return a.localeCompare(b);
     });
-    // Find max line number for padding
-    let maxLine = 1;
-    for (const def of resolved) {
-        if (def.tag.line > maxLine)
-            maxLine = def.tag.line;
-    }
-    const lineWidth = String(maxLine).length;
+    // Group files by module
+    const moduleGroups = groupByModule(sortedFiles);
+    // Apply module file limits
+    const { allowedFiles, omittedByModule } = limitFilesPerModule(moduleGroups, fileRanks, maxFilesPerModule);
+    // Sort modules by highest-ranked file in each module
+    const sortedModules = [...moduleGroups.keys()].sort((a, b) => {
+        const filesA = moduleGroups.get(a) ?? [];
+        const filesB = moduleGroups.get(b) ?? [];
+        const maxRankA = Math.max(...filesA.map((f) => fileRanks.get(f) ?? 0));
+        const maxRankB = Math.max(...filesB.map((f) => fileRanks.get(f) ?? 0));
+        if (maxRankB !== maxRankA)
+            return maxRankB - maxRankA;
+        return a.localeCompare(b);
+    });
     const lines = [];
     // Focus files header
     if (focusFiles && focusFiles.length > 0) {
         lines.push(`[Focus: [${focusFiles.join(", ")}]]`);
         lines.push("");
     }
-    // Format each file
-    for (const file of sortedFiles) {
-        const fileDefs = groups.get(file);
-        if (!fileDefs || fileDefs.length === 0)
+    // Get all ranks for percentile calculation (only from allowed files)
+    const allRanks = [...allowedFiles].map((f) => fileRanks.get(f) ?? 0);
+    // Format by module
+    for (const mod of sortedModules) {
+        const allModFiles = moduleGroups.get(mod) ?? [];
+        // Filter to allowed files only
+        const modFiles = allModFiles.filter((f) => allowedFiles.has(f));
+        if (modFiles.length === 0)
             continue;
-        const fileRank = fileRanks.get(file) ?? 0;
-        lines.push(`${file}:`);
-        lines.push(`(Rank: ${fileRank.toFixed(4)})`);
-        lines.push("");
-        // Sort definitions by line ascending
-        const sorted = [...fileDefs].sort((a, b) => a.tag.line - b.tag.line);
-        for (const def of sorted) {
-            const lineNum = String(def.tag.line).padStart(lineWidth, " ");
-            lines.push(`${lineNum}: ${def.tag.signature ?? def.tag.name}`);
+        // Module header - shows kept count, not total
+        const suffix = mod === "(root)" ? "" : "/";
+        lines.push(`## ${mod}${suffix} (${String(modFiles.length)} file${modFiles.length > 1 ? "s" : ""})`);
+        // Files in this module (already sorted by rank)
+        for (const file of modFiles) {
+            const fileDefs = fileGroups.get(file);
+            if (!fileDefs || fileDefs.length === 0)
+                continue;
+            const fileRank = fileRanks.get(file) ?? 0;
+            lines.push(`${file}: ${formatRankDisplay(fileRank, allRanks)}`);
+            // Sort definitions by line ascending
+            const sorted = [...fileDefs].sort((a, b) => a.tag.line - b.tag.line);
+            for (const def of sorted) {
+                lines.push(`  ${def.tag.signature ?? def.tag.name}`);
+            }
+        }
+        // Omission annotation if files were limited
+        const omitted = omittedByModule.get(mod);
+        if (omitted !== undefined && omitted > 0) {
+            const fileWord = omitted === 1 ? "file" : "files";
+            lines.push(`  ... (${String(omitted)} more ${fileWord} in ${mod}${suffix})`);
         }
         lines.push("");
     }
@@ -90,7 +222,7 @@ export function formatOutput(defs, graph, fileRanks, focusFiles) {
  * 3. If tokens ≤ budget, try more; else try fewer
  * 4. Return best fit
  */
-export function fitToTokenBudget(defs, graph, fileRanks, tokenBudget, focusFiles) {
+export function fitToTokenBudget(defs, graph, fileRanks, tokenBudget, focusFiles, maxFilesPerModule = MAX_FILES_PER_MODULE) {
     if (tokenBudget <= 0)
         return "";
     if (defs.length === 0) {
@@ -111,7 +243,7 @@ export function fitToTokenBudget(defs, graph, fileRanks, tokenBudget, focusFiles
             continue;
         }
         const subset = defs.slice(0, mid);
-        const output = formatOutput(subset, graph, fileRanks, focusFiles);
+        const output = formatOutput(subset, graph, fileRanks, focusFiles, maxFilesPerModule);
         const tokens = estimateTokens(output);
         if (tokens <= tokenBudget) {
             if (mid > bestCount) {

package/dist/pagerank.js

@@ -39,11 +39,10 @@ export function computePageRank(graph, options) {
     // Power iteration
     const next = new Float64Array(n);
     for (let iter = 0; iter < maxIter; iter++) {
-        // Base teleport term: (1-d)/N per spec §7.2
-        // Uses uniform distribution (not personalized) for teleport
-        const base = (1 - d) / n;
+        // Personalized teleport: (1-d) * pVec[i]
+        // Uses personalization vector for stronger focus biasing
         for (let i = 0; i < n; i++) {
-            next[i] = base;
+            next[i] = (1 - d) * (pVec[i] ?? 1 / n);
         }
         // Compute dangling sum
         let danglingSum = 0;

package/dist/parser.js

@@ -61,8 +61,47 @@ async function loadLanguage(config) {
  * Derived from LANGUAGE_REGISTRY to ensure single source of truth.
  */
 const ALL_DEFINITION_TYPES = new Set(Object.values(LANGUAGE_REGISTRY).flatMap((config) => [...config.definitionTypes]));
+/**
+ * Node types that block export inheritance.
+ * Local variables inside these should not be considered exported.
+ */
+const EXPORT_BLOCKERS = new Set([
+    "function_declaration",
+    "function",
+    "function_expression",
+    "arrow_function",
+    "method_definition",
+    "class_declaration",
+    "class",
+    "class_expression",
+]);
+/**
+ * Check if a variable_declarator is directly exported (not inside a function/class).
+ * Stops at function/class boundaries to prevent local variables from being captured.
+ */
+function isDirectlyExportedVariable(node) {
+    let current = node;
+    while (current && current.type !== "program") {
+        // Stop if we hit a function/class boundary - local variables not exported
+        if (EXPORT_BLOCKERS.has(current.type))
+            return false;
+        const parent = current.parent;
+        if (parent?.type === "export_statement") {
+            const decl = parent.childForFieldName("declaration");
+            if (!decl)
+                return false;
+            // Compare by node ID, not object identity (tree-sitter creates new wrapper objects)
+            if (current.id !== decl.id)
+                return false;
+            return decl.type === "lexical_declaration" || decl.type === "variable_declaration";
+        }
+        current = parent;
+    }
+    return false;
+}
 /**
  * Check if a node is inside an export statement (JS/TS).
+ * For function/class declarations (not variables).
  */
 function isExported(node) {
     let current = node.parent;
@@ -239,6 +278,22 @@ export async function parseFile(absPath, relPath) {
             if (shouldIncludeDefinition(node, langConfig)) {
                 const name = getDefinitionName(node);
                 if (name && !isBuiltin(name, langConfig)) {
+                    // Determine export status based on language and node type
+                    let nodeIsExported;
+                    if (langConfig.grammarName === "typescript") {
+                        // For TS/JS: check if it's directly exported or is a method
+                        // Methods are considered non-exported (internal to class)
+                        if (node.type === "method_definition") {
+                            nodeIsExported = false;
+                        }
+                        else {
+                            nodeIsExported = isExported(node);
+                        }
+                    }
+                    else {
+                        // For Python/Go/Rust/Solidity: all captured defs are "exported" (public API)
+                        nodeIsExported = true;
+                    }
                     tags.push({
                         relPath,
                         absPath,
@@ -246,12 +301,13 @@ export async function parseFile(absPath, relPath) {
                         name,
                         kind: "def",
                         signature: getSignature(node, sourceLines),
+                        isExported: nodeIsExported,
                     });
                 }
             }
         }
         // Check for exported variable declarators (const/let) - TypeScript/JavaScript only
-        if (node.type === "variable_declarator" && isExported(node)) {
+        if (node.type === "variable_declarator" && isDirectlyExportedVariable(node)) {
             const name = getVariableDeclaratorName(node);
             if (name && !isBuiltin(name, langConfig)) {
                 tags.push({
@@ -261,6 +317,7 @@ export async function parseFile(absPath, relPath) {
                     name,
                     kind: "def",
                     signature: getSignature(node, sourceLines),
+                    isExported: true, // isDirectlyExportedVariable already checks this
                 });
             }
         }