fix(docs): repair the broken ADR index table and guard it - #191
Conversation
A blank line after the 0038 row terminated the Markdown table, so ADRs 0039-0050 rendered on the published site as one run-on paragraph of literal pipe characters. Every existing gate was blind to it: nothing became an unresolvable link, so `mkdocs build --strict` stayed green, and `test_every_adr_is_indexed` passed because it greps for the link target, which is present whether the row is a table cell or prose. Remove the blank line, and rewrite each Title cell to that record's own H1 — several cells had grown into full Decision dumps (ADR-0047 ran to ~1700 characters), which is not an index. Guard both structurally, with no Markdown renderer: every ADR row must be preceded by a table line, and Title cells are bounded. python-markdown is not in the base conda-lock, so a render-based assertion could not run on the 3-OS test matrix. Verified: the built page now has two tables of 9 and 43 rows with zero literal pipes in any paragraph; reintroducing the blank line fails the new test on ADR 0039. Refs #156
|
@coderabbitai review |
✅ Action performedReview finished.
|
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 53 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe ADR index descriptions are revised, and tests now enforce a minimum of 50 numbered ADRs, valid table-row rendering, and concise title cells. ChangesADR index maintenance
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
Possibly related PRs
Suggested labels: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tests/test_adr_index.py`:
- Around line 100-119: Update test_index_titles_are_concise to resolve each
indexed ADR from its row identifier, read that record’s H1, and assert the
extracted Title cell exactly matches the H1. Keep the existing _MAX_TITLE_CHARS
length check as a separate assertion so both identity and concision are
validated.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 127ea283-8360-4466-86fa-2dee8ba6b044
📒 Files selected for processing (2)
docs/adr/README.mdtests/test_adr_index.py
The title guard checked only length, so a concise but WRONG title passed while still misrouting the reader — which is most of what an index is for. Split it in two: one test asserts each Title cell equals that record's own H1, the other keeps the length bound so an ADR whose heading grew into a Decision paragraph still fails. Extract the row-title parse into a helper that joins the middle cells rather than indexing [2], so a Title containing a pipe cannot shift the parse; Status and PRD anchor are always the last two. The H1 reader takes the first line starting "# " rather than line 1, because several records open with an HTML comment, and accepts em dash, en dash or hyphen as the number separator. Verified: rewriting the 0001 cell to a short but incorrect title fails the new identity test and passes the length test, which is precisely the gap. Addresses the review on #191.
|
@coderabbitai review |
✅ Action performedReview finished.
|
1 participant
Summary
ADRs 0039–0050 render on the published site as a single run-on paragraph of literal
|characters, in the middle of the ADR index. A blank line after the 0038 row terminates the Markdown table, and everything after it becomes prose.Every existing gate was blind to this. Nothing becomes an unresolvable link, so
mkdocs build --strictstays green; andtest_every_adr_is_indexedpasses because it greps for the](NNNN-title.md)link target, which is present whether the row is a table cell or a paragraph.Three changes:
|---|delimiter), and Title cells are bounded at 200 characters. A blank line between the two index sections stays legal, because the row after it is preceded by that section's own delimiter.python-markdownis not in the baseconda-lock.yml(onlymarkdown-it-py, viarich), so a render-based assertion could not run on the 3-OStestmatrix. The check is stdlib-only.Linked tracking
Type of change
feat— new capabilityfix— bug fixdocs/chore/ci/build/refactor/test/perf!/BREAKING CHANGE:— a deliberate schema-version bumpSelf-review checklist (PRD §12.4)
tests/test_adr_index.py, plus the stale>= 49record floor bumped to>= 50._MAX_TITLE_CHARSis a test-local formatting bound on an index table, not an analysis tunable.Testing
pytest tests/test_adr_index.py— 7 passed.Negative control, as the issue requires: reintroducing the blank line before the 0039 row fails the new guard with
[(67, '0039')], and removing it passes again.Rendered-output verification against
mkdocs build --strict(green, 61 pages, zero warnings):<table>elements<tr>per table|in any<p><td>50 records now render as table rows across the two sections (8 + 42), matching the 50 numbered ADRs on disk. Longest remaining Title cell is 161 characters (ADR-0019).
Summary by CodeRabbit
Documentation
Tests