cognitive_complexity library
A deterministic, algorithmic Cognitive Complexity calculation library and CLI tool for Dart and Flutter.
Supports modern Dart 3 features including switch expressions, pattern
guards (when clauses), and declarative collection control flow elements.
Also provides standard Git diff historical evaluation and GitHub Actions
diagnostic reporting capabilities.
Classes
- ComplexityAnalyzer
- Analyzes Dart files and directories to compute Cognitive Complexity scores and optional file/declaration line counts.
- ComplexityDelta
- Represents the comparison between historical and current complexity scores and declaration line spans.
- DeclarationUnit
- A single top-level declaration within an analyzed Dart source file.
- DeltaAnalyzer
- Evaluates git diffs to calculate cognitive complexity score deltas and optional file/declaration line deltas.
- DeltaSummary
- Summarizes cognitive complexity delta metrics across a repository evaluation.
- FileLineDelta
- Represents the comparison between historical and current file line counts.
- FileLineMetric
- Represents the total physical line count of a Dart source file.
- FileSplitAnalyzer
-
Analyzes a Dart source file's resolved AST to build its intra-file
declaration dependency graph, condense Strongly Connected Components (SCCs),
absorb single-dominator private helpers, and recommend low-churn acyclic
extraction cuts (
Tier 1,Tier 2, orTier 3). - FileSplitReport
- Complete decomposition report for an analyzed Dart file.
- FunctionComplexity
- Represents the analyzed cognitive complexity of a specific declaration.
- GitDiffService
- A service wrapping Git commands for repository evaluation and diffing.
- GitHubReporter
- Formats and emits diagnostic reports specifically for GitHub Actions CI/CD.
- PathFilter
- Configurable path filter evaluating whether file paths should be excluded from analysis.
- ShallowAnalyzer
- Analyzes Dart files and directories to detect single-caller shallow helper functions and simulate their exact caller Cognitive Complexity when inlined.
- ShallowFinding
- Represents a single-caller helper function or method flagged as a shallow extraction candidate.
- ShallowReport
-
Summary report produced by
ShallowAnalyzer. - SplitCluster
-
A recommended extraction cut produced by
FileSplitAnalyzer.
Enums
- DeltaStatus
- Describes the delta trajectory of a function's cognitive complexity score or file/declaration line count.
- ShallowClassification
- Classification of a single-caller shallow helper based on simulated caller Cognitive Complexity after inlining.
- SplitTier
-
The 3-Tier File Decomposition classification (analogous to
data_flow's 3-Tier Function Decomposition Rubric).
Constants
- kAskUserPartsPreferenceDirective → const String
-
Default instruction surfaced when
part/part ofis auto-recommended (useParts == null) for an oversized class or tightly coupled SCC.
Functions
-
compareBySignificance(
ComplexityDelta a, ComplexityDelta b, {int? failThreshold, int? maxFunctionLines, bool failOnIncrease = false}) → int - Orders deltas for review: violations first, then new score descending, then delta descending, then file path, name, and start line so ties are deterministic.
-
isExcludedPath(
String relativePath) → bool -
Whether
relativePathsits inside a directory that should never be scanned (.dart_tool,.git, orbuildoutput).
Typedefs
- ComplexityComposition = ({int booleanOps, int branches, int maxDepth, int nesting})
- Breakdown of a Cognitive Complexity score.