ph-code-graph 0.1.0__py3-none-any.whl

ph_code_graph/skills/code-graph/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: code-graph
+version: 1.0.0
+description: Understand an unfamiliar codebase by asking its graph — what a name is, who calls it, what a change breaks, what is biggest — instead of reading files to find out.
+argument-hint: "<what you are trying to find out>"
+allowed-tools: [code_index, code_graph, read, grep, glob]
+---
+
+# Reading a codebase by asking it
+
+You have `code_index` and `code_graph`. They answer questions about structure
+and they **never return source code** — every answer is a `path:start-end` you
+then `read`. Used in that order they replace most of the reading you would
+otherwise do to find out which two files mattered.
+
+## Index first, once
+
+```
+code_index(paths=["packages/thing/src"])
+```
+
+Point it at a package, not a monorepo. It re-parses only files whose contents
+changed, so running it again after your own edits is cheap and keeps every
+later answer current — do that rather than reasoning about a stale graph.
+
+If a query says no index exists, this is the step you skipped.
+
+## Then ask the question you actually have
+
+| you want to know | call |
+|---|---|
+| "there is something about X here" | `code_graph(mode="search", query="X in your own words")` |
+| "where exactly is `foo`" | `code_graph(mode="define", query="foo")` |
+| "what calls `foo`" | `code_graph(mode="callers", query="foo")` |
+| "what does `foo` use" | `code_graph(mode="callees", query="foo")` |
+| "what breaks if I change `foo`" | `code_graph(mode="impact", query="foo", distance=2)` |
+| "what are the big pieces here" | `code_graph(mode="entities", path="pkg/", kind="class")` |
+
+`search` takes **prose** and matches names and docstrings, so ask it the way you
+would ask a colleague. `define`/`callers`/`callees`/`impact` take an **exact
+symbol name**.
+
+## Then read the narrow thing
+
+Every row carries `path`, `start_line`, `end_line`. Feed those to `read` — with
+`offset`/`limit` around the span — rather than opening whole files. For
+`callers` and `callees`, `ref_path:ref_line` is the *call site* and
+`path:start_line` is the *definition*; they are usually different files, and the
+call site is normally what you want to see first.
+
+## Two things to hold in mind
+
+**Matching is by name.** Two `register` methods on two classes are one name to
+this index. When a result reports `definitions` greater than 1 the answer may
+mix them — run `mode="define"` to see the candidates and pick, rather than
+assuming the first is yours.
+
+**It is structure, not behaviour.** It cannot tell you what a function does,
+whether a branch is reachable, or what a value is at runtime. It tells you where
+to look. When the answer you need is *why*, read the code and its comments.
+
+## When to use `grep` instead
+
+When you know the exact string — an error message, a config key, a literal. This
+tool is for when you know the *idea* and not the spelling. They compose well:
+`code_graph` to find the region, `grep` to find every occurrence inside it.

ph_code_graph-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.5
+Name: ph-code-graph
+Version: 0.1.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.1.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. Normalised 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 materialises 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 materialising 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.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ph_code_graph/__init__.py,sha256=yZ_-2_lqcNebXl1CqodxHx2OvAVw8SYcJ7z5CCqP8Yo,35102
+ph_code_graph/_extract.py,sha256=UpPE-fAHHz9AO3ktcKHbjeKrypI2ZpGlrwNy_pzImF4,23756
+ph_code_graph/_store.py,sha256=dcQkUslTCFY8n7tBkjCO5Ggci2hPSWyNN48ITfwD5Z4,26964
+ph_code_graph/bundle.yaml,sha256=x3UoJbgQ6QUootM-M6rWZpDQT1sRGSCrtiBh2LFq1ms,1190
+ph_code_graph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ph_code_graph/skills/code-graph/SKILL.md,sha256=Jm4GPQG3gq_e1_7wbF_TenCN0M8Xbrta4o4YHIuqsew,2951
+ph_code_graph-0.1.0.dist-info/METADATA,sha256=Vk7orrjzvCDqaQIy43ZnXFnwhJ4TA2c5f8OLFZFEDC0,13501
+ph_code_graph-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+ph_code_graph-0.1.0.dist-info/entry_points.txt,sha256=4DPMS_RTRniZPXb59juSl5mpTpi0fHpwViZPCvffAgo,94
+ph_code_graph-0.1.0.dist-info/licenses/LICENSE,sha256=sN3yhtK25eQpVcewQbaq1k4A-_fWl3RkTf3QfGDh3ko,1070
+ph_code_graph-0.1.0.dist-info/RECORD,,

ph_code_graph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ph_code_graph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[ph.bundles]
+code-graph = ph_code_graph:BUNDLE
+
+[ph.plugins]
+code-graph = ph_code_graph:apply

ph_code_graph-0.1.0.dist-info/licenses/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.