System Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib.rs
• rust-code-analysis-cli/src/main.rs
• README.md
• rust-code-analysis-book/src/developers/README.md
• src/macros.rs
• src/tools.rs
• rust-code-analysis-book/src/commands/rest.md

rust-code-analysis is a multi-layered ecosystem designed to analyze, extract metrics, and transform source code across various programming languages. The system is built upon a core library that leverages Tree Sitter for incremental parsing and Abstract Syntax Tree (AST) generation. This foundation supports multiple interfaces, including a Command Line Interface (CLI) and a Web-based REST API, providing flexible integration for developers and automated systems.

Sources: README.md:14-26, src/lib.rs:1-5

Core Architecture Components

The project is structured as a workspace containing three primary components that fulfill different operational requirements.

Component	Description	Reference
rust-code-analysis	The core Rust library providing the API for parsing and metric extraction.	src/lib.rs
rust-code-analysis-cli	A command-line tool for direct interaction with the library's API.	rust-code-analysis-cli/src/main.rs
rust-code-analysis-web	A web server implementation offering the library's features via a REST API.	rust-code-analysis-book/src/commands/rest.md

Sources: README.md:14-26, rust-code-analysis-book/src/developers/README.md:32-48

Layered Processing Flow

The system operates by ingesting source code, determining the target language, parsing it into an AST, and then executing specific callbacks (e.g., metric calculation or comment removal).

The diagram above illustrates the high-level data flow from raw source code to structured analytical output.
Sources: src/lib.rs:43-125, rust-code-analysis-cli/src/main.rs:77-133, src/tools.rs:188-228

Core Library Features

The central library handles the complexity of managing different language grammars and providing a unified interface for analysis. It includes modules for:

• AST Traversal: Utilities to navigate and inspect nodes within the syntax tree.
• Metric Calculation: Implementation of complex metrics like Cyclomatic Complexity (CC), Halstead, and Maintainability Index (MI).
• Preprocessing: Support for C/C++ preprocessor results and include fixing.
• Concurrency: A ConcurrentRunner to process multiple files in parallel using available CPU resources.

Sources: src/lib.rs:43-125, rust-code-analysis-cli/src/main.rs:248-261

Language Support and Dispatch

The library uses macros to implement trait-based dispatch for different languages. This allows a single action function to execute tasks across C++, Rust, Python, and more.

pub fn action<T: Callback>(lang: &LANG, source: Vec<u8>, path: &Path, pr: Option<Arc<PreprocResults>>, cfg: T::Cfg) -> T::Res {
    match lang {
        $(
            LANG::$camel => {
                let parser = $parser::new(source, path, pr);
                T::call(cfg, &parser)
            },
        )*
    }
}

Sources: src/macros.rs:135-144

Command Line Interface (CLI)

The CLI acts as a wrapper around the core library, providing an interface for users to run analyses on local files or directories. It supports glob-based inclusion/exclusion and multi-threaded execution.

CLI Execution Sequence

The following sequence shows how the CLI processes a user request to compute metrics.

The CLI coordinates file discovery and delegates the heavy lifting of analysis to the core library via the ConcurrentRunner.
Sources: rust-code-analysis-cli/src/main.rs:77-164, rust-code-analysis-cli/src/main.rs:275-300

Web Service (REST API)

The web component provides a stateless interface for analysis. It exposes endpoints to compute metrics, remove comments, or retrieve function spans without requiring the user to have a local Rust environment.

API Endpoints

Endpoint	Method	Description
/ping	GET	Health check.
/comments	POST	Removes comments from provided code.
/functions	POST	Retrieves function names and their line spans.
/metrics	POST	Computes full code metrics for the provided snippet.

Sources: rust-code-analysis-book/src/commands/rest.md:14-100

Utility and Support Systems

Language Detection

The system identifies languages through three primary mechanisms:

1. File Extensions: Mapping extensions like .rs or .py to internal LANG enums.
2. Emacs/Vim Modelines: Parsing headers within the file (e.g., -*- mode: c++ -*-).
3. Explicit Override: User-provided language flags in CLI or API requests.

Sources: src/tools.rs:125-132, src/tools.rs:188-228, src/macros.rs:232-248

Build and Test Infrastructure

The project utilizes cargo for building and testing, with specific flags for workspace-wide operations. Snapshots are used for regression testing via the insta crate.

# Build the entire workspace
cargo build --workspace

# Run all tests with features
cargo test --workspace --all-features --verbose

Sources: rust-code-analysis-book/src/developers/README.md:32-52, README.md:41-55

Conclusion

The architecture of rust-code-analysis follows a modular design that isolates parsing logic (via Tree Sitter) from analysis logic (the core library) and presentation (CLI and Web). This separation ensures that new languages can be added with minimal impact on the existing analytical infrastructure, while providing consistent metrics across all interfaces.