rsc-universal 0.1.1

package/skills/spring-boot/references/jpa.md

@@ -0,0 +1,94 @@
+# JPA persistence depth
+
+The SKILL.md covers entities, `JpaRepository`, derived/`@Query`, paging, and the N+1 /
+`LazyInitializationException` headline. This is the depth: relationships, fetch strategy,
+projections, Specifications, optimistic locking, and migrations. Engine-level SQL (index
+design, `EXPLAIN`, partitioning) is `../postgresdb/SKILL.md`'s job — this file stays on the
+JPA/Hibernate layer above it.
+
+## Relationships, cascade, fetch type
+
+- Default `@ManyToOne` is **EAGER**, `@OneToMany`/`@ManyToMany` are **LAZY**. Make
+  `@ManyToOne` lazy explicitly when you don't always need the parent:
+  `@ManyToOne(fetch = FetchType.LAZY)`.
+- Never put `CascadeType.ALL` on a `@ManyToOne` — you'll cascade-delete shared parents. Cascade
+  belongs on the owning side of a true parent/child aggregate (`@OneToMany`).
+- Map the relationship on **one** side and mark the other `mappedBy`. Two owning sides write
+  the join column twice.
+
+```java
+@Entity
+class Order {
+    @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "user_id")
+    private User user;
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<OrderLine> lines = new ArrayList<>();
+}
+```
+
+## N+1 detection and fixes
+
+**Detect.** Turn on SQL logging in a test profile and watch for a query repeated once per
+parent:
+
+```yaml
+logging.level.org.hibernate.SQL: DEBUG
+spring.jpa.properties.hibernate.generate_statistics: true   # logs query counts per session
+```
+
+**Fix, in order of preference:**
+
+1. **`join fetch`** in a `@Query` — best when you always need the association for that path.
+2. **`@EntityGraph`** on the repository method — declarative, reusable, no JPQL.
+   ```java
+   @EntityGraph(attributePaths = {"orders"})
+   Optional<User> findById(Long id);
+   ```
+3. **`@BatchSize(size = 50)`** on the collection/entity — turns N+1 into N/50 IN-queries when
+   you can't fetch-join (e.g. multiple bags).
+
+Do **not** "fix" N+1 by making everything EAGER — that just moves the cost to every query and
+risks cartesian-product blowups when fetch-joining two collections at once.
+
+## Projections — don't fetch what you won't return
+
+- **Interface projection:** declare an interface of getters; Spring builds a proxy selecting
+  only those columns.
+  ```java
+  interface UserSummary { Long getId(); String getName(); }
+  List<UserSummary> findByActiveTrue();
+  ```
+- **DTO/record projection** via constructor expression:
+  `@Query("select new com.acme.UserSummary(u.id, u.name) from User u")`.
+
+Projections sidestep `LazyInitializationException` entirely — there is no lazy proxy to touch.
+
+## Specifications (dynamic queries)
+
+For optional filters, prefer `JpaSpecificationExecutor` over building JPQL strings:
+
+```java
+interface OrderRepository extends JpaRepository<Order, Long>, JpaSpecificationExecutor<Order> {}
+
+Specification<Order> byStatus(Status s) {
+    return (root, q, cb) -> s == null ? null : cb.equal(root.get("status"), s);
+}
+// repo.findAll(byStatus(status).and(byUser(userId)), pageable);
+```
+
+## Optimistic locking
+
+Add a `@Version` field to detect concurrent updates; Hibernate increments it and throws
+`OptimisticLockingFailureException` on a stale write. Cheaper than pessimistic locks for
+low-contention web apps.
+
+```java
+@Version private long version;
+```
+
+## Migrations
+
+Let **Flyway** (`V1__init.sql`, `V2__add_index.sql`) or **Liquibase** own the schema; set
+`spring.jpa.hibernate.ddl-auto=validate` so Hibernate verifies but never mutates the schema.
+Never ship `ddl-auto=update` to production — it makes uncontrolled, unordered changes. The
+actual DDL/index design for those migration files is `../postgresdb/SKILL.md`.

package/skills/spring-boot/references/security.md

@@ -0,0 +1,92 @@
+# Spring Security depth (Security 7)
+
+SKILL.md has the headline: one `SecurityFilterChain` bean, lambda DSL,
+`authorizeHttpRequests` + `requestMatchers`, stateless for token APIs. This is the depth.
+The language-agnostic authz/secret reasoning is `../secure-coding/SKILL.md`; this file is the
+Spring wiring.
+
+## JWT resource server (validate tokens minted elsewhere)
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://issuer.example.com/   # discovers JWKS + validates iss/exp/sig
+```
+
+```java
+@Bean
+SecurityFilterChain api(HttpSecurity http) throws Exception {
+    http
+      .csrf(csrf -> csrf.disable())
+      .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+      .authorizeHttpRequests(auth -> auth
+          .requestMatchers("/actuator/health", "/api/public/**").permitAll()
+          .anyRequest().authenticated())
+      .oauth2ResourceServer(o -> o.jwt(jwt -> jwt.jwtAuthenticationConverter(converter())));
+    return http.build();
+}
+```
+
+Map JWT scopes/claims to authorities with a `JwtAuthenticationConverter` (e.g. a `roles` claim
+-> `ROLE_*`) so `hasRole`/`@PreAuthorize` work against your token's shape.
+
+## OAuth2 client (call protected services on the user's behalf)
+
+`spring-boot-starter-oauth2-client` + `spring.security.oauth2.client.registration.*`. Pair it
+with an `@HttpExchange` client (see SKILL.md) so the access token is attached automatically by
+an `OAuth2ClientHttpRequestInterceptor`/exchange filter — no manual `Authorization` header.
+
+## Method security
+
+`@EnableMethodSecurity` (replaces the old `@EnableGlobalMethodSecurity`) turns on
+`@PreAuthorize`/`@PostAuthorize`:
+
+```java
+@PreAuthorize("hasRole('ADMIN') or #userId == authentication.name")
+UserResponse get(Long userId) { ... }
+```
+
+Use it for row-level / ownership checks the URL matcher can't express. URL matchers guard
+coarse routes; method security guards fine-grained access.
+
+## CORS
+
+Define one `CorsConfigurationSource` bean and reference it from the chain — never echo the
+request `Origin` blindly:
+
+```java
+@Bean CorsConfigurationSource cors() {
+    var c = new CorsConfiguration();
+    c.setAllowedOrigins(List.of("https://app.example.com"));   // explicit allowlist
+    c.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE"));
+    c.setAllowCredentials(true);
+    var src = new UrlBasedCorsConfigurationSource();
+    src.registerCorsConfiguration("/api/**", c);
+    return src;
+}
+// in the chain: .cors(Customizer.withDefaults())
+```
+
+`allowCredentials(true)` with `allowedOrigins("*")` is rejected by the spec — list real origins.
+
+## CSRF posture — the one decision people get wrong
+
+- **Token API, no cookies** (JWT in `Authorization`): CSRF is not exploitable, so
+  `csrf.disable()` is correct. Always leave a comment saying *why* it's disabled.
+- **Cookie/session app** (server-rendered, `JSESSIONID`): keep CSRF **enabled**; use the
+  `CookieCsrfTokenRepository` and send the token from the client. Disabling it here is a real
+  vulnerability.
+
+## Common pitfalls
+
+- **Matcher ordering:** first match wins. A broad `permitAll()` placed before a narrow
+  `hasRole()` opens the narrow route. Order most-specific-first.
+- **Forgetting `STATELESS`:** a "stateless" API that still creates sessions leaks `JSESSIONID`
+  cookies and breaks horizontal scaling.
+- **`permitAll` vs no rule:** `anyRequest().authenticated()` must be the catch-all; an
+  unmatched request with no terminal rule is a misconfiguration.
+- **Encoding passwords with the wrong bean:** use the injected `PasswordEncoder`
+  (`BCryptPasswordEncoder` or `DelegatingPasswordEncoder`), never `MessageDigest`/plain hashes.

package/skills/spring-boot/references/testing.md

@@ -0,0 +1,95 @@
+# Testing depth (JUnit 5 + slices + Testcontainers)
+
+SKILL.md has the slice table, `@MockitoBean`, the `@WebMvcTest` example, and the
+`@ServiceConnection` snippet. This is the depth: when each slice earns its cost, container
+reuse, the modern test clients, `@DataJpaTest` patterns, and a CI gate.
+
+## Slice selection (cost vs coverage)
+
+- **`@WebMvcTest(Foo.class)`** — loads only that controller, Bean Validation, Jackson, and
+  Spring Security. Milliseconds. Supply collaborators with `@MockitoBean`. Use for: status
+  codes, validation errors, JSON shape, auth rules.
+- **`@DataJpaTest`** — loads JPA + a database, wraps each test in a transaction it rolls back.
+  Use for: derived queries, `@Query` correctness, mappings, fetch behavior. Point it at a real
+  Postgres via Testcontainers (below) rather than H2, so dialect differences don't hide bugs.
+- **`@SpringBootTest`** — full context; slowest. Use only for genuine end-to-end paths
+  (controller -> service -> real repo -> DB). Add `webEnvironment = RANDOM_PORT` + `WebTestClient`
+  for real HTTP.
+
+Reach down this list only when the cheaper slice can't express the assertion.
+
+## Mocking — `@MockitoBean`, not `@MockBean`
+
+`@MockBean`/`@SpyBean` are removed in Boot 4. Use `@MockitoBean`/`@MockitoSpyBean` from
+`org.springframework.test.context.bean.override.mockito`. They replace the matching bean in
+the context for that test class.
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mvc;
+    @MockitoBean UserService users;
+
+    @Test void returns201() throws Exception {
+        when(users.create(any())).thenReturn(new UserResponse(1L, "Ada", "ada@x.io"));
+        mvc.perform(post("/api/users").contentType(APPLICATION_JSON)
+                .content("{\"name\":\"Ada\",\"email\":\"ada@x.io\"}"))
+           .andExpect(status().isCreated())
+           .andExpect(header().string("Location", "/api/users/1"));
+    }
+}
+```
+
+`MockMvcTester` (Boot 4, AssertJ-style) is the more fluent alternative to raw `MockMvc` for
+new tests; `WebTestClient` is the choice for real-port `@SpringBootTest`.
+
+## Testcontainers + `@ServiceConnection`
+
+A container `@Bean` annotated `@ServiceConnection` registers its `ConnectionDetails`
+automatically — Spring points the datasource at the container with no `@DynamicPropertySource`.
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+class ContainersConfig {
+    @Bean @ServiceConnection
+    PostgreSQLContainer<?> postgres() { return new PostgreSQLContainer<>("postgres:17"); }
+}
+
+@DataJpaTest
+@Import(ContainersConfig.class)
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)  // use the real container
+class UserRepositoryTest {
+    @Autowired UserRepository repo;
+    @Test void findsByEmail() { /* save + assert */ }
+}
+```
+
+Speed local runs with reuse — survives across test JVMs:
+
+```text
+# ~/.testcontainers.properties
+testcontainers.reuse.enable=true
+```
+
+…and `new PostgreSQLContainer<>("postgres:17").withReuse(true)`. (Reuse is a local convenience;
+CI usually starts fresh containers per run.)
+
+## `@DataJpaTest` patterns
+
+- **Test-data builders** beat hand-built entity graphs: a `users().withEmail(...).build()`
+  helper keeps tests readable and tolerant of new required fields.
+- Use `TestEntityManager` to persist + `flush()` + `clear()` before asserting a query, so you
+  read from the DB, not the first-level cache.
+- Each test rolls back by default — don't assert across tests or rely on insertion order.
+
+## CI gate
+
+Wire the build's test phase plus this skill's static reviewer:
+
+```bash
+./mvnw -q verify          # compile + unit + slice + integration tests (or ./gradlew check)
+./scripts/verify.sh src   # flag legacy Spring idioms (WebSecurityConfigurerAdapter, @MockBean, javax.*, …)
+```
+
+Run real integration tests behind a tag/profile so the fast slices give quick feedback and the
+container-backed tests run on the gate.

package/skills/spring-boot/scripts/verify.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static reviewer for legacy / wrong-generation Spring Boot idioms.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]     # defaults to "."
+#
+# Greps the project's Spring sources (*.java, application*.yml|yaml|properties) for idioms
+# that are removed or discouraged on the Boot 4 / Framework 7 / Security 7 / Jakarta 11
+# generation, and prints each hit with the modern replacement. Read-only: it never edits a
+# file. On a clean tree — or a tree with no Spring sources at all — it prints nothing
+# actionable and exits 0 (no false failure). It exits 1 only when at least one finding is
+# present, so it can double as a non-blocking CI lint signal.
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, no process
+# substitution that trips `set -u`.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+if [ ! -e "$TARGET" ]; then
+  printf '%serror:%s target path %s does not exist.\n' "$RED" "$RESET" "$TARGET" >&2
+  exit 2
+fi
+
+findings=0
+
+# Run a grep over Java sources; print findings with a fix hint. Never fails the script by
+# itself (grep's no-match exit 1 is swallowed); increments the global findings counter.
+scan_java() {
+  pattern="$1"; label="$2"; fix="$3"
+  hits="$(grep -REn --include='*.java' -- "$pattern" "$TARGET" 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    findings=1
+    printf '%s[finding]%s %s -> %s\n' "$YELLOW" "$RESET" "$label" "$fix"
+    printf '%s\n' "$hits" | sed 's/^/    /'
+  fi
+}
+
+scan_config() {
+  pattern="$1"; label="$2"; fix="$3"
+  hits="$(grep -REn --include='application*.yml' --include='application*.yaml' \
+            --include='application*.properties' -- "$pattern" "$TARGET" 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    findings=1
+    printf '%s[finding]%s %s -> %s\n' "$YELLOW" "$RESET" "$label" "$fix"
+    printf '%s\n' "$hits" | sed 's/^/    /'
+  fi
+}
+
+# --- removed / wrong-generation idioms ---
+scan_java 'WebSecurityConfigurerAdapter'        'WebSecurityConfigurerAdapter (removed in Security 6/7)' 'a SecurityFilterChain bean + lambda DSL'
+scan_java '@(MockBean|SpyBean)\b'               '@MockBean / @SpyBean (removed in Boot 4)'               '@MockitoBean / @MockitoSpyBean'
+scan_java '\.(authorizeRequests|antMatchers|mvcMatchers)\s*\(' 'authorizeRequests / antMatchers / mvcMatchers (gone in Security 6/7)' 'authorizeHttpRequests + requestMatchers'
+scan_java 'import[[:space:]]+javax\.persistence' 'javax.persistence import (Jakarta EE 11 baseline)'      'jakarta.persistence.*'
+scan_java 'import[[:space:]]+javax\.validation'  'javax.validation import (Jakarta EE 11 baseline)'       'jakarta.validation.*'
+
+# --- discouraged patterns (heuristic) ---
+# Field @Autowired: an @Autowired line whose payload is not a method/constructor (no '(').
+field_autowired="$(grep -REn --include='*.java' -- '@Autowired' "$TARGET" 2>/dev/null \
+  | grep -Ev '\(' || true)"
+if [ -n "$field_autowired" ]; then
+  findings=1
+  printf '%s[finding]%s field/setter @Autowired (heuristic) -> %s\n' "$YELLOW" "$RESET" 'constructor injection, final fields'
+  printf '%s\n' "$field_autowired" | sed 's/^/    /'
+fi
+
+# @Transactional inside a @RestController source file (tx belongs on the service).
+tx_in_controller=""
+ctrl_files="$(grep -REl --include='*.java' -- '@RestController' "$TARGET" 2>/dev/null || true)"
+if [ -n "$ctrl_files" ]; then
+  # bash 3.2-safe iteration over newline-separated file list
+  OLDIFS="$IFS"; IFS='
+'
+  for f in $ctrl_files; do
+    hit="$(grep -En -- '@Transactional' "$f" 2>/dev/null || true)"
+    if [ -n "$hit" ]; then
+      tx_in_controller="${tx_in_controller}${f}:\n${hit}\n"
+    fi
+  done
+  IFS="$OLDIFS"
+fi
+if [ -n "$tx_in_controller" ]; then
+  findings=1
+  printf '%s[finding]%s @Transactional in a @RestController file -> %s\n' "$YELLOW" "$RESET" 'move @Transactional to the service method'
+  printf '%b' "$tx_in_controller" | sed 's/^/    /'
+fi
+
+# csrf().disable() with no rationale comment on the same line.
+csrf_hits="$(grep -REn --include='*.java' -- 'csrf\s*\(\s*\)\s*\.\s*disable|csrf\(.*disable' "$TARGET" 2>/dev/null || true)"
+if [ -n "$csrf_hits" ]; then
+  csrf_unexplained="$(printf '%s\n' "$csrf_hits" | grep -Ev '//' || true)"
+  if [ -n "$csrf_unexplained" ]; then
+    findings=1
+    printf '%s[finding]%s csrf().disable() with no rationale comment -> %s\n' "$YELLOW" "$RESET" 'disable only for stateless token APIs; add a // comment saying why'
+    printf '%s\n' "$csrf_unexplained" | sed 's/^/    /'
+  fi
+fi
+
+scan_config 'ddl-auto:[[:space:]]*(update|create-drop)' 'hibernate ddl-auto=update/create-drop in config' 'use validate + Flyway/Liquibase migrations'
+
+if [ "$findings" -eq 0 ]; then
+  printf '%s[ ok ]%s no legacy Spring idioms found in %s\n' "$GREEN" "$RESET" "$TARGET"
+  exit 0
+fi
+
+printf '%s[note]%s findings above are advisory; review and migrate to the Boot 4 idioms.\n' "$RED" "$RESET"
+exit 1