codegraph-ai 0.1.0__tar.gz

codegraph_ai-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: codegraph-ai
+Version: 0.1.0
+Summary: Hybrid graph + vector code intelligence powered by NeuG and zvec
+Requires-Python: >=3.10
+Requires-Dist: neug
+Requires-Dist: zvec
+Requires-Dist: tree-sitter-language-pack
+Requires-Dist: sentence-transformers
+Requires-Dist: numpy
+Provides-Extra: server
+Requires-Dist: fastmcp; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

codegraph_ai-0.1.0/README.md

@@ -0,0 +1,346 @@
+# CodeScope
+
+Hybrid **graph + vector** code intelligence, powered by [NeuG](https://github.com/GraphScope/neug) (embedded graph database) and [zvec](https://github.com/alibaba/zvec) (embedded vector database).
+
+CodeScope indexes source code into a knowledge graph of functions, calls, imports, classes, modules, commits, and semantic embeddings — enabling analyses impossible with grep, LSP, or vector search alone.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+This installs the `codegraph` CLI. Verify:
+
+```bash
+codegraph --help
+```
+
+Dependencies:
+
+| Package | Purpose |
+|---------|---------|
+| `neug` | Embedded graph database (Cypher) |
+| `zvec` | Embedded vector database |
+| `tree-sitter-language-pack` | AST parsing for Python / JavaScript / C |
+| `sentence-transformers` | Local embedding model (`all-MiniLM-L6-v2`) |
+| `numpy` | Vector operations |
+
+## Quick Start
+
+### 1. Index a repository
+
+```bash
+# Index the current directory (auto-detects language)
+codegraph init
+
+# Index a specific repo with options
+codegraph init --repo /path/to/project --lang c --commits 500
+
+# Index with git history and MODIFIES backfill
+codegraph init --repo . --lang python --commits 1000 --backfill-limit 200
+```
+
+### 2. Check index status
+
+```bash
+codegraph status
+```
+
+### 3. Ask questions
+
+```bash
+codegraph query "who calls free_irq?"
+codegraph query "find functions related to memory allocation" --json
+```
+
+### 4. Generate an architecture analysis report
+
+```bash
+codegraph analyze
+codegraph analyze --output my-report.md
+```
+
+### 5. Ingest more git history
+
+```bash
+codegraph ingest --commits 2000
+codegraph ingest --backfill-limit 500
+codegraph ingest --commits 1000 --backfill-limit 300 --vectors
+```
+
+### 6. Start the MCP server (for Cursor, OpenClaw, etc.)
+
+```bash
+codegraph server
+```
+
+## CLI Reference
+
+```
+codegraph init [--repo PATH] [--db PATH] [--lang LANG] [--commits N] [--backfill-limit N]
+    Create a new index for a repository.
+    --repo          Path to repository (default: .)
+    --db            Database directory (default: .codegraph)
+    --lang          Language: auto, python, c, javascript, typescript (default: auto)
+    --commits       Number of git commits to ingest (default: 0)
+    --backfill-limit  Max commits to compute MODIFIES edges (default: 0)
+
+codegraph open [--db PATH]
+    Open an existing index and print a summary.
+
+codegraph query "<question>" [--db PATH] [--topk N] [--json]
+    Ask a question against the index.
+    Supports structural, semantic, historical, and intent queries.
+
+codegraph analyze [--db PATH] [--output PATH]
+    Generate a comprehensive architecture analysis report (Markdown).
+
+codegraph status [--db PATH]
+    Show index health, counts, and backfill progress.
+
+codegraph ingest [--repo PATH] [--db PATH] [--commits N] [--backfill-limit N] [--vectors]
+    Ingest additional git history into an existing index.
+    --commits       Commits to ingest (default: 500)
+    --backfill-limit  Max commits to compute MODIFIES edges (default: 0)
+    --vectors       Rebuild vectors after ingestion
+
+codegraph server [--db PATH] [--repo PATH]
+    Start the MCP server for AI coding agents.
+```
+
+## Use with AI Coding Agents
+
+### Claude Code CLI / QwenCode
+
+After indexing, AI agents can invoke `codegraph` subcommands directly:
+
+```bash
+# Agent workflow:
+codegraph init --repo . --lang python --commits 200
+codegraph query "what functions handle authentication?"
+codegraph analyze
+```
+
+### Cursor (MCP Integration)
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["server"],
+      "env": {
+        "CODESCOPE_DB_DIR": "/absolute/path/to/.codegraph",
+        "HF_HUB_OFFLINE": "1"
+      }
+    }
+  }
+}
+```
+
+### Agent Skill
+
+A skill file is provided at `skill/codegraph-qa/SKILL.md` that teaches AI agents how to use CodeScope — including the full graph schema, Cypher query patterns, and composition strategies for custom analyses.
+
+## Python API
+
+All CLI commands are backed by the `CodeScope` class, which can be used directly:
+
+```python
+from codegraph.core import CodeScope
+
+cs = CodeScope(".codegraph")
+cs.index("/path/to/project", languages=["python"])
+
+# Structural analysis
+results = cs.impact("execute_query", "return type changed", max_hops=3)
+spots = cs.hotspots(topk=10)
+dead = cs.dead_code()
+
+# Architecture intelligence
+bridges = cs.bridge_functions(topk=30)
+layers = cs.layer_discovery(topk=30)
+coupling = cs.module_coupling(topk=10)
+stability = cs.stability_analysis(topk=50)
+
+# Semantic search
+results = cs.vector_only_search("error handling pattern", topk=10)
+
+# Evolution
+history = cs.change_attribution("sched_fork")
+coupled = cs.co_change("kmalloc")
+
+# Report generation
+from codegraph.analyzer import generate_report
+report = generate_report(cs)
+
+cs.close()
+```
+
+## Architecture
+
+```
+Source Code
+    |
+    v
++----------+     +---------------------------------+
+|tree-sitter|---->|  NeuG (Graph)                   |
+|  parsers  |     |  File, Function, Class, Module  |
+|  (AST)    |     |  Commit, CALLS, MODIFIES, ...   |
++----------+     +---------------------------------+
+    |
+    | embeddings  +---------------------------------+
+    +------------>|  zvec (Vector)                  |
+                  |  Semantic function embeddings   |
+                  +---------------------------------+
+```
+
+## Graph Schema
+
+```
+Node Tables:
+  File(id, path, language, loc, is_external)
+  Function(id, name, qualified_name, signature, file_path, is_historical)
+  Class(id, name, qualified_name, file_path)
+  Module(id, name, path_prefix)
+  Commit(id, hash, message, author, timestamp, version_tag)
+
+Relationship Tables:
+  CALLS(Function -> Function)
+  DEFINES_FUNC(File -> Function)
+  DEFINES_CLASS(File -> Class)
+  HAS_METHOD(Class -> Function)
+  IMPORTS(File -> File)
+  BELONGS_TO(File -> Module)
+  INHERITS(Class -> Class)
+  MODIFIES(Commit -> Function)   -- requires backfill
+  TOUCHES(Commit -> File)
+```
+
+| `version_tag` | Meaning |
+|---------------|---------|
+| `''` (empty) | Commit ingested, MODIFIES edges not yet computed |
+| `'bf'` | Backfill completed, MODIFIES edges have been computed |
+
+## Supported Languages
+
+| Language | Adapter | Status |
+|----------|---------|--------|
+| C / C headers | `CAdapter` | Supported |
+| Python | `PythonAdapter` | Supported |
+| JavaScript / TypeScript | `JsAdapter` | Supported |
+
+Adding a new language requires implementing `BaseAdapter` (see `codegraph/adapters/base.py`).
+
+## Project Structure
+
+```
+codegraph/
+  codegraph/
+    cli.py                # CLI entry point (codegraph command)
+    core.py               # CodeScope class — graph + vector orchestration
+    analyzer.py           # Architecture report generator
+    models.py             # Data models (dataclasses)
+    qa.py                 # Natural-language Q&A classifier
+    mcp_server.py         # MCP server (FastMCP)
+    __main__.py           # python -m codegraph support
+    adapters/
+      base.py             # BaseAdapter interface
+      c_adapter.py        # C parser (tree-sitter)
+      python_adapter.py
+      js_adapter.py
+  skill/codegraph-qa/     # Agent skill files
+  sample_project/         # Demo Python codebase
+  tests/                  # Unit and integration tests
+  pyproject.toml          # Package metadata + CLI entry point
+```
+
+## Troubleshooting
+
+### neug: "Database locked"
+
+```
+RuntimeError: Database locked: The database is already locked for write access
+```
+
+**Cause**: A previous process crashed without releasing the neug write lock.
+
+**Fix**:
+```bash
+rm <db>/graph.db/neugdb.lock
+# Example: rm .codegraph/graph.db/neugdb.lock
+```
+
+The CLI auto-cleans this on startup if it detects a lock issue.
+
+### zvec: "Can't open lock file"
+
+```
+RuntimeError: Can't open lock file
+```
+
+**Cause**: The zvec `LOCK` file was accidentally deleted.
+
+**Fix**:
+```bash
+touch <db>/vectors/LOCK
+# Example: touch .codegraph/vectors/LOCK
+```
+
+### zvec: "Can't lock read-write collection"
+
+```
+RuntimeError: Can't lock read-write collection
+```
+
+**Cause**: Another process is currently holding the zvec lock.
+
+**Fix**:
+```bash
+# Find and kill the process holding the lock
+lsof <db>/vectors/idmap.0/LOCK
+kill <pid>
+```
+
+### zvec: "recovery idmap failed"
+
+```
+RuntimeError: recovery idmap failed
+```
+
+**Cause**: Stale RocksDB WAL files left by repeated crashes.
+
+**Fix**:
+```bash
+# Remove empty WAL files from the idmap directory
+find <db>/vectors/idmap.0/ -name "*.log" -size 0 -delete
+# Example: find .codegraph/vectors/idmap.0/ -name "*.log" -size 0 -delete
+```
+
+### SentenceTransformer: network errors
+
+```
+ConnectionError / ReadTimeoutError during model download
+```
+
+**Cause**: The embedding model needs to be downloaded on first use.
+
+**Fix**: Download the model once with internet access, then use offline mode:
+```bash
+# First run (needs internet):
+python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# All subsequent runs (offline):
+export HF_HUB_OFFLINE=1
+export TRANSFORMERS_OFFLINE=1
+codegraph init --repo .
+```
+
+The CLI sets these environment variables automatically after the model is cached.
+
+## Privacy
+
+All processing is fully local. Code never leaves your machine. The embedding model (`all-MiniLM-L6-v2`) runs locally, and both NeuG and zvec are embedded databases with no network requirements.

codegraph_ai-0.1.0/codegraph/__init__.py

@@ -0,0 +1 @@
+"""CodeScope: Graph + Vector Code Intelligence powered by neug and zvec."""

codegraph_ai-0.1.0/codegraph/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m codegraph`` to invoke the CLI."""
+
+from codegraph.cli import main
+
+main()

codegraph_ai-0.1.0/codegraph/adapters/__init__.py

@@ -0,0 +1 @@
+"""CodeScope language adapters for parsing source code via tree-sitter."""

codegraph_ai-0.1.0/codegraph/adapters/base.py

@@ -0,0 +1,38 @@
+"""Abstract base class for language-specific source code adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from codegraph.models import ParseResult
+
+
+class BaseAdapter(ABC):
+    """Parse a single source file and extract structural information."""
+
+    @abstractmethod
+    def language_name(self) -> str:
+        """Return the canonical language name, e.g. ``'python'``, ``'c'``."""
+        ...
+
+    @abstractmethod
+    def supported_extensions(self) -> list[str]:
+        """Return file extensions this adapter handles, e.g. ['.py']."""
+        ...
+
+    @abstractmethod
+    def parse_file(self, source: bytes, file_path: str) -> ParseResult:
+        """Parse *source* bytes and return structured code elements.
+
+        Parameters
+        ----------
+        source:
+            Raw bytes of the source file.
+        file_path:
+            Repository-relative path used to generate unique IDs.
+        """
+        ...
+
+    def can_handle(self, file_path: str) -> bool:
+        """Return ``True`` if *file_path* has a supported extension."""
+        return any(file_path.endswith(ext) for ext in self.supported_extensions())