heimdall-code 0.1.0__tar.gz

heimdall_code-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "heimdall",
+  "description": "Code knowledge graph for AI agents -- callers, blast radius and call paths from a SQLite index instead of a grep sweep.",
+  "owner": {
+    "name": "Bogdan Sapovskyi",
+    "url": "https://github.com/stPhoenix"
+  },
+  "plugins": [
+    {
+      "name": "heimdall",
+      "description": "Indexes any repository into a SQLite property graph and serves it over MCP: what calls this, what breaks if I change it, how does A reach B.",
+      "source": "./",
+      "category": "development"
+    }
+  ]
+}

heimdall_code-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "heimdall",
+  "version": "0.1.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",
+    "url": "https://github.com/stPhoenix"
+  },
+  "homepage": "https://github.com/stPhoenix/heimdall",
+  "repository": "https://github.com/stPhoenix/heimdall",
+  "license": "Apache-2.0",
+  "keywords": ["code-intelligence", "knowledge-graph", "mcp", "static-analysis", "tree-sitter"]
+}

heimdall_code-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+# Publish heimdall-code to PyPI when a v* tag is pushed.
+#
+# No API token anywhere: PyPI trusted publishing exchanges GitHub's OIDC token for a
+# short-lived upload credential, which is why `id-token: write` is the one permission
+# granted. Configure the publisher once at
+# https://pypi.org/manage/project/heimdall-code/settings/publishing/
+# (or as a pending publisher, before the first release) with:
+#   owner stPhoenix / repo heimdall / workflow release.yml / environment pypi
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: # re-run a failed publish without cutting another tag
+
+permissions: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    env:
+      # the floor in pyproject.toml, so the gate tests what the package claims to support
+      # rather than whatever the runner image ships this month
+      UV_PYTHON: "3.12"
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v9.0.0 # setup-uv stopped publishing moving major tags
+        with:
+          enable-cache: true
+
+      - run: uv sync --locked
+
+      # a PyPI version is immutable, so catch a mismatched tag before the upload, not after
+      - name: Version matches the tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          v=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')
+          [ "v$v" = "$GITHUB_REF_NAME" ] || { echo "pyproject.toml says $v, tag says $GITHUB_REF_NAME"; exit 1; }
+
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+
+      - run: uv build
+
+      # the wheel is what users actually get, and a PyPI version cannot be replaced:
+      # install it clean and drive it once before the upload, not after
+      - name: Smoke test the wheel
+        run: |
+          uv run --isolated --no-project --with dist/*.whl heimdall index . --json
+          uv run --isolated --no-project --with dist/*.whl heimdall stats
+
+      - run: uv publish --trusted-publishing always

heimdall_code-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.heimdall/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.idea/

heimdall_code-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "heimdall": {
+      "command": "uvx",
+      "args": ["--from", "heimdall-code", "heimdall", "mcp"]
+    }
+  }
+}

heimdall_code-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.1.0 — unreleased
+
+First release.
+
+### Added
+
+- **Index.** `heimdall index` builds `.heimdall/graph.db` in four passes — discover
+  (`git ls-files`, submodules included), parse (tree-sitter, one process per core),
+  resolve, FTS5. 1.7 s and 48 MB for Django's 2,927 files.
+- **Query.** `search`, `context`, `impact`, `trace`, `stats`, `projects` and a read-only
+  `sql` escape hatch over a two-table schema. Every command takes `--json` and
+  `-p/--project`.
+- **18 languages**, declared as data in `parse.py` and each covered by a test that fails
+  if a grammar renames a node type.
+- **MCP server** (`heimdall mcp`): one process serves every repo in
+  `~/.heimdall/registry.json`, eight tools returning assembled answers rather than raw
+  edges.
+- **`heimdall install [claude|codex|all]`** — writes `~/.claude.json`, `./.mcp.json`,
+  `~/.codex/config.toml` or `./.codex/config.toml`, merging around your existing
+  settings; `--cli` installs the skill instead of the server.
+- **Claude Code plugin**: `/plugin marketplace add stPhoenix/heimdall`.
+- **Benchmark** (`bench/`) against GitNexus and graphify, graded by a CPython `ast`
+  oracle.
+
+### Resolution fixes found by the benchmark
+
+Each of these was a wrong answer before it was a test:
+
+- Imports resolve per scope, so a function with its own `from x import y` is no longer
+  matched against the whole file.
+- `pkg/main.py` is reachable as `pkg.main`, not only as `pkg`.
+- `as` renames are followed home — but only for in-repo targets, so
+  `from asyncio import run as arun` cannot bind to your own `run`.
+- A decorator is a call by the function it wraps, not by the enclosing class. Worth 26%
+  of imported-call recall on Django.
+- Recursion produces an edge.
+- A class name used as a receiver resolves inside that class — including when several
+  classes share the name, because the one that defines the member is the one that was
+  meant. Took *who calls `Model.check`* from 0% to 94% precision.

heimdall_code-0.1.0/CLAUDE.md

@@ -0,0 +1,40 @@
+# Heimdall
+
+A code knowledge graph in SQLite. See [CONTRIBUTING.md](CONTRIBUTING.md) for the module
+map, how to add a language, and the release steps — read it before changing anything
+structural.
+
+## Working here
+
+```console
+uv run ruff format . && uv run ruff check . && uv run pytest   # the gate, under a second
+uv run python -m heimdall.install       # the install self-check alone
+uv run heimdall index . && uv run heimdall context Graph.impact   # dogfood
+```
+
+Use Heimdall on itself instead of grepping for callers; if the answer looks wrong, that
+is a bug worth a fixture.
+
+## Constraints that are load-bearing
+
+- **Two runtime dependencies** (tree-sitter, mcp) and the standard library. "No embedded
+  graph engine, no server, no embeddings" is the pitch — a new dependency needs an
+  argument, not a convenience.
+- **Language support is data.** Add rows to the dicts in `parse.py`, never a per-language
+  module. If a language will not fit the generic walker, say so rather than special-casing
+  it in the walker.
+- **Queries are one SQL statement.** Anything expensive is precomputed in `index.py`.
+- **`graph.query()` is a trust boundary** — read-only, one statement. Don't widen it.
+- **Confidence is the honesty mechanism.** A name-only match is `0.3` and must stay
+  labelled as such; never promote a guess to look certain.
+- `install.py` writes user config files: keep writes atomic, keep unparseable files
+  reported rather than replaced.
+
+## Claims
+
+The README and `bench/` state numbers. Don't add or edit one without rerunning the
+benchmark that produced it (`python bench/compare.py`, `python bench/questions.py`), and
+keep the rows that don't flatter us — the limitations section is deliberate.
+
+Every resolution bug gets the smallest fixture that would have caught it, in
+`tests/test_heimdall.py`. One test file, no fixtures directory, no frameworks.

heimdall_code-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Developing Heimdall
+
+```console
+git clone https://github.com/stPhoenix/heimdall && cd heimdall
+uv sync                       # Python 3.12+, runtime deps plus pytest and ruff
+uv run pytest                 # or: uv run python tests/test_heimdall.py
+uv run ruff format . && uv run ruff check .   # config lives in pyproject.toml
+uv run heimdall index .       # dogfood: the graph of this repo
+```
+
+Ruff owns the formatting, so don't argue with it — 120 columns, its line breaks. What it
+cannot do for you: `from __future__ import annotations`, a docstring saying *why* the
+module exists rather than what it does, and the Apache header on every new file.
+
+There is no CI. The gate is `uv run pytest && uv run ruff check .` before you push.
+
+## The map
+
+| | |
+|---|---|
+| `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/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`. |
+| `heimdall/mcp_server.py` | one server, every registered repo. Tools return assembled answers, not raw edges. |
+| `heimdall/registry.py` | `~/.heimdall/registry.json` (override with `HEIMDALL_HOME`). |
+| `heimdall/install.py` | writes agent configs. Self-checks against a fake `$HOME`: `python -m heimdall.install`. |
+| `skills/heimdall/SKILL.md` | the CLI skill — one copy, force-included into the wheel as `heimdall/SKILL.md`. |
+
+## 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
+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.
+
+## Tests
+
+One file, `tests/test_heimdall.py`, runnable with or without pytest. Every resolution bug
+found so far is pinned there by a fixture that reproduces it — function-scoped imports,
+`as` renames, class receivers, ambiguous receivers, recursion, decorators. Fix a
+resolution bug, add the smallest fixture that would have caught it.
+
+## Benchmark
+
+`bench/` scores Heimdall against GitNexus and graphify on a real repo, graded by a CPython
+`ast` oracle — see [bench/README.md](bench/README.md). It is not part of the test suite
+(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`.
+
+## Release
+
+Bump `version` in `pyproject.toml`, `__version__` in `heimdall/__init__.py` and `version`
+in `.claude-plugin/plugin.json` together, add the [CHANGELOG](CHANGELOG.md) entry, then:
+
+```console
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+[`.github/workflows/release.yml`](.github/workflows/release.yml) takes it from there —
+lint, tests, build, a smoke test that installs the built wheel and drives it, then upload.
+It refuses to publish if the tag and `pyproject.toml` disagree, because a PyPI version
+cannot be replaced afterwards.
+
+Credentials: none. The workflow uses PyPI trusted publishing, which needs a one-time
+publisher registered on PyPI (owner `stPhoenix`, repo `heimdall`, workflow `release.yml`,
+environment `pypi`) and a `pypi` environment in the repository settings. To publish by
+hand instead: `uv build && uv publish --token pypi-...`.
+
+The distribution is `heimdall-code`; the command is `heimdall`.

heimdall_code-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.