Better feedback on incorrect syntax for qubit allocation (#2897)

This adds some additional help messages when code is known to be
incorrectly performing qubit allocation. This addresses the remaining
items from and fixes #331.

<img width="708" height="214" alt="image"
src="https://github.com/user-attachments/assets/b3d55bb0-9dd0-4235-b751-52f7ea204c89"
/>
<img width="708" height="214" alt="image"
src="https://github.com/user-attachments/assets/033008ff-3023-4cd0-b916-1b6ce6e00872"
/>

Author: swernli

source/compiler/qsc_frontend/src/resolve.rs

@@ -213,6 +213,13 @@ pub(super) enum Error {
     #[diagnostic(code("Qsc.Resolve.NotFound"))]
     NotAvailable(String, String, #[label] Span),
 
+    #[error("`Qubit` not found")]
+    #[diagnostic(help(
+        "to allocate qubits, use syntax like `use q = Qubit();` or `use qs = Qubit[N];` or `use (q1, q2) = (Qubit(), Qubit());`"
+    ))]
+    #[diagnostic(code("Qsc.Resolve.NotFoundQubit"))]
+    NotFoundQubit(#[label] Span),
+
     #[error("use of unimplemented item `{0}`")]
     #[diagnostic(help("this item is not implemented and cannot be used"))]
     #[diagnostic(code("Qsc.Resolve.Unimplemented"))]
@@ -772,6 +779,8 @@ impl Resolver {
                             format!("{}.{}", dropped_name.namespace, dropped_name.name),
                             span,
                         ))
+                    } else if name == "Qubit" {
+                        Err(Error::NotFoundQubit(span))
                     } else {
                         Err(Error::NotFound(name, span))
                     }

source/compiler/qsc_frontend/src/resolve/tests.rs

@@ -2341,6 +2341,50 @@ fn resolve_local_generic() {
     );
 }
 
+#[test]
+fn incorrect_single_qubit_allocation_syntax_gets_extra_help() {
+    check(
+        indoc! {"
+            namespace A {
+                operation B() : Unit {
+                    let q = Qubit();
+                }
+            }
+        "},
+        &expect![[r#"
+            namespace namespace3 {
+                operation package2_item1() : Unit {
+                    let local13 = Qubit();
+                }
+            }
+
+            // NotFoundQubit(Span { lo: 57, hi: 62 })
+        "#]],
+    );
+}
+
+#[test]
+fn incorrect_qubit_array_allocation_syntax_gets_extra_help() {
+    check(
+        indoc! {"
+            namespace A {
+                operation B() : Unit {
+                    let q = Qubit[5];
+                }
+            }
+        "},
+        &expect![[r#"
+            namespace namespace3 {
+                operation package2_item1() : Unit {
+                    let local13 = Qubit[5];
+                }
+            }
+
+            // NotFoundQubit(Span { lo: 57, hi: 62 })
+        "#]],
+    );
+}
+
 #[test]
 fn dropped_base_callable_from_unrestricted() {
     check_with_capabilities(

source/compiler/qsc_parse/src/stmt.rs

@@ -154,6 +154,7 @@ fn parse_qubit(s: &mut ParserContext) -> Result<Box<StmtKind>> {
 }
 
 fn parse_qubit_init(s: &mut ParserContext) -> Result<Box<QubitInit>> {
+    let help_text = "to allocate qubits, use syntax like `use q = Qubit();` or `use qs = Qubit[N];` or `use (q1, q2) = (Qubit(), Qubit());`";
     let lo = s.peek().span.lo;
     s.expect(WordKinds::Qubit);
     let kind = if let Ok(name) = ident(s) {
@@ -162,33 +163,32 @@ fn parse_qubit_init(s: &mut ParserContext) -> Result<Box<QubitInit>> {
                 "qubit initializer",
                 "identifier",
                 name.span,
-            )));
+            ))
+            .with_help(help_text));
         } else if token(s, TokenKind::Open(Delim::Paren)).is_ok() {
-            token(s, TokenKind::Close(Delim::Paren))?;
+            token(s, TokenKind::Close(Delim::Paren)).map_err(|e| e.with_help(help_text))?;
             QubitInitKind::Single
         } else if token(s, TokenKind::Open(Delim::Bracket)).is_ok() {
-            let size = expr(s)?;
-            token(s, TokenKind::Close(Delim::Bracket))?;
+            let size = expr(s).map_err(|e| e.with_help(help_text))?;
+            token(s, TokenKind::Close(Delim::Bracket)).map_err(|e| e.with_help(help_text))?;
             QubitInitKind::Array(size)
         } else {
             let token = s.peek();
-            return Err(Error::new(ErrorKind::Rule(
-                "qubit suffix",
-                token.kind,
-                token.span,
-            )));
+            return Err(
+                Error::new(ErrorKind::Rule("qubit suffix", token.kind, token.span))
+                    .with_help(help_text),
+            );
         }
     } else if token(s, TokenKind::Open(Delim::Paren)).is_ok() {
-        let (inits, final_sep) = seq(s, parse_qubit_init)?;
-        token(s, TokenKind::Close(Delim::Paren))?;
+        let (inits, final_sep) = seq(s, parse_qubit_init).map_err(|e| e.with_help(help_text))?;
+        token(s, TokenKind::Close(Delim::Paren)).map_err(|e| e.with_help(help_text))?;
         final_sep.reify(inits, QubitInitKind::Paren, QubitInitKind::Tuple)
     } else {
         let token = s.peek();
-        return Err(Error::new(ErrorKind::Rule(
-            "qubit initializer",
-            token.kind,
-            token.span,
-        )));
+        return Err(
+            Error::new(ErrorKind::Rule("qubit initializer", token.kind, token.span))
+                .with_help(help_text),
+        );
     };
 
     Ok(Box::new(QubitInit {

source/compiler/qsc_parse/src/stmt/tests.rs

@@ -144,6 +144,9 @@ fn use_invalid_init() {
                         hi: 14,
                     },
                 ),
+                Some(
+                    "to allocate qubits, use syntax like `use q = Qubit();` or `use qs = Qubit[N];` or `use (q1, q2) = (Qubit(), Qubit());`",
+                ),
             )
         "#]],
     );