The cognitive_complexity package provides a high-performance, deterministic
CLI scanner for measuring Cognitive Complexity across Dart and Flutter
codebases.
Requires Dart SDK 3.12.0 or greater.
Run the scanner directly in any Dart or Flutter project using the @ syntax,
which resolves and executes the latest published version:
dart run cognitive_complexity@ [options] [targets]Add the package to dev_dependencies in pubspec.yaml:
dev_dependencies:
cognitive_complexity: ^1.0.0Execute locally:
dart run cognitive_complexity [options] [targets]Install globally onto your system PATH:
dart install cognitive_complexity
cognitive_complexity [options] [targets]In addition to cognitive_complexity, the package includes three specialized
static-analysis CLIs:
dart run cognitive_complexity:data_flow: Statement-level data-flow and method-extraction slice analyzer (--sdk-pathsupported).dart run cognitive_complexity:file_split: Intra-file dependency graph and acyclic file-decomposition advisor (--sdk-pathsupported).dart run cognitive_complexity:shallow: Single-caller shallow-helper and nesting-aware re-inlining advisor.
| Option / Flag | Type | Default | Description |
|---|---|---|---|
-h, --help |
flag |
false |
Print usage information and exit. |
-t, --threshold <value> |
int |
0 |
Minimum complexity score to include in the report. |
-f, --fail-threshold <value> |
int |
None | Ceiling score; exits with code 1 if any declaration exceeds this value. |
--max-file-lines <lines> |
int |
0 |
Opt-in maximum physical line count per source file (0 = disabled). |
--max-function-lines <lines> |
int |
0 |
Opt-in maximum line span per function/method declaration (0 = disabled). |
-d, --git-diff <git-ref> |
String |
None | Compares current workspace declarations against <git-ref>, evaluating complexity deltas (Δ). |
--fail-on-increase |
flag |
false |
With --git-diff, fails if any modified function increases in complexity (or exceeds --fail-threshold when both are set). |
--format <type> |
enum |
text |
Output format: text (terminal), json (machine-readable), or github (GHA annotations). |
-v, --verbose |
flag |
false |
With --format=text, adds a Breakdown column (branches, nesting, boolean_ops, max_depth) and tags _test.dart entrypoints. |
--comment-output <path> |
String |
None | With --format=github and --git-diff, writes a significance-ordered standalone PR comment report. |
--max-comment-rows <count> |
int |
0 |
Maximum table rows in --comment-output (0 = unlimited). |
--exclude <glob> |
multi |
None | Glob patterns of files/directories to exclude (repeatable or comma-separated). |
--[no-]ignore-generated |
flag |
true |
Exclude generated files (*.g.dart, *.freezed.dart, *.mocks.dart, etc.). |
Note
By default, --format=json emits a top-level JSON array of declaration
objects ([...]). When --max-file-lines is enabled (> 0), it emits a
top-level object {"declarations": [...], "files": [...]} so file-line
violations are reported alongside declaration scores.
Pass one or more file paths or directories as positional arguments:
# Scan specific directories
dart run cognitive_complexity lib bin
# Scan specific files
dart run cognitive_complexity lib/src/analyzer.dart lib/src/visitor.dart
# Auto-discover lib/ (or workspace members packages/*/lib, pkgs/*/lib)
dart run cognitive_complexityThe --git-diff option compares declarations in the working copy against a base
Git ref (such as origin/main or a feature branch base).
When --fail-on-increase is specified alongside --fail-threshold, a
complexity increase does not fail the run as long as the total score remains
below or equal to the --fail-threshold. This permits minor additions (e.g.
input validation or error handlers) while enforcing an absolute ceiling:
dart run cognitive_complexity --git-diff=origin/main --fail-threshold=15 --fail-on-increaseWhen --fail-on-increase is specified without --fail-threshold, any
complexity increase on a modified function immediately exits with code 1:
dart run cognitive_complexity --git-diff=origin/main --fail-on-increase0: Scan completed successfully; all thresholds and gates satisfied.1: Complexity ceiling exceeded, unauthorized complexity increase detected, file/function line limit exceeded, or fatal analysis error.64: Invalid command-line arguments, unknown option, or missing target path.