From 9be09ead336f9c53c6195cb655556a652f40ee9b Mon Sep 17 00:00:00 2001 From: afadesigns Date: Fri, 26 Jun 2026 02:52:56 +0200 Subject: [PATCH] docs: correct CLI and integration sweep claims A documentation audit, verified against the live binary and the pinned corpus manifest, surfaced five accuracy gaps: - `-no-color` is not implied for a non-TTY: the binary has no isatty detection and emits ANSI even when piped. Drop the false auto-disable claim; colour is on by default and `-no-color` turns it off. - A parse error emits a well-formed report (JSON an empty array, SARIF a valid run with an empty `results` list), not nothing. Correct the FAQ. - Document exit code 2 for a command-line parsing error (an unknown flag or a flag missing its value); an invalid flag value stays exit 1. - INTEGRATIONS.md and README claimed every listed integration runs the per-release sweep, but the heaviest Featured trees (oh-my-zsh, powerlevel10k, zsh-syntax-highlighting) are swept manually, not in the pinned gate. Qualify the claim to the pinned corpus matrix. Signed-off-by: afadesigns --- INTEGRATIONS.md | 6 ++++-- README.md | 4 ++-- docs/USER_GUIDE.md | 10 ++++++---- 3 files changed, 12 insertions(+), 8 deletions(-) diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index 5cd19b50..3ab8020f 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -1,7 +1,8 @@ # Integrations ZShellCheck is verified against the script trees of widely used Zsh integrations. -Every release runs a parse and lint sweep over each — no panics, no crashes, deterministic output. +Every release runs a parse and lint sweep over the pinned corpus matrix — no panics, no crashes, deterministic output. +The heaviest Featured trees are swept manually rather than in the per-release gate, because their clones are too large to pin in CI. The list grows with every release. ## Featured @@ -140,7 +141,8 @@ To propose another corpus, follow [Adding an integration](#adding-an-integration ## How the sweep runs -Each release tag triggers a parse and lint pass over every integration listed in the **Featured** and per-category tables. +Each release tag triggers a parse and lint pass over every integration in the pinned corpus matrix. +The heaviest Featured trees, whose clones are too large to pin in CI, are swept manually instead. Each pass produces: - `parse_errors` — total parser failures across the integration. diff --git a/README.md b/README.md index 685a0757..2c679b42 100644 --- a/README.md +++ b/README.md @@ -115,8 +115,8 @@ Pin `@latest` and `rev: latest` to a tag from [Releases](https://github.com/afad ## Integrations ZShellCheck is verified against widely used Zsh frameworks, plugin managers, plugins, and prompts on every release. -Each runs a parse-and-findings sweep: zero parser errors, zero crashes, and kata findings locked to a reviewed baseline. -The full catalog with file counts lives in [INTEGRATIONS.md](INTEGRATIONS.md). +The pinned corpus matrix runs a parse-and-findings sweep: zero parser errors, zero crashes, and kata findings locked to a reviewed baseline. +The heaviest trees are swept manually; the full catalog with file counts lives in [INTEGRATIONS.md](INTEGRATIONS.md). | Category | Examples | | :--- | :--- | diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index a5edb4a1..3ba25c00 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -40,7 +40,7 @@ Files with `.go`, `.md`, `.json`, `.yml`, `.yaml`, or `.txt` extensions are skip | `-add-noka` | off | Append a `# noka: ZC####` directive to every line with a finding, write the files, and exit. | | `-detect-stale-noka` | off | Report `# noka` directives that suppress no actual finding; exit non-zero if any. | | `-verbose` | off | Emit full kata descriptions in text output. | -| `-no-color` | off | Disable ANSI colours. Implied when stdout is not a TTY. | +| `-no-color` | off | Disable ANSI colours in the report. | | `-no-banner` | off | Suppress the startup banner. Implied for JSON and SARIF output and when `-no-color` is set. | | `-cpuprofile ` | — | Write a Go pprof CPU profile to `` for benchmarking. | | `-fix` | off | Apply auto-fixes in place. Safe (value-preserving) fixes only, unless `-unsafe-fixes` is set. | @@ -57,7 +57,8 @@ Files with `.go`, `.md`, `.json`, `.yml`, `.yaml`, or `.txt` extensions are skip | Code | Meaning | | ---: | --- | | `0` | No violations. | -| `1` | One or more violations, a parse error, or a usage error. | +| `1` | One or more violations, a parse error, or an invalid flag value. | +| `2` | A command-line parsing error: an unknown flag, or a flag missing its value. | ### Examples @@ -330,9 +331,10 @@ The set of fixable katas is listed in [KATAS.md](../KATAS.md) — every entry ca `-fix` runs multi-pass (up to five iterations) so nested rewrites resolve in a single invocation. Pair `-fix` with `-dry-run` to report what would change without writing. -### The SARIF output is empty after a parse error. Why? +### Why does a file with a parse error report no findings? -When the parser rejects a file, ZShellCheck exits before katas run; there is nothing to emit. +A parse error stops ZShellCheck before the katas run, so the file yields no findings and the run exits `1`. +The machine-readable formats still emit a well-formed document — JSON an empty array, SARIF a valid run with an empty `results` list — so downstream tooling always receives parseable output. Fix the syntax (`zsh -n file.zsh` is a fast sanity check), or open an issue when valid Zsh is being rejected. ### Where does ZShellCheck look for config?