Moving bash check scripts to alint

From a one-liner to a rule

The shell lines that turn up in check scripts, and the rule kind that does the same job. Each kind links to its page in the rule catalog, with its options and an example.

Two scripts side by side

Every package has a README

#!/usr/bin/env bash
set -euo pipefail
fail=0
for d in packages/*/; do
  if [ ! -f "${d}README.md" ]; then
    echo "missing: ${d}README.md" >&2
    fail=1
  fi
done
exit $fail

missing: packages/emails/README.mdmissing: packages/web/README.md

- id: package-readme
  kind: for_each_dir
  select: "packages/*"
  require:
    - kind: file_exists
      paths: "{path}/README.md"
      message: "{path} has no README.md"
  level: error

packages/emails  ✗  error    package-readme              packages/emails has no README.md packages/web  ✗  error    package-readme              packages/web has no README.md

packages/emails  ✗  error    package-readme              packages/emails has no              README.md packages/web  ✗  error    package-readme              packages/web has no              README.md

Every crate declares a license

#!/usr/bin/env bash
for f in crates/*/Cargo.toml; do
  grep -q 'license =' "$f" || { echo "no license: $f"; exit 1; }
done

no license: crates/core/Cargo.toml

- id: every-crate-declares-license
  kind: toml_path_matches
  paths: "crates/*/Cargo.toml"
  path: "$.package.license"
  matches: '^[A-Za-z0-9.+-]+( (OR|AND) [A-Za-z0-9.+-]+)*$'
  message: "Set package.license to an SPDX expression"
  level: error

crates/cli/Cargo.toml  ✗  error    every-crate-declares-license              Set package.license to an SPDX expression crates/core/Cargo.toml  ✗  error    every-crate-declares-license              Set package.license to an SPDX expression crates/web/Cargo.toml  ✗  error    every-crate-declares-license              Set package.license to an SPDX expression

crates/cli/Cargo.toml  ✗  error    every-crate-declares-license              Set package.license to an              SPDX expression crates/core/Cargo.toml  ✗  error    every-crate-declares-license              Set package.license to an              SPDX expression crates/web/Cargo.toml  ✗  error    every-crate-declares-license              Set package.license to an              SPDX expression

Checks that need more than grep

Which scripts move

Running the scripts you keep

A command rule runs a program for each matching file and reports a non-zero exit as a finding, so CI still calls one tool:

- id: shellcheck
  kind: command
  paths: "**/*.sh"
  command: ["shellcheck", "-x", "{path}"]
  level: error

- id: templated-fields
  kind: command
  paths: "src/**/*.py"
  command: ["scripts/check-templated-fields.py", "{path}"]
  timeout: 60
  level: warning

- id: shellcheck
  kind: command
  paths: "**/*.sh"
  command: ["shellcheck", "-x", "{path}"]
  level: error

- id: templated-fields
  kind: command
  paths: "src/**/*.py"
  command: ["scripts/check-templated-fields.py", "{path}"]
  timeout: 60
  level: warning

• Command rules work only in your own top-level config; a ruleset pulled in with extends: can't add one.
• The program gets the file path in its arguments as {path} and in ALINT_PATH. Other variables carry the repository root, the rule id and level, and your vars and facts; the command rule page lists them.

Three repositories

alint configs were written for these projects, with every check they already run sorted. The projects don't use alint; each reference page has the config and what it found.

A plan for the move

1. Sort each script into the rows of the "Which scripts move" table.
2. Start .alint.yml with the bundled rulesets for your stack. alint list prints every rule they bring in, so you can cross off the scripts they already cover.
3. Add a rule for each remaining script that moves. Use readable ids; they appear in every report.
4. Run alint check on your main branch. Expect a few findings the scripts missed and a few rules with paths set too wide. Record what you won't fix yet with alint baseline.
5. Wrap the scripts you keep in command rules.
6. Replace the CI steps with one alint check and pick the output your CI reads: SARIF, GitHub annotations, JUnit or GitLab code quality are among the 8 output formats.

alint suggest looks for problems already in the tree and proposes rules for them, which helps with step 3.