From 43690c8be4354f80a0516e75ba1cc5871f391ed3 Mon Sep 17 00:00:00 2001
From: Pokey Rule <755842+pokey@users.noreply.github.com>
Date: Fri, 16 Jun 2023 16:13:44 +0100
Subject: [PATCH] Add almost testable comments to `.scm` files

---
 queries/javascript.core.scm     | 33 +++++++++++++++++++++
 queries/javascript.function.scm | 52 ++++++++++++++++-----------------
 queries/javascript.jsx.scm      | 28 +++++++++++++++++-
 queries/javascript.scm          | 15 ++++++----
 queries/typescript.scm          | 29 ++++++++++++------
 5 files changed, 116 insertions(+), 41 deletions(-)

diff --git a/queries/javascript.core.scm b/queries/javascript.core.scm
index 864fd57af9..18da580d60 100644
--- a/queries/javascript.core.scm
+++ b/queries/javascript.core.scm
@@ -1,10 +1,13 @@
 ;; import javascript.function.scm
 
+;; `name` scope without `export`
 (
   (_
       name: (_) @name
   ) @_.domain
   (#not-parent-type? @_.domain export_statement)
+
+  ;; We have special cases for these defined elsewhere
   (#not-type?
       @_.domain
       variable_declarator
@@ -14,20 +17,33 @@
       field_definition
   )
 )
+
+;; `name` scope with `export`
 (export_statement
   (_
       name: (_) @name
   ) @dummy
+
+  ;; We have a special case for this one.  Note we don't need to list the other
+  ;; special cases from above because they can't be exported
   (#not-type? @dummy variable_declarator)
 ) @_.domain
 
+;; Special cases for `(let | const | var) foo = ...;` because the full statement
+;; is actually a grandparent of the `name` node, so we want the domain to include
+;; this full grandparent statement.
 (
   [
+    ;;!! (const | let) foo = ...;
+    ;;!  --------------^^^-------
     (lexical_declaration
       (variable_declarator
           name: (_) @name
       )
     )
+
+    ;;!! var foo = ...;
+    ;;!  ----^^^-------
     ;; Note that we can't merge this with the variable declaration above because
     ;; of https://github.com/tree-sitter/tree-sitter/issues/1442#issuecomment-1584628651
     (variable_declaration
@@ -37,24 +53,38 @@
     )
   ] @_.domain
   (#not-parent-type? @_.domain export_statement)
+
+  ;; Handle multiple variable declarators in one statement, eg
+  ;;!! (let | const | var) aaa = ..., ccc = ...;
+  ;;!  --------------------^^^--------^^^-------
   (#allow-multiple! @name)
 )
 
 (
   (export_statement
     (_
+      ;;!! export [default] (let | const | var) foo = ...;
+      ;;!  -------------------------------------^^^-------
       (variable_declarator
           name: (_) @name
       )
     )
   ) @_.domain
+
+  ;; Handle multiple variable declarators in one statement, eg
+  ;;!! var foo = ..., bar = ...;
+  ;;!  ----^^^--------^^^-------
   (#allow-multiple! @name)
 )
 
+;;!! foo += ...;
+;;!  ^^^--------
 (augmented_assignment_expression
     left: (_) @name
 ) @_.domain
 
+;;!! foo = ...;
+;;!  ^^^-------
 (assignment_expression
     left: (_) @name
 ) @_.domain
@@ -64,6 +94,9 @@
   (formal_parameters)
 ] @name.iteration
 
+;; Treat interior of all bodies as iteration scopes for `name`, eg
+;;!! function foo() {   }
+;;!                  ***
 (
   (_
     body: (_
diff --git a/queries/javascript.function.scm b/queries/javascript.function.scm
index a9f236d654..f2ba89aa21 100644
--- a/queries/javascript.function.scm
+++ b/queries/javascript.function.scm
@@ -1,16 +1,16 @@
 ;; Anonymous functions
 [
-  ;; function() {}
+  ;;!! function() {}
   (function
     !name
   )
 
-  ;; function *() {}
+  ;;!! function *() {}
   (generator_function
     !name
   )
 
-  ;; () => {}
+  ;;!! () => {}
   (arrow_function)
 ] @anonymousFunction
 
@@ -18,17 +18,17 @@
 ;; named function.
 (export_statement
   [
-    ;; export default function() {}
+    ;;!! export default function() {}
     (function
       !name
     )
 
-    ;; export default function *() {}
+    ;;!! export default function *() {}
     (generator_function
       !name
     )
 
-    ;; export default () => {}
+    ;;!! export default () => {}
     (arrow_function)
   ]
 ) @namedFunction
@@ -36,19 +36,19 @@
 ;; Named functions without export
 (
   [
-    ;; function foo() {}
+    ;;!! function foo() {}
     (function_declaration
       name: (_) @functionName
     )
 
-    ;; function *foo() {}
+    ;;!! function *foo() {}
     (generator_function_declaration
       name: (_) @functionName
     )
 
-    ;; (let | const) foo = () => {}
-    ;; (let | const) foo = function() {}
-    ;; (let | const) foo = function *() {}
+    ;;!! (let | const) foo = () => {}
+    ;;!! (let | const) foo = function() {}
+    ;;!! (let | const) foo = function *() {}
     (lexical_declaration
       (variable_declarator
         name: (_) @functionName
@@ -64,9 +64,9 @@
       )
     )
 
-    ;; var foo = () => {}
-    ;; var foo = function() {}
-    ;; var foo = function *() {}
+    ;;!! var foo = () => {}
+    ;;!! var foo = function() {}
+    ;;!! var foo = function *() {}
     ;; Note that we can't merge this with the variable declaration above because
     ;; of https://github.com/tree-sitter/tree-sitter/issues/1442#issuecomment-1584628651
     (variable_declaration
@@ -90,19 +90,19 @@
 ;; Exported named functions
 (export_statement
   [
-    ;; export [default] function foo() {}
+    ;;!! export [default] function foo() {}
     (function_declaration
       name: (_) @functionName
     )
 
-    ;; export [default] function *foo() {}
+    ;;!! export [default] function *foo() {}
     (generator_function_declaration
       name: (_) @functionName
     )
 
-    ;; export [default] (let | const | var) foo = () => {}
-    ;; export [default] (let | const | var) foo = function() {}
-    ;; export [default] (let | const | var) foo = function *() {}
+    ;;!! export [default] (let | const | var) foo = () => {}
+    ;;!! export [default] (let | const | var) foo = function() {}
+    ;;!! export [default] (let | const | var) foo = function *() {}
     (_
       (variable_declarator
         name: (_) @functionName
@@ -125,25 +125,25 @@
 ;; We also don't handle function declarations that only exist in Javascript;
 ;; see javascript.scm.
 [
-  ;; (function foo() {})
+  ;;!! (function foo() {})
   (function
     name: (_) @functionName
   )
 
-  ;; (function *foo() {})
+  ;;!! (function *foo() {})
   (generator_function
     name: (_) @functionName
   )
 
-  ;; foo() {}
-  ;; (in class bodies)
+  ;;!! class Foo { foo() {} }
+  ;;!              ^^^^^^^^
   (method_definition
     name: (_) @functionName
   )
 
-  ;; foo = () => {};
-  ;; foo = function() {};
-  ;; foo = function *() {};
+  ;;!! foo = () => {};
+  ;;!! foo = function() {};
+  ;;!! foo = function *() {};
   (assignment_expression
     left: (_) @functionName
     right: [
diff --git a/queries/javascript.jsx.scm b/queries/javascript.jsx.scm
index 84b95ceba4..635f0e6511 100644
--- a/queries/javascript.jsx.scm
+++ b/queries/javascript.jsx.scm
@@ -1,9 +1,15 @@
+;;!! <foo>bar</foo>
+;;!  ^^^^^^^^^^^^^^
+;;!       ###
+;;!       ***
 (
   (jsx_element) @xmlElement @_.interior @_.iteration
   (#child-range! @_.interior 0 -1 true true)
   (#child-range! @_.iteration 0 -1 true true)
 )
 
+;;!! <foo>bar</foo>
+;;!       ***
 (
   (jsx_element) @xmlStartTag.iteration @xmlEndTag.iteration @xmlBothTags.iteration
   (#child-range! @xmlStartTag.iteration 0 -1 true true)
@@ -11,25 +17,37 @@
   (#child-range! @xmlBothTags.iteration 0 -1 true true)
 )
 
+;;!! <foo>bar</foo>
+;;!  ^^^^^---------
 (jsx_element
   (jsx_opening_element) @xmlStartTag @xmlBothTags
   (#allow-multiple! @xmlBothTags)
 ) @_.domain
 
+;;!! <foo>bar</foo>
+;;!  --------^^^^^^
 (jsx_element
   (jsx_closing_element) @xmlEndTag @xmlBothTags
   (#allow-multiple! @xmlBothTags)
 ) @_.domain
 
+;;!! <foo/>
 (jsx_self_closing_element) @xmlElement
 
-;; JSX fragments, eg <>foo</>
+;; ======== JSX fragments, eg <>foo</>  ==========
+
+;;!! <>foo</>
+;;!  ^^^^^^^^
+;;!    ###
+;;!    ***
 (
   (jsx_fragment) @xmlElement @_.interior @_.iteration
   (#child-range! @_.interior 1 -3 true true)
   (#child-range! @_.iteration 1 -3 true true)
 )
 
+;;!! <>foo</>
+;;!    ***
 (
   (jsx_fragment) @xmlStartTag.iteration @xmlEndTag.iteration @xmlBothTags.iteration
   (#child-range! @xmlStartTag.iteration 1 -3 true true)
@@ -37,6 +55,8 @@
   (#child-range! @xmlBothTags.iteration 1 -3 true true)
 )
 
+;;!! <>foo</>
+;;!  ^^------
 (
   (jsx_fragment) @xmlStartTag @xmlBothTags @_.domain
   (#child-range! @xmlStartTag 0 1)
@@ -44,6 +64,8 @@
   (#allow-multiple! @xmlBothTags)
 )
 
+;;!! <>foo</>
+;;!  -----^^^
 (
   (jsx_fragment) @xmlEndTag @xmlBothTags @_.domain
   (#child-range! @xmlEndTag -3)
@@ -51,6 +73,10 @@
   (#allow-multiple! @xmlBothTags)
 )
 
+;; Sets `name` to be empty range inside the fragment tag:
+;;!! <>foo</>
+;;!  {}    {}
+;;!  --   ---
 (
   (jsx_fragment
     "<" @_.domain.start
diff --git a/queries/javascript.scm b/queries/javascript.scm
index 381e7b1ff0..697325d548 100644
--- a/queries/javascript.scm
+++ b/queries/javascript.scm
@@ -7,10 +7,14 @@
 ;; Define this here because the `field_definition` node type doesn't exist
 ;; in typescript.
 (
-  ;; foo = () => {};
-  ;; foo = function() {};
-  ;; foo = function *() {};
-  ;; (inside class bodies)
+  ;;!! class Foo {
+  ;;!!   foo = () => {};
+  ;;!    ^^^^^^^^^^^^^^^
+  ;;!!   foo = function() {};
+  ;;!    ^^^^^^^^^^^^^^^^^^^^
+  ;;!!   foo = function *() {};
+  ;;!    ^^^^^^^^^^^^^^^^^^^^^^
+  ;;!! }
   (field_definition
     property: (_) @functionName
     value: [
@@ -28,7 +32,8 @@
 )
 
 (
-  ;; foo = ...;
+  ;;!! foo = ...;
+  ;;!  ^^^-------
   (field_definition
     property: (_) @name
   ) @name.domain.start
diff --git a/queries/typescript.scm b/queries/typescript.scm
index 6be6ee6dab..1bbbb8b273 100644
--- a/queries/typescript.scm
+++ b/queries/typescript.scm
@@ -4,10 +4,14 @@
 
 ;; import javascript.core.scm
 
+;;!! function aaa(bbb?: Ccc = "ddd") {}
+;;!               ^^^--------------
 (optional_parameter
     (identifier) @name
 ) @_.domain
 
+;;!! function aaa(bbb: Ccc = "ddd") {}
+;;!               ^^^-------------
 (required_parameter
     (identifier) @name
 ) @_.domain
@@ -15,22 +19,28 @@
 ;; Define these here because these node types don't exist in javascript.
 (
   [
-    ;; foo(): void;
-    ;; (in interface)
-    ;; foo() {}
-    ;; (in class)
+    ;;!! class Foo { foo() {} }
+    ;;!              ^^^^^^^^
+    ;;!! interface Foo { foo(): void; }
+    ;;!                  ^^^^^^^^^^^^
     (method_signature
       name: (_) @functionName @name
     )
 
-    ;; abstract foo(): void;
+    ;;!! class Foo { abstract foo(): void; }
+    ;;!              ^^^^^^^^^^^^^^^^^^^^^
     (abstract_method_signature
       name: (_) @functionName @name
     )
 
-    ;; [public | private | protected] foo = () => {};
-    ;; [public | private | protected] foo = function() {};
-    ;; [public | private | protected] foo = function *() {};
+    ;;!! class Foo {
+    ;;!!   (public | private | protected) foo = () => {};
+    ;;!                                   ^^^^^^^^^^^^^^^
+    ;;!!   (public | private | protected) foo = function() {};
+    ;;!                                   ^^^^^^^^^^^^^^^^^^^^
+    ;;!!   (public | private | protected) foo = function *() {};
+    ;;!                                   ^^^^^^^^^^^^^^^^^^^^^^
+    ;;!! }
     (public_field_definition
       name: (_) @functionName
       value: [
@@ -49,7 +59,8 @@
 )
 
 (
-  ;; [public | private | protected] foo = ...;
+  ;;!! (public | private | protected) foo = ...;
+  ;;!  -------------------------------^^^-------
   (public_field_definition
     name: (_) @name
   ) @name.domain.start