wayfind 0.1.0__tar.gz

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

@@ -0,0 +1,38 @@
+name: release
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+# Trusted publishing requires `id-token: write`; no token is stored in the repo.
+# See https://docs.pypi.org/trusted-publishers/
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/wayfind/
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: The tag matches the pyproject version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PYVER="$(grep -E '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')"
+          if [ "$TAG" != "$PYVER" ]; then
+            echo "::error::tag $TAG does not match pyproject version $PYVER"
+            exit 1
+          fi
+
+      - run: uv sync --locked
+      - run: make check
+      - run: uv build
+      - name: Publish to PyPI (trusted publishing via uv)
+        run: uv publish --trusted-publishing always

wayfind-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,13 @@
+name: tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked
+      - run: make check

wayfind-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+*.egg-info/

wayfind-0.1.0/AGENTS.md

@@ -0,0 +1,37 @@
+# wayfind
+
+A tree-sitter map of a git repository: layout, outlines, callers, impact, and
+numbers (metrics, cycles, unused, diff) that report and never judge. Agents use
+it to read a codebase; CI reads its numbers and holds the thresholds itself.
+aegis depends on it from PyPI and mounts its CLI as `aegis map`.
+
+## What done means
+
+- `make check` passes: format, lint, typecheck and the tests. CI runs it on
+  every push and PR.
+- New behaviour ships with a test that builds a small git repository and runs
+  the CLI on it, as `tests/test_wayfind.py` does, watched failing first.
+- A change to a command or its output updates `README.md`, which is the user
+  reference. aegis's help page `code-map` describes the same commands; a change
+  users of `aegis map` would notice gets a line there when aegis next bumps its
+  pin.
+- English everywhere.
+
+## Where everything lives
+
+| What | Where |
+|---|---|
+| Every command and what it prints | `README.md` |
+| The design rules and their reasons | `DESIGN.md`, and the package docstring in `src/wayfind/__init__.py` |
+| Open work | GitHub issues |
+| Releases | `CHANGELOG.md`; a `vX.Y.Z` tag publishes to PyPI (`.github/workflows/release.yml`) |
+
+## Working here
+
+```bash
+uv sync
+make check
+uv run wayfind repo        # the map of this repository
+```
+
+Work lands through issue, branch, PR and green CI.

wayfind-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## v0.1.0
+
+- First release as its own package. The map was `aegis map` in aegis up to
+  2.11; it brings its history, the receiver types, `--exclude`, and the
+  `metrics`, `cycles`, `unused` and `diff` views.

wayfind-0.1.0/DESIGN.md

@@ -0,0 +1,27 @@
+# Design — wayfind
+
+The rules and their reasons are in the package docstring
+(`src/wayfind/__init__.py`); this file says how the modules divide the work.
+
+```
+src/wayfind/parse.py     one source file into definitions, references, facts and imports
+src/wayfind/specs.py     per-language query patterns: receiver types, bases, branches
+src/wayfind/index.py     the shared, mtime-refreshed index and name resolution
+src/wayfind/measures.py  metrics, cycles, unused and diff over the index
+src/wayfind/views.py     the plain-text views
+src/wayfind/cli.py       one typer subcommand per view; `app` is what aegis mounts
+```
+
+The index is one pickle per repository under the user's cache directory
+(`$XDG_CACHE_HOME/wayfind`), refreshed by mtime and size and replaced
+atomically, so every process of the user shares it. A cold index parses in a
+pool of processes.
+
+It needs no language server. An edge found by name only is printed with `?`;
+deeper levels of `callers` and `impact` follow sure edges only. What a language
+adds over name matching, receiver types, base classes and an exact branch
+count, is one `Spec` of query patterns in `specs.py`, so a language is data,
+not code.
+
+The numbers views report and never judge. A threshold belongs to whoever reads
+them: a `jq` filter, a review, or a CI linter reading `--json`.

wayfind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Piad Morffis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wayfind-0.1.0/Makefile

@@ -0,0 +1,15 @@
+.PHONY: check test lint format-check typecheck
+
+check: format-check lint typecheck test
+
+test:
+	uv run pytest -q
+
+lint:
+	uv run ruff check src/ tests/
+
+format-check:
+	uv run ruff format --check src/ tests/
+
+typecheck:
+	uv run ty check src/

wayfind-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: wayfind
+Version: 0.1.0
+Summary: A tree-sitter map of a git repository: layout, outlines, callers, impact and numbers, for agents and CI
+Project-URL: Repository, https://github.com/apiad/wayfind
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: tree-sitter-language-pack>=1.22
+Requires-Dist: tree-sitter>=0.25
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# wayfind
+
+A tree-sitter map of a git repository, for agents and for CI. It started as
+`aegis map` in [aegis](https://github.com/apiad/aegis), which now uses it as a
+library and mounts the same commands under that name.
+
+## Install
+
+```bash
+uv tool install wayfind        # or: uvx wayfind repo
+```
+
+`wayfind` reads a git repository with tree-sitter and answers what grep
+cannot say it answered completely: the repository's layout with each module's
+first doc line, a file's outline, every caller of a definition, and everything
+that depends on it. It runs in the shell, needs no server and works in any
+language the pack of tree-sitter grammars has, from Python and TypeScript to
+Go, Rust, Java and C.
+
+## Start with the layout
+
+Run `wayfind repo` in the repository for its top folders, with how many
+classes, functions and methods each holds. Give a folder and `--depth 2` to
+open it further: each file then shows its first doc line, which is often
+enough to know where to look. `wayfind outline <path>` lists a file's or a
+folder's definitions with their line, signature and first doc line, and
+`wayfind deps <path>` says which files use which.
+
+Read a whole file only once the map has said it is the one you need.
+`wayfind show <symbol>` prints one definition's source without the rest of
+its file.
+
+## Name a definition
+
+Every command that takes a symbol accepts a bare name (`save`), a class and
+method (`Store.put`), or a path and a name (`pkg/store.py:helper`), where the
+path may be any ending of the file's path. A name defined in several places
+answers for each; `wayfind find <name>` lists them.
+
+## Callers and impact
+
+`wayfind callers <symbol>` lists every call of a definition, grouped by
+file, as the enclosing definition and its line. `--depth 2` also lists the
+callers of those callers, indented. `wayfind impact <symbol>` counts every
+use, not only calls, and follows three levels by default: what you would have
+to check if you changed it, or what would break. `wayfind callees <symbol>` goes the other way.
+
+A call on a receiver, such as `self.queues.turn_ended()`, resolves through the
+receiver's type wherever the source states one: a parameter or variable
+annotation, a constructor call assigned to it, a class field, an import under
+another name. When nothing in the receiver's class types an attribute (it is
+set to `None` there and assigned from outside), the map takes the one class
+every assignment to an attribute of that name agrees on, preferring
+assignments through a receiver of the same class, and leaving out tests' fakes
+when it answers for code outside the tests. A call through a base class or
+protocol method also reaches every override in a subclass, since that is what
+may run: `callers` of an implementation lists the calls made through its
+protocol.
+
+An edge without a mark is sure. An edge ending in `?` is not: either the
+receiver's type is stated nowhere, so the call matched every method of that
+name, or the receiver may hold more than one class. A call on a receiver never
+matches a module-level function by name, and a call on a type from outside the
+repository (`Path`, `dict`, `json`) matches nothing. Deeper levels follow sure
+edges only.
+
+The receiver types work in Python, JavaScript and TypeScript. Other languages
+get the rest of the map with calls matched by name; another language is
+one more `Spec` in `src/wayfind/specs.py` (its docstring says how).
+
+## Numbers for a review
+
+Four views give numbers and no verdicts. Which numbers matter, and where a
+line falls, is yours to decide: each takes `--json`, and a gate or a review is
+a filter over it.
+
+- `wayfind metrics [path]` has one row per definition, file and
+  folder: lines, complexity (counted as ruff's C901 counts it for Python, and
+  as decision points for other languages), whether it has a doc, parameters
+  with a type out of all, a stated return type, uses of `Any`, calls on a
+  receiver of unknown type (the missing types that cost navigation), and
+  fan-in and fan-out. Folders carry which folders they use. The text view
+  ranks the top rows; `--sort complexity` or `fan-in` and `--top` change it.
+- `wayfind cycles [path]` lists the files, or with `--level package` the
+  folders, that use each other in a cycle, with one cycle spelled out. In
+  Python a use in an annotation counts.
+- `wayfind unused [path]` lists definitions no reference names outside
+  their own body, and those only tests name. It goes by name, so a function
+  reached through a string (a `getattr` dispatch, a route table, HTML) is
+  listed; dunders, decorated registrations, overrides, handlers assigned to
+  `on…` properties and members of object literals are left out.
+- `wayfind diff [base]` reads a branch: every definition the branch touched
+  since `base` (by default the merge-base with `origin/main`, uncommitted work
+  included), whether it was added, removed, moved or modified, its lines and
+  complexity before and after, the sure users outside the branch, and for a
+  removed one every place that still names it.
+
+For example, the definitions over 50 lines and those ruff's C901 would flag:
+
+```bash
+wayfind metrics src --json | jq '[.functions[] | select(.lines > 50)] | length'
+wayfind metrics src --json | jq -r '.functions[] | select(.complexity > 10) | .id'
+```
+
+## The index
+
+The first command in a repository parses every file `git ls-files` lists in
+a known language, in a pool of processes. That takes a few seconds on a
+thousand files, and stderr says how many it parsed. Ignored files are never
+indexed; `--exclude <path or glob>` (or `-x`, repeatable) leaves out more,
+such as a `legacy/` folder or generated code, from the views and from what a
+name may match. An excluded file keeps its place in the index, so changing
+the exclusions re-parses nothing. After that each command re-parses only the
+files whose modification time or size changed, so a query costs about a
+second. The index lives in the user's cache directory, one file per
+repository, and every session of the same user shares it.
+
+Each grammar downloads the first time the map meets its language. On a host
+without internet those files are skipped, and stderr names how many of which
+language.
+
+## Development
+
+```bash
+uv sync
+make check        # format, lint, typecheck, tests
+```
+
+## License
+
+MIT

wayfind-0.1.0/README.md

@@ -0,0 +1,131 @@
+# wayfind
+
+A tree-sitter map of a git repository, for agents and for CI. It started as
+`aegis map` in [aegis](https://github.com/apiad/aegis), which now uses it as a
+library and mounts the same commands under that name.
+
+## Install
+
+```bash
+uv tool install wayfind        # or: uvx wayfind repo
+```
+
+`wayfind` reads a git repository with tree-sitter and answers what grep
+cannot say it answered completely: the repository's layout with each module's
+first doc line, a file's outline, every caller of a definition, and everything
+that depends on it. It runs in the shell, needs no server and works in any
+language the pack of tree-sitter grammars has, from Python and TypeScript to
+Go, Rust, Java and C.
+
+## Start with the layout
+
+Run `wayfind repo` in the repository for its top folders, with how many
+classes, functions and methods each holds. Give a folder and `--depth 2` to
+open it further: each file then shows its first doc line, which is often
+enough to know where to look. `wayfind outline <path>` lists a file's or a
+folder's definitions with their line, signature and first doc line, and
+`wayfind deps <path>` says which files use which.
+
+Read a whole file only once the map has said it is the one you need.
+`wayfind show <symbol>` prints one definition's source without the rest of
+its file.
+
+## Name a definition
+
+Every command that takes a symbol accepts a bare name (`save`), a class and
+method (`Store.put`), or a path and a name (`pkg/store.py:helper`), where the
+path may be any ending of the file's path. A name defined in several places
+answers for each; `wayfind find <name>` lists them.
+
+## Callers and impact
+
+`wayfind callers <symbol>` lists every call of a definition, grouped by
+file, as the enclosing definition and its line. `--depth 2` also lists the
+callers of those callers, indented. `wayfind impact <symbol>` counts every
+use, not only calls, and follows three levels by default: what you would have
+to check if you changed it, or what would break. `wayfind callees <symbol>` goes the other way.
+
+A call on a receiver, such as `self.queues.turn_ended()`, resolves through the
+receiver's type wherever the source states one: a parameter or variable
+annotation, a constructor call assigned to it, a class field, an import under
+another name. When nothing in the receiver's class types an attribute (it is
+set to `None` there and assigned from outside), the map takes the one class
+every assignment to an attribute of that name agrees on, preferring
+assignments through a receiver of the same class, and leaving out tests' fakes
+when it answers for code outside the tests. A call through a base class or
+protocol method also reaches every override in a subclass, since that is what
+may run: `callers` of an implementation lists the calls made through its
+protocol.
+
+An edge without a mark is sure. An edge ending in `?` is not: either the
+receiver's type is stated nowhere, so the call matched every method of that
+name, or the receiver may hold more than one class. A call on a receiver never
+matches a module-level function by name, and a call on a type from outside the
+repository (`Path`, `dict`, `json`) matches nothing. Deeper levels follow sure
+edges only.
+
+The receiver types work in Python, JavaScript and TypeScript. Other languages
+get the rest of the map with calls matched by name; another language is
+one more `Spec` in `src/wayfind/specs.py` (its docstring says how).
+
+## Numbers for a review
+
+Four views give numbers and no verdicts. Which numbers matter, and where a
+line falls, is yours to decide: each takes `--json`, and a gate or a review is
+a filter over it.
+
+- `wayfind metrics [path]` has one row per definition, file and
+  folder: lines, complexity (counted as ruff's C901 counts it for Python, and
+  as decision points for other languages), whether it has a doc, parameters
+  with a type out of all, a stated return type, uses of `Any`, calls on a
+  receiver of unknown type (the missing types that cost navigation), and
+  fan-in and fan-out. Folders carry which folders they use. The text view
+  ranks the top rows; `--sort complexity` or `fan-in` and `--top` change it.
+- `wayfind cycles [path]` lists the files, or with `--level package` the
+  folders, that use each other in a cycle, with one cycle spelled out. In
+  Python a use in an annotation counts.
+- `wayfind unused [path]` lists definitions no reference names outside
+  their own body, and those only tests name. It goes by name, so a function
+  reached through a string (a `getattr` dispatch, a route table, HTML) is
+  listed; dunders, decorated registrations, overrides, handlers assigned to
+  `on…` properties and members of object literals are left out.
+- `wayfind diff [base]` reads a branch: every definition the branch touched
+  since `base` (by default the merge-base with `origin/main`, uncommitted work
+  included), whether it was added, removed, moved or modified, its lines and
+  complexity before and after, the sure users outside the branch, and for a
+  removed one every place that still names it.
+
+For example, the definitions over 50 lines and those ruff's C901 would flag:
+
+```bash
+wayfind metrics src --json | jq '[.functions[] | select(.lines > 50)] | length'
+wayfind metrics src --json | jq -r '.functions[] | select(.complexity > 10) | .id'
+```
+
+## The index
+
+The first command in a repository parses every file `git ls-files` lists in
+a known language, in a pool of processes. That takes a few seconds on a
+thousand files, and stderr says how many it parsed. Ignored files are never
+indexed; `--exclude <path or glob>` (or `-x`, repeatable) leaves out more,
+such as a `legacy/` folder or generated code, from the views and from what a
+name may match. An excluded file keeps its place in the index, so changing
+the exclusions re-parses nothing. After that each command re-parses only the
+files whose modification time or size changed, so a query costs about a
+second. The index lives in the user's cache directory, one file per
+repository, and every session of the same user shares it.
+
+Each grammar downloads the first time the map meets its language. On a host
+without internet those files are skipped, and stderr names how many of which
+language.
+
+## Development
+
+```bash
+uv sync
+make check        # format, lint, typecheck, tests
+```
+
+## License
+
+MIT

wayfind-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "wayfind"
+version = "0.1.0"
+description = "A tree-sitter map of a git repository: layout, outlines, callers, impact and numbers, for agents and CI"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+dependencies = [
+    "tree-sitter>=0.25",
+    "tree-sitter-language-pack>=1.22",
+    "typer>=0.24.1",
+]
+
+[project.scripts]
+wayfind = "wayfind.cli:app"
+
+[project.urls]
+Repository = "https://github.com/apiad/wayfind"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.9,<0.16",
+    "ty==0.0.29",
+    "pytest>=8.0.0",
+]
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wayfind-0.1.0/src/wayfind/__init__.py

@@ -0,0 +1,32 @@
+"""wayfind: a tree-sitter map of a git repository, for agents.
+
+It answers what grep cannot say it answered completely: the repository's
+layout with each module's first doc line, a file's outline, and every caller
+of a symbol and everything that depends on it.
+
+The rules, with their reasons:
+
+- **Heuristics, no language server.** tree-sitter parses any of the pack's
+  languages in milliseconds and needs nothing installed per language. The
+  pack's tags queries give definitions and calls for the languages that have
+  them; any other language falls back to nodes whose type reads like a
+  definition (parse.py).
+- **Every edge says how it was found.** An edge is *sure* when the name is
+  defined in the same file, when the using file's imports name both the
+  target's module and the name, or when the receiver's type is stated
+  (index.py says where from). Anything else is a name match, printed with
+  ``?``. Measured against jedi on aegis, where this map began, sure edges were right 96% of
+  the time and both kinds together found 97% of real references; the ``?``
+  edges were mostly common method names, so ``impact`` expands through sure
+  edges only (index.py).
+- **One index per repository, shared, refreshed by mtime.** Every session of
+  the user reads the same cache file, and each query re-parses only the files
+  whose mtime or size changed, so a warm query costs a stat per file. The file
+  is replaced atomically, so two sessions writing it at once lose a refresh,
+  never the index.
+- **Numbers, not verdicts.** metrics, cycles, unused and diff report per
+  definition, file and folder, with ``--json``; thresholds belong to whoever
+  reads them (measures.py).
+- **A CLI, not MCP tools.** Every MCP tool's schema rides on every request of
+  every session; a subcommand costs nothing until an agent runs it.
+"""