@starci/hfs 4.0.10 → 4.2.0

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

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
 import { locateDeclaration } from '../slots.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one
@@ -33,191 +34,282 @@ 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;
 
+const exportedInjectorName = (ts, kit, node) => {
+  if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && ts.isVariableStatement(node.parent?.parent) && kit.isExported(node.parent.parent)) return node.name.text;
+  if (ts.isFunctionDeclaration(node) && kit.isExported(node) && node.name) return node.name.text;
+  return null;
+};
+
+const ENV_ASSIGNMENT = /^(?:export\s+)?([A-Za-z_]\w*)\s*=/u;
+const LINE_BREAK = /[\n\r\u2028\u2029]/u;
+
+// One `KEY=value` line: a value holding a line break after its first character is not an assignment.
+function parseEnvLine(raw) {
+  const line = raw.trim();
+  if (!line || line.startsWith('#')) return null;
+  const match = ENV_ASSIGNMENT.exec(line);
+  if (!match) return null;
+  let value = line.slice(match[0].length).trim();
+  if (LINE_BREAK.test(value)) return null;
+  if (/^(['"]).*\1$/u.test(value)) value = value.slice(1, -1);
+  return [match[1], value.trim()];
+}
+
+function readEnvFile(file, merged) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return; }
+  for (const raw of text.split(/\r?\n/u)) {
+    const parsed = parseEnvLine(raw);
+    if (parsed) merged.set(parsed[0], parsed[1]);
+  }
+}
+
 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);
+  if (stat.isFile()) readEnvFile(target, merged);
   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));
+    if (entry.isFile() && !entry.name.toLowerCase().endsWith('.md')) readEnvFile(path.join(target, entry.name), merged);
   }
   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}/`));
+const exportsVariable = (ts, kit, item, name) => ts.isVariableStatement(item) && kit.isExported(item)
+  && item.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name);
 
-  // 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 checkConnectionFile = (connection, kit, ts, report) => {
+  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 });
+    return;
+  }
+  const checker = kit.checkerOf(connectionFile.sourceFile);
+  const statement = connectionFile.sourceFile.statements.find(item => exportsVariable(ts, kit, item, 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 checkInjectorFile = (connection, kit, ts, report, decoratorsFile) => {
+  const decorators = kit.graphFile(decoratorsFile(connection.name));
+  const injector = `Inject${pascal(connection.name)}EntityManager`;
+  const exported = decorators?.sourceFile.statements.some(item => exportsVariable(ts, kit, item, 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 isProcessEnvAccess = (ts, node) => ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'env'
+  && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process';
+
+const configEnvKey = (ts, node) => {
+  if (ts.isStringLiteralLike(node) && ENV_KEY.test(node.text)) return node.text;
+  if (isProcessEnvAccess(ts, node) && ENV_KEY.test(node.name.text)) return node.name.text;
+  return null;
+};
+
+const checkConfigFile = (connection, declared, kit, ts, report, configRel, configFile) => {
+  let readsSchema = false;
+  kit.walk(configFile.sourceFile, node => {
+    const key = configEnvKey(ts, node);
+    if (key === null) return true;
+    if (key === `${connection.envPrefix}_SCHEMA`) readsSchema = true;
+    const own = key.startsWith(`${connection.envPrefix}_`);
+    const foreign = declared.some(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 });
     }
-    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 });
+    return false;
+  });
+  if (connection.isolation === 'schema' && !readsSchema) report(configRel, `Connection ${connection.name} is isolated as a schema of a shared database (hfs.json isolation), so ${configRel} must read ${connection.envPrefix}_SCHEMA and hand it to the data source; splitting the context out into its own database is then an env change only.`, { connection: connection.name });
+};
+
+const checkDeclaredConnections = (declared, kit, ts, report, decoratorsFile) => {
+  for (const connection of declared) {
+    checkConnectionFile(connection, kit, ts, report);
+    checkInjectorFile(connection, kit, ts, report, decoratorsFile);
     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;
     }
-    let readsSchema = false;
-    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;
-      if (key === `${connection.envPrefix}_SCHEMA`) readsSchema = 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;
-    });
-    if (connection.isolation === 'schema' && !readsSchema) report(configRel, `Connection ${connection.name} is isolated as a schema of a shared database (hfs.json isolation), so ${configRel} must read ${connection.envPrefix}_SCHEMA and hand it to the data source; splitting the context out into its own database is then an env change only.`, { connection: connection.name });
+    checkConfigFile(connection, declared, kit, ts, report, configRel, configFile);
   }
+};
+
+const reportUndeclaredDatabaseFiles = (databaseFiles, byName, report) => {
   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 inspectManagerToken = (file, checker, node, binding, state) => {
+  const { kit, byName, decoratorsFile, report, perDecorators } = state;
+  const value = kit.stringValue(checker, node.arguments[0]);
+  const home = value === null ? null : decoratorsFile(value);
+  if (value === null || !byName.has(value)) {
+    const target = value === null ? 'a connection that cannot be resolved to a constant' : `connection ${value}, which hfs.json does not declare`;
+    report(file.rel, `${binding.name}() names ${target}; 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 });
+  }
+};
+
+const inspectDataSourceCall = (file, node, binding, state) => {
+  const allowed = file.rel.startsWith(`${DATABASE_DIR}/`) || state.slotIs(file, 'be.app.cli') || state.slotIs(file, 'be.cli') || state.slotIs(file, 'be.tests.fixtures');
+  if (!allowed) state.report(file.rel, `${binding.name}() reaches the DataSource outside platform/database and the cli; inject the shared EntityManager of the connection instead.`, state.kit.at(file.rel, file.sourceFile, node));
+};
+
+const inspectTypeormCall = (file, checker, node, state) => {
+  const binding = state.kit.importBinding(checker, node.expression);
+  if (binding?.module === TYPEORM && MANAGER_CALLS.has(binding.name)) inspectManagerToken(file, checker, node, binding, state);
+  else if (binding?.module === TYPEORM && SOURCE_CALLS.has(binding.name)) inspectDataSourceCall(file, node, binding, state);
+};
+
+const inspectInjectorExport = (file, node, state) => {
+  const { ts, kit, byName, decoratorsFile, report } = state;
+  const exportedName = exportedInjectorName(ts, kit, node);
+  if (!exportedName || !INJECTOR_NAME.test(exportedName)) return;
+  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));
+  }
+};
+
+const inspectManagerNode = (file, checker, node, state) => {
+  if (state.ts.isCallExpression(node)) inspectTypeormCall(file, checker, node, state);
+  inspectInjectorExport(file, node, state);
+  return true;
+};
+
+const checkManagerCalls = (graph, state) => {
   const perDecorators = new Map();
+  const walkState = { ...state, perDecorators, slotIs: (file, id) => file.slot === id };
   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.cli') || slotIs('be.cli') || slotIs('be.tests.fixtures');
-          if (!allowed) report(file.rel, `${binding.name}() reaches the DataSource outside platform/database and the cli; 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;
-    });
+    const checker = state.kit.checkerOf(file.sourceFile);
+    state.kit.walk(file.sourceFile, node => inspectManagerNode(file, checker, node, walkState));
   }
+};
+
+/** The receiver of a `<receiver>.register(...)` call that `node` is, or null. */
+const registerReceiver = (ts, node) => {
+  if (!ts.isCallExpression(node)) return null;
+  const callee = node.expression;
+  return ts.isPropertyAccessExpression(callee) && callee.name.text === 'register' ? callee.expression : null;
+};
+
+const isPropertyName = (ts, node) => (ts.isPropertyAssignment(node.parent ?? {}) || ts.isPropertyAccessExpression(node.parent ?? {})) && node.parent.name === node;
+
+const passConnections = (argument, scope) => {
+  const { ts, kit, checker, byName, passed, root, app, report } = scope;
+  kit.walk(argument, inner => {
+    if (isPropertyName(ts, 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;
+  });
+};
 
-  // 3. Each connection is passed to the database module registration once per app.
+const checkAppRegistrations = (config, kit, ts, byName, report) => {
   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();
+    const scope = { ts, kit, checker, byName, passed: new Map(), root, app, report };
     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;
+      const receiver = registerReceiver(ts, node);
+      if (!receiver) return;
+      const owner = kit.declarationsOf(checker, receiver).map(kit.ownerOfDeclaration).find(Boolean);
+      if (owner?.tier !== 'platform' || owner.name !== 'database') return;
       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;
+      for (const argument of node.arguments) passConnections(argument, scope);
     });
   }
+  return registrations;
+};
+
+const listStackEnvs = stacksRoot => {
+  try { return fs.readdirSync(stacksRoot, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name).sort(byCodeUnit); } catch { return []; }
+};
+
+// The resolved database of one connection in one stack env, or null while its host, port or name is unset.
+const resolveStackConnection = (kit, connection, values) => {
+  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) return null;
+  const schema = connection.isolation === 'schema' ? (values.get(`${connection.envPrefix}_SCHEMA`) ?? '') : null;
+  return { host, port, database, triple: `${host.toLowerCase()}|${port}|${database}`, schema };
+};
+
+// True when the env resolves at least one connection; false when it is skipped.
+const checkStackEnv = (config, kit, declared, report, stacksRoot, env) => {
+  // Relative to the side folder the machine judges (`../.starcistacks/...` for a side): the app-relative path once the side is prefixed.
+  const rel = path.relative(config.root, path.join(stacksRoot, env, 'runtime', 'env')).split(path.sep).join('/');
+  const values = readEnvFiles(path.join(stacksRoot, env, 'runtime', 'env'));
+  if (!values || values.size === 0) return false;
+  const seen = new Map(); // host|port|database -> [{name, isolation, schema}]
+  let resolved = 0;
+  for (const connection of declared) {
+    const found = resolveStackConnection(kit, connection, values);
+    if (!found) continue;
+    resolved += 1;
+    const { host, port, database, triple, schema } = found;
+    const sharing = seen.get(triple) ?? [];
+    // Two contexts may share one database only as distinct, named schemas; a context that is its own database shares it with nobody.
+    const clash = sharing.find(other => schema === null || other.schema === null || other.schema === schema);
+    if (clash) {
+      const schemaDetail = schema !== null && clash.schema === schema ? `, schema ${schema || '(none)'}` : '';
+      report(rel, `Connections ${clash.name} and ${connection.name} resolve to the same database (${host}:${port}/${database}${schemaDetail}) in stack ${env}; contexts share a database only as distinct schemas (isolation schema, a different ${connection.envPrefix}_SCHEMA), otherwise one physical database is one connection.`, { connection: connection.name, env });
+    }
+    sharing.push({ name: connection.name, schema });
+    seen.set(triple, sharing);
+  }
+  return resolved > 0;
+};
 
-  // 4. Stacks: two connections that resolve to one host, port and database are one database.
+const checkStackConnections = (config, kit, declared, report) => {
   let stacksChecked = 0;
   let stacksSkipped = 0;
   // .starcistacks sits at the app root: the side folder the machine judges reads its app's tree (locateDeclaration).
   const stacksRoot = path.join(locateDeclaration(config.root).appRoot, '.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) {
-    // Relative to the side folder the machine judges (`../.starcistacks/...` for a side): the app-relative path once the side is prefixed.
-    const rel = path.relative(config.root, path.join(stacksRoot, env, 'runtime', 'env')).split(path.sep).join('/');
-    const values = readEnvFiles(path.join(stacksRoot, env, 'runtime', 'env'));
-    if (!values || values.size === 0) { stacksSkipped += 1; continue; }
-    const seen = new Map(); // host|port|database -> [{name, isolation, schema}]
-    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}`;
-      const schema = connection.isolation === 'schema' ? (values.get(`${connection.envPrefix}_SCHEMA`) ?? '') : null;
-      const sharing = seen.get(triple) ?? [];
-      // Two contexts may share one database only as distinct, named schemas; a context that is its own database shares it with nobody.
-      const clash = sharing.find(other => schema === null || other.schema === null || other.schema === schema);
-      if (clash) {
-        report(rel, `Connections ${clash.name} and ${connection.name} resolve to the same database (${host}:${port}/${database}${schema !== null && clash.schema === schema ? `, schema ${schema || '(none)'}` : ''}) in stack ${env}; contexts share a database only as distinct schemas (isolation schema, a different ${connection.envPrefix}_SCHEMA), otherwise one physical database is one connection.`, { connection: connection.name, env });
-      }
-      sharing.push({ name: connection.name, schema });
-      seen.set(triple, sharing);
-    }
-    if (resolved) stacksChecked += 1; else stacksSkipped += 1;
+  for (const env of listStackEnvs(stacksRoot)) {
+    if (checkStackEnv(config, kit, declared, report, stacksRoot, env)) stacksChecked += 1; else stacksSkipped += 1;
   }
+  return { stacksChecked, stacksSkipped };
+};
 
+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}/`));
+  const state = { config, graph, kit, ts, declared, byName, violations, report, decoratorsFile };
+  checkDeclaredConnections(declared, kit, ts, report, decoratorsFile);
+  reportUndeclaredDatabaseFiles(databaseFiles, byName, report);
+  checkManagerCalls(graph, state);
+  const registrations = checkAppRegistrations(config, kit, ts, byName, report);
+  const { stacksChecked, stacksSkipped } = checkStackConnections(config, kit, declared, report);
   return { violations, coverage: { status: 'checked', connections: declared.length, registrations, stacksChecked, stacksSkipped } };
 }

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

@@ -35,24 +35,30 @@ function tokenOfArgument(kit, checker, argument) {
   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) {
+/** The first `injector(...)` call under a decorator declaration, or null. */
+function injectorCallOf(kit, declaration) {
   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);
+      const binding = kit.importBinding(kit.checkerOf(declaration.getSourceFile()), node.expression);
       if ((binding?.name ?? node.expression.text) === 'injector') injectorCall = node;
     }
     return true;
   });
+  return injectorCall;
+}
+
+/** 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 };
+  const injectorCall = injectorCallOf(kit, declaration);
   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 };

package/runtime/scripts/hfs/architecture/context-coupling.mjs

@@ -19,12 +19,83 @@ const RULE = 'BE_CONTEXT_COUPLING';
 const TYPEORM = 'typeorm';
 const RELATIONS = new Set(['OneToOne', 'OneToMany', 'ManyToOne', 'ManyToMany']);
 // The table identifier after the SQL keyword REFERENCES, optionally schema-qualified and quoted.
-const REFERENCES = /\bREFERENCES\s+(?:"?[A-Za-z0-9_]+"?\s*\.\s*)?"?([A-Za-z0-9_]+)"?/giu;
+const REFERENCES = /\bREFERENCES\s+(?:"?\w+"?\s*\.\s*)?"?(\w+)"?/giu;
+
+const checkCrossContextImports = (graph, model, covered, counts, once) => {
+  for (const edge of graph.edges) {
+    const from = graph.files.get(edge.from);
+    const to = graph.files.get(edge.to);
+    if (!from?.owner || !to?.owner || from.owner.root === to.owner.root) continue;
+    const fromContext = model.contextOfFile(edge.from);
+    const toContext = model.contextOfFile(edge.to);
+    if (!fromContext || !toContext || fromContext === toContext) continue;
+    counts.imports += 1;
+    if (covered.has(`${edge.from}|${to.owner.root}`)) continue;
+    once(`${edge.from}|${edge.to}|${edge.line}`, { path: edge.from, line: edge.line, column: edge.column, message: `${from.owner.root} (context ${fromContext}) imports ${to.owner.root} (context ${toContext}); a context never imports another context's entities, services or SQL. Keep a local copy fed by its events, or read a projection.`, context: fromContext, targetContext: toContext });
+  }
+};
+
+const relationTarget = (kit, model, argument) => {
+  const { ts } = kit;
+  const isFunction = argument && (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+  const target = isFunction && !ts.isBlock(argument.body) ? model.unparen(argument.body) : null;
+  return target && (ts.isIdentifier(target) || ts.isPropertyAccessExpression(target)) ? target : null;
+};
+
+// The relation decorator (`@ManyToOne(() => Target)` imported from typeorm) a node is, with the checker that resolves it, else null.
+const relationBinding = (kit, checker, node) => {
+  const { ts } = kit;
+  if (!ts.isDecorator(node) || !ts.isCallExpression(node.expression)) return null;
+  const binding = kit.importBinding(checker, node.expression.expression);
+  return binding?.module === TYPEORM && RELATIONS.has(binding.name) ? binding : null;
+};
+
+const checkRelations = (scan, file, ownContext) => {
+  const { kit, model, counts, covered, once } = scan;
+  const { ts } = kit;
+  const checker = kit.checkerOf(file.sourceFile);
+  kit.walk(file.sourceFile, node => {
+    const binding = relationBinding(kit, checker, node);
+    if (!binding) return;
+    counts.relations += 1;
+    const target = relationTarget(kit, model, node.expression.arguments[0]);
+    if (!target) return;
+    const home = kit.declarationsOf(checker, ts.isPropertyAccessExpression(target) ? target.name : target).map(kit.ownerOfDeclaration).find(Boolean);
+    const targetContext = home ? model.contextOfCapability(home.root) : null;
+    if (!home || !targetContext || targetContext === ownContext) return;
+    covered.add(`${file.rel}|${home.root}`);
+    once(`${file.rel}|${node.getStart()}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A ${binding.name} relation in ${file.owner.root} (context ${ownContext}) targets an entity of ${home.root} (context ${targetContext}); a relation never crosses a context. Keep the other context's id as a plain column and fill a local copy or a projection from its events.`, context: ownContext, targetContext });
+  });
+};
+
+const stringText = (ts, node) => (ts.isTemplateExpression(node) ? node.head.text + node.templateSpans.map(span => ` ${span.literal.text}`).join('') : node.text);
+
+const checkForeignKeys = (scan, file, ownContext) => {
+  const { kit, model, tables, counts, once } = scan;
+  const { ts } = kit;
+  kit.walk(file.sourceFile, node => {
+    if (!(ts.isStringLiteralLike(node) || ts.isTemplateExpression(node))) return;
+    for (const match of stringText(ts, node).matchAll(REFERENCES)) {
+      counts.foreignKeys += 1;
+      const entity = tables.get(match[1].toLowerCase());
+      const targetContext = entity ? model.contextOfCapability(entity.owner) : null;
+      if (!entity || !targetContext || targetContext === ownContext) continue;
+      once(`${file.rel}|${node.getStart()}|${match[1]}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A foreign key in ${file.rel} references table ${entity.table} of ${entity.owner} (context ${targetContext}), but this migration belongs to context ${ownContext}; a foreign key never crosses a context. Keep the id as a plain column and validate it through the other context's API or a local copy fed by its events.`, context: ownContext, targetContext, table: entity.table });
+    }
+  });
+};
+
+const checkPersistenceFile = (scan, file) => {
+  if (file.slot !== 'be.persistence' || !file.owner) return;
+  const ownContext = scan.model.contextOfCapability(file.owner.root);
+  if (!ownContext) return;
+  if (path.posix.basename(file.rel).endsWith('.entity.ts')) checkRelations(scan, file, ownContext);
+  if (file.rel.slice(file.owner.root.length + 1).startsWith('persistence/migrations/')) checkForeignKeys(scan, file, ownContext);
+};
 
 export function checkContextCoupling(input) {
   const { graph } = input;
   const kit = machineKit(input);
-  const { ts, resolver } = kit;
   const model = contextModelOf(kit, graph);
   const { tables } = entitiesOf(kit, graph);
   const violations = [];
@@ -32,57 +103,10 @@ export function checkContextCoupling(input) {
   const once = (key, violation) => { if (!seen.has(key)) { seen.add(key); violations.push({ ruleId: RULE, ...violation }); } };
   const counts = { relations: 0, foreignKeys: 0, imports: 0 };
   const covered = new Set(); // `${fromRel}|${targetRoot}` pairs a relation already reported, so the import edge is not a second finding
+  const scan = { kit, model, tables, counts, covered, once };
 
-  for (const file of graph.files.values()) {
-    if (file.slot !== 'be.persistence' || !file.owner) continue;
-    const base = path.posix.basename(file.rel);
-    const ownContext = model.contextOfCapability(file.owner.root);
-    if (!ownContext) continue;
-    const checker = kit.checkerOf(file.sourceFile);
-    if (base.endsWith('.entity.ts')) {
-      kit.walk(file.sourceFile, node => {
-        if (!ts.isDecorator(node) || !ts.isCallExpression(node.expression)) return true;
-        const binding = kit.importBinding(checker, node.expression.expression);
-        if (binding?.module !== TYPEORM || !RELATIONS.has(binding.name)) return true;
-        counts.relations += 1;
-        const argument = node.expression.arguments[0];
-        const target = argument && (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument)) && !ts.isBlock(argument.body) ? model.unparen(argument.body) : null;
-        if (!target || !(ts.isIdentifier(target) || ts.isPropertyAccessExpression(target))) return true;
-        const home = kit.declarationsOf(checker, ts.isPropertyAccessExpression(target) ? target.name : target).map(kit.ownerOfDeclaration).find(Boolean);
-        const targetContext = home ? model.contextOfCapability(home.root) : null;
-        if (!home || !targetContext || targetContext === ownContext) return true;
-        covered.add(`${file.rel}|${home.root}`);
-        once(`${file.rel}|${node.getStart()}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A ${binding.name} relation in ${file.owner.root} (context ${ownContext}) targets an entity of ${home.root} (context ${targetContext}); a relation never crosses a context. Keep the other context's id as a plain column and fill a local copy or a projection from its events.`, context: ownContext, targetContext });
-        return true;
-      });
-    }
-    if (file.rel.slice(file.owner.root.length + 1).startsWith('persistence/migrations/')) {
-      kit.walk(file.sourceFile, node => {
-        if (!(ts.isStringLiteralLike(node) || ts.isTemplateExpression(node))) return true;
-        const text = ts.isTemplateExpression(node) ? node.head.text + node.templateSpans.map(span => ` ${span.literal.text}`).join('') : node.text;
-        for (const match of text.matchAll(REFERENCES)) {
-          counts.foreignKeys += 1;
-          const entity = tables.get(match[1].toLowerCase());
-          const targetContext = entity ? model.contextOfCapability(entity.owner) : null;
-          if (!entity || !targetContext || targetContext === ownContext) continue;
-          once(`${file.rel}|${node.getStart()}|${match[1]}`, { ...kit.at(file.rel, file.sourceFile, node), message: `A foreign key in ${file.rel} references table ${entity.table} of ${entity.owner} (context ${targetContext}), but this migration belongs to context ${ownContext}; a foreign key never crosses a context. Keep the id as a plain column and validate it through the other context's API or a local copy fed by its events.`, context: ownContext, targetContext, table: entity.table });
-        }
-        return true;
-      });
-    }
-  }
+  for (const file of graph.files.values()) checkPersistenceFile(scan, file);
 
-  for (const edge of graph.edges) {
-    const from = graph.files.get(edge.from);
-    const to = graph.files.get(edge.to);
-    if (!from?.owner || !to?.owner || from.owner.root === to.owner.root) continue;
-    const fromContext = model.contextOfFile(edge.from);
-    const toContext = model.contextOfFile(edge.to);
-    if (!fromContext || !toContext || fromContext === toContext) continue;
-    counts.imports += 1;
-    if (covered.has(`${edge.from}|${to.owner.root}`)) continue;
-    once(`${edge.from}|${edge.to}|${edge.line}`, { path: edge.from, line: edge.line, column: edge.column, message: `${from.owner.root} (context ${fromContext}) imports ${to.owner.root} (context ${toContext}); a context never imports another context's entities, services or SQL. Keep a local copy fed by its events, or read a projection.`, context: fromContext, targetContext: toContext });
-  }
-  void resolver;
+  checkCrossContextImports(graph, model, covered, counts, once);
   return { violations, coverage: { status: 'checked', ...counts } };
 }