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

package/docs/rules/clean-function-ceiling.md

@@ -0,0 +1,53 @@
+# ddd-ts-kit/clean-function-ceiling
+
+Architecture id: `clean/function-size`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file, tests and module files included.
+
+## Why
+
+`clean/function-size` asks for short functions with a limit a project may tune, and leaves `describe` callbacks and module files alone. This rule is the part that is not negotiable: past 100 lines of code a function is a file in disguise, whatever it is, and a test suite of that length tests more than one thing. ESLint gives one severity to a rule name, so the ceiling is a rule of its own: an `error` while `clean-function-size` stays a `warn`.
+
+## Reported
+
+- a function, a method or an arrow function whose body holds more than 100 lines of code, the callbacks of `describe`, `suite` and `context` and the functions of `<context>.module.ts` included
+
+Incorrect:
+
+```ts
+describe('an invoice', () => {
+  // 140 lines of tests about issuing, paying and voiding
+});
+```
+
+Correct:
+
+```ts
+describe('an invoice being issued', () => {
+  // the tests about issuing
+});
+
+describe('an invoice being paid', () => {
+  // the tests about paying
+});
+```
+
+## Details
+
+Lines of code are counted as `clean-function-size` counts them: the lines of the body that carry at least one token; blank lines and comment lines are not counted. A nested function counts in the length of the function around it.
+
+The same number caps the configurable limit: `limits.maxFunctionLines` of `ddd-ts-kit.config.json` and the option `maxLines` of `clean-function-size` are read as 100 when they are higher.
+
+## Options
+
+None.
+
+`rules."clean/function-size"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/function-size -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The rule cannot be lowered to a warning from `ddd-ts-kit.config.json`: only `off` reaches it, with `clean/function-size` as a whole.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the ceiling under `clean/function-size` with the severity `error`, on the text of the file: methods, function declarations at any depth, function expressions and arrow functions, a class property arrow and a callback of `describe` or `it` included. It does not read the methods of an object literal, and counts a template literal written on several lines as one line. This rule is the authority.

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

@@ -0,0 +1,45 @@
+# ddd-ts-kit/clean-function-size
+
+Architecture id: `clean/function-size`. Default severity: `warn` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+A function with more than three parameters hides a concept that has no name yet; a function longer than a screen does more than one thing.
+
+## Reported
+
+- more than `maxParameters` parameters (default 3); constructors are exempt, a `this` parameter is not counted
+- more than `maxLines` lines of code in the body (default 30, never above 100); blank lines and comment lines are not counted
+
+Incorrect:
+
+```ts
+function charge(amount: Amount, card: Card, at: Date, retries: number): void {}
+```
+
+Correct:
+
+```ts
+function charge(payment: Payment, policy: RetryPolicy): void {}
+```
+
+## Details
+
+The module file of a context (`<context>.module.ts`) is exempt from the line limit: a composition grows with the context. So is the callback of `describe`, `suite` and `context`: it holds tests, not steps. Both are still held by the hard ceiling of 100 lines, which is the companion rule [`clean-function-ceiling`](clean-function-ceiling.md), an `error` whatever the severity of this one.
+
+## Options
+
+`[{ "maxParameters": 3, "maxLines": 30 }]`. When an option is absent, `limits.maxParameters` and `limits.maxFunctionLines` of `ddd-ts-kit.config.json` apply, then the defaults. A `maxLines` or a `limits.maxFunctionLines` above 100 is read as 100.
+
+`rules."clean/function-size"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/function-size -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The standard `max-params` and `max-lines-per-function` are not enabled by the presets: they cannot exempt constructors nor read the limits of the config, and would report twice.
+- A nested function counts in the length of the function around it.
+
+## With the CLI checker
+
+`ddd-ts-kit check` approximates this rule on the text of the file and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/clean-no-commented-out-code.md

@@ -0,0 +1,48 @@
+# ddd-ts-kit/clean-no-commented-out-code
+
+Architecture id: `clean/no-commented-out-code`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+Code in a comment does not run, is not type-checked and is never deleted. Version control keeps the old version.
+
+## Reported
+
+- a `//` paragraph or a `/* */` block whose text parses as statements, as a function body or as class members, and holds a declaration, a control statement, a call or an assignment
+- an opening line left alone (`if (x) {`, `items.forEach((item) => {`)
+
+Incorrect:
+
+```ts
+// const total = lines.reduce(add, 0);
+// if (invoice.isPaid()) {
+//   return;
+// }
+```
+
+Correct:
+
+```ts
+// The vendor rounds half up (contract 4.2), so we round before summing.
+```
+
+## Details
+
+The comment body is given to the parser configured for the file, so TypeScript syntax is understood. Prose is filtered before and after parsing: a sentence of plain words, a lone identifier, a label (`note: ...`), a type expression, `name (unit)`, a `TODO`, a URL and tool directives are never code. JSDoc blocks are skipped: their `@example` and fenced samples are documentation.
+
+## Options
+
+None.
+
+`rules."clean/no-commented-out-code"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/no-commented-out-code -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A one-line call such as `// validate(input);` is reported even when it was meant as a mention: quote it in backticks inside a sentence.
+- Code written as a sentence, or without any punctuation of code (`return value`), is not seen.
+
+## With the CLI checker
+
+`ddd-ts-kit check` approximates this rule on the text of the file, with the same exemption of JSDoc blocks, and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/clean-no-escape-hatch.md

@@ -0,0 +1,80 @@
+# ddd-ts-kit/clean-no-escape-hatch
+
+Architecture id: `clean/no-escape-hatch`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+Each escape hatch switches the compiler off for a value and for everything it touches. Foreign data enters through mappers and adapters, where an assertion is expected; anywhere else it hides a design problem.
+
+## Reported
+
+- `value as X` and `<X>value` outside `*.mapper.ts`, `infrastructure/**` of a context and the files matched by `adapterGlobs` (`as const`, `as unknown` and `satisfies` are allowed; `as unknown as X` is reported once)
+- `eslint-disable`, `eslint-disable-line` and `eslint-disable-next-line` without a reason after `--`
+
+Incorrect:
+
+```ts
+const invoice = raw as Invoice;
+// eslint-disable-next-line no-console
+console.log(invoice);
+```
+
+Correct:
+
+```ts
+const invoice = parseInvoice(raw);
+const roles = ['admin', 'agent'] as const;
+// eslint-disable-next-line no-console -- the CLI prints its result
+console.log(invoice);
+```
+
+## Details
+
+**Delegated to standard rules.** The rest of the architecture rule is held by typescript-eslint, enabled by every preset of this plugin instead of being written a second time:
+
+| Part of `clean/no-escape-hatch` | Standard rule |
+|---|---|
+| explicit `any` | `@typescript-eslint/no-explicit-any` |
+| non-null assertion `!` | `@typescript-eslint/no-non-null-assertion` |
+| `@ts-ignore`, `@ts-nocheck`, `@ts-expect-error` without description | `@typescript-eslint/ban-ts-comment` (`ts-expect-error: allow-with-description`) |
+
+Enabling `ddd-ts-kit/clean-no-escape-hatch` alone therefore does not report these three: use a preset, or enable the three rules next to it.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `typeAssertions` | `true` | `false` keeps only the comment check (the presets use it for tests) |
+| `adapterGlobs` | `[]` | other places where foreign data enters, where an assertion is expected |
+| `allowCallerClaimedGenerics` | `false` | lets `value as T` through when the caller chose `T` |
+
+**`adapterGlobs`.** The exemption for adapters is read from the path: `*.mapper.ts` anywhere, and `infrastructure/` of a context. A project that keeps adapters elsewhere (the platform, a package of a monorepo) declares them:
+
+```js
+'ddd-ts-kit/clean-no-escape-hatch': ['error', { adapterGlobs: ['src/platform/database/**', 'packages/*/src/postgres/**'] }]
+```
+
+Globs are posix paths relative to the project root (the directory of `ddd-ts-kit.config.json`, else the working directory): `**` crosses directories, `*` stays inside one, `?` is one character. Nothing changes inside a context.
+
+**`allowCallerClaimedGenerics`.** A function such as `get<Body>(path): Promise<Body>` cannot know `Body`: the caller claims it. With the option, `value as T` is accepted when `T` is exactly a type parameter of the function or method around it and that parameter appears in its declared return type.
+
+```ts
+async get<Body>(path: string): Promise<Body> {
+  return (await this.read(path)) as Body; // accepted with the option
+}
+```
+
+The trade-off: nothing checks the claim. `client.get<Invoice>('/x')` is an assertion written by the caller, in any layer, that no rule sees any more. Keep the option off where a schema can parse the value, and turn it on for the few transport helpers whose callers validate what they receive. `value as T[]`, a type parameter of a class and a function that does not return `T` stay reported.
+
+`rules."clean/no-escape-hatch"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/no-escape-hatch -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A blanket `/* eslint-disable */` silences this rule too, so it cannot report it: `governance/recorded-deviation` does.
+- `any` produced by inference is the business of the type-checked `no-unsafe-*` rules of typescript-eslint.
+
+## With the CLI checker
+
+`ddd-ts-kit check` approximates this rule on the text of the file and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/clean-no-flag-argument.md

@@ -0,0 +1,50 @@
+# ddd-ts-kit/clean-no-flag-argument
+
+Architecture id: `clean/no-flag-argument`. Default severity: `warn` in `recommended`, `error` in `strict`.
+
+Applies to: public methods of classes in `domain/`, and `execute` in `application/`; tests excluded.
+
+## Why
+
+A boolean parameter says that the method does two things. The call site reads `close(true)` and nobody knows what is true.
+
+## Reported
+
+- a parameter typed `boolean` (also `boolean | undefined`, optional) or defaulting to `true` or `false`
+
+Incorrect:
+
+```ts
+class Invoice {
+  close(force: boolean): void {}
+}
+```
+
+Correct:
+
+```ts
+class Invoice {
+  close(): void {}
+  forceClose(reason: string): void {}
+}
+```
+
+## Details
+
+Classes named `...Command` or `...Query` are messages and carry data: they are exempt. Private methods and constructors are exempt.
+
+## Options
+
+None.
+
+`rules."clean/no-flag-argument"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/no-flag-argument -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The type is read from the annotation, not inferred: `flag = isReady()` is not seen.
+- Functions outside classes are not judged.
+- Without a `ddd-ts-kit.config.json` layout (file outside a context) the rule is silent.
+
+## With the CLI checker
+
+`ddd-ts-kit check` approximates this rule on the text of the file and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/clean-no-hash-private.md

@@ -0,0 +1,63 @@
+# ddd-ts-kit/clean-no-hash-private
+
+Architecture id: `clean/no-hash-private`. Default severity: `error` in `recommended`, `error` in `strict`. Fixable with `--fix`.
+
+Applies to: every linted file.
+
+## Why
+
+There is one way to hide a member: the `private` keyword. It reads the same on a field, a method, an accessor and a constructor parameter, the compiler checks it, and the rules of this plugin and the CLI checker read it. `#name` is a second spelling of the same intention, with a different run-time behaviour that nothing in a domain model relies on.
+
+## Reported
+
+- a field, a method, an accessor or a static member declared `#name`
+
+Incorrect:
+
+```ts
+class Invoice {
+  #total = 0;
+
+  add(amount: number): void {
+    this.#total += amount;
+  }
+}
+```
+
+Correct:
+
+```ts
+class Invoice {
+  private total = 0;
+
+  add(amount: number): void {
+    this.total += amount;
+  }
+}
+```
+
+## Details
+
+**The fix.** `--fix` rewrites the declarations of `#name` (a getter and its setter together) and every use of it into `private name`, with `private` placed before `static`, `readonly`, `async`, `get` and `set`, after the decorators. It is applied only when it cannot change what the code means:
+
+- the class has no other member, and no constructor parameter property, called `name`;
+- no other class of the file declares the same `#name`;
+- the file has no brand check `#name in value`;
+- every use is `this.#name` or `<identifier>.#name` inside the class.
+
+Otherwise the member is reported without a fix. Two different names in one class are rewritten in two passes of the same `--fix` run.
+
+## Options
+
+None.
+
+`rules."clean/no-hash-private"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/no-hash-private -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- `private` is erased at compile time: code that relied on `#name` being unreachable at run time (a brand check, a hostile caller) has to be rewritten by hand, which is why those cases are not fixed.
+- A subclass that declares a member with the name freed by the fix is then a compile error; rename one of the two.
+
+## 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/clean-no-noise-comment.md

@@ -0,0 +1,55 @@
+# ddd-ts-kit/clean-no-noise-comment
+
+Architecture id: `clean/no-noise-comment`. Default severity: `warn` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+A comment is kept for what the code cannot say: why, a consequence, an external reference. Anything else is a second, unmaintained copy of the code.
+
+## Reported
+
+- a banner (`// ----- helpers -----`)
+- a label after a closing brace (`} // end if`)
+- an author, a date or a change journal
+- `@param name` or `@returns` without description
+- a `TODO` or `FIXME` without owner (`TODO(owner)`) nor reference (`#123`, `ABC-12`, a URL)
+- a comment or JSDoc description that only repeats the name declared below it
+
+Incorrect:
+
+```ts
+/** The invoice repository. */
+export class InvoiceRepository {}
+
+// TODO fix this
+```
+
+Correct:
+
+```ts
+/** Loads by number as well: support looks invoices up by what the customer reads. */
+export class InvoiceRepository {}
+
+// TODO(billing#142): retry with backoff
+```
+
+## Details
+
+"Repeats the name" compares words with a small English inflection (`Issues the invoice` says `issueInvoice`), ignoring filler words.
+
+## Options
+
+None.
+
+`rules."clean/no-noise-comment"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/no-noise-comment -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- Heuristics on wording: a short description made of the words of the name plus filler is flagged even if the author found it useful.
+- Only the comment directly above a declaration is compared with a name.
+
+## With the CLI checker
+
+`ddd-ts-kit check` approximates this rule on the text of the file and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/clean-one-export-per-file.md

@@ -0,0 +1,88 @@
+# ddd-ts-kit/clean-one-export-per-file
+
+Architecture id: `clean/one-export-per-file`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: sources under the source root (in a workspace, under the `src` directory of a package). Tests (`*.spec.ts`, `*.test.ts`, a `test/` directory) and declaration files are not judged.
+
+## Why
+
+A file that exports one thing is found by its name, read in one sitting and moved without untangling. The companions it may keep are the types of its own signature: they have no life without it. Entry files are the opposite: they declare nothing, so that the map of a package stays a map.
+
+## Reported
+
+- a file exporting two or more classes, interfaces or functions that are not one thing (the allowances are below)
+- a file not named after its export in kebab-case
+- in an entry file (`index.ts` at any depth, `<context>.declarations.ts`, the files of the option `entries`): any statement that is not a re-export
+
+Incorrect:
+
+```ts
+// src/platform/collaborators.ts
+export function loggerOr(given?: Logger): Logger {}
+export function clockOr(given?: Clock): Clock {}
+
+// src/platform/event-bus.ts
+export class RabbitMqEventBus {}
+
+// src/platform/index.ts
+export const VERSION = '1.0.0';
+```
+
+Correct:
+
+```ts
+// src/platform/retry.ts: a function and the type of its signature
+export interface RetryOptions {
+  readonly attempts: number;
+}
+
+export function retry(options: RetryOptions): Aspect {}
+
+// src/platform/rabbit-mq-event-bus.ts
+export class RabbitMqEventBus {}
+
+// src/platform/index.ts
+export { retry, type RetryOptions } from '@/platform/retry.js';
+```
+
+## Details
+
+**What is counted.** The distinct names of the exported classes (abstract or not), interfaces and functions. An exported `const`, `type` or `enum` is never counted, the overloads of a function count once, and a function sharing its name with an interface or a type (`CommandHandler` the decorator and `CommandHandler<M>` the shape it decorates) counts once. A file with no counted export is not judged at all, neither for its count nor for its name.
+
+**What may stand together.** Two or more counted exports pass when one of these holds:
+
+| Allowance | Rule |
+|---|---|
+| the types of the signature | every other counted export is an interface reached from the signature of one export of the file: the parameters and the return type of a function (every overload), the constructor, the public members and the `implements` list of a class, the members of an interface or of a type alias, and from there through the interfaces and type aliases of the file. `type Result = Ok \| Err` with its two interfaces is this case |
+| a derived form | a function named after the main function with a suffix and called by it (`retryAdvice` next to `retry`) stands with it, with the types of its own signature |
+| a type and its constructors or combinators | every exported function returns one type, declared by the file or imported by it (`allOf`, `anyOf`, `not` returning `Condition`); when that type is a union of the file, a function may return one of its members |
+| the accessors of one private state | every exported function reads or writes a module-level variable that is not exported (a `let`, or a `const` holding a `new ..`), and those variables tie the functions into one group (`sequence` and `resetSequences` around `const counters = new Map()`) |
+
+Anything else is declared, with the sentence that says why the exports are one thing, in `onePerFile.allow` of `ddd-ts-kit.config.json` or in the option `allow`.
+
+**The file name.** The base name without its extension, with every `.` read as `-`, is the kebab-case of the export: `rabbit-mq-event-bus.ts` for `RabbitMqEventBus`, `standard-schema-v1.ts` for `StandardSchemaV1`, `http-server.ts` for `HTTPServer`, `issue-invoice.handler.ts` for `IssueInvoiceHandler`. In a role file `<name>.<role>.ts` whose export does not end with the role word, the part before the first dot is the name: `invoice.aggregate.ts` for `Invoice`, `payment-gateway.port.ts` for `PaymentGateway`. A product is spelled in the file name as the class spells it.
+
+The export the file is named after is the counted one; with the types of a signature, any export that holds the others in its signature (`job-run-observer.ts` for a `type JobRunObserver` that takes the exported `interface JobRunDetail`); with a type and its constructors, the type when the file declares it. A family that no export names (the accessors of a state, the combinators of an imported type) is named freely. A file allowed by `allow` is named after one of its exports.
+
+**Entry files** may hold `export .. from`, `export * from`, `export type .. from` an import for its side effect (`import 'reflect-metadata';`) and the empty `export {};` of a package that exports nothing yet, nothing else. They are exempt from the count and from the name.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `allow` | `[]` | `[{ "file": "<path or glob>", "reason": "<why these exports are one thing>" }]`, added to `onePerFile.allow` of the config; an allowed file is exempt from the count, never from its name |
+| `entries` | `[]` | globs of the entry files besides every `index.ts` and `<contextsDir>/*/*.declarations.ts`: the subpath entries of a package (`packages/*/src/testing.ts`) |
+
+Paths and globs are posix, relative to the project root (the directory of `ddd-ts-kit.config.json`, else the working directory): `**` crosses directories, `*` stays inside one, `?` is one character. An entry of `allow` without a `file` or without a `reason` allows nothing.
+
+`rules."clean/one-export-per-file"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/one-export-per-file -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- The signature is read from the syntax, without types: a type reached only through an inferred return type or through a type of another file is not seen as a companion. Write the return type.
+- Only interfaces are companions: a second class or a second function is never excused by a signature.
+- A re-export (`export { a } from`) in a file that also declares something is not counted and not reported.
+
+## With the CLI checker
+
+`ddd-ts-kit check` holds the same count, the same `allow` list, the entry file rule and the file name, with a text approximation of the allowances. This rule is the authority.

package/docs/rules/clean-stepdown.md

@@ -0,0 +1,60 @@
+# ddd-ts-kit/clean-stepdown
+
+Architecture id: `clean/stepdown`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every linted file.
+
+## Why
+
+A file reads like a newspaper: the intention at the top, the details below. A reader who opens a class meets what it does before how, and never has to scroll up to find the helper a function just called.
+
+## Reported
+
+- a private, `#private` or protected method declared before a public method
+- a public static method declared after a public instance method (static factories come first)
+- a private method declared above its first caller
+- a non-exported top-level function, or constant holding a function, declared above its first caller
+
+Incorrect:
+
+```ts
+function price(line: Line): number {
+  return line.unit * line.quantity;
+}
+
+export function total(lines: Line[]): number {
+  return lines.map(price).reduce(add, 0);
+}
+```
+
+Correct:
+
+```ts
+export function total(lines: Line[]): number {
+  return lines.map(price).reduce(add, 0);
+}
+
+function price(line: Line): number {
+  return line.unit * line.quantity;
+}
+```
+
+## Details
+
+Callers are found with the scope manager for functions, and through `this.x`, `this.#x` and `ClassName.x` for members. Recursion and mutual recursion have no right order and are not reported. A constant holding a function is left alone when it is used while the module loads, since moving it below that use would break at run time.
+
+## Options
+
+None.
+
+`rules."clean/stepdown"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line clean/stepdown -- <reason>` silences one line, exactly as for `ddd-ts-kit check`.
+
+## Limits
+
+- A member called only through another receiver than `this` or the class name (`other.#helper()`) has no known caller and is not reported.
+- Constructors, properties that do not hold a function, accessors without body and overload signatures are neutral.
+- An exported function is never asked to move: the order between exported functions is the author's.
+
+## With the CLI checker
+
+`ddd-ts-kit check` approximates this rule on the text of the file and stays the fast edit-time guard. This rule is the authority.

package/docs/rules/context-declared-relationship.md

@@ -0,0 +1,49 @@
+# ddd-ts-kit/context-declared-relationship
+
+Architecture id: `context/declared-relationship`. Default severity: `error` in `recommended`, `error` in `strict`.
+
+Applies to: every file of a context, tests included.
+
+## Why
+
+Relationships between contexts are strategic decisions written in `ddd-ts-kit.config.json` and drawn in the context map. An import must never be the only place where a dependency exists.
+
+## Reported
+
+- an import of the published language of a context that is not listed in `contexts.<this context>.upstreams`
+
+Incorrect:
+
+```ts
+// ddd-ts-kit.config.json: "shipping": { "upstreams": [] }
+// src/contexts/shipping/application/integration/handlers/billing-invoice-issued.integration-handler.ts
+import type { InvoiceIssuedV1 } from '@/contexts/billing/published-language/index.js';
+```
+
+Correct:
+
+```ts
+// ddd-ts-kit.config.json: "shipping": { "upstreams": [{ "context": "billing", "relationship": "published-language" }] }
+import type { InvoiceIssuedV1 } from '@/contexts/billing/published-language/index.js';
+```
+
+## Details
+
+Static imports, type-only imports, `export ... from`, dynamic `import()`, `require()`, `import x = require()` and `import("...")` types are all read, through relative paths and the configured `importAlias`.
+
+## Options
+
+None.
+
+`rules."context/declared-relationship"` in `ddd-ts-kit.config.json` set to `off` silences the rule, and `// ddd-ts-kit-disable-next-line context/declared-relationship -- <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.
+- Cycles between declared relationships are found by `ddd-ts-kit check` (`context/no-cycle`), which reads the whole config.
+
+## With the CLI checker
+
+`ddd-ts-kit check` reports the same id from a regex reading of the file. This rule is the authority for the import; the CLI stays the authority for the config (`config/valid`, `context/no-cycle`).