callix 0.1.0__tar.gz

callix-0.1.0/.github/workflows/CI.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    # The ty/ruff tree is about 200 crates; a cold build takes a long time,
+    # a warm one finishes in a few minutes.
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      # Go is only needed at build time: the typescript-go bridge is linked
+      # statically, and users get a prebuilt wheel.
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+          cache-dependency-path: go/go.sum
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - uses: arduino/setup-task@v2
+
+      # Without the cache every run would rebuild all of ty from scratch.
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-all-crates: true
+
+      - name: Install
+        run: task install
+
+      - name: Lint
+        run: task lint
+
+      - name: Build
+        run: task build
+
+      - name: Stubs are up to date
+        run: task stubs:check
+
+      - name: Example
+        run: task example

callix-0.1.0/.github/workflows/bench.yml

@@ -0,0 +1,167 @@
+name: Benchmark
+
+# A load benchmark on real-world projects — report only, it never gates a
+# release. The matrix runs per language: one hung resolver neither blocks the
+# others nor eats their time.
+#
+# - workflow_dispatch — every language runs, and the README is refreshed and
+#   committed; run it by hand after a release when all the numbers are wanted.
+# - pull_request — only the languages whose adapter the PR touches. The result
+#   goes to the job summary; the README is left alone.
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: ["*"]
+
+permissions:
+  contents: read
+
+jobs:
+  changes:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    outputs:
+      # paths-filter's `changes` output is already a JSON array of the filters
+      # that matched — exactly what the matrix below needs.
+      langs: ${{ steps.filter.outputs.changes }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            python:
+              - "src/python/**"
+              - "benchmarks/**"
+              - ".github/workflows/bench.yml"
+            typescript:
+              - "src/typescript/**"
+              - "go/bridge.go"
+              - "benchmarks/**"
+              - ".github/workflows/bench.yml"
+            go:
+              - "src/golang/**"
+              - "go/bridge_go.go"
+              - "benchmarks/**"
+              - ".github/workflows/bench.yml"
+            rust:
+              - "src/rustlang/**"
+              - "benchmarks/**"
+              - ".github/workflows/bench.yml"
+
+  benchmark:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (needs.changes.result == 'success' && needs.changes.outputs.langs != '[]')
+    needs: [changes]
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        lang: >-
+          ${{ github.event_name == 'workflow_dispatch'
+              && fromJSON('["python","typescript","go","rust"]')
+              || fromJSON(needs.changes.outputs.langs) }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: dtolnay/rust-toolchain@stable
+      # Go is needed both to build the bridge and as the toolchain the Go
+      # resolver drives.
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+          cache-dependency-path: go/go.sum
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-all-crates: true
+
+      - name: Install rust-analyzer (the Rust resolver)
+        if: matrix.lang == 'rust'
+        run: |
+          rustup component add rust-analyzer
+          echo "$(dirname "$(rustup which rust-analyzer)")" >> "$GITHUB_PATH"
+
+      - name: Build
+        run: |
+          task install
+          task build
+
+      - name: Benchmark ${{ matrix.lang }}
+        run: task bench:run BENCH_LANG=${{ matrix.lang }}
+
+      - name: Report
+        if: always()
+        run: |
+          {
+            echo "## callix benchmark — ${{ matrix.lang }}"
+            echo
+            task bench:show VERSION="${{ github.sha }}"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: benchmark-results-${{ matrix.lang }}
+          path: benchmarks/results/
+
+  # Aggregates every language's results and refreshes the README. Manual runs
+  # only: a PR never commits anything.
+  render:
+    if: always() && github.event_name == 'workflow_dispatch'
+    needs: benchmark
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: benchmark-render
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Download results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: benchmark-results-*
+          path: benchmarks/results
+          merge-multiple: true
+
+      - name: Render into README
+        # benchmarks/results/ holds the committed results of the previous run
+        # overlaid with the fresh ones: languages that did not run this time
+        # keep their last known numbers.
+        run: task bench:render VERSION="${{ github.ref_name }}"
+
+      - name: Commit
+        run: |
+          if git diff --quiet -- README.md benchmarks/results; then
+            echo "Nothing changed"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md benchmarks/results
+          git commit -m "docs(bench): refresh benchmark metrics [skip ci]"
+          for i in 1 2 3 4; do
+            git push origin HEAD:main && exit 0
+            git pull --rebase origin main || true
+            sleep "$((2 ** i))"
+          done
+          echo "::error::could not push the README update"
+          exit 1

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

@@ -0,0 +1,172 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # 1. Version, changelog, tag. Wheels are built from that tag.
+  # ---------------------------------------------------------------------------
+  version:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: kenji-miyake/setup-git-cliff@v2
+
+      - name: Determine next version
+        id: version
+        run: task release:version
+
+      - name: Bump version
+        run: task release:bump VERSION=${{ steps.version.outputs.version }}
+
+      - name: Generate changelog
+        run: task release:changelog TAG=${{ steps.version.outputs.tag }}
+
+      - name: Commit and tag
+        run: task release:commit TAG=${{ steps.version.outputs.tag }}
+
+      - name: Push
+        run: task release:push TAG=${{ steps.version.outputs.tag }}
+
+  # ---------------------------------------------------------------------------
+  # 2. Wheels. One wheel cannot cover every platform: ty and the Go bridge to
+  #    typescript-go are linked inside. Thanks to abi3-py313 the matrix runs
+  #    over platforms only, not over Python versions.
+  # ---------------------------------------------------------------------------
+  wheels:
+    needs: version
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+          # A native ARM runner rather than QEMU inside the container: the ty
+          # tree alone is ~200 crates, and emulating that would not fit the
+          # timeout.
+          - os: ubuntu-24.04-arm
+            target: aarch64
+          - os: macos-latest
+            target: aarch64
+          # macos-latest is Apple Silicon, so the Intel wheel is cross-built;
+          # build.rs passes the architecture on to Go and clang.
+          - os: macos-latest
+            target: x86_64
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.version.outputs.tag }}
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.26"
+          cache-dependency-path: go/go.sum
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          # The manylinux container carries no Go, and build.rs cannot build
+          # the bridge without it, so Go is installed into the container first.
+          manylinux: ${{ startsWith(matrix.os, 'ubuntu') && '2_28' || 'auto' }}
+          before-script-linux: |
+            case "$(uname -m)" in
+              x86_64)  goarch=amd64 ;;
+              aarch64) goarch=arm64 ;;
+              *) echo "unsupported container arch $(uname -m)" >&2; exit 1 ;;
+            esac
+            curl -sSL "https://go.dev/dl/go1.26.0.linux-${goarch}.tar.gz" \
+              | tar -C /usr/local -xz
+            export PATH=$PATH:/usr/local/go/bin
+            go version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}-${{ matrix.target }}
+          path: dist/
+
+  # ---------------------------------------------------------------------------
+  # 3. The source distribution, so platforms outside the matrix can build.
+  # ---------------------------------------------------------------------------
+  sdist:
+    needs: version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.version.outputs.tag }}
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/
+
+  # ---------------------------------------------------------------------------
+  # 4. Publishing and the GitHub Release.
+  # ---------------------------------------------------------------------------
+  publish:
+    needs: [version, wheels, sdist]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.version.outputs.tag }}
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: arduino/setup-task@v2
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: astral-sh/setup-uv@v7
+      - uses: kenji-miyake/setup-git-cliff@v2
+
+      - name: Collect artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: task release:publish
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: task release:github TAG=${{ needs.version.outputs.tag }}

callix-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+/target
+
+# The typescript-go clone for the Go bridge: fetched by build.rs, ~370 MB
+/.ts-go
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+.pytest_cache/
+*.py[cod]
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+.venv/
+env/
+/bin/
+/build/
+develop-eggs/
+dist/
+eggs/
+/lib/
+/lib64/
+/parts/
+sdist/
+/var/
+/include/
+/man/
+venv/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+pip-selfcheck.json
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.cache
+nosetests.xml
+coverage.xml
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Rope
+.ropeproject
+
+# Django stuff:
+*.log
+*.pot
+
+.DS_Store
+
+# Sphinx documentation
+docs/_build/
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# Pyenv
+.python-version

callix-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-07-29
+### Bug Fixes
+
+- ci
+- ci release
+- **build**: unbreak the linux wheel and widen the platform matrix
+
+### Documentation
+
+- **bench**: refresh benchmark metrics [skip ci] by @github-actions[bot]
+- add CLAUDE.md
+
+### Features
+
+- reinit
+- update docs
+
+
+### New Contributors
+
+- @ made their first contribution
+- @github-actions[bot] made their first contribution
+
+
+<!-- generated by git-cliff -->

callix-0.1.0/CLAUDE.md

@@ -0,0 +1,172 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Language
+
+All code, comments, docs, commit messages and error strings in this repository
+are **English**. Keep it that way when adding code.
+
+## Commands
+
+Everything goes through [Task](https://taskfile.dev) — `taskfile.dist.yaml`.
+Run cargo through the tasks rather than directly (see *Build gotchas* below).
+
+```bash
+task                             # build → regenerate .pyi → run example/test.py
+task install                     # create .venv (Python 3.13) + maturin
+task build                       # maturin develop, release profile
+task lint                        # clippy with -D warnings (CI gate)
+task check                       # cargo check, no module build
+task test                        # cargo test + example smoke run
+task stubs / task stubs:check    # regenerate / verify committed .pyi
+task example -- example/foo.py   # run a different script
+DEBUG=1 task ...                 # switch every cargo task to the debug profile
+```
+
+There is no test suite yet: `cargo test` compiles but has no tests, and
+correctness is currently established by parity runs against graphlens (below).
+
+Benchmarks (`benchmarks/Taskfile.yaml`, included as `bench:`):
+
+```bash
+task bench:list [BENCH_LANG=rust]
+task bench:one PROJECT=gin-gonic/gin
+task bench:run [BENCH_LANG=go]
+task bench:render VERSION=0.1.0   # splices the table into README.md
+```
+
+## Architecture
+
+callix is a Rust rewrite of [graphlens](https://github.com/Neko1313/graphlens).
+Everything of substance lives in the Rust extension module `callix._core`;
+`python/callix/` is a facade of re-exports plus a thin `TyResolver` wrapper.
+
+### The graph contract
+
+`src/node.rs`, `src/relation.rs`, `src/graph.rs`, `src/ids.rs`, `src/span.rs`.
+14 `NodeKind`s, 12 `RelationKind`s, 1-based spans, and IDs that must stay
+deterministic: `sha256("{project}::{kind}::{qualified_name}")[:16]`. Boundary
+IDs deliberately depend only on `mechanism` + normalized key, which is what
+makes a server in one language and a client in another collapse into one node.
+
+Two ordering constraints are load-bearing and easy to break:
+
+- `Graph` stores nodes in an `IndexMap`, not a `HashMap` — insertion order is
+  part of the output and a `HashMap` silently reshuffles `CONTAINS` edges.
+- `src/roots.rs::sort_paths` compares paths **component by component**, the
+  way Python's `sorted()` over `pathlib.Path` does. Sorting by the whole
+  string diverges on neighbours like `src/v4-mini/…` vs `src/v4/…`.
+
+### Anatomy of a language adapter
+
+Each of `src/python/`, `src/typescript/`, `src/golang/`, `src/rustlang/`
+follows the same layout:
+
+| File | Role |
+|---|---|
+| `mod.rs` | thread-local tree-sitter parser, re-exports |
+| `detector.rs` / `deps.rs` | project roots, manifest parsing, import classification |
+| `visitor.rs` | CST walk → nodes, `DECLARES`/`CONTAINS`/`RESOLVES_TO` edges, occurrences |
+| `boundary.rs` | cross-language ports via tree-sitter queries |
+| `resolver.rs` | symbol resolution backend |
+| `adapter.rs` | orchestration of `analyze()` |
+
+**Visitors never create CALLS / REFERENCES / HAS_TYPE / INHERITS_FROM edges.**
+They emit `OccurrenceRef`s (`src/occurrence.rs`) with a role — `call`, `read`,
+`write`, `annotation`, `base` — which the resolution pass turns into edges.
+
+`analyze()` always runs three phases, and the order is not cosmetic:
+
+1. **Structure** for every sub-root, no resolution. The `SpanIndex` built next
+   has to span the whole workspace, or cross-root definitions have nothing to
+   bind to.
+2. **One resolver for the whole call.** Per-root resolvers would both lose
+   cross-root references and re-index the workspace once per root.
+3. **Boundaries**, so BOUNDARY nodes land in the graph after resolver edges.
+
+Resolution maps a definition position back to a node through
+`SpanIndex::lookup_name` (name spans, not full extents). Anything that misses
+falls through to an `EXTERNAL_SYMBOL` so the edge is never lost.
+
+### Node schemes differ per language
+
+Do not assume Python's shape elsewhere. `MODULE` is a dotted name in Python and
+TypeScript, a **package directory** in Go (its `qualified_name` equals the
+import path, so internal imports bind by direct lookup), and a Rust module path
+in `rustlang`. Rust dispatches `impl` blocks in a second pass because a type may
+be declared below its `impl`.
+
+### Resolvers: what is linked in and what is not
+
+| Language | Backend | External requirement |
+|---|---|---|
+| Python | `ty` linked as a library (`src/python/ty_embedded.rs`) | none |
+| TypeScript | typescript-go via a Go c-archive (`go/bridge.go`) | none |
+| Go | `go/packages` + `go/types` via the same c-archive (`go/bridge_go.go`) | Go toolchain |
+| Rust | `rust-analyzer scip` subprocess + own SCIP decoder (`src/rustlang/scip.rs`) | rust-analyzer + Cargo |
+
+Go and Rust cannot be compiled in: both need their standard library's sources
+and a real workspace load. `build.rs` clones typescript-go into `.ts-go/`
+(~370 MB, survives `cargo clean`) and builds `go/` into a c-archive. That
+c-archive is why **Windows is unsupported** — cgo emits a mingw-w64 GNU
+archive that will not link into the MSVC target; `build.rs` refuses up front.
+It also derives GOOS/GOARCH from the Rust target so an Apple Intel wheel can
+be cross-built on an Apple Silicon runner, and passes `-buildvcs=false`
+because `go build` otherwise fails where git will not read the checkout (a
+manylinux container mounts the workspace under another uid).
+
+Resolvers are swappable from Python — any object with `prepare`/`resolve_all`/
+`status` — as are dependency parsers (`can_parse`/`parse`). Rust calls them
+through the ordinary Python protocol.
+
+## Parity with graphlens
+
+This is the project's correctness harness. graphlens lives at
+`~/project/graphlens` with its own venv at `~/project/graphlens/.venv/bin/python`
+(callix's venv does not have graphlens's tree-sitter grammars installed).
+
+Method: build the same graph both ways → `to_dict()` →
+`json.dumps(sort_keys=True)` → `diff`. Every subtle bug found so far (key
+ordering, HashMap vs IndexMap, path sorting) surfaced only this way. When
+comparing structure only, use `Adapter(resolve=False)` on the callix side and a
+stub resolver on graphlens's; the metrics block will differ because callix skips
+the pass entirely, and that is expected.
+
+Re-snapshot graphlens baselines before trusting a diff — a stale dump once
+produced a fake 448k-line regression.
+
+**One intentional divergence, applied to all four languages.** When the resolver
+finds a definition it cannot name, the synthetic `EXTERNAL_SYMBOL` key includes
+the project-relative file path (`{role}@{path}:{line}:{col}`). graphlens omits
+the path, which merges distinct sites that share coordinates — 98% of external
+nodes on apache/superset. Expect diffs confined to those nodes' ids/names.
+
+## Build gotchas
+
+- **`PYO3_PYTHON`** is set globally in the Taskfile to `.venv/bin/python`.
+  `abi3-py313` refuses anything older than 3.13, and bare `cargo` otherwise
+  picks the first `python3` on PATH.
+- **All cargo tasks share one profile**, release by default. The ty/ruff tree is
+  ~200 crates; linting in debug while building in release compiles it twice.
+- **`get-size2` is pinned to `=0.10.0`** with a hand-written feature list.
+  Outside ruff's workspace the features are not inherited, and 0.10.3 moved to
+  `compact_str` 0.10 while ruff is on 0.9 — without the pin `ruff_python_ast`
+  does not compile at all.
+- **ty comes from a git `rev`** pinned across several `Cargo.toml` entries;
+  updating means changing all of them together and re-verifying.
+- Large SCIP indexes and Go builds respect `TMPDIR`; a small `/tmp` will fill.
+- `cargo fmt` is deliberately not a task — formatting is hand-tuned in places.
+
+## Stubs and release
+
+`python/callix/_core/__init__.pyi` is generated by `src/bin/stub_gen.rs` from
+the Rust doc comments and **is committed**; CI fails on drift. Module constants
+and an exception-base-class fixup are appended manually there because
+pyo3-stub-gen 0.23 does not emit them correctly.
+
+Versions live **only** in `Cargo.toml` (`pyproject.toml` declares it `dynamic`).
+`cliff.toml` drives both conventional-commit parsing and the changelog template;
+its `[remote.github]` owner/repo must match the real repository or git-cliff
+panics on a 404. Wheels are built by a per-platform matrix in `release.yml` —
+one wheel cannot cover every platform with ty and the Go bridge linked inside.