@blamechris/repo-memory 0.9.0 → 0.11.0

package/README.md

@@ -34,6 +34,19 @@ npm install -g @blamechris/repo-memory
 repo-memory  # starts MCP server on stdio
 ```
 
+### Prewarm the cache
+The first time an agent touches a file it pays full price — the summary has to be generated. You can pay that cost ahead of time (post-pull hook, CI step) so the first session starts with cache hits:
+
+```bash
+repo-memory index            # index the current directory
+repo-memory index /path/to/project
+repo-memory index --quiet    # no output on success (for scripts/CI)
+```
+
+Only missing or stale entries are re-summarized; unchanged files are left untouched.
+
+To automate it, drop a git `post-merge` hook in the project (see [docs/usage.md](docs/usage.md#cli) for the snippet) so every pull keeps the cache warm.
+
 ## How It Works
 
 ### The problem
@@ -194,7 +207,7 @@ Create a `.repo-memory.json` in your project root to customize behavior:
 }
 ```
 
-`summarizer` selects the summary engine: `"regex"` (default) or `"ast"`. AST mode parses TypeScript/JavaScript files (`.ts/.tsx/.js/.jsx/.mjs/.cjs`) with tree-sitter, producing accurate exports/declarations and a semantic `purpose` line that names the dominant symbols (e.g. `class CacheStore (9 methods)` instead of `source`) — which is what `search_by_purpose` matches against. TS/JS only for now; other languages, unsupported extensions, and files with parse errors fall back to the regex summarizer automatically. Switching modes regenerates summaries lazily on next access.
+`summarizer` selects the summary engine: `"regex"` (default) or `"ast"`. AST mode parses supported languages (see [Language Support](#language-support)) with tree-sitter, producing accurate exports/declarations and a semantic `purpose` line that names the dominant symbols (e.g. `class CacheStore (9 methods)` instead of `source`) — which is what `search_by_purpose` matches against. Other languages, unsupported extensions, and files with parse errors fall back to the regex summarizer automatically. Switching modes regenerates summaries lazily on next access.
 
 The `tools` block toggles tool groups. `navigation` and `summaries` are **on by default** (set `"summaries": false` to drop the summary tools); `tasks` and `telemetry` are **off by default** (set them to `true` to enable).
 
@@ -209,11 +222,15 @@ Config validation is per-key: an invalid value is skipped with a warning on stde
 
 ## Language Support
 
-Summaries are extracted via regex analysis (or tree-sitter when `"summarizer": "ast"` is set — TS/JS only). Supported languages:
-- **TypeScript / JavaScript** — exports, imports, declarations, purpose classification; optional AST mode for semantic purpose lines
-- **Python** — functions, classes, `__all__`, `from`/`import` statements
-- **Go** — exported names (uppercase), imports, type/func/var/const declarations
-- **Rust** — `pub` items, `use`/`mod` statements, structs/enums/traits/impls
+Summaries are extracted via regex analysis, or from tree-sitter parse trees when `"summarizer": "ast"` is set. All language families below have AST support in `ast` mode, which adds semantic purpose lines derived from doc comments; regex stays as the universal fallback for other languages and unparseable files. Supported languages:
+- **TypeScript / JavaScript** — exports, imports, declarations, purpose classification; AST mode adds JSDoc-derived purpose lines
+- **Python** — functions, classes (incl. `async def`), `__all__`, `from`/`import` statements; AST mode adds docstring-derived purpose lines
+- **Go** — exported names (uppercase), imports, type/func/var/const declarations; AST mode adds doc-comment purpose lines and grouped `var (…)` / `const (…)` support
+- **Rust** — `pub` items, `use`/`mod` statements, structs/enums/traits/impls; AST mode adds `///` doc-comment purpose lines and `pub use` re-exports
+- **Kotlin** (`.kt/.kts`) — AST mode only: public top-level `fun`/`class`/`object`/`interface`/`enum class`/`data class`/`val`/`var`/`typealias` (excluding `private`/`internal`), `import` paths, KDoc-derived purpose lines; regex mode gives only basic filename classification
+- **Java** — AST mode only: public types and the public methods/fields of the public type, `import` statements (incl. `static` and wildcard), Javadoc-derived purpose lines; regex mode gives only basic filename classification
+
+The dependency graph (`get_related_files`, `get_dependency_graph`) extracts imports for all six language families regardless of summarizer mode.
 
 Config files (JSON, YAML, TOML) and other file types get basic classification.
 

package/dist/cli/index-command.d.ts

@@ -0,0 +1,30 @@
+export interface IndexOptions {
+    /** Suppress the human-readable report printed to stdout. */
+    quiet?: boolean;
+}
+export interface IndexReport {
+    projectRoot: string;
+    cacheDbPath: string;
+    scanned: number;
+    summarized: number;
+    fresh: number;
+    skipped: number;
+    skippedPaths: string[];
+    elapsedMs: number;
+}
+/**
+ * Prewarm the summary cache for a project: scan all indexable files and run
+ * each one through the same hash/compare/summarize/store path the
+ * `get_file_summary` tool uses, so a later MCP session starts with cache hits.
+ *
+ * Files whose hash already matches the cache are left untouched ("fresh");
+ * files that cannot be read or summarized are counted as skipped rather than
+ * aborting the run.
+ */
+export declare function runIndex(projectRoot: string, options?: IndexOptions): Promise<IndexReport>;
+/**
+ * Thin argv wrapper for `repo-memory index [projectRoot] [--quiet]`.
+ * Exits 0 on success, 1 on error (message to stderr).
+ */
+export declare function runIndexCli(argv: string[]): Promise<never>;
+//# sourceMappingURL=index-command.d.ts.map

package/dist/cli/index-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-command.d.ts","sourceRoot":"","sources":["../../src/cli/index-command.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAsDtB;AAeD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CA4BhE"}

package/dist/cli/index-command.js

@@ -0,0 +1,112 @@
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { scanProject } from '../indexer/scanner.js';
+import { ensureSummaryGeneration } from '../indexer/summarize.js';
+import { getDatabasePath } from '../persistence/db.js';
+import { getFileSummary } from '../tools/get-file-summary.js';
+/**
+ * Prewarm the summary cache for a project: scan all indexable files and run
+ * each one through the same hash/compare/summarize/store path the
+ * `get_file_summary` tool uses, so a later MCP session starts with cache hits.
+ *
+ * Files whose hash already matches the cache are left untouched ("fresh");
+ * files that cannot be read or summarized are counted as skipped rather than
+ * aborting the run.
+ */
+export async function runIndex(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        throw new Error(`project root does not exist or is not a directory: ${root}`);
+    }
+    const started = Date.now();
+    // Verify cached summaries match the configured summarizer mode/generation
+    // before any cache comparisons happen.
+    ensureSummaryGeneration(root);
+    const files = await scanProject(root);
+    let summarized = 0;
+    let fresh = 0;
+    const skippedPaths = [];
+    for (const file of files) {
+        try {
+            // Reuses the exact cache-read/write semantics of the get_file_summary
+            // tool: hash, compare, regenerate only when missing/stale. Telemetry is
+            // suppressed — prewarm traffic isn't agent traffic and would distort
+            // hit-ratio stats.
+            const result = await getFileSummary(root, file, { trackTelemetry: false });
+            if (result.fromCache) {
+                fresh += 1;
+            }
+            else {
+                summarized += 1;
+            }
+        }
+        catch {
+            // Unreadable entries (deleted since scan, gitlinks, permission errors).
+            skippedPaths.push(file);
+        }
+    }
+    const report = {
+        projectRoot: root,
+        cacheDbPath: getDatabasePath(root),
+        scanned: files.length,
+        summarized,
+        fresh,
+        skipped: skippedPaths.length,
+        skippedPaths,
+        elapsedMs: Date.now() - started,
+    };
+    if (!options.quiet) {
+        // stdout is safe here — the index command never runs while the MCP stdio
+        // transport is active, so this cannot corrupt the protocol channel.
+        process.stdout.write(formatReport(report));
+    }
+    return report;
+}
+function formatReport(report) {
+    const lines = [
+        `Indexed ${report.projectRoot}`,
+        `  scanned:       ${report.scanned}`,
+        `  summarized:    ${report.summarized}`,
+        `  already fresh: ${report.fresh}`,
+        `  skipped:       ${report.skipped}`,
+        `  elapsed:       ${(report.elapsedMs / 1000).toFixed(2)}s`,
+        `  cache db:      ${report.cacheDbPath}`,
+    ];
+    return lines.join('\n') + '\n';
+}
+/**
+ * Thin argv wrapper for `repo-memory index [projectRoot] [--quiet]`.
+ * Exits 0 on success, 1 on error (message to stderr).
+ */
+export async function runIndexCli(argv) {
+    let quiet = false;
+    let projectRoot;
+    for (const arg of argv) {
+        if (arg === '--quiet' || arg === '-q') {
+            quiet = true;
+        }
+        else if (arg.startsWith('-')) {
+            process.stderr.write(`repo-memory index: unknown option '${arg}'\n`);
+            process.stderr.write('Usage: repo-memory index [projectRoot] [--quiet]\n');
+            process.exit(1);
+        }
+        else if (projectRoot === undefined) {
+            projectRoot = arg;
+        }
+        else {
+            process.stderr.write(`repo-memory index: unexpected argument '${arg}'\n`);
+            process.stderr.write('Usage: repo-memory index [projectRoot] [--quiet]\n');
+            process.exit(1);
+        }
+    }
+    try {
+        await runIndex(projectRoot ?? process.cwd(), { quiet });
+        process.exit(0);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`repo-memory index: ${message}\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=index-command.js.map

package/dist/cli/index-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-command.js","sourceRoot":"","sources":["../../src/cli/index-command.ts"],"names":[],"mappings":"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"}

package/dist/indexer/ast-summarizer.d.ts

@@ -1,8 +1,8 @@
 import type { FileSummary } from '../types.js';
 /**
- * Summarize a TS/JS file from its syntax tree. Falls back to the regex
- * summarizer for unsupported extensions, empty files, parse errors, or when
- * the WASM runtime cannot be loaded.
+ * Summarize a TS/JS, Python, Go, Rust, Kotlin or Java file from its syntax
+ * tree. Falls back to the regex summarizer for unsupported extensions, empty
+ * files, parse errors, or when the WASM runtime cannot be loaded.
  */
 export declare function summarizeFileAst(filePath: string, contents: string): Promise<FileSummary>;
 /** True when the AST summarizer handles this file natively (vs regex fallback). */

package/dist/indexer/ast-summarizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast-summarizer.d.ts","sourceRoot":"","sources":["../../src/indexer/ast-summarizer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA+Y/C;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmC/F;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}
+{"version":3,"file":"ast-summarizer.d.ts","sourceRoot":"","sources":["../../src/indexer/ast-summarizer.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAsvC/C;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqC/F;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD"}