04 — HunterX Coding Standards

Status: Ratified Version: 1.0.0 Applies to: All Python code in src/hunterx/, plugins/, tools/, tests/, scripts/ Baseline config: pyproject.toml (ruff, line-length 120, target py311, E501 ignored)

1. Language & Runtime

• Python >= 3.11, targeting 3.11–3.13 (see classifiers in pyproject.toml).
• Async-first where I/O-bound (network, DB, subprocess, AI). Compute-bound work must not block the event loop (use executor pools).
• Type annotations are mandatory on all public functions, methods, and module-level variables (PEP 484 / PEP 604 syntax, X | None).

2. Type Hints

• Always annotate arguments and return types. -> None for side-effect-only.
• Prefer structural typing (Protocol) for ports/interfaces over ABC where possible; ABC is acceptable where a base implementation is shared.
• Use TypedDict for dict-shaped config/JSON payloads; dataclasses for value objects and entities; Enum (or StrEnum) for closed sets.
• Use pydantic models only in delivery/application boundaries (CLI, API, config, plugin manifests). Domain layer uses dataclasses + TypeGuards.
• Any is forbidden in public signatures except at the external boundary with an explicit comment justifying it.
• Generic types: prefer Sequence, Mapping, Iterable over concrete list/dict in interfaces; concrete types in implementations.
• Final for module-level constants; Self for fluent/static factories.
• Annotate exceptions in raises: via documentation; enforce with a custom lint rule where available.
• Never use # type: ignore without a comment referencing an issue; adding ignores is a code-review flag.

from typing import Protocol, TypeGuard

class ResolvesTargets(Protocol):
    def resolve(self, scope: Scope) -> Sequence[Host]: ...

def is_authorized(actor: Actor, action: Action) -> TypeGuard[AuthorizedActor]:
    return actor.can(action)

3. Naming Conventions

Forbidden:

• Hungarian notation, single-letter names (except loop vars), abbreviations beyond established ones (stdout, http, ip, dns).
• Leading/trailing underscores in public APIs.

4. Logging

• Logging is structured, never string-concatenated prose:

  logger.info("tool.completed", tool="nmap", target_id=target_id, duration_ms=12_340)
  

  (Key-value pairs, not f-strings in the message.)

• Use structlog-style keyword logging or the project JSON logger; plain logging %-style with zero context fields is not acceptable.
• Levels: debug (detail), info (state transitions), warning (degradation), error (recoverable failure), critical (service-down).
• Never log secrets, credentials, tokens, cookies, or full request bodies. Use masking helpers (src/hunterx/shared/masking.py).
• Every log line emitted inside a workflow/tool run carries correlation_id and span_id (bound via contextvars).
• See 18 - Logging Standards.md for the field contract.

5. Exceptions

• Define a domain exception hierarchy rooted at HunterXError (src/hunterx/domain/exceptions/).
• Never except Exception without either re-raising or converting to a domain exception with context.
• Never swallow exceptions silently; at minimum log with context.
• Catch at the boundary (CLI/API/worker), translate to user-facing error codes, and record the full trace with correlation_id.
• Prefer explicit exception types over assert in production paths (assert disabled under -O).
• Distinguish by retryability: TransientError (retry) vs PermanentError (do not retry). See 17 - Error Handling Standards.md.
• Custom exceptions carry a stable machine code:

  class ScopeViolationError(HunterXError):
      code = "HX-SCOPE-001"
  

6. Architecture Rules

1. Dependency rule: domain imports only stdlib + shared value types. application imports domain. infrastructure implements domain ports. Delivery (CLI/API) composes at the root. Enforced in CI.
2. No framework imports in domain: no fastapi, sqlalchemy, pydantic, redis, requests, aiohttp, structlog, typer, click in domain/.
3. AI isolation: only infrastructure/ai and engines/reasoning.py may import AI SDKs. Agents, skills, tools must go through the abstraction.
4. DB isolation: only infrastructure/db may import ORM/driver SDKs. Engines use StorePort.
5. Tool execution isolation: tool binaries are executed via tools/sandbox.py; adapters never shell out directly.
6. Events over imports: cross-subsystem communication uses the Event Bus, not direct imports of another subsystem’s internals.
7. No business logic in delivery: CLI/API handlers are thin; they validate, call use-cases, and render.
8. No import * anywhere; no cyclic imports (enforced with import-linter).

7. Dependency Injection

• Constructor injection everywhere. No hidden global singletons in domain logic.
• A single composition root builds the object graph (CLI entry, API startup, worker entry).
• Interfaces are Protocols defined in domain/ports/; implementations are chosen by config + environment.
• Provide NullObject implementations for tests and degraded modes (e.g., NullReporter, NullQueue).
• Dependency resolution is explicit and deterministic; no runtime metaclass magic.

8. SOLID

9. Clean Architecture Concretely

• Entities & value objects: immutable where possible (frozen=True dataclasses); domain invariants live in the model, not the caller.
• Use cases: one class per use case where logic is non-trivial; input validation at boundary; domain rule checks inside domain services.
• Ports & adapters: an adapter may implement multiple ports but a port is never bound to one adapter.
• The shared/result.py types (Success, Failure) replace bare (ok, value) tuples; errors are values that can be returned and tested.

10. Async & Concurrency

• Use asyncio for I/O concurrency. Do not use threads for I/O; use asyncio.to_thread/executors only for CPU-bound or blocking third-party calls.
• Never block the event loop: no time.sleep, no synchronous DB/HTTP calls inside coroutines (use async drivers or to_thread).
• Use asyncio.create_task with explicit TaskGroup management; every task has a reference held to avoid GC cancellation.
• Cancellation: use asyncio.CancelledError handling at boundaries to propagate clean shutdown (close sessions, release locks).
• Rate limiting is applied at the tool/queue layer, not scattered in callers.

11. Thread Safety

• Immutable by default; shared mutable state only behind explicit synchronization (asyncio.Lock, threading.RLock as appropriate).
• Contextvars for request-scoped context (correlation_id, actor, scope) — never module-global mutable singletons.
• Singletons allowed only for infrastructure identity (registry, event bus) and must be documented as such with thread-safe access.
• Never mutate a config object after startup; config is immutable post-load.
• Cache access is atomic; use get_or_set semantics.

12. Performance

• Streaming for large tool outputs: iterate lines/chunks; never slurp multi-MB tool output into memory. (See 14 - Performance Standards.md.)
• Bounded caches (TTL + max entries + eviction). LRU for hot paths.
• Lazy imports inside heavy branches where startup latency matters (accepted at module-level only with justification).
• Precompute deterministic hashes (finding, plan) once; reuse.
• SQL: use indexes defined in 09 - Database Design.md; avoid N+1; batch inserts via executemany/bulk APIs.
• Profile before optimizing. Benchmarks live in tests/performance/.

13. Configuration

• Config is loaded via the loader, validated against JSON Schema, and exposed as an immutable typed object (Config dataclass).
• Access config only through injection; never import config; config.x from deep modules.
• Secrets are not config; secrets come from SecretPort.
• Config precedence: defaults < file < environment < CLI < remote.
• Every config field has a documented default and a test.

14. Code Review Gates

Code is not merged unless:

• ruff check . and ruff format --check . pass (120 cols).
• mypy --strict passes on src/hunterx.
• Import linter passes (domain purity, acyclic).
• Unit + integration tests pass; no new coverage regression below the gate (see 15 - Testing Standards.md §9).
• No Any, no uncommented type: ignore, no TODO/FIXME in shipped code.
• New public APIs have docstrings with params, returns, and raises.

15. Docstrings

• Module docstring: one line purpose + references to related docs.
• Public class/function: Google-style summary, params, returns, raises.
• No docstring duplication; code is self-documenting via naming.
• Examples only where non-obvious; prefer doctests in tests/.

16. Compatibility & Portability

• Linux-first; platform guards (sys.platform) for Windows/macOS paths.
• No reliance on shell-specific features in Python (subprocess always explicit with shlex-safe argument lists).
• Time: UTC internally, ISO 8601 with Z; convert at render boundary.
• Paths: pathlib everywhere; no raw string concatenation.