feat(validation): guard README dependency snippets#140
Merged
Conversation
- Add a generic docs-version sync check that compares Markdown dependency snippets against the Cargo package name and version - Run the docs-version check from the repository Semgrep policy lane - Refresh README determinant examples with explicit fallible handling and hidden doctest mirrors - Update CI uv pins to 0.11.19
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #140 +/- ##
=======================================
Coverage 99.47% 99.47%
=======================================
Files 5 5
Lines 2838 2838
=======================================
Hits 2823 2823
Misses 15 15
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Contributor
📝 WalkthroughWalkthroughPR bumps crate version to 0.4.2, adds automated validation for documentation version consistency via a new Python CLI tool, integrates it into CI workflows and build recipes, and updates all user-facing examples and documentation to reflect the new version with improved error-handling patterns. ChangesDocumentation v0.4.2 Update with Version-Sync Validation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
scripts/check_docs_version_sync.py (1)
70-71: ⚡ Quick winSkip directories should be pruned during traversal, not filtered after
rglob.Current traversal still descends into skipped trees (e.g.,
target,.venv) and only drops matches afterward. Pruning during walk will reduce CI time and I/O.🤖 Prompt for 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. In `@scripts/check_docs_version_sync.py` around lines 70 - 71, The current _iter_markdown_files uses root.rglob and filters matches post-traversal which still descends into skipped directories; change it to prune during traversal by iterating the tree (e.g., use os.walk or a recursive Path.iterdir approach) and remove/skip entries whose relative path parts intersect SKIP_DIRS so they are not descended into; return the same sorted list[Path] of .md files but ensure directories matching SKIP_DIRS are removed from the walk (modify the dirs list in-place when using os.walk) so traversal avoids visiting target/.venv etc.scripts/tests/test_check_docs_version_sync.py (1)
31-57: ⚡ Quick winAdd a regression test where inline-table
versionis not the first key.This scenario is valid TOML and currently untested, but it’s essential for the docs-version guard’s correctness.
🤖 Prompt for 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. In `@scripts/tests/test_check_docs_version_sync.py` around lines 31 - 57, Add a regression test to cover inline-table dependency entries where the version key is not the first key (valid TOML) by extending or creating a test in test_find_version_mismatches_reports_stale_dependency_snippets (or a new test function) that writes a Cargo.toml with package other-crate version "1.2.3" and a docs/install.md containing an inline-table like 'other-crate = { features = ["exact"], version = "1.2.2" }', then call check_docs_version_sync.find_version_mismatches(tmp_path) and assert a single mismatch with snippet.path == docs/install.md, snippet.line == 1, snippet.version == "1.2.2", package.name == "other-crate", and package.version == "1.2.3" so the parser correctly finds version when it is not the first key.
🤖 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 `@scripts/check_docs_version_sync.py`:
- Line 76: The current regex returned for matching dependency versions uses a
table branch that only matches when version is the first key; update the pattern
returned by the function that builds/returns the compiled regex (the line with
return re.compile(rf'(?<![\w.-]){escaped_name}...')) so the table alternative
allows arbitrary keys before or after version (e.g. match
\{[^}]*version\s*=\s*"(?P<table>[^"]+)"[^}]*\}) while still anchoring on the
dependency name via escaped_name and preserving the plain-string branch; replace
the table-part of the alternation accordingly so inline tables like `{ features
= ["exact"], version = "0.4.2" }` are captured.
In `@scripts/tests/test_check_docs_version_sync.py`:
- Line 6: Annotate the tmp_path parameter as Path in the test signatures to
satisfy typing rules: update
test_find_version_mismatches_accepts_matching_dependency_snippets(tmp_path) ->
None to tmp_path: Path and do the same for the other test referenced at line 31;
also add the necessary import (from pathlib import Path) at the top of the test
file so the Path type is available.
---
Nitpick comments:
In `@scripts/check_docs_version_sync.py`:
- Around line 70-71: The current _iter_markdown_files uses root.rglob and
filters matches post-traversal which still descends into skipped directories;
change it to prune during traversal by iterating the tree (e.g., use os.walk or
a recursive Path.iterdir approach) and remove/skip entries whose relative path
parts intersect SKIP_DIRS so they are not descended into; return the same sorted
list[Path] of .md files but ensure directories matching SKIP_DIRS are removed
from the walk (modify the dirs list in-place when using os.walk) so traversal
avoids visiting target/.venv etc.
In `@scripts/tests/test_check_docs_version_sync.py`:
- Around line 31-57: Add a regression test to cover inline-table dependency
entries where the version key is not the first key (valid TOML) by extending or
creating a test in
test_find_version_mismatches_reports_stale_dependency_snippets (or a new test
function) that writes a Cargo.toml with package other-crate version "1.2.3" and
a docs/install.md containing an inline-table like 'other-crate = { features =
["exact"], version = "1.2.2" }', then call
check_docs_version_sync.find_version_mismatches(tmp_path) and assert a single
mismatch with snippet.path == docs/install.md, snippet.line == 1,
snippet.version == "1.2.2", package.name == "other-crate", and package.version
== "1.2.3" so the parser correctly finds version when it is not the first key.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 076989eb-9cc9-453c-a85c-267976c7e9d0
📒 Files selected for processing (11)
.github/workflows/ci.yml.github/workflows/semgrep-sarif.ymlAGENTS.mdREADME.mddocs/BENCHMARKING.mdexamples/const_det_4x4.rsjustfilepyproject.tomlscripts/check_docs_version_sync.pyscripts/tests/test_check_docs_version_sync.pysrc/lib.rs
|
|
||
| def _dependency_regex(package_name: str) -> re.Pattern[str]: | ||
| escaped_name = re.escape(package_name) | ||
| return re.compile(rf'(?<![\w.-]){escaped_name}\s*=\s*(?:"(?P<plain>[^"]+)"|\{{\s*version\s*=\s*"(?P<table>[^"]+)")') |
Contributor
There was a problem hiding this comment.
Inline-table parsing misses valid version fields unless they are first.
The table-form regex only matches { version = "..." } when version appears first, so snippets like { features = ["exact"], version = "0.4.2" } are silently skipped and stale versions can pass undetected.
Suggested fix
def _dependency_regex(package_name: str) -> re.Pattern[str]:
escaped_name = re.escape(package_name)
- return re.compile(rf'(?<![\w.-]){escaped_name}\s*=\s*(?:"(?P<plain>[^"]+)"|\{{\s*version\s*=\s*"(?P<table>[^"]+)")')
+ return re.compile(
+ rf'(?<![\w.-]){escaped_name}\s*=\s*'
+ rf'(?:"(?P<plain>[^"]+)"|\{{[^}}]*\bversion\s*=\s*"(?P<table>[^"]+)"[^}}]*\}})'
+ )📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| return re.compile(rf'(?<![\w.-]){escaped_name}\s*=\s*(?:"(?P<plain>[^"]+)"|\{{\s*version\s*=\s*"(?P<table>[^"]+)")') | |
| return re.compile( | |
| rf'(?<![\w.-]){escaped_name}\s*=\s*' | |
| rf'(?:"(?P<plain>[^"]+)"|\{{[^}}]*\bversion\s*=\s*"(?P<table>[^"]+)"[^}}]*\}})' | |
| ) |
🤖 Prompt for 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.
In `@scripts/check_docs_version_sync.py` at line 76, The current regex returned
for matching dependency versions uses a table branch that only matches when
version is the first key; update the pattern returned by the function that
builds/returns the compiled regex (the line with return
re.compile(rf'(?<![\w.-]){escaped_name}...')) so the table alternative allows
arbitrary keys before or after version (e.g. match
\{[^}]*version\s*=\s*"(?P<table>[^"]+)"[^}]*\}) while still anchoring on the
dependency name via escaped_name and preserving the plain-string branch; replace
the table-part of the alternation accordingly so inline tables like `{ features
= ["exact"], version = "0.4.2" }` are captured.
| import check_docs_version_sync | ||
|
|
||
|
|
||
| def test_find_version_mismatches_accepts_matching_dependency_snippets(tmp_path) -> None: |
Contributor
There was a problem hiding this comment.
Add type annotations for tmp_path in new tests.
Please annotate tmp_path as Path in both test signatures to match the repository’s Python typing rule for new code.
As per coding guidelines: **/*.py: Add type hints to new Python code. Type checking via just python-check is blocking — all code must pass type checks.
Also applies to: 31-31
🤖 Prompt for 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.
In `@scripts/tests/test_check_docs_version_sync.py` at line 6, Annotate the
tmp_path parameter as Path in the test signatures to satisfy typing rules:
update
test_find_version_mismatches_accepts_matching_dependency_snippets(tmp_path) ->
None to tmp_path: Path and do the same for the other test referenced at line 31;
also add the necessary import (from pathlib import Path) at the top of the test
file so the Path type is available.
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 by CodeRabbit
Documentation
Examples
Testing