ForgeKit - Code Intelligence SDK for Rust

ForgeKit provides a unified SDK for code intelligence operations, integrating multiple tools into a single API with support for both SQLite and Native V3 backends.

Features

Core SDK:

• Graph queries: Symbol lookup, reference tracking, call graph navigation
• Impact analysis: k-hop traversal to find affected symbols
• Semantic search: Pattern-based code search via LLMGrep
• Control flow analysis: CFG construction and analysis via Mirage
• Dead code detection: Find unused functions and methods
• Complexity metrics: Cyclomatic complexity and risk analysis
• Safe code editing: Span-safe refactoring via Splice

Workflow Orchestration (v0.4):

• DAG-based task execution with dependency resolution
• Parallel execution via fork-join pattern
• State checkpointing and recovery
• Cancellation tokens and timeout handling
• Compensation-based rollback (saga pattern)
• YAML workflow parser for declarative workflows
• Tool registry with fallback handlers

Infrastructure:

• Dual backend support: SQLite (stable) or Native V3 (high performance)
• Async-first: Built on Tokio
• Type-safe error handling with thiserror

Quick Start

use forge_core::{Forge, BackendKind};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Open a codebase with default backend (SQLite)
    let forge = Forge::open("./my-project").await?;
    
    // Find symbols
    let symbols = forge.graph().find_symbol("main").await?;
    println!("Found: {:?}", symbols);
    
    // Find all callers of a function
    let callers = forge.graph().callers_of("my_function").await?;
    println!("Callers: {}", callers.len());
    
    // Impact analysis - what would break if we change this?
    let impact = forge.graph()
        .impact_analysis("critical_function", Some(2))
        .await?;
    println!("Affected symbols: {}", impact.len());
    
    Ok(())
}

Installation

Add to your Cargo.toml:

[dependencies]
forge-core = "0.2"

Feature Flags

Storage Backends:

• sqlite - SQLite backend (default)
• native-v3 - Native V3 high-performance backend

Tool Integrations:

• magellan-sqlite / magellan-v3 - Code indexing
• llmgrep-sqlite / llmgrep-v3 - Semantic search
• mirage-sqlite / mirage-v3 - CFG analysis
• splice-sqlite / splice-v3 - Code editing

Convenience Groups:

• tools-sqlite - All tools with SQLite
• tools-v3 - All tools with V3
• full-sqlite / full-v3 - Everything

Examples

# Default: SQLite backend with all tools
forge-core = "0.2"

# Native V3 backend with all tools
forge-core = { version = "0.2", features = ["full-v3"] }

# Minimal: Just storage backends
forge-core = { version = "0.2", default-features = false, features = ["sqlite"] }

Workspace Structure

Crate	Purpose	Documentation
forge_core	Core SDK with graph, search, CFG, and edit APIs	API Docs
forge_runtime	Indexing, caching, and file watching	Architecture
forge_agent	Workflow orchestration and agent loop	Manual

Backend Comparison

Feature	SQLite	Native V3
ACID Transactions	✅ Full	✅ WAL-based
Raw SQL Access	✅ Yes	❌ No
Dependencies	libsqlite3	Pure Rust
Performance	Fast	10-20x faster
Tool Compatibility	All tools	All tools (v2.0.5+)

Recommendation: Use Native V3 for new projects. Use SQLite if you need raw SQL access.

Working Examples

Impact Analysis

Find all symbols that would be affected by changing a function:

let forge = Forge::open("./project").await?;

// Find all symbols within 2 hops of "process_request"
let impacted = forge.graph()
    .impact_analysis("process_request", Some(2))
    .await?;

for symbol in impacted {
    println!("{} ({} hops): {}", 
        symbol.name, 
        symbol.hop_distance,
        symbol.file_path
    );
}

Dead Code Detection

Find unused functions in your codebase:

let analysis = forge.analysis();

let dead_code = analysis.find_dead_code().await?;
for symbol in dead_code {
    println!("Unused: {} in {}", symbol.name, symbol.location.file);
}

Complexity Analysis

Calculate cyclomatic complexity:

let analysis = forge.analysis();

// From source code
let metrics = analysis.analyze_source_complexity(source_code);
println!("Complexity: {} ({})", 
    metrics.cyclomatic_complexity,
    metrics.risk_level().as_str()
);

Control Flow Analysis

let cfg = forge.cfg();

// Get dominator tree for a function
let dominators = cfg.dominators(symbol_id).await?;

// Find loops
let loops = cfg.loops(symbol_id).await?;

// Enumerate paths
let paths = cfg.paths(symbol_id)
    .normal_only()
    .max_length(10)
    .execute()
    .await?;

Pattern Search

let search = forge.search();

// Regex pattern search
let results = search.pattern(r"fn.*test.*\(").await?;

// Semantic search
let results = search.semantic("authentication logic").await?;

Documentation

• API Reference - Complete API documentation
• Architecture - System design and internals
• Manual - User guide and tutorials
• Contributing - Contribution guidelines
• Changelog - Version history

Tool Integrations

ForgeKit integrates with these code intelligence tools:

Tool	Purpose	Backend Support
magellan	Code indexing and graph queries	SQLite, V3
llmgrep	Semantic code search	SQLite, V3
mirage-analyzer	CFG analysis	SQLite, V3
splice	Span-safe editing	SQLite, V3

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Current Version: 0.4.0

Status: The crate has not yet been published to crates.io. APIs may change until v1.0.

Compiler Warnings: The project uses sqlitegraph 2.0.8 which has 61 intentional dead code warnings. These are kept for API completeness, feature-gated functionality, and future use - they do not indicate bugs or incomplete code.