cerebro-code-memory 0.1.0__py3-none-any.whl

cerebro/summaries.py

@@ -0,0 +1,66 @@
+"""Cached English summaries (plan layer 2) and summary-staleness.
+
+A summary is tied to the file version it described via `source_hash`. When the
+file's current hash differs, the summary is flagged stale so a session knows to
+re-read just that file instead of trusting an outdated trace.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def record(conn, path: str, summary: str, model: str | None = None) -> dict:
+    row = conn.execute("SELECT hash FROM files WHERE path=?", (path,)).fetchone()
+    source_hash = row["hash"] if row else None
+    conn.execute(
+        """INSERT INTO summaries(path, summary_en, model, source_hash, updated_at)
+           VALUES(?,?,?,?,?)
+           ON CONFLICT(path) DO UPDATE SET
+             summary_en=excluded.summary_en, model=excluded.model,
+             source_hash=excluded.source_hash, updated_at=excluded.updated_at""",
+        (path, summary, model, source_hash, now_iso()),
+    )
+    conn.execute("DELETE FROM fts WHERE path=? AND kind='summary'", (path,))
+    conn.execute(
+        "INSERT INTO fts(path, kind, text) VALUES(?, 'summary', ?)", (path, summary)
+    )
+    conn.commit()
+    return {"path": path, "indexed": source_hash is not None}
+
+
+def get(conn, path: str, current_hash: str | None = None) -> dict | None:
+    """Look up a cached summary. Pass `current_hash` (the live on-disk hash) to
+    detect staleness against disk directly; otherwise it is compared against the
+    last-indexed hash, which only reflects changes after a reindex."""
+    row = conn.execute("SELECT * FROM summaries WHERE path=?", (path,)).fetchone()
+    if not row:
+        return None
+    if current_hash is None:
+        file_row = conn.execute(
+            "SELECT hash FROM files WHERE path=?", (path,)
+        ).fetchone()
+        current_hash = file_row["hash"] if file_row else None
+    stale = bool(
+        row["source_hash"] and current_hash and current_hash != row["source_hash"]
+    )
+    return {
+        "path": path,
+        "summary_en": row["summary_en"],
+        "model": row["model"],
+        "updated_at": row["updated_at"],
+        "stale": stale,
+    }
+
+
+def stale_summaries(conn) -> list[str]:
+    """Summaries whose source file changed since the summary was written."""
+    rows = conn.execute(
+        """SELECT s.path FROM summaries s JOIN files f ON f.path = s.path
+           WHERE s.source_hash IS NOT NULL AND s.source_hash != f.hash
+           ORDER BY s.path"""
+    ).fetchall()
+    return [r["path"] for r in rows]

cerebro/summarizer.py

@@ -0,0 +1,109 @@
+"""Batch summary generation (plan layer 2, warmed proactively).
+
+Generates English summaries for the most central files so even a first-time query
+is cheap, instead of waiting for sessions to fill them in lazily. Uses headless
+`claude -p` so it needs no API key — it rides the user's existing Claude Code auth.
+A cheap model (Haiku by default) keeps the one-time cost low.
+"""
+from __future__ import annotations
+
+import concurrent.futures as cf
+import os
+import shutil
+import subprocess
+
+from . import config as cfg
+from . import db, graph, summaries
+
+INSTRUCTION = (
+    "You are summarizing a source file for a code-navigation index. In 1-3 dense "
+    "sentences, in English, describe what this file does and its role in the system "
+    "(key responsibilities, important types/functions, how it fits in). Output ONLY "
+    "the summary text — no preamble, no markdown, no bullet points."
+)
+MAX_CHARS = 16000
+DEFAULT_MODEL = "claude-haiku-4-5"
+
+
+def _claude_bin() -> str:
+    return os.environ.get("CEREBRO_CLAUDE") or shutil.which("claude") or "claude"
+
+
+def summarize_one(config, rel: str, model: str) -> str | None:
+    """Generate a summary for one file via `claude -p`. Returns None on failure."""
+    abs_path = config.root / rel
+    try:
+        content = abs_path.read_text(encoding="utf-8", errors="ignore")[:MAX_CHARS]
+    except OSError:
+        return None
+    prompt = f"{INSTRUCTION}\n\nFile path: {rel}\n\n```\n{content}\n```\n"
+    try:
+        out = subprocess.run(
+            [_claude_bin(), "-p", "--model", model],
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=180,
+        )
+    except Exception:
+        return None
+    if out.returncode != 0:
+        return None
+    return out.stdout.strip() or None
+
+
+def select_central_missing(conn, limit: int, prefix: str | None = None) -> list[str]:
+    """Top files by dependency centrality that have no summary yet."""
+    have = {r["path"] for r in conn.execute("SELECT path FROM summaries")}
+    out = []
+    for path, _score in graph.rank(conn):
+        if path in have or cfg.Config.lang_for(path) is None:
+            continue
+        if prefix and not path.startswith(prefix):
+            continue
+        out.append(path)
+        if len(out) >= limit:
+            break
+    return out
+
+
+def run(config, conn, rels: list[str], model: str = DEFAULT_MODEL, workers: int = 4) -> dict:
+    """Summarize files in parallel (claude -p subprocesses), then record serially
+    (one sqlite writer). Returns a count of what was produced."""
+    produced: dict[str, str] = {}
+    with cf.ThreadPoolExecutor(max_workers=workers) as ex:
+        futs = {ex.submit(summarize_one, config, r, model): r for r in rels}
+        for fut in cf.as_completed(futs):
+            summary = fut.result()
+            if summary:
+                produced[futs[fut]] = summary
+    for rel, summary in produced.items():
+        summaries.record(conn, rel, summary, model=model)
+    return {"requested": len(rels), "summarized": len(produced)}
+
+
+def main():  # `cerebro-summarize` entry point
+    import argparse
+    import json
+
+    ap = argparse.ArgumentParser(description="Pre-generate Cerebro summaries via claude -p")
+    ap.add_argument("--limit", type=int, default=20, help="max files to summarize")
+    ap.add_argument("--model", default=DEFAULT_MODEL)
+    ap.add_argument("--prefix", default=None, help="only files under this path prefix")
+    ap.add_argument("--workers", type=int, default=4)
+    args = ap.parse_args()
+
+    config = cfg.Config.load()
+    conn = db.connect(config.db_path)
+    rels = select_central_missing(conn, args.limit, args.prefix)
+    if not rels:
+        print(json.dumps({"summarized": 0, "note": "nothing missing in scope"}))
+        return
+    result = run(config, conn, rels, model=args.model, workers=args.workers)
+    result["model"] = args.model
+    result["root"] = str(config.root)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

cerebro/tsconfig.py

@@ -0,0 +1,159 @@
+"""tsconfig / jsconfig path-alias resolution.
+
+Next.js and NestJS projects import via aliases like `@/components/Button` instead
+of relative paths. Those are declared in `compilerOptions.paths` (relative to
+`baseUrl`). Without expanding them, the dependency graph misses most edges in
+alias-heavy frontends. This module parses those configs (tolerating JSONC and a
+single level of `extends`) and expands an aliased import to candidate repo-relative
+module paths. The indexer then resolves a candidate to a real file.
+"""
+from __future__ import annotations
+
+import json
+import posixpath
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class AliasConfig:
+    dir: str                       # posix dir of the config, relative to root ("" == root)
+    base_url: str                  # posix dir that `paths` resolve from, relative to root
+    patterns: dict[str, list[str]] # e.g. {"@/*": ["./*"]}
+
+
+def _strip_comments(text: str) -> str:
+    """Remove // and /* */ comments while respecting string literals, so glob
+    patterns like "@/*" and "**/*.ts" (which contain /* and */) are not mistaken
+    for comment delimiters."""
+    out = []
+    i, n = 0, len(text)
+    in_str = False
+    while i < n:
+        ch = text[i]
+        if in_str:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if ch == '"':
+                in_str = False
+            i += 1
+            continue
+        if ch == '"':
+            in_str = True
+            out.append(ch)
+            i += 1
+            continue
+        if ch == "/" and i + 1 < n and text[i + 1] == "/":
+            i += 2
+            while i < n and text[i] not in "\n\r":
+                i += 1
+            continue
+        if ch == "/" and i + 1 < n and text[i + 1] == "*":
+            i += 2
+            while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"):
+                i += 1
+            i += 2
+            continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _loads_jsonc(text: str):
+    text = _strip_comments(text)
+    text = re.sub(r",(\s*[}\]])", r"\1", text)  # trailing commas
+    return json.loads(text)
+
+
+def _resolve_extends(base_dir: Path, ext: str) -> Path | None:
+    # Only follow path-like extends (./base, ../tsconfig.base.json); skip packages.
+    if not (ext.startswith(".") or "/" in ext):
+        return None
+    cand = base_dir / ext
+    if cand.suffix != ".json":
+        cand = base_dir / (ext + ".json")
+    return cand if cand.exists() else None
+
+
+def _read_with_extends(abs_path: Path, seen: set) -> dict:
+    rp = abs_path.resolve()
+    if rp in seen:
+        return {}
+    seen.add(rp)
+    try:
+        data = _loads_jsonc(abs_path.read_text(encoding="utf-8", errors="ignore"))
+    except Exception:
+        return {}
+    co = data.get("compilerOptions") or {}
+    result = {"baseUrl": co.get("baseUrl"), "paths": co.get("paths")}
+    ext = data.get("extends")
+    if isinstance(ext, str) and (result["baseUrl"] is None or result["paths"] is None):
+        parent = _resolve_extends(abs_path.parent, ext)
+        if parent is not None:
+            pdata = _read_with_extends(parent, seen)
+            for key in ("baseUrl", "paths"):
+                if result[key] is None:
+                    result[key] = pdata.get(key)
+    return result
+
+
+def load_alias_configs(config) -> list[AliasConfig]:
+    """Scan the repo for tsconfig.json / jsconfig.json files that declare paths."""
+    out: list[AliasConfig] = []
+    for rel, abs_path in config.iter_files():
+        if posixpath.basename(rel) not in ("tsconfig.json", "jsconfig.json"):
+            continue
+        merged = _read_with_extends(abs_path, set())
+        raw_paths = merged.get("paths") or {}
+        if not raw_paths:
+            continue
+        patterns = {
+            k: (v if isinstance(v, list) else [v]) for k, v in raw_paths.items()
+        }
+        cfg_dir = posixpath.dirname(rel)
+        base_url = merged.get("baseUrl") or "."
+        base = posixpath.normpath(posixpath.join(cfg_dir, base_url))
+        out.append(AliasConfig(dir=cfg_dir, base_url=base, patterns=patterns))
+    return out
+
+
+def _nearest(configs: list[AliasConfig], importer_rel: str) -> AliasConfig | None:
+    best = None
+    for c in configs:
+        prefix = (c.dir + "/") if c.dir else ""
+        if importer_rel.startswith(prefix):
+            if best is None or len(c.dir) > len(best.dir):
+                best = c
+    return best
+
+
+def _match(pattern: str, name: str) -> str | None:
+    """Return the wildcard capture if `name` matches `pattern`, else None.
+    Exact (no-`*`) patterns return '' on an exact match."""
+    if "*" in pattern:
+        pre, post = pattern.split("*", 1)
+        if name.startswith(pre) and name.endswith(post) and len(name) >= len(pre) + len(post):
+            return name[len(pre): len(name) - len(post)] if post else name[len(pre):]
+        return None
+    return "" if name == pattern else None
+
+
+def expand(import_str: str, importer_rel: str, configs: list[AliasConfig]) -> list[str]:
+    """Expand an aliased import to candidate repo-relative module paths (no
+    extension). The indexer resolves these against the known file set."""
+    cfg = _nearest(configs, importer_rel)
+    if cfg is None:
+        return []
+    out: list[str] = []
+    for pattern, targets in cfg.patterns.items():
+        cap = _match(pattern, import_str)
+        if cap is None:
+            continue
+        for t in targets:
+            sub = t.replace("*", cap, 1) if "*" in t else t
+            out.append(posixpath.normpath(posixpath.join(cfg.base_url, sub)))
+    return out

cerebro/views.py

@@ -0,0 +1,52 @@
+"""FastMCP-free renderers for the read tools.
+
+The MCP SDK (FastMCP → pydantic/starlette/uvicorn) costs ~230ms to import and is
+only needed to *serve* MCP. The CLI and the SessionStart hook just need the text
+these tools produce, so the rendering logic lives here — importable without pulling
+in the server module — and `server.py` delegates to it.
+"""
+from __future__ import annotations
+
+from . import db, graph, notes, summaries
+
+
+def map_text(conn, root, top: int = 30) -> str:
+    total = conn.execute("SELECT COUNT(*) AS n FROM files").fetchone()["n"]
+    if total == 0:
+        return "Index is empty. Run cerebro_reindex() first to build the map."
+    langs = ", ".join(f"{r['lang']}:{r['n']}" for r in db.lang_counts(conn))
+    last = conn.execute("SELECT value FROM meta WHERE key='last_reindex'").fetchone()
+    lines = [
+        f"# Cerebro map — {root}",
+        f"{total} files | {langs} | last reindex: {last['value'] if last else 'n/a'}",
+        "",
+        f"## Top {top} modules by centrality (most depended-upon):",
+    ]
+    for path, score in graph.rank(conn, top=top):
+        s = summaries.get(conn, path)
+        note = ""
+        if s:
+            flag = " (STALE)" if s["stale"] else ""
+            note = f" — {s['summary_en'][:90]}{flag}"
+        lines.append(f"  {score:.3f}  {path}{note}")
+    no_summary = conn.execute(
+        "SELECT COUNT(*) AS n FROM files f "
+        "LEFT JOIN summaries s ON s.path=f.path WHERE s.path IS NULL"
+    ).fetchone()["n"]
+    lines.append("")
+    lines.append(
+        f"{no_summary} files have no summary yet. As you learn a file, call "
+        f"cerebro_record(path, summary) so future sessions skip re-reading it."
+    )
+    return "\n".join(lines)
+
+
+def recall_text(conn, query: str = "", limit: int = 10) -> str:
+    rows = notes.recall(conn, query, limit=limit)
+    if not rows:
+        return "No notes recorded yet." if not query else f"No notes match '{query}'."
+    out = []
+    for r in rows:
+        head = f"#{r['id']}" + (f" [{r['topic']}]" if r["topic"] else "")
+        out.append(f"{head} ({r['created_at']})\n  {r['content']}")
+    return "\n".join(out)