cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [error-handling] Silent SyntaxError suppression in check-adr-compliance.py violates fail-fast principles #7303

New issue

Open

opened 2026-04-10 15:45:35 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-10 15:45:35 +00:00

Owner

Metadata

Branch: bugfix/m5-check-adr-compliance-syntax-error-suppression
Commit Message: fix(scripts): remove silent SyntaxError suppression in ADR compliance checker
Milestone: v3.5.0
Parent Epic: #2810

Background and Context

The check_adr003_dependency_injection() function in scripts/check-adr-compliance.py uses a bare except SyntaxError: continue clause to silently discard syntax errors encountered during AST parsing of Python service files. This directly violates the project's explicit fail-fast error handling principles documented in CONTRIBUTING.md and docs/specification.md.

Per CONTRIBUTING.md:

CRITICAL: Do not suppress errors. Let exceptions propagate to the top level.
Only catch when you can meaningfully handle (retry logic, resource cleanup, adding context).
Fail-Fast: Type safety, early validation, assertions, no silent failures, explicit over implicit.

When a Python file under src/cleveragents/application/services/ contains a syntax error, the compliance checker silently skips it with no diagnostic output. This means:

Malformed Python files are invisible to the ADR compliance check
Developers receive a false "all clear" result even when files cannot be parsed
The root cause of a syntax error is hidden, making debugging significantly harder

Current Behavior

File: scripts/check-adr-compliance.py
Function: check_adr003_dependency_injection()
Lines: 68–69

for py_file in services_dir.rglob("*.py"):
    if py_file.name.startswith("__"):
        continue
    try:
        tree = ast.parse(py_file.read_text())
    except SyntaxError:
        continue  # ← Silent suppression: SyntaxError is swallowed, file is skipped

Reproduction steps:

Create a Python file with a syntax error under src/cleveragents/application/services/
Run nox -s adr_compliance
Observe: the compliance check reports zero violations and exits 0 — the malformed file is silently ignored

Expected output (fail-fast): The script should either raise the SyntaxError (letting it propagate to the caller) or emit a diagnostic message identifying the offending file and exit non-zero.

Actual output: No output, no error, exit code 0. The malformed file is invisible.

Expected Behavior

According to the project specification and CONTRIBUTING.md, the script should follow one of these approaches:

Propagate (preferred): Remove the except clause entirely and let SyntaxError propagate to the top-level handler, providing a clear traceback with the file path.
Log and fail: Catch SyntaxError, emit a diagnostic message including the file path and error details, append a violation entry, and continue scanning remaining files — but exit non-zero at the end.
Strict/lenient flag: Add a --strict CLI flag; in strict mode (default) propagate the error; in lenient mode log and continue.

Under no circumstances should the error be silently discarded.

Acceptance Criteria

check_adr003_dependency_injection() no longer contains a bare except SyntaxError: continue that discards the error silently
A Python file with a syntax error under src/cleveragents/application/services/ causes nox -s adr_compliance to exit non-zero with a meaningful diagnostic message
The fix is consistent with the fail-fast principle: no silent failures
All existing ADR compliance checks continue to pass on valid source files
All nox sessions pass with coverage ≥ 97%

Supporting Information

Related issue: #4057 — ADR compliance script references non-existent ADR-002 and ADR-007 (same script, separate defect)
Related issue: #7282 — Silent error suppression in ADR inventory collection (same pattern, different file: hooks/adr_hooks.py)
Specification reference: CONTRIBUTING.md § "Error and Exception Handling" — "CRITICAL: Do not suppress errors. Let exceptions propagate to the top level."
TDD workflow: Per CONTRIBUTING.md Bug Fix Workflow, a TDD: issue (Type/Testing) must be created and merged before the fix branch is opened. The bug fix branch depends on the TDD issue. After this issue is verified, a TDD issue will be created tagged @tdd_issue, @tdd_issue_<this-issue-number>, and @tdd_expected_fail to prove the bug exists before fixing it.

Subtasks

Create TDD issue (Type/Testing, title: TDD: BUG-HUNT: [error-handling] Silent SyntaxError suppression in check-adr-compliance.py) and link it as a dependency of this issue
Remove the bare except SyntaxError: continue clause from check_adr003_dependency_injection()
Implement fail-fast error handling: propagate SyntaxError or log diagnostic with file path and exit non-zero
Consider adding --strict / --lenient CLI flag for parsing mode control
Tests (Behave): Add scenario proving a syntax-errored file causes non-zero exit (tagged @tdd_issue, @tdd_issue_<N>, remove @tdd_expected_fail on fix)
Tests (Robot): Add integration test scenario for ADR compliance script error handling
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 matches the Commit Message in Metadata exactly: fix(scripts): remove silent SyntaxError suppression in ADR compliance checker
The commit is pushed to the remote on the branch matching the Branch in Metadata: bugfix/m5-check-adr-compliance-syntax-error-suppression
The commit is submitted as a pull request to master, reviewed, and merged.
All nox sessions pass (lint, typecheck, security, unit_tests, integration_tests, coverage_report).
Coverage ≥ 97%.
The @tdd_expected_fail tag has been removed from all @tdd_issue_<N> scenarios (CI gate enforced).

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: Bug Hunter | Agent: new-issue-creator

## Metadata - **Branch**: `bugfix/m5-check-adr-compliance-syntax-error-suppression` - **Commit Message**: `fix(scripts): remove silent SyntaxError suppression in ADR compliance checker` - **Milestone**: v3.5.0 - **Parent Epic**: #2810 ## Background and Context The `check_adr003_dependency_injection()` function in `scripts/check-adr-compliance.py` uses a bare `except SyntaxError: continue` clause to silently discard syntax errors encountered during AST parsing of Python service files. This directly violates the project's explicit fail-fast error handling principles documented in `CONTRIBUTING.md` and `docs/specification.md`. Per `CONTRIBUTING.md`: > **CRITICAL: Do not suppress errors.** Let exceptions propagate to the top level. > Only catch when you can meaningfully handle (retry logic, resource cleanup, adding context). > **Fail-Fast:** Type safety, early validation, assertions, no silent failures, explicit over implicit. When a Python file under `src/cleveragents/application/services/` contains a syntax error, the compliance checker silently skips it with no diagnostic output. This means: - Malformed Python files are invisible to the ADR compliance check - Developers receive a false "all clear" result even when files cannot be parsed - The root cause of a syntax error is hidden, making debugging significantly harder ## Current Behavior **File**: `scripts/check-adr-compliance.py` **Function**: `check_adr003_dependency_injection()` **Lines**: 68–69 ```python for py_file in services_dir.rglob("*.py"): if py_file.name.startswith("__"): continue try: tree = ast.parse(py_file.read_text()) except SyntaxError: continue # ← Silent suppression: SyntaxError is swallowed, file is skipped ``` **Reproduction steps:** 1. Create a Python file with a syntax error under `src/cleveragents/application/services/` 2. Run `nox -s adr_compliance` 3. Observe: the compliance check reports zero violations and exits `0` — the malformed file is silently ignored **Expected output (fail-fast):** The script should either raise the `SyntaxError` (letting it propagate to the caller) or emit a diagnostic message identifying the offending file and exit non-zero. **Actual output:** No output, no error, exit code `0`. The malformed file is invisible. ## Expected Behavior According to the project specification and `CONTRIBUTING.md`, the script should follow one of these approaches: 1. **Propagate (preferred):** Remove the `except` clause entirely and let `SyntaxError` propagate to the top-level handler, providing a clear traceback with the file path. 2. **Log and fail:** Catch `SyntaxError`, emit a diagnostic message including the file path and error details, append a violation entry, and continue scanning remaining files — but exit non-zero at the end. 3. **Strict/lenient flag:** Add a `--strict` CLI flag; in strict mode (default) propagate the error; in lenient mode log and continue. Under no circumstances should the error be silently discarded. ## Acceptance Criteria - [ ] `check_adr003_dependency_injection()` no longer contains a bare `except SyntaxError: continue` that discards the error silently - [ ] A Python file with a syntax error under `src/cleveragents/application/services/` causes `nox -s adr_compliance` to exit non-zero with a meaningful diagnostic message - [ ] The fix is consistent with the fail-fast principle: no silent failures - [ ] All existing ADR compliance checks continue to pass on valid source files - [ ] All `nox` sessions pass with coverage ≥ 97% ## Supporting Information - **Related issue**: #4057 — ADR compliance script references non-existent ADR-002 and ADR-007 (same script, separate defect) - **Related issue**: #7282 — Silent error suppression in ADR inventory collection (same pattern, different file: `hooks/adr_hooks.py`) - **Specification reference**: `CONTRIBUTING.md` § "Error and Exception Handling" — "CRITICAL: Do not suppress errors. Let exceptions propagate to the top level." - **TDD workflow**: Per `CONTRIBUTING.md` Bug Fix Workflow, a `TDD:` issue (`Type/Testing`) must be created and merged **before** the fix branch is opened. The bug fix branch depends on the TDD issue. After this issue is verified, a TDD issue will be created tagged `@tdd_issue`, `@tdd_issue_<this-issue-number>`, and `@tdd_expected_fail` to prove the bug exists before fixing it. ## Subtasks - [ ] Create TDD issue (`Type/Testing`, title: `TDD: BUG-HUNT: [error-handling] Silent SyntaxError suppression in check-adr-compliance.py`) and link it as a dependency of this issue - [ ] Remove the bare `except SyntaxError: continue` clause from `check_adr003_dependency_injection()` - [ ] Implement fail-fast error handling: propagate `SyntaxError` or log diagnostic with file path and exit non-zero - [ ] Consider adding `--strict` / `--lenient` CLI flag for parsing mode control - [ ] Tests (Behave): Add scenario proving a syntax-errored file causes non-zero exit (tagged `@tdd_issue`, `@tdd_issue_<N>`, remove `@tdd_expected_fail` on fix) - [ ] Tests (Robot): Add integration test scenario for ADR compliance script error handling - [ ] 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 matches the Commit Message in Metadata exactly: `fix(scripts): remove silent SyntaxError suppression in ADR compliance checker` - The commit is pushed to the remote on the branch matching the Branch in Metadata: `bugfix/m5-check-adr-compliance-syntax-error-suppression` - The commit is submitted as a pull request to `master`, reviewed, and merged. - All `nox` sessions pass (lint, typecheck, security, unit_tests, integration_tests, coverage_report). - Coverage ≥ 97%. - The `@tdd_expected_fail` tag has been removed from all `@tdd_issue_<N>` scenarios (CI gate enforced). --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: Bug Hunter | Agent: new-issue-creator

HAL9000 added this to the v3.5.0 milestone

2026-04-10 15:45:42 +00:00

HAL9000 added the

labels

2026-04-10 15:52:23 +00:00

HAL9000 added a new dependency

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

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

HAL9000 added

and removed

labels

2026-04-14 06:23:53 +00:00

HAL9000 commented

2026-04-14 06:23:53 +00:00

Author

Owner

✅ Verified — Critical bug: silent SyntaxError suppression in ADR compliance check. MoSCoW: Must-have. Priority: Critical.

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

✅ **Verified** — Critical bug: silent SyntaxError suppression in ADR compliance check. MoSCoW: Must-have. Priority: Critical. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:29:31 +00:00

Author

Owner

✅ Verified — Critical bug: silent SyntaxError suppression in ADR compliance check. MoSCoW: Must-have. Priority: Critical.

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