ph-code-graph 0.2.0__tar.gz

ph_code_graph-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Build and environment
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+jjt/
+w2/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+# Written by the guest's subprocess collectors and combined at the end of the
+# run; see `conftest.GUEST_COVERAGE_RC`.
+.coverage-guest*
+htmlcov/
+# Dropped at the repo root by pytest-textual-snapshot when a snapshot test
+# fails. The reference snapshots under `__snapshots__/` are the committed
+# expectation; this is the diff viewer for a run that did not match one.
+snapshot_report.html
+
+# Reference checkouts of the upstream projects this port reads from. Vendored
+# locally so the plans' citations are verifiable; never part of this repo.
+sources/
+
+# Local scratch
+.ph/
+*.local.yaml

ph_code_graph-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Charles Tabor
+
+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.

ph_code_graph-0.2.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.5
+Name: ph-code-graph
+Version: 0.2.0
+Summary: pH plugin: `code_index` and `code_graph`, a Python-native tree-sitter code graph with line-accurate answers.
+Project-URL: Homepage, https://github.com/chastabor/pH
+Project-URL: Repository, https://github.com/chastabor/pH
+Project-URL: Documentation, https://github.com/chastabor/pH/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/chastabor/pH/issues
+Author: Charles Tabor
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,code-graph,code-search,llm,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: ph-core==0.2.0
+Requires-Dist: tree-sitter-language-pack>=1.16
+Requires-Dist: tree-sitter>=0.25
+Description-Content-Type: text/markdown
+
+# ph-code-graph
+
+*`code_index` and `code_graph`: ask a codebase about its own shape, and get back
+a `path:start-end` you can `read`.*
+
+One row, `code-graph`, registering two tools. No Node, no Rust toolchain, no
+submodule — tree-sitter through a Python wheel, the graph in stdlib `sqlite3`.
+
+```bash
+phern --patch '{insert: [{id: code-graph, name: code-graph}]}' --profile llama \
+   -p "index packages/ph-core, then tell me what breaks if I change claim_slot"
+```
+
+## The two tools
+
+**`code_index(paths, glob?, forget?)`** parses each file through `ctx.fs` and
+records what it defines and references.
+
+**Nothing watches the filesystem.** There is no daemon and no file watcher: the
+index changes when `code_index` runs, and at no other moment. So after your own
+edits, run it again — which is cheap by design, and cheap enough to be a habit.
+
+**Incremental in two layers**, and the order matters:
+
+1. *Does this file need opening?* Asked of **git or jj**, which already hold a
+   content-addressed tree — `ph.seams.changes`. A file the version control
+   vouches for is never read. Measured on `packages/ph-core/src/ph`: a re-index
+   of 137 unchanged files went from 0.10 s to **0.03 s**, with zero reads and
+   zero hashes, on a `tree_state` costing 7 ms for the whole 509-file repo.
+2. *Is what I opened different?* Asked of the file's **sha256**, exactly as
+   before. Never an mtime — a checkout or a rebase moves timestamps without
+   moving content, and re-indexing because git touched them is a cost nobody
+   attributes correctly.
+
+Layer 1 only decides what to open, so the guarantee layer 2 makes is untouched:
+a skip is always justified by somebody's content hash, never by a clock. A tree
+with no version control loses layer 1 and nothing else.
+
+**`code_graph(mode, query?, …)`** answers six questions:
+
+| `mode` | question | what comes back |
+|---|---|---|
+| `search` | "something about workspace tiers" | symbols ranked by FTS5 over name + docstring |
+| `define` | "where exactly is `claim_slot`" | every definition of that name |
+| `callers` | "what calls this" | the calling symbol **and the calling line** |
+| `callees` | "what does this call" | the definitions it reaches |
+| `impact` | "what breaks if I change this" | transitive callers, ring by ring |
+| `entities` | "what is big here" | definitions by span, biggest first |
+
+Every result carries `path:start-line-end-line`. That is the point of the
+package: the model finds what matters in one call, then `read`s exactly that.
+
+## Using it from the RLM
+
+Nothing to do. Under Code Mode the model is handed one callable and a generated
+SDK listing, and *every* registered tool is in that listing — so these arrive as
+`await tools.code_index(...)` and `await tools.code_graph(...)` with no Code
+Mode work in this package at all. The `rlm-indexed` profile is `rlm-stable` plus
+this bundle and `ph-text-index`'s:
+
+```bash
+phern --profile rlm-indexed --provider llama --model <model> --mode tui
+```
+
+This package registers a `ph.bundles` entry point, which is what lets `ph-app`
+compose that profile without depending on this distribution — and what makes an
+install missing it see no `rlm-indexed` rather than one that fails at mount.
+
+## It is a name-based graph, and it says so
+
+A reference records the *name* it used, and `callers`/`callees` join on that
+name. Two `register` methods in two classes are one name to this index.
+
+Every answer that could be ambiguous carries `definitions` — how many places
+that name is defined — and the rendered text says so outright when it is above
+one, so the model sees the ambiguity instead of being handed one of the
+possibilities. `mode=define` is how it disambiguates.
+
+Resolving properly means an import graph, scope, and per-language type
+inference. In the Rust/Node CodeGraph that is 29,708 lines of TypeScript, and
+this package deliberately did not port it. Name-based matching answers most of
+what an agent actually asks and reports where it cannot — which is a better
+trade than a resolved graph for one language.
+
+## Why Python-native, and not a wrapper
+
+The obvious plan was to submodule the Rust/Node CodeGraph and wrap its kernel
+with maturin. The investigation said no, for three reasons in increasing order
+of importance:
+
+1. **`codegraph-kernel` is a `#[napi]` crate** — `crate-type = ["cdylib"]`
+   against `napi`/`napi-derive`. maturin builds PyO3/cffi extensions; wrapping
+   it means forking the crate to rewrite its boundary.
+2. **It is only an extractor.** Its whole export surface is `extract_file`,
+   `contract_info`, `grammar_info` and two `cfnptr` helpers — "tree-sitter
+   parse+extract with one JS boundary crossing per file", in its own words. It
+   also has a complete TS/WASM fallback, so it is an accelerator, not the core.
+3. **The intelligence is TypeScript**: `resolution/` 29,708 lines, `extraction/`
+   25,612, `mcp/` 13,940, `graph/` 6,023, `db/` 5,475 — 112,612 against the
+   kernel's 25,242. Wrapping the kernel gets a parser and leaves the product
+   behind.
+
+And the parser is the part Python already has. `tree-sitter-language-pack` 1.16
+ships **26 languages compiled into a 3.7 MB wheel, working offline** (python,
+ts/tsx/js, rust, go, java, csharp, c, cpp, ruby, php, swift, kotlin, scala,
+dart, lua, r, and more), with 371 available and the long tail fetched on
+demand — which this row never triggers implicitly.
+
+## Why `sqlite3` and not `pyturso`
+
+pH's session log runs on turso, so this is the exception and the reason is
+measured. Against a real 40 MB CodeGraph database (11,396 nodes, 36,830 edges),
+`pyturso` served indexed lookups, joins and aggregates correctly, and then:
+
+- **FTS5 is absent** — a `CREATE VIRTUAL TABLE … USING fts5` is invisible to
+  it, shadow tables included. That is `search`.
+- **`Recursive CTEs are not yet supported`** — that is `impact`.
+- **`json_extract` silently returns NULL** where SQLite returns the value:
+  `0.95` against `None`, same rows, same expression. A wrong answer with no
+  error is worse than a missing feature.
+
+Two of the six modes here are exactly the two turso cannot serve. Stdlib
+`sqlite3` (SQLite 3.45, FTS5 compiled in) costs no dependency and does all six.
+If turso grows both, `_store.py` changes one import.
+
+## Extraction: two passes, and why
+
+- **`process()`**, the pack's intelligence layer — definitions with kinds, the
+  file's imports, docstrings and comments. What it will not give is
+  *references*: `SymbolInfo` says a function exists, never who calls it.
+- **the tags query**, tree-sitter's own `tags.scm` per language — the data
+  GitHub's code navigation is built on. `@definition.*` and, crucially,
+  `@reference.call`.
+
+Measured over `packages/ph-core/src/ph`: 136 files and 1.58 MiB through
+`process()` in 219 ms, through the tags query in 108 ms. Indexing this
+repository's core takes 2.0 s end to end including the SQLite writes, and
+0.1 s when nothing has changed. Parsing twice is worth more than the parse it
+saves.
+
+Four details that are easy to get wrong, each handled once in `_extract` and
+each pinned by a test:
+
+- **`ProcessConfig` spans are 0-based** while tree-sitter points are 0-based and
+  every line pH shows a model is 1-based. Normalized on the way out, so nothing
+  downstream has to remember which pass a number came from. Getting this wrong
+  is an off-by-one pointer, which is what makes a model stop trusting a tool.
+- **`SymbolInfo.doc` is always `None`.** The pack does not populate it —
+  measured against a file full of docstrings. Trusting it would have shipped an
+  index with an empty `doc` column and a `search` mode matching names only. The
+  prose is on two other channels: `result.docstrings`, which carries the pack's
+  own `associated_item`, and `result.comments` for doc comments (Rust `///`,
+  TypeScript block comments, Go `//`). Those have no association, so the rule is
+  positional and narrow — the comment's last line must be *immediately* above
+  the definition's first.
+- **A comment node's `span.end_line` can be one past the line it occupies**,
+  because Rust's `///` node includes its trailing newline. Trusting it missed
+  the definition directly below *and* matched one a blank line away. The line
+  count comes from the comment's own text instead.
+- **TypeScript's tags query is half the story.** Its grammar extends
+  javascript's and upstream splits the queries to match, so `class`, `function`
+  and `call` live in the *javascript* query — a `.ts` file matched against the
+  typescript query alone yields two tags and no calls. `INHERITS` fixes that.
+
+## Per-language caveats
+
+Both are pinned by tests, so they are known shapes rather than surprises:
+
+- **C has definitions but no call references.** Its tags query ships no
+  `@reference.*` captures at all, so `callers`/`callees` are empty for C while
+  `search`, `define` and `entities` work.
+- **A bare Ruby send is invisible.** `helper` without parentheses parses as an
+  identifier rather than a `call`, so only `helper()` becomes an edge.
+
+Only `reference.call` is stored. The tags queries also emit `reference.type`,
+`reference.class` and more; each is a real relationship, but folding them in
+would make `callers` return every place that merely *mentions* a type.
+
+## Where things live
+
+- **the index**: `$PH_CACHE/code-graph/<digest of the workspace root>.db` — the
+  cache root because it is rebuildable from the source, and keyed by root so two
+  checkouts do not answer each other's questions. `path:` in the row's config
+  overrides it.
+- **the grammars**: `$PH_CACHE/tree-sitter`, set by the row at mount.
+
+That second one is not housekeeping. The pack materializes even its *bundled*
+grammars into a writable cache on first use — the wheel ships them as an
+archive, not as loadable libraries — and it **fails hard** when that directory
+cannot be created, rather than falling back to the wheel. Its own default is
+`$XDG_CACHE_HOME/…`, which is right on a laptop and wrong in a container with a
+read-only `HOME`; both measured. So the row hands over the root pH already
+designates for rebuildable artifacts, and refuses at mount with a `MountRefusal`
+sentence — not a `pathlib` traceback — when even that is unwritable.
+
+`TREE_SITTER_LANGUAGE_PACK_CACHE_DIR` still wins if an operator set it: their
+spelling is what makes the variable mean anything.
+
+One consequence worth expecting: the **first** index on a cold grammar cache
+pays for materializing the grammar. Measured on `packages/ph-core/src/ph`, that
+is 9 s cold against 2 s warm, and 0.1 s when nothing changed.
+
+Provision it on purpose rather than during someone's turn:
+
+```
+/code-graph status     # how many grammars are ready, and where they live
+/code-graph install    # load each one now, naming any that will not
+```
+
+A **command**, not a tool — a person asks the harness to provision, and it costs
+no model turn. `phern doctor` reports the same path and the index's state without
+mounting an agent. It matters less here than for `ph-text-index`, whose model is
+a download rather than an unpack, but the question should have one answer per
+plugin asked the same way.
+
+## The skill
+
+The package installs a `code-graph` skill, so an RLM under progressive
+disclosure sees one line in its catalog and can read the page when it needs
+it — index first, ask the question you actually have, then `read` the narrow
+thing; and that a name-based graph reports ambiguity rather than resolving it.
+
+Registered by the row rather than found by a directory scan, so it arrives
+exactly when the tools do and leaves with them — `skills-progressive` ships an
+empty `paths` on purpose, because a skill is something a distribution installs
+deliberately (I7).
+
+## Tests
+
+`tests/test_code_graph.py` runs the real parser and the real SQLite index.
+Three things it pins deliberately:
+
+- **line spans against the file** — every span is checked by slicing the actual
+  source at it, not against an expected number, because a pointer that is off
+  by one still looks plausible in a diff;
+- **the enclosing-symbol rule** — a call inside a nested closure belongs to the
+  closure, not the 40-line function around it;
+- **incrementality** — a second index pass over an unchanged tree parses nothing
+  and a touched-but-unmodified file stays unchanged.

ph_code_graph-0.2.0/README.md

@@ -0,0 +1,239 @@
+# ph-code-graph
+
+*`code_index` and `code_graph`: ask a codebase about its own shape, and get back
+a `path:start-end` you can `read`.*
+
+One row, `code-graph`, registering two tools. No Node, no Rust toolchain, no
+submodule — tree-sitter through a Python wheel, the graph in stdlib `sqlite3`.
+
+```bash
+phern --patch '{insert: [{id: code-graph, name: code-graph}]}' --profile llama \
+   -p "index packages/ph-core, then tell me what breaks if I change claim_slot"
+```
+
+## The two tools
+
+**`code_index(paths, glob?, forget?)`** parses each file through `ctx.fs` and
+records what it defines and references.
+
+**Nothing watches the filesystem.** There is no daemon and no file watcher: the
+index changes when `code_index` runs, and at no other moment. So after your own
+edits, run it again — which is cheap by design, and cheap enough to be a habit.
+
+**Incremental in two layers**, and the order matters:
+
+1. *Does this file need opening?* Asked of **git or jj**, which already hold a
+   content-addressed tree — `ph.seams.changes`. A file the version control
+   vouches for is never read. Measured on `packages/ph-core/src/ph`: a re-index
+   of 137 unchanged files went from 0.10 s to **0.03 s**, with zero reads and
+   zero hashes, on a `tree_state` costing 7 ms for the whole 509-file repo.
+2. *Is what I opened different?* Asked of the file's **sha256**, exactly as
+   before. Never an mtime — a checkout or a rebase moves timestamps without
+   moving content, and re-indexing because git touched them is a cost nobody
+   attributes correctly.
+
+Layer 1 only decides what to open, so the guarantee layer 2 makes is untouched:
+a skip is always justified by somebody's content hash, never by a clock. A tree
+with no version control loses layer 1 and nothing else.
+
+**`code_graph(mode, query?, …)`** answers six questions:
+
+| `mode` | question | what comes back |
+|---|---|---|
+| `search` | "something about workspace tiers" | symbols ranked by FTS5 over name + docstring |
+| `define` | "where exactly is `claim_slot`" | every definition of that name |
+| `callers` | "what calls this" | the calling symbol **and the calling line** |
+| `callees` | "what does this call" | the definitions it reaches |
+| `impact` | "what breaks if I change this" | transitive callers, ring by ring |
+| `entities` | "what is big here" | definitions by span, biggest first |
+
+Every result carries `path:start-line-end-line`. That is the point of the
+package: the model finds what matters in one call, then `read`s exactly that.
+
+## Using it from the RLM
+
+Nothing to do. Under Code Mode the model is handed one callable and a generated
+SDK listing, and *every* registered tool is in that listing — so these arrive as
+`await tools.code_index(...)` and `await tools.code_graph(...)` with no Code
+Mode work in this package at all. The `rlm-indexed` profile is `rlm-stable` plus
+this bundle and `ph-text-index`'s:
+
+```bash
+phern --profile rlm-indexed --provider llama --model <model> --mode tui
+```
+
+This package registers a `ph.bundles` entry point, which is what lets `ph-app`
+compose that profile without depending on this distribution — and what makes an
+install missing it see no `rlm-indexed` rather than one that fails at mount.
+
+## It is a name-based graph, and it says so
+
+A reference records the *name* it used, and `callers`/`callees` join on that
+name. Two `register` methods in two classes are one name to this index.
+
+Every answer that could be ambiguous carries `definitions` — how many places
+that name is defined — and the rendered text says so outright when it is above
+one, so the model sees the ambiguity instead of being handed one of the
+possibilities. `mode=define` is how it disambiguates.
+
+Resolving properly means an import graph, scope, and per-language type
+inference. In the Rust/Node CodeGraph that is 29,708 lines of TypeScript, and
+this package deliberately did not port it. Name-based matching answers most of
+what an agent actually asks and reports where it cannot — which is a better
+trade than a resolved graph for one language.
+
+## Why Python-native, and not a wrapper
+
+The obvious plan was to submodule the Rust/Node CodeGraph and wrap its kernel
+with maturin. The investigation said no, for three reasons in increasing order
+of importance:
+
+1. **`codegraph-kernel` is a `#[napi]` crate** — `crate-type = ["cdylib"]`
+   against `napi`/`napi-derive`. maturin builds PyO3/cffi extensions; wrapping
+   it means forking the crate to rewrite its boundary.
+2. **It is only an extractor.** Its whole export surface is `extract_file`,
+   `contract_info`, `grammar_info` and two `cfnptr` helpers — "tree-sitter
+   parse+extract with one JS boundary crossing per file", in its own words. It
+   also has a complete TS/WASM fallback, so it is an accelerator, not the core.
+3. **The intelligence is TypeScript**: `resolution/` 29,708 lines, `extraction/`
+   25,612, `mcp/` 13,940, `graph/` 6,023, `db/` 5,475 — 112,612 against the
+   kernel's 25,242. Wrapping the kernel gets a parser and leaves the product
+   behind.
+
+And the parser is the part Python already has. `tree-sitter-language-pack` 1.16
+ships **26 languages compiled into a 3.7 MB wheel, working offline** (python,
+ts/tsx/js, rust, go, java, csharp, c, cpp, ruby, php, swift, kotlin, scala,
+dart, lua, r, and more), with 371 available and the long tail fetched on
+demand — which this row never triggers implicitly.
+
+## Why `sqlite3` and not `pyturso`
+
+pH's session log runs on turso, so this is the exception and the reason is
+measured. Against a real 40 MB CodeGraph database (11,396 nodes, 36,830 edges),
+`pyturso` served indexed lookups, joins and aggregates correctly, and then:
+
+- **FTS5 is absent** — a `CREATE VIRTUAL TABLE … USING fts5` is invisible to
+  it, shadow tables included. That is `search`.
+- **`Recursive CTEs are not yet supported`** — that is `impact`.
+- **`json_extract` silently returns NULL** where SQLite returns the value:
+  `0.95` against `None`, same rows, same expression. A wrong answer with no
+  error is worse than a missing feature.
+
+Two of the six modes here are exactly the two turso cannot serve. Stdlib
+`sqlite3` (SQLite 3.45, FTS5 compiled in) costs no dependency and does all six.
+If turso grows both, `_store.py` changes one import.
+
+## Extraction: two passes, and why
+
+- **`process()`**, the pack's intelligence layer — definitions with kinds, the
+  file's imports, docstrings and comments. What it will not give is
+  *references*: `SymbolInfo` says a function exists, never who calls it.
+- **the tags query**, tree-sitter's own `tags.scm` per language — the data
+  GitHub's code navigation is built on. `@definition.*` and, crucially,
+  `@reference.call`.
+
+Measured over `packages/ph-core/src/ph`: 136 files and 1.58 MiB through
+`process()` in 219 ms, through the tags query in 108 ms. Indexing this
+repository's core takes 2.0 s end to end including the SQLite writes, and
+0.1 s when nothing has changed. Parsing twice is worth more than the parse it
+saves.
+
+Four details that are easy to get wrong, each handled once in `_extract` and
+each pinned by a test:
+
+- **`ProcessConfig` spans are 0-based** while tree-sitter points are 0-based and
+  every line pH shows a model is 1-based. Normalized on the way out, so nothing
+  downstream has to remember which pass a number came from. Getting this wrong
+  is an off-by-one pointer, which is what makes a model stop trusting a tool.
+- **`SymbolInfo.doc` is always `None`.** The pack does not populate it —
+  measured against a file full of docstrings. Trusting it would have shipped an
+  index with an empty `doc` column and a `search` mode matching names only. The
+  prose is on two other channels: `result.docstrings`, which carries the pack's
+  own `associated_item`, and `result.comments` for doc comments (Rust `///`,
+  TypeScript block comments, Go `//`). Those have no association, so the rule is
+  positional and narrow — the comment's last line must be *immediately* above
+  the definition's first.
+- **A comment node's `span.end_line` can be one past the line it occupies**,
+  because Rust's `///` node includes its trailing newline. Trusting it missed
+  the definition directly below *and* matched one a blank line away. The line
+  count comes from the comment's own text instead.
+- **TypeScript's tags query is half the story.** Its grammar extends
+  javascript's and upstream splits the queries to match, so `class`, `function`
+  and `call` live in the *javascript* query — a `.ts` file matched against the
+  typescript query alone yields two tags and no calls. `INHERITS` fixes that.
+
+## Per-language caveats
+
+Both are pinned by tests, so they are known shapes rather than surprises:
+
+- **C has definitions but no call references.** Its tags query ships no
+  `@reference.*` captures at all, so `callers`/`callees` are empty for C while
+  `search`, `define` and `entities` work.
+- **A bare Ruby send is invisible.** `helper` without parentheses parses as an
+  identifier rather than a `call`, so only `helper()` becomes an edge.
+
+Only `reference.call` is stored. The tags queries also emit `reference.type`,
+`reference.class` and more; each is a real relationship, but folding them in
+would make `callers` return every place that merely *mentions* a type.
+
+## Where things live
+
+- **the index**: `$PH_CACHE/code-graph/<digest of the workspace root>.db` — the
+  cache root because it is rebuildable from the source, and keyed by root so two
+  checkouts do not answer each other's questions. `path:` in the row's config
+  overrides it.
+- **the grammars**: `$PH_CACHE/tree-sitter`, set by the row at mount.
+
+That second one is not housekeeping. The pack materializes even its *bundled*
+grammars into a writable cache on first use — the wheel ships them as an
+archive, not as loadable libraries — and it **fails hard** when that directory
+cannot be created, rather than falling back to the wheel. Its own default is
+`$XDG_CACHE_HOME/…`, which is right on a laptop and wrong in a container with a
+read-only `HOME`; both measured. So the row hands over the root pH already
+designates for rebuildable artifacts, and refuses at mount with a `MountRefusal`
+sentence — not a `pathlib` traceback — when even that is unwritable.
+
+`TREE_SITTER_LANGUAGE_PACK_CACHE_DIR` still wins if an operator set it: their
+spelling is what makes the variable mean anything.
+
+One consequence worth expecting: the **first** index on a cold grammar cache
+pays for materializing the grammar. Measured on `packages/ph-core/src/ph`, that
+is 9 s cold against 2 s warm, and 0.1 s when nothing changed.
+
+Provision it on purpose rather than during someone's turn:
+
+```
+/code-graph status     # how many grammars are ready, and where they live
+/code-graph install    # load each one now, naming any that will not
+```
+
+A **command**, not a tool — a person asks the harness to provision, and it costs
+no model turn. `phern doctor` reports the same path and the index's state without
+mounting an agent. It matters less here than for `ph-text-index`, whose model is
+a download rather than an unpack, but the question should have one answer per
+plugin asked the same way.
+
+## The skill
+
+The package installs a `code-graph` skill, so an RLM under progressive
+disclosure sees one line in its catalog and can read the page when it needs
+it — index first, ask the question you actually have, then `read` the narrow
+thing; and that a name-based graph reports ambiguity rather than resolving it.
+
+Registered by the row rather than found by a directory scan, so it arrives
+exactly when the tools do and leaves with them — `skills-progressive` ships an
+empty `paths` on purpose, because a skill is something a distribution installs
+deliberately (I7).
+
+## Tests
+
+`tests/test_code_graph.py` runs the real parser and the real SQLite index.
+Three things it pins deliberately:
+
+- **line spans against the file** — every span is checked by slicing the actual
+  source at it, not against an expected number, because a pointer that is off
+  by one still looks plausible in a diff;
+- **the enclosing-symbol rule** — a call inside a nested closure belongs to the
+  closure, not the 40-line function around it;
+- **incrementality** — a second index pass over an unchanged tree parses nothing
+  and a touched-but-unmodified file stays unchanged.

ph_code_graph-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ph-code-graph"
+version = "0.2.0"
+description = "pH plugin: `code_index` and `code_graph`, a Python-native tree-sitter code graph with line-accurate answers."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Charles Tabor" }]
+keywords = ["agent", "llm", "tree-sitter", "code-search", "code-graph"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+# Both are hard dependencies and both are small: `tree-sitter` is the binding
+# and `tree-sitter-language-pack` is a 3.7 MB wheel with 26 languages compiled
+# in (371 available, the rest fetched on demand — which this row never does
+# implicitly; see `_extract.indexable`). No Rust toolchain, no Node, no
+# submodule: the graph itself is stdlib `sqlite3`.
+dependencies = ["ph-core==0.2.0", "tree-sitter>=0.25", "tree-sitter-language-pack>=1.16"]
+
+[project.urls]
+Homepage = "https://github.com/chastabor/pH"
+Repository = "https://github.com/chastabor/pH"
+Documentation = "https://github.com/chastabor/pH/blob/main/docs/README.md"
+Issues = "https://github.com/chastabor/pH/issues"
+
+[project.entry-points."ph.bundles"]
+code-graph = "ph_code_graph:BUNDLE"
+
+[project.entry-points."ph.plugins"]
+code-graph = "ph_code_graph:apply"
+
+[tool.uv.sources]
+ph-core = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ph_code_graph"]