Skip to main content

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,
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.
--weight-of-class=<0.33> Weight Of a Class threshold.
--maintainability-index=<50> Maintainability Index threshold.

--root-folder=<./> Root folder
(defaults to current directory)
--exclude=<{/**.g.dart,/**.template.dart}> File paths in Glob syntax to be exclude
(defaults to "{/**.g.dart,/**.template.dart}")


--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.

Console

HTML

Use --reporter=html to enable this format.

HTML report overview

HTML

HTML single file report

HTML

HTML report details

HTML

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 format
  • records - an array of objects
  • summary - 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 file
  • classes - a map with class name as the key and class report as the value
  • functions - a map with function name as the key and function report as the value
  • issues - an array of issues detected in the target file
  • antiPatternCases - 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 record
  • title - a message with information about the record
  • value - an actual value of this record (can be an array or a single value)
  • violations - a value of a violations of a metric associated with this record (can be an array or a single value) (optional)
{
"status": "warning",
"title": "Average Cyclomatic Number per line of code",
"value": 0.3447098976109215,
"violations": 5
}

The report object fields are

  • codeSpan - a source code span of the target entity
  • metrics - an array with target entity metrics
{
"codeSpan": {
...
},
"metrics": [
...
]
}

The code span object fields are

  • start - a start location of an entity
  • end - an end location of an entity
  • text - 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 source
  • line - a zero-based line of the location in the source
  • column - 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 metric
  • value - an actual value computed by the metric
  • level - a level of the value computed by the metric
  • comment - a message with information about the value
  • recommendation - 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,
"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 user
  • codeSpan - 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 issue
  • documentation - an url of a page containing documentation associated with the issue
  • codeSpan - a source code span associated with the issue
  • severity - a severity of the issue
  • message - a short message
  • verboseMessage - 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 applied
  • replacement - 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 to dev_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 lib

    dart_code_metrics is not added to dev_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 --reporter=github lib

Example of a report in a PR:

Report example

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.

code_quality:
image: google/dart
before_script:
- dart pub global activate dart_code_metrics
script:
- dart pub global run dart_code_metrics:metrics lib -r gitlab > code-quality-report.json
artifacts:
reports:
codequality: code-quality-report.json

Example of a Code Quality widget in a PR:

Code Quality widget

Example of a Code Quality in a PR diff view:

GitLab diff