trueref/CODE_STYLE.md

# trueref — Code Style

## 1. Language & Toolchain
- **Java 21**, source/target 21.
- **Maven** with `spring-boot-maven-plugin` for the fat JAR.
- **Spotless** with **Palantir Java Format** for formatting (4-space indent, 120 col).
- **ErrorProne** + **NullAway** for static analysis. NullAway annotations: `@org.jspecify.annotations.Nullable` / `@NonNull`.
- Hexagonal boundaries are enforced by **Maven module dependencies** (no ArchUnit). See ARCHITECTURE §3.

## 2. Records, Sealed Types, Pattern Matching
- Prefer **records** for DTOs, value objects, and `port.in`/`port.out` parameter/result types.
- Use **sealed interfaces** for closed result/event hierarchies (`sealed interface IngestionEvent permits ...`).
- Use **pattern matching** (`switch` expressions, `instanceof`) over visitor pattern.

## 3. Nullability & Optional
- All API surfaces (public methods on ports, REST DTOs) are **non-null by default**; mark nullable explicitly with `@Nullable`.
- Use `Optional<T>` **only** as a return type from query-style methods. Never as a field, never as a parameter.

## 4. Concurrency
- Spawn virtual threads via `Thread.ofVirtual().start(...)` or `Executors.newVirtualThreadPerTaskExecutor()`. **Never** call `Thread.sleep` inside a synchronized block.
- Shared mutable state is forbidden in `domain` and discouraged in `application`. When unavoidable, use `java.util.concurrent.atomic.*` or a `ReentrantLock`.
- GPU work goes through `GpuSemaphore.acquire()` (a thin wrapper around `Semaphore`).
- Long-running orchestration uses **structured concurrency** (`StructuredTaskScope`) where it improves cancellation safety.

## 5. Error Handling
- **Domain errors** are sealed exception hierarchies rooted at `TrueRefException`. Adapters translate them to HTTP/JSON-RPC errors centrally (REST: `@ControllerAdvice`; MCP: dedicated translator).
- **No checked exceptions** at port boundaries. Wrap third-party checked exceptions at the adapter edge.
- Validation errors carry a stable `code` (string) so the UI can localize.
- Never `catch (Exception e)` and swallow. Either log + rethrow as a domain exception or let it propagate.

## 6. Logging
- **SLF4J** with parameterized messages: `log.info("indexed tag {} of repo {}", tag, repoName);` — never string-concatenate.
- Structured fields via MDC: `repoId`, `versionId`, `jobId`, `stage`. Cleared in a try/finally.
- Log levels:
  - `ERROR`: unrecoverable, requires operator attention.
  - `WARN`: degraded, automatic recovery in progress.
  - `INFO`: lifecycle events (job started/finished, repo registered).
  - `DEBUG`: per-file, per-chunk detail. Off by default.

## 7. Naming
- Use cases (`port.in`): imperative verb phrases — `IndexVersion`, `ResolveLibraryId`.
- SPIs (`port.out`): noun-ish role names — `EmbeddingService`, `ChunkStore`, `GitClient`.
- Adapter classes: `<Tech><Role>` — `LuceneChunkStore`, `OnnxEmbeddingService`, `JGitClient`.
- DTOs: `<Resource><Action>Request` / `<Resource>Response`.
- Records' field names are camelCase (no Hungarian, no `_` prefixes).

## 8. Package & File Discipline
- One public type per file.
- Internal helpers are package-private. Avoid `public` unless used across packages.
- Domain packages export **only** records and interfaces. No Spring annotations, no Lombok, no Jackson annotations.
- Adapter packages may use Spring stereotypes (`@Component`, `@Repository`, `@RestController`) but adapters depend on **port interfaces only** when interacting with the application.

## 9. Spring Wiring
- Wiring lives in `bootstrap`. Each adapter package may define a `@Configuration` (constructor-injected `@Bean` factories) but **does not** auto-`@ComponentScan` itself; bootstrap explicitly imports.
- Use `@ConfigurationProperties` records for typed config; never raw `@Value`.
- Prefer constructor injection. **No field injection.**

## 10. Persistence (H2)
- Migrations under `src/main/resources/db/migration` named `V<N>__<snake_case>.sql`. Flyway runs at startup.
- All access via Spring **`JdbcClient`** (Spring Boot 3.2+, fluent JDBC). **No JPA/Hibernate**, no `JdbcTemplate` directly.
- Mappers are explicit `RowMapper<T>` lambdas, not reflection-based.
- SQL lives next to the repository class, either as `static final String` constants or in `*.sql` files loaded via `ClassPathResource` for non-trivial queries.

## 11. REST
- Controllers in `adapter.in.rest`. They depend only on `port.in` interfaces and DTO records.
- DTOs are **separate** from domain records. Mapping via plain `static of(...)` factories. **No MapStruct.**
- All endpoints documented with `@Operation`, `@ApiResponses`, `@Schema` (springdoc).
- Request validation via `jakarta.validation` annotations on DTOs.
- SSE endpoints return `SseEmitter`; subscribe to `JobEventBus`, unsubscribe on completion/timeout.

## 12. MCP
- Tool definitions are **records** decorated to produce JSON Schema via Spring AI's MCP support. Schema strings stay verbatim (1:1 with Context7) so LLMs see identical contracts.
- Tool handlers depend only on `port.in` (`SearchLibraryDocs`, `ResolveLibraryId`).

## 13. Tests
- **JUnit 5** + **AssertJ** + **Mockito** (sparingly).
- Unit tests live next to the package they test. Integration tests under `src/test/java/.../it/` and use `@SpringBootTest`.
- Use **Testcontainers** only when truly required (we mostly avoid it via embedded stores).
- ArchUnit test suite is mandatory and runs in CI.

## 14. Dependency Hygiene
- BOM-managed versions only. Add a dependency only if it provides clear value over JDK + Spring Boot + already-included libs.
- No Lombok, no Guava (use JDK 21 equivalents), no Reactor (we use virtual threads + blocking).
- No Kotlin, no Scala.

## 15. Documentation
- All architectural decisions go in **ARCHITECTURE.md**.
- All research notes go in **FINDINGS.md** with sources.
- All conventions go in **this file**.
- Per-package `package-info.java` may exist for non-trivial packages, summarizing role and exported types.
- No README sprawl: `README.md` is a quickstart only and links to the three docs above.