Code Quality Report¶

Generated: 2026-04-05 04:25 UTC

Lines of Code¶

	Files	Code	Comment	Blank	Total
Source	31	4 636	987	515	6 138
Tests	27	6 492	520	895	7 907
Combined	58	11 128	1 507	1 410	14 045

Comment/code ratio: 21%
Test/source ratio: 140.0%

Source by module (click to expand)

Module	Files	Code	Comment	Blank
`terok_sandbox/`	31	4 636	987	515
`terok_sandbox/_util/`	4	61	23	23
`terok_sandbox/_util/__init__.py`	—	11	3	3
`terok_sandbox/_util/_fs.py`	—	23	3	4
`terok_sandbox/_util/_logging.py`	—	21	13	12
`terok_sandbox/_util/_templates.py`	—	6	4	4
`terok_sandbox/credential_proxy/`	7	818	194	94
`terok_sandbox/credential_proxy/resources/`	2	17	0	5
`terok_sandbox/credential_proxy/resources/systemd/`	2	17	0	5
`terok_sandbox/credential_proxy/__main__.py`	—	2	3	3
`terok_sandbox/credential_proxy/constants.py`	—	1	16	2
`terok_sandbox/credential_proxy/server.py`	—	483	78	47
`terok_sandbox/credential_proxy/ssh_agent.py`	—	315	94	36
`terok_sandbox/gate/`	5	483	66	18
`terok_sandbox/gate/resources/`	2	17	0	5
`terok_sandbox/gate/resources/systemd/`	2	17	0	5
`terok_sandbox/gate/__main__.py`	—	2	3	3
`terok_sandbox/gate/server.py`	—	464	60	9
`terok_sandbox/__init__.py`	—	165	40	18
`terok_sandbox/cli.py`	—	85	16	19
`terok_sandbox/commands.py`	—	619	34	3
`terok_sandbox/config.py`	—	94	18	7
`terok_sandbox/credential_db.py`	—	85	37	18
`terok_sandbox/credential_proxy_lifecycle.py`	—	363	102	74
`terok_sandbox/doctor.py`	—	103	66	33
`terok_sandbox/gate_server.py`	—	354	60	12
`terok_sandbox/gate_tokens.py`	—	75	23	16
`terok_sandbox/git_gate.py`	—	397	75	35
`terok_sandbox/paths.py`	—	76	36	18
`terok_sandbox/runtime.py`	—	319	45	28
`terok_sandbox/sandbox.py`	—	124	70	68
`terok_sandbox/shield.py`	—	91	52	25
`terok_sandbox/ssh.py`	—	324	30	6

Architecture¶

Module Dependency Graph¶

graph TD
    terok_sandbox.config --> terok_sandbox.paths
    terok_sandbox.runtime --> terok_sandbox._util
    terok_sandbox.shield --> terok_sandbox.config
    terok_sandbox.gate_tokens --> terok_sandbox.config
    terok_sandbox.gate_server --> terok_sandbox._util
    terok_sandbox.gate_server --> terok_sandbox.config
    terok_sandbox.gate_server --> terok_sandbox.gate
    terok_sandbox.gate_server --> terok_sandbox.gate_tokens
    terok_sandbox.ssh --> terok_sandbox._util
    terok_sandbox.ssh --> terok_sandbox.config
    terok_sandbox.git_gate --> terok_sandbox.config
    terok_sandbox.git_gate --> terok_sandbox.ssh
    terok_sandbox.credential_proxy_lifecycle --> terok_sandbox._util
    terok_sandbox.credential_proxy_lifecycle --> terok_sandbox.config
    terok_sandbox.credential_proxy_lifecycle --> terok_sandbox.credential_db
    terok_sandbox.credential_proxy_lifecycle --> terok_sandbox.credential_proxy
    terok_sandbox.sandbox --> terok_sandbox.config
    terok_sandbox.sandbox --> terok_sandbox.gate_server
    terok_sandbox.sandbox --> terok_sandbox.gate_tokens
    terok_sandbox.sandbox --> terok_sandbox.runtime
    terok_sandbox.sandbox --> terok_sandbox.shield
    terok_sandbox.sandbox --> terok_sandbox.ssh
    terok_sandbox.commands --> terok_sandbox.config
    terok_sandbox.commands --> terok_sandbox.credential_proxy_lifecycle
    terok_sandbox.commands --> terok_sandbox.doctor
    terok_sandbox.commands --> terok_sandbox.gate_server
    terok_sandbox.commands --> terok_sandbox.shield
    terok_sandbox.commands --> terok_sandbox.ssh
    terok_sandbox.cli --> terok_sandbox.commands
    terok_sandbox --> terok_sandbox.commands
    terok_sandbox --> terok_sandbox.config
    terok_sandbox --> terok_sandbox.doctor
    terok_sandbox --> terok_sandbox.credential_db
    terok_sandbox --> terok_sandbox.credential_proxy
    terok_sandbox --> terok_sandbox.credential_proxy_lifecycle
    terok_sandbox --> terok_sandbox.gate_server
    terok_sandbox --> terok_sandbox.gate_tokens
    terok_sandbox --> terok_sandbox.git_gate
    terok_sandbox --> terok_sandbox.paths
    terok_sandbox --> terok_sandbox.runtime
    terok_sandbox --> terok_sandbox.sandbox
    terok_sandbox --> terok_sandbox.shield
    terok_sandbox --> terok_sandbox.ssh
    terok_sandbox._util
    terok_sandbox.gate
    terok_sandbox.paths
    terok_sandbox.credential_db
    terok_sandbox.credential_proxy
    terok_sandbox.doctor

Module Boundaries¶

18 modules, 43 dependency edges — all boundaries validated.

Module Summary¶

18 modules (click to expand)

Module	Deps	Description
`terok_sandbox._util`	0	Vendored utilities — standalone, no internal deps
`terok_sandbox.gate`	0	Gate server — standalone HTTP server, zero internal imports
`terok_sandbox.paths`	0	Platform-aware path resolution — standalone, no internal deps
`terok_sandbox.config`	1	Configuration dataclass — depends on paths for defaults
`terok_sandbox.runtime`	1	Container runtime — depends on _util for logging/YAML
`terok_sandbox.shield`	1	Shield adapter — depends on config
`terok_sandbox.gate_tokens`	1	Gate token CRUD — depends on config
`terok_sandbox.gate_server`	4	Gate server lifecycle — depends on config, _util, gate_tokens, gate
`terok_sandbox.ssh`	2	SSH key management — depends on _util, config
`terok_sandbox.git_gate`	2	Git gate mirror management — depends on ssh, config
`terok_sandbox.credential_db`	0	Credential DB — standalone, no internal deps
`terok_sandbox.credential_proxy`	0	Credential proxy server — standalone, zero terok imports
`terok_sandbox.credential_proxy_lifecycle`	4	Credential proxy lifecycle — depends on config, credential_db, _util
`terok_sandbox.sandbox`	6	Sandbox facade — composes shield, gate, runtime, SSH
`terok_sandbox.doctor`	0	Health check protocol + sandbox-level diagnostics — standalone
`terok_sandbox.commands`	6	Command registry — defines all sandbox CLI commands
`terok_sandbox.cli`	1	CLI entry point — wires command registry to argparse
`terok_sandbox`	14	Package root — public API re-exports

Test Coverage¶

Coverage is collected from unit tests in CI and uploaded to Codecov.

Coverage Treemap¶

Each rectangle represents a source file. Size is proportional to the number of lines; colour shows the coverage percentage (green = high, red = low).

Cognitive Complexity¶

Threshold: 15 (functions above this are listed below)

Functions analyzed: 217
Median complexity: 2 · Average: 3.7 · Max: 64
Within threshold (15): 95% (206/217)

    0–  3 │ ██████████████████████████████ 154 (71.0%)
    4–  6 │ ██████                          33 (15.2%)
    7–  9 │ ██                              12 ( 5.5%)
   10– 12 │                                  2 ( 0.9%)
   13– 15 │ █                                5 ( 2.3%) ◄ threshold
   16– 18 │ █                                4 ( 1.8%)
   19– 21 │                                  2 ( 0.9%)
   22– 25 │                                  1 ( 0.5%)
   26+    │ █                                4 ( 1.8%)

11 functions exceeding threshold:

Complexity	Function	File
64	`stream_initial_logs`	`src/terok_sandbox/runtime.py`
45	`_handle_request`	`src/terok_sandbox/credential_proxy/server.py`
34	`_handle_connection`	`src/terok_sandbox/credential_proxy/ssh_agent.py`
33	`_handle_ssh_list`	`src/terok_sandbox/commands.py`
23	`SSHManager::init`	`src/terok_sandbox/ssh.py`
21	`_run_multi`	`src/terok_sandbox/credential_proxy/server.py`
21	`_make_handler_class`	`src/terok_sandbox/gate/server.py`
17	`_installed_base_path`	`src/terok_sandbox/gate_server.py`
16	`_wire_command`	`src/terok_sandbox/cli.py`
16	`ensure_server_reachable`	`src/terok_sandbox/gate_server.py`
16	`Sandbox::run`	`src/terok_sandbox/sandbox.py`

Dead Code Analysis¶

No dead code found at 80% confidence threshold.

Docstring Coverage¶

Needed: 13; Found: 12; Missing: 1; Coverage: 92.3%
Needed: 26; Found: 22; Missing: 4; Coverage: 84.6%
Needed: 17; Found: 16; Missing: 1; Coverage: 94.1%
Needed: 284 - Found: 278 - Missing: 6
Total coverage: 97.9% - Grade: Excellent

Generated by scc, complexipy, vulture, tach, and docstr-coverage.