feat: Add the option ignored-patterns to the rule format-comment (#828)

* ✨ format-comment | ignored-patterns

* ✅ Test format-comment | ignored-patterns

* 📝 Update documentation

* ✏️ Fix typos in add a better comment

* ♻️ Create a config parser

* 🎨 Move the class fields before the constructors

* 📝 Update the documentation

* ⚡ Cast as non nullable as we checked before

Co-authored-by: Dmitry Krutskikh <dmitry.krutskikh@gmail.com>

Author: ValentinVignal

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+* feat: add the `ignored-patterns` option to [`format-comment`](https://dartcodemetrics.dev/docs/rules/common/format-comment). The given regular expressions will be used to ignore comments that match them.
 * fix: [`avoid-border-all`](https://dartcodemetrics.dev/docs/rules/flutter/avoid-border-all) is triggered even when it is not a const.
 * fix: remove duplicated and ignore void function calls for [`prefer-moving-to-variable`](https://dartcodemetrics.dev/docs/rules/common/prefer-moving-to-variable).
 * fix: temporary remove enums support for [`prefer-trailing-comma`](https://dartcodemetrics.dev/docs/rules/common/prefer-trailing-comma).

lib/src/analyzers/lint_analyzer/rules/rules_list/format_comment/config_parser.dart

@@ -0,0 +1,12 @@
+part of 'format_comment_rule.dart';
+
+class _ConfigParser {
+  static const _ignoredPatternsConfig = 'ignored-patterns';
+
+  static Iterable<RegExp> getIgnoredPatterns(Map<String, Object> config) =>
+      config[_ignoredPatternsConfig] is Iterable
+          ? List<String>.from(
+              config[_ignoredPatternsConfig] as Iterable,
+            ).map((stringPattern) => RegExp(stringPattern))
+          : const [];
+}

lib/src/analyzers/lint_analyzer/rules/rules_list/format_comment/format_comment_rule.dart

@@ -12,27 +12,31 @@ import '../../../models/severity.dart';
 import '../../models/common_rule.dart';
 import '../../rule_utils.dart';
 
+part 'config_parser.dart';
 part 'models/comment_info.dart';
-
 part 'models/comment_type.dart';
-
 part 'visitor.dart';
 
 class FormatCommentRule extends CommonRule {
   static const String ruleId = 'format-comment';
 
   static const _warning = 'Prefer formatting comments like sentences.';
 
+  /// The patterns to ignore. They are used to ignore and not lint comments that
+  /// match at least one of them.
+  final Iterable<RegExp> _ignoredPatterns;
+
   FormatCommentRule([Map<String, Object> config = const {}])
-      : super(
+      : _ignoredPatterns = _ConfigParser.getIgnoredPatterns(config),
+        super(
           id: ruleId,
           severity: readSeverity(config, Severity.style),
           excludes: readExcludes(config),
         );
 
   @override
   Iterable<Issue> check(InternalResolvedUnitResult source) {
-    final visitor = _Visitor()..checkComments(source.unit.root);
+    final visitor = _Visitor(_ignoredPatterns)..checkComments(source.unit.root);
 
     return [
       for (final comment in visitor.comments)

lib/src/analyzers/lint_analyzer/rules/rules_list/format_comment/visitor.dart

@@ -11,6 +11,10 @@ const _ignoreExp = 'ignore:';
 const _ignoreForFileExp = 'ignore_for_file:';
 
 class _Visitor extends RecursiveAstVisitor<void> {
+  final Iterable<RegExp> _ignoredPatterns;
+
+  _Visitor(this._ignoredPatterns);
+
   final _comments = <_CommentInfo>[];
 
   Iterable<_CommentInfo> get comments => _comments;
@@ -54,8 +58,12 @@ class _Visitor extends RecursiveAstVisitor<void> {
 
     final isMacros = _regMacrosExp.hasMatch(text) || text == _macrosEndExp;
 
+    final isAnIgnoredPattern = _ignoredPatterns.any(
+      (regExp) => regExp.hasMatch(text),
+    );
+
     {
-      if (text.isEmpty || isIgnoreComment || isMacros) {
+      if (text.isEmpty || isIgnoreComment || isMacros || isAnIgnoredPattern) {
         return;
       } else {
         text = text.trim();

test/src/analyzers/lint_analyzer/rules/rules_list/format_comment/format_comment_test.dart

@@ -89,5 +89,39 @@ void main() {
       final unit = await RuleTestHelper.resolveFromFile(_withoutIssuePath);
       RuleTestHelper.verifyNoIssues(FormatCommentRule().check(unit));
     });
+
+    test('ignores the given patterns', () async {
+      final unit = await RuleTestHelper.resolveFromFile(_examplePath);
+      final issues = FormatCommentRule(const {
+        'ignored-patterns': [
+          // Ignores all the comments that start with 'Without'.
+          r'^Without.*$',
+        ],
+      }).check(unit);
+
+      RuleTestHelper.verifyIssues(
+        issues: issues,
+        startLines: [1, 5, 8, 10],
+        startColumns: [1, 5, 3, 5],
+        locationTexts: [
+          '// With start space without dot',
+          '// with start space with dot.',
+          '/// With start space without dot',
+          '/// with start space with dot.',
+        ],
+        messages: [
+          'Prefer formatting comments like sentences.',
+          'Prefer formatting comments like sentences.',
+          'Prefer formatting comments like sentences.',
+          'Prefer formatting comments like sentences.',
+        ],
+        replacements: [
+          '// With start space without dot.',
+          '// With start space with dot.',
+          '/// With start space without dot.',
+          '/// With start space with dot.',
+        ],
+      );
+    });
   });
 }

website/docs/rules/common/format-comment.md

@@ -1,5 +1,7 @@
 # Format comments
 
+![Configurable](https://img.shields.io/badge/-configurable-informational)
+
 ## Rule id {#rule-id}
 
 format-comment
@@ -12,6 +14,20 @@ Style
 
 Prefer format comments like sentences.
 
+Use `ignored-patterns` configuration, if you want to ignore comments that match the given regular expressions.
+
+### Config example {#config-example}
+
+```yaml
+dart_code_metrics:
+  ...
+  rules:
+    ...
+    - format-comment:
+        ignored-patterns:
+          - ^ cSpell.*  # Ignores all the comments that start with 'cSpell' (for example: '// cSpell:disable-next-line').
+```
+
 ### Example {#example}
 
 Bad:
@@ -50,4 +66,4 @@ class Test {
 }
 /* Prefer format comments 
 like sentences. */ 
-```
+```

website/docs/rules/overview.md

@@ -79,7 +79,7 @@ Rules configuration is [described here](../getting-started/configuration#configu
 
     Checks that double literals should begin with `0.` instead of just `.`, and should not end with a trailing `0`.
 
-- [format-comment](./common/format-comment.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success)
+- [format-comment](./common/format-comment.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/format-comment.md#config-example) ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success)
 
   Prefer format comments like sentences.