Skip to content

bloomreach-forge/brXM-Inspection-Tool

BranchesTags

Repository files navigation

Bloomreach CMS Inspections Tool

Comprehensive static analysis for Bloomreach Experience Manager (brXM) projects

Version License Build

A powerful static analysis tool for Bloomreach Experience Manager (brXM) projects, available as both an IntelliJ IDEA plugin and a standalone CLI tool. Detects common issues, performance bottlenecks, security vulnerabilities, and configuration problems based on analysis of 1,700+ community forum topics.

✨ Features

🔍 Comprehensive Inspections (44 Total)

  • Repository Tier (5 inspections, 40% priority)

    • JCR Session Leak Detection
    • Dangerous Session.refresh() Calls
    • Content Bean Mapping Issues
    • Document Workflow Implementation Issues
    • Workflow Action Availability Checks

  • Configuration (22 inspections, 25% priority)

    • Bootstrap UUID Conflict Detection
    • Sitemap Pattern Shadowing Detection
    • Component Parameter Null Checks
    • Cache Configuration Issues
    • HST Component Lifecycle Issues
    • HST Component Thread Safety Issues
    • HttpSession Usage in HST
    • HST Filter Implementation Issues
    • System.out/err Usage
    • Static Request/Session Storage (Concurrency Bug)
    • HST Configuration Root Path Issues
    • Channel Configuration Node Issues
    • HTML Comment Stripping Detection
    • Load Balancer Affinity / 409 Conflict Detection
    • Magic String Detection
    • Static Dropdown Values in Document Types
    • Development Channel Presence in HST Config
    • Project Approval Count Configuration
    • HST Configuration Bloat Detection
    • Resource Bundle Location Validation
    • Content Type Lock Detection
    • Duplicate Numbered Field Definitions

  • Performance (6 inspections, 15% priority)

    • Unbounded JCR Query Detection
    • Missing Database Index Detection
    • HippoFolder.getDocuments() Performance Issues
    • HstQueryResult.getSize() Performance Issues
    • Synchronous HTTP Calls in Components
    • _maxreflevel Parameter Usage in URLs

  • Security (9 inspections, 10% priority)

    • Hardcoded Credentials Detection
    • Hardcoded JCR Paths Detection
    • Missing REST Authentication
    • JCR Query SQL Injection (String Concatenation)
    • Missing XSS Output Escaping
    • Security Header Configuration (X-Frame-Options)
    • User Role Authentication Checks
    • External Preview Token Exposure
    • Open UI Extension Usage

  • Deployment (2 inspections)

    • Docker/Kubernetes Configuration Issues
    • Project Version Configuration & Compatibility

🚀 Dual Deployment Options

  1. IntelliJ IDEA Plugin - Real-time analysis as you code
  2. CLI Tool - Batch analysis for CI/CD integration

⚡ Performance

  • Parallel inspection execution
  • Smart parse caching
  • Incremental analysis
  • Fast file scanning with glob patterns

🛠️ Developer Experience

  • Real-time issue highlighting in IDE
  • Quick fixes (Alt+Enter)
  • Detailed issue descriptions with examples
  • Progress reporting
  • Multiple report formats (HTML, Markdown, JSON)

📦 Installation

IntelliJ Plugin

Supported IDEs: IntelliJ IDEA Community Edition 2023.2.5+ (builds 232-242.*)

  1. Build the plugin: 
    ./gradlew :intellij-plugin:build
  2. Locate plugin: intellij-plugin/build/distributions/intellij-plugin-1.2.0.zip
  3. Open IntelliJ IDEA
  4. Go to Settings > Plugins
  5. Click gear icon ⚙️ > Install Plugin from Disk...
  6. Select the built ZIP file
  7. Restart IDE
  8. Go to Settings > Tools > Bloomreach CMS Inspections to configure

Features after installation:

  • Real-time code inspection highlighting
  • Quick fixes via Alt+Enter (Cmd+Enter on Mac)
  • "Bloomreach Inspections" tool window with statistics
  • Per-inspection severity configuration
  • Enable/disable individual inspections

CLI Tool

Quick Start

# Build the CLI
./gradlew :cli:build

# Run it
java -jar cli/build/libs/cli-1.0.7.jar --help

Install Globally (Optional)

# Build distribution package
./gradlew :cli:build

# Extract and install
unzip cli/build/distributions/cli-1.0.7.zip -d /usr/local/

# Add to PATH (for Linux/Mac)
echo 'export PATH="/usr/local/cli-1.0.7/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Test installation
brxm-inspect --version

Windows Installation

REM Build and extract to Program Files
gradlew :cli:build
powershell Expand-Archive -Path cli\build\distributions\cli-1.0.7.zip -DestinationPath "C:\Program Files"

REM Add C:\Program Files\cli-1.0.7\bin to PATH environment variable
REM Then restart terminal and test
brxm-inspect --version

🎯 Quick Start

IntelliJ Plugin

  1. Open a Bloomreach project in IntelliJ
  2. Watch for issues - Highlighted in real-time as you type
  3. View all issues - Press Alt+6 (Cmd+6 on Mac) for Problems panel
  4. Apply fixes - Press Alt+Enter (Option+Enter on Mac) on highlighted issues
  5. Tool window - Click "Bloomreach Inspections" tab at bottom

CLI Tool

Analyze a Project

# Analyze a brXM project directory
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/bloomreach-project

# Analyze with verbose output
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project --verbose

# Analyze with parallel execution (faster)
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project --parallel --threads 8

List and Filter Inspections

# List all available inspections
java -jar cli/build/libs/cli-1.0.7.jar list-inspections

# List only ERROR severity
java -jar cli/build/libs/cli-1.0.7.jar list-inspections --severity ERROR

# List by category
java -jar cli/build/libs/cli-1.0.7.jar list-inspections --category SECURITY

Generate Reports

# Generate HTML, Markdown, and JSON reports
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project \
  --format html,markdown,json \
  --output ./brxm-reports

# Only report warnings and errors (skip info level)
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project \
  --min-severity WARNING \
  --output ./reports

Configuration-Based Analysis

# Initialize configuration file
java -jar cli/build/libs/cli-1.0.7.jar config init > brxm-inspections.yaml

# Edit the configuration file to customize inspections

# Analyze using configuration
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project \
  --config brxm-inspections.yaml

CI/CD Integration

# Exit with error code if issues found above threshold
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project \
  --fail-on-error \
  --max-errors 5

# Generate report for Jenkins/GitLab CI
java -jar cli/build/libs/cli-1.0.7.jar analyze /path/to/project \
  --format json \
  --output ./reports/analysis.json

📊 Example Output

IntelliJ Plugin

Real-time highlighting in editor:

Session session = repository.login();  // ❌ ERROR: Session Leak
// ... code ...
// Missing: session.logout() in finally block

Tool Window Display:

Bloomreach Inspections
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Issues: 47
  🔴 Errors: 12
  🟡 Warnings: 23
  🔵 Info: 10
  💡 Hints: 2

By Category:
  Repository Tier:     12 issues
  Configuration:       18 issues
  Performance:         14 issues
  Security:            3 issues

Files with Issues: 8
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recent Issues:
  🔴 repository.session-leak at SessionService.java:42
     JCR Session not closed in finally block

  🔴 security.hardcoded-credentials at DatabaseConfig.java:23
     Hardcoded password detected in configuration

  🟡 performance.unbounded-query at ContentDAO.java:156
     Query executed without setLimit()

  🟡 config.sitemap-shadowing at sitemap.xml:45
     General pattern shadows specific pattern

CLI Tool

Analysis output:

$ java -jar cli-1.0.7.jar analyze /path/to/project

Bloomreach CMS Inspections - Analyzing project
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scanning project structure...
Found 1,234 files to analyze

[████████████████████████░░░░░░░░░░░░░░░░░░] 62% (765/1234) - SessionService.java

Analysis complete in 45.3s

ANALYSIS RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Issues Found: 47

Severity Breakdown:
  🔴 Errors:   12 (Critical - Requires immediate attention)
  🟡 Warnings: 23 (Important - Should be addressed)
  🔵 Info:     10 (Informational - Optimization opportunities)
  💡 Hints:     2 (Suggestions - Consider for improvement)

By Category:
  Repository Tier:     12 issues ↳ SessionService, ContentDAO
  Configuration:       18 issues ↳ SitemapConfig, CacheConfig
  Performance:         14 issues ↳ QueryDAO, HttpClient
  Security:             3 issues ↳ Credentials, Authentication
  Deployment:           0 issues ✓

Top Issues:
  🔴 12 occurrences of JCR Session Leak (repository.session-leak)
  🔴  3 occurrences of Bootstrap UUID Conflict (config.bootstrap-uuid-conflict)
  🟡 15 occurrences of Unbounded Query (performance.unbounded-query)

FILES WITH MOST ISSUES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. SessionService.java              8 issues
2. ContentDAO.java                  6 issues
3. SitemapConfiguration.xml          5 issues
4. CacheConfig.java                 4 issues
5. DatabaseConfiguration.java        3 issues

REPORTS GENERATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Generated in: ./brxm-inspection-reports

Files:
  ✓ inspection-report.html       (Detailed interactive report)
  ✓ inspection-report.md         (Markdown for documentation)
  ✓ inspection-report.json       (Machine-readable format)

Next Steps:
  1. Review issues in inspection-report.html
  2. Address 🔴 Errors first (critical issues)
  3. Use Alt+Enter in IDE to apply quick fixes
  4. Run analysis again to verify fixes

JSON Report Sample:

{
  "analysis": {
    "project": "/path/to/project",
    "timestamp": "2025-12-11T10:30:00Z",
    "duration": "45.3s",
    "fileCount": 1234,
    "summary": {
      "totalIssues": 47,
      "byServerity": {
        "ERROR": 12,
        "WARNING": 23,
        "INFO": 10,
        "HINT": 2
      }
    },
    "issues": [
      {
        "id": "repository.session-leak",
        "severity": "ERROR",
        "file": "src/main/java/SessionService.java",
        "line": 42,
        "message": "JCR Session 'session' is not closed in finally block",
        "description": "Unclosed sessions cause session pool exhaustion...",
        "quickFix": "Add finally block with session.logout()"
      }
    ]
  }
}

📖 Documentation

🔧 Configuration

Plugin Settings

Settings > Tools > Bloomreach CMS Inspections

  • Enable/disable all inspections
  • Toggle parse cache
  • Configure parallel execution

Settings > Editor > Inspections > Bloomreach CMS

  • Enable/disable individual inspections
  • Set severity levels per inspection

CLI Configuration

Create brxm-inspections.yaml:

enabled: true
minSeverity: INFO
parallel: true
maxThreads: 8
cacheEnabled: true

excludePaths:
  - "**/target/**"
  - "**/build/**"

inspections:
  repository.session-leak:
    enabled: true
    severity: ERROR

  performance.unbounded-query:
    enabled: true
    severity: WARNING

🏗️ Architecture

brxm-inspections-tool/
├── core/                    # Framework-agnostic inspection engine
│   ├── engine/             # Execution engine, caching, indexing
│   ├── inspections/        # All inspection implementations
│   ├── parsers/            # Java, XML, YAML parsers
│   └── config/             # Configuration management
│
├── intellij-plugin/        # IntelliJ IDEA plugin
│   ├── inspections/        # IDE inspection wrappers
│   ├── bridge/             # Core <-> IDE adapters
│   ├── services/           # Project-level services
│   └── toolwindow/         # UI components
│
└── cli/                    # Standalone CLI tool
    ├── commands/           # CLI command implementations
    └── runner/             # File scanning, analysis coordination

Design Principles

  • Separation of Concerns - Core logic independent of IDE/CLI
  • Plugin Architecture - Easy to add new inspections
  • Performance First - Parallel execution, caching, incremental analysis
  • Extensibility - ServiceLoader-based inspection discovery

🧪 Testing

Run Tests

# All tests
./gradlew test

# Core tests only
./gradlew :core:test

# Build everything
./gradlew build

Test Files

Sample files for testing inspections are in test-samples/:

cd test-samples
java -jar ../cli/build/libs/cli-1.0.7.jar analyze .

See test-samples/README.md for details.

📋 Complete Inspection Reference

Repository Tier Inspections (5)

ID Name Severity Description
repository.session-leak JCR Session Leak 🔴 ERROR Detects JCR sessions not closed in finally blocks, causing session pool exhaustion.
repository.session-refresh Dangerous Session.refresh() 🟡 WARNING Detects unsafe session.refresh() calls that can discard unsaved changes.
repository.content-bean-mapping Content Bean Mapping Issues 🟡 WARNING Identifies issues in content bean JCR-to-POJO mapping and property access.
repository.document-workflow Document Workflow Issues 🟡 WARNING Detects problems in SCXML workflow implementations.
repository.workflow-action Workflow Action Availability 🔴 ERROR Ensures workflow actions check availability before execution.

Configuration Inspections (22)

ID Name Severity Description
config.bootstrap-uuid-conflict Bootstrap UUID Conflict 🔴 ERROR Detects duplicate UUIDs in hippoecm-extension.xml causing bootstrap failures.
config.sitemap-shadowing Sitemap Pattern Shadowing 🟡 WARNING Identifies HST sitemap patterns where general patterns shadow specific ones.
config.component-parameter-null Component Parameter Null Check 🟡 WARNING Detects HST component parameters accessed without null checks.
config.cache-configuration Cache Configuration Issues 🟡 WARNING Identifies caching configuration problems and optimization opportunities.
config.hst-component-lifecycle HST Component Lifecycle 🟡 WARNING Detects improper HST component lifecycle management.
config.hst-component-thread-safety HST Component Thread Safety 🔴 ERROR Identifies thread safety violations in HST component implementations.
config.http-session-use HttpSession Usage in HST 🟡 WARNING Detects improper HttpSession usage in stateless HST components.
config.hst-filter HST Filter Issues 🟡 WARNING Identifies problems in HST filter configuration and implementation.
config.system-out-calls System.out/err Usage 🔵 INFO Detects System.out/err calls that should use proper logging.
config.static-request-session Static Request/Session Storage 🔴 ERROR Detects static storage of request/session objects causing concurrency bugs.
config.hst-configuration-root-path HST Configuration Root Path 🔴 ERROR Detects missing or invalid hst.configuration.rootPath properties.
config.channel-configuration-node Channel Configuration Node 🟡 WARNING Detects incorrect HST channel node placement in the repository hierarchy.
config.html-comment-stripping HTML Comment Stripping 🟡 WARNING Detects comment removal configurations that break the Experience Manager UI.
config.load-balancer-affinity-409 Load Balancer Affinity (409) 🟡 WARNING Detects missing sticky-session configuration in multi-server deployments.
config.magic-string Magic String Detection 💡 HINT Detects hardcoded string literals that should be extracted as named constants.
config.static-dropdown-values Static Dropdown Values 🔴 ERROR Detects hardcoded label|value pairs in document type source properties.
config.development-channel-presence Development Channel Presence 🔴 ERROR Detects development/test channel nodes left in HST configuration.
config.project-approval-count Project Approval Count 🔴 ERROR Detects approval count set to 0 or 1 in experience projects.
config.hst-configuration-bloat HST Configuration Bloat 🔴 ERROR Detects excessive HST channel/site nodes indicating configuration bloat.
config.resource-bundle-location Resource Bundle Location 💡 HINT Flags resource bundles that may be in incorrect repository locations.
config.content-type-lock Content Type Lock 🟡 WARNING Detects locked content types (jcr:lockOwner) blocking structural changes.
config.duplicate-field-definition Duplicate Field Definition 💡 HINT Detects numbered field sequences (image1, image2) suggesting repeated fields.

Performance Inspections (6)

ID Name Severity Description
performance.unbounded-query Unbounded JCR Query 🟡 WARNING Detects JCR queries without setLimit() that can cause memory exhaustion.
performance.missing-index Missing Database Index 🔵 INFO Identifies potential missing database indexes on frequently queried properties.
performance.get-documents getDocuments() Performance 🟡 WARNING Detects inefficient HippoFolder.getDocuments() usage patterns.
performance.get-size getSize() Performance 🟡 WARNING Identifies inefficient HstQueryResult.getSize() calls that load all results.
performance.http-calls Synchronous HTTP Calls 🟡 WARNING Detects blocking HTTP calls in HST components that stall page rendering.
performance.maxreflevel-usage _maxreflevel Parameter Usage 🔴 ERROR Detects hardcoded _maxreflevel query parameters that bypass caching.

Security Inspections (9)

ID Name Severity Description
security.hardcoded-credentials Hardcoded Credentials 🔴 ERROR Detects hardcoded passwords, API keys, and access tokens in source code.
security.hardcoded-paths Hardcoded JCR Paths 🟡 WARNING Identifies hardcoded JCR paths that reduce configuration flexibility.
security.rest-authentication Missing REST Authentication 🔴 ERROR Detects REST endpoints without proper authentication checks.
security.jcr-parameter-binding JCR SQL Injection 🔴 ERROR Detects SQL injection vulnerabilities from string concatenation in JCR queries.
security.missing-jsp-escaping Missing XSS Escaping 🔴 ERROR Identifies missing output escaping in JSP/FreeMarker templates.
security.security-header-configuration Security Header Configuration 🔴 ERROR Detects X-Frame-Options: DENY that breaks the Experience Manager UI.
security.user-role-authentication User Role Authentication 🔴 ERROR Detects Channel Manager operations missing the xm.channel.user role check.
security.external-preview-token External Preview Token 🟡 WARNING Detects preview token configuration exposed in XML/YAML that may leak to clients.
security.open-ui-extension Open UI Extension Usage 🟡 WARNING Flags Open UI extension plugin classes for manual security review.

Deployment Inspections (2)

ID Name Severity Description
deployment.docker-config Docker/Kubernetes Configuration 🟡 WARNING Identifies Docker and Kubernetes configuration issues.
deployment.project-version Project Version 💡 HINT Reports project version for compatibility and end-of-life tracking.

Legend

  • 🔴 ERROR - Critical issue requiring immediate attention
  • 🟡 WARNING - Important issue that should be addressed
  • 🔵 INFO - Informational issue for optimization
  • 💡 HINT - Suggestion for improvement

🤝 Contributing

We welcome contributions! To add a new inspection:

  1. Create inspection class in core/src/main/kotlin/org/bloomreach/inspections/core/inspections/{category}/
  2. Implement Inspection interface with required properties (id, name, description, category, severity, applicableFileTypes)
  3. Create AST visitor or parser for analysis logic
  4. Add unit tests in core/src/test/kotlin/
  5. Register in META-INF/services/org.bloomreach.inspections.core.engine.Inspection
  6. (Optional) Create IDE wrapper in intellij-plugin/src/main/kotlin/.../inspections/
  7. (Optional) Register wrapper in plugin.xml

See Developer Guide for detailed examples and best practices.

📈 Project Status

Component Status Inspections Tests
Core Engine ✅ Complete 44 inspections 405 passing
IntelliJ Plugin ✅ Complete Full support -
CLI Tool ✅ Complete Full support -
Documentation ✅ Complete Comprehensive -

Completed Features

  • ✅ 44 core inspections implemented across all categories
    • 5 Repository Tier inspections
    • 22 Configuration inspections
    • 6 Performance inspections
    • 9 Security inspections
    • 2 Deployment inspections
  • ✅ IntelliJ plugin with real-time analysis (12+ inspection wrappers)
  • ✅ CLI tool with progress reporting and batch analysis
  • ✅ ServiceLoader-based dynamic discovery
  • ✅ Parallel execution engine for performance
  • ✅ Smart parse caching and AST reuse
  • ✅ Project-wide cross-file indexing
  • ✅ Quick fixes for most inspections
  • ✅ Tool window with statistics and filtering
  • ✅ Comprehensive settings panel
  • ✅ Full test coverage (405 tests, 100% pass rate)

Roadmap

  • 🔄 Report Generation - Enhanced HTML/Markdown/JSON output formats
  • 🔄 Quick Fixes - Expand quick fix support for more inspections
  • 🔄 Custom Rules - User-defined inspection rules and patterns
  • 🔄 Gradle Plugin - Gradle plugin for build-time analysis
  • 🔄 Maven Plugin - Maven plugin for CI/CD integration
  • 🔄 VS Code Extension - Visual Studio Code extension support
  • 🔄 JetBrains Marketplace - Publish IntelliJ plugin to official marketplace
  • 🔄 Additional Inspections - Community-requested inspections based on forum analysis

🙏 Acknowledgments

Built with analysis of 1,700+ Bloomreach community forum topics to identify the most common real-world issues faced by developers.

Inspired by:

  • intellij-hippoecm plugin by @machak
  • Bloomreach Community feedback and issues
  • IntelliJ Platform inspection framework
  • Picocli CLI framework

📄 License

Apache License 2.0

Copyright 2025 Bloomreach

📞 Support

🌟 Quick Links

Documentation Versions

Built with ❤️ for the Bloomreach Community

About

a CI/CD analysis tool specific to Bloomreach CMS projects

Resources

Readme

License

View license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages