cleveragents/cleveragents-core

Fork 3

UAT: 694 function-level imports found across codebase — CONTRIBUTING.md prohibits imports inside indented code blocks #4136

New issue

Open

opened 2026-04-06 10:33:45 +00:00 by freemo · 2 comments

freemo commented

2026-04-06 10:33:45 +00:00

Owner

Metadata

Branch: fix/backlog/function-level-imports-compliance
Commit Message: fix(imports): move all function-level imports to module top-level per CONTRIBUTING.md
Milestone: (backlog — see note below)
Parent Epic: (orphan — needs manual linking, see comment)

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Bug Report

Feature Area: Code Organization and Module Structure
Tested by: UAT tester instance uat-tester-code-org-001
Severity: Medium (CONTRIBUTING.md compliance violation — widespread)

What Was Tested

Checked all Python files in src/cleveragents/ for compliance with CONTRIBUTING.md lines 1379-1384:

"Ensure all imports (including from statements) are at the top of the Python file. Do not scatter imports throughout the file or bury them inside functions or methods. Never encapsulate imports inside an indented code block (like an if, try, or for block). The only exception is for imports used exclusively for type checking purposes and only when strictly needed to avoid circular dependencies (e.g., if TYPE_CHECKING:)."

Expected Behavior (from CONTRIBUTING.md)

All imports must be at the top of the file. The only exception is if TYPE_CHECKING: blocks for type-only imports.

Actual Behavior

694 function-level or method-level imports were found across the codebase — imports inside function/method bodies that are NOT inside if TYPE_CHECKING: blocks.

Evidence (Representative Sample)

Application layer violations:

application/services/plan_service.py:445:        from cleveragents.application.services.memory_service import MemoryService
application/services/plan_service.py:807:        from cleveragents.agents import AutoDebugAgent, AutoDebugState
application/services/acms_skeleton_compressor.py:256:    from cleveragents.application.services.acms_service import SkeletonCompressor
application/services/project_service.py:138:        from cleveragents.infrastructure.database.legacy_migrator import ...
application/services/checkpoint_service.py:738:            from cleveragents.domain.models.core.plan import ProcessingState
application/services/checkpoint_service.py:862:            from cleveragents.infrastructure.database.repositories import ...
application/services/component_resolver.py:725:            from cleveragents.application import services as builtin_services
application/services/vector_store_service.py:374:                from langchain_openai import OpenAIEmbeddings
application/services/vector_store_service.py:406:                from langchain_openai import OpenAIEmbeddings

Infrastructure layer violations:

infrastructure/database/models.py:336:        from cleveragents.domain.models.core.action import ...
infrastructure/database/models.py:800:        from cleveragents.domain.models.core.plan import NamespacedName
infrastructure/database/repositories.py:393:        from cleveragents.domain.models.core import PlanBuild, PlanResult
infrastructure/database/repositories.py:2005:        from cleveragents.domain.models.core.resource_type import ...

Resource handler violations:

resource/handlers/_base.py:357:            from cleveragents.application.services.permission_service import ...
resource/handlers/fs_directory.py:283:        import tempfile
resource/handlers/git_checkout.py:179:            import shutil
resource/handlers/database.py:385:        import importlib

TUI violations:

tui/permissions/models.py:91:        import difflib
tui/permissions/models.py:106:        import difflib
tui/permissions/models.py:142:        import difflib

Steps to Reproduce

grep -rn "^\s\+import \|^\s\+from .* import" src/cleveragents/ --include="*.py" | grep -v "TYPE_CHECKING\|#" | wc -l
# Returns: 694

Impact

Imports scattered throughout the codebase make dependency analysis difficult
Function-level imports can hide circular dependency issues
Violates the project's stated coding standards
Makes static analysis tools less effective

Suggested Fix

Move all function-level imports to the top of their respective files. Where circular imports prevent this, use if TYPE_CHECKING: blocks for type-only imports and restructure the code to break actual runtime circular dependencies.

Code Location

Widespread — affects at minimum:

src/cleveragents/application/services/ (multiple files)
src/cleveragents/infrastructure/database/models.py
src/cleveragents/infrastructure/database/repositories.py
src/cleveragents/resource/handlers/ (multiple files)
src/cleveragents/tui/permissions/models.py
src/cleveragents/cli/commands/plan.py

Subtasks

Audit all 694 violations and categorise: (a) safe to hoist, (b) circular dependency — needs TYPE_CHECKING, (c) conditional optional dependency
Hoist all category (a) imports to module top-level
Refactor category (b) imports: use if TYPE_CHECKING: for type-only uses; restructure runtime circular deps
Handle category (c) optional-dependency imports (e.g. langchain_openai) with a top-level try/except or lazy-import pattern approved by the project
Add a ruff or flake8-import-order / isort lint rule (or Semgrep rule) to prevent regression
Tests (Behave): add/update scenarios to cover any behaviour changes caused by import restructuring
Verify nox -e typecheck passes (Pyright)
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -e coverage_report

Definition of Done

All subtasks above are completed and checked off
Zero function-level imports remain outside if TYPE_CHECKING: blocks (re-run the grep command above returns 0)
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/backlog/function-level-imports-compliance` - **Commit Message**: `fix(imports): move all function-level imports to module top-level per CONTRIBUTING.md` - **Milestone**: *(backlog — see note below)* - **Parent Epic**: *(orphan — needs manual linking, see comment)* > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- ## Bug Report **Feature Area:** Code Organization and Module Structure **Tested by:** UAT tester instance uat-tester-code-org-001 **Severity:** Medium (CONTRIBUTING.md compliance violation — widespread) ### What Was Tested Checked all Python files in `src/cleveragents/` for compliance with CONTRIBUTING.md lines 1379-1384: > *"Ensure all imports (including `from` statements) are at the top of the Python file. Do not scatter imports throughout the file or bury them inside functions or methods. Never encapsulate imports inside an indented code block (like an `if`, `try`, or `for` block). The only exception is for imports used exclusively for type checking purposes and only when strictly needed to avoid circular dependencies (e.g., `if TYPE_CHECKING:`)."* ### Expected Behavior (from CONTRIBUTING.md) All imports must be at the top of the file. The only exception is `if TYPE_CHECKING:` blocks for type-only imports. ### Actual Behavior **694 function-level or method-level imports** were found across the codebase — imports inside function/method bodies that are NOT inside `if TYPE_CHECKING:` blocks. ### Evidence (Representative Sample) **Application layer violations:** ``` application/services/plan_service.py:445: from cleveragents.application.services.memory_service import MemoryService application/services/plan_service.py:807: from cleveragents.agents import AutoDebugAgent, AutoDebugState application/services/acms_skeleton_compressor.py:256: from cleveragents.application.services.acms_service import SkeletonCompressor application/services/project_service.py:138: from cleveragents.infrastructure.database.legacy_migrator import ... application/services/checkpoint_service.py:738: from cleveragents.domain.models.core.plan import ProcessingState application/services/checkpoint_service.py:862: from cleveragents.infrastructure.database.repositories import ... application/services/component_resolver.py:725: from cleveragents.application import services as builtin_services application/services/vector_store_service.py:374: from langchain_openai import OpenAIEmbeddings application/services/vector_store_service.py:406: from langchain_openai import OpenAIEmbeddings ``` **Infrastructure layer violations:** ``` infrastructure/database/models.py:336: from cleveragents.domain.models.core.action import ... infrastructure/database/models.py:800: from cleveragents.domain.models.core.plan import NamespacedName infrastructure/database/repositories.py:393: from cleveragents.domain.models.core import PlanBuild, PlanResult infrastructure/database/repositories.py:2005: from cleveragents.domain.models.core.resource_type import ... ``` **Resource handler violations:** ``` resource/handlers/_base.py:357: from cleveragents.application.services.permission_service import ... resource/handlers/fs_directory.py:283: import tempfile resource/handlers/git_checkout.py:179: import shutil resource/handlers/database.py:385: import importlib ``` **TUI violations:** ``` tui/permissions/models.py:91: import difflib tui/permissions/models.py:106: import difflib tui/permissions/models.py:142: import difflib ``` ### Steps to Reproduce ```bash grep -rn "^\s\+import \|^\s\+from .* import" src/cleveragents/ --include="*.py" | grep -v "TYPE_CHECKING\|#" | wc -l # Returns: 694 ``` ### Impact - Imports scattered throughout the codebase make dependency analysis difficult - Function-level imports can hide circular dependency issues - Violates the project's stated coding standards - Makes static analysis tools less effective ### Suggested Fix Move all function-level imports to the top of their respective files. Where circular imports prevent this, use `if TYPE_CHECKING:` blocks for type-only imports and restructure the code to break actual runtime circular dependencies. ### Code Location Widespread — affects at minimum: - `src/cleveragents/application/services/` (multiple files) - `src/cleveragents/infrastructure/database/models.py` - `src/cleveragents/infrastructure/database/repositories.py` - `src/cleveragents/resource/handlers/` (multiple files) - `src/cleveragents/tui/permissions/models.py` - `src/cleveragents/cli/commands/plan.py` --- ## Subtasks - [ ] Audit all 694 violations and categorise: (a) safe to hoist, (b) circular dependency — needs `TYPE_CHECKING`, (c) conditional optional dependency - [ ] Hoist all category (a) imports to module top-level - [ ] Refactor category (b) imports: use `if TYPE_CHECKING:` for type-only uses; restructure runtime circular deps - [ ] Handle category (c) optional-dependency imports (e.g. `langchain_openai`) with a top-level try/except or lazy-import pattern approved by the project - [ ] Add a `ruff` or `flake8-import-order` / `isort` lint rule (or Semgrep rule) to prevent regression - [ ] Tests (Behave): add/update scenarios to cover any behaviour changes caused by import restructuring - [ ] Verify `nox -e typecheck` passes (Pyright) - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -e coverage_report` ## Definition of Done - [ ] All subtasks above are completed and checked off - [ ] Zero function-level imports remain outside `if TYPE_CHECKING:` blocks (re-run the grep command above returns 0) - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo commented

2026-04-06 10:34:06 +00:00

Author

Owner

⚠️ Orphan Issue — Needs Manual Parent Epic Linking

This issue was created without a parent Epic. Per CONTRIBUTING.md, orphan issues are not permitted — every issue must be linked to a parent Epic using Forgejo's dependency system (child blocks parent).

Action required by a human reviewer:

Identify or create an appropriate parent Epic for this code-quality / import-compliance work (e.g. a "Code Standards Compliance" or "Technical Debt" Epic)

Create the dependency link so that this issue (#4136) blocks the parent Epic:

curl -s -X POST "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/issues/4136/blocks" \
  -H "Authorization: token <PAT>" \
  -H "Content-Type: application/json" \
  -d '{"owner": "cleveragents", "repo": "cleveragents-core", "index": <PARENT_EPIC_NUMBER>}'

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

⚠️ **Orphan Issue — Needs Manual Parent Epic Linking** This issue was created without a parent Epic. Per CONTRIBUTING.md, orphan issues are not permitted — every issue must be linked to a parent Epic using Forgejo's dependency system (child **blocks** parent). **Action required by a human reviewer:** 1. Identify or create an appropriate parent Epic for this code-quality / import-compliance work (e.g. a "Code Standards Compliance" or "Technical Debt" Epic) 2. Create the dependency link so that this issue (#4136) **blocks** the parent Epic: ```bash curl -s -X POST "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/issues/4136/blocks" \ -H "Authorization: token <PAT>" \ -H "Content-Type: application/json" \ -d '{"owner": "cleveragents", "repo": "cleveragents-core", "index": <PARENT_EPIC_NUMBER>}' ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo referenced this issue

2026-04-06 10:39:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added this to the v3.5.0 milestone

2026-04-06 18:07:28 +00:00

freemo commented

2026-04-06 18:45:13 +00:00

Author

Owner

Milestone Triage Decision: Moved to Backlog

This build/metadata compliance issue has been moved out of v3.5.0 during aggressive milestone triage. While important for code quality, it does not block core autonomy hardening functionality.

Reasoning:

v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle)
This issue: Build compliance (function-level imports) - important but not blocking
Impact: Code quality improvement, not functional capability

Will be addressed in a future milestone after core autonomy functionality is stable.

**Milestone Triage Decision: Moved to Backlog** This build/metadata compliance issue has been moved out of v3.5.0 during aggressive milestone triage. While important for code quality, it does not block core autonomy hardening functionality. **Reasoning:** - v3.5.0 focus: Essential autonomy hardening (guard enforcement, A2A facade, plan lifecycle) - This issue: Build compliance (function-level imports) - important but not blocking - Impact: Code quality improvement, not functional capability Will be addressed in a future milestone after core autonomy functionality is stable.

freemo removed this from the v3.5.0 milestone

2026-04-06 20:42:40 +00:00