lintmax-py

Maximum-strictness Python quality gate. One command, always-latest, never stale.

The Python counterpart to lintmax (TypeScript), lintmax-go and lintmax-rs. Designed for coding agents, not humans.

Why

Python ships no strictness by default: no compiler, no unused-import error, no type enforcement. lintmax-py closes that gap and pushes past it — every rule ruff carries including the preview set, every ty diagnostic at error severity, plus the layers neither tool covers: dead code, unused dependencies, vulnerabilities, spelling, shell scripts and every non-Python file in the tree.

Never stale

No tool version is ever pinned. Ruff, ty and every child tool are fetched at latest on each run, and the rule set is DERIVED from the installed ruff rather than listed — so the moment ruff ships a new rule, your gate runs it. Dependency staleness is scanned against upstream every run.

dprint plugins resolve through each plugin's latest.json and the concrete versioned URL is written back. A constant floating URL is deliberately NOT used: dprint caches a plugin by its URL, so an unchanging URL resolves once and then freezes silently, which is the exact staleness the floating form appears to solve.

Use

Exactly four commands — the lean agent-first surface:

lintmax-py fix      # format + autofix + full gate — the default action
lintmax-py check    # verify only, no writes (CI mode) — same exhaustive scanner set
lintmax-py version  # print version
lintmax-py rules    # list every enabled rule under the maxed config

Prints ok on a single line on success, exit 0 = clean. Tool output is shown only on failure. A clean run that is cached prints ok (cached).

Self-evolving (automatic, never a command)

• Child tools reinstalled at latest on a refresh cadence; CI always forces latest.
• The binary refreshes itself in CI before gating.
• No green-tree-hash cache: measured on 10,039 real files with all 968 rules, a full ruff run costs 4.3s while hashing the tree to skip it costs 2.6s, so the cache buys ~40% in its best case and adds a false-green failure mode. The expensive work is the network, and that is TTL-cached instead.
• Dependency staleness scanned against upstream every run.

What runs

Strictness policy

• The ruff rule set is derived from ruff rule --all, so a newly shipped rule is enabled the run after it lands. ALL alone is not enough: preview rules require their exact code.
• Every rule is error or off, never warn.
• ty runs with all rules at error severity.
• Ruff's own conflicting-rule pairs resolve to the stricter member.
• The disable list starts EMPTY. Each entry is earned by a concrete conflict found on real code, never anticipated, and carries its reason.

Earned disables

Configless

Every rule config is embedded in the tool. Your project stays clean — no ruff.toml, no ty.toml, no dprint.json. Updating lintmax-py updates every project's strictness. The bundled config is generic only and carries no project or ecosystem opinion.

The single exception is vocabulary, which is data rather than strictness. A spell checker with no project dictionary reports every domain noun a codebase owns — a client name, a product name, a protocol token — as a misspelling, and the only escapes would be renaming the domain or turning the stage off. So the [default.extend-words] and [default.extend-identifiers] tables are read from whichever of typos.toml, _typos.toml, .typos.toml or pyproject.toml ([tool.typos]) your project carries, in that order, and merged into the generated config. Nothing else in that file is read: the switches stay owned by the gate, so a project can name the words it uses and cannot weaken the check that reads them.

# typos.toml
[default.extend-words]
myproduct = "myproduct"

The same principle covers the ambiguous-character rule: a codebase whose domain language is not Latin uses punctuation the rule reads as a homoglyph, and rewriting it would change the text the product ships. Declare those characters in ruff.toml, .ruff.toml or pyproject.toml ([tool.ruff.lint]) and they are merged into the generated config; every character you do not name stays flagged.

# ruff.toml
[lint]
allowed-confusables = ["（", "）", "："]

Two more facts a gate cannot infer are read the same way. A dead-code scan cannot see a function reached only through a registration decorator, nor an attribute read only by a metaclass, so a project states them and every other name stays scanned:

# pyproject.toml
[tool.vulture]
ignore_decorators = ["@app.route"]
ignore_names = ["model_config"]

And the copyright rule enforces nothing until a project says whose notice it wants — the holder is a legal fact about that codebase. Declare notice-rgx and the rule is enforced on every file; declare nothing and it stands down, with no other rule relaxed.

# ruff.toml
[lint.flake8-copyright]
notice-rgx = "(?i)Copyright\\s+\\(c\\) Example Ltd"

License

MIT