Research: Issue #313: Core → Utils Layer Violation

Research – Issue #313: Core → Utils Layer Violation

Date: 2026-01-27 Owner: Claude (research agent) Phase: Research Issue: #313 Layer violation: core → utils (18 imports, skips Layer 2)

Goal

Document all core → utils imports, categorize by fix strategy, and provide a migration plan to eliminate the layer violation where core (Layer 1) imports directly from utils (Layer 3), skipping Layer 2 (tools/indexing/lsp).

Architecture Reference

ui (Layer 0)
  ↓ only
core (Layer 1)
  ↓ only
tools | indexing | lsp (Layer 2)
  ↓ only
utils (Layer 3)

Foundation (exempt): types, configuration, constants

Findings

Current Import Analysis

Total: 24 imports across 13 files

Utils Modules Dependency Analysis

Existing Facade Pattern

Core already has facade files that re-export from utils:

• core/messaging.py → re-exports get_content
• core/formatting.py → re-exports truncate_diagnostic_message
• core/user_configuration.py → re-exports config functions
• core/system_paths.py → re-exports path utilities
• core/file_filter.py → re-exports FileFilter

Pattern uses underscore-prefixed imports:

from tunacode.utils.messaging import get_content as _get_content

Key Patterns / Solutions Found

Fix Strategy Categories

1. Move to Foundation (configuration/) - 4 modules

• utils/system/paths.py → configuration/paths.py
• utils/config/user_configuration.py → configuration/user_config.py
• utils/limits.py → configuration/limits.py
• utils/system/ignore_patterns.py → configuration/ignore_patterns.py

2. Move to Foundation (types/adapters/) - 1 module

• utils/messaging/ → types/adapters/ (message format conversion)

3. Re-export through Layer 2 (tools/) - 1 module

• utils/parsing/ → tools/parsing/ (tool-specific parsing logic)

4. Inline into Core - 2 modules

• utils/ui/helpers.py (DotDict, 14 lines) → inline into core/agents/main.py
• utils/formatting.py (6-line function) → inline into core/formatting.py

5. Move to Infrastructure - 1 module

• utils/ui/file_filter.py → new infrastructure/ package

Migration Order

To avoid circular dependencies, migrate in this order:

1. Phase 1 - Inline tiny modules (no dependencies)

   • Inline utils/formatting.py into core/formatting.py
   • Inline DotDict from utils/ui/helpers.py into core/agents/main.py

2. Phase 2 - Foundation layer (configuration/)

   • Move utils/system/ignore_patterns.py → configuration/ignore_patterns.py
   • Move utils/config/user_configuration.py → configuration/user_config.py
   • Move utils/limits.py → configuration/limits.py
   • Move utils/system/paths.py → configuration/paths.py

3. Phase 3 - Foundation layer (types/adapters/)

   • Move utils/messaging/ → types/adapters/

4. Phase 4 - Infrastructure

   • Create infrastructure/ package
   • Move utils/ui/file_filter.py → infrastructure/file_filter.py

5. Phase 5 - Tool layer re-export

   • Move utils/parsing/ → tools/parsing/
   • Update core/agents/.../tool_dispatcher.py to import from tools.parsing

6. Phase 6 - Cleanup

   • Delete empty utils/ directories
   • Update all imports across codebase
   • Verify with grimp/import-linter

Knowledge Gaps

• Cross-layer import counts: Need to verify tools/ also imports from some utils modules (limits, ignore_patterns)
• Test coverage: Need to verify tests don't have direct utils imports
• UI layer: Need to verify UI doesn't import directly from utils (should go through core facades)

Acceptance Criteria (from issue)

• Zero direct imports from tunacode.utils in tunacode.core
• Utils accessed through tools/indexing/lsp layer OR moved to foundation
• import-linter passes with layer config
• No new functionality added (pure refactor)
• Tests pass

Impact Assessment

References

• Issue: https://github.com/alchemiststudiosDOTai/tunacode/issues/313
• Architecture: docs/architecture/layers_html.html
• Dependency map: docs/architecture/DEPENDENCY_MAP.md
• Related issues: #311 (core→types), #312 (core→configuration), #314 (Layer 2 lateral), #315 (lsp→configuration)

File Inventory

Files to Modify (core/ - update imports)

1. src/tunacode/core/system_paths.py
2. src/tunacode/core/agents/resume/sanitize_debug.py
3. src/tunacode/core/agents/resume/summary.py
4. src/tunacode/core/agents/resume/prune.py
5. src/tunacode/core/agents/resume/sanitize.py
6. src/tunacode/core/agents/agent_components/agent_config.py
7. src/tunacode/core/agents/agent_components/orchestrator/tool_dispatcher.py
8. src/tunacode/core/agents/main.py
9. src/tunacode/core/file_filter.py
10. src/tunacode/core/formatting.py
11. src/tunacode/core/user_configuration.py
12. src/tunacode/core/state.py
13. src/tunacode/core/messaging.py

Files to Move/Create

Files to Delete (after migration)

• src/tunacode/utils/formatting.py
• src/tunacode/utils/ui/helpers.py (if only contains DotDict)
• Empty utils/ subdirectories