Make unused query captures errors

src/checker.rs

···
     UndefinedSyntaxCapture(String, Location),
     #[error("Undefined variable {0} at {1}")]
     UndefinedVariable(String, Location),
+    #[error("Unused capture(s) {0} at {1}. Remove or prefix with _.")]
+    UnusedCaptures(String, Location),
     #[error("{0}: {1} at {2}")]
     Variable(VariableError, String, Location),
 }
···
             CheckError::NullableRegex(_, location) => *location,
             CheckError::UndefinedSyntaxCapture(_, location) => *location,
             CheckError::UndefinedVariable(_, location) => *location,
+            CheckError::UnusedCaptures(_, location) => *location,
             CheckError::Variable(_, _, location) => *location,
         };
         writeln!(f, "{}", self.error)?;
···
             ctx.file_query
                 .capture_index_for_name(FULL_MATCH)
                 .expect("missing capture index for full match") as usize;
+
+        let mut used_captures = HashSet::new();
         for statement in &mut self.statements {
-            statement.check(&mut ctx)?;
+            let stmt_result = statement.check(&mut ctx)?;
+            used_captures.extend(stmt_result.used_captures);
+        }
+
+        let all_captures = self
+            .query
+            .capture_names()
+            .into_iter()
+            .filter(|cn| {
+                self.query
+                    .capture_index_for_name(cn)
+                    .expect("capture should have index")
+                    != self.full_match_stanza_capture_index as u32
+            })
+            .map(|cn| Identifier::from(cn.as_str()))
+            .collect::<HashSet<_>>();
+        let unused_captures = all_captures
+            .difference(&used_captures)
+            .filter(|i| !i.starts_with("_"))
+            .map(|i| format!("@{}", i))
+            .collect::<Vec<_>>();
+        if !unused_captures.is_empty() {
+            return Err(CheckError::UnusedCaptures(
+                unused_captures.join(" "),
+                self.location,
+            ));
         }
+
         Ok(())
     }
 }
···
 
 impl ast::DeclareImmutable {
     fn check(&mut self, ctx: &mut CheckContext) -> Result<StatementResult, CheckError> {
+        let mut used_captures = HashSet::new();
         let value = self.value.check(ctx)?;
-        let used_captures = value.used_captures.clone();
-        self.variable.check_add(ctx, value, false)?;
+        used_captures.extend(value.used_captures.iter().cloned());
+        let var_result = self.variable.check_add(ctx, value, false)?;
+        used_captures.extend(var_result.used_captures);
         Ok(StatementResult { used_captures })
     }
 }
 
 impl ast::DeclareMutable {
     fn check(&mut self, ctx: &mut CheckContext) -> Result<StatementResult, CheckError> {
+        let mut used_captures = HashSet::new();
         let value = self.value.check(ctx)?;
-        let used_captures = value.used_captures.clone();
-        self.variable.check_add(ctx, value, true)?;
+        used_captures.extend(value.used_captures.iter().cloned());
+        let var_result = self.variable.check_add(ctx, value, true)?;
+        used_captures.extend(var_result.used_captures);
         Ok(StatementResult { used_captures })
     }
 }
 
 impl ast::Assign {
     fn check(&mut self, ctx: &mut CheckContext) -> Result<StatementResult, CheckError> {
+        let mut used_captures = HashSet::new();
         let value = self.value.check(ctx)?;
-        let used_captures = value.used_captures.clone();
-        self.variable.check_set(ctx, value)?;
+        used_captures.extend(value.used_captures.iter().cloned());
+        let var_result = self.variable.check_set(ctx, value)?;
+        used_captures.extend(var_result.used_captures);
         Ok(StatementResult { used_captures })
     }
 }
 
 impl ast::CreateGraphNode {
     fn check(&mut self, ctx: &mut CheckContext) -> Result<StatementResult, CheckError> {
-        self.node.check_add(
+        let node_result = self.node.check_add(
             ctx,
             ExpressionResult {
                 is_local: true,
···
             false,
         )?;
         Ok(StatementResult {
-            used_captures: HashSet::default(),
+            used_captures: node_result.used_captures,
         })
     }
 }
···
             stanza_query: ctx.stanza_query,
             locals: &mut loop_locals,
         };
-        self.variable
+        let var_result = self
+            .variable
             .check_add(&mut loop_ctx, value_result, false)?;
+        used_captures.extend(var_result.used_captures);
+
         for statement in &mut self.statements {
             let stmt_result = statement.check(&mut loop_ctx)?;
             used_captures.extend(stmt_result.used_captures);
···
             stanza_query: ctx.stanza_query,
             locals: &mut loop_locals,
         };
-        self.variable
+        let var_result = self
+            .variable
             .check_add(&mut loop_ctx, value_result, false)?;
+        used_captures.extend(var_result.used_captures);
 
         let element_result = self.element.check(&mut loop_ctx)?;
         used_captures.extend(element_result.used_captures);
···
             stanza_query: ctx.stanza_query,
             locals: &mut loop_locals,
         };
-        self.variable
+        let var_result = self
+            .variable
             .check_add(&mut loop_ctx, value_result, false)?;
+        used_captures.extend(var_result.used_captures);
 
         let element_result = self.element.check(&mut loop_ctx)?;
         used_captures.extend(element_result.used_captures);
···
 //-----------------------------------------------------------------------------
 // Variables
 
+#[derive(Clone, Debug)]
+struct VariableResult {
+    used_captures: HashSet<Identifier>,
+}
+
 impl ast::Variable {
     fn check_add(
         &mut self,
         ctx: &mut CheckContext,
         value: ExpressionResult,
         mutable: bool,
-    ) -> Result<(), CheckError> {
+    ) -> Result<VariableResult, CheckError> {
         match self {
             Self::Unscoped(v) => v.check_add(ctx, value, mutable),
             Self::Scoped(v) => v.check_add(ctx, value, mutable),
···
         &mut self,
         ctx: &mut CheckContext,
         value: ExpressionResult,
-    ) -> Result<(), CheckError> {
+    ) -> Result<VariableResult, CheckError> {
         match self {
             Self::Unscoped(v) => v.check_set(ctx, value),
             Self::Scoped(v) => v.check_set(ctx, value),
···
         ctx: &mut CheckContext,
         value: ExpressionResult,
         mutable: bool,
-    ) -> Result<(), CheckError> {
+    ) -> Result<VariableResult, CheckError> {
         if ctx.globals.get(&self.name).is_some() {
             return Err(CheckError::CannotHideGlobalVariable(
                 self.name.as_str().to_string(),
···
         if mutable {
             value.is_local = false;
         }
+        let used_captures = value.used_captures.clone();
+        value.used_captures.clear(); // prevent used captures from escaping
+                                     // we may want to separate quantifier/is_local from
+                                     // the used_captures and only store the former in the
+                                     // future for a cleaner solution
         ctx.locals
             .add(self.name.clone(), value, mutable)
-            .map_err(|e| CheckError::Variable(e, format!("{}", self.name), self.location))
+            .map_err(|e| CheckError::Variable(e, format!("{}", self.name), self.location))?;
+        Ok(VariableResult { used_captures })
     }
 
     fn check_set(
         &mut self,
         ctx: &mut CheckContext,
         value: ExpressionResult,
-    ) -> Result<(), CheckError> {
+    ) -> Result<VariableResult, CheckError> {
         if ctx.globals.get(&self.name).is_some() {
             return Err(CheckError::CannotSetGlobalVariable(
                 self.name.as_str().to_string(),
···
         // Since we process all statement in order, we don't have info on later
         // assignments, and can assume non-local to be sound.
         value.is_local = false;
+        let used_captures = value.used_captures.clone();
+        value.used_captures.clear(); // prevent used captures from escaping
+                                     // we may want to separate quantifier/is_local from
+                                     // the used_captures and only store the former in the
+                                     // future for a cleaner solution
         ctx.locals
             .set(self.name.clone(), value)
-            .map_err(|e| CheckError::Variable(e, format!("{}", self.name), self.location))
+            .map_err(|e| CheckError::Variable(e, format!("{}", self.name), self.location))?;
+        Ok(VariableResult { used_captures })
     }
 
     fn check_get(&mut self, ctx: &mut CheckContext) -> Result<ExpressionResult, CheckError> {
···
         ctx: &mut CheckContext,
         _value: ExpressionResult,
         _mutable: bool,
-    ) -> Result<(), CheckError> {
-        self.scope.check(ctx)?;
-        Ok(())
+    ) -> Result<VariableResult, CheckError> {
+        let scope_result = self.scope.check(ctx)?;
+        Ok(VariableResult {
+            used_captures: scope_result.used_captures,
+        })
     }
 
     fn check_set(
         &mut self,
         ctx: &mut CheckContext,
         _value: ExpressionResult,
-    ) -> Result<(), CheckError> {
-        self.scope.check(ctx)?;
-        Ok(())
+    ) -> Result<VariableResult, CheckError> {
+        let scope_result = self.scope.check(ctx)?;
+        Ok(VariableResult {
+            used_captures: scope_result.used_captures,
+        })
     }
 
     fn check_get(&mut self, ctx: &mut CheckContext) -> Result<ExpressionResult, CheckError> {
-        self.scope.check(ctx)?;
+        let scope_result = self.scope.check(ctx)?;
         Ok(ExpressionResult {
             is_local: false,
             quantifier: One, // FIXME we don't really know
-            used_captures: HashSet::new(),
+            used_captures: scope_result.used_captures,
         })
     }
 }

src/reference/mod.rs

···
 //! example stanza, whose query is `(identifier) @id`, `@id` would refer to the `identifier` syntax
 //! node that the stanza matched against.
 //!
+//! Unused query captures are considered errors, unless they start with an underscode. For example,
+//! a capture `@id` must be used within the stanza, but `@_id` does not.
+//!
 //! # Variables
 //!
 //! You can use variables to pass information between different stanzas and statements in a graph

tests/it/execution.rs

···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var new_node = #null
             var current_node = (node)
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var current_node = (node)
 
···
         indoc! {r#"
           global filename
 
-          (module) @root
+          (module)
           {
             node n
             attr (n) filename = filename
···
         indoc! {r#"
           global pkgname = ""
 
-          (module) @root
+          (module)
           {
             node n
             attr (n) pkgname = pkgname
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             let x = (node)
             let y = x
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node node0
             attr (node0) val = (replace "accacc" (replace "abc" "b" "c") (replace "abc" "a" "b"))
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             scan "abc" {
               "^\\b" {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             node node0
             if some @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x) @root
+          (module (import_statement)? @x)
           {
             node node0
             if none @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x (pass_statement)? @y) @root
+          (module (import_statement)? @x (pass_statement)? @y)
           {
             node node0
             if none @x, some @y {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x (pass_statement)? @y) @root
+          (module (import_statement)? @x (pass_statement)? @y)
           {
             node node0
             if some @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x) @root
+          (module (import_statement)? @x)
           {
             node node0
             if some @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x) @root
+          (module (import_statement)?)
           {
             node node0
             if #true {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x (import_statement)? @y) @root
+          (module (import_statement)? @x (import_statement)? @y)
           {
             node node0
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             let n = 1
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             var n = 1
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             var n = 1
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             var n = 0
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (import_statement)* @xs) @root
+          (module (import_statement)* @xs)
           {
             var n = 0
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var n = 0
             for x in [#null, #null, #null] {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             let n = 1
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             var n = 1
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)+ @xs) @root
+          (module (pass_statement)+ @xs)
           {
             var n = 0
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             node node0
             attr (node0) val = [ (named-child-index x) for x in @xs ]
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             node node0
             attr (node0) val = { (source-text x) for x in @xs }

tests/it/functions.rs

···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) eq = (eq #true #true)
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) eq = (eq #true #false)
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) eq = (eq #true "false")
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (format "{} : {{ {} }}" "foo" #null)
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (format "{} : {{ {} }}" "foo")
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (format "{} : {{ {} }}" "foo" #null 42)
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (format "{} : { {} }}" "foo" #null)
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (format "{} : {{ {} }" "foo" #null)
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) xs = (concat [1, 2] [] [3, 4, 5])
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (join [1, 2, 3] ".")
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
             attr (n) str = (join [1, 2, 3])

tests/it/lazy_execution.rs

···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var new_node = #null
             var current_node = (node)
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var current_node = (node)
 
···
         indoc! {r#"
           global filename
 
-          (module) @root
+          (module)
           {
             node n
             attr (n) filename = filename
···
         indoc! {r#"
           global pkgname = ""
 
-          (module) @root
+          (module)
           {
             node n
             attr (n) pkgname = pkgname
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             let x = (node)
             let y = x
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node node0
             attr (node0) val = (replace "accacc" (replace "abc" "b" "c") (replace "abc" "a" "b"))
···
     fail_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             scan "abc" {
               "^\\b" {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             node node0
             if some @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x) @root
+          (module (import_statement)? @x)
           {
             node node0
             if none @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x (pass_statement)? @y) @root
+          (module (import_statement)? @x (pass_statement)? @y)
           {
             node node0
             if none @x, some @y {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x (pass_statement)? @y) @root
+          (module (import_statement)? @x (pass_statement)? @y)
           {
             node node0
             if some @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x) @root
+          (module (import_statement)? @x)
           {
             node node0
             if some @x {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x) @root
+          (module (import_statement)?)
           {
             node node0
             if #true {
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module (import_statement)? @x (import_statement)? @y) @root
+          (module (import_statement)? @x (import_statement)? @y)
           {
             node node0
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             let n = 1
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             var n = 1
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)? @x) @root
+          (module (pass_statement)? @x)
           {
             var n = 1
             if some @x {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             var n = 0
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (import_statement)* @xs) @root
+          (module (import_statement)* @xs)
           {
             var n = 0
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var n = 0
             for x in [#null, #null, #null] {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             let n = 1
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             var n = 1
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)+ @xs) @root
+          (module (pass_statement)+ @xs)
           {
             var n = 0
             for x in @xs {
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             node node0
             attr (node0) val = [ (named-child-index x) for x in @xs ]
···
           pass
         "#,
         indoc! {r#"
-          (module (pass_statement)* @xs) @root
+          (module (pass_statement)* @xs)
           {
             node node0
             attr (node0) val = { (source-text x) for x in @xs }
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node node0
           }
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node node0
             node node1
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node node0
             node node1
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var node = #null
 
···
           print(a.d.f)
         "#},
         indoc! {r#"
-          (call function:(_)@fun arguments: (argument_list (_)@arg)) {
+          (call function:(_) arguments: (argument_list (_)@arg)) {
           ; let @arg.no_object.lala = 3 ; error
             let @arg.object.lala = 3
             let @arg.object.object.lala = 12
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
 
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
 
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
 
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
 
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             node n
 
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var x = 0
             var y = 0
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var x = 0
             var y = 0
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var x = 0
 
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var x = 0
             var y = 0
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             let x = (node)
             attr ((node)) ref = x
···
     check_execution(
         "pass",
         indoc! {r#"
-          (module) @root
+          (module)
           {
             var x = #null
             set x = (node)

tests/it/parser.rs

···
 fn can_parse_blocks() {
     let source = r#"
         (function_definition
-          name: (identifier) @cap1) @cap2
+          name: (identifier) @_cap1) @cap2
         {
           node loc1
           node @cap2.prop1
···
 #[test]
 fn can_parse_list_comprehension() {
     let source = r#"
-        (module (_)* @xs)@mod
+        (module (_)* @xs)
         {
           print [ (named-child-index x) for x in @xs ]
         }
···
 #[test]
 fn can_parse_set_comprehension() {
     let source = r#"
-        (module (_)* @xs)@mod
+        (module (_)* @xs)
         {
           print { (named-child-index x) for x in @xs }
         }
···
     assert_eq!(err.column, 13, "expected column 13, got {}", err.column);
     assert_eq!(err.offset, 112, "expected offset 112, got {}", err.offset);
 }
+
+#[test]
+fn cannot_parse_unused_capture() {
+    let source = r#"
+        (function_definition name: (identifier) @name) {
+        }
+    "#;
+    if let Ok(_) = File::from_str(tree_sitter_python::language(), source) {
+        panic!("Parse succeeded unexpectedly");
+    }
+}
+
+#[test]
+fn can_parse_explicitly_unused_capture() {
+    let source = r#"
+        (function_definition name: (identifier) @_name) {
+        }
+    "#;
+    File::from_str(tree_sitter_python::language(), source).expect("parse to succeed");
+}