CLI: Computing Metrics

Relevant source files

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

• rust-code-analysis-book/src/commands/metrics.md
• rust-code-analysis-cli/README.md
• rust-code-analysis-cli/Cargo.toml
• src/spaces.rs
• src/output/dump_metrics.rs
• src/lib.rs

The rust-code-analysis-cli tool provides a command-line interface for calculating a wide array of static code metrics across multiple programming languages. It acts as a wrapper around the core rust-code-analysis library, allowing users to analyze local files or directories and export results in standardized formats like JSON, YAML, TOML, and CBOR.

This system is designed for high performance, utilizing Tree-sitter for incremental parsing and supporting multi-threaded processing of files. The metrics extracted provide quantitative data regarding code complexity, maintainability, and size, aiding developers in identifying problematic areas within a codebase.

Sources: rust-code-analysis-cli/README.md, src/lib.rs:1-12, rust-code-analysis-book/src/commands/metrics.md

Core Execution Flow

The CLI operates by accepting paths to files or directories, determining the language type, and invoking the core library's metrics function. The process involves parsing source code into an Abstract Syntax Tree (AST), traversing that tree to identify "spaces" (such as functions, classes, or modules), and accumulating metric data for each space.

The diagram above illustrates the high-level data flow from user input to the final metric representation.
Sources: src/spaces.rs:245-310, rust-code-analysis-cli/README.md

CLI Parameters and Configuration

The CLI supports various options to control the depth of analysis, the output format, and the execution environment.

Command Line Options

Option	Long Flag	Description
-p	--paths	Paths to the files or directories to be analyzed.
-m	--metrics	Required flag to trigger metric computation.
-O	--output-format	Format for export: json, toml, yaml, or cbor.
-o	--output	Target directory for output files.
--pr		Pretty-print JSON output.
-j	--num-jobs	Number of threads to use for analysis.
-I	--include	Include files matching specific patterns.
-X	--exclude	Exclude files matching specific patterns.

Sources: rust-code-analysis-cli/README.md, rust-code-analysis-book/src/commands/metrics.md

Usage Example

To compute and export pretty-printed JSON metrics for a specific file:

rust-code-analysis-cli -m -p /path/to/code.rs --pr -O json -o /output/dir

Sources: rust-code-analysis-book/src/commands/metrics.md

Data Structures: Functional Spaces and Metrics

The analysis results are structured into FuncSpace objects. A FuncSpace represents a logical unit of code and contains both metadata and a CodeMetrics container.

FuncSpace Structure

The FuncSpace structure captures the hierarchy of the analyzed code, where a top-level unit (like a file) contains nested subspaces (like functions or classes).

This relationship allows the CLI to report metrics at different levels of granularity, from the whole file down to specific closures.
Sources: src/spaces.rs:114-135

Metric Categories

The CodeMetrics struct aggregates various metric suites:

• Loc (Lines of Code): Includes SLOC (source), PLOC (physical), LLOC (logical), CLOC (comment), and blank lines.
• Cyclomatic Complexity: Measures control flow complexity.
• Cognitive Complexity: Measures how difficult code is to understand.
• Halstead: Suite for volume, difficulty, and effort.
• MI (Maintainability Index): Calculates a maintainability score based on other metrics.
• NOM (Number of Methods): Counts functions and closures.

Sources: src/spaces.rs:77-101, src/lib.rs:14-43

Output and Serialization

The tool provides two primary ways to view results: terminal dumping and file serialization.

Terminal Dumping

When results are printed to the console, the tool uses the dump_root function to create a tree-like visualization with color-coded metrics.

pub fn dump_root(space: &FuncSpace) -> std::io::Result<()> {
    let stdout = StandardStream::stdout(ColorChoice::Always);
    let mut stdout = stdout.lock();
    dump_space(space, "", true, &mut stdout)?;
    color(&mut stdout, Color::White)?;
    Ok(())
}

Sources: src/output/dump_metrics.rs:43-50

File Export Logic

Serialization is handled via serde. The CLI supports several formats defined in its dependencies:

• serde_json for JSON/Pretty JSON
• toml for TOML format
• serde_yaml for YAML format
• serde_cbor for binary CBOR format

Sources: rust-code-analysis-cli/Cargo.toml:19-25, rust-code-analysis-book/src/commands/metrics.md

Summary

The "CLI: Computing Metrics" feature provides a robust entry point for static analysis. By leveraging Tree-sitter for multi-language support and a hierarchical data model (FuncSpace), it enables developers to extract deep insights into code maintainability and complexity directly from their terminal or as part of a CI/CD pipeline.