184 lines
6.4 KiB
Markdown
184 lines
6.4 KiB
Markdown
# AGENTS.md - Development Guide for WSON
|
|
|
|
## Build & Test Commands
|
|
|
|
### Gradle Tasks
|
|
```bash
|
|
./gradlew build # Build and test all modules
|
|
./gradlew test # Run all tests
|
|
./gradlew test --tests "<pattern>" # Run specific tests (e.g., "*.JSONTest")
|
|
./gradlew check # Run all verification tasks
|
|
./gradlew clean # Clean build outputs
|
|
./gradlew jacocoTestReport # Generate code coverage report
|
|
```
|
|
|
|
### Module-Specific Commands
|
|
```bash
|
|
./gradlew :wson-cli:envelopeJar # Create executable JAR
|
|
./gradlew :wson-cli:nativeImage # Build GraalVM native image
|
|
./gradlew :benchmark:jmh # Run JMH benchmarks
|
|
./gradlew :antlr:generateGrammarSource # Generate ANTLR parsers
|
|
./gradlew :wcfg:generateGrammarSource # Generate WCFG parsers
|
|
./gradlew javadoc # Generate API documentation
|
|
./gradlew sourcesJar # Build sources JAR
|
|
./gradlew publish # Publish to Maven repository
|
|
```
|
|
|
|
### Running a Single Test
|
|
```bash
|
|
./gradlew test --tests "net.woggioni.wson.serialization.binary.JBONTest"
|
|
./gradlew test --tests "*.JSONTest" # By class name
|
|
./gradlew test --tests "net.woggioni.wson.*" # By package
|
|
./gradlew test --tests "*Test.consistencyTest" # By method name
|
|
./gradlew :wson-cli:test --tests "CliTest" # Module-specific
|
|
```
|
|
|
|
### Test Options
|
|
```bash
|
|
./gradlew test --fail-fast # Stop after first failure
|
|
./gradlew test --rerun # Force re-run even if up-to-date
|
|
./gradlew test --info # Show detailed test output
|
|
```
|
|
|
|
## Project Structure
|
|
- `src/main/java/net/woggioni/wson/` - Main library code
|
|
- `src/test/java/net/woggioni/wson/` - Test code
|
|
- `test-utils/` - Shared test utilities (e.g., JsonBomb for DoS testing)
|
|
- `antlr/` - ANTLR-based JSON parser implementation
|
|
- `wson-cli/` - CLI with GraalVM native image support
|
|
- `wcfg/` - Configuration file parser (ANTLR-based)
|
|
- `benchmark/` - JMH benchmarks
|
|
- `wson-w3c-json/` - Jakarta JSON-P provider
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Java Version & Toolchain
|
|
- **Target**: Java 25 (GraalVM)
|
|
- **Release**: Java 17 compatibility
|
|
- **Module System**: JPMS enabled (`module-info.java`)
|
|
|
|
### Imports Organization
|
|
```java
|
|
// 1. Lombok annotations (if used)
|
|
import lombok.Builder;
|
|
import lombok.EqualsAndHashCode;
|
|
|
|
// 2. Project imports (net.woggioni.wson)
|
|
import net.woggioni.wson.exception.TypeException;
|
|
import net.woggioni.wson.value.NullValue;
|
|
|
|
// 3. Standard Java imports (java.*, org.*, com.*)
|
|
import java.util.Map;
|
|
import java.util.ArrayList;
|
|
```
|
|
|
|
### Naming Conventions
|
|
- **Packages**: `net.woggioni.wson.<function>` (e.g., `value`, `serialization`, `traversal`, `exception`, `xface`)
|
|
- **Interfaces**: Descriptive names (`Value`, `Parser`, `Dumper`, `ValueVisitor`)
|
|
- **Implementations**: `<Format><Role>` pattern (`JSONParser`, `JBONDumper`, `JSONDumper`)
|
|
- **Value types**: `<Type>Value` pattern (`StringValue`, `IntegerValue`, `ObjectValue`)
|
|
- **Exceptions**: `<Name>Exception` extending `WsonException`
|
|
- **Tests**: `<ClassName>Test.java` in parallel test directory structure
|
|
|
|
### Formatting
|
|
- **Indentation**: 4 spaces
|
|
- **Braces**: K&R style (opening brace on same line)
|
|
- **Line length**: ~120 characters
|
|
- **Blank lines**: Separate logical blocks between methods and classes
|
|
|
|
### Lombok Usage
|
|
Heavy use of Lombok for reducing boilerplate:
|
|
- `@EqualsAndHashCode` - Value objects
|
|
- `@NoArgsConstructor` / `@AllArgsConstructor` - Constructors
|
|
- `@Getter` - Simple getters
|
|
- `@Builder` - Configuration classes and builders
|
|
- `@Slf4j` - Logging
|
|
- `@SneakyThrows` - Test code only (avoid in production)
|
|
- `@NonNull` - Null-safety annotations
|
|
- `@RequiredArgsConstructor` - Constructor injection
|
|
|
|
### Error Handling
|
|
All exceptions extend `WsonException` (RuntimeException):
|
|
```java
|
|
// Exception hierarchy
|
|
WsonException (base)
|
|
├── ParseException (includes line/column info)
|
|
├── TypeException (type conversion errors)
|
|
├── IOException (I/O errors)
|
|
├── NotImplementedException (unreachable code)
|
|
└── MaxDepthExceededException (DoS protection)
|
|
```
|
|
|
|
Pattern for parser errors (include position info):
|
|
```java
|
|
private <T extends RuntimeException> T error(Function<String, T> constructor,
|
|
String fmt, Object... args) {
|
|
return constructor.apply(String.format(
|
|
"Error at line %d column %d: %s",
|
|
currentLine, currentColumn, String.format(fmt, args)));
|
|
}
|
|
```
|
|
|
|
### Design Patterns
|
|
- **Interface/Implementation**: Define contracts in `xface` package, multiple implementations
|
|
- **Factory methods**: Configuration-driven instantiation
|
|
- **Visitor pattern**: `ValueVisitor` for tree traversal
|
|
- **Builder pattern**: `Value.Configuration` with Lombok `@Builder`
|
|
|
|
### Testing Patterns
|
|
- Use JUnit 5 (`org.junit.jupiter.api.*`)
|
|
- `@TempDir` for temporary test files
|
|
- Try-with-resources for streams
|
|
- Common tests: `consistencyTest` (round-trip), `comparativeTest` (vs Jackson)
|
|
- Test resources in `src/test/resources/`
|
|
|
|
### Logging
|
|
- Use SLF4J via Lombok `@Slf4j`
|
|
- Logging framework: slf4j-simple (test/runtime)
|
|
|
|
## Module System (JPMS)
|
|
Exports from `module-info.java`:
|
|
```java
|
|
module net.woggioni.wson {
|
|
requires static lombok;
|
|
requires net.woggioni.jwo;
|
|
|
|
exports net.woggioni.wson.xface;
|
|
exports net.woggioni.wson.value;
|
|
exports net.woggioni.wson.exception;
|
|
exports net.woggioni.wson.serialization;
|
|
exports net.woggioni.wson.serialization.json;
|
|
exports net.woggioni.wson.serialization.binary;
|
|
exports net.woggioni.wson.traversal;
|
|
}
|
|
```
|
|
|
|
## CI/CD (Jenkins)
|
|
Pipeline stages:
|
|
1. `./gradlew build` - Build and test
|
|
2. Archive JUnit results: `**/build/test-results/test/*.xml`
|
|
3. Generate JaCoCo coverage report
|
|
4. Archive Javadoc and JAR artifacts
|
|
5. `./gradlew publish` - Deploy to Gitea Maven repository
|
|
|
|
## Versioning
|
|
- Scheme: `YYYY.MM.DD` (e.g., `2026.03.12`)
|
|
- Configured in `gradle.properties`: `wson.version`
|
|
- Dependency catalog: `lys-catalog:2026.02.19`
|
|
|
|
## Environment Setup
|
|
```properties
|
|
# gradle.properties
|
|
org.gradle.caching=true
|
|
wson.version = 2026.03.12
|
|
lys.version = 2026.02.19
|
|
gitea.maven.url = https://gitea.woggioni.net/api/packages/woggioni/maven
|
|
```
|
|
|
|
## Build Notes
|
|
- GraalVM 25 required for native image builds
|
|
- Java 17 release compatibility for produced artifacts
|
|
- Gradle 9.4.0+
|
|
- Use `--warning-mode all` to see deprecation notices
|
|
- Configuration cache can be enabled for faster builds
|