Aller au contenu

🚦 Lint Gates & Code Policy

LibreFolio's Python hygiene rules are enforced by gates, not by convention documents: everything listed here lives in [tool.ruff.lint] in the repo-root pyproject.toml and runs on every ./dev.py lint invocation. The audit lesson behind this setup (audit 08, P1-2): "level zero" cleanups do not hold without a gate that fails the build when the level regresses.

./dev.py lint            # ruff check --fix (auto-fixes what is safe)
./dev.py format          # black, line-length 300
./dev.py lint --dead-code  # vulture dead-code scan (config in pyproject.toml)

🧱 The gate list

Gate Rule family Why it is on
E / W pycodestyle errors / warnings Baseline style (E501 line-length stays off — black owns it)
F pyflakes Unused imports, undefined names
I isort Import ordering
B flake8-bugbear Real-bug patterns (B008 stays off — FastAPI Depends() needs call defaults)
C4 flake8-comprehensions Unnecessary comprehension/list/dict calls
UP pyupgrade Modern syntax — with UP006/UP007/UP035/UP045 off by choice: List[X], Union[X, Y], Optional[X] and typing imports are kept because they read more explicitly next to Pydantic
PLC0415 import-outside-toplevel Imports belong at module top; the few legitimate function-local imports carry a justified # noqa: PLC0415
S110 try-except-pass No silent except: pass swallows — audit 08/P0-3 fixed the instances, the gate keeps them from coming back
C901 cyclomatic complexity Gated at 10 ([tool.ruff.lint.mccabe] max-complexity = 10) — see the policy below
RUF022 sorted __all__ Barrel modules keep __all__ sorted — with 4 deliberate exceptions, see below

ruff check backend/ is green under these gates; a regression is a lint failure, not a discussion.

📏 The C901 policy: flat packers vs real complexity

McCabe counts every decision point — including ternaries and boolean operators — so a flat "unpack-and-repack" data mapper with 12 ternaries scores 13 while being perfectly linear code. Cognitive complexity would be the honest metric for that shape, but ruff does not implement it. The threshold was therefore set low (10) and the resulting triage distinguishes two kinds of over-threshold function:

  1. Flat data shuffling (packers, CSV parsers, per-rule validators, bulk loops with early returns) → keeps a per-function justified noqa that says why it is flat:
def validate_chain_steps(  # noqa: C901 — flat numbered rule-chain validation
  1. Genuinely nested logic (orchestrators, state machines, nested closures) → marked TODO(P2-refactor) in the same comment and tracked in the audit backlog for real decomposition:
async def get_lots_analysis(  # noqa: C901 — TODO(P2-refactor): long orchestrator; extract per-analysis stage helpers

The transaction batch refactor demonstrates the preferred outcome: TransactionService.execute_batch() no longer has a C901 exemption or TODO(P2-refactor). Its former 637-line body is now an approximately 50-line orchestrator over TransactionBatchContext and ordered functions in transaction_batch_stages.py.

As of 2026-09-11, the current tree carries 201 # noqa: C901 sites and 24 TODO(P2-refactor) markers. Relative to the tracked pre-refactor tree, execute_batch() accounts for the one-site reduction in both totals (202 → 201 and 25 → 24). Recheck live counts instead of copying these numbers:

grep -rn "noqa: C901" backend/ scripts/ --include="*.py" | wc -l
grep -rn "TODO(P2-refactor)" backend/ scripts/ --include="*.py" | wc -l

Writing a new # noqa: C901

Read the whole function first. If its branches are flat format/error handling, write the noqa with the flat-shape justification. If you found real nesting, mark it TODO(P2-refactor) — or better, extract a helper and drop the noqa entirely.

🛢️ The 4 RUF022 exceptions

__all__ is kept sorted everywhere except four barrel modules that group their exports by domain with section comments — sorting would scatter related names away from their group:

  • backend/app/db/__init__.py
  • backend/app/db/base.py
  • backend/app/schemas/__init__.py
  • backend/app/schemas/assets.py

Each carries # noqa: RUF022 — grouped by domain with section comments; sorting would scatter related names.

🪵 Logging inside except (TRY400 convention)

Inside an exception handler, use logger.exception(...) — never logger.error(...): the former attaches the active traceback, the latter silently drops it. Audit 08 converted all 55 logger.error-in-except sites (03/09) and the codebase is TRY400-clean today (ruff check --select TRY400 passes), although the rule is not yet part of the select list — treat it as mandatory style regardless.

🧪 Beyond the linter: JSON validator vs sanitizer

Two JSON-safety helpers coexist with opposite error policies, and they must not be merged (audit 08, report 03 §N-03-A):

  • ensure_json_safe (backend/app/utils/json_utils.py) — the validator: recursively checks a value is natively JSON-serializable and raises ValueError otherwise. Used by Pydantic field_validators on contract boundaries (signals, AI Export payloads), where a non-JSON value means the producer is broken and must be rejected.
  • _json_safe_details (local to backend/app/services/asset_source.py) — the sanitizer: stringifies anything non-primitive and never raises. It exists for one field (AssetSourceError.details in provider diagnostics), preserves None/empty as "omit the field", and sanitizes one list level deep — exactly what provider-error localization needs.

Rejecting and stringifying are opposite answers to the same input. If a boundary needs validation, call the validator; if a diagnostic field needs to survive arbitrary provider data, call the sanitizer. Never let one grow the other's behavior.