Ship whole features with a team of three.

/// # Ordering
/// > Take a customer's order and see it through until it ships.
///
/// ## Operations
/// - `place-order`: take an order for a customer (`Orders.place`)
/// - `open-orders`: list what still has to ship (`Orders.open`)
/// - `ship-order`: hand an open order over to shipping (`Orders.ship`)
///
/// ## Requirements
/// ### R1: Place an order
/// - R1.1 — When a customer places an order with at least one line,
///   the slice shall list it as open.
/// - R1.2 — If an order has no lines, then the slice shall reject it.
///
/// ### R2: Ship an order
/// - R2.1 — When an open order is shipped, the slice shall no longer
///   list it as open.
/// - R2.2 — When an open order is shipped, the slice shall publish
///   `OrderShipped`.
/// - R2.3 — If the order has already shipped, then the slice shall
///   reject the request.
///
/// ## Events
/// - publishes `OrderShipped` (R2.2)
/// - listens to nothing
///
/// ## Entities
/// - `Order`: one document with its customer, lines and status
///
/// ## Out of scope
/// - prices and invoices (`billing`)
/// - parcels and carriers (`shipping`)
@ApplicationModule(displayName = "Ordering", allowedDependencies = {})
package com.acme.shop.ordering;

import org.springframework.modulith.ApplicationModule;

package com.acme.shop.ordering;

public class OrdersPage extends WebPage {

    @SpringBean
    private Orders orders;

    public OrdersPage() {
        var list = new WebMarkupContainer("list");
        add(list.setOutputMarkupId(true));

        var open = LoadableDetachableModel.of(orders::open);
        list.add(new ListView<>("orders", open) {
            @Override
            protected void populateItem(ListItem<Order> item) {
                Order order = item.getModelObject();
                String id = order.id();
                item.add(new Label("customer", order.customer()));
                item.add(Oat.Components.button("ship", "Ship", ajax -> {
                    orders.ship(id);
                    Oat.toast(ajax, "Shipped", OatVariant.SUCCESS);
                    ajax.add(list);
                }));
            }
        });
    }
}

<!-- Plain HTML. A designer can open it in a browser. -->
<h1>Open orders</h1>

<ul wicket:id="list">
    <li wicket:id="orders">
        <span wicket:id="customer">Jane Doe</span>
        <button wicket:id="ship">Ship</button>
    </li>
</ul>

package com.acme.shop.ordering.internal;

@Service
@Transactional
public class Orders {

    private final OrderRepository repository;
    private final ApplicationEventPublisher events;

    Orders(OrderRepository repository,
           ApplicationEventPublisher events) {
        this.repository = repository;
        this.events = events;
    }

    public Order place(String customer, List<Order.Line> lines) {
        return repository.save(Order.open(customer, lines));
    }

    public List<Order> open() {
        return repository.findByShippedAtIsNull();
    }

    public void ship(String id) {
        var order = repository.findById(id).orElseThrow().ship();
        repository.save(order);
        // billing and shipping react to this; ordering never calls them
        events.publishEvent(new OrderShipped(order.id()));
    }
}

// OrderShipped.java, in the base package: other slices
// may use it; everything in internal stays hidden
public record OrderShipped(String orderId) {}

package com.acme.shop.ordering.internal;

// Stored as one document, lines included: no join table,
// no mapping layer, no migration script for a new field.
@Document("orders")
public record Order(@Id String id, String customer,
                    List<Line> lines, Instant shippedAt) {

    public record Line(String product, int quantity) {}

    public static Order open(String customer, List<Line> lines) {
        if (lines.isEmpty()) {
            throw new IllegalArgumentException("an order needs lines");
        }
        return new Order(null, customer, List.copyOf(lines), null);
    }

    public Order ship() {
        if (shippedAt != null) {
            throw new IllegalStateException("already shipped");
        }
        return new Order(id, customer, lines, Instant.now());
    }
}

// OrderRepository.java: the whole persistence layer
public interface OrderRepository
        extends MongoRepository<Order, String> {

    List<Order> findByShippedAtIsNull();
}

package com.acme.shop.ordering;

/// Each test starts with the id of the requirement it proves.
/// The requirements live in this slice's `package-info.java`.
@ApplicationModuleTest
// a real MongoDB in Docker; a replica set, so transactions work
@Import(MongoDbReplicaSetConfiguration.class)
class OrdersTests {

    static final List<Order.Line> ONE_WIDGET =
        List.of(new Order.Line("Widget", 1));

    @Autowired Orders orders;
    @Autowired OrderRepository repository;

    @BeforeEach
    void startEmpty() {
        repository.deleteAll();
    }

    @Test
    @DisplayName("R1.1 a placed order is listed as open")
    void placedOrderIsOpen() {
        var order = orders.place("ACME", ONE_WIDGET);

        assertThat(orders.open())
            .extracting(Order::id).containsExactly(order.id());
    }

    @Test
    @DisplayName("R1.2 an order without lines is rejected")
    void orderWithoutLinesIsRejected() {
        assertThatThrownBy(() -> orders.place("ACME", List.of()))
            .isInstanceOf(IllegalArgumentException.class);
    }

    @Test
    @DisplayName("R2.1 a shipped order is no longer open")
    void shippedOrderIsNotOpen() {
        var order = orders.place("ACME", ONE_WIDGET);

        orders.ship(order.id());

        assertThat(orders.open()).isEmpty();
    }

    @Test
    @DisplayName("R2.2 shipping an order publishes OrderShipped")
    void shippingPublishesOrderShipped(Scenario scenario) {
        var order = orders.place("ACME", ONE_WIDGET);

        scenario.stimulate(() -> orders.ship(order.id()))
            .andWaitForEventOfType(OrderShipped.class)
            .toArriveAndVerify(event ->
                assertThat(event.orderId()).isEqualTo(order.id()));
    }

    @Test
    @DisplayName("R2.3 an order cannot ship twice")
    void orderCannotShipTwice() {
        var order = orders.place("ACME", ONE_WIDGET);
        orders.ship(order.id());

        assertThatThrownBy(() -> orders.ship(order.id()))
            .isInstanceOf(IllegalStateException.class);
    }
}

class ArchitectureTests {

    ApplicationModules modules =
        ApplicationModules.of(ShopApplication.class);

    @Test
    void slicesStayOutOfEachOthersInternals() {
        // fails on cycles and on any use of another slice's
        // internal package, from the root too
        modules.verify();
    }

    @Test
    void followsTheFullstack4jRules() {
        // what verify() leaves alone: slice names, what a base package
        // holds, documents, events, pages, and no @Disabled tests
        Fullstack4jRules.builder(ShopApplication.class)
            .build()
            .checkAll();
    }

    @Test
    void documentsTheArchitecture() {
        new Documenter(modules).writeDocumentation();
    }
}

/// Keeps every slice's spec and its tests in step.
///
/// A requirement id in a slice's `package-info.java` with no test
/// naming it in its `@DisplayName` is a gap. A test naming an id the
/// spec doesn't have is drift. Either one fails the build.
class SpecTraceabilityTests {

    static final Path MAIN = Path.of("src/main/java");
    static final Path TEST = Path.of("src/test/java");

    static final Pattern REQUIREMENT = Pattern.compile(
        "^\\s*///\\s*-\\s*(R\\d+\\.\\d+)\\b", Pattern.MULTILINE);
    static final Pattern TESTED = Pattern.compile(
        "@(?:[\\w.]+\\.)?DisplayName\\(\\s*\"(R\\d+\\.\\d+)\\b");

    @TestFactory
    Stream<DynamicTest> everySliceMatchesItsSpec() throws IOException {
        try (var files = Files.walk(MAIN)) {
            return files
                .filter(file -> file.endsWith("package-info.java"))
                .filter(spec -> !ids(REQUIREMENT, spec).isEmpty())
                .map(spec -> MAIN.relativize(spec.getParent()))
                .map(slice -> dynamicTest(name(slice), () -> {
                    var required = ids(REQUIREMENT, MAIN.resolve(slice)
                        .resolve("package-info.java"));
                    var tested = testedIds(TEST.resolve(slice));
                    assertAll(
                        () -> assertThat(without(required, tested))
                            .as("requirements without a test")
                            .isEmpty(),
                        () -> assertThat(without(tested, required))
                            .as("tests without a requirement")
                            .isEmpty());
                }))
                .toList()
                .stream();
        }
    }

    static Set<String> testedIds(Path dir) {
        if (!Files.isDirectory(dir)) {
            return Set.of();
        }
        try (var files = Files.walk(dir)) {
            return files
                .filter(file -> file.toString().endsWith(".java"))
                .flatMap(file -> ids(TESTED, file).stream())
                .collect(toCollection(TreeSet::new));
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }

    static Set<String> ids(Pattern pattern, Path file) {
        try {
            return pattern.matcher(Files.readString(file)).results()
                .map(match -> match.group(1))
                .collect(toCollection(TreeSet::new));
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }

    static Set<String> without(Set<String> these, Set<String> those) {
        var rest = new TreeSet<>(these);
        rest.removeAll(those);
        return rest;
    }

    static String name(Path slice) {
        return slice.toString()
            .replace(slice.getFileSystem().getSeparator(), ".");
    }
}