@snevins/repo-mapper 1.0.3

package/dist/ranking.js

@@ -0,0 +1,55 @@
+/**
+ * Build personalization vector for focus files.
+ * Each focus file gets weight 1.0.
+ */
+export function buildPersonalization(focusFiles) {
+    const result = new Map();
+    for (const file of focusFiles) {
+        result.set(file, 1.0);
+    }
+    return result;
+}
+/**
+ * Rank definitions by propagating PageRank through symbol edges.
+ * Focus file definitions are excluded from output.
+ *
+ * Formula: def_rank[definer:ident] += PR(referencer) * edge_weight / out_weight(referencer)
+ */
+export function rankDefinitions(graph, fileRanks, focusFiles) {
+    const focusSet = focusFiles ?? new Set();
+    const accumulator = new Map();
+    for (const [from, toMap] of graph.symbolEdges) {
+        const outWeight = graph.outWeights.get(from);
+        if (outWeight === undefined || outWeight === 0) {
+            continue;
+        }
+        const pr = fileRanks.get(from) ?? 0;
+        for (const [to, symbolMap] of toMap) {
+            if (focusSet.has(to)) {
+                continue;
+            }
+            for (const [symbol, count] of symbolMap) {
+                const key = `${to}\0${symbol}`;
+                const contribution = (pr * count) / outWeight;
+                accumulator.set(key, (accumulator.get(key) ?? 0) + contribution);
+            }
+        }
+    }
+    const result = [];
+    for (const [key, rank] of accumulator) {
+        const sepIdx = key.indexOf("\0");
+        const file = key.slice(0, sepIdx);
+        const ident = key.slice(sepIdx + 1);
+        result.push({ file, ident, rank });
+    }
+    result.sort((a, b) => {
+        if (b.rank !== a.rank) {
+            return b.rank - a.rank;
+        }
+        if (a.file !== b.file) {
+            return a.file.localeCompare(b.file);
+        }
+        return a.ident.localeCompare(b.ident);
+    });
+    return result;
+}

package/dist/tokens.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Count special characters (non-alphanumeric, non-whitespace).
+ * Used for token estimation adjustment.
+ */
+export declare function countSpecialChars(text: string): number;
+/**
+ * Estimate token count using heuristic from spec §8.1:
+ * tokens ≈ (character_count / 4) + (special_char_count × 0.3)
+ */
+export declare function estimateTokens(text: string): number;

package/dist/tokens.js

@@ -0,0 +1,23 @@
+const ALPHANUMERIC_OR_WHITESPACE = /[a-zA-Z0-9\s]/;
+/**
+ * Count special characters (non-alphanumeric, non-whitespace).
+ * Used for token estimation adjustment.
+ */
+export function countSpecialChars(text) {
+    let count = 0;
+    for (const char of text) {
+        if (!ALPHANUMERIC_OR_WHITESPACE.test(char)) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Estimate token count using heuristic from spec §8.1:
+ * tokens ≈ (character_count / 4) + (special_char_count × 0.3)
+ */
+export function estimateTokens(text) {
+    const charCount = text.length;
+    const specialCount = countSpecialChars(text);
+    return Math.floor(charCount / 4 + specialCount * 0.3);
+}

package/dist/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * A parsed symbol occurrence (definition or reference) in source code.
+ */
+export interface Tag {
+    readonly relPath: string;
+    readonly absPath: string;
+    readonly line: number;
+    readonly name: string;
+    readonly kind: "def" | "ref";
+    readonly signature?: string;
+}
+/**
+ * CLI options parsed from command line arguments.
+ */
+export interface CliOptions {
+    readonly tokens: number;
+    readonly focus: readonly string[];
+    readonly output: string | undefined;
+    readonly refresh: boolean;
+    readonly verbose: boolean;
+    readonly ignore: readonly string[];
+    readonly noIgnore: boolean;
+    readonly maxFiles: number;
+}
+/**
+ * Result of parsing CLI arguments.
+ */
+export interface ParsedArgs {
+    readonly paths: readonly string[];
+    readonly options: CliOptions;
+}
+/**
+ * Options for file discovery.
+ */
+export interface FileDiscoveryOptions {
+    readonly rootDir: string;
+    readonly maxDepth?: number;
+    readonly extensions?: ReadonlySet<string>;
+    readonly ignoredDirs?: ReadonlySet<string>;
+    readonly ignoredPatterns?: readonly string[];
+    readonly respectGitignore?: boolean;
+    readonly includeHidden?: boolean;
+    readonly maxFiles?: number;
+}
+/**
+ * Result of file discovery.
+ */
+export interface FileDiscoveryResult {
+    readonly files: readonly string[];
+    readonly totalDiscovered: number;
+    readonly wasLimited: boolean;
+}
+/**
+ * Options for PageRank computation.
+ */
+export interface PageRankOptions {
+    /** Damping factor (default: 0.85) */
+    readonly dampingFactor?: number;
+    /** Convergence threshold for score changes (default: 1e-6) */
+    readonly convergenceThreshold?: number;
+    /** Maximum iterations before stopping (default: 100) */
+    readonly maxIterations?: number;
+    /** Optional personalization vector to bias scores toward specific files */
+    readonly personalization?: ReadonlyMap<string, number>;
+}
+/**
+ * File reference graph for ranking.
+ * Nodes are files (relPath), edges are symbol references.
+ *
+ * Note: ReadonlyMap provides type-level immutability for consumers.
+ * Internal Maps are structurally compatible but not frozen at runtime.
+ */
+export interface FileGraph {
+    /** Unique file paths (relPath), sorted for determinism */
+    readonly nodes: readonly string[];
+    /** File-level edges: from → to → total weight (for PageRank) */
+    readonly edges: ReadonlyMap<string, ReadonlyMap<string, number>>;
+    /** Symbol-level edges: from → to → symbol → count (for definition ranking) */
+    readonly symbolEdges: ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, number>>>;
+    /** Total outgoing weight per file */
+    readonly outWeights: ReadonlyMap<string, number>;
+    /** Definitions indexed by symbol name */
+    readonly defsByName: ReadonlyMap<string, readonly Tag[]>;
+}
+/**
+ * A ranked definition for output.
+ */
+export interface RankedDefinition {
+    readonly file: string;
+    readonly ident: string;
+    readonly rank: number;
+}
+/**
+ * A cached entry for a single file.
+ */
+export interface CacheEntry {
+    readonly mtime: number;
+    readonly tags: readonly Tag[];
+}
+/**
+ * The cache file structure stored on disk.
+ */
+export interface CacheFile {
+    readonly version: number;
+    readonly entries: Record<string, CacheEntry>;
+}
+/**
+ * In-memory cache structure.
+ */
+export interface Cache {
+    readonly version: number;
+    readonly entries: Map<string, CacheEntry>;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@snevins/repo-mapper",
+  "version": "1.0.3",
+  "description": "Generate token-budgeted repo maps for LLM context using tree-sitter and PageRank",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "repo-mapper": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "prepack": "pnpm build",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevennevins/repo-mapper.git"
+  },
+  "homepage": "https://github.com/stevennevins/repo-mapper#readme",
+  "bugs": {
+    "url": "https://github.com/stevennevins/repo-mapper/issues"
+  },
+  "keywords": [
+    "llm",
+    "context",
+    "repo-map",
+    "tree-sitter",
+    "pagerank",
+    "ai",
+    "code-analysis"
+  ],
+  "author": "Steven Nevins",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.9",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.0",
+    "vitest": "^4.0.17"
+  },
+  "dependencies": {
+    "ignore": "^7.0.5",
+    "tree-sitter-go": "^0.25.0",
+    "tree-sitter-javascript": "^0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-solidity": "^1.2.13",
+    "tree-sitter-typescript": "^0.23.2",
+    "web-tree-sitter": "^0.26.3"
+  }
+}