@snevins/repo-mapper 1.0.3 → 1.2.0

package/dist/ranking.d.ts

@@ -1,9 +1,36 @@
-import type { FileGraph, RankedDefinition } from "./types.js";
+import type { FileGraph, RankedDefinition, FileDegrees } from "./types.js";
+import type { DuplicateGroup } from "./dedup.js";
+/**
+ * Detect entrypoint files from a list of file paths.
+ */
+export declare function detectEntrypoints(nodes: readonly string[]): string[];
+/**
+ * Build personalization vector for detected entrypoints.
+ * Used when no focus files specified to boost common entrypoint patterns.
+ */
+export declare function buildEntrypointPersonalization(nodes: readonly string[]): Map<string, number>;
+/**
+ * Adjust file ranks based on architecture signals.
+ * - Hub penalty: penalize files with high in-degree (many importers)
+ * - Path penalty: penalize utility/internal paths
+ * - Entry point boost: boost files matching entry point patterns
+ * - Diversity bonus: boost files that reference many different modules
+ * - Duplicate penalty: penalize non-canonical duplicates
+ */
+export declare function adjustFileRanks(fileRanks: ReadonlyMap<string, number>, degrees: ReadonlyMap<string, FileDegrees>, nodes: readonly string[], duplicates?: ReadonlyMap<string, DuplicateGroup>): Map<string, number>;
 /**
  * Build personalization vector for focus files.
  * Each focus file gets weight 1.0.
  */
 export declare function buildPersonalization(focusFiles: readonly string[]): Map<string, number>;
+/**
+ * Build personalization vector with boosted first-order neighbors.
+ * This strengthens the focus bias by giving higher weights to:
+ * - Focus files (highest)
+ * - Files that focus file references (dependencies)
+ * - Files that reference focus file (dependents)
+ */
+export declare function buildFocusPersonalization(focusFiles: readonly string[], graph: FileGraph): Map<string, number>;
 /**
  * Rank definitions by propagating PageRank through symbol edges.
  * Focus file definitions are excluded from output.
@@ -11,3 +38,12 @@ export declare function buildPersonalization(focusFiles: readonly string[]): Map
  * Formula: def_rank[definer:ident] += PR(referencer) * edge_weight / out_weight(referencer)
  */
 export declare function rankDefinitions(graph: FileGraph, fileRanks: Map<string, number>, focusFiles?: ReadonlySet<string>): RankedDefinition[];
+/**
+ * Combine structural ranks (import graph) with reference density (ref graph).
+ *
+ * Structural importance (from binary import graph) is weighted more heavily
+ * than raw reference counts to prevent "noisy" files from dominating.
+ *
+ * Formula: combined = structRank * structWeight + normalizedDensity * (1 - structWeight)
+ */
+export declare function combineRanks(structuralRanks: ReadonlyMap<string, number>, refGraph: FileGraph, structuralWeight?: number): Map<string, number>;

package/dist/ranking.js

@@ -1,3 +1,154 @@
+/**
+ * Boilerplate method names to filter from ranked definitions.
+ * These are common trait implementations and overrides that add noise.
+ */
+const BOILERPLATE_NAMES = new Set([
+    // Rust trait impls
+    "fmt", "default", "new", "from", "into", "clone",
+    "eq", "hash", "deref", "drop", "serialize", "deserialize",
+    // JS/TS common overrides
+    "toString", "valueOf", "toJSON",
+    // Generic method names (inflate rankings, not meaningful)
+    "log", "init", "get", "set", "update", "handle",
+    "on", "parse", "format", "name", "value", "path",
+    "start", "stop", "reset", "run", "execute",
+]);
+/**
+ * Patterns identifying internal/tool/utility paths that should be penalized.
+ * These are typically support code, not primary business logic.
+ *
+ * Note: We don't penalize top-level `internal/` because Go uses this for
+ * production code (prevents external imports), not utility code.
+ */
+const INTERNAL_PATH_PATTERNS = [
+    // Tool/script directories (at any level)
+    /^tools\//,
+    /^scripts\//,
+    /\/tools\//,
+    /\/scripts\//,
+    // Nested internal directories (not top-level, which Go uses for prod code)
+    /\/internal\//,
+    // Utility/helper directories (common across languages)
+    /\/utils\//,
+    /\/util\//,
+    /\/helpers\//,
+    /\/helper\//,
+    /\/common\//,
+    /\/shared\//,
+    /\/support\//,
+    /\/primitives\//, // Solidity primitive types
+    /\/vendor\//, // Vendored code
+    // Language-specific patterns
+    /^crates\/.*\/src\/util/, // Rust internal utils
+    /^pkg\/util/, // Go pkg/util pattern
+];
+const INTERNAL_PATH_PENALTY = 0.5;
+/**
+ * Check if a file path matches any internal path pattern.
+ */
+function isInternalPath(path) {
+    for (const pattern of INTERNAL_PATH_PATTERNS) {
+        if (pattern.test(path)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Patterns that identify likely entrypoint files.
+ */
+const ENTRYPOINT_PATTERNS = [
+    /^src\/main\.(ts|js|py|go|rs)$/,
+    /^src\/index\.(ts|js)$/,
+    /^src\/lib\.(ts|js|rs)$/,
+    /^main\.(ts|js|py|go|rs)$/,
+    /^index\.(ts|js)$/,
+    /^lib\.rs$/,
+    /^app\/.+\.(ts|tsx|js|jsx)$/, // Next.js app router
+    /^pages\/.+\.(ts|tsx|js|jsx)$/, // Next.js pages router
+    /^cmd\/.+\.go$/, // Go cmd pattern
+];
+const ENTRYPOINT_WEIGHT = 2.0;
+/**
+ * Detect entrypoint files from a list of file paths.
+ */
+export function detectEntrypoints(nodes) {
+    const result = [];
+    for (const node of nodes) {
+        for (const pattern of ENTRYPOINT_PATTERNS) {
+            if (pattern.test(node)) {
+                result.push(node);
+                break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Build personalization vector for detected entrypoints.
+ * Used when no focus files specified to boost common entrypoint patterns.
+ */
+export function buildEntrypointPersonalization(nodes) {
+    const entrypoints = detectEntrypoints(nodes);
+    const result = new Map();
+    for (const file of entrypoints) {
+        result.set(file, ENTRYPOINT_WEIGHT);
+    }
+    return result;
+}
+// Architecture-aware adjustment coefficients
+const ENTRY_POINT_BOOST = 2.0; // Boost for entry point files
+const DIVERSITY_BONUS_FACTOR = 0.15; // log2(modules) * factor
+const DUPLICATE_PENALTY = 0.3; // Non-canonical duplicates get 70% penalty
+/**
+ * Adjust file ranks based on architecture signals.
+ * - Hub penalty: penalize files with high in-degree (many importers)
+ * - Path penalty: penalize utility/internal paths
+ * - Entry point boost: boost files matching entry point patterns
+ * - Diversity bonus: boost files that reference many different modules
+ * - Duplicate penalty: penalize non-canonical duplicates
+ */
+export function adjustFileRanks(fileRanks, degrees, nodes, duplicates) {
+    const entrypoints = new Set(detectEntrypoints(nodes));
+    const result = new Map();
+    for (const [file, rank] of fileRanks) {
+        const deg = degrees.get(file);
+        if (!deg) {
+            result.set(file, rank);
+            continue;
+        }
+        let adjustedRank = rank;
+        // 1. Hub penalty: log-based penalty for high in-degree files
+        // Files imported by many others get penalized proportionally
+        const { inDegree, uniqueModulesReferenced } = deg;
+        if (inDegree > 0) {
+            const hubPenalty = 1 / Math.log2(1 + inDegree);
+            adjustedRank *= hubPenalty;
+        }
+        // 2. Path penalty: penalize utility/internal paths
+        if (isInternalPath(file)) {
+            adjustedRank *= INTERNAL_PATH_PENALTY;
+        }
+        // 3. Entry point boost
+        if (entrypoints.has(file)) {
+            adjustedRank *= ENTRY_POINT_BOOST;
+        }
+        // 4. Module diversity bonus: files that import from many modules
+        if (uniqueModulesReferenced > 1) {
+            const diversityBonus = 1 + Math.log2(uniqueModulesReferenced) * DIVERSITY_BONUS_FACTOR;
+            adjustedRank *= diversityBonus;
+        }
+        // 5. Duplicate penalty: non-canonical duplicates get reduced rank
+        if (duplicates) {
+            const group = duplicates.get(file);
+            if (group && group.canonical !== file) {
+                adjustedRank *= DUPLICATE_PENALTY;
+            }
+        }
+        result.set(file, adjustedRank);
+    }
+    return result;
+}
 /**
  * Build personalization vector for focus files.
  * Each focus file gets weight 1.0.
@@ -9,6 +160,53 @@ export function buildPersonalization(focusFiles) {
     }
     return result;
 }
+// Weight constants for focus personalization
+const FOCUS_WEIGHT = 10.0; // Focus file itself
+const DEPENDENCY_WEIGHT = 3.0; // Files that focus file imports
+const DEPENDENT_WEIGHT = 1.0; // Files that import focus file
+/**
+ * Build personalization vector with boosted first-order neighbors.
+ * This strengthens the focus bias by giving higher weights to:
+ * - Focus files (highest)
+ * - Files that focus file references (dependencies)
+ * - Files that reference focus file (dependents)
+ */
+export function buildFocusPersonalization(focusFiles, graph) {
+    if (focusFiles.length === 0) {
+        return new Map();
+    }
+    const result = new Map();
+    const focusSet = new Set(focusFiles);
+    // Give focus files highest weight
+    for (const file of focusFiles) {
+        result.set(file, FOCUS_WEIGHT);
+    }
+    // Find files that focus files reference (outgoing edges = dependencies)
+    for (const focusFile of focusFiles) {
+        const outgoing = graph.edges.get(focusFile);
+        if (outgoing) {
+            for (const [target] of outgoing) {
+                if (!focusSet.has(target)) {
+                    const current = result.get(target) ?? 0;
+                    result.set(target, Math.max(current, DEPENDENCY_WEIGHT));
+                }
+            }
+        }
+    }
+    // Find files that reference focus files (incoming edges = dependents)
+    for (const [from, toMap] of graph.edges) {
+        if (focusSet.has(from))
+            continue;
+        for (const [to] of toMap) {
+            if (focusSet.has(to)) {
+                const current = result.get(from) ?? 0;
+                result.set(from, Math.max(current, DEPENDENT_WEIGHT));
+                break; // Only need to count once per file
+            }
+        }
+    }
+    return result;
+}
 /**
  * Rank definitions by propagating PageRank through symbol edges.
  * Focus file definitions are excluded from output.
@@ -30,7 +228,11 @@ export function rankDefinitions(graph, fileRanks, focusFiles) {
             }
             for (const [symbol, count] of symbolMap) {
                 const key = `${to}\0${symbol}`;
-                const contribution = (pr * count) / outWeight;
+                let contribution = (pr * count) / outWeight;
+                // Apply penalty for internal/tool paths
+                if (isInternalPath(to)) {
+                    contribution *= INTERNAL_PATH_PENALTY;
+                }
                 accumulator.set(key, (accumulator.get(key) ?? 0) + contribution);
             }
         }
@@ -40,6 +242,10 @@ export function rankDefinitions(graph, fileRanks, focusFiles) {
         const sepIdx = key.indexOf("\0");
         const file = key.slice(0, sepIdx);
         const ident = key.slice(sepIdx + 1);
+        // Filter out boilerplate names
+        if (BOILERPLATE_NAMES.has(ident)) {
+            continue;
+        }
         result.push({ file, ident, rank });
     }
     result.sort((a, b) => {
@@ -53,3 +259,38 @@ export function rankDefinitions(graph, fileRanks, focusFiles) {
     });
     return result;
 }
+/**
+ * Combine structural ranks (import graph) with reference density (ref graph).
+ *
+ * Structural importance (from binary import graph) is weighted more heavily
+ * than raw reference counts to prevent "noisy" files from dominating.
+ *
+ * Formula: combined = structRank * structWeight + normalizedDensity * (1 - structWeight)
+ */
+export function combineRanks(structuralRanks, refGraph, structuralWeight = 0.7) {
+    const result = new Map();
+    if (structuralRanks.size === 0) {
+        return result;
+    }
+    // Find max outWeight for normalization
+    let maxOutWeight = 0;
+    for (const weight of refGraph.outWeights.values()) {
+        if (weight > maxOutWeight) {
+            maxOutWeight = weight;
+        }
+    }
+    // If no refs at all, just return structural ranks scaled
+    if (maxOutWeight === 0) {
+        for (const [file, rank] of structuralRanks) {
+            result.set(file, rank * structuralWeight);
+        }
+        return result;
+    }
+    for (const [file, structRank] of structuralRanks) {
+        const refDensity = refGraph.outWeights.get(file) ?? 0;
+        const normalizedDensity = refDensity / maxOutWeight;
+        const combined = structRank * structuralWeight + normalizedDensity * (1 - structuralWeight);
+        result.set(file, combined);
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -8,6 +8,8 @@ export interface Tag {
     readonly name: string;
     readonly kind: "def" | "ref";
     readonly signature?: string;
+    /** Whether this definition is exported (public API). Only set for "def" kind. */
+    readonly isExported?: boolean;
 }
 /**
  * CLI options parsed from command line arguments.
@@ -19,8 +21,10 @@ export interface CliOptions {
     readonly refresh: boolean;
     readonly verbose: boolean;
     readonly ignore: readonly string[];
+    readonly include: readonly string[];
     readonly noIgnore: boolean;
     readonly maxFiles: number;
+    readonly type: readonly string[];
 }
 /**
  * Result of parsing CLI arguments.
@@ -38,6 +42,7 @@ export interface FileDiscoveryOptions {
     readonly extensions?: ReadonlySet<string>;
     readonly ignoredDirs?: ReadonlySet<string>;
     readonly ignoredPatterns?: readonly string[];
+    readonly includePatterns?: readonly string[];
     readonly respectGitignore?: boolean;
     readonly includeHidden?: boolean;
     readonly maxFiles?: number;
@@ -63,6 +68,13 @@ export interface PageRankOptions {
     /** Optional personalization vector to bias scores toward specific files */
     readonly personalization?: ReadonlyMap<string, number>;
 }
+/**
+ * Options for building the file reference graph.
+ */
+export interface GraphBuildOptions {
+    /** Return weight multiplier for edges FROM this file (default: 1.0) */
+    readonly edgeWeightMultiplier?: (fromPath: string) => number;
+}
 /**
  * File reference graph for ranking.
  * Nodes are files (relPath), edges are symbol references.
@@ -90,6 +102,17 @@ export interface RankedDefinition {
     readonly ident: string;
     readonly rank: number;
 }
+/**
+ * Degree metrics for a file in the graph.
+ */
+export interface FileDegrees {
+    /** Number of unique files that reference this file */
+    readonly inDegree: number;
+    /** Number of unique files this file references */
+    readonly outDegree: number;
+    /** Number of unique first-level modules this file references */
+    readonly uniqueModulesReferenced: number;
+}
 /**
  * A cached entry for a single file.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snevins/repo-mapper",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Generate token-budgeted repo maps for LLM context using tree-sitter and PageRank",
   "type": "module",
   "main": "dist/index.js",