From 104372adbe4cb1a3f33338923c39a128aa3be87a Mon Sep 17 00:00:00 2001 From: Maxi Wittich Date: Thu, 10 Sep 2026 12:56:14 +0200 Subject: [PATCH 1/2] enable typos in operator-templating and downstream --- .pre-commit-config.yaml | 9 ++++ README.md | 73 +++++++++++++++++++++++++++++ template/.pre-commit-config.yaml.j2 | 14 ++++++ 3 files changed, 96 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 85e824d0..f7817110 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,6 +5,15 @@ default_language_version: node: system repos: + - repo: https://github.com/crate-ci/typos + rev: v1.50.1 + hooks: + - id: typos + # Drop the upstream default `--write-changes` so the hook reports and + # fails instead of rewriting files. Keep `--force-exclude` so the + # excludes in typos.toml still apply to the paths prek passes in. + args: ["--force-exclude"] + - repo: https://github.com/pre-commit/pre-commit-hooks rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # 6.0.0 hooks: diff --git a/README.md b/README.md index 9972f105..4521fe66 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,79 @@ These are the only variables currently being used on the playbooks, but can be e Additional settings can be found in `playbook/group_vars/all`, but these are not intended to be freely changed and should be treated with care. +## Spell checking + +Every managed repository runs [typos](https://github.com/crate-ci/typos) as a prek hook. +The hook is templated in `template/.pre-commit-config.yaml.j2`. +The word lists are **not** templated: each repository carries its own `typos.toml`, hand-maintained. + +That split is forced by the tool. typos has no layered configuration yet ([crate-ci/typos#193](https://github.com/crate-ci/typos/issues/193)). +Keeping the word lists local also means adding a word is a single PR in a single repository, rather than a PR here plus a sync to every managed repository. + +### The core config + +As convention, new repositories should start from this block and add only what they actually need. + +```toml +[files] +# Bare `typos` skips hidden directories, but prek passes explicit paths and so does +# check them. Turn it off so a local run and the hook agree; without it, .github/ +# and .readme/ are invisible locally but not to CI. +ignore-hidden = false + +extend-exclude = [ + # Required once ignore-hidden is off, or typos walks .git/objects. + ".git/", + # Generated by `make regenerate-nix` (crate2nix). + "Cargo.nix", + "crate-hashes.json", + # Generated by `make crds`. See "check each string once" below. + "extra/crds.yaml", + "deploy/helm/*/crds/crds.yaml", + # Diagram sources; the payload is base64 and produces only noise. + "*.drawio", + "*.drawio.svg", +] + +[default] +# typos has no native suppression directive (crate-ci/typos#316), so these regexes +# provide one. They cover `#`, `//`, ``, `;`, `/* */` and Jinja `{# #}` +# comments. Both failure modes are safe: an unterminated `:off` suppresses nothing +# rather than swallowing the rest of the file, and `disable-line` only matches when +# the marker ends the line, so trailing text defeats it instead of widening it. +extend-ignore-re = [ + "(?Rm)^.*(#|//||#\\}|\\*/)?\\s*$", + "(#|//||#\\}|\\*/)?\\s*\\n.*", + "(?s)(#|//||#\\}|\\*/|\")?.*?(#|//||#\\}|\\*/|\")?", +] + +[default.extend-words] +# Azure Kubernetes Service. Appears in the README footer and as the runner platform +# in tests/interu.yaml. A single lowercase entry covers every casing. +aks = "aks" +``` + +`aks` is the only word that is genuinely universal. +Everything else measured across the operator repositories turned out to be repo-local: `aas` in opa-operator, `shs` in spark-k8s-operator, base64 fixtures in secret-operator. +Short tokens that appear in several repositories (`ot`, `fo`) do so for unrelated reasons and belong in the repository that has them, not here. + +### Check each string once + +`extra/crds.yaml` is excluded on purpose. +Its content is generated: partly Kubernetes' own schema documentation, which is not ours to correct, and partly doc comments owned by `operator-rs` or by the operator's own `crd` module — both of which are already checked at their source. +The same applies to files rendered from `template/`: a typo in `template/.readme/partials/borrowed/footer.md.j2.j2` is caught here, once, instead of in all sixteen repositories. + +> [!NOTE] +> Excluding rendered content more thoroughly — everything a repository receives from `operator-templating` or `operator-rs` — is a known refinement that has not been done yet. +> The generated CRDs are the case that mattered in practice. + +### Conventions + +- The hook runs report-only. `args: ["--force-exclude"]`. +- Every entry in a `typos.toml` gets a one-line comment saying what the word is. +- Prefer an in-place marker over a config entry when the word is correct at one site and would still be a typo elsewhere: `spellchecker:disable-line` at the end of the line, `spellchecker:ignore-next-line` on the line above, or `spellchecker:off` / `:on` around a block. +- Licence and other verbatim third-party files are excluded, never corrected. + ## Making changes to the template If you want to make a change that should be rolled out to all operators, make the change in the `template` directory. diff --git a/template/.pre-commit-config.yaml.j2 b/template/.pre-commit-config.yaml.j2 index 8b73bcdf..2f56acbb 100644 --- a/template/.pre-commit-config.yaml.j2 +++ b/template/.pre-commit-config.yaml.j2 @@ -7,6 +7,20 @@ default_language_version: node: system repos: + # The word lists live in a per-repo `typos.toml`, which is deliberately NOT + # templated: typos has no layered configuration + # (https://github.com/crate-ci/typos/issues/193), so the nearest config file + # wins outright and a templated one could not be extended locally. Only the + # hook itself is shared, because it is identical everywhere. + - repo: https://github.com/crate-ci/typos + rev: v1.50.1 + hooks: + - id: typos + # Drop the upstream default `--write-changes` so the hook reports and + # fails instead of rewriting files. Keep `--force-exclude` so the + # excludes in typos.toml still apply to the paths prek passes in. + args: ["--force-exclude"] + - repo: https://github.com/pre-commit/pre-commit-hooks rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # 6.0.0 hooks: From 8fc24729231e48ec76d73b72694d9dbd2a61978b Mon Sep 17 00:00:00 2001 From: Maxi Wittich Date: Thu, 10 Sep 2026 13:01:09 +0200 Subject: [PATCH 2/2] Adding typos.toml --- typos.toml | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 typos.toml diff --git a/typos.toml b/typos.toml new file mode 100644 index 00000000..7811a496 --- /dev/null +++ b/typos.toml @@ -0,0 +1,52 @@ +# Configuration for typos (https://github.com/crate-ci/typos), run via the prek +# hook in .pre-commit-config.yaml. +# +# This config covers operator-templating itself. The operator repositories each +# carry their own typos.toml, which is deliberately NOT rolled out from +# template/: typos has no layered configuration +# (https://github.com/crate-ci/typos/issues/193), so the nearest config file +# wins outright and is never merged with one further up the tree. A templated +# config could not be extended with repo-specific words, and adding one word to +# one operator would otherwise mean a PR here plus a sync to all repositories. +# +# Only the hook is shared, via template/.pre-commit-config.yaml.j2. +# +# Before adding an entry here, consider an in-place marker instead. Use one when +# the word is correct at this one site and would still be a typo elsewhere: +# +# # spellchecker:disable-line at the end of the line it applies to +# # spellchecker:ignore-next-line on its own line, above the offending line +# # spellchecker:off / :on around a block +# +# Every entry below gets a one-line comment saying what the word is. + +[files] +# Bare `typos` skips hidden directories, but prek passes explicit paths and so +# does check them. Turn it off so both agree -- without this, template/.readme/ +# and template/.github/ are invisible to a local run but not to the hook. +ignore-hidden = false + +extend-exclude = [ + # `.git` itself, which ignore-hidden = false would otherwise pull in. + ".git/", +] + +[default] +# typos has no native suppression directive +# (https://github.com/crate-ci/typos/issues/316), so these regexes provide one. +# They cover `#`, `//`, ``, `;`, `/* */` and Jinja `{# #}` comments. +# +# Both failure modes are safe: an unterminated `:off` suppresses nothing rather +# than swallowing the rest of the file, and `disable-line` only matches when the +# marker ends the line, so trailing text defeats it instead of widening it. +extend-ignore-re = [ + "(?Rm)^.*(#|//||#\\}|\\*/)?\\s*$", + "(#|//||#\\}|\\*/)?\\s*\\n.*", + "(?s)(#|//||#\\}|\\*/|\")?.*?(#|//||#\\}|\\*/|\")?", +] + +[default.extend-words] +# Azure Kubernetes Service. Appears in the README footer partial that is +# rendered into every operator repository. A single lowercase entry covers +# every casing, so no separate `AKS` entry is needed. +aks = "aks"