From 9667315d49c344e9455a70265857de5e6d3cf6e3 Mon Sep 17 00:00:00 2001 From: Paolo Tranquilli Date: Thu, 24 Feb 2022 10:55:53 +0100 Subject: [PATCH] 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 | 8 +++++ docs/pre-commit-hook-setup.md | 58 +++++++++++++++++++++++------------ misc/scripts/check-qhelp.py | 28 +++++++++++++++++ 3 files changed, 75 insertions(+), 19 deletions(-) create mode 100755 misc/scripts/check-qhelp.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c95ccf5f280..496c141ba5b 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/docs/pre-commit-hook-setup.md b/docs/pre-commit-hook-setup.md index 7f6595c4691..a745d72fc81 100644 --- a/docs/pre-commit-hook-setup.md +++ b/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. diff --git a/misc/scripts/check-qhelp.py b/misc/scripts/check-qhelp.py new file mode 100755 index 00000000000..8446cc66e13 --- /dev/null +++ b/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)