@alveolus/arch 0.2.0 → 0.3.0

package/docs/rules/tactical/no-aggregate-reference.md

@@ -0,0 +1,139 @@
+---
+description: "Architecture rule: an aggregate refers to another aggregate by its identifier, never by holding it, to keep transactions and loading small."
+---
+
+# no-aggregate-reference
+
+An aggregate refers to another aggregate by its identifier, never by holding it.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-aggregate-reference</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A building block holding another aggregate, an entity held by two aggregates</dd>
+	<dt>Applies to</dt><dd>Every class that extends <code>AggregateRoot</code>, <code>Entity</code>, <code>ValueObject</code> or <code>DomainEvent</code>, in core bounded contexts and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-aggregate-reference": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`Order` holds a `Customer`. The next handler that places an order also updates the customer, in
+the same transaction, because it is right there. Loading an order now drags the customer along,
+two users editing either one conflict, and the two boundaries have merged without anyone deciding
+it.
+
+::: tip The fix
+The order keeps a `CustomerId`. Each aggregate stays a consistency boundary of its own, loaded,
+changed and saved alone. The command handler loads the customer when it really needs it, and
+changes to it happen in their own transaction, usually in reaction to an event.
+:::
+
+## What it checks
+
+### No aggregate held
+
+In every aggregate, entity, value object and domain event, no property, no constructor parameter,
+no value object props and no event payload holds another aggregate, however deep it is:
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title">Alone or in a union</span><code>customer: Customer | undefined</code></div>
+<div class="al-card"><span class="al-card-title">In a generic</span>An array, a tuple, a <code>Map</code>, a <code>Record</code>, a <code>Pick</code>, a <code>Promise</code>, or a generic of your own.</div>
+<div class="al-card"><span class="al-card-title">In an object type</span><code>{ customer: Customer }</code>, or an interface of the project.</div>
+<div class="al-card"><span class="al-card-title">Loaded lazily</span><code>load: () =&gt; Promise&lt;Customer&gt;</code>: what a function returns counts.</div>
+<div class="al-card"><span class="al-card-title">In value object props</span><code>ValueObject&lt;{ customer: Customer }&gt;</code></div>
+<div class="al-card"><span class="al-card-title">In an event payload</span><code>DomainEvent&lt;OrderId, { customer: Customer }&gt;</code></div>
+</div>
+
+The parameters of a function do not count: `onChange: (customer: Customer) => void` receives a
+customer, it does not hold one.
+
+### One owner per entity
+
+An entity other than a root belongs to one aggregate. The rule finds every entity each aggregate
+holds, directly or through its entities and value objects, and reports an entity held by two
+aggregates: the `Address` of a `Customer` cannot be held by an `Order` too.
+
+## What it reports
+
+```
+src/ordering/domain/aggregates/order.aggregate.ts
+  6  error  tactical/no-aggregate-reference: Order.customer holds the
+  aggregate Customer: reference it by its identifier instead.
+
+src/ordering/domain/value-objects/buyer.value-object.ts
+  3  error  tactical/no-aggregate-reference: Buyer holds the aggregate
+  Customer in its Props: reference it by its identifier instead.
+
+src/ordering/domain/aggregates/order.aggregate.ts
+  8  error  tactical/no-aggregate-reference: Order.shipping holds the entity
+  Address, which Customer holds too: an entity belongs to one
+  aggregate.
+```
+
+## Fix it
+
+### Hold the identifier instead
+
+So that each aggregate stays its own boundary, replace the property with the
+[identifier](../../core/domain/value-objects.md#identifier) of the other aggregate, and put that
+identifier in the snapshot.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.aggregate.ts]
+import { AggregateRoot } from "@alveolus/core";
+
+import type { Customer } from "./customer.aggregate";
+
+export class Order extends AggregateRoot<OrderId> {
+	private readonly customer: Customer;
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+import { AggregateRoot } from "@alveolus/core";
+
+import type { CustomerId } from "../value-objects/customer-id.identifier";
+
+export class Order extends AggregateRoot<OrderId> {
+	private readonly customerId: CustomerId;
+}
+```
+
+</div>
+
+### Give each aggregate its own entity
+
+When two aggregates need the same kind of data, each one owns its own: the customer keeps its
+`Address` entity, the order keeps a `ShippingAddress` value object copied from it when the order
+is placed. Changing the customer's address no longer changes past orders.
+
+### Load the other aggregate in the handler
+
+When a rule needs data from the other aggregate, the
+[command handler](../../core/application/command-handlers.md) loads it through its repository and
+passes what the rule needs to the business method. When the other aggregate must change too, a
+second handler does it on the event, in its own transaction.
+
+## Limits
+
+::: warning What the rule cannot see
+- An interface with the shape of another aggregate, such as `CustomerLike`: TypeScript types are
+  structural, so the rule cannot tell that a `Customer` will be passed in. Hold the identifier.
+- The parameters of a callback are not followed: `onChange: (customer: Customer) => void` is
+  accepted, and a closure can still capture the aggregate it receives.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-aggregate-reference": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new code keeps the rule while you rework the old references.
+
+## See also
+
+- [Aggregates: refer to other aggregates by identity](../../core/domain/aggregates.md)
+- [`tactical/no-thrown-failure`](./no-thrown-failure.md), another rule on aggregates
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-foreign-command-dependency.md

@@ -0,0 +1,119 @@
+---
+description: "Architecture rule for command handlers: a command handler receives command repositories, ports, event translators, domain services and value objects, never a view or another handler."
+---
+
+# no-foreign-command-dependency
+
+A command handler receives what changes aggregates and what they need: nothing that reads views,
+and no other handler.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-foreign-command-dependency</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A command handler that receives a query repository, another handler or a class that is no building block</dd>
+	<dt>Applies to</dt><dd>The constructor parameters and fields of every <code>CommandHandler</code> of a core bounded context or the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-foreign-command-dependency": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`PlaceOrderHandler` checks the order summary to decide whether the order may be placed. The view is
+shaped for reading: it may be denormalised, stale or partial, and it protects no rule. Injecting
+`GetOrderSummaryHandler` instead changes nothing, and injecting `PayOrderHandler` hides a second
+transaction inside the first one.
+
+::: tip The fix
+A command loads the aggregate and lets it decide. What a handler may receive is a short list:
+everything else is reported, so a new way of reaching a view does not slip through.
+:::
+
+## What it checks
+
+Every constructor parameter and every field of each `CommandHandler`, followed into `Pick`,
+generics and objects such as `deps: { … }`:
+
+| Receives | Allowed |
+| --- | --- |
+| A `CommandRepository` | ✅ |
+| A `Port`: `Clock`, `IdGenerator`, `UnitOfWork`, `Outbox`, your own ports | ✅ |
+| An `EventTranslator`, a `DomainService` | ✅ |
+| A value object, an identifier, a plain value such as a `number` | ✅ |
+| A class of a package listed in `applicationDependencies` | ✅ |
+| A `QueryRepository`, even though it is a `Port` | ❌ |
+| An `EventPublisher`, even though it is a `Port`: events leave through the outbox, and the relay publishes them | ❌ |
+| A `CommandHandler` or a `QueryHandler` | ❌ |
+| Any other class of the project | ❌ |
+
+A parameter counts by what its type extends: `OrderSummaries` extends
+`QueryRepository<OrderSummary>`.
+
+## What it reports
+
+```
+src/ordering/application/commands/place-order.command.ts
+  2  error  tactical/no-foreign-command-dependency: The CommandHandler
+  PlaceOrderHandler receives OrderSummaries, a QueryRepository: a
+  command handler receives command repositories, ports, event
+  translators, domain services and value objects.
+```
+
+## Fix it
+
+### Decide from the aggregate
+
+So that the decision is taken by what keeps the rules, a command handler loads the aggregate
+through its [command repository](../../core/domain/repositories.md) and lets it decide.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/application/commands/place-order.command.ts]
+export class PlaceOrderHandler extends CommandHandler<PlaceOrder> {
+	constructor(private readonly summaries: OrderSummaries) {
+		super();
+	}
+}
+```
+
+```ts [✅ Prefer: src/ordering/application/commands/place-order.command.ts]
+export class PlaceOrderHandler extends CommandHandler<PlaceOrder> {
+	constructor(private readonly orders: Orders) {
+		super();
+	}
+}
+```
+
+</div>
+
+### React to an event instead of calling another handler
+
+So that each command stays one transaction, a handler never calls another one. When placing an
+order must also do something else, the other handler reacts to the domain event, in its own
+transaction.
+
+## Limits
+
+::: warning What the rule cannot see
+- A plain `Port` whose adapter reads the views: the rule sees a port, not what its adapter does.
+  In review, a port named like a read (`OrderStats`, `…Summary`) used by a command is a query in
+  disguise.
+- An interface that a query repository happens to satisfy: an interface is no class, so the rule
+  cannot tell what will be injected. Type dependencies with the port class itself.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-foreign-command-dependency": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new commands keep to their list while you rework the old ones.
+
+## See also
+
+- [Command handlers](../../core/application/command-handlers.md), what is checked
+- [Repositories](../../core/domain/repositories.md) and [Ports](../../core/domain/ports.md), what a
+  command handler receives
+- [`tactical/no-foreign-query-dependency`](./no-foreign-query-dependency.md), the same list for
+  query handlers
+- [Rules](../index.md), every rule by category

package/docs/rules/tactical/no-foreign-query-dependency.md

@@ -0,0 +1,106 @@
+---
+description: "Architecture rule for query handlers: a query handler receives query repositories, ports that do not write and value objects, never what changes state."
+---
+
+# no-foreign-query-dependency
+
+A query handler receives what reads: nothing that writes or changes state.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-foreign-query-dependency</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A query handler that receives a command repository, an outbox, a unit of work, an event publisher, a handler, a domain service, an event translator or a class that is no building block</dd>
+	<dt>Applies to</dt><dd>The constructor parameters and fields of every <code>QueryHandler</code> of a core bounded context or the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-foreign-query-dependency": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`GetOrderSummaryHandler` receives the unit of work: a read can now change state, and the caller who
+asked a question gets a side effect too. A command handler or a domain service injected into it
+does the same, one step removed.
+
+::: tip The fix
+A query reads a view through a query repository, and writes nothing. A query that seems to need a
+write is a command, or a command followed by a query.
+:::
+
+## What it checks
+
+Every constructor parameter and every field of each `QueryHandler`, followed into `Pick`,
+generics and objects such as `deps: { … }`:
+
+| Receives | Allowed |
+| --- | --- |
+| A `QueryRepository` | ✅ |
+| A `Port` that does not write, such as `Clock` or your own ports | ✅ |
+| A value object, an identifier, a plain value such as a `number` | ✅ |
+| A class of a package listed in `applicationDependencies` | ✅ |
+| A `CommandRepository`, an `Outbox`, a `UnitOfWork`, an `EventPublisher` | ❌ |
+| A `CommandHandler`, a `QueryHandler`, a `DomainService`, an `EventTranslator` | ❌ |
+| Any other class of the project | ❌ |
+
+A parameter counts by what its type extends: `Orders` extends `CommandRepository<Order>`.
+
+## What it reports
+
+```
+src/ordering/application/queries/get-order-summary.query.ts
+  3  error  tactical/no-foreign-query-dependency: The QueryHandler
+  GetOrderSummaryHandler receives UnitOfWork, a UnitOfWork: a query
+  handler receives query repositories, ports that do not write, and
+  value objects.
+```
+
+## Fix it
+
+### Read a view, and nothing else
+
+So that a read never changes state, a [query handler](../../core/application/query-handlers.md)
+receives only query repositories.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/application/queries/get-order-summary.query.ts]
+constructor(
+	private readonly summaries: OrderSummaries,
+	private readonly unitOfWork: UnitOfWork,
+) {
+	super();
+}
+```
+
+```ts [✅ Prefer: src/ordering/application/queries/get-order-summary.query.ts]
+constructor(private readonly summaries: OrderSummaries) {
+	super();
+}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- A plain `Port` whose adapter writes: the rule sees a port, not what its adapter does. In review,
+  a port with a verb such as `mark…`, `record…` or `save…` has no place in a query.
+- An interface that a command repository happens to satisfy: an interface is no class, so the rule
+  cannot tell what will be injected. Type dependencies with the port class itself.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-foreign-query-dependency": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new queries keep to reading while you split the old ones.
+
+## See also
+
+- [Query handlers](../../core/application/query-handlers.md), what is checked
+- [Repositories](../../core/domain/repositories.md) and [Views](../../core/domain/views.md), what
+  a query reads
+- [`tactical/no-foreign-command-dependency`](./no-foreign-command-dependency.md), the same list for
+  command handlers
+- [Rules](../index.md), every rule by category

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