Code Quality Report¶
Generated: 2026-04-04 03:23 UTC
Lines of Code¶
| Files | Code | Comment | Blank | Total | |
|---|---|---|---|---|---|
Source (src/terok/) |
85 | 13 819 | 2 417 | 1 863 | 18 099 |
Tests (tests/) |
119 | 19 774 | 1 691 | 2 881 | 24 346 |
| Combined | 204 | 33 593 | 4 108 | 4 744 | 42 445 |
- Comment/code ratio: 17%
- Test/source ratio: 143.1%
Source by module (click to expand)
| Module | Files | Code | Comment | Blank |
|---|---|---|---|---|
terok/ |
85 | 13 819 | 2 417 | 1 863 |
terok/cli/ |
15 | 1 763 | 205 | 276 |
terok/cli/commands/ |
11 | 1 481 | 167 | 242 |
terok/cli/commands/_completers.py |
— | 17 | 5 | 8 |
terok/cli/commands/completions.py |
— | 96 | 12 | 22 |
terok/cli/commands/credentials.py |
— | 43 | 8 | 1 |
terok/cli/commands/image.py |
— | 65 | 10 | 22 |
terok/cli/commands/info.py |
— | 234 | 19 | 32 |
terok/cli/commands/project.py |
— | 112 | 11 | 21 |
terok/cli/commands/setup.py |
— | 147 | 12 | 18 |
terok/cli/commands/shield.py |
— | 150 | 22 | 16 |
terok/cli/commands/sickbay.py |
— | 257 | 43 | 59 |
terok/cli/commands/task.py |
— | 360 | 17 | 42 |
terok/cli/__init__.py |
— | 2 | 3 | 3 |
terok/cli/__main__.py |
— | 3 | 3 | 3 |
terok/cli/main.py |
— | 137 | 24 | 26 |
terok/cli/wiring.py |
— | 140 | 8 | 2 |
terok/lib/ |
41 | 6 184 | 1 468 | 944 |
terok/lib/core/ |
11 | 1 369 | 452 | 339 |
terok/lib/core/config.py |
— | 252 | 136 | 69 |
terok/lib/core/git_authorship.py |
— | 31 | 7 | 2 |
terok/lib/core/images.py |
— | 21 | 9 | 12 |
terok/lib/core/paths.py |
— | 57 | 37 | 22 |
terok/lib/core/project_model.py |
— | 63 | 37 | 18 |
terok/lib/core/projects.py |
— | 322 | 50 | 16 |
terok/lib/core/task_display.py |
— | 83 | 37 | 34 |
terok/lib/core/version.py |
— | 178 | 35 | 21 |
terok/lib/core/work_status.py |
— | 136 | 38 | 20 |
terok/lib/core/yaml_schema.py |
— | 226 | 63 | 124 |
terok/lib/domain/ |
11 | 1 743 | 406 | 240 |
terok/lib/domain/wizards/ |
2 | 169 | 44 | 45 |
terok/lib/domain/wizards/new_project.py |
— | 169 | 41 | 44 |
terok/lib/domain/agent_config.py |
— | 56 | 32 | 17 |
terok/lib/domain/facade.py |
— | 146 | 23 | 19 |
terok/lib/domain/image_cleanup.py |
— | 174 | 55 | 41 |
terok/lib/domain/log_format.py |
— | 218 | 67 | 53 |
terok/lib/domain/project.py |
— | 447 | 89 | 12 |
terok/lib/domain/project_state.py |
— | 257 | 28 | 7 |
terok/lib/domain/task.py |
— | 125 | 25 | 11 |
terok/lib/domain/task_logs.py |
— | 151 | 40 | 35 |
terok/lib/orchestration/ |
10 | 2 795 | 457 | 295 |
terok/lib/orchestration/autopilot.py |
— | 29 | 21 | 2 |
terok/lib/orchestration/container_doctor.py |
— | 193 | 60 | 61 |
terok/lib/orchestration/container_exec.py |
— | 73 | 19 | 15 |
terok/lib/orchestration/docker.py |
— | 184 | 58 | 58 |
terok/lib/orchestration/environment.py |
— | 357 | 77 | 22 |
terok/lib/orchestration/hooks.py |
— | 80 | 36 | 13 |
terok/lib/orchestration/ports.py |
— | 43 | 16 | 11 |
terok/lib/orchestration/task_runners.py |
— | 958 | 56 | 55 |
terok/lib/orchestration/tasks.py |
— | 878 | 111 | 58 |
terok/lib/util/ |
8 | 277 | 145 | 69 |
terok/lib/util/ansi.py |
— | 27 | 20 | 14 |
terok/lib/util/emoji.py |
— | 85 | 30 | 17 |
terok/lib/util/fs.py |
— | 59 | 25 | 10 |
terok/lib/util/host_cmd.py |
— | 31 | 25 | 8 |
terok/lib/util/logging_utils.py |
— | 23 | 33 | 13 |
terok/lib/util/template_utils.py |
— | 6 | 5 | 4 |
terok/lib/util/yaml.py |
— | 46 | 4 | 2 |
terok/resources/ |
8 | 227 | 46 | 54 |
terok/resources/instructions/ |
1 | 36 | 0 | 18 |
terok/resources/presets/ |
3 | 137 | 26 | 20 |
terok/resources/templates/ |
4 | 54 | 20 | 16 |
terok/resources/templates/projects/ |
4 | 54 | 20 | 16 |
terok/tui/ |
17 | 5 555 | 670 | 574 |
terok/tui/widgets/ |
6 | 688 | 55 | 50 |
terok/tui/widgets/__init__.py |
— | 25 | 11 | 3 |
terok/tui/widgets/project_list.py |
— | 114 | 10 | 12 |
terok/tui/widgets/project_state.py |
— | 232 | 5 | 14 |
terok/tui/widgets/status_bar.py |
— | 21 | 14 | 6 |
terok/tui/widgets/task_detail.py |
— | 170 | 3 | 6 |
terok/tui/widgets/task_list.py |
— | 126 | 12 | 9 |
terok/tui/__init__.py |
— | 2 | 3 | 3 |
terok/tui/__main__.py |
— | 3 | 3 | 3 |
terok/tui/app.py |
— | 1 014 | 94 | 82 |
terok/tui/clipboard.py |
— | 122 | 28 | 28 |
terok/tui/log_viewer.py |
— | 504 | 42 | 4 |
terok/tui/polling.py |
— | 180 | 77 | 56 |
terok/tui/project_actions.py |
— | 549 | 37 | 31 |
terok/tui/screens.py |
— | 1 660 | 197 | 203 |
terok/tui/serve.py |
— | 53 | 10 | 11 |
terok/tui/shell_launch.py |
— | 142 | 53 | 30 |
terok/tui/task_actions.py |
— | 638 | 71 | 73 |
terok/ui_utils/ |
3 | 68 | 16 | 10 |
terok/ui_utils/editor.py |
— | 53 | 2 | 1 |
terok/ui_utils/terminal.py |
— | 15 | 11 | 8 |
terok/__init__.py |
— | 22 | 12 | 5 |
Architecture¶
Layer Overview¶
graph LR
core["core (20 modules)"]
domain["domain (8 modules)"]
orchestration["orchestration (10 modules)"]
presentation["presentation (2 modules)"]
domain -->|17 deps| core
domain -->|12 deps| orchestration
orchestration -->|33 deps| core
presentation -->|12 deps| core
presentation -->|3 deps| domain
presentation -->|6 deps| orchestrationModule Dependency Graph¶
graph TD
terok.cli -->|3| terok.lib.core
terok.cli -->|3| terok.lib.domain
terok.cli -->|3| terok.lib.orchestration
terok.cli -->|2| terok.lib.util
terok.cli --> terok.ui_utils.terminal
terok.lib.core --> terok
terok.lib.core -->|4| terok.lib.util
terok.lib.domain -->|13| terok.lib.core
terok.lib.domain -->|11| terok.lib.orchestration
terok.lib.domain -->|5| terok.lib.util
terok.lib.domain --> terok.ui_utils.editor
terok.lib.orchestration -->|16| terok.lib.core
terok.lib.orchestration --> terok.lib.domain
terok.lib.orchestration -->|15| terok.lib.util
terok.lib.util --> terok.lib.core
terok.tui -->|4| terok.lib.core
terok.tui --> terok.lib.domain
terok.tui -->|2| terok.lib.orchestration
terok.tui -->|2| terok.lib.util
terok.ui_utils.terminal --> terok.lib.utilModule Boundaries¶
40 modules, 115 dependency edges — all boundaries validated.
Module Summary¶
40 modules across 4 layers (click to expand)
| Module | Layer | Deps | Description |
|---|---|---|---|
terok.cli |
presentation | 12 | CLI frontend |
terok.tui |
presentation | 9 | TUI frontend |
terok.lib.domain.facade |
domain | 10 | Service facade (aggregates shared cross-cutting operations) |
terok.lib.domain.project |
domain | 10 | Rich domain object: Project (Aggregate Root) |
terok.lib.domain.task |
domain | 4 | Rich domain object: Task (Entity) |
terok.lib.orchestration.autopilot |
orchestration | 1 | Autopilot container lifecycle (wait, logs) |
terok.lib.domain.task_logs |
domain | 4 | Task log viewing and streaming |
terok.lib.domain.log_format |
domain | 1 | Agent log formatters (Claude stream-json, plain text) |
terok.lib.domain.image_cleanup |
domain | 1 | Image listing & cleanup |
terok.lib.domain.agent_config |
orchestration | 2 | Lives in domain/ but has orchestration-level layer so that task_runners can import it. |
terok.lib.domain.project_state |
domain | 4 | Project infrastructure state (queries podman & filesystem) |
terok.lib.domain.wizards.new_project |
domain | 4 | Interactive project creation |
terok.lib.orchestration.task_runners |
orchestration | 12 | Task container runners (CLI, headless, toad, restart) |
terok.lib.orchestration.tasks |
orchestration | 12 | Task metadata, lifecycle, and queries |
terok.lib.orchestration.environment |
orchestration | 4 | Task environment & volume mounts |
terok.lib.orchestration.docker |
orchestration | 4 | Dockerfile generation & image building |
terok.lib.orchestration.ports |
orchestration | 2 | Task port allocation |
terok.lib.orchestration.hooks |
orchestration | 1 | Task lifecycle hooks (host-side) |
terok.lib.orchestration.container_exec |
orchestration | 1 | Container-based command execution (sandboxed git via podman exec) |
terok.lib.orchestration.container_doctor |
orchestration | 4 | In-container health checks (layered doctor protocol via podman exec) |
terok |
core | 0 | Top-level package (version metadata only) |
terok.lib.core.version |
core | 1 | Version info |
terok.lib.core.paths |
core | 0 | Path resolution (FHS/XDG) |
terok.lib.core.config |
core | 3 | Configuration management |
terok.lib.core.project_model |
core | 0 | Project and preset data models (pure types, no I/O) |
terok.lib.core.yaml_schema |
core | 0 | Raw YAML schema models (Pydantic validation, no I/O) |
terok.lib.core.git_authorship |
core | 0 | Git authorship mode helpers |
terok.lib.core.projects |
core | 5 | Project discovery, loading, and preset management |
terok.lib.core.images |
core | 0 | Image naming conventions |
terok.lib.core.task_display |
core | 1 | Task display types and status computation |
terok.lib.core.work_status |
core | 1 | Agent work status reading |
terok.ui_utils.terminal |
core | 1 | Terminal ANSI formatting |
terok.ui_utils.editor |
core | 0 | $EDITOR launching |
terok.lib.util.fs |
core | 0 | Filesystem helpers (mkdir, writable check) |
terok.lib.util.template_utils |
core | 0 | Simple {{VAR}} template rendering |
terok.lib.util.ansi |
core | 0 | ANSI color utilities |
terok.lib.util.logging_utils |
core | 1 | Debug logging stub |
terok.lib.util.emoji |
core | 0 | Emoji display-width utilities |
terok.lib.util.yaml |
core | 0 | Centralised YAML I/O (round-trip via ruamel.yaml) |
terok.lib.util.host_cmd |
core | 0 | Host-side subprocess safety guards |
Test Coverage¶
Cognitive Complexity¶
Threshold: 15 (functions above this are listed below)
- Functions analyzed: 696
- Median complexity: 1.0 · Average: 3.3 · Max: 74
- Within threshold (15): 97% (674/696)
0– 3 │ ██████████████████████████████ 499 (71.7%)
4– 6 │ █████ 85 (12.2%)
7– 9 │ ███ 49 ( 7.0%)
10– 12 │ ██ 28 ( 4.0%)
13– 15 │ █ 13 ( 1.9%) ◄ threshold
16– 18 │ 7 ( 1.0%)
19– 21 │ 2 ( 0.3%)
22– 25 │ 6 ( 0.9%)
26+ │ 7 ( 1.0%)
22 functions exceeding threshold:
| Complexity | Function | File |
|---|---|---|
| 74 | render_project_details |
src/terok/tui/widgets/project_state.py |
| 62 | LogViewerScreen::_stream_logs |
src/terok/tui/log_viewer.py |
| 57 | get_project_state |
src/terok/lib/domain/project_state.py |
| 54 | task_logs |
src/terok/lib/domain/task_logs.py |
| 43 | _credential_proxy_env_and_volumes |
src/terok/lib/orchestration/environment.py |
| 32 | _print_config |
src/terok/cli/commands/info.py |
| 29 | render_task_details |
src/terok/tui/widgets/task_detail.py |
| 24 | get_version_info |
src/terok/lib/core/version.py |
| 24 | ClaudeStreamJsonFormatter::_handle_user |
src/terok/lib/domain/log_format.py |
| 24 | _TuiLogFormatter::_handle_user |
src/terok/tui/log_viewer.py |
| 24 | _parent_process_has_name |
src/terok/tui/shell_launch.py |
| 22 | dispatch |
src/terok/cli/commands/project.py |
| 22 | PollingMixin::_sync_worker |
src/terok/tui/polling.py |
| 21 | _dispatch_task_sub |
src/terok/cli/commands/task.py |
| 21 | _archive_project |
src/terok/lib/domain/project.py |
| 17 | _security_mode_env_and_volumes |
src/terok/lib/orchestration/environment.py |
| 17 | task_restart |
src/terok/lib/orchestration/task_runners.py |
| 17 | task_run_headless |
src/terok/lib/orchestration/task_runners.py |
| 16 | _check_containers |
src/terok/cli/commands/sickbay.py |
| 16 | wire |
src/terok/cli/wiring.py |
| 16 | collect_wizard_inputs |
src/terok/lib/domain/wizards/new_project.py |
| 16 | task_status |
src/terok/lib/orchestration/tasks.py |
Dead Code Analysis¶
| Confidence | Location | Issue |
|---|---|---|
| 100% confidence | src/terok/lib/domain/task_logs.py:134 |
unused variable 'frame' |
| 100% confidence | src/terok/lib/domain/task_logs.py:134 |
unused variable 'signum' |
Docstring Coverage¶
- Needed: 41; Found: 39; Missing: 2; Coverage: 95.1%
- Needed: 924 - Found: 922 - Missing: 2
- Total coverage: 99.8% - Grade: Excellent
Generated by scc, complexipy, vulture, tach, and docstr-coverage.