@starci/eslint-canon-fe 6.0.2 → 7.1.0

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -0,0 +1,309 @@
+schema: starci/knowledge-source@1
+id: fe.folder
+title: Folder
+purpose: |
+  Given a piece of frontend code, which directory and which file name does it get? Apply the HFS frontend tree
+  (knowledge/hfs/README.md section 6, slots fe.*).
+appliesTo:
+  - frontend
+family: fe
+provenance:
+  reviewedAt: 2026-09-29
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - https://nextjs.org/docs/app/getting-started/project-structure
+    - https://next-intl.dev/docs/routing
+    - packages/grammar/src/**
+  limitations: |
+    Folder rules place code by responsibility. They do not prove rendered behavior or accessibility. Inspect the
+    selected repository's actual source, manifests, aliases and lint and test configuration. Verify installed Grammar
+    exports at @starci/grammar/common.
+rules:
+  - id: FE-FOLDER-1
+    title: Responsibility directories
+    kind: mandatory
+    hfsRules: [R01, R02, R59, R64]
+    requirement: |
+      Every frontend repository is an apps/<app>/ monorepo even with one app, named by its role (for example web), and
+      all product source lives under apps/<app>/src. A repository-root src/ does not exist. Each Next source root
+      (apps/<app>/src) uses app/ for framework adapters; features/{pages,layouts,overlays} for route-facing product
+      composition; components/{blocks,composites,branches,leaves} for product visuals; hooks/<domain> for React hooks;
+      and modules/<capability> for cohesive reusable technical and domain capabilities. Every app has the modules api,
+      config, i18n and routes, and one brand.css under modules/brand when it sets brand tokens. No other empty role
+      folder is required. Grammar remains a separate product-agnostic package. The only files that may sit directly in the
+      source root (the directory holding app/) are the framework-pinned root files listed in frameworkPinnedRootFiles
+      below: Next.js loads them from that exact place. Each is a thin framework adapter whose internal imports enter
+      modules or a feature public entry only; every other rule still applies to it, except that the export names the
+      framework mandates there (frameworkPinnedRootExports) keep their framework spelling. HFS uses proxy.ts for locale
+      routing; a middleware.* file is refused on Next 16 and later by the Next conventions check and the slot
+      fe.source-root-pinned, even though the machine list names it as a file Next loads. Any other file at the source
+      root, including a helper folder beside a pinned file, has no owner and is refused.
+    frameworkPinnedRootFiles:
+      # Machine list read by scripts/checks/architecture/framework-pinned.mjs (FE_SOURCE_LAYOUT_INVALID accepts exactly
+      # these basenames directly in a Next source root; FE_TIER_DIRECTION keeps them thin). Exact names,
+      # case-sensitive, no globs. It lists what the framework loads from the source root. Which of them a repository may
+      # keep is decided by the slot fe.source-root-pinned and FE_NEXT_CONVENTIONS, not by this list.
+      # Machine list read by scripts/checks/architecture/framework-pinned.mjs (FE_SOURCE_LAYOUT_INVALID
+      # accepts exactly these basenames directly in a Next source root;
+      # their imports follow the FE_TIER_DIRECTION matrix). Exact names, case-sensitive, no globs. Supervisor rulings for nivo
+      # wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4 and inc-846867b9a34e (proxy is the Next 16 name of
+      # middleware, listed so the list survives the upgrade).
+      - middleware.ts
+      - middleware.js
+      - middleware.mjs
+      - proxy.ts
+      - proxy.js
+      - proxy.mjs
+      - instrumentation.ts
+      - instrumentation.js
+      - instrumentation.mjs
+      - instrumentation-client.ts
+      - instrumentation-client.js
+      - instrumentation-client.mjs
+      - next-env.d.ts
+    frameworkPinnedRootExports:
+      # Export names the framework mandates in a pinned root file, keyed by file stem (read by
+      # scripts/checks/architecture/framework-pinned.mjs). FE_SOURCE_NAME_SHAPE accepts exactly these names in exactly
+      # these files when they sit directly in a Next source root; everywhere else the name-shape rule is unchanged.
+      middleware: [config, middleware, default]
+      proxy: [config, proxy, default]
+      instrumentation: [register, onRequestError]
+      instrumentation-client: [onRouterTransitionStart]
+    rationale: |
+      One fixed source root per app keeps every repository the same shape while preventing app helpers, component-local
+      hooks and feature-local transport buckets from becoming undeclared owners.
+    cases:
+      - id: case-1
+        when: "A routed authentication scenario"
+        write: "apps/<app>/src/features/pages/AuthenticationPage/index.tsx"
+      - id: case-2
+        when: "A reusable API client, reader or session capability"
+        write: >
+          apps/<app>/src/modules/api/ or apps/<app>/src/modules/session/ with one explicit public index.ts entry
+      - id: case-3
+        when: "A reusable product visual without scenario ownership"
+        write: "apps/<app>/src/components/{blocks,composites,branches,leaves}/<Name>/index.tsx"
+      - id: case-4
+        when: "A React hook"
+        write: "apps/<app>/src/hooks/<domain>/useAutoScroll.ts; built-in React hook calls may remain in visuals"
+      - id: case-5
+        kind: exception
+        when: "Next.js only loads the file from the source root (proxy, instrumentation, instrumentation-client, next-env.d.ts)"
+        write: >
+          apps/<app>/src/proxy.ts beside apps/<app>/src/app/ as a thin adapter; locale routing logic lives in
+          apps/<app>/src/modules/i18n/ and the adapter imports it; the names the framework mandates there
+          (frameworkPinnedRootExports, for example export const config = { matcher }) keep their framework spelling
+      - id: case-6
+        when: "Any other file or folder directly under the source root (apps/<app>/src/i18n/request.ts, apps/<app>/src/config.ts), and a repository-root src/"
+        write: >
+          Move it to its owner, for example apps/<app>/src/modules/i18n/request.ts, and point framework configuration
+          (apps/<app>/next.config.ts) at the new path
+      - id: case-7
+        when: "The per-slot data-status recipe"
+        write: >
+          apps/<app>/src/components/composites/SlotView/index.tsx, apps/<app>/src/modules/slot/index.ts (Slot, toSlot,
+          SlotLabels) and apps/<app>/src/hooks/slot/useSlotLabels.ts, one copy each (examples/shape-slot)
+    verification:
+      automated:
+        - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_REQUIRED_MISSING
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_NEXT_CONVENTIONS
+        - FE_TIER_DIRECTION
+        - FE_CUSTOM_HOOK_LOCATION
+        - HFS_APPS_REQUIRED
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+      manual:
+        - Confirm the unit's responsibility and public entry, rather than assigning it by consumer count.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-2
+    title: Discoverable files for one unit
+    kind: mandatory
+    hfsRules: [R02, R55, R65]
+    requirement: |
+      A split unit (a connected block, and a feature page, layout or overlay) uses index.tsx for the connected X and
+      sibling component.tsx for the pure XBase, its XBaseProps and xDefaultState, plus XState when the shape is its own union
+      (a shape that is a domain status is typed with that status, never a second name for it). Only that index.tsx and the
+      unit's specs import component.tsx. Pure blocks, composites, branches and leaves use index.tsx only and never gain an
+      empty twin. classNames.ts is present only when the unit owns class strings. Budgets: component.tsx 300 lines,
+      connected index.tsx 200 lines, at most 6 data hooks and 6 useState per connected unit.
+    rationale: |
+      Stable basenames make class, tests and the connected and presentational split discoverable without forwarding
+      twins, and budgets keep a unit reviewable.
+    cases:
+      - id: case-1
+        when: "Connected block with product-world lifecycle"
+        write: "blocks/CatalogBlock/{index.tsx,component.tsx}; every nonempty index render reaches the sibling"
+      - id: case-2
+        when: "Feature page, layout or overlay"
+        write: >
+          features/pages/OperatePage/{index.tsx,component.tsx,classNames.ts}, features/layouts/WorkspaceLayout/…,
+          features/overlays/SendHandoffOverlay/… (examples/shape-slot)
+      - id: case-3
+        when: "Single visual unit"
+        write: "leaves/ButtonStateSample/{classNames.ts,index.tsx}; no component.tsx twin without a separate world owner"
+      - id: case-4
+        when: "Custom hook or reusable module"
+        write: "hooks/<domain>/useX.ts or modules/<capability>/...; do not create visual twins"
+    verification:
+      automated:
+        - class-names-in-colocated-file
+        - no-inline-class-name
+        - FE_CONNECTED_BLOCK_RENDER_PAIR
+        - FE_SIZE_AND_STATE_BUDGET
+        - HFS_SIZE_GROWTH
+        - starci-fe/base-import-pair
+      manual:
+        - Confirm each file owns a real responsibility; do not add a component.tsx twin by habit.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-3
+    title: Route files adapt to one visual owner and every app has its boundaries
+    kind: mandatory
+    hfsRules: [R53, R54, R55, R57]
+    requirement: |
+      Route files under app/[locale]/ (page, layout, template, loading, not-found) are server components. A route may
+      resolve framework server inputs (params, searchParams, headers, cookies), then mounts one page-level visual owner.
+      A route whose complete responsibility is redirect or notFound mounts none. A route file holds no inline component, no
+      drawing decision and no hook, and a redirect from an old URL lives in next.config redirects(), never in a page. Every app has
+      app/global-error.tsx, app/[locale]/layout.tsx, app/[locale]/error.tsx and app/[locale]/not-found.tsx, and a loading.tsx
+      for each route group that reads data. Each page exports generateMetadata. force-dynamic on a client page is forbidden.
+    rationale: |
+      Keeping default exports in the App Router layer prevents components from becoming route-coupled, and mandatory
+      boundaries turn a render failure into a recoverable screen instead of a blank page.
+    cases:
+      - id: case-1
+        when: "A route"
+        write: >
+          app/[locale]/authentication/page.tsx: const AuthenticationRoute = async () => <AuthenticationPage />, then export
+          default AuthenticationRoute
+      - id: case-2
+        kind: exception
+        when: "Redirect or notFound adapter"
+        write: "Resolve framework inputs and redirect or terminate without a visual owner."
+      - id: case-3
+        when: "Global app files"
+        write: >
+          app/globals.css, app/global-error.tsx, app/[locale]/error.tsx, app/[locale]/not-found.tsx, app/sitemap.ts,
+          app/robots.ts, app/health/{live,ready}/route.ts
+    verification:
+      automated:
+        - FE_ERROR_BOUNDARY_MISSING
+        - FE_ROUTE_FILES_THIN
+        - FE_CLIENT_BOUNDARY
+        - FE_OWNER_REACHABLE
+        - FE_TIER_DIRECTION
+      manual:
+        - Confirm visual routes have one page owner and redirect-only routes have no visual tree.
+    relatedExamples: []
+
+  - id: FE-FOLDER-4
+    title: Hooks are hooks; readers and transport live in modules
+    kind: mandatory
+    hfsRules: [R56, R50, R49]
+    requirement: |
+      hooks/<domain>/ holds React hooks (use*.ts, one hook per file) and exactly one <domain>.shared.ts for shared
+      non-hook helpers of that domain (key builders, token readers). A file in hooks/ that is not a hook and is not the shared
+      file is a finding. Server-side readers (fetch and map, no React) live in modules/api/<domain>/read-*.ts and are
+      wrapped in React cache() when several blocks call them in one request. Generic client plumbing, the Outcome type,
+      the contract copy and generated wire types live in modules/api; environment reading lives in modules/config; every
+      href builder lives in modules/routes; locale routing lives in modules/i18n; colour values live in modules/brand.
+      A helper name defined twice across hook files is a finding.
+    rationale: |
+      A rule that says what a hooks folder is also says where everything else goes, so nobody copies a helper sixteen
+      times or fills hooks/ with server fetch functions.
+    cases:
+      - id: case-1
+        when: "Authentication request lifecycle"
+        write: "apps/<app>/src/hooks/authentication/useAuthentication.ts"
+      - id: case-2
+        when: "A helper shared by the hooks of one domain"
+        write: "apps/<app>/src/hooks/sales/sales.shared.ts, for example useSalesAccessToken's token reader"
+      - id: case-3
+        when: "A server read used by several blocks"
+        write: "apps/<app>/src/modules/api/sales/read-sales-summary.ts, exported through modules/api/index.ts"
+      - id: case-4
+        when: "The API client"
+        write: "apps/<app>/src/modules/api/client.ts and apps/<app>/src/modules/api/outcome.ts"
+      - id: case-5
+        when: "Intrinsic custom helper"
+        write: "apps/<app>/src/hooks/ui/useAutoScroll.ts; direct useRef and useState calls may remain in their visual owner"
+    verification:
+      automated:
+        - FE_HOOKS_ARE_HOOKS
+        - FE_CUSTOM_HOOK_LOCATION
+        - HFS_DUPLICATE_CODE
+        - FE_TIER_DIRECTION
+      manual:
+        - Confirm each lifecycle has one feature owner and transport mechanics have one module owner.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-5
+    title: Package unit
+    kind: mandatory
+    hfsRules: [R63]
+    requirement: |
+      A shared package is packages/<pkg>/ with package.json (explicit exports), src/index.ts, tsconfig.json and colocated
+      specs, built to dist. Grammar components live under packages/grammar/src/core/<tier>/<Name>/ with collocated class
+      strings and specs; family entries and built-output proof stay at the package roots. See packages.yaml for the shared
+      UI package shape.
+    rationale: |
+      Package layout separates primitives from app composition and keeps public entry verification against dist.
+    cases:
+      - id: case-1
+        when: "A Grammar component"
+        write: "packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx"
+      - id: case-2
+        when: "A Grammar component's class strings and spec"
+        write: "sibling classNames.ts and index.spec.tsx"
+      - id: case-3
+        when: "Built-output proof"
+        write: "common/index.test.mjs, core/index.test.mjs, package-boundary.test.mjs (node:test against dist/)"
+    verification:
+      automated:
+        - FE_PACKAGE_SHAPE
+      manual:
+        - Verify public app imports use @starci/grammar/common and installed exports, never the package root.
+    relatedExamples: []
+
+  - id: FE-FOLDER-6
+    title: Keep units cohesive
+    kind: mandatory
+    hfsRules: [R49, R21]
+    requirement: |
+      A unit folder contains files that change for the same responsibility. Do not create generic helpers/ or utils/
+      buckets inside components, read deployment configuration in presentation, or split files solely to meet a count.
+      Collocated subordinate renders and pure helpers are valid when they remain private to the owner; a separately stable
+      responsibility receives its own named owner.
+    rationale: |
+      Cohesion prevents helper sprawl and duplicated configuration while avoiding one-component-per-folder ceremony that
+      has no dependency boundary.
+    cases:
+      - id: case-1
+        when: "A small subordinate render is private to one owner"
+        write: "Keep it local with an unexported contract; extract it when it gains a stable public responsibility."
+      - id: case-2
+        when: "Class strings in component.tsx"
+        write: "Never; they go to classNames.ts (lint class-names-in-colocated-file, no-inline-class-name)"
+      - id: case-3
+        when: "A helpers/ or utils/ folder"
+        write: "Do not use it to hide mixed feature, transport or visual responsibilities."
+      - id: case-4
+        when: "A deployment constant"
+        write: >
+          Never. process.env.NEXT_PUBLIC_* is read only in apps/<app>/src/modules/config and reached through that module,
+          with no localhost fallback; a missing value in production throws when the module loads.
+    verification:
+      automated:
+        - FE_ENV_OWNER
+        - class-names-in-colocated-file
+        - no-inline-class-name
+        - no-helper-folder-in-components
+      manual:
+        - Confirm extraction is justified by ownership or lifecycle rather than file length or count.
+    relatedExamples: []

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