# 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