heimdall-code 0.1.0__py3-none-any.whl

heimdall/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: heimdall
+description: Answer "what calls this?", "what breaks if I change it?" and "how does A reach B?" from a precomputed code graph instead of grepping. Use whenever a question is about how a codebase is wired -- callers, blast radius, dead code, call paths -- in any of 18 languages.
+---
+
+# Heimdall
+
+A SQLite call/import/inheritance graph of the repository. One index, then every
+structural question is a single fast query instead of a grep sweep.
+
+## First
+
+```bash
+heimdall index          # build .heimdall/graph.db for the current repo (~1.5s for Django)
+```
+
+Idempotent — re-run after any large change. `heimdall projects` lists what is already
+indexed; every command takes `-p NAME` to query another repo, and `--json` for parsing.
+
+## Then
+
+| Question | Command |
+|---|---|
+| what is this repo? | `heimdall stats` |
+| where is the thing called roughly *this*? | `heimdall search "retry backoff"` |
+| who calls X, what does X call, what is X? | `heimdall context X` |
+| what breaks if I change X? | `heimdall impact X -d 2 -c 0.7` |
+| how does A reach B? | `heimdall trace A B` |
+| anything else | `heimdall sql "SELECT ..."` |
+
+`X` is a bare name (`save`), a qualified name (`app/models.py:User.save`) or a file path.
+A receiver disambiguates: `context Model.check` answers for the `Model` that defines
+`check`, not for every `check` in the tree.
+
+## Confidence
+
+Call edges are scored 0.3 (name match only) to 1.0 (certain). `impact` and `trace`
+default to 0.3 and 0.5. Raise with `-c 0.7` when a wide answer looks like noise —
+`client.get()` on an inferred variable is the usual source of the extra rows.
+
+## SQL escape hatch
+
+```sql
+node(id, kind, name, qname, path, line, end_line, lang, signature)  -- Folder|File|Class|Interface|Function|Method
+edge(src, dst, kind, confidence, line)                             -- CONTAINS|DEFINES|IMPORTS|CALLS|EXTENDS
+```
+
+Read-only, one `SELECT` or `WITH` per call; recursive CTEs work. That is the whole model.
+
+## Don't
+
+- Don't grep for callers when the repo is indexed — `context` already has them, with lines.
+- Don't trust a 0.3 edge as a fact; say it is a candidate.
+- Don't re-index inside a loop. Once per session is enough.

heimdall/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Heimdall -- a code knowledge graph that sees everything.
+
+Indexes a repository into a SQLite property graph (symbols, calls, imports,
+inheritance) and serves it to agents over MCP.
+"""
+
+from .graph import Graph
+from .index import build
+
+__version__ = "0.1.0"
+__all__ = ["Graph", "__version__", "build"]

heimdall/__main__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

heimdall/cli.py

@@ -0,0 +1,200 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import registry
+from .graph import Graph
+from .index import build
+
+
+def _log(msg: str) -> None:
+    print(msg, file=sys.stderr, flush=True)
+
+
+def _emit(data, as_json: bool) -> None:
+    if as_json:
+        json.dump(data, sys.stdout, indent=2, default=str)
+        print()
+    else:
+        _render(data)
+
+
+def _loc(n: dict) -> str:
+    return f"{n.get('path')}:{n.get('line')}" if n.get("line") else str(n.get("path") or "")
+
+
+def _line(n: dict, prefix: str = "") -> str:
+    conf = n.get("confidence")
+    tag = f" ({conf:.2f})" if isinstance(conf, float) and conf < 1.0 else ""
+    return f"{prefix}{n.get('kind', ''):<10} {n.get('qname', '')}{tag}\n{prefix}{'':<10} {_loc(n)}"
+
+
+def _render(data) -> None:
+    if isinstance(data, list):
+        if data and not all(isinstance(n, dict) and "qname" in n and "kind" in n for n in data):
+            for row in data:  # arbitrary SQL result
+                print(json.dumps(row, default=str))
+            return
+        for n in data:
+            print(_line(n))
+        return
+    if not isinstance(data, dict):
+        print(data)
+        return
+    if "error" in data:
+        print(f"error: {data['error']}")
+        for s in data.get("suggestions", []):
+            print(f"  did you mean  {s['qname']}")
+        return
+    if "symbol" in data:  # context
+        s = data["symbol"]
+        print(f"{s['kind']} {s['qname']}\n  {_loc(s)}\n  {s['signature']}")
+        for key in ("defined_in", "members", "calls", "callers", "extends", "extended_by", "ambiguous_with"):
+            v = data.get(key)
+            if not v:
+                continue
+            rows = v if isinstance(v, list) else [v]
+            print(f"\n{key.replace('_', ' ')} ({len(rows)}):")
+            for n in rows[:25]:
+                print(_line(n, "  "))
+            if len(rows) > 25:
+                print(f"  ... {len(rows) - 25} more")
+        return
+    if "by_depth" in data:  # impact
+        print(f"impact of {data['target']['qname']}: {data['total']} symbols, {len(data['files_affected'])} files")
+        for depth in sorted(data["by_depth"], key=int):
+            rows = data["by_depth"][depth]
+            print(f"\ndepth {depth} ({len(rows)}):")
+            for n in rows[:25]:
+                print(_line(n, "  "))
+            if len(rows) > 25:
+                print(f"  ... {len(rows) - 25} more")
+        return
+    if "found" in data:  # trace
+        if not data["found"]:
+            print("no path found")
+            return
+        print(f"path of length {data['length']}:")
+        for i, n in enumerate(data["path"]):
+            print(f"  {'  ' * i}-> {n['qname']}  [{_loc(n)}]")
+        return
+    print(json.dumps(data, indent=2, default=str))
+
+
+def main(argv: list[str] | None = None) -> int:
+    # the same two flags before or after the subcommand; SUPPRESS keeps the subparser
+    # from overwriting a value already given globally
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="emit raw JSON")
+    common.add_argument("-p", "--project", default=argparse.SUPPRESS, help="indexed project name or path to a graph.db")
+
+    ap = argparse.ArgumentParser(prog="heimdall", description="Code knowledge graph for AI agents.")
+    ap.add_argument("--json", action="store_true", help="emit raw JSON")
+    ap.add_argument("-p", "--project", help="indexed project name or path to a graph.db")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def cmd(name, help):
+        return sub.add_parser(name, help=help, parents=[common])
+
+    p = cmd("index", "build or rebuild the graph for a repository")
+    p.add_argument("root", nargs="?", default=".", type=Path)
+    p.add_argument("--db", type=Path, help="output database (default <root>/.heimdall/graph.db)")
+    p.add_argument("-j", "--jobs", type=int, default=0, help="parser processes (default: all cores)")
+    p.add_argument("--name", help="registry name (default: directory name)")
+
+    p = cmd("search", "BM25 symbol search")
+    p.add_argument("query")
+    p.add_argument("-k", "--kind", help="Function|Method|Class|Interface|File")
+    p.add_argument("-n", "--limit", type=int, default=20)
+
+    p = cmd("context", "full 360 view of one symbol")
+    p.add_argument("symbol")
+
+    p = cmd("impact", "what breaks if this symbol changes")
+    p.add_argument("symbol")
+    p.add_argument("-d", "--depth", type=int, default=3)
+    p.add_argument("-c", "--min-confidence", type=float, default=0.3)
+    p.add_argument("-n", "--per-depth", type=int, default=40)
+
+    p = cmd("trace", "shortest path between two symbols")
+    p.add_argument("source")
+    p.add_argument("target")
+    p.add_argument("-d", "--depth", type=int, default=8)
+    p.add_argument("-c", "--min-confidence", type=float, default=0.5)
+
+    cmd("stats", "what is in the graph")
+    cmd("projects", "list indexed repositories")
+    cmd("mcp", "run the MCP server on stdio")
+
+    # no `parents=[common]`: this one owns --project, and it takes no -p/--project target
+    p = sub.add_parser("install", help="register heimdall with a coding agent")
+    p.add_argument("agent", nargs="?", default="all", choices=["claude", "codex", "all"])
+    p.add_argument("--project", action="store_true", help="write into this repository instead of your home config")
+    p.add_argument(
+        "--cli", action="store_true", help="install the skill that drives the CLI, instead of the MCP server"
+    )
+
+    p = cmd("sql", "read-only SQL against the graph")
+    p.add_argument("query")
+    p.add_argument("-n", "--limit", type=int, default=100)
+
+    a = ap.parse_args(argv)
+
+    if a.cmd == "index":
+        root = a.root.resolve()
+        db = a.db or registry.db_path_for(root)
+        stats = build(root, db, jobs=a.jobs, log=_log)
+        registry.register(a.name or root.name, db)
+        _emit(stats, a.json)
+        return 0
+
+    if a.cmd == "projects":
+        entries = registry.load()
+        if a.json:
+            _emit(entries, True)
+        else:
+            for name, db in sorted(entries.items()):
+                print(f"{name:<28} {db}")
+        return 0
+
+    if a.cmd == "install":
+        from .install import install
+
+        lines = install(a.agent, project=a.project, cli=a.cli)
+        if a.json:
+            _emit(lines, True)
+        else:
+            print(*lines, sep="\n")
+        return 1 if any(line.startswith("!") for line in lines) else 0
+
+    if a.cmd == "mcp":
+        from .mcp_server import serve
+
+        serve(a.project)
+        return 0
+
+    g = Graph.open(registry.resolve(a.project), readonly=True)
+    try:
+        match a.cmd:
+            case "search":
+                _emit(g.search(a.query, a.limit, a.kind), a.json)
+            case "context":
+                _emit(g.context(a.symbol), a.json)
+            case "impact":
+                _emit(g.impact(a.symbol, a.depth, a.min_confidence, a.per_depth), a.json)
+            case "trace":
+                _emit(g.trace(a.source, a.target, a.depth, a.min_confidence), a.json)
+            case "stats":
+                _emit(g.stats(), True)
+            case "sql":
+                _emit(g.query(a.query, a.limit), a.json)
+    finally:
+        g.close()
+    return 0

heimdall/graph.py

@@ -0,0 +1,286 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The knowledge graph, stored in SQLite.
+
+A graph database is two tables and a recursive CTE. SQLite ships with Python, does
+BM25 through FTS5, and handles a few million edges without complaint -- so there is
+no embedded graph engine, no WASM, and no server here.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+SCHEMA = """
+PRAGMA journal_mode=WAL;
+CREATE TABLE IF NOT EXISTS node(
+    id        INTEGER PRIMARY KEY,
+    kind      TEXT NOT NULL,          -- Folder|File|Function|Method|Class|Interface
+    name      TEXT NOT NULL,
+    qname     TEXT NOT NULL UNIQUE,
+    path      TEXT,
+    line      INTEGER DEFAULT 0,
+    end_line  INTEGER DEFAULT 0,
+    lang      TEXT,
+    signature TEXT DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS edge(
+    src        INTEGER NOT NULL REFERENCES node(id),
+    dst        INTEGER NOT NULL REFERENCES node(id),
+    kind       TEXT NOT NULL,         -- CONTAINS|DEFINES|CALLS|IMPORTS|EXTENDS
+    confidence REAL DEFAULT 1.0,
+    line       INTEGER DEFAULT 0,
+    PRIMARY KEY (src, dst, kind, line)
+) WITHOUT ROWID;
+CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT);
+CREATE INDEX IF NOT EXISTS node_name ON node(name);
+CREATE INDEX IF NOT EXISTS node_path ON node(path);
+CREATE INDEX IF NOT EXISTS node_kind ON node(kind);
+CREATE INDEX IF NOT EXISTS edge_dst  ON edge(dst, kind);
+CREATE INDEX IF NOT EXISTS edge_src  ON edge(src, kind);
+CREATE VIRTUAL TABLE IF NOT EXISTS node_fts
+    USING fts5(name, qname, signature, content='node', content_rowid='id', tokenize='porter unicode61');
+"""
+
+TRAVERSABLE = ("CALLS", "EXTENDS", "IMPORTS")
+
+
+@dataclass(slots=True)
+class Graph:
+    db: sqlite3.Connection
+
+    # ------------------------------------------------------------ lifecycle
+
+    @staticmethod
+    def open(path: str | Path, *, readonly: bool = False) -> Graph:
+        path = Path(path)
+        if readonly:
+            db = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            db = sqlite3.connect(path)
+            db.executescript(SCHEMA)
+        db.row_factory = sqlite3.Row
+        return Graph(db)
+
+    def close(self) -> None:
+        self.db.close()
+
+    def reindex_fts(self) -> None:
+        self.db.execute("INSERT INTO node_fts(node_fts) VALUES('rebuild')")
+
+    def set_meta(self, **kv: object) -> None:
+        self.db.executemany(
+            "INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)",
+            [(k, json.dumps(v)) for k, v in kv.items()],
+        )
+
+    def meta(self) -> dict:
+        return {r["key"]: json.loads(r["value"]) for r in self.db.execute("SELECT key, value FROM meta")}
+
+    # ------------------------------------------------------------ writing
+
+    def add_nodes(self, rows) -> None:
+        self.db.executemany(
+            "INSERT OR IGNORE INTO node(kind,name,qname,path,line,end_line,lang,signature)"
+            " VALUES (:kind,:name,:qname,:path,:line,:end_line,:lang,:signature)",
+            rows,
+        )
+
+    def add_edges(self, rows) -> None:
+        self.db.executemany("INSERT OR IGNORE INTO edge(src,dst,kind,confidence,line) VALUES (?,?,?,?,?)", rows)
+
+    def ids_by_qname(self) -> dict[str, int]:
+        return {r["qname"]: r["id"] for r in self.db.execute("SELECT id, qname FROM node")}
+
+    # ------------------------------------------------------------ reading
+
+    def resolve(self, ref: str) -> list[sqlite3.Row]:
+        """Find nodes by exact qname, then by path, then by bare name."""
+        for sql, arg in (
+            ("SELECT * FROM node WHERE qname = ?", ref),
+            ("SELECT * FROM node WHERE path = ?", ref),
+            ("SELECT * FROM node WHERE name = ? ORDER BY kind, qname LIMIT 25", ref),
+            ("SELECT * FROM node WHERE qname LIKE ? ORDER BY length(qname) LIMIT 25", f"%{ref}"),
+        ):
+            rows = self.db.execute(sql, (arg,)).fetchall()
+            if rows:
+                return rows
+        return []
+
+    @staticmethod
+    def _fts_query(query: str) -> str:
+        """Free text -> FTS5. Terms are OR'd with prefix matching, so `retry backoff`
+        ranks symbols mentioning either and symbols mentioning both highest."""
+        words = re.findall(r"\w+", query)
+        if not words:
+            return ""
+        return " OR ".join(f'"{w}"*' for w in words)
+
+    def search(self, query: str, limit: int = 20, kind: str | None = None) -> list[dict]:
+        """BM25 ranked symbol search. Falls back to substring match for odd queries."""
+        # folders match everything under them and drown out real symbols; ask for them by name
+        where = " AND n.kind = ?" if kind else " AND n.kind != 'Folder'"
+        args: list = [self._fts_query(query)]
+        if kind:
+            args.append(kind)
+        args.append(limit)
+        try:
+            rows = self.db.execute(
+                "SELECT n.*, bm25(node_fts, 6.0, 3.0, 1.0) AS score FROM node_fts"
+                " JOIN node n ON n.id = node_fts.rowid"
+                f" WHERE node_fts MATCH ?{where} ORDER BY score LIMIT ?",
+                args,
+            ).fetchall()
+        except sqlite3.OperationalError:  # unquotable FTS syntax, e.g. a bare "*"
+            rows = []
+        if not rows:
+            rows = self.db.execute(
+                "SELECT *, 0 AS score FROM node WHERE name LIKE ?"
+                + (" AND kind = ?" if kind else " AND kind != 'Folder'")
+                + " ORDER BY length(name) LIMIT ?",
+                [f"%{query}%"] + ([kind] if kind else []) + [limit],
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    @staticmethod
+    def _slim(row) -> dict:
+        """List entries carry only what an agent needs to act: what, where, how sure.
+        Full records are reserved for the symbol actually asked about."""
+        out = {k: row[k] for k in ("kind", "qname", "path", "line") if k in row.keys()}
+        conf = row["confidence"] if "confidence" in row.keys() else None
+        if conf is not None and conf < 1.0:
+            out["confidence"] = round(conf, 2)
+        if "depth" in row.keys():
+            out["depth"] = row["depth"]
+        return out
+
+    def edges_of(self, node_id: int, kind: str, direction: str) -> list[dict]:
+        col, other = ("src", "dst") if direction == "out" else ("dst", "src")
+        return [
+            self._slim(r)
+            for r in self.db.execute(
+                f"SELECT n.*, e.confidence, e.line AS at_line FROM edge e"
+                f" JOIN node n ON n.id = e.{other}"
+                f" WHERE e.{col} = ? AND e.kind = ? ORDER BY e.confidence DESC LIMIT 200",
+                (node_id, kind),
+            )
+        ]
+
+    def context(self, ref: str) -> dict:
+        """Everything about one symbol: where it lives, who calls it, what it calls."""
+        matches = self.resolve(ref)
+        if not matches:
+            return {"error": f"no symbol matching {ref!r}", "suggestions": self.search(ref, 5)}
+        n = matches[0]
+        nid = n["id"]
+        parent = self.db.execute(
+            "SELECT n.* FROM edge e JOIN node n ON n.id = e.src WHERE e.dst = ? AND e.kind = 'DEFINES'", (nid,)
+        ).fetchone()
+        return {
+            "symbol": dict(n),
+            "defined_in": self._slim(parent) if parent else None,
+            "members": self.edges_of(nid, "DEFINES", "out"),
+            "callers": self.edges_of(nid, "CALLS", "in"),
+            "calls": self.edges_of(nid, "CALLS", "out"),
+            "extends": self.edges_of(nid, "EXTENDS", "out"),
+            "extended_by": self.edges_of(nid, "EXTENDS", "in"),
+            "ambiguous_with": [self._slim(m) for m in matches[1:6]],
+        }
+
+    def impact(self, ref: str, depth: int = 3, min_confidence: float = 0.3, per_depth: int = 40) -> dict:
+        """Blast radius: everything that transitively reaches this symbol, by depth."""
+        matches = self.resolve(ref)
+        if not matches:
+            return {"error": f"no symbol matching {ref!r}", "suggestions": self.search(ref, 5)}
+        nid = matches[0]["id"]
+        rows = self.db.execute(
+            """
+            WITH RECURSIVE up(id, d, conf) AS (
+                SELECT ?, 0, 1.0
+                UNION
+                SELECT e.src, up.d + 1, min(up.conf, e.confidence)
+                FROM edge e JOIN up ON e.dst = up.id
+                WHERE e.kind IN ('CALLS','EXTENDS') AND up.d < ? AND e.confidence >= ?
+            )
+            SELECT n.*, min(up.d) AS depth, max(up.conf) AS confidence
+            FROM up JOIN node n ON n.id = up.id
+            WHERE up.d > 0 GROUP BY n.id ORDER BY depth, confidence DESC LIMIT 500
+            """,
+            (nid, depth, min_confidence),
+        ).fetchall()
+        by_depth: dict[int, list] = {}
+        for r in rows:
+            by_depth.setdefault(r["depth"], []).append(self._slim(r))
+        files = sorted({r["path"] for r in rows if r["path"]})
+        out = {
+            "target": dict(matches[0]),
+            "total": len(rows),
+            "by_depth": {d: v[:per_depth] for d, v in by_depth.items()},
+            "files_affected": files,
+        }
+        dropped = {d: len(v) - per_depth for d, v in by_depth.items() if len(v) > per_depth}
+        if dropped:  # never truncate silently: an agent must know the list is partial
+            out["truncated"] = {
+                "hidden_per_depth": dropped,
+                "hint": "raise per_depth, raise min_confidence, or query `edge` directly for the rest",
+            }
+        return out
+
+    def trace(self, src: str, dst: str, max_depth: int = 8, min_confidence: float = 0.5) -> dict:
+        """Shortest directed path between two symbols. A bare name that matches several
+        symbols is searched from/to all of them, so `trace execute save` finds the one
+        `execute` that actually reaches `save`."""
+        a, b = self.resolve(src), self.resolve(dst)
+        if not a or not b:
+            missing = src if not a else dst
+            return {"error": f"unresolved: {missing!r}", "suggestions": self.search(missing, 5)}
+        starts = [r["id"] for r in a[:10]]
+        ends = [r["id"] for r in b[:10]]
+        kinds = ",".join(f"'{k}'" for k in TRAVERSABLE)
+        row = self.db.execute(
+            f"""
+            WITH RECURSIVE p(id, path, d) AS (
+                SELECT id, '>' || id || '>', 0 FROM node WHERE id IN ({",".join("?" * len(starts))})
+                UNION ALL
+                SELECT e.dst, p.path || e.dst || '>', p.d + 1
+                FROM edge e JOIN p ON e.src = p.id
+                WHERE p.d < ? AND e.kind IN ({kinds}) AND e.confidence >= ?
+                  AND instr(p.path, '>' || e.dst || '>') = 0
+            )
+            SELECT path, d FROM p WHERE id IN ({",".join("?" * len(ends))}) ORDER BY d LIMIT 1
+            """,
+            (*starts, max_depth, min_confidence, *ends),
+        ).fetchone()
+        if row is None:
+            return {"found": False, "from": dict(a[0]), "to": dict(b[0])}
+        ids = [int(x) for x in row["path"].strip(">").split(">")]
+        placeholders = ",".join("?" * len(ids))
+        nodes = {
+            r["id"]: self._slim(r) for r in self.db.execute(f"SELECT * FROM node WHERE id IN ({placeholders})", ids)
+        }
+        return {"found": True, "length": row["d"], "path": [nodes[i] for i in ids]}
+
+    def stats(self) -> dict:
+        nodes = {r["kind"]: r["n"] for r in self.db.execute("SELECT kind, count(*) n FROM node GROUP BY kind")}
+        edges = {r["kind"]: r["n"] for r in self.db.execute("SELECT kind, count(*) n FROM edge GROUP BY kind")}
+        langs = {
+            r["lang"]: r["n"]
+            for r in self.db.execute(
+                "SELECT lang, count(*) n FROM node WHERE lang IS NOT NULL AND kind='File' GROUP BY lang ORDER BY n DESC"
+            )
+        }
+        return {"nodes": nodes, "edges": edges, "languages": langs, **self.meta()}
+
+    def query(self, sql: str, limit: int = 100) -> list[dict]:
+        """Read-only escape hatch. The schema is small enough to query directly."""
+        stripped = sql.lstrip().lower()
+        if not (stripped.startswith("select") or stripped.startswith("with")):
+            raise ValueError("only SELECT / WITH queries are allowed")
+        if ";" in sql.rstrip().rstrip(";"):
+            raise ValueError("only a single statement is allowed")
+        return [dict(r) for r in self.db.execute(sql).fetchmany(limit)]