pre-commit: add qhelp check

Also the instructions on customizing `pre-commit`'s behaviour have been
updated to use the `--config` option.

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
+
 -   repo: local
     hooks:
     -   id: codeql-format
@@ -14,8 +15,15 @@ repos:
         files: \.qll?$
         language: system
         entry: codeql query format --in-place
+
     -   id: sync-files
         name: Fix files required to be identical
         language: system
         entry: python3 config/sync-files.py --latest
         pass_filenames: false
+
+    -   id: qlhelp
+        name: Check query help generation
+        files: \.qhelp$
+        language: system
+        entry: python3 misc/scripts/check-qhelp.py

docs/pre-commit-hook-setup.md

@@ -1,6 +1,44 @@
 # CodeQL pre-commit-hook setup
 
-As stated in [CONTRIBUTING](../CONTRIBUTING.md) all CodeQL files must be formatted according to our [CodeQL style guide](ql-style-guide.md). You can use our pre-commit hook to avoid committing incorrectly formatted code. To use it, simply copy the [pre-commit](../misc/scripts/pre-commit) script to `.git/hooks/pre-commit` and make sure that:
+
+As stated in [CONTRIBUTING](../CONTRIBUTING.md) all CodeQL files must be formatted according to our [CodeQL style guide](ql-style-guide.md). You can use a pre-commit hook to avoid committing incorrectly formatted code, as well as prevent some other easily checkable errors.
+
+## Using the `pre-commit` framework
+
+Preferably, you can use the [pre-commit framework](https://pre-commit.com/). There are some pre-commit hooks already configured on [`.pre-commit-config.yaml`](../.pre-commit-config.yaml). In order to install them you need to follow pre-commit's [installation instructions](https://pre-commit.com/#installation) and then run `pre-commit install`. Typically (assuming you have [`pip`](https://pip.pypa.io/en/stable/installation/) installed):
+```
+python3 -m pip install pre-commit
+pre-commit install
+```
+
+Also, make sure that the CodeQL CLI has been added to your `PATH`.
+
+By default, pre-commit will check and fix:
+* trailing whitespaces;
+* absence of or duplicate newlines at end of files;
+* QL formatting;
+* files out of sync (see [`config/sync-files.py`](../config/sync-files.py)).
+
+It will additionally check:
+* `.qhelp` files for query help generation.
+
+It will run the checks only on files changed by the commit (except for the file sync check) and it will skip all files under `test` directories unless they are `.ql`, `.qll` or `.qlref` files.
+
+If you want to change any behaviour (for example, you want to skip the out-of-sync file check, or you want to avoid auto-fixing formatting or file syncing), you can copy the configuration file to a separate location, modify it and use that. For example
+```
+cp .pre-commit-config.yaml ~/my-codeql-pre-commit-config.yaml
+pre-commit install --config ~/my-codeql-pre-commit-config.yaml
+# edit ~/my-codeql-pre-commit-config.yaml to your linking
+```
+
+You can for example:
+* change `--in-place` to `--check-only` in the `codeql-format` hook to have it report formatting problems instead of auto-fixing them;
+* remove `--latest` in the `sync-files` hook to do the same;
+* remove any hook altogether.
+
+## Manual approach
+
+You can have the formatting check in place by copying the [pre-commit](../misc/scripts/pre-commit) script to `.git/hooks/pre-commit` and make sure that:
 
 - The script is executable. On Linux and macOS this can be done using `chmod +x`.
 - The CodeQL CLI has been added to your `PATH`.
@@ -14,21 +52,3 @@ ql/cpp/ql/src/printAst.ql would change by autoformatting.
 ```
 
 If you prefer to have the script automatically format the code (and not abort the commit), you can replace the line `codeql query format --check-only` with `codeql query format --in-place` (and `exit $exitVal` with `exit 0`).
-
-## Using the `pre-commit` framework
-
-Alternatively, you can use the [pre-commit framework](https://pre-commit.com/). There are some pre-commit hooks already configured on [`.pre-commit-config.yaml`](../.pre-commit-config.yaml). In order to install them you need to follow pre-commit's [installation instructions](https://pre-commit.com/#installation) and then run `pre-commit install`.
-
-By default, pre-commit will check and fix
-* trailing whitespaces;
-* absence of or duplicate newlines at end of files;
-* QL formatting;
-* files out of sync (see [`config/sync-files.py`](../config/sync-files.py)).
-
-It will run the checks only on files changed by the commit (except for the file sync check) and it will skip all files under `test` directories unless they are `.ql`, `.qll` or `.qlref` files.
-
-If you want to change one of these default behaviours (for example, you want to skip the out-of-sync file check, or you prefer to pass `--check-only` instead of `--in-place` to the query formatter), run
-```
-git update-index --assume-unchanged .pre-commit-config.yaml
-```
-and you can then modify the configuration at your will.

misc/scripts/check-qhelp.py

@@ -0,0 +1,28 @@
+#!/bin/env python3
+
+"""cross platform wrapper around codeql generate query-help to check .qhelp files
+
+This takes care of:
+* providing a temporary directory to --output
+* turning .inc.qhelp arguments into their containing directory
+"""
+
+import pathlib
+import tempfile
+import sys
+import subprocess
+
+def transform_input(arg):
+    arg = pathlib.Path(arg)
+    if arg.suffixes == ['.inc', '.qhelp']:
+        return str(arg.parent)
+    return str(arg)
+
+cmd = ["codeql", "generate", "query-help", "--format=markdown"]
+
+with tempfile.TemporaryDirectory() as tmp:
+    cmd += [f"--output={tmp}", "--"]
+    cmd.extend(transform_input(x) for x in sys.argv[1:])
+    res = subprocess.run(cmd)
+
+sys.exit(res.returncode)