BUG-HUNT: [type-safety] Unsafe int() conversion in `_build_related_adrs_section` #2404

New issue

Open

opened 2026-04-03 17:34:43 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 17:34:43 +00:00

Owner

Metadata

Branch: bugfix/m7-adr-related-unsafe-int-conversion
Commit Message: fix(hooks): guard int() conversion in _build_related_adrs_section against invalid ADR numbers
Milestone: v3.6.0 (Post-MVP Release)
Parent Epic: #400

Background

The function _build_related_adrs_section in hooks/adr_hooks.py processes the related_adrs list from ADR front-matter. At line 314, it calls int(num) on the number field of each related ADR entry without any guard. If a front-matter author provides a non-integer value (e.g., "abc" or null), Python raises a ValueError or TypeError, which propagates up and crashes the entire MkDocs build.

Location: hooks/adr_hooks.py, function _build_related_adrs_section, line 314.

Violates: CONTRIBUTING.md error-handling rule — "Only catch exceptions when you can meaningfully handle them." The meaningful handling here is to log a warning and skip the malformed entry rather than crashing the build.

Current Behavior

A related_adrs entry with a non-integer number field:

related_adrs:
  - number: "abc"
    title: "Some other ADR"
    relationship: "related to"

causes the following crash at build time:

ValueError: invalid literal for int() with base 10: 'abc'

This terminates the MkDocs build entirely.

Expected Behavior

The code should handle non-integer number values gracefully by catching ValueError and TypeError, logging a warning, and skipping the malformed entry so the rest of the build continues unaffected.

Suggested Fix

try:
    adr_num = int(num)
    link_path = _resolve_adr_link(adr_num, files)
    if link_path:
        adr_col = f"[ADR-{adr_num:03d}]({link_path})"
    else:
        adr_col = f"ADR-{adr_num:03d}"
except (ValueError, TypeError):
    log.warning("Invalid ADR number in related_adrs: %s", num)
    continue  # skip this malformed entry

Subtasks

Add a try...except (ValueError, TypeError) guard around the int(num) call at line 314 of hooks/adr_hooks.py
Log a warning-level message identifying the invalid value when the exception is caught
Skip the malformed entry (via continue) so the rest of the related_adrs list is still processed
Tests (Behave): Add a TDD issue-capture scenario tagged @tdd_expected_fail demonstrating the crash, then a passing scenario verifying the graceful skip-and-warn behaviour
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: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `bugfix/m7-adr-related-unsafe-int-conversion` - **Commit Message**: `fix(hooks): guard int() conversion in _build_related_adrs_section against invalid ADR numbers` - **Milestone**: v3.6.0 (Post-MVP Release) - **Parent Epic**: #400 ## Background The function `_build_related_adrs_section` in `hooks/adr_hooks.py` processes the `related_adrs` list from ADR front-matter. At line 314, it calls `int(num)` on the `number` field of each related ADR entry without any guard. If a front-matter author provides a non-integer value (e.g., `"abc"` or `null`), Python raises a `ValueError` or `TypeError`, which propagates up and crashes the entire MkDocs build. **Location**: `hooks/adr_hooks.py`, function `_build_related_adrs_section`, line 314. **Violates**: CONTRIBUTING.md error-handling rule — *"Only catch exceptions when you can meaningfully handle them."* The meaningful handling here is to log a warning and skip the malformed entry rather than crashing the build. ## Current Behavior A `related_adrs` entry with a non-integer `number` field: ```yaml related_adrs: - number: "abc" title: "Some other ADR" relationship: "related to" ``` causes the following crash at build time: ``` ValueError: invalid literal for int() with base 10: 'abc' ``` This terminates the MkDocs build entirely. ## Expected Behavior The code should handle non-integer `number` values gracefully by catching `ValueError` and `TypeError`, logging a warning, and skipping the malformed entry so the rest of the build continues unaffected. ## Suggested Fix ```python try: adr_num = int(num) link_path = _resolve_adr_link(adr_num, files) if link_path: adr_col = f"[ADR-{adr_num:03d}]({link_path})" else: adr_col = f"ADR-{adr_num:03d}" except (ValueError, TypeError): log.warning("Invalid ADR number in related_adrs: %s", num) continue # skip this malformed entry ``` ## Subtasks - [ ] Add a `try...except (ValueError, TypeError)` guard around the `int(num)` call at line 314 of `hooks/adr_hooks.py` - [ ] Log a `warning`-level message identifying the invalid value when the exception is caught - [ ] Skip the malformed entry (via `continue`) so the rest of the `related_adrs` list is still processed - [ ] Tests (Behave): Add a TDD issue-capture scenario tagged `@tdd_expected_fail` demonstrating the crash, then a passing scenario verifying the graceful skip-and-warn behaviour - [ ] 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: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-03 17:34:49 +00:00

freemo added a new dependency

2026-04-03 17:35:23 +00:00

#400 Epic: Post-MVP Security

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — Unsafe int() conversion in _build_related_adrs_section could raise ValueError on malformed input. Defensive coding improvement.
Milestone: v3.6.0
MoSCoW: Could Have — Only triggers with malformed ADR data. Low probability of occurrence in normal operation.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — Unsafe `int()` conversion in `_build_related_adrs_section` could raise `ValueError` on malformed input. Defensive coding improvement. - **Milestone**: v3.6.0 - **MoSCoW**: Could Have — Only triggers with malformed ADR data. Low probability of occurrence in normal operation. --- **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:09:33 +00:00