UAT: Production code contains ~593 function-level imports violating CONTRIBUTING.md import guidelines #3926

New issue

Open

opened 2026-04-06 07:29:41 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 07:29:41 +00:00

Owner

Background and Context

The CONTRIBUTING.md import guidelines (lines 1377–1386) state:

"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 statement)."
"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:)."

A code-level audit of src/cleveragents/ using grep -rn "^ from \|^ from " (excluding TYPE_CHECKING blocks) found approximately 593 instances of imports inside functions, methods, try blocks, and other indented contexts — a widespread violation of the documented import standard.

Current Behavior

Multiple files contain imports inside functions, try blocks, and other indented contexts. Key examples:

src/cleveragents/application/services/plan_lifecycle_service.py lines 339–341:

try:
    from cleveragents.application.services.plan_executor import (
        EstimationStubActor,
    )

src/cleveragents/application/services/plan_lifecycle_service.py lines 423–426:

try:
    from cleveragents.actor.reconciliation import (
        InvariantReconciliationActor,
        ReconciliationResult,
    )

src/cleveragents/application/services/plan_service.py lines 445, 807–808 (imports inside methods)
src/cleveragents/application/container.py lines 249–250, 263–264, 274–275 (imports inside factory methods)
src/cleveragents/cli/main.py lines 38–40, 48–50 (imports inside functions)

Steps to reproduce:

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

Expected Behavior

Per CONTRIBUTING.md, all imports should be at the top of the file. The only permitted exception is if TYPE_CHECKING: blocks used strictly to avoid circular dependencies.

Acceptance Criteria

All function-level and indented imports in src/cleveragents/ are moved to module level, OR
CONTRIBUTING.md is explicitly updated to allow lazy imports in specific, documented contexts (e.g., CLI startup, optional dependencies), with a clear policy on when each pattern is acceptable
The grep command above returns 0 (or only legitimate TYPE_CHECKING-guarded imports)
No regressions introduced — all existing tests continue to pass
nox (all default sessions) passes with no new errors
Coverage remains ≥ 97%

Supporting Information

Scope: Approximately 593 instances across src/cleveragents/ — widespread, not isolated
Likely causes: Lazy imports for performance (CLI startup time), circular dependency avoidance, optional dependency guards
Resolution options:
1. Move all imports to module level (preferred per CONTRIBUTING.md)
2. Update CONTRIBUTING.md to explicitly allow lazy imports in specific contexts (e.g., CLI commands, optional dependencies) — this would require a policy decision by the project owner
Detection method: grep -rn "^ from \|^ from " src/cleveragents --include="*.py" | grep -v "TYPE_CHECKING"

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

Metadata

Branch: refactor/fix-function-level-imports
Commit Message: refactor(imports): move function-level imports to module level per CONTRIBUTING guidelines
Milestone: (Backlog — no milestone assigned)
Parent Epic: #2810 (CI Quality Gates Restoration — closest available; a dedicated code-quality Epic may be more appropriate)

Subtasks

Audit all ~593 instances and categorise: (a) straightforward move-to-top, (b) circular dependency, (c) optional/lazy import for performance
For category (a): move imports to module level
For category (b): convert to if TYPE_CHECKING: guard with TYPE_CHECKING import from typing
For category (c): decide with project owner whether to move to top or update CONTRIBUTING.md policy
Update CONTRIBUTING.md if a lazy-import exception policy is adopted
Tests (Behave): verify no unit test regressions after import restructuring
Tests (Robot): verify no integration test regressions
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
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 lines providing relevant details about the implementation.
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-uat-tester

## Background and Context The CONTRIBUTING.md import guidelines (lines 1377–1386) state: > "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` statement)." > "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:`)." A code-level audit of `src/cleveragents/` using `grep -rn "^ from \|^ from "` (excluding `TYPE_CHECKING` blocks) found approximately **593 instances** of imports inside functions, methods, `try` blocks, and other indented contexts — a widespread violation of the documented import standard. ## Current Behavior Multiple files contain imports inside functions, try blocks, and other indented contexts. Key examples: 1. `src/cleveragents/application/services/plan_lifecycle_service.py` lines 339–341: ```python try: from cleveragents.application.services.plan_executor import ( EstimationStubActor, ) ``` 2. `src/cleveragents/application/services/plan_lifecycle_service.py` lines 423–426: ```python try: from cleveragents.actor.reconciliation import ( InvariantReconciliationActor, ReconciliationResult, ) ``` 3. `src/cleveragents/application/services/plan_service.py` lines 445, 807–808 (imports inside methods) 4. `src/cleveragents/application/container.py` lines 249–250, 263–264, 274–275 (imports inside factory methods) 5. `src/cleveragents/cli/main.py` lines 38–40, 48–50 (imports inside functions) **Steps to reproduce:** ```bash grep -rn "^ from \|^ from " src/cleveragents --include="*.py" | grep -v "TYPE_CHECKING" | wc -l # Returns: 593 ``` ## Expected Behavior Per CONTRIBUTING.md, all imports should be at the top of the file. The only permitted exception is `if TYPE_CHECKING:` blocks used strictly to avoid circular dependencies. ## Acceptance Criteria - [ ] All function-level and indented imports in `src/cleveragents/` are moved to module level, OR - [ ] CONTRIBUTING.md is explicitly updated to allow lazy imports in specific, documented contexts (e.g., CLI startup, optional dependencies), with a clear policy on when each pattern is acceptable - [ ] The grep command above returns 0 (or only legitimate `TYPE_CHECKING`-guarded imports) - [ ] No regressions introduced — all existing tests continue to pass - [ ] `nox` (all default sessions) passes with no new errors - [ ] Coverage remains ≥ 97% ## Supporting Information - **Scope**: Approximately 593 instances across `src/cleveragents/` — widespread, not isolated - **Likely causes**: Lazy imports for performance (CLI startup time), circular dependency avoidance, optional dependency guards - **Resolution options**: 1. Move all imports to module level (preferred per CONTRIBUTING.md) 2. Update CONTRIBUTING.md to explicitly allow lazy imports in specific contexts (e.g., CLI commands, optional dependencies) — this would require a policy decision by the project owner - **Detection method**: `grep -rn "^ from \|^ from " src/cleveragents --include="*.py" | grep -v "TYPE_CHECKING"` --- > **Backlog note:** This issue was discovered during autonomous operation on milestone v3.7.0. It does not block milestone completion and has been placed in the backlog for human review and future milestone assignment. --- ## Metadata - **Branch**: `refactor/fix-function-level-imports` - **Commit Message**: `refactor(imports): move function-level imports to module level per CONTRIBUTING guidelines` - **Milestone**: *(Backlog — no milestone assigned)* - **Parent Epic**: #2810 (CI Quality Gates Restoration — closest available; a dedicated code-quality Epic may be more appropriate) ## Subtasks - [ ] Audit all ~593 instances and categorise: (a) straightforward move-to-top, (b) circular dependency, (c) optional/lazy import for performance - [ ] For category (a): move imports to module level - [ ] For category (b): convert to `if TYPE_CHECKING:` guard with `TYPE_CHECKING` import from `typing` - [ ] For category (c): decide with project owner whether to move to top or update CONTRIBUTING.md policy - [ ] Update CONTRIBUTING.md if a lazy-import exception policy is adopted - [ ] Tests (Behave): verify no unit test regressions after import restructuring - [ ] Tests (Robot): verify no integration test regressions - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - 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 lines providing relevant details about the implementation. - 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-uat-tester

freemo added a new dependency

2026-04-06 07:30:00 +00:00

#2810 Epic: CI Quality Gates Restoration — Restore All 11 CI Jobs to Passing on Master

freemo added the

Points

label

2026-04-06 07:31:58 +00:00

freemo referenced this issue

2026-04-06 07:44:00 +00:00

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

freemo referenced this issue

2026-04-06 07:49:16 +00:00