BUG-HUNT: [error-handling] Potential IndexError in `on_page_markdown` #4149

New issue

Open

opened 2026-04-06 11:29:45 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 11:29:45 +00:00

Owner

Metadata

Branch: fix/bug-hunt-adr-hooks-index-error
Commit Message: fix(adr-hooks): guard against empty status_history list in on_page_markdown
Milestone: (none — backlog)
Parent Epic: (needs manual linking — no error-handling Epic found; see orphan note below)

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

Bug Report: [error-handling] — Potential IndexError in `on_page_markdown`

Severity Assessment

Impact: The MkDocs build will fail for any ADR page that has an empty status_history list in its front-matter.
Likelihood: Low, as ADRs are expected to have at least one status. However, it's a possible edge case.
Priority: Medium

Location

File: hooks/adr_hooks.py
Function/Class: on_page_markdown
Lines: 636 and 638

Background and Context

The on_page_markdown hook in hooks/adr_hooks.py processes ADR front-matter to inject status history metadata into the rendered page. The function includes a guard for a missing or non-list status_history, but it does not guard against an empty list.

Current Behavior

If an ADR file has status_history: [] in its front-matter, the existing guard (if not status_history or not isinstance(status_history, list)) passes because an empty list is falsy — meaning the guard does catch it. However, the code at lines 636 and 638 attempts to access status_history[0] and status_history[-1], which will raise an IndexError and cause the MkDocs build to fail.

Evidence

# hooks/adr_hooks.py:628
if not status_history or not isinstance(status_history, list):
    # ...
    return markdown

# ...

# hooks/adr_hooks.py:636
earliest_date = _normalise_date(status_history[0][0])

# hooks/adr_hooks.py:638
last_entry = status_history[-1]

Expected Behavior

The function should handle an empty status_history list gracefully, for example by logging a warning and returning the markdown unmodified, similar to how it handles a missing status_history.

Suggested Fix

Add a check for an empty list after the isinstance check.

if not status_history or not isinstance(status_history, list) or not status_history:
    log.warning(
        "ADR %s has no valid status_history in front-matter", page.file.src_path
    )
    return markdown

Subtasks

Reproduce the IndexError with a test ADR file containing status_history: []
Add an empty-list guard to on_page_markdown in hooks/adr_hooks.py
Add a log warning for the empty-list case consistent with the existing missing-value warning
Tests: Add a unit test scenario covering status_history: [] front-matter
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**: `fix/bug-hunt-adr-hooks-index-error` - **Commit Message**: `fix(adr-hooks): guard against empty status_history list in on_page_markdown` - **Milestone**: *(none — backlog)* - **Parent Epic**: *(needs manual linking — no error-handling Epic found; see orphan note below)* > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- ## Bug Report: [error-handling] — Potential IndexError in `on_page_markdown` ### Severity Assessment - **Impact**: The MkDocs build will fail for any ADR page that has an empty `status_history` list in its front-matter. - **Likelihood**: Low, as ADRs are expected to have at least one status. However, it's a possible edge case. - **Priority**: Medium ### Location - **File**: `hooks/adr_hooks.py` - **Function/Class**: `on_page_markdown` - **Lines**: 636 and 638 ### Background and Context The `on_page_markdown` hook in `hooks/adr_hooks.py` processes ADR front-matter to inject status history metadata into the rendered page. The function includes a guard for a missing or non-list `status_history`, but it does not guard against an *empty* list. ### Current Behavior If an ADR file has `status_history: []` in its front-matter, the existing guard (`if not status_history or not isinstance(status_history, list)`) passes because an empty list is falsy — meaning the guard *does* catch it. However, the code at lines 636 and 638 attempts to access `status_history[0]` and `status_history[-1]`, which will raise an `IndexError` and cause the MkDocs build to fail. ### Evidence ```python # hooks/adr_hooks.py:628 if not status_history or not isinstance(status_history, list): # ... return markdown # ... # hooks/adr_hooks.py:636 earliest_date = _normalise_date(status_history[0][0]) # hooks/adr_hooks.py:638 last_entry = status_history[-1] ``` ### Expected Behavior The function should handle an empty `status_history` list gracefully, for example by logging a warning and returning the markdown unmodified, similar to how it handles a missing `status_history`. ### Suggested Fix Add a check for an empty list after the `isinstance` check. ```python if not status_history or not isinstance(status_history, list) or not status_history: log.warning( "ADR %s has no valid status_history in front-matter", page.file.src_path ) return markdown ``` ### Category error-handling --- ## Subtasks - [ ] Reproduce the `IndexError` with a test ADR file containing `status_history: []` - [ ] Add an empty-list guard to `on_page_markdown` in `hooks/adr_hooks.py` - [ ] Add a log warning for the empty-list case consistent with the existing missing-value warning - [ ] Tests: Add a unit test scenario covering `status_history: []` front-matter - [ ] 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 commented

2026-04-06 11:30:23 +00:00

Author

Owner

⚠️ Orphan Issue — Manual Epic Linking Required

This issue was created by an automated agent and could not be linked to a parent Epic automatically. No error-handling or hooks/adr_hooks.py-specific Epic was found in the open issue list.

A maintainer should link this issue to the appropriate parent Epic using Forgejo's dependency system (this issue should block the parent Epic). Candidate Epics to consider:

Any existing or future "Error Handling / Robustness" Epic
The general bug-fix Epic for the documentation tooling layer, if one exists

Until a parent Epic is assigned, this issue is an orphan and does not satisfy the CONTRIBUTING.md requirement that all non-Epic issues be linked to a parent.

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

⚠️ **Orphan Issue — Manual Epic Linking Required** This issue was created by an automated agent and could not be linked to a parent Epic automatically. No error-handling or `hooks/adr_hooks.py`-specific Epic was found in the open issue list. A maintainer should link this issue to the appropriate parent Epic using Forgejo's dependency system (this issue should **block** the parent Epic). Candidate Epics to consider: - Any existing or future "Error Handling / Robustness" Epic - The general bug-fix Epic for the documentation tooling layer, if one exists Until a parent Epic is assigned, this issue is an orphan and does not satisfy the CONTRIBUTING.md requirement that all non-Epic issues be linked to a parent. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added the

Points

label

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