codegraph

# CodeScope Q&A CodeScope indexes source code into a two-layer knowledge graph — **structure** (functions, calls, imports, classes, modules) and **evolution** (commits, file changes, function modifications) — plus **semantic embeddings** for every function. Supports **Python, JavaScript/TypeScript, C, and Java** (including Hadoop-scale repositories with 8K+ files). This combination enables analyses that grep, LSP, or pure vector search cannot do alone. It can also **fetch GitHub issues and trace bugs to code**, and **review open PRs** — scoring per-PR risk, detecting cross-PR conflicts, identifying auto-merge candidates, and applying GitHub labels. ## When to Use This Skill - User asks about call chains, callers, callees, or dependencies - User wants to find dead code, hotspots, or architectural layers - User asks about code history, who changed what, or why something was modified - User wants to find semantically similar functions across a codebase - User wants a full architecture analysis or report - User asks about module coupling, circular dependencies, or bridge functions - User wants to index or analyze a Java project (Maven, Gradle, plain Java) - User wants to analyze GitHub issues or bug reports to find root causes - User asks "why does this project have so many bugs" or "what code is most buggy" - User wants to trace a bug report to the most relevant code locations - User asks about class relationships, ownership, composition, or wants a class diagram / UML - User wants to understand which classes own or depend on other classes - User wants to review PRs, assess PR risk, or prioritize PR reviews - User asks about cross-PR conflicts or which PRs can be merged independently - User wants to find auto-merge candidates or generate a PR review report - User asks about the blast radius or impact scope of a PR - User wants to apply labels to PRs from analysis results - User wants to explore PR-specific follow-up questions for a given PR - A `.codegraph` directory (or similar index) exists in the workspace ## Getting Started ### Installation ```bash pip install codegraph-ai ``` ### Environment Variables (optional) ```bash # Create Python virtural environment python -m venv .venv source .venv/bin/activate # Point to a pre-built database (skip indexing) export CODESCOPE_DB_DIR="/path/to/.linux_db" # Offline mode for HuggingFace models export HF_HUB_OFFLINE="1" # Fallback when HuggingFace is unreachable (e.g., network issues in China) # Use HF mirror or ModelScope for sentence-transformers models: export HF_ENDPOINT="https://hf-mirror.com" # https://www.modelscope.cn/models/sentence-transformers/all-MiniLM-L6-v2 ``` ### Check Index Status ```bash codegraph status --db $CODESCOPE_DB_DIR ``` If no index exists, create one: ```bash codegraph init --repo . --lang auto --commits 500 ``` Supported languages: `python`, `c`, `javascript`, `typescript`, `java`, or `auto` (auto-detects from file extensions). The `--commits` flag ingests git history (for evolution queries). Without it, only structural analysis is available. Add `--backfill-limit 200` to also compute function-level `MODIFIES` edges (slower but enables `change_attribution` and `co_change`). To add git history to an existing index (without re-indexing structure): ```bash codegraph ingest --repo . --db $CODESCOPE_DB_DIR --commits 500 codegraph ingest --repo . --db $CODESCOPE_DB_DIR --backfill-limit 200 # add MODIFIES edges only ``` ## Two Interfaces: CLI vs Python **Use the CLI** for status and reports: ```bash codegraph status --db $CODESCOPE_DB_DIR codegraph analyze --db $CODESCOPE_DB_DIR --output report.md ``` **Use the Python API** for queries and custom analyses: ```python import os os.environ['HF_HUB_OFFLINE'] = '1' # required from codegraph.core import CodeScope cs = CodeScope(os.environ['CODESCOPE_DB_DIR']) # Cypher query rows = list(cs.conn.execute(''' MATCH (caller:Function)-[:CALLS]->(f:Function {name: "free_irq"}) RETURN caller.name, caller.file_path LIMIT 10 ''')) for r in rows: print(r) cs.close() # always close when done ``` The Python API is more powerful — it gives you raw Cypher access and lets you chain queries. ## Core Python API ### Raw Queries These are the building blocks for any custom analysis: | Method | What it does | | --------------------------------------- | ---------------------------------------------------------------------- | | `cs.conn.execute(cypher)` | Run any Cypher query against the graph — returns list of tuples | | `cs.vector_only_search(query, topk=10)` | Semantic search over all function embeddings — returns `[{id, score}]` | | `cs.summary()` | Print a human-readable overview of the indexed codebase | ### Structural Analysis | Method | What it does | | ----------------------------------------------- | --------------------------------------------------------------------- | | `cs.impact(func_name, change_desc, max_hops=3)` | Find callers up to N hops, ranked by semantic relevance to the change | | `cs.hotspots(topk=10)` | Rank functions by structural risk (fan-in × fan-out) | | `cs.dead_code()` | Find functions with zero callers (excluding entry points) | | `cs.circular_deps()` | Detect circular import chains at file level | | `cs.module_coupling(topk=10)` | Find cross-module coupling pairs with call counts | | `cs.bridge_functions(topk=30)` | Find functions called from the most distinct modules | | `cs.layer_discovery(topk=30)` | Auto-discover infrastructure / mid / consumer layers | | `cs.stability_analysis(topk=50)` | Correlate fan-in with modification frequency | | `cs.class_hierarchy(class_name=None)` | Return inheritance tree for a class (or all classes) | ### Class Dependency Relationships (UML-Style) CodeScope extracts three UML relationship types from class fields and type annotations during indexing: | Relationship | UML symbol | Meaning | How detected | | ------------ | -------------------- | ------------------------------------------------- | ------------------------------------------------ | | `COMPOSES` | `*--` filled diamond | Strong ownership — field always holds an instance | Non-optional field assigned a constructed object | | `AGGREGATES` | `o--` open diamond | Optional/weak reference — may be `None` | `Optional[X]`, `X \| None`, or assigned `None` | | `INHERITS` | `<\|--` hollow arrow | Subclass extends parent | `class A(B)` | ```python # Get all composition relationships (A strongly owns B) list(cs.conn.execute('MATCH (c1:Class)-[:COMPOSES]->(c2:Class) RETURN c1.name, c2.name')) # Get all aggregation relationships (A optionally holds B) list(cs.conn.execute('MATCH (c1:Class)-[:AGGREGATES]->(c2:Class) RETURN c1.name, c2.name')) # How many objects does a class directly own? list(cs.conn.execute( 'MATCH (c:Class {name: "Llama"})-[:COMPOSES]->(t:Class) RETURN t.name' )) # Full dependency graph for a class (composition + aggregation + inheritance) list(cs.conn.execute( 'MATCH (c:Class {name: "GPUModelRunner"})-[r:COMPOSES|AGGREGATES]->(t:Class) ' 'RETURN type(r), t.name' )) ``` **Generating a Mermaid class diagram:** ```python inherits = list(cs.conn.execute('MATCH (c1:Class)-[:INHERITS]->(c2:Class) RETURN c1.name, c2.name')) composes = list(cs.conn.execute('MATCH (c1:Class)-[:COMPOSES]->(c2:Class) RETURN c1.name, c2.name')) aggregates = list(cs.conn.execute('MATCH (c1:Class)-[:AGGREGATES]->(c2:Class) RETURN c1.name, c2.name')) print('classDiagram') for src, tgt in inherits: print(f' {tgt} <|-- {src}') # parent <|-- child for src, tgt in composes: print(f' {src} *-- {tgt}') # owner *-- owned for src, tgt in aggregates: print(f' {src} o-- {tgt}') # holder o-- optional ``` **Scale reference:** | Project | Classes | INHERITS | COMPOSES | AGGREGATES | Index time | | ---------------- | ------- | -------- | -------- | ---------- | ---------- | | llama-cpp-python | 128 | 18 | 8 | 4 | ~2s | | vllm | 4,002 | 2,185 | 3,217 | 149 | ~50s | ### Semantic Search | Method | What it does | | ----------------------------------------------- | ----------------------------------------------------------------------- | | `cs.similar(function, scope, topk=10)` | Find functions similar to a given function within a module scope | | `cs.cross_locate(query, topk=10)` | Find semantically related functions, then reveal call-chain connections | | `cs.semantic_cross_pollination(query, topk=15)` | Find similar functions across distant subsystems | ### Evolution (requires `--commits` during init) | Method | What it does | | ----------------------------------------------------------------- | ------------------------------------------------------ | | `cs.change_attribution(func_name, file_path=None, limit=20)` | Which commits modified a function? (requires backfill) | | `cs.co_change(func_name, file_path=None, min_commits=2, topk=10)` | Functions that are always modified together | | `cs.intent_search(query, topk=10)` | Find commits matching a natural-language intent | | `cs.commit_modularity(topk=20)` | Score commits by how many modules they touch | | `cs.hot_cold_map(topk=30)` | Module modification density | ### Report Generation ```python from codegraph.analyzer import generate_report report = generate_report(cs) # full architecture analysis as markdown ``` Or via CLI: ```bash codegraph analyze --output reports/analysis.md ``` The report covers: overview stats, subsystem distribution, top modules, architectural layers (with Mermaid diagrams), bridge functions, fan-in/fan-out hotspots, cross-module coupling, evolution hotspots, and dead code density. ## Java Support CodeScope includes a full Java adapter that handles enterprise-scale repositories like Apache Hadoop (~8K files, ~97K functions indexed in ~3.5 minutes). ### What Gets Indexed