Cb Code Quality

Circuit Breaker — Code Quality

Run the real gates, not remembered ones

Every check below is wired into the Makefile. Prefer these over ad-hoc tool invocations — they carry the flags, paths, and env the repo actually needs, and they are the same commands CI runs.

make lint          # ruff check + mypy src/app + eslint          (fast)
make format        # ruff format + prettier
make verify        # Tier 0 static + Tier 1 unit — THE PRE-PUSH GATE (~3m20s)
make verify-full   # verify + the backend suite                  (~6m45s)
make test-backend  # integration tests; provisions the test DB first
make test-frontend # vitest

make verify is the gate to run before pushing. make verify-fast (~90s) is the Tier 0 static subset when you only need a quick signal.

There is no flake8 and no cognitive-complexity plugin in this project. Do not install them — ruff is the Python linter (line-length = 100, select = ["E", "F", "I", "UP", "ASYNC"]) and it is also the formatter.

.pre-commit-config.yaml runs gitleaks, ruff, ruff-format, and mypy --strict on commit. If a commit is rejected, read which hook failed before changing code — a gitleaks rejection means a secret reached a staged file and the fix is to remove the secret, never to bypass the hook.

The frontend is JavaScript, not TypeScript

apps/frontend/src is 318 .jsx + 123 .js files and one stray .ts. There is a tsconfig.json, but it is not what the code is written in.

Write .jsx for components and .js for hooks, API modules, and helpers, and match the surrounding file. Do not add TypeScript annotations, interface declarations, or .ts/.tsx files to existing directories — a lone typed file in a JS tree is churn for the next reader, not an upgrade. Type intent goes in JSDoc and PropTypes where the surrounding code already uses them.

Backend types are enforced

[tool.mypy] sets disallow_untyped_defs = true, check_untyped_defs = true, and warn_return_any = true against src/app. Every function you add needs annotated parameters and a return type, or make lint fails:

async def get_cached_telemetry(hardware_id: int) -> dict | None:

ignore_missing_imports is on and import-untyped is disabled, so third-party libraries without stubs will not fight you. Your own code has no such excuse.

Constants

Backend  : apps/backend/src/app/core/constants.py
Frontend : apps/frontend/src/lib/constants.js

Name any literal that carries meaning — a TTL, a threshold, a retry budget, a port. The value is that a reader meets TELEMETRY_CACHE_TTL_SECONDS instead of 300 and does not have to reconstruct intent from a number.

await redis.setex(cache_key, TELEMETRY_CACHE_TTL_SECONDS, payload)   # not 300

Exempt: 0, 1, "", booleans, and format strings. A literal used exactly once, immediately beside the thing that explains it, is often clearer inline — use judgment rather than extracting on reflex.

Error handling

Anything touching I/O — DB, Redis, NATS, HTTP, filesystem, SNMP/IPMI/Redfish — needs a handler that names the exception it expects. The reason to catch specifically is that a broad catch hides the failure you did not anticipate, and this project runs unattended in other people's homelabs where a silently swallowed error is indistinguishable from working software.

try:
    raw = await get_redis().get(cache_key)
except redis.ConnectionError as exc:
    logger.warning("[telemetry_cache] Redis unavailable for hw:%s: %s", hardware_id, exc)
    return None
except json.JSONDecodeError as exc:
    logger.error("[telemetry_cache] corrupt cache for hw:%s: %s", hardware_id, exc)
    return None

Every handler either logs and returns a typed fallback, or re-raises. Never except Exception: pass. Prefix log messages with [module_name] and use logger, never print().

Degradation is a first-class path here: Redis or NATS being down should leave the app serving REST, not crashing. CB_ALLOW_DEGRADED_DEPENDENCIES exists for exactly this and the integration suite runs with it on.