@ddd-ts-kit/eslint-plugin 0.1.1 → 0.2.0

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

@@ -30,7 +30,7 @@ Incorrect:
 // src/contexts/billing/application/event-handlers/invoice-issued.event-handler.ts
 import { Cache } from '@ddd-ts-kit/kernel';
 import { DomainEventHandler } from '@ddd-ts-kit/kernel/declarations';
-import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository';
 
 @DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [InvoiceRepository, Cache])
 export class InvoiceIssuedEventHandler {

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

@@ -12,7 +12,7 @@ The alias is declared once, under `paths` in `tsconfig.json`, which the compiler
 
 ## Reported
 
-- a relative specifier, `./x.js` or `../x.js`, the same directory included: fixed to the alias of the file
+- a relative specifier, `./x` or `../x`, with or without an extension, 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
 
@@ -20,22 +20,22 @@ 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';
+import { Invoice } from '../../../domain/aggregates/invoice.aggregate';
+import { IssueInvoiceCommand } from './issue-invoice.command';
 
 // test/e2e/issue-invoice.e2e.spec.ts
-import { startApplication } from './support/start-application.js';
+import { startApplication } from './support/start-application';
 ```
 
 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';
+import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command';
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate';
 
 // test/e2e/issue-invoice.e2e.spec.ts
-import { startApplication } from '$test/e2e/support/start-application.js';
+import { startApplication } from '$test/e2e/support/start-application';
 ```
 
 ## Details
@@ -51,7 +51,7 @@ The aliases of a project:
 | `$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.
+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, ending as `importExtension` of the config says: with nothing under `none`, with `.js` under `js` (a config without the key). 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).
 
@@ -59,13 +59,14 @@ An alias that names no file is not this rule's concern: the compiler reports it
 
 ## Options
 
-None. `sourceRoot` and `importAlias` of `ddd-ts-kit.config.json` say what the alias of the sources is.
+None. `sourceRoot` and `importAlias` of `ddd-ts-kit.config.json` say what the alias of the sources is, `importExtension` what the fixed specifier ends with.
 
 `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 ending of an alias specifier is the business of [`imports/extension`](imports-extension.md).
 - 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

package/docs/rules/imports-extension.md

@@ -0,0 +1,83 @@
+# ddd-ts-kit/imports-extension
+
+Architecture id: `imports/extension`. 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 import of a file of the project has one spelling. `importExtension` in `ddd-ts-kit.config.json` says which:
+
+| `importExtension` | An import is written | The compiler resolves it | Who holds the other spelling |
+|---|---|---|---|
+| `none`, the default of a new project | `@/contexts/billing/domain/aggregates/invoice.aggregate` | as a bundler does (`"moduleResolution": "Bundler"`, with the `node` condition), which accepts both spellings | this rule: the compiler would let `.js` through |
+| `js`, also what a config without the key means | `@/contexts/billing/domain/aggregates/invoice.aggregate.js` | as Node does (`"moduleResolution": "NodeNext"`), which requires the extension | the compiler (`TS2835`), and this rule, which fixes it |
+
+Node needs the extension at run time whatever the sources write: `ddd-ts-kit build-aliases`, the second step of `npm run build`, rewrites each alias of the compiled output into a relative path ending in `.js`. The build names one file per specifier and guesses nothing, so a specifier written the other way stops it: this rule reports the mistake in the editor instead. See [Import aliases](../../../../docs/tools/import-aliases.md).
+
+## Reported
+
+- under `none`: an alias specifier that ends with `.js`, `.mjs`, `.cjs`, `.ts`, `.mts` or `.cts`: fixed by removing the extension
+- under `js`: an alias specifier that does not end with `.js` (`.mjs` and `.cjs` are accepted, they name what an `.mts` or a `.cts` file emits): fixed by writing `.js` in place of what it ends with
+
+Incorrect under `none`:
+
+```ts
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.js';
+import { startApplication } from '$test/e2e/support/start-application.ts';
+```
+
+Correct under `none`:
+
+```ts
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate';
+import { startApplication } from '$test/e2e/support/start-application';
+```
+
+Incorrect under `js`:
+
+```ts
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate';
+```
+
+Correct under `js`:
+
+```ts
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.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.
+
+Only a specifier that starts with an alias of the project is judged (`importAlias`, `$test/`, `$scripts/`, and `$generated/` with `stack.orm` `prisma`). A package is never a file of the project, whatever its subpath ends with: `zod/v4/core.js` and `@scope/package/file.js` are left alone, and so is a Node built-in. A relative import is reported by [`imports/alias-only`](imports-alias-only.md), whose fix writes the alias with the right ending.
+
+A dot in a file name is not an extension: `invoice.aggregate`, `issue-invoice.command` and `load-config` are all read as written without one.
+
+The fix keeps the quotes of the specifier. Under `none` a fixed import is three characters shorter and may now fit on one 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, which Node runs as written and which therefore keeps its extensions) and the client under `generated/`, which a tool writes.
+
+## Moving a project to the other spelling
+
+A project generated before the key existed is read as `js` and keeps working untouched. To drop the extensions:
+
+1. set `"importExtension": "none"` in `ddd-ts-kit.config.json`;
+2. run `ddd-ts-kit check`: `imports/alias-declared` gives the `module`, `moduleResolution` and `customConditions` to write in `tsconfig.json`, and the jest mapping when the project runs jest;
+3. run `eslint --fix`, then `npm run format`;
+4. regenerate what the kit generates (`ddd-ts-kit generate` or `ddd-ts-kit docs` rewrites the declarations barrels), then `npm run verify`.
+
+## Options
+
+None. `importExtension` of `ddd-ts-kit.config.json` decides.
+
+`rules."imports/extension"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line imports/extension -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A specifier that names a directory (`@/contexts/billing/published-language`, resolved by a bundler to its `index.ts`) is not reported here: this rule reads no disk. `ddd-ts-kit check` reports it under the same id, and `ddd-ts-kit build-aliases` refuses it: an alias names one file, `.../published-language/index`.
+- The rule does not check that `tsconfig.json` resolves as the config says: `imports/alias-declared` of `ddd-ts-kit check` does.
+
+## 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/`, gives the specifier to write in its fix sentence, and also reports an alias that names a directory. This rule is the one that rewrites the import.

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

@@ -23,7 +23,7 @@ Incorrect:
 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';
+import { DrizzleInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository';
 ```
 
 Correct:
@@ -31,8 +31,8 @@ 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';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository';
+import { PaymentGateway } from '@/contexts/billing/application/ports/payment-gateway.port';
 
 // declared style
 import { CommandHandler } from '@ddd-ts-kit/kernel/declarations';

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

@@ -24,7 +24,7 @@ Incorrect:
 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';
+import type { InvoiceRow } from '@/contexts/billing/infrastructure/persistence/billing.schema';
 ```
 
 Correct:
@@ -32,8 +32,8 @@ 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';
+import type { Amount } from '@/contexts/billing/domain/value-objects/amount.vo';
+import { Money } from '@/shared-kernel/money.vo';
 ```
 
 ## Details

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

@@ -16,13 +16,13 @@ Incorrect:
 
 ```ts
 // src/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.ts
-import type { IssueInvoiceBody } from '@/contexts/billing/presentation/http/issue-invoice.dto.js';
+import type { IssueInvoiceBody } from '@/contexts/billing/presentation/http/issue-invoice.dto';
 ```
 
 Correct:
 
 ```ts
-import type { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+import type { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository';
 ```
 
 ## Details

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

@@ -16,13 +16,13 @@ Incorrect:
 
 ```ts
 // src/contexts/billing/presentation/http/issue-invoice.route.ts
-import { DrizzleInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.js';
+import { DrizzleInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository';
 ```
 
 Correct:
 
 ```ts
-import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command.js';
+import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command';
 ```
 
 ## Details

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

@@ -6,17 +6,18 @@ 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.
+A dependency is named by its port, never by what implements it. A handler that is given `KnexInvoiceRepository` is wired to one technology, cannot be given a fake, and makes the application layer depend on infrastructure through its own registration. In the declared style a class states what it depends on in its constructor, so the types of its parameters are held like the entries of a list.
 
 ## 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
+- in a declared-style project, in a role file: a class of either place that types a constructor parameter of a class carrying a declaration decorator without a list (`constructor(private readonly invoices: KnexInvoiceRepository) {}`)
 
 Incorrect:
 
 ```ts
-import { KnexInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/knex-invoice.repository.js';
+import { KnexInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/knex-invoice.repository';
 
 @CommandHandler(IssueInvoiceCommand, [KnexInvoiceRepository, Clock])
 export class IssueInvoiceHandler {}
@@ -25,7 +26,7 @@ export class IssueInvoiceHandler {}
 Correct:
 
 ```ts
-import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository';
 
 @CommandHandler(IssueInvoiceCommand, [InvoiceRepository, Clock])
 export class IssueInvoiceHandler {}

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

@@ -17,7 +17,7 @@ Incorrect:
 
 ```ts
 const save = vi.fn();
-vi.mock('@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository.js');
+vi.mock('@/contexts/billing/infrastructure/persistence/drizzle-invoice.repository');
 ```
 
 Correct:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddd-ts-kit/eslint-plugin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AST-accurate ESLint rules for DDD and Clean Architecture in TypeScript: layer and context isolation, domain purity, clean code ordering.",
   "license": "MIT",
   "repository": {