Document docstrings and repair test helpers - #96
Draft
leynos wants to merge 2 commits into
Draft
Conversation
Define comprehensive NumPy-style documentation for public APIs and concise, selective documentation for private helpers and tests.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
leynos
enabled auto-merge (squash)
July 29, 2026 12:03
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughUpdate contributor documentation and refactor IR and Markdown tests to propagate construction errors, centralise static regex strategies, and validate explicitly mutated documents and source spans. ChangesTest quality updates
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 20✅ Passed checks (20 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Reviewer's guide (collapsed on small PRs)Reviewer's GuideAdds explicit Python docstring conventions for public APIs and private helpers to AGENTS.md, emphasizing NumPy-style docstrings, CQRS/cohesion review for verbose helpers, and meaningful test documentation. Flow diagram for private helper docstring conventionsflowchart TD
A["Write or update private helper"] --> B["Add single-line docstring by default"]
B --> C{"Need explanatory paragraph?"}
C -- "No" --> D["Keep concise single-line docstring"]
C -- "Yes" --> E["Review for CQRS and cohesion issues"]
E --> F{"Responsibilities conflated?"}
F -- "Yes" --> G["Split or extract focused helper"]
G --> B
F -- "No" --> H["Responsibility cohesive; explanation documents local constraint"]
H --> I["Keep paragraph and optional NumPy-style sections"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Return fixture construction failures to recognized test bodies and keep shared assertion helpers query-only. Centralize static proptest regex literals behind documented test-definition boundaries so Whitaker sees no anonymous expects outside tests.
There was a problem hiding this comment.
Gates Failed
(1 file with Code Duplication)
Our agent can fix these. Install it.
Gates Passed
Reason for failure
| Enforce advisory code health rules | Violations | Code Health Impact | |
|---|---|---|---|
| ir_consistency.rs | 1 advisory rule | 10.00 → 9.39 | Suppress |
Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.
Comment on lines
+127
to
+132
| let mut document = valid_document().expect("expected Markdown IR document"); | ||
| if let Some(node) = document.nodes.first().cloned() { | ||
| document.nodes.push(node); | ||
| } | ||
|
|
||
| assert_validation_reports(&document, "ir-duplicate-node-id", &["duplicate node id"]); |
There was a problem hiding this comment.
❌ New issue: Code Duplication
The module contains 5 functions with similar structure: validate_ir_consistency_reports_duplicate_node_ids,validate_ir_consistency_reports_duplicate_region_ids,validate_ir_consistency_reports_invalid_origin_nodes,validate_ir_consistency_reports_region_text_mismatches and 1 more functions
leynos
marked this pull request as draft
July 29, 2026 12:27
auto-merge was automatically disabled
July 29, 2026 12:27
Pull request was converted to draft
leynos
changed the title
![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 `@AGENTS.md`:
- Around line 26-28: Update the public API documentation rule in AGENTS.md to
align its example requirement with the rule at lines 23–25 by either requiring
examples for every public API or defining explicit exceptions for “where
appropriate.” Remove the duplicated test-documentation rule at lines 43–44, or
designate one occurrence as canonical.
🪄 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 Plus
Run ID: 64e145da-358c-4613-a836-4fe3249a9e5b
📒 Files selected for processing (8)
AGENTS.mdcrates/stilyagi-ir/src/tests/segment_properties.rscrates/stilyagi-ir/src/tests/suppression.rscrates/stilyagi-markdown/src/tests/coverage.rscrates/stilyagi-markdown/src/tests/ir_consistency.rscrates/stilyagi-markdown/src/tests/malformed.rscrates/stilyagi-markdown/src/tests/segment_validation.rscrates/stilyagi-markdown/src/tests/suppression_support.rs
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
leynos/pylint-pypy-shim(auto-detected)leynos/episodic(auto-detected)
Comment on lines
+26
to
+28
| - **Document public APIs comprehensively.** Public functions, classes, and | ||
| methods must have comprehensive NumPy-style docstrings, including clear | ||
| examples that demonstrate usage and outcome where appropriate. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Reconcile the overlapping documentation rules.
Make the example requirement consistent with lines 23–25: require examples for every public API, or define explicit exceptions for “where appropriate”. Remove the repeated test-documentation rule at lines 43–44, or make one rule canonical.
Triage: [type:docstyle]
As per coding guidelines, documentation guidance must remain clear, concise, and maintainable.
Also applies to: 43-44
🤖 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 `@AGENTS.md` around lines 26 - 28, Update the public API documentation rule in
AGENTS.md to align its example requirement with the rule at lines 23–25 by
either requiring examples for every public API or defining explicit exceptions
for “where appropriate.” Remove the duplicated test-documentation rule at lines
43–44, or designate one occurrence as canonical.
Source: Coding guidelines
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
This draft records the canonical Python docstring conventions in AGENTS.md.
Its first CI run exposed four still-valid Whitaker
no_expect_outside_testsfindings in Rust test-support functions. The separate conformance commit propagates fixture-construction errors, moves test-verdict unwrapping into recognised test bodies, keeps shared assertion helpers query-only, and uses one documented structural construction boundary per affected proptest crate. It adds no lint suppressions, exclusions, or naming workarounds.Because that repair spans seven Rust test files, this PR is intentionally left as a draft for review rather than auto-merged.
Validation
stilyagi-ir: rustfmt, Clippy, 57 tests, two doctests, Whitakerstilyagi-markdown: rustfmt, Clippy, 81 tests, Whitakermake all:make check-fmtmake typecheckmake lint, including full-workspace Whitakermake test— 330 Rust tests, 10 doctests, 195 Python testsmake markdownlint— including 12 spelling-policy testsmake nixie08cfa3d68ae407acc01006f27bc0261135b43ef4References