CLI: Analyzing Nodes and Errors
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The rust-code-analysis-cli tool provides specialized commands to inspect the structural elements of source code, referred to as nodes, which are part of an Abstract Syntax Tree (AST). Nodes represent syntactic constructs in various programming languages, and the CLI allows developers to count specific constructs, detect syntactic errors, and visualize the code's structural hierarchy.
This functionality is critical for finding code syntax errors before compilation and for gaining insights into the syntactic density of a project. By leveraging Tree Sitter, the CLI can identify if a specific language construct is present and locate where errors occur in the source file.
Sources: rust-code-analysis-book/src/commands/README.md, rust-code-analysis-book/src/commands/nodes.md, README.md
Node Analysis Capabilities
The CLI supports several operations related to nodes, primarily driven by the Find and Count modules in the underlying library.
Error Detection
One of the primary uses of node analysis is identifying syntactic errors. Users can filter for nodes of a specific type (e.g., error) across a directory or file.
rust-code-analysis-cli -p /path/to/code -I "*.rs" -f error
Sources: rust-code-analysis-book/src/commands/nodes.md:5-13
Node Counting
The CLI can tally occurrences of specific node types using the --count flag. This is useful for statistical analysis of codebases, such as counting the number of if_statement or function_definition nodes.
Sources: rust-code-analysis-book/src/commands/nodes.md:16-22, rust-code-analysis-cli/src/main.rs:252-253
AST Visualization
To understand how the parser interprets source code, the CLI can "dump" the full AST to stdout. This displays the parent-child relationships between all nodes in the file.
Sources: rust-code-analysis-book/src/commands/nodes.md:24-29, rust-code-analysis-cli/src/main.rs:238-239
Technical Implementation
The node analysis logic is implemented through a combination of configuration structures and action handlers.
Core Data Structures
The CLI utilizes specific configuration structs to execute node-related actions:
FindCfg: Stores paths, node filters, and optional line boundaries.CountCfg: Stores filters and a mutex-protectedCountobject for thread-safe tallies.DumpCfg: Defines the range of lines for AST visualization.
Sources: rust-code-analysis-cli/src/main.rs:77-106, src/lib.rs:88-91
Data Flow for Node Operations
The following diagram illustrates the flow from a CLI command to the execution of a node-based action.
The CLI uses a ConcurrentRunner to process files in parallel, applying these actions based on the detected or specified language.
Sources: rust-code-analysis-cli/src/main.rs:136-168, rust-code-analysis-cli/src/main.rs:328-332
CLI Options for Nodes and Errors
The table below summarizes the CLI parameters specifically related to node analysis and error detection.
| Option | Long Flag | Description | Related Config |
|---|---|---|---|
-f | --find | Find and list nodes of a given type. | FindCfg |
-C | --count | Count occurrences of specific node types. | CountCfg |
-d | --dump | Dump the Abstract Syntax Tree to stdout. | DumpCfg |
--ls | --ls | Start line for analysis/dumping. | line_start |
--le | --le | End line for analysis/dumping. | line_end |
Sources: rust-code-analysis-cli/src/main.rs:236-253, rust-code-analysis-cli/README.md:27-44
Partial Code Analysis
Node operations can be constrained to specific portions of a file using the line start (--ls) and line end (--le) parameters. This is particularly useful for debugging specific functions or blocks within large source files.
// In main.rs, these are mapped to the analysis config
let cfg = FindCfg {
path: path.clone(),
filters: cfg.find_filter.clone(),
line_start: cfg.line_start,
line_end: cfg.line_end,
};
Sources: rust-code-analysis-cli/src/main.rs:154-159, rust-code-analysis-book/src/commands/nodes.md:31-38
Conclusion
Node and error analysis in rust-code-analysis-cli provides a technical gateway into the syntactic structure of a project. By leveraging AST traversal, the tool facilitates automated error detection and quantitative analysis of language constructs, supporting 10+ programming languages through a unified interface.