BUG: [error-handling] Silent exception swallowing in MigrationRunner._find_alembic_ini #1273

New issue

Open

opened 2026-04-02 08:15:04 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 08:15:04 +00:00

Owner

Metadata

Branch: fix/error-handling-migration-runner-silent-exception
Commit Message: fix(error-handling): log swallowed exception in MigrationRunner._find_alembic_ini
Milestone: v3.3.0
Parent Epic: #362

Background

The _find_alembic_ini static method in MigrationRunner uses a broad except Exception: pass to silently swallow any error that occurs when attempting to import the cleveragents package and resolve its __file__ path. This violates the project's error-handling standards (CONTRIBUTING.md: "Errors must never be suppressed") and makes it impossible to diagnose failures in non-standard installation environments.

Location

File: src/cleveragents/infrastructure/database/migration_runner.py
Function: MigrationRunner._find_alembic_ini
Lines: 66–68

Evidence

# Current (broken) code
try:
    import cleveragents as _pkg

    pkg_init = getattr(_pkg, "__file__", None)
    if pkg_init is not None:
        search_roots.append(Path(pkg_init).resolve().parent)
except Exception:  # pragma: no cover - defensive
    pass

Suggested Fix

except Exception as e:  # pragma: no cover - defensive
    _logger.debug("Could not determine package path for cleveragents: %s", e)

Subtasks

Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail that asserts the exception is logged at DEBUG level when the package import fails (e.g., by monkeypatching __import__ to raise)
Apply the one-line fix: bind the exception to e and emit _logger.debug("Could not determine package path for cleveragents: %s", e) in place of pass
Remove the @tdd_expected_fail tag from the TDD scenario once the fix is in place and verify it passes
Run nox -e typecheck to confirm no type regressions
Run nox -e unit_tests to confirm all Behave tests pass
Run nox -e coverage_report to confirm coverage remains ≥ 97%

Definition of Done

The @tdd_expected_fail TDD capture scenario is committed first and demonstrates the missing log
The fix (pass → _logger.debug(...)) is applied in MigrationRunner._find_alembic_ini (line 67 of migration_runner.py)
The TDD scenario passes without @tdd_expected_fail after the fix
No regressions in existing migration or database-related tests
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests, nox -e coverage_report)
Coverage >= 97%
Commit is on branch fix/error-handling-migration-runner-silent-exception with message fix(error-handling): log swallowed exception in MigrationRunner._find_alembic_ini
PR is merged and this issue is closed

## Metadata - **Branch**: `fix/error-handling-migration-runner-silent-exception` - **Commit Message**: `fix(error-handling): log swallowed exception in MigrationRunner._find_alembic_ini` - **Milestone**: v3.3.0 - **Parent Epic**: #362 ## Background The `_find_alembic_ini` static method in `MigrationRunner` uses a broad `except Exception: pass` to silently swallow any error that occurs when attempting to import the `cleveragents` package and resolve its `__file__` path. This violates the project's error-handling standards (CONTRIBUTING.md: *"Errors must never be suppressed"*) and makes it impossible to diagnose failures in non-standard installation environments. ### Location - **File**: `src/cleveragents/infrastructure/database/migration_runner.py` - **Function**: `MigrationRunner._find_alembic_ini` - **Lines**: 66–68 ### Evidence ```python # Current (broken) code try: import cleveragents as _pkg pkg_init = getattr(_pkg, "__file__", None) if pkg_init is not None: search_roots.append(Path(pkg_init).resolve().parent) except Exception: # pragma: no cover - defensive pass ``` ### Suggested Fix ```python except Exception as e: # pragma: no cover - defensive _logger.debug("Could not determine package path for cleveragents: %s", e) ``` ## Subtasks - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` that asserts the exception is logged at DEBUG level when the package import fails (e.g., by monkeypatching `__import__` to raise) - [ ] Apply the one-line fix: bind the exception to `e` and emit `_logger.debug("Could not determine package path for cleveragents: %s", e)` in place of `pass` - [ ] Remove the `@tdd_expected_fail` tag from the TDD scenario once the fix is in place and verify it passes - [ ] Run `nox -e typecheck` to confirm no type regressions - [ ] Run `nox -e unit_tests` to confirm all Behave tests pass - [ ] Run `nox -e coverage_report` to confirm coverage remains ≥ 97% ## Definition of Done - [ ] The `@tdd_expected_fail` TDD capture scenario is committed first and demonstrates the missing log - [ ] The fix (`pass` → `_logger.debug(...)`) is applied in `MigrationRunner._find_alembic_ini` (line 67 of `migration_runner.py`) - [ ] The TDD scenario passes without `@tdd_expected_fail` after the fix - [ ] No regressions in existing migration or database-related tests - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`, `nox -e coverage_report`) - [ ] Coverage >= 97% - [ ] Commit is on branch `fix/error-handling-migration-runner-silent-exception` with message `fix(error-handling): log swallowed exception in MigrationRunner._find_alembic_ini` - [ ] PR is merged and this issue is closed

Rows
Columns