Architecture diagrams
These diagrams come from a single LikeC4 model in the alint
repository. They stay in lockstep with the code: the crate elements and their
dependency edges are gated against cargo metadata, the rule catalogue against
docs/rules.md, the config keys against the JSON schema, and the whole model is
checked by likec4 validate in CI. The same model is also exported to
static Mermaid diagrams
for viewing in the GitHub repository.
Drag to pan, scroll to zoom, and click an element to step into it.
System context
Section titled “System context”Who and what alint interacts with: developers and CI, the linted repository, package registries, editors (via the LSP), GitHub Code Scanning, and alint.org.
Containers
Section titled “Containers”The alint system as containers: the CLI, the LSP server, and the dev or build
tooling.
CLI components
Section titled “CLI components”The crates inside the CLI and their runtime relationships.
Crate dependency graph
Section titled “Crate dependency graph”All workspace crates and their dependency edges, grouped by container: runtime
dependencies solid, dev/build-only dashed. Generated from cargo metadata.
Execution pipeline
Section titled “Execution pipeline”alint check: config load, facts, rule filtering, the single parallel walk,
dispatch, evaluation, aggregation, optional fix, and output.
Config load and the extends trust boundary
Section titled “Config load and the extends trust boundary”How extends: resolves (local path, https with SRI, bundled) and why
process-spawning rule kinds and out-of-root access are rejected outside the
top-level config (ADR-0004).
Dispatch and read-coalescing
Section titled “Dispatch and read-coalescing”Rule-major versus per-file dispatch, and how each matched file is read at most once (ADR-0003).
Rule catalogue
Section titled “Rule catalogue”The built-in rule families and the canonical kinds within them. Click a family to step in.
Config DSL domain model
Section titled “Config DSL domain model”The .alint.yml entities and how they relate.
Rule execution type model
Section titled “Rule execution type model”The engine’s core types: how a Rule (or PerFileRule), a Fixer, and the
Violation / RuleResult / Report values relate.
Facts and conditional rules
Section titled “Facts and conditional rules”Facts are evaluated once (in parallel, cached), then used to filter which rules
run via their when: conditions.
Fix flow
Section titled “Fix flow”alint fix: how auto-fixable violations are applied (including content-reading
fix operations) and re-checked.
Walk, gitignore, and filtering
Section titled “Walk, gitignore, and filtering”The single parallel directory walk: gitignore handling, include/exclude
filtering, and the deterministic, sorted FileIndex.
Template expansion
Section titled “Template expansion”How ${...} template variables in rule options are expanded before evaluation.
Monorepo nesting and scoping
Section titled “Monorepo nesting and scoping”How nested .alint.yml files layer and scope rules across a monorepo.
Output formats
Section titled “Output formats”How a Report is rendered into each output format (human, JSON, SARIF, and the
rest).
The language server: how an editor’s open/change/save events drive a per-file check and publish diagnostics.
Editor integrations
Section titled “Editor integrations”How the editor extensions (VS Code, JetBrains) connect to the alint LSP server.
CI: GitHub Action and SARIF
Section titled “CI: GitHub Action and SARIF”The GitHub Action: how a CI run produces SARIF for GitHub Code Scanning.
pre-commit: the commit gate
Section titled “pre-commit: the commit gate”How the pre-commit hook runs alint check on commit and blocks on errors, plus
the manual alint-fix hook.
Release and distribution
Section titled “Release and distribution”How a tagged release fans out to crates.io, npm, Homebrew, Docker, and the install script.
Contributing a rule kind
Section titled “Contributing a rule kind”The touch-points for a new rule kind: the registry, the options struct and JSON schema, and the generated docs.
Docs as code and drift gates
Section titled “Docs as code and drift gates”How the generated contracts (facts, schema, rules, this model) flow to alint.org and are gated against drift.
Deterministic performance gating
Section titled “Deterministic performance gating”The load-immune, Valgrind-based performance check that guards the engine against regressions independently of machine load.
Plugin model
Section titled “Plugin model”How an external rule plugin is declared, gated (spawning kinds rejected outside the top-level config), and invoked.
Security: path confinement and spawning-kind gating
Section titled “Security: path confinement and spawning-kind gating”Two guards: keeping file access within the repository root, and rejecting
process-spawning rule kinds pulled in via extends: (ADR-0004).
Security: Trojan-source and unicode hygiene
Section titled “Security: Trojan-source and unicode hygiene”How bidirectional-override and invisible-character (Trojan-source) attacks are detected in scanned files.