Apache/struts
1
0
Fork 0
mirror of https://github.com/apache/struts.git synced 2026-08-05 14:47:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: streamline CLAUDE.md for clarity and conciseness (#1568)

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Lukasz Lenart
2026-02-04 07:06:29 +01:00
committed by GitHub
parent 22b0fa9f12
commit 4cd02529ca
1 changed files with 86 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+86 -133
View File
@@ -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
### Core Architecture
#### MVC Framework Components
**Request Lifecycle**: `Dispatcher` → `ActionProxy` → `ActionInvocation` → Interceptor stack → `Action` → Result
- **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)
Key components:
#### Key Packages
- **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)
- `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
Key packages in `org.apache.struts2`:
- `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
### Technology Stack
- **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
- **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
## Security-First Development
## Security-Critical Patterns
### Critical Security Principles
Apache Struts has a history of security vulnerabilities. Follow these strictly:
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
**For comprehensive security analysis, use:** `/security_scan`
### 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
Run `/security_scan` for comprehensive security analysis.
### Intelligent Test Execution Approach
## Testing
When running tests, use this priority order:
**Priority order for running tests:**
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`
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`
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
Tests use JUnit 5 with AssertJ assertions and Mockito for mocking.
3. **Direct Maven** (fallback):
- Use only when explicitly requested or for simple verification
- Command: `mvn test -DskipAssembly`
### Test Structure & Coverage
- **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
## 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`
### Key Principles
- 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
## Available Automated Tools
## Available Tools
### Commands
- `/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
- `/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
### Specialized Agents
- `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
- `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
## Pull Request Guidelines
## Pull Requests
- **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)`
- **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
## Common Pitfalls to Avoid
## Common Pitfalls
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
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