63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
Spring State Machine Explorer is a static analysis tool that extracts and visualizes Spring State Machines from source code. It does **not** run Maven/Gradle on target projects.
|
|
|
|
## Build System
|
|
|
|
- **Java 21** required (toolchain configured in all build.gradle files)
|
|
- **Gradle** build system with shadow plugin for fat JARs
|
|
- Run from root: `./gradlew <task>`
|
|
|
|
## Key Commands
|
|
|
|
### Run the exporter
|
|
```bash
|
|
./gradlew :state_machine_exporter:run --args="-i ./my-project -o ./out -f json"
|
|
```
|
|
|
|
### Run the HTML generator
|
|
```bash
|
|
./gradlew :state_machine_exporter_html:run --args="-i ./my-project -o ./out_html"
|
|
```
|
|
|
|
### Update golden test files
|
|
```bash
|
|
./gradlew :state_machine_exporter:runGolden
|
|
```
|
|
|
|
### Run tests
|
|
```bash
|
|
./gradlew :state_machine_exporter:test
|
|
./gradlew :state_machine_exporter_html:test
|
|
```
|
|
|
|
## Module Structure
|
|
|
|
- **state_machine_exporter**: Core Java AST analyzer (Main class: `click.kamil.springstatemachineexporter.Main`)
|
|
- **state_machine_exporter_html**: HTML portal generator (Main class: `click.kamil.springstatemachineexporter.html.Main`)
|
|
- **state_machine_exporter_spring_based**: Spring-based exporter sample
|
|
- **file_combine**: Utility for concatenating Java files
|
|
- **state_machines/**: Sample state machine projects for testing
|
|
|
|
## Architecture Notes
|
|
|
|
- **Source-first analysis**: Reads source + build metadata (pom.xml, settings.gradle) statically
|
|
- **Accessor inlining**: Enabled by default (O(1) lookup for trivial getters/setters). Disable with `--no-inline-accessors`
|
|
- **Generated sources**: Scans `target/`/`build/` by default. Control with `--include-generated-sources`
|
|
- **Debug mode**: Use `--debug` flag for verbose logging and unresolved chain diagnostics
|
|
- **Spring profiles**: Pass with `-p, --profiles` for property placeholder resolution
|
|
|
|
## Testing
|
|
|
|
- **Golden tests**: JSON/PNG/PUML/DOT/SCXML outputs are compared against golden files in `state_machine_exporter/src/test/resources/golden/`
|
|
- **E2E tests**: Tagged with `@Tag("e2e")` in `PlantUmlE2ETest.java`
|
|
- **Test scenarios**: Defined in `TestScenario.java` record with name, inputPath, goldenPath, baseName, activeProfiles
|
|
|
|
## Important Constraints
|
|
|
|
- **No Maven/Gradle execution**: The tool does not run the target project's build
|
|
- **JDT bindings**: Limited to library types (Spring Boot 3.2.0, Spring State Machine 3.2.0) - external JARs not resolved
|
|
- **Monorepo structure**: All modules in root; state_machines/ contains sample projects
|
|
- **Java 21 only**: All modules require Java 21 toolchain |