fix(linter): narrow annotation spans to highlight minimal code regions

closes #745

Signed-off-by: azjezz <[email protected]>

Author: azjezz

crates/linter/src/rule/correctness/strict_types.rs

@@ -142,12 +142,21 @@ impl LintRule for StrictTypesRule {
         }
 
         if !found {
+            let annotation_span = program
+                .statements
+                .iter()
+                .find_map(|s| match s {
+                    Statement::OpeningTag(tag) => Some(tag.span()),
+                    _ => None,
+                })
+                .unwrap_or_else(|| program.span());
+
             let issue = Issue::new(
                 self.cfg.level(),
                 "Missing `declare(strict_types=1);` statement at the beginning of the file.",
             )
             .with_code(self.meta.code)
-            .with_annotation(Annotation::primary(program.span()))
+            .with_annotation(Annotation::primary(annotation_span))
             .with_note("The `strict_types` directive enforces strict type checking, which can prevent subtle bugs.")
             .with_help("Add `declare(strict_types=1);` at the top of your file.");
 

crates/linter/src/rule/maintainability/too_many_enum_cases.rs

@@ -5,7 +5,6 @@ use serde::Serialize;
 use mago_reporting::Annotation;
 use mago_reporting::Issue;
 use mago_reporting::Level;
-use mago_span::HasSpan;
 use mago_syntax::ast::ClassLikeMember;
 use mago_syntax::ast::Node;
 use mago_syntax::ast::NodeKind;
@@ -15,6 +14,7 @@ use crate::context::LintContext;
 use crate::requirements::RuleRequirements;
 use crate::rule::Config;
 use crate::rule::LintRule;
+use crate::rule::utils::misc::get_class_like_header_span;
 use crate::rule_meta::RuleMeta;
 use crate::settings::RuleSettings;
 
@@ -126,7 +126,7 @@ impl LintRule for TooManyEnumCasesRule {
                 Issue::new(self.cfg.level, "Enum has too many cases.")
                     .with_code(self.meta.code)
                     .with_annotation(
-                        Annotation::primary(r#enum.span()).with_message(format!(
+                        Annotation::primary(get_class_like_header_span(node)).with_message(format!(
                             "Enum has {cases} cases, which exceeds the threshold of {}.",
                             self.cfg.threshold
                         ))

crates/linter/src/rule/maintainability/too_many_methods.rs

@@ -5,14 +5,14 @@ use serde::Serialize;
 use mago_reporting::Annotation;
 use mago_reporting::Issue;
 use mago_reporting::Level;
-use mago_span::HasSpan;
 use mago_syntax::ast::*;
 
 use crate::category::Category;
 use crate::context::LintContext;
 use crate::requirements::RuleRequirements;
 use crate::rule::Config;
 use crate::rule::LintRule;
+use crate::rule::utils::misc::get_class_like_header_span;
 use crate::rule::utils::misc::is_method_setter_or_getter;
 use crate::rule_meta::RuleMeta;
 use crate::settings::RuleSettings;
@@ -150,17 +150,13 @@ impl LintRule for TooManyMethodsRule {
             ctx.collector.report(
                 Issue::new(self.cfg.level, format!("{kind} has too many methods."))
                     .with_code(self.meta.code)
-                    .with_annotation(Annotation::primary(node.span()).with_message(format!(
+                    .with_annotation(Annotation::primary(get_class_like_header_span(node)).with_message(format!(
                         "{kind} has {count} methods, which exceeds the threshold of {}.",
                         self.cfg.threshold
                     )))
                     .with_note("Having a large number of methods can make structures harder to understand and maintain.")
                     .with_help("Try reducing the number of methods, or consider splitting the structure into smaller, more focused structures.")
             );
-
-            // If this structure has too many methods, we don't need to check the nested structures.
-        } else {
-            // Continue checking nested structures, if any.
         }
     }
 }

crates/linter/src/rule/maintainability/too_many_properties.rs

@@ -5,7 +5,6 @@ use serde::Serialize;
 use mago_reporting::Annotation;
 use mago_reporting::Issue;
 use mago_reporting::Level;
-use mago_span::HasSpan;
 use mago_syntax::ast::ClassLikeMember;
 use mago_syntax::ast::Node;
 use mago_syntax::ast::NodeKind;
@@ -16,6 +15,7 @@ use crate::context::LintContext;
 use crate::requirements::RuleRequirements;
 use crate::rule::Config;
 use crate::rule::LintRule;
+use crate::rule::utils::misc::get_class_like_header_span;
 use crate::rule_meta::RuleMeta;
 use crate::settings::RuleSettings;
 
@@ -128,17 +128,13 @@ impl LintRule for TooManyPropertiesRule {
             ctx.collector.report(
                 Issue::new(self.cfg.level, format!("{kind} has too many properties."))
                     .with_code(self.meta.code)
-                    .with_annotation(Annotation::primary(node.span()).with_message(format!(
+                    .with_annotation(Annotation::primary(get_class_like_header_span(node)).with_message(format!(
                         "{kind} has {properties} properties, which exceeds the threshold of {}.",
                         self.cfg.threshold
                     )))
                     .with_note("Having a large number of properties can make classes harder to understand and maintain.")
                     .with_help("Try reducing the number of properties, or consider grouping related properties into a single object.")
             );
-
-            // If this structure has too many props, we don't need to check the nested structures.
-        } else {
-            // Continue checking nested structures, if any.
         }
     }
 }

crates/linter/src/rule/utils/misc.rs

@@ -1,5 +1,23 @@
+use mago_span::HasSpan;
+use mago_span::Span;
 use mago_syntax::ast::*;
 
+/// Returns the minimal span for a class-like node (just keyword + name).
+///
+/// For named classes/traits/enums/interfaces, this returns the span from the keyword to the name.
+/// For anonymous classes, this returns just the `class` keyword span.
+#[inline]
+pub fn get_class_like_header_span(node: Node<'_, '_>) -> Span {
+    match node {
+        Node::Class(class) => class.class.span().join(class.name.span()),
+        Node::Trait(r#trait) => r#trait.r#trait.span().join(r#trait.name.span()),
+        Node::Enum(r#enum) => r#enum.r#enum.span().join(r#enum.name.span()),
+        Node::Interface(interface) => interface.interface.span().join(interface.name.span()),
+        Node::AnonymousClass(class) => class.class.span(),
+        _ => node.span(),
+    }
+}
+
 #[inline]
 pub fn get_single_return_statement<'ast, 'arena>(block: &'ast Block<'arena>) -> Option<&'ast Return<'arena>> {
     let statements = block.statements.as_slice();