ferrolint

Extensible Python linter in Rust that runs custom rules, loaded as WASM plugins, next to Ruff.

Table of contents

• About
• Key features
• Requirements
• Usage
• Getting started
• How a run works
• Writing a plugin
• Type inference with ty
• Security
• Contributing
• License

About

ferrolint lints Python code with Ruff's own parser crates (ruff_python_parser, ruff_python_ast, ruff_python_semantic) and runs checks that ship as WASM plugins. Instead of a plugin host interpreting Python, each check is a compiled WebAssembly component: the contract feeds it AST visitor events and lets it ask scope and binding questions, and the plugin answers with diagnostics carrying a code, message, range, severity and an optional fix.

Ruff stays in the loop and keeps every built-in rule, including the Pylint PL* checks. ferrolint is the layer for checks Ruff does not have: a team's custom rules, ported Pylint checkers, and Pylint message-ID/symbol mappings, all running in the same pass.

Key features

• Plugins as WebAssembly components. Each plugin runs in an empty sandbox with per-file fuel and time caps, and loads only with its pinned SHA-256.
• Pylint compatibility. Rules keep Pylint's message IDs and symbols, so selecting, ignoring and # pylint: disable= comments keep working.
• Speed on large codebases. On a million lines with the ten benchmark plugins, a cold run takes about 6.5 s on four cores and a warm run 0.25 s; Pylint running the same ten checks takes 167 s. make bench measures it.
• Incremental runs. A content-keyed cache in .ferrolint-cache/ and --diff-base to lint only what changed.
• Deterministic output in text, JSON, SARIF or JUnit.
• One static binary for Linux x86_64 and aarch64 and for macOS aarch64.

Requirements

• Linux (x86_64 or aarch64) or macOS (aarch64). There is no Windows build.
• Python 3.9 or later and pip or uv, to install the wheel. The linter itself is a native binary and lints any Python code.
• To write a plugin: Rust and the wasm32-wasip2 target (rustup target add wasm32-wasip2).

Usage

Lint the current directory:

ferrolint

Lint chosen paths with an explicit configuration file, in SARIF:

ferrolint --config ci.toml --format sarif src tests

Configuration lives in ferrolint.toml or in the [tool.ferrolint] table of pyproject.toml (all keys):

select = ["FL002"]
ignore = ["FL003"]
exclude = ["vendor/"]

[[plugins]]
path = "plugins/my_checker.wasm"
sha256 = "…"

[per-file-ignores]
"tests/*.py" = ["FL002"]

Getting started

Install the wheel from PyPI:

pip install ferrolint        # or: uv tool install ferrolint
ferrolint --version

To try an unreleased commit, install from Git. The build needs the pinned Rust toolchain and the wasm32-wasip2 target, and the first build compiles Wasmtime, which takes minutes:

pip install "git+https://github.com/gajaguar/ferrolint"

How a run works

A run discovers the Python files under its targets, honouring .gitignore and the configured excludes, parses them in parallel with Ruff's parser, and runs the host's own rules plus every configured WASM plugin against the plugin.wit contract. The rules and their Pylint counterparts are listed in Native rules. The requirements and the design decisions live in the docs/ bundle: requirements and decisions.

Writing a plugin

A plugin is a Rust cdylib built to wasm32-wasip2 against ferrolint-plugin-sdk:

[dependencies]
ferrolint-plugin-sdk = "1"

The SDK's version is the version of the plugin contract: a plugin built against any 1.x loads in a ferrolint 1.x host. The sample unused-import ports Pylint's W0611 and matches its findings on the fixtures. Writing a plugin builds it step by step, and A plugin outside this repository covers a plugin kept in its own crate.

Type inference with ty

ty is an optional extension that adds ten Pylint rules needing the type of a value. The published wheels are built without it. To use it, build with cargo build --release --features ty and set VIRTUAL_ENV to the project's environment. See Rules answered by ty.

Security

Report a vulnerability by emailing dev@gajaguar.com rather than opening a public issue. SECURITY.md has the supported versions.

Contributing

See CONTRIBUTING.md.

License

ferrolint is released under the MIT License; see LICENSE.