fix(analyzer): Handle multiple docblocks before a statements (#818)

Author: dotdash

crates/analyzer/src/context/mod.rs

@@ -5,7 +5,7 @@ use mago_codex::metadata::CodebaseMetadata;
 use mago_codex::ttype::resolution::TypeResolutionContext;
 use mago_collector::Collector;
 use mago_database::file::File;
-use mago_docblock::document::Document;
+use mago_docblock::document::Element;
 use mago_names::ResolvedNames;
 use mago_names::scope::NamespaceScope;
 use mago_reporting::Annotation;
@@ -137,46 +137,44 @@ impl<'ctx, 'arena> Context<'ctx, 'arena> {
         }
     }
 
-    pub fn get_docblock(&self) -> Option<&'arena Trivia<'arena>> {
-        comments::docblock::get_docblock_before_position(
-            self.source_file,
-            self.comments,
-            self.statement_span.start.offset,
-        )
-    }
-
-    pub fn get_parsed_docblock(&mut self) -> Option<Document<'arena>> {
-        let trivia = self.get_docblock()?;
-
-        match mago_docblock::parse_trivia(self.arena, trivia) {
-            Ok(document) => Some(document),
-            Err(error) => {
-                let error_span = error.span();
+    pub fn get_parsed_docblocks(&mut self) -> Vec<Element<'arena>> {
+        let mut elements = vec![];
+        let mut start = self.statement_span.start.offset;
+        while let Some(trivia) =
+            comments::docblock::get_docblock_before_position(self.source_file, self.comments, start)
+        {
+            match mago_docblock::parse_trivia(self.arena, trivia) {
+                Ok(document) => elements.extend(document.elements),
+                Err(error) => {
+                    let error_span = error.span();
+
+                    let mut issue = Issue::error(error.to_string())
+                        .with_annotation(
+                            Annotation::primary(error_span)
+                                .with_message("This part of the docblock has a syntax error"),
+                        )
+                        .with_note(error.note());
+
+                    if trivia.span != error_span {
+                        issue = issue.with_annotation(
+                            Annotation::secondary(trivia.span).with_message("The error is within this docblock"),
+                        );
+                    }
 
-                let mut issue = Issue::error(error.to_string())
-                    .with_annotation(
-                        Annotation::primary(error_span).with_message("This part of the docblock has a syntax error"),
-                    )
-                    .with_note(error.note());
-
-                if trivia.span != error_span {
                     issue = issue.with_annotation(
-                        Annotation::secondary(trivia.span).with_message("The error is within this docblock"),
+                        Annotation::secondary(self.statement_span)
+                            .with_message("This docblock is associated with the following statement"),
                     );
-                }
 
-                issue = issue.with_annotation(
-                    Annotation::secondary(self.statement_span)
-                        .with_message("This docblock is associated with the following statement"),
-                );
+                    issue = issue.with_help(error.help());
 
-                issue = issue.with_help(error.help());
-
-                self.collector.report_with_code(IssueCode::InvalidDocblock, issue);
-
-                None
+                    self.collector.report_with_code(IssueCode::InvalidDocblock, issue);
+                }
             }
+            start = trivia.span.start.offset;
         }
+
+        elements
     }
 
     pub fn record<T>(&mut self, callback: impl FnOnce(&mut Context<'ctx, 'arena>) -> T) -> (T, IssueCollection) {

crates/analyzer/src/utils/docblock.rs

@@ -75,10 +75,10 @@ pub fn populate_docblock_variables_excluding<'ctx>(
     }
 }
 
-/// Retrieves all `@var`, `@psalm-var`, and `@phpstan-var` tags from the docblock of the
+/// Retrieves all `@var`, `@psalm-var`, and `@phpstan-var` tags from the docblocks preceding the
 /// current statement in the context, parsing their variable types.
 ///
-/// This function scans the docblock associated with the current statement in the context,
+/// This function scans the docblocks associated with the current statement in the context,
 /// extracting all variable type declarations. It returns a vector of tuples, each containing:
 ///
 /// - An optional variable name (if specified in the tag)
@@ -104,11 +104,7 @@ pub fn get_docblock_variables<'ctx>(
     artifacts: &mut AnalysisArtifacts,
     allow_tracing: bool,
 ) -> Vec<(Option<mago_atom::Atom>, TUnion, Span)> {
-    let Some(elements) = context.get_parsed_docblock().map(|document| document.elements) else {
-        return vec![];
-    };
-
-    elements
+    context.get_parsed_docblocks()
         .into_iter()
         // Filter out non-tag elements
         .filter_map(|element| match element {

crates/analyzer/tests/cases/docblock_var_on_non_assignment.php

@@ -18,11 +18,16 @@
 }
 
 // Also test with multiple @var annotations
-/** @var array<string, object> $map */
+/** @var array<int|string, object> $map */
 $map = ['key' => new DateTime()];
 
+function want_string(string $x): string {
+  return $x;
+}
+
 foreach ($map as $key => $value) {
     /** @var string $key */
     /** @var DateTime $value */
     $result = $value->format('Y-m-d');
+    want_string($key);
 }

crates/analyzer/tests/cases/issue_801.php

@@ -22,11 +22,9 @@ public function __construct()
     }
 }
 
-/**
- * @var Config $config
- * @var Session $session
- */
+/** @var Config $config */
+/** @var Session $session */
 if (!$session->isLoggedIn()) {
 }
 
-echo $config->site_name;
+echo $config->site_name;