coding-standard.md

Coding Standard

Applies to all runner code under src/ and tests/. Keep it short; when in doubt, match the surrounding code.

Language & tooling

• Python 3.11+ (the reference sibling openlan-schema-validator is 3.10+; we standardize up).
• ruff — lint and format (no separate black). CI fails on lint errors.
• mypy --strict — everything is type-hinted; no untyped public functions.
• pytest — the only test runner (see tdd.md).

File discipline (this is what keeps agent context small)

• One concern per module. Prefer many small files over a few large ones. Soft cap ~300 lines.
• Every src/ package has a contract README.md — purpose, which spec/plan REQs it serves, its interface, its dependencies, and a "to work here read only: …" line. The card is the low-context entry point; keep it current with the code.
• No cross-package reach-around. Depend on interfaces (ABCs), not concrete siblings.

Project-specific rules (more important than style)

1. Black-box discipline. Runner code MUST NOT assume anything about DUT internals — no file paths, no SSH by default, no implementation knowledge. It acts only through the impersonated cloud and reads only the defined observation signals. (SSH is the one opt-in exception, gated by the manifest switch.)
2. Determinism & pinning. No unpinned inputs. No direct time.time()/random in logic — inject a Clock. Timing assertions are tolerance-based (e.g. 10 s ± 2 s), never exact.
3. Interfaces first. Fixtures and DUT drivers are ABCs; concrete impls are swappable. Wiring is dependency-injected via RunContext — no global singletons, no import-time side effects.
4. Result taxonomy is sacred. PASS/FAIL are conformance verdicts; ERROR is a rig/oracle fault and is NOT a conformance result. A timeout is adjudicated by a rig health check → ERROR only if a fixture is unhealthy, else FAIL. Never collapse these.
5. Evidence, always. An assertion records the exact timeline events that decided it. A FAIL with no captured evidence is a bug in the test, not a result.
6. Naming to avoid the collision. src/suites/ = certification scenarios (the product). tests/ = the runner's own unit/component tests. Never blur the two in names or docs.

Conventions

• Snake_case modules/functions, PascalCase classes, SCREAMING_CASE constants.
• Public functions/classes carry docstrings stating intent and, for assertions, the REQ they map to.
• Errors: raise typed exceptions; RigError (→ ERROR) is distinct from a conformance FAIL.
• No secrets or private keys in the tree except pre-created test PKI material under the pinned bundle path (see ../src/pki/README.md).