@coralai/sps-cli 0.42.0 → 0.44.0

package/skills/java/references/concurrency.md

@@ -0,0 +1,194 @@
+# Java — Concurrency
+
+Virtual threads (21+), `ExecutorService`, `CompletableFuture`, structured concurrency.
+
+## Virtual threads — Java 21+
+
+Cheap threads mapped many-to-one onto OS threads. For I/O-bound work, replace platform-thread pools.
+
+```java
+// One virtual thread per request — simple, no thread-pool sizing
+var executor = Executors.newVirtualThreadPerTaskExecutor();
+executor.submit(() -> handle(req));
+
+// Or inline:
+Thread.startVirtualThread(() -> handle(req));
+```
+
+Virtual threads block cheaply. A thread per request becomes a reasonable model. `Thread.sleep`, blocking I/O (JDBC, filesystem), locks — all yield the carrier thread rather than burning it.
+
+When NOT to use virtual threads:
+- CPU-bound work (thousands of virtual threads running compute just migrate between OS threads; no gain).
+- Code heavy on `synchronized` blocks (pinning problem — before Java 24 the carrier is locked; better in 24+).
+- Legacy reactive code where migration is a separate project.
+
+## Platform threads — `ExecutorService`
+
+For CPU-bound work or when you need explicit thread-pool sizing.
+
+```java
+try (var exec = Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors())) {
+    var futures = items.stream()
+        .map(i -> exec.submit(() -> compute(i)))
+        .toList();
+    for (var f : futures) results.add(f.get());
+}
+```
+
+`try-with-resources` on `ExecutorService` (Java 19+) shuts it down cleanly.
+
+Sizing:
+- CPU-bound: `n = cores` or `cores + 1`.
+- Mixed: `n = cores × (1 + wait/compute ratio)`.
+- If you can't estimate, virtual threads take the question away.
+
+## `CompletableFuture` — composable async
+
+```java
+CompletableFuture<User> userF  = fetchUser(id);
+CompletableFuture<Prefs> prefsF = fetchPrefs(id);
+
+CompletableFuture<Screen> result = userF.thenCombine(prefsF, Screen::new);
+
+result.thenAccept(screen -> render(screen))
+      .exceptionally(err -> { log.error(err); return null; });
+```
+
+`supplyAsync`, `thenApply`, `thenCompose`, `thenCombine`, `allOf`, `anyOf`, `exceptionally` — the basic toolkit.
+
+**Always** provide an explicit `Executor`:
+
+```java
+CompletableFuture.supplyAsync(this::load, executor)
+```
+
+Default is `ForkJoinPool.commonPool()` — OK for CPU-bound, wrong for I/O. Named executors are clearer and tune-able.
+
+Rules:
+- `.get()` blocks; use `.join()` in lambdas if you must.
+- Don't mix async chains with blocking calls; stay reactive all the way or don't bother.
+- With virtual threads, plain imperative code is usually preferable to `CompletableFuture` chains.
+
+## Structured concurrency (preview → stable)
+
+```java
+try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
+    Subtask<User>  userT  = scope.fork(() -> fetchUser(id));
+    Subtask<Prefs> prefsT = scope.fork(() -> fetchPrefs(id));
+
+    scope.join().throwIfFailed();
+    return new Screen(userT.get(), prefsT.get());
+}
+```
+
+Ties child tasks' lifecycle to the enclosing scope. Compiler / runtime ensures all children finish (or are cancelled) before the scope exits. Pairs nicely with virtual threads.
+
+Check your JDK version — this API has been in preview; use the stable namespace (available in 25 LTS+).
+
+## Locks
+
+| Use | Tool |
+|---|---|
+| Short critical section | `synchronized` block |
+| Read-heavy | `ReadWriteLock` / `StampedLock` |
+| Atomic counter / flag | `java.util.concurrent.atomic.*` |
+| One-time init | `volatile` + double-checked init, or `Holder` class pattern |
+
+```java
+private final Object lock = new Object();
+private int counter;
+
+void inc() {
+    synchronized (lock) { counter++; }
+}
+```
+
+Prefer `AtomicInteger` / `AtomicReference` over mutex + primitive for simple cases.
+
+`Lock` interface (`ReentrantLock`) for tryLock, timeouts, fairness. Don't reach for it unless you need one of those.
+
+## Concurrent collections
+
+| Type | Use |
+|---|---|
+| `ConcurrentHashMap<K,V>` | Thread-safe map; scales to many cores |
+| `CopyOnWriteArrayList<T>` | Mostly read, rarely written; snapshots |
+| `BlockingQueue<T>` (`LinkedBlockingQueue`, etc.) | Producer / consumer |
+| `ConcurrentLinkedQueue<T>` | Unbounded lock-free queue |
+
+Don't wrap a regular `HashMap` in `Collections.synchronizedMap` and call it concurrent — it serializes every operation.
+
+## `volatile`
+
+Publishes writes to other threads. Does NOT make compound operations atomic.
+
+```java
+private volatile boolean running = true;
+// other thread can see running = false without extra sync
+```
+
+Don't use `volatile` for counters. Use `AtomicInteger` / `AtomicLong` — `i++` is not atomic on `volatile int`.
+
+## `ThreadLocal`
+
+Per-thread storage. With platform threads + thread pools, a `ThreadLocal` can leak across requests because threads are reused. Use `try` / `finally` to clean up, or switch to `ScopedValue` (Java 21+).
+
+```java
+private static final ScopedValue<User> CURRENT_USER = ScopedValue.newInstance();
+
+ScopedValue.where(CURRENT_USER, user).run(() -> {
+    // CURRENT_USER.get() is user for the duration of this block
+});
+```
+
+`ScopedValue` is immutable, bound by lexical scope, plays well with virtual threads.
+
+## Avoid blocking in async frameworks
+
+If you're on Reactor / RxJava / Mutiny (Quarkus), a blocking call on an event loop stalls the whole world. Mark blocking operations for a different scheduler:
+
+```java
+Mono.fromCallable(this::blockingThing).subscribeOn(Schedulers.boundedElastic());
+```
+
+Or move to virtual threads and stop needing reactive at all.
+
+## Shutdown hooks
+
+```java
+Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+    exec.shutdown();
+    try { exec.awaitTermination(30, TimeUnit.SECONDS); } catch (Exception ignored) {}
+    db.close();
+}));
+```
+
+Web frameworks do most of this for you. In plain-Java apps, do it explicitly.
+
+## Timeouts
+
+Every network / DB call has a timeout. Defaults are usually "infinite" or "very long".
+
+```java
+// HttpClient
+var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(3)).build();
+var req    = HttpRequest.newBuilder(uri).timeout(Duration.ofSeconds(5)).GET().build();
+
+// JDBC
+statement.setQueryTimeout(5);
+```
+
+See `backend/references/resilience.md` for the full budget model.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `Thread.sleep` in request handlers | Use scheduled executors; or `VirtualThread.sleep` if truly needed |
+| `new Thread(...).start()` for each task | Use an `ExecutorService` |
+| `synchronized` across I/O calls | Hold locks briefly; never across network |
+| Catching `InterruptedException` and discarding | `Thread.currentThread().interrupt()` before returning, or rethrow |
+| `CompletableFuture` chains without an explicit executor | Always specify |
+| `.get()` without timeout | `.get(timeout, unit)` or restructure async |
+| Mutable shared state without synchronization | Lock it, use concurrent collections, or use an actor-ish pattern |
+| `Future.cancel(true)` assumed to stop blocking I/O | Cancel interrupts; blocking calls may not honour it |

package/skills/java/references/idioms.md

@@ -0,0 +1,283 @@
+# Java — Idioms
+
+Records, sealed types, streams, `Optional`, modern collections.
+
+## Records — data classes done right
+
+```java
+public record User(String id, String email, boolean active) {}
+
+var u = new User("u1", "a@x.com", true);
+u.email();                 // accessor
+new User("u1", "a@x.com", false).equals(u);   // false — structural equality
+```
+
+Records give you `equals`, `hashCode`, `toString`, and component accessors for free.
+
+Compact canonical constructor for validation:
+
+```java
+public record Email(String value) {
+    public Email {
+        if (!value.contains("@")) throw new IllegalArgumentException("bad email");
+    }
+}
+```
+
+Don't use records when you need mutation, inheritance, or behaviour beyond data + validation.
+
+## Sealed types + pattern switch
+
+Model sum types exhaustively.
+
+```java
+public sealed interface Result<T>
+    permits Result.Ok, Result.Err {
+    record Ok<T>(T value)      implements Result<T> {}
+    record Err<T>(String error) implements Result<T> {}
+}
+
+String handle(Result<User> r) {
+    return switch (r) {
+        case Result.Ok(var u)      -> "got " + u.email();
+        case Result.Err(var msg)   -> "fail " + msg;
+    };                   // no default — compiler enforces exhaustiveness
+}
+```
+
+`permits` limits implementers to the named classes. Add a new variant → every `switch` breaks until updated.
+
+## `var` — locals only
+
+```java
+var users = userRepo.findAll();           // List<User>
+var map   = new HashMap<String, List<Order>>();
+```
+
+Don't use `var` in method signatures, field declarations, or where the inferred type would surprise a reader.
+
+```java
+// ❌ — what is x?
+var x = svc.doThing();
+
+// ✅ keep the type when not obvious
+List<User> users = svc.loadUsers();
+```
+
+## `Optional<T>`
+
+For **return values** that might legitimately be absent.
+
+```java
+Optional<User> findById(String id) { ... }
+
+findById(id)
+    .map(User::email)
+    .orElseThrow(() -> new NotFoundException("no user " + id));
+```
+
+Never:
+- `Optional` as a field type (serialization headache, mutable wrapper)
+- `Optional` as a method parameter (overloads are clearer)
+- `Optional.get()` without `isPresent()` (same bug as `unwrap`)
+
+## Collections
+
+```java
+List<String> immutable = List.of("a", "b", "c");
+Map<String, Integer> m = Map.of("a", 1, "b", 2);
+Set<String> s         = Set.of("x", "y");
+
+var mutable = new ArrayList<String>();
+mutable.add("a");
+
+var copy = List.copyOf(mutable);           // defensive copy, unmodifiable
+```
+
+Prefer `List.of` / `Map.of` for small known data. Prefer `ArrayList` / `HashMap` for mutable.
+
+## Streams
+
+Concise collection transformations.
+
+```java
+var emails = users.stream()
+    .filter(User::active)
+    .map(User::email)
+    .toList();
+
+var byRole = users.stream()
+    .collect(Collectors.groupingBy(User::role));
+
+var count = users.stream().filter(User::active).count();
+```
+
+Rules:
+- `toList()` (Java 16+) over `collect(Collectors.toList())`.
+- Don't use streams for simple for-loops with side effects — the loop is clearer.
+- Don't mix stream and `forEach` for state mutation; prefer `collect` / `reduce`.
+
+Stream of a single op doesn't improve readability:
+
+```java
+// ❌
+list.stream().filter(p).findFirst().orElse(null);
+
+// ✅
+list.stream().filter(p).findFirst().orElseThrow();
+// or use a library method if it exists
+```
+
+## `switch` expressions
+
+```java
+String label = switch (status) {
+    case ACTIVE   -> "active";
+    case PENDING  -> "pending";
+    case BANNED   -> "banned";
+};
+
+// Pattern matching (preview/stable depending on JDK)
+var description = switch (shape) {
+    case Circle c    -> "circle r=" + c.radius();
+    case Square s    -> "square s=" + s.side();
+    case null, default -> "unknown";
+};
+```
+
+Arrow `->` form has no fall-through. Traditional `case X:` has fall-through — avoid.
+
+## Exceptions
+
+- **Checked** (`extends Exception`) — recoverable, documented in signature.
+- **Unchecked** (`extends RuntimeException`) — programmer errors, boundary validation.
+
+```java
+public class ValidationException extends RuntimeException {
+    private final String field;
+    public ValidationException(String field, String msg) {
+        super(msg);
+        this.field = field;
+    }
+    public String field() { return field; }
+}
+```
+
+Chain the cause:
+
+```java
+try { ... }
+catch (IOException e) {
+    throw new ConfigException("loading " + path, e);    // ← pass e as cause
+}
+```
+
+Never catch `Throwable` / `Exception` and swallow. Catch specifics, log, handle or rethrow.
+
+## `final` — for invariants
+
+- On class: no subclasses.
+- On method: can't override.
+- On field: immutable reference.
+- On local / param: can't reassign (noisy; `var` encourages it implicitly).
+
+Records' components are implicitly final.
+
+Don't sprinkle `final` on every local — IDEs and modern reviewers treat it as clutter unless the team convention says otherwise.
+
+## Nullability
+
+Java doesn't have built-in non-null types. Options:
+
+- **`@Nullable` / `@NonNull`** from JSR-305, JetBrains, or Checker Framework.
+- **Records + `@NotNull` in canonical constructor validation.**
+- **Kotlin interop** — declare nullability to help Kotlin callers.
+
+Pick one annotation set; configure your IDE + CI to enforce it.
+
+## `java.time.*` — not `Date`
+
+```java
+var now     = Instant.now();
+var today   = LocalDate.now();
+var inZone  = ZonedDateTime.now(ZoneId.of("Asia/Tokyo"));
+var later   = now.plus(Duration.ofMinutes(30));
+
+Instant.parse("2026-04-21T10:00:00Z");
+DateTimeFormatter.ofPattern("yyyy-MM-dd").format(today);
+```
+
+`java.util.Date` and `Calendar` are deprecated in spirit; every use is a code smell in new code.
+
+## Equality
+
+- `equals()` for value equality; `==` for reference equality.
+- `record` gets `equals` automatically.
+- For classes, use IDE / Lombok / `EqualsBuilder` — never hand-write `equals` without `hashCode` to match.
+
+```java
+Objects.equals(a, b);                  // null-safe
+Objects.hash(field1, field2);
+```
+
+## String
+
+```java
+String s = "hi";
+String formatted = "user %s (%d)".formatted(name, count);     // Java 15+
+String multiline = """
+    Hello
+    %s
+    """.formatted(name);                                        // text blocks (15+)
+
+var sb = new StringBuilder();          // for building in loops
+```
+
+`String.format` for static strings is fine. `"...".formatted(...)` reads better.
+
+`String.repeat(n)`, `String.strip()` (vs `trim()` which is ASCII-only) are modern.
+
+## Lambdas vs. method references
+
+```java
+users.stream().map(u -> u.email());         // lambda
+users.stream().map(User::email);             // method ref — preferred when trivial
+
+users.stream().filter(u -> u.active());
+users.stream().filter(User::active);
+
+// Constructor reference
+users.stream().map(name -> new User(name)).toList();
+users.stream().map(User::new).toList();
+```
+
+Method references when the operation is a direct member access. Lambdas when there's any extra logic.
+
+## Builder pattern
+
+For types with many optional fields, use a builder. Lombok provides `@Builder`; libraries like Immutables generate it.
+
+```java
+var req = HttpRequest.builder()
+    .url("https://x.com")
+    .timeout(Duration.ofSeconds(5))
+    .header("X-Auth", token)
+    .build();
+```
+
+For records, a static factory + named params via builder is common.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `public` mutable fields | Getters or records |
+| `if (x == null) throw new NullPointerException(...)` everywhere | Non-null annotations + validate at boundary |
+| `instanceof x + cast` chains | Pattern switch / sealed types |
+| Anonymous inner class for a SAM | Lambda |
+| `Collections.unmodifiableList(new ArrayList<>(...))` | `List.copyOf(...)` |
+| Hand-rolled `equals` / `hashCode` on data classes | Record or generated code |
+| Catching `Exception e` to "simplify" | Catch specific; let unknown propagate |
+| `System.out.println` in production | Use SLF4J / `java.util.logging` |
+| `Thread.currentThread().sleep(...)` | `Thread.sleep(...)` — static method; use as such |
+| `new Integer(x)` / `new String(x)` | Use valueOf / literal |

package/skills/java/references/testing.md

@@ -0,0 +1,228 @@
+# Java — Testing
+
+JUnit 5, AssertJ, Mockito, Testcontainers. For TDD, see `coding-standards/references/tdd.md`.
+
+## JUnit 5 — the default
+
+```java
+import org.junit.jupiter.api.*;
+import static org.junit.jupiter.api.Assertions.*;
+
+class UserServiceTest {
+    private UserService service;
+
+    @BeforeEach
+    void setUp() { service = new UserService(new InMemoryUserRepo()); }
+
+    @Test
+    @DisplayName("creates a user with a generated id")
+    void create_returnsPersistedUser() {
+        var u = service.create("A", "a@x.com");
+        assertEquals("A", u.name());
+        assertNotNull(u.id());
+    }
+
+    @Test
+    void create_rejectsEmptyEmail() {
+        assertThrows(ValidationException.class, () -> service.create("A", ""));
+    }
+}
+```
+
+Use `@DisplayName` for behaviour-focused names that don't fit Java method-name rules.
+
+## AssertJ — fluent assertions
+
+```java
+import static org.assertj.core.api.Assertions.*;
+
+assertThat(users)
+    .hasSize(3)
+    .extracting(User::email)
+    .contains("a@x.com")
+    .doesNotContain("banned@x.com");
+
+assertThat(user.role()).isEqualTo(Role.ADMIN);
+
+assertThatThrownBy(() -> service.create("A", ""))
+    .isInstanceOf(ValidationException.class)
+    .hasMessageContaining("email");
+```
+
+Much richer than JUnit's built-ins. Most Java codebases use AssertJ or Hamcrest. Pick one per project.
+
+## Mockito — when you need mocks
+
+Fakes > mocks (see `coding-standards` / `typescript`/`python` refs). But Mockito works when a fake is too heavy.
+
+```java
+import static org.mockito.Mockito.*;
+
+@Test
+void loadsFromRepo() {
+    var repo = mock(UserRepository.class);
+    when(repo.find("u1")).thenReturn(Optional.of(new User("u1", "a@x.com")));
+
+    var service = new UserService(repo);
+    assertEquals("a@x.com", service.getEmail("u1"));
+
+    verify(repo, times(1)).find("u1");
+}
+```
+
+`@Mock` + `@InjectMocks` for less boilerplate; enable with `@ExtendWith(MockitoExtension.class)`.
+
+Don't mock types you own — change them instead. Mock boundaries (HTTP clients, clocks, external APIs).
+
+## Parametrized tests
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "1, 2, 3",
+    "0, 0, 0",
+    "-1, 1, 0",
+})
+void add(int a, int b, int expected) {
+    assertEquals(expected, Math.addExact(a, b));
+}
+
+@ParameterizedTest
+@EnumSource(Role.class)
+void allRolesHaveLabel(Role r) {
+    assertNotNull(r.label());
+}
+
+@ParameterizedTest
+@MethodSource("loginCases")
+void login(LoginCase c) { ... }
+static Stream<LoginCase> loginCases() { ... }
+```
+
+## Lifecycle annotations
+
+| Annotation | Runs |
+|---|---|
+| `@BeforeEach` | Before each `@Test` |
+| `@AfterEach` | After each `@Test` |
+| `@BeforeAll` | Once before any test (static) |
+| `@AfterAll` | Once after all tests (static) |
+| `@Nested` class | Group related tests, fresh fixtures |
+
+`@TestInstance(Lifecycle.PER_CLASS)` if you want non-static `@BeforeAll` or shared state.
+
+## `@Nested` for readability
+
+```java
+@Nested
+@DisplayName("when user is banned")
+class WhenBanned {
+    @BeforeEach void setUp() { user = userWithStatus(BANNED); }
+
+    @Test void cannotLogin() { ... }
+    @Test void cannotPost()  { ... }
+}
+```
+
+Reads as a spec. Tests stay organized without helper functions exploding the file.
+
+## Integration tests — Testcontainers
+
+Real dependencies, Docker-driven, ephemeral.
+
+```java
+@Testcontainers
+class UserRepoIT {
+    @Container
+    static final PostgreSQLContainer<?> PG =
+        new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @Test
+    void savesAndLoads() throws Exception {
+        var ds = dataSource(PG.getJdbcUrl(), PG.getUsername(), PG.getPassword());
+        var repo = new JdbcUserRepository(ds);
+        repo.save(new User("u1", "a@x.com"));
+        assertThat(repo.find("u1")).isPresent();
+    }
+}
+```
+
+Split integration tests (`*IT.java`) from unit tests (`*Test.java`) in the build so you don't run them every time.
+
+## Spring Boot tests
+
+Layered:
+
+```java
+@WebMvcTest(UserController.class)          // only web layer + @MockBean repo
+class UserControllerTest { ... }
+
+@DataJpaTest                                // only JPA + embedded DB
+class UserRepoTest { ... }
+
+@SpringBootTest                             // full app context
+class UserIntegrationTest { ... }
+```
+
+Prefer `@WebMvcTest` / `@DataJpaTest` over `@SpringBootTest` — they load a slice, are much faster.
+
+`@TestContainers` + `@SpringBootTest` for real-DB integration tests on the production stack.
+
+## Async tests
+
+```java
+@Test
+void futureCompletes() throws Exception {
+    var f = asyncService.load(id);
+    assertEquals("a@x.com", f.get(5, TimeUnit.SECONDS).email());
+}
+```
+
+For streams/flows, use Awaitility:
+
+```java
+import static org.awaitility.Awaitility.await;
+
+await().atMost(5, SECONDS).until(() -> queue.size() > 0);
+```
+
+## Property tests — jqwik
+
+```java
+@Property
+boolean sortIsIdempotent(@ForAll List<@IntRange(min = -1000, max = 1000) Integer> xs) {
+    var sorted = xs.stream().sorted().toList();
+    var twice  = sorted.stream().sorted().toList();
+    return sorted.equals(twice);
+}
+```
+
+Niche but valuable for parsers, invariants.
+
+## Coverage
+
+JaCoCo is the default. Set a threshold in Maven / Gradle and fail CI on drop.
+
+```xml
+<!-- Maven: jacoco-maven-plugin -->
+<rule>
+  <element>BUNDLE</element>
+  <limits>
+    <limit><counter>LINE</counter><minimum>0.80</minimum></limit>
+  </limits>
+</rule>
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `Thread.sleep` to wait for async | Awaitility / explicit futures |
+| `@Test(expected = ...)` (JUnit 4) | JUnit 5: `assertThrows` |
+| Mocking what you don't own without wrapping | Create a wrapper type; mock the wrapper |
+| Tests that load full Spring context for a pure-logic test | `@WebMvcTest` / plain JUnit |
+| Mockito `any()` for every arg | Assert specific args — catches bugs |
+| Mocking final classes without Mockito inline extension | Enable `mockito-inline` or refactor to an interface |
+| Shared mutable static state across tests | `@BeforeEach` reset or move state into instance |
+| Snapshot / text asserts for time-dependent output | Inject a clock |
+| Tests named `test1`, `test2` | Describe behaviour — `create_rejectsEmptyEmail` |