Boolean Lints

boolean_lints is a developer tool made using custom_lint, designed to help stop common issues and simplify repetetive tasks. It aims to adds various warnings with quick fixes and refactoring options. At the moment, the only lint rule enabled is banned_code.

Table of Contents

Usage

Installing boolean_lints

boolean_lints is implemented using custom_lint. As such, it uses custom_lint's installation logic.
Long story short:

  • Add both boolean_lints and custom_lint to your pubspec.yaml:

    dev_dependencies:
  custom_lint:
  boolean_lints:

  • Enable custom_lint's plugin in your analysis_options.yaml:

    analyzer:
  plugins:
    - custom_lint

Enabling/disabling lints

By default when installing boolean_lints, most of the lints will be enabled. To change this, you have a few options.

Disable one specific rule

You may dislike one of the various lint rules offered by boolean_lints. In that event, you can explicitly disable this lint rule for your project by modifying the analysis_options.yaml

analyzer:
  plugins:
    - custom_lint

custom_lint:
  rules:
    # Explicitly disable one lint rule
    - banned_code: false

boolean_lints:
  rules:
    banned_code:
      severity: warning
      entries:
        - id: test4
          class_name: BannedCodeUsage
          source: package:id_class_package
          reason: "BannedCodeUsage.test4 from the example package is not allowed"

Note that you can both enable and disable lint rules at once. This can be useful if your analysis_options.yaml includes another one:

include: path/to/another/analysis_options.yaml
analyzer:
  plugins:
    - custom_lint

custom_lint:
  rules:
    # Enable one rule
    - banned_code
    # Disable another
    - custom_lint_example: false

boolean_lints:
  rules:
    banned_code:
      severity: warning
      entries:
        - id: test4
          class_name: BannedCodeUsage
          source: package:id_class_package
          reason: "BannedCodeUsage.test4 from the example package is not allowed"

Disable all lints by default

Instead of having all lints on by default and manually disabling lints of your choice, you can switch to the opposite logic:
Have lints off by default, and manually enable lints.

This can be done in your analysis_options.yaml with the following:

analyzer:
  plugins:
    - custom_lint

custom_lint:
  # Forcibly disable lint rules by default
  enable_all_lint_rules: false
  rules:
    # You can now enable one specific rule in the "rules" list
    - banned_code

boolean_lints:
  rules:
    banned_code:
      severity: warning
      entries:
        - id: test4
          class_name: BannedCodeUsage
          source: package:id_class_package
          reason: "BannedCodeUsage.test4 from the example package is not allowed"

Configuring Lints

Some of the lints have configurations. These can be specified in the analysis_options.yaml or the pubspec.yaml file under the top level key boolean_lints:.

All lints have the following options:

  • severity: This can be set to none, info, warning or error.
  • include: Only lint files matching these regular expressions.
  • exclude: Skip linting files matching these regular expressions.
boolean_lints:
  rules_exclude:
    - "test/.*\\.dart"
  rules:
    example_lint_code:
      severity: info
      include:
        - "lib/.*\\.dart"
      exclude:
        - "lib/.*_temp\\.dart"

Running boolean_lints in the terminal/CI

Custom lint rules created by boolean_lints may not show-up in dart analyze. To fix this, you can run a custom command line: custom_lint.

Since your project should already have custom_lint installed (cf installing boolean_lints), then you should be able to run:

dart run custom_lint

Alternatively, you can globally install custom_lint:

# Install custom_lint for all projects
dart pub global activate custom_lint
# run custom_lint's command line in a project
dart run custom_lint

All Lint Rules

Most lints have configuration options. These can be specified in the analysis_options.yaml or the pubspec.yaml. See LINTS.md for a list of implemented lint rules and their configuration options.

Contributing Guide

Creating Lints

  1. Create a new file with the lint name in lib/src/lints, type lint and use snippet to generate the boilerplate code.
  2. Add the lint logic to the OptionsLintRule.run method.
  3. (Optional) Adding a fix for the lint
    1. Create a fix file in the lib/src/lints/fixes, type fix and use the snippet to generate the boilerplate code.
    2. Add it to the lint's OptionsLintRule.getFixes method.
  4. Add the lint to the lib/lints.dart getAllLints method. Type fix and use the lint to generate the boilerplate code.
  5. (Optional) Adding configuration options. These options are available with the options getter in the OptionsLintRule and OptionsAssist classes.
    1. Create a new file for each key in lib/src/options/, type options and use the snippet to generate the boilerplate code.
    2. Add the mixin OptionsMixin to the option class and add fields List<String> excludes and List<String> includes to add rule path configuration.
      • In your lint classes, use options.rules.lintName.shouldSkipFile to skip excluded/non-included files.
      • Also use options.isFileRuleExcluded to skip excluded files that were excluded from all lints.
    3. Add the new options class to the lib/src/options/rules.dart constructor with named parameters.
    4. Run dart pub run build_runner build to generate the new dart_mappable classes.
  6. Update LINTS.md with the new lint and configuration options.

Creating Assists

  1. Create a new file with the lint name in lib/src/assists, type assist and use snippet to generate the boilerplate code.
  2. Add the assist to the lib/lints.dart getAllAssists method.
  3. (Optional) Adding configuration options. Follow Creating Lints Step 3.

Debugging/Testing

Follow the custom_lint debugging/testing docs.

Semantic Versioning Policy

boolean_lints follows semantic versioning.

Major:

  • New lint rules are added
  • Lint is enabled by default (previously disabled by default).
  • Lint configuration options changed

Minor:

  • New lint rule added (disabled by default)
  • New fix/assist added
  • Lint configuration option added (without changing the default behavior)

Patch:

  • Bug fixes
  • Documentation updates

Resources

Libraries

boolean_lints
Contains the entrypoint of the plugin for use by custom_lint.