heimdall-code 0.1.1__tar.gz → 0.3.0__tar.gz

{heimdall_code-0.1.1 → heimdall_code-0.3.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "heimdall",
-  "version": "0.1.1",
+  "version": "0.3.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.3.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# 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.3.0 — 2026-08-01
+
+### Added
+
+- **Kubernetes manifests**, as the 20th language and the second one the generic walker
+  could not reach. A document with `apiVersion`, `kind` and `metadata.name` is indexed
+  under the address `kubectl` uses for it — `Deployment/api` — and every field holding
+  the name of another document becomes a `CALLS` edge. The field decides the kind: a name
+  under `configMapRef.name` can only be a ConfigMap, and where the field does not say
+  (`roleRef`, `scaleTargetRef`) the sibling `kind` does. So `impact ConfigMap/app-config`
+  now answers with the workloads that would restart.
+- **Label selectors are edges too**, which is the one Kubernetes reference not written as
+  a name: a Service's selector is matched against the labels a workload puts on its pods,
+  within one namespace, so a prod Service cannot end up wired to staging pods. Scope
+  settles which copy was meant — a directory of manifests is a scope the way a Terraform
+  module is, and `kustomization.yaml`'s `resources` say which other directories join it.
+- `bench/kubernetes.py`, graded by an oracle that re-reads the manifests by indentation
+  and shares no code with the tree-sitter reader. Across four public repos — 1,988 files,
+  2,748 documents — every reference by name and by label resolves to the right document
+  and none of the edges is wrong. The one reference with no edge is `##CRBNAME##`, a sed
+  placeholder in an argo-cd test fixture, which is not a name.
+- Yaml that is not a manifest is a file in the graph and nothing more. An unrendered Helm
+  chart is skipped rather than guessed at: `{{ .Release.Name }}-api` is not a name.
+
+### Fixed
+
+- A yaml file is now parsed one document at a time, split on YAML's own `---` before the
+  grammar sees it. A single document the grammar could not follow used to take every
+  document after it down with it — in argo-cd's 1.9 MB rendered `install.yaml` that was
+  82 of 130 objects, left out of the graph with nothing to say they were missing.
+
+## 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.1 → heimdall_code-0.3.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 — plus `_parse_hcl` and `_parse_yaml`, the two readers that could not be rows. |
 | `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,20 @@ 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 and YAML are the two that did not fit, and they are worth reading before deciding
+yours does not either: neither has definition nodes or call nodes, so no set of rows could
+express them. Each gets a reader beside the walker rather than a branch inside it —
+`_parse_hcl` with its three tables of Terraform addressing rules, `_parse_yaml` with its
+table of Kubernetes field paths — and the walker stays untouched. 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 +57,15 @@ 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, and
+`bench/kubernetes.py` for manifests against an oracle that re-reads them by indentation.
+No other tool to compare against, so both only grade Heimdall's own edges:
+
+```console
+python bench/terraform.py /path/to/some-terraform-repo
+python bench/kubernetes.py /path/to/some-manifest-repo
+```
+
 ## Release
 
 Bump `version` in `pyproject.toml`, `__version__` in `heimdall/__init__.py` and `version`

{heimdall_code-0.1.1 → heimdall_code-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: heimdall-code
-Version: 0.1.1
+Version: 0.3.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
@@ -32,14 +32,14 @@ Apache-2.0. No server, no cloud, no embedded graph engine. **The graph is a SQLi
 ```console
 $ heimdall index ~/code/django
 pass 1/4  discovering files
-  2974 source files
+  2998 source 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.35s          # 45,515 symbols, 418,951 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.6 s** | 23.1 s | 28.6 s |
+| index on disk | **78 MB** | 730 MB | 151 MB |
+| `impact X` from cold | **59 ms** | 977 ms | 830 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,77 @@ 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, Kubernetes. 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.
+
+### Kubernetes
+
+`.yaml` and `.yml` are read the same way and for the same reason. A document that carries
+`apiVersion`, `kind` and `metadata.name` is indexed under the address `kubectl` uses for
+it — `Deployment/api`, `ConfigMap/app-config` — and every field that holds the name of
+another document becomes a `CALLS` edge. Which kind a name refers to is decided by the
+field it sits in: the string under `configMapRef.name` can only be a ConfigMap, and where
+the field does not say (`roleRef`, `scaleTargetRef`) the sibling `kind` does.
+
+```console
+heimdall impact ConfigMap/app-config   # every workload that would restart
+heimdall context Deployment/api        # what it mounts, and who routes to it
+```
+
+A Service names no Deployment, so the one reference that is not written as a name is
+matched by shape instead: a selector's labels against the labels a workload puts on its
+pods, within one namespace. Scope settles the rest — a directory of manifests is a scope
+like a Terraform module, and `kustomization.yaml`'s `resources` say which other
+directories to add, so a `base` and its overlays resolve to the copy that was meant.
+
+Scored against an oracle that re-reads the manifests by indentation, on four public repos
+— 1,988 files, 2,748 documents — every reference by name and every reference by label
+resolves to the right document, and none of the edges is wrong.
+
+Yaml that is not a manifest is a file in the graph and nothing more; a Helm chart is not
+yaml until it is rendered, and `{{ .Release.Name }}-api` is not a name, so unrendered
+templates are skipped rather than guessed at.
+
+One approximation worth knowing: a selector is matched against pod labels whatever kind
+wrote it. A Prometheus `ServiceMonitor` selects *Services*, not pods, so Heimdall links it
+to the workload whose pods carry those labels — the neighbouring object rather than the
+exact one. Matching by kind would need a table of what every CRD selects; matching by
+labels gets a CRD that selects pods right without knowing it exists.
+
 ## Limitations
 
 Call resolution is name-based, not type-based. `self.x()` and `module.x()` resolve

{heimdall_code-0.1.1 → heimdall_code-0.3.0}/README.md

@@ -12,14 +12,14 @@ Apache-2.0. No server, no cloud, no embedded graph engine. **The graph is a SQLi
 ```console
 $ heimdall index ~/code/django
 pass 1/4  discovering files
-  2974 source files
+  2998 source 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.35s          # 45,515 symbols, 418,951 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.6 s** | 23.1 s | 28.6 s |
+| index on disk | **78 MB** | 730 MB | 151 MB |
+| `impact X` from cold | **59 ms** | 977 ms | 830 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,77 @@ 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, Kubernetes. 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.
+
+### Kubernetes
+
+`.yaml` and `.yml` are read the same way and for the same reason. A document that carries
+`apiVersion`, `kind` and `metadata.name` is indexed under the address `kubectl` uses for
+it — `Deployment/api`, `ConfigMap/app-config` — and every field that holds the name of
+another document becomes a `CALLS` edge. Which kind a name refers to is decided by the
+field it sits in: the string under `configMapRef.name` can only be a ConfigMap, and where
+the field does not say (`roleRef`, `scaleTargetRef`) the sibling `kind` does.
+
+```console
+heimdall impact ConfigMap/app-config   # every workload that would restart
+heimdall context Deployment/api        # what it mounts, and who routes to it
+```
+
+A Service names no Deployment, so the one reference that is not written as a name is
+matched by shape instead: a selector's labels against the labels a workload puts on its
+pods, within one namespace. Scope settles the rest — a directory of manifests is a scope
+like a Terraform module, and `kustomization.yaml`'s `resources` say which other
+directories to add, so a `base` and its overlays resolve to the copy that was meant.
+
+Scored against an oracle that re-reads the manifests by indentation, on four public repos
+— 1,988 files, 2,748 documents — every reference by name and every reference by label
+resolves to the right document, and none of the edges is wrong.
+
+Yaml that is not a manifest is a file in the graph and nothing more; a Helm chart is not
+yaml until it is rendered, and `{{ .Release.Name }}-api` is not a name, so unrendered
+templates are skipped rather than guessed at.
+
+One approximation worth knowing: a selector is matched against pod labels whatever kind
+wrote it. A Prometheus `ServiceMonitor` selects *Services*, not pods, so Heimdall links it
+to the workload whose pods carry those labels — the neighbouring object rather than the
+exact one. Matching by kind would need a table of what every CRD selects; matching by
+labels gets a CRD that selects pods right without knowing it exists.
+
 ## Limitations
 
 Call resolution is name-based, not type-based. `self.x()` and `module.x()` resolve

{heimdall_code-0.1.1 → heimdall_code-0.3.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%) |