fix(readme-generator): warn about mistyped and missing section markers - #708
Conversation
A marker whose name misses a section by a letter, and a README with no section markers at all, both produced a successful run that generated nothing, with the reason logged at debug level only. Before any section is written, generate now warns about a marker whose name is within two edits of a section name, suggesting that section, and about a README with no marker for any section, pointing at README.example.md. A name far from every section is left alone: the template's own [.github/ghadocs/examples/] marker and other tools' markers use the same syntax. Markers inside code are examples and are not reported. The exit code is unchanged. Fixes #644 Fixes #641 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. Warning Review limit reachedNext included review available in 37 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: Repository: bitflight-devops/github-action-readme-generator/.coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (4)
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository: bitflight-devops/github-action-readme-generator/.coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (5)
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review. WalkthroughThe generator now diagnoses missing or misspelled README section markers and logs warnings before updating sections. The README usage example also references version v2.0.1. ChangesMarker diagnostics
README usage example
Priority: ➖ Normal Estimated code review effort: 3 (Moderate) | ~20 minutes Change: Bug fix · Severity of issue fixed: Medium Sequence Diagram(s)sequenceDiagram
participant ReadmeGenerator
participant diagnoseMarkers
participant logger
ReadmeGenerator->>diagnoseMarkers: README content and README_SECTIONS
diagnoseMarkers-->>ReadmeGenerator: warning messages
ReadmeGenerator->>logger: log each warning
Suggested reviewers: Merge Risk: ⚪ Minimal · up to No blocking issue was identified in the marker diagnostics, generator integration, or usage example; the change is mergeable after normal checks. Security Architecture ReviewSecurity architecture risk: 🔵 Low · up to The change primarily adds warnings. It does not appear to grant new access or change where README content is written, but a diagnostic failure could now stop generation before updates begin. Retained concerns Security review detailsSecurity Blast Radius
Trust Boundaries and Controls
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Out of Scope Changes checkExplanation The README change updates the usage version from ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bc18fda49c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The mistyped-marker check set aside every marker inside code, so a single mistyped pair after an unclosed generated fence went unreported. It now follows locateSection's rule: a single pair counts wherever it sits, and code only sets aside markers that are not one pair. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2124cb477b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
A typo on one side splits a pair across two names, so the pair rule saw neither side as a pair and set the typo aside when it sat after an unclosed fence. Markers are now grouped by their section, or the section a near-miss name was meant to be, before the pair rule is applied. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6a789cda3b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The mistyped-marker check used the single-pair rule as a stand-in for "the markers sit after an unclosed fence", and each edge case of that stand-in produced a missed or false warning. It now asks the real question: a marker inside closed code is an example, and a marker inside a fence that nothing closes is reported. The missing-markers warning now checks the sections being generated, so --sections=inputs against a README with only a title pair warns, and an empty selection does not. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 39e6ee2ffb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The unclosed-fence check read a code range's kind from its text, so inline code opened by triple backticks, or an indented block whose first line is backticks, was taken for a fence that nothing closes, and a mistyped example inside it was reported. The parser's node kind now decides: only a fenced code block, whose node starts at its fence, can be unclosed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
Only fenced code blocks reach isUnclosedFence, and a fenced block's node starts at its fence, so the branch for a missing opener could not run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f9b50e38a1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const examples = codeRanges(source).filter( | ||
| ([from, to, fenced]) => !fenced || !isUnclosedFence(source.slice(from, to)), | ||
| ); |
There was a problem hiding this comment.
When an unclosed fenced example contains only one near-miss marker, such as a lone <!-- start input -->, this filter removes the entire code range from examples and emits a typo warning. Because this is not a complete start/end pair, locateSection would still set the marker aside as code; only a complete inferred pair should bypass code filtering. Otherwise valid third-party READMEs receive false warnings for documented examples.
AGENTS.md reference: AGENTS.md:L14-L19
Useful? React with 👍 / 👎.
## [2.0.3](v2.0.2...v2.0.3) (2026-09-29) ### Bug Fixes * **markers:** never pair a marker with an example in closed code ([#712](#712)) ([44f4da7](44f4da7)) * **readme-generator:** warn about mistyped and missing section markers ([#708](#708)) ([7d6c536](7d6c536)) * **sections:** keep fenced code blocks in a description intact ([#709](#709)) ([47728d4](47728d4))
|
🎉 This PR is included in version 2.0.3 🎉 The release is available on: Your semantic-release bot 📦🚀 |
2 participants
Description
A marker whose name misses a section by a letter (#644), and a README with no section markers at all (#641), both gave a successful run that generated nothing. The only log of the reason was at debug level. Unpaired and ambiguous markers already warn, since #704.
Type of Change
Related Issues
Changes Made
diagnoseMarkers(source, sections)insrc/markers.tsreturns one warning per problem.ReadmeGenerator.generate()logs each warning before any section is written.<!-- start input -->gets "Did you mean 'inputs'?".[.github/ghadocs/examples/]marker inREADME.example.md, which nothing fills, and on other tools' markers that use the same comment syntax.README.example.md.Testing
vp test,vp check, bundled-binary test)diagnoseMarkerscases for a missing letter, a different case and a transposition. Also a far name, a typo inside code, a README with no markers, and an unpaired-only README. Twogenerate()tests: one README warns, one does not.<!-- start input -->and on a README with no markers.setup-cosmocccarries the[.github/ghadocs/examples/]marker.Additional Notes
The pre-commit
generate-docsrun also changed two generated files:README.mdnow uses the v2.0.1 tag..github/ghadocs/branding.svghas its attributes reordered. The image is unchanged.🤖 Generated with Claude Code
https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t
Generated by Claude Code
Summary by CodeRabbit
New Features
Documentation