Merged
Conversation
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughThis PR adds automated Markdown link validation (script + poe task + pyproject entry) and integrates it into CI, creates new reference docs (developer-workflow, workflows-reference, docs-inventory), updates contributor/dev guidance to include the check, and removes several obsolete planning documents. Changes
Sequence Diagram(s)sequenceDiagram
actor CI as GitHub Actions CI
participant Workflow as ci.yml
participant Poe as poe task runner
participant LinkScript as check_markdown_links.py
participant Files as README & docs/*.md
participant Reporter as Link Report
CI->>Workflow: start lint job
Workflow->>Poe: run `poetry run poe docs-links`
Poe->>LinkScript: invoke script
LinkScript->>Files: scan files for Markdown links
Files-->>LinkScript: return file contents
LinkScript->>LinkScript: extract links (regex), ignore external/anchors
LinkScript->>LinkScript: resolve relative targets → file paths
LinkScript->>LinkScript: validate existence
LinkScript->>Reporter: collect broken links
alt broken links found
Reporter-->>Workflow: non-zero exit (list broken links)
else no broken links
Reporter-->>Workflow: zero exit (OK)
end
Workflow-->>CI: report status
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 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: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CONTRIBUTING.md (1)
69-69:⚠️ Potential issue | 🟡 MinorRemove stale reference to deleted plan file
The file
docs/plans/2026-02-13-docs-refresh-execution-plan.mdreferenced at line 69 in CONTRIBUTING.md no longer exists in the repository. Since it's in backticks rather than a Markdown link, thedocs-linkschecker won't catch this. Update line 69 to remove this stale reference.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CONTRIBUTING.md` at line 69, Remove the stale backticked reference `docs/plans/2026-02-13-docs-refresh-execution-plan.md` from CONTRIBUTING.md (the item on line 69) by deleting that filename from the list or replacing it with an accurate/current plan filename or a generic placeholder; ensure the surrounding punctuation and list formatting remain correct so the markdown renders cleanly.
🧹 Nitpick comments (4)
scripts/check_markdown_links.py (1)
21-24: Consider expanding scan scope to all root-level Markdown files
_candidate_markdown_filesonly scansREADME.md+docs/**/*.md.CONTRIBUTING.md,RELEASE.md, and any future root-level.mdfiles are silently excluded, so local links added there won't be caught by CI.♻️ Proposed refactor — scan all root *.md files
def _candidate_markdown_files(repo_root: Path) -> list[Path]: - files = [repo_root / "README.md"] - files.extend((repo_root / "docs").rglob("*.md")) + files = list(repo_root.glob("*.md")) + files.extend((repo_root / "docs").rglob("*.md")) return [file for file in files if file.exists()]This also updates the module docstring:
-"""Validate local markdown links in README and docs.""" +"""Validate local markdown links in repository root and docs."""🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/check_markdown_links.py` around lines 21 - 24, The function _candidate_markdown_files currently only includes README.md and docs/**/*.md; update it to also glob all root-level .md files (e.g., CONTRIBUTING.md, RELEASE.md, and any future *.md at repo_root) so they are included in CI checks — modify the logic in _candidate_markdown_files to extend files with a repo_root.glob("*.md") result (while keeping the existing docs.rglob and README inclusion) and return only existing files as before; ensure you reference and update any module docstring to describe the expanded scan scope.CONTRIBUTING.md (1)
27-27: "Markdown" should be capitalised as a proper noun
markdown→Markdownin thepoe docs-linksdescription row, consistent with the rest of the table and the standard spelling.✏️ Proposed fix
-| `poe docs-links` | Validate local markdown links in `README.md` and `docs/` | +| `poe docs-links` | Validate local Markdown links in `README.md` and `docs/` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CONTRIBUTING.md` at line 27, Update the table row for the `poe docs-links` command so the word "markdown" is capitalized as "Markdown": locate the row containing "`poe docs-links` | Validate local markdown links in `README.md` and `docs/`" and change "markdown" → "Markdown" to match the rest of the doc's capitalization and standard spelling.docs/reference/developer-workflow.md (1)
22-22: Nit: capitalise "Markdown" (proper noun).✏️ Proposed fix
-| `poetry run poe docs-links` | Prevent broken local markdown links in `README.md` and `docs/` | +| `poetry run poe docs-links` | Prevent broken local Markdown links in `README.md` and `docs/` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reference/developer-workflow.md` at line 22, The table entry text currently uses "markdown" in lowercase; update the string in the table row that contains "`poetry run poe docs-links` | Prevent broken local markdown links in `README.md` and `docs/`" to capitalize "Markdown" so it reads "Prevent broken local Markdown links in `README.md` and `docs/`" (modify the table cell where that phrase appears, e.g., the row containing `poetry run poe docs-links`).docs/design/documentation-architecture.md (1)
117-119: Nit: line 119 is redundant after the new line 117.
poe docs-linksvalidates exactly what "Local markdown links resolve." already states — keeping both adds noise to the checklist.✏️ Proposed fix
- `poe docs-links` passes. - `poe test-e2e` passes when CLI behavior changes. -- Local markdown links resolve. - New docs files are linked from `docs/README.md`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/design/documentation-architecture.md` around lines 117 - 119, The checklist contains a redundant item: remove the duplicate bullet "`poe docs-links` passes." (or the line "Local markdown links resolve.") so only one of these equivalent entries remains; edit the checklist in documentation-architecture.md to delete the redundant line and leave the clearer/most specific entry (referencing the two checklist lines containing "poe docs-links" and "Local markdown links resolve.").
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/design/documentation-architecture.md`:
- Around line 36-42: The architecture diagram's Reference section omits the new
docs-inventory entry: add a new node R8[docs-inventory.md] and connect it from
Reference (matching the existing pattern Reference --> R1..R7) so the diagram
includes docs/reference/docs-inventory.md; update the same diagram block that
defines Reference --> R1..R7 to include Reference --> R8[docs-inventory.md] so
the diagram remains the authoritative map of docs.
In `@docs/reference/workflows-reference.md`:
- Line 31: The docs entry for the "docs-links" workflow (the `docs-links` poe
task / command `poetry run poe docs-links`) is missing its required behavioral
contract; update the docs/reference/workflows-reference.md entry for
`docs-links` to state the user-visible guarantees: exact exit codes (which
code(s) indicate success vs link failures), discovery semantics (which
files/globs under docs/**/*.md are scanned and how symlinks/ignored files are
treated), and dry-run semantics (whether a dry-run option exists and what it
reports). Refer to the `docs-links` task name when editing so the contract is
co-located with the command listing.
In `@scripts/check_markdown_links.py`:
- Line 11: The LINK_PATTERN currently uses ([^)]+) which captures link titles
too (e.g., ./file.md "title"); update LINK_PATTERN to capture only the URL
portion by using a pattern like ([^\s)]+) so it stops at the first whitespace or
closing paren and does not include title attributes; change the compiled regex
constant LINK_PATTERN accordingly and verify the _resolve_target call continues
to receive the correct URL string (no title) so broken-link checks stop
producing false positives.
---
Outside diff comments:
In `@CONTRIBUTING.md`:
- Line 69: Remove the stale backticked reference
`docs/plans/2026-02-13-docs-refresh-execution-plan.md` from CONTRIBUTING.md (the
item on line 69) by deleting that filename from the list or replacing it with an
accurate/current plan filename or a generic placeholder; ensure the surrounding
punctuation and list formatting remain correct so the markdown renders cleanly.
---
Nitpick comments:
In `@CONTRIBUTING.md`:
- Line 27: Update the table row for the `poe docs-links` command so the word
"markdown" is capitalized as "Markdown": locate the row containing "`poe
docs-links` | Validate local markdown links in `README.md` and `docs/`" and
change "markdown" → "Markdown" to match the rest of the doc's capitalization and
standard spelling.
In `@docs/design/documentation-architecture.md`:
- Around line 117-119: The checklist contains a redundant item: remove the
duplicate bullet "`poe docs-links` passes." (or the line "Local markdown links
resolve.") so only one of these equivalent entries remains; edit the checklist
in documentation-architecture.md to delete the redundant line and leave the
clearer/most specific entry (referencing the two checklist lines containing "poe
docs-links" and "Local markdown links resolve.").
In `@docs/reference/developer-workflow.md`:
- Line 22: The table entry text currently uses "markdown" in lowercase; update
the string in the table row that contains "`poetry run poe docs-links` | Prevent
broken local markdown links in `README.md` and `docs/`" to capitalize "Markdown"
so it reads "Prevent broken local Markdown links in `README.md` and `docs/`"
(modify the table cell where that phrase appears, e.g., the row containing
`poetry run poe docs-links`).
In `@scripts/check_markdown_links.py`:
- Around line 21-24: The function _candidate_markdown_files currently only
includes README.md and docs/**/*.md; update it to also glob all root-level .md
files (e.g., CONTRIBUTING.md, RELEASE.md, and any future *.md at repo_root) so
they are included in CI checks — modify the logic in _candidate_markdown_files
to extend files with a repo_root.glob("*.md") result (while keeping the existing
docs.rglob and README inclusion) and return only existing files as before;
ensure you reference and update any module docstring to describe the expanded
scan scope.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/design/documentation-architecture.md (1)
48-57: Code-to-Docs Ownership Map omitsworkflows-reference.mdfor theCodeWorkflowsnodeLine 55 maps
CodeWorkflows[.github/workflows/]only toReleaseGuide[RELEASE.md], but line 66 (new update rule) establishes thatdocs/reference/workflows-reference.mdmust also be updated when CI/release workflow behavior changes. The ownership map is the canonical code→doc traceability diagram and should be consistent with the update rules.✏️ Proposed addition
CodeWorkflows[.github/workflows/] --> ReleaseGuide[RELEASE.md] + CodeWorkflows --> WorkflowsRef[docs/reference/workflows-reference.md]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/design/documentation-architecture.md` around lines 48 - 57, The Code-to-Docs ownership map is missing the workflows-reference mapping for the CodeWorkflows node; update the mermaid diagram by adding a link from CodeWorkflows[.github/workflows/] to WorkflowsRef[docs/reference/workflows-reference.md] (in the same style as the existing CodeWorkflows --> ReleaseGuide relation) so the diagram reflects that changes to CI/release workflows must also update workflows-reference.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 39-41: The fenced code block containing "Contracts → Core → SDK →
CLI" triggers markdownlint MD040 because it lacks a language specifier; update
that fenced block in CLAUDE.md (the triple-backtick block that currently wraps
"Contracts → Core → SDK → CLI") to include a language tag such as ```text so the
block becomes ```text ... ``` to satisfy the linter.
---
Nitpick comments:
In `@docs/design/documentation-architecture.md`:
- Around line 48-57: The Code-to-Docs ownership map is missing the
workflows-reference mapping for the CodeWorkflows node; update the mermaid
diagram by adding a link from CodeWorkflows[.github/workflows/] to
WorkflowsRef[docs/reference/workflows-reference.md] (in the same style as the
existing CodeWorkflows --> ReleaseGuide relation) so the diagram reflects that
changes to CI/release workflows must also update workflows-reference.md.
Comment on lines
+39
to
+41
| ``` | ||
| Contracts → Core → SDK → CLI | ||
| ``` |
There was a problem hiding this comment.
Add a language specifier to the architecture fenced code block (MD040)
The bare fenced block is flagged by markdownlint-cli2 (MD040) and will fail any future markdownlint CI step.
✏️ Proposed fix
-```
+```text
Contracts → Core → SDK → CLI</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 39-39: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @CLAUDE.md around lines 39 - 41, The fenced code block containing "Contracts
→ Core → SDK → CLI" triggers markdownlint MD040 because it lacks a language
specifier; update that fenced block in CLAUDE.md (the triple-backtick block that
currently wraps "Contracts → Core → SDK → CLI") to include a language tag such
as text so the block becomes text ... ``` to satisfy the linter.
</details>
<!-- fingerprinting:phantom:triton:churro -->
<!-- This is an auto-generated comment by CodeRabbit -->
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Expand docs-links scan to all root-level *.md files (not just README.md) - Fix LINK_PATTERN to stop at whitespace, avoiding false positives from titled links like [text](path "title") - Capitalize "Markdown" (proper noun) in CONTRIBUTING.md and developer-workflow.md - Replace stale plan file reference in CONTRIBUTING.md with docs-inventory.md - Add docs-inventory.md node to documentation-architecture IA diagram - Remove redundant "Local markdown links resolve." checklist item - Add behavioral contract for docs-links in workflows-reference.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
aryeko
force-pushed
the
chore/repo-audit-doc-refresh
branch
from
fd75221 to
1631729
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
scripts/check_markdown_links.py+poe docs-linkstask)developer-workflow.md,workflows-reference.md,docs-inventory.mddocs/README.mddiscoverability and navigationCONTRIBUTING.md,README.md,RELEASE.mdto reference new docs and link checkerdocs/plans/Test plan
poe docs-linkspasses — no broken markdown linkspoe lintpasses (ruff, mypy)pytestpasses — 509 tests, 98% coverageactionlintpasses on updated CI workflow🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores