@anhth2/spec-driven-dev-plugin 0.5.0

package/core/modules/golang/architecture-snippets/domain-layout.md

@@ -0,0 +1,283 @@
+# Go — Domain-Driven Layout Code Patterns
+
+## Domain Model
+
+```go
+// internal/domain/order.go
+package domain
+
+import (
+    "errors"
+    "time"
+)
+
+// OrderStatus represents the lifecycle state of an order.
+type OrderStatus string
+
+const (
+    OrderStatusPending   OrderStatus = "PENDING"
+    OrderStatusConfirmed OrderStatus = "CONFIRMED"
+    OrderStatusShipped   OrderStatus = "SHIPPED"
+    OrderStatusCancelled OrderStatus = "CANCELLED"
+)
+
+// Order is the aggregate root for the order domain.
+type Order struct {
+    ID              int64
+    CustomerID      int64
+    Status          OrderStatus
+    Items           []OrderItem
+    ShippingAddress string
+    CreatedAt       time.Time
+    UpdatedAt       time.Time
+}
+
+// OrderItem represents a single line item within an order.
+type OrderItem struct {
+    ProductID  int64
+    Quantity   int
+    UnitPrice  float64
+}
+
+// TotalAmount calculates the total order value.
+func (o *Order) TotalAmount() float64 {
+    var total float64
+    for _, item := range o.Items {
+        total += float64(item.Quantity) * item.UnitPrice
+    }
+    return total
+}
+
+// Cancel transitions the order to CANCELLED status.
+func (o *Order) Cancel() error {
+    if o.Status == OrderStatusShipped {
+        return errors.New("cannot cancel an order that has already been shipped")
+    }
+    o.Status = OrderStatusCancelled
+    return nil
+}
+```
+
+## Repository Interface (defined in domain)
+
+```go
+// internal/domain/order_repository.go
+package domain
+
+import "context"
+
+// OrderRepository defines persistence operations for orders.
+// Implementations live in internal/repo/.
+type OrderRepository interface {
+    GetByID(ctx context.Context, id int64) (*Order, error)
+    GetByCustomerID(ctx context.Context, customerID int64) ([]*Order, error)
+    Create(ctx context.Context, order *Order) error
+    Update(ctx context.Context, order *Order) error
+}
+```
+
+## Use Case (business logic)
+
+```go
+// internal/usecase/order_usecase.go
+// @trace.implements=ORDER-UC1
+package usecase
+
+import (
+    "context"
+    "fmt"
+    "myapp/internal/domain"
+    "time"
+)
+
+// OrderUseCase handles all order-related business operations.
+type OrderUseCase struct {
+    repo domain.OrderRepository
+}
+
+// NewOrderUseCase creates a new OrderUseCase with required dependencies.
+func NewOrderUseCase(repo domain.OrderRepository) *OrderUseCase {
+    return &OrderUseCase{repo: repo}
+}
+
+// CreateOrderRequest holds input data for creating an order.
+type CreateOrderRequest struct {
+    CustomerID      int64
+    Items           []domain.OrderItem
+    ShippingAddress string
+}
+
+// CreateOrder creates a new order for a customer.
+// @trace.implements=ORDER-UC1-SC1
+func (uc *OrderUseCase) CreateOrder(ctx context.Context, req CreateOrderRequest) (*domain.Order, error) {
+    if len(req.Items) == 0 {
+        return nil, fmt.Errorf("order must contain at least one item")
+    }
+
+    order := &domain.Order{
+        CustomerID:      req.CustomerID,
+        Status:          domain.OrderStatusPending,
+        Items:           req.Items,
+        ShippingAddress: req.ShippingAddress,
+        CreatedAt:       time.Now(),
+    }
+
+    if err := uc.repo.Create(ctx, order); err != nil {
+        return nil, fmt.Errorf("create order: %w", err)
+    }
+    return order, nil
+}
+
+// GetOrder retrieves an order by ID.
+// @trace.implements=ORDER-UC1-SC2
+func (uc *OrderUseCase) GetOrder(ctx context.Context, id int64) (*domain.Order, error) {
+    order, err := uc.repo.GetByID(ctx, id)
+    if err != nil {
+        return nil, fmt.Errorf("get order %d: %w", id, err)
+    }
+    if order == nil {
+        return nil, domain.ErrNotFound
+    }
+    return order, nil
+}
+```
+
+## HTTP Handler (Gin)
+
+```go
+// internal/handler/order_handler.go
+// @trace.implements=ORDER-UC1
+package handler
+
+import (
+    "errors"
+    "net/http"
+    "strconv"
+
+    "github.com/gin-gonic/gin"
+    "myapp/internal/domain"
+    "myapp/internal/usecase"
+)
+
+// OrderHandler handles HTTP requests for order operations.
+type OrderHandler struct {
+    uc *usecase.OrderUseCase
+}
+
+// NewOrderHandler creates a new OrderHandler.
+func NewOrderHandler(uc *usecase.OrderUseCase) *OrderHandler {
+    return &OrderHandler{uc: uc}
+}
+
+// RegisterRoutes registers all order endpoints on the given router group.
+func (h *OrderHandler) RegisterRoutes(r *gin.RouterGroup) {
+    r.POST("/orders", h.CreateOrder)        // @trace.implements=ORDER-UC1-SC1
+    r.GET("/orders/:id", h.GetOrder)        // @trace.implements=ORDER-UC1-SC2
+}
+
+// CreateOrder handles POST /v1/orders.
+func (h *OrderHandler) CreateOrder(c *gin.Context) {
+    var req usecase.CreateOrderRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    order, err := h.uc.CreateOrder(c.Request.Context(), req)
+    if err != nil {
+        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusCreated, order)
+}
+
+// GetOrder handles GET /v1/orders/:id.
+func (h *OrderHandler) GetOrder(c *gin.Context) {
+    id, err := strconv.ParseInt(c.Param("id"), 10, 64)
+    if err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": "invalid order id"})
+        return
+    }
+    order, err := h.uc.GetOrder(c.Request.Context(), id)
+    if errors.Is(err, domain.ErrNotFound) {
+        c.JSON(http.StatusNotFound, gin.H{"error": "order not found"})
+        return
+    }
+    if err != nil {
+        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusOK, order)
+}
+```
+
+## Table-Driven Test Pattern
+
+```go
+// internal/usecase/order_usecase_test.go
+// @trace.verifies=ORDER-UC1
+// @trace.test_type=unit
+package usecase_test
+
+import (
+    "context"
+    "testing"
+
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/mock"
+    "myapp/internal/domain"
+    "myapp/internal/usecase"
+)
+
+func TestOrderUseCase_CreateOrder(t *testing.T) {
+    tests := []struct {
+        name        string
+        request     usecase.CreateOrderRequest
+        setupMock   func(*MockOrderRepository)
+        expectError bool
+        expectOrder bool
+    }{
+        {
+            name: "valid order with items should create successfully",
+            request: usecase.CreateOrderRequest{
+                CustomerID:      1,
+                Items:           []domain.OrderItem{{ProductID: 10, Quantity: 2, UnitPrice: 99.9}},
+                ShippingAddress: "123 Main St",
+            },
+            setupMock: func(m *MockOrderRepository) {
+                m.On("Create", mock.Anything, mock.AnythingOfType("*domain.Order")).Return(nil)
+            },
+            expectError: false,
+            expectOrder: true,
+        },
+        {
+            name: "empty items should return validation error",
+            request: usecase.CreateOrderRequest{
+                CustomerID: 1,
+                Items:      []domain.OrderItem{},
+            },
+            setupMock:   func(m *MockOrderRepository) {},
+            expectError: true,
+            expectOrder: false,
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            mockRepo := new(MockOrderRepository)
+            tt.setupMock(mockRepo)
+            uc := usecase.NewOrderUseCase(mockRepo)
+
+            order, err := uc.CreateOrder(context.Background(), tt.request)
+
+            if tt.expectError {
+                assert.Error(t, err)
+                assert.Nil(t, order)
+            } else {
+                assert.NoError(t, err)
+                assert.NotNil(t, order)
+            }
+            mockRepo.AssertExpectations(t)
+        })
+    }
+}
+```

package/core/modules/golang/module.yaml

@@ -0,0 +1,6 @@
+name: "Go"
+version: "1.0.0"
+description: "Go with domain-driven layout"
+language: "Go"
+framework: "Standard library / Gin / Echo"
+stack_type: "backend"

package/core/modules/golang/stack-profile.yaml

@@ -0,0 +1,40 @@
+build:
+  compile: "go build ./..."
+  test: "go test ./..."
+  run: "go run ./cmd/{service-name}"
+
+architecture:
+  style: "Domain-driven layout"
+  directory_structure:
+    cmd/: "Main entry points, one per binary (e.g., cmd/api/main.go)"
+    internal/domain/: "Domain entities, interfaces, and business rules"
+    internal/repo/: "Repository implementations (DB, cache)"
+    internal/handler/: "HTTP handlers (Gin/Echo) — thin, delegate to use cases"
+    internal/usecase/: "Use case implementations (business logic)"
+    pkg/: "Reusable packages safe for external use"
+    config/: "Configuration loading (env vars, YAML)"
+  key_rules:
+    - "Define interfaces in the consumer package (dependency inversion)"
+    - "internal/ packages cannot be imported outside the module"
+    - "Handlers must not contain business logic — only parse, call use case, respond"
+    - "Use cases own business rules and call repository interfaces"
+    - "Repositories implement persistence — never call use cases"
+
+coding_standards:
+  naming:
+    packages: "lowercase single word (e.g., order, handler, repo)"
+    interfaces: "Describe behavior, no 'I' prefix (e.g., OrderRepository, not IOrderRepository)"
+    structs: "PascalCase for exported, camelCase for unexported"
+    methods: "PascalCase for exported, camelCase for unexported"
+  patterns:
+    error_handling: "Return error as last return value; use errors.Is/As; wrap with fmt.Errorf(\"...: %w\", err)"
+    interfaces: "Define small interfaces at point of use; prefer 1-2 method interfaces"
+    constructors: "NewXxx(deps...) *Xxx — always use constructor functions"
+
+testing:
+  framework: "Standard library testing package + testify"
+  patterns:
+    - "Table-driven tests for all cases"
+    - "Use testify/assert and testify/mock"
+    - "Test file: {file}_test.go in same package (white-box) or {pkg}_test package (black-box)"
+    - "Integration tests in internal/{pkg}/integration_test.go with build tag //go:build integration"

package/core/modules/java-spring/architecture-snippets/layered-arch.md

@@ -0,0 +1,201 @@
+# Java Spring Boot — Layered Architecture Code Patterns
+
+## Controller Pattern
+
+```java
+@RestController
+@RequestMapping("/v1/orders")
+@RequiredArgsConstructor
+// @trace.implements=ORDER-UC1-SC1
+// @trace.source=specs/bdd/order/ORDER-UC1-create-order.feature
+public class OrderController {
+
+    private final OrderFacade orderFacade;
+
+    @PostMapping
+    public ResponseEntity<ApiResponse<OrderResponse>> createOrder(
+            @Valid @RequestBody CreateOrderRequest request) {
+        OrderResponse result = orderFacade.createOrder(request);
+        return ResponseEntity.status(HttpStatus.CREATED)
+                .body(ApiResponse.success(result));
+    }
+
+    @GetMapping("/{id}")
+    // @trace.implements=ORDER-UC1-SC2
+    public ResponseEntity<ApiResponse<OrderResponse>> getOrder(@PathVariable Long id) {
+        OrderResponse result = orderFacade.getOrder(id);
+        return ResponseEntity.ok(ApiResponse.success(result));
+    }
+}
+```
+
+## Service Interface Pattern
+
+```java
+public interface OrderService {
+    OrderResponse createOrder(CreateOrderRequest request);
+    OrderResponse getOrderById(Long id);
+    void cancelOrder(Long id);
+}
+```
+
+## Service Implementation Pattern
+
+```java
+@Service
+@RequiredArgsConstructor
+@Transactional(readOnly = true)
+public class OrderServiceImpl implements OrderService {
+
+    private final OrderRepository orderRepository;
+    private final OrderMapper orderMapper;
+
+    @Override
+    @Transactional
+    public OrderResponse createOrder(CreateOrderRequest request) {
+        Order order = orderMapper.toEntity(request);
+        order.setStatus(OrderStatus.PENDING);
+        Order saved = orderRepository.save(order);
+        return orderMapper.toResponse(saved);
+    }
+
+    @Override
+    public OrderResponse getOrderById(Long id) {
+        Order order = orderRepository.findById(id)
+                .orElseThrow(() -> new ResourceNotFoundException("Order", id));
+        return orderMapper.toResponse(order);
+    }
+
+    @Override
+    @Transactional
+    public void cancelOrder(Long id) {
+        Order order = orderRepository.findById(id)
+                .orElseThrow(() -> new ResourceNotFoundException("Order", id));
+        order.setStatus(OrderStatus.CANCELLED);
+    }
+}
+```
+
+## Repository Interface Pattern
+
+```java
+@Repository
+public interface OrderRepository extends JpaRepository<Order, Long> {
+
+    List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status);
+
+    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id")
+    Optional<Order> findByIdWithItems(@Param("id") Long id);
+
+    Page<Order> findByCreatedAtBetween(
+            LocalDateTime from, LocalDateTime to, Pageable pageable);
+}
+```
+
+## DTO Pattern
+
+```java
+// Request DTO
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class CreateOrderRequest {
+    @NotNull(message = "customerId is required")
+    private Long customerId;
+
+    @NotEmpty(message = "items must not be empty")
+    private List<OrderItemRequest> items;
+
+    @NotBlank(message = "shippingAddress is required")
+    private String shippingAddress;
+}
+
+// Response DTO
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class OrderResponse {
+    private Long id;
+    private Long customerId;
+    private OrderStatus status;
+    private List<OrderItemResponse> items;
+    private BigDecimal totalAmount;
+    private LocalDateTime createdAt;
+}
+```
+
+## MapStruct Mapper Pattern
+
+```java
+@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.ERROR)
+public interface OrderMapper {
+
+    @Mapping(target = "id", ignore = true)
+    @Mapping(target = "status", ignore = true)
+    @Mapping(target = "createdAt", ignore = true)
+    Order toEntity(CreateOrderRequest request);
+
+    OrderResponse toResponse(Order order);
+
+    List<OrderResponse> toResponseList(List<Order> orders);
+}
+```
+
+## ApiResponse Wrapper Pattern
+
+```java
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ApiResponse<T> {
+    private boolean success;
+    private T data;
+    private String message;
+    private String errorCode;
+    private LocalDateTime timestamp;
+
+    public static <T> ApiResponse<T> success(T data) {
+        return ApiResponse.<T>builder()
+                .success(true)
+                .data(data)
+                .timestamp(LocalDateTime.now())
+                .build();
+    }
+
+    public static <T> ApiResponse<T> error(String errorCode, String message) {
+        return ApiResponse.<T>builder()
+                .success(false)
+                .errorCode(errorCode)
+                .message(message)
+                .timestamp(LocalDateTime.now())
+                .build();
+    }
+}
+```
+
+## Facade Pattern (optional orchestration layer)
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderFacade {
+
+    private final OrderService orderService;
+    private final InventoryService inventoryService;
+    private final NotificationService notificationService;
+
+    public OrderResponse createOrder(CreateOrderRequest request) {
+        // 1. Validate inventory
+        inventoryService.validateAvailability(request.getItems());
+        // 2. Create order
+        OrderResponse order = orderService.createOrder(request);
+        // 3. Reserve inventory
+        inventoryService.reserveItems(order.getId(), request.getItems());
+        // 4. Send confirmation
+        notificationService.sendOrderConfirmation(order);
+        return order;
+    }
+}
+```

package/core/modules/java-spring/module.yaml

@@ -0,0 +1,15 @@
+name: "Java Spring Boot"
+version: "1.0.0"
+description: "Spring Boot 3.x with layered architecture"
+language: "Java"
+framework: "Spring Boot"
+stack_type: "backend"
+default_layer_order:
+  - DTO
+  - Entity/Model
+  - Repository
+  - Service interface
+  - Service impl
+  - Facade (optional)
+  - Controller
+test_framework: "JUnit 5 + Mockito"

package/core/modules/java-spring/stack-profile.yaml

@@ -0,0 +1,28 @@
+build:
+  compile: "mvn clean install -DskipTests"
+  test: "mvn test"
+  run: "mvn spring-boot:run"
+
+architecture:
+  style: "Layered (Controller → Facade → Service → Repository)"
+  key_rules:
+    - "Controllers must not contain business logic"
+    - "Services own transaction boundaries (@Transactional)"
+    - "Repositories use Spring Data JPA"
+    - "Facades orchestrate multiple services (optional layer)"
+
+coding_standards:
+  naming:
+    classes: "PascalCase"
+    methods: "camelCase"
+    packages: "lowercase.snake_case"
+  patterns:
+    response_wrapper: "ApiResponse<T>"
+    mapping: "MapStruct"
+    exception_base: "ResourceNotFoundException"
+
+trace_tags:
+  implements: "@trace.implements={UC-ID}-SC{N}"
+  source: "@trace.source=specs/bdd/{domain}/{UC-ID}.feature"
+  verifies: "@trace.verifies={UC-ID}"
+  test_type: "@trace.test_type=unit|integration"