Migrating custom bash validation scripts to alint

Patterns with no clean alint mapping

These are the kinds of script you keep. alint deliberately doesn't try to do them; many are on the v0.10+ candidate list.

Side-by-side: a real script

Every package has a README

The for d in packages/*/; do …; done shape is one of the most common in OSS monorepos. The bash version:

#!/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

The alint equivalent (five lines of YAML) supports the same invariant, but also handles ignore filtering, parallel evaluation, JSON / SARIF / GitHub-annotation output formats, and --changed-mode incremental runs:

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

If your monorepo lives under packages/ AND apps/, the monorepo@v1 bundled ruleset already covers this with one extends: line.

Every Cargo.toml declares a license

Slightly more complex. The bash version typically has two subtle bugs: it doesn't catch license-file = (the alternate form), and it doesn't catch a TOML-comment-shaped license line that grep matches but TOML parsers reject. The alint version is TOML-aware:

- id: every-crate-declares-license
  kind: for_each_dir
  select: "crates/*"
  when_iter: 'iter.has_file("Cargo.toml")'
  require:
    - kind: toml_path_matches
      paths: "{path}/Cargo.toml"
      path: "$.package.license"
      matches: '^[A-Za-z0-9.+\-]+( OR [A-Za-z0-9.+\-]+)*$'
  level: error

when_iter: filters out non-package directories under crates/ without any extra grep. The TOML path query handles the parsing; the regex pins the license to a SPDX-shaped value. The replacement isn't shorter; it's stricter.

Composability for the long tail

For checks that don't map (an in-house tool, an AST-aware Python script, a runtime probe), command: keeps them inside the same gate:

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

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

Now alint check runs both the declarative rules and the surviving scripts; CI calls alint check once instead of running bash hack/verify-all.sh.

The command: trust gate

A few notes on the survivor-wrapping pattern:

• Trust gate. command: rules are only allowed in the user's own top-level config. A kind: command rule introduced via extends: (local file, HTTPS URL, or alint://bundled/) is rejected at load time. Adopting a published ruleset never grants arbitrary process execution.
• --changed interaction. command is a per-file rule, so under alint check --changed it spawns only for files in the diff. Your expensive shell-out is automatically incremental in CI.
• Environment threaded into the child. ALINT_PATH, ALINT_ROOT, ALINT_RULE_ID, ALINT_LEVEL, plus any top-level vars: you define. Existing scripts usually need no changes; most read $1 or $ALINT_PATH directly.

Step-by-step migration

A real-world plan, scoped to roughly one afternoon for a 30-script directory.

1. Inventory and categorise. For each script, ask: is this structural (file existence, content patterns, manifest fields, filename grammar)? → maps to alint. AST-aware? → keep, optionally wrap in command:. Runtime (binary version, network probe)? → keep, optionally wrap. Generator (update-*, regen-*)? → not alint's job; keep. Cross-API-version diff or module-graph analysis? → out of scope; keep. The kubernetes case study tags each of its 50 scripts; copy that template.
2. Write .alint.yml with bundled rulesets first. Start with what already encodes 80% of what most projects want:

   version: 1
   
   extends:
     - alint://bundled/oss-baseline@v1
     - alint://bundled/<your-language>@v1
     - alint://bundled/ci/github-actions@v1
     - alint://bundled/hygiene/no-tracked-artifacts@v1
   
   rules:
     # your project-specific rules go here

   Run alint list --config .alint.yml to see the rule expansion. Many of the scripts you'd planned to translate will already be covered.
3. Translate the structural subset. Walk your inventory's "structural" pile, one script at a time, and add a rule per script. Keep IDs human (team-go-license-header, team-no-todo-in-prod); they show up in violation messages and CI logs. Reuse the pattern catalogue above.
4. Reconcile with current main. Run alint check against the current tip. You will surface either: a handful of true positives (your script's tolerances were slightly off; alint catches what it silently let through); a flood of false positives (your paths: scope is too broad, narrow it); or existing live failures (some bash scripts are silently broken: they ran, exited 0, but their grep was hitting nothing).
5. Wrap surviving scripts in command: rules. For the AST / runtime / cross-API-version / generator scripts you deliberately kept, add one command: rule each. Now both the declarative and survivor checks run under alint check.
6. Update CI. Replace your master bash hack/verify-all.sh invocation with alint check. Drop the per-script CI steps; one binary, one exit code, one output file.
7. (Optional) retire the surviving scripts organically. Surviving scripts that become candidates for new alint primitives (registry_paths_resolve, import_gate, generated_file_fresh, cross_file_value_equals, all on the v0.10+ list) will retire themselves over the next few releases.

What you gain by consolidating

• One config to read. The structural contract becomes a single artifact, not a directory.
• Faster CI. alint runs declarative rules in parallel; on a 100k-file repo (the kubernetes shape), the alint-replaceable subset benchmarks at ~1-2 seconds; the equivalent shell pipeline measures in tens of seconds dominated by N redundant walks.
• Output formats CI can read. human, json, sarif, github, markdown, junit, gitlab, agent. Eight formats, no echo glue.
• Auto-fix where it's safe. 12 mechanically-safe ops (trim whitespace, normalize line endings, strip BOM/bidi/zero-width, prepend / append, rename, remove).
• A declarative DSL anyone can edit. Adding a rule is a 5-line YAML block; editing one is changing a regex.
• Composition. extends: pulls bundled rulesets, local files, or HTTPS+SRI URLs.

See also

• kubernetes case study: the headline 50-to-17 story, with the full inventory.
• cpython case study: 56 surfaces across Make targets / pre-commit / Tools/build/* / .gitattributes.
• airflow case study: 109 pre-commit hooks, ~40% map.
• Rule catalogue: every alint rule kind, with examples.
• Bundled rulesets: what extends: ships out of the box.
• How alint compares to other tools, including Repolinter, ls-lint, Megalinter, EditorConfig.