codegraph-py 1.0.0__py3-none-any.whl

codegraph/utils.py

@@ -0,0 +1,218 @@
+"""
+CodeGraph Utilities
+
+Shared utility functions and classes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Callable, Iterator, List, Optional, TypeVar
+
+T = TypeVar('T')
+
+
+# =============================================================================
+# Hashing
+# =============================================================================
+
+def sha256_hash(content: str) -> str:
+    """Calculate SHA256 hash of string content."""
+    return hashlib.sha256(content.encode('utf-8')).hexdigest()
+
+
+def sha256_file(filepath: str) -> str:
+    """Calculate SHA256 hash of a file."""
+    h = hashlib.sha256()
+    with open(filepath, 'rb') as f:
+        for chunk in iter(lambda: f.read(65536), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+# =============================================================================
+# Path Utilities
+# =============================================================================
+
+def normalize_path(p: str) -> str:
+    """Normalize path separators to forward slashes."""
+    return p.replace('\\', '/')
+
+
+def is_subpath(child: str, parent: str) -> bool:
+    """Check if child path is under parent path."""
+    child = os.path.normpath(os.path.abspath(child))
+    parent = os.path.normpath(os.path.abspath(parent))
+    if child == parent:
+        return True
+    # Add trailing separator to parent to avoid partial matches
+    parent = parent.rstrip(os.sep) + os.sep
+    return child.startswith(parent)
+
+
+def validate_path_within_root(path: str, root: str) -> bool:
+    """Validate that a path is within the project root (no traversal)."""
+    abs_path = os.path.normpath(os.path.abspath(path))
+    abs_root = os.path.normpath(os.path.abspath(root))
+    return abs_path.startswith(abs_root + os.sep) or abs_path == abs_root
+
+
+# =============================================================================
+# Mutex (Async-friendly via threading)
+# =============================================================================
+
+class Mutex:
+    """A simple mutex for preventing concurrent operations within a process."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._owner = None
+
+    def acquire(self, blocking: bool = True) -> bool:
+        """Acquire the mutex."""
+        return self._lock.acquire(blocking=blocking)
+
+    def release(self) -> None:
+        """Release the mutex."""
+        if self._lock.locked():
+            self._lock.release()
+
+    def __enter__(self):
+        self._lock.acquire()
+        return self
+
+    def __exit__(self, *args):
+        self._lock.release()
+
+    async def with_lock(self, func: Callable[..., T]) -> T:
+        """Execute a function while holding the lock."""
+        with self._lock:
+            return func()
+
+
+# =============================================================================
+# File Lock (cross-process)
+# =============================================================================
+
+class FileLock:
+    """Cross-process file lock using a lock file."""
+
+    def __init__(self, lock_path: str, timeout: float = 10.0):
+        self.lock_path = lock_path
+        self.timeout = timeout
+        self._fd = None
+
+    def acquire(self) -> bool:
+        """Acquire the file lock. Returns True if successful."""
+        import fcntl
+        deadline = time.time() + self.timeout
+        while time.time() < deadline:
+            try:
+                self._fd = os.open(self.lock_path, os.O_CREAT | os.O_RDWR, 0o644)
+                fcntl.flock(self._fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                return True
+            except (IOError, OSError):
+                if self._fd:
+                    os.close(self._fd)
+                    self._fd = None
+                time.sleep(0.1)
+        return False
+
+    def release(self) -> None:
+        """Release the file lock."""
+        if self._fd is not None:
+            try:
+                import fcntl
+                fcntl.flock(self._fd, fcntl.LOCK_UN)
+                os.close(self._fd)
+            except (IOError, OSError):
+                pass
+            finally:
+                self._fd = None
+                try:
+                    os.unlink(self.lock_path)
+                except OSError:
+                    pass
+
+    def __enter__(self):
+        self.acquire()
+        return self
+
+    def __exit__(self, *args):
+        self.release()
+
+
+# =============================================================================
+# Batch Processing
+# =============================================================================
+
+def process_in_batches(items: List[T], batch_size: int) -> Iterator[List[T]]:
+    """Yield successive batches from items."""
+    for i in range(0, len(items), batch_size):
+        yield items[i:i + batch_size]
+
+
+# =============================================================================
+# Debounce / Throttle
+# =============================================================================
+
+class Debouncer:
+    """Debounce calls to a function."""
+
+    def __init__(self, delay_ms: float = 2000):
+        self.delay = delay_ms / 1000.0
+        self._timer: Optional[threading.Timer] = None
+        self._last_call: float = 0
+
+    def call(self, func: Callable, *args, **kwargs) -> None:
+        """Call function after debounce delay."""
+        if self._timer:
+            self._timer.cancel()
+        self._timer = threading.Timer(self.delay, func, args, kwargs)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def cancel(self) -> None:
+        """Cancel pending call."""
+        if self._timer:
+            self._timer.cancel()
+            self._timer = None
+
+
+# =============================================================================
+# Generated File Detection
+# =============================================================================
+
+_GENERATED_PATTERNS = [
+    '.pb.', '_pb2.py', '_pb2_grpc.py',
+    '.grpc.', '.gen.', '_gen.',
+    '.generated.', '_generated.',
+    'grpc_', 'proto_',
+]
+
+
+def is_generated_file(filepath: str) -> bool:
+    """Check if a file appears to be generated."""
+    name = os.path.basename(filepath).lower()
+    for pattern in _GENERATED_PATTERNS:
+        if pattern in name:
+            return True
+    return False
+
+
+# =============================================================================
+# Config Leaf Languages
+# =============================================================================
+
+CONFIG_LEAF_LANGUAGES = frozenset({
+    'terraform', 'yaml', 'properties', 'nix', 'solidity',
+})
+
+
+def is_config_leaf_node(node_kind: str, node_language: str) -> bool:
+    """Check if a node is a config-leaf (no meaningful children to recurse)."""
+    return node_language in CONFIG_LEAF_LANGUAGES

codegraph_py-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,44 @@
+codegraph/__init__.py,sha256=Qkd-AU1AJ6sYtHtWnlWZD8WGUycr_F0twWO7ZguJDVk,285
+codegraph/__main__.py,sha256=CU1tC_q6j0dvOAONsWUSBfVtbpVEsLmt8Jj358sbGjg,136
+codegraph/cli.py,sha256=b8GZ_C5f7g2vmtIWlBa9DRQqkZ2m8cZtjRMNjnRfvEw,31967
+codegraph/codegraph.py,sha256=B_Vvc1OeqA5LB4hGdNol5k_gJz0io3eOZy8L6NPpm4Q,23109
+codegraph/directory.py,sha256=N-6LiwqDnvD87ms9SEPpeukXRuZWpgIT0-juQRBxgG4,5136
+codegraph/errors.py,sha256=70lFoLu-BW4VLR39O0fsqRStG4IgwUSCxVkWvLPlYTA,2861
+codegraph/project_config.py,sha256=14tBQ66vPi44wVxJF3Suasy0xrHfCQYuHokEIh0sbfU,6117
+codegraph/types.py,sha256=hxTqcqEu-nnhaSuZGQvgm50NZlSFuzBYLmExBWwYzHU,9637
+codegraph/utils.py,sha256=OkgKpYUI1VWchfxmBstObjpkSU3JT0fHbrQzgU6aTUQ,6998
+codegraph/context/__init__.py,sha256=TCU36JORIUL2XyUbxhAk3E89uU2mErCP6pji13Sasp4,7871
+codegraph/db/__init__.py,sha256=geWlUD7spD1kYC638ON5V2jPRmtt6s1_lcR5vVEvUls,302
+codegraph/db/connection.py,sha256=xG6XSt5SWugWlePqpMP3paAgwCO_4Fva-GYPac0esww,5670
+codegraph/db/queries.py,sha256=-_a-5Bu9rfnuT5Cy_mKoOXJDpcICwLPWAsmUo7UO9Oc,29425
+codegraph/db/schema.sql,sha256=4yJFQytPksbu0cvx92_xVyrxDYfoV2Um86kofQ7EoBU,5508
+codegraph/extraction/__init__.py,sha256=EHJfbFhww0zmTZ-i7TLY_QioE1O9TY7Zny8equ1h0uk,31451
+codegraph/extraction/tree_sitter_extractor.py,sha256=4tDqaSs5enxdN_WtCvmHAf8H70WAOffR9m1Tmuts9iI,25217
+codegraph/extraction/languages/__init__.py,sha256=9OTdDdAxRwkvaFoF_lkMJ0zEvDiMK0vNoQAvjDcnPII,2175
+codegraph/extraction/languages/base.py,sha256=huH08ABk_d3zRlp2zVQ4NxO3R75fWYZJqGZYsOS2Ubw,4747
+codegraph/extraction/languages/c_cfg.py,sha256=vU8f04Ohvvoy1WYtiGVwZJQ6VCPecW54WYrZ6jy_APQ,2049
+codegraph/extraction/languages/cpp_cfg.py,sha256=Hq70zSi451dKutcaf4PJEtNmuYyat6H8fUK3Ykde7Y4,2621
+codegraph/extraction/languages/dart_cfg.py,sha256=yXaMpTiVUrrRYXXCHjqM1-YNIVfzXrb3_VcT63Ge4ZY,2142
+codegraph/extraction/languages/go_cfg.py,sha256=qaCJrCgBNK31vlb_MSdh4HzSpcZXvm1uiSV769jT1mE,2717
+codegraph/extraction/languages/java_cfg.py,sha256=F3spSAlPu8wqbWktTLA-ntqcSHcIMbg5ybrVticfkkU,2294
+codegraph/extraction/languages/javascript_cfg.py,sha256=QtveWNxjABiBVFOiUuLH5csgECOPjaefSQ1ZAUN6OM8,3040
+codegraph/extraction/languages/kotlin_cfg.py,sha256=cngAu4wRonfvy5kJx3XrB2CJBjyFk3pGvf6xfP1Kpbc,2053
+codegraph/extraction/languages/lua_cfg.py,sha256=nRF9IA9kgAG2PWwyrjAdnRTtGtRION37n5Xz9sv2VQ4,2415
+codegraph/extraction/languages/python_cfg.py,sha256=C4HKjR9mcN_PJGnNYOsKSvewDWgk_BRHRcp4T5yUlJk,2857
+codegraph/extraction/languages/ruby_cfg.py,sha256=etSpVnq43zuszqyWsUjnGzzTl7XBUy-_Jo4qX_mH-_0,1724
+codegraph/extraction/languages/rust_cfg.py,sha256=JUxwXFH8l62VVRc7TBxLLf6xmkziip4ToPVjmIdCFto,2566
+codegraph/extraction/languages/scala_cfg.py,sha256=biL-Q-B_2bIaFyzcH2V3RbFV57BUCC4bPSgvcAFng5A,2284
+codegraph/extraction/languages/swift_cfg.py,sha256=VE2Wm1HOttZOZ1XpbM8ePwDjlXEmTN7pH3vekzxCGvs,2497
+codegraph/extraction/languages/typescript_cfg.py,sha256=IlSQ7AXC8gPUengePZlS0R3J9JpI02wc--IrO_HphFw,3331
+codegraph/graph/__init__.py,sha256=EoZIK_EqcnOWSkZhTjspchB82TK_zjkmfsHSG_Oi8xg,23129
+codegraph/installer/__init__.py,sha256=0S058PkGTZrzyC0ZLFnWbCmsyeGBEiI6swdYINlyhm0,240
+codegraph/mcp/__init__.py,sha256=o4AQEeC7dnkKt7ZTgodklVofJ3B_bdsBG48vZvgcdy4,25729
+codegraph/resolution/__init__.py,sha256=VfDWWeFvYTNgJG1Mb3HW6vfbGafMGLEN97wKjnFliTc,13167
+codegraph/search/__init__.py,sha256=ZLghOTL2MWiwa0tQMKsjP0ARvALCVK0tvnowXR1DZK4,22109
+codegraph/sync/__init__.py,sha256=n6Voj1neoSQPCwdvECoOzTFhCfN2zeHA1sPmJyUixww,6558
+codegraph/ui/__init__.py,sha256=tCi-_FJ7-MLPwmRt02dadMlJ3iy3QR26o1fgFc1DsUI,229
+codegraph_py-1.0.0.dist-info/METADATA,sha256=H7RzzsItDz9T5vgP8MMOZjzna4Dew_biogE-ckYI_pY,8393
+codegraph_py-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+codegraph_py-1.0.0.dist-info/entry_points.txt,sha256=3f2dJK7oR3dBzP21qRk_KuQa6Li8MVbVXeKcx3UjQ6c,49
+codegraph_py-1.0.0.dist-info/top_level.txt,sha256=RqBj9sPbifZTb9aeHtnbxTgKJvfHIQdmYE1Brv8Wdkg,10
+codegraph_py-1.0.0.dist-info/RECORD,,

codegraph_py-1.0.0.dist-info/WHEEL

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

codegraph_py-1.0.0.dist-info/entry_points.txt

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

codegraph_py-1.0.0.dist-info/top_level.txt

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