This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/struts.git
The following commit(s) were added to refs/heads/main by this push:
new 4cd02529c docs: streamline CLAUDE.md for clarity and conciseness
(#1568)
4cd02529c is described below
commit 4cd02529ca260f6f93bf53aa17b9df5560805525
Author: Lukasz Lenart <[email protected]>
AuthorDate: Wed Feb 4 07:06:29 2026 +0100
docs: streamline CLAUDE.md for clarity and conciseness (#1568)
Simplify the Claude Code guidance document by:
- Condensing verbose descriptions into concise bullet points
- Adding current version info (7.2.0-SNAPSHOT)
- Improving build commands section with more examples
- Reorganizing architecture section for better readability
- Streamlining security patterns section
- Adding clear request lifecycle diagram
- Consolidating available tools into organized sections
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <[email protected]>
---
CLAUDE.md | 223 +++++++++++++++++++++++++-------------------------------------
1 file changed, 88 insertions(+), 135 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index a536f59d0..1cb6922da 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,188 +2,141 @@
This file provides guidance to Claude Code (claude.ai/code) when working with
code in this repository.
-This document outlines essential practices for working with Claude Code on the
Apache Struts project. For detailed
-procedures, use the specialized agents and commands available in
`.claude/agents/` and `.claude/commands/`.
+For detailed procedures, use the specialized agents and commands in
`.claude/agents/` and `.claude/commands/`.
## Project Overview
-Apache Struts is a mature MVC web application framework for Java, originally
based on WebWork 2. The project follows a
-modular architecture with clear separation between core framework, plugins,
and applications.
+Apache Struts is a mature MVC web application framework for Java (originally
WebWork 2). Current version: *
+*7.2.0-SNAPSHOT**.
-### Build System & Environment
-
-- **Build Tool**: Maven with multi-module structure
-- **Java Version**: Java 17+
-- **Testing**: JUnit 5 with AssertJ assertions
-- **IDE Support**: IntelliJ IDEA with project-specific configurations
-
-### Key Build Commands
+### Build Commands
```bash
# Full build with tests
mvn clean install
-# Run tests
+# Run all tests (faster, skips assembly)
mvn test -DskipAssembly
-# Build without running tests
+# Run single test class
+mvn test -DskipAssembly -Dtest=MyClassTest
+
+# Run single test method
+mvn test -DskipAssembly -Dtest=MyClassTest#testMethodName
+
+# Run tests in a specific module
+mvn test -DskipAssembly -pl core
+
+# Build without tests
mvn clean install -DskipTests
+
+# Build with code coverage (JaCoCo)
+mvn clean install -Pcoverage
+
+# Build with Jakarta EE 11 (Spring 7)
+mvn clean install -Pjakartaee11
+
+# Run OWASP dependency vulnerability check
+mvn verify -Pdependency-check
```
### Project Structure
```
struts/
-├── core/ # Core framework (struts2-core)
-├── plugins/ # Plugin modules (tiles, json, etc.)
-├── apps/ # Sample applications (showcase, rest-showcase)
-├── assembly/ # Distribution packaging
-├── bom/ # Bill of Materials for dependency management
-├── parent/ # Parent POM with shared configuration
-└── jakarta/ # Jakarta EE compatibility modules
+├── core/ # struts2-core - main framework
+├── plugins/ # Plugin modules (json, rest, spring, tiles, velocity,
etc.)
+├── apps/ # Sample applications (showcase, rest-showcase)
+├── assembly/ # Distribution packaging
+├── bom/ # Bill of Materials for dependency management
+├── parent/ # Parent POM with shared configuration
+└── jakarta/ # Jakarta EE compatibility modules
```
-### Core Architecture Components
-
-#### MVC Framework Components
+### Core Architecture
-- **ActionSupport**: Base class for actions with validation and
internationalization
-- **ActionContext**: Thread-local context holding request/response data
-- **ActionProxy/ActionInvocation**: Handles action execution lifecycle
-- **Dispatcher**: Core request dispatcher and framework initialization
-- **Interceptors**: Cross-cutting concerns (validation, file upload, security)
+**Request Lifecycle**: `Dispatcher` → `ActionProxy` → `ActionInvocation` →
Interceptor stack → `Action` → Result
-#### Key Packages
+Key components:
-- `org.apache.struts2.dispatcher`: Request handling and context management
-- `org.apache.struts2.interceptor`: Interceptor implementations
-- `org.apache.struts2.components`: UI component system
-- `org.apache.struts2.views`: View technologies (JSP, FreeMarker, Velocity)
-- `org.apache.struts2.security`: Security-related utilities
+- **ActionSupport**: Base class for actions (validation, i18n, messages)
+- **ActionContext**: Thread-local context with request/response/session data
+- **Interceptors**: Cross-cutting concerns (validation, file upload, security,
params)
+- **Results**: Response handlers (dispatcher, redirect, json, stream)
-### Technology Stack
+Key packages in `org.apache.struts2`:
-- **Jakarta EE**: Servlet API, JSP, JSTL
-- **Core Libraries**: OGNL (expression language), Commons FileUpload2, Log4j2
-- **Template Engines**: FreeMarker, Velocity (via plugins)
-- **Build Dependencies**: Maven, various plugins for assembly and site
generation
+- `dispatcher` - Request handling, `Dispatcher`, servlet integration
+- `interceptor` - Built-in interceptors (params, validation, fileUpload)
+- `components` - UI tag components (form, textfield, submit)
+- `action` - Action interfaces (`UploadedFilesAware`, `SessionAware`, etc.)
+- `security` - Security utilities and OGNL member access policies
-## Security-First Development
+### Technology Stack
-### Critical Security Principles
+- **Java 17+** with Jakarta EE 10 (Servlet 6.0, JSP 3.1)
+- **OGNL** - Expression language for value stack access
+- **FreeMarker** - Default template engine for UI tags
+- **Commons FileUpload2** - File upload handling
+- **Log4j2/SLF4J** - Logging
-1. **Never create files in system temp directories** - always use controlled
application directories
-2. **Use UUID-based naming** for temporary files to prevent collisions and
path traversal
-3. **Implement proper resource cleanup** with try-with-resources and finally
blocks
-4. **Track all temporary resources** for explicit cleanup (security critical)
-5. **Validate all user inputs** and sanitize filenames before processing
+## Security-Critical Patterns
-**For comprehensive security analysis, use:** `/security_scan`
+Apache Struts has a history of security vulnerabilities. Follow these strictly:
-### Security Implementation Patterns
+1. **Temporary files**: Never use system temp directory; use UUID-based names
in controlled locations
+2. **OGNL expressions**: Never evaluate user-controlled OGNL; use allowlist
member access
+3. **File uploads**: Validate content types, sanitize filenames, enforce size
limits
+4. **Parameter injection**: Use `ParameterNameAware` to filter dangerous
parameter names
```java
-// GOOD: Secure temporary file creation
+// Secure temporary file pattern
protected File createTemporaryFile(String fileName, Path location) {
String uid = UUID.randomUUID().toString().replace("-", "_");
- File file = location.resolve("upload_" + uid + ".tmp").toFile();
- LOG.debug("Creating temporary file: {} (originally: {})", file.getName(),
fileName);
- return file;
+ return location.resolve("upload_" + uid + ".tmp").toFile();
}
```
-## Testing Implementation
-
-### Intelligent Test Execution Approach
-
-When running tests, use this priority order:
+Run `/security_scan` for comprehensive security analysis.
-1. **JetBrains MCP** (when available in IntelliJ IDEA):
- - Use `mcp__jetbrains__execute_run_configuration` for specific test
configurations
- - First check if configuration exists with `get_run_configurations`
+## Testing
-2. **test-runner agent** (primary method):
- - Use Task tool with `subagent_type="test-runner"` for comprehensive test
execution
- - Provides intelligent test analysis and coverage reports
+**Priority order for running tests:**
-3. **Direct Maven** (fallback):
- - Use only when explicitly requested or for simple verification
- - Command: `mvn test -DskipAssembly`
+1. **JetBrains MCP** (in IntelliJ): `mcp__jetbrains__execute_run_configuration`
+2. **test-runner agent**: `Task` tool with `subagent_type="test-runner"`
+3. **Direct Maven**: `mvn test -DskipAssembly -Dtest=TestClassName`
-### Test Structure & Coverage
+Tests use JUnit 5 with AssertJ assertions and Mockito for mocking.
-- **Unit Tests**: Test individual methods with mocked dependencies
-- **Integration Tests**: Test complete workflows with real file I/O
-- **Security Tests**: Verify directory traversal prevention, secure naming
-- **Error Handling Tests**: Test exception scenarios and error reporting
-- **Cleanup Tests**: Verify resource cleanup and tracking
+## Available Tools
-## Documentation Standards
-
-**For comprehensive documentation quality analysis, use:** `/quality_check`
-
-### Documentation Requirements
-
-- **Always document security implications** in methods handling files/user
input
-- **Include usage examples** for complex methods and classes
-- **Document exception conditions** and error handling behavior
-- **Reference related methods** using `@see` tags
-- **Explain resource management** responsibilities
-
-## Error Handling & Logging
-
-### Logging Best Practices
-
-- Use parameterized logging for performance: `LOG.debug("Processing: {}",
value)`
-- Log security-relevant operations appropriately
-- Use appropriate log levels (debug/info/warn/error)
-- Avoid logging sensitive information
-
-## Code Quality Standards
-
-**For comprehensive code quality analysis, use:** `/quality_check`
+### Commands
-### Key Principles
+- `/security_scan` - OGNL injection, CVE detection, security analysis
+- `/quality_check` - JavaDoc compliance, coding standards
+- `/config_analyze` - struts.xml validation, interceptor analysis
+- `/create_plan` / `/validate_plan` - Implementation planning
+- `/research_codebase` - Codebase exploration
-- Use `protected` for methods that subclasses might override
-- Catch specific exceptions rather than generic `Exception`
-- Use clear, descriptive method and variable names
-- Follow existing project conventions and patterns
+### Specialized Agents
-## Available Automated Tools
+- `test-runner` - Maven test execution (use this to RUN tests)
+- `security-analyzer` - Security vulnerability scanning
+- `codebase-locator` - Find files, classes, implementations
+- `codebase-pattern-finder` - Find similar code patterns
+- `config-validator` - Validate Struts configuration files
-### Commands
+## Pull Requests
-- `/security_scan` - Comprehensive security analysis
-- `/quality_check` - Code quality and documentation analysis
-- `/config_analyze` - Configuration validation and optimization
-- `/create_plan` - Implementation planning assistance
-- `/validate_plan` - Plan validation and verification
-- `/commit` - Guided git commit creation
-- `/research_codebase` - Comprehensive codebase research
+- **Title format**: `WW-XXXX Description` (Jira ticket ID required)
+- **Link ticket in description**: `Fixes
[WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
+- **Issue tracker**: https://issues.apache.org/jira/projects/WW
-### Specialized Agents
+## Common Pitfalls
-- `security-analyzer` - OGNL injection scanning, CVE detection
-- `test-runner` - Maven test execution and coverage analysis, use this agent
to RUN the tests
-- `code-quality-checker` - JavaDoc compliance, pattern consistency
-- `config-validator` - struts.xml validation, interceptor analysis
-- `codebase-analyzer` - Project structure and architecture analysis
-- `codebase-locator` - Code and file location assistance
-- `codebase-pattern-finder` - Pattern examples and usage
-
-## Pull Request Guidelines
-
-- **PR title must start with Jira ticket ID** (e.g., `WW-5588 Allow Preparable
interface...`)
-- **PR description must link to the ticket** using GitHub keywords:
- - `Closes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
- - `Fixes [WW-XXXX](https://issues.apache.org/jira/browse/WW-XXXX)`
-
-## Common Pitfalls to Avoid
-
-1. **File Security**: Never use `File.createTempFile()` without directory
control
-2. **Resource Leaks**: Always track and clean up temporary files
-3. **Test Coverage**: Don't forget to test error conditions and cleanup
-4. **Documentation**: Always document security implications
-5. **Exception Handling**: Don't let cleanup failures affect main operations
-6. **Path Validation**: Always validate and sanitize file paths
\ No newline at end of file
+1. Never use `File.createTempFile()` without controlling the directory
+2. Always clean up temporary files (track and delete in finally blocks)
+3. Test error paths and cleanup behavior, not just happy paths
+4. Don't catch generic `Exception` - catch specific types
+5. Use `protected` visibility for methods subclasses may override
\ No newline at end of file
