🔧 Enhanced Diagram Support: Fix Structurizr CLI Integration (#1480)

[raifdmueller]

🎯 Problem Solved

This PR addresses GitHub Issue docToolchain#1480: "AsciiDoc Diagrams can't leverage Structurizr CLI"

When using asciidoctor-diagram with external CLI tools like Structurizr CLI through docToolchain, the diagram tools were not accessible due to environment variable isolation and process execution context issues.

🔧 Solution Overview

This enhancement provides comprehensive support for external diagram CLI tools by:

1. Environment Variable Propagation: Ensures diagram tool environment variables reach the AsciidoctorJ subprocess
2. Enhanced Fork Configuration: Proper JVM arguments and system properties for external tools
3. Debug Support: Comprehensive debugging and environment checking capabilities
4. Memory Optimization: Increased default memory allocation for complex diagram processing

📁 Files Added

• scripts/DiagramSupport.gradle - Main enhancement script with AsciidoctorJ configuration
• template_config/DiagramConfig.groovy - Configuration template and examples
• src/docs/015_tasks/03_task_enhanced_diagrams.adoc - Comprehensive documentation
• src/docs/015_tasks/03_task_structurizr_test.adoc - Test document with working examples
• DIAGRAM_ENHANCEMENT.md - Complete README with setup and troubleshooting

🚀 New Features

Tasks

./dtcw checkDiagramEnvironment     # Environment verification
./dtcw cleanDiagramCache          # Cache management  
./dtcw generateHTML -Ddiagram.debug=true  # Verbose logging

Environment Variables Supported

• DIAGRAMS_STRUCTURIZRCLI_HOME - Structurizr CLI path
• PLANTUML_JAR - PlantUML JAR path
• GRAPHVIZ_DOT - Graphviz DOT executable path

Debug Output Example

docToolchain> Propagating DIAGRAMS_STRUCTURIZRCLI_HOME=/opt/structurizr-cli
docToolchain> Document attribute set: structurizr-cli-path=/opt/structurizr-cli
docToolchain> Created diagram cache directory: /project/build/diagrams-cache

📋 Usage Example

Docker Setup

ENV DIAGRAMS_STRUCTURIZRCLI_HOME=/opt/structurizr-cli

AsciiDoc Usage

[structurizr,format=svg,target=example]
----
workspace {
    model {
        user = person "User"
        system = softwareSystem "System"
        user -> system "Uses"
    }
    views {
        systemContext system {
            include *
            autoLayout lr
        }
    }
}
----

✅ Testing Instructions

1. Environment Check:

   ./dtcw checkDiagramEnvironment

2. Test with Example Document:

   ./dtcw generateHTML -Ddiagram.debug=true

3. Verify Structurizr CLI Integration:

   • Set DIAGRAMS_STRUCTURIZRCLI_HOME environment variable
   • Use test document in src/docs/015_tasks/03_task_structurizr_test.adoc
   • Verify diagrams render as SVG images (not embedded text)

🔄 Backward Compatibility

• ✅ No breaking changes to existing APIs
• ✅ Existing diagram configurations continue to work
• ✅ Environment variables are optional (graceful degradation)
• ✅ Debug features are opt-in

🐛 Fixes

• Issue AsciiDoc Diagrams can't leverage Structurizr CLI docToolchain/docToolchain#1480: Structurizr CLI now properly accessible through asciidoctor-diagram
• Environment Isolation: External tools can now access required environment variables
• Debug Visibility: Clear troubleshooting information for diagram issues
• Performance: Improved caching and memory management for diagrams

🔍 Review Notes

The main enhancement is in scripts/DiagramSupport.gradle which:

• Configures forkOptions to propagate environment variables
• Sets up proper JVM arguments for external tools
• Provides comprehensive debugging capabilities
• Includes preprocessor for document attribute configuration

This approach is non-intrusive and can be easily included in existing projects without modifying core docToolchain files.

📖 Documentation

Complete documentation is provided in:

• DIAGRAM_ENHANCEMENT.md - Overview and quick start
• src/docs/015_tasks/03_task_enhanced_diagrams.adoc - Detailed usage guide
• src/docs/015_tasks/03_task_structurizr_test.adoc - Working examples and troubleshooting

---

Ready for Review ✨

This enhancement makes docToolchain much more powerful for architecture documentation by enabling seamless integration with external diagram tools like Structurizr CLI.