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

package/docs/rules/events-consumer-idempotent.md

@@ -0,0 +1,68 @@
+# ddd-ts-kit/events-consumer-idempotent
+
+Architecture id: `events/consumer-idempotent`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every file of a context, tests excluded; the direct `subscribe` only in `application/` and the module file.
+
+## Why
+
+Delivery is at least once. A consumer without a stable name and a processed-event store handles a redelivered event a second time: the invoice is issued twice. The name is the idempotency scope, so it is written once and never derived.
+
+## Reported
+
+- `<builder>.on(definition)` or `<builder>.on(definition, {})` followed by `.handledBy(...)` or `.handledByFactory(...)`, without a `consumer` (an empty string counts as absent)
+- `on(definition, handler)` of `@ddd-ts-kit/events` whose third argument does not carry both `consumer` and `processed`
+- in `application/` and the module file: a direct `.subscribe(...)` whose handler is not wrapped by `idempotent(...)`
+- in a declared-style project (`stack.style: "declared"`): a class carrying `@IntegrationEventHandler(...)` of `@ddd-ts-kit/kernel/declarations` whose options do not write `consumer` as a non-empty string literal (missing, empty, a variable, a template with a substitution, options held in a variable or only spread)
+
+Incorrect:
+
+```ts
+builder.on(productListedV1).handledBy(ProductListedHandler, [CommandBus]);
+
+subscribeAll(platform.subscriber, [on(productListedV1, (event) => consumer.handle(event))]);
+
+resolve(IntegrationEventSubscriber).subscribe('catalog.product.listed', (event) => consumer.handle(event));
+
+// declared style
+@IntegrationEventHandler(productListedV1, { consumer: consumerName }, [CommandBus])
+export class CatalogProductListedHandler {}
+```
+
+Correct:
+
+```ts
+builder.on(productListedV1, { consumer: 'billing.price-list' }).handledBy(ProductListedHandler, [CommandBus]);
+
+subscribeAll(platform.subscriber, [
+  on(productListedV1, (event) => consumer.handle(event), { consumer: 'billing.price-list', processed: platform.persistence.processedEvents }),
+]);
+
+// declared style
+@IntegrationEventHandler(productListedV1, { consumer: 'billing.catalog-product-listed' }, [CommandBus])
+export class CatalogProductListedHandler {}
+```
+
+## Details
+
+`on` is recognised by its import from `@ddd-ts-kit/events`, under any local name; `builder.on` by the chain that ends with a handler, which tells it from the `on` of an event emitter. `consume` requires both options by its type and is not judged. `subscribe(type, idempotent(name, store, handler))` is accepted: `idempotent` of the kernel is what `on` and `consume` are built on.
+
+In a declared-style project an integration event handler class is its own registration: `@IntegrationEventHandler(definition, { consumer: '<context>.<reaction>' }, [ports])` satisfies the rule and nothing has to be written in a module file. The decorator counts when its name is imported from `@ddd-ts-kit/kernel/declarations` in the file, under an alias or a namespace too. A module file kept in a declared-style project is judged as in the explicit style. In an explicit-style project the decorator is not read.
+
+## Options
+
+None.
+
+`rules."events/consumer-idempotent"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line events/consumer-idempotent -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Options held in a variable or spread from another object are not followed: nothing is reported as missing.
+- That the consumer name is unique and stable over time is not checked here: ESLint judges one file at a time, and two `@IntegrationEventHandler`, or one and a module registration, live in two files. `ddd-ts-kit check` compares the names of the whole project, decorators included, and `createApplication` refuses a name declared twice for the same event.
+- That a `*.integration-handler.ts` file carries `@IntegrationEventHandler` at all is the business of `declarations-role-declared`, which also reports the unwritten `consumer`.
+- That the store is transactional, or that the mark commits with the handler, is not checked: prefer `consume`, or pass `unitOfWork`.
+- Any `.subscribe(...)` in `application/` or the module file is taken for an event subscription, whatever the receiver 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. This rule is the authority.

package/docs/rules/events-name-format.md

@@ -0,0 +1,50 @@
+# ddd-ts-kit/events-name-format
+
+Architecture id: `events/name-format`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/events/` and `published-language/` of a context, tests excluded.
+
+## Why
+
+An event name is a public address: consumers subscribe to it, the catalog lists it. `<context>.<aggregate>.<fact>` says who owns it and what happened.
+
+## Reported
+
+- in `domain/events/`: a `name` property or object key whose string is not `<this context>.<aggregate>.<fact>` in kebab-case
+- in `published-language/`: the `type` given to `defineIntegrationEvent`, and any other `type` holding a dotted string
+
+Incorrect:
+
+```ts
+export class InvoiceIssued implements DomainEvent {
+  readonly name = 'InvoiceIssued';
+}
+```
+
+Correct:
+
+```ts
+export class InvoiceIssued implements DomainEvent {
+  readonly name = 'billing.invoice.issued';
+}
+```
+
+## Details
+
+Template literals without interpolation are read like strings.
+
+## Options
+
+None.
+
+`rules."events/name-format"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line events/name-format -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The shape and the context prefix are checked, not the grammar of the fact (past tense is checked by the generator).
+- A name built at run time (`${context}.invoice.issued`) is not read.
+- That an integration event is declared once, with a payload, is checked by `ddd-ts-kit check` (`events/defined-in-published-language`).
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id and owns the companion rule `events/defined-in-published-language`. This rule is the authority for the format.

package/docs/rules/events-outbox-required.md

@@ -0,0 +1,57 @@
+# ddd-ts-kit/events-outbox-required
+
+Architecture id: `events/outbox-required`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` and `application/` of a context, tests excluded.
+
+## Why
+
+Publishing an integration event and committing the state change it describes must succeed or fail together. A handler that talks to a broker does both separately: the event leaves and the transaction rolls back, or the reverse. The handler writes to the `IntegrationEventPublisher` port; the composition root binds it to the outbox, and a relay publishes afterwards.
+
+## Reported
+
+- an import of a broker client: `amqplib`, `kafkajs`, `nats`, `@aws-sdk/client-sqs`, `@aws-sdk/client-sns`, `@google-cloud/pubsub`, `@ddd-ts-kit/rabbitmq` (configurable)
+- an import of a concrete bus: `InMemoryEventBus`, `OutboxRelay`, `OutboxPublisher`, from any module, type-only imports included
+- in `application/integration/publishers/`: a constructor parameter whose type is named `...EventBus` or `...Relay`
+
+Incorrect:
+
+```ts
+// application/integration/publishers/invoice-issued.publisher.ts
+import type { RabbitMqEventBus } from '@ddd-ts-kit/rabbitmq';
+
+export class InvoiceIssuedPublisher {
+  constructor(private readonly bus: RabbitMqEventBus) {}
+}
+```
+
+Correct:
+
+```ts
+import type { IdGenerator, IntegrationEventPublisher } from '@ddd-ts-kit/kernel';
+
+export class InvoiceIssuedPublisher {
+  constructor(private readonly publisher: IntegrationEventPublisher, private readonly ids: IdGenerator) {}
+}
+```
+
+## Details
+
+Static imports, type-only imports, `export ... from`, dynamic `import()` and `require()` are read for the broker packages; the concrete buses are recognised by their exported name, whatever they are renamed to.
+
+## Options
+
+`[{ "brokerPackages": ["amqplib", "bullmq"] }]` replaces the default list of broker clients.
+
+`rules."events/outbox-required"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line events/outbox-required -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- That the port is bound to an `OutboxPublisher` in the composition root, and that `stack.events` is `outbox` whenever `stack.orm` is set, is a matter of configuration and wiring: `ddd-ts-kit check` holds it.
+- A handler that calls a broker through a port of its own (`NotificationQueue`) is not seen: the name of a port says nothing of what is behind.
+- Outside `application/integration/publishers/` a constructor parameter typed `EventBus` is not reported: the kernel type is a port, only the publisher has a narrower one to prefer.
+- A broker client that is not in the list is reported by `layer/application-inward` as a package, not by this rule.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files and owns the configuration side. This rule is the authority for the code.

package/docs/rules/governance-recorded-deviation.md

@@ -0,0 +1,55 @@
+# ddd-ts-kit/governance-recorded-deviation
+
+Architecture id: `governance/recorded-deviation`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+The architecture can be changed deliberately, not bypassed case by case. A suppression is either refused or recorded as a decision, with its reason, its scope and the condition for removing it. A shortcut that is not written down is a defect, whoever asked for it.
+
+## Reported
+
+- `eslint-disable`, `eslint-disable-line`, `eslint-disable-next-line` and `ddd-ts-kit-disable-next-line` whose reason after `--` holds no `ADR-<digits>`
+- the same comments when they name no rule at all, whatever follows `--`
+
+Incorrect:
+
+```ts
+/* eslint-disable */
+// eslint-disable-next-line no-console -- the CLI prints its result
+console.log(result);
+```
+
+Correct:
+
+```ts
+// eslint-disable-next-line no-console -- ADR-0012: the CLI prints its result
+console.log(result);
+```
+
+## Details
+
+Record the decision with `ddd-ts-kit generate adr`, then reference its number.
+
+ESLint drops a report made inside the range of a directive that covers its rule, so a blanket `/* eslint-disable */` would silence the very rule that judges it. Such a comment (blanket, or naming `ddd-ts-kit/governance-recorded-deviation` without a decision record) is therefore reported ahead of the range it opens: at the first position of the file for `eslint-disable`, on the line above for `eslint-disable-line`. The message always gives the line of the comment.
+
+`clean/no-escape-hatch` reports an `eslint-disable` with no reason at all; this rule asks more of the reason. With both enabled, a comment without any reason is reported twice.
+
+## Options
+
+None.
+
+`rules."governance/recorded-deviation"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line governance/recorded-deviation -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- That `docs/adr/` holds the record named is not checked here: `ddd-ts-kit check` does.
+- The other deviations of the architecture reference (a lowered severity, an extra directory, an extra allowed package in `ddd-ts-kit.config.json`) are not sources: `ddd-ts-kit check` judges them.
+- A suppression written in the ESLint config (`rules: { ...: 'off' }`, `ignores`) or on the command line is out of reach of any rule.
+- The report placed ahead of a blanket disable relies on the order in which ESLint applies directives; `// eslint-disable-next-line ddd-ts-kit/governance-recorded-deviation` written on the line above a comment still silences its report.
+- `@ts-expect-error` and `@ts-ignore` are held by `@typescript-eslint/ban-ts-comment`.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id for the suppressions and for the config, and verifies that the decision record exists. This rule is the authority for the comments ESLint understands.

package/docs/rules/imports-alias-only.md

@@ -0,0 +1,73 @@
+# ddd-ts-kit/imports-alias-only
+
+Architecture id: `imports/alias-only`. Default severity: `error` in `recommended`, `error` in `strict`. Fixable (`eslint --fix`).
+
+Applies to: every TypeScript file under the source root, under `test/` and under `scripts/`.
+
+## Why
+
+An alias names a file from the root of the project. The import reads the same from every file, says which context and which layer it reaches without counting `../`, and does not change when the importing file moves. One spelling also means one thing to review: the layer and context rules of this plugin, `ddd-ts-kit check` and dependency-cruiser resolve an alias exactly as they resolve a relative path, so a boundary is never crossed by choosing the other spelling.
+
+The alias is declared once, under `paths` in `tsconfig.json`, which the compiler and the tools read. Node reads no alias: `ddd-ts-kit build-aliases`, the second step of `npm run build`, rewrites each alias of the compiled output into a relative path, so the output runs with plain `node`: no loader, no runtime dependency. See [Import aliases](../../../../docs/tools/import-aliases.md).
+
+## Reported
+
+- a relative specifier, `./x.js` or `../x.js`, the same directory included: fixed to the alias of the file
+- a relative specifier that names a file under no aliased directory (a manifest, a build product): reported, not fixed
+- an alias specifier with a `.` or `..` segment, which could name a file outside the directory of the alias: reported, not fixed
+
+Incorrect:
+
+```ts
+// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { Invoice } from '../../../domain/aggregates/invoice.aggregate.js';
+import { IssueInvoiceCommand } from './issue-invoice.command.js';
+
+// test/e2e/issue-invoice.e2e.spec.ts
+import { startApplication } from './support/start-application.js';
+```
+
+Correct:
+
+```ts
+// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command.js';
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.js';
+
+// test/e2e/issue-invoice.e2e.spec.ts
+import { startApplication } from '$test/e2e/support/start-application.js';
+```
+
+## Details
+
+Static imports, type-only imports, `export ... from`, `export *`, dynamic `import()`, `import()` types and `require()` are all read. A dynamic import whose specifier is computed is not judged.
+
+The aliases of a project:
+
+| Alias | Directory | Declared by |
+|---|---|---|
+| `importAlias` of `ddd-ts-kit.config.json`, `@/` by default | `sourceRoot` | the config |
+| `$test/` | `test/` | fixed |
+| `$scripts/` | `scripts/` | fixed |
+| `$generated/` | `generated/`, with `stack.orm` `prisma` only | fixed |
+
+The fix computes the alias from the place of the file and the config: the relative specifier is resolved from the directory of the file, and the result is written from the directory its alias names, with a `.js` extension. It keeps the quotes of the specifier. A fixed import is often longer than the line: run the formatter after the fix (`npm run format`). Fixing twice changes nothing.
+
+Not judged: a file outside the three directories (a config file at the project root, a JavaScript migration), the client under `generated/`, which a tool writes, and a specifier that is neither relative nor one of the aliases (a package, a Node built-in).
+
+An alias that names no file is not this rule's concern: the compiler reports it (`TS2307`), and the build refuses it (`ddd-ts-kit build-aliases`).
+
+## Options
+
+None. `sourceRoot` and `importAlias` of `ddd-ts-kit.config.json` say what the alias of the sources is.
+
+`rules."imports/alias-only"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line imports/alias-only -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Only a module the build emits can be named by the alias: a JSON file or another asset is read at run time instead of imported.
+- The rule does not check that `tsconfig.json` declares the alias, nor that the build rewrites it: `imports/alias-declared` of `ddd-ts-kit check` does, with everything else that has to follow the one declaration.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the import specifiers it reads in the text of the files, under the source root, `test/` and `scripts/`, and gives the alias to write in its fix sentence. This rule is the one that rewrites the import.

package/docs/rules/layer-application-inward.md

@@ -0,0 +1,62 @@
+# ddd-ts-kit/layer-application-inward
+
+Architecture id: `layer/application-inward`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `application/` of a context, tests excluded.
+
+## Why
+
+Use cases orchestrate the domain through ports. An import of an adapter, a driver or a framework makes the use case impossible to run with fakes and moves a technical decision into the application.
+
+## Reported
+
+- a package outside `applicationAllowedPackages`
+- `@ddd-ts-kit/aspects`, `@ddd-ts-kit/audit`, `@ddd-ts-kit/redis`, `@ddd-ts-kit/scheduling`, `@ddd-ts-kit/sentry` and `@ddd-ts-kit/tracing`, by any entry (`.`, `/decorators`, `/testing`, `/node`, ...), with a message of their own: they apply or record a concern from outside the use cases
+- any Node built-in
+- `infrastructure/`, `presentation/` or the module file of the same context
+- the platform or `main.ts`
+
+Incorrect:
+
+```ts
+// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { eq } from 'drizzle-orm';
+import { retry } from '@ddd-ts-kit/aspects';
+import { RedisCache } from '@ddd-ts-kit/redis';
+import { DrizzleInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.js';
+```
+
+Correct:
+
+```ts
+// a port is an abstract class: the type of the dependency and its injection token
+import { Cache, Clock } from '@ddd-ts-kit/kernel';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+import { PaymentGateway } from '@/contexts/billing/application/ports/payment-gateway.port.js';
+
+// declared style
+import { CommandHandler } from '@ddd-ts-kit/kernel/declarations';
+
+@CommandHandler(IssueInvoiceCommand, [InvoiceRepository, PaymentGateway, Clock])
+export class IssueInvoiceHandler implements CommandHandler<IssueInvoiceCommand> {}
+```
+
+## 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. `applicationAllowedPackages` in `ddd-ts-kit.config.json` replaces the allow-list, which defaults to `@ddd-ts-kit/kernel` and `@ddd-ts-kit/auth` (permissions and policies are declared in `application/authorization/`). In a declared-style project (`stack.style: "declared"`) `@ddd-ts-kit/kernel/declarations` is allowed whatever the list says: a handler, a consumer or a policy says what it is with a decorator of that entry, which is pure metadata. In an explicit-style project the entry is allowed like the rest of `@ddd-ts-kit/kernel`, by the list. `@ddd-ts-kit/aspects`, `@ddd-ts-kit/audit`, `@ddd-ts-kit/redis` and `@ddd-ts-kit/tracing` stay refused even when the list names them: an aspect is applied at the composition root (`.with(...)` on a binding, the `decorate` hook), in a bus middleware or on an adapter in `infrastructure/`; a use case depends on the port (`Cache` of the kernel, a port in `application/ports/`) and the platform binds the Redis adapter; the audit trail is fed by the bus middleware, the authorization hook and an event subscription, never by a use case. The only way around is a recorded suppression of the line.
+
+`rules."layer/application-inward"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line layer/application-inward -- <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, fast enough for an editor hook. This rule is the authority: it reads the syntax tree.

package/docs/rules/layer-domain-purity.md

@@ -0,0 +1,60 @@
+# ddd-ts-kit/layer-domain-purity
+
+Architecture id: `layer/domain-purity`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` of a context, tests excluded.
+
+## Why
+
+The domain is the part of the system that must survive a change of framework, ORM or transport. Every outward import ties a business rule to a technical decision and makes it untestable without that technology.
+
+## Reported
+
+- a package outside `domainAllowedPackages` (default: `@ddd-ts-kit/kernel`)
+- `@ddd-ts-kit/aspects`, `@ddd-ts-kit/audit`, `@ddd-ts-kit/redis`, `@ddd-ts-kit/scheduling`, `@ddd-ts-kit/sentry` and `@ddd-ts-kit/tracing`, by any entry (`.`, `/decorators`, `/testing`, `/node`, ...), with a message of their own: they apply or record a concern from outside the model
+- in a declared-style project (`stack.style: "declared"`): `@ddd-ts-kit/kernel/declarations`, even though `@ddd-ts-kit/kernel` is allowed, with a message of its own: the domain declares nothing
+- any Node built-in
+- another layer of the same context, the platform, `main.ts`
+- the published language of another context (translate it in an integration event handler or an anti-corruption layer)
+
+Incorrect:
+
+```ts
+// src/contexts/billing/domain/aggregates/invoice.aggregate.ts
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { Logged } from '@ddd-ts-kit/aspects/decorators';
+import type { InvoiceRow } from '@/contexts/billing/infrastructure/persistence/billing.schema.js';
+```
+
+Correct:
+
+```ts
+// src/contexts/billing/domain/aggregates/invoice.aggregate.ts
+import { AggregateRoot } from '@ddd-ts-kit/kernel';
+import type { Amount } from '@/contexts/billing/domain/value-objects/amount.vo.js';
+import { Money } from '@/shared-kernel/money.vo.js';
+```
+
+## Details
+
+Aggregates, entities, value objects, events, services and repository ports carry no decorator and no dependency list: the decorator goes on the class of `application/` or `infrastructure/` that plays a role, and a port is an abstract class of `domain/repositories/` or `application/ports/`. The refusal of the declarations entry holds even when `domainAllowedPackages` names it. An explicit-style project is judged as before: the entry is part of `@ddd-ts-kit/kernel` there. A decorator that is nevertheless carried by a class of `domain/` is reported by `declarations-role-declared`.
+
+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. `domainAllowedPackages` in `ddd-ts-kit.config.json` extends the allow-list. The four packages above stay refused even when the list names them: logging, metrics, retry, timeout, circuit breaking, caching and tracing reach the model from the composition root (`.with(...)` on a binding, the `decorate` hook), a bus middleware or an adapter in `infrastructure/`; Redis sits behind a port; the audit trail is fed by the bus middleware, the authorization hook and an event subscription. The only way around is a recorded suppression of the line.
+
+`rules."layer/domain-purity"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line layer/domain-purity -- <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.
+- Internals of another context are left to `context-published-language-only`, so that one import gives one report.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from a regex reading of the file, fast enough for an editor hook. This rule is the authority: it reads the syntax tree.

package/docs/rules/layer-infrastructure-no-presentation.md

@@ -0,0 +1,46 @@
+# ddd-ts-kit/layer-infrastructure-no-presentation
+
+Architecture id: `layer/infrastructure-no-presentation`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `infrastructure/` of a context, tests excluded.
+
+## Why
+
+Adapters implement ports of the application and the domain. An adapter that knows a DTO of the transport couples persistence to HTTP: the shared type belongs to the application.
+
+## Reported
+
+- an import of `presentation/` of the same context
+
+Incorrect:
+
+```ts
+// src/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.ts
+import type { IssueInvoiceBody } from '@/contexts/billing/presentation/http/issue-invoice.dto.js';
+```
+
+Correct:
+
+```ts
+import type { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.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."layer/infrastructure-no-presentation"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line layer/infrastructure-no-presentation -- <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, fast enough for an editor hook. This rule is the authority: it reads the syntax tree.

package/docs/rules/layer-presentation-no-infrastructure.md

@@ -0,0 +1,46 @@
+# ddd-ts-kit/layer-presentation-no-infrastructure
+
+Architecture id: `layer/presentation-no-infrastructure`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `presentation/` of a context, tests excluded.
+
+## Why
+
+A route translates a request into a command or a query and a result into a response. When it reaches an adapter directly, the use case is bypassed and so are its rules, its unit of work and its authorization.
+
+## Reported
+
+- an import of `infrastructure/` of the same context
+
+Incorrect:
+
+```ts
+// src/contexts/billing/presentation/http/issue-invoice.route.ts
+import { DrizzleInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.js';
+```
+
+Correct:
+
+```ts
+import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command.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."layer/presentation-no-infrastructure"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line layer/presentation-no-infrastructure -- <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, fast enough for an editor hook. This rule is the authority: it reads the syntax tree.

package/docs/rules/ports-abstract-class.md

@@ -0,0 +1,70 @@
+# ddd-ts-kit/ports-abstract-class
+
+Architecture id: `ports/abstract-class`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: port files of a context: `domain/repositories/*.repository.ts` and `application/ports/*.port.ts`.
+
+## Why
+
+A port is an abstract class with abstract members only. The class is the contract and the injection token at once: it names the dependency in a dependency list, carries its type to the constructor, and there is no constant and no token file to keep in step with it. A port that holds a body, a field or a constructor is a base class in disguise: adapters start to inherit behaviour, and a fake no longer fits.
+
+## Reported
+
+- a class that is not `abstract`
+- a constructor
+- a `private`, `protected` or `#` member
+- a method with a body, a property with an initializer, a member that is not `abstract`
+- an exported `interface`: a port is declared as an abstract class
+
+Incorrect:
+
+```ts
+// application/ports/payment-gateway.port.ts
+export interface PaymentGateway {
+  charge(invoiceId: string): Promise<void>;
+}
+
+// domain/repositories/invoice.repository.ts
+export abstract class InvoiceRepository {
+  constructor(protected readonly table: string) {}
+
+  async exists(id: string): Promise<boolean> {
+    return (await this.findById(id)) !== undefined;
+  }
+}
+```
+
+Correct:
+
+```ts
+// application/ports/payment-gateway.port.ts
+export abstract class PaymentGateway {
+  abstract charge(invoiceId: string): Promise<void>;
+}
+
+// domain/repositories/invoice.repository.ts
+import { Repository } from '@ddd-ts-kit/kernel';
+
+export abstract class InvoiceRepository extends Repository<Invoice> {}
+```
+
+## Details
+
+A port may extend another one: the kernel `Repository<A>`, or a port of the same context. One member is allowed besides the abstract ones: `static readonly tokenKey = '<package>.<Port>'`, a string literal that gives the port one identity when its package is loaded twice. A value that is not a port (settings, a database handle) is typed the same way, by an abstract class with `abstract readonly` properties.
+
+An exported `type` alias is not reported: the shape of the data that travels through the port may be a type. An interface that is not exported is left alone too.
+
+## Options
+
+None.
+
+`rules."ports/abstract-class"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line ports/abstract-class -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A member inherited from a class of another file is not read: `@Repository`, `@Gateway` and `@Adapter` refuse a port with a body when the file loads.
+- A port declared outside the two port folders is not judged.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files. This rule is the authority for the code.

package/docs/rules/ports-implements-never-extends.md

@@ -0,0 +1,53 @@
+# ddd-ts-kit/ports-implements-never-extends
+
+Architecture id: `ports/implements-never-extends`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+An adapter honours a contract; it does not inherit from it. `implements` lets the compiler check the adapter against the port and keeps the port free of behaviour, so that a fake, an in-memory class and a remote client are interchangeable. `extends` turns the port into a base class and ties every adapter to it.
+
+## Reported
+
+- a class carrying `@Repository(Port, ..)`, `@Gateway(Port, ..)` or `@Adapter(Port, ..)` that does not write `implements Port`, or that `extends Port`
+- the class given to `bind(Port).toClass(Class, ..)` or `rebind(Port).toClass(Class, ..)` that does not implement `Port`, or that extends it
+- under `infrastructure/` of a context: a class that `extends` a class imported from a port file
+
+Incorrect:
+
+```ts
+@Repository(InvoiceRepository, [Database])
+export class KnexInvoiceRepository extends InvoiceRepository {}
+
+builder.bind(PaymentGateway).toClass(StripePaymentGateway, [PaymentSettings]);
+// where: export class StripePaymentGateway {}
+```
+
+Correct:
+
+```ts
+@Repository(InvoiceRepository, [Database])
+export class KnexInvoiceRepository implements InvoiceRepository {}
+
+export class StripePaymentGateway implements PaymentGateway {}
+```
+
+## Details
+
+The class given to `toClass` is looked up in the linted file, then in the file it is imported from by a relative path or the import alias: that file is read from disk and parsed without types. When it cannot be found (a class of a package, a barrel, a renaming export), nothing is reported. A class bound to itself (`bind(Registry).toClass(Registry)`) is no port and is not judged. Port files are `domain/repositories/*.repository.ts` and `application/ports/*.port.ts`.
+
+## Options
+
+None.
+
+`rules."ports/implements-never-extends"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line ports/implements-never-extends -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- `implements` is compared by name: `implements kernel.Clock` for a port named `Clock` is not recognised; import the port by name.
+- An adapter that extends its port through an intermediate class of another file is not seen: the decorators refuse it when the file loads.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files. This rule is the authority for the code.