CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Build and Test

./gradlew build                              # Build the plugin
./gradlew test -x rat                        # Run unit tests (excluding Apache RAT license checks)
./gradlew test --tests "OgnlParsingTest"     # Run specific test class
./gradlew test --tests "*Resolving*"         # Run tests matching pattern
./gradlew check                              # Run tests and code analysis
./gradlew koverHtmlReport                    # Generate code coverage report (build/reports/kover/)

Development and Debugging

./gradlew runIde                             # Run IntelliJ IDEA with the plugin loaded
./gradlew runIdeForUiTests                   # Launch IDE with robot server on port 8082
./gradlew buildPlugin                        # Build plugin distribution (build/distributions/)
./gradlew runPluginVerifier                  # Verify compatibility against specified IDEs

Code Quality

./gradlew runInspections                     # Run Qodana inspections (requires Docker)
./gradlew rat                                # Run Apache RAT license check

Project Architecture

This is an IntelliJ IDEA Ultimate plugin for Apache Struts 2 framework, providing IDE support for struts.xml configuration, OGNL expressions, validation files, and JSP tag libraries.

Package Structure

  • com.intellij.struts2 - Core Struts 2 plugin functionality
  • com.intellij.lang.ognl - OGNL language support (lexer, parser, highlighting, completion)

Key Architectural Components

DOM Model Layer (com.intellij.struts2.dom)

  • struts/ - Struts XML configuration DOM (actions, results, interceptors, packages)
  • validator/ - Validation XML DOM models
  • params/ - Parameter handling and type conversion
  • DOM converters in impl/ packages handle reference resolution

Framework Integration (com.intellij.struts2.facet)

  • StrutsFacet / StrutsFacetType - Framework facet configuration
  • StrutsFrameworkDetector - Auto-detection of Struts projects
  • StrutsFrameworkInitializer - Modern ProjectActivity-based initialization (replaces deprecated StartupManager)
  • FileSetConfigurationTab - UI for configuring struts.xml file sets

Reference Resolution (com.intellij.struts2.reference)

  • StrutsReferenceContributor - XML reference providers for struts.xml
  • jsp/ - JSP tag library references and action link resolution
  • Reference contributors for various Struts tag libraries (jQuery, Bootstrap, etc.)

OGNL Language (com.intellij.lang.ognl)

  • OgnlLanguage / OgnlFileType - Language definition
  • lexer/ - JFlex-based lexer (ognl.flex)
  • parser/ - Grammar Kit parser (OgnlParser.bnf)
  • psi/ - PSI element types and implementations in impl/
  • highlight/ - Syntax and semantic highlighting
  • completion/ - Code completion providers

Extension Points (defined in plugin.xml)

  • struts2.constantContributor - Add custom Struts constants
  • struts2.resultContributor - Custom result type path resolution
  • struts2.classContributor - Extend class resolution (actions, interceptors)
  • struts2.paramNameCustomConverter - Custom parameter name resolution

Template Engine Integrations

Optional modules loaded via <depends optional="true">:

  • struts2-freemarker.xml - FreeMarker template support
  • struts2-velocity.xml - Velocity template support
  • struts2-spring.xml - Spring integration
  • struts2-groovy.xml - Groovy annotations support

Test Organization

  • src/test/java - Test classes following IntelliJ Platform test patterns
  • src/test/testData - Test fixture files (XML, JSP, Java sources)
  • Test base classes extend IntelliJ Platform's LightJavaCodeInsightFixtureTestCase or similar

Generated Code

  • src/main/gen/ - Generated parser/lexer code (included in source set automatically)
  • Source grammars: src/main/grammar/ognl.bnf (Grammar Kit), _OgnlLexer.flex (JFlex)

IntelliJ Platform Version Mapping

BranchPlatform VersionBuild Range
242.x2024.2242.*
243.x2024.3243.*
251.x2025.1251.*
252.x2025.2252.*
253.x2025.3253.*

Plugin Version Format

{BRANCH}.{BUILD}.{FIX} (e.g., 252.18970.1)

  • BRANCH - IntelliJ Platform branch (252 = 2025.2)
  • BUILD - Automatically calculated in GitHub Actions as 18969 + git rev-list --count HEAD
  • FIX - Patch version (typically 1 for new builds)

The base value 18969 maintains historical continuity from when the plugin was donated by JetBrains to Apache Software Foundation, ensuring version numbers continue from the previous build sequence.

Platform Upgrade Checklist

When upgrading to a new IntelliJ Platform version:

  1. Update gradle.properties:
  • platformVersion - Target platform (e.g., 2025.2)
  • pluginSinceBuild / pluginUntilBuild - Build range (e.g., 251 to 252.*)
  • pluginVersion - Match branch prefix (e.g., 252.x.y)
  1. Check API Compatibility:
  • Review https://jb.gg/intellij-api-changes for breaking changes
  • Run ./gradlew runPluginVerifier to detect issues
  • Common changes: deprecated UI icons, removed internal APIs, changed test framework paths
  1. Update CI/Tooling (if Java version changes):
  • .github/workflows/build.yml - Java version in setup
  • qodana.yml - Linter version and projectJDK
  • build.gradle.kts - jvmToolchain() version
  1. Fix Test Path Issues:
  • IntelliJ Platform test frameworks sometimes change path resolution
  • Override getBasePath() and getTestDataPath() if tests fail to find fixtures
  • Use project-relative paths like "src/test/testData/..."
  1. Update CHANGELOG.md with dependency upgrades

Known Platform Quirks

Test Data Path Resolution: IntelliJ 2024.2+ changed how LexerTestCase and DomStubTest resolve paths. If tests fail with “Cannot find source file”, override path methods to use project-relative paths.

Internal API Usage: Some platform icons and utilities are internal. The plugin verifier will warn about these. Prefer public APIs:

  • Use AllIcons.Nodes.* instead of PlatformIcons
  • Use Charset.availableCharsets() instead of CharsetToolkit.getAvailableCharsets()

JSP Reference Providers: The javaee.web.customServletReferenceProvider extension point behavior changed in 2024.2. Action link references in JSP may need alternative registration approaches.

Temporarily Disabled Tests: Several tests are disabled pending 2025.3 compatibility fixes: OgnlLexerTest, StrutsCompletionTest, StrutsHighlightingSpringTest, StrutsResultResolvingTest, ActionLinkReferenceProviderTest. See CHANGELOG.md for full list - these should be re-enabled when infrastructure issues are resolved.

Claude Guidance

  • Always use https://jb.gg/intellij-api-changes when researching IntelliJ Platform API changes
  • Update CHANGELOG.md when upgrading dependencies: - Dependencies - upgrade <name> to <version>
  • Run ./gradlew test -x rat before committing to catch test regressions
  • Prefer editing existing files over creating new ones
  • When fixing test failures, check if path resolution changed before assuming code bugs