#405 Fix "File name too long" error with deep paths in JUnit reports

[ascheman]

Summary

Fixes #405 - Resolves "File name too long" error when generating JUnit XML reports for HTML files in deeply nested directory structures.

The solution introduces a configurable output style for JUnit XML reports:

• FLAT (default): Maintains backward compatibility with existing behavior - all files in one directory with encoded paths
• HIERARCHICAL: New mode that mirrors source file directory structure, solving filename length issues

Changes

Core Implementation

• Added JunitOutputStyle enum as nested class in Configuration (FLAT, HIERARCHICAL)
• Refactored JUnitXmlReporter to support both output modes with strategy pattern
• Implemented getHierarchicalOutputFile() with path normalization and security checks
• Updated AllChecksRunner to pass configuration to JUnitXmlReporter

Security & Quality Improvements (from GitHub Copilot review)

• Enhanced path traversal security: Replaced string-based path validation with NIO Path API for robust protection against sophisticated attacks
• Improved error diagnostics: Added detailed context to directory creation failures including existence status and parent permissions
• Comprehensive security testing: Added tests for path traversal attacks and error message validation

Plugin/CLI Updates

• Gradle plugin: Added junitOutputStyle input property
• Maven plugin: Added junitOutputStyle parameter
• CLI: Added --junitOutputStyle / -o command-line option

Testing

• Added 7 comprehensive tests for HIERARCHICAL mode including edge cases
• Added 2 tests for FLAT mode and exception handling
• Added 5 tests for security (path traversal) and enhanced error messages
• Improved overall test coverage for JUnitXmlReporter
• All 384+ tests pass successfully

Documentation

• Created comprehensive AsciiDoc documentation in src/docs/development/_includes/issue-405.adoc
• Includes problem description, solution details, configuration examples, and implementation notes

Testing with JitPack

You can test this fix before it's released by using JitPack to build from this branch:

Gradle

```groovy repositories { maven { url 'https://jitpack.io' } }

dependencies { // For the Gradle plugin classpath 'com.github.aim42.htmlSanityCheck:htmlSanityCheck-gradle-plugin:bugfix~405-enable-junit-results-per-dir-SNAPSHOT' }

htmlSanityCheck { junitOutputStyle = org.aim42.htmlsanitycheck.Configuration.JunitOutputStyle.HIERARCHICAL } ```

Maven

```xml jitpack.io https://jitpack.io

com.github.aim42.htmlSanityCheck htmlSanityCheck-maven-plugin bugfix~405-enable-junit-results-per-dir-SNAPSHOT HIERARCHICAL \`\`\`

Note: JitPack replaces / with ~ in branch names, so bugfix/405-enable-junit-results-per-dir becomes bugfix~405-enable-junit-results-per-dir-SNAPSHOT

Backward Compatibility

✅ Fully backward compatible - The default value is FLAT, maintaining existing behavior unless explicitly configured to use HIERARCHICAL mode.

CI Status

All workflows passing:

• ✅ Build and Test
• ✅ HTML Sanity Check Matrix Test (Java 8, 11, 17, 21 on Ubuntu, macOS, Windows)
• ✅ GitHub Pages
• ✅ SonarCloud Quality Gate

Related Commits

• 7116615 - Initial fix with hierarchical structure
• d076086 - Made feature configurable for backward compatibility
• 3fad99e - Improved test coverage for SonarCloud
• bf8ce30 - Enhanced path security and error handling (Copilot review)