Show HN: Alint, a fast linter for repository structure and hygiene

2 points

16 days ago

Hi HN, I have been working on alint for the last little while. It is a linter for the shape of a repository rather than the code inside it. clippy, ruff, eslint, and others already handle the AST and code space. alint checks the other layer: required files, filename conventions, content patterns, structured values inside package.json / Cargo.toml / GitHub workflow YAML, and cross-file invariants. You write one .alint.yml describing what the repo should look like, and it runs in CI. Today it covers 70 rule kinds across 13 families, 19 bundled rulesets, 12 auto-fix ops, and 8 output formats including SARIF.

To check the design against reality, I built (vibed) working configs for 30 real OSS repos. The corpus is deliberately varied: single-language workspaces and polyglot monorepos, from small clean trees up to roughly 150k-file mega-repos, with and without mature in-house tooling. Each one has a writeup of what alint catches that the repo's existing tooling does not, including the false-positive-in-spirit cases; the configs are committed under examples/ so the claims are checkable instead of asserted. Findings span large-scale verify-script consolidation in mega-repos, real Trojan-Source bidi-control characters in archived release notes (caught by the bundled oss-baseline ruleset), and the usual CI hygiene drift.

The benchmark is the project's strongest discipline, every release is thoroughly benchmark-gated - see docs/benchmarks for methodology and results. 0.2s-1.5s for 100k file repos, 5s-15s for 1m file repos.

Test discipline is layered: unit tests, declarative YAML end-to-end scenarios, property-based invariants, smoke fixtures that pin rule semantics so an ignored knob is caught at PR time, and the benchmark gate. The project is dual-licensed Apache-2.0 OR MIT, telemetry-free (the only outbound is an extends: URL you wrote yourself, SRI-pinned), reproducible build, one static binary. Install: cargo install alint, a Homebrew tap, a distroless Docker image, an npm shim, or a GitHub Action.

The roadmap is public under docs/design/. Near-term: broader extensibility (richer plugin surface, more bundled rulesets) and a few high-demand rule kinds the case studies surfaced.

The fit with coding agents has been getting the most interest lately. Agents make exactly the structural mistakes alint catches: a stray .bak file, a scratch PLAN.md at the repo root, a committed console.log, drift off the repo naming convention. A --format agent output emits per-violation instruction strings an agent can act on, and alint export-agents-md writes the active ruleset into an AGENTS.md or CLAUDE.md section.

What it deliberately does not do is parse code. If a check needs an AST or type information, that belongs to clippy or eslint and alint stays out of it. On bazel roughly 29% (15 of 52 checks) are out of scope for exactly that reason, and the writeup breaks down which and why.

I am open to all kinds of feedback: pain points, things that should be primitives and are not, install or first-run friction, naming, DSL ergonomics (the JSONPath dashed-key bracket-form papercut has caught everyone), ruleset coverage. If you try it on a repo of yours and it falls over, that is the feedback I most want to hear.

Repo: https://github.com/asamarts/alint

Site and docs: https://alint.org

Benchmarks: https://alint.org/benchmarks/

The 30 example configs: https://alint.org/examples/

1 comment