@ingenioz-it/caits 0.5.1 → 0.7.0

package/quality/mutation-summary.mjs

@@ -1,41 +1,58 @@
 // `caits mutation-summary`: the mutation score of each file, from the report of Stryker. With --survivors, the mutants that survived.
+// In a terminal: the score in green when every mutant is killed, else in red; the score of each file the same way, and its path in cyan;
+// for each survivor, its line dim, its status in red, its mutator in yellow.
 import { existsSync, readFileSync } from "node:fs";
+import { NOT_RUN } from "./mutation-suite.mjs";
+import { painterOf } from "./terminal.mjs";
 
 /** The report that Stryker writes in JSON (quality/caits/stryker.mjs). */
 export const REPORT = "reports/mutation/mutation.json";
 
-/** @typedef {{ status: string; mutatorName: string; replacement?: string; location: { start: { line: number } } }} Mutant */
+/** @typedef {{ status: string; statusReason?: string; mutatorName: string; replacement?: string; location: { start: { line: number } } }} Mutant */
 
 /** @type {(file: string) => unknown} */
 const readJson = file => JSON.parse(readFileSync(file, "utf8"));
 
+/** Stryker counts a suite that stopped before its tests as a kill: the mutant is not tested (`caits mutation-suite`). @type {(m: Mutant) => boolean} */
+const notTested = m => m.status === "Killed" && Boolean(m.statusReason?.includes(NOT_RUN));
+
+/** @type {(m: Mutant) => string} */
+const tag = m => (m.status === "NoCoverage" ? "[no cov]" : m.status === "Survived" ? "[survived]" : "[not tested]");
+
 /**
  * @param {string[]} args
- * @returns {number}
+ * @returns {number} 1 when a mutant is not tested
  */
 export function run(args) {
   if (!existsSync(REPORT)) throw new Error(`${REPORT} is missing: run the mutation tests first (npm run test:mutation).`);
   const report = /** @type {{ files: Record<string, { source: string; mutants: Mutant[] }> }} */ (readJson(REPORT));
   const rows = [];
-  let killedTotal = 0, validTotal = 0;
+  let killedTotal = 0, validTotal = 0, notTestedTotal = 0;
   for (const [file, data] of Object.entries(report.files)) {
     /** @type {(status: string) => number} */
     const count = status => data.mutants.filter(m => m.status === status).length;
-    const killed = count("Killed") + count("Timeout");
+    const untested = data.mutants.filter(notTested).length;
+    const killed = count("Killed") - untested + count("Timeout");
     const survived = count("Survived");
     const noCoverage = count("NoCoverage");
-    const valid = killed + survived + noCoverage;
-    killedTotal += killed; validTotal += valid;
-    rows.push({ file, killed, survived, noCoverage, score: valid ? (100 * killed) / valid : 100, survivors: data.mutants.filter(m => m.status === "Survived" || m.status === "NoCoverage"), source: data.source.split("\n") });
+    const valid = killed + survived + noCoverage + untested;
+    killedTotal += killed; validTotal += valid; notTestedTotal += untested;
+    rows.push({ file, killed, survived, noCoverage, untested, score: valid ? (100 * killed) / valid : 100, survivors: data.mutants.filter(m => m.status === "Survived" || m.status === "NoCoverage" || notTested(m)), source: data.source.split("\n") });
   }
   rows.sort((a, b) => a.score - b.score);
   const verbose = args.includes("--survivors");
-  console.log(`Mutation score: ${(validTotal ? (100 * killedTotal) / validTotal : 100).toFixed(1)}%  (${killedTotal} killed of ${validTotal} valid mutants)\n`);
+  const paint = painterOf(process.stdout);
+  /** @type {(killed: number, valid: number) => "green" | "red"} */
+  const colorOf = (killed, valid) => killed === valid ? "green" : "red";
+  console.log(`${paint([colorOf(killedTotal, validTotal), "bold"], `Mutation score: ${(validTotal ? (100 * killedTotal) / validTotal : 100).toFixed(1)}%  (${killedTotal} killed of ${validTotal} valid mutants)`)}\n`);
   for (const row of rows) {
-    console.log(`${row.score.toFixed(0).padStart(4)}%  ${row.file}  (killed ${row.killed}, survived ${row.survived}, no coverage ${row.noCoverage})`);
+    const valid = row.killed + row.survived + row.noCoverage + row.untested;
+    console.log(`${paint(colorOf(row.killed, valid), `${row.score.toFixed(0).padStart(4)}%`)}  ${paint("cyan", row.file)}  (killed ${row.killed}, survived ${row.survived}, no coverage ${row.noCoverage}${row.untested ? `, not tested ${row.untested}` : ""})`);
     if (verbose && row.survivors.length) {
-      for (const m of row.survivors) console.log(`        L${m.location.start.line} ${m.status === "NoCoverage" ? "[no cov]" : "[survived]"} ${m.mutatorName}: ${(row.source[m.location.start.line - 1] ?? "").trim().slice(0, 90)}  →  ${String(m.replacement ?? "").slice(0, 60)}`);
+      for (const m of row.survivors) console.log(`        ${paint("dim", `L${m.location.start.line}`)} ${paint("red", tag(m))} ${paint("yellow", m.mutatorName)}: ${(row.source[m.location.start.line - 1] ?? "").trim().slice(0, 90)}  ${paint("dim", "→")}  ${String(m.replacement ?? "").slice(0, 60)}`);
     }
   }
-  return 0;
+  if (!notTestedTotal) return 0;
+  console.log(`\n${paint("red", `${notTestedTotal} ${notTestedTotal === 1 ? "mutant is" : "mutants are"} not tested: the unit tests did not run, and Stryker counts ${notTestedTotal === 1 ? "it" : "them"} as killed. Run the mutation tests again. Why they did not run: reports/mutation/index.html.`)}`);
+  return 1;
 }

package/quality/mutation.mjs

@@ -1,5 +1,6 @@
 // `caits mutation`: the mutation tests (Stryker, with quality/stryker.config.mjs), then the score of each file and the mutants that
 // survived, whether Stryker passed or not. Stryker alone ends with its threshold when the score is too low: the survivors say what to fix.
+// The run fails also when a mutant is not tested, which Stryker counts as killed (`caits mutation-summary`).
 import { spawn } from "node:child_process";
 import { existsSync, rmSync } from "node:fs";
 import { REPORT, run as summary } from "./mutation-summary.mjs";
@@ -9,7 +10,7 @@ export const STRYKER_CONFIG = "quality/stryker.config.mjs";
 
 /**
  * @param {string[]} args the options of Stryker
- * @returns {Promise<number>} the exit code of Stryker
+ * @returns {Promise<number>} the exit code of Stryker, or 1 when a mutant is not tested
  */
 export async function run(args) {
   if (!existsSync(STRYKER_CONFIG)) throw new Error(`${STRYKER_CONFIG} is missing: it gives the configuration of the mutation tests. Run \`npx caits init .\` to write it.`);
@@ -22,9 +23,7 @@ export async function run(args) {
     stryker.on("error", () => resolve(1));
     stryker.on("close", code => resolve(code ?? 1));
   });
-  if (existsSync(REPORT)) {
-    console.log("");
-    summary(["--survivors"]);
-  }
-  return status;
+  if (!existsSync(REPORT)) return status;
+  console.log("");
+  return summary(["--survivors"]) || status;
 }

package/quality/terminal.mjs

@@ -0,0 +1,30 @@
+// The colors of the outputs of CAITS. A tool prints its lines through the painter of its stream: in a terminal, the painter colors the
+// parts of a line; in a pipe or a file (an AI agent, a log), it gives the text as it is, without a code. NO_COLOR turns the colors off,
+// FORCE_COLOR turns them on, as for the other tools. Each kind of line has its colors: caits.dev shows the outputs with the same ones.
+import { styleText } from "node:util";
+
+/** @typedef {"bold" | "dim" | "red" | "green" | "yellow" | "cyan"} Style */
+/** Gives the text with the styles, or as it is. @typedef {(style: Style | Style[], text: string) => string} Paint */
+
+/**
+ * The painter of a stream: it colors when the stream is a terminal, or when FORCE_COLOR asks for colors, and never with NO_COLOR.
+ * @param {NodeJS.WriteStream} stream
+ * @returns {Paint}
+ */
+export const painterOf = stream => (style, text) => styleText(style, text, { stream });
+
+/** The painter of a text without colors. @type {Paint} */
+export const plain = (_style, text) => text;
+
+/** Whether a painter colors. @type {(paint: Paint) => boolean} */
+export const colors = paint => paint("bold", "x") !== "x";
+
+/**
+ * A command, then what it does, after two spaces or more: the command in cyan. A line without an explanation is all command.
+ * @param {string} step
+ * @param {Paint} paint
+ */
+export function commandOf(step, paint) {
+  const [, command = step, explanation = ""] = /^(\S.*?)(\s{2,}.*)?$/.exec(step) ?? [];
+  return `${paint("cyan", command)}${explanation}`;
+}

package/quality/test-docs/test-docs.mjs

@@ -28,13 +28,12 @@ const readJson = file => JSON.parse(readFileSync(file, "utf8"));
 
 /** @type {Record<string, number>} */
 const PROJECTS = { "End-to-end": 0, Backend: 1, Frontend: 2, Other: 3 };
-const LAYERS = ["presentation", "application", "domain", "infra"];
+const LAYERS = ["presentation", "command", "query", "event", "domain", "infra"];
 
 /** A path relative to the project root, with "/" on every system. @type {(file: string) => string} */
 export const fromProjectRoot = file => relative(projectRoot, file).split(sep).join("/");
 
 /** Removes the terminal colors from an error message. @type {(text: string) => string} */
-// eslint-disable-next-line no-control-regex -- a color of the terminal starts with the character ESC.
 export const withoutColors = text => text.replace(/\u001b\[[0-9;]*m/g, "");
 
 /**

package/src/DomainEvent.ts

@@ -1,4 +1,7 @@
-/** An event a context publishes: a fact that the context map may turn into input DTOs of other contexts. The publisher never waits for them. */
+/**
+ * An event a context publishes: a fact of the context, that its context map may share as an event of the context shared, which the
+ * context maps of the other contexts turn into input DTOs of their own. The publisher never waits for them.
+ */
 export abstract class DomainEvent {
   declare protected readonly fact?: true;
 }

package/src/di/Container.ts

@@ -52,7 +52,11 @@ export class Container {
   private readonly built = new Map<Key, unknown>();
 
   constructor(bindings: readonly Binding[] = [], private readonly parent?: Container) {
-    for (const binding of bindings) this.bindings.set(binding.key, binding);
+    for (const binding of bindings) {
+      // A di.ts that gives something else would lose it without a word: the kernel refuses it when it starts.
+      if (!isKey((binding as { key?: unknown } | undefined)?.key)) throw new Error(`A di.ts gives bindings, made with bind(Key).to(…), .toValue(…) or .toFactory(…): ${JSON.stringify(binding) ?? typeof binding} is not one`);
+      this.bindings.set(binding.key, binding);
+    }
   }
 
   /** A container whose bindings come first, and which asks this container for the others. */

package/src/di/createBackend.ts

@@ -1,10 +1,9 @@
 import type { DomainEvent } from "../DomainEvent.js";
 import type { Token } from "../Token.js";
 import { BackendEventBus, type Published } from "../messaging/BackendEventBus.js";
-import { ContextMap } from "../messaging/ContextMap.js";
+import { ContextMap, type Envelope, type Translation } from "../messaging/ContextMap.js";
 import { EventPublisher } from "../messaging/EventPublisher.js";
-import { InProcessMessageBus } from "../messaging/InProcessMessageBus.js";
-import type { Input } from "../messaging/Input.js";
+import { InProcessMessageBus, UnknownInputError } from "../messaging/InProcessMessageBus.js";
 import { MessageBus } from "../messaging/MessageBus.js";
 import { ReportError, reportToConsole } from "../messaging/ReportError.js";
 import { bind, Container, type Binding, type Concrete } from "./Container.js";
@@ -18,51 +17,89 @@ export type BackendOptions = {
   nextEventId?: () => string;
 };
 
-type Context = { readonly container: Container; readonly useCases: readonly UseCase[] };
+/** A context, and the events of shared that an event of its handlers gives. */
+type Context = { readonly container: Container; readonly useCases: readonly UseCase[]; readonly shares: (event: DomainEvent) => DomainEvent[] };
 
 const SYSTEM: RequestContext = { correlationId: "system" };
 
+/** The context whose events are those of shared: its handlers publish them on the shared bus. */
+const SHARED = "shared";
+
 /**
  * Builds every context in a container of its own, child of the container of shared: the dependencies of a context are private to it,
  * those of shared are built once for all. Each request gets a child of its context, with its correlation id, the publisher of its events
- * and its message bus: its handlers and its controllers are built there. The backend event bus carries the events between contexts.
+ * and its message bus: its handlers and its controllers are built there. The backend event bus is the shared bus: the context map of a
+ * context shares there the events of shared that the events of its handlers give, and the context map of each context turns the events
+ * of shared that it hears into inputs of the context. The handlers of the context shared publish its events there.
  */
 export function createBackend(modules: BackendModules, options: BackendOptions = {}) {
   const reportError = options.reportError ?? reportToConsole;
   const shared = new Container([bind(ReportError).toValue(reportError), ...modules.shared, ...(options.replace?.shared ?? [])]);
   const contexts = new Map<string, Context>();
   const owners = new Map<unknown, Context>();
+  const listeners = new Set<(event: DomainEvent) => void>();
 
-  const ownerOf = (owned: Class): Context => {
+  /** The context of an input DTO, or of a controller: the error of an input is that of the message bus, which names the fix. */
+  const ownerOf = (owned: Class, refusal: () => Error): Context => {
     const context = owners.get(owned);
-    if (!context) throw new Error(`No context owns ${owned.name}`);
+    if (!context) throw refusal();
     return context;
   };
+  const ownerOfInput = (input: object): Context => ownerOf(input.constructor as Class, () => new UnknownInputError(input.constructor.name));
 
   /** The container of a request, and its message bus: each input DTO gets a new handler. */
-  const requestOf = ({ container, useCases }: Context, request: RequestContext) => {
+  const requestOf = ({ container, useCases, shares }: Context, request: RequestContext) => {
     const bus = new InProcessMessageBus();
     const scope = container.child([
       bind(RequestContext).toValue(request),
-      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => { eventBus.publish(event, request); } }),
+      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => { tell(shares, event, request); } }),
       ...(container.has(MessageBus) ? [] : [bind(MessageBus).toValue(bus)])
     ]);
     for (const { input, handler } of useCases) bus.subscribe(input as never, received => scope.create(handler as Concrete<{ execute(input: unknown): unknown }>).execute(received) as never);
     return { scope, bus };
   };
 
-  const send = async <Output>(input: Input<Output>, request: RequestContext = SYSTEM): Promise<Output> =>
-    requestOf(ownerOf(input.constructor as Class), request).bus.send(input);
+  const send = async (input: object, request: RequestContext = SYSTEM): Promise<unknown> =>
+    requestOf(ownerOfInput(input), request).bus.send(input);
+
+  /**
+   * An event that a handler publishes, in its context: the events of shared that the lines of its map that share give go to the shared
+   * bus, in the request of the handler. A line that fails is reported: the handler never waits for the other contexts, nor fails for them.
+   */
+  const tell = (shares: Context["shares"], event: DomainEvent, request: RequestContext) => {
+    for (const listener of [...listeners]) listener(event);
+    let told: DomainEvent[];
+    try {
+      told = shares(event);
+    } catch (error) {
+      reportError(error);
+      return;
+    }
+    for (const sharedEvent of told) eventBus.publish(sharedEvent, request);
+  };
 
+  // The lines that hear shared in the context maps, as one: each line gives the inputs of its own context, never those of another.
+  const lines = Object.entries(modules.contexts).flatMap(([name, { map }]) => map.flatMap((line): Translation[] => line.shares ? [] : [{
+    shares: false,
+    event: line.event,
+    inputs: (event: never, envelope: Envelope) => {
+      const inputs = line.inputs(event, envelope);
+      const foreign = inputs.find(input => ownerOfInput(input) !== contexts.get(name));
+      if (foreign) throw new Error(`the context map of ${name} gives ${foreign.constructor.name}, an input of another context: a context map gives the inputs of its own context`);
+      return inputs;
+    }
+  }]));
   const eventBus = new BackendEventBus({
-    map: new ContextMap(modules.map),
+    map: new ContextMap(lines),
     send: (input, envelope) => send(input, { correlationId: envelope.correlationId }),
     nextEventId: options.nextEventId ?? (() => crypto.randomUUID()),
     reportError
   });
 
-  for (const [name, { bindings, useCases, controllers }] of Object.entries(modules.contexts)) {
-    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases };
+  for (const [name, { bindings, useCases, controllers, map }] of Object.entries(modules.contexts)) {
+    const contextMap = new ContextMap(map);
+    const shares = name === SHARED ? (event: DomainEvent) => [event] : (event: DomainEvent) => contextMap.eventsFor(event);
+    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases, shares };
     for (const { input } of useCases) owners.set(input, context);
     for (const controller of controllers) owners.set(controller, context);
     contexts.set(name, context);
@@ -83,10 +120,18 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
     send,
     /** The controller of a context, built for a request. */
     controller: <C>(controller: abstract new (...args: never[]) => C, request: RequestContext = SYSTEM): C =>
-      requestOf(ownerOf(controller), request).scope.create(controller as unknown as Concrete<C>),
+      requestOf(ownerOf(controller, () => new Error(`No context has the controller ${controller.name}: write it in the folder of its use case, as <use-case>.<name>.controller.ts`)), request)
+        .scope.create(controller as unknown as Concrete<C>),
+    /** Publishes an event of shared on the shared bus. */
     publish: (event: DomainEvent, request: RequestContext = SYSTEM) => { eventBus.publish(event, request); },
     redeliver: (published: Published) => { eventBus.redeliver(published.event, published.envelope); },
+    /** Watches every event on the shared bus, in its envelope. */
     subscribe: (listener: (published: Published) => void) => eventBus.subscribe(listener),
+    /** Watches every event that the handlers publish in their context, before their context map shares it. */
+    subscribeToContexts: (listener: (event: DomainEvent) => void): (() => void) => {
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    },
     settled: () => eventBus.settled(),
     /** For the tests: the dependency with this token, built now if nothing needed it before. */
     get: <T>(token: Token<T>): T => {

package/src/di/createFrontend.ts

@@ -11,7 +11,7 @@ import { Fetcher } from "./Fetcher.js";
 type Handler = new () => { execute(input: unknown): unknown };
 
 /**
- * Builds the frontend of a context: its event bus, its message bus with the handlers of its use cases, its store, and a container with
+ * Builds the frontend of a context: its event bus, its message bus with the handlers of its use cases, its store if it has one, and a container with
  * the bindings of its di.ts. The container gives each class what its constructor needs: a handler gets the event bus as its
  * EventPublisher. The store gets it as its EventSubscriber.
  */
@@ -25,11 +25,14 @@ function build(context: FrontendModules, fetch: Fetcher, replace: readonly Bindi
     container.check(handler as Handler);
     bus.subscribe(input as never, received => container.create(handler as Handler).execute(received) as never);
   }
-  return { events, store: createStore(context.store, { events, bus }), bus, container };
+  return { events, store: context.store && createStore(context.store, { events, bus }), bus, container };
 }
 
-/** The frontend of a context, as the views get it: the publisher of its events, and the store they subscribe to. */
-export function createFrontend(context: FrontendModules, fetch: Fetcher, replace: readonly Binding[] = []): { events: EventPublisher<unknown>; store: Store<unknown> } {
+/**
+ * The frontend of a context, as the views get it: the publisher of its events, and the store they subscribe to (none, for a context
+ * without a store). The kernel subscribes to its events too, for its context map: the events of the context that it shares.
+ */
+export function createFrontend(context: FrontendModules, fetch: Fetcher, replace: readonly Binding[] = []): { events: FrontendEventBus<unknown>; store: Store<unknown> | undefined } {
   const { events, store } = build(context, fetch, replace);
   return { events, store };
 }

package/src/di/declareDependencies.js

@@ -9,12 +9,14 @@
  */
 
 /**
- * The code that a module needs after its own, for the containers:
+ * The code that a module needs after its own, for the containers and the message buses:
  * - after each class that has a constructor, the dependencies of the constructor (DEPENDENCIES in Container.ts): the name of each
  *   parameter, if it is optional, and the token of its type when the type has a value of the same name, declared in the module or
  *   imported from a relative path, from a shortcut of the project (#…, which a package.json or a tsconfig.json maps to a folder) or from
  *   one of the packages given (a port and its token, or a class: the kernel gives EventPublisher, DataDirectory…). The token is read only
  *   when the container needs it, thus a cycle between modules does no harm. The name of the type goes with its token, for the errors;
+ * - after each class that has an execute method, the value of the type of its first parameter, found the same way (INPUT in
+ *   discover.ts): the input DTO of a handler, which the message bus gives it;
  * - the name of each token declared without one: the name of its constant.
  * The names are text: the minifier can rename the code.
  * @param {string} code
@@ -31,6 +33,8 @@ export function declareDependencies(code, filename, parse, packages) {
   const values = new Set();
   /** @type {{ name: string; parameters: readonly ESTree.ParamPattern[] }[]} */
   const classes = [];
+  /** @type {{ name: string; input: ESTree.ParamPattern }[]} */
+  const executes = [];
   /** @type {string[]} */
   const tokens = [];
 
@@ -57,9 +61,12 @@ export function declareDependencies(code, filename, parse, packages) {
       values.add(declaration.id.name);
       const constructor = declaration.body.body.find(member => member.type === "MethodDefinition" && member.kind === "constructor");
       if (constructor?.type === "MethodDefinition") classes.push({ name: declaration.id.name, parameters: constructor.value.params });
+      const execute = declaration.body.body.find(member => member.type === "MethodDefinition" && member.kind === "method" && !member.static && !member.computed
+        && member.key.type === "Identifier" && member.key.name === "execute");
+      const input = execute?.type === "MethodDefinition" ? execute.value.params[0] : undefined;
+      if (input) executes.push({ name: declaration.id.name, input });
     }
   }
-  if (classes.length === 0 && tokens.length === 0) return undefined;
 
   /** @type {Map<string, string>} */
   const namespaces = new Map();
@@ -75,8 +82,7 @@ export function declareDependencies(code, filename, parse, packages) {
   };
   /** @type {(parameter: ESTree.ParamPattern, index: number) => string} */
   const dependencyOf = (parameter, index) => {
-    const inner = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter;
-    const pattern = inner.type === "AssignmentPattern" ? inner.left : inner;
+    const { inner, pattern } = partsOf(parameter);
     const name = pattern.type === "Identifier" ? pattern.name : `#${index}`;
     const typed = tokenOf(pattern.typeAnnotation?.typeAnnotation);
     const optional = inner.type === "AssignmentPattern" || pattern.optional === true;
@@ -84,9 +90,23 @@ export function declareDependencies(code, filename, parse, packages) {
   };
 
   const declarations = classes.map(({ name, parameters }) => `${name}[Symbol.for("kernel.dependencies")] = [${parameters.map(dependencyOf).join(", ")}];`);
+  const inputs = executes.flatMap(({ name, input }) => {
+    const typed = tokenOf(partsOf(input).pattern.typeAnnotation?.typeAnnotation);
+    return typed ? [`${name}[Symbol.for("kernel.input")] = () => ${typed.token};`] : [];
+  });
   const imports = [...namespaces].map(([source, alias]) => `import * as ${alias} from ${JSON.stringify(source)};`);
   const names = tokens.map(name => `${name}.name = ${JSON.stringify(name)};`);
-  return [...imports, ...declarations, ...names].join("\n");
+  const lines = [...imports, ...declarations, ...inputs, ...names];
+  return lines.length > 0 ? lines.join("\n") : undefined;
+}
+
+/**
+ * A parameter, without what TypeScript adds around it (`private readonly`), and its pattern, without its default value.
+ * @param {ESTree.ParamPattern} parameter
+ */
+function partsOf(parameter) {
+  const inner = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter;
+  return { inner, pattern: inner.type === "AssignmentPattern" ? inner.left : inner };
 }
 
 /** @type {(name: ESTree.ModuleExportName) => string} */

package/src/di/discover.ts

@@ -1,11 +1,14 @@
 import type { Translation } from "../messaging/ContextMap.js";
-import { Input } from "../messaging/Input.js";
 import type { Binding } from "./Container.js";
 
 export type Class = abstract new (...args: never[]) => unknown;
 export type UseCase = { readonly input: Class; readonly handler: Class };
-export type ContextModules = { bindings: readonly Binding[]; useCases: UseCase[]; controllers: Class[] };
-export type BackendModules = { shared: readonly Binding[]; contexts: Record<string, ContextModules>; map: Translation[] };
+/**
+ * A context of the backend: its bindings, its use cases, its controllers, and its context map: the events of shared that it hears, and
+ * the events of its own that it shares.
+ */
+export type ContextModules = { bindings: readonly Binding[]; useCases: UseCase[]; controllers: Class[]; map: Translation[] };
+export type BackendModules = { shared: readonly Binding[]; contexts: Record<string, ContextModules> };
 
 type Modules = Record<string, Record<string, unknown>>;
 
@@ -17,23 +20,59 @@ export function single<T>(found: T[], what: string): T {
   return found[0];
 }
 
-/** Turns the modules found in the backend folder (src/backend by default) into the contexts of the backend: a handler serves the input DTO of its use-case folder. */
-export function discover(found: { bindings: Record<string, readonly Binding[]>; dtos: Modules; handlers: Modules; controllers: Modules; map: Record<string, Translation[]> }): BackendModules {
+/** Where the plugin of the kernel writes the input DTO of a handler (see declareDependencies.js). */
+export const INPUT = Symbol.for("kernel.input");
+
+/**
+ * The use case of a handler: the handler, and the input DTO that its execute takes. The plugin of the kernel reads the class from the
+ * type of the parameter, as it reads the ports from the types of the constructor.
+ */
+export function useCaseOf(path: string, module: Record<string, unknown>): UseCase {
+  const handler = single(classesOf(module), `${path} declares one handler`);
+  const input = (handler as { [INPUT]?: () => unknown })[INPUT]?.();
+  if (typeof input !== "function") {
+    throw new Error(`${path}: ${handler.name}.execute names no input DTO. Give its parameter the type of the input DTO, the class that the use case receives.`);
+  }
+  return { input: input as Class, handler };
+}
+
+/**
+ * The lines of a context map, as its file gives them: the kernel refuses, when it starts, a map that is not a list of lines, rather than
+ * lose what it holds without a word. `isLine` tells a line of the side.
+ */
+export function linesIn<L>(path: string, map: unknown, isLine: (line: Partial<Record<string, unknown>>) => boolean, kernel: string): L[] {
+  const refused = (what: string) => new Error(`${path} lists the lines of its context map, export default [when(…), share(…)], made with ${kernel}: ${what}`);
+  if (!Array.isArray(map)) throw refused(`${JSON.stringify(map) ?? typeof map} is not a list`);
+  for (const line of map as unknown[]) {
+    if (!isLine(line ?? {})) throw refused(`${JSON.stringify(line) ?? typeof line} is not a line`);
+  }
+  return map as L[];
+}
+
+/** A line of a backend context map: one that hears gives inputs, one that shares gives events. */
+const isTranslation = ({ shares, event, inputs, events }: Partial<Record<string, unknown>>) =>
+  typeof event === "function" && (shares === false ? typeof inputs === "function" : shares === true && typeof events === "function");
+
+/**
+ * Turns the modules found in the backend folder (src/backend by default) into the contexts of the backend: a handler serves the input
+ * DTO that its execute takes, and the context map of a context gives the events of shared that it hears and those of its own that it
+ * shares.
+ */
+export function discover(found: { bindings: Record<string, readonly Binding[]>; handlers: Modules; controllers: Modules; maps: Record<string, Translation[]> }): BackendModules {
   const contexts: Record<string, ContextModules> = {};
-  const context = (path: string) => contexts[contextOf(path)] ??= { bindings: [], useCases: [], controllers: [] };
+  const context = (path: string) => contexts[contextOf(path)] ??= { bindings: [], useCases: [], controllers: [], map: [] };
   let shared: readonly Binding[] = [];
 
   for (const [path, bindings] of Object.entries(found.bindings)) {
     if (contextOf(path) === "shared") shared = bindings;
     else context(path).bindings = bindings;
   }
-  for (const [path, module] of Object.entries(found.handlers)) {
-    const dto = path.replace(".handler.ts", ".dto.ts");
-    const input = single(classesOf(found.dtos[dto] ?? {}).filter(type => type.prototype instanceof Input), `${dto} declares one input DTO`);
-    const handler = single(classesOf(module), `${path} declares one handler`);
-    context(path).useCases.push({ input, handler });
-  }
+  for (const [path, module] of Object.entries(found.handlers)) context(path).useCases.push(useCaseOf(path, module));
   for (const [path, module] of Object.entries(found.controllers)) context(path).controllers.push(...classesOf(module));
+  for (const [path, map] of Object.entries(found.maps)) {
+    if (contextOf(path) === "shared") throw new Error(`the backend context shared hears no other context: it has no context map (${path})`);
+    context(path).map = linesIn(path, map, isTranslation, "@ingenioz-it/caits/messaging/ContextMap");
+  }
 
-  return { shared, contexts, map: Object.values(found.map)[0] ?? [] };
+  return { shared, contexts };
 }

package/src/di/discoverFrontends.ts

@@ -1,36 +1,55 @@
-import { Input } from "../messaging/Input.js";
+import type { Line } from "../messaging/FrontendContextMap.js";
 import type { StoreDefinition } from "../state/createStore.js";
 import type { Binding } from "./Container.js";
-import { classesOf, single, type UseCase } from "./discover.js";
+import { linesIn, useCaseOf, type UseCase } from "./discover.js";
 
-export type FrontendModules = { bindings: readonly Binding[]; useCases: UseCase[]; store: StoreDefinition<unknown, unknown> };
+/**
+ * A context of the frontend: its bindings, its use cases, its store (none for a context without a use case: its views and its
+ * components publish events, and read no state), and its context map: the events of the context shared that it hears, and the events
+ * of its own that it shares.
+ */
+export type FrontendModules = { bindings: readonly Binding[]; useCases: UseCase[]; store?: StoreDefinition<unknown, unknown>; map: readonly Line[] };
 
 type Modules = Record<string, Record<string, unknown>>;
 
 const contextOf = (path: string) => /frontend\/([^/]+)\//.exec(path)![1];
 
+/** A line of a frontend context map: one that hears and one that shares both give events. */
+const isLine = ({ shares, event, events }: Partial<Record<string, unknown>>) => typeof shares === "boolean" && typeof event === "function" && typeof events === "function";
+
 /**
- * Turns the modules found in the frontend folder (src/frontend by default) into the contexts of the frontend: a context has a di.ts and a store,
- * and a handler serves the input DTO of its use-case folder.
+ * Turns the modules found in the frontend folder (src/frontend by default) into the contexts of the frontend: a context has a di.ts,
+ * a store at most, and its context map if it hears the context shared or shares events with it; a handler serves the input DTO that
+ * its execute takes.
  */
 export function discoverFrontends(found: {
   bindings: Record<string, readonly Binding[]>;
-  dtos: Modules;
   handlers: Modules;
   stores: Record<string, StoreDefinition<unknown, unknown>>;
+  maps: Record<string, readonly Line[]>;
 }): Record<string, FrontendModules> {
   const contexts: Record<string, FrontendModules> = {};
   for (const [path, bindings] of Object.entries(found.bindings)) {
     const name = contextOf(path);
-    const store = single(Object.entries(found.stores).filter(([storePath]) => contextOf(storePath) === name).map(([, definition]) => definition), `the frontend ${name} declares one store in presentation/store/`);
-    contexts[name] = { bindings, useCases: [], store };
+    const stores = Object.entries(found.stores).filter(([storePath]) => contextOf(storePath) === name).map(([, definition]) => definition);
+    if (stores.length > 1) throw new Error(`the frontend ${name} declares one store at most in presentation/store/ (found ${stores.length})`);
+    contexts[name] = { bindings, useCases: [], store: stores[0], map: [] };
+  }
+  for (const [path, map] of Object.entries(found.maps)) {
+    const context = contexts[contextOf(path)];
+    if (!context) throw new Error(`${path} belongs to a frontend without a di.ts`);
+    if (contextOf(path) === "shared") throw new Error(`the frontend context shared hears no other context: it has no context map (${path})`);
+    context.map = linesIn(path, map, isLine, "@ingenioz-it/caits/messaging/FrontendContextMap");
   }
   for (const [path, module] of Object.entries(found.handlers)) {
     const context = contexts[contextOf(path)];
     if (!context) throw new Error(`${path} belongs to a frontend without a di.ts`);
-    const dto = path.replace(".handler.ts", ".dto.ts");
-    const input = single(classesOf(found.dtos[dto] ?? {}).filter(type => type.prototype instanceof Input), `${dto} declares one input DTO`);
-    context.useCases.push({ input, handler: single(classesOf(module), `${path} declares one handler`) });
+    context.useCases.push(useCaseOf(path, module));
+  }
+  for (const [name, context] of Object.entries(contexts)) {
+    if (context.useCases.length > 0 && !context.store) {
+      throw new Error(`the frontend ${name} has use cases, but no store to send their input DTOs: it declares one in presentation/store/`);
+    }
   }
   return contexts;
 }

package/src/di/discovered.ts

@@ -1,6 +1,6 @@
 /// <reference path="../virtual-modules.d.ts" />
-import { bindings, dtos, handlers, controllers, map } from "virtual:kernel/backend";
+import { bindings, handlers, controllers, maps } from "virtual:kernel/backend";
 import { discover } from "./discover.js";
 
-/** Every context of the backend: its di.ts, its use cases and its controllers, and the context map. The plugin of the kernel finds them. */
-export const discovered = discover({ bindings, dtos, handlers, controllers, map });
+/** Every context of the backend: its di.ts, its use cases, its controllers and its context map. The plugin of the kernel finds them. */
+export const discovered = discover({ bindings, handlers, controllers, maps });

package/src/di/discoveredFrontends.ts

@@ -1,6 +1,6 @@
 /// <reference path="../virtual-modules.d.ts" />
-import { bindings, dtos, handlers, stores } from "virtual:kernel/frontend";
+import { bindings, handlers, maps, stores } from "virtual:kernel/frontend";
 import { discoverFrontends } from "./discoverFrontends.js";
 
-/** Every context of the frontend: its di.ts, its use cases and its store. The plugin of the kernel finds them. */
-export const discoveredFrontends = discoverFrontends({ bindings, dtos, handlers, stores });
+/** Every context of the frontend: its di.ts, its use cases, its store and its context map. The plugin of the kernel finds them. */
+export const discoveredFrontends = discoverFrontends({ bindings, handlers, stores, maps });