BUG-HUNT: [error-handling] Broad OSError exception in `_collect_adr_inventory` hides file access errors #2397

New issue

Open

opened 2026-04-03 17:31:51 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 17:31:51 +00:00

Owner

Metadata

Branch: bugfix/m7-adr-inventory-oserror-silent
Commit Message: fix(hooks): log warning when OSError occurs reading ADR file in _collect_adr_inventory
Milestone: v3.6.0 (Post-MVP Release)
Parent Epic: #400

Background

The function _collect_adr_inventory in hooks/adr_hooks.py reads all ADR files to generate an inventory. When reading a file, it uses a bare try...except OSError: block. If an OSError occurs (e.g., due to incorrect file permissions), the exception is caught silently and the loop continues to the next file with no logging or warning. This means that if an ADR file is unreadable, it will be silently omitted from the generated ADR index page, violating the project's error-handling standard that errors must never be suppressed.

Location: hooks/adr_hooks.py, function _collect_adr_inventory, lines 395–396.

Violates: CONTRIBUTING.md error-handling rule — "Errors must never be suppressed. Exceptions should propagate to the top-level execution where they can be logged and handled centrally."

Current Behaviour

# hooks/adr_hooks.py:393-396
try:
    content = Path(f.abs_src_path).read_text(encoding="utf-8")
except OSError:
    continue

An unreadable ADR file is silently skipped. No log message is emitted. The user has no indication that the ADR inventory is incomplete.

Expected Behaviour

When an OSError occurs while reading an ADR file, a log.warning(...) is emitted identifying the affected file and the error, so the user can diagnose and fix the underlying file-system issue.

Suggested Fix

try:
    content = Path(f.abs_src_path).read_text(encoding="utf-8")
except OSError as e:
    log.warning("Could not read ADR file %s: %s", f.src_path, e)
    continue

Subtasks

Write a failing Behave unit test (TDD) that verifies a log.warning is emitted when OSError is raised reading an ADR file
Implement the fix: capture the exception as e and add log.warning("Could not read ADR file %s: %s", f.src_path, e) inside the except block
Verify the fix does not alter behaviour for successfully-read ADR files
Run nox -s lint and resolve any issues
Run nox -s typecheck and resolve any type errors
Run nox -s unit_tests and confirm all tests pass
Run nox -s coverage_report and confirm coverage ≥ 97%
Run full nox suite and confirm all stages pass

Definition of Done

All subtasks above are checked off
A failing Behave test reproducing the bug is committed to the TDD branch before the fix
The fix is committed with the exact commit message specified in Metadata
A pull request is submitted, reviewed (≥ 2 approvals), and merged
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `bugfix/m7-adr-inventory-oserror-silent` - **Commit Message**: `fix(hooks): log warning when OSError occurs reading ADR file in _collect_adr_inventory` - **Milestone**: v3.6.0 (Post-MVP Release) - **Parent Epic**: #400 ## Background The function `_collect_adr_inventory` in `hooks/adr_hooks.py` reads all ADR files to generate an inventory. When reading a file, it uses a bare `try...except OSError:` block. If an `OSError` occurs (e.g., due to incorrect file permissions), the exception is caught silently and the loop continues to the next file with no logging or warning. This means that if an ADR file is unreadable, it will be silently omitted from the generated ADR index page, violating the project's error-handling standard that errors must never be suppressed. **Location**: `hooks/adr_hooks.py`, function `_collect_adr_inventory`, lines 395–396. **Violates**: CONTRIBUTING.md error-handling rule — *"Errors must never be suppressed. Exceptions should propagate to the top-level execution where they can be logged and handled centrally."* ## Current Behaviour ```python # hooks/adr_hooks.py:393-396 try: content = Path(f.abs_src_path).read_text(encoding="utf-8") except OSError: continue ``` An unreadable ADR file is silently skipped. No log message is emitted. The user has no indication that the ADR inventory is incomplete. ## Expected Behaviour When an `OSError` occurs while reading an ADR file, a `log.warning(...)` is emitted identifying the affected file and the error, so the user can diagnose and fix the underlying file-system issue. ## Suggested Fix ```python try: content = Path(f.abs_src_path).read_text(encoding="utf-8") except OSError as e: log.warning("Could not read ADR file %s: %s", f.src_path, e) continue ``` ## Subtasks - [ ] Write a failing Behave unit test (TDD) that verifies a `log.warning` is emitted when `OSError` is raised reading an ADR file - [ ] Implement the fix: capture the exception as `e` and add `log.warning("Could not read ADR file %s: %s", f.src_path, e)` inside the `except` block - [ ] Verify the fix does not alter behaviour for successfully-read ADR files - [ ] Run `nox -s lint` and resolve any issues - [ ] Run `nox -s typecheck` and resolve any type errors - [ ] Run `nox -s unit_tests` and confirm all tests pass - [ ] Run `nox -s coverage_report` and confirm coverage ≥ 97% - [ ] Run full `nox` suite and confirm all stages pass ## Definition of Done - [ ] All subtasks above are checked off - [ ] A failing Behave test reproducing the bug is committed to the TDD branch before the fix - [ ] The fix is committed with the exact commit message specified in Metadata - [ ] A pull request is submitted, reviewed (≥ 2 approvals), and merged - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-03 17:31:56 +00:00

freemo added a new dependency

2026-04-03 17:32:19 +00:00

#400 Epic: Post-MVP Security

freemo commented

2026-04-03 18:26:10 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — Broad OSError exception in _collect_adr_inventory hides file access errors. Error handling quality improvement.
Milestone: v3.6.0
MoSCoW: Could Have — The ADR inventory collection works in normal operation. This only matters when file access fails, which is rare.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — Broad `OSError` exception in `_collect_adr_inventory` hides file access errors. Error handling quality improvement. - **Milestone**: v3.6.0 - **MoSCoW**: Could Have — The ADR inventory collection works in normal operation. This only matters when file access fails, which is rare. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

MoSCoW

Could have

label

2026-04-03 18:26:35 +00:00

freemo removed the

MoSCoW

Could have

label

2026-04-05 04:16:53 +00:00