fix(analyzer): Handle multiple docblocks before a statements

Currently we're only handling docblocks that are tied to a statement,
and only consider a single docblock to be tied to any given statement.
This means that having multiple consecutive docblocks to declare
variables, for example in a classic PHP-only template file, will have us
only considering the last of these docblocks. We can improve this by
treating all consecutive docblocks that preceed a given statement, only
separated by whitespace or comments, to apply to that statement.

This uncovered a bug in the docblock_var_on_non_assignment testcase
which actually didn't test what it was supposed to test because the
extra docblock was ignored. With the new behaviour, that test actually
complains that the docblock is redundant because it doesn't narrow the
known type. We can widen the original type and add a call that actually
requires the type-narrowing docblock to be processed.

We can also adjust the test case for issue #801 because we now fully
support the original code.

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 preceeding 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;