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

package/docs/rules/ports-no-concrete-dependency.md

@@ -0,0 +1,52 @@
+# ddd-ts-kit/ports-no-concrete-dependency
+
+Architecture id: `ports/no-concrete-dependency`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+A dependency list names ports, never what implements them. A handler that lists `KnexInvoiceRepository` is wired to one technology, cannot be given a fake, and makes the application layer depend on infrastructure through its own registration.
+
+## Reported
+
+- a class named in a dependency list and imported from `infrastructure/` of a context
+- a class named in a dependency list and imported from `test/fakes/` of a context
+
+Incorrect:
+
+```ts
+import { KnexInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/knex-invoice.repository.js';
+
+@CommandHandler(IssueInvoiceCommand, [KnexInvoiceRepository, Clock])
+export class IssueInvoiceHandler {}
+```
+
+Correct:
+
+```ts
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+
+@CommandHandler(IssueInvoiceCommand, [InvoiceRepository, Clock])
+export class IssueInvoiceHandler {}
+```
+
+## Details
+
+A dependency list is the array that names what a constructor receives: the last argument of a declaration decorator of `@ddd-ts-kit/kernel/declarations` (`@CommandHandler(M, [..])`, `@QueryHandler`, `@IntegrationEventHandler`, `@DomainEventHandler`, `@Scheduled`, `@Repository`, `@Gateway`, `@Adapter`, `@Policy`) and the second argument of `.toClass(C, [..])` and `.handledBy(H, [..])` of `@ddd-ts-kit/di`.
+
+The first argument of `toClass` and `handledBy` is the implementation and is not part of the list: `builder.bind(InvoiceRepository).toClass(KnexInvoiceRepository, [Database])` is how a module says which class stands behind a port. The origin of a name is read from its import, through relative paths and the configured `importAlias`.
+
+## Options
+
+None.
+
+`rules."ports/no-concrete-dependency"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line ports/no-concrete-dependency -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A concrete class declared in the same file, or reached through a barrel outside `infrastructure/`, is not seen: the compiler refuses a concrete class where its port is expected.
+
+## 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-no-token-constant.md

@@ -0,0 +1,57 @@
+# ddd-ts-kit/ports-no-token-constant
+
+Architecture id: `ports/no-token-constant`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+A port class is its own injection token. A constant next to it, a `token(..)` helper, a symbol or a string is a second name for the same thing: it has to be kept in step by hand, it loses the type, and it hides the dependency list from the compiler.
+
+## Reported
+
+- a call of `token`, imported from a package of the kit (`@ddd-ts-kit/*`), by name, by alias or through a namespace
+- `Symbol(..)`, `Symbol.for(..)` or a string literal given as first argument of a binding call, and a variable declared as such a symbol given to one
+- an identifier in upper snake case (two characters at least) in a dependency list
+- a file named `*.ports.ts` or `tokens.ts` under the source root, reported on its first line
+
+Incorrect:
+
+```ts
+// a constant that stands for the port, in a file that collects them
+export const invoiceRepositoryToken = Symbol('billing.InvoiceRepository');
+
+builder.bind(invoiceRepositoryToken).toClass(KnexInvoiceRepository, [Database]);
+builder.bind('clock').toValue(clock);
+```
+
+Correct:
+
+```ts
+// domain/repositories/invoice.repository.ts
+export abstract class InvoiceRepository extends Repository<Invoice> {}
+
+builder.bind(InvoiceRepository).toClass(KnexInvoiceRepository, [Database]);
+builder.bind(Clock).toValue(clock);
+```
+
+## Details
+
+A dependency list is the array that names what a constructor receives: the last argument of a declaration decorator of `@ddd-ts-kit/kernel/declarations` (`@CommandHandler(M, [..])`, `@QueryHandler`, `@IntegrationEventHandler`, `@DomainEventHandler`, `@Scheduled`, `@Repository`, `@Gateway`, `@Adapter`, `@Policy`) and the second argument of `.toClass(C, [..])` and `.handledBy(H, [..])` of `@ddd-ts-kit/di`.
+
+A binding call is `bind`, `rebind`, `resolve`, `fake` or `override`, plain or as a member (`builder.bind(X)`, `app.resolve(X)`), and is read only in a file that imports something from `@ddd-ts-kit/di`; `Promise.resolve`, `path.resolve`, `require.resolve` and `import.meta.resolve` are never binding calls.
+
+## Options
+
+None.
+
+`rules."ports/no-token-constant"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line ports/no-token-constant -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A token made by a home-made helper, or a symbol declared in another file, is not followed.
+- An upper snake case name is reported in a dependency list only: a constant of the domain anywhere else is not a token.
+
+## 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-value-import.md

@@ -0,0 +1,55 @@
+# ddd-ts-kit/ports-value-import
+
+Architecture id: `ports/value-import`. Default severity: `error` in `recommended`, `error` in `strict`. Fixable with `--fix`.
+
+Applies to: every linted file.
+
+## Why
+
+The abstract class of a port is a value: it is what a container binds and resolves. `import type` erases it when the file is compiled, so a dependency list that names a type-only import has nothing to name at run time.
+
+## Reported
+
+- a name in a dependency list imported with `import type { X }` or `import { type X }`
+- the first argument of `bind` or `rebind` imported that way
+
+Incorrect:
+
+```ts
+import type { Clock } from '@ddd-ts-kit/kernel';
+
+@CommandHandler(IssueInvoiceCommand, [Clock])
+export class IssueInvoiceHandler {}
+```
+
+Correct:
+
+```ts
+import { Clock } from '@ddd-ts-kit/kernel';
+
+@CommandHandler(IssueInvoiceCommand, [Clock])
+export class IssueInvoiceHandler {}
+```
+
+## Details
+
+A dependency list is the array that names what a constructor receives: the last argument of a declaration decorator of `@ddd-ts-kit/kernel/declarations` (`@CommandHandler(M, [..])`, `@QueryHandler`, `@IntegrationEventHandler`, `@DomainEventHandler`, `@Scheduled`, `@Repository`, `@Gateway`, `@Adapter`, `@Policy`) and the second argument of `.toClass(C, [..])` and `.handledBy(H, [..])` of `@ddd-ts-kit/di`.
+
+A binding call is `bind`, `rebind`, `resolve`, `fake` or `override`, plain or as a member (`builder.bind(X)`, `app.resolve(X)`), and is read only in a file that imports something from `@ddd-ts-kit/di`; `Promise.resolve`, `path.resolve`, `require.resolve` and `import.meta.resolve` are never binding calls. Only `bind` and `rebind` are read by this rule.
+
+**The fix.** `import { type X }` loses its keyword; `import type { X, Y }` becomes `import { X, type Y }`, which `@typescript-eslint/consistent-type-imports` then splits if the project asks for separate type imports.
+
+## Options
+
+None.
+
+`rules."ports/value-import"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line ports/value-import -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The compiler reports the same mistake (a type used as a value) when the file is type-checked; this rule reports it at edit time and fixes it.
+- A default or a namespace import is not rewritten by the fix when the declaration is `import type`.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the file. This rule is the authority, and the only one that fixes.

package/docs/rules/purity-no-ambient-randomness.md

@@ -0,0 +1,43 @@
+# ddd-ts-kit/purity-no-ambient-randomness
+
+Architecture id: `purity/no-ambient-randomness`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` and `application/` of a context, tests excluded.
+
+## Why
+
+An identifier drawn inside a rule cannot be predicted by a test nor replayed. Identifiers come from the `IdGenerator` port.
+
+## Reported
+
+- `Math.random`
+- `crypto.randomUUID`, `getRandomValues`, `randomBytes`, `randomInt`, also imported by name from `node:crypto`
+- an import of `uuid`, `nanoid`, `ulid`, `ulidx`, `cuid`, `@paralleldrive/cuid2`, `ksuid`, `shortid`, `uuidv7`, `hyperid`, `bson`
+
+Incorrect:
+
+```ts
+import { v4 } from 'uuid';
+const id = crypto.randomUUID();
+```
+
+Correct:
+
+```ts
+const invoice = Invoice.create(this.ids.next(), this.clock.now());
+```
+
+## Options
+
+None.
+
+`rules."purity/no-ambient-randomness"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line purity/no-ambient-randomness -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A wrapper around the forbidden access (a helper of the platform that calls `Date.now()`) is not seen here; the layer rules stop the import of that helper.
+- A local declaration that shadows the global (`const process = ...`) is not reported.
+
+## With the CLI checker
+
+`ddd-ts-kit check` looks for the same names with regular expressions. This rule is the authority: it knows a shadowed name from the global, and code from a string.

package/docs/rules/purity-no-environment.md

@@ -0,0 +1,45 @@
+# ddd-ts-kit/purity-no-environment
+
+Architecture id: `purity/no-environment`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` and `application/` of a context, tests excluded.
+
+## Why
+
+Configuration, logs, files and the network are the outside world. Reached directly they make a use case depend on the machine it runs on; behind a port they are a parameter.
+
+## Reported
+
+- `process.env`, `argv`, `cwd`, `exit`, `stdout`, `stderr`, `stdin`
+- any member of `console`
+- a call of the global `fetch`, `new XMLHttpRequest`, `new WebSocket`, `new EventSource`
+- an import of `fs`, `http`, `https`, `http2`, `net`, `dgram`, `dns`, `tls`, `child_process`, `worker_threads`, `os`, `readline`, `axios`, `node-fetch`, `undici`, `got`, `dotenv`
+
+Incorrect:
+
+```ts
+const url = process.env['PAYMENT_URL'];
+console.log('charging', amount);
+await fetch(url);
+```
+
+Correct:
+
+```ts
+await this.paymentGateway.charge(amount);
+```
+
+## Options
+
+None.
+
+`rules."purity/no-environment"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line purity/no-environment -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A wrapper around the forbidden access (a helper of the platform that calls `Date.now()`) is not seen here; the layer rules stop the import of that helper.
+- A local declaration that shadows the global (`const process = ...`) is not reported.
+
+## With the CLI checker
+
+`ddd-ts-kit check` looks for the same names with regular expressions. This rule is the authority: it knows a shadowed name from the global, and code from a string.

package/docs/rules/purity-no-system-clock.md

@@ -0,0 +1,49 @@
+# ddd-ts-kit/purity-no-system-clock
+
+Architecture id: `purity/no-system-clock`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: `domain/` and `application/` of a context, tests excluded.
+
+## Why
+
+A rule that reads the clock gives a different answer at every run. Time is an input: the domain receives it, the application takes it from the `Clock` port, a test fixes it with `FixedClock`.
+
+## Reported
+
+- `new Date()` without argument
+- `Date.now`, `Date()`
+- `performance.now`, `performance.timeOrigin`
+- the same through `globalThis`, `window`, `self` or `global`
+
+Incorrect:
+
+```ts
+const overdue = invoice.dueAt < new Date();
+const started = Date.now();
+```
+
+Correct:
+
+```ts
+const overdue = invoice.isOverdue(this.clock.now());
+const due = new Date(issuedAt.getTime() + 30 * DAY);
+```
+
+## Details
+
+`new Date(value)` builds a date from data and is allowed.
+
+## Options
+
+None.
+
+`rules."purity/no-system-clock"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line purity/no-system-clock -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A wrapper around the forbidden access (a helper of the platform that calls `Date.now()`) is not seen here; the layer rules stop the import of that helper.
+- A local declaration that shadows the global (`const process = ...`) is not reported.
+
+## With the CLI checker
+
+`ddd-ts-kit check` looks for the same names with regular expressions. This rule is the authority: it knows a shadowed name from the global, and code from a string.

package/docs/rules/scheduling-job-name.md

@@ -0,0 +1,57 @@
+# ddd-ts-kit/scheduling-job-name
+
+Architecture id: `scheduling/job-name`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file; the `systemActor` check applies to `*.job.ts` files.
+
+## Why
+
+The name of a job is its identity: the lock that keeps an occurrence to one run, its settings, its metrics, its line in the audit trail are keyed by it. It is written once as a string literal, never derived from a class name that may be renamed, and it starts with the context the job belongs to, so that it leaves with the context when it is extracted.
+
+## Reported
+
+- a first argument of `@Scheduled(..)` or of `job(..)` (in a statement ending with `handledBy` or `handledByFactory`) that is not a string literal
+- a name that is not `<context>.<job-name>`: two segments in lower-case kebab-case
+- a name whose first segment is not the context of the file (in a module file, the context of the module)
+- in a `*.job.ts` file: a `systemActor(..)` call that does not pass the name the job is declared with
+
+Incorrect:
+
+```ts
+@Scheduled('SendReminders', { every: '15m' }, [CommandBus])
+export class SendRemindersJob implements ScheduledJob {
+  async run(execution: JobExecution): Promise<void> {
+    await this.commands.execute(new SendRemindersCommand(systemActor('reminders'), execution.scheduledAt));
+  }
+}
+```
+
+Correct:
+
+```ts
+@Scheduled('billing.send-reminders', { every: '15m' }, [CommandBus])
+export class SendRemindersJob implements ScheduledJob {
+  async run(execution: JobExecution): Promise<void> {
+    await this.commands.execute(new SendRemindersCommand(systemActor('billing.send-reminders'), execution.scheduledAt));
+  }
+}
+```
+
+## Details
+
+A template literal without substitution counts as a string literal. Outside a context (`main.ts`, the platform) the format is checked and the first segment is free. In a job file without `@Scheduled` (the explicit style, where the name is written in the module file), `systemActor(..)` must pass a literal that is a job name of the context of the file.
+
+## Options
+
+None.
+
+`rules."scheduling/job-name"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line scheduling/job-name -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- That a job name is unique in the project is a fact of the project: `ddd-ts-kit check` holds it.
+- In the explicit style the name given to `systemActor` in the job file is not compared with the name written in the module file.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the text of the files, and is alone to check that a name is unique project-wide.

package/docs/rules/scheduling-job-triggers-use-case.md

@@ -0,0 +1,71 @@
+# ddd-ts-kit/scheduling-job-triggers-use-case
+
+Architecture id: `scheduling/job-triggers-use-case`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: production files of a context.
+
+## Why
+
+A job is a schedule, not a use case. It sends a command, and the work is in the handler of that command, where it is authorized, transactional, audited and tested like any other use case, and where an operator can also trigger it by hand. A job that loads aggregates and saves them is a use case that escaped all of that.
+
+## Reported
+
+In `application/scheduling/*.job.ts`:
+
+- no exported class implementing `ScheduledJob`
+- a `run` method that calls no `<something>.execute(..)`, or no `run` method
+- a repository (a class imported from `domain/repositories/`) in the dependency list or as the type of a constructor parameter
+- an import from `domain/aggregates/`, `domain/entities/`, `domain/services/` or `infrastructure/`
+
+Anywhere else in a context:
+
+- a class carrying `@Scheduled`
+- `job(..).handledBy(Class, ..)` naming a class imported from a file that is not `application/scheduling/*.job.ts`
+
+Incorrect:
+
+```ts
+// application/scheduling/send-reminders.job.ts
+@Scheduled('billing.send-reminders', { every: '15m' }, [InvoiceRepository, Mailer])
+export class SendRemindersJob implements ScheduledJob {
+  async run(): Promise<void> {
+    for (const invoice of await this.invoices.overdue()) {
+      await this.mailer.remind(invoice);
+    }
+  }
+}
+```
+
+Correct:
+
+```ts
+// application/scheduling/send-reminders.job.ts
+@Scheduled('billing.send-reminders', { every: '15m' }, [CommandBus])
+export class SendRemindersJob implements ScheduledJob {
+  constructor(private readonly commands: CommandBus) {}
+
+  async run(execution: JobExecution): Promise<void> {
+    await this.commands.execute(new SendRemindersCommand(systemActor('billing.send-reminders'), execution.scheduledAt));
+  }
+}
+```
+
+## Details
+
+The rule holds in both styles: an explicit-style job is the same class without `@Scheduled`, registered by `builder.job('<context>.<job>', schedule).handledBy(Job, [CommandBus])` in the module file. Value objects, events, errors and the commands of `application/commands/` may be imported by a job. That a job file of a declared-style project carries `@Scheduled` is `declarations/role-declared`.
+
+## Options
+
+None.
+
+`rules."scheduling/job-triggers-use-case"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line scheduling/job-triggers-use-case -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A command sent through a helper of another file (`this.trigger()`) is not seen: call `execute` in `run`.
+- A job registered with `handledByFactory` names no class and is not followed.
+- A class carrying `@Scheduled` outside a context (the platform) 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/standard-no-parallel-interface.md

@@ -0,0 +1,95 @@
+# ddd-ts-kit/standard-no-parallel-interface
+
+Architecture id: `standard/no-parallel-interface`. Default severity: `warn` in `recommended`, `error` in `strict`.
+
+Applies to: every production file under the source root; tests excluded.
+
+## Why
+
+The kernel defines the shapes every project shares (`Actor`, `Session`, `ExecutionContext`, `Logger`, `Metrics`, `Cache`, `Page` and `PageRequest`, `AuditStamp`, `Clock`, `IdGenerator`, `UnitOfWork`, `JobScheduler`, `ScheduledJob`, `ErrorReporter`), so that an adapter, a middleware or a dashboard written once fits them all. A home-made `ILogger` or `UserContext` next to them forks the shape: every adapter needs a translation, and the fields of the project never reach the standard log lines, spans and audit entries.
+
+## Reported
+
+A class, an interface or a type alias declared under one of these names:
+
+| Declared name | Use instead |
+|---|---|
+| `ILogger`, `AppLogger`, `LoggerService`, `LoggerInterface` | `Logger` |
+| `IMetrics`, `MetricsService` | `Metrics` |
+| `ICache`, `CacheService` | `Cache` |
+| `UserContext`, `CurrentUser`, `AuthContext`, `RequestContext` (outside `presentation/` and the platform), `IExecutionContext`, `IActor` | `ExecutionContext` or `Actor` |
+| `UserSession`, `AuthSession`, `SessionData`, `ISession` | `Session` |
+| `PaginatedResult`, `PageResult`, `PaginatedResponse`, `Paginated`, `IPage` | `Page` |
+| `PaginationParams`, `PageParams`, `IPageRequest` | `PageRequest` |
+| `AuditLog`, `AuditLogEntry`, `AuditRecord`, `IAuditEntry` | `AuditEntry` of `@ddd-ts-kit/audit` (`AuditStamp`, also `IAuditStamp`, for audit columns) |
+| `IClock`, `IIdGenerator`, `IUnitOfWork` | `Clock`, `IdGenerator`, `UnitOfWork` |
+| `IJobScheduler`, `JobSchedulerService`, `CronScheduler`, `TaskScheduler` | `JobScheduler` |
+| `IScheduledJob`, `CronJob`, `ScheduledTask`, `BackgroundJob` | `ScheduledJob` |
+| `IErrorReporter`, `ErrorReporterService`, `ErrorTracker`, `ExceptionReporter`, `CrashReporter` | `ErrorReporter` |
+
+Incorrect:
+
+```ts
+// src/contexts/billing/application/ports/logger.port.ts
+export interface ILogger {
+  info(message: string): void;
+}
+
+// src/shared-kernel/user-context.ts
+export interface UserContext {
+  userId: string;
+  tenantId: string;
+  plan: string;
+}
+```
+
+Correct:
+
+```ts
+import type { ExecutionContext, Logger } from '@ddd-ts-kit/kernel';
+
+// src/platform/kernel-extensions.ts
+declare module '@ddd-ts-kit/kernel' {
+  interface ExecutionContextExtensions {
+    plan: string;
+  }
+}
+
+// src/contexts/billing/infrastructure/external/pino.logger.ts
+export class PinoLogger implements Logger {}
+```
+
+## Details
+
+The match is the whole declared name, case-sensitive, against an explicit table: the names above, and `I` followed by a standard name. Nothing is inferred from a word inside a name, so `StdoutLogger`, `RedisCache`, `UserSessionPolicy`, `PageLayout` and `FakeLogger` are not reported, and neither are the kernel names themselves, their imports or their uses.
+
+A class that `implements` or `extends` the interface it would replace (`class CacheService implements Cache`) is an implementation, not a second interface, and is not reported; name it after its technology all the same. An interface that `extends` the kernel one, and a type alias of it, are reported: the kernel interfaces are extended by declaration merging of `SessionExtensions`, `ExecutionContextExtensions`, `ActorExtensions`, `LogFields` and `MetricLabels`, not by a subtype under another name.
+
+`RequestContext` is the context of one transport request: `presentation/` of a context and the platform may declare one.
+
+## Options
+
+None. The table is changed by `standardInterfaces` in `ddd-ts-kit.config.json`, merged over the defaults: a string adds a name or replaces what to use instead, `false` drops a default.
+
+```json
+{
+  "standardInterfaces": {
+    "TenantInfo": "TenantScoped",
+    "CurrentUser": false
+  }
+}
+```
+
+`rules."standard/no-parallel-interface"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line standard/no-parallel-interface -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A domain concept that carries one of these names for a good reason (an `AuditLog` aggregate in an audit context, a `CurrentUser` read model of an identity context whose glossary defines the term) is reported: the glossary is not read. Drop the entry in `standardInterfaces`, or record the suppression of the line.
+- A parallel shape under a name the table does not hold (`LogService`, `Pagination`, `Principal`) is not seen; add it to `standardInterfaces`.
+- A copy made without a declaration of its own (an inline object type, a re-export under another name, `export { Logger as ILogger }`) is not seen.
+- A class expression (`const ILogger = class {}`) and an enum are not judged.
+- The class exemption reads the names in `implements` and `extends`, not what they resolve to: a local interface called `Logger` exempts the class as well.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from the declarations it reads in the text of the files, with the same table (a test pins the two) and the same exemptions. This rule is the authority.

package/docs/rules/test-no-mocks.md

@@ -0,0 +1,47 @@
+# ddd-ts-kit/test-no-mocks
+
+Architecture id: `test/no-mocks`. Default severity: `warn` in `recommended`, `error` in `strict`.
+
+Applies to: test files of a context (`test/**`, `*.spec.ts`, `*.test.ts`).
+
+## Why
+
+A mock asserts calls, not outcomes, and breaks on every refactoring. A fake is a working in-memory implementation of the port, held to the same contract suite as the real adapter.
+
+## Reported
+
+- `vi.mock`, `vi.doMock`, `vi.fn`, `vi.spyOn`, `vi.mocked` and their `jest` twins
+- an import of `sinon`, `ts-mockito`, `jest-mock`, `jest-mock-extended`, `vitest-mock-extended`, `testdouble`, `ts-auto-mock`, `typemoq`, `moq.ts`, `@golevelup/ts-jest`, `@golevelup/ts-vitest`
+
+Incorrect:
+
+```ts
+const save = vi.fn();
+vi.mock('@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.js');
+```
+
+Correct:
+
+```ts
+const invoices = new FakeInvoiceRepository();
+await handler.execute(command);
+expect(await invoices.findById(id)).toBeDefined();
+```
+
+## Details
+
+`vi.useFakeTimers` and `vi.setSystemTime` are not mocks of a collaborator and are allowed, although `FixedClock` is the usual way.
+
+## Options
+
+None.
+
+`rules."test/no-mocks"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line test/no-mocks -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Tests outside a context (`test/e2e`) are not judged.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id with regular expressions. This rule is the authority.

package/docs/rules/tracing-platform-only.md

@@ -0,0 +1,65 @@
+# ddd-ts-kit/tracing-platform-only
+
+Architecture id: `tracing/platform-only`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every file under the source root, tests included, except the platform directory, `main.ts` and `apps/`.
+
+## Why
+
+Tracing is non-invasive: the platform wires it once, and one action is one trace because every span is opened by the same few places (the request boundary, the bus middleware, the instrumentation around adapters and handlers, the outbox relay). A context that imports the tracing package or the OpenTelemetry API opens spans of its own, with names and attributes nobody reviews, and can no longer be traced differently, or not at all, by changing the composition root alone.
+
+## Reported
+
+- an import of `@ddd-ts-kit/tracing` or of one of its entries (`/node`, `/testing`) outside the platform directory, `main.ts` and `apps/`
+- an import of any `@opentelemetry/*` package in the same places
+
+Incorrect:
+
+```ts
+// src/contexts/billing/infrastructure/external/stripe-payment.gateway.ts
+import { trace } from '@opentelemetry/api';
+
+export class StripePaymentGateway implements PaymentGateway {
+  async charge(invoiceId: string): Promise<void> {
+    await trace.getTracer('billing').startActiveSpan('charge', () => this.client.charge(invoiceId));
+  }
+}
+```
+
+Correct:
+
+```ts
+// src/platform/tracing.ts: the one place that knows the tracing package
+import { traceApplication, tracedPublisher } from '@ddd-ts-kit/tracing';
+import { initTracing } from '@ddd-ts-kit/tracing/node';
+
+// src/contexts/billing/infrastructure/external/stripe-payment.gateway.ts
+export class StripePaymentGateway implements PaymentGateway {
+  async charge(invoiceId: string): Promise<void> {
+    await this.client.charge(invoiceId);
+  }
+}
+```
+
+## Details
+
+Static imports, type-only imports, `export ... from`, dynamic `import()` and `require()` are all read. The platform directory is `platformDir` of `ddd-ts-kit.config.json`, the source root is `sourceRoot`; `main.ts` is the one at the source root and `apps/` the directory of that name at the source root (`src/apps/<context>/main.ts`, `src/apps/worker/main.ts`).
+
+Judged: every layer of a context, its module file and its tests, the shared kernel and any other file under the source root. Not judged: files outside the source root (the `test/` directory at the root of the project, `scripts/`, config files).
+
+In `domain/` and `application/` the layer rules refuse the same import under their own id, so one import gives two reports there: `layer/*` says the layer is pure, this rule says where tracing lives.
+
+## Options
+
+None. `platformDir` and `sourceRoot` of `ddd-ts-kit.config.json` say where the platform and the sources are.
+
+`rules."tracing/platform-only"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line tracing/platform-only -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A tracing helper re-exported by a file of the platform and imported from there is not followed: that is how a context is expected to receive nothing at all, and a platform that exports its tracer to the contexts defeats the rule.
+- Another tracing library (a vendor SDK that is not under `@opentelemetry/`) is not recognised.
+
+## 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.