@ingenioz-it/caits 0.5.0 → 0.6.0

package/template/caits/eslint.js

@@ -15,6 +15,9 @@ export default tseslint.config(
   js.configs.recommended,
   ...tseslint.configs.recommendedTypeChecked,
   {
+    // The code turns off no rule: a comment such as eslint-disable has no effect. An exception lives in quality/eslint.config.js, for the
+    // files that need it (the architecture rule exceptions-in-quality refuses the comment itself).
+    linterOptions: { noInlineConfig: true },
     languageOptions: { parserOptions: { projectService: true, tsconfigRootDir: root } },
     rules: {
       "@typescript-eslint/no-floating-promises": "error",
@@ -25,6 +28,21 @@ export default tseslint.config(
       "no-empty-pattern": ["error", { allowObjectPatternsAsParameters: true }]
     }
   },
+  // A context map translates an event into others: what the new events hold comes from the event that it reads (and, in the backend,
+  // from its envelope), never from the clock, from chance, from the page or from a state that the map would keep.
+  {
+    files: ["src/*/*/context-map.ts"],
+    rules: {
+      "no-restricted-globals": ["error", ...["window", "document", "globalThis", "self", "localStorage", "sessionStorage", "navigator", "location", "fetch", "crypto", "performance", "process", "setTimeout", "setInterval", "queueMicrotask"]
+        .map(name => ({ name, message: "a context map reads only the event that it translates: the event of the context holds what the new events need" }))],
+      "no-restricted-properties": ["error", ...[["Date", "now"], ["Math", "random"]]
+        .map(([object, property]) => ({ object, property, message: "a context map reads only the event that it translates: the event of the context holds when and what" }))],
+      "no-restricted-syntax": ["error",
+        { selector: "NewExpression[callee.name='Date'][arguments.length=0]", message: "a context map reads only the event that it translates: the event of the context holds when" },
+        { selector: "Program > VariableDeclaration[kind!='const'], Program > ExportNamedDeclaration > VariableDeclaration[kind!='const']", message: "a context map keeps no state: each line gives the new events from the event alone" }
+      ]
+    }
+  },
   {
     files: ["test/**/*.ts", "src/**/*.test.ts", "src/**/*.contract.ts", "src/**/test.di.ts"],
     rules: { "@typescript-eslint/unbound-method": "off", "@typescript-eslint/no-unsafe-assignment": "off", "@typescript-eslint/no-unsafe-member-access": "off", "@typescript-eslint/no-unsafe-argument": "off", "@typescript-eslint/no-unsafe-call": "off", "@typescript-eslint/require-await": "off", "@typescript-eslint/no-empty-function": "off" }

package/template/caits/imports.mjs

@@ -0,0 +1,14 @@
+/**
+ * The packages that each layer may import, as CAITS gives them. An entry is a package (`uuid`), a module (`@ingenioz-it/caits/Token`), a
+ * Node API (`node:crypto`), or a folder of modules, ending with `/*` (`@ingenioz-it/caits/messaging/*`). A layer without a list imports
+ * any package. The imports of the files of the project (`#context/…`, `./…`) are not packages: the other rules check them.
+ * The domain holds the business rules: it imports only the primitives of the kernel. The application adds what a use case needs: its
+ * input DTOs extend Input, and its handler publishes events. The presentation, the infra, di.ts and the context map have no list.
+ * The project starts from these lists in its quality/imports.mjs.
+ */
+const domain = ["@ingenioz-it/caits/Result", "@ingenioz-it/caits/Token", "@ingenioz-it/caits/DomainEvent"];
+
+export const allowed = {
+  domain,
+  application: [...domain, "@ingenioz-it/caits/messaging/Input", "@ingenioz-it/caits/messaging/EventPublisher"]
+};

package/template/caits/tsconfig.json

@@ -10,7 +10,7 @@
     "noEmit": true,
     "noImplicitOverride": true,
     "noUnusedLocals": true,
-    "paths": { "#shared/*": ["../../src/backend/shared/*"] },
+    "paths": { "#shared/*": ["../../src/backend/shared/*"], "#frontend-shared/*": ["../../src/frontend/shared/*"] },
     "resolveJsonModule": true,
     "skipLibCheck": true,
     "strict": true,

package/template/caits/vite.ts

@@ -15,8 +15,10 @@ export default defineConfig({
   // `caits check` runs the checks at once: it gives each one a build folder of its own (CAITS_OUT_DIR), else they empty the folder of
   // each other. Without it, the build goes in dist/, which `npm start` runs.
   build: { outDir: process.env.CAITS_OUT_DIR || "dist" },
-  // The checks write their reports while the development server runs: a report is not a file of the app, and reloads no page.
-  server: { watch: { ignored: ["**/reports/**"] } },
+  // The checks write their reports while the development server runs: a report is not a file of the app, and reloads no page. The
+  // sandbox of the mutation tests (.stryker-tmp/) copies the project, its tsconfig.json too: the server would empty its cache at each
+  // copy, and lose the dependencies that it optimized.
+  server: { watch: { ignored: ["**/reports/**", "**/.stryker-tmp/**"] } },
   css: { preprocessorOptions: { scss: { loadPaths: [STYLE_FOLDER] } } },
   test: {
     include: ["src/**/*.test.ts", "test/**/*.test.ts", "quality/**/*.test.mjs"],

package/template/project/AGENTS

@@ -11,18 +11,22 @@ A CAITS project (Clean Architecture In TypeScript): a Marko app with a backend a
 
 ## Where the code goes
 
-- The business lives in bounded contexts: `src/backend/<context>/` and `src/frontend/<context>/`, each with `domain/`, `application/`, `infra/`, `presentation/` and a `di.ts`. To add one, copy the shape of an existing one.
+- The business lives in bounded contexts: `src/backend/<context>/` and `src/frontend/<context>/`, each with `domain/`, `infra/`, its use cases in `command/` and `query/`, and a `di.ts`. A frontend context has `event/` and `presentation/` too. To add one, copy the shape of an existing one.
 - Domain: entities, value objects, errors, domain events, and ports (`domain/port/<port>/`), each with its contract (`<Port>.contract.ts`).
-- Application: one folder per use case, `command/<use-case>/` or `query/<use-case>/`, with its DTOs, its handler and its test.
+- Use cases: one folder per use case, `command/<use-case>/` or `query/<use-case>/`, which holds all of it: its DTOs, its handler and its test, `<use-case>.application.test.ts`, and in the backend its controllers, `<use-case>.<name>.controller.ts` (`<use-case>.http.controller.ts` for HTTP), each with its test, `<use-case>.<name>.presentation.test.ts`. An endpoint lives in one folder, and the name of a test says the layer that it tests. A use case imports nothing from another use case: what they share lives in the domain.
 - Infra: the adapters of the ports, in `infra/<port>/`. The test of each adapter runs the contract of its port.
-- Presentation: the controllers in the backend; the views and the store in the frontend.
-- Dependencies point to the domain. A context imports its own files with `#context/`, never with `../`.
-- `src/routes/` holds the pages and the HTTP handlers: a page places views, a handler gives the request to a controller.
+- Frontend: its events, one file each in `event/`, and its presentation, which serves several use cases: the views (`presentation/view/<view>/`), which the routes place; the components, `presentation/component/<component>/`, the parts that the views place; and the store (`presentation/store/`), if the context has use cases. A view and a component take the frontend of their context only, publish its events and read its store. A view imports no other view, and a component no view.
+- The contexts talk through the context shared, `src/backend/shared/` and `src/frontend/shared/`, and their context map, `context-map.ts` beside their di.ts. A handler (in the frontend, also a view or a component) publishes an event of its context; the context map, `share(Event, event => [...])`, turns it into events of shared on the shared bus (the event of the context holds what they need). The context map of each context that hears it, `when(Event, event => [...])`, turns it into input DTOs of the context (backend) or into events of the context (frontend). Each line goes one way, reads only its event, and the lines make no cycle. A context names only itself and shared, never another context: only its context map imports the events of shared.
+- A component of the frontend context shared is a Marko tag, `component/<name>/index.marko`: a context places it by its name (`<badge>`), and `src/frontend/marko.json` gives Marko their folder.
+- Dependencies point to the domain. A context imports its own files with `#context/`, and the context shared of its side with `#shared/` (backend) or `#frontend-shared/` (frontend), never with `../`.
+- `src/routes/` holds the pages and the HTTP handlers, and no logic and no test: a page places views, a handler gives the request to a controller. A document that the pages give in another format than HTML (a sitemap, a feed) has its route in a folder named after its file, `` `sitemap.xml`/+handler.ts ``, which gives the GET of a view. The code that a test reads lives in a context.
 
 ## Rules
 
 - Write the test first. The coverage and the mutation score stay at 100%.
+- A test reads only its own context and shared: no test crosses contexts.
 - A check that fails names the file and the rule: fix the code, not the rule.
+- No comment turns off a check (`eslint-disable`, `@ts-ignore`, `v8 ignore`, `Stryker disable`), and no test is skipped. An exception lives in `quality/`, as narrow as it can be.
 - Do not change `quality/` (the rules, the thresholds, the configuration of the tools) without asking.
 
 Documentation: https://caits.dev/docs

package/template/project/quality/imports.mjs

@@ -0,0 +1,10 @@
+import { allowed } from "./caits/imports.mjs";
+
+/**
+ * The packages that each layer of this project may import, which `caits architecture` checks. They start from those of CAITS
+ * (quality/caits/imports.mjs): the domain and the application import only the kernel's primitives, and the other layers any package.
+ * Add a package to a list on purpose, for example:
+ *   export default { ...allowed, domain: [...allowed.domain, "uuid"] };
+ * The keys are domain, application, presentation, infra, di and contextMap. A layer without a list imports any package.
+ */
+export default allowed;