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

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

@@ -1,6 +1,6 @@
 {
   "name": "heimdall",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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 → heimdall_code-0.3.1}/CHANGELOG.md

@@ -3,6 +3,48 @@
 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.1 — 2026-08-12
+
+### Fixed
+
+- A failed project lookup no longer takes the MCP server down with it. `search` with no
+  project, from a directory with no index, raised `SystemExit` — a `BaseException` the
+  tool handler never turned into an error reply, so it unwound the server's task group
+  and every later call found a dead pipe. `registry.resolve` raises `LookupError` now and
+  `cli.py` turns it back into `SystemExit` where a terminal is watching; the message and
+  exit code are unchanged there.
+
+## 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

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/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`, `CONST_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`. |
@@ -35,12 +35,13 @@ 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".
+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
 
@@ -56,9 +57,14 @@ 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`.
+`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
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: heimdall-code
-Version: 0.2.0
+Version: 0.3.1
 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,11 +32,11 @@ 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 2.42s          # 45,515 symbols, 418,925 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: 10 symbols, 8 files
@@ -98,9 +98,9 @@ against [graphify](https://pypi.org/project/graphifyy/) in its AST-only mode:
 | 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 | **2.7 s** | 23.6 s | 29.8 s |
+| 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 | **58 ms** | 969 ms | 837 ms |
+| `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`
@@ -245,9 +245,9 @@ 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, 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.
+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 four dicts in `heimdall/parse.py` — node types
 for definitions, for calls, for imports and for name bindings — plus a snippet in the test.
@@ -282,6 +282,40 @@ edges — one reference of 2,828 goes unresolved and none of the edges is wrong;
 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.2.0 → heimdall_code-0.3.1}/README.md

@@ -12,11 +12,11 @@ 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 2.42s          # 45,515 symbols, 418,925 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: 10 symbols, 8 files
@@ -78,9 +78,9 @@ against [graphify](https://pypi.org/project/graphifyy/) in its AST-only mode:
 | 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 | **2.7 s** | 23.6 s | 29.8 s |
+| 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 | **58 ms** | 969 ms | 837 ms |
+| `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`
@@ -225,9 +225,9 @@ 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, 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.
+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 four dicts in `heimdall/parse.py` — node types
 for definitions, for calls, for imports and for name bindings — plus a snippet in the test.
@@ -262,6 +262,40 @@ edges — one reference of 2,828 goes unresolved and none of the edges is wrong;
 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.2.0 → heimdall_code-0.3.1}/bench/README.md

@@ -9,6 +9,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 |
+| `kubernetes.py` | the same question for manifests, where the oracle reads indentation | 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
@@ -154,6 +155,50 @@ Bare resource references (`aws_s3_bucket.logs.arn`) are excluded from the recall
 no regex can tell one from an attribute lookup on something else — but the edges Heimdall
 emits for them are still graded for precision.
 
+## Kubernetes (`kubernetes.py`)
+
+No competitor here either. The oracle reads every manifest a second time, by indentation,
+sharing no code with the tree-sitter reader — what it cannot avoid sharing is the domain:
+that `configMapRef.name` names a ConfigMap, and that a Service selects by label, are facts
+about Kubernetes and both readers have to know them.
+
+```console
+git clone --depth 1 https://github.com/GoogleCloudPlatform/microservices-demo
+git clone --depth 1 https://github.com/kubernetes/examples
+git clone --depth 1 https://github.com/prometheus-operator/kube-prometheus
+git clone --depth 1 https://github.com/argoproj/argo-cd
+python bench/kubernetes.py microservices-demo examples kube-prometheus argo-cd
+```
+
+| repo | files | documents | refs by name | recall | selectors | recall | precision |
+|---|---|---|---|---|---|---|---|
+| microservices-demo | 54 | 149 | 1 | 100.0% | 2 | 100.0% | 100.0% |
+| kubernetes/examples | 244 | 274 | 40 | 100.0% | 33 | 100.0% | 100.0% |
+| kube-prometheus | 109 | 114 | 38 | 100.0% | 20 | 100.0% | 100.0% |
+| argo-cd | 1,581 | 2,211 | 47 | 97.9% | 10 | 100.0% | 100.0% |
+| **total** | **1,988** | **2,748** | **126** | **99.2%** | **65** | **100.0%** | **100.0%** |
+
+*by name* — a field that names another object (`serviceAccountName`, `secretKeyRef.name`,
+a `roleRef` whose sibling `kind` says what it is) must produce an edge to the document
+that declares it. *by label* — where exactly one workload in the repo carries labels a
+selector matches, that must be an edge too. *precision* — an edge is endorsed only if the
+source really names the target, or really selects labels the target really carries in the
+same namespace.
+
+The one reference with no edge is `##CRBNAME##`, a sed placeholder in an argo-cd test
+fixture. It is not a name, Heimdall is right to skip it, and the oracle is not clever
+enough to know that — the row stays at 97.9% rather than being tuned to 100%.
+
+Two things the oracle counts but does not score, because the right answer depends on
+kustomize scope it does not model: 842 references whose name two or more files declare,
+and 112 documents inside unrendered Helm charts, where `{{ .Release.Name }}-api` is not
+a name that anything could resolve.
+
+The oracle assumes `kubectl`-shaped yaml — two-space indents, `- key: value` list items.
+Both of its own bugs found so far are pinned in its docstring: it first read correct edges
+as wrong ones by collapsing repeated field paths into a dict, so a pod mounting six
+ConfigMaps looked like it mounted one.
+
 ## Edge cases (`questions.py`, part 1)
 
 Cases 1–11 are aggregates over a real repository, which is the right way to measure the
@@ -225,5 +270,9 @@ Django's `_("...")`, i.e. `gettext` under its usual alias, of being invented.
   not a receiver the tool threw away.
 - Cases 12–27 are one repository of 29 hand-written files. They find shapes that break a
   resolver; they say nothing about how often those shapes occur.
+- `kubernetes.py` cannot catch a modelling choice both readers share. Label matching is
+  generic — a `ServiceMonitor` selects Services rather than pods, and both this oracle and
+  Heimdall will pair it with the workload carrying those labels. That edge is endorsed
+  here and is still an approximation.
 - One repository, one language family. Django is a hard case for a name-based resolver,
   but it is still one data point — the runners take a `--repo` for a reason.

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

@@ -44,8 +44,8 @@ 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,063 | 1,904 | 14 ms |
-| GitNexus (LadybugDB Cypher, node subprocess) | 1,904 | 1,904 | 419 ms |
+| Heimdall (SQLite recursive CTE, in-process) | 2,063 | 1,904 | 13 ms |
+| GitNexus (LadybugDB Cypher, node subprocess) | 1,904 | 1,904 | 387 ms |
 
 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`
 
@@ -55,8 +55,8 @@ The two answers differ mostly because the graphs differ, not because the travers
 
 | | Heimdall | GitNexus | graphify |
 |---|---|---|---|
-| 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 from scratch | 2.6 s | 23.1 s | 28.6 s |
+| re-index, nothing changed | 2.6 s | 17.9 s | 28.7 s |
 | index on disk | 78 MB | 730 MB | 151 MB |
-| `impact create` from cold, median of 5 | 58 ms | 969 ms | 837 ms |
+| `impact create` from cold, median of 5 | 59 ms | 977 ms | 830 ms |
 

heimdall_code-0.3.1/bench/kubernetes.py

@@ -0,0 +1,295 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Does Heimdall resolve Kubernetes references to the right document?
+
+The oracle reads the manifests a second time, by indentation, and shares no code with the
+tree-sitter reader -- so a mistake in the reader cannot make itself look right. What it
+cannot share is the domain: which field names a ConfigMap, and that a Service selects by
+label, are facts about Kubernetes, and both readers have to know them.
+
+Two kinds of reference are graded separately, because they fail differently:
+
+  by name      `configMapRef.name: app-config` names one object. Every such reference
+               whose target exactly one document in the repo declares must be an edge to
+               that document's file.
+  by label     a Service names no Deployment -- it names the labels one puts on its pods.
+               Where exactly one workload in the repo carries a matching set, that must
+               be an edge too.
+
+Precision covers both: an edge is endorsed only if the source document really names the
+target, or really selects labels the target really carries in the same namespace.
+
+References the oracle cannot adjudicate -- a name two files declare, a label set three
+copies of an app answer to -- are counted and reported rather than scored, since the right
+answer depends on kustomize scope that the oracle does not model.
+
+The oracle assumes `kubectl`-shaped yaml: two-space indents, `- key: value` for list
+items, one object per document. It cannot read an unrendered Helm chart, and neither can
+anything else.
+
+Usage:
+    python bench/kubernetes.py REPO [REPO ...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import subprocess
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+
+# field path suffix -> the kind the value names; "*" means a sibling `kind` says which.
+REFS = {
+    "serviceAccountName": "ServiceAccount",
+    "secretName": "Secret",
+    "claimName": "PersistentVolumeClaim",
+    "storageClassName": "StorageClass",
+    "ingressClassName": "IngressClass",
+    "priorityClassName": "PriorityClass",
+    "runtimeClassName": "RuntimeClass",
+    "volumeName": "PersistentVolume",
+    "serviceName": "Service",
+    "configMap.name": "ConfigMap",
+    "configMapRef.name": "ConfigMap",
+    "configMapKeyRef.name": "ConfigMap",
+    "secret.name": "Secret",
+    "secretRef.name": "Secret",
+    "secretKeyRef.name": "Secret",
+    "imagePullSecrets.name": "Secret",
+    "backend.service.name": "Service",
+    "roleRef.name": "*",
+    "subjects.name": "*",
+    "scaleTargetRef.name": "*",
+    "targetRef.name": "*",
+    "ownerReferences.name": "*",
+}
+SELECTORS = {("spec", "selector"), ("spec", "selector", "matchLabels"), ("spec", "podSelector", "matchLabels")}
+BLOCKS = {"|", ">", "|-", ">-", "|+", ">+", "{}", "[]", "null", "~"}
+
+
+def leaves(lines: list[str]) -> list[tuple[tuple[str, ...], str]]:
+    """(path, value) for every `key: value` in one document, by indentation alone.
+
+    List indices are dropped: the reader needs them to tell two containers apart, this
+    does not, and leaving them out is one more way for the two to disagree.
+    """
+    out: list[tuple[tuple[str, ...], str]] = []
+    stack: list[tuple[int, str]] = []
+    for raw in lines:
+        text = raw.rstrip()
+        if not text.strip() or text.lstrip().startswith("#"):
+            continue
+        indent = len(text) - len(text.lstrip())
+        body = text.lstrip()
+        while body.startswith("- "):  # a list item opens a mapping two columns in
+            indent, body = indent + 2, body[2:]
+        if ":" not in body:
+            continue
+        key, _, val = body.partition(":")
+        key = key.strip().strip("\"'")
+        if not key or " " in key:  # a url, or prose inside a block scalar
+            continue
+        val = val.strip().split(" #")[0].strip().strip("\"'")
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        if val and val not in BLOCKS:
+            out.append(((*tuple(k for _, k in stack), key), val))
+        else:
+            stack.append((indent, key))
+    return out
+
+
+def documents(text: str) -> list[list[str]]:
+    docs: list[list[str]] = [[]]
+    for line in text.splitlines():
+        if line.rstrip() == "---":
+            docs.append([])
+        else:
+            docs[-1].append(line)
+    return [d for d in docs if d]
+
+
+def refs_of(multi: dict[tuple[str, ...], list[str]]) -> tuple[set[tuple[str, str]], int]:
+    """(kind, name) for every field that names another object, and the count of fields
+    that cannot be judged: without list indices, a `roleRef` whose sibling `kind` says
+    two different things cannot be paired back up with the right one."""
+    found, skipped = set(), 0
+    for path, values in multi.items():
+        for n in (3, 2, 1):
+            kind = REFS.get(".".join(path[-n:])) if len(path) >= n else None
+            if not kind:
+                continue
+            if kind == "*":
+                kinds = set(multi.get((*path[:-1], "kind"), ()))
+                if len(kinds) != 1:
+                    skipped += len(values)
+                    break
+                kind = kinds.pop()
+            found |= {(kind, v) for v in values if v}
+            break
+    return found, skipped
+
+
+class Oracle:
+    def __init__(self, root: Path) -> None:
+        self.docs: dict[tuple[str, str], dict] = {}
+        self.declares: dict[str, list[str]] = defaultdict(list)
+        self.unrendered = self.unpaired = 0
+        files = [p for p in (*root.rglob("*.yaml"), *root.rglob("*.yml")) if ".git" not in p.parts]
+        for p in files:
+            rel = str(p.relative_to(root))
+            for lines in documents(p.read_text(errors="replace")):
+                # one path can hold many values -- a pod mounts six ConfigMaps at the same
+                # `volumes.configMap.name` once the list indices are gone -- so keep them
+                # all. Collapsing them into a dict is how this oracle first read a
+                # correct edge as a wrong one.
+                multi: dict[tuple[str, ...], list[str]] = defaultdict(list)
+                for path, value in leaves(lines):
+                    multi[path].append(value)
+                vals = {p: v[0] for p, v in multi.items()}
+                kind, name = vals.get(("kind",)), vals.get(("metadata", "name"))
+                if not (("apiVersion",) in vals and kind and name):
+                    continue
+                if "{{" in kind or "{{" in name:
+                    # a Helm chart is not yaml until it is rendered, and `{{ .Values.x }}`
+                    # is not a name. Counted rather than quietly dropped.
+                    self.unrendered += 1
+                    continue
+                labels = {
+                    k[-1]: v
+                    for k, v in vals.items()
+                    if (
+                        k[:-1] == ("metadata", "labels")
+                        if kind == "Pod"
+                        else k[-4:-1] == ("template", "metadata", "labels")
+                    )
+                }
+                found, skipped = refs_of(multi)
+                self.unpaired += skipped
+                doc = {
+                    "file": rel,
+                    "addr": f"{kind}/{name}",
+                    "ns": vals.get(("metadata", "namespace"), ""),
+                    "refs": found,
+                    "labels": labels,
+                    "selector": {} if labels else {k[-1]: v for k, v in vals.items() if k[:-1] in SELECTORS},
+                }
+                self.docs.setdefault((rel, doc["addr"]), doc)
+                self.declares[doc["addr"]].append(rel)
+
+    def expected(self) -> tuple[dict[tuple[str, str, str], str], int, dict[tuple[str, str, str], str], int]:
+        """The edges that must exist, by name and by label, plus what cannot be judged."""
+        names: dict[tuple[str, str, str], str] = {}
+        labels: dict[tuple[str, str, str], str] = {}
+        blurry = blurry_sel = 0
+        for (rel, addr), doc in self.docs.items():
+            for kind, name in doc["refs"]:
+                target = f"{kind}/{name}"
+                owners = set(self.declares.get(target, ()))
+                if len(owners) == 1:
+                    names[(rel, addr, target)] = owners.pop()
+                elif owners:
+                    blurry += 1
+            if doc["selector"]:
+                hits = [
+                    d
+                    for d in self.docs.values()
+                    if d["labels"] and d["ns"] == doc["ns"] and doc["selector"].items() <= d["labels"].items()
+                ]
+                if len(hits) == 1:
+                    labels[(rel, addr, hits[0]["addr"])] = hits[0]["file"]
+                elif hits:
+                    blurry_sel += 1
+        return names, blurry, labels, blurry_sel
+
+    def endorses(self, sfile: str, saddr: str, dfile: str, daddr: str) -> bool:
+        s, d = self.docs.get((sfile, saddr)), self.docs.get((dfile, daddr))
+        if s is None or d is None:
+            return False
+        kind, _, name = daddr.partition("/")
+        if (kind, name) in s["refs"]:
+            return True
+        return bool(s["selector"]) and s["ns"] == d["ns"] and s["selector"].items() <= d["labels"].items()
+
+
+def edges(db: Path) -> list[tuple[str, str, str, str, float]]:
+    """(src file, src address, target file, target address, confidence) for yaml edges."""
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    rows = con.execute(
+        "SELECT s.path, s.name, d.path, d.name, e.confidence FROM edge e"
+        " JOIN node s ON s.id = e.src JOIN node d ON d.id = e.dst"
+        " WHERE e.kind = 'CALLS' AND d.lang = 'yaml' AND s.lang = 'yaml'"
+    ).fetchall()
+    con.close()
+    return rows
+
+
+def run(repo: Path, heimdall: str) -> dict:
+    db = repo / ".heimdall" / "graph.db"
+    t0 = time.time()
+    subprocess.run([heimdall, "index", str(repo)], check=True, capture_output=True)
+    secs = time.time() - t0
+
+    oracle = Oracle(repo)
+    names, blurry, labels, blurry_sel = oracle.expected()
+    found = edges(db)
+    keys = {(s, sa, da) for s, sa, _d, da, _c in found}
+    landed = {(s, sa, d, da) for s, sa, d, da, _c in found}
+    endorsed = [1 for s, sa, d, da, _c in found if oracle.endorses(s, sa, d, da)]
+
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    docs = con.execute("SELECT count(*) FROM node WHERE lang='yaml' AND kind='Class'").fetchone()[0]
+    con.close()
+    hit = sum(1 for k, dst in names.items() if (*k[:2], dst, k[2]) in landed)
+    hit_sel = sum(1 for k, dst in labels.items() if (*k[:2], dst, k[2]) in landed)
+    return {
+        "repo": repo.name,
+        "files": len({d["file"] for d in oracle.docs.values()}),
+        "docs": docs,
+        "refs": len(names),
+        "hit": hit,
+        "sel": len(labels),
+        "hit_sel": hit_sel,
+        "edges": len(found),
+        "endorsed": len(endorsed),
+        "recall": hit / len(names) if names else 0.0,
+        "recall_sel": hit_sel / len(labels) if labels else 0.0,
+        "precision": len(endorsed) / len(found) if found else 0.0,
+        "conf": sum(c for *_r, c in found) / len(found) if found else 0.0,
+        "unlinked": len(names) - len({k for k in names if k in keys}),
+        "blurry": blurry + blurry_sel + oracle.unpaired,
+        "unrendered": oracle.unrendered,
+        "seconds": secs,
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("repos", nargs="+", type=Path)
+    ap.add_argument("--heimdall", default="heimdall")
+    args = ap.parse_args()
+
+    rows = [run(r, args.heimdall) for r in args.repos]
+    cols = f"{'files':>5} {'docs':>5} {'refs':>5} {'byname':>7} {'sel':>5} {'bylabel':>8} {'prec':>6} {'index':>7}"
+    print(f"\n{'repo':26} {cols}")
+    for r in rows:
+        print(
+            f"{r['repo'][:26]:26} {r['files']:5} {r['docs']:5} {r['refs']:5} {r['recall']:6.1%}"
+            f" {r['sel']:6} {r['recall_sel']:7.1%} {r['precision']:5.1%} {r['seconds']:6.2f}s"
+        )
+    tot = {k: sum(r[k] for r in rows) for k in ("files", "docs", "refs", "hit", "sel", "hit_sel", "edges", "endorsed")}
+    print(
+        f"{'total':26} {tot['files']:5} {tot['docs']:5} {tot['refs']:5} {tot['hit'] / tot['refs']:6.1%}"
+        f" {tot['sel']:6} {tot['hit_sel'] / tot['sel']:7.1%} {tot['endorsed'] / tot['edges']:5.1%}"
+    )
+    print(f"\nreferences with no edge at all: {sum(r['unlinked'] for r in rows)}")
+    print(f"references the oracle cannot adjudicate (two files answer to the name): {sum(r['blurry'] for r in rows)}")
+    print(f"documents skipped as unrendered Helm templates: {sum(r['unrendered'] for r in rows)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/heimdall/__init__.py

@@ -9,5 +9,5 @@ inheritance) and serves it to agents over MCP.
 from .graph import Graph
 from .index import build
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 __all__ = ["Graph", "__version__", "build"]

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/heimdall/cli.py

@@ -181,7 +181,11 @@ def main(argv: list[str] | None = None) -> int:
         serve(a.project)
         return 0
 
-    g = Graph.open(registry.resolve(a.project), readonly=True)
+    try:
+        db = registry.resolve(a.project)
+    except LookupError as exc:
+        raise SystemExit(str(exc)) from None
+    g = Graph.open(db, readonly=True)
     try:
         match a.cmd:
             case "search":

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/heimdall/index.py

@@ -42,8 +42,9 @@ SKIP_DIRS = {
     "vendor",
     "coverage-report",
 }
-# package roots and index files that do not contribute a module name segment
-_INDEX_STEMS = {"__init__", "index", "mod", "lib", "main"}
+# package roots and index files that do not contribute a module name segment.
+# `kustomization` is one: it is the index file of a directory of manifests.
+_INDEX_STEMS = {"__init__", "index", "mod", "lib", "main", "kustomization"}
 _SRC_ROOTS = {"src", "lib", "app", "pkg", "internal", "source"}
 # receivers that name the enclosing class rather than another object
 SELF_NAMES = {"self", "this", "cls", "me", "Self"}
@@ -143,7 +144,7 @@ def _module_keys(rel: str) -> list[str]:
     return keys
 
 
-_IMPORT_EXTS = (".js", ".ts", ".jsx", ".tsx", ".py", ".h", ".hpp", ".mjs", ".cjs")
+_IMPORT_EXTS = (".js", ".ts", ".jsx", ".tsx", ".py", ".h", ".hpp", ".mjs", ".cjs", ".yaml", ".yml")
 
 
 def _strip_ext(mod: str) -> str:
@@ -309,19 +310,38 @@ def build(root: Path, db_path: Path, jobs: int = 0, log=lambda m: None) -> dict:
     # sibling -- never the same-named one inside the child module it calls. So for HCL the
     # ranker's notion of "imported" is the siblings, replacing the `source` edges above;
     # those stay as edges, and their alias still points module arguments at the child.
-    tf_dirs: dict[str, set[str]] = {}
+    #
+    # A manifest tree scopes the same way and for the same reason: a name written in one
+    # file means the object of that name beside it. What kustomize adds is a way to say
+    # which *other* directories are in scope, and it says it once per directory rather
+    # than once per file -- so a `resources: [../../base]` puts the base in scope for
+    # every manifest sitting next to that kustomization.yaml, not just for itself.
+    by_dir: dict[tuple[str, str], set[str]] = {}
     for fp in parsed:
-        if fp.lang == "hcl":
-            tf_dirs.setdefault(str(Path(fp.path).parent), set()).add(fp.path)
+        if fp.lang in ("hcl", "yaml"):
+            by_dir.setdefault((fp.lang, str(Path(fp.path).parent)), set()).add(fp.path)
+    paths = {fp.path for fp in parsed}
+    kustomized: dict[str, set[str]] = {}
+    for fp in parsed:
+        if fp.lang == "yaml" and Path(fp.path).stem == "kustomization":
+            here = kustomized.setdefault(str(Path(fp.path).parent), set())
+            for mod, _line, _scope in fp.imports:
+                target = _relative_target(fp.path, mod)
+                if target is not None:  # a directory of manifests, or one manifest
+                    here |= by_dir.get(("yaml", target), set())
+                    here |= {p for p in (f"{target}.yaml", f"{target}.yml") if p in paths}
     for fp in parsed:
+        d = str(Path(fp.path).parent)
         if fp.lang == "hcl":
-            imported[fp.path] = tf_dirs[str(Path(fp.path).parent)] - {fp.path}
+            imported[fp.path] = by_dir[("hcl", d)] - {fp.path}
             # and a called module is a whole directory, not the one file the generic
             # alias landed on: `region = ...` means the `variable "region"` anywhere in it
             for mod, _line, _scope in fp.imports:
                 target = _relative_target(fp.path, mod)
                 if target is not None:
                     aliases[fp.path][target.rsplit("/", 1)[-1]] = target
+        elif fp.lang == "yaml":
+            imported[fp.path] = (by_dir[("yaml", d)] | kustomized.get(d, set())) - {fp.path}
 
     # --- name index for call/heritage resolution
     by_name: dict[str, list[tuple[int, str, str, str, str]]] = {}
@@ -386,6 +406,32 @@ def build(root: Path, db_path: Path, jobs: int = 0, log=lambda m: None) -> dict:
             for dst, _path, _kind, conf in ranked[:5]:
                 edges.append((src, dst, "CALLS", conf, line))  # a self-edge is recursion
 
+    # --- kubernetes label selectors: the one reference here that is not written as a
+    #     name. A Service says which labels it wants, a Deployment says which labels its
+    #     pods carry, and the edge exists when the first set is inside the second -- in
+    #     the same namespace, so a prod Service cannot end up wired to staging pods.
+    #     Scope decides between matches exactly as it does for a name: a repo that keeps
+    #     three copies of the same app -- plain manifests, a kustomize base, a rendered
+    #     release -- has every copy answering to `app: adservice`, and the one in scope is
+    #     the one that was meant.
+    # ponytail: selectors x workloads, which on a manifest repo is thousands of set
+    # comparisons. An index keyed by one label would be the fix if that stops being true.
+    offers = [(ids[q], fp.path, ns, lab) for fp in parsed for q, ns, lab in fp.labels if q in ids]
+    for fp in parsed:
+        here = imported.get(fp.path, ())
+        for qname, ns, want, line in fp.selectors:
+            src = ids.get(qname)
+            if src is None:
+                continue
+            hits = [(dst, path) for dst, path, dns, lab in offers if dns == ns and want.items() <= lab.items()]
+            hits = [h for h in hits if h[0] != src]
+            near = [h for h in hits if h[1] == fp.path] or [h for h in hits if h[1] in here]
+            conf = 0.95 if any(h[1] == fp.path for h in near) else 0.9 if near else 0.7
+            if not near and len(hits) != 1:
+                continue  # several copies and nothing to choose between them: say nothing
+            for dst, _path in (near or hits)[:5]:
+                edges.append((src, dst, "CALLS", conf, line))
+
     g.add_edges(edges)
     log("pass 4/4  building search index")
     g.reindex_fts()

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/heimdall/parse.py

@@ -6,9 +6,9 @@ Language support is a data table, not code: node-type -> symbol kind. Tree-sitte
 grammars name their nodes consistently enough that one generic walker covers every
 language here. Adding a language means adding rows, not a module.
 
-HCL is the one exception, and it is a real one rather than a shortcut: Terraform has no
-definitions and no calls, so it gets its own reader further down instead of bending the
-walker around it.
+HCL and YAML are the two exceptions, and they are real ones rather than shortcuts:
+Terraform has no definitions and no calls, and a Kubernetes manifest has neither either.
+Both get their own reader further down instead of bending the walker around them.
 """
 
 from __future__ import annotations
@@ -50,6 +50,8 @@ EXT_LANG = {
     ".sh": "bash",
     ".tf": "hcl",
     ".hcl": "hcl",
+    ".yaml": "yaml",
+    ".yml": "yaml",
 }
 
 _JS_DEFS = {
@@ -252,6 +254,11 @@ class FileParse:
     renames: list[tuple[str, str, int]] = field(default_factory=list)
     # (class_qname, base_name)
     heritage: list[tuple[str, str]] = field(default_factory=list)
+    # kubernetes selects by shape, not by name: a Service names no Deployment, it names
+    # the labels one puts on its pods. (qname, namespace, labels offered) and
+    # (qname, namespace, labels required, line) -- matched against each other in index.py.
+    labels: list[tuple[str, str, dict[str, str]]] = field(default_factory=list)
+    selectors: list[tuple[str, str, dict[str, str], int]] = field(default_factory=list)
     error: str | None = None
 
 
@@ -558,6 +565,179 @@ def _parse_hcl(out: FileParse, root, src: bytes) -> FileParse:
     return out
 
 
+# ---------------------------------------------------------------- kubernetes (yaml)
+#
+# The second reader beside the walker, and for the same reason as the first: a manifest
+# declares nothing and calls nothing either. What it has is a document that names itself
+# the way `kubectl` addresses it -- `kind` plus `metadata.name` -- and fields elsewhere
+# holding the names of other documents. The *field* is what says which kind a name refers
+# to: the string under `configMapRef.name` can only be a ConfigMap. So the rules are a
+# table of field paths, and yaml that is not a Kubernetes object produces nothing at all.
+
+# field path suffix -> the kind the value names. "*" means the kind is not implied by the
+# field but written beside it, in a sibling `kind`.
+K8S_REFS = {
+    "serviceAccountName": "ServiceAccount",
+    "secretName": "Secret",
+    "claimName": "PersistentVolumeClaim",
+    "storageClassName": "StorageClass",
+    "ingressClassName": "IngressClass",
+    "priorityClassName": "PriorityClass",
+    "runtimeClassName": "RuntimeClass",
+    "volumeName": "PersistentVolume",
+    "serviceName": "Service",
+    "configMap.name": "ConfigMap",
+    "configMapRef.name": "ConfigMap",
+    "configMapKeyRef.name": "ConfigMap",
+    "secret.name": "Secret",
+    "secretRef.name": "Secret",
+    "secretKeyRef.name": "Secret",
+    "imagePullSecrets.name": "Secret",
+    "backend.service.name": "Service",
+    "roleRef.name": "*",
+    "subjects.name": "*",
+    "scaleTargetRef.name": "*",
+    "targetRef.name": "*",
+    "ownerReferences.name": "*",
+}
+# the paths a label selector is written at. A workload's own `spec.selector` selects its
+# own pods, which is why an object that offers pod labels never gets a selector edge.
+K8S_SELECTORS = {
+    ("spec", "selector"),
+    ("spec", "selector", "matchLabels"),
+    ("spec", "podSelector", "matchLabels"),
+}
+# kustomize: the only import a manifest tree has
+K8S_INCLUDES = {"resources", "bases", "components", "patchesStrategicMerge", "patches", "crds"}
+
+
+def _yaml_text(node) -> str:
+    return _text(node).strip().strip("\"'")
+
+
+def _k8s_name(v: str) -> bool:
+    """A name Kubernetes would accept. This is also what rules out an unrendered chart:
+    `{{ .Release.Name }}-api` is not a name until something renders it."""
+    return 0 < len(v) < 254 and v[0].isalnum() and all(c.isalnum() or c in "._-:@" for c in v)
+
+
+def _yaml_leaves(node, path: tuple[str, ...], out: list, depth: int = 0) -> None:
+    """(path, value, line) for every scalar in the tree.
+
+    The path stays a tuple rather than a dotted string because label keys are routinely
+    `app.kubernetes.io/name`, and a dotted path could not be split back apart. List
+    indices are part of it: they are what tells two `configMapRef`s in one pod apart, and
+    what makes the sibling `kind` of a `roleRef` findable.
+    """
+    # ponytail: a stack guard, not a semantic limit. A CronJob's pod spec is ~15 keys
+    # deep and every key costs four frames here; nothing real comes near this.
+    if depth > 400:
+        return
+    if node.type in ("block_mapping_pair", "flow_pair"):
+        k, v = node.child_by_field_name("key"), node.child_by_field_name("value")
+        if k is not None and v is not None:
+            _yaml_leaves(v, (*path, _yaml_text(k)), out, depth + 1)
+        return
+    if node.type in ("block_sequence", "flow_sequence"):
+        i = 0
+        for c in node.children:
+            if c.type in ("block_sequence_item", "block_node", "flow_node"):
+                _yaml_leaves(c, (*path, str(i)), out, depth + 1)
+                i += 1
+        return
+    if node.type == "flow_node" and not any(c.type in ("flow_mapping", "flow_sequence") for c in node.children):
+        out.append((path, _yaml_text(node), node.start_point[0] + 1))
+        return
+    for c in node.children:
+        _yaml_leaves(c, path, out, depth + 1)
+
+
+def _k8s_ref(path: tuple[str, ...]) -> str | None:
+    """The kind this field's value names, if the field is one that names something."""
+    bare = [s for s in path if not s.isdigit()]
+    for n in (3, 2, 1):
+        if len(bare) >= n:
+            kind = K8S_REFS.get(".".join(bare[-n:]))
+            if kind:
+                return kind
+    return None
+
+
+def _yaml_documents(src: bytes) -> list[tuple[int, bytes]]:
+    """(first line number, bytes) per document, split on YAML's own separator.
+
+    Before the parser rather than after it, because a rendered manifest is one file of
+    sixty documents and a single one the grammar cannot follow takes every document after
+    it down with it -- the remains end up loose at the top of the tree with no `---` left
+    to tell them apart. Split first and the damage stops at the document that caused it.
+    """
+    docs: list[tuple[int, bytes]] = []
+    start, buf = 1, []
+    for i, line in enumerate(src.split(b"\n"), 1):
+        if line.rstrip() == b"---" or line.startswith(b"--- "):
+            docs.append((start, b"\n".join(buf)))
+            start, buf = i + 1, []
+        else:
+            buf.append(line)
+    docs.append((start, b"\n".join(buf)))
+    return [(n, b) for n, b in docs if b.strip()]
+
+
+def _parse_yaml(out: FileParse, parser, src: bytes) -> FileParse:
+    for first, chunk in _yaml_documents(src):
+        root = parser.parse(chunk).root_node
+        found: list[tuple[tuple[str, ...], str, int]] = []
+        _yaml_leaves(root, (), found)
+        leaves = [(p, v, first + ln - 1) for p, v, ln in found]
+        vals = {p: v for p, v, _line in leaves}
+
+        # kustomize `resources` names the files and directories this one composes. They
+        # are relative to this file, always -- said with a leading `./` so the resolver
+        # cannot mistake one for the name of a module somewhere else in the repo.
+        for path, value, line in leaves:
+            if path[:1] and path[0] in K8S_INCLUDES and (path[-1].isdigit() or path[-1] == "path"):
+                if "://" not in value and not value.startswith(("http", "git@")):
+                    out.imports.append((value if value.startswith(".") else f"./{value}", line, None))
+
+        kind, name = vals.get(("kind",)), vals.get(("metadata", "name"))
+        if not (("apiVersion",) in vals and kind and name and kind.isalnum() and _k8s_name(name)):
+            continue  # any other yaml, or a chart nobody has rendered
+        ns = vals.get(("metadata", "namespace"), "")
+        addr = f"{kind}/{name}"
+        sym = Symbol(
+            kind="Class",
+            name=addr,
+            qname=f"{out.path}:{addr}",
+            line=first + root.start_point[0],
+            end_line=first + root.end_point[0],
+            parent=None,
+            signature=f"{addr} -n {ns}" if ns else addr,
+        )
+        out.symbols.append(sym)
+
+        for path, value, line in leaves:
+            target = _k8s_ref(path)
+            if target is None or not _k8s_name(value):
+                continue
+            if target == "*":
+                target = vals.get((*path[:-1], "kind"), "")
+            if target.isalnum():
+                out.calls.append((sym.qname, f"{target}/{value}", line, None, True))
+
+        # a pod template is a pod template wherever the workload keeps it: a Deployment
+        # holds one at spec.template, a CronJob two levels further down
+        if kind == "Pod":
+            offered = {p[-1]: v for p, v in vals.items() if p[:-1] == ("metadata", "labels")}
+        else:
+            offered = {p[-1]: v for p, v in vals.items() if p[-4:-1] == ("template", "metadata", "labels")}
+        selects = [(p[-1], v, line) for p, v, line in leaves if p[:-1] in K8S_SELECTORS]
+        if offered:
+            out.labels.append((sym.qname, ns, offered))
+        elif selects:
+            out.selectors.append((sym.qname, ns, {k: v for k, v, _line in selects}, min(ln for _k, _v, ln in selects)))
+    return out
+
+
 # ---------------------------------------------------------------- the walker
 
 
@@ -568,7 +748,11 @@ def parse_source(path: str, lang: str, src: bytes) -> FileParse:
     imports = IMPORT_NODES.get(lang, set())
     consts = CONST_NODES.get(lang, set())
     try:
-        tree = get_parser(lang).parse(src)
+        parser = get_parser(lang)
+        # yaml is parsed one document at a time, so it does its own
+        if lang == "yaml":
+            return _parse_yaml(out, parser, src)
+        tree = parser.parse(src)
     except Exception as exc:  # unparsable file: record and keep indexing the repo
         out.error = f"{type(exc).__name__}: {exc}"
         return out

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/heimdall/registry.py

@@ -31,7 +31,12 @@ def register(name: str, db: Path) -> None:
 
 
 def resolve(project: str | None, cwd: Path | None = None) -> Path:
-    """A project name, an explicit db path, or the repo in the current directory."""
+    """A project name, an explicit db path, or the repo in the current directory.
+
+    Failure is a LookupError, never SystemExit: this also runs inside the MCP server,
+    where a BaseException escapes the tool handler and kills the process mid-request --
+    the client then hangs on a reply that will never come.
+    """
     if project:
         p = Path(project)
         if p.suffix == ".db" and p.exists():
@@ -42,10 +47,10 @@ def resolve(project: str | None, cwd: Path | None = None) -> Path:
         matches = [v for k, v in entries.items() if project in k]
         if len(matches) == 1:
             return Path(matches[0])
-        raise SystemExit(f"unknown project {project!r}; known: {', '.join(sorted(load())) or '(none)'}")
+        raise LookupError(f"unknown project {project!r}; known: {', '.join(sorted(load())) or '(none)'}")
     here = (cwd or Path.cwd()).resolve()
     for d in (here, *here.parents):
         db = d / ".heimdall" / "graph.db"
         if db.exists():
             return db
-    raise SystemExit("no index found here -- run `heimdall index` first, or pass --project")
+    raise LookupError("no index found here -- run `heimdall index` first, or pass --project")

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # `heimdall` on PyPI is an unrelated screenshot library; the command is still `heimdall`
 name = "heimdall-code"
-version = "0.2.0"
+version = "0.3.1"
 description = "A code knowledge graph that sees everything -- indexes any repository into a SQLite property graph and serves it to AI agents over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/skills/heimdall/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 19 languages, Terraform included.
+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 20 languages, Terraform and Kubernetes manifests included.
 ---
 
 # Heimdall

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/tests/test_heimdall.py

@@ -171,6 +171,83 @@ output "subnet_id" {
   value = var.region
 }
 """,
+    # kubernetes: a document is addressed `Kind/name`, and which kind a name refers to is
+    # decided by the field holding it
+    "k8s/base/deployment.yaml": """
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+spec:
+  selector:
+    matchLabels:
+      app: api
+  template:
+    metadata:
+      labels:
+        app: api
+    spec:
+      serviceAccountName: api-sa
+      containers:
+        - name: web
+          envFrom:
+            - configMapRef:
+                name: app-config
+""",
+    # two documents in one file, and a same-labelled workload in another namespace that
+    # the Service below must *not* be wired to
+    "k8s/base/extras.yaml": """
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config
+data:
+  LEVEL: debug
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: api-sa
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-staging
+  namespace: staging
+spec:
+  template:
+    metadata:
+      labels:
+        app: api
+    spec:
+      containers:
+        - name: web
+""",
+    # a Service names no Deployment: it names the labels one puts on its pods
+    "k8s/base/service.yaml": """
+apiVersion: v1
+kind: Service
+metadata:
+  name: api
+spec:
+  selector:
+    app: api
+""",
+    "k8s/base/kustomization.yaml": "resources:\n  - deployment.yaml\n  - extras.yaml\n  - service.yaml\n",
+    # ... and an overlay reaches the base only because its kustomization says so
+    "k8s/overlays/prod/kustomization.yaml": "resources:\n  - ../../base\n",
+    "k8s/overlays/prod/hpa.yaml": """
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: api
+spec:
+  scaleTargetRef:
+    kind: Deployment
+    name: api
+""",
+    # yaml that is not a manifest is not a symbol
+    "ci.yml": "jobs:\n  build:\n    steps:\n      - run: make\n",
 }
 
 
@@ -280,6 +357,25 @@ def test_end_to_end() -> None:
         callers = {c["qname"] for c in g.context("infra/modules/vpc/main.tf:var.region")["callers"]}
         assert callers == {"infra/main.tf:module.vpc", "infra/modules/vpc/main.tf:output.subnet_id"}, callers
 
+        # kubernetes: `kind` + `metadata.name` is the address, and the field a name sits
+        # in is what says which kind it refers to
+        assert g.resolve("k8s/base/deployment.yaml:Deployment/api"), "document address"
+        refs = {c["qname"] for c in g.context("k8s/base/deployment.yaml:Deployment/api")["calls"]}
+        assert refs == {"k8s/base/extras.yaml:ConfigMap/app-config", "k8s/base/extras.yaml:ServiceAccount/api-sa"}, refs
+
+        # a Service selects labels, not names -- and only in its own namespace, so the
+        # identically labelled staging Deployment is not one of its answers
+        selected = {c["qname"] for c in g.context("k8s/base/service.yaml:Service/api")["calls"]}
+        assert selected == {"k8s/base/deployment.yaml:Deployment/api"}, selected
+
+        # an overlay reaches the base because its kustomization.yaml says it does
+        hpa = g.context("k8s/overlays/prod/hpa.yaml:HorizontalPodAutoscaler/api")["calls"]
+        assert [c["qname"] for c in hpa] == ["k8s/base/deployment.yaml:Deployment/api"], hpa
+        assert hpa[0]["confidence"] == 0.8
+
+        # yaml that is not a manifest contributes a file and nothing else
+        assert g.query("SELECT count(*) AS n FROM node WHERE path = 'ci.yml'")[0]["n"] == 1
+
         # dead code is visible as "no callers"
         assert g.context("src/loader.py:unused")["callers"] == []
 
@@ -318,6 +414,7 @@ SNIPPETS = {
     "dart": ("a.dart", "import 'x.dart';\nclass A extends B { void m(){ foo(); } }\n"),
     "bash": ("a.sh", "f() { g; }\n"),
     "hcl": ("main.tf", 'variable "r" {}\nresource "aws_s3_bucket" "b" {\n  bucket = var.r\n}\n'),
+    "yaml": ("p.yaml", "apiVersion: v1\nkind: Pod\nmetadata:\n  name: p\nspec:\n  serviceAccountName: sa\n"),
 }
 
 
@@ -354,6 +451,20 @@ def test_install_writes_agent_config() -> None:
     assert r.returncode == 0, r.stdout + r.stderr  # the assertion that failed, not just "exit 1"
 
 
+def test_resolve_failures_are_ordinary_exceptions() -> None:
+    """SystemExit here killed the MCP server mid-request; the client hung, then reconnected."""
+    from heimdall import registry
+
+    with tempfile.TemporaryDirectory() as d:
+        for bad in (lambda: registry.resolve(None, Path(d)), lambda: registry.resolve("nope::missing", Path(d))):
+            try:
+                bad()
+            except Exception as exc:  # LookupError is an Exception; SystemExit is not
+                assert isinstance(exc, LookupError), exc
+            else:
+                raise AssertionError("expected a LookupError")
+
+
 def test_every_declared_language_extracts() -> None:
     from heimdall.parse import EXT_LANG, parse_source
 
@@ -369,5 +480,6 @@ if __name__ == "__main__":
     test_end_to_end()
     test_submodules_are_indexed()
     test_install_writes_agent_config()
+    test_resolve_failures_are_ordinary_exceptions()
     test_every_declared_language_extracts()
     print("ok")

{heimdall_code-0.2.0 → heimdall_code-0.3.1}/uv.lock

@@ -204,7 +204,7 @@ wheels = [
 
 [[package]]
 name = "heimdall-code"
-version = "0.2.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "mcp" },