fix: add special syntax class for empty ref syntax (#2324)

closes #2319. This pull request refines the language analysis
capabilities by introducing a dedicated syntax class for the standalone
'@' symbol. Previously, this might have been ambiguously handled; now,
it's explicitly recognized as an 'empty' reference.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: Myriad-Dreamin

crates/tinymist-analysis/src/syntax/matcher.rs

@@ -652,6 +652,11 @@ pub enum SyntaxClass<'a> {
         /// `@a:b:|`.
         suffix_colon: bool,
     },
+    /// A `@` text, which can be viewed as references with "empty content"
+    At {
+        /// The node containing the `@` text.
+        node: LinkedNode<'a>,
+    },
     /// A callee expression.
     Callee(LinkedNode<'a>),
     /// An import path expression.
@@ -685,6 +690,7 @@ impl<'a> SyntaxClass<'a> {
             SyntaxClass::VarAccess(cls) => cls.node(),
             SyntaxClass::Label { node, .. }
             | SyntaxClass::Ref { node, .. }
+            | SyntaxClass::At { node, .. }
             | SyntaxClass::Callee(node)
             | SyntaxClass::ImportPath(node)
             | SyntaxClass::IncludePath(node)
@@ -847,10 +853,7 @@ pub fn classify_syntax(node: LinkedNode<'_>, cursor: usize) -> Option<SyntaxClas
         && node.offset() + 1 == cursor
         && node.text().starts_with('@')
     {
-        return Some(SyntaxClass::Ref {
-            node,
-            suffix_colon: false,
-        });
+        return Some(SyntaxClass::At { node });
     }
 
     // todo: check if we can remove Text here
@@ -1150,6 +1153,11 @@ pub enum SyntaxContext<'a> {
         /// `@a:b:|`.
         suffix_colon: bool,
     },
+    /// A cursor on a `@` text.
+    At {
+        /// The node of the `@` text.
+        node: LinkedNode<'a>,
+    },
     /// A cursor on a normal [`SyntaxClass`].
     Normal(LinkedNode<'a>),
 }
@@ -1168,6 +1176,7 @@ impl<'a> SyntaxContext<'a> {
             SyntaxContext::Paren { container, .. } => container.clone(),
             SyntaxContext::Label { node, .. }
             | SyntaxContext::Ref { node, .. }
+            | SyntaxContext::At { node, .. }
             | SyntaxContext::ImportPath(node)
             | SyntaxContext::IncludePath(node)
             | SyntaxContext::Normal(node) => node.clone(),
@@ -1261,6 +1270,9 @@ pub fn classify_context(node: LinkedNode<'_>, cursor: Option<usize>) -> Option<S
         SyntaxClass::Ref { node, suffix_colon } => {
             return Some(SyntaxContext::Ref { node, suffix_colon });
         }
+        SyntaxClass::At { node } => {
+            return Some(SyntaxContext::At { node });
+        }
         SyntaxClass::ImportPath(node) => {
             return Some(SyntaxContext::ImportPath(node));
         }
@@ -1530,6 +1542,7 @@ mod tests {
                 Some(SyntaxClass::Normal(..)) => 'n',
                 Some(SyntaxClass::Label { .. }) => 'l',
                 Some(SyntaxClass::Ref { .. }) => 'r',
+                Some(SyntaxClass::At { .. }) => 'r',
                 Some(SyntaxClass::Callee(..)) => 'c',
                 Some(SyntaxClass::ImportPath(..)) => 'i',
                 Some(SyntaxClass::IncludePath(..)) => 'I',
@@ -1551,6 +1564,7 @@ mod tests {
                 Some(SyntaxContext::IncludePath(..)) => 'I',
                 Some(SyntaxContext::Label { .. }) => 'l',
                 Some(SyntaxContext::Ref { .. }) => 'r',
+                Some(SyntaxContext::At { .. }) => 'r',
                 Some(SyntaxContext::Normal(..)) => 'n',
                 None => ' ',
             }
@@ -1634,15 +1648,11 @@ Text
     }
 
     #[test]
-    fn ref_syntxax() {
+    fn ref_syntax() {
         assert_snapshot!(map_syntax("@ab:"), @r###"
         @ab:
         rrrr
         "###);
-    }
-
-    #[test]
-    fn ref_syntax() {
         assert_snapshot!(map_syntax("@"), @r"
         @
         r
@@ -1651,6 +1661,10 @@ Text
         @;
         r
         ");
+        assert_snapshot!(map_syntax("@ t"), @r"
+        @ t
+        r
+        ");
         assert_snapshot!(map_syntax("@ab"), @r###"
         @ab
         rrr

crates/tinymist-query/src/analysis/completion.rs

@@ -260,6 +260,14 @@ impl<'a> CompletionCursor<'a> {
                 return Some(SelectedNode::Ref(self.leaf.clone()));
             }
 
+            // @identifier
+            //  ^ from
+            let is_from_ref = matches!(self.syntax, Some(SyntaxClass::At { .. }))
+                && self.leaf.offset() + 1 == self.from;
+            if is_from_ref {
+                return Some(SelectedNode::At(self.leaf.clone()));
+            }
+
             None
         })
     }
@@ -287,6 +295,7 @@ impl<'a> CompletionCursor<'a> {
                     | SyntaxContext::Paren { .. }
                     | SyntaxContext::Label { .. }
                     | SyntaxContext::Ref { .. }
+                    | SyntaxContext::At { .. }
                     | SyntaxContext::Normal(..),
                 )
                 | None => {}
@@ -342,8 +351,13 @@ impl<'a> CompletionCursor<'a> {
 
                 self.lsp_range_of(rng)
             }
-            Some(SelectedNode::Ref(from_ref)) => {
-                let mut rng = from_ref.range();
+            Some(node @ (SelectedNode::At(from_ref) | SelectedNode::Ref(from_ref))) => {
+                let mut rng = if matches!(node, SelectedNode::At(..)) {
+                    let offset = from_ref.offset();
+                    offset..offset + 1
+                } else {
+                    from_ref.range()
+                };
                 if from_ref.text().starts_with('@') && !snippet.starts_with('@') {
                     rng.start += 1;
                 }
@@ -382,6 +396,8 @@ enum SelectedNode<'a> {
     Label(LinkedNode<'a>),
     /// Selects a reference, e.g. `@foobar|` or `@foo|bar`.
     Ref(LinkedNode<'a>),
+    /// Selects a `@` text, e.g. `@|`.
+    At(LinkedNode<'a>),
 }
 
 /// Autocomplete a cursor position in a source file.
@@ -522,6 +538,7 @@ impl<'a> CompletionWorker<'a> {
         let _ = pair.complete_cursor();
 
         // Filters
+        // todo: reference filter
         if let Some(SelectedNode::Ident(from_ident)) = cursor.selected_node() {
             let ident_prefix = cursor.text[from_ident.offset()..cursor.cursor].to_string();
 
@@ -641,10 +658,13 @@ impl CompletionPair<'_, '_, '_> {
                 return Some(());
             }
             // todo: complete reference by type
-            Some(SyntaxContext::Ref {
-                node,
-                suffix_colon: _,
-            }) => {
+            Some(
+                SyntaxContext::Ref {
+                    node,
+                    suffix_colon: _,
+                }
+                | SyntaxContext::At { node },
+            ) => {
                 self.cursor.from = node.offset() + 1;
                 self.ref_completions();
                 return Some(());

crates/tinymist-query/src/analysis/definition.rs

@@ -124,6 +124,7 @@ pub fn definition(
             node: _,
             suffix_colon: true,
         }
+        | SyntaxClass::At { node: _ }
         | SyntaxClass::Normal(..) => None,
     }
 }

crates/tinymist-query/src/analysis/post_tyck.rs

@@ -321,6 +321,7 @@ impl<'a> PostTypeChecker<'a> {
             | SyntaxContext::VarAccess(VarClass::DotAccess(node))
             | SyntaxContext::Label { node, .. }
             | SyntaxContext::Ref { node, .. }
+            | SyntaxContext::At { node, .. }
             | SyntaxContext::Normal(node) => {
                 let label_or_ref_ty = match cursor {
                     SyntaxContext::Label { is_error: true, .. } => {

crates/tinymist-query/src/fixtures/completion/ref_empty.typ

@@ -0,0 +1,10 @@
+/// contains:test
+/// compile: true
+
+#set heading(numbering: "1.1")
+
+#heading(numbering: "1.1", level: 1)[Test] <test>
+
+= H <tes>
+
+There is a reference here @ w /* range -3..-2 */

crates/tinymist-query/src/fixtures/completion/snaps/test@ref_empty.typ.snap

@@ -0,0 +1,33 @@
+---
+source: crates/tinymist-query/src/completion.rs
+description: Completion on   (158..159)
+expression: "JsonRepr::new_pure(results)"
+input_file: crates/tinymist-query/src/fixtures/completion/ref_empty.typ
+---
+[
+ {
+  "isIncomplete": false,
+  "items": [
+   {
+    "kind": 18,
+    "label": "test",
+    "labelDetails": {
+     "description": "Test"
+    },
+    "textEdit": {
+     "newText": "test",
+     "range": {
+      "end": {
+       "character": 27,
+       "line": 9
+      },
+      "start": {
+       "character": 27,
+       "line": 9
+      }
+     }
+    }
+   }
+  ]
+ }
+]

crates/tinymist-query/src/references.rs

@@ -54,6 +54,7 @@ pub(crate) fn find_references(
         | SyntaxClass::Ref {
             suffix_colon: true, ..
         }
+        | SyntaxClass::At { node: _ }
         | SyntaxClass::Normal(..) => {
             return None;
         }