Configuration

DCM is designed to be flexible and configurable for your use case. You can enable metrics or rules individually, or have both metrics and rules enabled.

To configure DCM, add a dcm entry to analysis_options.yaml:

analysis_options.yaml
dcm:
  extends:
    - ... # configures the list of extended presets
  exclude: # configures excluded files
  exclude-public-api: # configures the "exclude-public-api" mode for the commands that support it
  rules:
    - ... # configures the list of rules
  pubspec-rules:
    - ... # configures the list of rules for pubspec.yaml
  metrics:
    - ... # configures the list of enabled metrics
  formatter:
    - ... # configures the formatter
  project: # configures the project id for DCM Dashboards (Enterprise only)
  project-tags:
    - ... # configure the list of tags for DCM Dashboards (Enterprise only)

note

This configuration is used by both CLI and the IDE analyzer.

Configuring Extended Presets

Presets are predefined sets or rules/metrics (for example, for a particular package or for a particular set of problems) that help you quickly configure DCM.

To simplify the tool's integration, some presets can be enabled without installing any additional package, for example, the "recommended" preset:

analysis_options.yaml
dcm:
  extends:
    - recommended

To enable recommended metrics, use the metrics-recommended preset:

analysis_options.yaml
dcm:
  extends:
    - metrics-recommended

To read more about preset, refer to the Presets documentation page.

Enabling Rules

Rules are one of the core building blocks of DCM. A rule validates if your code meets a certain expectation, and what to do if it does not meet that expectation.

All rules can be configured with severity, ignorable, effort, exclude and include options, but some rules also have additional configuration options specific to that rule and are marked with ⚙️.

Example of basic rules config:

analysis_options.yaml
dcm:
  rules:
    - avoid-dynamic
    - avoid-passing-async-when-sync-expected
    - avoid-redundant-async
    - avoid-unnecessary-type-assertions
    - avoid-unnecessary-type-casts
    - avoid-unrelated-type-assertions
    - avoid-unused-parameters
    - avoid-nested-conditional-expressions
    - newline-before-return
    - no-boolean-literal-compare
    - no-empty-block
    - prefer-trailing-comma
    - prefer-conditional-expressions
    - no-equal-then-else
    - prefer-moving-to-variable
    - prefer-match-file-name
    - avoid-collapsible-if
    - avoid-redundant-else
    - avoid-incomplete-copy-with
    - avoid-self-compare
    - avoid-self-assignment
    - avoid-unnecessary-nullable-return-type
    - avoid-unrelated-type-casts
    - prefer-declaring-const-constructor
  pubspec-rules:
    - dependencies-ordering
    - prefer-commenting-pubspec-ignores
    - prefer-publish-to-none
    - prefer-semver-version
    - pubspec-ordering

info

You can find a list of recommended rules here.

Enabling Metrics

Metrics are one of the core building blocks of DCM. Metrics help you understand the complexity of your code and identify areas that may be difficult to maintain or test.

All metrics are configurable.

Example of basic metrics config:

analysis_options.yaml
dcm:
  exclude:
    metrics:
      - test/**
  metrics:
    cyclomatic-complexity:
      threshold: 20
    number-of-parameters:
      threshold: 4
    maximum-nesting-level:
      threshold: 5

info

You can find a list of recommended metrics here.

Configuring Excluded Files

DCM supports ignore comments, automatically excludes files listed under the analyzer exclude: section as well as supports dedicated excludes for each command.

To read more about excludes, refer to the Excluding Code documentation page.

Excluding Public API

For commands that can affect the package's public API ("Check Unused Code", "Check Unused Files" and "Check Parameters"), setting the exclude-public-api entry in the analysis_options.yaml file will override the --exclude-public-api CLI option.

For example, if publicly exported files of a particular package are not expected to be changed, setting the exclude-public-api entry to true and running the command will exclude the public API only for that particular package.

analysis_options.yaml
dcm:
  exclude-public-api: true # excludes public API for a particular package

Configuring Formatter

DCM provides a configurable formatter that supports project-wide configuration.

To learn move about the formatter configuration, refer to the Formatter documentation page.

Ignore Issues

Ignore issues are synthetic issues produced by the analyzer when parsing ignore comments (// ignore: and // ignore_for_file:). Such issues do not have corresponding rules and cannot be ignored or enabled/disabled.

Issue name	Description
avoid-duplicate-ignores	Highlights ignores that appear more than once.
avoid-unused-ignores	Highlights ignores that have no effect.

Configuration Issues

Configuration issues are synthetic issues produces by the analyzer when parsing the analysis_options.yaml file. Such issues do not have corresponding rules and cannot be ignored or enabled/disabled.

Issue name	Description
duplicate-rule	Highlights a rule that is added to the list of rules more than one time.
unknown-rule	Highlights a rule that does not match any known rule name.
not-available-rule	Highlights a rule that is not available to your pricing plan.
config-not-available	Highlights a rule configuration that is not available to your pricing plan.
empty-rule-config	Highlights a rule with an incorrect configuration resulting in an empty configuration.
unknown-rule-config	Highlights a rule that has an unknown configuration entry.
incorrect-rule-config	Highlights a rule that has an incorrect configuration entry.
requires-config	Highlights a rule that requires configuration to show any issues.
------
unknown-metric	Highlights a metric that does not match any known metric name.
empty-metric-config	Highlights a metric with an incorrect configuration resulting in an empty configuration.
unknown-metric-config	Highlights a metric that has an unknown configuration entry.
incorrect-metric-threshold	Highlights a metric that has an incorrect threshold value.
incorrect-metric-config	Highlights a metric that has an incorrect configuration entry.
------
preset-not-found	Highlights an unresolved or incorrect preset name.
incorrect-preset-config	Highlights an incorrectly configured preset.
presets-not-available	Highlights a preset that is not available to your pricing plan.
incorrect-exclude-public-api-config	Highlights an incorrectly configured `exclude-public-api` entry.
incorrect-exclude-config	Highlights an incorrectly configured `exclude` entry.
unknown-exclude-config	Highlights an incorrectly configured `exclude` subentry.
unknown-config	Highlights an unknown top-level config entry.

Custom `analysis_option.yaml` Files

Aside from the regular analysis_option.yaml file, you can add a custom config file that matches one of the given patterns

starts with analysis_options (e.g. analysis_options.1.1.0.yaml)
starts with dcm (e.g. dcm_config.yaml or dcm.yaml)
placed inside a folder called dcm (e.g. dcm/config.yaml)

If such a file is referenced by any analysis_option.yaml file, DCM will correctly update configuration changes, validate rule names and display a configuration icon (⚙️) for configurable rules.

However, unlike for regular analysis_options.yaml files, code actions are not available.

IDE Autocompletion

VS Code
IntelliJ / Android Studio

To enable configuration autocompletion, modify the settings.json to the following:

.vscode/settings.json
{
  "[yaml]": {
    "editor.quickSuggestions": {
      "strings": "on"
    }
  }
}

No additional configuration is needed, simply modify any analysis_options.yaml file with DCM configuration to see the autocompletion results.

Configuring Extended Presets​

Enabling Rules​

Enabling Metrics​

Configuring Excluded Files​

Excluding Public API​

Configuring Formatter​

Configuration-related Issues​

Ignore Issues​

Configuration Issues​

Custom analysis_option.yaml Files​

IDE Autocompletion​

Next Steps​