ForgeKit - Deterministic Code Intelligence SDK

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

• 🔍 Graph Queries: Symbol lookup, reference tracking, call graph navigation
• 🔎 Semantic Search: Pattern-based code search via LLMGrep integration
• 🌳 Control Flow Analysis: CFG construction and analysis via Mirage
• ✏️ Safe Code Editing: Span-safe refactoring via Splice
• 📊 Dual Backend Support: SQLite (stable) or Native V3 (high performance)
• 📡 Pub/Sub Events: Real-time notifications for code changes
• ⚡ Async-First: Built on Tokio for async/await support

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?;
    
    // Or use Native V3 backend for better performance
    let forge = Forge::open_with_backend("./my-project", BackendKind::NativeV3).await?;
    
    // Find symbols
    let symbols = forge.graph().find_symbol("main").await?;
    println!("Found: {:?}", symbols);
    
    // Search code
    let results = forge.search().pattern("fn.*test").await?;
    
    Ok(())
}

Installation

Add to your Cargo.toml:

[dependencies]
forge-core = "0.2"

Feature Flags

ForgeKit uses feature flags for flexible backend and tool selection:

Storage Backends:

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

Tool Integrations (per-backend):

• 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 - Everything with SQLite
• full-v3 - Everything with V3

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"] }

# Mix and match: Magellan with V3, LLMGrep with SQLite
forge-core = { version = "0.2", features = ["magellan-v3", "llmgrep-sqlite"] }

Workspace Structure

ForgeKit is organized as a workspace with three crates:

Backend Comparison

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

Pub/Sub (Real-time Events)

ForgeKit supports real-time event notifications for code changes:

use forge_core::{Forge, BackendKind};
use std::sync::mpsc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let forge = Forge::open_with_backend("./project", BackendKind::NativeV3).await?;
    
    // Subscribe to node changes
    let (id, rx) = forge.subscribe(
        SubscriptionFilter::nodes_only()
    ).await?;
    
    // Receive events in a separate task
    tokio::spawn(async move {
        while let Ok(event) = rx.recv() {
            println!("Code changed: {:?}", event);
        }
    });
    
    Ok(())
}

Event Types

• NodeChanged - Symbol created or modified
• EdgeChanged - Reference/call created or modified
• KVChanged - Key-value store entry changed
• SnapshotCommitted - Transaction committed

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:

License

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

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Note: This is an early-stage project. APIs may change until v1.0.