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/")
    --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.

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​

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