@alveolus/arch 0.2.0 → 0.4.0

package/docs/rules/index.md

@@ -0,0 +1,185 @@
+---
+description: "Architecture checks for Domain-Driven Design in TypeScript: alveolus arch check reports every way a project drifts from its layers and bounded contexts."
+---
+
+# Rules
+
+`alveolus arch check` applies rules that each report one way a project drifts: a shortcut between
+bounded contexts, a framework leaking into the domain, a helper that lands nowhere in particular.
+
+<dl class="al-glance">
+	<dt>Command</dt><dd><code>npx alveolus arch check</code></dd>
+	<dt>Rule names</dt><dd><a href="#how-rules-are-named"><code>&lt;category&gt;/no-&lt;what it reports&gt;</code></a></dd>
+	<dt>Categories</dt><dd><a href="#strategic">Strategic</a>, <a href="#layers">Layers</a>, <a href="#tactical">Tactical</a></dd>
+	<dt>Default</dt><dd>Every rule on; test files never checked</dd>
+	<dt>Where</dt><dd><a href="#where-a-rule-applies">Every rule on a core context, the boundary rules on a supporting or generic one</a></dd>
+	<dt>Config</dt><dd><a href="#turn-a-rule-off"><code>rules</code></a> in <code>alveolus.config.ts</code></dd>
+</dl>
+
+## Why
+
+A review catches what a reviewer looks at. The import that crosses a boundary, the class in the
+wrong folder or the error thrown instead of returned slip through, one change at a time, and
+coding agents make more changes than anyone reviews.
+
+::: tip The fix
+Each architecture decision becomes a rule that runs on every change. A violation says where, what
+is wrong and what is allowed instead, so a developer or an agent can fix it without knowing the
+whole architecture.
+:::
+
+## How rules are named
+
+Every rule is named `<category>/no-<what it reports>`: the category says which part of the
+architecture it guards, the rest says what a violation is.
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><code>strategic/</code></span>Between bounded contexts: what may cross a boundary, and through which door.</div>
+<div class="al-card"><span class="al-card-title"><code>layers/</code></span>Inside a bounded context: which layer may depend on which, and what each one may import.</div>
+<div class="al-card"><span class="al-card-title"><code>tactical/</code></span>Inside the domain and the application: how building blocks are written and where they live.</div>
+</div>
+
+## Where a rule applies
+
+`subdomains` in `alveolus.config.ts` says which bounded contexts are
+[core, supporting or generic](../guide/project-layout.md#core-supporting-generic). A core context
+and the shared kernel are checked by every rule. A supporting or generic context is checked only
+by the rules about its boundary, the `strategic/` and `tooling/` ones: how it is written inside is
+its own business. The "Applies to" line of each rule page says which it is.
+
+## Strategic
+
+| Rule | Reports |
+| --- | --- |
+| [`strategic/no-cross-context-import`](./strategic/no-cross-context-import.md) | An import from another bounded context that is not its open host service, a composition root that re-exports. |
+| [`strategic/no-fat-shared-kernel`](./strategic/no-fat-shared-kernel.md) | An aggregate, a repository or a handler in the shared kernel. |
+| [`strategic/no-leaky-host-service`](./strategic/no-leaky-host-service.md) | An open host service that exposes a class of its context instead of the published language. |
+| [`strategic/no-unmapped-context`](./strategic/no-unmapped-context.md) | A context consuming one the context map does not allow, or two contexts that depend on each other. |
+
+## Layers
+
+In core bounded contexts and the shared kernel.
+
+| Rule | Reports |
+| --- | --- |
+| [`layers/no-driving-shortcut`](./layers/no-driving-shortcut.md) | A driving adapter reaching a repository, a port or an aggregate instead of calling a handler. |
+| [`layers/no-impure-domain`](./layers/no-impure-domain.md) | The domain importing a framework, a database or another layer. |
+| [`layers/no-outward-import`](./layers/no-outward-import.md) | A dependency pointing away from the domain, and a file outside the layers. |
+| [`layers/no-portless-adapter`](./layers/no-portless-adapter.md) | A driven adapter that extends no port, a port declared outside the domain. |
+
+## Tactical
+
+In core bounded contexts and the shared kernel.
+
+| Rule | Reports |
+| --- | --- |
+| [`tactical/no-aggregate-reference`](./tactical/no-aggregate-reference.md) | An aggregate holding another aggregate instead of its identifier, an entity held by two aggregates. |
+| [`tactical/no-foreign-command-dependency`](./tactical/no-foreign-command-dependency.md) | A command handler receiving a query repository, another handler or a plain class. |
+| [`tactical/no-foreign-query-dependency`](./tactical/no-foreign-query-dependency.md) | A query handler receiving what writes or changes state. |
+| [`tactical/no-loose-code`](./tactical/no-loose-code.md) | Code outside a building block in the domain or the application: a plain or static-only class, a class that extends an expression, a function, an enum, a namespace, module state, a computed constant; anything but the module in a composition root. |
+| [`tactical/no-misplaced-class`](./tactical/no-misplaced-class.md) | A class in the wrong folder or file, two classes in one file. |
+| [`tactical/no-public-field`](./tactical/no-public-field.md) | A public field on an aggregate, an entity, a value object or an identifier. |
+| [`tactical/no-stateful-service`](./tactical/no-stateful-service.md) | A domain service holding a port, a repository or another service. |
+| [`tactical/no-thrown-failure`](./tactical/no-thrown-failure.md) | A business failure thrown instead of returned. |
+
+## Tooling
+
+| Rule | Reports |
+| --- | --- |
+| [`tooling/no-loose-disable`](./tooling/no-loose-disable.md) | A disable comment that names no known rule, gives no reason, or disables nothing. |
+
+## Read a violation
+
+Violations are grouped by file. Each one gives the line, the rule, what is wrong and what is allowed
+instead:
+
+```
+src/ordering/application/commands/place-order.command.ts
+  4  error  layers/no-outward-import: The application layer imports
+  src/ordering/driven/pg/adapters/mailer.adapter.ts (ordering driven):
+  it may only import domain, application, published-language.
+```
+
+`--format json` gives the same information as JSON, with the symbol involved, for tools and
+agents.
+
+## Building blocks are recognised by inheritance
+
+The rules know what a class is from what it extends: `class Order extends AggregateRoot` is an
+aggregate, wherever it is and whatever its name. A class that extends one of your own base classes
+counts too, as long as that base class extends a building block of `@alveolus/core`.
+
+::: tip
+There are no decorators or naming conventions to learn: the class says what it is, and the rules
+take it at its word.
+:::
+
+## Every import counts
+
+The rules that check imports read every way a file can depend on another one, not only
+`import … from`:
+
+```ts
+import { Pool } from "pg";
+export { Pool } from "pg";
+type Pool = import("pg").Pool;
+const pg = await import("pg");
+const pg = require("pg");
+import pg = require("pg");
+```
+
+A global declared by the project, in a `declare global` block, counts as an import of the file that
+declares it.
+
+An import the analysis cannot see through counts as a file outside the project: one that does not
+resolve, such as a `.js` file without types, one whose path is computed at runtime, or one that is
+ignored, such as a test file. No layer imports it: only the composition root and the files at the
+root of `src/` may.
+
+```
+src/ordering/domain/services/pricing.service.ts
+  2  error  layers/no-impure-domain: The domain imports
+  src/ordering/domain/services/db.spec.ts (ignored by the analysis):
+  it may only import the domain.
+```
+
+## Set the level of a rule
+
+Every rule reports an `error` by default, and an error fails the check. In `alveolus.config.ts`,
+lower a rule to `warn` or `info`, which report without failing, or turn it `off`, with its full
+name:
+
+```ts [alveolus.config.ts]
+export default defineConfig({
+	boundedContexts: { ordering: "ordering" },
+	contextMap: { ordering: { consumes: [] } },
+	root: "src",
+	rules: { "tactical/no-misplaced-class": "off", "tactical/no-public-field": "warn" },
+	subdomains: { core: ["ordering"] },
+});
+```
+
+`warn` and `info` are the way in on an existing project: a rule reports for a while, the team
+fixes, then it becomes an error.
+
+To turn one violation off where it stands, with a reason, write a disable comment above the line:
+see [Getting started](../guide/getting-started.md#turn-a-violation-off). To adopt the rules on an
+existing project without turning them off, record the current violations in a baseline: see
+[Getting started](../guide/getting-started.md#adopt-it-on-an-existing-project).
+
+Tests and their companions (`*.spec.ts`, `*.test.ts`, `*.e2e-spec.ts`, `*.fixture.ts`, `*.stories.ts`,
+`__tests__/`, `__mocks__/`) are never checked, and production code may not
+import them.
+
+## What the rules cannot see
+
+The rules read the code, not what it does at run time: a port whose adapter reads the views, an
+interface shaped like an aggregate, or an anti-corruption layer that passes data through untouched
+all look right. Each rule page lists its limits in a **Limits** section, with what to watch for in
+review. A file that matches `ignore` in `alveolus.config.ts` is not analysed at all: review a
+change to `ignore` as you would review a rule turned off.
+
+## See also
+
+- [Getting started](../guide/getting-started.md), to configure and run the checks
+- [Project layout](../guide/project-layout.md), the layout the rules keep

package/docs/rules/layers/no-driving-shortcut.md

@@ -0,0 +1,119 @@
+---
+description: "Architecture rule: a driving adapter calls the command and query handlers, and never reaches a repository, a port or an aggregate of the domain itself."
+---
+
+# no-driving-shortcut
+
+A driving adapter calls the command and query handlers: it never reaches a repository, a port, an
+aggregate or a domain service itself.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>layers/no-driving-shortcut</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#layers">Layers</a>: what each layer may depend on</dd>
+	<dt>Reports</dt><dd>A file of <code>driving/</code> that imports a <code>CommandRepository</code>, a <code>QueryRepository</code>, a <code>Port</code>, an <code>AggregateRoot</code>, an <code>Entity</code> or a <code>DomainService</code></dd>
+	<dt>Applies to</dt><dd>Every file in <code>driving/</code>, in every core bounded context and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"layers/no-driving-shortcut": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`OrdersController` injects `Orders`, loads the order, calls `place()` and saves it: the use case
+now lives in the controller. The next entry point, a message consumer, copies those lines; the
+transaction, the outbox and the events that `PlaceOrderHandler` handles are skipped, and the
+rules that `no-foreign-command-dependency` keeps on handlers do not apply to a controller.
+
+::: tip The fix
+A driving adapter translates a request into a command or a query, calls its handler, and
+translates the `Result` into a response. The use case exists once, in the application.
+:::
+
+## What it checks
+
+Every import of a file in `driving/` that points to a file of the project:
+
+| Imported class | Allowed |
+| --- | --- |
+| A `CommandHandler`, a `QueryHandler`, an `EventTranslator` | ✅ |
+| A value object, an identifier, a domain error, a view, a representation | ✅ |
+| A `CommandRepository`, a `QueryRepository`, a `Port` | ❌ |
+| An `AggregateRoot`, an `Entity`, a `DomainService` | ❌ |
+
+A class counts by what it extends: `Orders` extends `CommandRepository<Order>`. `import type`
+counts too, since a dependency injected by type is a dependency. Every form of import counts, see
+[Every import counts](../index.md#every-import-counts).
+
+## What it reports
+
+```
+src/ordering/driving/http/orders.controller.ts
+  3  error  layers/no-driving-shortcut: Imports Orders, a CommandRepository:
+     a driving adapter calls the command and query handlers, never
+     the ports, repositories or aggregates of the domain.
+```
+
+## Fix it
+
+### Call the handler
+
+So that the use case exists once, the controller receives the handler and passes it a command.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/driving/http/orders.controller.ts]
+export class OrdersController {
+	constructor(private readonly orders: Orders) {}
+
+	async place(id: string): Promise<void> {
+		const order = await this.orders.findById(new OrderId(id));
+		order?.place();
+		await this.orders.save(order);
+	}
+}
+```
+
+```ts [✅ Prefer: src/ordering/driving/http/orders.controller.ts]
+export class OrdersController {
+	constructor(private readonly placeOrder: PlaceOrderHandler) {}
+
+	async place(id: string): Promise<void> {
+		const result = await this.placeOrder.handle({ orderId: id });
+		if (!result.ok) {
+			throw new BadRequestException(result.error.type);
+		}
+	}
+}
+```
+
+</div>
+
+### Read through a query
+
+So that a read goes through the same door, a controller that needs data calls a
+[query handler](../../core/application/query-handlers.md), never a query repository.
+
+## Limits
+
+::: warning What the rule cannot see
+- A handler injected and then bypassed: the controller may still receive a repository through a
+  framework token (`@Inject("ORDERS")`) typed as `unknown`. In review, a driving adapter has no
+  provider but handlers.
+- What the driving adapter does with a value object or an error: those stay importable to map
+  requests and responses.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "layers/no-driving-shortcut": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new entry points go through the handlers while you move the old use cases out of the controllers.
+
+## See also
+
+- [Command handlers](../../core/application/command-handlers.md) and
+  [Query handlers](../../core/application/query-handlers.md), what a driving adapter calls
+- [`layers/no-outward-import`](./no-outward-import.md), what each layer may import
+- [Project layout: layers](../../guide/project-layout.md#layers)
+- [Rules](../index.md), every rule by category

package/docs/rules/layers/no-impure-domain.md

@@ -0,0 +1,191 @@
+---
+description: "Architecture rule: the domain layer depends on nothing but itself and @alveolus/core, with no ORM, framework or infrastructure import."
+---
+
+# no-impure-domain
+
+The domain depends on nothing but itself: its own domain, the domain of the shared kernel and the
+domain building blocks of `@alveolus/core`.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>layers/no-impure-domain</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#layers">Layers</a>: what each layer may depend on</dd>
+	<dt>Reports</dt><dd>The domain importing a framework, a database, another layer or a package not allowed, using a global of the host, reading the clock or drawing a random value</dd>
+	<dt>Applies to</dt><dd>Every file in <code>domain/</code>, in every core bounded context and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"layers/no-impure-domain": "off"</code></a></dd>
+</dl>
+
+## Why
+
+The `Order` aggregate carries TypeORM decorators so that it can be saved as is, and calls a mailer
+when it is placed. Upgrading the ORM now means touching the business rules, and testing that an
+empty order is refused needs a database and an SMTP server.
+
+::: tip The fix
+The domain imports nothing technical. Storage and email are [ports](../../core/domain/ports.md)
+declared by the domain and implemented by driven adapters. The business rules change when the
+business does, not when a library does, and run in a test without any infrastructure.
+:::
+
+## What it checks
+
+Every import of a file in `domain/`, in a bounded context or in the shared kernel:
+
+| Import | Allowed when |
+| --- | --- |
+| A file of the project | It is in the `domain/` of the same context or of the shared kernel. |
+| `@alveolus/core` | Every imported name is a domain building block or part of `Result`: `AggregateRoot`, `Entity`, `ValueObject`, `Identifier`, `DomainEvent`, `DomainError`, `DomainService`, `Port`, `Clock`, `IdGenerator`, `CommandRepository`, `QueryRepository`, `View`, `Result`, `ok`, `err`, `map`, `mapErr`, `andThen`, `combine` and their `Any…` types. |
+| Any other package | It is listed in `domainDependencies`; when its entry lists names, every imported name is one of them. |
+
+Importing from the root `@alveolus/core` is fine: the rule checks each imported name, not the path.
+
+Every form of import counts, see [Every import counts](../index.md#every-import-counts).
+
+### Globals
+
+A global is used without an import, so the rule reads every global the domain uses:
+
+| Global | Allowed when |
+| --- | --- |
+| An ECMAScript built-in: `Array`, `Map`, `JSON`, `Math`, `Promise`, `Intl`… | Always, except `Date.now()`, `new Date()` without argument, `Date()` and `Math.random()`, which read the clock or draw a random value. |
+| A global of the host: `fetch`, `process`, `console`, `setTimeout`, `crypto`, a DOM type such as `Response`… | Never. |
+| A global declared by the project, in a `declare global` block | As if the domain imported the file that declares it. |
+
+The rule tells them apart by where they are declared: the ECMAScript library of TypeScript, the
+types of the host (DOM, Node), or a file of the project. A local variable named `fetch` is not a
+global.
+
+## What it reports
+
+```
+src/ordering/domain/aggregates/order.aggregate.ts
+  1  error  layers/no-impure-domain: The domain imports @nestjs/common:
+  add it to domainDependencies if the domain really needs it.
+  2  error  layers/no-impure-domain: The domain imports UnitOfWork from
+  @alveolus/core: only domain building blocks and Result are allowed.
+  5  error  layers/no-impure-domain: The domain imports
+  src/ordering/driven/smtp/adapters/mailer.adapter.ts
+  (ordering driven): it may only import the domain.
+```
+
+A global of the host, the clock and randomness:
+
+```
+src/ordering/domain/services/pricing.service.ts
+  3  error  layers/no-impure-domain: The domain uses fetch, a global of the
+  host: reach it through a port.
+
+src/ordering/domain/aggregates/order.aggregate.ts
+  12  error  layers/no-impure-domain: The domain reads the system clock with
+  Date.now: receive the time from the Clock port.
+  13  error  layers/no-impure-domain: The domain draws a random value with
+  Math.random: receive it from a port, such as IdGenerator.
+```
+
+A name not allowed from a restricted package is reported as well:
+
+```
+  layers/no-impure-domain: The domain imports format from date-fns:
+  domainDependencies only allows addDays, isBefore.
+```
+
+## Fix it
+
+### Keep infrastructure behind a port
+
+So that the business rules survive a change of database, framework or mail provider, the domain
+declares what it needs as a port, and a driven adapter implements it. Transactions belong to the
+command handler, not to the domain.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.aggregate.ts]
+import { Injectable } from "@nestjs/common";
+import { AggregateRoot, UnitOfWork } from "@alveolus/core";
+import { Column, Entity } from "typeorm";
+
+import { Mailer } from "../../driven/smtp/adapters/mailer.adapter";
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+import { AggregateRoot, err, ok, type Result } from "@alveolus/core";
+
+import { Money } from "../../../shared-kernel/domain/value-objects/money.value-object";
+import { InvalidTotal } from "../errors/invalid-total.error";
+```
+
+</div>
+
+### Receive the time and random values
+
+So that a rule about dates gives the same answer in a test as in production, the domain never
+reads the clock or draws a random value itself. The command handler asks the
+[`Clock` and `IdGenerator` ports](../../core/domain/ports.md) and passes the values in.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.aggregate.ts]
+public place(): Result<void, never> {
+	this.placedAt = new Date();
+	return ok(undefined);
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+public place(at: Date): Result<void, never> {
+	this.placedAt = at;
+	return ok(undefined);
+}
+```
+
+</div>
+
+### Map storage outside the domain
+
+So that the aggregate is not shaped by its table, it exposes a snapshot, and the repository
+adapter maps that snapshot to its storage. See [Aggregates](../../core/domain/aggregates.md).
+
+## Allow a package
+
+Some packages belong in a domain, such as a decimal library for money. Declare them, with `true`
+to allow everything they export, or with the names you allow:
+
+```ts [alveolus.config.ts]
+export default defineConfig({
+	boundedContexts: { ordering: "ordering" },
+	contextMap: { ordering: { consumes: [] } },
+	domainDependencies: {
+		"date-fns": ["addDays", "isBefore"],
+		"decimal.js": true,
+	},
+	root: "src",
+	subdomains: { core: ["ordering"] },
+});
+```
+
+The packages of `domainDependencies` are allowed in the application too.
+
+## Limits
+
+::: warning What the rule cannot see
+- `domainDependencies` is not transitive: a package you allow may import anything itself. Allow
+  small, pure packages, such as a decimal or a date library.
+- A file that matches `ignore` in `alveolus.config.ts` is not analysed at all, and the domain may
+  import it: review a change to `ignore` as you would review a rule turned off.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "layers/no-impure-domain": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new code keeps the domain pure while you clean up the old one.
+
+## See also
+
+- [Project layout: layers](../../guide/project-layout.md#layers)
+- [Ports](../../core/domain/ports.md), to reach infrastructure from the domain
+- [`layers/no-outward-import`](./no-outward-import.md), the same idea for the other layers
+- [Rules](../index.md), every rule by category