@ddd-ts-kit/eslint-plugin 0.0.0-stage → 0.1.1

package/docs/rules/context-extractable.md

@@ -0,0 +1,109 @@
+# ddd-ts-kit/context-extractable
+
+Architecture id: `context/extractable`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every file of a context, tests excluded; each check in the place named below.
+
+## Why
+
+A bounded context is a deployable unit in waiting. Moving one to its own service must change a composition root and adapters, never domain or application code. A join on another context's table, a variable shared through an import or a token borrowed from another module each turn that move into a rewrite.
+
+## Reported
+
+In `infrastructure/persistence/`:
+
+- `contextSchema('<other>')` or `schemaNameOf('<other>')` with the name of another context of the config
+- a string or template literal that reads as SQL and names `<other_schema>.` or `"<other_schema>".`, the schema of another context of the config
+
+In any file of a context:
+
+- `export let` and `export var`
+- an exported `const` holding `new Map`, `new Set`, `new WeakMap`, `new WeakSet`, `new Array`, an array literal or an object literal, when the same file changes it (`push`, `set`, `add`, `delete`, an assignment to a member, `Object.assign`, ...)
+
+In `<context>.module.ts`:
+
+- a name imported from another context, outside its `published-language/`, given to `bind`, `rebind`, `resolve`, or to `handledBy` and `toClass` (directly or in the dependency list)
+
+In a role file of a declared-style project (`stack.style: "declared"`; the files of the table below):
+
+- anything imported from a port file of another context: its `domain/repositories/*.repository.ts` and its `application/ports/*.port.ts`
+
+Incorrect:
+
+```ts
+// billing/infrastructure/persistence/drizzle-invoice.repository.ts
+await sql`select i.id, p.label from billing.invoices i join catalog.products p on p.id = i.product_id`;
+
+// billing/application/ports/rate-cache.ts
+export const rates = new Map<string, number>();
+export function remember(currency: string, rate: number): void {
+  rates.set(currency, rate);
+}
+
+// billing/billing.module.ts
+import { ProductReader } from '@/contexts/catalog/application/ports/product-reader.port.js';
+builder.query(GetPrice).public().handledBy(GetPriceHandler, [ProductReader]);
+
+// declared style: billing/application/queries/get-price/get-price.handler.ts
+import { ProductReader } from '@/contexts/catalog/application/ports/product-reader.port.js';
+
+@QueryHandler(GetPriceQuery, [ProductReader])
+export class GetPriceHandler {}
+```
+
+Correct:
+
+```ts
+// billing keeps its own projection, fed by catalog.product.listed
+await sql`select i.id, p.label from billing.invoices i join billing.products p on p.id = i.product_id`;
+
+// billing/billing.module.ts
+builder.bind(PriceSource).toClass(InProcessPriceSource, [QueryBus]).as('gateway');
+builder.query(GetPrice).public().handledBy(GetPriceHandler, [PriceSource]);
+
+// declared style: the port is one of billing, its gateway calls catalog
+import { PriceCatalog } from '@/contexts/billing/application/ports/price-catalog.port.js';
+
+@QueryHandler(GetPriceQuery, [PriceCatalog])
+export class GetPriceHandler {}
+```
+
+## Details
+
+The schema of a context is its name with dashes turned into underscores, as `schemaNameOf` computes it. A text reads as SQL when it holds one of `select`, `insert`, `update`, `delete`, `from`, `join`, `into`, `references`. The import of another context's internals is itself reported by `context/published-language-only`; this rule reports what is done with it.
+
+In the declared style there is no module file: a class names the ports it needs next to its decorator, so the import of a port is the wiring. The role files are:
+
+| File, relative to the context | Role |
+|---|---|
+| `application/commands/**/*.command.ts`, `application/queries/**/*.query.ts` | message |
+| `application/commands/**/*.handler.ts`, `application/queries/**/*.handler.ts` | handler |
+| `application/integration/handlers/**/*.integration-handler.ts` | integration event handler |
+| `application/event-handlers/**/*.event-handler.ts`, `application/integration/publishers/**/*.publisher.ts` | reaction to a domain event |
+| `application/authorization/**/*.policy.ts` | policy |
+| `application/scheduling/**/*.job.ts` | scheduled job |
+| `infrastructure/persistence/**/*.repository.ts`, `infrastructure/**/*.gateway.ts`, `infrastructure/**/*.adapter.ts` | adapter |
+
+Ports of the same context, of `@ddd-ts-kit/kernel`, of `@ddd-ts-kit/auth` and of the platform directory are what a role file wires with. An integration event definition imported from the published language of an upstream (`productListedV1`) is not a port and is not reported. A module file kept in a declared-style project is judged as in the explicit style, and an explicit-style project is judged as before.
+
+## Options
+
+None.
+
+`rules."context/extractable"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line context/extractable -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Only contexts listed under `contexts` in `ddd-ts-kit.config.json` are known as "another context".
+- A table reached through a query builder (`knex('catalog.products')`, `.withSchema('catalog')`, a Drizzle table object imported from the other context) is not read as SQL; the import of that table object is reported by `context/published-language-only`.
+- A column or an alias that happens to be called like another context (`catalog.id` where `catalog` is an alias) is reported: rename the alias.
+- SQL outside `infrastructure/persistence/` is not read.
+- A shared transaction (two contexts writing in one unit of work) is not visible in one file.
+- An exported container changed only by its importers is not seen; one never changed is taken for a constant. `Object.freeze` is not required.
+- In a role file only the port files of another context are reported: a port that another context declares elsewhere is reported by `context/published-language-only`, as any import of its internals.
+- A port of another context re-exported by a file of the importing context is not seen.
+- A foreign port that reaches the module through the platform or the shared kernel is not seen: `dependency-cruiser` and the generated test that boots each context alone close that gap.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files and from the config. This rule is the authority for the code.

package/docs/rules/context-published-language-is-a-contract.md

@@ -0,0 +1,47 @@
+# ddd-ts-kit/context-published-language-is-a-contract
+
+Architecture id: `context/published-language-is-a-contract`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `published-language/` of a context, tests excluded.
+
+## Why
+
+What a context publishes must be serializable and stable. A contract that imports the domain exposes the internal model under another name.
+
+## Reported
+
+- any import other than `publishedLanguageAllowedPackages` (default: the kernel, `@ddd-ts-kit/events`, `@ddd-ts-kit/validation` and the schema library of `stack.validation`) and other published languages
+
+Incorrect:
+
+```ts
+// src/contexts/billing/published-language/invoice-issued.v1.integration-event.ts
+import type { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.js';
+```
+
+Correct:
+
+```ts
+import { defineIntegrationEvent } from '@ddd-ts-kit/events';
+import { z } from 'zod';
+```
+
+## Details
+
+Static imports, type-only imports, `export ... from`, dynamic `import()`, `require()`, `import x = require()` and `import("...")` types are all read, through relative paths and the configured `importAlias`.
+
+## Options
+
+None. `publishedLanguageAllowedPackages` in `ddd-ts-kit.config.json` replaces the allow-list.
+
+`rules."context/published-language-is-a-contract"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line context/published-language-is-a-contract -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The target is classified by its path: a barrel in an allowed layer that re-exports a forbidden one is not followed. `dependency-cruiser` (see `pipeline/depcruise-config.mjs`) resolves the real graph and closes that gap.
+- A computed specifier (`import(name)`) is not judged.
+- `tsconfig` paths other than `importAlias` are not resolved.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from a regex reading of the file. This rule is the authority for the import; the CLI stays the authority for the config (`config/valid`, `context/no-cycle`).

package/docs/rules/context-published-language-only.md

@@ -0,0 +1,47 @@
+# ddd-ts-kit/context-published-language-only
+
+Architecture id: `context/published-language-only`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every file of a context, tests included.
+
+## Why
+
+A bounded context owns its model. Another context that imports its aggregate or its table freezes that model: the published language is the only contract designed to be depended on.
+
+## Reported
+
+- an import of another context outside its `published-language/`
+
+Incorrect:
+
+```ts
+// src/contexts/billing/application/...
+import { Product } from '@/contexts/catalog/domain/aggregates/product.aggregate.js';
+```
+
+Correct:
+
+```ts
+import type { ProductListedV1 } from '@/contexts/catalog/published-language/index.js';
+```
+
+## Details
+
+Static imports, type-only imports, `export ... from`, dynamic `import()`, `require()`, `import x = require()` and `import("...")` types are all read, through relative paths and the configured `importAlias`.
+
+## Options
+
+None.
+
+`rules."context/published-language-only"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line context/published-language-only -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The target is classified by its path: a barrel in an allowed layer that re-exports a forbidden one is not followed. `dependency-cruiser` (see `pipeline/depcruise-config.mjs`) resolves the real graph and closes that gap.
+- A computed specifier (`import(name)`) is not judged.
+- `tsconfig` paths other than `importAlias` are not resolved.
+- Files outside the contexts directory (the platform, `main.ts`) are not judged: the composition root knows every context.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from a regex reading of the file. This rule is the authority for the import; the CLI stays the authority for the config (`config/valid`, `context/no-cycle`).

package/docs/rules/declarations-role-declared.md

@@ -0,0 +1,109 @@
+# ddd-ts-kit/declarations-role-declared
+
+Architecture id: `declarations/role-declared`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every file of a context in a declared-style project (`stack.style: "declared"` in `ddd-ts-kit.config.json`), tests excluded. Nothing is reported in an explicit-style project, which is also what a config that does not say is.
+
+## Why
+
+In the declared style a context has no module file: a class says what it is with a decorator of `@ddd-ts-kit/kernel/declarations`, and the composition root is assembled from what the classes say. A role file whose class says nothing is in no assembly: the handler is never registered and the first command fails at run time. A name that is derived instead of written changes when a class is renamed, and with it the idempotency scope of a consumer. A decorator in the domain ties the model to the wiring.
+
+## Reported
+
+In a role file (the table below), other than `*.command.ts` and `*.query.ts`, which `authz-declared` holds:
+
+- no exported class carries the decorator of the role
+- a class of the file carries another declaration decorator than the one of the role
+
+On any class of `application/`, `infrastructure/`, `presentation/` or the context root:
+
+- `@IntegrationEventHandler(definition, { consumer })`, `@Policy(permission, { name })` or `@DomainEventHandler(Event, { name })` whose name is not a non-empty string literal: missing, empty, a variable, a template with a substitution, options held in a variable or only spread
+- `@DomainEventHandler(Event, { name })` whose `name` differs from the `name` literal of the event class, when that class is in view
+
+Under `domain/`:
+
+- a class carrying any declaration decorator: `Requires`, `Public`, `CommandHandler`, `QueryHandler`, `IntegrationEventHandler`, `DomainEventHandler`, `Scheduled`, `Repository`, `Gateway`, `Adapter`, `Policy`
+
+| File, relative to the context | Exported class carries |
+|---|---|
+| `application/commands/**/*.handler.ts` | `@CommandHandler` |
+| `application/queries/**/*.handler.ts` | `@QueryHandler` |
+| `application/integration/handlers/**/*.integration-handler.ts` | `@IntegrationEventHandler` |
+| `application/event-handlers/**/*.event-handler.ts` | `@DomainEventHandler` |
+| `application/integration/publishers/**/*.publisher.ts` | `@DomainEventHandler` |
+| `application/authorization/**/*.policy.ts` | `@Policy` |
+| `application/scheduling/**/*.job.ts` | `@Scheduled` |
+| `infrastructure/persistence/**/*.repository.ts` | `@Repository` |
+| `infrastructure/**/*.gateway.ts` | `@Gateway` |
+| `infrastructure/**/*.adapter.ts` | `@Adapter` |
+
+Incorrect:
+
+```ts
+// application/commands/issue-invoice/issue-invoice.handler.ts
+export class IssueInvoiceHandler {}
+
+// application/queries/search-invoices/search-invoices.handler.ts
+@CommandHandler(SearchInvoicesQuery, [InvoiceReader])
+export class SearchInvoicesHandler {}
+
+// application/authorization/only-issuer-voids.policy.ts
+@Policy(billingPermissions['invoice.void'], { name: policyName })
+export class OnlyIssuerVoidsPolicy {}
+
+// application/event-handlers/invoice-issued.event-handler.ts, where InvoiceIssued is named 'billing.invoice.issued'
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.sent' })
+export class InvoiceIssuedEventHandler {}
+
+// domain/aggregates/invoice.aggregate.ts
+@Repository(InvoiceRepository)
+export class Invoice {}
+```
+
+Correct:
+
+```ts
+// application/commands/issue-invoice/issue-invoice.handler.ts
+import { Clock } from '@ddd-ts-kit/kernel';
+import { CommandHandler } from '@ddd-ts-kit/kernel/declarations';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+
+@CommandHandler(IssueInvoiceCommand, [InvoiceRepository, Clock])
+export class IssueInvoiceHandler implements CommandHandler<IssueInvoiceCommand> {}
+
+// application/authorization/only-issuer-voids.policy.ts
+@Policy(billingPermissions['invoice.void'], { name: 'billing.only-issuer-voids' })
+export class OnlyIssuerVoidsPolicy {}
+
+// application/event-handlers/invoice-issued.event-handler.ts
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' })
+export class InvoiceIssuedEventHandler {}
+```
+
+## Details
+
+A decorator counts when its name is one of the ten declaration decorators and that name is imported from `@ddd-ts-kit/kernel/declarations` in the file: `{ Repository }`, an alias `{ Repository as Repo }`, or a namespace `declarations.Repository`. A home-made decorator of the same name, or one of another package (`@Retry` of `@ddd-ts-kit/aspects/decorators`), is ignored.
+
+The role of a file is read from its suffix and its folder, as the generator writes them. A class is exported inline, by `export { A }` or by `export default A`. When a class carries another declaration decorator, only that is reported: fixing it also answers the missing one.
+
+The event class of `@DomainEventHandler` is in view when it is declared in the same file, or imported by name from a source of the project that exists on disk; that file is then parsed, syntax only, and its `readonly name = '...'` property is read (`as const` and `satisfies` are looked through). When the class cannot be found, or its name is not a literal, nothing is compared.
+
+## Options
+
+None.
+
+`rules."declarations/role-declared"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line declarations/role-declared -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- An event class reached through a barrel (`@/contexts/billing/domain/events/index.js`), a renaming export, a default import or a namespace is not followed: its name is not compared. `ddd-ts-kit check` resolves the same import in the project.
+- A decorator applied through a variable (`const declare = Repository(InvoiceRepository); @declare class ...`) is not recognised.
+- That the dependency list matches the constructor and that a handler handles its message is checked by the compiler, not here; that an adapter implements its port is `ports/implements-never-extends`, and where a job lives and what it is named are `scheduling/job-triggers-use-case` and `scheduling/job-name`.
+- That each role file holds a single declared class is `naming/one-concept-per-file` of `ddd-ts-kit check`.
+- That the generated barrel `<context>.declarations.ts` lists every role file is `declarations/barrel-current` of `ddd-ts-kit check`: it is a fact of the project, not of one file.
+- A role file written outside the folders of the table is not known to be one: `naming/suffix` and `tree/closed` of `ddd-ts-kit check` hold the tree.
+- The unwritten `consumer` of `@IntegrationEventHandler` is also reported by `events-consumer-idempotent`, for what it costs at run time.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/domain-aggregate-encapsulation.md

@@ -0,0 +1,63 @@
+# ddd-ts-kit/domain-aggregate-encapsulation
+
+Architecture id: `domain/aggregate-encapsulation` (added by this plugin). Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/aggregates/` and `domain/entities/` of a context, tests excluded.
+
+## Why
+
+An aggregate guards its invariants. A public constructor lets anyone build an invalid one, a public mutable property or a setter lets anyone change it without the rule that should have run.
+
+## Reported
+
+- a public constructor (abstract classes are exempt)
+- a class without constructor and without base class
+- a public property that is neither `readonly` nor a method, including `public` constructor parameter properties and `accessor` fields
+- a public `set` accessor, and a public `setX` method whose body only assigns to `this`
+
+Incorrect:
+
+```ts
+export class Invoice {
+  constructor(public status: string) {}
+  setStatus(status: string): void {
+    this.status = status;
+  }
+}
+```
+
+Correct:
+
+```ts
+export class Invoice extends AggregateRoot<string> {
+  private constructor(id: string, private state: InvoiceState) {
+    super(id);
+  }
+  static create(id: string, now: Date): Invoice {
+    return new Invoice(id, { createdAt: now });
+  }
+  issue(at: Date): void {
+    this.state = { ...this.state, issuedAt: at };
+    this.record(new InvoiceIssued(this.id, at));
+  }
+}
+```
+
+## Details
+
+A class that extends another one and declares no constructor inherits the visibility of its base: `AggregateRoot` and `Entity` of the kernel are protected.
+
+## Options
+
+None.
+
+`rules."domain/aggregate-encapsulation"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line domain/aggregate-encapsulation -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The visibility of an inherited constructor is not checked (no type information is used).
+- A `setX` method that does anything besides assigning is trusted to be an intention.
+
+## With the CLI checker
+
+New with this plugin: the CLI checker has no equivalent, because the shape of a class needs a syntax tree.

package/docs/rules/domain-events-dispatched-on-save.md

@@ -0,0 +1,83 @@
+# ddd-ts-kit/domain-events-dispatched-on-save
+
+Architecture id: `domain-events/dispatched-on-save`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `application/` and `infrastructure/` of a context, tests excluded.
+
+## Why
+
+Domain events leave with the save. After a repository method that was handed an aggregate resolves, the events the aggregate recorded are dispatched in order, inside the unit of work of the command, so their handlers and the outbox commit or roll back with the state change. A handler that pulls the events and dispatches them itself announces them a second time, or announces them outside the transaction; a repository adapter that dispatches mixes persistence with wiring. Events leave with the save: `await repository.save(aggregate)` and nothing else; a removal that announces an event takes the aggregate.
+
+## Reported
+
+- a call to `.pullEvents()` in any production file under `application/` or `infrastructure/` of a context
+- in `application/commands/`, `application/queries/` and a repository adapter (`infrastructure/persistence/**/*.repository.ts`): `DomainEventDispatcher` imported (from any module, type-only imports included), named in a dependency list, or typing a constructor parameter
+
+Incorrect:
+
+```ts
+// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { Clock, DomainEventDispatcher } from '@ddd-ts-kit/kernel';
+
+@CommandHandler(IssueInvoice, [InvoiceRepository, Clock, DomainEventDispatcher])
+export class IssueInvoiceHandler {
+  constructor(
+    private readonly invoices: InvoiceRepository,
+    private readonly clock: Clock,
+    private readonly dispatcher: DomainEventDispatcher,
+  ) {}
+
+  async execute(command: IssueInvoice): Promise<string> {
+    const invoice = Invoice.issue(command.customerId, this.clock.now());
+
+    await this.invoices.save(invoice);
+    await this.dispatcher.dispatch(invoice.pullEvents());
+
+    return invoice.id;
+  }
+}
+```
+
+Correct:
+
+```ts
+// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { Clock } from '@ddd-ts-kit/kernel';
+
+@CommandHandler(IssueInvoice, [InvoiceRepository, Clock])
+export class IssueInvoiceHandler {
+  constructor(
+    private readonly invoices: InvoiceRepository,
+    private readonly clock: Clock,
+  ) {}
+
+  async execute(command: IssueInvoice): Promise<string> {
+    const invoice = Invoice.issue(command.customerId, this.clock.now());
+
+    await this.invoices.save(invoice);
+
+    return invoice.id;
+  }
+}
+```
+
+## Details
+
+`pullEvents` is read as a method call on anything (`invoice.pullEvents()`, `this.invoice?.pullEvents()`, `invoice['pullEvents']()`): a declaration of that name and a bare identifier are not calls. A dependency list is the last argument of a declaration decorator of `@ddd-ts-kit/kernel/declarations` (`@CommandHandler(M, [..])`, `@QueryHandler`, `@Repository`) and the second argument of `.toClass(C, [..])` and `.handledBy(H, [..])`.
+
+Not judged: `domain/` (the aggregate records and hands over its own events), the specs and everything under `test/` of a context, `<context>.module.ts` (the explicit module may still register event handlers on the dispatcher), the platform, `main.ts`, `apps/` and every file outside a context. `application/event-handlers/` and `application/integration/` are held to the `pullEvents()` part only.
+
+## Options
+
+None.
+
+`rules."domain-events/dispatched-on-save"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line domain-events/dispatched-on-save -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A dispatcher reached under another name (a re-export renamed by a barrel, a home-made port that wraps it) is not recognised.
+- Events pulled by a helper that lives in the platform or in the shared kernel and is called from a handler are not followed.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files: one finding per line that calls `.pullEvents(`, per import that binds `DomainEventDispatcher`, per dependency list and per constructor that names it. This rule is the authority.

package/docs/rules/domain-events-transactional-before-commit.md

@@ -0,0 +1,92 @@
+# ddd-ts-kit/domain-events-transactional-before-commit
+
+Architecture id: `domain-events/transactional-before-commit`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: production files of a context, on every class carrying `@DomainEventHandler`.
+
+## Why
+
+An effect of a domain event exists only if the state change that recorded the event is committed. A handler that runs before the commit (the default phase) runs inside the transaction of the command, and the commit itself can still fail after the handler ran: a deferred constraint, a serialization failure, a lost connection. That is safe only when the rollback undoes everything the handler did, so a before-commit handler may only have transactional effects. A cache entry, a lock, a job, a message on the bus or a call to a remote system would survive the rollback and tell the world about a fact that never happened.
+
+Declare the handler `phase: 'after-commit'` when its effect may be lost on a crash (it then runs at most once), or publish an integration event from a publisher (outbox, at least once) and do the work in the handler of that event when it must not be lost.
+
+## Reported
+
+The phase of a handler is `after-commit` when the options object of its `@DomainEventHandler` writes `phase: 'after-commit'`; otherwise it is `before-commit`. Its dependencies are the names of the dependency list of the decorator and the types of its constructor parameters, each resolved through the imports of the file.
+
+For a before-commit handler, a dependency that is:
+
+- `Cache`, `Lock`, `RateLimiter`, `JobScheduler` or `EventBus` of `@ddd-ts-kit/kernel`
+- imported from `infrastructure/` of its context
+- imported from another context
+- imported from the platform directory
+- imported from a package other than `@ddd-ts-kit/kernel` and `@ddd-ts-kit/auth`, a Node.js builtin included
+
+For an after-commit handler, a dependency on `IntegrationEventPublisher` of `@ddd-ts-kit/kernel`, and nothing else: after the commit nothing makes the outbox row atomic with a state change, so the handler sends a command through `CommandBus` instead.
+
+Incorrect:
+
+```ts
+// src/contexts/billing/application/event-handlers/invoice-issued.event-handler.ts
+import { Cache } from '@ddd-ts-kit/kernel';
+import { DomainEventHandler } from '@ddd-ts-kit/kernel/declarations';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [InvoiceRepository, Cache])
+export class InvoiceIssuedEventHandler {
+  constructor(
+    private readonly invoices: InvoiceRepository,
+    private readonly cache: Cache,
+  ) {}
+}
+```
+
+```ts
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued', phase: 'after-commit' }, [IntegrationEventPublisher])
+export class InvoiceIssuedEventHandler {}
+```
+
+Correct:
+
+```ts
+// the state the handler changes commits or rolls back with the command
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [InvoiceRepository, CommandBus])
+export class InvoiceIssuedEventHandler {}
+```
+
+```ts
+// an effect no transaction covers runs once the transaction has committed, at most once
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued', phase: 'after-commit' }, [Cache])
+export class InvoiceIssuedEventHandler {}
+```
+
+```ts
+// an effect that must not be lost goes through the outbox: the handler of the integration event does the work
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [IntegrationEventPublisher, IdGenerator])
+export class InvoiceIssuedPublisher {}
+```
+
+## Details
+
+A before-commit handler may depend on anything of the `domain/` layer of its context (a repository port, a domain service), on every other port of `@ddd-ts-kit/kernel` (`IntegrationEventPublisher`, `CommandBus`, `QueryBus`, `Clock`, `IdGenerator`, `Logger`, `Metrics`, `ActorContext`, `ExecutionScope`..), on `@ddd-ts-kit/auth`, and on the files of its context outside `infrastructure/` and `application/ports/`. A kernel port imported under another name (`import { Cache as Entries }`) is recognised by the name the kernel exports.
+
+Only names that are dependencies are judged: a type-only import that types a method parameter, or an import the class never receives, is not a dependency. A name the file does not import is left alone.
+
+## Options
+
+None.
+
+`rules."domain-events/transactional-before-commit"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line domain-events/transactional-before-commit -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+ESLint judges one file, so two parts of the rule are held by `ddd-ts-kit check` alone:
+
+- A port of `application/ports/` of the context is accepted before the commit only when it is a persistence port: at least one production class implements it under `infrastructure/persistence/` and none anywhere else under `infrastructure/`. Where the adapters of a port live is not in the file of the handler: this rule reports no port of `application/ports/`.
+- In the explicit styles the class carries no decorator and its phase is the third argument of its `.on(name, callback, { phase: 'after-commit' })` registration in `<context>.module.ts`: a handler without `@DomainEventHandler` is not judged here.
+
+Also not seen: a dependency list held in a constant, a port reached through a namespace import (`kernel.Cache`) or a barrel that renames it, and an effect reached without a dependency (a module-level client, a static call).
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files, and adds what needs the project: the adapters of a port of `application/ports/`, and the phase and the `.toClass(Handler, [..])` list written in the module file of an explicit-style context. This rule is the authority for what one declared class shows.

package/docs/rules/domain-no-generic-error.md

@@ -0,0 +1,40 @@
+# ddd-ts-kit/domain-no-generic-error
+
+Architecture id: `domain/no-generic-error` (added by this plugin). Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` and `application/` of a context, tests excluded.
+
+## Why
+
+An expected business failure has a name and a stable code that presentation maps to a status in one place. `new Error("...")` gives the caller a sentence to parse.
+
+## Reported
+
+- `throw new Error(...)` and `throw Error(...)`
+
+Incorrect:
+
+```ts
+throw new Error('Invoice already issued');
+```
+
+Correct:
+
+```ts
+throw new InvoiceAlreadyIssued(this.id);
+```
+
+## Options
+
+None.
+
+`rules."domain/no-generic-error"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line domain/no-generic-error -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Only the global `Error` is reported: `TypeError` and friends are left to review.
+- A generic error returned in a `Result` (`err(new Error())`) or rejected (`Promise.reject`) is not seen.
+
+## With the CLI checker
+
+New with this plugin: the CLI checker has no equivalent, because the shape of a class needs a syntax tree.

package/docs/rules/domain-value-object-immutability.md

@@ -0,0 +1,52 @@
+# ddd-ts-kit/domain-value-object-immutability
+
+Architecture id: `domain/value-object-immutability` (added by this plugin). Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/value-objects/` of a context, tests excluded.
+
+## Why
+
+A value object is its value. If it can change, two holders of the same instance disagree about what they hold, and equality by value stops meaning anything.
+
+## Reported
+
+- a property or constructor parameter property without `readonly` (private and `#private` included)
+- a `set` accessor
+- outside the constructor, an assignment or an increment that starts at `this` (`this.props.cents += 1`)
+- outside the constructor, an array mutator called on something of `this` (`push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`, `fill`, `copyWithin`)
+
+Incorrect:
+
+```ts
+export class Amount {
+  constructor(private cents: number) {}
+  add(other: Amount): void {
+    this.cents += other.cents;
+  }
+}
+```
+
+Correct:
+
+```ts
+export class Amount extends ValueObject<AmountProps> {
+  add(other: Amount): Amount {
+    return new Amount({ cents: this.props.cents + other.props.cents });
+  }
+}
+```
+
+## Options
+
+None.
+
+`rules."domain/value-object-immutability"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line domain/value-object-immutability -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Deep immutability of what a property holds (`readonly items: string[]`) is not checked: prefer `readonly string[]`.
+- `Map`, `Set` and object mutation through method calls is not seen.
+
+## With the CLI checker
+
+New with this plugin: the CLI checker has no equivalent, because the shape of a class needs a syntax tree.