@ingenioz-it/caits 0.5.0 → 0.6.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). */
-const REPORT = "reports/mutation/mutation.json";
+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

@@ -0,0 +1,29 @@
+// `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";
+
+/** The configuration of Stryker in a project: it imports the defaults of CAITS (quality/caits/stryker.mjs). */
+export const STRYKER_CONFIG = "quality/stryker.config.mjs";
+
+/**
+ * @param {string[]} args the options 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.`);
+  // A run that stops before its report must not show the summary of the run before.
+  rmSync(REPORT, { force: true });
+  // Ctrl+C and `caits check` stop the whole group of processes: Stryker and its test runners stop with this command.
+  const stryker = spawn("npx", ["stryker", "run", STRYKER_CONFIG, ...args], { stdio: "inherit" });
+  /** @type {number} */
+  const status = await new Promise(resolve => {
+    stryker.on("error", () => resolve(1));
+    stryker.on("close", code => resolve(code ?? 1));
+  });
+  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,7 +1,7 @@
 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";
@@ -18,20 +18,27 @@ 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 => {
     const context = owners.get(owned);
@@ -40,11 +47,11 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   };
 
   /** 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);
@@ -54,15 +61,44 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
   const send = async <Output>(input: Input<Output>, request: RequestContext = SYSTEM): Promise<Output> =>
     requestOf(ownerOf(input.constructor as Class), 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 => ownerOf(input.constructor as Class) !== 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);
@@ -84,9 +120,16 @@ export function createBackend(modules: BackendModules, options: BackendOptions =
     /** 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>),
+    /** 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/discover.ts

@@ -4,8 +4,12 @@ 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,10 +21,31 @@ 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 {
+/**
+ * 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 of its use-case folder, 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[]>; dtos: Modules; 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)) {
@@ -34,6 +59,10 @@ export function discover(found: { bindings: Record<string, readonly Binding[]>;
     context(path).useCases.push({ input, handler });
   }
   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,29 +1,47 @@
 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 { classesOf, linesIn, single, 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 of its
+ * use-case folder.
  */
 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)];
@@ -32,5 +50,10 @@ export function discoverFrontends(found: {
     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`) });
   }
+  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, dtos, 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, dtos, 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, dtos, 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, dtos, handlers, stores, maps });

package/src/di/frontend.ts

@@ -1,3 +1,5 @@
+import type { EventPublisher } from "../messaging/EventPublisher.js";
+import { eventsFor, type Line } from "../messaging/FrontendContextMap.js";
 import { createFrontend } from "./createFrontend.js";
 import { discoveredFrontends } from "./discoveredFrontends.js";
 import type { Fetcher } from "./Fetcher.js";
@@ -6,7 +8,6 @@ import type { Fetcher } from "./Fetcher.js";
  * The frontends of the contexts, by name. Each context adds its own, next to its type:
  * `declare module "@ingenioz-it/caits/di/frontend" { interface Frontends { counter: CounterFrontend } }`.
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the contexts fill it
 export interface Frontends {}
 
 const kept = Symbol("frontends");
@@ -17,17 +18,58 @@ export function frontendsOn($global: object): Map<string, unknown> {
   return ($global as Global)[kept] ??= new Map<string, unknown>();
 }
 
+/** The context whose bus is the shared bus: the context maps share its events there, and hear them. */
+const SHARED = "shared";
+
 /**
  * The frontend of a context, for the views of one $global: the server has one $global per request, the browser one per page.
  * It is built the first time a view asks. On the server, it reaches the API with the fetch of the request (Marko Run, in the
- * same process); in the browser, with the fetch of the browser.
+ * same process); in the browser, with the fetch of the browser. The bus of the context shared is the shared bus of the $global: the
+ * context map of a context shares there the events of shared that the events of its context give, and each of them goes to the
+ * contexts whose context map hears it.
  */
 export function frontendOf<Name extends keyof Frontends>($global: object, name: Name): Frontends[Name] {
+  return frontendNamed($global, name) as Frontends[Name];
+}
+
+/** The frontend of the context of this name on a $global, built the first time that something asks for it. */
+function frontendNamed($global: object, name: string): unknown {
   const frontends = frontendsOn($global);
   if (!frontends.has(name)) {
     const context = discoveredFrontends[name];
     if (!context) throw new Error(`No frontend context is named ${name}`);
-    frontends.set(name, createFrontend(context, ($global as Global).fetch ?? ((input, init) => fetch(input, init))));
+    const frontend = createFrontend(context, ($global as Global).fetch ?? ((input, init) => fetch(input, init)));
+    frontends.set(name, frontend);
+    if (name === SHARED) frontend.events.subscribe(event => { hear($global, event as object); });
+    frontend.events.subscribe(event => { tell($global, context.map, event as object); });
+  }
+  return frontends.get(name);
+}
+
+/** The lines of a map that hear the context shared, or those that share with it. */
+const lines = (map: readonly Line[], shares: boolean) => map.filter(line => line.shares === shares);
+
+/**
+ * An event of a context, on its bus: the events of shared that the lines of its map that share give go to the shared bus of the $global.
+ * The frontend of shared is built when a context first shares an event.
+ */
+function tell($global: object, map: readonly Line[], event: object): void {
+  const told = eventsFor(lines(map, true), event);
+  if (told.length === 0) return;
+  const { events: shared } = frontendNamed($global, SHARED) as { events: EventPublisher<object> };
+  for (const sharedEvent of told) shared.publish(sharedEvent);
+}
+
+/**
+ * An event of the context shared, on the shared bus of a $global: each context whose context map hears it publishes the events that
+ * the lines that hear it give on its own bus, its frontend built if no view asked for it yet. A context that does not hear it is not
+ * built.
+ */
+function hear($global: object, event: object): void {
+  for (const [name, context] of Object.entries(discoveredFrontends)) {
+    const events = eventsFor(lines(context.map, false), event);
+    if (events.length === 0) continue;
+    const { events: bus } = frontendNamed($global, name) as { events: EventPublisher<object> };
+    for (const own of events) bus.publish(own);
   }
-  return frontends.get(name) as Frontends[Name];
 }

package/src/messaging/BackendEventBus.ts

@@ -8,8 +8,9 @@ export type Published = { readonly event: DomainEvent; readonly envelope: Envelo
 const nextTurn = () => new Promise(resolve => { setTimeout(resolve, 0); });
 
 /**
- * Carries the events of the contexts. The context map turns each event into input DTOs, and each input goes to the context that
- * handles it. The publisher never waits for the reactions; every failure is reported.
+ * The shared bus: carries the events of shared that the context maps share. The context map of each context turns the events of shared
+ * that it hears into input DTOs of the context, and each input goes to it. The publisher never waits for the reactions; every failure is
+ * reported.
  */
 export class BackendEventBus {
   private inFlight = new Set<Promise<void>>();
@@ -34,7 +35,7 @@ export class BackendEventBus {
     void delivery.then(() => { this.inFlight.delete(delivery); });
   }
 
-  /** Watches every event the contexts publish. */
+  /** Watches every event on the shared bus. */
   subscribe(listener: (published: Published) => void): () => void {
     this.listeners.add(listener);
     return () => { this.listeners.delete(listener); };

package/src/messaging/ContextMap.ts

@@ -6,17 +6,41 @@ export type Envelope = { readonly eventId: string; readonly correlationId: strin
 
 type EventClass<E> = abstract new (...args: never[]) => E;
 
-export type Translation = { readonly event: EventClass<DomainEvent>; readonly inputs: (event: never, envelope: Envelope) => Input<unknown>[] };
+/**
+ * One line of the context map of a backend context (its context-map.ts): an event of the context shared that it hears, which becomes
+ * input DTOs of the context, or an event of the context that it shares, which becomes events of the context shared.
+ */
+export type Translation =
+  | { readonly shares: false; readonly event: EventClass<DomainEvent>; readonly inputs: (event: never, envelope: Envelope) => Input<unknown>[] }
+  | { readonly shares: true; readonly event: EventClass<DomainEvent>; readonly events: (event: never) => DomainEvent[] };
 
-/** One line of the context map: an event of a context becomes input DTOs, for whichever contexts handle them. */
+/**
+ * A line that hears the context shared: when this event of shared comes on the shared bus, the handlers of the context execute these
+ * input DTOs. A context map names only its own context and the context shared: two contexts never name each other.
+ */
 export function when<E extends DomainEvent>(event: EventClass<E>, inputs: (event: E, envelope: Envelope) => Input<unknown>[]): Translation {
-  return { event, inputs };
+  return { shares: false, event, inputs };
+}
+
+/**
+ * A line that tells the other contexts: when a handler of the context publishes this event of its own, the context publishes these
+ * events of shared on the shared bus, and the context map of each context that hears them turns them into inputs of its own. The event
+ * of the context holds what the events of shared need.
+ */
+export function share<E extends DomainEvent>(event: EventClass<E>, events: (event: E) => DomainEvent[]): Translation {
+  return { shares: true, event, events };
 }
 
 export class ContextMap {
   constructor(private readonly translations: Translation[]) {}
 
+  /** The input DTOs that the lines that hear this event of shared give, none when no line hears it. */
   inputsFor(event: DomainEvent, envelope: Envelope): Input<unknown>[] {
-    return this.translations.filter(translation => event instanceof translation.event).flatMap(translation => translation.inputs(event as never, envelope));
+    return this.translations.flatMap(translation => !translation.shares && event instanceof translation.event ? translation.inputs(event as never, envelope) : []);
+  }
+
+  /** The events of shared that the lines that share this event of the context give, none when no line shares it. */
+  eventsFor(event: DomainEvent): DomainEvent[] {
+    return this.translations.flatMap(translation => translation.shares && event instanceof translation.event ? translation.events(event as never) : []);
   }
 }

package/src/messaging/EventPublisher.ts

@@ -2,8 +2,8 @@ import { Token } from "../Token.js";
 
 /**
  * Publishes the events of a context: the handlers get it, and the views of the frontend. It cannot subscribe, and it gives nothing back.
- * In the backend, the events go later to the other contexts, through the context map. In the frontend, they go at once to the store of
- * the same context.
+ * In the backend, the context map of the context shares them as events of shared, which go later to the other contexts. In the frontend,
+ * they go at once to the store of the same context, and its context map shares them.
  */
 export interface EventPublisher<E> {
   publish(event: E): void;