codegraph-network 0.1.0__py3-none-any.whl

codegraph/tools.py

@@ -0,0 +1,99 @@
+"""One definition of the codegraph tool surface, shared by the MCP server and the CLI.
+
+Keeping the signature, the argument spec and the handler in one place is the only way the two
+front ends cannot drift apart.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Param:
+    name: str
+    type: str  # "str" | "int" | "bool"
+    default: object = None
+    help: str = ""
+
+
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    summary: str  # what the agent should use it for
+    params: tuple[Param, ...] = field(default_factory=tuple)
+
+    def defaults(self) -> dict:
+        return {p.name: p.default for p in self.params}
+
+    def usage(self) -> str:
+        parts = [p.name if p.default is None else f"[{p.name}]" for p in self.params]
+        return f"codegraph {self.name} " + " ".join(parts)
+
+
+def _p(name, type_, default=None, help_=""):
+    return Param(name, type_, default, help_)
+
+
+TOOLS: tuple[Tool, ...] = (
+    Tool("repo_map", "Ranked overview of the repo. Start here instead of reading whole files.",
+         (_p("prefix", "str", "", "directory prefix to zoom into"),
+          _p("max_tokens", "int", 1500),
+          _p("focus", "str", "", "symbols, words or paths, comma separated"))),
+    Tool("search", "Find symbols by name, split words or docstring; by meaning too when the embed extra is installed.",
+         (_p("query", "str", None), _p("limit", "int", 10))),
+    Tool("outline", "Symbol tree of a file, without any code.",
+         (_p("file", "str", None),)),
+    Tool("context", "Best first call for a symbol: source, what it uses, who uses it.",
+         (_p("symbol", "str", None), _p("max_tokens", "int", 1500))),
+    Tool("related", "Closest symbols to one symbol, direct and multi-hop, ranked.",
+         (_p("symbol", "str", None), _p("max_tokens", "int", 800))),
+    Tool("similar", "Symbols that mean the same thing as this one, even with no call between them "
+                    "(needs the embed extra).",
+         (_p("symbol", "str", None), _p("limit", "int", 10))),
+    Tool("source", "Exact source of one symbol.",
+         (_p("symbol", "str", None),)),
+    Tool("callers", "Who calls / uses / inherits from this symbol.",
+         (_p("symbol", "str", None), _p("depth", "int", 1), _p("limit", "int", 30))),
+    Tool("callees", "What this symbol calls.",
+         (_p("symbol", "str", None), _p("depth", "int", 1), _p("limit", "int", 30))),
+    Tool("impact", "Blast radius of a change, grouped by file. Use before editing.",
+         (_p("symbol", "str", None), _p("depth", "int", 3))),
+    Tool("deps", "What a file imports and which files import it.",
+         (_p("file", "str", None),)),
+    Tool("stats", "Index size: files, symbols, edges by confidence, imports, communities."),
+    Tool("report", "Whole-repo overview: key symbols, communities, surprising connections. "
+                   "Also writes .codegraph/GRAPH_REPORT.md and a browsable graph.html.",
+         (_p("max_tokens", "int", 1500),)),
+    Tool("review", "Review a change: symbols the git diff touches, their blast radius, missing tests, "
+                   "files that usually change with it.",
+         (_p("base", "str", "", "branch/commit to diff against (default: where this branch left main)"),
+          _p("max_tokens", "int", 1500))),
+    Tool("reindex", "Re-scan the repo incrementally. Use after large external edits.",
+         (_p("force", "bool", False),)),
+)
+
+TOOLS_BY_NAME = {t.name: t for t in TOOLS}
+
+# extra CLI spellings, e.g. `codegraph map` for `repo_map`
+CLI_ALIASES = {"repo_map": ("map",), "review": ("prs", "pr")}
+QUERY_TOOLS = tuple(t for t in TOOLS if t.name not in ("reindex",))
+
+# CLI flag aliases: param name -> (long flag, short flag or None).
+# Anything not listed here is exposed under its own parameter name.
+CLI_FLAGS = {
+    "max_tokens": ("tokens", "-t"),
+    "focus": ("focus", "-f"),
+    "depth": ("depth", "-d"),
+}
+
+
+def make_callable(tool: Tool, graph, reindex_fn=None):
+    """Bind a Tool spec to a Graph, producing the callable used by both front ends."""
+    def call(**kwargs):
+        return getattr(graph, tool.name)(**kwargs)
+    call.__name__ = tool.name
+    call.__doc__ = tool.summary
+    if tool.name == "reindex":
+        assert reindex_fn is not None
+        call = reindex_fn
+    return call

codegraph_network-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: codegraph-network
+Version: 0.1.0
+Summary: Graph-based code understanding for LLM agents: fewer tokens, better answers
+Author: Oviing
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Oviing/codegraph
+Project-URL: Issues, https://github.com/Oviing/codegraph/issues
+Keywords: code-graph,tree-sitter,mcp,llm,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-language-pack
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: embed
+Requires-Dist: fastembed>=0.4; extra == "embed"
+Requires-Dist: numpy>=1.24; extra == "embed"
+Provides-Extra: bench
+Requires-Dist: pyyaml>=6; extra == "bench"
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4; extra == "pdf"
+Dynamic: license-file
+
+# codegraph
+
+Graph-based code understanding for LLM agents. Parses a repo once with tree-sitter (no LLM, no cost),
+stores symbols and relations in SQLite, and serves compact, token-budgeted answers over MCP.
+
+Instead of reading whole files, the agent asks the graph.
+
+## Install
+
+    pip install codegraph-network              # provides the `codegraph` command
+    pip install "codegraph-network[embed]"     # optional: semantic search, see "Hybrid search"
+
+From a checkout:
+
+    pip install -e ".[dev]"     # drop [dev] if you don't need pytest/ruff
+    pip install -e ".[embed]"   # optional: semantic search (fastembed + numpy), see "Hybrid search"
+
+## Use with Claude Code
+
+    claude mcp add codegraph -- codegraph -r /path/to/repo serve
+
+Or in any MCP client config:
+
+    {"mcpServers": {"codegraph": {"command": "codegraph", "args": ["-r", "/path/to/repo", "serve"]}}}
+
+The index lives in `<repo>/.codegraph/graph.db` and updates incrementally on every server start;
+`reindex` re-scans after edits made outside the session. `.gitignore` it.
+
+## Tools
+
+| Tool | Use it to |
+|---|---|
+| `repo_map` | PageRank-ranked overview within a token budget; `focus=` personalizes it to what you're working on |
+| `search` | Find symbols by name, words (camel/snake split) or docstring; with the embed extra also by meaning, each hit tagged `[lexical]` / `[semantic]` / `[both]` |
+| `context` | Best first call: source + signatures it uses + who uses it, in one reply |
+| `source` | Exact source of one symbol |
+| `outline` | Symbol tree of a file, without code |
+| `callers` / `callees` | Walk the call/inherit graph (depth N) |
+| `impact` | Blast radius of a change, grouped by file |
+| `related` | Closest symbols to one symbol (direct + multi-hop), ranked by personalized PageRank; each line says how it is related (`uses`, `used by`, `tested by`, `tests`, `key`, `similar`) |
+| `similar` | Symbols that mean the same thing as this one even with no call between them (needs the embed extra) |
+| `file_deps` | What a file imports and what imports it |
+| `stats` | Index size, edges by confidence, communities |
+| `report` | Key symbols, communities, surprising connections; writes `.codegraph/GRAPH_REPORT.md` and a browsable `graph.html` |
+| `review` (`prs`) | What the git diff touches: blast radius per changed symbol, missing tests, files that usually change with it |
+| `reindex` | Re-scan after big external edits |
+
+The MCP server and the CLI are both generated from one tool registry (`src/codegraph/tools.py`), so
+they cannot drift apart. The CLI mirrors the tools: `codegraph map`, `codegraph context Store.resolve`,
+`codegraph impact parse`, ...
+
+## Languages
+
+Python, TypeScript/TSX, JavaScript, Go, Rust, C/C++.
+
+Beyond code, also parsed statically (no LLM): Markdown (headings become `section` symbols; `` `code spans` `` link
+to the symbols they name, relative links count as imports), SQL (`CREATE TABLE/VIEW/FUNCTION/PROCEDURE`, with
+`FROM`/`JOIN`/`REFERENCES` links), and PDF pages (`pip install -e ".[pdf]"`). Prose and SQL mentions link only
+when the name is unambiguous.
+
+## Edge confidence
+
+Every edge records how it was resolved: `extracted` (one target named by the source itself: same file, an import,
+`self.x()`), `inferred` (a name match by proximity) or `ambiguous` (several equally plausible targets). `callers`,
+`callees` and `context` tag anything that is not `extracted`; `impact` marks it with `?`. Treat tagged edges as
+upper bounds.
+
+## Scripting and ignoring
+
+`codegraph <tool>` exits 0 on an answer, 3 when a name matches several symbols, 4 when it matches none.
+`.codegraphignore` (gitignore-style: `#` comments, `dir/`, `/anchored`, `*.glob`, `!negation`) excludes paths
+from the index, on top of the built-in skips (`node_modules`, `venv`, `dist`, hidden directories, ...).
+
+## Installing into assistants and git
+
+    codegraph install [claude|cursor|gemini|agents|all]   # skill, MCP config, guidance block; --uninstall to undo
+    codegraph hook install                                # re-index after commit, checkout, merge, rebase
+
+`install` is idempotent and merges into existing files (guidance lives between `<!-- codegraph:start/end -->`
+markers; JSON configs keep their other entries). For Claude Code it also adds a `Glob|Grep` hint hook
+(`--no-hooks` to skip). Git hooks are appended to existing ones and run the indexer in the background.
+
+## How it works
+
+Indexing is incremental in two layers. Files are re-parsed only when their hash changes, and edge
+resolution is scoped: a change re-resolves only the raw references whose name, or whose source file,
+is affected. Parsing runs across processes and writes are batched; PageRank and community detection
+warm-start from the previous run. On a 3,091-file / 59k-symbol / 79k-edge corpus (8 cores) a full index takes
+~7.6s (was ~22s single-process), changing one file ~2s, and a no-op reindex ~0.3s. PageRank is the one step
+that always walks the whole graph; whether it converged is reported by `codegraph index` rather than assumed.
+
+Edge resolution is name-based, using the strongest evidence available:
+
+- `self.x()` / `this.x()` link only to methods of the enclosing class, its bases and its subclasses
+  (no match => inherited from an external base => no edge).
+- `obj.x()` links only if a candidate is in the same file, an imported file or the same directory.
+- bare `x()` prefers same file, then imported files, then same directory, then anywhere.
+- a bare call to a Python builtin, or to a name imported from a module outside the repo
+  (`from typing import cast`), links to nothing — otherwise `isinstance(...)` would attach thousands
+  of phantom edges to whatever repo method happens to share the name.
+- Targets defined in more than 4 places are dropped as too ambiguous.
+
+## Hybrid search and hidden links
+
+Everything above is exact and structural. A second layer adds *recall* for relationships that are not
+spelled out in code. It never touches `callers` / `callees` / `impact` or global PageRank: those stay
+structural. Soft links live in their own tables (`links`, `file_links`) and enter the personalized
+PageRank behind `context` / `related` / `repo_map(focus=)` at a lower weight than a call edge
+(`LINK_WEIGHT` in `queries.py`).
+
+| Link | Source | Needs |
+|---|---|---|
+| `tests` | `test_foo.py` / `foo.test.ts` / `foo_test.go` -> the file named after it, and `test_bar` -> `bar` inside that pair; test callers are labelled `tested by` | nothing |
+| `key` | the same string literal used in matching roles in different files: route path (`@app.get("/x")` vs `requests.get("/x")`, express vs `fetch`), event name (`emit` vs `on`), config key (`getenv`, `config.get`). Table-driven: add a row to `PATTERNS` in `keys.py`. Keys shared by more than 8 symbols and generic events (`error`, `data`, ...) are ignored | nothing |
+| co-change | `git log --name-only` (last 1000 commits, commits over 30 files ignored, pairs need 3+ co-changes); shown by `deps` and used by `repo_map`'s ranking. No git or no history: no edges | git |
+| `similar` | top-5 nearest neighbours by embedding cosine >= 0.85, skipping pairs already linked by a call/inheritance, overloads, and test-to-test pairs | embed extra |
+
+**Semantic search** is optional: `pip install codegraph[embed]` (fastembed + numpy). Each function / method /
+class / type is embedded from its name as words, qualified name, signature and doc line with a small local
+ONNX model (`BAAI/bge-small-en-v1.5`); there is no network access at query time, the model files are
+downloaded once at the first index. Vectors are cached in SQLite by content hash, so only changed symbols are
+ever re-embedded and a no-change reindex stays near-instant. `search` fuses FTS5 and vector rankings with
+reciprocal rank fusion (semantic hits in test files count half). Without the extra, or with
+`CODEGRAPH_EMBED=off`, nothing changes: the output is the plain lexical search, byte for byte.
+
+Providers are pluggable: `CODEGRAPH_EMBED=package.module:factory` loads any object with a `name`,
+`embed_passages(list[str])` and `embed_query(str)` returning L2-normalised float32 vectors (see
+`tests/fake_embed.py`); `CODEGRAPH_EMBED_MODEL` picks another fastembed model.
+
+### Measured (fastembed bge-small, Apple silicon, CPU)
+
+| | Flask (Python) | ky (TypeScript) |
+|---|---|---|
+| files / symbols | 88 / 1,723 | 100 / 11,427 |
+| cold index, no embeddings | 0.4 s | 0.9 s |
+| first-time embedding (one-off, then cached) | 27 s / 1,624 symbols | 58 s / 7,389 symbols |
+| no-change reindex | 0.06 s | 0.04 s |
+| edges (structural) | 1,011 calls, 74 inherits | 2,915 calls, 8 inherits |
+| soft links | 70 tests, 52 key, 353 similar, 39 co-change | 3 key, 1,261 similar, 40 co-change |
+
+`codegraph bench tasks.yaml` replays your own `(task, expected symbols)` list and reports, per task and in
+total, recall@k of lexical-only vs hybrid search and the tokens an agent reads through the graph vs reading
+the files that contain the expected symbols (`pip install codegraph[bench]` for YAML; JSON works without).
+On 7 Flask and 5 ky natural-language tasks written for this README: hybrid recall 8/9 and 3/5, lexical-only
+1/9 and 1/5. The lexical baseline is the existing search, which needs every query word to match, so it
+scores ~0 on questions phrased unlike the code by construction. Treat the gap as "what the semantic layer adds
+for descriptive queries", not as a general accuracy figure.
+
+The similarity threshold (0.85) was set on codegraph's own code: bge-small cosines are high in general
+(median nearest-neighbour 0.80 here); real near-duplicates (`make_repo` in two test files, `pagerank` vs
+`personalized_pagerank`) start around 0.85, and below it the pairs are mostly generically similar test names.
+
+## Tests
+
+    pytest              # 232 tests
+    pytest tests/test_edges.py -rA      # per-language edge precision/recall report
+
+`tests/fixtures/<lang>/expected.json` holds hand-verified edges per language. Each fixture lists
+`true` edges (must all be found) and `known_ambiguous` ones (accepted false positives from not
+tracking receiver types, each with a stated reason). Anything the tool emits that is in neither list
+fails the test, so a new kind of false positive cannot slip in unnoticed.
+
+## Known limits
+
+- Remaining false positives: `obj.x()` where `obj`'s type is unknown and an imported file defines a
+  method called `x` (e.g. `Path(p).resolve()` vs your own `resolve`). Type-aware indexers (SCIP) fix this.
+- Dynamic dispatch, reflection and macros are mostly invisible.
+- Semantic search is as good as a small local model: it can miss (`jsonify` for "turn python objects into a
+  json response" in Flask) and it ranks by meaning of the name/signature/doc line, not of the body. Variables
+  and TypeScript interface fields are not embedded.
+- String keys match on identical literals only (no `/users/{id}` vs `/users/1`), and only for Python and
+  JS/TS call shapes listed in `keys.py`. `os.environ["X"]` and `process.env.X` are not recognised yet.
+- Co-change uses the last 1000 commits and treats renames as new files.
+- Object-literal properties in JS/TS (`{ json: body }`) are indexed as methods by the parser, which inflates
+  TypeScript indexes (ky: 11k symbols for 100 files) and puts noise in semantic results.
+- Go/Rust/C++ import resolution is heuristic. Notably a stdlib import can collide with a local
+  directory of the same name: `net/http` matches an `internal/http` directory, because there is no
+  `go.mod` to tell the module prefix apart. Python imports are exact (see `py_lookup` in `store.py`).
+
+## Next steps
+
+- Type-aware resolution via SCIP/LSIF indexers for exact call edges
+- Optional one-line LLM summaries per symbol, generated once at index time
+- Git-aware ranking by recency (co-change is in; "recently changed" is not)

codegraph_network-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+codegraph/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+codegraph/bench.py,sha256=-2_kV76N8gjM58mW5Qb3tvMGGxfB-XEj_MsJTg7-t8s,3880
+codegraph/cli.py,sha256=08n_GNkr4jEKKy6f_6Bfnft8M3lIENy5VzgjYqtXnj8,4877
+codegraph/community.py,sha256=HtsQK58zDfUkySLE1mvuEoup1GR9RIIwh7UoY4iRDnw,3737
+codegraph/docs.py,sha256=YHzg24v9tviiz5PqSG_nqHsnQhPntVgk8ABx2pmarcI,6126
+codegraph/embed.py,sha256=LVryGlwSkktpWgPJzVtRFYJny4yWWu3AtuF-RQXruyo,9891
+codegraph/indexer.py,sha256=ySizCFui6JFMgE00SoPChpTh4l0bm20XokyMWZc5hnU,7825
+codegraph/install.py,sha256=ldx78xs6M2eiJZFnxxMoAY9mBdih7RfUWoDfjg2Qads,9821
+codegraph/keys.py,sha256=OcDYsTxst8Jg_hcSNucuk-jxoTbLAuSgVbPm3bNbV7E,4149
+codegraph/links.py,sha256=sn7bZIxf0fLFv7BjoK7V2opMVW1BuwQNaXsMSQprI04,9846
+codegraph/parser.py,sha256=Q4mtOCaqyZm-b0fnPNH9fa6sA39tejmZmLag__RZa-w,19619
+codegraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codegraph/queries.py,sha256=CTt6TpRfWOcXgA4wwXIJJYs6-Vu8r14UUt-WdqepXpc,30829
+codegraph/rank.py,sha256=FUJ-W9ogQPnXngNxCBHD-58ke6sXBTlZlb1xETuC6-g,4963
+codegraph/report.py,sha256=xjoQ7KYKo-6hjDsmA6wykbeX2Yi0uFbVZknUeRYYS_E,9853
+codegraph/review.py,sha256=yh5hNWtnsppc40hidL8Kb4kzSb9gugO5MJrIxY-37kM,6380
+codegraph/server.py,sha256=lTmdhnHE-r2aLmNwWKu_svHBZ5XJ1j7higQDoT9W-TY,3094
+codegraph/store.py,sha256=rOxweItAg1jMvb8D6W_rt4TTZSVkUOrj2tjurW_OVqY,30847
+codegraph/tools.py,sha256=UNsiuta7TFaC1AgGMTDCOHb5jV0Czvz-5kh7nXoUB70,4338
+codegraph_network-0.1.0.dist-info/licenses/LICENSE,sha256=2g3-GEuR7lJgSNW_8hDmQ67ottLWLC7TB7pWmiVYcdQ,1063
+codegraph_network-0.1.0.dist-info/METADATA,sha256=b7tTVDFxSGgadSmqUUyFteXKf0MR-TTrI4iQWu9APr8,13153
+codegraph_network-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+codegraph_network-0.1.0.dist-info/entry_points.txt,sha256=3f2dJK7oR3dBzP21qRk_KuQa6Li8MVbVXeKcx3UjQ6c,49
+codegraph_network-0.1.0.dist-info/top_level.txt,sha256=RqBj9sPbifZTb9aeHtnbxTgKJvfHIQdmYE1Brv8Wdkg,10
+codegraph_network-0.1.0.dist-info/RECORD,,

codegraph_network-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codegraph_network-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codegraph = codegraph.cli:main

codegraph_network-0.1.0.dist-info/licenses/LICENSE

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

codegraph_network-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+codegraph