Lintmax

Lintmax

lintmax combines biome, oxlint, eslint, prettier, and sort-package-json into one command. We own it.

CLI — agents MUST read this

lintmax fix fixes everything, then runs a full verification internally (all 5 linters run twice — once to fix, once to check). Silent on success. Exit 0 = fully clean.

The ONLY command you run is bun run fix. That's it. If it exits silently, the code is clean. Nothing else to do.

bun run check / lintmax check is CI-only — it checks without modifying files. Agents must NEVER run it. It is redundant after fix because fix already verified internally. Running check after fix wastes 2+ minutes re-running 5 linters for zero new information.

On failure, lintmax outputs diagnostics already optimized for agents — grouped by file → linter → rule, with compressed line numbers, deduplicated across all 5 linters. Read the output directly. Do not reformat, grep, or filter it.

NEVER:

• Run bun run check — use bun run fix instead
• Add | tail or | head to any lintmax command — empty output IS success, failure output is already agent-formatted
• Run lintmax check --human to "see violations" — run bun run fix and read its output on failure

Ignore Syntax

Ignore Strategy

1. Fix the code — always first choice
2. File-level disable — when a file has many unavoidable violations of the same rule (sequential DB mutations, standard React patterns, external images)
3. Per-line ignore — isolated unavoidable violations
4. Consolidate — if file-level biome-ignore-all exists, remove redundant per-line biome-ignore for the same rule
5. NEVER 5+ per-line ignores for the same rule — use file-level

• File-level directives go at absolute file top, above any imports/code (including 'use client'/'use node').
• Per-line directives go on the line ABOVE the code, NEVER inline on the same line (triggers no-inline-comments).
• When 2+ linters flag the same line, use file-level for one and per-line for the other — don’t stack multiple per-line directives above one line.
• Remove duplicate directives; keep one canonical directive block.
• Use one top eslint-disable line per file; combine multiple rules with commas.

Cross-linter Rules

• 2 linters with the same rule (biome noAwaitInLoops + oxlint no-await-in-loop) = double enforcement, NOT a conflict. Never disable one because the other covers it.
• To suppress a shared eslint/oxlint rule: suppress eslint’s version — oxlint auto-picks up eslint rules and is faster.
• oxlint eslint/sort-keys conflicts with perfectionist (ASCII vs natural sort) — disabled in lintmax.

Never-ignore Rules

These rules exist to catch real bugs. Suppressing them is NEVER acceptable — fix the code instead:

• @typescript-eslint/no-unsafe-* (no-unsafe-assignment, no-unsafe-call, no-unsafe-member-access, no-unsafe-return, no-unsafe-argument) — use proper types, never suppress type safety
• @typescript-eslint/no-explicit-any — define the actual type
• @ts-ignore, @ts-expect-error, @ts-nocheck — fix the type error
• @typescript-eslint/no-non-null-assertion — handle the null case

If an agent suppresses any of these, the code must be rewritten to satisfy the rule.

Safe-to-ignore Rules

oxlint: promise/prefer-await-to-then (Promise.race, ky chaining)

eslint: no-await-in-loop, max-statements, max-depth, complexity (sequential ops) · @typescript-eslint/no-unnecessary-condition (type narrowing) · @typescript-eslint/promise-function-async (thenable returns) · @typescript-eslint/max-params · @next/next/no-img-element (external images) · react-hooks/refs

biome: style/noProcessEnv (env files) · performance/noAwaitInLoops (sequential ops) · nursery/noForIn · performance/noImgElement · suspicious/noExplicitAny (generic boundaries)

Playbook Maintenance

• Every new lesson must be merged into the most relevant existing section immediately; do NOT create append-only “recent lessons” buckets.
• Correct rules in place (single source of truth), then remove superseded guidance.