[nmbro]

Make the script and documentation checks report problems where they are, on the changed lines, instead of somewhere in a long CI log, and add a ShellCheck check for the shell scripts that a PR changes.

Problem

• Spellcheck errors are hard to find. make spellcheck printed unknown words with egrep -b byte offsets into the aspell output (e.g. 18011:& backticks 13 16: ...), not with a location in the source document. In CI, the failure is somewhere in the step log.
• No real ShellCheck. make shellcheck is only a syntax check (sh -n/bash -n) with the system /bin/sh. Running the real shellcheck on the tree gives about 2900 findings (28 errors, 258 warnings), mostly deliberate portability idioms or old code, so checking the whole tree would always fail.
• make shellcheck noise and coverage (Ignore $(...) vs backtick syntax warning in make shellcheck #1058, Extend make shellcheck to support our SHELL_PROGS envvar from some of the tests #1059): ksh93 (the /bin/sh on illumos and Solaris) prints a "... obsolete, use $(...)" warning for every backtick in syntax-check mode: 1442 of them for 47 scripts on current master, which buried the 15 other warnings it had. And there was no way to check with other shells than /bin/sh.
• aspell resources on CentOS 7 (CI: More fixes for aspell usage on stranger platforms #2068): configure did not look in lib64, nor in aspell-0.60 style directories for a 4-component version like 0.60.6.1.

Changes

1. build: SHELL_PROGS for make shellcheck -- make shellcheck (check-scripts-syntax) checks POSIX shell scripts with each interpreter listed in SHELL_PROGS (default still /bin/sh), like the NDE self-test already does; bash scripts are still checked with bash, and the error names the shell. The backticks warning is filtered out (keeping the syntax check exit code). Closes Ignore $(...) vs backtick syntax warning in make shellcheck #1058, closes Extend make shellcheck to support our SHELL_PROGS envvar from some of the tests #1059.
2. ci: add ShellCheck check for changed scripts -- a new "GHA-07: ShellCheck" workflow for PRs runs tools/shellcheck-ci.pl, which checks the base and PR versions of the changed shell scripts and reports only new findings, matched by file, ShellCheck code and source line text (so moved code does not count as new). New "warning"/"error" findings fail the check; new "note" (info/style) ones are shown as notices. Findings show as annotations on the changed lines and in the job summary. The helper is Perl (like tools/check-source-nonascii.pl; Perl is already needed by autogen.sh in Git workspaces), uses only core Perl 5 modules and the gcc output format of shellcheck (no JSON module needed), and can be run locally: perl tools/shellcheck-ci.pl origin/master. A new .shellcheckrc disables the checks for deliberate NUT portability idioms: backticks (SC2006, the ShellCheck side of Ignore $(...) vs backtick syntax warning in make shellcheck #1058), x"$var" comparisons (SC2268) and expr (SC2003); it is distributed like .editorconfig. The workflow uses only actions/checkout, read-only permissions, and compares the PR merge commit with its first parent.
3. docs: locate spellcheck errors, annotate in GHA -- unknown words are reported as file:line:col: <aspell result line>, with paths relative to the source root. In GitHub Actions they also become annotations on the source lines and a table in the job summary, each word once (the top-level recipe collects them, because the sequential retry after a failed parallel attempt and the ci_build.sh re-runs report the same errors again, and annotations per step are limited). No annotations with SPELLCHECK_ERROR_FATAL=no (the distcheck steps).
4. m4: find aspell resources in lib64 and X.Y dirs -- also try ../lib64 and the major.minor version directory. The other part of CI: More fixes for aspell usage on stranger platforms #2068 (only enable spellcheck if aspell actually works) was already done by the live check from e519320, verified with a missing dictionary. Closes CI: More fixes for aspell usage on stranger platforms #2068.

Docs: docs/qa-guide.adoc (shell script and spelling checks sections), NEWS.adoc.

Example from the field

A test run of this branch on my fork showed what this is for: the "Spellcheck with old aspell-en 7.1 (as on CentOS 7)" job, which then failed for every PR, annotated docs/man/microdowell.txt:42:14 with initialisation from #3744, which is not in the old dictionary (commented there, since fixed by 3cb4c2f). Without this change, finding that needed a read through the job log.

Screenshots

From a test PR on my fork with deliberate findings (not part of this PR):

Testing

• tools/shellcheck-ci.pl: the first version of build: keep full git version out of config.h (ccache-friendly) #3759 is reported for its one new SC2166 warning ([ p -a q ]), the final version passes; renamed, added, removed and non-shell files; a bad base revision (exit 2); local and GitHub Actions output modes.
• make shellcheck SHELL_PROGS="dash ksh bash" (ksh 93u+m/1.0.8): passes, no backticks warnings left, other ksh warnings still shown; syntax errors in a POSIX or bash script fail, naming the file and shell.
• Spellcheck with typos in NEWS.adoc, docs/man/upsc.txt and scripts/upsdrvsvcctl/README.adoc: correct file, line and column; each annotation and summary row once, also via BUILD_TYPE=default-spellcheck ./ci_build.sh; none with SPELLCHECK_ERROR_FATAL=no or without GITHUB_ACTIONS.
• configure with a fake CentOS 7 aspell layout (version 0.60.6.1, resources in lib64/aspell-0.60): found where master found none, and make spellcheck passes with that --filter-path; unchanged paths on Ubuntu.
• Test PR on my fork: annotations and job summaries for ShellCheck and both spellcheck jobs (current and old aspell-en).
• actionlint 1.7.7 and zizmor 1.25.2 on the workflow, make spellcheck, make distcheck-light, ASCII-only check on the changes.

Open questions

• The new .shellcheckrc dotfile in the source root, and its list of disabled checks: are there other idioms that should be in it?
• Should new ShellCheck "warning" findings fail the check, or only "error" ones at first?

Checklist

• Described the changes in the PR submission
• Multiple commits, each with a functional change
• Use of coding helper tools and AI disclosed: Claude Code was used for development assistance
• Revised for NUT code style and ASCII-only text
• For newly added files, the Makefile.am recipes were updated and make distcheck-light passes
• Added bullet points into NEWS.adoc
• Passed make spellcheck, updated docs/nut.dict (no words removed)

🤖 Generated with Claude Code

[github-actions]

A ZIP file with standard source tarball and another tarball with pre-built docs for commit ce43b09 is temporarily available: NUT-tarballs-PR-3773.zip.

[jimklimov]

Looks super, thanks!

[AppVeyorBot]

✅ Build nut 2.8.5.5779-master completed (commit 88b1710c64 by @jimklimov)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.5779-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.5780-master completed (commit 88b1710c64 by @jimklimov)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.5780-master.7z