devcontainer: Add ast-grep

Install `ast-grep` so that our C++ code can be checked against the rules
under `Utilities/ast-grep` before pushing, as our CI job now does.
Ubuntu does not carry it, so install the release that job does, verified
by checksum, leaving out the `sg` alias, whose name is taken by the
command that runs a command under another group.

Issue: #28119
Suggested-by: Brad King <brad.king@kitware.com>

.devcontainer/Dockerfile

@@ -56,6 +56,13 @@ RUN --mount=type=bind,source=install_glab.sh,target=/root/install_glab.sh \
     --mount=type=tmpfs,target=/tmp \
     sh /root/install_glab.sh
 
+# Install `ast-grep`, to check our C++ code against the rules under
+# `Utilities/ast-grep`.  Unpack its release in a `tmpfs`, as for `glab`, so
+# that the download leaves nothing behind in the image.
+RUN --mount=type=bind,source=install_ast_grep.sh,target=/root/install_ast_grep.sh \
+    --mount=type=tmpfs,target=/tmp \
+    sh /root/install_ast_grep.sh
+
 # Create an unprivileged user matching the typical host account so that files
 # created in the mounted source tree are not owned by `root`.
 RUN --mount=type=bind,source=create_user.sh,target=/root/create_user.sh \

.devcontainer/dev_packages.lst

@@ -60,6 +60,10 @@ python3-sphinx
 clang-format-18
 pre-commit
 
+# Unpack the `ast-grep` release that `install_ast_grep.sh` downloads, as
+# Ubuntu does not carry `ast-grep` itself.
+unzip
+
 # Run `glab` and `glab-axi`, and reach GitLab over SSH.  `nodejs` and `npm`
 # are needed both to install `glab-axi` and to run it.
 nodejs

.devcontainer/install_ast_grep.sh

@@ -0,0 +1,42 @@
+#!/bin/sh
+
+# Install `ast-grep`, which checks our C++ code against the rules under
+# `Utilities/ast-grep`.  It is not provided by the distribution.
+# See `Help/dev/devcontainer.rst`.
+
+set -e
+
+# Install the release our CI job does, from `.gitlab/ci/ast-grep.sh`, so that
+# a scan here reports what that job reports.
+readonly version="0.45.3"
+
+case "$(uname -m)" in
+    x86_64)
+        sha256sum="f8ac830881339d1edee6b2652f54798c0f4da5a827f2db38a08ee31117783ce8"
+        filename="app-x86_64-unknown-linux-gnu.zip"
+        ;;
+    aarch64)
+        sha256sum="b39cfbc58da4b869a88b8a4bc57bd5deb0d24541e704cf7c257da7b53ec81c8f"
+        filename="app-aarch64-unknown-linux-gnu.zip"
+        ;;
+    *)
+        echo "Unsupported architecture: $(uname -m)" >&2
+        exit 1
+        ;;
+esac
+
+readonly baseurl="https://github.com/ast-grep/ast-grep/releases/download/${version}"
+
+# The release also carries `sg`, a shorter alias for `ast-grep`.  Leave it
+# out, as our CI job does: the name is taken by the `sg` command that runs a
+# command under another group.
+cd /tmp
+curl -L -o "$filename" "$baseurl/$filename"
+echo "$sha256sum  $filename" > ast-grep.sha256sum
+sha256sum --check ast-grep.sha256sum
+unzip -d /usr/local/bin "$filename" ast-grep
+rm "$filename" ast-grep.sha256sum
+
+# Enable shell completion for interactive use.
+mkdir -p /etc/bash_completion.d
+/usr/local/bin/ast-grep completions bash > /etc/bash_completion.d/ast-grep

Help/dev/devcontainer.rst

@@ -175,6 +175,16 @@ against, the container provides:
   ``CMake_USE_CLANG_TIDY_MODULE`` needs `Utilities/ClangTidyModule`_ built
   against Clang's development files, which the container does not install.
 
+* ``ast-grep``, to check our C++ code against the rules under
+  `Utilities/ast-grep`_, and to test the rules themselves:
+
+  .. code-block:: console
+
+    $ ast-grep scan
+    $ ast-grep test
+
+  It is the release our CI job runs, so it reports what that job reports.
+
 * ``glab``, the `GitLab CLI`_, to work with merge requests, issues, and
   pipelines on our GitLab instance, and `glab-axi`_, a wrapper around it
   whose output follows the `AXI`_ conventions:
@@ -190,6 +200,7 @@ against, the container provides:
 .. _`C++ Code Style`: source.rst#c-code-style
 .. _`.pre-commit-config.yaml`: ../../.pre-commit-config.yaml
 .. _`Utilities/ClangTidyModule`: ../../Utilities/ClangTidyModule
+.. _`Utilities/ast-grep`: ../../Utilities/ast-grep
 .. _`CMake Documentation Guide`: documentation.rst
 .. _`CMake Debugging Guide`: debug.rst
 .. _`GitLab CLI`: https://docs.gitlab.com/editor_extensions/gitlab_cli/