@alveolus/arch 0.1.0 → 0.3.0

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

package/docs/rules/tactical/no-thrown-failure.md

@@ -0,0 +1,162 @@
+---
+description: "Architecture rule: a business failure is returned in a Result, the domain and the application never throw, and exceptions stay in adapters."
+---
+
+# no-thrown-failure
+
+A business failure is a value: the aggregate returns it in a `Result`. The domain and the
+application never throw; exceptions stay in adapters, for technical failures.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tactical/no-thrown-failure</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tactical">Tactical</a>: how building blocks are written</dd>
+	<dt>Reports</dt><dd>A public method or function property of an aggregate or entity that returns no <code>Result</code>, a public setter, any <code>throw</code> or <code>Promise.reject</code> in the domain or the application</dd>
+	<dt>Applies to</dt><dd>Classes that extend <code>AggregateRoot</code> or <code>Entity</code>; every file in <code>domain/</code> and <code>application/</code>; in core bounded contexts and the shared kernel</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tactical/no-thrown-failure": "off"</code></a></dd>
+</dl>
+
+## Why
+
+`order.place()` throws `InvalidTotal` when the total is zero. Nothing in its signature says so: the
+controller that calls it does not catch it, and a customer gets an error 500 for a mistake they
+could have fixed.
+
+::: tip The fix
+The method returns `Result<void, InvalidTotal>`. The failure is in the type, and TypeScript makes
+every caller deal with it before it reaches the value. A method that changes state says whether it
+worked; reads are getters.
+:::
+
+## What it checks
+
+<div class="al-cards">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Public methods return a Result</span>Every public method of a class that extends <code>AggregateRoot</code> or <code>Entity</code>, and every public property holding a function, such as <code>place = () =&gt; …</code>, even when its return type is inferred. A <code>Promise</code> of a <code>Result</code> counts. Getters, static methods, <code>toSnapshot</code>, <code>equals</code> and the protocol methods <code>toString</code>, <code>toJSON</code>, <code>valueOf</code> and <code>[Symbol.…]</code> are left out.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>No setter</span>A public setter changes the state without saying whether it worked: a business method does it instead.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Nothing is thrown</span>No <code>throw</code> and no <code>Promise.reject</code> in <code>domain/</code> or <code>application/</code>, whatever is thrown: an <code>Error</code>, a domain error or an <code>unknown</code>. Adapters may throw on a technical failure, such as a lost connection.</div>
+</div>
+
+## What it reports
+
+```
+src/ordering/domain/aggregates/order.aggregate.ts
+  2  error  tactical/no-thrown-failure: Order.place must return a Result:
+  expose reads as getters and return business failures as
+  values.
+  4  error  tactical/no-thrown-failure: A failure is thrown: return it in a
+  Result instead.
+  9  error  tactical/no-thrown-failure: Order.status is a setter: change the
+  state through a business method that returns a Result.
+```
+
+## Fix it
+
+### Return the failure in a Result
+
+So that the caller sees what can go wrong, return the domain error with `err(…)` and success with
+`ok()`, and declare both in the return type.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.aggregate.ts]
+export class Order extends AggregateRoot<OrderId> {
+	place(total: number): void {
+		if (total <= 0) {
+			throw new InvalidTotal({ total });
+		}
+	}
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+export class Order extends AggregateRoot<OrderId> {
+	place(total: number): Result<void, InvalidTotal> {
+		if (total <= 0) {
+			return err(new InvalidTotal({ total }));
+		}
+		return ok();
+	}
+}
+```
+
+</div>
+
+### Expose reads as getters
+
+So that the public methods are the ones that change state, a read without parameters is a getter,
+which the rule leaves out.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/aggregates/order.aggregate.ts]
+isPlaced(): boolean {
+	return this.status === "placed";
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/aggregates/order.aggregate.ts]
+get isPlaced(): boolean {
+	return this.status === "placed";
+}
+```
+
+</div>
+
+A read that needs parameters, such as `canShip(date)`, returns `ok(…)`, or moves to a
+[`DomainService`](../../core/domain/domain-services.md) when it involves more than the aggregate.
+
+### Make the impossible state unrepresentable
+
+So that a guard against an impossible state needs no `throw`, keep the constructor private and
+build through a static factory that returns a `Result`: an invalid value never exists.
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/value-objects/quantity.value-object.ts]
+export class Quantity extends ValueObject<{ value: number }> {
+	constructor(value: number) {
+		if (value <= 0) {
+			throw new Error("A quantity is positive.");
+		}
+		super({ value });
+	}
+}
+```
+
+```ts [✅ Prefer: src/ordering/domain/value-objects/quantity.value-object.ts]
+export class Quantity extends ValueObject<{ value: number }> {
+	private constructor(value: number) {
+		super({ value });
+	}
+
+	static of(value: number): Result<Quantity, InvalidQuantity> {
+		return value > 0 ? ok(new Quantity(value)) : err(new InvalidQuantity({ value }));
+	}
+}
+```
+
+</div>
+
+## Limits
+
+::: warning What the rule cannot see
+- A promise rejected from its executor, `new Promise((_, reject) => reject(…))`, is not seen: only
+  `throw` and `Promise.reject` are.
+- A function of a package that throws is not seen either: the rule reads your code, not what it
+  calls. Wrap such a call in a `Result` where it happens.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tactical/no-thrown-failure": "off" },
+```
+
+On an existing project, prefer a [baseline](../../guide/getting-started.md#adopt-it-on-an-existing-project):
+new methods return a `Result` while you convert the old ones.
+
+## See also
+
+- [Result](../../core/utilities/result.md) and [Domain errors](../../core/domain/domain-errors.md), what the methods return
+- [Aggregates](../../core/domain/aggregates.md), whose business methods this rule checks
+- [`tactical/no-loose-code`](./no-loose-code.md), which keeps `extends Error` out of the domain
+- [Rules](../index.md), every rule by category

package/docs/rules/tooling/no-loose-disable.md

@@ -0,0 +1,98 @@
+---
+description: "Architecture rule: a disable comment names a rule and gives a reason, and is removed once the line below breaks the rule no more."
+---
+
+# no-loose-disable
+
+A disable comment turns one violation off, says which rule and why, and goes away with the
+violation.
+
+<dl class="al-glance">
+	<dt>Rule</dt><dd><code>tooling/no-loose-disable</code></dd>
+	<dt>Category</dt><dd><a href="/rules/#tooling">Tooling</a>: how the checks themselves are used</dd>
+	<dt>Reports</dt><dd>A <code>// alveolus-disable-next-line</code> comment that names no known rule, gives no reason, or disables nothing</dd>
+	<dt>Applies to</dt><dd>Every analysed file</dd>
+	<dt>Turn off</dt><dd><a href="#turn-it-off"><code>"tooling/no-loose-disable": "off"</code></a></dd>
+</dl>
+
+## Why
+
+A violation is sometimes right to keep for a while: a legacy import that a ticket will remove, a
+rule that does not fit one file yet. A comment above the line turns it off, where a reviewer sees
+it. Without a rule and a reason, the comment says nothing, and once the line is fixed it stays
+behind and hides the next violation.
+
+::: tip The fix
+Write the rule and the reason: `// alveolus-disable-next-line layers/no-impure-domain: legacy pool, ORD-412`.
+When the line breaks the rule no more, the comment is reported until it is removed.
+:::
+
+## What it checks
+
+Every `// alveolus-disable-next-line` comment:
+
+<div class="al-cards al-cards-2">
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">1</span>Names a rule</span>The id of a rule, as the rules page lists it. One rule per comment.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">2</span>Gives a reason</span>After a colon: why this line keeps its violation. Free text, read in review.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">3</span>Turns something off</span>The line below breaks that rule. A comment that disables nothing is reported.</div>
+<div class="al-card"><span class="al-card-title"><span class="al-card-step">4</span>Is counted</span>The summary says how many violations are disabled, and <code>--format json</code> lists them with their reason.</div>
+</div>
+
+A comment that names no rule, an unknown rule, or no reason disables nothing: the violation below
+is reported as well.
+
+## What it reports
+
+```
+src/ordering/domain/services/pricing.service.ts
+  1  error  tooling/no-loose-disable: The disable comment gives no reason:
+     write `// alveolus-disable-next-line layers/no-impure-domain:
+     <why this line keeps its violation>`.
+  4  error  tooling/no-loose-disable: The disable comment disables nothing:
+     the line below breaks layers/no-impure-domain no more; remove
+     the comment.
+```
+
+## Fix it
+
+### Say which rule, and why
+
+<div class="al-compare">
+
+```ts [❌ Avoid: src/ordering/domain/services/pricing.service.ts]
+// alveolus-disable-next-line
+import { Pool } from "pg";
+```
+
+```ts [✅ Prefer: src/ordering/domain/services/pricing.service.ts]
+// alveolus-disable-next-line layers/no-impure-domain: legacy pool, removed with ORD-412
+import { Pool } from "pg";
+```
+
+</div>
+
+### Remove the comment with the violation
+
+Once the line is fixed, the comment is reported: delete it. A disable comment never outlives what
+it disables.
+
+## Limits
+
+::: warning What the rule cannot see
+- Whether the reason is a good one: `: because` passes. The reason is for the reviewer.
+- A violation turned off is still a violation: for a whole file or a whole rule, prefer `ignore`
+  or `rules` in `alveolus.config.ts`, and for the past, the baseline.
+:::
+
+## Turn it off
+
+```ts [alveolus.config.ts]
+rules: { "tooling/no-loose-disable": "off" },
+```
+
+Disable comments then still work, but nothing checks them.
+
+## See also
+
+- [Getting started: turn a violation off](../../guide/getting-started.md#turn-a-violation-off)
+- [Rules](../index.md), every rule by category

package/package.json

@@ -22,7 +22,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "homepage": "https://alveolus.dev/",
   "keywords": [
@@ -47,9 +48,9 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && biome check --write package.json",
     "typecheck": "tsc -p tsconfig.json"
   }
 }