feat(describe): add opt-in apply mode for /describe command to replace PR title and body

[matheusandre1]

What type of PR is this?

• 🐛 Bug fix
• ✨ Feature
• 📝 Documentation
• 🔧 Refactor
• 🚀 Performance
• ✅ Test
• 🔒 Security
• 📦 Dependency update
• 🏗️ CI/CD

Description

• optional in apply mode for /describe command

Related Issues

Closes: #325

How Has This Been Tested?

• Unit tests
• Integration tests
• Manual testing

Checklist

• My code follows the project's coding standards
• I have performed a self-review of my own code
• [X ] 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
• I have updated the documentation accordingly
• My changes generate no new warnings or error

[thrillhousebot]

🤖 ThrillhouseBot PR Summary

What this PR does

Adds an opt-in REVIEW_DESCRIBE_APPLY configuration that switches /describe from posting a suggestion comment to replacing the PR title and body via a new retrying GitHub PATCH, posting a confirmation comment that preserves the replaced content, and falling back to suggest-only when parsing or the update fails.

Description vs. Implementation

No mismatch found between the PR description and the change.

Control-Flow Diagram

🔀 Show diagram

flowchart TD
  A["/describe received (write gate passed, not paused)"] --> B{"describe.apply == true?"}
  B -- "no" --> C["generate() and post suggestion comment only"]
  B -- "yes" --> D["generateSuggestion() returns Suggestion record"]
  D --> E{"suggestion == null?"}
  E -- "yes" --> F["Post no-output notice"]
  E -- "no" --> G{"title and description parsed?"}
  G -- "no" --> H["Post suggestBody comment (fallback)"]
  G -- "yes" --> I["PATCH updatePullRequest(title, description)"]
  I --> J{"update failed?"}
  J -- "yes" --> H
  J -- "no" --> K["Post applyBody confirmation preserving previous title/body"]

Loading

Changes Overview

• Files changed: 12
• Lines added: +584
• Lines removed: -10

Changed Files

File	Change	Summary
.env.example	Modified	Adds a commented REVIEW_DESCRIBE_APPLY=false example.
CHANGELOG.md	Modified	Adds Unreleased entry for the opt-in /describe apply mode.
README.md	Modified	Documents /describe apply mode, the write-access gating, and the REVIEW_DESCRIBE_APPLY env var.
src/main/java/dev/thiagogonzaga/thrillhousebot/config/ThrillhouseConfig.java	Modified	Adds nested DescribeConfig mapping with apply() defaulting to false.
src/main/java/dev/thiagogonzaga/thrillhousebot/github/GitHubPullRequestClient.java	Modified	Adds retrying PATCH updatePullRequest and UpdatePullRequestRequest record capping title at 256 chars and body via CommentBodyLimit.
src/main/java/dev/thiagogonzaga/thrillhousebot/review/PrDescriptionGenerator.java	Modified	Splits generate() around a new doGenerate(); adds Suggestion record, parseSections() for title/description extraction, and an applyBody confirmation preserving replaced content.
src/main/java/dev/thiagogonzaga/thrillhousebot/webhook/CommentCommandService.java	Modified	Routes /describe to opt-in apply mode: PATCHes PR title/body via GitHubPullRequestClient and posts confirmation, with fallbacks to suggest-only.
src/main/resources/application.properties	Modified	Maps REVIEW_DESCRIBE_APPLY to thrillhousebot.review.describe.apply with a false default.
src/test/java/dev/thiagogonzaga/thrillhousebot/config/DescribeApplyDefaultOffTest.java	Added	QuarkusTest asserting describe.apply resolves to false by default.
src/test/java/dev/thiagogonzaga/thrillhousebot/github/GitHubPullRequestClientTest.java	Modified	Covers UpdatePullRequestRequest pass-through, title/body capping, and title/body-only serialization.
src/test/java/dev/thiagogonzaga/thrillhousebot/review/PrDescriptionGeneratorTest.java	Modified	Covers Suggestion record, parseSections shapes, applyBody preservation, and degraded suggest-only fallbacks.
src/test/java/dev/thiagogonzaga/thrillhousebot/webhook/CommentCommandServiceTest.java	Modified	Covers suggest-only default, apply-mode PATCH, and fallbacks on unparseable output or update failure.

Risk Assessment

Risk	Count
🔴 Critical	0
🟠 High	0
🟡 Medium	1
🔵 Low	0

Key Findings

• MEDIUM: parseSections: fenced/odd backtick titles parse as valid and get applied with backticks (src/main/java/dev/thiagogonzaga/thrillhousebot/review/PrDescriptionGenerator.java:259)

⚠️ Required CI Checks Status

Some required checks are still pending or have failed:

Check	Type	Status	Detail
format	missing	⏳ Pending	-
test	missing	⏳ Pending	-
frontend	missing	⏳ Pending	-
trivy	missing	⏳ Pending	-
dependency-review	missing	⏳ Pending	-

---

Automated review by ThrillhouseBot. Reply with /review to re-run.

[thrillhousebot]

🤖 ThrillhouseBot — changes since the last review

• New findings this round: 1
• Previous findings resolved: 1
• Previous findings still open: 0

[thrillhousebot]

ThrillhouseBot noted 1 lower-confidence item(s) under Things to double-check in the PR summary (not posted as inline threads):

• LOW: parseSections: unclosed backtick/fence opener is applied to the PR title verbatim (src/main/java/dev/thiagogonzaga/thrillhousebot/review/PrDescriptionGenerator.java:259)
  New decision rule: the backtick-tolerance branch only runs when the extracted title line BOTH starts and ends with a backtick (title.startsWith("") && title.endsWith("")). A line that OPENS with backtick(s) but has no matching close on the same line skips the branch entirely and is returned as an accepted title. Input not in the diff: '### Suggested title\nfeat: add the widget\n\n### Suggested description\nBody.' parses to title 'feat: add the widget' (starts with a backtick, ends with 't'), and the unclosed-fence variant '### Suggested title\nfeat: add the widget\n\n### Suggested description\nBody.' parses to 'feat: add the widget'. Both are non-empty, fail the strip condition, and are then PATCHed verbatim onto the PR title field by the opt-in apply path, with the confirmation comment claiming success. The parser's own contract states the opposite: its Javadoc says 'a shape the parser cannot read degrades the run to suggest-only rather than failing it', and the strip-branch comment says 'Only a single wrapping pair is the tolerated shape' and names 'a bare fence line' as a shape that must degrade. An unclosed opening is exactly that shape minus its closing backtick, so the asymmetry defeats the guard from the previous round (which only fixed both-ends-closed shapes). The in-diff tests cover only '``feat…``' and '' (both ends closed), so none exercise this path. Fix: when the title starts with a backtick but does not end with one, return null so the run degrades to the suggestion comment. Trade-off to note: a legitimately unwrapped title that merely begins with an inline code span, e.g. 'foo bar', would then also degrade to suggest-only rather than being applied — safe, because the suggestion comment still carries the full content.

[thrillhousebot]

🤖 ThrillhouseBot — changes since the last review

• New findings this round: 1
• Previous findings resolved: 1
• Previous findings still open: 0

[thrillhousebot]

ThrillhouseBot noted 1 lower-confidence item(s) under Things to double-check in the PR summary (not posted as inline threads):

• MEDIUM: Confirmation comment embeds full previous PR body without the comment-length cap (src/main/java/dev/thiagogonzaga/thrillhousebot/review/PrDescriptionGenerator.java:230)
  applyBody is assembled as APPLIED_HEADER + previousContent(inputs) + note + APPLIED_FOOTER + disclosure(plan), and previousContent embeds inputs.body() verbatim with no size bound. The same change caps every other outgoing text field — UpdatePullRequestRequest runs its body through CommentBodyLimit.cap and its Javadoc says that applies "like every other outgoing text field" — but the confirmation comment, which carries the feature's non-destructive guarantee ("whatever /describe replaced stays recoverable on the PR itself"), is not capped. Concrete edge: a PR whose existing body approaches GitHub's comment-length limit (~65536 chars; the PR-body field itself is allowed up to that limit) produces an applyBody that exceeds it; GitHub's comment endpoint rejects the post with 422, so after the PR title/body were already replaced, the comment preserving the previous content is never posted and the failure propagates out of describeAndApply after the mutation. Verify GitHub's exact 65536-char comment limit and what postComment does on a 4xx/5xx, then cap the assembled applyBody with CommentBodyLimit.cap (importing it from the github package into this review package) or truncate the embedded old body. No in-diff test uses a large previous body, so the short-old-body tests (applyBodyPreservesThePreviousTitleAndDescription) do not exercise this path.