Crate fob_graph 

fob-graph

Pure graph data structures for module dependency graphs.

This crate provides the core graph primitives and ModuleGraph implementation without any I/O or analysis logic. It’s designed to be lightweight and WASM-compatible.

Overview

fob-graph is the foundation for building module dependency graphs from JavaScript/TypeScript codebases. It provides:

• Pure Data Structures: No I/O, no file system dependencies
• WASM-Compatible: Can run in browser environments
• Thread-Safe: Uses Arc for efficient shared ownership
• Memory Efficient: Arena-based allocation where possible
• Type-Safe: Strong typing for modules, imports, exports, and dependencies

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    ModuleGraph                              │
│  (Arc-based, thread-safe, WASM-compatible)                  │
└────────────────────┬────────────────────────────────────────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
         ▼           ▼           ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ Module  │ │ Import  │ │ Export  │
   │ (Node)  │ │ (Edge)  │ │ (Edge)  │
   └─────────┘ └─────────┘ └─────────┘
         │           │           │
         └───────────┼───────────┘
                     │
                     ▼
         ┌──────────────────────┐
         │   SymbolTable        │
         │   (Intra-file        │
         │    analysis)         │
         └──────────────────────┘

Quick Start

Building a Module Graph

use fob_graph::{ModuleGraph, Module, ModuleId, SourceType};
use std::path::PathBuf;

// Create a new graph
let graph = ModuleGraph::new()?;

// Add a module
let module_id = ModuleId::new("src/index.ts")?;
let module = Module::builder(module_id.clone(), PathBuf::from("src/index.ts"), SourceType::TypeScript)
    .entry(true)
    .build();

graph.add_module(module)?;

// Query the graph
let dependencies = graph.dependencies(&module_id)?;
println!("Dependencies: {:?}", dependencies);

Symbol Analysis

use fob_graph::semantic::analyze_symbols;
use fob_graph::{SourceType, SymbolTable};

let source = r#"
    const used = 42;
    const unused = 100;
    console.log(used);
"#;

let table: SymbolTable = analyze_symbols(source, "example.js", SourceType::JavaScript)?;

// Find unused symbols
let unused = table.unused_symbols();
println!("Unused symbols: {:?}", unused);

Extension Trait Pattern

The crate uses extension traits to add functionality without modifying core types. Methods are organized into logical groups:

• [memory::queries] - Query operations (dependencies, dependents, etc.)
• [memory::mutations] - Modification operations (add module, add dependency)
• [memory::exports] - Export analysis (unused exports, usage counts)
• [memory::symbols] - Symbol-level analysis (unused symbols, statistics)
• [memory::chains] - Dependency chain analysis (circular detection)

Thread Safety

ModuleGraph uses Arc internally for efficient shared ownership. Multiple threads can safely read from the graph concurrently. For modifications, use appropriate synchronization (e.g., Mutex or RwLock).

WASM Compatibility

The crate is designed to work in WASM environments:

• No file system dependencies
• No network dependencies
• Pure Rust data structures
• Compatible with wasm-bindgen and wasm-pack

Re-exports

pub use collection::CollectedExport;

pub use collection::CollectedImport;

pub use collection::CollectedImportSpecifier;

pub use collection::CollectedModule;

pub use collection::CollectionState;

pub use collection::parse_module_structure;

pub use dependency_chain::ChainAnalysis;

pub use dependency_chain::DependencyChain;

pub use export::Export;

pub use export::ExportKind;

pub use external_dep::ExternalDependency;

pub use framework_rules::FrameworkRule;

pub use from_collection::CollectionGraphError;

pub use import::Import;

pub use import::ImportKind;

pub use import::ImportSpecifier;

pub use module::Module;

pub use module::SourceType;

pub use module_id::ModuleId;

pub use module_id::ModuleIdError;

pub use package_json::DependencyCoverage;

pub use package_json::DependencyType;

pub use package_json::PackageJson;

pub use package_json::TypeCoverage;

pub use package_json::UnusedDependency;

pub use package_json::extract_package_name;

pub use span::SourceSpan;

pub use statistics::GraphStatistics;

pub use symbol::ClassMemberMetadata;

pub use symbol::EnumMemberMetadata;

pub use symbol::EnumMemberValue;

pub use symbol::Symbol;

pub use symbol::SymbolKind;

pub use symbol::SymbolMetadata;

pub use symbol::SymbolSpan;

pub use symbol::SymbolStatistics;

pub use symbol::SymbolTable;

pub use symbol::UnreachableCode;

pub use symbol::UnusedSymbol;

pub use symbol::Visibility;

pub use runtime::FileMetadata;

pub use runtime::Runtime;

pub use runtime::RuntimeError;

pub use runtime::RuntimeResult;

pub use runtime::native::NativeRuntime;

pub use analysis::AnalysisResult;

pub use analysis::AnalyzeError;

pub use analysis::AnalyzeOptions;

pub use analysis::Analyzer;

pub use analysis::CacheAnalysis;

pub use analysis::CacheEffectiveness;

pub use analysis::Configured;

pub use analysis::ImportOutcome;

pub use analysis::ImportResolution;

pub use analysis::RenameEvent;

pub use analysis::RenamePhase;

pub use analysis::TransformationTrace;

pub use analysis::Unconfigured;

pub use analysis::analyze;

pub use analysis::analyze_with_options;

Modules

analysis

Analysis Module

collection

Shared collection types for module graph analysis.

dependency_chain

Dependency chain analysis for understanding module relationships.

export

external_dep

framework_rules

Framework-aware dead code analysis.

from_collection

Convert intermediate collection types to final graph representation.

import

module

module_id

oxc

OXC (Oxidation Compiler) foundation types re-exported for workspace consistency.

package_json

Package.json parsing and dependency analysis.

runtime

Platform runtime abstraction for Fob bundler

semantic

Semantic analysis engine using Oxc for symbol extraction.

span

statistics

symbol

Symbol tracking for intra-file dead code analysis.

Structs

ClassMemberInfo

Information about a class member symbol

EnumMemberInfo

Information about an enum member

ModuleGraph

In-memory module dependency graph.

NamespaceImportInfo

Information about a namespace import

SideEffectImport

A side-effect-only import (no bindings, just execution)

TypeOnlyImport

A type-only import (TypeScript)

UnusedExport

Output entry for unused exports.

Enums

Error

Error types for fob operations.

Type Aliases

Result

Result type alias for fob operations.