feat(highlights)!: enforce documented captures (#6232)

Problem: Allowing undocumented "secret" (sub)captures makes it harder
to write comprehensive colorschemes and catch inconsistent captures.

Solution: Only allow captures listed in CONTRIBUTING.md. Add useful
(cross-language) subcaptures and drop language-specific or too niche
ones.

Follow-up: Adding further `*.builtin` captures and changing queries to
use them.

Language-specific subcaptures should instead be added in user config or
a custom language plugin.

26 files changed, 87 insertions, 91 deletions

diff --git a/queries/cpp/highlights.scm b/queries/cpp/highlights.scm
index 786391e32..b021e8b37 100644
--- a/queries/cpp/highlights.scm
+++ b/queries/cpp/highlights.scm
@@ -220,12 +220,11 @@
   "constexpr"
 ] @keyword
 
-"co_await" @keyword.coroutine
-
 [
+  "co_await"
   "co_yield"
   "co_return"
-] @keyword.coroutine.return
+] @keyword.coroutine
 
 [
   "public"
diff --git a/queries/cue/locals.scm b/queries/cue/locals.scm
index 9c5a7378e..b2a8972f7 100644
--- a/queries/cue/locals.scm
+++ b/queries/cue/locals.scm
@@ -19,13 +19,13 @@
 (package_identifier) @local.definition.namespace
 
 (for_clause
-  (identifier) @local.definition.variable
+  (identifier) @local.definition.var
   (expression))
 
 (for_clause
   (identifier)
-  (identifier) @local.definition.variable
+  (identifier) @local.definition.var
   (expression))
 
 (let_clause
-  (identifier) @local.definition.variable)
+  (identifier) @local.definition.var)
diff --git a/queries/ebnf/highlights.scm b/queries/ebnf/highlights.scm
index 8715091b1..4254d04dd 100644
--- a/queries/ebnf/highlights.scm
+++ b/queries/ebnf/highlights.scm
@@ -1,7 +1,7 @@
 ; Simple tokens ;;;;
-(terminal) @string.grammar
+(terminal) @string
 
-(special_sequence) @string.special.grammar
+(special_sequence) @string.special
 
 (integer) @number
 
diff --git a/queries/firrtl/highlights.scm b/queries/firrtl/highlights.scm
index 8e078fad2..14f12b169 100644
--- a/queries/firrtl/highlights.scm
+++ b/queries/firrtl/highlights.scm
@@ -87,7 +87,7 @@
   "reader"
   "writer"
   "readwriter"
-] @variable.member.builtin
+] @variable.member
 
 ((field_id) @variable.member
   (#set! "priority" 105))
diff --git a/queries/fsh/highlights.scm b/queries/fsh/highlights.scm
index 3404fa7c6..2354a2037 100644
--- a/queries/fsh/highlights.scm
+++ b/queries/fsh/highlights.scm
@@ -86,7 +86,7 @@
 ; Constants
 (strength_value) @constant
 
-(bool) @constant.boolean
+(bool) @boolean
 
 (flag) @constant
 
diff --git a/queries/hare/locals.scm b/queries/hare/locals.scm
index b81ee5135..12a214bf7 100644
--- a/queries/hare/locals.scm
+++ b/queries/hare/locals.scm
@@ -61,5 +61,5 @@
 (let_declaration
   "let"
   .
-  (identifier) @local.definition.variable
+  (identifier) @local.definition.var
   ","?)
diff --git a/queries/hoon/highlights.scm b/queries/hoon/highlights.scm
index 767b0dd22..d98ee44e0 100644
--- a/queries/hoon/highlights.scm
+++ b/queries/hoon/highlights.scm
@@ -28,7 +28,7 @@
 
 (mold) @string.special.symbol
 
-(specialIndex) @number.builtin
+(specialIndex) @number
 
 (lark) @operator
 
diff --git a/queries/jsonnet/highlights.scm b/queries/jsonnet/highlights.scm
index acd838cbe..85670a25c 100644
--- a/queries/jsonnet/highlights.scm
+++ b/queries/jsonnet/highlights.scm
@@ -118,7 +118,7 @@
   identifier: (id) @variable.parameter)
 
 (bind
-  (id) @variable.local)
+  (id) @variable)
 
 (bind
   function: (id) @function)
diff --git a/queries/latex/highlights.scm b/queries/latex/highlights.scm
index 5b5f19768..819a2ff94 100644
--- a/queries/latex/highlights.scm
+++ b/queries/latex/highlights.scm
@@ -41,16 +41,16 @@
 
 ; General environments
 (begin
-  command: _ @markup.environment
+  command: _ @module
   name:
     (curly_group_text
-      (text) @markup.environment.name))
+      (text) @label))
 
 (end
-  command: _ @markup.environment
+  command: _ @module
   name:
     (curly_group_text
-      (text) @markup.environment.name))
+      (text) @label))
 
 ; Definitions and references
 (new_command_definition
@@ -77,7 +77,7 @@
   command: _ @function.macro
   name:
     (curly_group_text
-      (_) @markup.environment.name))
+      (_) @label))
 
 (paired_delimiter_definition
   command: _ @function.macro
@@ -260,8 +260,8 @@
   (begin
     name:
       (curly_group_text
-        (text) @markup.environment.name)
-    (#any-of? @markup.environment.name "frame"))
+        (text) @label)
+    (#any-of? @label "frame"))
   .
   (curly_group
     (_) @markup.heading))
diff --git a/queries/linkerscript/highlights.scm b/queries/linkerscript/highlights.scm
index 23a483745..12330169e 100644
--- a/queries/linkerscript/highlights.scm
+++ b/queries/linkerscript/highlights.scm
@@ -63,7 +63,7 @@
   "LENGTH"
   "len"
   "l"
-] @variable.member.builtin
+] @variable.member
 
 ; Constants
 ((symbol) @constant
diff --git a/queries/markdown/highlights.scm b/queries/markdown/highlights.scm
index e4d375b54..5d77e7217 100644
--- a/queries/markdown/highlights.scm
+++ b/queries/markdown/highlights.scm
@@ -1,34 +1,34 @@
 ;From MDeiml/tree-sitter-markdown & Helix
 (setext_heading
   (paragraph) @markup.heading.1
-  (setext_h1_underline) @markup.heading.1.marker)
+  (setext_h1_underline) @markup.heading.1)
 
 (setext_heading
   (paragraph) @markup.heading.2
-  (setext_h2_underline) @markup.heading.2.marker)
+  (setext_h2_underline) @markup.heading.2)
 
 (atx_heading
-  (atx_h1_marker) @markup.heading.1.marker
+  (atx_h1_marker) @markup.heading.1
   (inline) @markup.heading.1)
 
 (atx_heading
-  (atx_h2_marker) @markup.heading.2.marker
+  (atx_h2_marker) @markup.heading.2
   (inline) @markup.heading.2)
 
 (atx_heading
-  (atx_h3_marker) @markup.heading.3.marker
+  (atx_h3_marker) @markup.heading.3
   (inline) @markup.heading.3)
 
 (atx_heading
-  (atx_h4_marker) @markup.heading.4.marker
+  (atx_h4_marker) @markup.heading.4
   (inline) @markup.heading.4)
 
 (atx_heading
-  (atx_h5_marker) @markup.heading.5.marker
+  (atx_h5_marker) @markup.heading.5
   (inline) @markup.heading.5)
 
 (atx_heading
-  (atx_h6_marker) @markup.heading.6.marker
+  (atx_h6_marker) @markup.heading.6
   (inline) @markup.heading.6)
 
 (info_string) @label
@@ -54,12 +54,12 @@
   (#set! "priority" 90))
 
 (fenced_code_block
-  (fenced_code_block_delimiter) @markup.raw.delimiter
+  (fenced_code_block_delimiter) @markup.raw.block
   (#set! conceal ""))
 
 (fenced_code_block
   (info_string
-    (language) @conceal
+    (language) @label
     (#set! conceal "")))
 
 (link_destination) @markup.link.url
diff --git a/queries/markdown_inline/highlights.scm b/queries/markdown_inline/highlights.scm
index e9b41c31d..cae8acfb4 100644
--- a/queries/markdown_inline/highlights.scm
+++ b/queries/markdown_inline/highlights.scm
@@ -16,10 +16,10 @@
 ] @string.escape
 
 ; Conceal codeblock and text style markers
-((code_span_delimiter) @markup.raw.delimiter
-  (#set! conceal ""))
-
-((emphasis_delimiter) @conceal
+([
+  (code_span_delimiter)
+  (emphasis_delimiter)
+] @conceal
   (#set! conceal ""))
 
 ; Conceal inline links
diff --git a/queries/objc/highlights.scm b/queries/objc/highlights.scm
index 7a83376c2..dd2c796bd 100644
--- a/queries/objc/highlights.scm
+++ b/queries/objc/highlights.scm
@@ -174,12 +174,12 @@
     "__unsafe_unretained"
     "__unused"
     "__weak"
-  ]) @function.macro.builtin
+  ]) @function.macro
 
 [
   "__real"
   "__imag"
-] @function.macro.builtin
+] @function.macro
 
 ((call_expression
   function: (identifier) @function.macro)
diff --git a/queries/perl/highlights.scm b/queries/perl/highlights.scm
index 1b0dc2dc1..fcd0f3071 100644
--- a/queries/perl/highlights.scm
+++ b/queries/perl/highlights.scm
@@ -65,7 +65,7 @@
 (yadayada) @keyword.exception
 
 (phaser_statement
-  phase: _ @keyword.phaser)
+  phase: _ @keyword)
 
 [
   "or"
@@ -207,50 +207,50 @@
   ; highlights punc vars and also numeric only like $11
   (#lua-match? @variable.builtin "^%A+$"))
 
-(scalar) @variable.scalar
+(scalar) @variable
 
 (scalar_deref_expression
   [
     "$"
     "*"
-  ] @variable.scalar)
+  ] @variable)
 
 [
   (array)
   (arraylen)
-] @variable.array
+] @variable
 
 (array_deref_expression
   [
     "@"
     "*"
-  ] @variable.array)
+  ] @variable)
 
-(hash) @variable.hash
+(hash) @variable
 
 (hash_deref_expression
   [
     "%"
     "*"
-  ] @variable.hash)
+  ] @variable)
 
 (array_element_expression
-  array: (_) @variable.array)
+  array: (_) @variable)
 
 (slice_expression
-  array: (_) @variable.array)
+  array: (_) @variable)
 
 (keyval_expression
-  array: (_) @variable.array)
+  array: (_) @variable)
 
 (hash_element_expression
-  hash: (_) @variable.hash)
+  hash: (_) @variable)
 
 (slice_expression
-  hash: (_) @variable.hash)
+  hash: (_) @variable)
 
 (keyval_expression
-  hash: (_) @variable.hash)
+  hash: (_) @variable)
 
 (comment) @comment
 
diff --git a/queries/rbs/highlights.scm b/queries/rbs/highlights.scm
index 11dbf7c2c..340bc254e 100644
--- a/queries/rbs/highlights.scm
+++ b/queries/rbs/highlights.scm
@@ -80,7 +80,7 @@
 (const_name
   (constant) @constant)
 
-(global_name) @variable.global
+(global_name) @variable
 
 ; Standard Arguments
 (parameter
diff --git a/queries/rst/injections.scm b/queries/rst/injections.scm
index 7ca479a65..da57daa65 100644
--- a/queries/rst/injections.scm
+++ b/queries/rst/injections.scm
@@ -41,15 +41,7 @@
     (body
       (arguments) @injection.language
       (content) @injection.content))
-  (#any-of? @_type "code" "code-block" "sourcecode"))
-
-((directive
-  name: (type) @_type
-  body:
-    (body
-      (arguments) @injection.language
-      (content) @injection.content))
-  (#eq? @_type "raw"))
+  (#any-of? @_type "raw" "code" "code-block" "sourcecode"))
 
 ((directive
   name: (type) @_type
@@ -59,7 +51,6 @@
   (#set! injection.language "latex")
   (#eq? @_type "math"))
 
-; TODO: re-add when a parser for csv is added.
 ((directive
   name: (type) @_type
   body:
diff --git a/queries/ruby/highlights.scm b/queries/ruby/highlights.scm
index 50e8c9093..5b5fcbf9f 100644
--- a/queries/ruby/highlights.scm
+++ b/queries/ruby/highlights.scm
@@ -1,7 +1,8 @@
 ; Variables
-(identifier) @variable
-
-(global_variable) @variable.global
+[
+  (identifier)
+  (global_variable)
+] @variable
 
 ; Keywords
 [
diff --git a/queries/rust/highlights.scm b/queries/rust/highlights.scm
index f5fff58d0..4639d8859 100644
--- a/queries/rust/highlights.scm
+++ b/queries/rust/highlights.scm
@@ -288,7 +288,7 @@
   [
     "'"
     (identifier)
-  ] @keyword.storage.lifetime)
+  ] @keyword.storage)
 
 "fn" @keyword.function
 
diff --git a/queries/slint/locals.scm b/queries/slint/locals.scm
index 2d256b7ac..7e895a6b5 100644
--- a/queries/slint/locals.scm
+++ b/queries/slint/locals.scm
@@ -16,7 +16,7 @@
 (argument) @local.definition.var
 
 (callback
-  name: (_) @local.definition.member)
+  name: (_) @local.definition.field)
 
 (component_definition
   name: (_) @local.definition.type)
diff --git a/queries/soql/highlights.scm b/queries/soql/highlights.scm
index 5356b8a7f..721e84ed2 100644
--- a/queries/soql/highlights.scm
+++ b/queries/soql/highlights.scm
@@ -82,9 +82,10 @@
 
 (string_literal) @string
 
-(date) @variable.readonly
-
-(date_time) @variable.readonly
+[
+  (date)
+  (date_time)
+] @string.special
 
 [
   "TRUE"
diff --git a/queries/squirrel/highlights.scm b/queries/squirrel/highlights.scm
index da7bef337..28d072029 100644
--- a/queries/squirrel/highlights.scm
+++ b/queries/squirrel/highlights.scm
@@ -64,15 +64,16 @@
 ] @type.qualifier
 
 ; Variables
-(identifier) @variable
+[
+  (identifier)
+  (global_variable)
+] @variable
 
 (local_declaration
-  (identifier) @variable.local
+  (identifier) @variable
   .
   "=")
 
-(global_variable) @variable.global
-
 ((identifier) @variable.builtin
   (#any-of? @variable.builtin "base" "this" "vargv"))
 
diff --git a/queries/squirrel/locals.scm b/queries/squirrel/locals.scm
index 3858eb6b0..e5fce7d57 100644
--- a/queries/squirrel/locals.scm
+++ b/queries/squirrel/locals.scm
@@ -67,9 +67,9 @@
 (var_statement
   "var"
   .
-  (identifier) @local.definition.variable)
+  (identifier) @local.definition.var)
 
 (local_declaration
-  (identifier) @local.definition.variable
+  (identifier) @local.definition.var
   .
   "=")
diff --git a/queries/strace/highlights.scm b/queries/strace/highlights.scm
index 62fa724bd..70a14fd2d 100644
--- a/queries/strace/highlights.scm
+++ b/queries/strace/highlights.scm
@@ -16,9 +16,10 @@
 (syscall) @function.builtin
 
 ; Literals
-(integer) @number
-
-(pointer) @number.special
+[
+  (integer)
+  (pointer)
+] @number
 
 (value) @label
 
diff --git a/queries/ungrammar/locals.scm b/queries/ungrammar/locals.scm
index 389d5c262..0f745bd14 100644
--- a/queries/ungrammar/locals.scm
+++ b/queries/ungrammar/locals.scm
@@ -1,7 +1,8 @@
 (grammar) @local.scope
 
-(definition) @local.definition
-
-(label_name) @local.definition.label
+[
+  (definition)
+  (label_name)
+] @local.definition
 
 (identifier) @local.reference
diff --git a/queries/vimdoc/highlights.scm b/queries/vimdoc/highlights.scm
index 294fa94f1..21b2b98c6 100644
--- a/queries/vimdoc/highlights.scm
+++ b/queries/vimdoc/highlights.scm
@@ -7,11 +7,11 @@
 (column_heading) @markup.heading.4
 
 (column_heading
-  "~" @markup.heading.4.marker
+  "~" @markup.heading.4
   (#set! conceal ""))
 
 (tag
-  "*" @markup.heading.5.marker
+  "*" @label
   (#set! conceal "")
   text: (_) @label)
 
@@ -24,7 +24,7 @@
   text: (_) @markup.link)
 
 (codespan
-  "`" @markup.raw.delimiter
+  "`" @markup.raw
   (#set! conceal "")
   text: (_) @markup.raw)
 
@@ -32,14 +32,15 @@
   (#set! "priority" 90))
 
 (codeblock
-  [
-    ">"
-    (language)
-  ] @markup.raw.delimiter
+  ">" @markup.raw
+  (#set! conceal ""))
+
+(codeblock
+  (language) @label
   (#set! conceal ""))
 
 (block
-  "<" @markup.raw.delimiter
+  "<" @markup.raw
   (#set! conceal ""))
 
 (argument) @variable.parameter
diff --git a/queries/xml/highlights.scm b/queries/xml/highlights.scm
index 4585d2ae3..464207990 100644
--- a/queries/xml/highlights.scm
+++ b/queries/xml/highlights.scm
@@ -51,9 +51,9 @@
 (CharData) @none @spell
 
 ((CDSect
-  (CDStart) @markup.environment
+  (CDStart) @module
   (CData) @markup.raw
-  "]]>" @markup.environment)
+  "]]>" @module)
   (#set! "priority" 105))
 
 ; Delimiters & punctuation