codegraph-ir 0.3.0__tar.gz → 0.4.0__tar.gz

{codegraph_ir-0.3.0 → codegraph_ir-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-ir
-Version: 0.3.0
+Version: 0.4.0
 Summary: The deterministic contract layer for AI-modified codebases — effects, purity, contracts, and blast radius, with zero LLM calls.
 Project-URL: Homepage, https://github.com/asonkiya/llm-semantic-compilers
 Project-URL: Repository, https://github.com/asonkiya/llm-semantic-compilers
@@ -43,8 +43,9 @@ Requires-Python: >=3.11
 Requires-Dist: jsonschema>=4.21
 Requires-Dist: networkx>=3.2
 Requires-Dist: pydantic>=2.6
-Requires-Dist: tree-sitter-go<0.25,>=0.23
+Requires-Dist: tree-sitter-go<0.24,>=0.23
 Requires-Dist: tree-sitter-python<0.24,>=0.23
+Requires-Dist: tree-sitter-rust<0.23.3,>=0.23
 Requires-Dist: tree-sitter-typescript<0.24,>=0.23
 Requires-Dist: tree-sitter<0.25,>=0.23
 Requires-Dist: typer>=0.12
@@ -92,7 +93,7 @@ For library/agent use in a project: `uv pip install codegraph-ir`
 ## The local loop
 
 ```bash
-cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
+cgir scan .                          # build the .cgir index (Python, TypeScript, Go, Rust)
 cgir watch .                         # keep it live: re-scan + show contract drift on save
 cgir pack app.service.charge --repo .   # minimal context bundle for one component
 cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests
@@ -133,6 +134,27 @@ agent-PR case study.
 Setup guide for agents (MCP config + CLAUDE.md snippet): [`docs/agents.md`](./docs/agents.md).
 Or via the [pre-commit framework](https://pre-commit.com): hook id `cgir-contract-check`.
 
+## How it compares (honestly)
+
+| | **CGIR** | CodeGraph-style MCP graphs | Greptile / CodeRabbit | import-linter / ArchUnit | oasdiff / Pact |
+|---|---|---|---|---|---|
+| Effects & purity contracts per function | ✅ | ❌ | ❌ LLM judgment | ❌ | ❌ |
+| Invariants declared in source (`# cgir: pure`) & enforced | ✅ | ❌ | ❌ | imports only | API boundary only |
+| Deterministic (same input → same verdict, zero LLM) | ✅ | ✅ structure only | ❌ | ✅ | ✅ |
+| Catches "service silently stopped calling the backend" | ✅ | ❌ | sometimes | ❌ | at spec boundaries |
+| Blast radius + coverage-grounded test selection | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Agent context over MCP | ✅ contract packs | ✅ broader retrieval | ❌ | ❌ | ❌ |
+| Finds logic bugs | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Languages | 4 builtin + [plugin API](./docs/languages.md) | 30+ | most | per-tool | spec-level |
+| Cycle / layer rules | ✅ | ❌ | ❌ | ✅ mature | ❌ |
+| Cost | free, local | mostly free | ~$24–30/user/mo | free | free |
+
+Where CGIR loses, we say so: it does **not** find logic bugs (a subtly wrong
+algorithm with unchanged effects passes the gate — pair it with tests or a
+reviewer), supports 3 languages not 38, and its effect detection is static
+analysis with [documented, measured limits](./docs/gate-noise.md) — every
+tag carries a confidence tier so you know which claims are verified.
+
 ## Docs
 
 - [`docs/strategy.md`](./docs/strategy.md) — positioning: the deterministic contract layer

{codegraph_ir-0.3.0 → codegraph_ir-0.4.0}/README.md

@@ -23,7 +23,7 @@ For library/agent use in a project: `uv pip install codegraph-ir`
 ## The local loop
 
 ```bash
-cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
+cgir scan .                          # build the .cgir index (Python, TypeScript, Go, Rust)
 cgir watch .                         # keep it live: re-scan + show contract drift on save
 cgir pack app.service.charge --repo .   # minimal context bundle for one component
 cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests
@@ -64,6 +64,27 @@ agent-PR case study.
 Setup guide for agents (MCP config + CLAUDE.md snippet): [`docs/agents.md`](./docs/agents.md).
 Or via the [pre-commit framework](https://pre-commit.com): hook id `cgir-contract-check`.
 
+## How it compares (honestly)
+
+| | **CGIR** | CodeGraph-style MCP graphs | Greptile / CodeRabbit | import-linter / ArchUnit | oasdiff / Pact |
+|---|---|---|---|---|---|
+| Effects & purity contracts per function | ✅ | ❌ | ❌ LLM judgment | ❌ | ❌ |
+| Invariants declared in source (`# cgir: pure`) & enforced | ✅ | ❌ | ❌ | imports only | API boundary only |
+| Deterministic (same input → same verdict, zero LLM) | ✅ | ✅ structure only | ❌ | ✅ | ✅ |
+| Catches "service silently stopped calling the backend" | ✅ | ❌ | sometimes | ❌ | at spec boundaries |
+| Blast radius + coverage-grounded test selection | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Agent context over MCP | ✅ contract packs | ✅ broader retrieval | ❌ | ❌ | ❌ |
+| Finds logic bugs | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Languages | 4 builtin + [plugin API](./docs/languages.md) | 30+ | most | per-tool | spec-level |
+| Cycle / layer rules | ✅ | ❌ | ❌ | ✅ mature | ❌ |
+| Cost | free, local | mostly free | ~$24–30/user/mo | free | free |
+
+Where CGIR loses, we say so: it does **not** find logic bugs (a subtly wrong
+algorithm with unchanged effects passes the gate — pair it with tests or a
+reviewer), supports 3 languages not 38, and its effect detection is static
+analysis with [documented, measured limits](./docs/gate-noise.md) — every
+tag carries a confidence tier so you know which claims are verified.
+
 ## Docs
 
 - [`docs/strategy.md`](./docs/strategy.md) — positioning: the deterministic contract layer

{codegraph_ir-0.3.0 → codegraph_ir-0.4.0}/docs/languages.md

@@ -28,6 +28,7 @@ full test suite green.
 | 3 | ingest structural dispatch + attr extraction (normalized `Declaration`s) | ✅ done |
 | 4 | `TypeScriptAdapter` + per-file language dispatch | ✅ done |
 | 5 | `GoAdapter` (package=directory merge, struct-field DI, panic≙raise) | ✅ done |
+| 6 | `RustAdapter` (agent-written from the docs, reviewed & promoted; structs/impl, use-trees, match CFG) | ✅ done |
 
 **Two languages ship (Python, TypeScript); a mixed repo scans both.**
 Zero grammar node-type strings remain outside `cgir/languages/`. The CFG builder is pure topology over statement
@@ -66,3 +67,46 @@ closure, symbol-table resolution, slicing, and all seven product surfaces.
 Register it in `cgir/languages/__init__.py:ADAPTERS`. The effect *taxonomy*
 (`io`/`net`/`fs`/`db`/`nondeterm`/`raise`) is language-neutral and fixed in
 `analyses/effects.py`; the adapter only decides which calls map to which tag.
+
+**Full authoring guide: [`writing-an-adapter.md`](./writing-an-adapter.md)** — self-contained; written so an implementer (human or agent) needs no other source.
+
+## Packaging a language plugin
+
+Adapters are discovered via the ``cgir.languages`` entry-point group — no
+fork needed. A minimal plugin package:
+
+```toml
+# pyproject.toml of cgir-rust
+[project]
+name = "cgir-rust"
+dependencies = ["codegraph-ir", "tree-sitter-rust"]
+
+[project.entry-points."cgir.languages"]
+rust = "cgir_rust:RustAdapter"
+```
+
+```python
+# cgir_rust/__init__.py
+from cgir.languages.base import ADAPTER_API_VERSION, LanguageAdapter
+
+class RustAdapter(LanguageAdapter):
+    name = "rust"
+    file_extensions = (".rs",)
+    api_version = ADAPTER_API_VERSION
+    # implement: parse, locate_function, direct_effects, call_sites,
+    # function_body, block_statements, describe_statement,
+    # module_declarations — see GoAdapter for the most recent template.
+    # Optional (defaults provided): direct_effects_confidence,
+    # global_declared_names.
+```
+
+`pip install cgir-rust` and `cgir languages` shows it. Safety rules:
+builtins win extension conflicts; a plugin that fails to load, isn't a
+`LanguageAdapter`, or reuses a language name is skipped with a warning —
+a broken plugin never crashes cgir. An `api_version` mismatch warns but
+loads (new adapter methods get base-class defaults, so older plugins
+usually keep working).
+
+Start from `src/cgir/languages/go.py` — the newest adapter and the best
+template — and mirror `tests/unit/test_go_adapter.py` for the expected
+pipeline-level test coverage.

{codegraph_ir-0.3.0 → codegraph_ir-0.4.0}/docs/status.md

@@ -79,6 +79,9 @@ cgir scan tests/fixtures/python_sample --out /tmp/cgir-out
 | `forbid-cycle` (Tarjan SCCs) + `layers` rules in lint | done | `report/lint.py:_cycle_violations`, `_layer_violations` |
 | Coverage-grounded test linkage (.coverage/coverage.json contexts ∪ static; pack test sources capped) | done | `analyses/coverage_link.py` |
 | LSP diagnostics (`cgir lsp`, `cgir[lsp]` extra): pin violations as errors, gate drift as warnings, on save | done | `src/cgir/api/lsp_server.py`, `docs/lsp.md` |
+| Language plugin registry (`cgir.languages` entry points, `cgir languages`, ADAPTER_API_VERSION; builtins win conflicts, broken plugins degrade to warnings) | done | `languages/registry.py:discover_adapters` |
+| Adapter authoring guide, validated by a docs-only agent experiment (Rust adapter, 36/36, 9/9 bar; gaps folded back; PinIndex line_comment fix) | done | `docs/writing-an-adapter.md`, `examples/rust-adapter/` |
+| Rust adapter (structs+impl methods w/ field DI, use-tree imports, match/loop CFG, effect tiers; agent-written, reviewed+promoted) | done | `src/cgir/languages/rust.py` |
 | Entrypoint recognition (HTTP/CLI/task decorators) | done | `src/cgir/analyses/entrypoints.py` |
 | Context packer (`cgir pack`, budget-aware, type closure + docstrings + raises) | done | `src/cgir/report/pack.py` |
 | Docstring / raises / module-variable extraction | done | `tree_sitter_source._docstring_text`, `_raised_names`, `_add_module_variables` |
@@ -98,7 +101,7 @@ cgir scan tests/fixtures/python_sample --out /tmp/cgir-out
 
 ## Test coverage
 
-`pytest -q` runs 498 tests, all green (the table below lists the load-bearing files; newer suites — `test_impact.py`, `test_watch.py`, `test_hook.py`, `test_python_di.py`, `test_typescript_adapter.py`, `test_diff.py` — are described by their docstrings):
+`pytest -q` runs 541 tests, all green (the table below lists the load-bearing files; newer suites — `test_impact.py`, `test_watch.py`, `test_hook.py`, `test_python_di.py`, `test_typescript_adapter.py`, `test_diff.py` — are described by their docstrings):
 
 | File | Covers |
 |---|---|

codegraph_ir-0.4.0/docs/writing-an-adapter.md

@@ -0,0 +1,309 @@
+# Writing a language adapter
+
+This document is **self-contained**: everything needed to implement a new
+language for CGIR without reading its source. An adapter is one class
+implementing ~8 methods over a tree-sitter grammar; every downstream
+feature — effects, purity, kind classification, pins, packs, blast radius,
+the pre-commit gate, the LSP — works on your language for free.
+
+## The mental model
+
+CGIR's pipeline is language-neutral. Only *grammar extraction* is per
+language, behind the `LanguageAdapter` ABC:
+
+1. **Ingest** calls `module_declarations` to get normalized declarations
+   (functions, classes, imports, variables) and builds the graph.
+2. **Call graph** calls `call_sites` per function and resolves callees via
+   language-neutral symbol tables.
+3. **CFG** calls `function_body` / `block_statements` /
+   `describe_statement` per function; the *topology* (branch wiring, loop
+   back-edges) is built centrally — you only classify statements.
+4. **Effects** calls `direct_effects_confidence` per function; transitive
+   propagation is central.
+
+You never build graph nodes or edges. You translate grammar shapes into
+the descriptor dataclasses below.
+
+## Grammar version compatibility (check first)
+
+tree-sitter grammar wheels ship a compiled language ABI; the `tree-sitter`
+core only accepts a range. If `Language(...)` raises
+``Incompatible Language version``, pin an older grammar wheel (e.g.
+``tree-sitter-rust<0.24`` against ``tree-sitter 0.24``).
+
+## Setup
+
+```python
+import tree_sitter_rust  # any tree-sitter grammar package
+from tree_sitter import Language, Parser
+from tree_sitter import Node as TSNode
+
+from cgir.languages.base import (
+    ADAPTER_API_VERSION, AssignDesc, BranchDesc, CallSite, CaseDesc,
+    ClassDecl, Declaration, FunctionDecl, ImportDecl, LanguageAdapter,
+    LoopDesc, MatchDesc, ParamDecl, PinIndex, ReturnDesc, SimpleDesc,
+    StatementDesc, TryDesc, VariableDecl, WithDesc,
+)
+
+class RustAdapter(LanguageAdapter):
+    name = "rust"                      # unique language name
+    file_extensions = (".rs",)         # extensions this adapter claims
+    api_version = ADAPTER_API_VERSION  # currently 1
+
+    def __init__(self) -> None:
+        self._parser = Parser(Language(tree_sitter_rust.language()))
+```
+
+Useful helper you'll write once: `node.text` returns the node's source
+bytes (offset-safe); decode with `errors="replace"`.
+
+**Comment node types:** grammars disagree (`comment` in python/ts/go;
+`line_comment`/`block_comment` in rust/c/java). `PinIndex` handles all of
+these (`cgir.languages.base.COMMENT_NODE_TYPES`) — but your
+`block_statements` comment filter must use *your grammar's* comment types.
+
+## The required methods, exactly
+
+### `parse(self, source: bytes) -> TSNode`
+Return `self._parser.parse(source).root_node`.
+
+### `locate_function(self, root, name: str, start_row: int) -> TSNode | None`
+Find the function/method definition node whose **name** matches and whose
+**start row equals `start_row` (0-based)**. Analyses call this to re-find a
+function from graph metadata; if it returns None for a function, no
+analysis runs on it. Walk the whole tree (functions nest inside classes/
+impl blocks).
+
+### `module_declarations(self, root, source: bytes, module_name: str, rel_path: str) -> list[Declaration]`
+Walk the module's top level and return normalized declarations.
+`module_name` is the dotted module path derived from the file path
+(`internal/store/keys.rs` → `internal.store.keys`); `rel_path` is the
+repo-relative file path (for path-based import specifiers).
+
+Declaration shapes (all carry `node: TSNode` — used for line spans):
+
+- **`FunctionDecl(node, name, params, signature, returns, doc, raises,
+  decorators, free_names, pins)`**
+  - `params`: `list[ParamDecl(name, node)]` — **exclude** the implicit
+    receiver (`self`/`this`).
+  - `signature`: human-readable, e.g. `"add(a: i64, b: i64) -> i64"`.
+  - `returns`: return-type text or None.
+  - `doc`: docstring/doc-comment text, `""` if none.
+  - `raises`: exception-ish names; for panic-style languages return
+    `["panic"]` when the body contains a panic, else `[]`. For
+    Result/error-value languages (Rust `?`, Go `error` returns), error
+    *values* are not raises — only aborts (panic) count.
+  - `decorators`: attribute/annotation strings (may be `[]`).
+  - `free_names`: identifiers the body references that aren't locally
+    bound (feeds context packing; `[]` is acceptable v1).
+  - `pins`: see **Pins** below.
+- **`ClassDecl(node, name, methods, fields)`** — for any named type that
+  owns methods or fields (structs, impl targets, interfaces).
+  - `methods`: list of FunctionDecl (their params exclude the receiver).
+  - `fields`: `dict[field_name, type_name]` — **powers DI resolution**: a
+    call `self.client.fetch()` resolves through the declared type of
+    `client`. For plain data shapes (structs without methods) fields also
+    feed shape-drift detection; use the base type name for DI-relevant
+    fields (strip pointers/references), full type text is fine for
+    data-only shapes.
+- **`ImportDecl(node, target, alias)`** — `target` is the imported module
+  as a **dotted path** (`std::collections::HashMap` →
+  `std.collections.HashMap`); `alias` is the local name it binds (the last
+  segment when unaliased). Resolution against in-repo modules happens
+  centrally by exact/unique-suffix match on dotted module names.
+- **`VariableDecl(node, name)`** — module-level constants/statics.
+
+### `call_sites(self, func_node, source) -> list[CallSite]`
+`CallSite = tuple[str, list[str], int]` — (dotted callee text, argument
+identifier names, 0-based line). Rules:
+- A plain call `f(x)` → `("f", ["x"], line)`.
+- A path/method call → dotted text: `store::save(k)` → `"store.save"`;
+  `client.fetch(id)` → `"client.fetch"`.
+- **Receiver normalization (required for DI):** inside a method, calls
+  through the method's own receiver must be emitted with the literal
+  receiver replaced by `self`: in `fn sync(&self)` a call
+  `self.client.fetch(id)` → `"self.client.fetch"`. (In Go, where receivers
+  are arbitrarily named, `s.client.Fetch` must become
+  `"self.client.Fetch"`.) The central resolver keys on the `self.`/`this.`
+  prefix + the owning class's `fields` map.
+- Skip panic/raise intrinsics (they're effects, not calls).
+
+### `direct_effects(self, func_node, source, aliases) -> set[str]`
+Effect tags directly present in the body. Tags: `io`, `net`, `fs`, `db`,
+`nondeterm`, `raise`. `aliases` maps local import names → absolute dotted
+targets (`r` → `requests`), built centrally from your ImportDecls —
+normalize dotted callees through it before matching your tables.
+Implement as `return set(self.direct_effects_confidence(...))`.
+
+### `direct_effects_confidence(self, func_node, source, aliases) -> dict[str, str]`
+The real classifier: `{tag: "high" | "lexical"}`.
+- `"high"`: exact or prefix matches against curated tables of known APIs
+  (`reqwest.`, `std.fs.`, `println!`) — ideally alias-normalized.
+- `"lexical"`: guesses from bare method suffixes or receiver names
+  (`anything.now()`, `db.query(...)` gated only by the receiver being
+  named `db`). These are *reported but don't fail builds by default* — be
+  honest about which of your rules are guesses.
+If a tag matches both ways, high wins. Raise/panic detection is `"high"`.
+
+### `function_body(self, func_node) -> TSNode | None`
+The body block node (usually `child_by_field_name("body")`).
+
+### `block_statements(self, block) -> list[TSNode]`
+The block's statement nodes, comments filtered
+(`[c for c in block.named_children if c.type != "comment"]`).
+
+### `describe_statement(self, node, source) -> StatementDesc`
+Classify one statement into exactly one descriptor. The CFG builder wires
+topology from these; **you never recurse into sub-blocks yourself** — you
+hand back the sub-block *nodes* and the builder calls you again for their
+statements.
+
+- **`AssignDesc(writes, mutates, reads)`** — assignments/let-bindings.
+  `writes`: plain names bound; `mutates`: base names of attribute/index
+  targets (`self.x = v` → mutates `["self"]`, `xs[0] = v` → `["xs"]`);
+  `reads`: identifiers read on the RHS.
+- **`BranchDesc(reads, consequence, else_block, next_branch)`** — an
+  if-arm. `reads`: condition identifiers. `consequence`: then-block node.
+  For `else if`, set `next_branch` to the nested if node (it will be
+  described again); for a plain `else`, set `else_block` to its block.
+- **`LoopDesc(reads, writes, body)`** — all loop forms. `writes`: loop
+  variables (`for x in xs` → `["x"]`).
+- **`ReturnDesc(reads, mutates)`** — returns; `reads` from the returned
+  expression.
+- **`MatchDesc(cases=[CaseDesc(node, reads, consequence)])`** — match/
+  switch. `reads`: the scrutinee identifiers (repeat per case is fine);
+  `consequence`: the case's body node (the case node itself is acceptable
+  when the grammar nests statements directly under it).
+- **`TryDesc(body, handlers=[HandlerDesc(node, writes, block)], else_block,
+  finally_block)`** — try/catch shapes; skip if the language has none.
+- **`WithDesc(writes, reads, body)`** — resource-acquisition headers;
+  skip if none.
+- **`SimpleDesc(reads, mutates)`** — everything else (expression
+  statements). Put mutator-method receivers in `mutates` if you track
+  them; `reads` from the expression.
+
+Purity note: a function is classified `pure_function` only if it has no
+impure effects **and** no caller-observable mutation — `mutates` on a
+parameter or module global is what flips it to `state_transformer`.
+
+### Optional: `global_declared_names(self, func_node, source) -> set[str]`
+Names the function declares as outer-scope (Python `global`/`nonlocal`).
+Assignments to them count as mutations. Default: empty set — correct for
+most languages.
+
+## Pins (required wiring in `module_declarations`)
+
+Pins are `cgir:` comment pragmas (`// cgir: pure`). `PinIndex` does the
+extraction; you wire it:
+
+```python
+def module_declarations(self, root, source, module_name, rel_path):
+    pin_index = PinIndex(root, source)   # works on any grammar with "comment" nodes
+    ...
+    # per definition — pass the OUTERMOST node (so a pin above an
+    # attribute/export/pub keyword is found):
+    fn = FunctionDecl(..., pins=pin_index.for_definition(outermost_node))
+    ...
+    # module-level pins: a header comment block applies to every function
+    # in the file — UNLESS it sits directly above a pinnable definition
+    # (then it's that definition's pin). Pass the first decl's row only
+    # when that first decl is a function/class-like node; imports and
+    # plain statements must pass None-equivalent:
+    first = next((c for c in root.named_children if c.type != "comment"), None)
+    pinnable = {"function_item", "struct_item", "impl_item"}  # your grammar's types
+    module_pins = pin_index.module_pins(
+        first.start_point[0] if first is not None and first.type in pinnable else None
+    )
+    if module_pins:
+        for decl in decls:
+            if isinstance(decl, FunctionDecl):
+                decl.pins = sorted(set(decl.pins) | set(module_pins))
+            elif isinstance(decl, ClassDecl):
+                for m in decl.methods:
+                    m.pins = sorted(set(m.pins) | set(module_pins))
+    return decls
+```
+
+## Registration
+
+**In-tree:** add your adapter to the tuple in
+`src/cgir/languages/registry.py` (`_BUILTINS`).
+
+**As a plugin package** (no fork):
+
+```toml
+[project.entry-points."cgir.languages"]
+rust = "cgir_rust:RustAdapter"
+```
+
+Builtins win extension conflicts; broken plugins degrade to warnings.
+`cgir languages` shows what loaded.
+
+## The test bar
+
+Mirror this pipeline-level suite (this is the acceptance standard; adapt
+the code snippets to your language):
+
+```python
+from cgir.analyses.call_graph import build_call_graph
+from cgir.analyses.cfg import build as build_cfg
+from cgir.analyses.effects import classify
+from cgir.analyses.purity import score
+from cgir.analyses.symbols import build_symbol_tables
+from cgir.ir.component_spec import ComponentKind
+from cgir.ir.edges import EdgeKind
+from cgir.ir.nodes import NodeKind
+from cgir.slicing import slice_components
+from cgir.sources import TreeSitterSource
+
+def _scan(tmp_path):
+    graph = TreeSitterSource().ingest(tmp_path)
+    tables = build_symbol_tables(graph)
+    build_call_graph(graph, tables, tmp_path)
+    build_cfg(graph, tmp_path)
+    effects = classify(graph, tmp_path)
+    purity = score(graph, effects)
+    return {s.id: s for s in slice_components(graph, effects=effects, purity_scores=purity)}
+```
+
+Cover at least:
+1. functions and methods ingested with correct ids
+   (`<module>.<fn>` / `<module>.<Type>.<method>`). Note the graph split:
+   free functions are `NodeKind.Function` with `func:` node ids; methods
+   are `NodeKind.Method` with `method:` ids — queries must use the right
+   prefix.
+2. params + signature extracted; `spec.language == "<your name>"`
+3. effect detection per tag you implement, incl. a pure function staying
+   `ComponentKind.pure_function` with `purity == 1.0`
+4. struct/class `fields` extracted
+5. receiver-field call resolves:
+   `graph.out_edges("method:<mod>.<Type>.<m>", EdgeKind.CALLS)` contains
+   the target method (this proves your `self.` normalization)
+6. caller of an effectful callee gets `"calls_effectful"` in effects
+7. CFG: a function with if + loop has `NodeKind.Branch` and
+   `NodeKind.Loop` children
+8. a `// cgir: pure` pin lands in `spec.pins`
+9. cross-file call resolution through your ImportDecls
+
+**Unregistered-adapter warning (applies to every pass, not just
+ingest):** each analysis that reads source (`build_call_graph`,
+`build_cfg`, `classify`) resolves the adapter per file extension over
+*registered* adapters, and **silently produces empty results** for files
+nobody claims. During development either register your adapter (in-tree
+tuple or installed entry point) or pass it explicitly everywhere:
+
+```python
+adapter = RustAdapter()
+graph = TreeSitterSource(adapter=adapter).ingest(tmp_path)
+tables = build_symbol_tables(graph)
+build_call_graph(graph, tables, tmp_path, adapter=adapter)
+build_cfg(graph, tmp_path, adapter=adapter)
+effects = classify(graph, tmp_path, adapter=adapter)
+```
+
+## Honesty requirements
+
+Document your known limits in the module docstring (which dynamic features
+you can't see; which effect rules are lexical guesses). CGIR's credibility
+is that its claims are checkable — an adapter that silently over-claims
+purity is worse than none.

codegraph_ir-0.4.0/examples/rust-adapter/NOTES.md

@@ -0,0 +1,145 @@
+# Rust Adapter — Implementation Notes
+
+## Doc gaps and ambiguities found during implementation
+
+### 1. PinIndex comment type mismatch
+**Gap:** The spec says "Wire pins using PinIndex per the doc's pattern," and PinIndex is documented as
+"grammar-agnostic: both supported grammars use `comment` nodes." However, the Rust tree-sitter
+grammar uses `line_comment` and `block_comment` node types, NOT `comment`. The base PinIndex
+would silently miss all Rust `cgir:` pragmas.
+
+**Resolution:** Implemented `RustPinIndex` — a complete reimplementation of PinIndex that extends
+the type check to `{"comment", "line_comment", "block_comment"}`. This is a drop-in replacement
+and the adapter uses it everywhere instead of PinIndex.
+
+### 2. Pipeline adapter threading
+**Gap:** The spec/doc does not mention that `classify`, `build_call_graph`, and `build_cfg` each
+accept an optional `adapter` parameter. Without passing the RustAdapter, these functions call
+`adapter_for_extension(".rs")` which returns `None` (since RustAdapter is a plugin not in the
+builtin registry), silently giving empty results for effects, call sites, and CFG nodes.
+
+**Resolution:** All pipeline calls must pass `adapter=adapter`. This is a required pattern for any
+language plugin that is not registered in `cgir.languages.registry`. The test suite documents this
+by always threading the adapter through.
+
+### 3. `impl_item` type field name
+**Gap:** The spec says "check if `impl_item.child_by_field_name('type')` works or if you need to
+iterate children." `child_by_field_name("type")` works correctly — confirmed via grammar probing.
+The field is indeed named `"type"` in the tree-sitter-rust 0.23.2 grammar.
+
+### 4. `for_expression` field names
+**Gap:** Spec was partially uncertain about `for`-loop field names. Confirmed via probing:
+- `pattern` = loop variable (identifier)
+- `value` = iterable expression
+- `body` = the block
+
+### 5. `if_expression` alternative field
+**Gap:** Spec mentioned field might be `"alternative"`. Confirmed it IS `"alternative"` and
+its child is `else_clause`. The `else_clause` contains either a `block` (for plain `else`) or
+an `if_expression` (for `else if`).
+
+### 6. `match_expression` fields
+**Gap:** The spec mentioned field names might vary. Confirmed:
+- `value` = the scrutinee expression
+- `body` = match_block containing match_arm nodes
+- Each `match_arm` has: `pattern` (match_pattern), `value` (the RHS expression/block)
+
+### 7. Doc comment node naming
+**Gap:** Spec says look for `line_comment` nodes with `outer_doc_comment_marker` child. This is
+correct. The doc text is in a `doc_comment` named child within `line_comment`. However, doc
+comment collection needs sibling-based walking (look backwards from function index in parent's
+children list), not the tree-sitter grammar's parent/child relationship, since line_comment nodes
+are siblings of function_item, not children.
+
+### 8. `NodeKind.Function` vs `NodeKind.Method`
+**Gap:** Not a Rust adapter issue per se, but test authors need to know: Rust impl methods are
+ingested as `NodeKind.Method` (id prefix `method:`), while top-level functions are
+`NodeKind.Function` (id prefix `func:`). `graph.nodes(NodeKind.Function)` returns only free
+functions, not methods. Tests querying for methods must use `NodeKind.Method` or combine both.
+
+### 9. `scoped_use_list` child structure
+**Gap:** When parsing `use std::io::{Read, Write}`, the `scoped_use_list` node contains:
+- An `identifier` or `scoped_identifier` child (the path prefix, e.g. `std::io`)
+- A `use_list` named child containing `identifier` and `use_as_clause` items
+
+The path prefix node is NOT always a `scoped_identifier` — for single-segment prefixes it's
+`identifier`. The adapter handles both.
+
+---
+
+## Known limits
+
+### Effect detection limits
+
+1. **Macro expansion:** Macros beyond `println!`, `panic!`, etc. that expand to effectful calls
+   are not detected. CGIR's design flags dynamic dispatch/macros as precision limits.
+
+2. **Trait object calls:** `dyn Trait` method calls cannot be resolved to concrete implementations
+   without type inference. These appear as call sites but won't resolve to specific methods.
+
+3. **`async`/`.await`:** Async functions are parsed identically to sync ones. The `await` keyword
+   appears as a child node in expressions but is not specially handled. Effects from async
+   functions work correctly since the body is walked the same way.
+
+4. **`?` operator (question mark / error propagation):** `expr?` desugars to an early return +
+   `From::from` conversion. The `?` operator is not currently detected as a potential `raise`
+   source (it's not a panic). This is intentional — `?` is value-based error handling, not an
+   exception.
+
+5. **`std::process::exit`:** Not in the effect tables. Could be added as a `raise`-like effect.
+
+6. **`reqwest::blocking::` vs `reqwest::`:** Both map to `net` via the `reqwest.` prefix after
+   `::` → `.` normalization.
+
+### Call site resolution limits
+
+7. **Chained method calls:** `c.get(url).send()` — the adapter resolves the outermost call
+   (`send`) with a receiver that is itself a call expression. In this case `_field_expr_dotted`
+   recursively resolves the chain, yielding the callee name. This is best-effort; very deeply
+   chained expressions may produce incomplete dotted paths.
+
+8. **Closure captures:** Calls inside closure bodies (`|| { foo() }`) are walked and collected,
+   but they are attributed to the containing function, not to a separate closure component.
+
+9. **`use crate::...` imports:** The `crate` prefix is left as-is (`crate.store.MyStore`). The
+   CGIR central resolver must handle `crate` → current package name mapping. Without that mapping,
+   cross-crate-relative imports won't resolve to their target functions.
+
+10. **Conditional compilation (`#[cfg(...)]`):** Attribute filtering is not applied; all items
+    are ingested regardless of `#[cfg]` attributes.
+
+### CFG limits
+
+11. **Implicit returns:** Rust blocks often return the last expression without `return`. These
+    appear as bare expressions in the block's named_children (e.g., `identifier`, `binary_expression`)
+    rather than `return_expression`. The adapter processes them as `SimpleDesc` nodes rather than
+    `ReturnDesc`. CFG topology still terminates correctly since the block ends.
+
+12. **`loop` + `break value`:** A `loop { ... break value; }` expression can return a value via
+    `break`. The `break` is treated as a statement without connecting its value to a `ReturnDesc`.
+
+13. **Pattern matching in `if let` / `while let`:** `if let Some(x) = expr` is parsed as
+    `if_expression` with a `let_condition` in the condition field rather than a plain expression.
+    The adapter extracts reads from the condition node generically, which collects identifiers
+    from the pattern as reads rather than writes. This is a minor inaccuracy in the CFG.
+
+### Structural limits
+
+14. **`enum` items:** `enum` declarations are not ingested as classes or any other typed node.
+    Enum variants are not extracted. This is a known omission — enums would need a new kind
+    (or `ClassDecl`) with each variant as a pseudo-field.
+
+15. **`trait` items:** Trait declarations are not ingested. Trait method signatures are invisible
+    to the pipeline. Only concrete `impl` blocks are processed.
+
+16. **Nested `impl` blocks / `impl Trait for Type`:** The adapter uses `child_by_field_name("type")`
+    to get the implementing type. For `impl Display for MyStruct`, the field is `name` (the trait
+    name) rather than `type` (the implementing type). The adapter handles the `"type"` field path
+    and falls back to iterating named_children for a `type_identifier`. Trait impls where the
+    implementing type is complex (generic bounds) may not resolve the struct name correctly.
+
+17. **Same-crate cross-file calls without `use`:** Unlike Go (same-package = no import needed),
+    Rust requires explicit `use` or full path qualification for cross-module calls. A bare call
+    `helper(x)` in `b.rs` to `helper` defined in `a.rs` (same directory) will NOT resolve unless
+    `b.rs` has `use crate::a::helper`. The `use crate::a::helper` import correctly creates an
+    `ImportDecl` with `target="crate.a.helper"` and `alias="helper"`, which feeds the call graph.

codegraph_ir-0.4.0/examples/rust-adapter/README.md

@@ -0,0 +1,15 @@
+# Rust adapter — the docs-only experiment
+
+Rust support was written by an **independent agent (Claude Sonnet) given
+only [`docs/writing-an-adapter.md`](../../docs/writing-an-adapter.md)** —
+no access to CGIR's source — as a usability test of the plugin docs. It hit
+all 9 points of the doc's test bar (36/36 tests) in one sitting; the doc
+gaps it surfaced were folded back into the guide, and its biggest find —
+`PinIndex` missing `line_comment` grammars — became a core fix.
+
+The adapter was then reviewed and **promoted to a builtin**:
+`src/cgir/languages/rust.py` (tests: `tests/unit/test_rust_adapter.py`).
+`NOTES.md` here preserves the agent's original gap report and limits list.
+
+The takeaway for plugin authors: the guide is sufficient — an implementer
+who has never seen the codebase produced a promotable adapter from it.

{codegraph_ir-0.3.0 → codegraph_ir-0.4.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # Distribution name (the import package and CLI command are both `cgir`;
 # the PyPI project name `cgir` was already taken, so we ship as codegraph-ir).
 name = "codegraph-ir"
-version = "0.3.0"
+version = "0.4.0"
 description = "The deterministic contract layer for AI-modified codebases — effects, purity, contracts, and blast radius, with zero LLM calls."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -43,7 +43,10 @@ dependencies = [
   "tree-sitter>=0.23,<0.25",
   "tree-sitter-python>=0.23,<0.24",
   "tree-sitter-typescript>=0.23,<0.24",
-  "tree-sitter-go>=0.23,<0.25",
+  "tree-sitter-go>=0.23,<0.24",  # 0.24+ ships language ABI 15
+  # <0.23.3: rust grammar bumped language ABI to 15 in a PATCH release;
+  # tree-sitter 0.24 core supports <=14 (0.23.2 is the last ABI-14 wheel)
+  "tree-sitter-rust>=0.23,<0.23.3",
   "jsonschema>=4.21",
 ]
 

{codegraph_ir-0.3.0 → codegraph_ir-0.4.0}/src/cgir/__init__.py

@@ -3,4 +3,4 @@
 See ``Code-IR.md`` at the repo root for the product specification.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"