lintsmith 0.0.16__tar.gz

lintsmith-0.0.16/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Build / test artifacts
+.coverage
+pytest-coverage.txt
+coverage.xml
+junit.xml
+htmlcov/
+node_modules/
+
+# Benchmark output
+bench-results.jsonl
+bench-*.jsonl
+results.md
+lint-*.log
+exit-*.txt
+
+.DS_Store
+
+# APM dependencies
+apm_modules/

lintsmith-0.0.16/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Meyer Elphick Frandsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lintsmith-0.0.16/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: lintsmith
+Version: 0.0.16
+Summary: Lean, tailored Super-Linter images: only the linters you enable, plus any extra tools you need.
+Project-URL: Homepage, https://github.com/ghwfxlab/lintsmith
+Project-URL: Repository, https://github.com/ghwfxlab/lintsmith
+Project-URL: Issues, https://github.com/ghwfxlab/lintsmith/issues
+Author: Peter Meyer Elphick Frandsen
+License: MIT
+License-File: LICENSE
+Keywords: ci-cd,docker,github-actions,linting,super-linter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# lintsmith
+
+Generate lean, pinned [Super-Linter](https://github.com/super-linter/super-linter)
+images that contain only the linters a repository uses, to cut the cold
+pull-and-unpack time in CI.
+
+Formerly `superlint-lean`. The old PyPI package and repository URL keep working, but
+new releases are published as `lintsmith`.
+
+Status: working, early. On GitHub-hosted runners a lean image pulls 5x to 8x
+faster than upstream `slim`:
+
+| Stack | Upstream slim | Lean | Faster |
+| --- | --- | --- | --- |
+| ghwm | 70.7 s | 10.7 s | 6.6x |
+| python | 67.9 s | 11.6 s | 5.9x |
+| frontend-react | 68.7 s | 10.4 s | 6.6x |
+| dotnet (against upstream standard) | 91.0 s | 16.9 s | 5.4x |
+
+Cold pull, median of 3, upstream v9.0.0. All profiles, the method and the
+caveats are in [docs/benchmarks](docs/benchmarks/README.md).
+
+## Idea
+
+1. A repository declares the linters it needs, or they are discovered from the
+   `VALIDATE_*` flags in its Super-Linter workflow.
+2. A compiler builds an overlay image: same Python/Alpine base as upstream, plus
+   only the needed tool paths copied from the upstream release image.
+3. A PR check fails when a change adds file types the current image does not
+   cover.
+4. A scheduled job rebuilds when upstream publishes a new release.
+5. The workflows are distributed through the ghwm registry; see
+   [Run the lean image with the ghwm registry workflows](docs/using-with-ghwm.md).
+
+## Install
+
+The CLI is a Python package, managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install lintsmith    # or: pipx install lintsmith
+uvx lintsmith --help         # run without installing
+```
+
+The latest unreleased code is available with
+`uvx --from git+https://github.com/ghwfxlab/lintsmith lintsmith --help`.
+
+Commands:
+
+| Command | Purpose |
+| --- | --- |
+| `lintsmith generate` | `VALIDATE_*` flags (env files or a workflow) -> Dockerfile, tool self-checks and plan |
+| `lintsmith drift` | PR drift check: fails when changed files are not covered by the enabled linters |
+| `lintsmith sync-mapping` | Compare the linter mapping with an upstream checkout and add draft entries |
+| `lintsmith release-notes` | Release notes with before/after benchmarks of two upstream versions |
+| `lintsmith compare`, `summarize` | Markdown tables from benchmark results: lean against baseline, and every variant on its own |
+| `lintsmith repository-settings` | Print or apply the repository settings in `docs/repository-settings.md` (maintainers) |
+| `lintsmith bench` | Time cold or warm pulls and container start of an image (the benchmark workflow) |
+| `lintsmith select-upstream` | Pick the upstream release to sync to, honouring a cooldown |
+| `lintsmith smoke` | Lint upstream's good and bad fixtures with a built image, one linter at a time |
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `src/lintsmith/` | The package: `cli.py`, `generate.py`, `drift.py`, `config.py` (reads workflows and env files with upstream's `VALIDATE_*` semantics), `mapping_sync.py`, `release_notes.py` |
+| `src/lintsmith/data/` | `linters.json` (flag -> upstream paths, venvs, npm and apk packages), `filetypes.json` (file type rules transcribed from upstream), `prune-node-modules.js` |
+| `tests/` | pytest suite (Arrange/Act/Assert), using the ghwm workflow as a fixture |
+| `base/opinionated.env` | The opinionated base: the checks almost every repository wants (EditorConfig, env, actionlint, zizmor, gitleaks, JSON, Markdown, natural language, YAML, shell, hadolint) |
+| `toolchains/` | Example toolchains on top of the base: python, Java, dotnet, rust, c-cpp, frontend-{vanilla,react,vue,angular,svelte}, base-only |
+| `examples/` | `ghwm.env` (a real repository's exact flags, without the base) and `with-extras.env` |
+| `.github/workflows/` | `tests`, `profiles` (benchmarks), `upstream-sync`, `release`, `self-image` (this repository's own lean image), and the reusable `drift-blocker` |
+
+## Development
+
+```sh
+make install          # uv sync
+make setup-precommit  # pre-commit hooks (super-linter and the tests)
+make test             # pytest with coverage
+make lint             # ruff
+make type-check       # mypy
+make lang             # textlint for the docs
+make super-linter     # super-linter via Docker
+make build            # sdist and wheel
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, [AGENTS.md](AGENTS.md)
+for the guide used by coding agents, [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+and [docs/reference/cli.md](docs/reference/cli.md) for the internals and the
+command reference, [docs/verifying-images.md](docs/verifying-images.md) to
+check a pulled image, and [docs/repository-settings.md](docs/repository-settings.md)
+for the repository settings. Report vulnerabilities as described in
+[SECURITY.md](SECURITY.md).
+
+## Configuration
+
+Nothing is fixed. The base and the toolchains are plain env files with
+`VALIDATE_*=true` lines, and the generator takes any combination of them:
+
+- leave the base out, or write your own
+- stack several toolchains (`--env toolchains/python.env --env toolchains/rust.env`)
+- drop single linters from a combination with `--exclude NATURAL_LANGUAGE`
+- add tools Super-Linter does not ship: Alpine packages (`--extra-apk`), npm
+  packages (`--extra-npm`) and pip packages (`--extra-pip`), plus `--extra-check`
+  commands that must succeed in the built image. They can also be written in an
+  env file (`EXTRA_APK=`, `EXTRA_NPM=`, `EXTRA_PIP=`, `EXTRA_CHECK=`), see
+  `examples/with-extras.env`. Extras are installed at build time from the
+  package registries, in their own layers (`/opt/extras`), and npm installs run
+  with `--ignore-scripts`
+
+The toolchains in this repository, and the numbers in
+[docs/benchmarks](docs/benchmarks/README.md), are examples of combinations, not
+the supported set.
+
+The reason for an opinionated base is that a repository using one linter has no
+use for Super-Linter. The value is in running a broad set of checks, so the base
+is broad and each toolchain adds a stack on top.
+
+## Block pull requests that outgrow the image
+
+The image only contains the linters you enabled. If a pull request adds a file
+type whose linters are not enabled (a `.rs` file when no Rust linter is on),
+Super-Linter would silently skip it. The drift blocker fails that pull request
+and says which linter to enable:
+
+```yaml
+jobs:
+  drift:
+    permissions:
+      contents: read
+    uses: ghwfxlab/lintsmith/.github/workflows/drift-blocker.yml@main
+    with:
+      workflow: .github/workflows/super-linter.yaml   # the workflow with the super-linter step
+      allow_ext: "txt lock"                    # file types you deliberately do not lint
+```
+
+The configuration is read from the `env:` of the Super-Linter step, with the
+upstream rules: if any `VALIDATE_X` is `true`, only those linters run; if only
+`false` values are set, everything else runs. `FILTER_REGEX_INCLUDE` and
+`FILTER_REGEX_EXCLUDE` are respected. The same discovery works in the compiler:
+`lintsmith generate --workflow .github/workflows/super-linter.yaml ...`. Content-based
+detections (OpenAPI, CloudFormation, Kubernetes, ARM, AWS States, Ansible) are
+not modelled, so a YAML file of those kinds is only checked as plain YAML.
+
+## Try it locally
+
+```sh
+lintsmith generate --env base/opinionated.env --env toolchains/python.env \
+  --upstream-tag v9.0.0 --upstream-dockerfile <upstream Dockerfile at that tag> --out build/python
+docker buildx build build/python -t lean-python
+docker run --rm -v "$PWD/build/python/checks.sh:/checks.sh:ro" --entrypoint bash lean-python /checks.sh
+```
+
+Profiles marked as needing the upstream `standard` image (dotnet, rust) are
+compared against `standard`, not `slim`. Upstream has no Svelte-specific linter,
+so the Svelte profile covers the JS, TS, CSS and HTML around it.
+
+## Limitations
+
+- Only linters in the mapping (`src/lintsmith/data/linters.json`, 95 flags
+  for upstream v9.0.0) can be selected. An unknown flag stops `generate` with a
+  message, and new upstream linters start as drafts that need a review (see
+  [CONTRIBUTING.md](CONTRIBUTING.md#extending-the-mapping)).
+- The generator reads upstream's published image and `Dockerfile`. A release
+  that moves tools around can break the mapping; `upstream-sync` reports it
+  before the pin moves.
+- The image is rebuilt after a change reaches `main`. A pull request that
+  changes the enabled linters is still linted with the previous image, and the
+  drift check only catches file types that no enabled linter covers.
+- The saving comes from leaving linters out. With every mapped linter enabled the
+  image is only about 11% smaller than upstream standard.
+- A runner that already holds the upstream image gains nothing: the pull is a
+  no-op either way.
+- Pulling a private image needs credentials: `packages: read` for GHCR in the
+  same organization, otherwise a registry login.
+- Only `linux/amd64` is tested. Images are not signed yet.
+- zstd layers are published and pull 0% to 15% faster than gzip; that is small next to leaving linters out.
+
+## Licence
+
+This repository is MIT licensed (see [LICENSE](LICENSE)). It contains no
+third-party linters. A generated image is built by copying files out of the
+published Super-Linter image, so it contains Super-Linter (MIT) and the linters
+you select, each under its own licence. If you publish such an image you
+redistribute those tools and must follow their licences; check them for the
+linters you pick. The smoke test reads Super-Linter's test fixtures at build
+time and does not copy them into this repository or into an image.

lintsmith-0.0.16/README.md

@@ -0,0 +1,186 @@
+# lintsmith
+
+Generate lean, pinned [Super-Linter](https://github.com/super-linter/super-linter)
+images that contain only the linters a repository uses, to cut the cold
+pull-and-unpack time in CI.
+
+Formerly `superlint-lean`. The old PyPI package and repository URL keep working, but
+new releases are published as `lintsmith`.
+
+Status: working, early. On GitHub-hosted runners a lean image pulls 5x to 8x
+faster than upstream `slim`:
+
+| Stack | Upstream slim | Lean | Faster |
+| --- | --- | --- | --- |
+| ghwm | 70.7 s | 10.7 s | 6.6x |
+| python | 67.9 s | 11.6 s | 5.9x |
+| frontend-react | 68.7 s | 10.4 s | 6.6x |
+| dotnet (against upstream standard) | 91.0 s | 16.9 s | 5.4x |
+
+Cold pull, median of 3, upstream v9.0.0. All profiles, the method and the
+caveats are in [docs/benchmarks](docs/benchmarks/README.md).
+
+## Idea
+
+1. A repository declares the linters it needs, or they are discovered from the
+   `VALIDATE_*` flags in its Super-Linter workflow.
+2. A compiler builds an overlay image: same Python/Alpine base as upstream, plus
+   only the needed tool paths copied from the upstream release image.
+3. A PR check fails when a change adds file types the current image does not
+   cover.
+4. A scheduled job rebuilds when upstream publishes a new release.
+5. The workflows are distributed through the ghwm registry; see
+   [Run the lean image with the ghwm registry workflows](docs/using-with-ghwm.md).
+
+## Install
+
+The CLI is a Python package, managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install lintsmith    # or: pipx install lintsmith
+uvx lintsmith --help         # run without installing
+```
+
+The latest unreleased code is available with
+`uvx --from git+https://github.com/ghwfxlab/lintsmith lintsmith --help`.
+
+Commands:
+
+| Command | Purpose |
+| --- | --- |
+| `lintsmith generate` | `VALIDATE_*` flags (env files or a workflow) -> Dockerfile, tool self-checks and plan |
+| `lintsmith drift` | PR drift check: fails when changed files are not covered by the enabled linters |
+| `lintsmith sync-mapping` | Compare the linter mapping with an upstream checkout and add draft entries |
+| `lintsmith release-notes` | Release notes with before/after benchmarks of two upstream versions |
+| `lintsmith compare`, `summarize` | Markdown tables from benchmark results: lean against baseline, and every variant on its own |
+| `lintsmith repository-settings` | Print or apply the repository settings in `docs/repository-settings.md` (maintainers) |
+| `lintsmith bench` | Time cold or warm pulls and container start of an image (the benchmark workflow) |
+| `lintsmith select-upstream` | Pick the upstream release to sync to, honouring a cooldown |
+| `lintsmith smoke` | Lint upstream's good and bad fixtures with a built image, one linter at a time |
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `src/lintsmith/` | The package: `cli.py`, `generate.py`, `drift.py`, `config.py` (reads workflows and env files with upstream's `VALIDATE_*` semantics), `mapping_sync.py`, `release_notes.py` |
+| `src/lintsmith/data/` | `linters.json` (flag -> upstream paths, venvs, npm and apk packages), `filetypes.json` (file type rules transcribed from upstream), `prune-node-modules.js` |
+| `tests/` | pytest suite (Arrange/Act/Assert), using the ghwm workflow as a fixture |
+| `base/opinionated.env` | The opinionated base: the checks almost every repository wants (EditorConfig, env, actionlint, zizmor, gitleaks, JSON, Markdown, natural language, YAML, shell, hadolint) |
+| `toolchains/` | Example toolchains on top of the base: python, Java, dotnet, rust, c-cpp, frontend-{vanilla,react,vue,angular,svelte}, base-only |
+| `examples/` | `ghwm.env` (a real repository's exact flags, without the base) and `with-extras.env` |
+| `.github/workflows/` | `tests`, `profiles` (benchmarks), `upstream-sync`, `release`, `self-image` (this repository's own lean image), and the reusable `drift-blocker` |
+
+## Development
+
+```sh
+make install          # uv sync
+make setup-precommit  # pre-commit hooks (super-linter and the tests)
+make test             # pytest with coverage
+make lint             # ruff
+make type-check       # mypy
+make lang             # textlint for the docs
+make super-linter     # super-linter via Docker
+make build            # sdist and wheel
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, [AGENTS.md](AGENTS.md)
+for the guide used by coding agents, [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+and [docs/reference/cli.md](docs/reference/cli.md) for the internals and the
+command reference, [docs/verifying-images.md](docs/verifying-images.md) to
+check a pulled image, and [docs/repository-settings.md](docs/repository-settings.md)
+for the repository settings. Report vulnerabilities as described in
+[SECURITY.md](SECURITY.md).
+
+## Configuration
+
+Nothing is fixed. The base and the toolchains are plain env files with
+`VALIDATE_*=true` lines, and the generator takes any combination of them:
+
+- leave the base out, or write your own
+- stack several toolchains (`--env toolchains/python.env --env toolchains/rust.env`)
+- drop single linters from a combination with `--exclude NATURAL_LANGUAGE`
+- add tools Super-Linter does not ship: Alpine packages (`--extra-apk`), npm
+  packages (`--extra-npm`) and pip packages (`--extra-pip`), plus `--extra-check`
+  commands that must succeed in the built image. They can also be written in an
+  env file (`EXTRA_APK=`, `EXTRA_NPM=`, `EXTRA_PIP=`, `EXTRA_CHECK=`), see
+  `examples/with-extras.env`. Extras are installed at build time from the
+  package registries, in their own layers (`/opt/extras`), and npm installs run
+  with `--ignore-scripts`
+
+The toolchains in this repository, and the numbers in
+[docs/benchmarks](docs/benchmarks/README.md), are examples of combinations, not
+the supported set.
+
+The reason for an opinionated base is that a repository using one linter has no
+use for Super-Linter. The value is in running a broad set of checks, so the base
+is broad and each toolchain adds a stack on top.
+
+## Block pull requests that outgrow the image
+
+The image only contains the linters you enabled. If a pull request adds a file
+type whose linters are not enabled (a `.rs` file when no Rust linter is on),
+Super-Linter would silently skip it. The drift blocker fails that pull request
+and says which linter to enable:
+
+```yaml
+jobs:
+  drift:
+    permissions:
+      contents: read
+    uses: ghwfxlab/lintsmith/.github/workflows/drift-blocker.yml@main
+    with:
+      workflow: .github/workflows/super-linter.yaml   # the workflow with the super-linter step
+      allow_ext: "txt lock"                    # file types you deliberately do not lint
+```
+
+The configuration is read from the `env:` of the Super-Linter step, with the
+upstream rules: if any `VALIDATE_X` is `true`, only those linters run; if only
+`false` values are set, everything else runs. `FILTER_REGEX_INCLUDE` and
+`FILTER_REGEX_EXCLUDE` are respected. The same discovery works in the compiler:
+`lintsmith generate --workflow .github/workflows/super-linter.yaml ...`. Content-based
+detections (OpenAPI, CloudFormation, Kubernetes, ARM, AWS States, Ansible) are
+not modelled, so a YAML file of those kinds is only checked as plain YAML.
+
+## Try it locally
+
+```sh
+lintsmith generate --env base/opinionated.env --env toolchains/python.env \
+  --upstream-tag v9.0.0 --upstream-dockerfile <upstream Dockerfile at that tag> --out build/python
+docker buildx build build/python -t lean-python
+docker run --rm -v "$PWD/build/python/checks.sh:/checks.sh:ro" --entrypoint bash lean-python /checks.sh
+```
+
+Profiles marked as needing the upstream `standard` image (dotnet, rust) are
+compared against `standard`, not `slim`. Upstream has no Svelte-specific linter,
+so the Svelte profile covers the JS, TS, CSS and HTML around it.
+
+## Limitations
+
+- Only linters in the mapping (`src/lintsmith/data/linters.json`, 95 flags
+  for upstream v9.0.0) can be selected. An unknown flag stops `generate` with a
+  message, and new upstream linters start as drafts that need a review (see
+  [CONTRIBUTING.md](CONTRIBUTING.md#extending-the-mapping)).
+- The generator reads upstream's published image and `Dockerfile`. A release
+  that moves tools around can break the mapping; `upstream-sync` reports it
+  before the pin moves.
+- The image is rebuilt after a change reaches `main`. A pull request that
+  changes the enabled linters is still linted with the previous image, and the
+  drift check only catches file types that no enabled linter covers.
+- The saving comes from leaving linters out. With every mapped linter enabled the
+  image is only about 11% smaller than upstream standard.
+- A runner that already holds the upstream image gains nothing: the pull is a
+  no-op either way.
+- Pulling a private image needs credentials: `packages: read` for GHCR in the
+  same organization, otherwise a registry login.
+- Only `linux/amd64` is tested. Images are not signed yet.
+- zstd layers are published and pull 0% to 15% faster than gzip; that is small next to leaving linters out.
+
+## Licence
+
+This repository is MIT licensed (see [LICENSE](LICENSE)). It contains no
+third-party linters. A generated image is built by copying files out of the
+published Super-Linter image, so it contains Super-Linter (MIT) and the linters
+you select, each under its own licence. If you publish such an image you
+redistribute those tools and must follow their licences; check them for the
+linters you pick. The smoke test reads Super-Linter's test fixtures at build
+time and does not copy them into this repository or into an image.

lintsmith-0.0.16/docs/benchmarks/README.md

@@ -0,0 +1,185 @@
+# Benchmarks
+
+Question: how much faster is a lean image than upstream `slim` on a cold runner,
+and is that enough to justify this tool?
+
+## Go / no-go
+
+Go if the lean image for the first target (ghwm) pulls in about 20 s or less, or
+is at least 3x faster than slim on a **GitHub-hosted** runner. Otherwise the
+honest outcome is a "slim plus caching" write-up.
+
+**Verdict: go.** On a GitHub-hosted runner the ghwm image pulls in 10.7 s against
+70.7 s for slim (6.6x), and every example profile is at least 5x faster.
+
+## When benchmarks run
+
+Nothing runs on upstream's behalf unless upstream has a newer release than the
+one pinned in `upstream-version.txt`:
+
+1. The weekly `upstream-sync` run makes one API call. If the pin is current it
+   stops there, with no checkout of upstream, no build and no benchmark.
+2. If upstream is ahead it adds missing linters to the mapping, checks them with
+   an all-linters image and opens a pull request that bumps the pin.
+3. Merging that pull request runs the `release` workflow: it benchmarks the old
+   version (only if no results are stored for it) and the new one with the same
+   profiles, and publishes a GitHub release `upstream-<tag>` whose notes show
+   the numbers before and after (`scripts/release_notes.py`).
+
+Results are stored on the `bench-results` branch under `results/by-tag/<tag>/`.
+The profiles used for releases come from the repository variable
+`RELEASE_PROFILES` (default `ghwm,python,frontend-react,dotnet`). Starting the
+`Toolchain benchmark` workflow by hand is still possible, as an explicit
+decision, for example to add a profile to the stored results.
+
+## Pipeline under test
+
+config -> create image -> push to GHCR -> pull on a runner. The "create
+image" step is `lintsmith generate` followed by `docker build`. Each
+scenario compares upstream slim ("without") with the generated lean image
+("with").
+
+## Scenarios
+
+1. **Cold, GitHub-hosted runner.** Headline number: what most users pay.
+2. **Cold, self-hosted runner.** Image removed before each pull.
+3. **Warm, self-hosted runner with the full image preloaded.** Tests whether a
+   smaller image helps when nothing has to be downloaded. Expect little change
+   in pull time; start time and disk use are the other things to look at.
+4. **Upgrade pull** (not yet automated): previous upstream tag present, pull the
+   next. Needs a second build.
+
+## Method
+
+- Workflow: `.github/workflows/profiles.yaml` (manual dispatch or called by the release workflow, one job per stack profile; runs on `ubuntu-latest` unless the `RUNNER_LABELS` repository variable or the `runner_labels` input says otherwise).
+- Variants:
+  - `slim`: `ghcr.io/super-linter/super-linter:slim-<tag>`
+  - `lean-gzip`: generated Dockerfile, default gzip layers
+  - `lean-zstd`: same image, zstd-compressed layers
+- Runners: `ubuntu-latest` (headline numbers) and optionally a self-hosted runner (repository variable `RUNNER_LABELS`), cold and warm (`BENCH_MODE`).
+- Each run removes the image locally, then times `docker pull`. With `crane`
+  available it also records a download-only pull and a `docker load`, giving a
+  rough download vs unpack split.
+- Median of N runs (default 5). Sizes are compressed layer size and
+  uncompressed image size.
+
+Self-hosted numbers are secondary. Runners that keep layers between jobs, or
+that sit close to the registry, will make every variant look faster than most
+users will see.
+
+## Caveats
+
+- `/action/linterVersions.txt` lists all upstream tools, not only the kept ones.
+- The self-hosted zstd numbers below come from a run before the cold-pull
+  cleanup of `lintsmith bench`. Within that run the zstd pull followed the
+  gzip pull of the same image, so they may be too low.
+
+## What the benchmark covers
+
+The tool is fully configurable, so the benchmark is only a set of example
+combinations: the opinionated base plus one example toolchain each
+(`toolchains/`), and the ghwm repository's exact flags (`examples/ghwm.env`).
+There are no single-linter profiles on purpose: a repository that needs one
+linter has no reason to use Super-Linter. `base-only` measures the base on its
+own, as the floor for the toolchains.
+
+## Results
+
+### GitHub-hosted runner (headline)
+
+Run 38303678148, upstream v9.0.0, `ubuntu-latest`, median of 3 cold pulls. Before
+every cold pull the script removes the image, every other unused image and the
+build cache, so no variant can reuse another's layers. The upstream baseline is
+`slim-v9.0.0`, except rust and dotnet, which need `standard-v9.0.0`. Every
+profile except `ghwm` is the shared base (`base/opinionated.env`) plus its stack
+flags. Raw data is on the `bench-results` branch under `results/by-tag/v9.0.0/`.
+
+| Profile | Upstream pull | Lean gzip | Lean zstd | Faster (gzip) | Faster (zstd) | Compressed: upstream to lean |
+| --- | --- | --- | --- | --- | --- | --- |
+| ghwm | 70.7 s | 10.7 s | 9.8 s | 6.6x | 7.2x | 1310 to 170 MB (-87%) |
+| python | 67.9 s | 11.6 s | 11.5 s | 5.9x | 5.9x | 1310 to 210 MB (-84%) |
+| Java | 68.3 s | 10.7 s | 9.7 s | 6.4x | 7.0x | 1310 to 233 MB (-82%) |
+| c-cpp | 77.6 s | 11.0 s | 10.5 s | 7.1x | 7.4x | 1310 to 156 MB (-88%) |
+| frontend-vanilla | 68.3 s | 9.8 s | 8.6 s | 7.0x | 8.0x | 1310 to 152 MB (-88%) |
+| frontend-react | 68.7 s | 10.4 s | 9.4 s | 6.6x | 7.3x | 1310 to 156 MB (-88%) |
+| frontend-vue | 68.3 s | 9.5 s | 8.7 s | 7.2x | 7.8x | 1310 to 152 MB (-88%) |
+| frontend-angular | 68.7 s | 9.5 s | 8.8 s | 7.2x | 7.8x | 1310 to 152 MB (-88%) |
+| frontend-svelte | 68.5 s | 9.6 s | 8.7 s | 7.2x | 7.9x | 1310 to 152 MB (-88%) |
+| base-only | 59.7 s | 8.4 s | 8.2 s | 7.1x | 7.3x | 1310 to 150 MB (-89%) |
+| rust | 81.2 s | 14.1 s | 14.3 s | 5.8x | 5.7x | 1798 to 376 MB (-79%) |
+| dotnet | 91.0 s | 16.9 s | 15.4 s | 5.4x | 5.9x | 1798 to 378 MB (-79%) |
+
+What to take from it:
+
+- A lean image pulls 5x to 8x faster, because 79% to 89% fewer compressed bytes
+  have to be downloaded and unpacked. The saving is about the same for every
+  stack that only drops other stacks' tools.
+- zstd layers pull 0% to 15% faster than gzip layers (up to 1.5 s), a small
+  extra gain on top of the 5x to 8x. Docker on the runner decompresses both
+  without trouble.
+- Baseline drift (first cold readings against the end-of-run bracket) stayed at
+  9% or below on every profile.
+- Warm runner (image already present): pull is a no-op (0.2 s to 0.7 s) for both
+  images. A smaller image does not help a runner that already holds the full one.
+- The "unpacked" sizes on this runner (3995 MB for slim) are lower than on the
+  self-hosted runner (5789 MB). The reason is not established, so only
+  compressed sizes are compared above (tracked in #30).
+
+An earlier hosted run (38284154555) reported zstd cold pulls of 0.2 s to 0.7 s.
+That was a measurement error: the zstd pull reused the layers of the gzip image
+still on the runner. It is fixed in `lintsmith bench` and those numbers
+were replaced by this run.
+
+### Self-hosted runner (secondary)
+
+Self-hosted numbers are secondary: a runner that keeps layers between jobs, or
+sits close to the registry, makes every variant look faster than most users will
+see.
+
+Run 38144305432, upstream v9.0.0, a self-hosted runner (Proxmox VM,
+2 CPU, 4 GB RAM, 40 GB disk), median of 3 cold pulls. Baseline is upstream
+`slim-v9.0.0`. Every profile except `ghwm` is the shared base
+(`base/opinionated.env`) plus its stack flags. Raw data is on the `bench-results`
+branch under `results/2026-10-11-run-38144305432/`.
+
+| Profile | Baseline pull | Lean gzip | Lean zstd | Unpacked: base to lean | Compressed: base to lean | Build gzip+zstd (incl. push) |
+| --- | --- | --- | --- | --- | --- | --- |
+| ghwm | 75.6 s | 10.2 s | 4.6 s | 5789 to 771 MB (-87%) | 1310 to 170 MB (-87%) | 129 s |
+| python | 73.4 s | 12.4 s | 5.7 s | 5789 to 965 MB (-83%) | 1310 to 210 MB (-84%) | 153 s |
+| Java | 71.7 s | 13.2 s | 5.3 s | 5789 to 1004 MB (-83%) | 1310 to 233 MB (-82%) | 182 s |
+| c-cpp | 69.2 s | 9.8 s | 3.6 s | 5789 to 726 MB (-87%) | 1310 to 156 MB (-88%) | 124 s |
+| frontend-vanilla | 71.1 s | 9.4 s | 3.4 s | 5789 to 722 MB (-88%) | 1310 to 152 MB (-88%) | 128 s |
+| frontend-react | 71.1 s | 9.7 s | 3.6 s | 5789 to 755 MB (-87%) | 1310 to 156 MB (-88%) | 133 s |
+| frontend-vue | 71.3 s | 9.3 s | 3.6 s | 5789 to 722 MB (-88%) | 1310 to 152 MB (-88%) | 130 s |
+| frontend-angular | 72.7 s | 8.9 s | 3.7 s | 5789 to 722 MB (-88%) | 1310 to 152 MB (-88%) | 135 s |
+| frontend-svelte | 71.9 s | 9.2 s | 4.1 s | 5789 to 722 MB (-88%) | 1310 to 152 MB (-88%) | 139 s |
+| rust | 96.0 s | 16.9 s | 6.6 s | 7885 to 1540 MB (-80%) | 1798 to 376 MB (-79%) | 177 s |
+| dotnet | 98.6 s | 15.1 s | 7.8 s | 7885 to 1555 MB (-80%) | 1798 to 378 MB (-79%) | 200 s |
+
+Warm runner (image already present): pull is a no-op, about 1.5 s for the
+baseline and 0.9 s for lean; container start 0.4 s vs 0.3 s. A smaller image
+does not make a runner that already holds the full image meaningfully faster.
+
+Baseline drift (first vs last cold pull) stayed within 5% on every profile.
+Build time is gzip and zstd together; later runs record them separately.
+
+dotnet and rust (run 38152523859, same runner) are compared against the upstream
+`standard` image (`v9.0.0`), which is larger than slim: 7885 MB unpacked, 1798 MB
+compressed. Their baseline drift was 2% and 13%. In that run the build time was
+recorded per variant (gzip 167 s / zstd 32 s for dotnet, 141 s / 36 s for rust).
+The zstd build runs second and reuses the build cache, so its time is not a
+fair cold-build number.
+
+### Every mapped linter at once
+
+Run 38165304659 built an image with all 95 mapped flags (`all-linters`, based on
+upstream `standard`) to verify the mapping: 80 tool checks ran and all tools
+worked (the one reported failure was a false positive in the checker, fixed).
+The lean image is 7037 MB unpacked and 1679 MB compressed against 7885 MB and
+1798 MB for upstream standard, with a cold pull of 72.4 s (gzip) and 26.5 s
+(zstd). With every linter enabled the size saving is only about 11%, as expected:
+the saving comes from leaving linters out, so the tool pays off for repositories
+that use a subset. The baseline pull of this run did not complete.
+
+Open: the upgrade-pull scenario (previous tag present, new tag pulled) and why
+unpacked sizes differ between the two runners.