fix(sections): keep a description's block Markdown in the description section

[Jamie-BitFlight]

Description

The description section replaced each blank line in an action description with <br /> and squashed runs of spaces. A list, a second paragraph or an indented code block lost its structure. A fence in a list item fell out of the list.

The description is now kept as written: it is only trimmed and CRLF becomes LF. Prettier formats the span as block Markdown.

Type of Change

• Bug fix (non-breaking change which fixes an issue)

Related Issues

• Fixes The description section flattens block Markdown, such as lists, into one paragraph #711
• Related to fix(sections): keep fenced code blocks in a description intact #709

Changes Made

• src/sections/update-description.ts: descriptionMarkdown keeps the description as written. The fence detection from fix(sections): keep fenced code blocks in a description intact #709 only protected fences from the squash, so it is removed.
• scripts/verify-readme-contract.mjs: the contract verifier builds its expected description with the same rule.
• __tests__/update-description.test.ts: covers the rule, the list-with-fence case from the issue, the prettier-formatted section, and a stable second format.
• __tests__/verify-readme-contract.test.ts: the verifier accepts a block Markdown description and rejects the old <br /> form.
• README.md: the pre-commit generate-docs run set the usage version to v2.0.2. The 2.0.3 release commit on main makes the same change, so this line is a no-op after merge.

Testing

• All existing tests pass (npm run check, npm run test)
• Added new tests for new functionality. The new tests fail against the old implementation.
• Manually tested the changes: the built binary ran three times on the example from the issue. The list and its fence are kept, and passes 1, 2 and 3 are identical.

Checklist

• My code follows the project's code style
• I have performed a self-review of my own code
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Additional Notes

This is filed as a non-breaking fix, because the text between the markers belongs to the tool. Consumers still see a one-time change:

• A README whose action description has a blank line changes once: paragraphs joined by <br /> become separate paragraphs.
• A heading line in a description now renders as a heading.
• Trailing double spaces in a description now render as hard line breaks.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H37LVnd9qB6PmZ5bJi5H2t

Summary by CodeRabbit

• Bug Fixes
  • README description output now preserves Markdown paragraphs, lists, nested code fences, and indented code blocks, while normalizing line endings.
  • README validation now checks that descriptions retain their original Markdown structure.
• Documentation
  • Updated the Usage example to reference github-action-readme-generator@v2.0.2.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: bitflight-devops/github-action-readme-generator/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: a809a9ed-1906-4b3d-8a5d-2a45b223a5ba

📥 Commits

Reviewing files that changed from the base of the PR and between a71f1e2 and b62e87d.

⛔ Files ignored due to path filters (1)

• .github/ghadocs/branding.svg is excluded by !**/*.svg

📒 Files selected for processing (5)

• README.md
• __tests__/update-description.test.ts
• __tests__/verify-readme-contract.test.ts
• scripts/verify-readme-contract.mjs
• src/sections/update-description.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The description formatter and README contract verifier now preserve block Markdown, including paragraph breaks, lists, and code blocks. The formatter trims outer whitespace and normalizes CRLF line endings. The README Usage example now references version v2.0.2.

Changes

Description Markdown preservation

Layer / File(s)	Summary
Preserve description Markdown structure src/sections/update-description.ts, scripts/verify-readme-contract.mjs, __tests__/update-description.test.ts, __tests__/verify-readme-contract.test.ts	The formatter trims descriptions and normalizes CRLF line endings without collapsing internal spacing or paragraph breaks. The contract verifier compares the description as written. Tests cover lists, nested and indented code blocks, formatted output stability, and README contract validation.

README Usage example version

Layer / File(s)	Summary
Update Usage example reference README.md	The Usage example changes its action reference from v2.0.1 to v2.0.2.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~15 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: bitflight-devops

Merge Risk: ⚪ Minimal · up to b62e8

The description changes and README example are ready to merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to b62e8

The generated description now retains block Markdown, but the change does not add a runtime entrypoint, privilege, or write target. No security regression was identified in the reviewed path.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The changed projection affects repository-authored action description text in the generated README section; the reviewed path shows no new destination or execution authority.

Trust Boundaries and Controls

• observed — The range labeled as a public API is a test-local formatting helper. Production description output continues through the existing marker-bounded editor.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The README change updates the Usage example from github-action-readme-generator@v2.0.1 to v2.0.2. The supplied issue scope concerns description Markdown preservation and verifier behavior. The sum…	Remove the unrelated README version-reference change, or provide a concrete issue requirement that requires this version update.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving block Markdown in the description section.
Linked Issues check	✅ Passed	Issue #711 requires action descriptions to retain blank lines and block Markdown, and requires the README contract verifier to use the same rule. src/sections/update-description.ts now trims input a…

Full details: Out of Scope Changes check

Explanation

The README change updates the Usage example from github-action-readme-generator@v2.0.1 to v2.0.2. The supplied issue scope concerns description Markdown preservation and verifier behavior. The summary provides no connection between this version-reference change and issue #711.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 4 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	92.14%	1009 / 1095
🔵	Statements	92.3%	1031 / 1117
🔵	Functions	95.03%	153 / 161
🔵	Branches	85.84%	552 / 643

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/sections/update-description.ts	100%	50%	100%	100%

Generated in workflow #1057 for commit b62e87d by the Vitest Coverage Report Action

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	92.14%	1009 / 1095
🔵	Statements	92.3%	1031 / 1117
🔵	Functions	95.03%	153 / 161
🔵	Branches	85.84%	552 / 643

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/sections/update-description.ts	100%	50%	100%	100%

Generated in workflow #1057 for commit b62e87d by the Vitest Coverage Report Action

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Jamie-BitFlight]

🎉 This PR is included in version 2.0.4 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀