Skip to main content

Check Unnecessarily Mutable Fields

Reports mutable fields and top-level variables (declared with var or type) that are never reassigned and can be made final.

To execute the command, run:

$ dcm check-unnecessarily-mutable-fields lib # or dcm umf lib

Full command description:

Usage: dcm check-unnecessarily-mutable-fields [arguments] <directories>
-h, --help                                         Print this usage information.


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


-r, --reporter="console" (--output-format)         Analysis output format.
                                                   [console (default), json, codeclimate, gitlab, checkstyle, sonar]
-a, --absolute-path                                Show absolute paths in console reporter output.
-c, --concise                                      A single-line per-violation format for console reporter output.
    --output-to="path/to/file"                     Path to the file with the analysis output.


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


    --[no-]fatal-found                             Treat unnecessarily public code as fatal.
                                                   (defaults to on)

Suppressing the Command​

To suppress issues produced by the command, add the ignore: unnecessarily-mutable-fields comment. To suppress the command for an entire file, add the ignore_for_file: unnecessarily-mutable-fields comment to the beginning of a file.

Excluding Public API​

By default, this command analyzes all code, even if it's part a package's public API.

To exclude such code from the analysis, pass the exclude-public-api CLI flag.

note

This command follows this convention when locating API and implementation files.

Overriding "exclude-public-api" for a Particular Package​

To override the exclude-public-api flag for a particular package, set the exclude-public-api entry in the analysis_options.yaml.

Output Example​

Console (default)​

Use --reporter=console to get output in console format.

Console

JSON​

Use --reporter=json to get output as a single JSON object containing metadata and the list of unnecessarily public code issues.

Format specification

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
  • unnecessarilyMutableFieldsResults - an array of objects
  • summary - an array of objects
{
  "formatVersion": 10,
  "timestamp": "2021-04-11 14:44:42",
  "unnecessarilyMutableFieldsResults": [
    {
      ...
    },
    {
      ...
    },
    {
      ...
    }
  ],
  "summary": [
    {
      ...
    },
    {
      ...
    }
  ]
}

The result object fields are​

  • path - the relative path to the file with issues
  • issues - an array of issues detected in the target file
{
  "path": "lib/src/some/file.dart",
  "issues": [
    ...
  ],
}

The issue object fields are​

  • id - issue id
  • message - the message associated with the issue
  • location - the location associated with the issue
  • effortInMinutes - an estimated effort to fix the issue (in minutes)
  • declarationName - unnecessarily mutable declaration name
  • declarationType - unnecessarily mutable declaration type
{
  "id": "unnecessarily-mutable-issue",
  "message": "The 'myVariable' top level variable is not reassigned and can be declared as final",
  "location": {
    ...
  },
  "effortInMinutes": 2,
  "declarationName": "myVariable",
  "declarationType": "top level variable",
}

The location object fields are​

  • startColumn - the start column of the entity
  • startLine - the start line of the entity
  • endColumn - the end column of the entity
  • endLine - the end line of the entity
  • startOffset - the offset of the entity
{
  "endColumn": 2,
  "endLine": 90,
  "startColumn": 1,
  "startLine": 48,
  "startOffset": 1638
}

The summary-record object fields are​

  • title - a message with the summary entry title
  • value - the actual value of the entry
{
  "title": "Total unnecessarily mutable fields",
  "value": 1
}

GitLab​

Use --reporter=gitlab to get output in a GitLab-compatible format. To learn how to integrate DCM with GitLab, refer to this guide.

Code Climate​

Use --reporter=codeclimate to get output in Code Climate format.

Output example
'{"type":"issue","check_name":"unnecessarily-mutable-issue","description":"The 'someField' field is not reassigned and can be declared as final","categories":["Bug Risk"],"location":{"path":"../abstract_class.dart","positions":{"begin":{"column":3,"line":5},"end":{"column":3,"line":5}}},"severity":"major","fingerprint":"5305a92074c27c1a471bd9b8aad1f462"}\x00',
'{"type":"issue","check_name":"unnecessarily-mutable-issue","description":"The 'myVariable' top level variable is not reassigned and can be declared as final","categories":["Bug Risk"],"location":{"path":"../class_with_factory_constructors.dart","positions":{"begin":{"column":3,"line":5},"end":{"column":3,"line":5}}},"severity":"major","fingerprint":"44a79fde135bc9ebc48e4fd6bdfbcc54"}\x00',

Checkstyle​

Use --reporter=checkstyle to get output in Checkstyle format.

Output example
<?xml version="1.0"?>
<checkstyle version="10.0">
  <file name="example.dart">
    <error line="5" column="3" severity="warning" message="The 'myVariable' top level variable is not reassigned and can be declared as final" source="unnecessarily-mutable-issue"/>
  </file>
</checkstyle>
note

Checkstyle format is supported by Bitbucket. To learn how to integrate DCM with Bitbucket, refer to this guide.

Sonar​

Use --reporter=sonar to get output in SonarQube's generic format for external issues.

Output example
{
  "rules": [
    {
      "cleanCodeAttribute": "CLEAR",
      "description": "To learn more, visit the documentation https://dcm.dev/docs/cli/code-quality-checks/unnecessarily-mutable-fields/",
      "engineId": "dcm",
      "id": "unnecessarily-mutable-issue",
      "impacts": [
        {
          "severity": "MEDIUM",
          "softwareQuality": "MAINTAINABILITY"
        }
      ],
      "name": "unnecessarily-mutable-issue"
    }
  ],
  "issues": [
    {
      "effortMinutes": 2,
      "primaryLocation": {
        "filePath": "lib/src/home_i18n.dart",
        "message": "The 'someField' field is not reassigned and can be declared as final",
        "textRange": {
          "endColumn": 9,
          "endLine": 14,
          "startColumn": 3,
          "startLine": 10
        }
      },
      "ruleId": "unnecessarily-mutable-issue"
    },
    {
      "effortMinutes": 10,
      "primaryLocation": {
        "filePath": "lib/src/home_i18n.dart",
        "message": "The 'myVariable' top level variable is not reassigned and can be declared as final",
        "textRange": {
          "endColumn": 9,
          "endLine": 20,
          "startColumn": 3,
          "startLine": 16
        }
      },
      "ruleId": "unnecessarily-mutable-issue"
    }
  ]
}
Last updated on