feat: introduce Halsted Volume metric (#434)

* refactor: remove unused metric documentation filed

* refactor: improve maintainability-index calculation

* refactor: improve HalsteadVolumeAstVisitor

* refactor: remove custom implementation of `sum`

* feature: introduce Halstead Volume metric

* refactor: improve maintainability-index calculation

* update changelog

Author: dkrutskikh

.vscode/settings.json

@@ -4,6 +4,7 @@
     "cSpell.words": [
         "Backport",
         "Gitlab",
+        "Halstead",
         "McCabe's",
         "SLOC",
         "ansicolor",

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 * Add support for global rules-exclude
+* Add `Halstead Volume` metric.
 
 ## 4.2.1
 

README.md

@@ -150,6 +150,7 @@ Usage: metrics [arguments...] <directories>
 
 
     --cyclomatic-complexity=<20>                  Cyclomatic Complexity threshold
+    --halstead-volume=<150>                       Halstead Volume threshold
     --lines-of-code=<100>                         Lines of Code threshold
     --maximum-nesting-level=<5>                   Maximum Nesting Level threshold
     --number-of-methods=<10>                      Number of Methods threshold

lib/src/analyzers/lint_analyzer/lint_analyzer.dart

@@ -3,6 +3,7 @@ import 'dart:math';
 
 import 'package:analyzer/dart/analysis/results.dart';
 import 'package:analyzer/dart/ast/ast.dart';
+import 'package:collection/collection.dart';
 import 'package:path/path.dart';
 
 import '../../config_builder/config_builder.dart';
@@ -14,10 +15,8 @@ import '../../utils/file_utils.dart';
 import '../../utils/node_utils.dart';
 import 'lint_analysis_config.dart';
 import 'lint_config.dart';
-import 'metrics/halstead_volume_ast_visitor.dart';
-import 'metrics/metric_utils.dart';
 import 'metrics/metrics_list/cyclomatic_complexity/cyclomatic_complexity_metric.dart';
-import 'metrics/metrics_list/source_lines_of_code/source_code_visitor.dart';
+import 'metrics/metrics_list/halstead_volume/halstead_volume_metric.dart';
 import 'metrics/metrics_list/source_lines_of_code/source_lines_of_code_metric.dart';
 import 'metrics/models/metric_documentation.dart';
 import 'metrics/models/metric_value.dart';
@@ -32,7 +31,6 @@ import 'models/scoped_class_declaration.dart';
 import 'models/scoped_function_declaration.dart';
 import 'models/suppression.dart';
 import 'reporters/reporter_factory.dart';
-import 'reporters/utility_selector.dart';
 
 class LintAnalyzer {
   const LintAnalyzer();
@@ -298,104 +296,48 @@ class LintAnalyzer {
     final functionRecords = <ScopedFunctionDeclaration, Report>{};
 
     for (final function in visitor.functions) {
-      final cyclomatic = config.methodsMetrics
-          .firstWhere(
-            (metric) => metric.id == CyclomaticComplexityMetric.metricId,
-          )
-          .compute(
+      final metrics = [
+        for (final metric in config.methodsMetrics)
+          if (metric.supports(
             function.declaration,
             visitor.classes,
             visitor.functions,
             source,
-          );
-
-      final sourceLinesOfCodeVisitor = SourceCodeVisitor(source.lineInfo);
-
-      function.declaration.visitChildren(sourceLinesOfCodeVisitor);
+          ))
+            metric.compute(
+              function.declaration,
+              visitor.classes,
+              visitor.functions,
+              source,
+            ),
+      ];
 
-      final sourceLinesOfCode = MetricValue<int>(
-        metricsId: SourceLinesOfCodeMetric.metricId,
-        documentation: const MetricDocumentation(
-          name: '',
-          shortName: '',
-          brief: '',
-          measuredType: EntityType.methodEntity,
-          recomendedThreshold: 0,
-          examples: [],
-        ),
-        value: sourceLinesOfCodeVisitor.linesWithCode.length,
-        level: valueLevel(
-          sourceLinesOfCodeVisitor.linesWithCode.length,
-          readNullableThreshold<int>(
-            config.metricsConfig,
-            SourceLinesOfCodeMetric.metricId,
-          ),
-        ),
-        comment: '',
+      final cyclomatic = metrics.firstWhereOrNull(
+        (value) => value.metricsId == CyclomaticComplexityMetric.metricId,
       );
 
-      final halsteadVolumeAstVisitor = HalsteadVolumeAstVisitor();
-
-      function.declaration.visitChildren(halsteadVolumeAstVisitor);
-
-      // Total number of occurrences of operators.
-      final totalNumberOfOccurrencesOfOperators =
-          sum(halsteadVolumeAstVisitor.operators.values);
-
-      // Total number of occurrences of operands
-      final totalNumberOfOccurrencesOfOperands =
-          sum(halsteadVolumeAstVisitor.operands.values);
-
-      // Number of distinct operators.
-      final numberOfDistinctOperators =
-          halsteadVolumeAstVisitor.operators.keys.length;
-
-      // Number of distinct operands.
-      final numberOfDistinctOperands =
-          halsteadVolumeAstVisitor.operands.keys.length;
-
-      // Halstead Program Length – The total number of operator occurrences and the total number of operand occurrences.
-      final halsteadProgramLength = totalNumberOfOccurrencesOfOperators +
-          totalNumberOfOccurrencesOfOperands;
-
-      // Halstead Vocabulary – The total number of unique operator and unique operand occurrences.
-      final halsteadVocabulary =
-          numberOfDistinctOperators + numberOfDistinctOperands;
-
-      // Program Volume – Proportional to program size, represents the size, in bits, of space necessary for storing the program. This parameter is dependent on specific algorithm implementation.
-      final halsteadVolume =
-          halsteadProgramLength * log2(max(1, halsteadVocabulary));
+      final halsteadVolume = metrics.firstWhereOrNull(
+        (value) => value.metricsId == HalsteadVolumeMetric.metricId,
+      );
 
-      final maintainabilityIndex = max(
-        0,
-        (171 -
-                5.2 * log(max(1, halsteadVolume)) -
-                cyclomatic.value * 0.23 -
-                16.2 * log(max(1, sourceLinesOfCode.value))) *
-            100 /
-            171,
-      ).toDouble();
+      final sourceLinesOfCode = metrics.firstWhereOrNull(
+        (value) => value.metricsId == SourceLinesOfCodeMetric.metricId,
+      );
 
-      final report = Report(
-        location: nodeLocation(
-          node: function.declaration,
-          source: source,
-        ),
-        declaration: function.declaration,
-        metrics: [
-          for (final metric in config.methodsMetrics)
-            if (metric.supports(
-              function.declaration,
-              visitor.classes,
-              visitor.functions,
-              source,
-            ))
-              metric.compute(
-                function.declaration,
-                visitor.classes,
-                visitor.functions,
-                source,
-              ),
+      if (cyclomatic != null &&
+          halsteadVolume != null &&
+          sourceLinesOfCode != null) {
+        final maintainabilityIndex = max(
+          0,
+          (171 -
+                  5.2 * log(max(1, halsteadVolume.value)) -
+                  cyclomatic.value * 0.23 -
+                  16.2 * log(max(1, sourceLinesOfCode.value))) *
+              100 /
+              171,
+        ).toDouble();
+
+        metrics.add(
           MetricValue<double>(
             metricsId: 'maintainability-index',
             documentation: const MetricDocumentation(
@@ -404,18 +346,21 @@ class LintAnalyzer {
               brief: '',
               measuredType: EntityType.classEntity,
               recomendedThreshold: 0,
-              examples: [],
             ),
             value: maintainabilityIndex,
             level: _maintainabilityIndexViolationLevel(
               maintainabilityIndex,
             ),
             comment: '',
           ),
-        ],
-      );
+        );
+      }
 
-      functionRecords[function] = report;
+      functionRecords[function] = Report(
+        location: nodeLocation(node: function.declaration, source: source),
+        declaration: function.declaration,
+        metrics: metrics,
+      );
     }
 
     return functionRecords;

lib/src/analyzers/lint_analyzer/metrics/metrics_factory.dart

@@ -1,5 +1,6 @@
 import '../models/entity_type.dart';
 import 'metrics_list/cyclomatic_complexity/cyclomatic_complexity_metric.dart';
+import 'metrics_list/halstead_volume/halstead_volume_metric.dart';
 import 'metrics_list/lines_of_code_metric.dart';
 import 'metrics_list/maximum_nesting_level/maximum_nesting_level_metric.dart';
 import 'metrics_list/number_of_methods_metric.dart';
@@ -11,6 +12,8 @@ import 'models/metric.dart';
 final _implementedMetrics = <String, Metric Function(Map<String, Object>)>{
   CyclomaticComplexityMetric.metricId: (config) =>
       CyclomaticComplexityMetric(config: config),
+  HalsteadVolumeMetric.metricId: (config) =>
+      HalsteadVolumeMetric(config: config),
   LinesOfCodeMetric.metricId: (config) => LinesOfCodeMetric(config: config),
   MaximumNestingLevelMetric.metricId: (config) =>
       MaximumNestingLevelMetric(config: config),

lib/src/analyzers/lint_analyzer/metrics/metrics_list/cyclomatic_complexity/cyclomatic_complexity_metric.dart

@@ -21,7 +21,6 @@ const _documentation = MetricDocumentation(
   brief: 'The number of linearly-independent paths through a code block',
   measuredType: EntityType.methodEntity,
   recomendedThreshold: 20,
-  examples: [],
 );
 
 /// Cyclomatic Complexity (CYCLO)

lib/src/analyzers/lint_analyzer/metrics/halstead_volume_ast_visitor.dart renamed to lib/src/analyzers/lint_analyzer/metrics/metrics_list/halstead_volume/halstead_volume_ast_visitor.dart

@@ -1,20 +1,31 @@
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/ast/token.dart';
 import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:collection/collection.dart';
 
 class HalsteadVolumeAstVisitor extends RecursiveAstVisitor<void> {
   final _operators = <String, int>{};
   final _operands = <String, int>{};
 
-  Map<String, int> get operators => _operators;
-  Map<String, int> get operands => _operands;
+  /// the number of operators
+  int get operators => _operators.values.sum;
+
+  /// the number of unique operators
+  int get uniqueOperators => _operators.keys.length;
+
+  /// the number of operands
+  int get operands => _operands.values.sum;
+
+  /// the number of unique operands
+  int get uniqueOperands => _operands.keys.length;
 
   @override
   void visitBlockFunctionBody(BlockFunctionBody node) {
     _analyzeFunctionBodyData(
       node.block.leftBracket.next,
       node.block.rightBracket,
     );
+
     super.visitBlockFunctionBody(node);
   }
 
@@ -24,7 +35,8 @@ class HalsteadVolumeAstVisitor extends RecursiveAstVisitor<void> {
       node.expression.beginToken.previous,
       node.expression.endToken.next,
     );
-    node.visitChildren(this);
+
+    super.visitExpressionFunctionBody(node);
   }
 
   void _analyzeFunctionBodyData(Token? firstToken, Token? lastToken) {
@@ -33,9 +45,11 @@ class HalsteadVolumeAstVisitor extends RecursiveAstVisitor<void> {
       if (token.isOperator) {
         _operators[token.type.name] = (_operators[token.type.name] ?? 0) + 1;
       }
+
       if (token.isIdentifier) {
         _operands[token.lexeme] = (_operands[token.lexeme] ?? 0) + 1;
       }
+
       token = token.next;
     }
   }

lib/src/analyzers/lint_analyzer/metrics/metrics_list/halstead_volume/halstead_volume_metric.dart

@@ -0,0 +1,75 @@
+import 'dart:math';
+
+import 'package:analyzer/dart/ast/ast.dart';
+
+import '../../../models/entity_type.dart';
+import '../../../models/internal_resolved_unit_result.dart';
+import '../../../models/scoped_class_declaration.dart';
+import '../../../models/scoped_function_declaration.dart';
+import '../../metric_utils.dart';
+import '../../models/function_metric.dart';
+import '../../models/metric_computation_result.dart';
+import '../../models/metric_documentation.dart';
+import 'halstead_volume_ast_visitor.dart';
+
+const _documentation = MetricDocumentation(
+  name: 'Halstead Volume',
+  shortName: 'HALVOL',
+  brief:
+      'The Halstead Volume is based on the Length and the Vocabulary. You can view this as the "bulk" of the code – how much information does the reader of the code have to absorb to understand its meaning. The biggest influence on the Volume metric is the Halstead length which causes a linear increase in the Volume i.e doubling the Length will double the Volume. In the case of the Vocabulary the increase is logarithmic.',
+  measuredType: EntityType.methodEntity,
+  recomendedThreshold: 150,
+);
+
+/// Halstead Volume (HALVOL)
+///
+/// The Halstead Volume is based on the Length and the Vocabulary. You can view
+/// this as the ‘bulk’ of the code – how much information does the reader of the
+/// code have to absorb to understand its meaning. The biggest influence on the
+/// Volume metric is the Halstead length which causes a linear increase in the
+/// Volume i.e doubling the Length will double the Volume. In the case of the
+/// Vocabulary the increase is logarithmic.
+class HalsteadVolumeMetric extends FunctionMetric<double> {
+  static const String metricId = 'halstead-volume';
+
+  HalsteadVolumeMetric({Map<String, Object> config = const {}})
+      : super(
+          id: metricId,
+          documentation: _documentation,
+          threshold: readNullableThreshold<double>(config, metricId),
+          levelComputer: valueLevel,
+        );
+
+  @override
+  MetricComputationResult<double> computeImplementation(
+    Declaration node,
+    Iterable<ScopedClassDeclaration> classDeclarations,
+    Iterable<ScopedFunctionDeclaration> functionDeclarations,
+    InternalResolvedUnitResult source,
+  ) {
+    final visitor = HalsteadVolumeAstVisitor();
+    node.visitChildren(visitor);
+
+    // LTH (length) - the sum of the number of operators and the number of operands
+    final lth = visitor.operators + visitor.operands;
+
+    // VOC (vocabulary) – the the number of unique operators and the number of unique operands
+    final voc = visitor.uniqueOperators + visitor.uniqueOperands;
+
+    // VOL (volume) – based on the length and the vocabulary
+    final vol = voc != 0 ? lth * _log2(voc) : 0.0;
+
+    return MetricComputationResult<double>(value: vol);
+  }
+
+  @override
+  String commentMessage(String nodeType, double value, double? threshold) {
+    final exceeds = threshold != null && value > threshold
+        ? ', which exceeds the maximum of $threshold allowed'
+        : '';
+
+    return 'This $nodeType has a halstead volume of $value$exceeds.';
+  }
+
+  double _log2(int a) => log(max(1, a)) / ln2;
+}

lib/src/analyzers/lint_analyzer/metrics/metrics_list/lines_of_code_metric.dart

@@ -16,7 +16,6 @@ const _documentation = MetricDocumentation(
       'The number of physical lines of code of a method, including blank lines and comments',
   measuredType: EntityType.methodEntity,
   recomendedThreshold: 100,
-  examples: [],
 );
 
 /// Lines of Code (LOC)

lib/src/analyzers/lint_analyzer/metrics/metrics_list/maximum_nesting_level/maximum_nesting_level_metric.dart

@@ -19,7 +19,6 @@ const _documentation = MetricDocumentation(
   brief: 'The maximum nesting level of control structures within a method',
   measuredType: EntityType.methodEntity,
   recomendedThreshold: 5,
-  examples: [],
 );
 
 /// Maximum Nesting Level (MAXNESTING)