Code Quality & Type Contracts

ContextUnity enforces strict basedpyright (0 errors, 0 warnings) on all production Python under packages/*/src, services/*/src, and extensions/{commerce,rag,spatial}/src. Type contracts are defined in the monorepo — not silenced in config.

Quality gate (pre-commit)

Install hooks once:

./scripts/install-hooks.sh

Each commit runs quality-gate.sh:

1. ruff check --fix .
2. ruff check .
3. ruff format .
4. basedpyright --project pyrightconfig.json --warnings (zero tolerance)
5. pytest for staged directories

uv run pre-commit run quality-gate --all-files

Pre-push runs the full pytest suite (integration + extensions). See Infrastructure → Deployment for CI parity.

Pyright configuration

Single root pyrightconfig.json extends types/django/pyrightconfig.base.json:

Setting	Value
Mode	typeCheckingMode: strict
Python	3.13
Django stubs	types/django/stubs via stubPath + per-package executionEnvironments
Missing imports	reportMissingImports: error
Missing third-party stubs	reportMissingTypeStubs: false (no noise for every PyPI package without .pyi; boundaries use guards + targeted stubs)
Rule suppressions	No report*: "none" overrides for model-field or import-cycle diagnostics

# Full monorepo (same as the hook):
uv run basedpyright --project pyrightconfig.json --warnings

# Core-only stricter pass:
uv run basedpyright packages/core/src --warnings

External Django hosts (e.g. NSZU) extend the same Django baseline — see types/django/README.md.

Type & contract boundaries (L0 → L4)

Canonical reference: docs/architecture/type-boundaries.md in the monorepo.

Layer	Type	Rule
L0	WireValue (object)	Parse only via contextunity.core.parsing
L2	JsonValue, JsonDict	Validate with is_json_value, is_json_dict
L3	ContextUnitPayload	Read keys via contextunity.core.sdk.payload.get_*
L4	Pydantic / TypedDict	Domain models after validation

Forbidden at boundaries without inline justification in the diff:

• Any
• cast()
• # type: ignore / # pyright: ignore

Use instead: contextunity.core.narrowing (as_str, as_json_dict, await_object, …), Protocol, TypedDict.

Services import shared types from contextunity.core.types and contextunity.core.sdk.types — never redefine JsonValue or parallel payload trees locally.

Runtime guards (beyond pyright)

Basedpyright alone misses import-time NameError, cross-module Pydantic JsonValue recursion, and metadata/tuple edge cases. After boundary refactors, run:

uv run pytest packages/core/tests/test_contract_boundaries.py \
  packages/core/tests/test_security.py \
  tests/test_engine_imports.py -q

Proto contracts

After editing .proto files under packages/core/protos/:

uv run python scripts/build_protos.py
# or: cd packages/core && ./compile_protos.sh

Never edit generated *_pb2.py / *_pb2_grpc.py by hand. See gRPC Contracts.