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

package/docs/rules/application-command-query-separation.md

@@ -0,0 +1,54 @@
+# ddd-ts-kit/application-command-query-separation
+
+Architecture id: `application/command-query-separation` (added by this plugin). Default severity: `warn` in `recommended`, `error` in `strict`.
+
+Applies to: files under `application/queries/` of a context, tests excluded.
+
+## Why
+
+A query answers and never changes state: it can then be retried, cached and run on a replica. A query that saves is a command with a return value.
+
+## Reported
+
+- a call of `save`, `delete` or `publish` on something held by the handler (`this.invoices.save(...)`, `this.#bus.publish(...)`)
+
+Incorrect:
+
+```ts
+export class SearchInvoicesHandler {
+  async execute(query: SearchInvoicesQuery): Promise<SearchInvoicesResult> {
+    await this.audit.save(query);
+    return this.reader.read(query);
+  }
+}
+```
+
+Correct:
+
+```ts
+export class SearchInvoicesHandler {
+  async execute(query: SearchInvoicesQuery): Promise<SearchInvoicesResult> {
+    return this.reader.read(query);
+  }
+}
+```
+
+## Details
+
+Pragmatic by design: the rule matches method names on dependencies reached through `this`. A local `Set` whose `delete` is called is not reported.
+
+## Options
+
+`[{ "mutators": ["save", "delete", "publish"] }]` replaces the list of method names.
+
+`rules."application/command-query-separation"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line application/command-query-separation -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A mutation behind another name (`upsert`, `record`) needs the `mutators` option.
+- A dependency passed as an argument instead of injected is not followed.
+- The other half of the principle, a command returning more than an identifier, is left to review.
+
+## 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/application-handler-shape.md

@@ -0,0 +1,52 @@
+# ddd-ts-kit/application-handler-shape
+
+Architecture id: `application/handler-shape` (added by this plugin). Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `*.handler.ts` under `application/` of a context.
+
+## Why
+
+A handler is one use case: one class, called by the bus through `execute`. A second public method is a second use case hiding in the first, or a business decision that belongs to the domain.
+
+## Reported
+
+- a handler file that exports no class
+- a second exported class
+- a handler class without a public `execute`
+- any other public method or function property, static ones included
+
+Incorrect:
+
+```ts
+export class IssueInvoiceHandler {
+  async handle(command: IssueInvoiceCommand): Promise<string> {}
+  computeTotal(): number {}
+}
+```
+
+Correct:
+
+```ts
+export class IssueInvoiceHandler implements CommandHandler<IssueInvoiceCommand> {
+  async execute(command: IssueInvoiceCommand): Promise<string> {}
+  private total(): number {}
+}
+```
+
+## Details
+
+Types, interfaces and constants exported next to the class are allowed. `*.event-handler.ts` files are not handlers of the bus and are not judged.
+
+## Options
+
+None.
+
+`rules."application/handler-shape"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line application/handler-shape -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The signature of `execute` is not checked against the command or query type: the compiler does it through `CommandHandler<T>` and `QueryHandler<T>`.
+
+## 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/aspects-outside-in.md

@@ -0,0 +1,54 @@
+# ddd-ts-kit/aspects-outside-in
+
+Architecture id: `aspects/outside-in`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every production file under the source root, except `infrastructure/` of a context and the platform directory; `domain/` and `application/` are left to the layer rules.
+
+## Why
+
+Logging, metrics, retry, timeout, circuit breaking and caching are applied from outside the code they wrap: the policy of a whole application is read in one place, the composition root, and changes without touching a class. The decorator form is the exception, kept for an adapter whose policy is part of what the adapter is (a client of a provider that documents its own retry and timeout rules). On a route, in a module file, in a published language or in the shared kernel, a decorator hides a policy where nobody looks for one.
+
+## Reported
+
+- an import of `@ddd-ts-kit/aspects/decorators` in `presentation/`, in `<context>.module.ts`, in `published-language/`, in any other production file of a context outside `infrastructure/`, in the shared kernel, in `main.ts` and in any other source under the source root (`apps/<context>/main.ts` included)
+
+Incorrect:
+
+```ts
+// src/contexts/billing/presentation/http/issue-invoice.route.ts
+import { Retry } from '@ddd-ts-kit/aspects/decorators';
+```
+
+Correct:
+
+```ts
+// src/contexts/billing/billing.module.ts
+import { retry, timeout } from '@ddd-ts-kit/aspects';
+
+builder.bind(PaymentGateway).toClass(StripePaymentGateway, [PaymentSettings]).with(retry({ attempts: 3 }), timeout(2000));
+
+// src/contexts/billing/infrastructure/external/stripe-payment.gateway.ts
+import { Retry } from '@ddd-ts-kit/aspects/decorators';
+```
+
+## Details
+
+Only the `/decorators` entry is judged: the wrappers of `@ddd-ts-kit/aspects` (`retry`, `timeout`, `aspects`, the bus middlewares) are what a module file and `main.ts` are expected to import. Static imports, type-only imports, `export ... from`, dynamic `import()` and `require()` are all read.
+
+In `domain/` and `application/` every entry of `@ddd-ts-kit/aspects` is already refused by `layer-domain-purity` and `layer-application-inward`: this rule stays silent there, so that one import gives one report. Tests and files outside the source root (scripts, config files) are not judged.
+
+## Options
+
+None. `platformDir` and `sourceRoot` of `ddd-ts-kit.config.json` say where the platform and the sources are.
+
+`rules."aspects/outside-in"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line aspects/outside-in -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A decorator re-exported by a file of `infrastructure/` or of the platform and imported from there is not followed.
+- A home-made decorator built on `weave` or on an aspect of the root entry is not recognised.
+- With `layer/domain-purity` or `layer/application-inward` set to `off`, nothing reports the decorators in that layer.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the import specifiers it reads in the text of the files, with the same exemptions. This rule is the authority.

package/docs/rules/authz-actor-explicit.md

@@ -0,0 +1,70 @@
+# ddd-ts-kit/authz-actor-explicit
+
+Architecture id: `authz/actor-explicit`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` and `application/` of a context, tests excluded.
+
+## Why
+
+A use case that reads "the current actor" from the air works behind an HTTP request and nowhere else: an integration event handler, a scheduled job and a test have to set a global first, and forget. The actor is data of the command or the query, like every other input. The `ExecutionScope` opened at the boundary (and `ActorContext`, a view of it) exists for code that is not handed the context: infrastructure and the platform read it for audit columns, tenant scoping and correlation.
+
+## Reported
+
+- an import of `ActorContext`, `ExecutionScope`, `AsyncLocalStorageExecutionScope`, `ScopedActorContext` or `AsyncLocalStorage`, from any module, as a type or as a value: the port class is also its injection token, so a value import is the one a dependency list would name
+- the same names reached through a namespace (`kernel.ExecutionScope`, `hooks.AsyncLocalStorage`)
+- a constructor parameter typed `ActorContext` or `ExecutionScope`
+- a call of `.current()` or `.require()` without argument on a receiver declared with one of these types, or, when the file does not show its declaration, named `actors`, `scope`, `scopes`, `...actorContext` or `...executionScope`
+- an import of the infrastructure helpers `stampCreation`, `stampUpdate` or `tenantScopeOf`, and their use through an imported namespace (`kernel.stampCreation`)
+
+Incorrect:
+
+```ts
+import { stampCreation, type ExecutionScope } from '@ddd-ts-kit/kernel';
+
+export class VoidInvoiceHandler {
+  constructor(private readonly invoices: InvoiceRepository, private readonly scope: ExecutionScope) {}
+
+  async execute(command: VoidInvoice): Promise<void> {
+    const { actor } = this.scope.require();
+    const stamp = stampCreation(this.scope, this.clock);
+  }
+}
+```
+
+Correct:
+
+```ts
+export class VoidInvoiceHandler {
+  constructor(private readonly invoices: InvoiceRepository, private readonly access: Access) {}
+
+  async execute(command: VoidInvoice): Promise<void> {
+    await this.access.authorize(command.actor, billingPermissions['invoice.void'], invoice);
+  }
+}
+
+// infrastructure/persistence/drizzle-invoice.repository.ts
+const row = { ...toRow(invoice), ...stampCreation(this.scope, this.clock), ...tenantScopeOf(this.scope) };
+```
+
+## Details
+
+`infrastructure/` and the platform may read the `ExecutionScope` and the `ActorContext` for audit columns, tenant scoping, log fields and the correlation id, and the module binds `ActorContext` and `ExecutionScope`: none of them is judged. Tests are not judged either, so `FixedExecutionScope` and `FixedActorContext` stay available to them. An import, the constructor parameter it types and the read are three reports, one per line to change.
+
+The type of a receiver is read from its declaration in the same file (a parameter, a variable, a property, a parameter property): no type information is needed. A receiver named `scope` and declared with another type (`AccessScope`, a concept of the domain) is not reported.
+
+## Options
+
+None.
+
+`rules."authz/actor-explicit"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line authz/actor-explicit -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- An ambient context reached under another name (a port of the project wrapping `ExecutionScope`, a module-level variable) is not seen.
+- A re-export through a file of the context that renames the port is not followed.
+- A receiver named `scope` whose declaration is not in the file (a destructured dependency, a property of a base class) is judged by its name: a concept of the domain called `scope` with a `current()` or `require()` method of its own is reported. Annotate the declaration, or record the suppression.
+- A method of the project named `stampCreation`, `stampUpdate` or `tenantScopeOf` is not reported; a helper imported under these names from another module than the kernel is.
+
+## 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: it knows no declared type, so it reports `.current()` and `.require()` on anything named `scope`, `scopes` or `...executionScope`, and a helper only when the file imports it under its own name. This rule is the authority.

package/docs/rules/authz-declared.md

@@ -0,0 +1,87 @@
+# ddd-ts-kit/authz-declared
+
+Architecture id: `authz/declared`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: the module file of a context for registrations, every production file for routes and messages, and in a declared-style project (`stack.style: "declared"`) the `*.command.ts` and `*.query.ts` files under `application/commands` and `application/queries`; tests excluded.
+
+## Why
+
+Nothing is reachable by default. A use case or a route that says nothing about who may call it is open by accident, and the accident is found in production. Saying "public" is a decision; saying nothing is not.
+
+## Reported
+
+- in `<context>.module.ts`: a chain `<builder>.command(X)` or `<builder>.query(X)` that reaches `.handledBy(...)` or `.handledByFactory(...)` with neither `.requires(...)` nor `.public()`, unless the class `X` is seen to carry `@Requires(...)` or `@Public()`
+- in a declared-style project: an exported class of a `*.command.ts` or `*.query.ts` file under `application/commands` or `application/queries` that carries neither `@Requires(...)` nor `@Public()` of `@ddd-ts-kit/kernel/declarations`
+- a `defineRoute({...})` whose spec has no `security` property, or `security: undefined`
+- a `defineRoute({...})` whose spec has `security: []`
+- a class extending `AuthorizedCommand` or `AuthorizedQuery` whose constructor does not pass one of its own parameters as first argument of `super(...)`
+
+Incorrect:
+
+```ts
+builder.command(VoidInvoice).handledBy(VoidInvoiceHandler, [INVOICES]);
+
+defineRoute({ method: 'POST', path: '/invoices/:id/void', operationId: 'voidInvoice', responses }, handler);
+
+export class VoidInvoice extends AuthorizedCommand {
+  constructor(readonly invoiceId: string) {
+    super(systemActor('billing'));
+  }
+}
+
+// declared style: application/commands/issue-invoice/issue-invoice.command.ts
+export class IssueInvoiceCommand extends AuthorizedCommand<string> {}
+```
+
+Correct:
+
+```ts
+builder.command(VoidInvoice).requires(billingPermissions['invoice.void']).handledBy(VoidInvoiceHandler, [INVOICES]);
+builder.query(GetCatalog).public().handledBy(GetCatalogHandler, [CATALOG]);
+
+defineRoute({ method: 'POST', path: '/invoices/:id/void', operationId: 'voidInvoice', responses, security: ['bearer'] }, handler);
+defineRoute({ method: 'GET', path: '/catalog', operationId: 'getCatalog', responses, security: false }, handler);
+
+export class VoidInvoice extends AuthorizedCommand {
+  constructor(actor: Actor, readonly invoiceId: string) {
+    super(actor);
+  }
+}
+
+// declared style: application/commands/issue-invoice/issue-invoice.command.ts
+import { Requires } from '@ddd-ts-kit/kernel/declarations';
+
+@Requires(billingPermissions['invoice.issue'])
+export class IssueInvoiceCommand extends AuthorizedCommand<string> {}
+```
+
+## Details
+
+The route type of `@ddd-ts-kit/http` enforces `security` already: `defineRoute` does not compile without it and refuses an empty list. This rule stays as the lint-level net for a route definition built loosely: a spec typed `any` or cast, a JavaScript file, a wrapper that widens the type.
+
+`@Requires(...)` or `@Public()` on the message class is the declaration, in any project: a module that registers a decorated message without `.requires(...)` or `.public()` is not reported. The class is in view when it is declared in the module file or imported by name from a source of the project that exists on disk, which is then parsed (syntax only). A decorator counts when its name is imported from `@ddd-ts-kit/kernel/declarations` in the file of the class, under an alias (`{ Requires as Needs }`) or a namespace (`declarations.Requires`) too; a home-made `Requires` does not.
+
+An explicit-style project is judged on its registrations only: a message file without a decorator is not reported there.
+
+The registration is recognised by its shape, whatever the builder is called. `super(input.actor)` is accepted when `input` is a constructor parameter. A class without a constructor inherits the one of `AuthorizedCommand`, which takes the actor.
+
+## Options
+
+None.
+
+`rules."authz/declared"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line authz/declared -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A registered message reached through a barrel, a renaming export, a default import or a namespace is not followed to its class: its decorator is not seen and the registration is reported.
+- In a declared-style project that keeps a `<context>.module.ts`, a message registered there with `.requires(...)` and written without a decorator is still reported in its own file: put the decorator on the class.
+- A `*.command.ts` or `*.query.ts` file that exports no class is not reported here.
+- A registration split over statements (`const target = builder.command(X); target.handledBy(H);`) is not followed.
+- A wiring written by hand with `AuthorizationMap.of(requires(...), publicUseCase(...))` is not read: `authorizationMiddleware` refuses an undeclared use case at run time, and `createApplication({ authorization: 'required' })` at start.
+- A message extending plain `Command` or `Query` while its registration calls `.requires(...)` spans two files and is not seen here; the compiler refuses it, since `requires` only exists for a message that carries an actor.
+- A route spec that is not an object literal, or that spreads another object, is not judged.
+- That the scheme named in `security` exists, and that the permission is the right one, is not checked.
+
+## 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/authz-in-application.md

@@ -0,0 +1,88 @@
+# ddd-ts-kit/authz-in-application
+
+Architecture id: `authz/in-application`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `presentation/`, `infrastructure/` and `domain/` of a context, tests excluded.
+
+## Why
+
+A permission decided in three places is decided in none. A role test in a route is skipped by the integration event handler that sends the same command; a refusal in a repository cannot be audited; an aggregate that knows roles cannot change authorization model. One place decides: the application layer, through the `Authorizer` port.
+
+## Reported
+
+In `presentation/`:
+
+- a read of `.roles`, `.permissions` or `.isAdmin` on anything
+- a comparison of a member named `role` with a string (`===`, `!==`, `==`, `!=`), and a `switch` on it
+- an import from `@ddd-ts-kit/auth` (any entry) of anything but the request glue (`actorOf`, `sessionOf`, `resolveSession`, `SessionAuthenticator`, `bearerCredential`, `inActorContext`, `principalResolver`, `HeaderValues`), the codes `FORBIDDEN` and `UNAUTHORIZED` and the error classes (the `Access` port included)
+- in a declared-style project (`stack.style: "declared"`): an import of `Requires`, `Public` or `Policy` from `@ddd-ts-kit/kernel/declarations`
+
+In `infrastructure/`:
+
+- a call to `.authorize(...)`, `.decide(...)` or `.check(...)` on something named `access` or `...authorizer...`, or declared with the type `Access` or `...Authorizer`
+- `new ForbiddenError(...)`
+- in a declared-style project: an import of `Requires`, `Public` or `Policy` from `@ddd-ts-kit/kernel/declarations`, or of the ports `Access` or `PolicyAccess` from `@ddd-ts-kit/auth` (any entry), as a type or as a value
+
+In `domain/`:
+
+- any import from `@ddd-ts-kit/auth`
+- an import of `Actor`, `Actored`, `ActorContext`, `Session` or `ExecutionContext` from `@ddd-ts-kit/kernel`
+- a read of `.roles` or `.permissions` on anything but `this`
+
+Incorrect:
+
+```ts
+// presentation/http/void-invoice.route.ts
+if (!context.principal.roles.includes('controller')) {
+  return { status: 403 };
+}
+
+// infrastructure/persistence/drizzle-invoice.repository.ts
+await this.access.authorize(actor, billingPermissions['invoice.read'], row);
+
+// domain/aggregates/invoice.aggregate.ts
+void(by: Actor): void {
+  if (!by.roles.includes('controller')) {
+    throw new NotAllowedError();
+  }
+}
+```
+
+Correct:
+
+```ts
+// presentation/http/void-invoice.route.ts
+await commandBus.execute(new VoidInvoice(actorOf(context.principal), params.invoiceId));
+
+// application/commands/void-invoice/void-invoice.handler.ts
+await this.access.authorize(command.actor, billingPermissions['invoice.void'], invoice);
+invoice.void(command.actor.id, this.clock.now());
+```
+
+## Details
+
+The type of a receiver is read from its declaration in the same file (a parameter, a variable, a property, a parameter property): no type information is needed. A class of `infrastructure/` that `implements` an `...Authorizer` is an adapter of the port (a cache, a remote service) and may delegate to another authorizer.
+
+`application/` is where access is declared and decided: `Requires`, `Public` and `Policy` of `@ddd-ts-kit/kernel/declarations` and the `Access` port of `@ddd-ts-kit/auth` are imported there freely, in both styles. In `domain/` of a declared-style project the whole declarations entry is refused by `layer-domain-purity`, so this rule does not report it a second time. The other names of the declarations entry (`Repository`, `CLOCK`, ...) are not the concern of this rule. An explicit-style project is judged as before: these imports are not reported outside `application/`.
+
+In `domain/`, `this.roles` and `this.state.roles` are not reported: a context whose subject is access itself (identity, membership) models roles as state.
+
+## Options
+
+None.
+
+`rules."authz/in-application"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line authz/in-application -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- `Requires`, `Public` or `Policy` reached through a namespace import of the declarations entry (`import * as declarations`) is not reported in `presentation/` and `infrastructure/`.
+- The names are the signal. A route of an administration API whose body legitimately carries `roles` or `permissions` (grant a role to a member) is reported when it reads them: destructure the body (`const { roles } = body`) or record the deviation.
+- A role test written without a member named `role` or `roles` (`isAdmin(user)`, `['admin'].includes(kind)`) is not seen.
+- `.check(...)` on an authorizer held under another name and typed in another file is not seen.
+- An ownership test (`row.ownerId !== actor.id`) is not recognised as such in any layer; in `infrastructure/` only the refusal that follows (`new ForbiddenError`) is.
+- `Authenticator` is not on the allow-list of `presentation/`: the principal is resolved once by the server (`principalResolver`), not by each route. `SessionAuthenticator` is, for the boundary that resolves a whole session with `resolveSession`.
+- A `Session` or an `ExecutionContext` declared by the project itself, or imported from another module than the kernel, is not reported in `domain/`.
+
+## 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/clean-blank-lines.md

@@ -0,0 +1,87 @@
+# clean/blank-lines (layout)
+
+Architecture id: `clean/blank-lines`. Default severity: `error` in `recommended`, `error` in `strict`. Fixable with `--fix`.
+
+Applies to: every linted TypeScript file.
+
+Not a rule of this plugin: two rules of [`@stylistic/eslint-plugin`](https://eslint.style) hold it, configured by the presets and exported as `standardRules.layout`.
+
+## Why
+
+A function reads as paragraphs: what it declares, what it decides, what it answers. A blank line before every `return` and between the logical blocks makes those paragraphs visible, and makes a block that has grown too many of them look like what it is, a function to split.
+
+## Reported
+
+- a `return` that is not alone in its block and has no blank line before it
+- no blank line after a group of declarations (`const`, `let`), or around an `if`, a `for`, a `while`, a `do`, a `try`, a `switch` or a block
+- no blank line around a statement or a declaration written on several lines
+- no blank line before or after a method of a class
+
+Incorrect:
+
+```ts
+function total(lines: readonly Line[]): number {
+  const amounts = lines.map((line) => line.amount);
+  if (amounts.length === 0) {
+    return 0;
+  }
+  return amounts.reduce((sum, amount) => sum + amount, 0);
+}
+```
+
+Correct:
+
+```ts
+function total(lines: readonly Line[]): number {
+  const amounts = lines.map((line) => line.amount);
+
+  if (amounts.length === 0) {
+    return 0;
+  }
+
+  return amounts.reduce((sum, amount) => sum + amount, 0);
+}
+```
+
+## Details
+
+What may stay together: consecutive one-line declarations; consecutive `case` labels; consecutive fields of a class, and consecutive abstract signatures of a port; the overloads of a method.
+
+```js
+'@stylistic/padding-line-between-statements': [level,
+  { blankLine: 'always', prev: '*', next: 'return' },
+  { blankLine: 'always', prev: ['const', 'let', 'var'], next: '*' },
+  { blankLine: 'any', prev: ['const', 'let', 'var'], next: ['const', 'let', 'var'] },
+  { blankLine: 'always', prev: '*', next: ['if', 'for', 'while', 'do', 'try', 'switch', 'block-like'] },
+  { blankLine: 'always', prev: ['if', 'for', 'while', 'do', 'try', 'switch', 'block-like'], next: '*' },
+  { blankLine: 'always', prev: '*', next: ['multiline-const', 'multiline-let', 'multiline-var', 'multiline-expression'] },
+  { blankLine: 'always', prev: ['multiline-const', 'multiline-let', 'multiline-var', 'multiline-expression'], next: '*' },
+  { blankLine: 'any', prev: ['case', 'default'], next: ['case', 'default'] },
+],
+'@stylistic/lines-between-class-members': [level, { enforce: [
+  { blankLine: 'always', prev: '*', next: 'method' },
+  { blankLine: 'always', prev: 'method', next: '*' },
+] }, { exceptAfterOverload: true }],
+```
+
+`dddTsKit()` and the two presets register the plugin under `@stylistic` and enable the two rules. A blank line right after `{` or right before `}`, two blank lines in a row and a blank line at an end of a file are removed by the formatter ([`clean/formatted`](clean-formatted.md)), not reported here. In a config composed by hand:
+
+```js
+import stylistic from '@stylistic/eslint-plugin';
+import { standardRules } from '@ddd-ts-kit/eslint-plugin';
+
+export default [{ files: ['**/*.ts'], plugins: { '@stylistic': stylistic }, rules: standardRules.layout }];
+```
+
+## Options
+
+None. `rules."clean/blank-lines"` in `ddd-ts-kit.config.json` gives the two rules their severity in `dddTsKit()`: `error` (default), `warn`, or `off`, which leaves them out. The `ddd-ts-kit-disable-next-line` comment does not reach these rules: they are not rules of this plugin, and both are fixed by `eslint --fix --fix-type layout`.
+
+## Limits
+
+- The rules judge blank lines, not line breaks, indentation or line length: the formatter of the project does, and keeps the blank lines it finds.
+- A blank line required on both sides of a multiline statement applies inside a group of declarations too: a `const` written on several lines is set apart from the one-line `const` around it.
+
+## With the CLI checker
+
+`ddd-ts-kit check` holds the cheap part only, as an approximation: a `return` glued to the statement above it, and a padded block of statements. It leaves the braces that hold no statement alone: an object literal, a type literal, an interface, an enum, a destructuring pattern, a list of imports or exports. These rules are the authority.

package/docs/rules/clean-braces.md

@@ -0,0 +1,61 @@
+# clean/braces (layout)
+
+Architecture id: `clean/braces`. Default severity: `error` in `recommended`, `error` in `strict`. Fixable with `--fix`.
+
+Applies to: every linted TypeScript file, and in `dddTsKit()` every linted `.js`, `.mjs` and `.cjs` file.
+
+Not a rule of this plugin: `curly` of ESLint holds it, configured by the presets and exported as `standardRules.braces`.
+
+## Why
+
+A branch written between braces, its body on its own lines, is visible at a glance, and a statement added to it later cannot silently fall outside it.
+
+## Reported
+
+- an `if`, an `else`, a `for`, a `for..of`, a `for..in`, a `while` or a `do` whose body is not a block
+
+Incorrect:
+
+```ts
+if (wrapped.has(repository)) return repository;
+
+for (const step of steps) await step();
+```
+
+Correct:
+
+```ts
+if (wrapped.has(repository)) {
+  return repository;
+}
+
+for (const step of steps) {
+  await step();
+}
+```
+
+## Details
+
+```js
+curly: [level, 'all'],
+```
+
+Not judged: a ternary, an arrow function returning an expression, `??` and `&&` expressions, a one-line object literal. An `else if` chain stays `} else if (...) {` on the line of the closing brace.
+
+`curly` adds the braces; where they go is the work of the formatter ([`clean/formatted`](clean-formatted.md)), which always breaks a block that holds a statement: `if (a) { return b; }` on one line does not survive `npm run format`, and `npm run format:check` refuses it. That is why `@stylistic/brace-style` is not enabled: it would only repeat what the formatter decides.
+
+In a config composed by hand:
+
+```js
+import { standardRules } from '@ddd-ts-kit/eslint-plugin';
+
+export default [{ files: ['**/*.ts'], rules: standardRules.braces }];
+```
+
+## Options
+
+None. `rules."clean/braces"` in `ddd-ts-kit.config.json` gives `curly` its severity in `dddTsKit()`: `error` (default), `warn`, or `off`, which leaves it out. The `ddd-ts-kit-disable-next-line` comment does not reach it: it is not a rule of this plugin.
+
+## With the CLI checker
+
+`ddd-ts-kit check` holds the same thing on text, as an approximation: a body without braces, a body on the line of its braces, an `else` on a line of its own. This rule and the formatter are the authority.

package/docs/rules/clean-file-size.md

@@ -0,0 +1,43 @@
+# ddd-ts-kit/clean-file-size
+
+Architecture id: `clean/file-size`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file, tests included.
+
+## Why
+
+A file that does not fit in one sitting holds more than one responsibility: two classes that grew together, a function and the helpers of another one, a spec that tests three behaviours. The limit is a signal to split by responsibility, not a number to reach.
+
+## Reported
+
+- a file of more than 350 lines: every physical line counts, comments and blank lines included; a final newline adds none
+
+Incorrect:
+
+```ts
+// invoice.aggregate.spec.ts: 600 lines, issuing, paying and voiding in one file
+```
+
+Correct:
+
+```ts
+// invoice-issuing.spec.ts, invoice-payment.spec.ts, invoice-voiding.spec.ts: one behaviour each
+```
+
+## Details
+
+The finding is reported once, on line 351. Declaration files (`*.d.ts`) and any file under a directory named `generated` are exempt: nobody reads them in one sitting, and nobody writes them.
+
+## Options
+
+None: the limit is 350 lines and is not configurable.
+
+`rules."clean/file-size"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/file-size -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The rule says that a file is too long, not where to cut it: split by responsibility, and name each file after what it holds (`clean/one-export-per-file`).
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id with the same count. Both tools agree.

package/docs/rules/clean-formatted.md

@@ -0,0 +1,32 @@
+# clean/formatted (layout)
+
+Architecture id: `clean/formatted`. No severity: a file is formatted or it is not. Fixable with `npm run format`.
+
+Applies to: every TypeScript, JavaScript and JSON file of the project.
+
+Not a rule of this plugin, and not a rule of ESLint: the formatter of the project, [Biome](https://biomejs.dev), holds it with the `biome.json` that `ddd-ts-kit init` writes.
+
+## Why
+
+One way to lay out a file leaves nothing to discuss in a review and nothing to decide while writing: a line is at most 120 columns wide, and a diff shows what changed, never how somebody likes their line breaks.
+
+## Checked
+
+- `npm run format:check` (`biome format .`) reports nothing to change; it runs on staged files before a commit, in `npm run verify` and in the lint job of the pipeline
+- `npm run format` (`biome format --write .`) settles it
+
+The settings: line width 120, two spaces, LF, single quotes, trailing commas, semicolons, parentheses around the parameter of an arrow function. The linter and the import organiser of Biome are off: ESLint with this plugin is the only linter, and the formatter never reorders an import.
+
+## With ESLint
+
+The presets enable no rule that decides where a token goes, so the two never fight: `biome format --write` then `eslint --fix` then `biome format` reports nothing to change. What ESLint keeps is what a formatter does not decide: the blank lines between statements ([`clean/blank-lines`](clean-blank-lines.md)) and the braces of a branch ([`clean/braces`](clean-braces.md)).
+
+## Limits
+
+- Markdown and YAML are not formatted.
+- Generated artifacts compared byte for byte by their own check (`openapi/*.json`, `asyncapi.json`, `.dependency-cruiser.cjs`) and build outputs are left out in `biome.json`.
+- A string literal, a URL or a regular expression longer than 120 columns stays on its line: a formatter does not cut a token.
+
+## With the CLI checker
+
+`ddd-ts-kit rules` lists the id and `ddd-ts-kit explain clean/formatted` says who decides; `ddd-ts-kit check` judges nothing here.