@reposkein/mcp 0.1.1 → 0.1.2

package/dist/temporal/gitlog.js

@@ -0,0 +1,254 @@
+/**
+ * Git-log mining: co-change, churn, and ownership signals.
+ *
+ * One `git log --no-merges --name-status -z --date=short` pass yields all three
+ * signals. Rename chains are reconstructed from R records so a file's history
+ * follows it across moves. Bulk commits (>K files) are excluded from co-change
+ * counting but still counted for churn. Min-support floor drops one-off pairs.
+ *
+ * All output ordering is by explicit sort keys — never Map iteration order.
+ */
+// ── parseGitLog ──────────────────────────────────────────────────────────────
+/**
+ * Parse output of:
+ *   git log --no-merges --name-status -z --date=short
+ *       --format='%x00%H%x1f%ad%x1f%aN%x1f%aE'
+ *
+ * The `-z` flag makes git NUL-terminate each path in the name-status block.
+ * We split on NUL to get tokens, then detect the commit header lines
+ * (which start with NUL %H %ad %aN %aE joined by FS=\x1f).
+ *
+ * Rename records arrive as e.g. `R100\toldpath\0newpath\0`.
+ * With -z, git emits: <status>\0<path1>\0 and for renames <status>\0<path1>\0<path2>\0.
+ *
+ * Actual git -z --name-status output format (tested):
+ *   \0<sha>\x1f<date>\x1f<name>\x1f<email>\n\n<status>\0<path>\0...<status>\0<old>\0<new>\0
+ * The commit separator is "\n\n" before the header NUL. We split entire output
+ * on the pattern "\x00\x00" (double NUL that appears between commits in -z mode)
+ * combined with the leading-NUL header.
+ *
+ * Strategy: split on NUL → walk tokens; whenever we see a token matching
+ * /^\x00<sha>\x1f.../ we start a new commit header; otherwise collect
+ * name-status entries.
+ */
+export function parseGitLog(raw) {
+    if (!raw.trim())
+        return [];
+    // With --format='%x00%H%x1f%ad%x1f%aN%x1f%aE' and -z, each commit header
+    // is emitted as a NUL-prefixed record. The name-status entries follow,
+    // NUL-separated, then the next commit header starts with NUL again.
+    // Split on NUL and walk tokens.
+    const tokens = raw.split("\x00");
+    const commits = [];
+    let current = null;
+    // raw file pairs for current commit before rename resolution: [status, path, ?renameTo]
+    let rawFiles = [];
+    const flush = () => {
+        if (!current)
+            return;
+        commits.push({ sha: current.sha, date: current.date, author_name: current.name, author_email: current.email, files: [] });
+        // attach raw files for post-processing (we store them temporarily)
+        commits[commits.length - 1]._raw = rawFiles;
+        rawFiles = [];
+        current = null;
+    };
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        // Commit headers start with \x00 then SHA\x1fDATE\x1fNAME\x1fEMAIL
+        // Since we split on \x00, the header token itself (after the leading NUL
+        // is consumed by split) may look like: \nSHA\x1f... or SHA\x1f...
+        // The very first token before any NUL may be empty or contain a newline.
+        // A header token contains \x1f (field separator).
+        if (tok.includes("\x1f")) {
+            // This is a commit header (possibly with leading whitespace/newlines)
+            flush();
+            const clean = tok.replace(/^\s+/, "");
+            const parts = clean.split("\x1f");
+            if (parts.length >= 4) {
+                current = {
+                    sha: parts[0].trim(),
+                    date: parts[1].trim(),
+                    name: parts[2].trim(),
+                    email: parts[3].trim(),
+                };
+            }
+            continue;
+        }
+        // Skip empty tokens / whitespace-only tokens (between commits, end of output)
+        const t = tok.trim();
+        if (!t)
+            continue;
+        if (!current)
+            continue; // haven't seen a commit header yet
+        // Name-status tokens: "M", "A", "D", "R100", "C100", ...
+        // In -z mode: after a status token, the next token(s) are paths.
+        // We handle this by peeking ahead.
+        if (/^[MADRCTU]\d*$/.test(t)) {
+            const status = t[0];
+            if (status === "R" || status === "C") {
+                // rename/copy: next two tokens are old-path and new-path
+                const oldPath = tokens[++i]?.trim() ?? "";
+                const newPath = tokens[++i]?.trim() ?? "";
+                if (oldPath && newPath) {
+                    rawFiles.push({ status, path: oldPath, renameTo: newPath });
+                }
+            }
+            else {
+                const path = tokens[++i]?.trim() ?? "";
+                if (path) {
+                    rawFiles.push({ status, path });
+                }
+            }
+        }
+        // If the token doesn't match a status code and isn't empty, it's likely a
+        // stray path token already consumed above — ignore.
+    }
+    flush();
+    // ── Rename chain reconstruction ───────────────────────────────────────────
+    // Git log outputs commits newest-first. A rename record `R old → new` in
+    // commit C means: at C, the file was renamed from `old` to `new`.
+    // Any commits OLDER than C that reference `old` should be canonicalized
+    // to `new` (the current name).
+    //
+    // Algorithm: process commits in git-log order (newest first).
+    // Maintain aliasMap: old-name → current-canonical-name.
+    // - For non-rename files: apply aliasMap to get canonical name.
+    // - For rename records (R/C): add oldPath → newPath to aliasMap (so
+    //   older commits referencing oldPath map to newPath). Also add oldPath
+    //   as a file in this commit (it was touched — it's being renamed).
+    //   The newPath is already in aliasMap for future lookups.
+    const aliasMap = new Map();
+    const resolved = commits.map((c) => {
+        const raw = c._raw ?? [];
+        const canonPaths = new Set();
+        for (const f of raw) {
+            if (f.status === "R" || f.status === "C") {
+                // This commit touched both old and new paths (it performed the rename).
+                // The canonical name for oldPath is newPath (or whatever newPath maps to).
+                if (f.renameTo) {
+                    const canonNew = resolveAlias(f.renameTo, aliasMap);
+                    canonPaths.add(canonNew);
+                    // Record: older commits using oldPath should map to canonNew
+                    aliasMap.set(f.path, canonNew);
+                }
+            }
+            else {
+                const canon = resolveAlias(f.path, aliasMap);
+                canonPaths.add(canon);
+            }
+        }
+        return { ...c, files: [...canonPaths].sort() };
+    });
+    return resolved;
+}
+function resolveAlias(path, aliasMap) {
+    let cur = path;
+    const seen = new Set();
+    while (aliasMap.has(cur) && !seen.has(cur)) {
+        seen.add(cur);
+        cur = aliasMap.get(cur);
+    }
+    return cur;
+}
+// ── computeTemporal ──────────────────────────────────────────────────────────
+export function computeTemporal(commits, opts) {
+    const K = opts.maxFilesPerCommit ?? 50;
+    const minSupport = opts.minSupport ?? 3;
+    const topCoChanged = opts.topCoChanged ?? 20;
+    const topAuthors = opts.topAuthors ?? 5;
+    // Per-file: churn counts, dates, author tallies
+    const changeCount = new Map();
+    const lastChanged = new Map();
+    const authorCommits = new Map(); // file → author_name → count
+    // Pairwise co-change counts (both directions stored): key = "a\x1fb"
+    const pairCount = new Map();
+    for (const commit of commits) {
+        const files = commit.files;
+        // ── churn (all commits including bulk) ───────────────────────────────
+        for (const f of files) {
+            changeCount.set(f, (changeCount.get(f) ?? 0) + 1);
+            const prev = lastChanged.get(f);
+            if (!prev || commit.date > prev)
+                lastChanged.set(f, commit.date);
+            // author tally
+            let am = authorCommits.get(f);
+            if (!am) {
+                am = new Map();
+                authorCommits.set(f, am);
+            }
+            am.set(commit.author_name, (am.get(commit.author_name) ?? 0) + 1);
+        }
+        // ── co-change (exclude bulk commits) ─────────────────────────────────
+        if (files.length < 2 || files.length > K)
+            continue;
+        for (let i = 0; i < files.length; i++) {
+            for (let j = i + 1; j < files.length; j++) {
+                const a = files[i];
+                const b = files[j];
+                const key = a < b ? `${a}\x1f${b}` : `${b}\x1f${a}`;
+                pairCount.set(key, (pairCount.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    // ── Build cochange map ────────────────────────────────────────────────────
+    // For each pair with support ≥ minSupport, compute confidence(a→b) and confidence(b→a).
+    const cochangeRaw = new Map();
+    for (const [key, support] of pairCount.entries()) {
+        if (support < minSupport)
+            continue;
+        const [a, b] = key.split("\x1f");
+        const countA = changeCount.get(a) ?? 1;
+        const countB = changeCount.get(b) ?? 1;
+        const confAB = support / countA;
+        const confBA = support / countB;
+        if (!cochangeRaw.has(a))
+            cochangeRaw.set(a, []);
+        if (!cochangeRaw.has(b))
+            cochangeRaw.set(b, []);
+        cochangeRaw.get(a).push({ path: b, support, confidence: confAB });
+        cochangeRaw.get(b).push({ path: a, support, confidence: confBA });
+    }
+    // Sort each file's co-change list: confidence desc, support desc, path asc
+    const cochange = {};
+    // Sort files for deterministic output
+    const cochangeFiles = [...cochangeRaw.keys()].sort();
+    for (const f of cochangeFiles) {
+        const list = cochangeRaw.get(f);
+        list.sort((a, b) => {
+            if (b.confidence !== a.confidence)
+                return b.confidence - a.confidence;
+            if (b.support !== a.support)
+                return b.support - a.support;
+            return a.path.localeCompare(b.path);
+        });
+        cochange[f] = list.slice(0, topCoChanged);
+    }
+    // ── Build files map ───────────────────────────────────────────────────────
+    const files = {};
+    // Sort file keys for deterministic output
+    const fileKeys = [...changeCount.keys()].sort();
+    for (const f of fileKeys) {
+        const am = authorCommits.get(f) ?? new Map();
+        // Sort authors: commits desc, then name asc
+        const authors = [...am.entries()]
+            .sort(([na, ca], [nb, cb]) => {
+            if (cb !== ca)
+                return cb - ca;
+            return na.localeCompare(nb);
+        })
+            .slice(0, topAuthors)
+            .map(([name, commits]) => ({ name, commits }));
+        files[f] = {
+            change_count: changeCount.get(f) ?? 0,
+            last_changed: lastChanged.get(f) ?? "",
+            authors,
+        };
+    }
+    return {
+        head_sha: opts.headSha,
+        shallow: opts.shallow,
+        files,
+        cochange,
+    };
+}
+//# sourceMappingURL=gitlog.js.map

package/dist/temporal/gitlog.js.map

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

package/dist/temporal/temporal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Temporal context runner + sidecar cache.
+ *
+ * Shells out to `git log` via execFile, caches computed TemporalStats to
+ * .reposkein/local/temporal/<head-sha>.json (gitignored). Second call with the
+ * same HEAD sha is a cache hit (file read only).
+ *
+ * Graceful: not-a-git-repo / git-missing / empty history →
+ *   { unavailable: "<reason>" }  (never throws into the request).
+ *
+ * Prunes old cache files (keeps newest K=3) on each successful compute.
+ */
+import { type TemporalStats } from "./gitlog.js";
+export type TemporalResult = TemporalStats | {
+    unavailable: string;
+};
+/**
+ * Compute (or load from cache) temporal stats for all files in the repo.
+ * Returns { unavailable: reason } if git is unavailable or repo has no history.
+ * Never throws.
+ */
+export declare function getTemporal(repoPath: string): Promise<TemporalResult>;

package/dist/temporal/temporal.js

@@ -0,0 +1,185 @@
+/**
+ * Temporal context runner + sidecar cache.
+ *
+ * Shells out to `git log` via execFile, caches computed TemporalStats to
+ * .reposkein/local/temporal/<head-sha>.json (gitignored). Second call with the
+ * same HEAD sha is a cache hit (file read only).
+ *
+ * Graceful: not-a-git-repo / git-missing / empty history →
+ *   { unavailable: "<reason>" }  (never throws into the request).
+ *
+ * Prunes old cache files (keeps newest K=3) on each successful compute.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, unlinkSync, statSync, } from "node:fs";
+import { join } from "node:path";
+import { parseGitLog, computeTemporal } from "./gitlog.js";
+const execFile = promisify(execFileCb);
+/** Max cache files to keep per repo (prune oldest when exceeded). */
+const MAX_CACHE_FILES = 3;
+/** Window defaults (also used for cache key). */
+const WINDOW_MONTHS = 12;
+const MAX_COMMITS = 1000;
+const COMMIT_SIZE_CAP = 50;
+const MIN_SUPPORT = 3;
+// ── git helpers ──────────────────────────────────────────────────────────────
+async function gitExec(args, cwd) {
+    try {
+        const { stdout } = await execFile("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+        return { stdout, ok: true };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { stdout: "", ok: false, error: "git executable not found in PATH" };
+        }
+        // git exits non-zero for "not a git repo" etc.
+        const msg = e.stderr ?? e.message ?? String(err);
+        return { stdout: e.stdout ?? "", ok: false, error: msg.trim() };
+    }
+}
+async function getHeadSha(repoPath) {
+    const r = await gitExec(["rev-parse", "HEAD"], repoPath);
+    if (!r.ok) {
+        // Check if it's a "not a git repo" error
+        if (r.error?.includes("not a git repository")) {
+            return { unavailable: "not a git repository" };
+        }
+        if (r.error?.includes("git executable not found")) {
+            return { unavailable: r.error };
+        }
+        // Could be an empty repo (no commits yet)
+        const check = await gitExec(["rev-parse", "--git-dir"], repoPath);
+        if (!check.ok)
+            return { unavailable: "not a git repository" };
+        return { unavailable: "repository has no commits" };
+    }
+    return { sha: r.stdout.trim() };
+}
+async function isShallow(repoPath) {
+    const r = await gitExec(["rev-parse", "--is-shallow-repository"], repoPath);
+    return r.ok && r.stdout.trim() === "true";
+}
+// ── cache helpers ─────────────────────────────────────────────────────────────
+function cacheDir(repoPath) {
+    return join(repoPath, ".reposkein", "local", "temporal");
+}
+function cachePath(repoPath, headSha) {
+    return join(cacheDir(repoPath), `${headSha}.json`);
+}
+function readCache(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const text = readFileSync(path, "utf8");
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic write: write to a .tmp file then rename (best-effort on all platforms). */
+function writeCache(path, stats) {
+    const tmp = `${path}.tmp`;
+    try {
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(tmp, JSON.stringify(stats));
+        renameSync(tmp, path);
+    }
+    catch {
+        // best-effort; a write failure must not break the tool call
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+    }
+}
+/** Keep only the newest MAX_CACHE_FILES files; prune the rest (best-effort). */
+function pruneCache(dir) {
+    try {
+        if (!existsSync(dir))
+            return;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => ({ name: f, mtime: statSync(join(dir, f)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime); // newest first
+        for (const f of files.slice(MAX_CACHE_FILES)) {
+            try {
+                unlinkSync(join(dir, f.name));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+// ── main export ──────────────────────────────────────────────────────────────
+/**
+ * Compute (or load from cache) temporal stats for all files in the repo.
+ * Returns { unavailable: reason } if git is unavailable or repo has no history.
+ * Never throws.
+ */
+export async function getTemporal(repoPath) {
+    try {
+        // 1. Resolve HEAD sha
+        const headResult = await getHeadSha(repoPath);
+        if ("unavailable" in headResult)
+            return headResult;
+        const headSha = headResult.sha;
+        // 2. Check cache
+        const cPath = cachePath(repoPath, headSha);
+        const cached = readCache(cPath);
+        if (cached)
+            return cached;
+        // 3. Detect shallow clone
+        const shallow = await isShallow(repoPath);
+        // 4. Run git log
+        const logArgs = [
+            "log",
+            "--no-merges",
+            "--name-status",
+            "-z",
+            "--date=short",
+            `--format=%x00%H%x1f%ad%x1f%aN%x1f%aE`,
+            `--since=${WINDOW_MONTHS} months ago`,
+            `-n`,
+            String(MAX_COMMITS),
+        ];
+        const logResult = await gitExec(logArgs, repoPath);
+        if (!logResult.ok) {
+            return { unavailable: `git log failed: ${logResult.error ?? "unknown error"}` };
+        }
+        const raw = logResult.stdout;
+        if (!raw.trim()) {
+            // No commits in window
+            const stats = {
+                head_sha: headSha,
+                shallow,
+                files: {},
+                cochange: {},
+            };
+            writeCache(cPath, stats);
+            return stats;
+        }
+        // 5. Parse and compute
+        const commits = parseGitLog(raw);
+        const stats = computeTemporal(commits, {
+            headSha,
+            shallow,
+            maxFilesPerCommit: COMMIT_SIZE_CAP,
+            minSupport: MIN_SUPPORT,
+        });
+        // 6. Write cache and prune
+        writeCache(cPath, stats);
+        pruneCache(cacheDir(repoPath));
+        return stats;
+    }
+    catch (err) {
+        // Should not reach here — but fail safe
+        return { unavailable: `unexpected error: ${err.message ?? String(err)}` };
+    }
+}
+//# sourceMappingURL=temporal.js.map

package/dist/temporal/temporal.js.map

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

package/dist/tools/impact.d.ts

@@ -0,0 +1,11 @@
+import type { GraphStore } from "../store/GraphStore.js";
+import type { ToolResult } from "./readCypher.js";
+export interface ImpactArgs {
+    node_id?: string;
+    file_path?: string;
+    name?: string;
+    depth?: number;
+    federated?: boolean;
+}
+/** Builds the impact tool handler bound to a store and repo. */
+export declare function makeImpact(store: GraphStore, repoId: string): (args: ImpactArgs) => Promise<ToolResult>;

package/dist/tools/impact.js

@@ -0,0 +1,63 @@
+import { resolveTarget } from "../profile/resolve.js";
+import { computeImpact } from "../profile/impact.js";
+import { federationIds } from "../store/federation.js";
+function clamp(val, min, max) {
+    return Math.min(Math.max(val, min), max);
+}
+/** Builds the impact tool handler bound to a store and repo. */
+export function makeImpact(store, repoId) {
+    return async (args) => {
+        const sel = {
+            node_id: args.node_id,
+            file_path: args.file_path,
+            name: args.name,
+        };
+        if (!sel.node_id && !sel.name && !sel.file_path) {
+            return {
+                content: [{ type: "text", text: "provide one of: node_id, file_path+name, or name" }],
+                isError: true,
+            };
+        }
+        try {
+            const repoIds = args.federated ? await federationIds(store, repoId) : [repoId];
+            const resolved = await resolveTarget(store, repoIds, sel);
+            if (resolved.kind === "not_found") {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "target not found" }) }],
+                    isError: true,
+                };
+            }
+            if (resolved.kind === "candidates") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ambiguous: true,
+                                candidates: resolved.candidates.map((c) => ({
+                                    id: c.id,
+                                    name: c.qualified_name,
+                                    file_path: c.file_path,
+                                    repo_id: c.repo_id,
+                                })),
+                            }),
+                        },
+                    ],
+                };
+            }
+            const target = resolved.target;
+            const depth = clamp(args.depth ?? 3, 1, 5);
+            const result = await computeImpact(store, repoIds, target.id, target.qualified_name, target.file_path, { depth, maxNodes: 500 });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: e.message }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=impact.js.map

package/dist/tools/impact.js.map

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

package/dist/tools/semanticFind.d.ts

@@ -0,0 +1,37 @@
+/**
+ * semantic_find tool — lexical (BM25F) + optional hybrid embedding entry-point discovery.
+ *
+ * Cold-start seed finder: answers "where is X?" when the agent has no node_id
+ * or exact identifier. Returns ranked node_ids ready for get_context_profile.
+ *
+ * Default behaviour (REPOSKEIN_EMBED_PROVIDER unset/none):
+ *   Pure-lexical BM25F — byte-identical to the pre-embeddings baseline.
+ *
+ * With a provider configured:
+ *   Hybrid: BM25F lexical + cosine similarity, fused via RRF (k=60).
+ *   On ANY embedding error → silently falls back to pure-lexical (never breaks the tool).
+ *   The lexical ranking is always computed first, so fallback is free.
+ *
+ * Architecture: calls store.searchCorpus to load the eligible node set, then
+ * the shared BM25F scorer ranks in TypeScript — byte-identical for both JSONL
+ * and Neo4j backends. No Neo4j vector index used.
+ */
+import type { GraphStore } from "../store/GraphStore.js";
+import type { ToolResult } from "./readCypher.js";
+import type { EmbeddingProvider } from "../embed/provider.js";
+export interface SemanticFindArgs {
+    query: string;
+    limit?: number;
+    kind?: "Function" | "Class" | "Interface" | "Enum";
+    federated?: boolean;
+}
+/**
+ * Factory for the semantic_find handler.
+ *
+ * @param store         The graph store.
+ * @param repoId        The active repo id.
+ * @param repoPath      File system path to the repo root (for the embedding cache).
+ * @param providerOverride  Inject a provider directly (for tests — avoids env/network).
+ *                          Pass null to force pure-lexical. Pass undefined to use env config.
+ */
+export declare function makeSemanticFind(store: GraphStore, repoId: string, repoPath?: string, providerOverride?: EmbeddingProvider | null): (args: SemanticFindArgs) => Promise<ToolResult>;