@alveolus/arch 0.2.0 → 0.3.0

package/docs/rules/layers/no-portless-adapter.md

@@ -0,0 +1,123 @@
+---
+description: "Architecture rule: every driven adapter implements a port declared by the domain, as hexagonal architecture requires."
+---
+
+# no-portless-adapter
+
+A driven adapter exists to implement a port: every class in `driven/<technology>/adapters/`
+extends one, and every port is declared by the domain.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>layers/no-portless-adapter</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#layers">Layers</a>: what each layer may depend on</dd>
+	<dt>Reports</dt><dd>A driven adapter that extends no port, a port declared outside the domain</dd>
+	<dt>Applies to</dt><dd>Every class in <code>driven/**/adapters/</code>, and every abstract class that extends <code>Port</code>, in core bounded contexts and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"layers/no-portless-adapter": "off"</code></a></dd>
+</dl>
+
+## Why
+
+A `Mailer` class in `driven/smtp/adapters/` sends emails, and the handler calls it directly. The
+application now depends on SMTP: testing a use case sends mail, and moving to an email API means
+rewriting the handler.
+
+::: tip The fix
+The domain says what it needs in its own words, as a [port](../../core/domain/ports.md); the
+adapter extends that port. The handler only knows the port, so the adapter can be swapped in a
+test or when the technology changes.
+:::
+
+## What it checks
+
+<div class="al-cards al-cards-2">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Every adapter extends a port</span>Every class in a <code>driven/**/adapters/</code> folder extends a <code>Port</code>, directly or through a repository, <code>Outbox</code>, <code>EventPublisher</code>, <code>UnitOfWork</code>, <code>Clock</code> or <code>IdGenerator</code>.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Every port lives in the domain</span>Every abstract class that extends <code>Port</code> is declared in <code>domain/ports/</code> or <code>domain/repositories/</code>.</div>
+</div>
+
+Abstract base classes for your adapters may also live in `driven/**/adapters/`, as long as they
+extend a port.
+
+## What it reports
+
+```
+src/ordering/driven/smtp/adapters/mailer.adapter.ts
+  1  error  layers/no-portless-adapter: Mailer is a driven adapter but
+  extends no Port: extend the port it implements.
+
+src/ordering/application/commands/notifications.ts
+  3  error  layers/no-portless-adapter: The port Notifications is declared
+  outside the domain: move it to domain/ports/ or
+  domain/repositories/.
+```
+
+## Fix it
+
+### Extend the port the adapter implements
+
+So that the application depends on what it needs and not on the technology, declare a port in the
+domain and make the adapter extend it. Name the adapter after its technology and its port.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/driven/smtp/adapters/mailer.adapter.ts]
+export class Mailer {
+	async send(to: string, body: string): Promise<void> {}
+}
+```
+
+```ts [✅ Prefer: src/ordering/driven/smtp/adapters/smtp-notifications.adapter.ts]
+import { Notifications } from "../../../domain/ports/notifications.port";
+
+export class SmtpNotifications extends Notifications {
+	async orderPlaced(email: string): Promise<void> {}
+}
+```
+
+</div>
+
+### Declare ports in the domain
+
+So that the domain knows every dependency it relies on, a port declared in the application or
+next to an adapter moves to `domain/ports/`, or to `domain/repositories/` for a repository.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/application/commands/notifications.ts]
+export abstract class Notifications extends Port {
+	abstract orderPlaced(email: string): Promise<void>;
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/ports/notifications.port.ts]
+export abstract class Notifications extends Port {
+	abstract orderPlaced(email: string): Promise<void>;
+}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- A class in `driven/<technology>/` outside `adapters/`, such as a mapper or an ORM entity: it is
+  not an adapter, so it needs no port, and nothing checks what it talks to.
+- A port written as an interface: a port is an abstract class that extends `Port`, and an adapter
+  that `implements` an interface is reported as extending no port.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "layers/no-portless-adapter": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new adapters extend a port while you wrap the old ones.
+
+## See also
+
+- [Ports](../../core/domain/ports.md), what an adapter implements
+- [Project layout: layers](../../guide/project-layout.md#layers)
+- [`tactical/no-misplaced-class`](../tactical/no-misplaced-class.md), for the folder and file name
+  of an adapter
+- [Rules](../index.md), every rule by category

package/docs/rules/strategic/no-cross-context-import.md

@@ -0,0 +1,140 @@
+---
+description: "Architecture rule: a bounded context is reached only through its open host service, from an anti-corruption layer or its composition root."
+---
+
+# no-cross-context-import
+
+A bounded context is closed: another context reaches it only through its open host service, from
+an anti-corruption layer or its composition root.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>strategic/no-cross-context-import</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#strategic">Strategic</a>: what crosses a bounded context</dd>
+	<dt>Reports</dt><dd>An import from another bounded context that is not its open host service, used where it may be</dd>
+	<dt>Applies to</dt><dd>Every file of every bounded context, whatever its subdomain, and of the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"strategic/no-cross-context-import": "off"</code></a></dd>
+</dl>
+
+## Why
+
+An adapter of ordering imports `Product` from the catalog domain, because it had the fields it
+needed. The two contexts now share one model without anyone deciding it: renaming a field in the
+catalog breaks ordering, and nothing showed the dependency until it broke.
+
+::: tip The fix
+One door on each side. The catalog exposes an
+[open host service](../../core/strategic/open-host-services.md); ordering calls it from an
+[anti-corruption layer](../../core/strategic/anti-corruption-layers.md) that translates the answer
+into its own model. Everything in between is free to change.
+:::
+
+## What it checks
+
+When a file of one bounded context imports a file of another one:
+
+<div class="al-cards al-cards-2">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Only open host services</span>Every imported name is a class that implements <code>OpenHostService</code>.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Only from an anti-corruption layer</span>In a core context, the importing file declares a class that implements <code>AntiCorruptionLayer</code>, or is the composition root of its context. A <a href="../../guide/project-layout.md#core-supporting-generic">supporting or generic context</a> calls the service from anywhere: it has no model to protect.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Composition roots meet freely</span>A composition root may import another context's composition root, to reach its open host services. It re-exports nothing, so that no other context reaches its model through it.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span>No foreign published language</span>The published language of another context is never imported, not even its types.</div>
+</div>
+
+The shared kernel imports no bounded context at all. Every context may import the shared kernel.
+
+Every form of import counts, see [Every import counts](../index.md#every-import-counts).
+
+## What it reports
+
+```
+src/ordering/driven/pg/adapters/stock.adapter.ts
+  1  error  strategic/no-cross-context-import: Imports
+  src/catalog/domain/aggregates/product.aggregate.ts (catalog domain):
+  only an OpenHostService of another bounded context may be imported.
+  2  error  strategic/no-cross-context-import: Imports the published language
+  of catalog: redeclare the fields you read in your own
+  published-language/.
+  3  error  strategic/no-cross-context-import: Uses the open host service of
+  catalog outside an AntiCorruptionLayer: translate it in an
+  anti-corruption layer.
+
+src/catalog/catalog.module.ts
+  2  error  strategic/no-cross-context-import: The composition root
+  re-exports Product: it exports its own module only, so that no
+  other context reaches through it.
+
+src/shared-kernel/domain/value-objects/money.value-object.ts
+  1  error  strategic/no-cross-context-import: The shared kernel imports no
+  bounded context, but imports
+  src/catalog/domain/value-objects/currency.value-object.ts
+  (catalog domain).
+```
+
+## Fix it
+
+### Go through an anti-corruption layer
+
+So that only one class knows the other context exists, declare in your domain a port that asks in
+your own words, and implement it in an anti-corruption layer that calls the open host service.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/driven/pg/adapters/stock.adapter.ts]
+import type { Product } from "../../../../catalog/domain/aggregates/product.aggregate";
+import type { ProductRepresentation } from "../../../../catalog/published-language/product.representation";
+```
+
+```ts [✅ Prefer: src/ordering/driven/catalog/adapters/catalog-price-list.adapter.ts]
+import type { AntiCorruptionLayer } from "@alveolus/core";
+
+import type { CatalogApi } from "../../../../catalog/driving/in-process/catalog-api";
+import { PriceList } from "../../../domain/ports/price-list.port";
+
+export class CatalogPriceList
+	extends PriceList
+	implements AntiCorruptionLayer
+{
+	constructor(private readonly catalog: CatalogApi) {
+		super();
+	}
+}
+```
+
+</div>
+
+### Redeclare the fields you read
+
+So that the upstream context can change its published language without breaking yours, the
+downstream context redeclares the fields it reads in its own `published-language/`, instead of
+importing the upstream types. When the open host service is called in the same process,
+TypeScript still checks that both shapes match, at the anti-corruption layer and nowhere else.
+
+### Keep the shared kernel independent
+
+So that a change in one context never reaches all the others, the shared kernel imports no
+bounded context. Move what it needs into the shared kernel, or keep it in the context that owns it.
+
+## Limits
+
+::: warning What the rule cannot see
+- The rule checks what an anti-corruption layer imports, not what it does with it: an adapter that
+  returns the open host service's answer as is, untranslated, is accepted. In review, the ACL
+  should build values of its own context.
+- A file that matches `ignore` in `alveolus.config.ts` is not analysed at all.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "strategic/no-cross-context-import": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new code keeps the boundaries while you remove the old shortcuts.
+
+## See also
+
+- [Project layout: bounded contexts](../../guide/project-layout.md#bounded-contexts)
+- [Open host services](../../core/strategic/open-host-services.md) and
+  [Anti-corruption layers](../../core/strategic/anti-corruption-layers.md)
+- [`layers/no-outward-import`](../layers/no-outward-import.md), for dependencies inside a context
+- [Rules](../index.md), every rule by category

package/docs/rules/strategic/no-fat-shared-kernel.md

@@ -0,0 +1,81 @@
+---
+description: "Architecture rule: the shared kernel holds value objects, ports and their adapters, never an aggregate, a repository or a handler."
+---
+
+# no-fat-shared-kernel
+
+The shared kernel stays small: value objects, identifiers, errors, ports and their adapters.
+Everything that changes with a business belongs to one bounded context.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>strategic/no-fat-shared-kernel</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#strategic">Strategic</a>: what crosses a bounded context</dd>
+	<dt>Reports</dt><dd>An <code>AggregateRoot</code>, an <code>Entity</code>, a <code>DomainEvent</code>, a <code>DomainService</code>, a repository, a handler or an <code>EventTranslator</code> in the shared kernel</dd>
+	<dt>Applies to</dt><dd>Every class of the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"strategic/no-fat-shared-kernel": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`Customer` is needed by every context, so it lands in the shared kernel. From then on every
+context depends on its shape, its rules and its repository; the KYC team cannot change how a
+customer is verified without a change that reaches the whole system. The shared kernel has become
+the one model nobody can touch.
+
+::: tip The fix
+Each context keeps its own view of a customer, under its own name: a `Payer` in payments, an
+`Applicant` in KYC, each with the fields it needs. What they share is small and stable: the
+`CustomerId`, the `Money` value object, the ports every context uses.
+:::
+
+## What it checks
+
+Every class in the shared kernel, by what it extends:
+
+| Class | Allowed |
+| --- | --- |
+| A `ValueObject`, an `Identifier`, a `DomainError` | ✅ |
+| A `Port`, abstract or implemented by an adapter: a tracer, an outbox, a clock | ✅ |
+| A representation of the published language | ✅ |
+| An `AggregateRoot`, an `Entity`, a `DomainEvent`, a `DomainService` | ❌ |
+| A `CommandRepository`, a `QueryRepository` | ❌ |
+| A `CommandHandler`, a `QueryHandler`, an `EventTranslator` | ❌ |
+
+## What it reports
+
+```
+src/shared-kernel/domain/aggregates/customer.aggregate.ts
+  3  error  strategic/no-fat-shared-kernel: Customer is an AggregateRoot in
+     the shared kernel: it belongs to one bounded context; the shared
+     kernel holds value objects, ports and their adapters.
+```
+
+## Fix it
+
+### Give the aggregate a home
+
+So that one team owns it, move the aggregate, its repository and its handlers to the context that
+decides its rules, and expose what the others need through an
+[open host service](../../core/strategic/open-host-services.md). The identifier stays in the
+shared kernel.
+
+## Limits
+
+::: warning What the rule cannot see
+- How big the shared kernel is: three hundred value objects pass. In review, a value object enters
+  the shared kernel when two contexts already have the same one, not before.
+- A folder declared as a bounded context named `shared` or `common` is a context, not the shared
+  kernel: the rule does not apply to it, and every other rule treats it as one more context.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "strategic/no-fat-shared-kernel": "off" },
+```
+
+## See also
+
+- [Project layout: shared kernel](../../guide/project-layout.md#shared-kernel)
+- [`strategic/no-unmapped-context`](./no-unmapped-context.md), the other way contexts get tied
+- [Rules](../index.md), every rule by category

package/docs/rules/strategic/no-leaky-host-service.md

@@ -0,0 +1,107 @@
+---
+description: "Architecture rule: an open host service speaks the published language, and never exposes a class of its bounded context."
+---
+
+# no-leaky-host-service
+
+An open host service speaks the published language: no class of its context appears in what it
+offers.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>strategic/no-leaky-host-service</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#strategic">Strategic</a>: what crosses a bounded context</dd>
+	<dt>Reports</dt><dd>A class of the project in the parameters, results, properties or getters of an open host service</dd>
+	<dt>Applies to</dt><dd>Every class that implements <code>OpenHostService</code></dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"strategic/no-leaky-host-service": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`CatalogApi.product` returns the `Product` aggregate, because it was already loaded. Ordering only
+imports the open host service, as the rules ask, yet it now holds the catalog's model: a change to
+`Product` breaks ordering, and ordering can call `product.changePrice()` from outside its
+boundary.
+
+::: tip The fix
+The service answers in the published language, plain JSON types that the catalog commits to keep
+stable. The model behind it can change freely.
+:::
+
+## What it checks
+
+Every public method, property and getter of a class that implements `OpenHostService`: its
+parameters and its result, followed into generics, `Promise`, arrays and object types.
+
+| Type | Allowed |
+| --- | --- |
+| A published-language type, a plain value | ✅ |
+| A class of the shared kernel, such as `Money` | ✅ |
+| A class of an installed package | ✅ |
+| Any other class of the project: an aggregate, an entity, a value object, an identifier, a domain event | ❌ |
+
+The constructor and private members are left out: they wire the service, other contexts never see
+them.
+
+## What it reports
+
+```
+src/catalog/driving/in-process/catalog-api.ts
+  6  error  strategic/no-leaky-host-service: CatalogApi.product exposes
+  Product, an AggregateRoot of catalog: an open host service speaks
+  the published language.
+```
+
+## Fix it
+
+### Answer in the published language
+
+So that the model can change without breaking other contexts, map it to a representation before it
+leaves the service, and take plain values as parameters.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/catalog/driving/in-process/catalog-api.ts]
+export class CatalogApi implements OpenHostService {
+	async product(id: ProductId): Promise<Product | undefined> {
+		return this.products.findById(id);
+	}
+}
+```
+
+```ts [✅ Prefer: src/catalog/driving/in-process/catalog-api.ts]
+export class CatalogApi implements OpenHostService {
+	async productById(productId: string): Promise<ProductRepresentation | undefined> {
+		const result = await this.getProduct.handle({ productId });
+		return result.ok ? result.value : undefined;
+	}
+}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- What a method returns as `unknown`, `any` or a plain object typed by hand with the fields of the
+  aggregate: the rule follows classes. In review, a method of an open host service returns a type of
+  `published-language/`.
+- A DTO class of the context is a leak too, on purpose: the published language is made of types,
+  not classes.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "strategic/no-leaky-host-service": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new methods answer in the published language while you map the old ones.
+
+## See also
+
+- [Open host services](../../core/strategic/open-host-services.md), what is checked
+- [Published Language](../../core/strategic/published-language.md), what the service answers in
+- [`strategic/no-cross-context-import`](./no-cross-context-import.md), which makes the service the
+  only door of a context
+- [Rules](../index.md), every rule by category

package/docs/rules/strategic/no-unmapped-context.md

@@ -0,0 +1,111 @@
+---
+description: "Architecture rule: a bounded context consumes only the contexts its context map declares, and two contexts never depend on each other."
+---
+
+# no-unmapped-context
+
+A bounded context consumes the contexts its context map declares, and nothing else: two contexts
+never depend on each other.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>strategic/no-unmapped-context</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#strategic">Strategic</a>: what crosses a bounded context</dd>
+	<dt>Reports</dt><dd>An import of another context that <code>contextMap</code> does not allow; without a map, an import that closes a cycle between contexts</dd>
+	<dt>Applies to</dt><dd>Every file of every bounded context</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"strategic/no-unmapped-context": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`Payments` reads balances from `Ledger`, through its open host service, as it should. A year
+later `Ledger` asks `Payments` whether a transfer is pending, through *its* open host service.
+Each import is clean on its own; together they tie the two contexts: neither can be deployed,
+extracted or rewritten without the other. In a system that lives for years, that knot is what
+turns "change this module" into "rewrite the application".
+
+::: tip The fix
+Write the context map, as DDD asks: which context is upstream of which. Declare it in
+`alveolus.config.ts`, and the code can no longer stray from it. A dependency that goes against
+the map is reversed: `Ledger` publishes an event, `Payments` reacts.
+:::
+
+## What it checks
+
+Every import from a file of one bounded context to a file of another, open host service or
+composition root alike:
+
+<div class="al-cards al-cards-2">
+<div class="al-card"><span class="al-card-title">With a context map</span>The importing context lists the imported one in <code>contextMap</code>. The map itself is checked when the configuration loads: an unknown context or a cycle is an error.</div>
+<div class="al-card"><span class="al-card-title">Without a context map</span>The imports observed form no cycle. An import that closes one is reported at both ends.</div>
+</div>
+
+Imports of the shared kernel are not consumptions: every context may import it.
+
+## What it reports
+
+```
+src/ledger/driven/payments/adapters/payment-status.adapter.ts
+  2  error  strategic/no-unmapped-context: ledger consumes payments, which the
+     context map does not allow: add payments to contextMap.ledger, or
+     reverse the dependency.
+```
+
+Without a map:
+
+```
+src/ledger/driven/payments/adapters/payment-status.adapter.ts
+  2  error  strategic/no-unmapped-context: ledger consumes payments, which
+     consumes ledger back: two contexts that depend on each other can
+     no longer change alone; declare a contextMap and reverse one
+     dependency.
+```
+
+## Fix it
+
+### Declare the context map
+
+So that the direction of every dependency is a decision, not an accident, list for each context
+the ones it consumes:
+
+```ts [alveolus.config.ts]
+export default defineConfig({
+	boundedContexts: { customers: "customers", ledger: "ledger", payments: "payments" },
+	contextMap: {
+		customers: [],
+		ledger: ["customers"],
+		payments: ["ledger", "customers"],
+	},
+	root: "src",
+});
+```
+
+A context absent from the map consumes nothing.
+
+### Reverse a dependency with an event
+
+So that `Ledger` stays upstream, it does not ask `Payments` anything: it publishes
+`TransferSettled` in its [published language](../../core/strategic/published-language.md), and
+`Payments` reacts to it.
+
+## Limits
+
+::: warning What the rule cannot see
+- A dependency that goes through the database, a queue or an HTTP call to another context's API
+  written as a string: the map covers imports. In review, every consumption of another context
+  is an import of its open host service.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "strategic/no-unmapped-context": "off" },
+```
+
+## See also
+
+- [Open host services](../../core/strategic/open-host-services.md) and
+  [Anti-corruption layers](../../core/strategic/anti-corruption-layers.md), how a context consumes another
+- [`strategic/no-cross-context-import`](./no-cross-context-import.md), which keeps the open host
+  service the only door
+- Vaughn Vernon, *Domain-Driven Design Distilled*, chapter 4, "Strategic Design with Context Mapping"
+- [Rules](../index.md), every rule by category