@starci/eslint-canon-fe 8.2.18 → 8.3.0

package/runtime/scripts/hfs/architecture/backend-app-files.mjs

@@ -0,0 +1,110 @@
+import path from 'node:path';
+import { allowsFile } from '../allows.mjs';
+import { relativePath, unwrapExpression } from './typescript.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
+
+const PROCESS_MODULES = new Set(['process', 'node:process']);
+const PROCESS_GLOBAL = new Set(['process']);
+const GLOBAL_HOLDERS = new Set(['globalThis', 'global']);
+const REFLECT_GLOBAL = new Set(['Reflect']);
+
+/** A static property name, including `object['env']` and `object[`env`]`. */
+export function accessName(ts, node) {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
+  return null;
+}
+
+function bindingName(ts, element) {
+  const name = element.propertyName ?? element.name;
+  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
+  return ts.isComputedPropertyName(name) && ts.isStringLiteralLike(name.expression) ? name.expression.text : null;
+}
+
+/** A global name is not a same-named local variable or parameter. */
+function isGlobalName(ts, checker, node, names) {
+  if (!ts.isIdentifier(node) || !names.has(node.text)) return false;
+  const declarations = checker?.getSymbolAtLocation(node)?.getDeclarations() ?? [];
+  return declarations.every(declaration => declaration.getSourceFile().isDeclarationFile);
+}
+
+function recordProcessBindings(ts, clause, add, report) {
+  if (clause?.name) add(clause.name);
+  const bindings = clause?.namedBindings;
+  if (bindings && ts.isNamespaceImport(bindings)) add(bindings.name);
+  if (!bindings || !ts.isNamedImports(bindings)) return;
+  for (const element of bindings.elements) {
+    const name = (element.propertyName ?? element.name).text;
+    if (name === 'env') report(element);
+    else if (name === 'default') add(element.name);
+  }
+}
+
+function processImportSymbols(ts, checker, sourceFile, report) {
+  const imports = new Set();
+  const add = name => {
+    const symbol = checker.getSymbolAtLocation(name);
+    if (symbol) imports.add(symbol);
+  };
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)
+      || !PROCESS_MODULES.has(statement.moduleSpecifier.text)) continue;
+    recordProcessBindings(ts, statement.importClause, add, report);
+  }
+  return imports;
+}
+
+/** Process bindings are resolved by symbol, so a nested parameter cannot masquerade as an imported process. */
+function processAccess(ts, checker, sourceFile, report) {
+  const imports = processImportSymbols(ts, checker, sourceFile, report);
+  const isProcess = expression => {
+    const node = unwrapExpression(ts, expression);
+    if (!node) return false;
+    if (ts.isIdentifier(node)) return imports.has(checker.getSymbolAtLocation(node))
+      || isGlobalName(ts, checker, node, PROCESS_GLOBAL);
+    return accessName(ts, node) === 'process'
+      && isGlobalName(ts, checker, node.expression, GLOBAL_HOLDERS);
+  };
+  return node => {
+    if (accessName(ts, node) === 'env' && isProcess(node.expression)) report(node);
+    if (ts.isVariableDeclaration(node) && node.initializer && isProcess(node.initializer) && ts.isObjectBindingPattern(node.name)
+      && node.name.elements.some(element => bindingName(ts, element) === 'env')) report(node);
+    if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'get'
+      && isGlobalName(ts, checker, node.expression.expression, REFLECT_GLOBAL)
+      && isProcess(node.arguments[0]) && node.arguments[1] && ts.isStringLiteralLike(node.arguments[1]) && node.arguments[1].text === 'env') report(node);
+  };
+}
+
+/** The declaration, rather than the caller's name, identifies EnvSource readers and configuration helpers. */
+function appEnvironmentCall(config, ts, checker, call) {
+  const declaration = checker.getResolvedSignature(call)?.declaration;
+  if (!declaration) return false;
+  const relative = relativePath(config.root, declaration.getSourceFile().fileName);
+  if (ts.isMethodDeclaration(declaration) && ts.isClassDeclaration(declaration.parent) && declaration.parent.name?.text === 'EnvSource') {
+    return config.hfs.tierOf(relative) === 'platform' && path.posix.basename(config.hfs.ownerOf(relative)?.root ?? '') === 'config';
+  }
+  if (!ts.isFunctionDeclaration(declaration) && !ts.isArrowFunction(declaration) && !ts.isFunctionExpression(declaration)) return false;
+  return allowsFile(config.hfs, relative)?.entry === '<app>.env.ts'
+    || (path.posix.basename(relative).endsWith('.config.ts') && config.hfs.slotOf(relative) !== null);
+}
+
+/** Composition groups and options consume parsed options; only the app's matching env role and main read them. */
+export function checkApplicationEnvironment(config, context, sourceFile, fileName, violations) {
+  const role = allowsFile(config.hfs, relativePath(config.root, fileName));
+  if (role?.allowed && (role.entry === 'main.ts' || role.entry === '<app>.env.ts')) return;
+  const { ts } = context;
+  const checker = context.checkerFor(fileName);
+  const report = node => violations.push({
+    ruleId: 'BE_APP_COMPOSITION_ONLY',
+    path: relativePath(config.root, fileName),
+    ...sourceLocation(sourceFile, node),
+    message: "Application environment reads live in main.ts or the matching <app>.env.ts. Options files and compose/<area>.ts receive the typed result of read<App>Env(env: EnvSource).",
+  });
+  const checkProcess = processAccess(ts, checker, sourceFile, report);
+  const visit = node => {
+    checkProcess(node);
+    if (ts.isCallExpression(node) && appEnvironmentCall(config, ts, checker, node)) report(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}

package/runtime/scripts/hfs/architecture/backend.mjs

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
-import { slotAdmitsFile } from '../allows.mjs';
+import { allowsFile, slotAdmitsFile } from '../allows.mjs';
 import { reachableViolation, relativePath } from './typescript.mjs';
+import { checkApplicationEnvironment } from './backend-app-files.mjs';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 
@@ -376,11 +377,23 @@ function checkApplicationComposition(config, ts, sourceFile, fileName, app, viol
       path: relativePath(config.root, fileName),
       line: 1,
       column: 1,
-      message: `Application source ${app.relative} is not a file its app slot requires or allows (main.ts, app.module.ts, <app>.options.ts).`,
+      message: `Application source ${app.relative} is not a file its app slot requires or allows (main.ts, app.module.ts, <app>.env.ts, <app>.options.ts, compose/<area>.ts).`,
     });
   }
 }
 
+/** The app's environment parser never depends on features, even through a type import or an internal barrel. */
+function checkApplicationEnvEdges(config, context, fileName, violations) {
+  const role = allowsFile(config.hfs, relativePath(config.root, fileName));
+  if (!role?.allowed || role.entry !== '<app>.env.ts') return;
+  const isFeature = target => config.hfs.tierOf(relativePath(config.root, target)) === 'feature';
+  for (const edge of context.edges.get(fileName) ?? []) {
+    const featureChain = reachableViolation(context.edges, edge, isFeature);
+    if (featureChain) violations.push(finding(config, edge, 'BE_APP_COMPOSITION_ONLY',
+      'The app environment file holds typed, fail-fast environment parsing only; it cannot depend on features, including through a type import or an internal barrel.', featureChain));
+  }
+}
+
 function checkApplicationTransport(config, context, sourceFile, fileName, violations) {
   for (const evidence of transportFrameworkEvidence(context.ts, sourceFile, context.checkerFor(fileName))) {
     violations.push({
@@ -409,7 +422,11 @@ function checkBackendSource(config, context, sourceFiles, roots, sourceFile, vio
   const fromFeatures = insideAny(featureRoots, fileName);
   const fromApplication = fromFeatures && insideFeatureLayer(featureRoots, fileName, 'application');
   const app = !fromModules && !fromFeatures ? appSource(config, fileName, nonAppRoots) : null;
-  if (app) checkApplicationComposition(config, context.ts, sourceFile, fileName, app, violations);
+  if (app) {
+    checkApplicationComposition(config, context.ts, sourceFile, fileName, app, violations);
+    checkApplicationEnvEdges(config, context, fileName, violations);
+    checkApplicationEnvironment(config, context, sourceFile, fileName, violations);
+  }
   if (!fromModules && !fromFeatures) return;
   if (fromApplication) checkApplicationTransport(config, context, sourceFile, fileName, violations);
   if (fromApplication) checkFeatureTransportEdges(config, context, sourceFiles, featureRoots, fileName, violations);

package/runtime/scripts/hfs/architecture/background-unowned.mjs

@@ -5,30 +5,45 @@ import { machineKit } from './machine-ast.mjs';
  * R46 `background-unowned` (BE_BACKGROUND_UNOWNED, BE-CONVENTION 1.6 and 1.13). Background work is a transport that only
  * a worker or api app runs (an api app composes the message transport of its own service; a separate worker is opt-in):
  *
- *   - every job processor (`*.processor.ts`, the jobs kind) and consumer (`*.consumer.ts`) is composed by an app of kind `worker` or
- *     `api`: the file is reachable, through runtime imports, from the root module of some such app declared in hfs.json; one no app
- *     reaches never runs. A schedule is a BullMQ job scheduler of a queue, so no scheduler decorator or timer is judged here: `@nestjs/schedule`
- *     and the timers are owned by platform capabilities (R90 BE_INFRA_OWNER);
- *   - a method whose name is one of the words the law names (`sweep`, `deliver`, `reconcile`, `retry`, alone or as the
- *     first word of a camelCase name) in a domain, integrations or feature class is reachable from a composed processor or
- *     consumer: from the processor or consumer files and everything they import, and from the files of the feature that holds them
- *     (its handlers are registered with the command bus, not imported by the processor). Mechanisms of platform are exempt.
+ *   - a processor, consumer, scheduler, saga or event handler is composed by an app of kind `worker` or `api`: its file is
+ *     reachable, through runtime imports, from an app root declared in hfs.json. Context comes from its file role or framework
+ *     decorators, never a method name. Infrastructure restrictions on scheduler libraries remain R90 BE_INFRA_OWNER's concern;
+ *   - methods in those contexts, and methods they call transitively, are reachable from a composed background entry point:
+ *     its imports and the files of its own feature (command handlers are registered with the bus). Platform mechanisms are
+ *     exempt. Resolvers and controllers are user entry points and never background, even when called by a background method.
  *
- * Reachability is static (imports, re-exports and the feature of the processor); it proves a processor or consumer could call the method,
- * not that it does.
+ * Classification follows statically resolved calls; ownership follows runtime imports, re-exports and the entry point's feature.
  */
 export const BACKGROUND_UNOWNED_RULE_IDS = ['BE_BACKGROUND_UNOWNED'];
 
 const RULE = 'BE_BACKGROUND_UNOWNED';
-const BACKGROUND_ROLES = new Set(['processor', 'consumer']);
-/** The words the law names for background methods (knowledge/hfs/README.md 5.7). */
-const BACKGROUND_WORDS = ['sweep', 'deliver', 'reconcile', 'retry'];
+const BACKGROUND_ROLES = new Set(['processor', 'consumer', 'scheduler', 'saga', 'event-handler']);
+const USER_ROLES = new Set(['resolver', 'controller']);
+const CLASS_DECORATORS = new Map([
+  ['@nestjs/bull:Processor', 'processor'], ['@nestjs/bullmq:Processor', 'processor'],
+  ['@nestjs/cqrs:EventsHandler', 'event-handler'],
+]);
+const METHOD_DECORATORS = new Map([
+  ['@nestjs/cqrs:Saga', 'saga'], ['@nestjs/event-emitter:OnEvent', 'event-handler'],
+  ...['Cron', 'Interval', 'Timeout'].map(name => [`@nestjs/schedule:${name}`, 'scheduler']),
+]);
+const USER_DECORATORS = new Map([['@nestjs/graphql:Resolver', 'resolver'], ['@nestjs/common:Controller', 'controller']]);
 
 const roleOf = rel => {
   const parts = path.posix.basename(rel).split('.');
-  return parts.length >= 3 && parts.at(-1) === 'ts' && BACKGROUND_ROLES.has(parts.at(-2)) ? parts.at(-2) : null;
+  return parts.length >= 3 && parts.at(-1) === 'ts' ? parts.at(-2) : null;
+};
+
+const decoratedRole = (kit, checker, node, roles) => {
+  for (const decorator of kit.decorators(node)) {
+    const expression = decorator.expression;
+    const callee = kit.ts.isCallExpression(expression) ? expression.expression : expression;
+    const binding = kit.importBinding(checker, callee);
+    const role = binding ? roles.get(`${binding.module}:${binding.name}`) : null;
+    if (role) return role;
+  }
+  return null;
 };
-const isBackgroundName = name => BACKGROUND_WORDS.some(word => name === word || (name.startsWith(word) && /[A-Z]/u.test(name[word.length] ?? '')));
 
 const adjacencyOf = edges => {
   const adjacency = new Map();
@@ -60,19 +75,16 @@ const appRootsOf = (apps, graph) => {
   return { workers, composed: [...workers, ...services] };
 };
 
-const backgroundFilesOf = graph => [...graph.files.values()].filter(file => roleOf(file.rel) && file.tier === 'feature');
-
 const reportUncomposedFiles = (background, composed, workerRoots, report) => {
-  for (const file of background) {
-    if (composed.has(file.rel)) continue;
-    const role = roleOf(file.rel);
-    report(file, file.sourceFile, `${file.rel} is a ${role} that no service app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; a ${role} runs only when the ${role === 'processor' ? 'job' : 'message'} module of its feature is imported by the root module of an app of kind worker or api.`, { role });
+  for (const { file, role } of background) {
+    if (file.tier === 'platform' || composed.has(file.rel)) continue;
+    report(file, file.sourceFile, `${file.rel} is a ${role} that no service app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; its module must be imported by the root module of an app of kind worker or api.`, { role });
   }
 };
 
 const rootsOfRunningFeatures = (running, files) => {
   const roots = new Set();
-  for (const file of running) {
+  for (const { file } of running) {
     roots.add(file.rel);
     const owner = file.owner?.root;
     if (owner) for (const other of files.values()) if (other.owner?.root === owner) roots.add(other.rel);
@@ -80,22 +92,125 @@ const rootsOfRunningFeatures = (running, files) => {
   return roots;
 };
 
-const backgroundMethodsOf = (node, kit, ts) => node.members.flatMap(member => {
-  if (!ts.isMethodDeclaration(member) || !member.name) return [];
-  const name = kit.propertyNameText(member.name);
-  return name && isBackgroundName(name) ? [{ name, node: member.name }] : [];
-});
+const callableKey = (kit, node) => `${kit.graphPath(node)}:${node.getStart()}`;
+const callableBody = (ts, declaration) => {
+  const node = declaration.initializer ?? declaration;
+  return ts.isFunctionLike(node) && node.body ? node : null;
+};
+const methodMember = (ts, node) => {
+  if (ts.isMethodDeclaration(node)) return node;
+  return ts.isPropertyDeclaration(node.parent) && node.parent.initializer === node ? node.parent : null;
+};
 
-const checkBackgroundMethods = ({ graph, kit, ts, reachable, report }) => {
-  let methods = 0;
-  const reportMethod = (file, method) => {
-    methods += 1;
-    if (!reachable.has(file.rel)) report(file, method.node, `${method.name} is background work (a ${BACKGROUND_WORDS.join(', ')} method) that no processor or consumer composed by a worker or api app can reach. Add a processor in features/jobs/<job> or a consumer in transport/message of a feature that runs it, and compose its module in a worker or api app.`, { method: method.name });
-  };
+const isUserClass = (kit, checker, node) => USER_ROLES.has(roleOf(kit.graphPath(node) ?? ''))
+  || Boolean(decoratedRole(kit, checker, node, USER_DECORATORS));
+
+const seedClass = (scope, file, checker, node, role) => {
+  scope.background.set(file.rel, { file, role });
+  scope.contextFiles.add(file.rel);
+  for (const symbol of checker.getTypeAtLocation(node).getProperties()) {
+    for (const declaration of symbol.declarations ?? []) {
+      const body = callableBody(scope.kit.ts, declaration);
+      if (body) scope.inherited.push(body);
+    }
+  }
+};
+
+const classContext = (scope, file, checker, node, state) => {
+  const user = state.user || isUserClass(scope.kit, checker, node);
+  if (!state.nested && user) scope.userFiles.add(file.rel);
+  let classRole = null;
+  if (!state.nested && !user) {
+    const fileRole = BACKGROUND_ROLES.has(state.fileRole) ? state.fileRole : null;
+    classRole = decoratedRole(scope.kit, checker, node, CLASS_DECORATORS) ?? fileRole;
+  }
+  if (classRole) seedClass(scope, file, checker, node, classRole);
+  return { ...state, user, classRole };
+};
+
+const recordCallable = (scope, file, checker, node, state) => {
+  const { kit } = scope;
+  const member = methodMember(kit.ts, node);
+  const canSeed = member && !state.user && !state.nested;
+  const role = canSeed ? decoratedRole(kit, checker, member, METHOD_DECORATORS) ?? state.classRole : null;
+  const entry = { file, node, checker, user: state.user, member, name: member ? kit.propertyNameText(member.name) : null };
+  scope.callables.set(callableKey(kit, node), entry);
+  if (role) {
+    scope.background.set(file.rel, { file, role });
+    scope.contextFiles.add(file.rel);
+    scope.seeds.push(entry);
+  }
+};
+
+const indexCallables = (scope, file, checker, node, state) => {
+  const { ts } = scope.kit;
+  if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) state = classContext(scope, file, checker, node, state);
+  const callable = ts.isFunctionLike(node);
+  if (callable && node.body) recordCallable(scope, file, checker, node, state);
+  const childState = { ...state, nested: state.nested || callable };
+  ts.forEachChild(node, child => indexCallables(scope, file, checker, child, childState));
+};
+
+/** Index callable bodies once; a resolver/controller is a barrier to background propagation. */
+const backgroundContextOf = (graph, kit) => {
+  const callables = new Map();
+  const background = new Map();
+  const seeds = [];
+  const inherited = [];
+  const scope = { kit, callables, background, seeds, inherited, userFiles: new Set(), contextFiles: new Set() };
   for (const file of graph.files.values()) {
-    if (file.tier === 'platform') continue;
-    kit.walk(file.sourceFile, node => {
-      if (ts.isClassDeclaration(node)) for (const method of backgroundMethodsOf(node, kit, ts)) reportMethod(file, method);
+    const checker = kit.checkerOf(file.sourceFile);
+    const fileRole = roleOf(file.rel);
+    if (BACKGROUND_ROLES.has(fileRole)) background.set(file.rel, { file, role: fileRole });
+    indexCallables(scope, file, checker, file.sourceFile, { fileRole, classRole: null, user: USER_ROLES.has(fileRole), nested: false });
+  }
+  // Request context overrides a file suffix; mixed files can still hold a separate background class.
+  for (const rel of scope.userFiles) if (!scope.contextFiles.has(rel)) background.delete(rel);
+  for (const body of inherited) {
+    const entry = callables.get(callableKey(kit, body));
+    if (entry) seeds.push(entry);
+  }
+  return { callables, background: [...background.values()], seeds };
+};
+
+const calledBodies = (kit, checker, call) => {
+  const { ts } = kit;
+  const expression = call.expression;
+  if (ts.isPropertyAccessExpression(expression) || ts.isElementAccessExpression(expression)) {
+    const receiver = checker.getNonNullableType(checker.getTypeAtLocation(expression.expression));
+    if (receiver.getSymbol()?.declarations?.some(declaration => isUserClass(kit, checker, declaration))) return [];
+  }
+  const target = ts.isPropertyAccessExpression(expression) ? expression.name : expression;
+  const declarations = [...kit.declarationsOf(checker, target)];
+  const signature = checker.getResolvedSignature(call)?.declaration;
+  if (signature) declarations.push(signature);
+  return declarations.map(declaration => callableBody(ts, declaration)).filter(Boolean);
+};
+
+const checkBackgroundMethods = ({ kit, context, reachable, report }) => {
+  const { callables, seeds } = context;
+  const seen = new Set();
+  const queue = [...seeds];
+  let methods = 0;
+  while (queue.length) {
+    const entry = queue.pop();
+    const { file, node, checker, user, member, name } = entry;
+    const key = callableKey(kit, node);
+    if (user || seen.has(key)) continue;
+    seen.add(key);
+    if (name && file.tier !== 'platform') {
+      methods += 1;
+      if (!reachable.has(file.rel)) report(file, member.name, `${name} is background work that no background entry point composed by a worker or api app can reach. Compose the processor, consumer, scheduler, saga or event handler that runs it in a worker or api app.`, { method: name });
+    }
+    kit.walk(node.body, inner => {
+      // Nested bodies run only through a resolved call or when passed as a callback.
+      if (kit.ts.isFunctionLike(inner) || kit.ts.isClassDeclaration(inner) || kit.ts.isClassExpression(inner)) return false;
+      if (!kit.ts.isCallExpression(inner)) return;
+      const callbacks = inner.arguments.filter(argument => kit.ts.isArrowFunction(argument) || kit.ts.isFunctionExpression(argument));
+      for (const body of [...calledBodies(kit, checker, inner), ...callbacks]) {
+        const called = callables.get(callableKey(kit, body));
+        if (called) queue.push(called);
+      }
     });
   }
   return methods;
@@ -104,7 +219,7 @@ const checkBackgroundMethods = ({ graph, kit, ts, reachable, report }) => {
 export function checkBackgroundUnowned(input) {
   const { graph } = input;
   const kit = machineKit(input);
-  const { ts, resolver } = kit;
+  const { resolver } = kit;
   const violations = [];
   const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
 
@@ -112,13 +227,14 @@ export function checkBackgroundUnowned(input) {
   const closure = starts => closureOf(adjacency, starts);
   const { workers: workerRoots, composed: appRoots } = appRootsOf(resolver.repo.apps, graph);
   const composed = closure(appRoots);
-  const background = backgroundFilesOf(graph);
-  const running = background.filter(file => composed.has(file.rel));
+  const context = backgroundContextOf(graph, kit);
+  const { background } = context;
+  const running = background.filter(({ file }) => composed.has(file.rel));
   reportUncomposedFiles(background, composed, workerRoots, report);
 
-  // Everything a composed processor or consumer can reach: its imports, and the files of its own feature (command handlers).
+  // Everything a composed background entry point can reach: its imports and its own feature's command handlers.
   const roots = rootsOfRunningFeatures(running, graph.files);
   const reachable = closure([...roots]);
-  const methods = checkBackgroundMethods({ graph, kit, ts, reachable, report });
+  const methods = checkBackgroundMethods({ kit, context, reachable, report });
   return { violations, coverage: { status: 'checked', workers: workerRoots.length, jobsAndConsumers: background.length, composed: running.length, backgroundMethods: methods } };
 }