# custom_lint 0.7.0 Lint rules are a powerful way to improve the maintainability of a project. Custom Lint allows package authors and developers to easily write custom lint rules. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir flutter pub add 'custom_lint:0.7.0' ``` Published: 2024-10-27T19:02:52.933666Z Expected archive SHA-256: 3486c470bb93313a9417f926c7dd694a2e349220992d7b9d14534dc49c15bba9 Available in cache; verification: upstream_checksum ## Direct dependencies - analyzer: ^6.6.0 - analyzer_plugin: ^0.11.0 - args: ^2.3.1 - async: ^2.9.0 - ci: ^0.1.0 - cli_util: ^0.4.0 - collection: ^1.16.0 - custom_lint_core: 0.7.0 - freezed_annotation: ^2.2.0 - json_annotation: ^4.7.0 - meta: ^1.7.0 - package_config: ^2.0.2 - path: ^1.8.0 - pub_semver: ^2.1.1 - pubspec_parse: ^1.2.0 - rxdart: ^0.28.0 - uuid: >=3.0.6 <5.0.0 - yaml: ^3.1.1 ## Package README (untrusted upstream documentation)

custom_lint

Tools for building custom lint rules.

License

---

--- ## Index - [Index](#index) - [Tutorial](#tutorial) - [About](#about) - [Usage](#usage) - [Creating a custom lint package](#creating-a-custom-lint-package) - [Using our custom lint package in an application](#using-our-custom-lint-package-in-an-application) - [Enabling/disabling and configuring lints](#enablingdisabling-and-configuring-lints) - [Obtaining the list of lints in the CI](#obtaining-the-list-of-lints-in-the-ci) - [Using the Dart debugger and enabling hot-reload](#using-the-dart-debugger-and-enabling-hot-reload) - [Testing your plugins](#testing-your-plugins) - [Testing lints](#testing-lints) - [Testing quick fixes and assists](#testing-quick-fixes-and-assists) ## Tutorial You can read the latest [blog post](https://invertase.link/b18R) or watch the [advanced use case with custom_lint video](https://invertase.link/RNoz). ## About Lint rules are a powerful way to improve the maintainability of a project. The more, the merrier! But while Dart offers a wide variety of lint rules by default, it cannot reasonably include every possible lint. For example, Dart does not include lints related to third-party packages. Custom_lint fixes that by allowing package authors to write custom lint rules. Custom_lint is similar to [analyzer_plugin], but goes deeper by trying to provide a better developer experience. That includes: - A command-line to obtain the list of lints in your CI without having to write a command line yourself. - A simplified project setup: No need to deal with the `analyzer` server or error handling. Custom_lint takes care of that for you, so that you can focus on writing lints. - Debugger support. Inspect your lints using the Dart debugger and place breakpoints. - Supports hot-reload/hot-restart: Updating the source code of a linter plugin will dynamically restart it, without having to restart your IDE/analyzer server. - Built-in support for `// ignore:` and `// ignore_for_file:`. - Built-in testing mechanism using `// expect_lint`. See [Testing your plugins](#testing-your-plugins) - Support for `print(...)` and exceptions: If your plugin somehow throws or print debug messages, custom_lint will generate a log file with the messages/errors. ## Usage Using custom_lint is split in two parts: - how to define a custom_lint package - how users can install our package in their application to see our newly defined lints ### Creating a custom lint package To create a custom lint, you will need two things: - updating your `pubspec.yaml` to include `custom_lint_builder` as a dependency: ```yaml # pubspec.yaml name: my_custom_lint_package environment: sdk: ">=3.0.0 <4.0.0" dependencies: # we will use analyzer for inspecting Dart files analyzer: analyzer_plugin: # custom_lint_builder will give us tools for writing lints custom_lint_builder: ``` - create a `lib/.dart` file in your project with the following: ```dart import 'package:analyzer/error/listener.dart'; import 'package:custom_lint_builder/custom_lint_builder.dart'; // This is the entrypoint of our custom linter PluginBase createPlugin() => _ExampleLinter(); /// A plugin class is used to list all the assists/lints defined by a plugin. class _ExampleLinter extends PluginBase { /// We list all the custom warnings/infos/errors @override List getLintRules(CustomLintConfigs configs) => [ MyCustomLintCode(), ]; } class MyCustomLintCode extends DartLintRule { MyCustomLintCode() : super(code: _code); /// Metadata about the warning that will show-up in the IDE. /// This is used for `// ignore: code` and enabling/disabling the lint static const _code = LintCode( name: 'my_custom_lint_code', problemMessage: 'This is the description of our custom lint', ); @override void run( CustomLintResolver resolver, ErrorReporter reporter, CustomLintContext context, ) { // Our lint will highlight all variable declarations with our custom warning. context.registry.addVariableDeclaration((node) { // "node" exposes metadata about the variable declaration. We could // check "node" to show the lint only in some conditions. // This line tells custom_lint to render a warning at the location of "node". // And the warning shown will use our `code` variable defined above as description. reporter.atNode(node, code); }); } } ``` That's it for defining a custom lint package! If you're looking for a more advanced example, see the [example](https://github.com/invertase/dart_custom_lint/tree/main/packages/custom_lint/example). This example implements: - a lint appearing on all variables of a specific type - a quick fix for that lint - an "assist" for providing refactoring options. Let's now use it in an application. ### Using our custom lint package in an application For users to run custom_lint packages, there are a few steps: - The application must contain an `analysis_options.yaml` with the following: ```yaml analyzer: plugins: - custom_lint ``` - The application also needs to add `custom_lint` and our package(s) as dev dependency in their application: ```yaml # The pubspec.yaml of an application using our lints name: example_app environment: sdk: ">=3.0.0 <4.0.0" dev_dependencies: custom_lint: my_custom_lint_package: ``` That's all! After running `pub get` (and possibly restarting their IDE), users should now see our custom lints in their Dart files: ![screenshot of our custom lints in the IDE](https://raw.githubusercontent.com/invertase/dart_custom_lint/main/resources/lint_showcase.png) ### Enabling/disabling and configuring lints By default, custom_lint enables all installed lints. But chances are you may want to disable one specific lint, or alternatively, disable all lints besides a few. This configuration is done in your `analysis_options.yaml`, but in a slightly different manner. Configurations are placed within a `custom_lint` object, as followed: ```yaml analyzer: plugins: - custom_lint custom_lint: rules: - my_lint_rule: false # disable this rule ``` As mentioned before, all lints are enabled by default. ```yaml custom_lint: # Disable all lints by default enable_all_lint_rules: false rules: - my_lint_rule # only enable my_lint_rule ``` If you want to change this, you can optionally disable all lints by default: Last but not least, some lint rules may be configurable. When a lint is configurable, you can configure it in the same place with: ```yaml custom_lint: rules: - my_lint_rule: some_parameter: "some value" ``` ### Obtaining the list of lints in the CI Unfortunately, running `dart analyze` does not pick up our newly defined lints. We need a separate command for this. To do that, users of our custom lint package can run the following inside their terminal: ```sh $ dart run custom_lint lib/main.dart:0:0 • This is the description of our custom lint • my_custom_lint_code ``` If you are working on a Flutter project, run `flutter pub run custom_lint` instead. ### Using the Dart debugger and enabling hot-reload By default, custom_lint does enable hot-reload or give you the necessary information to start the debugger. This is because most users don't need those, and only lint authors do. If you wish to debug lints, you'll have to update your `analysis_options.yaml` as followed: ```yaml analyzer: plugins: - custom_lint custom_lint: debug: true # Optional, will cause custom_lint to log its internal debug information verbose: true ``` Then, to debug plugins in custom_lint, you need to connect to plugins using "attach" mode in your IDE (`cmd+shift+p` + `Debug: attach to Dart process` in VSCode). When using this command, you will need a VM service URI provided by custom_lint. There are two possible ways to obtain one: - if you started your plugin using `custom_lint --watch`, it should be visible in the console output. - if your plugin is started by your IDE, you can open the `custom_lint.log` file that custom_lint created next to the `pubspec.yaml` of your analyzed projects. In both cases, what you're looking for is logs similar to: ``` The Dart VM service is listening on http://127.0.0.1:60671/9DS43lRMY90=/ The Dart DevTools debugger and profiler is available at: http://127.0.0.1:60671/9DS43lRMY90=/devtools/#/?uri=ws%3A%2F%2F127.0.0.1%3A60671%2F9DS43lRMY90%3D%2Fws ``` What you'll want is the first URI. In this example, that is `http://127.0.0.1:60671/9DS43lRMY90=/`. You can then pass this to your IDE, which should now be able to attach to the plugin. ### Testing your plugins #### Testing lints Custom_lint comes with an official testing mechanism for asserting that your plugins correctly work. Testing lints is straightforward: Simply write a file that should contain lints from your plugin (such as the example folder). Then, using a syntax similar to `// ignore`, write a `// expect_lint: code` in the line before your lint: ```dart // expect_lint: riverpod_final_provider var provider = Provider(...); ``` When doing this, there are two possible cases: - The line after the `expect_lint` correctly contains the expected lint. In that case, the lint is ignored (similarly to if we used `// ignore`) - The next line does **not** contain the lint. In that case, the `expect_lint` comment will have an error. This allows testing your plugins by simply running `custom_lint` on your test/example folder. Then, if any expected lint is missing, the command will fail. But if your plugin correctly emits the lint, the command will succeed. #### Testing quick fixes and assists Testing quick fixes and assists is also possible with regular tests by combining them with `pkg:analyzer` to manually execute the assists or fixes. An example can be found in the [Riverpod repository](https://github.com/rrousselGit/riverpod/tree/master/packages/riverpod_lint_flutter_test/test/assists). ---

Built and maintained by Invertase.

[analyzer_plugin]: https://pub.dev/packages/analyzer_plugin ## Changelog ## 0.7.0 - 2024-10-27 - `custom_lint --fix` and the generated "Fix all

" assists
  now correctly handle imports.
- Now supports a broad number of analyzer version.

## 0.6.10 - 2024-10-10

- Support installing custom_lint plugins in `dependencies:` instead of `dev_dependencies` (thanks to @dickermoshe).

## 0.6.9 - 2024-10-09

- `custom_lint_core` upgraded to `0.6.9`

## 0.6.8 - 2024-10-08

- Fix CI
- Fix custom_lint not warning non-Dart files when necessary.
- Custom_lint no-longer tries to analyze projects that lack a `.dart_tool/package_config.json`

## 0.6.7 - 2024-09-08

- Removed offline package resolution for the analyzer plugin.
  The logic seemed broken at times, so removing it should make custom_lint more stable.

## 0.6.6 - 2024-09-08

- Fixed an error in the CLI when Flutter generates code under `.dart_tool/` or has dependencies on iOS libraries (thanks to @Kurogoma4D)

## 0.6.5 - 2024-08-15

- Upgraded to analyzer ^6.6.0.
  This is a quick fix to unblock the stable Flutter channel.
  A more robust fix will come later.
- Fixed a bug where isSuperTypeOf throws if the element is null (thanks to @charlescyt)

## 0.6.4 - 2024-03-16

- Improve error message to attempt debugging a certain bug

## 0.6.3 - 2024-03-16

- Fixed Unimplemented error when running `pub get`.
- Hot-reload and debug mode is now disabled by default.

## 0.6.2 - 2024-02-19

- `custom_lint --format json` no-longer outputs non-JSON logs (thanks to @kzrnm)
- Upgrade analyzer to support 6.4.0
- Fix null exception when using `TypeChecker.isSuperTypeOf` (thanks to @charlescyt)

## 0.6.0 - 2024-02-04

- Added support for `--fix`

## 0.5.11 - 2024-01-27

- Added support for `analysis_options.yaml` that are nt at the root of the project (thanks to @mrgnhnt96)

## 0.5.8 - 2024-01-09

- `// ignore` comments now correctly respect indentation when they are inserted (thanks to @PiotrRogulski)

## 0.5.7 - 2023-11-20

- Support JSON output format via CLI parameter `--format json|default` (thanks to @kuhnroyal)

## 0.5.6 - 2023-10-30

Optimized logic for finding an unused VM_service port.

## 0.5.5 - 2023-10-26

- Support `hotreloader` 4.0.0

## 0.5.4 - 2023-10-20

- Sort lints by severity in the command line (thanks to @kuhnroyal)
- Fix watch mode not quitting with `q` (thanks to @kuhnroyal)
- Improve the command line's output (thanks to @kuhnroyal)
- Update uuid to 4.0.0
- Fixed a port leak
- Fix connection issues on Docker/windows (thanks to @hamsbrar)

## 0.5.3 - 2023-08-29

- The command line now supports ignoring warnings/infos with `--no-fatal-warnings`/`--no-fatal-infos` (thanks to @yamarkz)

## 0.5.2 - 2023-08-16

- Support both analyzer 5.12.0 and 6.0.0 at the same time.
- Attempt at fixing the windows crash

## 0.5.1 - 2023-08-03

Support analyzer v6

## 0.5.0 - 2023-06-21

- Now resolves packages using `pub get` if custom_lint failed to resolve packages offline.
  This should reduce the likelyness of a version conflict in mono-repositories.
  The conflict may still happen if two projects in a mono-repo use incompatible
  constraints. Like:
  ```yaml
  name: foo
  dependencies:
    package: ^1.0.0
  ```
  ```yaml
  name: bar
  dependencies:
    package: ^2.0.0
  ```
- The command line now shows the lints' severity (thanks to @praxder)
- Now requires Dart 3.0.0

## 0.4.0 - 2023-05-12

- Report uncaught exceptions inside `context.addPostRunCallback`
- Added support for analyzer 5.12.0

## 0.3.4 - 2023-04-19

- custom_lint now automatically generate quick-fixes for "ignore for line/file".
- Update the socket communication logic to avoid possible problem is the message
  contains a \n.
- fixes custom_lint on windows

## 0.3.3 - 2023-04-06

- Reduce the likelyness of a dependency version conflict.
- Fix `dart analyze` crashing on large projects in the CI due to custom_lint
  incorrectly trying to run plugins in debug mode.
- Fix the `custom_lint` command line never terminating in some cases where plugins
  fail to start (thanks to @kuhnroyal).
- Upgraded `analyzer` to `>=5.7.0 <5.11.0`
- `LintRuleNodeRegistry` and other AstVisitor-like now are based off `GeneralizingAstVisitor` instead of `GeneralizingAstVisitor`
- Upgraded `cli_util` to `^0.4.0`
- The command line no-longer throws if ran on an empty project or a project with
  no plugins enabled
- Exposes the Pubspec in CustomLintContext

## 0.3.2 - 2023-03-09

- Revert "Fixed an issue that caused a "Port already in use" error when
  trying to start custom_lint".
  This had the opposite effect of what's expected.

## 0.3.0 - 2023-03-09

- Update analyzer to >=5.7.0 <5.8.0
- Fixed an issue that caused a "Port already in use" error when trying to
  start custom_lint

## 0.2.12

Move json_serializable to dev dependencies

## 0.2.11

- Improved the error message when there is a version conflict in mono-repos (thanks to @@adsonpleal)
- Bump minimum Dart SDK to `sdk: ">=2.19.0 <3.0.0"`

## 0.2.5

Fix custom_lint not correctly killing sub-processes when the IDE stops custom_lint.

## 0.2.2

Fixes an exception thrown when a project contains images.

## 0.2.0

**Large Breaking change**
This new version introduces large changes to how lints/fixes/assists are defined.  
Long story short, besides the `createPlugin` method, the entire syntax changed.

See the readme, examples, and docs around how to use the new syntax.

The new syntax has multiple benefits:

- It is now possible to enable/disable lints inside the `analysis_options.yaml`
  as followed:

  ```yaml
  # optional
  include: path/to/another/analysis_options.yaml

  custom_lint:
    rules:
      # enable a lint rule
      - my_lint_rule
      # A lint rule that is explicitly disabled
      - another_lint_rule: false
  ```

  Enabling/disabling lints is supported by default with the new syntax. Nothing to do~

- Performance improvement when using a large number of lints.
  The workload of analyzing files is now shared between lints.

- The new syntax makes the code simpler to maintain.
  Before, the `PluginBase.getLints` rapidly ended-up doing too much.
  Now, it is simple to split the implementation in multiple bits

## 0.1.2-dev

Do some internal refactoring as an attempt to fix #60

## 0.1.1

- Fix an issue where plugins were hot-reloaded when the file analyzed changed.
- Optimized analysis such that `PluginBase.getLints()` is theorically not reinvoked
  unless the file analyzed changed.

## 0.1.0

- **Breaking**: The plugin entrypoint has moved.  
  Plugins no-longer should define a `/bin/custom_lint.dart` file.
  Instead they should define a `/lib/.dart`

- **Breaking**: The plugin entrypoint is modified. Plugins no-longer
  define a "main", but instead define a `createPlugin` function:

  Before:

  ```dart
  // /bin/custom_lint.dart
  void main(List args, SendPort sendPort) {
    startPlugin(sendPort, MyPlugin());
  }
  ```

  After:

  ```dart
  // /lib/ MyPlugin();
  ```

- Add assist support.
  Inside your plugins, you can now override `handleGetAssists`:

  ```dart
  import 'package:analyzer_plugin/protocol/protocol_generated.dart'
    as analyzer_plugin;

  class MyPlugin extends PluginBase {
    // ...

    Future handleGetAssists(
      ResolvedUnitResult resolvedUnitResult, {
      required int offset,
      required int length,
    }) async {
        // TODO return some assists for the given offset
    }
  }
  ```

## 0.0.16

Fix `expect_lint` not working if the file doesn't contain any lint.

## 0.0.15

- Custom_lint now has a built-in mechanism for testing lints.
  Simply write a file that should contain lints for your plugin.
  Then, using a syntax similar to `// ignore`, write a `// expect_lint: code`
  in the line before your lint:

  ```dart
  // expect_lint: riverpod_final_provider
  var provider = Provider(...);
  ```

  When doing this, there are two possible cases:

  - The line after the `expect_lint` correctly contains the expected lint.  
    In that case, the lint is ignored (similarly to if we used `// ignore`)
  - The next line does **not** contain the lint.
    In that case, the `expect_lint` comment will have an error.

  This allows testing your plugins by simply running `custom_lint` on your test/example folder.
  Then, if any expected lint is missing, the command will fail. But if your plugin correctly
  emits the lint, the command will succeed.

- Upgrade analyzer/analzer_plugin

## 0.0.14

- Fix custom_lint not working in the IDE

## 0.0.13

- Add debugger and hot-reload support (Thanks to @TimWhiting)
- Correctly respect `exclude` obtains from the analysis_options.yaml
- Fix `dart analyze` incorrectly failing due to showing the "plugin is starting" lint.

## 0.0.12

- Fix custom_lint plugins not working in release mode and when using git dependencies (thanks to @TimWhiting)
- Fix command line exit code not being set properly (thansk to @andrzejchm)

## 0.0.11

Fix custom_lint not showing in the IDE

## 0.0.10+1

Update docs

## 0.0.10

- Upgrade Riverpod to 2.0.0
- Fix deprecation errors with analyzer

## 0.0.9+1

Update description and readme

## 0.0.9

- Lint fixes can now be used when placing the cursor on the last character of a lint
- improve pub score

## 0.0.8

Allow lints to emit fixes

## 0.0.7

Fix a bug where the custom_lint command line may not list all lints

## 0.0.6

feat!: getLints now is expected to return a `Stream` instead of `Iterable`

fix: a bug where the lints shown by the IDE could get out of sync with the actual content of the file

## 0.0.5

Fixed error reporting if a custom_lint plugin throws but the exception comes
from a package instead of the plugin itself.

## 0.0.4

- Fixed a bug where the command line could show IDE-only meant for debugging

## 0.0.3

PluginBase.getLints now receive a `ResolvedUnitResult` instead of a `LibraryElement`.

## 0.0.2

- Compilation errors are now visible within the `pubspec.yaml` of applications
  that are using the plugin.

- Plugins that are currently loading are now highlighted inside the `pubspec.yaml`
  of applications that are using the plugin.

- If a plugin throws when trying to analyze a Dart file, the IDE will now
  show the exception at the top of the analyzed file.

- Compilation errors, exceptions and prints are now accessible within
  a log file (`custom_lint.log`) inside applications using the plugin.

## 0.0.1

Initial release