@ingenioz-it/caits 0.0.0-stage → 0.5.0

package/package.json

@@ -1,6 +1,116 @@
 {
   "name": "@ingenioz-it/caits",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "CAITS (Clean Architecture In TypeScript): the technical base of a Marko project with a backend and a frontend.",
+  "keywords": [
+    "clean-architecture",
+    "typescript",
+    "marko",
+    "marko-run",
+    "vite",
+    "vitest",
+    "ddd",
+    "hexagonal-architecture",
+    "starter",
+    "template"
+  ],
+  "homepage": "https://caits.dev",
+  "bugs": "https://github.com/IngeniozIT/caits/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IngeniozIT/caits.git"
+  },
+  "author": "Ingenioz IT",
+  "license": "0BSD",
+  "type": "module",
+  "bin": {
+    "caits": "bin/caits.js"
+  },
+  "exports": {
+    "./vite": {
+      "types": "./src/vite.types.d.ts",
+      "default": "./src/vite.js"
+    },
+    "./quality/*": "./quality/*.mjs",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "bin",
+    "quality",
+    "src",
+    "template",
+    "!bin/**/*.test.ts",
+    "!quality/**/*.test.mjs",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || >=26.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p .",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run stryker.config.json",
+    "test:template": "node test/template.js",
+    "check": "npm run typecheck && npm run lint && npm run test:coverage"
+  },
+  "dependencies": {
+    "magic-string": "^0.30.21"
+  },
+  "peerDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@marko/compiler": "^5.42.10",
+    "@marko/run": "^0.11.13",
+    "@playwright/test": "^1.64.0",
+    "typescript-eslint": "^8.71.0",
+    "vite": "^8.0.0",
+    "vitest": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@eslint/js": {
+      "optional": true
+    },
+    "@marko/compiler": {
+      "optional": true
+    },
+    "@marko/run": {
+      "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
+    },
+    "typescript-eslint": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@marko/compiler": "^5.42.10",
+    "@marko/run": "^0.11.13",
+    "@marko/type-check": "^3.2.1",
+    "@playwright/test": "^1.64.0",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/typescript-checker": "^10.0.0",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.11.0",
+    "happy-dom": "^20.14.5",
+    "marko": "^6.4.0",
+    "sass": "^1.105.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.0",
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
+  }
+}

package/quality/architecture/adapters/marko.mjs

@@ -0,0 +1,23 @@
+import compiler from "@marko/compiler";
+import { dirname, relative } from "node:path";
+import { factsOf } from "../facts.mjs";
+
+/**
+ * Reads a Marko template (its absolute path, and its text) with the Marko compiler: it parses the markup and the JavaScript in it,
+ * and translates nothing.
+ * A tag that Marko finds by discovery (in a tags/ folder of the project) is a dependency without an import: it counts as one.
+ * @param {string} file
+ * @param {string} text
+ */
+export function readMarko(file, text) {
+  const { ast } = compiler.compileSync(text, file, { output: "source", ast: true, code: false, sourceMaps: false });
+  const facts = factsOf(ast.program, text);
+  const lookup = compiler.taglib.buildLookup(dirname(file));
+  for (const name of new Set(facts.tags)) {
+    const template = lookup.getTag(name)?.template;
+    if (!template || template === file || template.includes("/node_modules/")) continue;
+    const specifier = relative(dirname(file), template).replaceAll("\\", "/");
+    facts.imports.push(specifier.startsWith(".") ? specifier : `./${specifier}`);
+  }
+  return facts;
+}

package/quality/architecture/adapters/scss.mjs

@@ -0,0 +1,52 @@
+import { dirname, posix } from "node:path";
+
+/** A string, or a comment: the comments are removed, the strings stay (a string can hold "//", as a URL does). */
+const STRING_OR_COMMENT = /("(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+const USE_OR_FORWARD = /@(?:use|forward)\s+(["'])(.+?)\1/g;
+const IMPORT = /@import\s+([^;]+);/g;
+const QUOTED = /^\s*(["'])(.+)\1\s*$/;
+
+/** The load path that the Vite configuration of CAITS gives to Sass: the folder of the stylesheets of the app (quality/caits/vite.ts). */
+export const STYLE_FOLDER = "src/routes/_frontend/style";
+
+/**
+ * Reads a stylesheet (SCSS): the files that it loads with `@use`, `@forward` and `@import`. The comments do not count.
+ * Sass looks for a path first next to the file, then in its load path, then in the packages. Thus a path that leads to a file next to
+ * the stylesheet (`theme` for _theme.scss) becomes relative (`./theme`); a path that leads to a file of the load path becomes a path
+ * from the root of the project (`/src/routes/_frontend/style/values`); the others stay names of packages, as `sass:math` does.
+ * @param {string} path the path of the stylesheet, from the root of the project
+ * @param {string} text
+ * @param {Set<string>} paths the paths of all the files of the project
+ */
+export function readScss(path, text, paths) {
+  const code = text.replace(STRING_OR_COMMENT, (/** @type {string} */ _match, /** @type {string | undefined} */ string) => string ?? "");
+  const specifiers = [...code.matchAll(USE_OR_FORWARD)].map(match => match[2]);
+  for (const [, list] of code.matchAll(IMPORT)) {
+    for (const item of list.split(",")) {
+      const [, , specifier] = QUOTED.exec(item) ?? [];
+      if (specifier) specifiers.push(specifier);
+    }
+  }
+  const imports = specifiers.map(specifier => {
+    if (isIn(dirname(path), specifier, paths)) return `./${specifier}`;
+    return isIn(STYLE_FOLDER, specifier, paths) ? `/${posix.join(STYLE_FOLDER, specifier)}` : specifier;
+  });
+  return { imports, exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [] };
+}
+
+/**
+ * Whether Sass finds a path without a dot (`theme`, `parts/menu`) in a folder: `theme.scss`, the partial `_theme.scss`, `theme.css`, or
+ * the index of a folder `theme/`.
+ * @param {string} folder
+ * @param {string} specifier
+ * @param {Set<string>} paths
+ */
+function isIn(folder, specifier, paths) {
+  if (/^[./#]|^[a-z]+:/.test(specifier)) return false;
+  const base = posix.join(folder, specifier);
+  const partial = posix.join(posix.dirname(base), `_${posix.basename(base)}`);
+  const candidates = /\.(scss|sass|css)$/.test(base)
+    ? [base, partial]
+    : [`${base}.scss`, `${partial}.scss`, `${base}.css`, `${base}/_index.scss`, `${base}/index.scss`];
+  return candidates.some(candidate => paths.has(candidate));
+}

package/quality/architecture/adapters/typescript.mjs

@@ -0,0 +1,13 @@
+import { parseSync } from "vite";
+import { factsOf } from "../facts.mjs";
+
+/**
+ * Reads a TypeScript file with oxc, the parser of Vite, which the build already uses (the plugin of the kernel, @ingenioz-it/caits/vite).
+ * @param {string} path
+ * @param {string} text
+ */
+export function readTypeScript(path, text) {
+  const { program, errors } = parseSync(path, text);
+  if (errors.length > 0) throw new Error(`${path}: ${errors[0].message}`);
+  return factsOf(program, text);
+}

package/quality/architecture/facts.mjs

@@ -0,0 +1,159 @@
+/**
+ * What the rules read in a file. An adapter parses the file, then gives its tree to factsOf: the tree of oxc (ESTree) for
+ * TypeScript, the tree of Babel for Marko. The two trees differ in a few names only, so one walk reads both.
+ */
+
+/**
+ * A node of the tree of oxc or of Babel. The nodes have many shapes, and the walk reads the fields of the two trees: they have no type.
+ * @typedef {any} Node
+ */
+/** @typedef {{ name: string | null; kind: string }} Export an exported name, and its kind */
+/** @typedef {{ name: string | null; readonly: boolean; value: string | null; asConst: boolean }} Property a property of a class */
+/** @typedef {{ name: string | null; exported: boolean; extends: string | null; implements: string[]; properties: Property[] }} Class */
+/** @typedef {{ chain: string[]; source: string }} Item an item of `export default [ … ]` */
+/** @typedef {{ name: string | null; args: (string | null)[] }} Call */
+/**
+ * What the rules read in a file: see factsOf.
+ * @typedef {{
+ *   imports: string[]; exports: Export[]; defaultArray: Item[] | null; classes: Class[]; constructed: (string | null)[]; calls: Call[];
+ *   objectTypes: string[]; strings: string[]; tags: string[]
+ * }} Facts
+ */
+
+const SKIPPED_KEYS = new Set(["loc", "range", "start", "end", "extra", "leadingComments", "innerComments", "trailingComments", "comments"]);
+const WITH_SOURCE = new Set(["ImportDeclaration", "ExportNamedDeclaration", "ExportAllDeclaration", "ImportExpression"]);
+/** @type {Record<string, string>} */
+const DECLARATION_KINDS = { ClassDeclaration: "class", FunctionDeclaration: "function", TSInterfaceDeclaration: "interface", TSTypeAliasDeclaration: "type", TSEnumDeclaration: "enum" };
+
+/** @type {(node: Node) => string | null} */
+const stringOf = node => {
+  if ((node?.type === "Literal" || node?.type === "StringLiteral") && typeof node.value === "string") return node.value;
+  if (node?.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0].value.cooked;
+  if (node?.type === "TSAsExpression" || node?.type === "TSLiteralType") return stringOf(node.expression ?? node.literal);
+  return null;
+};
+/** @type {(node: Node) => string | null} */
+const nameOf = node => node?.type === "Identifier" ? node.name : node?.type === "MemberExpression" && !node.computed ? node.property.name : null;
+/** @type {(node: Node) => string | null} */
+const keyOf = node => node.key?.name ?? stringOf(node.key);
+
+/**
+ * The names a call chain calls, from the first: `bind(X).to(Y).with(z)` calls bind, to, with.
+ * @param {Node} node
+ * @returns {string[]}
+ */
+function chainOf(node) {
+  /** @type {string[]} */
+  const names = [];
+  while (node?.type === "CallExpression") {
+    if (node.callee.type === "Identifier") return [node.callee.name, ...names];
+    if (node.callee.type !== "MemberExpression" || node.callee.computed) return [];
+    names.unshift(node.callee.property.name);
+    node = node.callee.object;
+  }
+  return [];
+}
+
+/**
+ * @param {Node} node
+ * @returns {Export[]}
+ */
+function exportsOf(node) {
+  if (node.type === "ExportDefaultDeclaration") return [{ name: "default", kind: "default" }];
+  if (node.type === "ExportAllDeclaration") return [{ name: node.exported ? nameOf(node.exported) ?? stringOf(node.exported) : "*", kind: "all" }];
+  const { declaration } = node;
+  if (!declaration) return node.specifiers.map((/** @type {Node} */ specifier) => ({ name: nameOf(specifier.exported) ?? stringOf(specifier.exported), kind: "specifier" }));
+  if (declaration.type === "VariableDeclaration") return declaration.declarations.map((/** @type {Node} */ declarator) => ({ name: declarator.id.name, kind: declaration.kind }));
+  return [{ name: declaration.id?.name, kind: DECLARATION_KINDS[declaration.type] ?? declaration.type }];
+}
+
+/** @type {(node: Node, exported: boolean) => Class} */
+const classOf = (node, exported) => ({
+  name: node.id?.name ?? null,
+  exported,
+  extends: nameOf(node.superClass),
+  implements: (node.implements ?? []).map((/** @type {Node} */ heritage) => nameOf(heritage.expression)).filter(Boolean),
+  properties: node.body.body.filter((/** @type {Node} */ member) => member.type === "PropertyDefinition" || member.type === "ClassProperty").map((/** @type {Node} */ member) => ({
+    name: keyOf(member),
+    readonly: Boolean(member.readonly),
+    value: stringOf(member.value),
+    asConst: member.value?.type === "TSAsExpression" && member.value.typeAnnotation?.typeName?.name === "const"
+  }))
+});
+
+/**
+ * - imports: every module the file imports or re-exports, dynamic imports included;
+ * - exports: each exported name, with its kind (class, interface, type, const, function, enum, specifier, default, all);
+ * - defaultArray: the items of `export default [ … ]`, with the calls of each item (`bind(X).to(Y)` calls bind, to), or null;
+ * - classes: the classes, with what they extend and implement, and their properties;
+ * - constructed: the class of each `new X(…)`;
+ * - calls: each call, with the value of its arguments that are strings (null for the others);
+ * - objectTypes: the value of each `type: "…"` of an object literal;
+ * - strings: every string of the code (comments and import paths aside);
+ * - tags: the name of each Marko tag (Marko only).
+ * @param {Node} program
+ * @param {string} text
+ * @returns {Facts}
+ */
+export function factsOf(program, text) {
+  /** @type {Facts} */
+  const facts = { imports: [], exports: [], defaultArray: null, classes: [], constructed: [], calls: [], objectTypes: [], strings: [], tags: [] };
+  const exportedClasses = new WeakSet();
+  const seen = new WeakSet();
+
+  /** @param {Node} node */
+  const visit = node => {
+    if (WITH_SOURCE.has(node.type)) {
+      const source = stringOf(node.source);
+      if (source !== null) facts.imports.push(source);
+    }
+    if (node.type === "TSImportType") {
+      const source = stringOf(node.source ?? node.argument);
+      if (source !== null) facts.imports.push(source);
+    }
+    if (node.type === "CallExpression" && node.callee.type === "Import") {
+      const source = stringOf(node.arguments[0]);
+      if (source !== null) facts.imports.push(source);
+    }
+    if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") {
+      facts.exports.push(...exportsOf(node));
+      if (node.declaration?.type === "ClassDeclaration") exportedClasses.add(node.declaration);
+      if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "ArrayExpression") {
+        facts.defaultArray = node.declaration.elements.map((/** @type {Node} */ item) => ({ chain: chainOf(item), source: item ? text.slice(item.start, item.end).replace(/\s+/g, " ") : "" }));
+      }
+    }
+    if (node.type === "ClassDeclaration") facts.classes.push(classOf(node, exportedClasses.has(node)));
+    if (node.type === "NewExpression") facts.constructed.push(nameOf(node.callee));
+    if (node.type === "CallExpression") facts.calls.push({ name: nameOf(node.callee), args: node.arguments.map(stringOf) });
+    if (node.type === "ObjectExpression") {
+      for (const property of node.properties) {
+        const type = stringOf(property.value);
+        if ((property.type === "Property" || property.type === "ObjectProperty") && !property.computed && keyOf(property) === "type" && type !== null) {
+          facts.objectTypes.push(type);
+        }
+      }
+    }
+    if ((node.type === "Literal" || node.type === "StringLiteral") && typeof node.value === "string") facts.strings.push(node.value);
+    if (node.type === "TemplateElement") facts.strings.push(node.value.cooked);
+    const tag = node.type === "MarkoTag" ? stringOf(node.name) : null;
+    if (tag !== null) facts.tags.push(tag);
+  };
+
+  /** @type {(node: Node, parentType?: string, key?: string) => void} */
+  const walk = (node, parentType = "", key = "") => {
+    if (!node || typeof node !== "object" || seen.has(node)) return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item, parentType, key);
+      return;
+    }
+    if (key === "source" && WITH_SOURCE.has(parentType)) return;
+    if (typeof node.type === "string") visit(node);
+    for (const [childKey, child] of Object.entries(node)) {
+      if (!SKIPPED_KEYS.has(childKey)) walk(child, node.type, childKey);
+    }
+  };
+
+  walk(program);
+  return facts;
+}

package/quality/architecture/project.mjs

@@ -0,0 +1,148 @@
+import { dirname, posix, relative, resolve } from "node:path";
+
+/** What the rules know of the project: where a file lives, what it imports, and how the parts are named. */
+
+/** @import { Facts } from "./facts.mjs" */
+/** @typedef {"backend" | "frontend"} Side */
+/**
+ * Where a file lives: see locate. Only a layer has a context and a layer, and only a layer and the routes have a side.
+ * @typedef {{ kind: "other" | "map" | "test-environment"; side?: undefined; context?: undefined; layer?: undefined }
+ *   | { kind: "routes"; side: Side; context?: undefined; layer?: undefined }
+ *   | { kind: "layer"; side: Side; context: string; layer: string }} Location
+ */
+/** A file of the project: its path from the root of the project, and what the rules read in it. @typedef {Facts & { path: string }} File */
+/** The project: its root, its files, and their paths. @typedef {{ root: string; files: File[]; paths: Set<string> }} Project */
+/**
+ * An import of the production code: its file, where the file and its target live, the specifier, and the target (a path from the root of
+ * the project when the import is internal, else the specifier).
+ * @typedef {{ file: File; from: Location; to: Location; specifier: string; internal: boolean; target: string }} Import
+ */
+/** What a check gives: nothing, or false, when the rule holds; else a message, or a list of messages. @typedef {string | string[] | false | null | undefined | void} Messages */
+/**
+ * A rule of the architecture: see the rules of CAITS (quality/caits/architecture.mjs). A rule can keep values of its own, which its check
+ * reads with `this`: a project can change them.
+ * @typedef {{ name: string; description: string; [value: string]: unknown } & (
+ *   | { on: "import"; check(link: Import): Messages }
+ *   | { on: "file"; production?: boolean; check(file: File, project: Project): Messages }
+ *   | { on: "project"; check(project: Project): { file: string; message: string }[] }
+ * )} Rule
+ */
+
+/** The kernel is a package: the app imports it by its name, and it holds no file of the project. */
+export const KERNEL = { name: "@ingenioz-it/caits" };
+
+/**
+ * The path of an import in the kernel, without the name of the kernel (`di/Container`), or null for an import of something else.
+ * @type {(specifier: string) => string | null}
+ */
+export const kernelPathOf = specifier => specifier.startsWith(`${KERNEL.name}/`) ? specifier.slice(KERNEL.name.length + 1) : null;
+
+/**
+ * Where a file lives: a test environment (test.di.ts), the routes of one side, the context map, a layer of a context (its di.ts is a
+ * layer too), or elsewhere.
+ * @param {string} path
+ * @returns {Location}
+ */
+export function locate(path) {
+  const parts = path.split("/");
+  if (parts[0] !== "src") return { kind: "other" };
+  if (parts[1] === "routes") return { kind: "routes", side: parts[2] === "_frontend" ? "frontend" : "backend" };
+  if (parts[1] === "backend" && parts.length === 3) return { kind: "map" };
+  if (/^test\.di\.(js|ts)$/.test(parts[parts.length - 1])) return { kind: "test-environment" };
+  if ((parts[1] === "backend" || parts[1] === "frontend") && parts.length === 4) return { kind: "layer", context: parts[2], side: parts[1], layer: "di" };
+  if (parts[1] === "backend" || parts[1] === "frontend") return { kind: "layer", context: parts[2], side: parts[1], layer: parts[3] };
+  return { kind: "other" };
+}
+
+/** The domain and the application: the code that holds no technology. @type {(where: Location) => boolean} */
+export const isCore = where => where.kind === "layer" && (where.layer === "domain" || where.layer === "application");
+
+/** Tests, contracts, test environments (test.di.ts) and test/. @type {(path: string) => boolean} */
+export const isTestCode = path => /\.(test|contract)\.ts$|(^|\/)test\.di\.ts$/.test(path) || path.startsWith("test/");
+
+/**
+ * The shortcuts of the imports, to the folders they lead to. #context leads to the context of the file: each context has a package.json
+ * that says it. #shared leads to the backend context shared: tsconfig.json says it to TypeScript, and the kernel's plugin to Vite.
+ * #backend and #frontend lead to the sides, for the routes: the package.json of the project says it.
+ */
+const SHORTCUTS = new Map([["shared", "src/backend/shared"], ["backend", "src/backend"], ["frontend", "src/frontend"]]);
+
+/** The folder of the context that holds a file (src/backend/notes), or undefined. @type {(path: string) => string | undefined} */
+const contextFolderOf = path => /^src\/(backend|frontend)\/[^/]+(?=\/)/.exec(path)?.[0];
+
+/**
+ * An import names a package (the kernel is one), or a file of the project: its target is then the path from the root of the project.
+ * So is a shortcut: `#context/domain/entity/Note.js`, in src/backend/notes, is src/backend/notes/domain/entity/Note.js.
+ * So is a path from the root of the project (`/src/…`): Vite reads it, and the reading of a stylesheet gives one for a load path.
+ * @param {string} from the path of the file that imports, from the root of the project
+ * @param {string} specifier
+ * @param {string} root
+ * @returns {{ internal: boolean; target: string }}
+ */
+export function resolveImport(from, specifier, root) {
+  const [, shortcut, rest] = /^#([^/]+)\/(.*)$/.exec(specifier) ?? [];
+  const folder = shortcut === "context" ? contextFolderOf(from) : SHORTCUTS.get(shortcut);
+  if (folder) return { internal: true, target: posix.normalize(`${folder}/${rest}`) };
+  if (specifier.startsWith("/")) return { internal: true, target: posix.normalize(specifier.slice(1)) };
+  if (!specifier.startsWith(".")) return { internal: false, target: specifier };
+  const absolute = resolve(root, dirname(from), specifier);
+  return { internal: true, target: relative(root, absolute).replaceAll("\\", "/") };
+}
+
+/** The files of the project that a file imports, without their extension. @type {(file: File, root: string) => string[]} */
+export const importedModules = (file, root) => file.imports
+  .map(specifier => resolveImport(file.path, specifier, root))
+  .filter(({ internal }) => internal)
+  .map(({ target }) => target.replace(/\.(js|ts)$/, ""));
+
+/** @type {(specifier: string, ...names: string[]) => boolean} */
+export const isPackage = (specifier, ...names) => names.some(name => specifier === name || specifier.startsWith(`${name}/`));
+/** @type {(specifier: string) => boolean} */
+export const isMarko = specifier => isPackage(specifier, "marko", "@marko/run", "@marko/vite") || specifier.endsWith(".marko");
+/** @type {(specifier: string) => boolean} */
+export const isNode = specifier => specifier.startsWith("node:");
+
+/**
+ * A port, or its contract: {context}/domain/port/{folder}/{Port}.ts or {Port}.contract.ts. Its module is its path without the extension.
+ * @param {string} path
+ * @returns {{ folder: string; name: string; contract: boolean; module: string } | null}
+ */
+export function portOf(path) {
+  const match = /^(src\/(?:backend|frontend)\/[^/]+)\/domain\/port\/([a-z0-9-]+)\/([A-Z]\w*?)(\.contract)?\.ts$/.exec(path);
+  if (!match) return null;
+  const [, context, folder, name, contract] = match;
+  return { folder, name, contract: Boolean(contract), module: `${context}/domain/port/${folder}/${name}` };
+}
+
+/**
+ * An adapter, or its test: {context}/infra/{folder}/{file}. It implements the port named after its folder.
+ * @param {string} path
+ * @returns {{ folder: string; test: boolean; port: string; portModule: string } | null}
+ */
+export function adapterOf(path) {
+  const match = /^(src\/(?:backend|frontend)\/[^/]+)\/infra\/([a-z0-9-]+)\/([^/]+)$/.exec(path);
+  if (!match) return null;
+  const [, context, folder, name] = match;
+  const port = pascal(folder);
+  return { folder, test: name.endsWith(".test.ts"), port, portModule: `${context}/domain/port/${folder}/${port}` };
+}
+
+/** The contexts whose frontend a file takes: `frontendOf($global, "notes")` takes the frontend of notes. @type {(file: File) => string[]} */
+export const frontendsOf = file => file.calls.flatMap(({ name, args: [, context] }) => name === "frontendOf" && typeof context === "string" ? [context] : []);
+
+/** @type {(name: string) => string} */
+export const kebab = name => name.replace(/(?<!^)([A-Z])/g, "-$1").toLowerCase();
+/** @type {(kebab: string) => string} */
+export const pascal = kebab => kebab.split("-").map(word => word[0].toUpperCase() + word.slice(1)).join("");
+
+/**
+ * The type of a frontend event, which the store reads: the context, then the name of the event without the context, in kebab-case.
+ * @param {string} context
+ * @param {string} name
+ */
+export function typeOfEvent(context, name) {
+  const plural = pascal(context);
+  const singular = plural.replace(/s$/, "");
+  const rest = name.startsWith(plural) ? name.slice(plural.length) : name.startsWith(singular) ? name.slice(singular.length) : name;
+  return `${context}.${kebab(rest)}`;
+}

package/quality/architecture.mjs

@@ -0,0 +1,116 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readMarko } from "./architecture/adapters/marko.mjs";
+import { readScss } from "./architecture/adapters/scss.mjs";
+import { readTypeScript } from "./architecture/adapters/typescript.mjs";
+import { isTestCode, locate, resolveImport } from "./architecture/project.mjs";
+
+/** What a rule knows of the project. The rules of CAITS use it, and the rules of a project can use it too. */
+export * from "./architecture/project.mjs";
+
+/** @import { File, Import, Messages, Rule } from "./architecture/project.mjs" */
+/** @typedef {{ rule: string; file: string; message: string; subject?: string }} Violation */
+
+/** The file of a project that gives its rules: its default export is the list of the rules. */
+export const RULES_FILE = "quality/architecture.mjs";
+
+/**
+ * Checks the rules on the files of a project. Each source is a file: its path from the root of the project, and its text.
+ * Gives the production files, the test files, and each violation: its rule, its file, its message, and the import that breaks it.
+ * @param {string} root
+ * @param {{ path: string; text: string }[]} sources
+ * @param {Rule[]} rules
+ * @returns {{ production: number; tests: number; violations: Violation[] }}
+ */
+export function checkArchitecture(root, sources, rules) {
+  checkRules(rules);
+  const paths = new Set(sources.map(({ path }) => path));
+  /** @type {(path: string, text: string) => import("./architecture/facts.mjs").Facts} */
+  const read = (path, text) => {
+    if (path.endsWith(".marko")) return readMarko(join(root, path), text);
+    return path.endsWith(".scss") ? readScss(path, text, paths) : readTypeScript(path, text);
+  };
+  /** @type {File[]} */
+  const files = sources.map(({ path, text }) => ({ path, ...read(path, text) }));
+  const production = files.filter(file => !isTestCode(file.path));
+  const project = { root, files, paths };
+
+  /** @type {Violation[]} */
+  const violations = [];
+  /** @type {(rule: Rule, file: string, message: string, subject?: string) => void} */
+  const report = (rule, file, message, subject) => { violations.push({ rule: rule.name, file, message, subject }); };
+  /** @type {(result: Messages) => string[]} */
+  const messagesOf = result => !result ? [] : Array.isArray(result) ? result : [result];
+
+  for (const rule of rules) {
+    if (rule.on === "file") {
+      for (const file of rule.production ? production : files) {
+        for (const message of messagesOf(rule.check(file, project))) report(rule, file.path, message);
+      }
+    }
+    if (rule.on === "project") {
+      for (const { file, message } of rule.check(project)) report(rule, file, message);
+    }
+  }
+
+  const importRules = rules.filter(/** @returns {rule is Extract<Rule, { on: "import" }>} */ rule => rule.on === "import");
+  for (const file of production) {
+    const from = locate(file.path);
+    for (const specifier of file.imports) {
+      const { internal, target } = resolveImport(file.path, specifier, root);
+      /** @type {Import} */
+      const link = { file, from, to: internal ? locate(target) : { kind: "other" }, specifier, internal, target };
+      for (const rule of importRules) {
+        for (const message of messagesOf(rule.check(link))) report(rule, file.path, message, target);
+      }
+    }
+  }
+
+  return { production: production.length, tests: files.length - production.length, violations };
+}
+
+/**
+ * Each rule has its own kebab-case name, a description, reads an import, a file or the project, and has a check.
+ * @param {unknown} rules
+ * @returns {asserts rules is Rule[]}
+ */
+function checkRules(rules) {
+  if (!Array.isArray(rules)) throw new Error(`${RULES_FILE} must export a list of rules`);
+  /** @type {Set<string>} */
+  const seen = new Set();
+  for (const rule of /** @type {unknown[]} */ (rules)) {
+    const { name, description, on, check } = /** @type {Partial<Record<string, unknown>>} */ (rule ?? {});
+    const valid = typeof name === "string" && /^[a-z]+(-[a-z]+)*$/.test(name) && description && ["import", "file", "project"].includes(String(on)) && typeof check === "function";
+    if (!valid) throw new Error(`each rule has a kebab-case name, a description, reads an import, a file or the project ("on"), and has a check: ${typeof name === "string" ? name : JSON.stringify(rule)}`);
+    if (seen.has(name)) throw new Error(`two rules have the name ${name}`);
+    seen.add(name);
+  }
+}
+
+/** @type {(file: string) => Promise<unknown>} */
+const importFile = file => import(pathToFileURL(file).href);
+
+/** `caits architecture`: checks the rules of quality/architecture.mjs on the files of src/ and test/: the code, and the stylesheets (SCSS). */
+export async function run() {
+  const root = process.cwd();
+  if (!existsSync(join(root, RULES_FILE))) throw new Error(`${RULES_FILE} is missing: it gives the rules that \`caits architecture\` checks. Run \`npx caits init .\` to write it.`);
+  const { default: rules } = /** @type {{ default: Rule[] }} */ (await importFile(join(root, RULES_FILE)));
+  /** @type {(directory: string) => string[]} */
+  const walk = directory => !existsSync(directory) ? [] : readdirSync(directory).flatMap(name => {
+    const path = join(directory, name);
+    return statSync(path).isDirectory() ? walk(path) : [path];
+  });
+  const sources = [...walk(join(root, "src")), ...walk(join(root, "test"))]
+    .filter(path => /\.(ts|marko|scss)$/.test(path))
+    .map(absolute => ({ path: relative(root, absolute).replaceAll("\\", "/"), text: readFileSync(absolute, "utf8") }));
+  const { production, tests, violations } = checkArchitecture(root, sources, rules);
+
+  if (violations.length === 0) {
+    console.log(`Architecture: ${production} production files and ${tests} test files respect the ${rules.length} rules.`);
+    return 0;
+  }
+  for (const { rule, file, message, subject } of violations) console.error(`${file}${subject ? ` → ${subject}` : ""}: ${message} (${rule})`);
+  console.error(`\n${violations.length} architecture ${violations.length === 1 ? "violation" : "violations"}.`);
+  return 1;
+}