Command Line Interface Usage
Relevant source files
The following files were used as context for generating this wiki page:
The rust-code-analysis-cli is a command-line tool designed to interface with the core rust-code-analysis library. Its primary purpose is to provide an accessible way for developers to compute and export code metrics, analyze source code structure via Abstract Syntax Trees (AST), and perform utility operations like comment removal across multiple programming languages.
Sources: README.md:14-22, rust-code-analysis-cli/README.md:3-8
The CLI supports a broad range of tasks including dumping ASTs to stdout, counting specific node types, finding function spans, and exporting metrics in formats like JSON, TOML, and YAML. It utilizes a concurrent runner to handle large sets of files efficiently.
Sources: rust-code-analysis-cli/README.md:10-14, rust-code-analysis-cli/src/main.rs:260-265
Core Architecture and Execution Flow
The CLI is built using the clap crate for argument parsing and relies on a ConcurrentRunner to execute actions on files in parallel. The execution starts by parsing command-line options into an Opts struct, which is then mapped to a internal Config object.
Sources: rust-code-analysis-cli/src/main.rs:170-222, rust-code-analysis-cli/src/main.rs:258-270
Execution Logic Diagram
The following diagram illustrates the flow from user input to the execution of specific code analysis actions.
The act_on_file function serves as the central dispatcher, determining which library function to call (e.g., Metrics, Dump, CommentRm) based on the provided configuration flags.
Sources: rust-code-analysis-cli/src/main.rs:69-140
Command Options and Features
The CLI provides a variety of options to control input selection, analysis type, and output formatting.
Input Selection and Filtering
Users can specify paths to individual files or entire directories. Filters can be applied using include/exclude globs.
| Option | Short | Description |
|---|---|---|
--paths | -p | Input files or directories to analyze. |
--include | -I | Glob pattern to include specific files (e.g., "*.rs"). |
--exclude | -X | Glob pattern to exclude files. |
--language-type | -l | Manually specify the language of input files. |
Sources: rust-code-analysis-cli/README.md:27-41, rust-code-analysis-book/src/commands/nodes.md:10-12
Analysis Actions
The CLI supports several distinct analysis "modes" triggered by specific flags:
- Metrics (
-m, --metrics): Computes static code metrics such as Cyclomatic Complexity, LOC, and Halstead metrics. - AST Dumping (
-d, --dump): Visualizes the Abstract Syntax Tree. Can be constrained to specific lines using--lsand--le. - Comment Removal (
-c, --comments): Strips comments from the source. Use-i, --in-placeto modify files directly. - Node Operations: Uses
-f, --findto search for specific node types (likeerror) or-C, --countto tally occurrences.
Sources: rust-code-analysis-cli/src/main.rs:88-135, rust-code-analysis-book/src/commands/nodes.md:15-38
Output Management
Analysis results can be exported in several machine-readable formats.
| Format | Description |
|---|---|
| CBOR | Concise Binary Object Representation. |
| JSON | Standard JSON; use --pr for pretty-printed output. |
| TOML | Tom's Obvious, Minimal Language. |
| YAML | YAML Ain't Markup Language. |
Sources: rust-code-analysis-cli/README.md:11-12, rust-code-analysis-cli/src/main.rs:211-215
Internal Data Structures
The CLI relies on specific Rust structures to manage its state during execution.
Config Struct
The Config struct holds the state derived from user input, governing how act_on_file behaves.
struct Config {
dump: bool,
in_place: bool,
comments: bool,
find_filter: Vec<String>,
count_filter: Vec<String>,
language: Option<LANG>,
function: bool,
metrics: bool,
ops: bool,
output_format: Option<Format>,
output: Option<PathBuf>,
pretty: bool,
line_start: Option<usize>,
line_end: Option<usize>,
// ... preprocessor and locking fields
}
Sources: rust-code-analysis-cli/src/main.rs:36-54
Usage Examples
Exporting Metrics
To compute metrics for a Rust file and export them as a pretty-printed JSON file in the current directory:
rust-code-analysis-cli --metrics --output-format json --pr --output . --paths src/main.rs
Sources: rust-code-analysis-cli/README.md:49-51
Detecting Syntactic Errors
To scan a directory for syntax errors in JavaScript files:
rust-code-analysis-cli -p ./project -I "*.js" -f error
Sources: rust-code-analysis-book/src/commands/nodes.md:9-11
Visualizing AST for a Specific Range
To view the AST for lines 10 through 20 of a file:
rust-code-analysis-cli -p file.cpp -d --ls 10 --le 20
Sources: rust-code-analysis-book/src/commands/nodes.md:36-38
Summary
rust-code-analysis-cli serves as a high-performance wrapper around the rust-code-analysis library. By leveraging Rust's concurrency and the Tree-sitter parsing engine, it allows developers to perform deep architectural inspections and quality audits on source code across various languages. Its ability to export data in multiple formats makes it a suitable component for automated CI/CD pipelines and developer tooling.
Sources: README.md:14-20, rust-code-analysis-book/src/developers/README.md:104-108