@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/hfs/architecture/ast-walks.mjs

@@ -0,0 +1,220 @@
+// ast-walks.mjs - AST walks the architecture checkers share (moved out of typescript.mjs, which keeps the program loading and module resolution).
+import { canonical, isInside } from './config.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { UNPROVEN_FRAMEWORK, isUnshadowedCommonJsRequire, relativePath, unwrapExpression } from './typescript.mjs';
+
+/** `expression` unwrapped by the caller's own predicate set (a predicate absent on an older ts reads as never). */
+export function unwrapEach(ts, expression, predicates) {
+  while (expression && predicates.some((predicate) => predicate?.(expression))) expression = expression.expression;
+  return expression;
+}
+
+/** `value` with every TS alias hop resolved (a re-exported import reads as its target symbol). */
+export function normalizedSymbolValue(ts, checker, value) {
+  let symbol = value ?? null;
+  const seen = new Set();
+  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
+    seen.add(symbol);
+    const target = checker.getAliasedSymbol(symbol);
+    if (!target || target === symbol) break;
+    symbol = target;
+  }
+  return symbol;
+}
+
+/** The symbol `node` names, aliases resolved. */
+export function normalizedSymbol(ts, checker, node) {
+  return normalizedSymbolValue(ts, checker, checker?.getSymbolAtLocation(node) ?? null);
+}
+
+/** The identifier or member-name node an expression selects through unwrapExpression, or null. */
+export function selectedNode(ts, expression) {
+  expression = unwrapExpression(ts, expression);
+  if (ts.isIdentifier(expression)) return expression;
+  if (ts.isPropertyAccessExpression(expression)) return expression.name;
+  if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression)) return expression.argumentExpression;
+  return null;
+}
+
+/**
+ * The symbol `node` ultimately evaluates to: its own symbol, followed through a single `const` variable
+ * initializer (and so on). `unselected: 'null'` answers null when `node` selects no name at all.
+ */
+export function valueSymbol(ts, checker, node, seen = new Set(), { unselected = 'node' } = {}) {
+  const selected = selectedNode(ts, node);
+  if (!selected && unselected === 'null') return null;
+  const symbol = normalizedSymbol(ts, checker, selected ?? node);
+  if (!symbol || seen.has(symbol)) return symbol;
+  seen.add(symbol);
+  const declarations = symbol.getDeclarations?.() ?? [];
+  if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
+    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
+    return valueSymbol(ts, checker, declarations[0].initializer, seen, { unselected });
+  }
+  return symbol;
+}
+
+/**
+ * The expressions `declaration` returns: its body when it is an expression-bodied arrow/function, else every
+ * `return`'s argument without descending into nested functions. `functionLike` overrides which node kinds bound
+ * that descent (default the four callable declaration kinds; pass `ts.isFunctionLike` for the wider set).
+ */
+export function returnedExpressions(ts, declaration, { functionLike = null } = {}) {
+  const boundary = functionLike ?? ((node) => ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)
+    || ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+  if ((ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration)) && !ts.isBlock(declaration.body)) return [declaration.body];
+  const body = boundary(declaration) ? declaration.body : null;
+  if (!body || !ts.isBlock(body)) return [];
+  const returned = [];
+  const visit = (node) => {
+    if (node !== body && boundary(node)) return;
+    if (ts.isReturnStatement(node) && node.expression) returned.push(node.expression);
+    else ts.forEachChild(node, visit);
+  };
+  visit(body);
+  return returned;
+}
+
+/** A node's decorators across TS versions (ts.getDecorators, else the legacy `decorators` property). */
+export function nodeDecorators(ts, node) {
+  return ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
+}
+
+/** One finding row: rule id, root-relative path, node position and message, plus rule extras. */
+export function violation(config, sourceFile, node, ruleId, message, extra = {}) {
+  return { ruleId, path: relativePath(config.root, sourceFile.fileName), ...sourceLocation(sourceFile, node), message, ...extra };
+}
+
+/** Whether `match` holds for `node` or a descendant (the walk stops at the first match). */
+export function anyDescendant(ts, node, match) {
+  let found = false;
+  const visit = (current) => {
+    if (found) return;
+    if (match(current)) { found = true; return; }
+    ts.forEachChild(current, visit);
+  };
+  visit(node);
+  return found;
+}
+
+/**
+ * The framework kinds `expression` can produce: `directOf(ts, checker, {symbol, selected, targets})` maps a
+ * selected node's symbols to a kind (default `targets.get(symbol)`); `shorthandOf` (when set) also resolves
+ * shorthand-property declarations and descends property assignments; `newExpression` descends `new X()` callees.
+ */
+export function tracedFrameworkKinds(ts, checker, expression, targets,
+  { seen = new Set(), depth = 0, directOf = null, shorthandOf = null, newExpression = false } = {}) {
+  if (!expression) return new Set();
+  if (depth > 10) return new Set([UNPROVEN_FRAMEWORK]);
+  expression = unwrapExpression(ts, expression);
+  const selected = selectedNode(ts, expression);
+  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
+  const direct = symbol ? (directOf ?? ((ts2, c, { symbol: s, targets: t }) => t.get(s) ?? null))(ts, checker, { symbol, selected, targets }) : null;
+  if (direct) return new Set([direct]);
+  const opts = { depth: depth + 1, directOf, shorthandOf, newExpression };
+  if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
+    const kinds = new Set();
+    for (const returned of returnedExpressions(ts, expression)) {
+      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, { ...opts, seen })) kinds.add(kind);
+    }
+    return kinds;
+  }
+  if (ts.isCallExpression(expression)) {
+    const kinds = tracedFrameworkKinds(ts, checker, expression.expression, targets, { ...opts, seen });
+    if (kinds.size) return kinds;
+  }
+  if (newExpression && ts.isNewExpression(expression)) {
+    return tracedFrameworkKinds(ts, checker, expression.expression, targets, { ...opts, seen });
+  }
+  if (!symbol || seen.has(symbol)) return new Set();
+  const nextSeen = new Set(seen).add(symbol);
+  const kinds = new Set();
+  for (const declaration of symbol.getDeclarations?.() ?? []) {
+    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
+    }
+    if (shorthandOf && ts.isShorthandPropertyAssignment(declaration)) {
+      const target = normalizedSymbolValue(ts, checker, checker.getShorthandAssignmentValueSymbol?.(declaration));
+      const kind = shorthandOf(ts, checker, target, targets);
+      if (kind) kinds.add(kind);
+    }
+    if (shorthandOf && ts.isPropertyAssignment(declaration)) {
+      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
+    }
+    for (const returned of returnedExpressions(ts, declaration)) {
+      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
+    }
+  }
+  return kinds;
+}
+
+/** 'unproven framework' | 'multiple framework' | the one kind | null, for a decorator whose expression constructs. */
+export function constructedDecoratorKind(ts, checker, decorator, targets, traceOpts = {}) {
+  const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+  const kinds = tracedFrameworkKinds(ts, checker, callee, targets, traceOpts);
+  if (kinds.has(UNPROVEN_FRAMEWORK)) return 'unproven framework';
+  return kinds.size === 1 ? [...kinds][0] : kinds.size ? 'multiple framework' : null;
+}
+
+/** The target a decorator resolves to through a `let`/`var` alias's single initializer, or null. */
+export function mutableDecoratorKind(ts, checker, decorator, targets) {
+  const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+  const selected = selectedNode(ts, callee);
+  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
+  const declarations = symbol?.getDeclarations?.() ?? [];
+  if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
+    || (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) return null;
+  return targets.get(valueSymbol(ts, checker, declarations[0].initializer)) ?? null;
+}
+
+/** The callee expression of a decorator (the called expression of `@x(...)`, else the expression itself). */
+export function decoratorCallee(ts, decorator) {
+  return ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+}
+
+/**
+ * The module `statement` (import, export-from or import-equals) statically binds: its specifier text, the
+ * module's symbol and its exported symbols by name (aliases resolved); `symbol` is null when the module does
+ * not resolve. Null when the statement names no static specifier.
+ */
+export function moduleExportsOf(ts, checker, statement) {
+  const moduleSpecifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
+    && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
+  const importEquals = ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)
+    && statement.moduleReference.expression && ts.isStringLiteralLike(statement.moduleReference.expression)
+    ? statement.moduleReference.expression : null;
+  const specifierNode = moduleSpecifier ?? importEquals;
+  const specifier = specifierNode?.text;
+  if (specifier == null) return null;
+  const symbol = checker.getSymbolAtLocation(specifierNode) ?? null;
+  const exports = new Map((symbol ? checker.getExportsOfModule(symbol) : []).map(item => [item.getName(), normalizedSymbolValue(ts, checker, item)]));
+  return { specifierNode, specifier, symbol, exports };
+}
+
+/**
+ * The program source files a framework-target scan of `checker` judges: every file in `localFiles`, plus (when
+ * `root` is given) declaration files inside the root but outside node_modules. Null when no program of the
+ * context owns the checker.
+ */
+export function programSourcesOf(context, checker, localFiles, { root = null } = {}) {
+  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker) ?? null;
+  if (!program) return null;
+  return program.getSourceFiles().filter(sourceFile => localFiles.has(canonical(sourceFile.fileName))
+    || (root && sourceFile.isDeclarationFile && isInside(root, sourceFile.fileName)
+      && !sourceFile.fileName.replaceAll('\\', '/').includes('/node_modules/')));
+}
+
+/**
+ * The CommonJS require() caveat every framework scan reports: each `require('<specifier>')` `accepted` pushes
+ * `${filePath} uses a CommonJS <label ?? specifier> <detail>` (the import-shape reasoning cannot prove that binding).
+ */
+export function commonJsRequireReasons(ts, checker, sourceFile, accepted, reasons, filePath, detail, label = null) {
+  const visit = node => {
+    if (ts.isCallExpression(node) && isUnshadowedCommonJsRequire(ts, checker, node.expression)
+      && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0]) && accepted(node.arguments[0].text)) {
+      reasons.push(`${filePath} uses a CommonJS ${label ?? node.arguments[0].text} ${detail}`);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}

package/runtime/scripts/{checks → hfs}/architecture/backend.mjs

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
-import { slotAdmitsFile } from '../../lib/hfs-allows.mjs';
-import { reachableViolation, relativePath, sourceLocation } from './typescript.mjs';
+import { slotAdmitsFile } from '../allows.mjs';
+import { reachableViolation, relativePath } from './typescript.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 const FORBIDDEN_APP_ROLE = /(?:^|\.)(?:service|provider|providers|resolver|controller|handler|repository|entity|use-case|command|query|listener|consumer|processor)\.[cm]?[jt]sx?$/i;
 const FORBIDDEN_DECLARATION = /(?:Service|Provider|Resolver|Controller|Handler|Repository|Entity|UseCase|Command|Query|Listener|Consumer|Processor)$/;
@@ -73,6 +74,18 @@ function roleEvidence(ts, sourceFile) {
 
 function transportFrameworkEvidence(ts, sourceFile, checker) {
   const found = [];
+  // The destructured binding elements naming a transport export (or a computed binding, which cannot be
+  // proved to exclude one): `const { Controller, [x]: y } = ...`. `rest` elements are always opaque.
+  const destructuredBindings = (elements, detail) => elements.flatMap(element => {
+    const selected = element.dotDotDotToken
+      ? null
+      : ts.isIdentifier(element.propertyName ?? element.name)
+        ? (element.propertyName ?? element.name).text
+        : ts.isStringLiteralLike(element.propertyName)
+          ? element.propertyName.text
+          : null;
+    return selected === null || NEST_COMMON_TRANSPORT.has(selected) ? [{ node: element, detail: selected ?? detail }] : [];
+  });
   const namespaceUsages = binding => {
     const usages = [];
     const alias = binding.text;
@@ -90,18 +103,7 @@ function transportFrameworkEvidence(ts, sourceFile, checker) {
         if (!ts.isObjectBindingPattern(node.name)) {
           usages.push({ node: node.name, detail: 'escaped @nestjs/common namespace access' });
         } else {
-          for (const element of node.name.elements) {
-            const selected = element.dotDotDotToken
-              ? null
-              : ts.isIdentifier(element.propertyName ?? element.name)
-                ? (element.propertyName ?? element.name).text
-                : ts.isStringLiteralLike(element.propertyName)
-                  ? element.propertyName.text
-                  : null;
-            if (selected === null || NEST_COMMON_TRANSPORT.has(selected)) {
-              usages.push({ node: element, detail: selected ?? 'computed @nestjs/common namespace destructuring' });
-            }
-          }
+          usages.push(...destructuredBindings(node.name.elements, 'computed @nestjs/common namespace destructuring'));
         }
       }
       ts.forEachChild(node, visit);
@@ -168,16 +170,7 @@ function transportFrameworkEvidence(ts, sourceFile, checker) {
         if (ts.isIdentifier(node.name)) {
           found.push(...namespaceUsages(node.name).map(item => ({ ...item, specifier })));
         } else if (ts.isObjectBindingPattern(node.name)) {
-          for (const element of node.name.elements) {
-            const selected = element.dotDotDotToken
-              ? null
-              : ts.isIdentifier(element.propertyName ?? element.name)
-                ? (element.propertyName ?? element.name).text
-                : ts.isStringLiteralLike(element.propertyName)
-                  ? element.propertyName.text
-                  : null;
-            if (selected === null || NEST_COMMON_TRANSPORT.has(selected)) found.push({ node: element, specifier, detail: selected ?? 'computed @nestjs/common require destructuring' });
-          }
+          found.push(...destructuredBindings(node.name.elements, 'computed @nestjs/common require destructuring').map(item => ({ ...item, specifier })));
         }
       }
     }

package/runtime/scripts/{checks → hfs}/architecture/background-unowned.mjs

@@ -3,29 +3,26 @@ 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 app runs:
+ * 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 (`*.job.ts`) and consumer (`*.consumer.ts`) is composed by an app of kind `worker`: the file is reachable,
- *     through runtime imports, from the root module of some worker app declared in hfs.json; one no worker reaches never runs;
- *   - no scheduler outside `platform/scheduling`: a `@Cron`, `@Interval` or `@Timeout` decorator of `@nestjs/schedule` and a
- *     `setInterval` call are refused everywhere else (platform/scheduling owns the lease, the fencing and the overlap guard);
+ *   - 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 job or
- *     consumer: from the job 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 job). Mechanisms of platform are exempt.
+ *     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.
  *
- * Reachability is static (imports, re-exports and the feature of the job); it proves a job or consumer could call the 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.
  */
 export const BACKGROUND_UNOWNED_RULE_IDS = ['BE_BACKGROUND_UNOWNED'];
 
 const RULE = 'BE_BACKGROUND_UNOWNED';
-const BACKGROUND_ROLES = ['job', 'consumer'];
+const BACKGROUND_ROLES = ['processor', 'consumer'];
 /** The words the law names for background methods (knowledge/hfs/README.md 5.7). */
 const BACKGROUND_WORDS = ['sweep', 'deliver', 'reconcile', 'retry'];
-const SCHEDULER_DECORATORS = ['Cron', 'Interval', 'Timeout'];
-const SCHEDULER_PACKAGE = '@nestjs/schedule';
-const SCHEDULING_CAPABILITY = 'scheduling';
 
 const roleOf = rel => {
   const parts = path.posix.basename(rel).split('.');
@@ -52,17 +49,18 @@ export function checkBackgroundUnowned(input) {
     return seen;
   };
 
-  const workerRoots = resolver.repo.apps.filter(app => app.kind === 'worker').map(app => `apps/${app.name}/src/app.module.ts`).filter(rel => graph.files.has(rel));
-  const composed = closure(workerRoots);
+  const rootOf = app => `apps/${app.name}/src/app.module.ts`;
+  const workerRoots = resolver.repo.apps.filter(app => app.kind === 'worker').map(rootOf).filter(rel => graph.files.has(rel));
+  const composed = closure([...workerRoots, ...resolver.repo.apps.filter(app => app.kind === 'api').map(rootOf).filter(rel => graph.files.has(rel))]);
   const background = [...graph.files.values()].filter(file => roleOf(file.rel) && file.tier === 'feature');
   const running = background.filter(file => composed.has(file.rel));
   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 worker app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; a ${role} runs only when the ${role === 'job' ? 'schedule' : 'message'} module of its feature is imported by the root module of an app of kind worker.`, { role });
+    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 });
   }
 
-  // Everything a composed job or consumer can reach: its imports, and the files of its own feature (command handlers).
+  // Everything a composed processor or consumer can reach: its imports, and the files of its own feature (command handlers).
   const roots = new Set();
   for (const file of running) {
     roots.add(file.rel);
@@ -73,31 +71,15 @@ export function checkBackgroundUnowned(input) {
 
   let methods = 0;
   for (const file of graph.files.values()) {
-    const checker = kit.checkerOf(file.sourceFile);
-    const inScheduling = file.owner?.slot === 'be.platform' && path.posix.basename(file.owner.root) === SCHEDULING_CAPABILITY;
     const mechanism = file.tier === 'platform';
     kit.walk(file.sourceFile, node => {
-      if (!inScheduling && ts.isDecorator(node)) {
-        const call = ts.isCallExpression(node.expression) ? node.expression.expression : node.expression;
-        const binding = kit.importBinding(checker, call);
-        if (binding && binding.module === SCHEDULER_PACKAGE && SCHEDULER_DECORATORS.includes(binding.name)) {
-          report(file, node, `@${binding.name} schedules work inside a class outside platform/scheduling. Write a job in transport/schedule/<job>.job.ts that dispatches one command or query, and let platform/scheduling and a worker app run it.`, { scheduler: binding.name });
-        }
-      }
-      if (!inScheduling && ts.isCallExpression(node)) {
-        const callee = node.expression;
-        const bare = ts.isIdentifier(callee) && callee.text === 'setInterval' && kit.declarationsOf(checker, callee).every(declaration => declaration.getSourceFile().isDeclarationFile);
-        const member = ts.isPropertyAccessExpression(callee) && callee.name.text === 'setInterval' && ts.isIdentifier(callee.expression) && ['globalThis', 'window', 'global'].includes(callee.expression.text);
-        const global = bare || member;
-        if (global) report(file, node, 'setInterval starts a scheduler outside platform/scheduling. Write a job in transport/schedule/<job>.job.ts and let platform/scheduling and a worker app run it.', { scheduler: 'setInterval' });
-      }
       if (!mechanism && ts.isClassDeclaration(node)) {
         for (const member of node.members) {
           if (!ts.isMethodDeclaration(member) || !member.name) continue;
           const name = kit.propertyNameText(member.name);
           if (!name || !isBackgroundName(name)) continue;
           methods += 1;
-          if (!reachable.has(file.rel)) report(file, member.name, `${name} is background work (a ${BACKGROUND_WORDS.join(', ')} method) that no job or consumer composed by a worker app can reach. Add a job in transport/schedule or a consumer in transport/message of a feature that runs it, and compose that transport module in a worker app.`, { method: name });
+          if (!reachable.has(file.rel)) report(file, member.name, `${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: name });
         }
       }
       return true;

package/runtime/scripts/{checks → hfs}/architecture/client-reaches-server.mjs

@@ -1,5 +1,6 @@
 import { builtinModules } from 'node:module';
-import { sourceLocation } from './typescript.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
+import { isServerActionModule } from './server-action.mjs';
 
 /**
  * R55 `client-reaches-server` (FE_CLIENT_REACHES_SERVER), the repository half of the eslint rule `client-no-server-import`,
@@ -75,6 +76,7 @@ export function checkClientReachesServer({ graph, context }) {
     const queue = [entry.rel];
     for (let head = 0; head < queue.length; head += 1) {
       const rel = queue[head];
+      if (isServerActionModule(ts, graph.files.get(rel).sourceFile)) continue;
       const state = seen.get(rel);
       for (const hit of serverOf(rel)) {
         const at = state.first ?? sourceLocation(graph.files.get(rel).sourceFile, hit.node);

package/runtime/scripts/{checks → hfs}/architecture/clones.mjs

@@ -16,7 +16,7 @@
  *
  * Two kinds of file are uniform by design and are not compared, both found through the slot resolver: the entry main.ts of
  * an app (slot appKind + its required main.ts) and the transport doors of a feature (a *.controller.ts, *.resolver.ts,
- * *.gateway.ts, *.consumer.ts, *.job.ts or *.cli.ts of a slot that a protocol app composes). This is not a loophole: logic
+ * *.gateway.ts, *.consumer.ts, *.processor.ts or *.cli.ts of a slot that a protocol app composes). This is not a loophole: logic
  * cannot live in either. A door body is dispatch only (eslint transport-is-thin, R88), and main.ts cannot share a
  * helper because NestFactory is allowed only in main.ts (BE_ENTRYPOINT_ONLY_IN_APPS), so what repeats there is the
  * canonical shape of section 5 of BE-CONVENTION. A door or main.ts that grows logic is refused by those enforcers, not
@@ -25,12 +25,12 @@
 export const CLONE_RULE_IDS = ['HFS_DUPLICATE_CODE'];
 
 const MAX_VIOLATIONS = 200;
-const DOOR_ROLES = new Set(['controller', 'resolver', 'gateway', 'consumer', 'job', 'cli']);
+const DOOR_ROLES = new Set(['controller', 'resolver', 'gateway', 'consumer', 'processor', 'cli']);
 const APP_ENTRY = 'main.ts';
 const ID = -1;
 const LIT = -2;
 
-function tokenize(ts, sourceFile) {
+export function tokenize(ts, sourceFile) {
   const { SyntaxKind } = ts;
   const literalKinds = new Set([SyntaxKind.StringLiteral, SyntaxKind.NumericLiteral, SyntaxKind.BigIntLiteral, SyntaxKind.RegularExpressionLiteral,
     SyntaxKind.NoSubstitutionTemplateLiteral, SyntaxKind.TemplateHead, SyntaxKind.TemplateMiddle, SyntaxKind.TemplateTail, SyntaxKind.JsxText]);
@@ -76,7 +76,7 @@ function uniformByDesign(resolver, rel) {
   const base = rel.slice(rel.lastIndexOf('/') + 1);
   if (slot.appKind !== undefined) return base === APP_ENTRY && (slot.requires ?? []).includes(APP_ENTRY);
   const role = base.split('.').at(-2);
-  return (slot.composedBy?.length ?? 0) > 0 && DOOR_ROLES.has(role) && base.endsWith('.ts');
+  return !slot.owner && (slot.composedBy?.length ?? 0) > 0 && DOOR_ROLES.has(role) && base.endsWith('.ts');
 }
 
 function homeText(profile, sameOwner, crossApp) {

package/runtime/scripts/{checks → hfs}/architecture/config.mjs

@@ -2,8 +2,8 @@ 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';
+import { isInside } from '../../lib/walk.mjs';
+import { openHfs } from '../slots.mjs';
 
 
 /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -120,9 +120,10 @@ function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side =
         }
         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.
+      // HFS_EMPTY_DIR / HFS_SLOT_UNDECLARED, never a reason to analyse nothing); a literal workspace path must resolve. A `*`
+      // pattern may match nothing: every app declares the same workspaces (fe/apps/*, fe/packages/*, HFS_MONO_WORKSPACES) whether
+      // or not it has a package yet, and the root patterns are held to that fixed list by the rule, not here.
       const wildcard = segments.includes('*');
       for (const candidate of candidates) admit(candidate, `workspace ${normalized}`, !wildcard);
     }
@@ -262,13 +263,13 @@ const GRAMMAR_PACKAGE = '@starci/grammar';
 function derivedGrammar(root, packageRoot, workspaces, apps = []) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
-  // The apps have no package.json of their own: the app root's one manifest declares their dependencies, and it is a consumer
-  // when it declares the Grammar package; so is every workspace package that does.
+  // Every fe app and package is an npm workspace that declares what it imports (HFS_MONO_WORKSPACE_DEP): each workspace that
+  // declares the Grammar package is a consumer, and so is the app root's manifest when it does.
   const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
   const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
   const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
-    if (!workspace.startsWith('packages/')) continue;
+    if (!workspace.startsWith('packages/') && !workspace.startsWith('apps/')) continue;
     const manifest = `${workspace}/package.json`;
     const pkg = readJson(path.join(root, ...manifest.split('/')));
     if (declaresGrammar(pkg)) consumerManifests.push(manifest);
@@ -298,7 +299,9 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
   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'],
+    // The layered feature root is the api kind (src/features/api/<feature>/: application/ and transport/<protocol>/); the cli
+    // feature root (src/features/cli/) has its own shape, held by its slot and the cli rules.
+    features: ['src/features/api'],
     apps: ['apps'],
     moduleRegistration: { providerIdentity: 'exported-class-token', handlerDecorators: [...DECLARED_HANDLER_DECORATORS] },
   };

package/runtime/scripts/{checks → hfs}/architecture/connection-map.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { machineKit, pascal, upperSnake } from './machine-ast.mjs';
-import { locateDeclaration } from '../../lib/hfs-slots.mjs';
+import { locateDeclaration } from '../slots.mjs';
 
 /**
  * R84 `connection-map` (BE_CONNECTION_DUPLICATE), folding RED01 and RED02. One physical database is one connection, one
@@ -14,11 +14,14 @@ import { locateDeclaration } from '../../lib/hfs-slots.mjs';
  *   - 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`
+ *     forms only in platform/database, the cli 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;
+ *   - a connection whose hfs.json `isolation` is `schema` reads `<PREFIX>_SCHEMA` in its config (a context is its own database or its own
+ *     schema of a shared one; splitting it out later is an env change only);
  *   - 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.
+ *     `<PREFIX>_NAME` (or `_DATABASE`, whichever the config reads) resolve to one triple are the same database, unless both are
+ *     `isolation: schema` with different `<PREFIX>_SCHEMA` values (two contexts as schemas of one database).
  */
 export const CONNECTION_RULE_IDS = ['BE_CONNECTION_DUPLICATE'];
 
@@ -92,12 +95,14 @@ export function checkConnectionMap(input) {
       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) {
@@ -105,6 +110,7 @@ export function checkConnectionMap(input) {
       }
       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 });
   }
   for (const file of databaseFiles) {
     const match = /^(.+)\.(connection|decorators|config)\.ts$/u.exec(path.posix.basename(file.rel));
@@ -133,8 +139,8 @@ export function checkConnectionMap(input) {
             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 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
@@ -189,7 +195,7 @@ export function checkConnectionMap(input) {
     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();
+    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`);
@@ -200,9 +206,15 @@ export function checkConnectionMap(input) {
       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);
+      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;
   }