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/")
--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.
--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,/**.template.dart}> File paths in Glob syntax to be exclude
(defaults to "{/**.g.dart,/**.template.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
DEPRECATED! This reporter is deprecated and will be removed in 5.0.0. You can migrate on our GitHub Action.
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: google/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: google/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: