feat: add Checkstyle format reporter. (#738)

* feat: add Checkstyle format reporter.

* chore: tune bitbucket pipeline

* chore: update Changelog

Author: dkrutskikh

.vscode/settings.json

@@ -6,6 +6,7 @@
         "backport",
         "behaviour",
         "bools",
+        "Checkstyle",
         "codeclimate",
         "codecov",
         "codequality",

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 * **Breaking Change:** cli arguments `--fatal-unused` and `--fatal-warnings` activate by default.
+* feat: add Checkstyle format reporter.
 * chore: restrict `analyzer` version to `>=3.0.0 <3.4.0`.
 * chore: restrict `analyzer_plugin` version to `>=0.9.0 <0.10.0`.
 * feat: add [prefer-immediate-return](https://dartcodemetrics.dev/docs/rules/common/prefer-immediate-return) rule

bitbucket-pipelines.yml

@@ -6,4 +6,6 @@ pipelines:
         name: analyze
         script:
           - dart pub upgrade
-          - dart run dart_code_metrics:metrics lib
+          - dart run dart_code_metrics:metrics lib -r checkstyle > checkstyle-result.xml
+        after-script:
+          - pipe: atlassian/checkstyle-report:0.3.1

lib/src/analyzers/lint_analyzer/reporters/reporter_factory.dart

@@ -1,5 +1,6 @@
 import 'dart:io';
 
+import '../../../reporters/models/checkstyle_reporter.dart';
 import '../../../reporters/models/code_climate_reporter.dart';
 import '../../../reporters/models/console_reporter.dart';
 import '../../../reporters/models/file_report.dart';
@@ -8,6 +9,7 @@ import '../../../reporters/models/html_reporter.dart';
 import '../../../reporters/models/json_reporter.dart';
 import '../../../reporters/models/reporter.dart';
 import 'lint_report_params.dart';
+import 'reporters_list/checkstyle/lint_checkstyle_reporter.dart';
 import 'reporters_list/code_climate/lint_code_climate_reporter.dart';
 import 'reporters_list/console/lint_console_reporter.dart';
 import 'reporters_list/github/lint_github_reporter.dart';
@@ -20,6 +22,7 @@ final _implementedReports = <
   IOSink output,
   String reportFolder,
 )>{
+  CheckstyleReporter.id: (output, _) => LintCheckstyleReporter(output),
   ConsoleReporter.id: (output, _) => LintConsoleReporter(output),
   ConsoleReporter.verboseId: (output, _) =>
       LintConsoleReporter(output, reportAll: true),

lib/src/analyzers/lint_analyzer/reporters/reporters_list/checkstyle/lint_checkstyle_reporter.dart

@@ -0,0 +1,75 @@
+import 'dart:io';
+
+import 'package:xml/xml.dart';
+
+import '../../../../../reporters/models/checkstyle_reporter.dart';
+import '../../../models/lint_file_report.dart';
+import '../../../models/severity.dart';
+import '../../../models/summary_lint_report_record.dart';
+import '../../lint_report_params.dart';
+
+/// Lint Checkstyle reporter.
+///
+/// Use it to create reports in Checkstyle format.
+class LintCheckstyleReporter extends CheckstyleReporter<LintFileReport,
+    SummaryLintReportRecord<Object>, LintReportParams> {
+  LintCheckstyleReporter(IOSink output) : super(output);
+
+  @override
+  Future<void> report(
+    Iterable<LintFileReport> records, {
+    Iterable<SummaryLintReportRecord<Object>> summary = const [],
+    LintReportParams? additionalParams,
+  }) async {
+    if (records.isEmpty) {
+      return;
+    }
+
+    final builder = XmlBuilder();
+
+    builder
+      ..processing('xml', 'version="1.0"')
+      ..element('checkstyle', attributes: {'version': '10.0'}, nest: () {
+        for (final record in records) {
+          if (!_needToReport(record)) {
+            continue;
+          }
+
+          builder.element(
+            'file',
+            attributes: {'name': record.relativePath},
+            nest: () {
+              final issues = [...record.issues, ...record.antiPatternCases];
+
+              for (final issue in issues) {
+                builder.element(
+                  'error',
+                  attributes: {
+                    'line': '${issue.location.start.line}',
+                    if (issue.location.start.column > 0)
+                      'column': '${issue.location.start.column}',
+                    'severity': _severityMapping[issue.severity] ?? 'ignore',
+                    'message': issue.message,
+                    'source': issue.ruleId,
+                  },
+                );
+              }
+            },
+          );
+        }
+      });
+
+    output.writeln(builder.buildDocument().toXmlString(pretty: true));
+  }
+
+  bool _needToReport(LintFileReport report) =>
+      report.issues.isNotEmpty || report.antiPatternCases.isNotEmpty;
+}
+
+const _severityMapping = {
+  Severity.error: 'error',
+  Severity.warning: 'warning',
+  Severity.style: 'info',
+  Severity.performance: 'warning',
+  Severity.none: 'ignore',
+};

lib/src/cli/commands/analyze_command.dart

@@ -110,6 +110,7 @@ class AnalyzeCommand extends BaseCommand {
         allowed: [
           FlagNames.consoleReporter,
           FlagNames.consoleVerboseReporter,
+          FlagNames.checkstyleReporter,
           FlagNames.codeClimateReporter,
           FlagNames.githubReporter,
           FlagNames.gitlabCodeClimateReporter,

lib/src/cli/models/flag_names.dart

@@ -1,3 +1,4 @@
+import '../../reporters/models/checkstyle_reporter.dart';
 import '../../reporters/models/code_climate_reporter.dart';
 import '../../reporters/models/console_reporter.dart';
 import '../../reporters/models/github_reporter.dart';
@@ -17,6 +18,7 @@ class FlagNames {
   static const consoleReporter = ConsoleReporter.id;
   static const consoleVerboseReporter = ConsoleReporter.verboseId;
   static const codeClimateReporter = CodeClimateReporter.id;
+  static const checkstyleReporter = CheckstyleReporter.id;
   static const htmlReporter = HtmlReporter.id;
   static const jsonReporter = JsonReporter.id;
   static const githubReporter = GitHubReporter.id;

lib/src/reporters/models/checkstyle_reporter.dart

@@ -0,0 +1,17 @@
+import 'dart:io';
+
+import 'package:meta/meta.dart';
+
+import 'file_report.dart';
+import 'reporter.dart';
+
+/// Creates reports in Checkstyle format widely understood by various CI and analysis tools
+abstract class CheckstyleReporter<T extends FileReport, S, P>
+    extends Reporter<T, S, P> {
+  static const String id = 'checkstyle';
+
+  @protected
+  final IOSink output;
+
+  const CheckstyleReporter(this.output);
+}

pubspec.yaml

@@ -22,6 +22,7 @@ dependencies:
   meta: ^1.3.0
   path: ^1.8.0
   source_span: ^1.8.0
+  xml: ^5.3.0
   yaml: ^3.1.0
 
 dev_dependencies:

test/src/analyzers/lint_analyzer/reporters/reporters_list/checkstyle/lint_checkstyle_reporter_test.dart

@@ -0,0 +1,56 @@
+import 'dart:io';
+
+import 'package:dart_code_metrics/src/analyzers/lint_analyzer/reporters/reporters_list/checkstyle/lint_checkstyle_reporter.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+import 'package:xml/xml.dart';
+
+import '../report_example.dart';
+
+class IOSinkMock extends Mock implements IOSink {}
+
+void main() {
+  group('LintCheckstyleReporter reports in json format', () {
+    // ignore: close_sinks
+    late IOSinkMock output;
+
+    setUp(() {
+      output = IOSinkMock();
+    });
+
+    test('empty report', () {
+      LintCheckstyleReporter(output).report([]);
+
+      verifyNever(() => output.write(captureAny()));
+    });
+
+    test('complex report', () {
+      LintCheckstyleReporter(output).report(testReport, summary: testSummary);
+
+      final captured = verify(
+        () => output.writeln(captureAny()),
+      ).captured.first as String;
+      final report = XmlDocument.parse(captured);
+
+      final file = report.findAllElements('file');
+      expect(
+        file.first.getAttribute('name'),
+        equals('test/resources/class_with_factory_constructors.dart'),
+      );
+
+      final errors = report.findAllElements('error');
+      expect(errors.first.getAttribute('line'), equals('0'));
+      expect(errors.first.getAttribute('severity'), equals('warning'));
+      expect(errors.first.getAttribute('message'), equals('simple message'));
+      expect(errors.first.getAttribute('source'), equals('id'));
+
+      expect(errors.last.getAttribute('line'), equals('0'));
+      expect(errors.last.getAttribute('severity'), equals('info'));
+      expect(
+        errors.last.getAttribute('message'),
+        equals('simple design message'),
+      );
+      expect(errors.last.getAttribute('source'), equals('designId'));
+    });
+  });
+}

test/src/cli/commands/analyze_command_test.dart

@@ -9,7 +9,7 @@ const _usage = 'Collect code metrics, rules and anti-patterns violations.\n'
     '\n'
     '\n'
     '-r, --reporter=<console>                          The format of the output of the analysis.\n'
-    '                                                  [console (default), console-verbose, codeclimate, github, gitlab, html, json]\n'
+    '                                                  [console (default), console-verbose, checkstyle, codeclimate, github, gitlab, html, json]\n'
     '-o, --output-directory=<OUTPUT>                   Write HTML output to OUTPUT.\n'
     '                                                  (defaults to "metrics")\n'
     '\n'

website/docs/cli/analyze.md

@@ -18,8 +18,7 @@ Usage: metrics analyze [arguments...] <directories>
 
 
 -r, --reporter=<console>                          The format of the output of the analysis
-                                                  [console (default), console-verbose,
-                                                  codeclimate, github, gitlab, html, json]
+                                                  [console (default), console-verbose, checkstyle, codeclimate, github, gitlab, html, json]
 -o, --output-directory=<OUTPUT>                   Write HTML output to OUTPUT
                                                   (defaults to "metrics/")
 
@@ -356,7 +355,7 @@ jobs:
         run: flutter pub get
 
       - name: Run Code Metrics
-        run: flutter pub run dart_code_metrics:metrics --reporter=github lib
+        run: flutter pub run dart_code_metrics:metrics --fatal-style --fatal-performance --fatal-warnings --reporter=github lib
 ```
 
 Example of a report in a PR:
@@ -375,7 +374,7 @@ code_quality:
   before_script:
     - dart pub global activate dart_code_metrics
   script:
-    - dart pub global run dart_code_metrics:metrics analyze lib -r gitlab > code-quality-report.json
+    - dart pub global run dart_code_metrics:metrics analyze --fatal-style --fatal-performance --fatal-warnings --reporter=gitlab lib > code-quality-report.json
   artifacts:
     reports:
       codequality: code-quality-report.json
@@ -388,3 +387,51 @@ Example of a Code Quality widget in a PR:
 Example of a Code Quality in a PR diff view:
 
 ![GitLab diff](../../static/img/gitlab-codequality-diff-view.jpg)
+
+### Checkstyle {#checkstyle}
+
+Reports about design and static code diagnostics issues. Use `--reporter=checkstyle` to enable this format.
+
+```xml
+<?xml version="1.0"?>
+<checkstyle version="10.0">
+  <file name="lib/src/analyzers/lint_analyzer/lint_analyzer.dart">
+    <error line="168" column="3" severity="ignore" message="Long method. This method contains 63 lines with code." source="long-method"/>
+  </file>
+  <file name="lib/src/analyzers/lint_analyzer/rules/rules_list/avoid_returning_widgets/visit_declaration.dart">
+    <error line="3" column="1" severity="ignore" message="Long Parameter List. This function require 6 arguments." source="long-parameter-list"/>
+  </file>
+  <file name="lib/src/analyzers/lint_analyzer/reporters/utility_selector.dart">
+    <error line="27" column="3" severity="ignore" message="Long method. This method contains 53 lines with code." source="long-method"/>
+  </file>
+  <file name="lib/src/analyzers/lint_analyzer/reporters/reporters_list/html/utility_functions.dart">
+    <error line="45" column="1" severity="ignore" message="Long function. This function contains 56 lines with code." source="long-method"/>
+  </file>
+  <file name="lib/src/analyzers/lint_analyzer/reporters/reporters_list/html/lint_html_reporter.dart">
+    <error line="74" column="3" severity="ignore" message="Long method. This method contains 136 lines with code." source="long-method"/>
+    <error line="330" column="3" severity="ignore" message="Long method. This method contains 159 lines with code." source="long-method"/>
+  </file>
+</checkstyle>
+```
+
+#### Example Bitbucket pipeline configuration
+
+- Define a pipeline in your [`bitbucket-pipelines.yml`](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/) file that generates the Checkstyle report and [process them](https://bitbucket.org/product/features/pipelines/integrations?p=atlassian/checkstyle-report).
+
+```yaml
+image: google/dart
+
+pipelines:
+  default:
+    - step:
+        name: analyze
+        script:
+          - dart pub global activate dart_code_metrics
+          - dart pub global run dart_code_metrics:metrics analyze --fatal-style --fatal-performance --fatal-warnings --reporter=checkstyle lib > checkstyle-result.xml
+        after-script:
+          - pipe: atlassian/checkstyle-report:0.3.1
+```
+
+Example of a report:
+
+![Checkstyle report in Bitbucket  ](../../static/img/bitbucket-pipeline-report.jpg)

website/docs/cli/overview.md

@@ -29,6 +29,7 @@ It will produce a result in one of the supported formats:
 
 - Console
 - GitHub
+- Checkstyle
 - Codeclimate
 - HTML
 - JSON