This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch docs/streamline-claude-md in repository https://gitbox.apache.org/repos/asf/struts.git
commit 116b4e8f058e1bec34f539da38164093b4f911df Author: Lukasz Lenart <[email protected]> AuthorDate: Wed Feb 4 07:02:25 2026 +0100 docs: streamline CLAUDE.md for clarity and conciseness 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
