feat: syntax highlighting for .bazelrc (#379)

feat: syntax highlighting for .bazelrc

The main purpose here is really to prevent vscode from autodetecting .bazelrc
as a shell file, resulting in complaints about syntax that isn't valid in a
bash script, or mistakenly highlighting e.g. variable expansions as if they
were actually honored in a .bazelrc.

We can also do a bit better, by actually understanding the semantics of e.g.
config specifiers and so on.

This does not attempt to handle full bourne-shell quoting semantics. It will
only handle quotes around the entire flag, e.g. "--foo=some value" or around
the flag value, e.g. --foo="some value"

This does _not_ try to exhaustively match the list of all possible flags, and
so it can make mistakes like treating --copt -O3 as if it were two separate
flags rather than a flag + value, however that's mostly harmless.  Maintaining
a list of known flags and whether or not the accept a value would be
prohibitively difficult to maintain without some kind of automation.

There is special treatment for a couple of flags, including `--config` and a
few flags that expect regex arguments, like `--instrumentation_filter`.

The grammar is written in YAML and compiled using `js-yaml` as part of the
build process. This requires promoting js-yaml (which was already a transitive
dependency) to a direct dev dependency, and adding a line to build.sh to do the
conversion.

YAML is easier to work with for a number of reasons, especially because
(depending on string style used) you don't need to json-escape strings, which
is especially helpful for regexes.  It also tends to version-control better,
and permits adding comments.

For testing the bazelrc grammar, this commit adds snapshot test.

Closes #259

.vscodeignore

@@ -7,6 +7,9 @@ test/**
 
 **/*.map
 
+syntaxes/bazelrc.tmLanguage.yaml
+syntaxes/.gitignore
+
 .gitignore
 AUTHORS
 CODEOWNERS

package.json

@@ -245,13 +245,29 @@
             }
         ],
         "grammars": [
+            {
+                "language": "bazelrc",
+                "scopeName": "source.bazelrc",
+                "path": "./syntaxes/bazelrc.tmLanguage.json"
+            },
             {
                 "language": "starlark",
                 "scopeName": "source.starlark",
                 "path": "./syntaxes/starlark.tmLanguage.json"
             }
         ],
         "languages": [
+            {
+                "id": "bazelrc",
+                "extensions": [
+                    ".bazelrc"
+                ],
+                "filenames": [
+                    ".bazelrc",
+                    "bazel.rc"
+                ],
+                "configuration": "./syntaxes/bazelrc.configuration.json"
+            },
             {
                 "id": "starlark",
                 "aliases": [
@@ -446,6 +462,8 @@
         "compile": "./scripts/build.sh",
         "format-check": "prettier --check .",
         "format-fix": "prettier --write .",
+        "test": "./scripts/test.sh",
+        "update-snapshot": "./scripts/test.sh -u",
         "vscode:prepublish": "./scripts/build.sh",
         "watch": "./scripts/build.sh -watch"
     },
@@ -456,9 +474,11 @@
         "eslint": "^8.57.0",
         "eslint-config-prettier": "^9.1.0",
         "eslint-plugin-jsdoc": "^48.2.2",
+        "js-yaml": "^4.1.0",
         "prettier": "^3.2.5",
         "typescript": "^5.4.4",
-        "typescript-eslint": "^7.5.0"
+        "typescript-eslint": "^7.5.0",
+        "vscode-tmgrammar-test": "^0.1.3"
     },
     "dependencies": {
         "protobufjs": "^6.8.0",
@@ -468,4 +488,4 @@
         "vscode-uri": "^3.0.2",
         "which": "^4.0.0"
     }
-}
+}

scripts/build.sh

@@ -31,5 +31,8 @@ if [[ ! -f src/protos/protos.d.ts ]] ; then
   pbts -o src/protos/protos.d.ts src/protos/protos.js
 fi
 
+# Convert yaml language definition to json form requred by vscode.
+js-yaml syntaxes/bazelrc.tmLanguage.yaml > syntaxes/bazelrc.tmLanguage.json
+
 # Compile the rest of the project.
 tsc "$@" -p ./

scripts/test.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -eu
+
+# Move into the top-level directory of the project.
+cd "$(dirname "${BASH_SOURCE[0]}")/.." > /dev/null
+
+# If tests are eventually added for other things, this line should probably
+# be replaced by just running scripts/build.sh.
+js-yaml syntaxes/bazelrc.tmLanguage.yaml > syntaxes/bazelrc.tmLanguage.json
+
+# Regression test for bazelrc grammar
+vscode-tmgrammar-snap "$@" test/example.bazelrc

syntaxes/.gitignore

@@ -0,0 +1 @@
+bazelrc.tmLanguage.json

syntaxes/bazelrc.configuration.json

@@ -0,0 +1,33 @@
+{
+    "comments": {
+        "lineComment": "#"
+    },
+    "autoClosingPairs": [
+        {
+            "open": "\"",
+            "close": "\"",
+            "notIn": [
+                "string",
+                "comment"
+            ]
+        },
+        {
+            "open": "'",
+            "close": "'",
+            "notIn": [
+                "string",
+                "comment"
+            ]
+        }
+    ],
+    "surroundingPairs": [
+        [
+            "\"",
+            "\""
+        ],
+        [
+            "'",
+            "'"
+        ]
+    ]
+}