Analyze
Reports code metrics, rules and anti-patterns violations. To execute the command, run
$ dart run dart_code_metrics:metrics analyze lib
# or for a Flutter package
$ flutter pub run dart_code_metrics:metrics analyze lib
Full command description:
Usage: metrics analyze [arguments...] <directories>
-h, --help Print this usage information.
-r, --reporter=<console> The format of the output of the analysis
[console (default), console-verbose, checkstyle, codeclimate, github, gitlab, html, json]
-o, --output-directory=<OUTPUT> Write HTML output to OUTPUT
(defaults to "metrics/")
--json-path=<path/to/file.json> Path to the JSON file with the output of the analysis.
--cyclomatic-complexity=<20> Cyclomatic Complexity threshold.
--halstead-volume=<150> Halstead Volume threshold.
--lines-of-code=<100> Lines of Code threshold.
--maximum-nesting-level=<5> Maximum Nesting Level threshold.
--number-of-methods=<10> Number of Methods threshold.
--number-of-parameters=<4> Number of Parameters threshold.
--source-lines-of-code=<50> Source lines of Code threshold.
--technical-debt=<0> Technical Debt threshold.
--weight-of-class=<0.33> Weight Of a Class threshold.
--maintainability-index=<50> Maintainability Index threshold.
-c, --print-config Print resolved config.
--root-folder=<./> Root folder
(defaults to current directory)
--sdk-path=<directory-path> Dart SDK directory path.
Should be provided only when you run the application as compiled executable(https://dart.dev/tools/dart-compile#exe) and automatic Dart SDK path detection fails.
--exclude=<{/**.g.dart,/**.freezed.dart}> File paths in Glob syntax to be exclude
(defaults to "{/**.g.dart,/**.freezed.dart}")
--no-congratulate Don't show output even when there are no issues.
--set-exit-on-violation-level=<warning> Set exit code 2 if code violations
have the same or higher level
[none, warning, alarm]
--[no-]fatal-style Treat style level issues as fatal.
--[no-]fatal-performance Treat performance level issues as fatal.
--[no-]fatal-warnings Treat warning level issues as fatal.
Output example
Console
Use --reporter=console
to enable this format.
HTML
Use --reporter=html
to enable this format.
HTML report overview
HTML single file report
HTML report details
JSON
The reporter prints a single JSON object containing meta information and the violations grouped by a file. Use --reporter=json
to enable this format.
The root object fields are
formatVersion
- an integer representing the format version (will be incremented each time the serialization format changes)timestamp
- a creation time of the report in YYYY-MM-DD HH:MM:SS formatrecords
- an array of objectssummary
- an array of objects (optional)
{
"formatVersion": 2,
"timestamp": "2021-04-11 14:44:42",
"records": [
{
...
},
{
...
},
{
...
}
],
"summary": [
{
...
},
{
...
}
]
}
The record object fields are
path
- a relative path to the target filefileMetrics
- an array with target file metricsclasses
- a map with class name as the key and class report as the valuefunctions
- a map with function name as the key and function report as the valueissues
- an array of issues detected in the target fileantiPatternCases
- an array of anti-pattern cases detected in the target file
{
"path": "lib/src/metrics/metric_computation_result.dart",
"classes": {
...
},
"functions": {
...
},
"issues": [
...
],
"antiPatternCases": [
...
]
}
The summary-record object fields are
status
- a status of information in this recordtitle
- a message with information about the recordvalue
- an actual value of this record (can be an array or a single value)violations
- a value of a violations count of a metric associated with this record
{
"status": "warning",
"title": "Average Cyclomatic Number per line of code",
"value": 0.3447098976109215,
"violations": 5
}
The report object fields are
{
"codeSpan": {
...
},
"metrics": [
...
]
}
The code span object fields are
start
- a start location of an entityend
- an end location of an entitytext
- a source code text of an entity
{
"start": {
...
},
"end": {
...
},
"text": "entity source code"
}
The location object fields are
offset
- a zero-based offset of the location in the sourceline
- a zero-based line of the location in the sourcecolumn
- a zero-based column of the location in the source
{
"offset": 156,
"line": 7,
"column": 1
}
The metric value object fields are
metricsId
- an id of the computed metricvalue
- an actual value computed by the metricunitType
- a human readable unit type (optional)level
- a level of the value computed by the metriccomment
- a message with information about the valuerecommendation
- a message with information about how the user can improve the value (optional)context
- an additional information associated with the value that helps understand how the metric was computed
{
"metricsId": "number-of-methods",
"value": 14,
"unitType": "methods",
"level": "warning",
"comment": "This class has 14 methods, which exceeds the maximum of 10 allowed.",
"recommendation": "Consider breaking this class up into smaller parts.",
"context": [
...
]
}
The context message object fields are
message
- an message to be displayed to the usercodeSpan
- a source code span associated with or referenced by the message
{
"message": "getter complexityEntities increase metric value",
"codeSpan": {
...
}
}
The issue object fields are
ruleId
- an id of the rule associated with the issuedocumentation
- an url of a page containing documentation associated with the issuecodeSpan
- a source code span associated with the issueseverity
- a severity of the issuemessage
- a short messageverboseMessage
- a verbose message containing information about how the user can fix the issue (optional)suggestion
- a suggested relevant change (optional)
{
"ruleId": "long-parameter-list",
"documentation": "https://git.io/JUGrU",
"codeSpan": {
...
},
"severity": "none",
"message": "Long Parameter List. This function require 5 arguments.",
"verboseMessage": "Based on configuration of this package, we don't recommend writing a function with argument count more than 4.",
"suggestion": {
...
}
}
The suggestion object fields are
comment
- a human-readable description of the change to be appliedreplacement
- a code with changes to replace original code with
{
"comment": "Add trailing comma",
"replacement": "WeightOfClassMetric.metricId: (config) => WeightOfClassMetric(config: config),"
}
GitHub
Reports about design and static code diagnostics issues in pull requests based on GitHub Actions Workflow commands. Use --reporter=github
to enable this format.
Install dart/flutter and get packages:
Flutter example
jobs:
your_job_name:
steps:
- name: Install Flutter
uses: subosito/flutter-action@master
with:
channel: stable
- name: Install dependencies
run: flutter pub get
...Dart example
jobs:
your_job_name:
steps:
- name: Install Dart
uses: dart-lang/setup-dart@v1
- name: Install dependencies
run: flutter pub get
...Run dart_code_metrics package:
dart_code_metrics
is added todev_dependencies
- name: Run Code Metrics
run: flutter pub run dart_code_metrics:metrics --reporter=github lib
# OR
# run: dart pub run dart_code_metrics:metrics --reporter=github libdart_code_metrics
is not added todev_dependencies
(run as a global dependency)- name: Run Code Metrics
run: flutter pub global activate dart_code_metrics && flutter pub global run dart_code_metrics:metrics --reporter=github lib
# OR
# run: dart pub global activate dart_code_metrics && dart pub global run dart_code_metrics:metrics --reporter=github lib
Full Example
jobs:
your_job_name:
steps:
- name: Install Flutter
uses: subosito/flutter-action@master
with:
channel: stable
- name: Install dependencies
run: flutter pub get
- name: Run Code Metrics
run: flutter pub run dart_code_metrics:metrics --fatal-style --fatal-performance --fatal-warnings --reporter=github lib
Example of a report in a PR:
GitLab
Reports about design and static code diagnostics issues in merge requests based on Code Quality custom tool. Use --reporter=gitlab
to enable this format.
- Define a job in your
.gitlab-ci.yml
file that generates the Code Quality report artifact.
code_quality:
image: dart
before_script:
- dart pub global activate dart_code_metrics
script:
- dart pub global run dart_code_metrics:metrics analyze --fatal-style --fatal-performance --fatal-warnings --reporter=gitlab lib > code-quality-report.json
artifacts:
reports:
codequality: code-quality-report.json
Example of a Code Quality widget in a PR:
Example of a Code Quality in a PR diff view:
Checkstyle
Reports about design and static code diagnostics issues. Use --reporter=checkstyle
to enable this format.
<?xml version="1.0"?>
<checkstyle version="10.0">
<file name="lib/src/analyzers/lint_analyzer/lint_analyzer.dart">
<error line="168" column="3" severity="ignore" message="Long method. This method contains 63 lines with code." source="long-method"/>
</file>
<file name="lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_returning_widgets/visit_declaration.dart">
<error line="3" column="1" severity="ignore" message="Long Parameter List. This function require 6 arguments." source="long-parameter-list"/>
</file>
<file name="lib/src/analyzers/lint_analyzer/reporters/utility_selector.dart">
<error line="27" column="3" severity="ignore" message="Long method. This method contains 53 lines with code." source="long-method"/>
</file>
<file name="lib/src/analyzers/lint_analyzer/reporters/reporters_list/html/utility_functions.dart">
<error line="45" column="1" severity="ignore" message="Long function. This function contains 56 lines with code." source="long-method"/>
</file>
<file name="lib/src/analyzers/lint_analyzer/reporters/reporters_list/html/lint_html_reporter.dart">
<error line="74" column="3" severity="ignore" message="Long method. This method contains 136 lines with code." source="long-method"/>
<error line="330" column="3" severity="ignore" message="Long method. This method contains 159 lines with code." source="long-method"/>
</file>
</checkstyle>
Example Bitbucket pipeline configuration
- Define a pipeline in your
bitbucket-pipelines.yml
file that generates the Checkstyle report and process them.
image: dart
pipelines:
default:
- step:
name: analyze
script:
- dart pub global activate dart_code_metrics
- dart pub global run dart_code_metrics:metrics analyze --fatal-style --fatal-performance --fatal-warnings --reporter=checkstyle lib > checkstyle-result.xml
after-script:
- pipe: atlassian/checkstyle-report:0.3.1
Example of a report: