Module analysis 

Analysis Module

Graph analysis with I/O and traversal capabilities for JavaScript/TypeScript module graphs.

This module provides the Analyzer API and related analysis functionality that operates on top of the fob-graph data structures. It enables fast, standalone analysis of module dependency graphs without requiring full bundling.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Analyzer API                          │
│  (Typestate pattern: Unconfigured → Configured → Analysis)  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                      GraphWalker                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Traversal   │  │    Parser    │  │  Validation  │      │
│  │   (BFS)      │→ │  (Extract)   │→ │  (Security)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    ModuleResolver                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Algorithm   │  │   Aliases    │  │  Extensions  │      │
│  │ (Resolution) │→ │  (Path maps) │→ │  (.ts, .js)  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    ModuleGraph                              │
│              (from fob-graph crate)                         │
└─────────────────────────────────────────────────────────────┘

Features

• Type-safe API: Typestate pattern ensures analysis can only be performed after configuration is complete
• Security: Path traversal protection and DoS limits (max depth, max modules, file size)
• Framework Support: Extracts JavaScript/TypeScript from framework components
• Path Aliases: Supports path alias resolution (e.g., @ → ./src)
• External Packages: Mark npm packages as external to skip analysis
• Usage Analysis: Compute export usage counts across the module graph

Quick Start

use fob_graph::{Analyzer, Result};

// Create analyzer and configure entry points
let analysis = Analyzer::new()
    .entry("src/index.ts")  // Required: transitions to Configured state
    .external(vec!["react", "lodash"])  // Mark as external
    .path_alias("@", "./src")  // Configure path aliases
    .max_depth(Some(100))  // Set DoS protection limits
    .analyze()  // Only available on Configured
    .await?;

// Use analysis results
let unused = analysis.unused_exports()?;
println!("Found {} unused exports", unused.len());

let circular = analysis.find_circular_dependencies()?;
println!("Found {} circular dependencies", circular.len());

Module Organization

• analyzer - Main Analyzer API with typestate pattern
• config - Configuration types and constants
• walker - Graph traversal and module parsing
  • [walker::traversal] - BFS traversal logic
  • [walker::parser] - Module parsing and script extraction
  • [walker::validation] - Path security validation
• resolver - Module resolution algorithm
  • [resolver::algorithm] - Core resolution logic
  • [resolver::aliases] - Path alias handling
  • [resolver::extensions] - File extension resolution
• extractors - Framework-specific script extractors
• result - Analysis result types

Security Considerations

The analyzer includes several security features:

• Path Traversal Protection: All paths are validated to prevent escaping the current working directory
• DoS Protection: Limits on maximum depth, module count, and file size prevent resource exhaustion attacks
• File Size Limits: Files larger than MAX_FILE_SIZE (10MB) are rejected

Examples

See the examples/ directory for more detailed usage examples:

• basic_analysis.rs - Simple analysis workflow
• path_aliases.rs - Configuring and using path aliases
• circular_detection.rs - Detecting circular dependencies
• framework_components.rs - Analyzing framework-specific components

Re-exports

pub use analyzer::Analyzer;

pub use analyzer::Configured;

pub use analyzer::Unconfigured;

pub use cache::CacheAnalysis;

pub use cache::CacheEffectiveness;

pub use config::AnalyzerConfig;

pub use config::ResolveResult;

pub use result::AnalysisResult;

pub use trace::ImportOutcome;

pub use trace::ImportResolution;

pub use trace::RenameEvent;

pub use trace::RenamePhase;

pub use trace::TransformationTrace;

Modules

analyzer

Fast standalone analysis API without bundling.

cache

config

Shared configuration types for analysis and building.

extractors

Framework script extractors.

resolver

Module resolution for standalone analysis.

result

stats

trace

walker

Graph walker for dependency traversal.

Structs

AnalyzeOptions

Options for the analyze() function.

Enums

AnalyzeError

Error that can occur during analysis.

Functions

analyze

Convenience function using default options.

analyze_with_options

Analyze module graph with custom options.