diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b12310b5..612c8627 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ { "name": "ecc", "source": "./", - "description": "The most comprehensive Claude Code plugin — 56 agents, 209 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning", + "description": "The most comprehensive Claude Code plugin — 56 agents, 213 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning", "version": "2.0.0-rc.1", "author": { "name": "Affaan Mustafa", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f946782d..7969aca0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ecc", "version": "2.0.0-rc.1", - "description": "Battle-tested Claude Code plugin for engineering teams — 56 agents, 209 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use", + "description": "Battle-tested Claude Code plugin for engineering teams — 56 agents, 213 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use", "author": { "name": "Affaan Mustafa", "url": "https://x.com/affaanmustafa" diff --git a/AGENTS.md b/AGENTS.md index a2c7b638..196c3f90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — Agent Instructions -This is a **production-ready AI coding plugin** providing 56 specialized agents, 209 skills, 72 commands, and automated hook workflows for software development. +This is a **production-ready AI coding plugin** providing 56 specialized agents, 213 skills, 72 commands, and automated hook workflows for software development. **Version:** 2.0.0-rc.1 @@ -148,7 +148,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat ``` agents/ — 56 specialized subagents -skills/ — 209 workflow skills and domain knowledge +skills/ — 213 workflow skills and domain knowledge commands/ — 72 slash commands hooks/ — Trigger-based automations rules/ — Always-follow guidelines (common + per-language) diff --git a/README.md b/README.md index 36a65a82..cf6bc714 100644 --- a/README.md +++ b/README.md @@ -358,7 +358,7 @@ If you stacked methods, clean up in this order: /plugin list ecc@ecc ``` -**That's it!** You now have access to 56 agents, 209 skills, and 72 legacy command shims. +**That's it!** You now have access to 56 agents, 213 skills, and 72 legacy command shims. ### Dashboard GUI @@ -526,6 +526,10 @@ everything-claude-code/ | |-- springboot-security/ # Spring Boot security (NEW) | |-- springboot-tdd/ # Spring Boot TDD (NEW) | |-- springboot-verification/ # Spring Boot verification (NEW) +| |-- quarkus-patterns/ # Quarkus REST, Panache, and messaging patterns (NEW) +| |-- quarkus-security/ # Quarkus JWT/OIDC and RBAC security (NEW) +| |-- quarkus-tdd/ # Quarkus testing with JUnit, REST Assured, and Dev Services (NEW) +| |-- quarkus-verification/ # Quarkus build, test, security, and native verification (NEW) | |-- configure-ecc/ # Interactive installation wizard (NEW) | |-- security-scan/ # AgentShield security auditor integration (NEW) | |-- java-coding-standards/ # Java coding standards (NEW) @@ -1358,7 +1362,7 @@ The configuration is automatically detected from `.opencode/opencode.json`. |---------|-------------|----------|--------| | Agents | PASS: 56 agents | PASS: 12 agents | **Claude Code leads** | | Commands | PASS: 72 commands | PASS: 35 commands | **Claude Code leads** | -| Skills | PASS: 209 skills | PASS: 37 skills | **Claude Code leads** | +| Skills | PASS: 213 skills | PASS: 37 skills | **Claude Code leads** | | Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** | | Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** | | MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** | @@ -1463,7 +1467,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e |---------|------------|------------|-----------|----------| | **Agents** | 56 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | | **Commands** | 72 | Shared | Instruction-based | 35 | -| **Skills** | 209 | Shared | 10 (native format) | 37 | +| **Skills** | 213 | Shared | 10 (native format) | 37 | | **Hook Events** | 8 types | 15 types | None yet | 11 types | | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | | **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | diff --git a/README.zh-CN.md b/README.zh-CN.md index 14e6f013..0504057a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/" /plugin list ecc@ecc ``` -**完成！** 你现在可以使用 56 个代理、209 个技能和 72 个命令。 +**完成！** 你现在可以使用 56 个代理、213 个技能和 72 个命令。 ### multi-* 命令需要额外配置 diff --git a/agent.yaml b/agent.yaml index 53c35b17..a21c3391 100644 --- a/agent.yaml +++ b/agent.yaml @@ -113,6 +113,10 @@ skills: - python-testing - pytorch-patterns - quality-nonconformance + - quarkus-patterns + - quarkus-security + - quarkus-tdd + - quarkus-verification - ralphinho-rfc-pipeline - regex-vs-llm-structured-text - repo-scan diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md index 44a10ec5..9f3f4895 100644 --- a/docs/zh-CN/AGENTS.md +++ b/docs/zh-CN/AGENTS.md @@ -1,6 +1,6 @@ # Everything Claude Code (ECC) — 智能体指令 -这是一个**生产就绪的 AI 编码插件**，提供 56 个专业代理、209 项技能、72 条命令以及自动化钩子工作流，用于软件开发。 +这是一个**生产就绪的 AI 编码插件**，提供 56 个专业代理、213 项技能、72 条命令以及自动化钩子工作流，用于软件开发。 **版本:** 2.0.0-rc.1 @@ -147,7 +147,7 @@ ``` agents/ — 56 个专业子代理 -skills/ — 209 个工作流技能和领域知识 +skills/ — 213 个工作流技能和领域知识 commands/ — 72 个斜杠命令 hooks/ — 基于触发的自动化 rules/ — 始终遵循的指导方针（通用 + 每种语言） diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md index 4df8718f..61cb39e1 100644 --- a/docs/zh-CN/README.md +++ b/docs/zh-CN/README.md @@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/" /plugin list ecc@ecc ``` -**搞定！** 你现在可以使用 56 个智能体、209 项技能和 72 个命令了。 +**搞定！** 你现在可以使用 56 个智能体、213 项技能和 72 个命令了。 *** @@ -1134,7 +1134,7 @@ opencode |---------|-------------|----------|--------| | 智能体 | PASS: 56 个 | PASS: 12 个 | **Claude Code 领先** | | 命令 | PASS: 72 个 | PASS: 35 个 | **Claude Code 领先** | -| 技能 | PASS: 209 项 | PASS: 37 项 | **Claude Code 领先** | +| 技能 | PASS: 213 项 | PASS: 37 项 | **Claude Code 领先** | | 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多！** | | 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** | | MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** | @@ -1242,7 +1242,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以 |---------|------------|------------|-----------|----------| | **智能体** | 56 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 | | **命令** | 72 | 共享 | 基于指令 | 35 | -| **技能** | 209 | 共享 | 10 (原生格式) | 37 | +| **技能** | 213 | 共享 | 10 (原生格式) | 37 | | **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 | | **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 | | **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 | diff --git a/manifests/install-components.json b/manifests/install-components.json index 28c107f6..9076882b 100644 --- a/manifests/install-components.json +++ b/manifests/install-components.json @@ -121,6 +121,15 @@ "framework-language" ] }, + { + "id": "framework:quarkus", + "family": "framework", + "description": "Quarkus-focused engineering guidance for REST, Panache, security, testing, and verification.", + "modules": [ + "framework-language", + "security" + ] + }, { "id": "capability:database", "family": "capability", diff --git a/manifests/install-modules.json b/manifests/install-modules.json index 6c37b063..627a27ef 100644 --- a/manifests/install-modules.json +++ b/manifests/install-modules.json @@ -157,6 +157,9 @@ "skills/perl-testing", "skills/python-patterns", "skills/python-testing", + "skills/quarkus-patterns", + "skills/quarkus-tdd", + "skills/quarkus-verification", "skills/rust-patterns", "skills/rust-testing", "skills/springboot-patterns", @@ -267,6 +270,7 @@ "skills/llm-trading-agent-security", "skills/nodejs-keccak256", "skills/perl-security", + "skills/quarkus-security", "skills/security-review", "skills/security-scan", "skills/security-bounty-hunter", diff --git a/package.json b/package.json index 7960dd3b..7f4aff76 100644 --- a/package.json +++ b/package.json @@ -215,6 +215,10 @@ "skills/python-patterns/", "skills/python-testing/", "skills/quality-nonconformance/", + "skills/quarkus-patterns/", + "skills/quarkus-security/", + "skills/quarkus-tdd/", + "skills/quarkus-verification/", "skills/ralphinho-rfc-pipeline/", "skills/regex-vs-llm-structured-text/", "skills/remotion-video-creation/", diff --git a/rules/java/patterns.md b/rules/java/patterns.md index 570282bd..44ed3f2f 100644 --- a/rules/java/patterns.md +++ b/rules/java/patterns.md @@ -143,4 +143,5 @@ public record ApiResponse(boolean success, T data, String error) { ## References See skill: `springboot-patterns` for Spring Boot architecture patterns. +See skill: `quarkus-patterns` for Quarkus architecture patterns with REST, Panache, and messaging. See skill: `jpa-patterns` for entity design and query optimization. diff --git a/rules/java/security.md b/rules/java/security.md index 31ca61b6..cbedc120 100644 --- a/rules/java/security.md +++ b/rules/java/security.md @@ -97,4 +97,5 @@ try { ## References See skill: `springboot-security` for Spring Security authentication and authorization patterns. +See skill: `quarkus-security` for Quarkus security with JWT/OIDC, RBAC, and CDI. See skill: `security-review` for general security checklists. diff --git a/rules/java/testing.md b/rules/java/testing.md index aa2e91f3..177b264a 100644 --- a/rules/java/testing.md +++ b/rules/java/testing.md @@ -112,6 +112,7 @@ class OrderRepositoryIT { ``` For Spring Boot integration tests, see skill: `springboot-tdd`. +For Quarkus integration tests, see skill: `quarkus-tdd`. ## Test Naming @@ -128,4 +129,5 @@ Use descriptive names with `@DisplayName`: ## References See skill: `springboot-tdd` for Spring Boot TDD patterns with MockMvc and Testcontainers. +See skill: `quarkus-tdd` for Quarkus TDD patterns with REST Assured and Dev Services. See skill: `java-coding-standards` for testing expectations. diff --git a/skills/quarkus-patterns/SKILL.md b/skills/quarkus-patterns/SKILL.md new file mode 100644 index 00000000..3de2cc71 --- /dev/null +++ b/skills/quarkus-patterns/SKILL.md @@ -0,0 +1,722 @@ +--- +name: quarkus-patterns +description: Quarkus 3.x LTS architecture patterns with Camel for messaging, RESTful API design, CDI services, data access with Panache, and async processing. Use for Java Quarkus backend work with event-driven architectures. +origin: ECC +--- + +# Quarkus Development Patterns + +Quarkus 3.x architecture and API patterns for cloud-native, event-driven services with Apache Camel. + +## When to Activate + +- Building REST APIs with JAX-RS or RESTEasy Reactive +- Structuring resource → service → repository layers +- Implementing event-driven patterns with Apache Camel and RabbitMQ +- Configuring Hibernate Panache, caching, or reactive streams +- Adding validation, exception mapping, or pagination +- Setting up profiles for dev/staging/production environments (YAML config) +- Custom logging with LogContext and Logback/Logstash encoder +- Working with CompletableFuture for async operations +- Implementing conditional flow processing +- Working with GraalVM native compilation + +## Service Layer with Multiple Dependencies + +```java +@Slf4j +@ApplicationScoped +@RequiredArgsConstructor +public class OrderProcessingService { + + private final OrderValidator orderValidator; + private final EventService eventService; + private final OrderRepository orderRepository; + private final FulfillmentPublisher fulfillmentPublisher; + private final AuditPublisher auditPublisher; + + @Transactional + public OrderReceipt process(CreateOrderCommand command) { + ValidationResult validation = orderValidator.validate(command); + if (!validation.valid()) { + eventService.createErrorEvent(command, "ORDER_REJECTED", validation.message()); + throw new WebApplicationException(validation.message(), Response.Status.BAD_REQUEST); + } + + Order order = Order.from(command); + orderRepository.persist(order); + + OrderReceipt receipt = OrderReceipt.from(order); + fulfillmentPublisher.publishAsync(receipt); + auditPublisher.publish("ORDER_ACCEPTED", receipt); + eventService.createSuccessEvent(receipt, "ORDER_ACCEPTED"); + + log.info("Processed order {}", order.id); + return receipt; + } +} +``` + +**Key Patterns:** +- `@RequiredArgsConstructor` for constructor injection via Lombok +- `@Slf4j` for Logback logging +- `@Transactional` on service methods that write through Panache or repositories +- Validate input before persistence or message publication +- Event tracking for success/error scenarios +- Async Camel message publishing + +## Custom Logging Context Pattern (Logback) + +```java +@ApplicationScoped +public class ProcessingService { + + public void processDocument(Document doc) { + LogContext logContext = CustomLog.getCurrentContext(); + try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) { + // Add context to all log statements + logContext.put("documentId", doc.getId().toString()); + logContext.put("documentType", doc.getType()); + logContext.put("userId", SecurityContext.getUserId()); + + log.info("Starting document processing"); + + // All logs within this scope inherit the context + processInternal(doc); + + log.info("Document processing completed"); + } catch (Exception e) { + log.error("Document processing failed", e); + throw e; + } + } +} +``` + +**Logback Configuration (logback.xml):** + +```xml + + + + true + true + + + + + + + + +``` + +## Event Service Pattern + +```java +@Slf4j +@ApplicationScoped +@RequiredArgsConstructor +public class EventService { + private final EventRepository eventRepository; + private final ObjectMapper objectMapper; + + public void createSuccessEvent(Object payload, String eventType) { + Objects.requireNonNull(payload, "Payload cannot be null"); + Event event = new Event(); + event.setType(eventType); + event.setStatus(EventStatus.SUCCESS); + event.setPayload(serializePayload(payload)); + event.setTimestamp(Instant.now()); + + eventRepository.persist(event); + log.info("Success event created: {}", eventType); + } + + public void createErrorEvent(Object payload, String eventType, String errorMessage) { + Objects.requireNonNull(payload, "Payload cannot be null"); + if (errorMessage == null || errorMessage.isBlank()) { + throw new IllegalArgumentException("Error message cannot be blank"); + } + Event event = new Event(); + event.setType(eventType); + event.setStatus(EventStatus.ERROR); + event.setErrorMessage(errorMessage); + event.setPayload(serializePayload(payload)); + event.setTimestamp(Instant.now()); + + eventRepository.persist(event); + log.error("Error event created: {} - {}", eventType, errorMessage); + } + + private String serializePayload(Object payload) { + try { + return objectMapper.writeValueAsString(payload); + } catch (JsonProcessingException e) { + throw new IllegalStateException("Failed to serialize event payload", e); + } + } +} +``` + +## Camel Message Publishing (RabbitMQ) + +```java +@Slf4j +@ApplicationScoped +@RequiredArgsConstructor +public class BusinessRulesPublisher { + private final ProducerTemplate producerTemplate; + + public void publishSync(BusinessRulesPayload payload) { + producerTemplate.sendBody( + "direct:business-rules-publisher", + payload + ); + } +} +``` + +**Camel Route Configuration:** + +```java +@ApplicationScoped +public class BusinessRulesRoute extends RouteBuilder { + + @ConfigProperty(name = "camel.rabbitmq.queue.business-rules") + String businessRulesQueue; + + @ConfigProperty(name = "rabbitmq.host") + String rabbitHost; + + @ConfigProperty(name = "rabbitmq.port") + Integer rabbitPort; + + @Override + public void configure() { + from("direct:business-rules-publisher") + .routeId("business-rules-publisher") + .log("Publishing message to RabbitMQ: ${body}") + .marshal().json(JsonLibrary.Jackson) + .toF("spring-rabbitmq:%s?hostname=%s&portNumber=%d", + businessRulesQueue, rabbitHost, rabbitPort); + } +} +``` + +## Camel Direct Routes (In-Memory) + +```java +@ApplicationScoped +public class DocumentProcessingRoute extends RouteBuilder { + + @Override + public void configure() { + // Error handling + onException(ValidationException.class) + .handled(true) + .to("direct:validation-error-handler") + .log("Validation error: ${exception.message}"); + + // Main processing route + from("direct:process-document") + .routeId("document-processing") + .log("Processing document: ${header.documentId}") + .bean(DocumentValidator.class, "validate") + .bean(DocumentTransformer.class, "transform") + .choice() + .when(header("documentType").isEqualTo("INVOICE")) + .to("direct:process-invoice") + .when(header("documentType").isEqualTo("CREDIT_NOTE")) + .to("direct:process-credit-note") + .otherwise() + .to("direct:process-generic") + .end(); + + from("direct:validation-error-handler") + .bean(EventService.class, "createErrorEvent") + .log("Validation error handled"); + } +} +``` + +## Camel File Processing + +```java +@ApplicationScoped +public class FileMonitoringRoute extends RouteBuilder { + + @ConfigProperty(name = "file.input.directory") + String inputDirectory; + + @ConfigProperty(name = "file.processed.directory") + String processedDirectory; + + @ConfigProperty(name = "file.error.directory") + String errorDirectory; + + @Override + public void configure() { + from("file:" + inputDirectory + "?move=" + processedDirectory + + "&moveFailed=" + errorDirectory + "&delay=5000") + .routeId("file-monitor") + .log("Processing file: ${header.CamelFileName}") + .to("direct:process-file"); + + from("direct:process-file") + .bean(OrderProcessingService.class, "processFile") + .log("File processing completed"); + } +} +``` + +## Camel Bean Invocation + +```java +@ApplicationScoped +public class InvoiceRoute extends RouteBuilder { + + @Override + public void configure() { + from("direct:invoice-validation") + .bean(InvoiceFlowValidator.class, "validateFlowWithConfig") + .log("Validation result: ${body}"); + + from("direct:persist-and-publish") + .bean(DocumentJobService.class, "createDocumentAndJobEntities") + .bean(BusinessRulesPublisher.class, "publishAsync") + .bean(EventService.class, "createSuccessEvent(${body}, 'PUBLISHED')"); + } +} +``` + +## REST API Structure + +```java +@Path("/api/documents") +@Produces(MediaType.APPLICATION_JSON) +@Consumes(MediaType.APPLICATION_JSON) +@RequiredArgsConstructor +public class DocumentResource { + private final DocumentService documentService; + + @GET + public Response list( + @QueryParam("page") @DefaultValue("0") int page, + @QueryParam("size") @DefaultValue("20") int size) { + List documents = documentService.list(page, size); + return Response.ok(documents).build(); + } + + @POST + public Response create(@Valid CreateDocumentRequest request, @Context UriInfo uriInfo) { + Document document = documentService.create(request); + URI location = uriInfo.getAbsolutePathBuilder() + .path(String.valueOf(document.id)) + .build(); + return Response.created(location).entity(DocumentResponse.from(document)).build(); + } + + @GET + @Path("/{id}") + public Response getById(@PathParam("id") Long id) { + return documentService.findById(id) + .map(DocumentResponse::from) + .map(Response::ok) + .orElse(Response.status(Response.Status.NOT_FOUND)) + .build(); + } +} +``` + +## Repository Pattern (Panache Repository) + +```java +@ApplicationScoped +public class DocumentRepository implements PanacheRepository { + + public List findByStatus(DocumentStatus status, int page, int size) { + return find("status = ?1 order by createdAt desc", status) + .page(page, size) + .list(); + } + + public Optional findByReferenceNumber(String referenceNumber) { + return find("referenceNumber", referenceNumber).firstResultOptional(); + } + + public long countByStatusAndDate(DocumentStatus status, LocalDate date) { + return count("status = ?1 and createdAt >= ?2", status, date.atStartOfDay()); + } +} +``` + +## Service Layer with Transactions + +```java +@ApplicationScoped +@RequiredArgsConstructor +public class DocumentService { + private final DocumentRepository repo; + private final EventService eventService; + + @Transactional + public Document create(CreateDocumentRequest request) { + Document document = new Document(); + document.setReferenceNumber(request.referenceNumber()); + document.setDescription(request.description()); + document.setStatus(DocumentStatus.PENDING); + document.setCreatedAt(Instant.now()); + + repo.persist(document); + + eventService.createSuccessEvent(document, "DOCUMENT_CREATED"); + + return document; + } + + public Optional findById(Long id) { + return repo.findByIdOptional(id); + } + + public List list(int page, int size) { + return repo.findAll() + .page(page, size) + .list(); + } +} +``` + +## DTOs and Validation + +```java +public record CreateDocumentRequest( + @NotBlank @Size(max = 200) String referenceNumber, + @NotBlank @Size(max = 2000) String description, + @NotNull @FutureOrPresent Instant validUntil, + @NotEmpty List<@NotBlank String> categories) {} + +public record DocumentResponse(Long id, String referenceNumber, DocumentStatus status) { + public static DocumentResponse from(Document document) { + return new DocumentResponse(document.getId(), document.getReferenceNumber(), + document.getStatus()); + } +} +``` + +## Exception Mapping + +```java +@Provider +public class ValidationExceptionMapper implements ExceptionMapper { + @Override + public Response toResponse(ConstraintViolationException exception) { + String message = exception.getConstraintViolations().stream() + .map(cv -> cv.getPropertyPath() + ": " + cv.getMessage()) + .collect(Collectors.joining(", ")); + + return Response.status(Response.Status.BAD_REQUEST) + .entity(Map.of("error", "validation_error", "message", message)) + .build(); + } +} + +@Provider +@Slf4j +public class GenericExceptionMapper implements ExceptionMapper { + + @Override + public Response toResponse(Exception exception) { + log.error("Unhandled exception", exception); + return Response.status(Response.Status.INTERNAL_SERVER_ERROR) + .entity(Map.of("error", "internal_error", "message", "An unexpected error occurred")) + .build(); + } +} +``` + +## CompletableFuture Async Operations + +```java +@Slf4j +@ApplicationScoped +@RequiredArgsConstructor +public class FileStorageService { + private final S3Client s3Client; + private final ExecutorService executorService; + + @ConfigProperty(name = "storage.bucket-name") + String bucketName; + + public CompletableFuture uploadOriginalFile( + InputStream inputStream, + long size, + LogContext logContext, + InvoiceFormat format) { + + return CompletableFuture.supplyAsync(() -> { + try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) { + String path = generateStoragePath(format); + + PutObjectRequest request = PutObjectRequest.builder() + .bucket(bucketName) + .key(path) + .contentLength(size) + .build(); + + s3Client.putObject(request, RequestBody.fromInputStream(inputStream, size)); + + log.info("File uploaded to S3: {}", path); + + return new StoredDocumentInfo(path, size, Instant.now()); + } catch (Exception e) { + log.error("Failed to upload file to S3", e); + throw new StorageException("Upload failed", e); + } + }, executorService); + } +} +``` + +## Caching + +```java +@ApplicationScoped +@RequiredArgsConstructor +public class DocumentCacheService { + private final DocumentRepository repo; + + @CacheResult(cacheName = "document-cache") + public Optional getById(@CacheKey Long id) { + return repo.findByIdOptional(id); + } + + @CacheInvalidate(cacheName = "document-cache") + public void evict(@CacheKey Long id) {} + + @CacheInvalidateAll(cacheName = "document-cache") + public void evictAll() {} +} +``` + +## Configuration as YAML + +```yaml +# application.yml +"%dev": + quarkus: + datasource: + jdbc: + url: jdbc:postgresql://localhost:5432/dev_db + username: dev_user + password: ${DB_PASSWORD} + hibernate-orm: + database: + generation: drop-and-create + + rabbitmq: + host: localhost + port: 5672 + username: ${RABBITMQ_USER} + password: ${RABBITMQ_PASSWORD} + +"%test": + quarkus: + datasource: + jdbc: + url: jdbc:h2:mem:test + hibernate-orm: + database: + generation: drop-and-create + +"%prod": + quarkus: + datasource: + jdbc: + url: ${DATABASE_URL} + username: ${DB_USER} + password: ${DB_PASSWORD} + hibernate-orm: + database: + generation: validate + + rabbitmq: + host: ${RABBITMQ_HOST} + port: ${RABBITMQ_PORT} + username: ${RABBITMQ_USER} + password: ${RABBITMQ_PASSWORD} + +# Camel configuration +camel: + rabbitmq: + queue: + business-rules: business-rules-queue + invoice-processing: invoice-processing-queue +``` + +## Health Checks + +```java +@Readiness +@ApplicationScoped +@RequiredArgsConstructor +public class DatabaseHealthCheck implements HealthCheck { + private final AgroalDataSource dataSource; + + @Override + public HealthCheckResponse call() { + try (Connection conn = dataSource.getConnection()) { + boolean valid = conn.isValid(2); + return HealthCheckResponse.named("Database connection") + .status(valid) + .build(); + } catch (SQLException e) { + return HealthCheckResponse.down("Database connection"); + } + } +} + +@Liveness +@ApplicationScoped +public class CamelHealthCheck implements HealthCheck { + @Inject + CamelContext camelContext; + + @Override + public HealthCheckResponse call() { + boolean isStarted = camelContext.getStatus().isStarted(); + return HealthCheckResponse.named("Camel Context") + .status(isStarted) + .build(); + } +} +``` + +## Dependencies (Maven) + +```xml + + 3.27.0 + 1.18.42 + 3.24.2 + 0.8.13 + 17 + + + + + + io.quarkus.platform + quarkus-bom + ${quarkus.platform.version} + pom + import + + + io.quarkus.platform + quarkus-camel-bom + ${quarkus.platform.version} + pom + import + + + + + + + + io.quarkus + quarkus-arc + + + io.quarkus + quarkus-config-yaml + + + + + org.apache.camel.quarkus + camel-quarkus-spring-rabbitmq + + + org.apache.camel.quarkus + camel-quarkus-direct + + + org.apache.camel.quarkus + camel-quarkus-bean + + + + + org.projectlombok + lombok + ${lombok.version} + provided + + + + + io.quarkiverse.logging.logback + quarkus-logging-logback + + + net.logstash.logback + logstash-logback-encoder + + +``` + +## Best Practices + +### Architecture +- Use `@RequiredArgsConstructor` with Lombok for constructor injection +- Keep service layer thin; delegate complex logic to specialized classes +- Use Camel routes for message routing and integration patterns +- Prefer Panache Repository pattern for data access + +### Event-Driven +- Always track operations with EventService (success/error events) +- Use Camel `direct:` endpoints for in-memory routing +- Use `spring-rabbitmq` component for RabbitMQ integration +- Implement async publishing with `ProducerTemplate.asyncSendBody()` + +### Logging +- Use Logback with Logstash encoder for structured logging +- Propagate LogContext through service calls with `SafeAutoCloseable` +- Add contextual information to LogContext for request tracing +- Use `@Slf4j` instead of manual logger instantiation + +### Async Operations +- Use CompletableFuture for non-blocking I/O operations +- Call `.join()` when you need to wait for completion +- Handle exceptions from CompletableFuture properly +- Pass LogContext to async operations for tracing + +### Configuration +- Use YAML configuration (`quarkus-config-yaml`) +- Profile-aware configuration for dev/test/prod environments +- Externalize sensitive configuration to environment variables +- Use `@ConfigProperty` for type-safe config injection + +### Validation +- Validate at resource layer with `@Valid` +- Use Bean Validation annotations on DTOs +- Map exceptions to proper HTTP responses with `@Provider` + +### Transactions +- Use `@Transactional` on service methods that modify data +- Keep transactions short and focused +- Avoid calling async operations within transactions + +### Testing +- Use `camel-quarkus-junit5` for route testing +- Use AssertJ for assertions +- Mock all external dependencies +- Test conditional flow logic thoroughly + +### Quarkus-Specific +- Stay on latest LTS version (3.x) +- Use Quarkus dev mode for hot reload +- Add health checks for production readiness +- Test native compilation compatibility periodically diff --git a/skills/quarkus-security/SKILL.md b/skills/quarkus-security/SKILL.md new file mode 100644 index 00000000..4a9af479 --- /dev/null +++ b/skills/quarkus-security/SKILL.md @@ -0,0 +1,467 @@ +--- +name: quarkus-security +description: Quarkus Security best practices for authentication, authorization, JWT/OIDC, RBAC, input validation, CSRF, secrets management, and dependency security. +origin: ECC +--- + +# Quarkus Security Review + +Best practices for securing Quarkus applications with authentication, authorization, and input validation. + +## When to Activate + +- Adding authentication (JWT, OIDC, Basic Auth) +- Implementing authorization with @RolesAllowed or SecurityIdentity +- Validating user input (Bean Validation, custom validators) +- Configuring CORS or security headers +- Managing secrets (Vault, environment variables, config sources) +- Adding rate limiting or brute-force protection +- Scanning dependencies for CVEs +- Working with MicroProfile JWT or SmallRye JWT + +## Authentication + +### JWT Authentication + +```java +// Resource protected with JWT +@Path("/api/protected") +@Authenticated +public class ProtectedResource { + + @Inject + JsonWebToken jwt; + + @Inject + SecurityIdentity securityIdentity; + + @GET + public Response getData() { + String username = jwt.getName(); + Set roles = jwt.getGroups(); + return Response.ok(Map.of( + "username", username, + "roles", roles, + "principal", securityIdentity.getPrincipal().getName() + )).build(); + } +} +``` + +Configuration (application.properties): +```properties +mp.jwt.verify.publickey.location=publicKey.pem +mp.jwt.verify.issuer=https://auth.example.com + +# OIDC +quarkus.oidc.auth-server-url=https://auth.example.com/realms/myrealm +quarkus.oidc.client-id=backend-service +quarkus.oidc.credentials.secret=${OIDC_SECRET} +``` + +### Custom Authentication Filter + +```java +@Provider +@Priority(Priorities.AUTHENTICATION) +public class CustomAuthFilter implements ContainerRequestFilter { + + @Inject + SecurityIdentity identity; + + @Override + public void filter(ContainerRequestContext requestContext) { + String authHeader = requestContext.getHeaderString(HttpHeaders.AUTHORIZATION); + + // Reject immediately if header is absent or malformed + if (authHeader == null || !authHeader.startsWith("Bearer ")) { + requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build()); + return; + } + + String token = authHeader.substring(7); + if (!validateToken(token)) { + requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build()); + } + } + + private boolean validateToken(String token) { + // Token validation logic + return true; + } +} +``` + +## Authorization + +### Role-Based Access Control + +```java +@Path("/api/admin") +@RolesAllowed("ADMIN") +public class AdminResource { + + @GET + @Path("/users") + public List listUsers() { + return userService.findAll(); + } + + @DELETE + @Path("/users/{id}") + @RolesAllowed({"ADMIN", "SUPER_ADMIN"}) + public Response deleteUser(@PathParam("id") Long id) { + userService.delete(id); + return Response.noContent().build(); + } +} + +@Path("/api/users") +public class UserResource { + + @Inject + SecurityIdentity securityIdentity; + + @GET + @Path("/{id}") + @RolesAllowed("USER") + public Response getUser(@PathParam("id") Long id) { + // Check ownership + if (!securityIdentity.hasRole("ADMIN") && + !isOwner(id, securityIdentity.getPrincipal().getName())) { + return Response.status(Response.Status.FORBIDDEN).build(); + } + return Response.ok(userService.findById(id)).build(); + } + + private boolean isOwner(Long userId, String username) { + return userService.isOwner(userId, username); + } +} +``` + +### Programmatic Security + +```java +@ApplicationScoped +public class SecurityService { + + @Inject + SecurityIdentity securityIdentity; + + public boolean canAccessResource(Long resourceId) { + if (securityIdentity.isAnonymous()) { + return false; + } + + if (securityIdentity.hasRole("ADMIN")) { + return true; + } + + String userId = securityIdentity.getPrincipal().getName(); + return resourceRepository.isOwner(resourceId, userId); + } +} +``` + +## Input Validation + +### Bean Validation + +```java +// BAD: No validation +@POST +public Response createUser(UserDto dto) { + return Response.ok(userService.create(dto)).build(); +} + +// GOOD: Validated DTO +public record CreateUserDto( + @NotBlank @Size(max = 100) String name, + @NotBlank @Email String email, + @NotNull @Min(18) @Max(150) Integer age, + @Pattern(regexp = "^\\+?[1-9]\\d{1,14}$") String phone +) {} + +@POST +@Path("/users") +public Response createUser(@Valid CreateUserDto dto) { + User user = userService.create(dto); + return Response.status(Response.Status.CREATED).entity(user).build(); +} +``` + +### Custom Validators + +```java +@Target({ElementType.FIELD, ElementType.PARAMETER}) +@Retention(RetentionPolicy.RUNTIME) +@Constraint(validatedBy = UsernameValidator.class) +public @interface ValidUsername { + String message() default "Invalid username format"; + Class[] groups() default {}; + Class[] payload() default {}; +} + +public class UsernameValidator implements ConstraintValidator { + @Override + public boolean isValid(String value, ConstraintValidatorContext context) { + if (value == null) return false; + return value.matches("^[a-zA-Z0-9_-]{3,20}$"); + } +} + +// Usage +public record CreateUserDto( + @ValidUsername String username, + @NotBlank @Email String email +) {} +``` + +## SQL Injection Prevention + +### Panache Active Record (Safe by Default) + +```java +// GOOD: Parameterized queries with Panache +List users = User.list("email = ?1 and active = ?2", email, true); + +Optional user = User.find("username", username).firstResultOptional(); + +// GOOD: Named parameters +List users = User.list("email = :email and age > :minAge", + Parameters.with("email", email).and("minAge", 18)); +``` + +### Native Queries (Use Parameters) + +```java +// BAD: String concatenation +@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true) + +// GOOD: Parameterized native query +@Entity +public class User extends PanacheEntity { + public static List findByEmailNative(String email) { + return getEntityManager() + .createNativeQuery("SELECT * FROM users WHERE email = :email", User.class) + .setParameter("email", email) + .getResultList(); + } +} +``` + +## Password Hashing + +```java +@ApplicationScoped +public class PasswordService { + + public String hash(String plainPassword) { + return BcryptUtil.bcryptHash(plainPassword); + } + + public boolean verify(String plainPassword, String hashedPassword) { + return BcryptUtil.matches(plainPassword, hashedPassword); + } +} + +// In service +@ApplicationScoped +public class UserService { + @Inject + PasswordService passwordService; + + @Transactional + public User register(CreateUserDto dto) { + String hashedPassword = passwordService.hash(dto.password()); + User user = new User(); + user.email = dto.email(); + user.password = hashedPassword; + user.persist(); + return user; + } + + public boolean authenticate(String email, String password) { + return User.find("email", email) + .firstResultOptional() + .map(u -> passwordService.verify(password, u.password)) + .orElse(false); + } +} +``` + +## CORS Configuration + +```properties +# application.properties +quarkus.http.cors=true +quarkus.http.cors.origins=https://app.example.com,https://admin.example.com +quarkus.http.cors.methods=GET,POST,PUT,DELETE +quarkus.http.cors.headers=accept,authorization,content-type,x-requested-with +quarkus.http.cors.exposed-headers=Content-Disposition +quarkus.http.cors.access-control-max-age=24H +quarkus.http.cors.access-control-allow-credentials=true +``` + +## Secrets Management + +```properties +# application.properties - NO SECRETS HERE + +# Use environment variables +quarkus.datasource.username=${DB_USER} +quarkus.datasource.password=${DB_PASSWORD} +quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET} + +# Or use Vault +quarkus.vault.url=https://vault.example.com +quarkus.vault.authentication.kubernetes.role=my-role +``` + +### HashiCorp Vault Integration + +```java +@ApplicationScoped +public class SecretService { + + @ConfigProperty(name = "api-key") + String apiKey; // Fetched from Vault + + public String getSecret(String key) { + return ConfigProvider.getConfig().getValue(key, String.class); + } +} +``` + +## Rate Limiting + +**Security Note**: Never use `X-Forwarded-For` directly — clients can spoof it. +Use the actual remote address from the servlet request, or an authenticated +identity (API key, JWT subject) when available. + +```java +@ApplicationScoped +public class RateLimitFilter implements ContainerRequestFilter { + private final Map limiters = new ConcurrentHashMap<>(); + + @Inject + HttpServletRequest servletRequest; + + @Override + public void filter(ContainerRequestContext requestContext) { + String clientId = getClientIdentifier(); + RateLimiter limiter = limiters.computeIfAbsent(clientId, + k -> RateLimiter.create(100.0)); // 100 requests per second + + if (!limiter.tryAcquire()) { + requestContext.abortWith( + Response.status(429) + .entity(Map.of("error", "Too many requests")) + .build() + ); + } + } + + private String getClientIdentifier() { + // Use the container-provided remote address (not X-Forwarded-For). + // If behind a trusted proxy, configure quarkus.http.proxy.proxy-address-forwarding=true + // so getRemoteAddr() returns the real client IP. + return servletRequest.getRemoteAddr(); + } +} +``` + +## Security Headers + +```java +@Provider +public class SecurityHeadersFilter implements ContainerResponseFilter { + + @Override + public void filter(ContainerRequestContext request, ContainerResponseContext response) { + MultivaluedMap headers = response.getHeaders(); + + // Prevent clickjacking + headers.putSingle("X-Frame-Options", "DENY"); + + // XSS protection + headers.putSingle("X-Content-Type-Options", "nosniff"); + headers.putSingle("X-XSS-Protection", "1; mode=block"); + + // HSTS + headers.putSingle("Strict-Transport-Security", "max-age=31536000; includeSubDomains"); + + // CSP — avoid 'unsafe-inline' for script-src as it negates XSS protection; + // use nonces or hashes instead. 'unsafe-inline' for style-src is acceptable + // when CSS frameworks require it, but prefer nonces where possible. + headers.putSingle("Content-Security-Policy", + "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'"); + } +} +``` + +## Audit Logging + +```java +@ApplicationScoped +public class AuditService { + private static final Logger LOG = Logger.getLogger(AuditService.class); + + @Inject + SecurityIdentity securityIdentity; + + public void logAccess(String resource, String action) { + String user = securityIdentity.isAnonymous() + ? "anonymous" + : securityIdentity.getPrincipal().getName(); + + LOG.infof("AUDIT: user=%s action=%s resource=%s timestamp=%s", + user, action, resource, Instant.now()); + } +} + +// Usage in resource +@Path("/api/sensitive") +public class SensitiveResource { + @Inject + AuditService auditService; + + @GET + @RolesAllowed("ADMIN") + public Response getData() { + auditService.logAccess("sensitive-data", "READ"); + return Response.ok(data).build(); + } +} +``` + +## Dependency Security Scanning + +```bash +# Maven +mvn org.owasp:dependency-check-maven:check + +# Gradle +./gradlew dependencyCheckAnalyze + +# Check Quarkus extensions +quarkus extension list --installable +``` + +## Best Practices + +- Always use HTTPS in production +- Enable JWT or OIDC for stateless authentication +- Use `@RolesAllowed` for declarative authorization +- Validate all input with Bean Validation +- Hash passwords with BCrypt (never plaintext) +- Store secrets in Vault or environment variables +- Use parameterized queries to prevent SQL injection +- Add security headers to all responses +- Implement rate limiting for public endpoints +- Audit sensitive operations +- Keep dependencies updated and scan for CVEs +- Use SecurityIdentity for programmatic checks +- Set appropriate CORS policies +- Test authentication and authorization paths diff --git a/skills/quarkus-tdd/SKILL.md b/skills/quarkus-tdd/SKILL.md new file mode 100644 index 00000000..beae1952 --- /dev/null +++ b/skills/quarkus-tdd/SKILL.md @@ -0,0 +1,811 @@ +--- +name: quarkus-tdd +description: Test-driven development for Quarkus 3.x LTS using JUnit 5, Mockito, REST Assured, Camel testing, and JaCoCo. Use when adding features, fixing bugs, or refactoring event-driven services. +origin: ECC +--- + +# Quarkus TDD Workflow + +TDD guidance for Quarkus 3.x services with 80%+ coverage (unit + integration). Optimized for event-driven architectures with Apache Camel. + +## When to Use + +- New features or REST endpoints +- Bug fixes or refactors +- Adding data access logic, security rules, or reactive streams +- Testing Apache Camel routes and event handlers +- Testing event-driven services with RabbitMQ +- Testing conditional flow logic +- Validating CompletableFuture async operations +- Testing LogContext propagation + +## Workflow + +1. Write tests first (they should fail) +2. Implement minimal code to pass +3. Refactor with tests green +4. Enforce coverage with JaCoCo (80%+ target) + +## Unit Tests with @Nested Organization + +Follow this structured approach for comprehensive, readable tests: + +```java +@ExtendWith(MockitoExtension.class) +@DisplayName("OrderService Unit Tests") +class OrderServiceTest { + + @Mock + private OrderRepository orderRepository; + + @Mock + private EventService eventService; + + @Mock + private FulfillmentPublisher fulfillmentPublisher; + + @InjectMocks + private OrderService orderService; + + private CreateOrderCommand validCommand; + + @BeforeEach + void setUp() { + validCommand = new CreateOrderCommand( + "customer-123", + List.of(new OrderLine("sku-123", 2)) + ); + } + + @Nested + @DisplayName("Tests for createOrder") + class CreateOrder { + + @Test + @DisplayName("Should persist order and publish fulfillment event") + void givenValidCommand_whenCreateOrder_thenPersistsAndPublishes() { + // ARRANGE + doNothing().when(orderRepository).persist(any(Order.class)); + + // ACT + OrderReceipt receipt = orderService.createOrder(validCommand); + + // ASSERT + assertThat(receipt).isNotNull(); + assertThat(receipt.customerId()).isEqualTo("customer-123"); + verify(orderRepository).persist(any(Order.class)); + verify(fulfillmentPublisher).publishAsync(receipt); + verify(eventService).createSuccessEvent(receipt, "ORDER_CREATED"); + } + + @Test + @DisplayName("Should reject missing customer id") + void givenMissingCustomerId_whenCreateOrder_thenThrowsBadRequest() { + // ARRANGE + CreateOrderCommand invalid = new CreateOrderCommand("", validCommand.lines()); + + // ACT & ASSERT + WebApplicationException exception = assertThrows( + WebApplicationException.class, + () -> orderService.createOrder(invalid) + ); + + assertThat(exception.getResponse().getStatus()).isEqualTo(400); + verify(orderRepository, never()).persist(any(Order.class)); + verify(fulfillmentPublisher, never()).publishAsync(any()); + } + + @Test + @DisplayName("Should record error event when persistence fails") + void givenPersistenceFailure_whenCreateOrder_thenRecordsErrorEvent() { + // ARRANGE + doThrow(new PersistenceException("database unavailable")) + .when(orderRepository).persist(any(Order.class)); + + // ACT & ASSERT + PersistenceException exception = assertThrows( + PersistenceException.class, + () -> orderService.createOrder(validCommand) + ); + + assertThat(exception.getMessage()).contains("database unavailable"); + verify(eventService).createErrorEvent( + eq(validCommand), + eq("ORDER_CREATE_FAILED"), + contains("database unavailable") + ); + verify(fulfillmentPublisher, never()).publishAsync(any()); + } + + @Test + @DisplayName("Should reject null commands") + void givenNullCommand_whenCreateOrder_thenThrowsNullPointerException() { + // ACT & ASSERT + assertThrows( + NullPointerException.class, + () -> orderService.createOrder(null) + ); + + verify(orderRepository, never()).persist(any(Order.class)); + } + } +} +``` + +### Key Testing Patterns + +1. **@Nested Classes**: Group tests by method being tested +2. **@DisplayName**: Provide readable test descriptions for test reports +3. **Naming Convention**: `givenX_whenY_thenZ` for clarity +4. **AAA Pattern**: Explicit `// ARRANGE`, `// ACT`, `// ASSERT` comments +5. **@BeforeEach**: Setup common test data to reduce duplication +6. **assertDoesNotThrow**: Test success scenarios without catching exceptions +7. **assertThrows**: Test exception scenarios with message validation using AssertJ +8. **Comprehensive Coverage**: Test happy paths, null inputs, edge cases, exceptions +9. **Verify Interactions**: Use Mockito `verify()` to ensure methods are called correctly +10. **Never Verify**: Use `never()` to ensure methods are NOT called in error scenarios + +## Testing Camel Routes + +```java +@QuarkusTest +@DisplayName("Business Rules Camel Route Tests") +class BusinessRulesRouteTest { + + @Inject + CamelContext camelContext; + + @Inject + ProducerTemplate producerTemplate; + + @InjectMock + EventService eventService; + + @InjectMock + DocumentValidator documentValidator; + + private BusinessRulesPayload testPayload; + + @BeforeEach + void setUp() { + // ARRANGE - Test data + testPayload = new BusinessRulesPayload(); + testPayload.setDocumentId(1L); + testPayload.setFlowProfile(FlowProfile.BASIC); + } + + @Nested + @DisplayName("Tests for business-rules-publisher route") + class BusinessRulesPublisher { + + @Test + @DisplayName("Should successfully publish message to RabbitMQ") + void givenValidPayload_whenPublish_thenMessageSentToQueue() throws Exception { + // ARRANGE + MockEndpoint mockRabbitMQ = camelContext.getEndpoint("mock:rabbitmq", MockEndpoint.class); + mockRabbitMQ.expectedMessageCount(1); + + // Replace real endpoint with mock for testing + camelContext.getRouteController().stopRoute("business-rules-publisher"); + AdviceWith.adviceWith(camelContext, "business-rules-publisher", advice -> { + advice.replaceFromWith("direct:business-rules-publisher"); + advice.weaveByToString(".*spring-rabbitmq.*").replace().to("mock:rabbitmq"); + }); + camelContext.getRouteController().startRoute("business-rules-publisher"); + + // ACT + producerTemplate.sendBody("direct:business-rules-publisher", testPayload); + + // ASSERT — body is a JSON String after .marshal().json(JsonLibrary.Jackson) + mockRabbitMQ.assertIsSatisfied(5000); + + assertThat(mockRabbitMQ.getExchanges()).hasSize(1); + String body = mockRabbitMQ.getExchanges().get(0).getIn().getBody(String.class); + assertThat(body).contains("\"documentId\":1"); + } + + @Test + @DisplayName("Should handle marshalling to JSON") + void givenPayload_whenPublish_thenMarshalledToJson() throws Exception { + // ARRANGE + MockEndpoint mockMarshal = new MockEndpoint("mock:marshal"); + camelContext.addEndpoint("mock:marshal", mockMarshal); + mockMarshal.expectedMessageCount(1); + + camelContext.getRouteController().stopRoute("business-rules-publisher"); + AdviceWith.adviceWith(camelContext, "business-rules-publisher", advice -> { + advice.weaveAddLast().to("mock:marshal"); + }); + camelContext.getRouteController().startRoute("business-rules-publisher"); + + // ACT + producerTemplate.sendBody("direct:business-rules-publisher", testPayload); + + // ASSERT + mockMarshal.assertIsSatisfied(5000); + + String body = mockMarshal.getExchanges().get(0).getIn().getBody(String.class); + assertThat(body).contains("\"documentId\":1"); + assertThat(body).contains("\"flowProfile\":\"BASIC\""); + } + } + + @Nested + @DisplayName("Tests for document-processing route") + class DocumentProcessing { + + @Test + @DisplayName("Should route invoice to correct processor") + void givenInvoiceType_whenProcess_thenRoutesToInvoiceProcessor() throws Exception { + // ARRANGE + MockEndpoint mockInvoice = camelContext.getEndpoint("mock:invoice", MockEndpoint.class); + mockInvoice.expectedMessageCount(1); + + camelContext.getRouteController().stopRoute("document-processing"); + AdviceWith.adviceWith(camelContext, "document-processing", advice -> { + advice.weaveByToString(".*direct:process-invoice.*").replace().to("mock:invoice"); + }); + camelContext.getRouteController().startRoute("document-processing"); + + // ACT + producerTemplate.sendBodyAndHeader("direct:process-document", + testPayload, "documentType", "INVOICE"); + + // ASSERT + mockInvoice.assertIsSatisfied(5000); + } + + @Test + @DisplayName("Should handle validation errors gracefully") + void givenValidationError_whenProcess_thenRoutesToErrorHandler() throws Exception { + // ARRANGE + MockEndpoint mockError = camelContext.getEndpoint("mock:error", MockEndpoint.class); + mockError.expectedMessageCount(1); + + camelContext.getRouteController().stopRoute("document-processing"); + AdviceWith.adviceWith(camelContext, "document-processing", advice -> { + advice.weaveByToString(".*direct:validation-error-handler.*") + .replace().to("mock:error"); + }); + camelContext.getRouteController().startRoute("document-processing"); + + // Mock validator bean to throw exception + when(documentValidator.validate(any())).thenThrow(new ValidationException("Invalid document")); + + // ACT + producerTemplate.sendBody("direct:process-document", testPayload); + + // ASSERT + mockError.assertIsSatisfied(5000); + + Exception exception = mockError.getExchanges().get(0).getException(); + assertThat(exception).isInstanceOf(ValidationException.class); + assertThat(exception.getMessage()).contains("Invalid document"); + } + } +} +``` + +## Testing Event Services + +```java +@ExtendWith(MockitoExtension.class) +@DisplayName("EventService Unit Tests") +class EventServiceTest { + + @Mock + private EventRepository eventRepository; + + @Mock + private ObjectMapper objectMapper; + + @InjectMocks + private EventService eventService; + + private BusinessRulesPayload testPayload; + + @BeforeEach + void setUp() { + // ARRANGE + testPayload = new BusinessRulesPayload(); + testPayload.setDocumentId(1L); + } + + @Nested + @DisplayName("Tests for createSuccessEvent") + class CreateSuccessEvent { + + @Test + @DisplayName("Should create success event with correct attributes") + void givenValidPayload_whenCreateSuccessEvent_thenEventPersisted() throws Exception { + // ARRANGE + when(objectMapper.writeValueAsString(testPayload)).thenReturn("{\"documentId\":1}"); + + // ACT + assertDoesNotThrow(() -> + eventService.createSuccessEvent(testPayload, "DOCUMENT_PROCESSED")); + + // ASSERT + verify(eventRepository).persist(argThat(event -> + event.getType().equals("DOCUMENT_PROCESSED") && + event.getStatus() == EventStatus.SUCCESS && + event.getPayload().equals("{\"documentId\":1}") && + event.getTimestamp() != null + )); + } + + @Test + @DisplayName("Should throw exception when payload is null") + void givenNullPayload_whenCreateSuccessEvent_thenThrowsException() { + // ARRANGE + Object nullPayload = null; + + // ACT & ASSERT + NullPointerException exception = assertThrows( + NullPointerException.class, + () -> eventService.createSuccessEvent(nullPayload, "EVENT_TYPE") + ); + + assertThat(exception.getMessage()).isEqualTo("Payload cannot be null"); + verify(eventRepository, never()).persist(any()); + } + } + + @Nested + @DisplayName("Tests for createErrorEvent") + class CreateErrorEvent { + + @Test + @DisplayName("Should create error event with error message") + void givenError_whenCreateErrorEvent_thenEventPersistedWithMessage() throws Exception { + // ARRANGE + String errorMessage = "Processing failed"; + when(objectMapper.writeValueAsString(testPayload)).thenReturn("{\"documentId\":1}"); + + // ACT + assertDoesNotThrow(() -> + eventService.createErrorEvent(testPayload, "PROCESSING_ERROR", errorMessage)); + + // ASSERT + verify(eventRepository).persist(argThat(event -> + event.getType().equals("PROCESSING_ERROR") && + event.getStatus() == EventStatus.ERROR && + event.getErrorMessage().equals(errorMessage) && + event.getPayload().equals("{\"documentId\":1}") + )); + } + + @ParameterizedTest + @DisplayName("Should reject invalid error messages") + @ValueSource(strings = {"", " "}) + void givenBlankErrorMessage_whenCreateErrorEvent_thenThrowsException(String blankMessage) { + // ACT & ASSERT + IllegalArgumentException exception = assertThrows( + IllegalArgumentException.class, + () -> eventService.createErrorEvent(testPayload, "ERROR", blankMessage) + ); + + assertThat(exception.getMessage()).contains("Error message cannot be blank"); + } + } +} +``` + +## Testing CompletableFuture + +```java +@ExtendWith(MockitoExtension.class) +@DisplayName("FileStorageService Unit Tests") +class FileStorageServiceTest { + + @Mock + private S3Client s3Client; + + @Mock + private ExecutorService executorService; + + @InjectMocks + private FileStorageService fileStorageService; + + private InputStream testInputStream; + private LogContext testLogContext; + + @BeforeEach + void setUp() { + // ARRANGE + testInputStream = new ByteArrayInputStream("test content".getBytes()); + testLogContext = new LogContext(); + testLogContext.put("traceId", "trace-123"); + } + + @Nested + @DisplayName("Tests for uploadOriginalFile") + class UploadOriginalFile { + + @Test + @DisplayName("Should successfully upload file and return document info") + void givenValidFile_whenUpload_thenReturnsDocumentInfo() throws Exception { + // ARRANGE + doAnswer(invocation -> { + ((Runnable) invocation.getArgument(0)).run(); + return null; + }).when(executorService).execute(any(Runnable.class)); + + when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class))) + .thenReturn(PutObjectResponse.builder().build()); + + // ACT + CompletableFuture future = + fileStorageService.uploadOriginalFile(testInputStream, 1024L, + testLogContext, InvoiceFormat.UBL); + + StoredDocumentInfo result = future.join(); + + // ASSERT + assertThat(result).isNotNull(); + assertThat(result.getPath()).isNotBlank(); + assertThat(result.getSize()).isEqualTo(1024L); + assertThat(result.getUploadedAt()).isNotNull(); + + verify(s3Client).putObject(any(PutObjectRequest.class), any(RequestBody.class)); + } + + @Test + @DisplayName("Should handle S3 upload failure") + void givenS3Failure_whenUpload_thenCompletableFutureFails() { + // ARRANGE — run synchronously so exception propagates through the future + doAnswer(invocation -> { + ((Runnable) invocation.getArgument(0)).run(); + return null; + }).when(executorService).execute(any(Runnable.class)); + + when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class))) + .thenThrow(new StorageException("S3 unavailable")); + + // ACT + CompletableFuture future = + fileStorageService.uploadOriginalFile(testInputStream, 1024L, + testLogContext, InvoiceFormat.UBL); + + // ASSERT + assertThatThrownBy(() -> future.join()) + .isInstanceOf(CompletionException.class) + .hasCauseInstanceOf(StorageException.class) + .hasMessageContaining("S3 unavailable"); + } + + @Test + @DisplayName("Should propagate LogContext to async operation") + void givenLogContext_whenUpload_thenContextPropagated() throws Exception { + // ARRANGE + AtomicReference capturedContext = new AtomicReference<>(); + + doAnswer(invocation -> { + capturedContext.set(CustomLog.getCurrentContext()); + ((Runnable) invocation.getArgument(0)).run(); + return null; + }).when(executorService).execute(any(Runnable.class)); + + // ACT + fileStorageService.uploadOriginalFile(testInputStream, 1024L, + testLogContext, InvoiceFormat.UBL).join(); + + // ASSERT + assertThat(capturedContext.get()).isNotNull(); + assertThat(capturedContext.get().get("traceId")).isEqualTo("trace-123"); + } + } +} +``` + +## Resource Layer Tests (REST Assured) + +```java +@QuarkusTest +@DisplayName("DocumentResource API Tests") +class DocumentResourceTest { + + @InjectMock + DocumentService documentService; + + @Nested + @DisplayName("Tests for GET /api/documents") + class ListDocuments { + + @Test + @DisplayName("Should return list of documents") + void givenDocumentsExist_whenList_thenReturnsOk() { + // ARRANGE + List documents = List.of(createDocument(1L, "DOC-001")); + when(documentService.list(0, 20)).thenReturn(documents); + + // ACT & ASSERT + given() + .when().get("/api/documents") + .then() + .statusCode(200) + .body("$.size()", is(1)) + .body("[0].referenceNumber", equalTo("DOC-001")); + } + } + + @Nested + @DisplayName("Tests for POST /api/documents") + class CreateDocument { + + @Test + @DisplayName("Should create document and return 201") + void givenValidRequest_whenCreate_thenReturns201() { + // ARRANGE + Document document = createDocument(1L, "DOC-001"); + when(documentService.create(any())).thenReturn(document); + + // ACT & ASSERT + given() + .contentType(ContentType.JSON) + .body(""" + { + "referenceNumber": "DOC-001", + "description": "Test document", + "validUntil": "2030-01-01T00:00:00Z", + "categories": ["test"] + } + """) + .when().post("/api/documents") + .then() + .statusCode(201) + .header("Location", containsString("/api/documents/1")) + .body("referenceNumber", equalTo("DOC-001")); + } + + @Test + @DisplayName("Should return 400 for invalid input") + void givenInvalidRequest_whenCreate_thenReturns400() { + // ACT & ASSERT + given() + .contentType(ContentType.JSON) + .body(""" + { + "referenceNumber": "", + "description": "Test" + } + """) + .when().post("/api/documents") + .then() + .statusCode(400); + } + } + + private Document createDocument(Long id, String referenceNumber) { + Document document = new Document(); + document.setId(id); + document.setReferenceNumber(referenceNumber); + document.setStatus(DocumentStatus.PENDING); + return document; + } +} +``` + +## Integration Tests with Real Database + +```java +@QuarkusTest +@TestProfile(IntegrationTestProfile.class) +@DisplayName("Document Integration Tests") +class DocumentIntegrationTest { + + @Test + @Transactional + @DisplayName("Should create and retrieve document via API") + void givenNewDocument_whenCreateAndRetrieve_thenSuccessful() { + // ACT - Create via API + Long id = given() + .contentType(ContentType.JSON) + .body(""" + { + "referenceNumber": "INT-001", + "description": "Integration test", + "validUntil": "2030-01-01T00:00:00Z", + "categories": ["test"] + } + """) + .when().post("/api/documents") + .then() + .statusCode(201) + .extract().path("id"); + + // ASSERT - Retrieve via API + given() + .when().get("/api/documents/" + id) + .then() + .statusCode(200) + .body("referenceNumber", equalTo("INT-001")); + } +} +``` + +## Coverage with JaCoCo + +### Maven Configuration (Complete) + +```xml + + org.jacoco + jacoco-maven-plugin + 0.8.13 + + + + prepare-agent + + prepare-agent + + + + + + report + verify + + report + + + + + + check + + check + + + + + BUNDLE + + + LINE + COVEREDRATIO + 0.80 + + + BRANCH + COVEREDRATIO + 0.70 + + + + + + + + +``` + +Run tests with coverage: +```bash +mvn clean test +mvn jacoco:report +mvn jacoco:check + +# Report at: target/site/jacoco/index.html +``` + +## Test Dependencies + +```xml + + + + io.quarkus + quarkus-junit5 + test + + + io.quarkus + quarkus-junit5-mockito + test + + + + + org.mockito + mockito-core + test + + + + + org.assertj + assertj-core + 3.24.2 + test + + + + + io.rest-assured + rest-assured + test + + + + + org.apache.camel.quarkus + camel-quarkus-junit5 + test + + +``` + +## Best Practices + +### Test Organization +- Use `@Nested` classes to group tests by method being tested +- Use `@DisplayName` for readable test descriptions visible in reports +- Follow `givenX_whenY_thenZ` naming convention for test methods +- Use `@BeforeEach` for common test data setup to reduce duplication + +### Test Structure +- Follow AAA pattern with explicit comments (`// ARRANGE`, `// ACT`, `// ASSERT`) +- Use `assertDoesNotThrow` for success scenarios +- Use `assertThrows` for exception scenarios with message validation +- Verify exception messages match expected values using AssertJ `contains()` or `isEqualTo()` + +### Test Coverage +- Test happy paths for all public methods +- Test null input handling +- Test edge cases (empty collections, boundary values, negative IDs, blank strings) +- Test exception scenarios comprehensively +- Mock all external dependencies (repositories, services, Camel endpoints) +- Aim for 80%+ line coverage, 70%+ branch coverage + +### Assertions +- **Prefer AssertJ** (`assertThat`) over JUnit assertions for value checks +- Use fluent AssertJ API for readability: `assertThat(list).hasSize(3).contains(item)` +- For exceptions: use JUnit `assertThrows` to capture, then AssertJ to validate the message +- For non-throwing success paths: use JUnit `assertDoesNotThrow` +- For collections: `extracting()`, `filteredOn()`, `containsExactly()` + +### Testing Integration +- Use `@QuarkusTest` for integration tests +- Use `@InjectMock` to mock dependencies in Quarkus tests +- Prefer REST Assured for API testing +- Use `@TestProfile` for test-specific configuration + +### Event-Driven Testing +- Test Camel routes with `AdviceWith` and `MockEndpoint` +- Use `@CamelQuarkusTest` annotation (if using standalone Camel tests) +- Verify message content, headers, and routing logic +- Test error handling routes separately +- Mock external systems (RabbitMQ, S3, databases) in unit tests + +### Camel Route Testing +- Use `MockEndpoint` for asserting message flow +- Use `AdviceWith` to modify routes for testing (replace endpoints with mocks) +- Test message transformation and marshalling +- Test exception handling and dead letter queues + +### Testing Async Operations +- Test CompletableFuture success and failure scenarios +- Use `.join()` in tests to wait for async completion +- Test exception propagation from CompletableFuture +- Verify LogContext propagation to async operations + +### Performance +- Keep tests fast and isolated +- Run tests in continuous mode: `mvn quarkus:test` +- Use parameterized tests (`@ParameterizedTest`) for input variations +- Build reusable test data builders or factory methods + +### Quarkus-Specific +- Stay on latest LTS version (Quarkus 3.x) +- Test native compilation compatibility periodically +- Use Quarkus test profiles for different scenarios +- Leverage Quarkus dev services for local testing +- Use `@InjectMock` instead of `@MockBean` (Quarkus-specific) + +### Verification Best Practices +- Always verify interactions on mocked dependencies +- Use `verify(mock, never())` to ensure methods are NOT called in error scenarios +- Use `argThat()` for complex argument matching +- Verify the order of calls when it matters: `InOrder` from Mockito diff --git a/skills/quarkus-verification/SKILL.md b/skills/quarkus-verification/SKILL.md new file mode 100644 index 00000000..54748e99 --- /dev/null +++ b/skills/quarkus-verification/SKILL.md @@ -0,0 +1,479 @@ +--- +name: quarkus-verification +description: "Verification loop for Quarkus projects: build, static analysis, tests with coverage, security scans, native compilation, and diff review before release or PR." +origin: ECC +--- + +# Quarkus Verification Loop + +Run before PRs, after major changes, and pre-deploy. + +## When to Activate + +- Before opening a pull request for a Quarkus service +- After major refactoring or dependency upgrades +- Pre-deployment verification for staging or production +- Running full build → lint → test → security scan → native compilation pipeline +- Validating test coverage meets thresholds (80%+) +- Testing native image compatibility + +## Phase 1: Build + +```bash +# Maven +mvn clean verify -DskipTests + +# Gradle +./gradlew clean assemble -x test +``` + +If build fails, stop and fix compilation errors. + +## Phase 2: Static Analysis + +### Checkstyle, PMD, SpotBugs (Maven) + +```bash +mvn checkstyle:check pmd:check spotbugs:check +``` + +### SonarQube (if configured) + +```bash +mvn sonar:sonar \ + -Dsonar.projectKey=my-quarkus-project \ + -Dsonar.host.url=http://localhost:9000 \ + -Dsonar.login=${SONAR_TOKEN} +``` + +### Common Issues to Address + +- Unused imports or variables +- Complex methods (high cyclomatic complexity) +- Potential null pointer dereferences +- Security issues flagged by SpotBugs + +## Phase 3: Tests + Coverage + +```bash +# Run all tests +mvn clean test + +# Generate coverage report +mvn jacoco:report + +# Enforce coverage threshold (80%) +mvn jacoco:check + +# Or with Gradle +./gradlew test jacocoTestReport jacocoTestCoverageVerification +``` + +### Test Categories + +#### Unit Tests +Test service logic with mocked dependencies: + +```java +@ExtendWith(MockitoExtension.class) +class UserServiceTest { + @Mock UserRepository userRepository; + @InjectMocks UserService userService; + + @Test + void createUser_validInput_returnsUser() { + var dto = new CreateUserDto("Alice", "alice@example.com"); + + // Panache persist() is void — use doNothing + verify + doNothing().when(userRepository).persist(any(User.class)); + + User result = userService.create(dto); + + assertThat(result.name).isEqualTo("Alice"); + verify(userRepository).persist(any(User.class)); + } +} +``` + +#### Integration Tests +Test with real database (Testcontainers): + +```java +@QuarkusTest +@QuarkusTestResource(PostgresTestResource.class) +class UserRepositoryIntegrationTest { + + @Inject + UserRepository userRepository; + + @Test + @Transactional + void findByEmail_existingUser_returnsUser() { + User user = new User(); + user.name = "Alice"; + user.email = "alice@example.com"; + userRepository.persist(user); + + Optional found = userRepository.findByEmail("alice@example.com"); + + assertThat(found).isPresent(); + assertThat(found.get().name).isEqualTo("Alice"); + } +} +``` + +#### API Tests +Test REST endpoints with REST Assured: + +```java +@QuarkusTest +class UserResourceTest { + + @Test + void createUser_validInput_returns201() { + given() + .contentType(ContentType.JSON) + .body(""" + {"name": "Alice", "email": "alice@example.com"} + """) + .when().post("/api/users") + .then() + .statusCode(201) + .body("name", equalTo("Alice")); + } + + @Test + void createUser_invalidEmail_returns400() { + given() + .contentType(ContentType.JSON) + .body(""" + {"name": "Alice", "email": "invalid"} + """) + .when().post("/api/users") + .then() + .statusCode(400); + } +} +``` + +### Coverage Report + +Check `target/site/jacoco/index.html` for detailed coverage: +- Overall line coverage (target: 80%+) +- Branch coverage (target: 70%+) +- Identify uncovered critical paths + +## Phase 4: Security Scanning + +### Dependency Vulnerabilities (Maven) + +```bash +mvn org.owasp:dependency-check-maven:check +``` + +Review `target/dependency-check-report.html` for CVEs. + +### Quarkus Security Audit + +```bash +# Check vulnerable extensions +mvn quarkus:audit + +# List all extensions +mvn quarkus:list-extensions +``` + +### OWASP ZAP (API Security Testing) + +```bash +docker run -t owasp/zap2docker-stable zap-api-scan.py \ + -t http://localhost:8080/q/openapi \ + -f openapi +``` + +### Common Security Checks + +- [ ] All secrets in environment variables (not in code) +- [ ] Input validation on all endpoints +- [ ] Authentication/authorization configured +- [ ] CORS properly configured +- [ ] Security headers set +- [ ] Passwords hashed with BCrypt +- [ ] SQL injection protection (parameterized queries) +- [ ] Rate limiting on public endpoints + +## Phase 5: Native Compilation + +Test GraalVM native image compatibility: + +```bash +# Build native executable +mvn package -Dnative + +# Or with container +mvn package -Dnative -Dquarkus.native.container-build=true + +# Test native executable +./target/*-runner + +# Run basic smoke tests +curl http://localhost:8080/q/health/live +curl http://localhost:8080/q/health/ready +``` + +### Native Image Troubleshooting + +Common issues: +- **Reflection**: Add reflection config for dynamic classes +- **Resources**: Include resources with `quarkus.native.resources.includes` +- **JNI**: Register JNI classes if using native libraries + +Example reflection config: +```java +@RegisterForReflection(targets = {MyDynamicClass.class}) +public class ReflectionConfiguration {} +``` + +## Phase 6: Performance Testing + +### Load Testing with K6 + +```javascript +// load-test.js +import http from 'k6/http'; +import { check } from 'k6'; + +export const options = { + stages: [ + { duration: '30s', target: 50 }, + { duration: '1m', target: 100 }, + { duration: '30s', target: 0 }, + ], +}; + +export default function () { + const res = http.get('http://localhost:8080/api/markets'); + check(res, { + 'status is 200': (r) => r.status === 200, + 'response time < 200ms': (r) => r.timings.duration < 200, + }); +} +``` + +Run: +```bash +k6 run load-test.js +``` + +### Metrics to Monitor + +- Response time (p50, p95, p99) +- Throughput (requests/sec) +- Error rate +- Memory usage +- CPU usage + +## Phase 7: Health Checks + +```bash +# Liveness +curl http://localhost:8080/q/health/live + +# Readiness +curl http://localhost:8080/q/health/ready + +# All health checks +curl http://localhost:8080/q/health + +# Metrics (if enabled) +curl http://localhost:8080/q/metrics +``` + +Expected responses: +```json +{ + "status": "UP", + "checks": [ + { + "name": "Database connection", + "status": "UP" + } + ] +} +``` + +## Phase 8: Container Image Build + +```bash +# Build container image +mvn package -Dquarkus.container-image.build=true + +# Or with specific registry +mvn package \ + -Dquarkus.container-image.build=true \ + -Dquarkus.container-image.registry=docker.io \ + -Dquarkus.container-image.group=myorg \ + -Dquarkus.container-image.tag=1.0.0 + +# Test container +docker run -p 8080:8080 myorg/my-quarkus-app:1.0.0 +``` + +### Container Security Scan + +```bash +# Trivy +trivy image myorg/my-quarkus-app:1.0.0 + +# Grype +grype myorg/my-quarkus-app:1.0.0 +``` + +## Phase 9: Configuration Validation + +```bash +# Check all configuration properties +mvn quarkus:info + +# List all config sources +curl http://localhost:8080/q/dev/io.quarkus.quarkus-vertx-http/config +``` + +### Environment-Specific Checks + +- [ ] Database URLs configured per environment +- [ ] Secrets externalized (Vault, env vars) +- [ ] Logging levels appropriate +- [ ] CORS origins set correctly +- [ ] Rate limiting configured +- [ ] Monitoring/tracing enabled + +## Phase 10: Documentation Review + +- [ ] OpenAPI/Swagger docs up to date (`/q/swagger-ui`) +- [ ] README has setup instructions +- [ ] API changes documented +- [ ] Migration guide for breaking changes +- [ ] Configuration properties documented + +Generate OpenAPI spec: +```bash +curl http://localhost:8080/q/openapi -o openapi.json +``` + +## Verification Checklist + +### Code Quality +- [ ] Build passes without warnings +- [ ] Static analysis clean (no high/medium issues) +- [ ] Code follows team conventions +- [ ] No commented-out code or TODOs in PR + +### Testing +- [ ] All tests pass +- [ ] Code coverage ≥ 80% +- [ ] Integration tests with real database +- [ ] Security tests pass +- [ ] Performance within acceptable limits + +### Security +- [ ] No dependency vulnerabilities +- [ ] Authentication/authorization tested +- [ ] Input validation complete +- [ ] Secrets not in source code +- [ ] Security headers configured + +### Deployment +- [ ] Native compilation successful +- [ ] Container image builds +- [ ] Health checks respond correctly +- [ ] Configuration valid for target environment + +### Native Image +- [ ] Native executable builds +- [ ] Native tests pass +- [ ] Startup time < 100ms +- [ ] Memory footprint acceptable + +## Automated Verification Script + +```bash +#!/bin/bash +set -e + +echo "=== Phase 1: Build ===" +mvn clean verify -DskipTests + +echo "=== Phase 2: Static Analysis ===" +mvn checkstyle:check pmd:check spotbugs:check + +echo "=== Phase 3: Tests + Coverage ===" +mvn test jacoco:report jacoco:check + +echo "=== Phase 4: Security Scan ===" +mvn org.owasp:dependency-check-maven:check + +echo "=== Phase 5: Native Compilation ===" +mvn package -Dnative -Dquarkus.native.container-build=true + +echo "=== All Phases Complete ===" +echo "Review reports:" +echo " - Coverage: target/site/jacoco/index.html" +echo " - Security: target/dependency-check-report.html" +echo " - Native: target/*-runner" +``` + +## CI/CD Integration + +### GitHub Actions Example + +```yaml +name: Verification + +on: [push, pull_request] + +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Set up JDK 21 + uses: actions/setup-java@v3 + with: + java-version: '21' + distribution: 'temurin' + + - name: Cache Maven packages + uses: actions/cache@v3 + with: + path: ~/.m2 + key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} + + - name: Build + run: mvn clean verify -DskipTests + + - name: Test with Coverage + run: mvn test jacoco:report jacoco:check + + - name: Security Scan + run: mvn org.owasp:dependency-check-maven:check + + - name: Upload Coverage + uses: codecov/codecov-action@v3 + with: + files: target/site/jacoco/jacoco.xml +``` + +## Best Practices + +- Run verification loop before every PR +- Automate in CI/CD pipeline +- Fix issues immediately; don't accumulate debt +- Keep coverage above 80% +- Update dependencies regularly +- Test native compilation periodically +- Monitor performance trends +- Document breaking changes +- Review security scan results +- Validate configuration for each environment