@starci/eslint-canon-fe 7.0.0 → 7.1.1

package/runtime/knowledge/sonar-gate.yaml

@@ -0,0 +1,86 @@
+schema: starci/sonar-gate@1
+id: sonar-gate
+title: The Sonar quality gate every product is held to
+purpose: |
+  The one place the Sonar thresholds live. A product repository never restates them: its
+  .starcistacks/application-stacks.yaml `services.sonar.qualityGate` names the gate below, and
+  scripts/checks/sonar-local.mjs (1) makes the local SonarQube's gate of that name carry exactly these
+  conditions and selects it for the project, and (2) judges an op's slice - the lines it changed - against
+  the same numbers. Code-writing ops cannot settle done while the slice is red
+  (scripts/kernel/sonar-settle.mjs). Changing a number here changes every repository on the next scan.
+  The gate has two parts: `newCode` (the recent work: duplication, blocker/critical issues, hotspots) and
+  `overall` (the whole code: no imported HFS, ESLint or stylelint finding, no duplicated-lines excess, no cognitive-
+  complexity issue). The one Sonar mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
+gate:
+  name: starci-new-code
+  # A project with no new-code baseline judges the whole project as new code (nivo inc-f92febebbb64); a fixed
+  # window keeps "new code" the recent work on main, so the server gate is passable on a healthy main.
+  newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
+newCode:
+  # Sonar holds NO coverage condition: unit coverage is the runner's job (jest per-file 100 on `*.service.ts`), never an lcov import.
+  # SonarQube's ignoreSmallChanges: fewer changed lines than this are not held to duplication.
+  ignoreBelowChangedLines: 20
+  duplication:
+    metric: new_duplicated_lines_density
+    maxPercent: 3
+  issues:
+    # An open issue of these severities on a changed line fails the slice; lesser ones are listed, never blocking.
+    blockingSeverities: [BLOCKER, CRITICAL]
+    metrics: {BLOCKER: new_blocker_violations, CRITICAL: new_critical_violations}
+    max: 0
+  hotspots:
+    metric: new_security_hotspots_reviewed
+    minReviewedPercent: 100
+    unreviewedMax: 0
+# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `hfs lint`
+# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry), which writes ONE file, reports/lint.sonar.json
+# (`npm run lint -- --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
+# the whole project at zero. The file carries three engines:
+#   starci-hfs   the repository findings of `hfs check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
+#   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)
+#   stylelint    stylelint's json over the style glob (front ends)
+# The engines share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own
+# ESLint import (sonar.eslint.reportPaths) is not used because it drops such issues.
+# A SonarQube gate condition cannot filter issues by engine, so the condition is the project's open issues (`violations`,
+# overall code): the three engines above are the imports it counts, and every native Sonar issue counts with them. That is
+# stricter than the engines alone and it is intended: a project that meets this gate has no open issue of any origin.
+overall:
+  issues:
+    metric: violations
+    max: 0
+    engines: [starci-hfs, eslint, stylelint]
+  # HFS_DUPLICATE_CODE (R21): duplicated lines density of the whole project, the Sonar enforcer of the machine's clone check.
+  # SonarJS runs its own token-based detection (sonar.cpd.* minimums are not read for TypeScript), so ruleParams.<profile>.duplicateBlock
+  # is enforced by the machine and imported as starci-hfs issues, and this density is the Sonar-side backstop.
+  duplication:
+    metric: duplicated_lines_density
+    maxPercent: 3
+  # HFS_SIZE_GROWTH (R20): the cognitive complexity of a function is the Sonar rule S3776 (typescript:S3776, Sonar way, default
+  # threshold); an open S3776 issue is an open issue of `overall.issues`, so the zero-issue condition is its gate.
+  cognitiveComplexity:
+    rule: typescript:S3776
+    via: overall.issues
+# The Sonar enforcers of the rule catalog (knowledge/hfs/rules.yaml): the failure code each condition above is the gate of.
+enforces:
+  - {rule: R20, code: HFS_SIZE_GROWTH, enforcer: cognitive-complexity, condition: cognitiveComplexity}
+  - {rule: R21, code: HFS_DUPLICATE_CODE, enforcer: duplicated-lines-density, condition: duplication}
+  - {rule: R21, code: HFS_DUPLICATE_SYMBOL, enforcer: duplicated-lines-density, condition: duplication}
+# Ops that write product code: each runs sonar-local on its own change and cannot settle done while the gate is red.
+enforcedOps: [backend.implement, interface.implement, code.refactor]
+reasoning: |
+  Chosen against the four projects the local server holds on 2026-09-29 (whole-project duplicated lines
+  1.6 / 2.1 / 1.7 / 0.0 percent), so new code that meets them is at or below what main already carries.
+  no coverage condition: the unit project fails below its per-file 100 threshold on `*.service.ts`, so Sonar never
+  imports an lcov report and never judges coverage.
+  duplication 3: the Sonar way value; the worst project today is 2.1, so 3 rejects a real copy-paste block and
+  passes ordinary work.
+  blocker/critical 0: the two severities that are defects, not style. main carries old debt of both kinds
+  (nivo-backend 3 blocker, 137 critical), so the SLICE verdict reads only changed lines and never main's backlog;
+  major and lower are reported on the summary and never fail a slice.
+  overall issues 0 and overall duplication 3: the server gate is also the owner's definition of done for the HFS canon:
+  a repository that carries any open ESLint, stylelint or HFS finding is not green, whatever the age of the line. The
+  op slice keeps judging changed lines (an op cannot fix a repository's whole backlog); the dashboard and CI show the
+  whole-project condition. Adopting a repository therefore means clearing its imported findings, which `hfs check`,
+  eslint and stylelint already demand at land.
+  hotspots 0 unreviewed: a hotspot is a question the author must answer; on changed lines it is answered in the
+  same slice.

package/runtime/packages/hfs/templates/be/package-scripts/package.json

@@ -0,0 +1,19 @@
+{
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    {{appScripts}}
+    "typecheck": "tsc -p tsconfig.json",
+    "typecheck:tests": "tsc -p src/tests/tsconfig.json",
+    "lint": "hfs lint",
+    "lint:fix": "hfs lint --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "jest --selectProjects unit --coverage",
+    "test:affected": "jest --selectProjects unit --passWithNoTests",
+    "test:integration": "npm run typecheck:tests && jest --selectProjects integration",
+    "test:e2e": "npm run typecheck:tests && jest --selectProjects e2e",
+    "test:contract": "npm run typecheck:tests && jest --selectProjects contract",
+    "test:stack": "starci-test-stack",
+    "contract:emit": "hfs emit-contracts"
+  }
+}

package/runtime/packages/hfs/templates/fe/package-scripts/package.json

@@ -0,0 +1,13 @@
+{
+  "scripts": {
+    "prepare": "husky",
+    {{appScripts}}
+    "codegen": "npm run codegen --workspaces --if-present",
+    "build": "npm run build --workspaces --if-present",
+    "typecheck": "npm run typecheck --workspaces --if-present",
+    "lint": "npm run codegen --silent && hfs lint --stylelint \"{{styleGlob}}\"",
+    "lint:fix": "npm run codegen --silent && hfs lint --fix --stylelint \"{{styleGlob}}\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}

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 } };
+}