heimdall-code 0.1.0__tar.gz → 0.2.0__tar.gz

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "heimdall",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A code knowledge graph that sees everything. Indexes any repo into a SQLite property graph and answers what calls this, what breaks if I change it, and how does A reach B.",
   "author": {
     "name": "Bogdan Sapovskyi",

heimdall_code-0.2.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+Notable changes, newest first. Versions follow [semver](https://semver.org); until 1.0
+the graph schema and the JSON payloads may still move.
+
+## 0.2.0 — 2026-08-01
+
+### Added
+
+- **Constants are symbols.** A `SCREAMING_SNAKE` module- or class-level binding is indexed
+  as a new node kind, `Constant`, and reading one is an edge. Endpoint tables, thresholds
+  and feature flags were previously not in the graph at all, so `impact SOME_THRESHOLD`
+  answered nothing and the question had to go back to `rg`.
+- **A function handed over rather than called** is an edge too — `register(on_save)`,
+  `key=parse`, `@decorator`, a class named as a receiver. On Django the oracle finds
+  12,000 such sites; recall went from 8.4% / 4.8% (local / imported) to 97.8% / 96.9%,
+  where GitNexus scores 1.9% / 0.1% and graphify 13.8% / 5.3%. Constant reads score
+  100.0% / 100.0%; neither other tool models them at all.
+- Both are `CALLS` edges, on the same argument the decorator edge already made: they break
+  the same way when the target changes. They differ from a call in the fallback — an
+  unresolvable *call* is emitted as up to five `0.3` candidates, an unresolvable
+  *reference* is dropped, because a bare name with no evidence behind it is almost always
+  a local variable. Django's `0.3` edge count came out *below* what it was before the
+  feature, and the referee still refutes 0 of 204,713 checkable edges.
+- The cost: Django indexes in 2.7 s instead of 1.7 s and the graph is 78 MB instead of 48.
+  `bench/RESULTS.md`, `bench/QUESTIONS.md` and the README tables are regenerated against
+  all three tools rather than edited.
+
+- **Terraform**, as the 19th language and the first one the generic walker could not
+  reach: `.tf` and `.hcl` are read by `_parse_hcl`, which indexes a block under the
+  address the rest of the configuration names it by (`resource "aws_instance" "web"` ->
+  `aws_instance.web`, `variable "region"` -> `var.region`) and turns every reference to
+  one into a `CALLS` edge. Scoping is Terraform's: a directory is a module, and a `module`
+  block's arguments resolve to the `variable` blocks in the directory its `source` names.
+- `bench/terraform.py`, graded by a regex oracle that shares no code with the reader.
+  Across three public repos — 432 HCL files, 5,104 blocks, 10,206 edges — one reference
+  of 2,828 goes unresolved and none of the edges is wrong.
+
+### Fixed
+
+- A name being *introduced* is no longer read as a reference to something else: a
+  parameter, a `*args` splat, a loop variable, a destructuring pattern and a keyword
+  argument's name all bind rather than read. Found by the referee, which refuted exactly
+  one edge — `def handle(self, *labels)` pointing at an unrelated `labels` method.
+- A relative import with more than one `..` (`from '../../store'`) resolved to nothing:
+  the dots after the first were read as module separators, which is right for
+  `..pkg.mod` and wrong for a path. Every such import in every JS/TS repo was silently
+  missing its edge.
+
+## 0.1.1 — 2026-08-01
+
+- `heimdall --version`.
+- Works on Python 3.12 again: `os.process_cpu_count()` is 3.13+, so every index crashed
+  on the version the package declares as its floor. The release workflow now runs the
+  suite on 3.12 rather than on whatever the runner image ships.
+- `install` no longer treats a heimdall in the default uv cache as durable when
+  `UV_CACHE_DIR` points elsewhere — that config would have rotted at the next `uv cache
+  prune`.
+
+## 0.1.0 — 2026-08-01
+
+First release.
+
+### Added
+
+- **Index.** `heimdall index` builds `.heimdall/graph.db` in four passes — discover
+  (`git ls-files`, submodules included), parse (tree-sitter, one process per core),
+  resolve, FTS5. 1.7 s and 48 MB for Django's 2,927 files.
+- **Query.** `search`, `context`, `impact`, `trace`, `stats`, `projects` and a read-only
+  `sql` escape hatch over a two-table schema. Every command takes `--json` and
+  `-p/--project`.
+- **18 languages**, declared as data in `parse.py` and each covered by a test that fails
+  if a grammar renames a node type.
+- **MCP server** (`heimdall mcp`): one process serves every repo in
+  `~/.heimdall/registry.json`, eight tools returning assembled answers rather than raw
+  edges.
+- **`heimdall install [claude|codex|all]`** — writes `~/.claude.json`, `./.mcp.json`,
+  `~/.codex/config.toml` or `./.codex/config.toml`, merging around your existing
+  settings; `--cli` installs the skill instead of the server.
+- **Claude Code plugin**: `/plugin marketplace add stPhoenix/heimdall`.
+- **Benchmark** (`bench/`) against GitNexus and graphify, graded by a CPython `ast`
+  oracle.
+
+### Resolution fixes found by the benchmark
+
+Each of these was a wrong answer before it was a test:
+
+- Imports resolve per scope, so a function with its own `from x import y` is no longer
+  matched against the whole file.
+- `pkg/main.py` is reachable as `pkg.main`, not only as `pkg`.
+- `as` renames are followed home — but only for in-repo targets, so
+  `from asyncio import run as arun` cannot bind to your own `run`.
+- A decorator is a call by the function it wraps, not by the enclosing class. Worth 26%
+  of imported-call recall on Django.
+- Recursion produces an edge.
+- A class name used as a receiver resolves inside that class — including when several
+  classes share the name, because the one that defines the member is the one that was
+  meant. Took *who calls `Model.check`* from 0% to 94% precision.

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/CONTRIBUTING.md

@@ -18,7 +18,7 @@ There is no CI. The gate is `uv run pytest && uv run ruff check .` before you pu
 
 | | |
 |---|---|
-| `heimdall/parse.py` | tree-sitter → symbols, calls, imports, heritage. Language support is **data** (`EXT_LANG`, `DEFS`, `CALL_NODES`, `IMPORT_NODES`, `HERITAGE_*`), walked by one generic function. |
+| `heimdall/parse.py` | tree-sitter → symbols, calls, imports, heritage. Language support is **data** (`EXT_LANG`, `DEFS`, `CALL_NODES`, `IMPORT_NODES`, `CONST_NODES`, `HERITAGE_*`), walked by one generic function. |
 | `heimdall/index.py` | the four passes: discover → parse (process pool) → resolve → store. Everything a query needs is precomputed here. |
 | `heimdall/graph.py` | schema + reads. Two tables, recursive CTEs, FTS5. `query()` is the read-only SQL gate. |
 | `heimdall/cli.py` | argparse; every command takes `--json` and `-p/--project`. |
@@ -29,11 +29,19 @@ There is no CI. The gate is `uv run pytest && uv run ruff check .` before you pu
 
 ## Adding a language
 
-Rows in three dicts in `parse.py` — definition node types, call node types, import node
-types — plus a snippet in `SNIPPETS` in `tests/test_heimdall.py`. No new module. The test
+Rows in four dicts in `parse.py` — definition node types, call node types, import node
+types, and the node types that bind a name (which is how constants are found) — plus a
+snippet in `SNIPPETS` in `tests/test_heimdall.py`. No new module. The test
 asserts the snippet still yields symbols *and* call edges, so a grammar renaming a node
 type fails the build instead of quietly emptying the graph.
 
+HCL is the one language that did not fit, and it is worth reading before deciding yours
+does not either: it has no definition nodes and no call nodes, so no set of rows could
+express it. It gets `_parse_hcl`, a reader beside the walker rather than a branch inside
+it, and its own three tables of Terraform addressing rules. That is the shape to copy if
+a language genuinely needs it — and the bar is "the grammar has nothing the walker is
+looking for", not "the walker gets a few nodes wrong".
+
 ## Tests
 
 One file, `tests/test_heimdall.py`, runnable with or without pytest. Every resolution bug
@@ -48,6 +56,10 @@ resolution bug, add the smallest fixture that would have caught it.
 (it wants Node, npm and a clone of Django), but it is what a change to resolution should
 be measured with: `python bench/compare.py /path/to/django` and `python bench/questions.py`.
 
+`bench/terraform.py` does the same for HCL against a regex oracle — no other tool to
+compare against, so it only grades Heimdall's own edges: `python bench/terraform.py
+/path/to/some-terraform-repo`.
+
 ## Release
 
 Bump `version` in `pyproject.toml`, `__version__` in `heimdall/__init__.py` and `version`

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: heimdall-code
-Version: 0.1.0
+Version: 0.2.0
 Summary: A code knowledge graph that sees everything -- indexes any repository into a SQLite property graph and serves it to AI agents over MCP.
 Project-URL: Homepage, https://github.com/stPhoenix/heimdall
 Project-URL: Source, https://github.com/stPhoenix/heimdall
@@ -36,10 +36,10 @@ pass 1/4  discovering files
 pass 2/4  parsing (24 workers)
 pass 3/4  building graph
 pass 4/4  building search index
-done in 1.49s          # 43,482 symbols, 353,101 edges
+done in 2.42s          # 45,515 symbols, 418,925 edges
 
 $ heimdall impact django/shortcuts.py:get_object_or_404 -d 2 -c 0.7
-impact of django/shortcuts.py:get_object_or_404: 6 symbols, 4 files
+impact of django/shortcuts.py:get_object_or_404: 10 symbols, 8 files
 
 depth 1 (5):
   Function   django/contrib/flatpages/views.py:flatpage (0.80)
@@ -53,7 +53,7 @@ path of length 2:
       -> django/http/response.py:HttpResponse
 ```
 
-A second and a half, cold, for the whole of Django on a laptop.
+Two and a half seconds, cold, for the whole of Django on a laptop.
 
 ## Why
 
@@ -89,16 +89,18 @@ against [graphify](https://pypi.org/project/graphifyy/) in its AST-only mode:
 |---|---|---|---|
 | `self.m()` bound correctly | 100.0% | 97.1% | 92.6% |
 | same-file call bound correctly | 100.0% | 93.4% | 89.3% |
-| imported call bound correctly | 99.7% | 71.5% | 75.4% |
+| imported call bound correctly | 99.7% | 71.4% | 75.3% |
 | class instantiation, same file / imported | 99.5% / 98.8% | not modelled | 95.2% / 98.2% |
+| constant read, same file / imported | 100.0% / 100.0% | not modelled | not modelled |
+| function passed as a value, same file / imported | 97.8% / 96.9% | 1.9% / 0.1% | 13.8% / 5.3% |
 | mean targets emitted per call | 1.00–1.06 | 1.00 | 1.00 |
-| edges the referee can refute outright | **0** of 157,036 | 0 of 23,736 | 202 of 30,882 |
-| live symbols wrongly shown as uncalled | **1** (0.0%) | 1,373 (29.4%) | 205 (4.4%) |
+| edges the referee can refute outright | **0** of 204,713 | 0 of 23,736 | 202 of 30,882 |
+| live symbols wrongly shown as uncalled | **1** (0.0%) | 3,635 (52.3%) | 2,381 (34.2%) |
 | hand-written edge cases missed or fabricated | **1** of 13 | 4 of 13 | 3 of 13 |
 | *who calls `Model.check`*, precision | 94% | 0% | 95% |
-| index from scratch | **1.7 s** | 23.0 s | 28.8 s |
-| index on disk | **48 MB** | 642 MB | 151 MB |
-| `impact X` from cold | **56 ms** | 949 ms | 856 ms |
+| index from scratch | **2.7 s** | 23.6 s | 29.8 s |
+| index on disk | **78 MB** | 730 MB | 151 MB |
+| `impact X` from cold | **58 ms** | 969 ms | 837 ms |
 
 Six of those Heimdall numbers only got there because the benchmark existed. It found that
 imports were resolved file-wide rather than per-scope, that a Python `pkg/main.py`
@@ -216,10 +218,18 @@ Four passes, all precomputed at index time so a query is one SQL statement:
 Receivers are used wherever they carry information: `self.foo()` resolves inside the
 enclosing class, `utils.foo()` inside the file imported as `utils`, and `Model.foo()`
 inside the class `Model` — including when *several* classes are called `Model`, because
-the one that defines `foo` is the one that was meant. On Django that leaves 46,260 of
-286,346 call edges resolved by name alone — and every one of them is labelled
+the one that defines `foo` is the one that was meant. On Django that leaves 46,277 of
+350,104 call edges resolved by name alone — and every one of them is labelled
 `confidence = 0.3`.
 
+A `CALLS` edge covers every way one symbol depends on another by name, not only
+invocation: reading a constant, handing a function over as a value (`register(on_save)`,
+`key=parse`), naming a class as a receiver, and a decorator. All of those break the same
+way when the target changes, which is the question `impact` answers. Where they differ is
+the fallback: an unresolvable *call* is emitted as up to five `0.3` candidates, while an
+unresolvable *reference* is dropped entirely — a bare name with nothing behind it is
+almost always a local variable, and guessing five ways at a local variable is noise.
+
 ### Schema
 
 ```sql
@@ -227,7 +237,7 @@ node(id, kind, name, qname, path, line, end_line, lang, signature)
 edge(src, dst, kind, confidence, line)
 ```
 
-`kind` on nodes: `Folder`, `File`, `Class`, `Interface`, `Function`, `Method`.
+`kind` on nodes: `Folder`, `File`, `Class`, `Interface`, `Function`, `Method`, `Constant`.
 `kind` on edges: `CONTAINS`, `DEFINES`, `IMPORTS`, `CALLS`, `EXTENDS`.
 
 That is the whole data model — `heimdall sql` gives you direct access to it.
@@ -235,17 +245,43 @@ That is the whole data model — `heimdall sql` gives you direct access to it.
 ## Languages
 
 Python, JavaScript, TypeScript, TSX, Go, Rust, Java, Kotlin, C#, Ruby, PHP, C, C++,
-Swift, Scala, Lua, Dart, Bash. Every one of them is covered by a test that asserts it
-still yields symbols and call edges, so a grammar rename fails the build rather than
-silently degrading the graph.
+Swift, Scala, Lua, Dart, Bash, Terraform. Every one of them is covered by a test that
+asserts it still yields symbols and call edges, so a grammar rename fails the build
+rather than silently degrading the graph.
 
-Adding a language means adding rows to three dicts in `heimdall/parse.py` — node types
-for definitions, for calls, and for imports — plus a snippet in the test.
+Adding a language means adding rows to four dicts in `heimdall/parse.py` — node types
+for definitions, for calls, for imports and for name bindings — plus a snippet in the test.
 
 One known gap: in Ruby, a receiver-less call without parentheses (`foo`) is
 indistinguishable from a variable reference in the grammar, so only `foo()` and
 `x.foo` produce call edges.
 
+### Terraform
+
+`.tf` and `.hcl` are read differently, because HCL has no definitions and no calls. A
+block is indexed under the address the rest of the configuration refers to it by —
+`resource "aws_instance" "web"` becomes `aws_instance.web`, `variable "region"` becomes
+`var.region`, and each `locals` attribute its own `local.x` — and every reference to one
+of those addresses becomes a `CALLS` edge. The scope is Terraform's own: a directory of
+`.tf` files is one module, and a `module` block's arguments resolve to the `variable`
+blocks in the directory its `source` points at, which is what makes *what breaks if I
+rename this module input* answerable.
+
+```console
+heimdall context aws_instance.web    # what it reads, and who reads it
+heimdall impact var.region           # everything downstream of one variable
+```
+
+Blocks are stored under the existing `Class` kind rather than a new one — the schema's
+six kinds are the same six for every language, and `Class` is already where Go's
+`type_spec` and C's `struct` live.
+
+Scored against a regex oracle on three public repos — 432 HCL files, 5,104 blocks, 10,206
+edges — one reference of 2,828 goes unresolved and none of the edges is wrong; see
+[bench/README.md](bench/README.md).
+Packer and Nomad `.hcl` parse with the same grammar and get symbols, but only Terraform's
+addressing rules are modelled.
+
 ## Limitations
 
 Call resolution is name-based, not type-based. `self.x()` and `module.x()` resolve

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/README.md

@@ -16,10 +16,10 @@ pass 1/4  discovering files
 pass 2/4  parsing (24 workers)
 pass 3/4  building graph
 pass 4/4  building search index
-done in 1.49s          # 43,482 symbols, 353,101 edges
+done in 2.42s          # 45,515 symbols, 418,925 edges
 
 $ heimdall impact django/shortcuts.py:get_object_or_404 -d 2 -c 0.7
-impact of django/shortcuts.py:get_object_or_404: 6 symbols, 4 files
+impact of django/shortcuts.py:get_object_or_404: 10 symbols, 8 files
 
 depth 1 (5):
   Function   django/contrib/flatpages/views.py:flatpage (0.80)
@@ -33,7 +33,7 @@ path of length 2:
       -> django/http/response.py:HttpResponse
 ```
 
-A second and a half, cold, for the whole of Django on a laptop.
+Two and a half seconds, cold, for the whole of Django on a laptop.
 
 ## Why
 
@@ -69,16 +69,18 @@ against [graphify](https://pypi.org/project/graphifyy/) in its AST-only mode:
 |---|---|---|---|
 | `self.m()` bound correctly | 100.0% | 97.1% | 92.6% |
 | same-file call bound correctly | 100.0% | 93.4% | 89.3% |
-| imported call bound correctly | 99.7% | 71.5% | 75.4% |
+| imported call bound correctly | 99.7% | 71.4% | 75.3% |
 | class instantiation, same file / imported | 99.5% / 98.8% | not modelled | 95.2% / 98.2% |
+| constant read, same file / imported | 100.0% / 100.0% | not modelled | not modelled |
+| function passed as a value, same file / imported | 97.8% / 96.9% | 1.9% / 0.1% | 13.8% / 5.3% |
 | mean targets emitted per call | 1.00–1.06 | 1.00 | 1.00 |
-| edges the referee can refute outright | **0** of 157,036 | 0 of 23,736 | 202 of 30,882 |
-| live symbols wrongly shown as uncalled | **1** (0.0%) | 1,373 (29.4%) | 205 (4.4%) |
+| edges the referee can refute outright | **0** of 204,713 | 0 of 23,736 | 202 of 30,882 |
+| live symbols wrongly shown as uncalled | **1** (0.0%) | 3,635 (52.3%) | 2,381 (34.2%) |
 | hand-written edge cases missed or fabricated | **1** of 13 | 4 of 13 | 3 of 13 |
 | *who calls `Model.check`*, precision | 94% | 0% | 95% |
-| index from scratch | **1.7 s** | 23.0 s | 28.8 s |
-| index on disk | **48 MB** | 642 MB | 151 MB |
-| `impact X` from cold | **56 ms** | 949 ms | 856 ms |
+| index from scratch | **2.7 s** | 23.6 s | 29.8 s |
+| index on disk | **78 MB** | 730 MB | 151 MB |
+| `impact X` from cold | **58 ms** | 969 ms | 837 ms |
 
 Six of those Heimdall numbers only got there because the benchmark existed. It found that
 imports were resolved file-wide rather than per-scope, that a Python `pkg/main.py`
@@ -196,10 +198,18 @@ Four passes, all precomputed at index time so a query is one SQL statement:
 Receivers are used wherever they carry information: `self.foo()` resolves inside the
 enclosing class, `utils.foo()` inside the file imported as `utils`, and `Model.foo()`
 inside the class `Model` — including when *several* classes are called `Model`, because
-the one that defines `foo` is the one that was meant. On Django that leaves 46,260 of
-286,346 call edges resolved by name alone — and every one of them is labelled
+the one that defines `foo` is the one that was meant. On Django that leaves 46,277 of
+350,104 call edges resolved by name alone — and every one of them is labelled
 `confidence = 0.3`.
 
+A `CALLS` edge covers every way one symbol depends on another by name, not only
+invocation: reading a constant, handing a function over as a value (`register(on_save)`,
+`key=parse`), naming a class as a receiver, and a decorator. All of those break the same
+way when the target changes, which is the question `impact` answers. Where they differ is
+the fallback: an unresolvable *call* is emitted as up to five `0.3` candidates, while an
+unresolvable *reference* is dropped entirely — a bare name with nothing behind it is
+almost always a local variable, and guessing five ways at a local variable is noise.
+
 ### Schema
 
 ```sql
@@ -207,7 +217,7 @@ node(id, kind, name, qname, path, line, end_line, lang, signature)
 edge(src, dst, kind, confidence, line)
 ```
 
-`kind` on nodes: `Folder`, `File`, `Class`, `Interface`, `Function`, `Method`.
+`kind` on nodes: `Folder`, `File`, `Class`, `Interface`, `Function`, `Method`, `Constant`.
 `kind` on edges: `CONTAINS`, `DEFINES`, `IMPORTS`, `CALLS`, `EXTENDS`.
 
 That is the whole data model — `heimdall sql` gives you direct access to it.
@@ -215,17 +225,43 @@ That is the whole data model — `heimdall sql` gives you direct access to it.
 ## Languages
 
 Python, JavaScript, TypeScript, TSX, Go, Rust, Java, Kotlin, C#, Ruby, PHP, C, C++,
-Swift, Scala, Lua, Dart, Bash. Every one of them is covered by a test that asserts it
-still yields symbols and call edges, so a grammar rename fails the build rather than
-silently degrading the graph.
+Swift, Scala, Lua, Dart, Bash, Terraform. Every one of them is covered by a test that
+asserts it still yields symbols and call edges, so a grammar rename fails the build
+rather than silently degrading the graph.
 
-Adding a language means adding rows to three dicts in `heimdall/parse.py` — node types
-for definitions, for calls, and for imports — plus a snippet in the test.
+Adding a language means adding rows to four dicts in `heimdall/parse.py` — node types
+for definitions, for calls, for imports and for name bindings — plus a snippet in the test.
 
 One known gap: in Ruby, a receiver-less call without parentheses (`foo`) is
 indistinguishable from a variable reference in the grammar, so only `foo()` and
 `x.foo` produce call edges.
 
+### Terraform
+
+`.tf` and `.hcl` are read differently, because HCL has no definitions and no calls. A
+block is indexed under the address the rest of the configuration refers to it by —
+`resource "aws_instance" "web"` becomes `aws_instance.web`, `variable "region"` becomes
+`var.region`, and each `locals` attribute its own `local.x` — and every reference to one
+of those addresses becomes a `CALLS` edge. The scope is Terraform's own: a directory of
+`.tf` files is one module, and a `module` block's arguments resolve to the `variable`
+blocks in the directory its `source` points at, which is what makes *what breaks if I
+rename this module input* answerable.
+
+```console
+heimdall context aws_instance.web    # what it reads, and who reads it
+heimdall impact var.region           # everything downstream of one variable
+```
+
+Blocks are stored under the existing `Class` kind rather than a new one — the schema's
+six kinds are the same six for every language, and `Class` is already where Go's
+`type_spec` and C's `struct` live.
+
+Scored against a regex oracle on three public repos — 432 HCL files, 5,104 blocks, 10,206
+edges — one reference of 2,828 goes unresolved and none of the edges is wrong; see
+[bench/README.md](bench/README.md).
+Packer and Nomad `.hcl` parse with the same grammar and get symbols, but only Terraform's
+addressing rules are modelled.
+
 ## Limitations
 
 Call resolution is name-based, not type-based. `self.x()` and `module.x()` resolve

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/bench/QUESTIONS.md

@@ -45,7 +45,7 @@ The *who writes into this table* question: a method name that several classes sh
 
 | | callers of the right one | callers of anything named `check` |
 |---|---|---|
-| Heimdall | 100% recall, 94% precision (109 returned) | 100% recall, 23% precision (442 returned) |
+| Heimdall | 100% recall, 94% precision (110 returned) | 100% recall, 23% precision (453 returned) |
 | GitNexus | 0% recall, 0% precision (7 returned) | 0% recall, 0% precision (42 returned) |
 | graphify | 99% recall, 95% precision (107 returned) | 99% recall, 61% precision (168 returned) |
 | graphify `+uses` | 99% recall, 95% precision (107 returned) | 99% recall, 61% precision (168 returned) |
@@ -58,11 +58,11 @@ Blast radius at depth 3 for the five most-called symbols the oracle is sure abou
 
 | target | truth | Heimdall | GitNexus | graphify | graphify `+uses` |
 |---|---|---|---|---|---|
-| `utils.py:setup` | 912 | 100% of truth, 971 total | 0% of truth, 103 total | 0% of truth, 59 total | 0% of truth, 59 total |
-| `utils.py:override_settings` | 200 | 100% of truth, 1,792 total | 0% of truth, 0 total | 100% of truth, 1,549 total | 100% of truth, 1,623 total |
-| `safestring.py:mark_safe` | 338 | 100% of truth, 11,830 total | 100% of truth, 430 total | 97% of truth, 482 total | 97% of truth, 482 total |
-| `utils.py:isolate_apps` | 132 | 100% of truth, 201 total | 0% of truth, 0 total | 100% of truth, 201 total | 100% of truth, 201 total |
-| `utils.py:CaptureQueriesContext` | 91 | 100% of truth, 91 total | 0% of truth, 0 total | 99% of truth, 90 total | 99% of truth, 90 total |
+| `utils.py:setup` | 912 | 100% of truth, 982 total | 0% of truth, 103 total | 0% of truth, 59 total | 0% of truth, 59 total |
+| `exceptions.py:ValidationError` | 393 | 100% of truth, 1,503 total | 0% of truth, 0 total | 29% of truth, 122 total | 29% of truth, 122 total |
+| `models.py:User` | 322 | 99% of truth, 2,527 total | 0% of truth, 0 total | 6% of truth, 20 total | 6% of truth, 20 total |
+| `functional.py:cached_property` | 298 | 100% of truth, 14,504 total | 0% of truth, 0 total | 1% of truth, 3 total | 9% of truth, 7,545 total |
+| `exceptions.py:ImproperlyConfigured` | 473 | 100% of truth, 9,413 total | 0% of truth, 0 total | 75% of truth, 444 total | 75% of truth, 444 total |
 
 ### Is any of this made up?
 
@@ -70,19 +70,19 @@ An edge `f -> g` is refuted when neither `g` nor anything imported *as* `g` occu
 
 | | refuted edges |
 |---|---|
-| Heimdall | 0 of 157,036 checkable (0.00%) |
+| Heimdall | 0 of 204,713 checkable (0.00%) |
 | GitNexus | 0 of 23,736 checkable (0.00%) |
 | graphify | 202 of 30,882 checkable (0.65%) |
 | graphify `+uses` | 48,856 of 84,172 checkable (58.04%) |
 
 ### Would it tell me live code is dead?
 
-4,668 symbols the oracle proves are called. A tool that reports no callers for one of them would send an agent to delete live code.
+6,952 symbols the oracle proves are called. A tool that reports no callers for one of them would send an agent to delete live code.
 
 | | symbols wrongly shown as uncalled |
 |---|---|
 | Heimdall | 1 (0.0%) |
-| GitNexus | 1,373 (29.4%) |
-| graphify | 205 (4.4%) |
-| graphify `+uses` | 199 (4.3%) |
+| GitNexus | 3,635 (52.3%) |
+| graphify | 2,381 (34.2%) |
+| graphify `+uses` | 1,134 (16.3%) |
 

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/bench/README.md

@@ -8,6 +8,7 @@ Two runners, because they measure different things:
 |---|---|---|
 | `compare.py` | are the *edges* right, and what do they cost? | [RESULTS.md](RESULTS.md) |
 | `questions.py` | is the *answer* right? | [QUESTIONS.md](QUESTIONS.md) |
+| `terraform.py` | the same question for HCL, where the oracle is a regex | stdout |
 
 The repository is [Django](https://github.com/django/django) — 2,927 Python files, deep
 inheritance, decorators everywhere, and `tests/` full of same-named methods, which is the
@@ -67,6 +68,13 @@ sites where the language leaves no room for interpretation:
 | `self.m()` inside class `C` | `C` defines `m` — a receiver of `self` cannot mean another class |
 | `m()` where `m` is defined once at module level | one definition in scope, nothing shadowing it |
 | `m()` where `m` came from `from <mod> import m` | the binding names the module, and the module is a file in this repo |
+| `m` *read* rather than called, same two rules | a constant or a function passed as a value is bound exactly as a call is |
+
+A name read rather than called is scored separately from a call, and split again by what
+it turned out to name: a `SCREAMING_SNAKE` module-level binding is a constant, anything
+else that resolves to a definition is a function or class handed over as a value. Base
+classes are excluded — `class A(B)` is an `EXTENDS` edge, and this runner only loads
+`CALLS`, so counting them would score a question it never asked.
 
 Class instantiation (`Thing()`) is scored separately from function calls, because it is a
 call in Python but not every tool models it as a `CALLS` edge — folding the two together
@@ -88,11 +96,13 @@ qualified-name convention, so neither tool's naming scheme wins by default.
 
 | # | Question | Metric |
 |---|---|---|
-| 1 | Does `self.m()` bind to the enclosing class? | recall over 5,389 sites |
+| 1 | Does `self.m()` bind to the enclosing class? | recall over 5,391 sites |
 | 2 | Does a same-file call bind to the right function? | recall over 1,255 sites |
 | 3 | Does a same-file class instantiation produce an edge? | recall over 943 sites |
-| 4 | Does an imported call bind to the right file? | recall over 4,238 sites |
+| 4 | Does an imported call bind to the right file? | recall over 4,242 sites |
 | 5 | Does an imported class instantiation produce an edge? | recall over 4,299 sites |
+| 5a | Is a constant read an edge, same file / imported? | recall over 765 / 659 sites |
+| 5b | Is a function *passed* rather than called an edge? | recall over 1,196 / 10,779 sites |
 | 6 | How many candidates does the answer arrive buried in? | mean fan-out per resolved site |
 | 7 | Who reaches these 5 hot symbols within 3 call hops? | set size, overlap, wall time |
 | 8 | Does clustering beat the directory tree? | Newman modularity, shared subgraph |
@@ -107,6 +117,43 @@ Case 9 is run twice — once on Heimdall's call graph and once on GitNexus's —
 label propagation is fitted on the graph it is then scored on, and Leiden is not. The
 second table is the one where Leiden has home advantage.
 
+## Terraform (`terraform.py`)
+
+No competitor here — neither of the other two reads HCL — so this one only asks whether
+Heimdall's own edges are right. The oracle is a regular expression, chosen precisely
+because it shares no code with the tree-sitter reader it grades.
+
+```console
+git clone --depth 1 https://github.com/terraform-aws-modules/terraform-aws-eks
+git clone --depth 1 https://github.com/terraform-aws-modules/terraform-aws-vpc
+git clone --depth 1 https://github.com/terraform-google-modules/terraform-example-foundation
+python bench/terraform.py terraform-aws-eks terraform-aws-vpc terraform-example-foundation
+```
+
+| repo | files | blocks | refs | edges | recall | precision | mean confidence |
+|---|---|---|---|---|---|---|---|
+| terraform-aws-eks | 90 | 1,363 | 950 | 2,989 | 100.0% | 100.0% | 0.87 |
+| terraform-aws-vpc | 77 | 1,872 | 472 | 3,461 | 99.8% | 100.0% | 0.84 |
+| terraform-example-foundation | 265 | 1,869 | 1,406 | 3,756 | 100.0% | 100.0% | 0.85 |
+| **total** | **432** | **5,104** | **2,828** | **10,206** | **100.0%** | **100.0%** | |
+
+*recall* — a `var.X` / `local.X` / `module.X` / `data.T.N` written in a directory where
+exactly one file declares that block must produce an edge to that file. *precision* — an
+edge is endorsed only if its target really declares that address and the target is either
+a sibling of the source or the directory a `module` block points `source` at.
+
+The one row that falls short is worth keeping: the missing reference is `var.azs` quoted
+inside a `description` string in terraform-aws-vpc, where the oracle cannot tell prose
+from code and Heimdall is right not to link it. Precision was 99.8% until references
+stopped being guessed at — the 17 wrong edges were all in terraform-aws-eks's
+`modules/karpenter/migrations.tf`, which names resources declared in no directory the
+oracle can reach, and all 17 were name-only matches that are now dropped rather than
+emitted at `confidence = 0.3`.
+
+Bare resource references (`aws_s3_bucket.logs.arn`) are excluded from the recall claim —
+no regex can tell one from an attribute lookup on something else — but the edges Heimdall
+emits for them are still graded for precision.
+
 ## Edge cases (`questions.py`, part 1)
 
 Cases 1–11 are aggregates over a real repository, which is the right way to measure the

{heimdall_code-0.1.0 → heimdall_code-0.2.0}/bench/RESULTS.md

@@ -8,25 +8,29 @@ Repo: `django` — 2927 Python files. Oracle: CPython `ast`, restricted to call
 
 | Call kind | sites | Heimdall recall | fan-out | GitNexus recall | fan-out | graphify recall | fan-out | graphify `+uses` recall | fan-out |
 |---|---|---|---|---|---|---|---|---|---|
-| `self` | 5389 | 100.0% | 1.00 | 97.1% | 1.00 | 92.6% | 1.00 | 92.6% | 1.00 |
+| `self` | 5391 | 100.0% | 1.01 | 97.1% | 1.00 | 92.6% | 1.00 | 92.6% | 1.00 |
 | `local call` | 1255 | 100.0% | 1.06 | 93.4% | 1.00 | 89.3% | 1.00 | 89.3% | 1.00 |
 | `local new` | 943 | 99.5% | 1.00 | 0.0% | nan | 95.2% | 1.00 | 95.2% | 1.00 |
-| `import call` | 4238 | 99.7% | 1.02 | 71.5% | 1.00 | 75.4% | 1.00 | 75.4% | 1.00 |
+| `local const` | 765 | 100.0% | 1.00 | 0.0% | nan | 0.0% | nan | 0.0% | nan |
+| `local ref` | 1196 | 97.8% | 1.02 | 1.9% | 1.00 | 13.8% | 1.00 | 13.8% | 1.00 |
+| `import call` | 4242 | 99.7% | 1.02 | 71.4% | 1.00 | 75.3% | 1.00 | 75.3% | 1.00 |
 | `import new` | 4299 | 98.8% | 1.03 | 0.0% | 1.00 | 98.2% | 1.00 | 98.2% | 1.00 |
+| `import const` | 659 | 100.0% | 1.02 | 0.0% | nan | 0.0% | nan | 0.0% | nan |
+| `import ref` | 10779 | 96.9% | 1.00 | 0.1% | 1.00 | 5.3% | 1.00 | 5.3% | 1.00 |
 
-Total CALLS edges: Heimdall 159,132, GitNexus 24,190, graphify 31,289, graphify `+uses` 84,579
+Total CALLS edges: Heimdall 208,517, GitNexus 24,190, graphify 31,289, graphify `+uses` 84,579
 
 ## Is Leiden clustering worth it?
 
-Newman modularity of each grouping on one shared subgraph (8,936 symbols, 36,310 call edges) — the symbols Leiden placed, so no partition is scored on edges another never saw. Leiden was fitted on GitNexus's own graph and is being replayed on Heimdall's.
+Newman modularity of each grouping on one shared subgraph (9,850 symbols, 41,274 call edges) — the symbols Leiden placed, so no partition is scored on edges another never saw. Leiden was fitted on GitNexus's own graph and is being replayed on Heimdall's.
 
 | Grouping | groups | modularity |
 |---|---|---|
-| Leiden (GitNexus) | 1,541 | 0.257 |
-| directory | 298 | 0.224 |
-| file | 1,006 | 0.194 |
-| label propagation (stdlib, ~15 lines) | 74 | 0.188 |
-| shuffled control | 1,541 | 0.016 |
+| Leiden (GitNexus) | 1,642 | 0.257 |
+| directory | 308 | 0.242 |
+| file | 1,154 | 0.203 |
+| label propagation (stdlib, ~15 lines) | 87 | 0.187 |
+| shuffled control | 1,642 | 0.016 |
 
 Same question on GitNexus's *own* graph (15,573 edges), where Leiden was actually fitted:
 
@@ -40,10 +44,10 @@ Same question on GitNexus's *own* graph (15,573 edges), where Leiden was actuall
 
 | | callers found | shared with the other | wall time |
 |---|---|---|---|
-| Heimdall (SQLite recursive CTE, in-process) | 2,047 | 1,904 | 13 ms |
-| GitNexus (LadybugDB Cypher, node subprocess) | 1,904 | 1,904 | 395 ms |
+| Heimdall (SQLite recursive CTE, in-process) | 2,063 | 1,904 | 14 ms |
+| GitNexus (LadybugDB Cypher, node subprocess) | 1,904 | 1,904 | 419 ms |
 
-Targets: `django/contrib/contenttypes/fields.py:create`, `django/contrib/sessions/backends/cache.py:create`, `django/contrib/sessions/backends/base.py:create`, `django/apps/config.py:create`, `django/test/testcases.py:assertRaisesMessage`
+Targets: `django/contrib/contenttypes/fields.py:create`, `django/contrib/sessions/backends/base.py:create`, `django/contrib/sessions/backends/cache.py:create`, `django/apps/config.py:create`, `django/test/testcases.py:assertRaisesMessage`
 
 The two answers differ mostly because the graphs differ, not because the traversals do — see the call-resolution table above. graphify is absent from this table on purpose: its traversal is in-process Python over the JSON graph, so the row would mostly measure how long that file takes to load, which the Cost table already reports.
 
@@ -51,8 +55,8 @@ The two answers differ mostly because the graphs differ, not because the travers
 
 | | Heimdall | GitNexus | graphify |
 |---|---|---|---|
-| index from scratch | 1.7 s | 23.0 s | 28.8 s |
-| re-index, nothing changed | 1.7 s | 17.9 s | 28.6 s |
-| index on disk | 48 MB | 642 MB | 151 MB |
-| `impact create` from cold, median of 5 | 56 ms | 949 ms | 856 ms |
+| index from scratch | 2.7 s | 23.6 s | 29.8 s |
+| re-index, nothing changed | 2.7 s | 18.6 s | 29.8 s |
+| index on disk | 78 MB | 730 MB | 151 MB |
+| `impact create` from cold, median of 5 | 58 ms | 969 ms | 837 ms |