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

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
  • fileMetrics - an array with target file metrics
  • 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 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 - 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
  • unitType - a human readable unit type (optional)
  • 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,
  "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 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 --fatal-style --fatal-performance --fatal-warnings --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 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:

Code Quality widget

Example of a Code Quality in a PR diff view:

GitLab diff

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​

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:

Checkstyle report in Bitbucket