refactor(analysis): 🕵️ add more lint rules and explain ignored diagnostics

analysis_options.yaml

@@ -3,11 +3,22 @@ include: package:very_good_analysis/analysis_options.yaml
 linter:
   rules:
     - annotate_redeclares
+    - avoid_annotating_with_dynamic
     - avoid_classes_with_only_static_members
+    - avoid_implementing_value_types
     - avoid_types_on_closure_parameters
+    - do_not_use_environment
+    - document_ignores
+    - matching_super_parameters
+    - no_literal_bool_comparisons
+    - prefer_expression_function_bodies
+    - prefer_foreach
+    - prefer_mixin
     - type_literal_in_constant_pattern
+    - unintended_html_in_doc_comment
     - unnecessary_library_name
     - unnecessary_null_aware_operator_on_extension_on_nullable
+    - unreachable_from_main
 
 analyzer:
   errors:

example/main.dart

@@ -1,3 +1,4 @@
+// For documentation purposes.
 // ignore_for_file: unnecessary_statements, cascade_invocations
 
 import 'package:music_notes/music_notes.dart';

lib/src/interval/interval.dart

@@ -1,3 +1,4 @@
+// To allow major (M) and minor (m) static constant names.
 // ignore_for_file: constant_identifier_names
 
 import 'package:meta/meta.dart' show immutable;

lib/src/interval/interval_class.dart

@@ -1,3 +1,4 @@
+// To allow major (M) and minor (m) static constant names.
 // ignore_for_file: constant_identifier_names
 
 import 'dart:collection' show SplayTreeSet;

lib/src/interval/quality.dart

@@ -61,6 +61,7 @@ sealed class Quality implements Comparable<Quality> {
   @override
   int compareTo(Quality other) => compareMultiple([
         () => semitones.compareTo(other.semitones),
+        // TODO(albertms10): rewrite without relying on `runtimeType`.
         // ignore: no_runtimetype_tostring
         () => '$runtimeType'.compareTo('${other.runtimeType}'),
       ]);

lib/src/note/pitch_class.dart

@@ -165,7 +165,7 @@ final class PitchClass extends Scalable<PitchClass>
   Note resolveClosestSpelling([Accidental? preferredAccidental]) {
     try {
       return resolveSpelling(preferredAccidental);
-      // ignore: avoid_catching_errors
+      // ignore: avoid_catching_errors to catch `ArgumentError`.
     } on ArgumentError {
       return resolveSpelling();
     }

lib/src/scalable.dart

@@ -4,7 +4,7 @@ import 'music.dart';
 import 'note/pitch_class.dart';
 import 'transposable.dart';
 
-/// A interface for items that can form scales.
+/// An interface for items that can form scales.
 abstract class Scalable<T extends Scalable<T>>
     with Enharmonic<PitchClass>
     implements Transposable<T> {

lib/src/transposable.dart

@@ -1,6 +1,6 @@
 import 'interval/interval.dart';
 
-/// A interface for items that can be transposed.
+/// An interface for items that can be transposed.
 // ignore: one_member_abstracts
 abstract interface class Transposable<T> {
   /// Transposes this [T] by [interval].

test/src/harmony/harmonic_function_test.dart

@@ -58,25 +58,25 @@ void main() {
     group('.hashCode', () {
       test('returns the same hashCode for equal HarmonicFunctions', () {
         expect(
-          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables
+          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables test
           HarmonicFunction([ScaleDegree.i]).hashCode,
-          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables
+          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables test
           HarmonicFunction([ScaleDegree.i]).hashCode,
         );
         expect(
-          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables
+          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables test
           HarmonicFunction([
-            // ignore: prefer_const_constructors
+            // ignore: prefer_const_constructors test
             ScaleDegree(
               2,
               quality: ImperfectQuality.major,
               inversion: 1,
               semitonesDelta: -1,
             ),
           ]).hashCode,
-          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables
+          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables test
           HarmonicFunction([
-            // ignore: prefer_const_constructors
+            // ignore: prefer_const_constructors test
             ScaleDegree(
               2,
               quality: ImperfectQuality.major,

test/src/interval/interval_class_test.dart

@@ -7,9 +7,9 @@ void main() {
   group('IntervalClass', () {
     group('constructor', () {
       test('creates a new IntervalClass from semitones', () {
-        // ignore: use_named_constants
+        // ignore: use_named_constants test
         expect(const IntervalClass(8), IntervalClass.M3);
-        // ignore: use_named_constants
+        // ignore: use_named_constants test
         expect(const IntervalClass(-2), IntervalClass.M2);
       });
     });

test/src/note/accidental_test.dart

@@ -1,5 +1,3 @@
-// ignore_for_file: use_named_constants
-
 import 'dart:collection' show SplayTreeSet;
 
 import 'package:music_notes/music_notes.dart';

test/src/note/hearing_range_test.dart

@@ -17,31 +17,31 @@ void main() {
     group('.hashCode', () {
       test('returns the same hashCode for equal ClosestPitches', () {
         expect(
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(1), max: Frequency(1000)).hashCode,
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(1), max: Frequency(1000)).hashCode,
         );
         expect(
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(10.646), max: Frequency(2345.3)).hashCode,
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(10.646), max: Frequency(2345.3)).hashCode,
         );
       });
 
       test('returns different hashCodes for different ClosestPitches', () {
         expect(
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(0), max: Frequency(30000)).hashCode,
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           isNot(HearingRange(min: Frequency(2), max: Frequency(3)).hashCode),
         );
         expect(
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(10.6), max: Frequency(2345.3)).hashCode,
           isNot(
-            // ignore: prefer_const_constructors
+            // ignore: prefer_const_constructors test
             HearingRange(min: Frequency(10.7), max: Frequency(2345.6)).hashCode,
           ),
         );
@@ -50,9 +50,9 @@ void main() {
       test('ignores equal ClosestPitch instances in a Set', () {
         final collection = {
           HearingRange.human,
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(0), max: Frequency(1000)),
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           HearingRange(min: Frequency(10), max: Frequency(20000)),
         };
         collection.addAll(collection);

test/src/note/pitch_class_test.dart

@@ -7,9 +7,9 @@ void main() {
   group('PitchClass', () {
     group('constructor', () {
       test('creates a new PitchClass from semitones', () {
-        // ignore: use_named_constants
+        // ignore: use_named_constants test
         expect(const PitchClass(-2), PitchClass.aSharp);
-        // ignore: use_named_constants
+        // ignore: use_named_constants test
         expect(const PitchClass(13), PitchClass.cSharp);
       });
     });

test/src/note/pitch_test.dart

@@ -1434,9 +1434,9 @@ void main() {
       test('returns the same hashCode for equal Pitches', () {
         expect(Note.c.inOctave(4).hashCode, Note.c.inOctave(4).hashCode);
         expect(
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           Pitch(Note.a, octave: 3).hashCode,
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           Pitch(Note.a, octave: 3).hashCode,
         );
       });

test/src/scale/scale_degree_test.dart

@@ -143,17 +143,17 @@ void main() {
 
     group('.hashCode', () {
       test('returns the same hashCode for equal ScaleDegrees', () {
-        // ignore: prefer_const_constructors
+        // ignore: prefer_const_constructors test
         expect(ScaleDegree(1).hashCode, ScaleDegree(1).hashCode);
         expect(
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           ScaleDegree(
             2,
             quality: ImperfectQuality.major,
             inversion: 1,
             semitonesDelta: -1,
           ).hashCode,
-          // ignore: prefer_const_constructors
+          // ignore: prefer_const_constructors test
           ScaleDegree(
             2,
             quality: ImperfectQuality.major,

test/src/scale/scale_pattern_test.dart

@@ -659,9 +659,9 @@ void main() {
           const ScalePattern([Interval.d5]),
           ScalePattern.major,
           ScalePattern.aeolian,
-          // ignore: equal_elements_in_set
+          // ignore: equal_elements_in_set test
           ScalePattern.naturalMinor,
-          // ignore: equal_elements_in_set
+          // ignore: equal_elements_in_set test
           ScalePattern.ionian,
           ScalePattern.mixolydian,
           ScalePattern.wholeTone,

test/src/tuning/equal_temperament_test.dart

@@ -64,7 +64,7 @@ void main() {
 
     group('operator ==()', () {
       test('compares this EqualTemperament to other', () {
-        // ignore: prefer_const_constructors
+        // ignore: prefer_const_constructors test
         expect(EqualTemperament.edo12(), EqualTemperament.edo12());
         expect(
           const EqualTemperament.edo12(),
@@ -93,9 +93,9 @@ void main() {
     group('.hashCode', () {
       test('returns the same hashCode for equal EqualTemperaments', () {
         expect(
-          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables
+          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables test
           EqualTemperament([1, 2]).hashCode,
-          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables
+          // ignore: prefer_const_constructors, prefer_const_literals_to_create_immutables test
           EqualTemperament([1, 2]).hashCode,
         );
       });