Fix incorrectly finding definitions in comments

Author: AJenbo

example.php

@@ -360,6 +360,38 @@ function handleIntersection(User&Loggable $entity): void {
 echo $typed;                              // Ctrl+Click on $typed → jumps to assignment
 
 
+// ── Type Hint Go-to-Definition ──────────────────────────────────────────────
+// Ctrl+Click on any class/interface name used as a type hint — in parameters,
+// return types, property types, catch blocks, and even inside docblock
+// annotations — to jump to its definition.
+
+// Parameter type hints (simple, nullable, union, intersection):
+function typeHintGtdParam(User $u): void {}                       // Ctrl+Click User
+function typeHintGtdNullable(?User $u): void {}                   // Ctrl+Click User after ?
+function typeHintGtdUnion(User|AdminUser $u): void {}             // Ctrl+Click either type
+function typeHintGtdIntersection(Renderable&Loggable $x): void {} // Ctrl+Click either type
+
+// Return type hints:
+function typeHintGtdReturn(): Response { return new Response(200); } // Ctrl+Click Response
+
+// Catch block exception types — Ctrl+Click NotFoundException or ValidationException:
+try { typeHintGtdParam(new User('', '')); } catch (NotFoundException|ValidationException $e) {}
+
+// Extends / implements — Ctrl+Click User, Renderable, or Loggable in scaffolding below.
+
+// Docblock type references — Ctrl+Click class names inside these annotations:
+/**
+ * @param TypedCollection<int, User> $items   Ctrl+Click User or TypedCollection
+ * @return Response                           Ctrl+Click Response
+ * @throws NotFoundException                  Ctrl+Click NotFoundException
+ */
+function typeHintGtdDocblock($items) { return new Response(200); }
+
+/** @var User $docblockVar */
+$docblockVar = getUnknownValue();
+$docblockVar->getEmail();                 // Ctrl+Click User in the @var above
+
+
 // ── Callable Snippet Insertion ──────────────────────────────────────────────
 // Completion inserts snippets with tab-stops for required params:
 

src/definition/resolve.rs

@@ -699,24 +699,87 @@ impl Backend {
     pub fn find_definition_position(content: &str, class_name: &str) -> Option<Position> {
         let keywords = ["class", "interface", "trait", "enum"];
 
+        // Track whether we are inside a `/* … */` block comment.
+        let mut in_block_comment = false;
+
         for (line_idx, line) in content.lines().enumerate() {
+            // ── Block-comment tracking ──────────────────────────────────
+            // Walk through the line handling `/*` and `*/` toggles so we
+            // know whether the keyword match is inside a comment.
+            let mut effective_line = String::new();
+            let line_bytes = line.as_bytes();
+            let mut i = 0;
+            while i < line_bytes.len() {
+                if in_block_comment {
+                    // Look for closing `*/`.
+                    if i + 1 < line_bytes.len()
+                        && line_bytes[i] == b'*'
+                        && line_bytes[i + 1] == b'/'
+                    {
+                        in_block_comment = false;
+                        // Replace the `*/` with spaces to preserve column offsets.
+                        effective_line.push(' ');
+                        effective_line.push(' ');
+                        i += 2;
+                    } else {
+                        effective_line.push(' ');
+                        i += 1;
+                    }
+                } else if i + 1 < line_bytes.len()
+                    && line_bytes[i] == b'/'
+                    && line_bytes[i + 1] == b'*'
+                {
+                    // Opening `/*` — rest of line (until `*/`) is a comment.
+                    in_block_comment = true;
+                    effective_line.push(' ');
+                    effective_line.push(' ');
+                    i += 2;
+                } else if i + 1 < line_bytes.len()
+                    && line_bytes[i] == b'/'
+                    && line_bytes[i + 1] == b'/'
+                {
+                    // Line comment `//` — blank out the rest of the line.
+                    while i < line_bytes.len() {
+                        effective_line.push(' ');
+                        i += 1;
+                    }
+                } else if line_bytes[i] == b'#' {
+                    // Line comment `#` — blank out the rest of the line.
+                    while i < line_bytes.len() {
+                        effective_line.push(' ');
+                        i += 1;
+                    }
+                } else {
+                    effective_line.push(line_bytes[i] as char);
+                    i += 1;
+                }
+            }
+
             for keyword in &keywords {
                 // Search for `keyword ClassName` making sure ClassName is
                 // followed by a word boundary (whitespace, `{`, `:`, end of
                 // line) so we don't match partial names.
                 let pattern = format!("{} {}", keyword, class_name);
-                if let Some(col) = line.find(&pattern) {
+                if let Some(col) = effective_line.find(&pattern) {
                     // Verify word boundary before the keyword: either start
                     // of line or preceded by whitespace / non-alphanumeric.
                     let before_ok = col == 0 || {
-                        let prev = line.as_bytes().get(col - 1).copied().unwrap_or(b' ');
+                        let prev = effective_line
+                            .as_bytes()
+                            .get(col - 1)
+                            .copied()
+                            .unwrap_or(b' ');
                         !(prev as char).is_alphanumeric() && prev != b'_'
                     };
 
                     // Verify word boundary after the class name.
                     let after_pos = col + pattern.len();
-                    let after_ok = after_pos >= line.len() || {
-                        let next = line.as_bytes().get(after_pos).copied().unwrap_or(b' ');
+                    let after_ok = after_pos >= effective_line.len() || {
+                        let next = effective_line
+                            .as_bytes()
+                            .get(after_pos)
+                            .copied()
+                            .unwrap_or(b' ');
                         !(next as char).is_alphanumeric() && next != b'_'
                     };
 

tests/definition_helpers.rs

@@ -256,6 +256,116 @@ fn test_find_definition_position_no_partial_match() {
     assert!(pos.is_none());
 }
 
+#[test]
+fn test_find_definition_position_skips_line_comment() {
+    let content = concat!(
+        "<?php\n",
+        "// class AdminUser extends Model\n",
+        "\n",
+        "class AdminUser {\n",
+        "}\n",
+    );
+    let pos = Backend::find_definition_position(content, "AdminUser");
+    assert!(pos.is_some());
+    let pos = pos.unwrap();
+    assert_eq!(pos.line, 3, "Should skip the commented-out class on line 1");
+    assert_eq!(pos.character, 0);
+}
+
+#[test]
+fn test_find_definition_position_skips_hash_comment() {
+    let content = concat!(
+        "<?php\n",
+        "# class Foo extends Bar\n",
+        "\n",
+        "class Foo {\n",
+        "}\n",
+    );
+    let pos = Backend::find_definition_position(content, "Foo");
+    assert!(pos.is_some());
+    assert_eq!(
+        pos.unwrap().line,
+        3,
+        "Should skip the #-commented class on line 1"
+    );
+}
+
+#[test]
+fn test_find_definition_position_skips_block_comment() {
+    let content = concat!(
+        "<?php\n",
+        "/* class Widget {} */\n",
+        "\n",
+        "class Widget {\n",
+        "}\n",
+    );
+    let pos = Backend::find_definition_position(content, "Widget");
+    assert!(pos.is_some());
+    assert_eq!(
+        pos.unwrap().line,
+        3,
+        "Should skip the block-commented class on line 1"
+    );
+}
+
+#[test]
+fn test_find_definition_position_skips_multiline_block_comment() {
+    let content = concat!(
+        "<?php\n",
+        "/*\n",
+        " * class Order extends Model\n",
+        " */\n",
+        "\n",
+        "class Order {\n",
+        "}\n",
+    );
+    let pos = Backend::find_definition_position(content, "Order");
+    assert!(pos.is_some());
+    assert_eq!(pos.unwrap().line, 5, "Should skip multi-line block comment");
+}
+
+#[test]
+fn test_find_definition_position_skips_docblock() {
+    let content = concat!(
+        "<?php\n",
+        "/**\n",
+        " * class Response extends BaseResponse\n",
+        " */\n",
+        "\n",
+        "class Response {\n",
+        "}\n",
+    );
+    let pos = Backend::find_definition_position(content, "Response");
+    assert!(pos.is_some());
+    assert_eq!(pos.unwrap().line, 5, "Should skip docblock comment");
+}
+
+#[test]
+fn test_find_definition_position_inline_comment_after_code() {
+    // The class declaration is real code; the comment is after it.
+    let content = concat!("<?php\n", "class Config { // class Settings\n", "}\n",);
+    let pos = Backend::find_definition_position(content, "Config");
+    assert!(pos.is_some());
+    assert_eq!(pos.unwrap().line, 1);
+
+    // "Settings" appears only inside the comment — should not match.
+    let pos2 = Backend::find_definition_position(content, "Settings");
+    assert!(
+        pos2.is_none(),
+        "Should not match class name inside trailing comment"
+    );
+}
+
+#[test]
+fn test_find_definition_position_only_in_comment_returns_none() {
+    let content = concat!("<?php\n", "// class Ghost extends Model\n",);
+    let pos = Backend::find_definition_position(content, "Ghost");
+    assert!(
+        pos.is_none(),
+        "Should return None when class only exists in a comment"
+    );
+}
+
 #[test]
 fn test_find_definition_position_with_namespace() {
     let content = concat!(