Skip to content

fix: preserve preformatted help descriptions - #1214

Open
efegokdemir wants to merge 7 commits into
apache:masterfrom
efegokdemir:codex/issue-845-preformatted-help
Open

efegokdemir wants to merge 7 commits into
apache:masterfrom
efegokdemir:codex/issue-845-preformatted-help

Conversation

@efegokdemir

Copy link
Copy Markdown

Summary

Fixes #845 (MPLUGIN-535) by preserving whitespace in JavaDoc <pre> blocks when generating plain-text plugin help output. Previously, code examples were flattened and their indentation was lost.

Codex assisted with repository analysis, implementation, and test preparation. The change has been reviewed locally, and all changed lines and validation results are disclosed here for human maintainer review.

Changes

  • Preserve raw text and line structure while converting <pre> content to plain text.
  • Keep the existing whitespace normalization for ordinary HTML descriptions.
  • Preserve leading spaces in generated help lines instead of treating them as word separators.
  • Add converter and help-basic-jdk11 regression coverage for a multi-line XML example.

Testing

  • mvn -pl maven-plugin-tools-generators -am -Dspotless.check.skip=true -Dspotless.apply.skip=true test -q ✅
  • mvn -pl maven-plugin-plugin -am -DskipTests -DskipITs -Dspotless.check.skip=true -Dspotless.apply.skip=true install -q ✅
  • mvn -pl maven-plugin-plugin -Prun-its -Dinvoker.test=help-basic-jdk11 -Dspotless.check.skip=true -Dspotless.apply.skip=true integration-test -q ⚠️ the fixture build succeeds, but the post-build Groovy hook cannot run with the local JDK 27 because the bundled Groovy runtime does not support class-file major version 71
  • Equivalent help-basic-jdk11 output comparison from the generated help.log against expected-help.txt ✅
  • git diff --check ✅
  • Spotless check ⚠️ local environment incompatibility: palantir-java-format fails with NoSuchFieldError against the installed JDK 27 compiler API

Notes

The production fix is shared by both legacy and Maven 4 help templates. The generated fixture output was verified independently because the repository's Groovy invoker hook is not compatible with the installed JDK 27. The commit is cryptographically signed and includes the required Signed-off-by trailer.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct fix for MPLUGIN-535 — the sentinel-char approach, the preformatted counter, and the whitespace-preservation logic all look sound. Two items worth cleaning up before merge.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up on my earlier review — both issues have been addressed.

  • ⚠️ Redundant second if (name.equals("pre")) block — ✅ merged into a single if/else-if chain
  • 💡 Edge-case tests — ✅ preformattedTextWithoutTrailingNewlinePreservesWhitespace and multiplePreformattedBlocksPreserveTheirBoundaries added

Pre-fix validation confirmed all 3 new tests fail on master and pass with the fix. The sentinel-char approach, the .vm preformatted-line detection heuristic (startsWith(" ") after converter normalization), and the boundary-suppression logic are all correct. The changed sections in help-class-source.vm and help-class-source-v4.vm are identical.

LGTM.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

@slachiewicz slachiewicz added the bug Something isn't working label Oct 29, 2026
Encode preformatted spaces only in the limited help descriptor so both
help templates preserve them during wrapping. Keep the public converter
and standard descriptors unchanged, and exercise generated Maven 3 and
Maven 4 help output.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up on my earlier review — the previous findings are all addressed, and this new commit correctly extends whitespace preservation through the full help generation pipeline using the NBSP-encoding approach. One item worth cleaning up:

This review was generated by an AI agent, Hermès on behalf of @gnodet.

Document the limited help descriptor's NBSP transport and generated
help decoding while distinguishing the ordinary converter behavior.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up on my earlier review — the previous Javadoc finding is addressed.

  • 💡 Missing Javadoc on convert(String, boolean) — ✅ addressed. The new Javadoc correctly documents the NBSP-encoding contract, the decode flow, and the caller (PluginDescriptorFilesGenerator for LIMITED_FOR_HELP_MOJO only).

The new tests in HtmlToPlainTextConverterTest and PluginDescriptorFilesGeneratorTest are thorough. One issue in the .vm templates worth fixing:

This review was generated by an AI agent, Hermès on behalf of @gnodet.

Signed-off-by: Efe Gökdemir <efe@rexcode.co.uk>

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All prior findings resolved. ✅

This is a clean, self-contained whitespace-preservation feature for <pre> blocks in help mojo output. The public API contract (convert(String)) is unchanged; the new preserveHelpWhitespace behavior is gated behind the package-private convert(String, boolean) overload and is only activated for DescriptorType.LIMITED_FOR_HELP_MOJO. All index accesses are properly bounds-checked, there are no concurrency concerns, no security issues, and no behavioral breaks for existing callers. The new tests thoroughly cover the feature.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[MPLUGIN-535] maven-plugin-plugin clobbers code block formatting

3 participants