Crate big_code_analysis

Expand description

big-code-analysis is a library to analyze and extract information from source codes written in many different programming languages.

You can find the source code of this software on GitHub, while issues and feature requests can be posted on the respective GitHub Issue Tracker.

§Quick start

Most callers want the recommended entry points exposed in prelude:

use big_code_analysis::prelude::*;

let source = b"fn main() {}";
let space = analyze(
    Source::new(LANG::Rust, source),
    MetricsOptions::default(),
).expect("Rust source parses");
println!("cognitive sum: {}", space.metrics.cognitive.cognitive_sum());

§Supported Languages

Each grammar is gated behind a per-language Cargo feature; the default all-languages feature enables every grammar so the historical “every language compiled in” behaviour is preserved. Library consumers that only need a subset can opt out of the defaults — see Per-language Cargo features in the book.

Bash (bash)
C/C++ (cpp, also exposes the internal Ccomment / Preproc helpers)
C# (csharp)
Elixir (elixir)
Go (go)
Groovy (groovy)
Java (java)
JavaScript (javascript)
JavaScript, Firefox-internal “MozJS” (mozjs)
Kotlin (kotlin)
Lua (lua)
Perl (perl)
PHP (php)
Python (python)
Ruby (ruby)
Rust (rust)
Tcl (tcl)
TSX (typescript)
TypeScript (typescript)

§Supported Metrics

ABC: it measures the size of a source code based on assignments, branches, and conditions.
CC: it calculates the code complexity examining the control flow of a program. Both standard and modified flavours are exposed: the modified variant collapses all case/match arms inside a single switch/match/when/select into one decision point.
Cognitive Complexity: it measures how difficult it is to understand a unit of code.
SLOC: it counts the number of lines in a source file.
PLOC: it counts the number of physical lines (instructions) contained in a source file.
LLOC: it counts the number of logical lines (statements) contained in a source file.
CLOC: it counts the number of comments in a source file.
BLANK: it counts the number of blank lines in a source file.
HALSTEAD: it is a suite that provides a series of information, such as the effort required to maintain the analyzed code, the size in bits to store the program, the difficulty to understand the code, an estimate of the number of bugs present in the codebase, and an estimate of the time needed to implement the software.
MI: it is a suite that allows to evaluate the maintainability of a software.
NOM: it counts the number of functions and closures in a file/trait/class.
NEXITS: it counts the number of possible exit points from a method/function.
NARGS: it counts the number of arguments of a function/method.
NPA: it counts the number of public attributes of a class.
NPM: it counts the number of public methods of a class.
WMC: it is the sum of the complexities of all methods in a class.

Re-exports§

pub use crate::output::CSV_EXTENSION;
pub use crate::output::CSV_HEADER;
pub use crate::output::Dump;
pub use crate::output::DumpCfg;
pub use crate::output::OffenderRecord;
pub use crate::output::Severity;
pub use crate::output::TOOL_ID;
pub use crate::output::dump_node;
pub use crate::output::dump_ops;
pub use crate::output::dump_ops;
pub use crate::output::dump_root;
pub use crate::output::write_checkstyle;
pub use crate::output::write_clang_warning;
pub use crate::output::write_csv;
pub use crate::output::write_msvc_warning;
pub use crate::output::write_sarif;
pub use ::tree_sitter;

Modules§

metrics: Per-metric implementations.
output: Output formatters: CSV, SARIF, Checkstyle, clang/MSVC warning lines, and AST/metric pretty-dumps used by bca and the offender reporters.
prelude: Recommended entry points for the 90% case.

Structs§

Ast: Parse-once, compute-many handle.
AstCallback: Type tag identifying the AST extraction action; carries no data.
AstCfg: Configuration options for retrieving the nodes of an AST.
AstNode: Information on an AST node.
AstPayload: The payload of an Ast request.
AstResponse: The response of an AST request.
BashCode: Per-language code type tag for Bash; carries no data.
CcommentCode: Per-language code type tag for Ccomment; carries no data.
CodeMetrics: All metrics data.
CommentRm: Type tag identifying the comment-removal action; carries no data.
CommentRmCfg: Configuration options for removing comments from a code.
ConcurrentRunner: A runner to process files concurrently.
Count: Count of different types of nodes in a code.
CountCfg: Configuration options for counting different types of nodes in a code.
CppCode: Per-language code type tag for Cpp; carries no data.
CsharpCode: Per-language code type tag for Csharp; carries no data.
Cursor: An AST cursor.
ElixirCode: Per-language code type tag for Elixir; carries no data.
FilesData: Data related to files.
Find: Type tag identifying the node-find action; carries no data.
FindCfg: Configuration options for finding different types of nodes in a code.
FuncSpace: Function space data.
Function: Type tag identifying the function-extraction action; carries no data.
FunctionCfg: Configuration options for detecting the span of each function in a code.
FunctionSpan: Function span data.
GoCode: Per-language code type tag for Go; carries no data.
GroovyCode: Per-language code type tag for Groovy; carries no data.
JavaCode: Per-language code type tag for Java; carries no data.
JavascriptCode: Per-language code type tag for Javascript; carries no data.
KotlinCode: Per-language code type tag for Kotlin; carries no data.
LuaCode: Per-language code type tag for Lua; carries no data.
MetricSet: Bitfield of selected metrics.
Metrics: Type tag identifying the metric-computation action; carries no data.
MetricsCfg: Configuration options for computing the metrics of a code.
MetricsOptions: Per-traversal options for [metrics_with_options].
MozjsCode: Per-language code type tag for Mozjs; carries no data.
Node: An AST node.
Ops: All operands and operators of a space.
OpsCfg: Configuration options for retrieving all the operands and operators in a code.
OpsCode: Type tag identifying the operator/operand extraction action; carries no data.
ParseMetricError: Error returned by Metric::from_str when the input is not a recognised metric name.
PerlCode: Per-language code type tag for Perl; carries no data.
PhpCode: Per-language code type tag for Php; carries no data.
PreprocCode: Per-language code type tag for Preproc; carries no data.
PreprocFile: Preprocessor data of a C/C++ file.
PreprocResults: Preprocessor data of a series of C/C++ files.
PythonCode: Per-language code type tag for Python; carries no data.
RubyCode: Per-language code type tag for Ruby; carries no data.
RustCode: Per-language code type tag for Rust; carries no data.
Source: In-memory source bundle handed to analyze.
TclCode: Per-language code type tag for Tcl; carries no data.
TsxCode: Per-language code type tag for Tsx; carries no data.
TypescriptCode: Per-language code type tag for Typescript; carries no data.

Enums§

ConcurrentErrors: Series of errors that might happen when processing files concurrently.
LANG: The list of supported languages.
Metric: One metric computed by the analysis walker.
MetricKind: Stable metric identifier set that suppression markers can name.
MetricsError: Error returned by the library’s metric-computation entry points.
SpaceKind: The list of supported space kinds.
SuppressionPolicy: Whether downstream consumers (threshold checking, audit logging) should honor parsed suppression markers.
SuppressionScope: Which metrics a suppression marker covers.

Traits§

Callback: A trait for callback functions.
LanguageInfo: Static identification of a language code tag.

Functions§

action: Runs a function, which implements the Callback trait, on a code written in one of the supported languages.
analyze: Compute every metric for a Source.
fix_includes: Constructs a dependency graph of the include directives in a C/C++ file.
get_from_emacs_mode: Detects the language associated to the input Emacs mode.
get_from_ext: Detects the language associated to the input file extension.
get_function_spacesDeprecated: Returns all function spaces data of a code.
get_function_spaces_with_optionsDeprecated: Returns all function spaces data of a code, applying the per-traversal flags in options (e.g. exclude_tests: true to elide Rust #[cfg(test)] / #[test] subtrees from every metric). Equivalent to get_function_spaces when options is the default.
get_language_for_file: Detects the language of a code using the extension of a file.
get_macros: Returns the macros contained in a C/C++ file.
get_ops: Returns all operators and operands of each space in a code.
guess_language: Guesses the language of a code.
is_generated: Returns true when buf looks like generated code: its leading window (first ~50 lines or first 5 KiB, whichever is smaller) contains a known marker phrase. Matching is case-insensitive for the marker and never allocates on the negative path.
metrics_from_tree: Returns all function spaces data of a code, reusing a caller-supplied tree_sitter::Tree instead of running the bundled parser.
preprocess: Extracts preprocessor data from a C/C++ file and inserts these data in a PreprocResults object.
read_file: Reads a file, normalising all CR-only and CRLF line endings to LF.
read_file_with_eol: Reads a file, normalising all CR-only and CRLF line endings to LF, and ensures the buffer ends with exactly one \n. Returns None for files ≤ 3 bytes or files that appear to be non-UTF-8.
write_file: Writes data to a file.

Type Aliases§

BashParser: The Bash language parser.
CcommentParser: The Ccomment language parser.
CppParser: The Cpp language parser.
CsharpParser: The Csharp language parser.
ElixirParser: The Elixir language parser.
GoParser: The Go language parser.
GroovyParser: The Groovy language parser.
JavaParser: The Java language parser.
JavascriptParser: The Javascript language parser.
KotlinParser: The Kotlin language parser.
LuaParser: The Lua language parser.
MozjsParser: The Mozjs language parser.
PerlParser: The Perl language parser.
PhpParser: The Php language parser.
PreprocParser: The Preproc language parser.
PythonParser: The Python language parser.
RubyParser: The Ruby language parser.
RustParser: The Rust language parser.
Span: Start and end positions of a node in a code in terms of rows and columns.
TclParser: The Tcl language parser.
TsxParser: The Tsx language parser.
TypescriptParser: The Typescript language parser.