@starci/eslint-canon-fe 6.0.2 → 7.1.0

package/runtime/scripts/checks/architecture/config.mjs

@@ -0,0 +1,310 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { slash } from '../../lib/path-key.mjs';
+import { readJsonFile as readJson } from '../../lib/json.mjs';
+import { isInside } from '../common.mjs';
+import { openHfs } from '../../lib/hfs-slots.mjs';
+
+
+/** A file's identity: its resolved real path, or the resolved path when it does not exist. */
+function canonical(file) {
+  const absolute = path.resolve(file);
+  try { return path.resolve(fs.realpathSync(absolute)); } catch { return absolute; }
+}
+
+function exactKeys(value, allowed, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw Error(`${label} must be an object.`);
+  const unknown = Object.keys(value).filter(key => !allowed.has(key));
+  if (unknown.length) throw Error(`${label} has unsupported fields: ${unknown.sort().join(', ')}.`);
+}
+
+/**
+ * The git repository `root` sits in, found by walking up for a `.git` entry (a directory in a clone, a
+ * file in a worktree), or null when there is none. It is the outer boundary a `file:` dependency may
+ * resolve into: a checked project is routinely one package of a repository that also ships the packages
+ * it consumes, and `--root` is the project, not the repository.
+ */
+function enclosingRepository(root) {
+  let cursor = path.resolve(root);
+  for (;;) {
+    if (fs.existsSync(path.join(cursor, '.git'))) return cursor;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return null;
+    cursor = parent;
+  }
+}
+
+function existingPackageDirectory(absolute) {
+  try {
+    if (!fs.lstatSync(absolute).isDirectory()) return false;
+    const manifest = fs.lstatSync(path.join(absolute, 'package.json'));
+    return manifest.isFile() && !manifest.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function existingDirectory(root, relative) {
+  try {
+    return fs.lstatSync(path.join(root, relative)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function existingRegularFile(root, relative) {
+  try {
+    const stat = fs.lstatSync(path.join(root, ...relative.split('/')));
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function workspaceDirectories(root) {
+  const directories = new Set();
+  const queue = [root];
+  const visited = new Set();
+  const repository = enclosingRepository(root);
+  const admit = (candidate, label = 'local package', strict = false) => {
+    const absolute = path.resolve(candidate);
+    if (!isInside(root, absolute) || absolute === root || !existingDirectory(root, slash(path.relative(root, absolute)))) {
+      if (strict) throw Error(`${label} must resolve to a package directory inside the repository.`);
+      return;
+    }
+    const manifest = path.join(absolute, 'package.json');
+    try {
+      if (!fs.lstatSync(manifest).isFile() || fs.lstatSync(manifest).isSymbolicLink()) {
+        if (strict) throw Error(`${label} must resolve to a regular package.json inside the repository.`);
+        return;
+      }
+    } catch (error) {
+      if (strict) throw Error(error.message.startsWith(label) ? error.message : `${label} must resolve to a regular package.json inside the repository.`);
+      return;
+    }
+    const relative = slash(path.relative(root, absolute));
+    if (!directories.has(relative)) { directories.add(relative); queue.push(absolute); }
+  };
+  while (queue.length) {
+    const packageRoot = queue.shift();
+    if (visited.has(packageRoot)) continue;
+    visited.add(packageRoot);
+    const pkg = readJson(path.join(packageRoot, 'package.json'));
+    const patterns = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
+    for (const pattern of Array.isArray(patterns) ? patterns : []) {
+      if (typeof pattern !== 'string' || !pattern.trim()) throw Error('package.json workspace entries must be non-empty paths.');
+      const normalized = slash(pattern.trim()).replace(/^\.\//, '');
+      const segments = normalized.split('/');
+      if (path.isAbsolute(normalized) || segments.some(segment => segment === '..' || (segment.includes('*') && segment !== '*'))) {
+        throw Error(`Unsupported local workspace pattern: ${normalized}.`);
+      }
+      let candidates = [packageRoot];
+      for (const segment of segments) {
+        const next = [];
+        for (const base of candidates) {
+          if (segment === '*') {
+            if (!fs.existsSync(base) || !fs.lstatSync(base).isDirectory()) continue;
+            next.push(...fs.readdirSync(base, { withFileTypes: true })
+              .filter(item => item.isDirectory())
+              .sort((a, b) => a.name.localeCompare(b.name))
+              .map(item => path.join(base, item.name)));
+          } else next.push(path.join(base, segment));
+        }
+        candidates = next;
+      }
+      if (!candidates.length) throw Error(`Workspace pattern matched no package directories: ${normalized}.`);
+      // npm expands a `*` segment to the directories that hold a package.json and skips the rest (an empty or untracked folder is
+      // HFS_EMPTY_DIR / HFS_SLOT_UNDECLARED, never a reason to analyse nothing); a literal workspace path must resolve.
+      const wildcard = segments.includes('*');
+      for (const candidate of candidates) admit(candidate, `workspace ${normalized}`, !wildcard);
+    }
+    for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+      for (const [name, value] of Object.entries(pkg?.[section] ?? {})) {
+        if (typeof value !== 'string' || !value.startsWith('file:')) continue;
+        const absolute = path.resolve(packageRoot, value.slice('file:'.length));
+        const label = `${section}.${name} file dependency`;
+        if (isInside(root, absolute)) { admit(absolute, label, true); continue; }
+        // A sibling package of the same repository: this project consumes it, so the path is real and
+        // resolvable, but it is not part of this project's own source layout and must not become one of
+        // its workspaces - collecting it would pull another package's src into these roots. Refusing it
+        // instead would fail the whole check closed over an ordinary monorepo shape.
+        if (!repository || !isInside(repository, absolute) || !existingPackageDirectory(absolute)) {
+          throw Error(`${label} must resolve to a package directory inside the repository.`);
+        }
+      }
+    }
+  }
+  return [...directories].sort();
+}
+
+function discoveredProjects(root, workspaces) {
+  const projects = [];
+  if (fs.existsSync(path.join(root, 'tsconfig.json'))) projects.push('tsconfig.json');
+  for (const workspace of workspaces) {
+    for (const name of ['tsconfig.json', 'tsconfig.app.json', 'tsconfig.build.json']) {
+      const candidate = `${workspace}/${name}`;
+      if (fs.existsSync(path.join(root, ...candidate.split('/')))) {
+        projects.push(candidate);
+        break;
+      }
+    }
+  }
+  return [...new Set(projects)];
+}
+
+function inferredLayout(root, workspaces) {
+  // HFS: frontend source roots live only under workspace packages (apps/<app>/, packages/<pkg>/);
+  // the repository root itself is never a frontend source root.
+  // The route, feature, component, hook and module roles are app slots (fe.route, fe.feature, fe.components, fe.hooks, fe.modules:
+  // apps/<app>/src/...); a workspace package is tier `package` and holds none of them - its own src/hooks is package source, and a
+  // grammar package's tier folders make it a component root below.
+  const appWorkspaces = workspaces.filter(prefix => prefix.startsWith('apps/'));
+  const collect = suffix => appWorkspaces.map(prefix => `${prefix}/${suffix}`).filter(relative => existingDirectory(root, relative));
+  // A design-system workspace whose src carries tier dirs (leaves/branches/…) IS a component root;
+  // collecting its src/components too would nest two roots in one role and fail the disjoint check.
+  const tierSources = new Set(workspaces.map(prefix => `${prefix}/src`)
+    .filter(source => ['leaves', 'branches', 'blocks', 'overlays', 'composites', 'layouts', 'product-shells', 'pages']
+      .some(tier => existingDirectory(root, `${source}/${tier}`))));
+  const components = collect('src/components')
+    .filter(relative => !tierSources.has(path.posix.dirname(relative)));
+  components.push(...tierSources);
+  return {
+    routes: collect('src/app'),
+    features: collect('src/features'),
+    components: [...new Set(components)],
+    hooks: collect('src/hooks'),
+    modules: collect('src/modules'),
+    transport: collect('src/modules/api'),
+  };
+}
+
+function assertFrontendRolesDisjoint(root, frontend) {
+  const roles = ['routes', 'features', 'components', 'hooks', 'modules'];
+  const entries = roles.flatMap(role => frontend[role].map(relative => ({
+    role,
+    relative,
+    absolute: path.join(root, ...relative.split('/')),
+  })));
+  for (let index = 0; index < entries.length; index += 1) for (let other = index + 1; other < entries.length; other += 1) {
+    const left = entries[index];
+    const right = entries[other];
+    if (isInside(left.absolute, right.absolute) || isInside(right.absolute, left.absolute)) {
+      throw Error(`Architecture frontend role roots must be disjoint; ${left.role} ${left.relative} overlaps ${right.role} ${right.relative}.`);
+    }
+  }
+}
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', 'coverage', 'test-results', '.starciwork', '.starcistacks']);
+
+function directoriesUnder(root, relative, depth) {
+  const out = [];
+  const visit = (dir, left) => {
+    let entries;
+    try { entries = fs.readdirSync(path.join(root, ...dir.split('/').filter(Boolean)), { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIPPED_DIRECTORIES.has(entry.name)) continue;
+      const child = dir ? `${dir}/${entry.name}` : entry.name;
+      out.push(child);
+      if (left > 1) visit(child, left - 1);
+    }
+  };
+  visit(relative, depth);
+  return out;
+}
+
+/** The owner entry a slot instance exposes: index.ts/index.tsx, a package's src/index.ts, an app's app.module.ts. */
+function ownerEntry(root, ownerRoot, tier) {
+  const candidates = tier === 'package' ? ['src/index.ts', 'src/index.tsx', 'index.ts', 'index.tsx']
+    : tier === 'app' ? ['app.module.ts'] : ['index.ts', 'index.tsx'];
+  for (const candidate of candidates) {
+    const relative = `${ownerRoot}/${candidate}`;
+    if (existingRegularFile(root, relative)) return relative;
+  }
+  return null;
+}
+
+/**
+ * Owners are derived from the slot manifest: every directory that an `owner: true` slot matches, with its entry file.
+ * An instance with no entry file is not listed: the required-files check reports the missing entry.
+ */
+function derivedOwners(root, resolver) {
+  const seen = new Map();
+  for (const directory of directoriesUnder(root, '', 6)) {
+    const owner = resolver.ownerOf(directory);
+    if (!owner || owner.root !== directory || seen.has(owner.root)) continue;
+    const slot = resolver.slot(owner.slot);
+    const entry = ownerEntry(root, owner.root, slot.tier);
+    if (entry) seen.set(owner.root, { id: `${owner.slot}:${owner.root}`, root: owner.root, entry, slot: owner.slot, tier: slot.tier });
+  }
+  return [...seen.values()].sort((a, b) => a.root.localeCompare(b.root));
+}
+
+const DECLARED_HANDLER_DECORATORS = ['CommandHandler', 'QueryHandler'];
+
+const GRAMMAR_PACKAGE = '@starci/grammar';
+
+/**
+ * The Grammar contract of a frontend repository, derived rather than declared: every app's globals.css is a style
+ * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
+ * a globals.css to judge (the contract is then reported unavailable, never passed).
+ */
+function derivedGrammar(root, apps, workspaces) {
+  const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
+  if (!styleSources.length) return null;
+  const consumerManifests = apps.map(app => `apps/${app.name}/package.json`).filter(relative => existingRegularFile(root, relative));
+  for (const workspace of workspaces) {
+    if (!workspace.startsWith('packages/')) continue;
+    const manifest = `${workspace}/package.json`;
+    const pkg = readJson(path.join(root, ...manifest.split('/')));
+    if (pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE))) consumerManifests.push(manifest);
+  }
+  if (!consumerManifests.length) return null;
+  return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react'] };
+}
+
+/**
+ * Resolve the layout contract from hfs.json and the slot manifest (knowledge/hfs/slots.yaml). architecture.json is
+ * retired: a repository carries only hfs.json. Owners, roots and the tier of every path come from slots; the contract
+ * has no ignore, waiver or baseline field.
+ */
+export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
+  const root = fs.realpathSync(path.resolve(repositoryRoot));
+  if (!fs.lstatSync(root).isDirectory()) throw Error('Repository root must be a directory.');
+  const opened = hfs ?? openHfs({ repoRoot: root });
+  const { profile, apps } = opened.repo;
+  const workspaces = workspaceDirectories(root);
+  const inferred = inferredLayout(root, [...new Set([...workspaces, ...apps.map(app => `apps/${app.name}`)])].sort());
+  const kinds = [profile === 'be' ? 'backend' : 'frontend'];
+  const projects = discoveredProjects(root, workspaces);
+  if (!projects.length) throw Error('The repository has no tsconfig.json to derive a TypeScript project from.');
+  const backend = {
+    modules: ['src/modules'],
+    features: ['src/features'],
+    apps: ['apps'],
+    moduleRegistration: { providerIdentity: 'exported-class-token', handlerDecorators: [...DECLARED_HANDLER_DECORATORS] },
+  };
+  const frontend = {
+    routes: inferred.routes,
+    features: inferred.features,
+    components: inferred.components,
+    hooks: inferred.hooks,
+    modules: inferred.modules,
+    transport: inferred.transport,
+    grammar: profile === 'fe' ? derivedGrammar(root, apps, workspaces) : null,
+  };
+  if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
+  return {
+    root,
+    repository: enclosingRepository(root),
+    kinds,
+    projects,
+    workspaces,
+    apps: apps.map(app => ({ name: app.name, kind: app.kind })),
+    hfs: opened,
+    owners: derivedOwners(root, opened),
+    backend,
+    frontend,
+  };
+}
+
+export { canonical, enclosingRepository, exactKeys, isInside, slash };

package/runtime/scripts/checks/architecture/connection-map.mjs

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
+
+/**
+ * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one
+ * `Inject<Conn>EntityManager()` injector, one config; the `hfs.json` connections, the connection files, the injectors, the
+ * database module registration of every app and the env of every stack correspond one to one.
+ *
+ *   - per declared connection `<name>`: `src/modules/platform/database/<name>.connection.ts` exports
+ *     `<NAME>_CONNECTION = "<name>"`, `<name>.decorators.ts` exports `Inject<Pascal>EntityManager`, `<name>.config.ts`
+ *     exists and reads only `<ENVPREFIX>_*` keys;
+ *   - a connection file for a name hfs.json does not declare is refused;
+ *   - `getEntityManagerToken(` and `InjectEntityManager(` (from @nestjs/typeorm) resolve their argument through the
+ *     checker to a connection name and may be called only in that connection's decorators file, once; the DataSource
+ *     forms only in platform/database, the migrate app and the test fixtures; an exported `Inject*EntityManager`
+ *     anywhere else (a capability-specific injector, a duplicate) is refused;
+ *   - inside one app every connection is passed to the platform/database module registration once;
+ *   - in every `.starcistacks/<env>/runtime/env` two connections whose `<PREFIX>_HOST`, `<PREFIX>_PORT` and
+ *     `<PREFIX>_NAME` (or `_DATABASE`, whichever the config reads) resolve to one triple are the same database.
+ */
+export const CONNECTION_RULE_IDS = ['BE_CONNECTION_DUPLICATE'];
+
+const RULE = 'BE_CONNECTION_DUPLICATE';
+export const DATABASE_DIR = 'src/modules/platform/database';
+const TYPEORM = '@nestjs/typeorm';
+const MANAGER_CALLS = new Set(['getEntityManagerToken', 'InjectEntityManager']);
+const SOURCE_CALLS = new Set(['getDataSourceToken', 'InjectDataSource']);
+const ENV_KEY = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/u;
+const INJECTOR_NAME = /^Inject[A-Za-z0-9]*EntityManager$/u;
+
+function readEnvFiles(target) {
+  const merged = new Map();
+  const readFile = file => {
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); } catch { return; }
+    for (const raw of text.split(/\r?\n/u)) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/u.exec(line);
+      if (!match) continue;
+      let value = match[2].trim();
+      if (/^(['"]).*\1$/u.test(value)) value = value.slice(1, -1);
+      merged.set(match[1], value.trim());
+    }
+  };
+  let stat;
+  try { stat = fs.statSync(target); } catch { return null; }
+  if (stat.isFile()) readFile(target);
+  else for (const entry of fs.readdirSync(target, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isFile() && !entry.name.toLowerCase().endsWith('.md')) readFile(path.join(target, entry.name));
+  }
+  return merged;
+}
+
+export function checkConnectionMap(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const declared = config.hfs.repo.connections ?? [];
+  const byName = new Map(declared.map(connection => [connection.name, connection]));
+  const violations = [];
+  const report = (rel, message, extra = {}) => violations.push({ ruleId: RULE, path: rel, message, ...extra });
+  const decoratorsFile = name => `${DATABASE_DIR}/${name}.decorators.ts`;
+  const databaseFiles = [...graph.files.values()].filter(file => file.rel.startsWith(`${DATABASE_DIR}/`));
+
+  // 1. The three files of each declared connection, and no file of an undeclared one.
+  for (const connection of declared) {
+    const connectionRel = `${DATABASE_DIR}/${connection.name}.connection.ts`;
+    const constant = `${upperSnake(connection.name)}_CONNECTION`;
+    const connectionFile = kit.graphFile(connectionRel);
+    if (!connectionFile) report(connectionRel, `hfs.json declares connection ${connection.name} but ${connectionRel} does not exist; declare \`export const ${constant} = "${connection.name}"\` there.`, { connection: connection.name });
+    else {
+      const checker = kit.checkerOf(connectionFile.sourceFile);
+      const statement = connectionFile.sourceFile.statements.find(item => ts.isVariableStatement(item) && kit.isExported(item)
+        && item.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === constant));
+      const initializer = statement?.declarationList.declarations.find(declaration => declaration.name.text === constant)?.initializer;
+      if (!statement || kit.stringValue(checker, initializer) !== connection.name) {
+        report(connectionRel, `${connectionRel} must export \`${constant} = "${connection.name}"\` (the connection name declared in hfs.json).`, { connection: connection.name });
+      }
+    }
+    const decorators = kit.graphFile(decoratorsFile(connection.name));
+    const injector = `Inject${pascal(connection.name)}EntityManager`;
+    const exported = decorators?.sourceFile.statements.some(item => (ts.isVariableStatement(item) && kit.isExported(item)
+      && item.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === injector))
+      || (ts.isFunctionDeclaration(item) && kit.isExported(item) && item.name?.text === injector));
+    if (!exported) report(decoratorsFile(connection.name), `Connection ${connection.name} needs ${decoratorsFile(connection.name)} exporting ${injector}, the one injector of its shared EntityManager.`, { connection: connection.name });
+    const configRel = `${DATABASE_DIR}/${connection.name}.config.ts`;
+    const configFile = kit.graphFile(configRel);
+    if (!configFile) {
+      report(configRel, `Connection ${connection.name} needs ${configRel}, the one place its ${connection.envPrefix}_* keys are read.`, { connection: connection.name });
+      continue;
+    }
+    kit.walk(configFile.sourceFile, node => {
+      let key = null;
+      if (ts.isStringLiteralLike(node) && ENV_KEY.test(node.text)) key = node.text;
+      else if (ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'env'
+        && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process' && ENV_KEY.test(node.name.text)) key = node.name.text;
+      if (key === null) return true;
+      const own = key.startsWith(`${connection.envPrefix}_`);
+      const foreign = declared.find(other => other !== connection && key.startsWith(`${other.envPrefix}_`));
+      if (!own || foreign) {
+        report(configRel, `${configRel} reads ${key}; the config of connection ${connection.name} reads only ${connection.envPrefix}_* keys.`, { ...kit.at(configRel, configFile.sourceFile, node), connection: connection.name });
+      }
+      return false;
+    });
+  }
+  for (const file of databaseFiles) {
+    const match = /^(.+)\.(connection|decorators|config)\.ts$/u.exec(path.posix.basename(file.rel));
+    if (match && path.posix.dirname(file.rel) === DATABASE_DIR && !byName.has(match[1])) {
+      report(file.rel, `${file.rel} belongs to connection ${match[1]}, which hfs.json does not declare; declare the database in hfs.json connections or delete the file.`, { connection: match[1] });
+    }
+  }
+
+  // 2. Every entity manager token and injector in the program: one home per connection.
+  const perDecorators = new Map();
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    const slotIs = id => file.slot === id;
+    kit.walk(file.sourceFile, node => {
+      if (ts.isCallExpression(node)) {
+        const binding = kit.importBinding(checker, node.expression);
+        if (binding?.module === TYPEORM && MANAGER_CALLS.has(binding.name)) {
+          const value = kit.stringValue(checker, node.arguments[0]);
+          const home = value === null ? null : decoratorsFile(value);
+          if (value === null || !byName.has(value)) {
+            report(file.rel, `${binding.name}() names ${value === null ? 'a connection that cannot be resolved to a constant' : `connection ${value}, which hfs.json does not declare`}; only the declared connections have an entity manager token.`, kit.at(file.rel, file.sourceFile, node));
+          } else if (file.rel !== home) {
+            report(file.rel, `${binding.name}(${value}) belongs in ${home} only; inject the shared manager with Inject${pascal(value)}EntityManager() instead of a second path to connection ${value}.`, { ...kit.at(file.rel, file.sourceFile, node), connection: value });
+          } else {
+            perDecorators.set(value, (perDecorators.get(value) ?? 0) + 1);
+            if (perDecorators.get(value) > 1) report(file.rel, `${home} resolves connection ${value} more than once; one connection has one injector.`, { ...kit.at(file.rel, file.sourceFile, node), connection: value });
+          }
+        } else if (binding?.module === TYPEORM && SOURCE_CALLS.has(binding.name)) {
+          const allowed = file.rel.startsWith(`${DATABASE_DIR}/`) || slotIs('be.app.migrate') || slotIs('be.tests.fixtures');
+          if (!allowed) report(file.rel, `${binding.name}() reaches the DataSource outside platform/database and the migrate app; inject the shared EntityManager of the connection instead.`, kit.at(file.rel, file.sourceFile, node));
+        }
+      }
+      const exportedName = (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && ts.isVariableStatement(node.parent?.parent) && kit.isExported(node.parent.parent)) ? node.name.text
+        : (ts.isFunctionDeclaration(node) && kit.isExported(node) && node.name ? node.name.text : null);
+      if (exportedName && INJECTOR_NAME.test(exportedName)) {
+        const home = [...byName.keys()].find(name => `Inject${pascal(name)}EntityManager` === exportedName);
+        if (!home || file.rel !== decoratorsFile(home)) {
+          report(file.rel, `${exportedName} is exported here, but the only injector of an entity manager is Inject<Conn>EntityManager in src/modules/platform/database/<conn>.decorators.ts, one per declared connection.`, kit.at(file.rel, file.sourceFile, node));
+        }
+      }
+      return true;
+    });
+  }
+
+  // 3. Each connection is passed to the database module registration once per app.
+  let registrations = 0;
+  for (const app of config.apps) {
+    const root = kit.appRoot(app.name);
+    if (!root) continue;
+    const checker = kit.checkerOf(root.sourceFile);
+    const passed = new Map();
+    kit.walk(root.sourceFile, node => {
+      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register')) return true;
+      const owner = kit.declarationsOf(checker, node.expression.expression).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!owner || owner.tier !== 'platform' || owner.name !== 'database') return true;
+      registrations += 1;
+      for (const argument of node.arguments) {
+        kit.walk(argument, inner => {
+          if (ts.isPropertyAssignment(inner.parent ?? {}) && inner.parent.name === inner) return true;
+          if (ts.isPropertyAccessExpression(inner.parent ?? {}) && inner.parent.name === inner) return true;
+          if (!(ts.isIdentifier(inner) || ts.isStringLiteralLike(inner) || ts.isPropertyAccessExpression(inner))) return true;
+          const value = kit.stringValue(checker, inner);
+          if (value === null || !byName.has(value)) return true;
+          passed.set(value, (passed.get(value) ?? 0) + 1);
+          if (passed.get(value) > 1) report(root.rel, `App ${app.name} passes connection ${value} to the database module registration more than once; one connection is registered once per app.`, { ...kit.at(root.rel, root.sourceFile, inner), connection: value, app: app.name });
+          return false;
+        });
+      }
+      return true;
+    });
+  }
+
+  // 4. Stacks: two connections that resolve to one host, port and database are one database.
+  let stacksChecked = 0;
+  let stacksSkipped = 0;
+  const stacksRoot = path.join(config.root, '.starcistacks');
+  let envs = [];
+  try { envs = fs.readdirSync(stacksRoot, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name).sort(); } catch { envs = []; }
+  for (const env of envs) {
+    const rel = `.starcistacks/${env}/runtime/env`;
+    const values = readEnvFiles(path.join(stacksRoot, env, 'runtime', 'env'));
+    if (!values || values.size === 0) { stacksSkipped += 1; continue; }
+    const seen = new Map();
+    let resolved = 0;
+    for (const connection of declared) {
+      const configFile = kit.graphFile(`${DATABASE_DIR}/${connection.name}.config.ts`);
+      const nameKey = configFile?.sourceFile.text.includes(`${connection.envPrefix}_DATABASE`) ? `${connection.envPrefix}_DATABASE` : `${connection.envPrefix}_NAME`;
+      const host = values.get(`${connection.envPrefix}_HOST`);
+      const port = values.get(`${connection.envPrefix}_PORT`);
+      const database = values.get(nameKey);
+      if (!host || !port || !database) continue;
+      resolved += 1;
+      const triple = `${host.toLowerCase()}|${port}|${database}`;
+      if (seen.has(triple)) {
+        report(rel, `Connections ${seen.get(triple)} and ${connection.name} resolve to the same database (${host}:${port}/${database}) in stack ${env}; one physical database is one connection.`, { connection: connection.name, env });
+      } else seen.set(triple, connection.name);
+    }
+    if (resolved) stacksChecked += 1; else stacksSkipped += 1;
+  }
+
+  return { violations, coverage: { status: 'checked', connections: declared.length, registrations, stacksChecked, stacksSkipped } };
+}

package/runtime/scripts/checks/architecture/constructor-deps.mjs

@@ -0,0 +1,100 @@
+import path from 'node:path';
+
+/**
+ * The constructor dependencies of a service, read the way the injection law (R85) writes them, shared by the unit-spec
+ * provider check (R48 `unit-spec-providers`) and the token export check (R85 `injection-token-exported`).
+ *
+ * A constructor parameter is one of
+ *   - `token`: decorated with a custom `Inject<Thing>()` decorator. The decorator is declared in a `<cap>.decorators.ts`
+ *     as `injector<T>(TOKEN)`; the dependency is the TOKEN it names, identified by the name the token is exported under
+ *     (the declaration's own name), never by the decorator's or the parameter's name. A raw `@Inject(TOKEN)` is read the same way.
+ *   - `class`: no injection decorator and a class type; the dependency is that class.
+ *   - `unresolved`: anything else (a token expression that is not a plain identifier, a decorator the reader cannot follow,
+ *     a type that is not a class).
+ */
+const INJECT_NAME = /^Inject(?:[A-Z][A-Za-z0-9]*)?$/u;
+
+/** The identifier a decorator names: `@InjectFoo()` -> InjectFoo, `@Inject(TOKEN)` -> Inject; null for a non-identifier decorator. */
+function decoratorCallee(ts, decorator) {
+  const expression = decorator.expression;
+  const callee = ts.isCallExpression(expression) ? expression.expression : expression;
+  return ts.isIdentifier(callee) ? { callee, call: ts.isCallExpression(expression) ? expression : null } : null;
+}
+
+/** The token a `injector(<arg>)` call names, judged where the argument is declared. */
+function tokenOfArgument(kit, checker, argument) {
+  const { ts } = kit;
+  if (!argument || !ts.isIdentifier(argument)) return { kind: 'unresolved', reason: 'its token is not a plain identifier of an exported const', node: argument ?? null };
+  const declaration = kit.declarationsOf(checker, argument).find(item => ts.isVariableDeclaration(item) || ts.isBindingElement(item));
+  if (declaration) {
+    const name = ts.isIdentifier(declaration.name) ? declaration.name.text : argument.text;
+    return { kind: 'token', name, declaration, argument, external: false };
+  }
+  const binding = kit.importBinding(checker, argument);
+  if (binding && !binding.module.startsWith('.')) return { kind: 'token', name: binding.name, declaration: null, argument, external: true };
+  return { kind: 'unresolved', reason: `the token ${argument.text} does not resolve to a declaration`, node: argument };
+}
+
+/** The injector token of a custom `Inject<Thing>()` decorator, or an unresolved reason. */
+function tokenOfInjectDecorator(kit, checker, parameter, decorator) {
+  const { ts } = kit;
+  const head = decoratorCallee(ts, decorator);
+  if (!head || !INJECT_NAME.test(head.callee.text)) return null;
+  if (head.callee.text === 'Inject' && head.call?.arguments.length) return { ...tokenOfArgument(kit, checker, head.call.arguments[0]), decorator: head.callee.text, decoratorDeclaration: null, decoratorFile: null };
+  const declaration = kit.declarationsOf(checker, head.callee).find(item => ts.isVariableDeclaration(item) || ts.isFunctionDeclaration(item));
+  if (!declaration) return { kind: 'unresolved', reason: `${head.callee.text}() does not resolve to a declaration`, node: parameter, decorator: head.callee.text };
+  let injectorCall = null;
+  kit.walk(declaration, node => {
+    if (injectorCall) return false;
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const declarationChecker = kit.checkerOf(declaration.getSourceFile());
+      const binding = kit.importBinding(declarationChecker, node.expression);
+      if ((binding?.name ?? node.expression.text) === 'injector') injectorCall = node;
+    }
+    return true;
+  });
+  if (!injectorCall) return { kind: 'unresolved', reason: `${head.callee.text}() is not built with injector<T>(TOKEN)`, node: parameter, decorator: head.callee.text };
+  const declarationChecker = kit.checkerOf(declaration.getSourceFile());
+  return { ...tokenOfArgument(kit, declarationChecker, injectorCall.arguments[0]), decorator: head.callee.text, decoratorDeclaration: declaration, injectorCall };
+}
+
+/** The class a parameter type names, judged where the type is declared; null when it is not a class type. */
+function classOfType(kit, checker, type) {
+  const { ts } = kit;
+  if (!type || !ts.isTypeReferenceNode(type) || !ts.isIdentifier(type.typeName)) return null;
+  const declarations = kit.declarationsOf(checker, type.typeName);
+  const declared = declarations.find(item => ts.isClassDeclaration(item) && item.name);
+  if (declared) return declared.name.text;
+  if (declarations.length) return null;
+  const binding = kit.importBinding(checker, type.typeName);
+  return binding && binding.name !== 'default' && binding.name !== '*' ? binding.name : null;
+}
+
+/** The dependencies of one class, in constructor order: [{kind, name?, node, parameter, ...}]. */
+export function constructorDependencies(kit, file, classDeclaration) {
+  const { ts } = kit;
+  const checker = kit.checkerOf(file.sourceFile);
+  const constructor = classDeclaration.members.find(member => ts.isConstructorDeclaration(member) && member.body !== undefined)
+    ?? classDeclaration.members.find(member => ts.isConstructorDeclaration(member));
+  if (!constructor) return [];
+  return constructor.parameters.map(parameter => {
+    for (const decorator of kit.decorators(parameter)) {
+      const token = tokenOfInjectDecorator(kit, checker, parameter, decorator);
+      if (token) return { ...token, parameter, node: token.node ?? parameter };
+    }
+    const name = classOfType(kit, checker, parameter.type);
+    if (name) return { kind: 'class', name, parameter, node: parameter };
+    return { kind: 'unresolved', reason: 'it has no Inject<Thing>() decorator and its type is not a class', parameter, node: parameter };
+  });
+}
+
+/** Every service class of the program: [{file, declaration}] for each class of a `*.service.ts` file. */
+export function serviceClasses(kit, graph) {
+  const { ts } = kit;
+  const found = [];
+  for (const file of graph.files.values()) {
+    if (!path.posix.basename(file.rel).endsWith('.service.ts')) continue;
+    for (const statement of file.sourceFile.statements) if (ts.isClassDeclaration(statement) && statement.name) found.push({ file, declaration: statement });
+  }
+  return found;
+}