codegraph-py 1.0.0__tar.gz

codegraph_py-1.0.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: codegraph-py
+Version: 1.0.0
+Summary: Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.
+Author-email: mading <martin98@bu.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/martin98-afk/codegraph-py
+Project-URL: Source, https://github.com/martin98-afk/codegraph-py
+Project-URL: Issues, https://github.com/martin98-afk/codegraph-py/issues
+Keywords: code-intelligence,knowledge-graph,static-analysis,mcp,ai-agent,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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 :: Python Modules
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Provides-Extra: ts
+Requires-Dist: tree-sitter>=0.21; extra == "ts"
+Requires-Dist: tree-sitter-python>=0.21; extra == "ts"
+Requires-Dist: tree-sitter-javascript>=0.21; extra == "ts"
+Requires-Dist: tree-sitter-typescript>=0.21; extra == "ts"
+Requires-Dist: tree-sitter-java>=0.21; extra == "ts"
+Requires-Dist: tree-sitter-go>=0.21; extra == "ts"
+Requires-Dist: tree-sitter-rust>=0.21; extra == "ts"
+Provides-Extra: watch
+Requires-Dist: watchfiles>=0.20.0; extra == "watch"
+Provides-Extra: all
+Requires-Dist: codegraph-py[ts,watch]; extra == "all"
+
+# codegraph-py
+
+**Python 版 CodeGraph** — 基于知识图谱的语义代码智能引擎，为 AI 编程助手提供精准的代码上下文。
+
+> 对代码库建立预索引的知识图谱。AI Agent 直接查询图结构而非逐文件扫描 —— 精准上下文、更少工具调用、更快回答。
+
+---
+
+## 特性
+
+- 🔍 **多语言 AST 解析** — 基于 tree-sitter 的符号级解析（Python/JS/TS/Go/Java/Rust，更多开发中）
+- 🧠 **知识图谱** — 函数、类、方法、接口之间的包含、调用、继承关系全量索引
+- ⚡ **FTS5 全文搜索** — 毫秒级符号查找，支持 camelCase / snake_case 分词
+- 🔗 **调用链分析** — `callers` / `callees` / `impact` 精准定位影响范围
+- 🏗 **增量同步** — 仅索引变更文件，监听文件系统变更
+- 🛠 **MCP 服务器** — 8 个工具，直接对接 Claude/Cursor 等 AI Agent
+- 🚀 **SQLite WAL 模式** — 256MB 内存映射 I/O，批量 checkpoint，生产级性能
+
+## 快速开始
+
+```bash
+# 安装
+pip install codegraph-py
+
+# 在项目目录初始化索引
+cd your-project
+codegraph init
+
+# 搜索符号
+codegraph query "calculateTotal"
+
+# 探索代码上下文
+codegraph explore "How does authentication work?"
+
+# 查看索引状态
+codegraph status
+```
+
+## CLI 命令
+
+| 命令 | 描述 |
+|------|------|
+| `init [path]` | 初始化并建立索引 |
+| `uninit [path]` | 移除 CodeGraph 索引 |
+| `index [path]` | 重建完整索引 |
+| `sync [path]` | 增量同步变更 |
+| `status [path]` | 显示索引统计 |
+| `query <search>` | 全文搜索符号 |
+| `explore <query>` | 探索代码（符号源码 + 调用路径） |
+| `node <name>` | 查看符号详细信息 |
+| `files` | 列出索引文件及符号统计 |
+| `callers <symbol>` | 查找调用者 |
+| `callees <symbol>` | 查找被调用者 |
+| `impact <symbol>` | 影响范围分析 |
+| `affected [files]` | 查找受影响的测试文件 |
+| `serve [path]` | 启动 MCP 服务器 |
+| `unlock [path]` | 移除陈旧锁文件 |
+| `install` | CLI 集成指南 |
+
+## Python API
+
+```python
+from codegraph import CodeGraph
+
+# 初始化或打开项目
+cg = CodeGraph.init_sync('/path/to/project')
+
+# 全量索引
+result = cg.index_all()
+print(f"Indexed {result.files_indexed} files, {result.nodes_created} nodes")
+
+# 搜索符号
+results = cg.search_nodes("calculateTotal")
+for r in results:
+    print(f"{r.node.kind}: {r.node.name} ({r.node.file_path}:{r.node.start_line})")
+
+# 调用链分析
+callers = cg.get_callers(node.id)
+callees = cg.get_callees(node.id)
+
+# 影响分析
+impact = cg.get_impact_radius(node.id)
+print(f"{len(impact.nodes)} symbols affected by change")
+
+# 统计信息
+stats = cg.get_stats()
+print(f"Files: {stats.file_count}, Nodes: {stats.node_count}")
+
+# 关闭连接
+cg.close()
+```
+
+## MCP 服务器
+
+启动 MCP 服务器供 AI Agent 集成：
+
+```bash
+codegraph serve
+```
+
+暴露的 MCP 工具：
+
+| 工具 | 功能 |
+|------|------|
+| `codegraph_explore` | 主探索工具 — 自然语言查询符号和上下文 |
+| `codegraph_node` | 获取符号或文件的源码 |
+| `codegraph_search` | 快速符号搜索 |
+| `codegraph_callers` | 查找函数调用者 |
+| `codegraph_callees` | 查找函数被调用者 |
+| `codegraph_impact` | 影响范围分析 |
+| `codegraph_status` | 索引健康检查 |
+| `codegraph_files` | 列出索引文件 |
+
+## 工作原理
+
+1. **`codegraph init`** 在项目根创建 `.codegraph/` 目录（含 SQLite 数据库 + `.gitignore`）
+2. **索引阶段** 扫描源文件，用 tree-sitter 解析 AST，提取符号（函数、类、方法、接口等），存入节点和边
+3. **FTS5 全文索引** 支持毫秒级符号搜索，智能分词 camelCase / snake_case
+4. **图遍历引擎** 沿边（调用、包含、继承等）查找调用链和影响范围
+5. **增量同步** 通过文件 mtime 对比实现，仅处理变更文件
+6. **MCP 服务器** 基于 JSON-RPC 2.0 stdio 协议，8 个工具直连 AI Agent
+
+## 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 数据库 | SQLite (WAL + mmap + FTS5) |
+| AST 解析 | tree-sitter (Python/JS/TS/Go/Java/Rust) |
+| CLI | Click |
+| MCP | JSON-RPC 2.0 over stdio |
+| 文件监控 | watchfiles（可选） |
+
+## 性能
+
+在 **原版 CodeGraph TypeScript 项目**（329 个源文件）上的压测结果：
+
+| 指标 | 数据 |
+|------|------|
+| 索引文件数 | 329 |
+| 提取节点数 | 2,349（1,069 函数 + 699 方法 + 153 接口 + 60 类 + 39 类型别名） |
+| 索引耗时 | **3.7 秒** |
+| 数据库 PRAGMA | WAL + 256MB mmap + 64MB cache + NORMAL sync |
+
+## 支持的语言
+
+### tree-sitter 完整 AST 解析
+- Python ✅
+- JavaScript / JSX ✅
+- TypeScript / TSX ✅
+- Go ✅
+- Java ✅
+- Rust ✅
+
+### 更多语言（文件级别跟踪，AST 解析即将支持）
+- C/C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Scala, Lua, Objective-C, R, Solidity, Terraform, 等 50+ 种
+
+## 安装
+
+```bash
+# 基础安装
+pip install codegraph-py
+
+# 带 tree-sitter 多语言支持
+pip install "codegraph-py[ts]"
+
+# 带文件监控
+pip install "codegraph-py[watch]"
+
+# 全功能
+pip install "codegraph-py[all]"
+```
+
+## 项目结构
+
+```
+codegraph/
+├── codegraph/
+│   ├── cli.py                    # 16 个 CLI 命令
+│   ├── codegraph.py              # 核心 CodeGraph 类
+│   ├── types.py                  # 类型定义
+│   ├── db/                       # SQLite 数据库层
+│   │   ├── connection.py         # 连接管理 + PRAGMA 优化
+│   │   ├── queries.py            # 查询构建器
+│   │   └── schema.sql            # 数据库 schema
+│   ├── extraction/               # 代码解析引擎
+│   │   ├── tree_sitter_extractor.py  # tree-sitter 核心提取器
+│   │   └── languages/            # 语言配置（6 种）
+│   ├── graph/                    # 图遍历引擎
+│   ├── search/                   # FTS5 全文搜索
+│   ├── mcp/                      # MCP 服务器
+│   ├── sync/                     # 文件同步/监控
+│   └── resolution/               # 引用解析
+├── tests/
+│   └── test_codegraph.py         # 11 个单元测试
+└── pyproject.toml
+```
+
+## 许可证
+
+MIT — 基于原版 [CodeGraph](https://github.com/colbymchenry/codegraph) TypeScript 项目。

codegraph_py-1.0.0/README.md

@@ -0,0 +1,200 @@
+# codegraph-py
+
+**Python 版 CodeGraph** — 基于知识图谱的语义代码智能引擎，为 AI 编程助手提供精准的代码上下文。
+
+> 对代码库建立预索引的知识图谱。AI Agent 直接查询图结构而非逐文件扫描 —— 精准上下文、更少工具调用、更快回答。
+
+---
+
+## 特性
+
+- 🔍 **多语言 AST 解析** — 基于 tree-sitter 的符号级解析（Python/JS/TS/Go/Java/Rust，更多开发中）
+- 🧠 **知识图谱** — 函数、类、方法、接口之间的包含、调用、继承关系全量索引
+- ⚡ **FTS5 全文搜索** — 毫秒级符号查找，支持 camelCase / snake_case 分词
+- 🔗 **调用链分析** — `callers` / `callees` / `impact` 精准定位影响范围
+- 🏗 **增量同步** — 仅索引变更文件，监听文件系统变更
+- 🛠 **MCP 服务器** — 8 个工具，直接对接 Claude/Cursor 等 AI Agent
+- 🚀 **SQLite WAL 模式** — 256MB 内存映射 I/O，批量 checkpoint，生产级性能
+
+## 快速开始
+
+```bash
+# 安装
+pip install codegraph-py
+
+# 在项目目录初始化索引
+cd your-project
+codegraph init
+
+# 搜索符号
+codegraph query "calculateTotal"
+
+# 探索代码上下文
+codegraph explore "How does authentication work?"
+
+# 查看索引状态
+codegraph status
+```
+
+## CLI 命令
+
+| 命令 | 描述 |
+|------|------|
+| `init [path]` | 初始化并建立索引 |
+| `uninit [path]` | 移除 CodeGraph 索引 |
+| `index [path]` | 重建完整索引 |
+| `sync [path]` | 增量同步变更 |
+| `status [path]` | 显示索引统计 |
+| `query <search>` | 全文搜索符号 |
+| `explore <query>` | 探索代码（符号源码 + 调用路径） |
+| `node <name>` | 查看符号详细信息 |
+| `files` | 列出索引文件及符号统计 |
+| `callers <symbol>` | 查找调用者 |
+| `callees <symbol>` | 查找被调用者 |
+| `impact <symbol>` | 影响范围分析 |
+| `affected [files]` | 查找受影响的测试文件 |
+| `serve [path]` | 启动 MCP 服务器 |
+| `unlock [path]` | 移除陈旧锁文件 |
+| `install` | CLI 集成指南 |
+
+## Python API
+
+```python
+from codegraph import CodeGraph
+
+# 初始化或打开项目
+cg = CodeGraph.init_sync('/path/to/project')
+
+# 全量索引
+result = cg.index_all()
+print(f"Indexed {result.files_indexed} files, {result.nodes_created} nodes")
+
+# 搜索符号
+results = cg.search_nodes("calculateTotal")
+for r in results:
+    print(f"{r.node.kind}: {r.node.name} ({r.node.file_path}:{r.node.start_line})")
+
+# 调用链分析
+callers = cg.get_callers(node.id)
+callees = cg.get_callees(node.id)
+
+# 影响分析
+impact = cg.get_impact_radius(node.id)
+print(f"{len(impact.nodes)} symbols affected by change")
+
+# 统计信息
+stats = cg.get_stats()
+print(f"Files: {stats.file_count}, Nodes: {stats.node_count}")
+
+# 关闭连接
+cg.close()
+```
+
+## MCP 服务器
+
+启动 MCP 服务器供 AI Agent 集成：
+
+```bash
+codegraph serve
+```
+
+暴露的 MCP 工具：
+
+| 工具 | 功能 |
+|------|------|
+| `codegraph_explore` | 主探索工具 — 自然语言查询符号和上下文 |
+| `codegraph_node` | 获取符号或文件的源码 |
+| `codegraph_search` | 快速符号搜索 |
+| `codegraph_callers` | 查找函数调用者 |
+| `codegraph_callees` | 查找函数被调用者 |
+| `codegraph_impact` | 影响范围分析 |
+| `codegraph_status` | 索引健康检查 |
+| `codegraph_files` | 列出索引文件 |
+
+## 工作原理
+
+1. **`codegraph init`** 在项目根创建 `.codegraph/` 目录（含 SQLite 数据库 + `.gitignore`）
+2. **索引阶段** 扫描源文件，用 tree-sitter 解析 AST，提取符号（函数、类、方法、接口等），存入节点和边
+3. **FTS5 全文索引** 支持毫秒级符号搜索，智能分词 camelCase / snake_case
+4. **图遍历引擎** 沿边（调用、包含、继承等）查找调用链和影响范围
+5. **增量同步** 通过文件 mtime 对比实现，仅处理变更文件
+6. **MCP 服务器** 基于 JSON-RPC 2.0 stdio 协议，8 个工具直连 AI Agent
+
+## 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 数据库 | SQLite (WAL + mmap + FTS5) |
+| AST 解析 | tree-sitter (Python/JS/TS/Go/Java/Rust) |
+| CLI | Click |
+| MCP | JSON-RPC 2.0 over stdio |
+| 文件监控 | watchfiles（可选） |
+
+## 性能
+
+在 **原版 CodeGraph TypeScript 项目**（329 个源文件）上的压测结果：
+
+| 指标 | 数据 |
+|------|------|
+| 索引文件数 | 329 |
+| 提取节点数 | 2,349（1,069 函数 + 699 方法 + 153 接口 + 60 类 + 39 类型别名） |
+| 索引耗时 | **3.7 秒** |
+| 数据库 PRAGMA | WAL + 256MB mmap + 64MB cache + NORMAL sync |
+
+## 支持的语言
+
+### tree-sitter 完整 AST 解析
+- Python ✅
+- JavaScript / JSX ✅
+- TypeScript / TSX ✅
+- Go ✅
+- Java ✅
+- Rust ✅
+
+### 更多语言（文件级别跟踪，AST 解析即将支持）
+- C/C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Scala, Lua, Objective-C, R, Solidity, Terraform, 等 50+ 种
+
+## 安装
+
+```bash
+# 基础安装
+pip install codegraph-py
+
+# 带 tree-sitter 多语言支持
+pip install "codegraph-py[ts]"
+
+# 带文件监控
+pip install "codegraph-py[watch]"
+
+# 全功能
+pip install "codegraph-py[all]"
+```
+
+## 项目结构
+
+```
+codegraph/
+├── codegraph/
+│   ├── cli.py                    # 16 个 CLI 命令
+│   ├── codegraph.py              # 核心 CodeGraph 类
+│   ├── types.py                  # 类型定义
+│   ├── db/                       # SQLite 数据库层
+│   │   ├── connection.py         # 连接管理 + PRAGMA 优化
+│   │   ├── queries.py            # 查询构建器
+│   │   └── schema.sql            # 数据库 schema
+│   ├── extraction/               # 代码解析引擎
+│   │   ├── tree_sitter_extractor.py  # tree-sitter 核心提取器
+│   │   └── languages/            # 语言配置（6 种）
+│   ├── graph/                    # 图遍历引擎
+│   ├── search/                   # FTS5 全文搜索
+│   ├── mcp/                      # MCP 服务器
+│   ├── sync/                     # 文件同步/监控
+│   └── resolution/               # 引用解析
+├── tests/
+│   └── test_codegraph.py         # 11 个单元测试
+└── pyproject.toml
+```
+
+## 许可证
+
+MIT — 基于原版 [CodeGraph](https://github.com/colbymchenry/codegraph) TypeScript 项目。

codegraph_py-1.0.0/codegraph/__init__.py

@@ -0,0 +1,12 @@
+"""
+CodeGraph - Semantic Code Intelligence for AI coding agents.
+
+A local-first code intelligence system that builds a semantic
+knowledge graph from any codebase.
+"""
+
+__version__ = "1.0.0"
+
+from codegraph.codegraph import CodeGraph
+
+__all__ = ['CodeGraph', '__version__']

codegraph_py-1.0.0/codegraph/__main__.py

@@ -0,0 +1,6 @@
+"""CodeGraph CLI entry point for `python -m codegraph`."""
+
+from codegraph.cli import main
+
+if __name__ == '__main__':
+    main()