@starci/hfs 1.0.1 → 2.0.0

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

@@ -0,0 +1,350 @@
+import path from 'node:path';
+import { isInside } from './config.mjs';
+import { slotAdmitsFile } from '../../lib/hfs-allows.mjs';
+import { reachableViolation, relativePath, sourceLocation } from './typescript.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)$/;
+const FORBIDDEN_DECORATORS = new Set(['Controller', 'Resolver', 'Injectable', 'Processor', 'WebSocketGateway']);
+const TRANSPORT_PACKAGES = /^(?:@nestjs\/(?:graphql|microservices|platform-[^/]+|websockets)(?:\/|$)|@apollo\/|apollo-server(?:\/|$)|express(?:\/|$)|fastify(?:\/|$)|graphql(?:\/|$)|class-validator(?:\/|$)|class-transformer(?:\/|$))/;
+const NEST_COMMON_TRANSPORT = new Set(['Controller', 'Get', 'Post', 'Put', 'Patch', 'Delete', 'Options', 'Head', 'Body', 'Param', 'Query', 'Req', 'Request', 'Res', 'Response', 'Headers', 'Header', 'HttpCode', 'Redirect', 'Render', 'Sse', 'UploadedFile', 'UploadedFiles', 'UseGuards', 'UseInterceptors', 'UsePipes']);
+
+function absolute(root, relative) {
+  return path.resolve(root, ...relative.split('/'));
+}
+
+function roots(root, relatives) {
+  return relatives.map(relative => absolute(root, relative));
+}
+
+function insideAny(candidates, fileName) {
+  return candidates.some(root => isInside(root, fileName));
+}
+
+function insideFeatureLayer(featureRoots, fileName, layer) {
+  return featureRoots.some(root => isInside(root, fileName)
+    && relativePath(root, fileName).split('/').some(segment => segment.toLowerCase() === layer));
+}
+
+function appSource(config, fileName, excludedRoots = []) {
+  if (excludedRoots.some(excluded => isInside(excluded, fileName))) return null;
+  for (const appRoot of roots(config.root, config.backend.apps)) {
+    if (!isInside(appRoot, fileName)) continue;
+    const parts = relativePath(appRoot, fileName).split('/');
+    const sourceIndex = parts.indexOf('src');
+    if (sourceIndex >= 0) return { appRoot, relative: parts.slice(sourceIndex + 1).join('/') };
+    // An app root may name its src/ directly (apps/<app>/src), but the repository src/ itself is
+    // never an app root: HFS composition lives under apps/<app> only.
+    const appRootRelative = relativePath(config.root, appRoot).split('/');
+    if (path.basename(appRoot).toLowerCase() === 'src' && appRootRelative[0] === 'apps' && appRootRelative.length > 1) {
+      return { appRoot, relative: parts.join('/') };
+    }
+    return null;
+  }
+  return null;
+}
+
+function decoratorName(ts, decorator) {
+  const expression = decorator.expression;
+  const called = ts.isCallExpression(expression) ? expression.expression : expression;
+  if (ts.isIdentifier(called)) return called.text;
+  return ts.isPropertyAccessExpression(called) ? called.name.text : null;
+}
+
+function roleEvidence(ts, sourceFile) {
+  let found = null;
+  const visit = node => {
+    if (found) return;
+    const decorators = ts.canHaveDecorators?.(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
+    const forbidden = decorators.find(item => FORBIDDEN_DECORATORS.has(decoratorName(ts, item)));
+    if (forbidden) {
+      found = { node: forbidden, detail: `@${decoratorName(ts, forbidden)}` };
+      return;
+    }
+    if ((ts.isClassDeclaration(node) || ts.isFunctionDeclaration(node)) && node.name && FORBIDDEN_DECLARATION.test(node.name.text)) {
+      found = { node: node.name, detail: node.name.text };
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return found;
+}
+
+function transportFrameworkEvidence(ts, sourceFile, checker) {
+  const found = [];
+  const namespaceUsages = binding => {
+    const usages = [];
+    const alias = binding.text;
+    const bindingSymbol = checker?.getSymbolAtLocation(binding);
+    const isAlias = node => ts.isIdentifier(node) && node.text === alias
+      && (!bindingSymbol || checker?.getSymbolAtLocation(node) === bindingSymbol);
+    const visit = node => {
+      if (ts.isPropertyAccessExpression(node) && isAlias(node.expression)
+        && NEST_COMMON_TRANSPORT.has(node.name.text)) usages.push({ node: node.name, detail: node.name.text });
+      if (ts.isElementAccessExpression(node) && isAlias(node.expression)) {
+        const selected = ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
+        if (selected === null || NEST_COMMON_TRANSPORT.has(selected)) usages.push({ node: node.argumentExpression, detail: selected ?? 'computed @nestjs/common namespace access' });
+      }
+      if (ts.isVariableDeclaration(node) && isAlias(node.initializer)) {
+        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' });
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return usages;
+  };
+  for (const statement of sourceFile.statements) {
+    const importEqualsSpecifier = ts.isImportEqualsDeclaration(statement)
+      && ts.isExternalModuleReference(statement.moduleReference)
+      && statement.moduleReference.expression
+      && ts.isStringLiteralLike(statement.moduleReference.expression)
+      ? statement.moduleReference.expression
+      : null;
+    const importSpecifier = ts.isImportDeclaration(statement) && ts.isStringLiteralLike(statement.moduleSpecifier)
+      ? statement.moduleSpecifier
+      : importEqualsSpecifier;
+    if (!importSpecifier) continue;
+    const specifier = importSpecifier.text;
+    if (TRANSPORT_PACKAGES.test(specifier)) {
+      found.push({ node: importSpecifier, specifier, detail: specifier });
+      continue;
+    }
+    if (specifier !== '@nestjs/common') continue;
+    if (ts.isImportEqualsDeclaration(statement)) {
+      found.push(...namespaceUsages(statement.name).map(item => ({ ...item, specifier })));
+      continue;
+    }
+    if (!statement.importClause) continue;
+    const bindings = statement.importClause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) {
+      found.push(...namespaceUsages(bindings.name).map(item => ({ ...item, specifier })));
+      continue;
+    }
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      const imported = element.propertyName?.text ?? element.name.text;
+      if (NEST_COMMON_TRANSPORT.has(imported)) found.push({ node: element, specifier, detail: imported });
+    }
+  }
+  const visitRequire = node => {
+    const requiredSpecifier = call => ts.isCallExpression(call)
+      && ts.isIdentifier(call.expression) && call.expression.text === 'require'
+      && call.arguments.length === 1 && ts.isStringLiteralLike(call.arguments[0])
+      ? call.arguments[0].text
+      : null;
+    if ((ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) && ts.isCallExpression(node.expression)) {
+      const specifier = requiredSpecifier(node.expression);
+      const selected = ts.isPropertyAccessExpression(node)
+        ? node.name.text
+        : ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
+      if (specifier && TRANSPORT_PACKAGES.test(specifier)) {
+        found.push({ node: ts.isPropertyAccessExpression(node) ? node.name : node.argumentExpression, specifier, detail: `${selected ?? 'computed member'} from ${specifier}` });
+      } else if (specifier === '@nestjs/common' && (selected === null || NEST_COMMON_TRANSPORT.has(selected))) {
+        found.push({ node: ts.isPropertyAccessExpression(node) ? node.name : node.argumentExpression, specifier, detail: selected ?? 'computed @nestjs/common require access' });
+      }
+    }
+    if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer)
+      && requiredSpecifier(node.initializer)) {
+      const specifier = requiredSpecifier(node.initializer);
+      if (TRANSPORT_PACKAGES.test(specifier)) {
+        found.push({ node: node.initializer.arguments[0], specifier, detail: specifier });
+      } else if (specifier === '@nestjs/common') {
+        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' });
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visitRequire);
+  };
+  visitRequire(sourceFile);
+  return found;
+}
+
+function importedSurface(ts, declaration) {
+  if (!ts.isImportDeclaration(declaration)) return null;
+  const clause = declaration.importClause;
+  if (!clause) return null;
+  const names = new Set(clause.name ? ['default'] : []);
+  const bindings = clause.namedBindings;
+  if (bindings && ts.isNamespaceImport(bindings)) return null;
+  if (bindings && ts.isNamedImports(bindings)) {
+    for (const element of bindings.elements) names.add(element.propertyName?.text ?? element.name.text);
+  }
+  return names;
+}
+
+function selectedReexportSurface(ts, declaration, selected) {
+  if (!ts.isExportDeclaration(declaration)) return undefined;
+  if (!declaration.exportClause) return selected;
+  if (ts.isNamespaceExport(declaration.exportClause)) {
+    return selected === null || selected.has(declaration.exportClause.name.text) ? null : undefined;
+  }
+  if (!ts.isNamedExports(declaration.exportClause)) return undefined;
+  const next = new Set();
+  for (const element of declaration.exportClause.elements) {
+    if (selected === null || selected.has(element.name.text)) next.add(element.propertyName?.text ?? element.name.text);
+  }
+  return next.size ? next : undefined;
+}
+
+function externalTransportReexport(ts, sourceFile, selected) {
+  const imported = new Map();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier) || !statement.importClause) continue;
+    const specifier = statement.moduleSpecifier.text;
+    const bindings = statement.importClause.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) imported.set(element.name.text, { specifier, imported: element.propertyName?.text ?? element.name.text });
+    } else if (bindings && ts.isNamespaceImport(bindings)) imported.set(bindings.name.text, { specifier, imported: null });
+  }
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExportDeclaration(statement)) continue;
+    const clause = statement.exportClause;
+    const specifier = ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+    if (specifier && (specifier === '@nestjs/common' || TRANSPORT_PACKAGES.test(specifier))) {
+      if (!clause) {
+        if (specifier !== '@nestjs/common' || selected === null || [...selected].some(name => NEST_COMMON_TRANSPORT.has(name))) {
+          return { node: statement.moduleSpecifier, specifier, detail: selected === null ? `unbounded ${specifier} re-export` : `re-exported ${[...selected].join(', ')}` };
+        }
+        continue;
+      }
+      if (ts.isNamespaceExport(clause)) {
+        if (selected === null || selected.has(clause.name.text)) return { node: clause.name, specifier, detail: `namespace re-export from ${specifier}` };
+        continue;
+      }
+      if (!ts.isNamedExports(clause)) continue;
+      for (const element of clause.elements) {
+        if (selected !== null && !selected.has(element.name.text)) continue;
+        const original = element.propertyName?.text ?? element.name.text;
+        if (specifier !== '@nestjs/common' || NEST_COMMON_TRANSPORT.has(original)) return { node: element, specifier, detail: `${element.name.text} re-exported from ${specifier}` };
+      }
+      continue;
+    }
+    if (specifier || !clause || !ts.isNamedExports(clause)) continue;
+    for (const element of clause.elements) {
+      if (selected !== null && !selected.has(element.name.text)) continue;
+      const local = element.propertyName?.text ?? element.name.text;
+      const binding = imported.get(local);
+      if (!binding) continue;
+      if (binding.specifier !== '@nestjs/common' && !TRANSPORT_PACKAGES.test(binding.specifier)) continue;
+      if (binding.specifier === '@nestjs/common' && (binding.imported === null || !NEST_COMMON_TRANSPORT.has(binding.imported))) continue;
+      return { node: element, specifier: binding.specifier, detail: `${element.name.text} re-exported from ${binding.specifier}` };
+    }
+  }
+  return null;
+}
+
+function reexportedTransportEvidence(ts, context, sourceFiles, firstEdge) {
+  const queue = [{ file: firstEdge.to, selected: importedSurface(ts, firstEdge.declaration), chain: [firstEdge.from, firstEdge.to] }];
+  const visited = new Set();
+  while (queue.length) {
+    const current = queue.shift();
+    const key = `${current.file}\0${current.selected === null ? '*' : [...current.selected].sort().join(',')}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+    const sourceFile = sourceFiles.get(path.resolve(current.file));
+    if (!sourceFile) continue;
+    const evidence = externalTransportReexport(ts, sourceFile, current.selected);
+    if (evidence) return { evidence, chain: current.chain };
+    for (const edge of context.edges.get(current.file) ?? []) {
+      if (!edge.reexport) continue;
+      const selected = selectedReexportSurface(ts, edge.declaration, current.selected);
+      if (selected !== undefined) queue.push({ file: edge.to, selected, chain: [...current.chain, edge.to] });
+    }
+  }
+  return null;
+}
+
+function finding(config, edge, ruleId, message, chain) {
+  return {
+    ruleId,
+    path: relativePath(config.root, edge.from),
+    line: edge.line,
+    column: edge.column,
+    specifier: edge.specifier,
+    resolvedPath: relativePath(config.root, chain.at(-1)),
+    dependencyChain: chain.map(file => relativePath(config.root, file)),
+    message,
+  };
+}
+
+/** Enforce backend direction and keep executable apps as measurable composition roots. */
+export function checkBackend(config, context) {
+  const violations = [];
+  const moduleRoots = roots(config.root, config.backend.modules);
+  const featureRoots = roots(config.root, config.backend.features);
+  const nonAppRoots = [...moduleRoots, ...featureRoots];
+  const sourceFiles = new Map(context.files.map(file => [path.resolve(file.fileName), file]));
+  for (const sourceFile of context.files) {
+    const fileName = path.resolve(sourceFile.fileName);
+    const fromModules = insideAny(moduleRoots, fileName);
+    const fromFeatures = insideAny(featureRoots, fileName);
+    const fromApplication = fromFeatures && insideFeatureLayer(featureRoots, fileName, 'application');
+    const app = !fromModules && !fromFeatures ? appSource(config, fileName, nonAppRoots) : null;
+    if (app) {
+      const evidence = roleEvidence(context.ts, sourceFile);
+      if (evidence) {
+        violations.push({
+          ruleId: 'BE_APP_BUSINESS_ROLE',
+          path: relativePath(config.root, fileName),
+          ...sourceLocation(sourceFile, evidence.node),
+          message: `Application composition source contains measurable business/provider role ${evidence.detail}. Move that role under src/features or src/modules.`,
+        });
+      } else if (slotAdmitsFile(config.hfs, relativePath(config.root, fileName)) !== true) {
+        violations.push({
+          ruleId: FORBIDDEN_APP_ROLE.test(path.posix.basename(app.relative)) ? 'BE_APP_BUSINESS_ROLE' : 'BE_APP_COMPOSITION_ONLY',
+          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).`,
+        });
+      }
+    }
+    if (!fromModules && !fromFeatures) continue;
+    if (fromApplication) {
+      for (const evidence of transportFrameworkEvidence(context.ts, sourceFile, context.checkerFor(fileName))) violations.push({
+        ruleId: 'BE_APPLICATION_TRANSPORT_FRAMEWORK',
+        path: relativePath(config.root, fileName),
+        ...sourceLocation(sourceFile, evidence.node),
+        specifier: evidence.specifier,
+        message: `Feature application code imports transport framework surface ${evidence.detail}. Keep protocol decorators, request/response types, validation DTOs, and generated transport types under transport/.`,
+      });
+    }
+    for (const edge of context.edges.get(fileName) ?? []) {
+      if (fromApplication) {
+        const reexported = reexportedTransportEvidence(context.ts, context, sourceFiles, edge);
+        if (reexported) violations.push(finding(config, edge, 'BE_APPLICATION_TRANSPORT_FRAMEWORK', `Feature application code imports protocol surface ${reexported.evidence.detail} through an internal re-export. Keep protocol decorators and types under transport/.`, reexported.chain));
+        const transportChain = reachableViolation(context.edges, edge, target => insideFeatureLayer(featureRoots, target, 'transport'));
+        if (transportChain) violations.push(finding(config, edge, 'BE_APPLICATION_IMPORTS_TRANSPORT', 'Feature application code cannot depend on transport adapters or DTOs, including through a type import or barrel.', transportChain));
+      }
+    }
+  }
+  return violations;
+}

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

@@ -0,0 +1,107 @@
+import path from 'node:path';
+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:
+ *
+ *   - 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);
+ *   - 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.
+ *
+ * Reachability is static (imports, re-exports and the feature of the job); it proves a job 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'];
+/** 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('.');
+  return parts.length >= 3 && parts.at(-1) === 'ts' && BACKGROUND_ROLES.includes(parts.at(-2)) ? parts.at(-2) : null;
+};
+const isBackgroundName = name => BACKGROUND_WORDS.some(word => name === word || (name.startsWith(word) && /[A-Z]/u.test(name[word.length] ?? '')));
+
+export function checkBackgroundUnowned(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts, 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 });
+
+  const adjacency = new Map();
+  for (const edge of graph.edges) if (edge.runtime) {
+    if (!adjacency.has(edge.from)) adjacency.set(edge.from, []);
+    adjacency.get(edge.from).push(edge.to);
+  }
+  const closure = starts => {
+    const seen = new Set(starts);
+    const queue = [...starts];
+    while (queue.length) for (const next of adjacency.get(queue.shift()) ?? []) if (!seen.has(next)) { seen.add(next); queue.push(next); }
+    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 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 });
+  }
+
+  // Everything a composed job 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);
+    const owner = file.owner?.root;
+    if (owner) for (const other of graph.files.values()) if (other.owner?.root === owner) roots.add(other.rel);
+  }
+  const reachable = closure([...roots]);
+
+  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 });
+        }
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', workers: workerRoots.length, jobsAndConsumers: background.length, composed: running.length, backgroundMethods: methods } };
+}

package/runtime/scripts/checks/architecture/client-reaches-server.mjs

@@ -0,0 +1,94 @@
+import { builtinModules } from 'node:module';
+import { sourceLocation } from './typescript.mjs';
+
+/**
+ * R55 `client-reaches-server` (FE_CLIENT_REACHES_SERVER), the repository half of the eslint rule `client-no-server-import`,
+ * which sees one hop from a file that carries the directive. The machine walks the resolved import graph from every module
+ * whose first statement is the `"use client"` directive, over runtime edges only (a type-only import vanishes at build), and
+ * reports any reachable module (the entry itself included) that imports a server-only surface:
+ *
+ *   - `server-only`, `next/headers`, `next/server`, `next-intl/server`;
+ *   - a Node built-in: `node:*` and every bare name of `module.builtinModules` (`fs`, `path`, `crypto`, ...).
+ *
+ * The finding sits on the client entry, names the shortest import chain from it to the offending module (multi-hop) and the
+ * specifier. Only imports that reach the client bundle count: `import type`, an import whose every named specifier is
+ * `type`, and `export type` re-exports are skipped.
+ */
+export const CLIENT_REACHES_SERVER_RULE_IDS = ['FE_CLIENT_REACHES_SERVER'];
+
+const RULE = 'FE_CLIENT_REACHES_SERVER';
+const SERVER_MODULES = new Set(['server-only', 'next/headers', 'next/server', 'next-intl/server']);
+const NODE_BUILTINS = new Set(builtinModules.map(name => name.replace(/^node:/u, '').split('/')[0]));
+
+const isServerSpecifier = specifier => SERVER_MODULES.has(specifier) || specifier.startsWith('node:') || NODE_BUILTINS.has(specifier.split('/')[0]);
+
+export function checkClientReachesServer({ graph, context }) {
+  const ts = context.ts;
+  const isClientEntry = file => {
+    const first = file.sourceFile.statements[0];
+    return Boolean(first) && ts.isExpressionStatement(first) && ts.isStringLiteral(first.expression) && first.expression.text === 'use client';
+  };
+  /** True when the import or re-export declaration reaches the bundle: not `import type`, not all-`type` specifiers. */
+  const reachesBundle = declaration => {
+    if (ts.isImportDeclaration(declaration)) {
+      const clause = declaration.importClause;
+      if (!clause) return true;
+      if (clause.isTypeOnly) return false;
+      if (!clause.name && clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+        const elements = clause.namedBindings.elements;
+        return elements.length === 0 || !elements.every(element => element.isTypeOnly);
+      }
+      return true;
+    }
+    return !declaration.isTypeOnly;
+  };
+  /** The server-only specifiers a file imports, with the node to point at. */
+  const serverImports = file => {
+    const found = [];
+    const visit = node => {
+      const specifier = (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && reachesBundle(node) ? node.moduleSpecifier
+        : ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require')) ? node.arguments[0]
+          : null;
+      if (specifier && ts.isStringLiteralLike(specifier) && isServerSpecifier(specifier.text)) found.push({ specifier: specifier.text, node });
+      ts.forEachChild(node, visit);
+    };
+    visit(file.sourceFile);
+    return found;
+  };
+
+  const runtime = new Map();
+  for (const edge of graph.edges) {
+    if (!edge.runtime) continue;
+    if (!runtime.has(edge.from)) runtime.set(edge.from, []);
+    runtime.get(edge.from).push(edge);
+  }
+  const serverByFile = new Map();
+  const serverOf = rel => {
+    if (!serverByFile.has(rel)) serverByFile.set(rel, serverImports(graph.files.get(rel)));
+    return serverByFile.get(rel);
+  };
+
+  const violations = [];
+  const entries = [...graph.files.values()].filter(isClientEntry).sort((a, b) => a.rel.localeCompare(b.rel));
+  for (const entry of entries) {
+    const seen = new Map([[entry.rel, { chain: [entry.rel], first: null }]]);
+    const queue = [entry.rel];
+    for (let head = 0; head < queue.length; head += 1) {
+      const rel = queue[head];
+      const state = seen.get(rel);
+      for (const hit of serverOf(rel)) {
+        const at = state.first ?? sourceLocation(graph.files.get(rel).sourceFile, hit.node);
+        violations.push({
+          ruleId: RULE, path: entry.rel, line: at.line, column: at.column, clientEntry: entry.rel, importer: rel, specifier: hit.specifier, dependencyChain: state.chain,
+          message: `${entry.rel} is a client module ("use client") and reaches ${hit.specifier} through ${[...state.chain, hit.specifier].join(' -> ')}; a server-only surface never enters the client bundle. Read on the server and pass the value down, or move the import out of the client graph.`,
+        });
+      }
+      for (const edge of runtime.get(rel) ?? []) {
+        if (seen.has(edge.to)) continue;
+        seen.set(edge.to, { chain: [...state.chain, edge.to], first: state.first ?? { line: edge.line, column: edge.column } });
+        queue.push(edge.to);
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', clientEntries: entries.length } };
+}