@alveolus/arch 0.2.0 → 0.4.0

package/docs/rules/tactical/no-loose-code.md

@@ -0,0 +1,171 @@
+---
+description: "Architecture rule: the domain and application layers contain only building blocks, types and constants of data, with no loose function, namespace or module state."
+---
+
+# no-loose-code
+
+The domain and the application contain building blocks, types and constants of data, and nothing
+else: every class extends a building block of `@alveolus/core`, and every function is a method.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-loose-code</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A plain class, a class with only static members or that extends an expression, a function, an enum, a namespace, a computed constant, module state, a statement run on load; anything but the module class in a composition root</dd>
+	<dt>Applies to</dt><dd>Files in <code>domain/</code> and <code>application/</code>, in every core bounded context and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-loose-code": "off"</code></a></dd>
+</dl>
+
+## Why
+
+Rounding an amount needs a few lines, so a `roundAmount` function lands in `pricing.ts`. The next
+helper goes next to it, then a `utils.ts` appears, and the model slowly dissolves into code that has
+no defined place and that no other rule knows how to treat.
+
+::: tip The fix
+Every element of the domain and the application is a building block. Rounding belongs to `Money`,
+a value object; a rule that no object owns goes in a `DomainService`. Each one has a home that
+people and agents can find, and the rest of the rules know what it is.
+:::
+
+## What it checks
+
+Every top-level statement of a file in `domain/` or `application/`. The list says what is allowed;
+anything else is reported:
+
+| Statement | Allowed when |
+| --- | --- |
+| An `import` or an `export` | Always. |
+| A `type` or an `interface`, a `declare global` block | Always. |
+| A class | It extends a building block of `@alveolus/core` by its name, directly or through your own base class, and has at least one member that is not static. A mixin, a cast or a constant in `extends` hides what the class is. |
+| A `const` | Its value is plain data: a literal, an array or object of data, arithmetic or a template on data, a reference to another constant, with `as const` or `satisfies` if you like. |
+| A function, or a constant holding one, even wrapped in a call, parentheses or `as` | Never. |
+| An object holding a method, a value computed by a call or `new`, a class expression | Never. |
+| `let` or `var`: state kept by the module | Never. |
+| An `enum`, a `namespace` | Never. |
+| A statement run when the module loads, such as `registry.register(Order)` | Never. |
+
+The building blocks to extend are, in the domain, `AggregateRoot`, `Entity`, `ValueObject`,
+`Identifier`, `DomainEvent`, `DomainError`, `DomainService`, a `Port` or a repository; in the
+application, `CommandHandler`, `QueryHandler` or `EventTranslator`.
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title">Allowed</span>Types, interfaces and constants holding data, and functions written inside a method. A static factory next to instance members.</div>
+<div class="al-card"><span class="al-card-title">Composition roots</span>Its module class, imports and constants of data: a function, a computed constant or a statement around it is reported.</div>
+<div class="al-card"><span class="al-card-title">Adapter layers</span><code>driven/</code> and <code>driving/</code> hold classes: adapters, mappers, controllers, any class. A function, a computed constant or module state is reported there too.</div>
+<div class="al-card"><span class="al-card-title">Not checked</span>The files at the root of <code>src/</code>, such as <code>main.ts</code>.</div>
+</div>
+
+## What it reports
+
+```
+src/ordering/domain/services/pricing.ts
+  1  error  tactical/no-loose-code: PriceHelper extends no building
+  block: extend AggregateRoot, Entity, ValueObject, Identifier,
+  DomainEvent, DomainError, DomainService or a Port.
+  3  error  tactical/no-loose-code: The function roundAmount floats
+  outside any class: make it a method of a value object or of
+  a DomainService.
+  7  error  tactical/no-loose-code: The enum OrderStatus has no place
+  here: use a union of literal types, or a ValueObject when it
+  has behaviour.
+  12  error  tactical/no-loose-code: The constant Pricing is computed when
+  the module loads: keep top-level constants to plain data.
+
+src/ordering/domain/value-objects/utils.value-object.ts
+  3  error  tactical/no-loose-code: Utils only has static members: a class
+  of functions is no building block; make them methods of the
+  value object they work on, or of a DomainService.
+```
+
+In the application, the message lists `CommandHandler, QueryHandler or EventTranslator`.
+
+## Fix it
+
+### Find the building block it belongs to
+
+So that each piece of logic has a known home, replace each declaration with the building block that
+owns it:
+
+| Instead of | Write |
+| --- | --- |
+| A helper function, an object or a namespace of functions, a class of static helpers | A method of the value object it works on, or of a `DomainService` when no object owns it. |
+| A plain class (policy, calculator, specification) | A `DomainService`. |
+| A factory function | A static method of the aggregate, entity or value object. |
+| A mapper in the application | An `EventTranslator`, or a mapper in an adapter. |
+| An `enum` | A union of literal types, or a value object when the values have behaviour. |
+| A constant built by `new Currency("EUR")` | A static getter of the value object: `Currency.euro`. |
+| A counter or a cache in a module | State of an aggregate, or a port implemented by an adapter. |
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/services/pricing.ts]
+export class PriceHelper {}
+
+export function roundAmount(amount: number): number {
+	return Math.round(amount * 100) / 100;
+}
+
+export enum OrderStatus {
+	Draft,
+	Placed,
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/value-objects/money.value-object.ts]
+import { ValueObject } from "@alveolus/core";
+
+export class Money extends ValueObject<{ readonly amount: number }> {
+	rounded(): Money {
+		return new Money({
+			amount: Math.round(this.props.amount * 100) / 100,
+		});
+	}
+}
+```
+
+</div>
+
+### Return business failures as domain errors
+
+So that callers see in the signature what can go wrong, a business failure is not a subclass of
+`Error`: it is a `DomainError`, returned in a [`Result`](../../core/utilities/result.md). A
+technical failure is thrown by an adapter, never by the domain.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/errors/price-too-high.error.ts]
+export class PriceTooHigh extends Error {}
+```
+
+```ts [✅ Prefer: src/ordering/domain/errors/price-too-high.error.ts]
+import { DomainError } from "@alveolus/core";
+
+export class PriceTooHigh extends DomainError<{ readonly max: number }> {}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- The methods of the module class in a composition root are not read: a business rule written in
+  `OrderingModule.discount()` goes unnoticed. The module only wires.
+- A constant may refer to a class, such as `[PlaceOrderHandler, GetOrderSummaryHandler]`: classes
+  are values that cannot be called, so they count as data.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-loose-code": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new code keeps to building blocks while you move the old helpers.
+
+## See also
+
+- [Building blocks](../../core/index.md), what each class can extend
+- [`tactical/no-misplaced-class`](./no-misplaced-class.md), for the folder of each building block
+- [`tactical/no-thrown-failure`](./no-thrown-failure.md), for business failures
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-misplaced-class.md

@@ -0,0 +1,146 @@
+---
+description: "Architecture rule: each class lives in the folder of its kind, in a file named after that kind, one class per file."
+---
+
+# no-misplaced-class
+
+Each class lives in the folder of its kind, in a file whose name ends with that kind, one class per
+file.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-misplaced-class</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A class in the wrong folder or file, two classes in one file</dd>
+	<dt>Applies to</dt><dd>Every class that extends a building block, in every core bounded context and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-misplaced-class": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`OrderId` and `Order` are declared together in `domain/aggregates/order.ts`, because that is where the task
+started. The next developer looks for the identifier in `value-objects/` and does not find it; the
+next agent creates a second one there. The shared layout only helps if it holds.
+
+::: tip The fix
+The kind of a class decides where it lives: `Order` extends `AggregateRoot`, so it is in
+`domain/aggregates/order.aggregate.ts`, alone. Finding a concept takes no search, a review shows at
+a glance what a change touches, and an agent puts new code where the existing code is.
+:::
+
+## What it checks
+
+Two things, in every file:
+
+<div class="al-cards al-cards-2">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>One class per file</span>The types that belong to a class, such as its snapshot or its command input, stay in its file.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>The folder and file of its kind</span>A class that extends a building block is where the table below says, whatever its name.</div>
+</div>
+
+| Extends | Folder | File name ends with |
+| --- | --- | --- |
+| `AggregateRoot` | `domain/aggregates/` | `.aggregate.ts` |
+| `Entity` | `domain/entities/` | `.entity.ts` |
+| `Identifier` | `domain/value-objects/` | `.identifier.ts` |
+| `ValueObject` | `domain/value-objects/` | `.value-object.ts` |
+| `DomainEvent` | `domain/events/` | `.event.ts` |
+| `DomainError` | `domain/errors/` | `.error.ts` |
+| `DomainService` | `domain/services/` | `.service.ts` |
+| `CommandRepository`<br>`QueryRepository` | `domain/repositories/` | `.repository.ts` |
+| `Port`, abstract | `domain/ports/` | `.port.ts` |
+| `CommandHandler` | `application/commands/` | `.command.ts` |
+| `QueryHandler` | `application/queries/` | `.query.ts` |
+| `EventTranslator` | `application/translators/` | `.translator.ts` |
+| a port, concrete | `driven/<technology>/adapters/` | `.adapter.ts` |
+
+A marker fixes the place of its class, whatever the class extends: a class that implements
+`AntiCorruptionLayer` is an adapter in `driven/<technology>/adapters/*.adapter.ts`, a class that
+implements `OpenHostService` lives under `driving/<technology>/`, with any file name. A command
+handler marked as an anti-corruption layer is reported. Classes that extend no building block, such as a controller
+or a module, are not placed by this rule.
+
+## What it reports
+
+```
+src/ordering/domain/aggregates/order.ts
+  3  error  tactical/no-misplaced-class: OrderId belongs in
+  domain/value-objects/*.identifier.ts.
+  5  error  tactical/no-misplaced-class: Order shares its file
+  with OrderId: one class per file.
+```
+
+A class that shares its file is reported for that only: its place is checked once it has a file
+of its own.
+
+## Fix it
+
+### Move each class to the file of its kind
+
+Split the file, then move each class to the folder and file name the message gives. Import the
+others from their new place.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.ts]
+import { AggregateRoot, Identifier } from "@alveolus/core";
+
+export class OrderId extends Identifier<string, "OrderId"> {}
+
+export class Order extends AggregateRoot<OrderId> {}
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+import { AggregateRoot } from "@alveolus/core";
+
+import type { OrderId } from "../value-objects/order-id.identifier";
+
+export class Order extends AggregateRoot<OrderId> {}
+```
+
+</div>
+
+### Keep the types of a class in its file
+
+A snapshot, a command input or an error union is not a class: it stays next to the class it
+belongs to, and the rule does not report it.
+
+```ts [src/ordering/application/commands/place-order.command.ts]
+export interface PlaceOrder {
+	readonly orderId: string;
+}
+
+export type PlaceOrderError =
+	| OrderNotFound
+	| OrderAlreadyPlaced
+	| EmptyOrder;
+
+export class PlaceOrderHandler extends CommandHandler<
+	PlaceOrder,
+	void,
+	PlaceOrderError
+> { … }
+```
+
+## Limits
+
+::: warning What the rule cannot see
+- A class that extends no building block: it has no place to be in, so the rule leaves it alone;
+  `tactical/no-loose-code` reports it in the domain and the application.
+- The file name and the class name: `order.aggregate.ts` may declare `Invoice`. The suffix is
+  checked, the stem is not.
+- Types and interfaces: a `View` in `domain/views/` is a type, and the rule places classes.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-misplaced-class": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new code keeps the layout while you move the old one.
+
+## See also
+
+- [Project layout: folders and file names](../../guide/project-layout.md#folders-and-file-names)
+- [`tactical/no-loose-code`](./no-loose-code.md), so that every class has a kind
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-public-field.md

@@ -0,0 +1,113 @@
+---
+description: "Architecture rule: an aggregate, an entity, a value object or an identifier keeps its state private and exposes it through getters."
+---
+
+# no-public-field
+
+An aggregate, an entity, a value object or an identifier keeps its state private: nothing outside
+changes it, and what callers need is read through a getter.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-public-field</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A public instance field, declared or as a constructor parameter, <code>readonly</code> or not</dd>
+	<dt>Applies to</dt><dd>Every class that extends <code>AggregateRoot</code>, <code>Entity</code>, <code>ValueObject</code> or <code>Identifier</code>, in core bounded contexts and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-public-field": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`Account` has `public balance = 0`. The withdraw handler checks the balance and subtracts the
+amount itself; the next handler does the same with a slightly different check. The rule "an
+account never goes below its overdraft" now lives in four handlers, and the aggregate is a bag of
+fields: the model is anemic, and the day the rule changes, nobody finds every copy.
+
+::: tip The fix
+The state is private, and changes through a method that returns a `Result`: `account.withdraw(amount)`.
+A value the outside needs to read is a getter. The rule lives once, where the state is.
+:::
+
+## What it checks
+
+Every instance field of a class that extends one of the four building blocks:
+
+| Field | Allowed |
+| --- | --- |
+| `private balance`, `protected readonly opened` | ✅ |
+| `constructor(private readonly currency: string)` | ✅ |
+| `get balance(): Money` | ✅ |
+| `public static readonly limit = 100` | ✅ |
+| `public balance = 0`, `public readonly currency` | ❌ |
+| `constructor(public readonly owner: string)` | ❌ |
+
+A `readonly` public field is reported too: a value object of it can still be mutated, and the
+getter keeps the shape of the class free to change.
+
+## What it reports
+
+```
+src/ledger/domain/aggregates/account.aggregate.ts
+  4  error  tactical/no-public-field: Account.balance is a public field:
+     keep the state private, and expose what callers need through a
+     getter.
+```
+
+## Fix it
+
+### Change the state through a method
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ledger/domain/aggregates/account.aggregate.ts]
+export class Account extends AggregateRoot<AccountId> {
+	public balance = 0;
+}
+
+// in a handler
+if (account.balance >= amount) {
+	account.balance -= amount;
+}
+```
+
+```ts [✅ Prefer: src/ledger/domain/aggregates/account.aggregate.ts]
+export class Account extends AggregateRoot<AccountId> {
+	private balance = 0;
+
+	get currentBalance(): number {
+		return this.balance;
+	}
+
+	withdraw(amount: number): Result<void, InsufficientFunds> {
+		if (this.balance < amount) {
+			return err(new InsufficientFunds({ amount }));
+		}
+		this.balance -= amount;
+		return ok();
+	}
+}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- A getter that returns a mutable object, such as the array of lines: a caller can push into it.
+  Return a copy, or a readonly type.
+- A `protected` field: a subclass may change it. The rule stops the outside, not the hierarchy.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-public-field": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new fields stay private while you move the rules back into the aggregates.
+
+## See also
+
+- [Aggregates](../../core/domain/aggregates.md) and [Entities](../../core/domain/entities.md), what is checked
+- [`tactical/no-thrown-failure`](./no-thrown-failure.md), which makes every change return a `Result`
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-stateful-service.md

@@ -0,0 +1,102 @@
+---
+description: "Architecture rule for domain services: a domain service is stateless and holds configuration only, never a port, a repository or another service."
+---
+
+# no-stateful-service
+
+A domain service holds configuration only: the command handler passes it what it needs.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-stateful-service</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A domain service that holds a port, a repository, another service or any class other than a value object</dd>
+	<dt>Applies to</dt><dd>The constructor parameters and fields of every <code>DomainService</code> of a core bounded context or the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-stateful-service": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`OrderLimit` receives `Orders` to count the orders of a customer. The rule now loads data on its
+own, a query handler that uses it can write, and testing it needs a repository. A domain service
+is a stateless operation: it is given the aggregates and values it works on.
+
+::: tip The fix
+The command handler loads what the rule needs and passes it to the service method. The service
+keeps only its configuration, such as a limit or a rate.
+:::
+
+## What it checks
+
+Every constructor parameter and every field of each `DomainService`:
+
+| Holds | Allowed |
+| --- | --- |
+| A plain value such as a `number` or a `string` | ✅ |
+| A value object, an identifier | ✅ |
+| A class of a package listed in `domainDependencies` | ✅ |
+| A `Port`, a `CommandRepository`, a `QueryRepository` | ❌ |
+| Another `DomainService`, an aggregate, an entity, a handler | ❌ |
+| Any other class of the project | ❌ |
+
+## What it reports
+
+```
+src/ordering/domain/services/order-limit.service.ts
+  4  error  tactical/no-stateful-service: The DomainService OrderLimit holds
+  Orders, a CommandRepository: a domain service holds configuration
+  only; the command handler passes it what it needs.
+```
+
+## Fix it
+
+### Pass what the rule needs to the method
+
+So that the service stays a pure operation, the command handler loads the data and passes it in.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/services/order-limit.service.ts]
+export class OrderLimit extends DomainService {
+	constructor(private readonly orders: Orders) {
+		super();
+	}
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/services/order-limit.service.ts]
+export class OrderLimit extends DomainService {
+	constructor(private readonly maxLinesForNewCustomers: number) {
+		super();
+	}
+
+	check(order: Order, customer: Customer): Result<void, OrderTooLarge> {
+		// …
+	}
+}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- A port passed to a method of the service, call after call: the rule checks what the service
+  holds, not what it receives. In review, a domain service method takes aggregates and values.
+- State reached through a module: the service has no field, but reads a constant that holds a
+  connection. `tactical/no-loose-code` reports the constant; the rule does not see the read.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-stateful-service": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new services stay stateless while you rework the old ones.
+
+## See also
+
+- [Domain services](../../core/domain/domain-services.md), what is checked
+- [Command handlers](../../core/application/command-handlers.md), which load what a service needs
+- [Rules](../index.md), every rule by category