Skip to main content

Init

General command to set up DCM. Supports three subcommands: "baseline", "lints-preview" and "metrics-preview".

Full command description:

Usage: dcm init <subcommand> [arguments] <directories>
-h, --help Print this usage information.

Available subcommands:
baseline Generate baseline.
lints-preview Preview all issues from all DCM lint rules.
metrics-preview Preview all metric values from all DCM metrics.

Baseline Teams+​

Creates a JSON file with all existing violations for lint rules, unused code, unused files, code duplications, assets, incomplete exports and dependencies which will be used by IDE integrations (only for lint rules) and CLI as baseline.

Any violations added to this file will not be reported until the related code is changed.

note

Each analysis_options.yaml file will have its own baseline file generated. The baseline file won't be generated if the analysis produces no issues.

info

You need to configure rules entry in the analysis_options.yaml to have rule violations included into the baseline file.

To execute the command, run:

$ dcm init baseline --analyze --unused-code lib # or dcm i b --analyze --unused-code lib

Full command description:

Usage: dcm init baseline [arguments] <directories>
-h, --help Print this usage information.


--all Run all dcm commands.
--analyze Run dcm analyze.
--analyze-assets Run dcm analyze-assets.
--code-duplication Run dcm check-code-duplication.
--unused-code Run dcm check-unused-code.
--unused-files Run dcm check-unused-files.
--unused-l10n Run dcm check-unused-l10n.
--dependencies Run dcm check-dependencies.
--exports-completeness Run dcm check-exports-completeness.


-t, --type="exact" Baseline sensitivity level.

[exact] (default) Invalidate baseline issues when the exact issue area changes.
[line] Invalidate baseline issues when the issue line changes.
[file] Invalidate baseline issues when the containing file changes.

--update Update the existing baseline to include only still existing issues.


Code duplication options:
--per-package Compare code for duplications only within one package.
--exclude-overrides Exclude methods marked with @override.
--lines-threshold Minimum number of lines for a duplication entry.
(defaults to "3")
--entries-threshold Minimum number of duplication entries to report.
(defaults to "1")


Unused code options:
--no-exclude-overridden Do not treat overridden members as always used.


Unused localization options:
-p, --class-pattern="^AppLocalizations$" Regular expression for class names to detect classes that provide localization (e.g., ^AppLocalizations$).
(defaults to "^AppLocalizations$")


Dependencies options:
--ignored-packages="my-package,other,..." Package names that should be ignored.


Assets options:
--size Size limit for image assets.
(defaults to "500KB")
--webp Require converting .jpg and .png images to .webp.
--naming Required naming convention for image assets.
[pascal, kebab, snake]
--[no-]resolution Find missing or incorrect resolution-aware image assets.
(defaults to on)
--allowed-formats List of allowed formats for particular folders (e.g. icons:svg).


-c, --print-config Print resolved config.


--root-folder="./" Root folder.
(defaults to the current directory)
-s, --sdk-path="directory-path" Dart SDK directory path.
If the project has a `.fvm/flutter_sdk` symlink, it will be used if the SDK is not found.
-e, --exclude="{**/*.g.dart,**/*.freezed.dart}" Files to exclude (in Glob syntax).
(defaults to "{**/*.g.dart,**/*.freezed.dart}")
--root-exclude Files to exclude, relative to the root folder (in Glob syntax).


--[no-]congratulate Show output even when there are no issues.


--verbose Show verbose logs.


--ci-key The license key to run on CI server. Can be provided via DCM_CI_KEY env variable.
--email The email used to purchase the license. Can be provided via DCM_EMAIL env variable.


--no-analytics Disable sending anonymous usage statistics.

--exclude-public-api Exclude publicly exported code from the analysis output.

IDE Integrations​

When your project has a generated baseline file, the code actions menu in the IDE will show an additional action to include issues from the current file to the baseline. When issues are included to the baseline via a code action, no analysis server restart is needed for this update to take effect.

Monorepo Support​

For repositories with multiple packages, calling dcm init baseline . from the root of the repository will create a baseline file for each analysis_options.yaml.

If several packages share the same analysis_options.yaml, the baseline file will contain issues from all those packages.

info

Calling dcm init baseline . inside a package that shares analysis_options.yaml with other package will result in the baseline containing issues only from that specific package.

Updating Existing Baseline​

To remove already addressed issues from an existing baseline file, pass the --update flag. This flag ensures no new issues will be added.

note

Make sure that the target folder and other CLI options match the ones used to generate the initial baseline.

Sensitivity​

By default, the baseline uses exact issue area to create a signature and an issue will be highlighted only if the exact are changes.

To change this behavior, pass the --type option. Using --type=line will include the issue line and invalidate the baseline on a line change and using --type=file will invalidate the baseline on any containing file change.

Line Endings​

Line endings in your files can affect the baseline output. Make sure you only have one type of line endings configured.

You can configure line endings via .editorconfig and .gitattributes.

note

This only applies if you choose the file-level baseline sensitivity (--type=file).

Case Sensitivity​

Some platforms (such as macOS) are case-insensitive, which can result in differences in local and remote (e.g. in your git repo) file names.

If the baseline does not work on CI/CD for a particular file, make sure there is no case difference.

Output Example​

warning

The file with the baseline should be added to the version control system (e.g. git).

dcm_baseline.json
{
"date": "2023-04-06 11:21:12.433111Z",
"version": "1.16.0",
"paths": {
"lib/src/fixes/models/fix_producer.dart": {
"prefer-match-file-name": [
"2dca28e191c53faa330a518d0af4ffc5"
]
},
"lib/src/fixes/correct_source_visitor.dart": {
"no-empty-block": [
"99914b932bd37a50b983c5e7c90ae93b",
"99914b932bd37a50b983c5e7c90ae93b"
],
"prefer-correct-identifier-length": [
"865c0c0b4ab0e063e5caa3387c1a8741",
"865c0c0b4ab0e063e5caa3387c1a8741"
]
},
"lib/src/analyzers/unused_code_analyzer/public_code_visitor.dart": {
"avoid-collapsible-if": [
"271a669d554d76db67710f0c8f9fc94e"
]
}
}
}

The baseline contains all the file paths that have violations, grouped by rule name for easy incremental fixing. If you want to fix violations in a specific file, you can simply remove that file's entry from the baseline, and the violations will appear.

warning

The IDE must be restarted each time the baseline file is changed for the changes to take effect.

Lints Preview​

Runs selected (by default all available) rules against the given directories and shows the number of issues generated by each rule.

info

This command supports different output formats. See "Output Example" for more details.

To execute the command, run:

$ dcm init lints-preview lib # or dcm i lp lib

Full command description:

Usage: dcm init lints-preview [arguments] <directories>
-h, --help Print this usage information.


--format="console" Output format.

[console] (default) Format as plain text.
[analysis_options] Format as analysis_options.yaml.
[table] Format as table.

--severity="warning,style,..." Report rules only with this severity (all by default).

[error] (default) Rules with the 'error' severity.
[warning] (default) Rules with the 'warning' severity.
[style] (default) Rules with the 'style' severity.
[none] (default) Rules with the 'none' severity.

--rule-types="common,flutter,..." Rule categories to include (all by default).

[common] (default) Rules for Dart.
[flutter] (default) Rules for Flutter.
[intl] (default) Rules for the 'intl' package.
[flame] (default) Rules for the 'flame' package.
[fake-async] (default) Rules for the 'fake_async' package.
[provider] (default) Rules for the 'provider' package.
[bloc] (default) Rules for the 'bloc' package.
[equatable] (default) Rules for the 'equatable' package.
[patrol] (default) Rules for the 'patrol' package.
[get-it] (default) Rules for the 'get_it' package.
[flutter-hooks] (default) Rules for the 'flutter_hooks' package.
[riverpod] (default) Rules for the 'riverpod' package.
[getx] (default) Rules for the 'getx' package.
[easy-localization] (default) Rules for the 'easy_localization' package.
[firebase-analytics] (default) Rules for the 'firebase_analytics' package.

--rule-version="1.29.0" Rule version to include (all by default).

[1.0.0] Rules added in 1.0.0
[1.1.0] Rules added in 1.1.0
[1.2.0] Rules added in 1.2.0
[1.3.0] Rules added in 1.3.0
[...]
[1.27.0] Rules added in 1.27.0
[1.28.0] Rules added in 1.28.0
[1.29.0] Rules added in 1.29.0
[1.30.0] Rules added in 1.30.0

--rule-tags="correctness,consistency,..." Rule tags to include (all by default).

[abstractions] Rules for detecting abstraction issues.
[accessibility] Rules for detecting accessibility issues.
[architecture] Rules for enforcing architecture agreements.
[assignments] Rules for detecting issues with assignments.
[async] Rules for detecting issues with asynchronous code and Futures.
[collections] Rules for detecting issues with collections.
[conditions] Rules for detecting issues with conditions and logical expressions.
[consistency] Rules for detecting consistency issues.
[control-flow] Rules for detecting control flow issues.
[correctness] Rules for detecting potential bugs.
[cwe] Rules for detecting CWE issues.
[encapsulation] Rules for detecting issues with encapsulation.
[error-handling] Rules for detecting issues with exceptions and error handling.
[imports] Rules for detecting issues with imports and exports.
[maintainability] Rules for improving maintainability.
[memory-leak] Rules for detecting memory leaks.
[naming] Rules for detecting naming issues.
[nullability] Rules for detecting nullability issues.
[pedantic] Rules for pedantic devs!
[performance] Rules for detecting performance issues.
[readability] Rules for improving readability.
[requires-config] Rules that require configuration.
[security] Rules for detecting security issues.
[testing] Rules for detecting issues with tests.
[types] Rules for detecting issues with type operations and annotations.
[unused-code] Rules for detecting unused code.

--only-enabled Include only enabled rules.
--only-absent Include only those rules that are not added to the configuration.
--only-fixable Show only fixable violations.
--[no-]empty-violations Show rules with only 0 violations / Hide rules with 0 violations.
--no-baseline-violations Hide violations included into baseline.


--root-folder="./" Root folder.
(defaults to the current directory)
-s, --sdk-path="directory-path" Dart SDK directory path.
-e, --exclude="{**/*.g.dart,**/*.freezed.dart}" Files to exclude (in Glob syntax).
(defaults to "{**/*.g.dart,**/*.freezed.dart}")
--root-exclude Files to exclude, relative to the root folder (in Glob syntax).


--[no-]congratulate Show output even when there are no issues.


--ci-key The license key to run on CI server. Can be provided via DCM_CI_KEY env variable.
--email The email used to purchase the license. Can be provided via DCM_EMAIL env variable.


--no-analytics Disable sending anonymous usage statistics.

Configuring the Set of Rules​

By default, the command runs all available rules.

You can change this behavior by passing --severity, --rule-types, --rule-version, --rule-tags, --only-absent, --only-enabled and --only-fixable options.

For example, to get rule violations only for Flutter and Bloc, and with warning and style severities, pass --severity=warning,style --rule-types=flutter,bloc.

info

Pass --no-empty-violations if you want to excluded rules with 0 violations from the output or --empty-violations to only show rules with 0 violations.

Understanding the Estimated Effort​

This command also shows the estimated effort to fix all violations of a particular rule (the value can be in minutes or in hours).

Rules that are supported by "dcm fix" have a lower estimated effort as they only require a review after the fixes are applied.

note

This number is very approximate and is shown only to help you decide which violations to address first.

Output Example​

Console (default)​

Console example

Table​

Use --format=table to enable this format.

Table example

Analysis Options​

Use --format=analysis_options to enable this format.

Analysis Options example

Metrics Preview​

Runs selected (by default all available) metrics against the given directories and shows the values generated by each metric.

info

This command supports different output formats. See "Output Example" for more details.

To execute the command, run:

$ dcm init metrics-preview lib # or dcm i mp lib

Full command description:

Usage: dcm init metrics-preview [arguments] <directories>
-h, --help Print this usage information.


--format="console" Output format.

[console] (default) Format as plain text.
[analysis_options] Format as analysis_options.yaml.
[table] Format as table.

--metric-types="function,class,..." Metric categories to include (all by default).

[function] (default) Function-level metrics (apply to functions, methods, and getters).
[class] (default) Class-level metrics (apply to classes, extensions, mixins, and enums).
[file] (default) File-level metrics.

--only-metrics="metrics:threshold,metric2:threshold2,..." Include only passed metrics.
--only-enabled Include only enabled metrics.
--only-absent Include only those metrics that are not added to the configuration.
--[no-]empty-violations Show metrics with only 0 violations / Hide metrics with 0 violations.


--root-folder="./" Root folder.
(defaults to the current directory)
-s, --sdk-path="directory-path" Dart SDK directory path.
-e, --exclude="{**/*.g.dart,**/*.freezed.dart,**/*.mapper.dart}" Files to exclude (in Glob syntax).
(defaults to "{**/*.g.dart,**/*.freezed.dart,**/*.mapper.dart}")
--root-exclude Files to exclude, relative to the root folder (in Glob syntax).


--[no-]congratulate Show output even when there are no issues.


--ci-key The license key to run on CI server. Can be provided via DCM_CI_KEY env variable.
--email The email used to purchase the license. Can be provided via DCM_EMAIL env variable.


--no-analytics Disable sending anonymous usage statistics.

Configuring the Set of Metrics​

By default, the command runs all available metrics.

You can change this behavior by passing --metric-types, --no-empty-violations , --only-absent and --only-enabled options.

To run only passed metrics, use --only-metrics. For example, running dcm init mp lib --only-metrics="cyclomatic-complexity:20" will only pass the Cyclomatic Complexity metric with the threshold of 20.

info

Pass --no-empty-violations if you want to excluded metrics with 0 violations from the output or --empty-violations to only show metrics with 0 violations.

Understanding the Estimated Effort​

This command also shows the estimated effort to fix all violations of a particular metric (the value can be in minutes or in hours).

note

This number is very approximate and is shown only to help you decide which violations to address first.

Output Example​

Console (default)​

Table​

Use --format=table to enable this format.

Analysis Options​

Use --format=analysis_options to enable this format.