codegraph Workspace

A fast, reliable, and flexible graph database optimized for storing and querying code relationships, with production-ready language parsers.

Mission

The codegraph ecosystem provides:

• codegraph: Fast graph database for storing code relationships
• codegraph-parser-api: Unified parser interface and types
• Language parsers: Production-ready parsers for Python, Rust, TypeScript, and Go
• A complete solution for building code analysis tools

Workspace Crates

Quick Start

Using the Complete Solution (Database + Parser)

[dependencies]
codegraph = "0.1.1"
codegraph-parser-api = "0.1.0"
codegraph-python = "0.2.0"  # or rust, typescript, go

use codegraph::CodeGraph;
use codegraph_parser_api::CodeParser;
use codegraph_python::PythonParser;
use std::path::Path;

// Create parser and graph
let parser = PythonParser::new();
let mut graph = CodeGraph::open("./my_project.graph")?;

// Parse a file
let file_info = parser.parse_file(Path::new("main.py"), &mut graph)?;
println!("Parsed: {} functions, {} classes",
    file_info.functions.len(),
    file_info.classes.len()
);

// Parse entire project
let project_info = parser.parse_directory(Path::new("./src"), &mut graph)?;
println!("Parsed {} files in {:?}",
    project_info.files.len(),
    project_info.total_parse_time
);

// Query the graph
let neighbors = graph.get_neighbors(&file_info.file_id)?;

Language-Specific Examples

use codegraph_python::PythonParser;
use codegraph_parser_api::{CodeParser, ParserConfig};

let config = ParserConfig {
    include_tests: false,      // Skip test_ functions
    include_private: false,     // Skip _private functions
    parallel: true,             // Use parallel parsing
    ..Default::default()
};

let parser = PythonParser::with_config(config);
let mut graph = CodeGraph::open("project.graph")?;

// Parse Python project
let info = parser.parse_directory(Path::new("./src"), &mut graph)?;

use codegraph_rust::RustParser;
use codegraph_parser_api::CodeParser;

let parser = RustParser::new();
let mut graph = CodeGraph::open("project.graph")?;

// Parse Rust source
let info = parser.parse_file(Path::new("main.rs"), &mut graph)?;

// Extracts: functions, structs, enums, traits, impl blocks, use statements

use codegraph_typescript::TypeScriptParser;
use codegraph_parser_api::CodeParser;

let parser = TypeScriptParser::new();
let mut graph = CodeGraph::open("project.graph")?;

// Supports .ts, .tsx, .js, .jsx files
let info = parser.parse_file(Path::new("App.tsx"), &mut graph)?;

// Extracts: functions, classes, interfaces, imports, JSX components

use codegraph_go::GoParser;
use codegraph_parser_api::CodeParser;

let parser = GoParser::new();
let mut graph = CodeGraph::open("project.graph")?;

// Parse Go package
let info = parser.parse_directory(Path::new("./pkg"), &mut graph)?;

// Extracts: functions, structs, interfaces, imports

Core Principles

🔌 Unified Parser API

"One trait to parse them all."

All language parsers implement the same CodeParser trait, providing:

• Consistent API across languages
• Standardized entity types (functions, classes, imports)
• Uniform error handling and metrics
• Drop-in interchangeability

⚡ Performance First

"Sub-100ms queries or it didn't happen."

• Single node lookup: <1ms
• Neighbor query: <10ms
• Graph traversal (depth=5): <50ms
• 100K node graphs are practical

🧪 Test-Driven Development

"If it's not tested, it's broken."

• 421+ tests across entire workspace
• codegraph: 39 tests (85% coverage)
• parser-api: 12 tests with comprehensive entity validation
• Python: 111 tests (~90% coverage)
• Rust: 64 tests (40 unit + 24 integration)
• TypeScript: 63 tests (40 unit + 23 integration)
• Go: 54 tests (34 unit + 20 integration)
• Every public API tested with TDD methodology

🪄 Zero Magic

"Explicit over implicit, always."

• No global state
• No automatic file scanning
• No convention-over-configuration
• Explicit error handling (no panics in library code)
• No unsafe code

💾 Persistence is Primary

"Graphs outlive processes."

• RocksDB backend for production
• Crash-safe with write-ahead logging
• Atomic batch operations
• Memory backend for testing only

Using Just the Database

If you want to use your own parsers:

[dependencies]
codegraph = "0.1.1"

use codegraph::{CodeGraph, Node, NodeType, Edge, EdgeType};
use std::path::Path;

// Create a persistent graph
let mut graph = CodeGraph::open(Path::new("./my_project.graph"))?;

// Add nodes manually
let file_id = graph.add_file(Path::new("src/main.rs"), "rust")?;
let func_id = graph.add_node(NodeType::Function, properties)?;

// Create relationships
graph.add_edge(file_id, func_id, EdgeType::Contains, properties)?;

// Query the graph
let neighbors = graph.get_neighbors(&file_id)?;

Architecture

codegraph is organized in clear layers:

User Tools (parsers, analysis)
    ↓
Code Helpers (convenience API)
    ↓
Query Builder (fluent interface)
    ↓
Core Graph (nodes, edges, algorithms)
    ↓
Storage Backend (RocksDB, memory)

Each layer:

• Has well-defined boundaries
• Can be tested independently
• Doesn't leak abstractions
• Has minimal dependencies on upper layers

Features

• Persistent Storage: Production-ready RocksDB backend
• Type-Safe API: Rust's type system prevents common errors
• Schema-less Properties: Flexible JSON properties on nodes and edges
• Efficient Queries: O(1) neighbor lookups with adjacency indexing
• Explicit Operations: No hidden behavior or magical conventions
• Comprehensive Tests: 85% test coverage (983/1158 lines)
• Zero Unsafe Code: Memory-safe by default

What We Provide

✅ Complete Solution

• Graph Database: Fast, persistent storage for code relationships
• Parser API: Unified interface for all language parsers
• Language Parsers: Production-ready Python, Rust, TypeScript, and Go parsers
• Analysis Foundation: Building blocks for custom code analysis tools

❌ Out of Scope

• Semantic Analysis: No type inference or advanced static analysis
• IDE Integration: No LSP server or editor plugins
• Build System: No compilation or dependency resolution
• Complete Framework: You build the analysis logic, we provide the infrastructure

Performance Targets

Development

Workspace Commands

# Build all crates
cargo build --workspace --release

# Test all crates (421+ tests)
cargo test --workspace

# Test specific parser
cargo test -p codegraph-python
cargo test -p codegraph-rust

# Generate documentation for all crates
cargo doc --workspace --open

Code Quality

# Format all code
cargo fmt --all

# Lint with clippy (all warnings as errors)
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Check test coverage
cargo tarpaulin --workspace --exclude-files "tests/*"

# Run individual crate checks
cargo clippy -p codegraph-go --all-targets --all-features -- -D warnings

Individual Crate Development

# Work on specific parser
cd crates/codegraph-typescript
cargo test
cargo clippy -- -D warnings

# Add features to parser API
cd crates/codegraph-parser-api
cargo test
cargo doc --open

Examples

See the examples/ directory for complete examples:

• basic_usage.rs - Creating and querying a simple graph
• call_graph.rs - Function call analysis with syn integration
• dependency_tree.rs - File dependency and circular dependency analysis
• impact_analysis.rs - Complex query patterns for impact analysis
• visualize.rs - Exporting graphs to DOT, JSON, CSV, and RDF formats

API Overview

Core Operations

// Node operations
let node_id = graph.add_node(NodeType::Function, properties)?;
let node = graph.get_node(node_id)?;
graph.delete_node(node_id)?;

// Edge operations
let edge_id = graph.add_edge(source, target, EdgeType::Calls, properties)?;
let neighbors = graph.get_neighbors(node_id, Direction::Outgoing)?;

// Batch operations
graph.add_nodes_batch(nodes)?;
graph.add_edges_batch(edges)?;

Helper Functions

use codegraph::helpers;

// Code-specific operations
let file_id = helpers::add_file(&mut graph, "main.rs", "rust")?;
let func_id = helpers::add_function(&mut graph, file_id, "main", 10, 20)?;
helpers::add_call(&mut graph, func1_id, func2_id, Some(15))?;

// Relationship queries
let callers = helpers::get_callers(&graph, func_id)?;
let deps = helpers::get_file_dependencies(&graph, file_id)?;

Query Builder

// Fluent query interface
let results = graph.query()
    .node_type(NodeType::Function)
    .in_file("src/main.rs")
    .property("visibility", "public")
    .name_contains("test")
    .execute()?;

Graph Algorithms

// Transitive analysis
let all_deps = helpers::transitive_dependencies(&graph, file_id, Some(5))?;
let all_dependents = helpers::transitive_dependents(&graph, file_id, None)?;

// Call chains
let paths = helpers::call_chain(&graph, from_func, to_func, Some(10))?;

// Circular dependencies
let cycles = helpers::circular_deps(&graph)?;

Export Formats

use codegraph::export;

// Graphviz DOT
export::export_dot(&graph, &mut output)?;

// D3.js JSON
export::export_json(&graph, &mut output)?;

// CSV (nodes and edges)
export::export_csv_nodes(&graph, &mut output)?;
export::export_csv_edges(&graph, &mut output)?;

// RDF N-Triples
export::export_triples(&graph, &mut output)?;

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Before contributing, please:

1. Follow TDD methodology
2. Ensure all tests pass
3. Run cargo fmt and cargo clippy

License

codegraph is licensed under the Apache License 2.0, which means:

✅ You can:

• Use in commercial products
• Modify and distribute
• Use in proprietary software

✅ You must:

• Include a copy of the license
• Disclose significant changes (in a CHANGES file)
• Include the patent grant notice

✅ You can't:

• Hold us liable
• Claim we endorse your product

This is a truly open license. There's no "gotcha" later where we switch to GPL or a commercial model. Apache-2.0 is forever.

Code of Conduct

This project adheres to the Rust Code of Conduct. See CODE_OF_CONDUCT.md.

Versioning

This project follows Semantic Versioning:

• v0.x: API may change between minor versions (with deprecation warnings)
• v1.0+: Stability guaranteed, breaking changes only in major versions

Current version: 0.1.1 (Initial release + formatting fixes)

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Roadmap

v0.2.0 (Current Release)

• Unified parser API with standardized types
• Python parser with comprehensive test coverage
• Rust parser with full AST extraction
• TypeScript/JavaScript parser with JSX/TSX support
• Go parser with import tracking
• 421+ tests across all crates

v0.3-0.5 (Near-term)

• Query language improvements (graph patterns, filters)
• More export formats (GraphML, Cypher, Neo4j)
• Performance optimizations (batch operations, caching)
• Parser enhancements (semantic relationships, type information)

v0.6-0.9 (Medium-term)

• Incremental updates (watch mode, delta parsing)
• Change tracking and diff analysis
• Statistics and metrics API
• CLI tool for parsing and querying
• Additional language parsers (Java, C++, C#)

v1.0+ (Long-term)

• Schema validation and constraints
• Full-text search integration
• Compression options for large graphs
• Distributed graphs for multi-repo analysis

Acknowledgments

This project draws inspiration from:

• Rust Language governance model
• SQLite's reliability principles
• Redis project philosophy
• Kubernetes governance structure

Built with ❤️ in Rust