@starci/eslint-canon-fe 8.2.17 → 8.3.0

package/runtime/scripts/hfs/architecture/frontend-block-render.mjs

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { normalizedSymbolValue } from './ast-walks.mjs';
+import { unwrapExpression } from './typescript.mjs';
+
+/** Feature composition may inject block renders into a pure view without making the view a world owner. */
+export class BlockRenderAnalysis {
+  constructor(renderer) {
+    this.renderer = renderer;
+    this.world = renderer.world;
+  }
+
+  featureComposition(expression, expectedFile) {
+    const file = expression?.getSourceFile().fileName;
+    return Boolean(file && !expectedFile && this.world.insideAny(this.world.roots.features, file)
+      && path.basename(file) === 'index.tsx');
+  }
+
+  renderProp(expression, checker, expectedFile) {
+    return this.featureComposition(expression, expectedFile) && this.renderValue(expression, checker);
+  }
+
+  blockTarget(expression, checker) {
+    const functions = this.world.expressionFunctions(expression, checker);
+    return functions.length > 0 && functions.every(fn => {
+      const file = fn.getSourceFile().fileName;
+      return this.world.sourceSet.has(path.resolve(file)) && path.basename(file) === 'index.tsx'
+        && this.world.tierOf(this.world.roots.components, file)?.tier === 'blocks'
+        && this.renderer.functionHasRender(fn, checker);
+    });
+  }
+
+  callbacksRender(functions, checker, seen) {
+    return functions.length > 0 && functions.every(fn => {
+      const values = this.renderer.helpers.returnedExpressions(this.world.ts, fn);
+      return !this.world.functionUsesWorld(fn, checker) && values.length > 0
+        && values.every(value => this.renderValue(value, checker, seen));
+    });
+  }
+
+  renderValue(input, checker, seen = new Set()) {
+    const ts = this.world.ts;
+    const value = unwrapExpression(ts, input);
+    if (!value) return false;
+    if (value.kind === ts.SyntaxKind.NullKeyword || value.kind === ts.SyntaxKind.FalseKeyword) return true;
+    if (ts.isConditionalExpression(value)) return this.renderValue(value.whenTrue, checker, seen)
+      && this.renderValue(value.whenFalse, checker, seen);
+    if (ts.isBinaryExpression(value) && value.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken)
+      return this.renderValue(value.right, checker, seen);
+    if (ts.isArrayLiteralExpression(value)) return value.elements.every(item => this.renderValue(item, checker, seen));
+    if (ts.isJsxFragment(value)) return this.fragmentBlocks(value, checker, seen);
+    if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value)) return this.jsxBlock(value, checker, seen);
+    if (ts.isCallExpression(value)) return this.createdBlock(value, checker, seen) || this.mappedBlocks(value, checker, seen);
+    if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) return this.callbacksRender([value], checker, seen);
+    return this.referencedBlocks(value, checker, seen);
+  }
+
+  fragmentBlocks(value, checker, seen) {
+    const ts = this.world.ts;
+    return value.children.every(child => {
+      if (ts.isJsxText(child)) return !child.text.trim();
+      return this.renderValue(ts.isJsxExpression(child) ? child.expression : child, checker, seen);
+    });
+  }
+
+  jsxBlock(value, checker, seen) {
+    const ts = this.world.ts;
+    const opening = ts.isJsxElement(value) ? value.openingElement : value;
+    if (!this.blockTarget(opening.tagName, checker)) return false;
+    const boundary = { hasBoundary: true };
+    return this.renderer.jsxChildrenBoundary(value, opening, checker, seen, null, false, boundary)
+      && this.renderer.jsxAttributesBoundary(opening, checker, seen, null, boundary);
+  }
+
+  mappedBlocks(value, checker, seen) {
+    const ts = this.world.ts;
+    const callee = unwrapExpression(ts, value.expression);
+    if (!ts.isPropertyAccessExpression(callee) && !ts.isElementAccessExpression(callee)) return false;
+    let name = ts.isPropertyAccessExpression(callee) ? callee.name.text : null;
+    if (name === null && ts.isStringLiteralLike(callee.argumentExpression)) name = callee.argumentExpression.text;
+    return name === 'map' && value.arguments.length > 0
+      && this.callbacksRender(this.world.expressionFunctions(value.arguments[0], checker), checker, seen);
+  }
+
+  createdBlock(value, checker, seen) {
+    const ts = this.world.ts;
+    if (!this.renderer.isCreateElement(value, checker) || !value.arguments[0]
+      || !this.blockTarget(value.arguments[0], checker)) return false;
+    const boundary = { hasBoundary: true };
+    const props = value.arguments[1] ? unwrapExpression(ts, value.arguments[1]) : null;
+    return this.renderer.createElementPropsBoundary(props, checker, seen, null, boundary, false)
+      && value.arguments.slice(2).every(child => this.renderer.renderBoundary(child, checker, seen));
+  }
+
+  referencedBlocks(value, checker, seen) {
+    const ts = this.world.ts;
+    const symbol = normalizedSymbolValue(ts, checker, this.renderer.helpers.selectedSymbol(ts, checker, value));
+    if (!symbol || seen.has(symbol)) return false;
+    const nextSeen = new Set(seen).add(symbol);
+    const values = (symbol.getDeclarations?.() ?? []).flatMap(declaration => ts.isVariableDeclaration(declaration)
+      && declaration.initializer ? [declaration.initializer] : []);
+    if (values.length) return values.every(item => this.renderValue(item, checker, nextSeen));
+    return this.callbacksRender(this.world.expressionFunctions(value, checker), checker, nextSeen);
+  }
+}

package/runtime/scripts/hfs/architecture/frontend-world-render.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { normalizedSymbolValue } from './ast-walks.mjs';
 import { relativePath, unwrapExpression } from './typescript.mjs';
+import { BlockRenderAnalysis } from './frontend-block-render.mjs';
 function importDeclarationFor(ts, node) {
   for (let current = node; current; current = current.parent) if (ts.isImportDeclaration(current)) return current;
   return null;
@@ -41,12 +42,14 @@ export class WorldRenderAnalysis {
   constructor(world, helpers) {
     this.world = world;
     this.helpers = helpers;
+    this.blocks = new BlockRenderAnalysis(this);
   }
 
   expressionHasRender(expression, checker, seen = new Set()) {
     expression = unwrapExpression(this.world.ts, expression);
     if (!expression) return false;
     if (this.world.ts.isJsxElement(expression) || this.world.ts.isJsxSelfClosingElement(expression) || this.world.ts.isJsxFragment(expression)) return true;
+    if (this.world.ts.isArrayLiteralExpression(expression)) return expression.elements.some(item => this.expressionHasRender(item, checker, seen));
     if (this.world.ts.isCallExpression(expression) && isReactCreateElement(this.world.ts, checker, expression)) return true;
     if (this.world.ts.isConditionalExpression(expression)) return this.conditionalExpressionHasRender(expression, checker, seen);
     const logicalRender = this.logicalExpressionHasRender(expression, checker, seen);
@@ -148,6 +151,22 @@ export class WorldRenderAnalysis {
       || this.world.expressionFunctions(expression, checker).some(fn => this.functionHasRender(fn, checker));
   }
 
+  isCreateElement(expression, checker) {
+    return isReactCreateElement(this.world.ts, checker, expression);
+  }
+
+  propValueBoundary(input, checker, seen, expectedFile, pureTarget) {
+    const ts = this.world.ts;
+    const value = unwrapExpression(ts, input);
+    if (pureTarget && this.blocks.renderProp(value, checker, expectedFile)) return true;
+    if (pureTarget && this.blocks.featureComposition(value, expectedFile) && ts.isObjectLiteralExpression(value)) {
+      return value.properties.every(property => !ts.isPropertyAssignment(property)
+        || this.propValueBoundary(property.initializer, checker, seen, expectedFile, pureTarget));
+    }
+    return !this.expressionSuppliesRender(value, checker) || this.pureRenderTarget(value, checker, expectedFile)
+      || this.renderBoundary(value, checker, seen, true, expectedFile);
+  }
+
   routedLayoutChild(opening, child, checker) {
     const ts = this.world.ts;
     if (!ts.isJsxExpression(child) || !child.expression) return false;
@@ -216,7 +235,7 @@ export class WorldRenderAnalysis {
     if (!pureTarget && !wrapper) return false;
     const boundary = { hasBoundary: pureTarget };
     const props = expression.arguments[1] ? unwrapExpression(ts, expression.arguments[1]) : null;
-    if (!this.createElementPropsBoundary(props, checker, seen, expectedFile, boundary)) return false;
+    if (!this.createElementPropsBoundary(props, checker, seen, expectedFile, boundary, pureTarget)) return false;
     const children = expression.arguments.slice(2);
     if (children.length) {
       if (!children.every(child => this.renderBoundary(child, checker, seen, false, expectedFile))) return false;
@@ -225,19 +244,19 @@ export class WorldRenderAnalysis {
     return boundary.hasBoundary;
   }
 
-  createElementPropsBoundary(props, checker, seen, expectedFile, boundary) {
+  createElementPropsBoundary(props, checker, seen, expectedFile, boundary, pureTarget) {
     const ts = this.world.ts;
     if (!props || props.kind === ts.SyntaxKind.NullKeyword) return true;
     if (!ts.isObjectLiteralExpression(props) || props.properties.some(property => ts.isSpreadAssignment(property))) return false;
-    return props.properties.every(property => this.propsPropertyBoundary(property, checker, seen, expectedFile, boundary));
+    return props.properties.every(property => this.propsPropertyBoundary(property, checker, seen, expectedFile, boundary, pureTarget));
   }
 
-  propsPropertyBoundary(property, checker, seen, expectedFile, boundary) {
+  propsPropertyBoundary(property, checker, seen, expectedFile, boundary, pureTarget) {
     const ts = this.world.ts;
     if (!ts.isPropertyAssignment(property)) return true;
     const value = unwrapExpression(ts, property.initializer);
+    if (!this.propValueBoundary(value, checker, seen, expectedFile, pureTarget)) return false;
     if (!this.expressionSuppliesRender(value, checker)) return true;
-    if (!this.pureRenderTarget(value, checker, expectedFile) && !this.renderBoundary(value, checker, seen, true, expectedFile)) return false;
     const name = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
     if (['children', 'component', 'content', 'render', 'view'].includes(name)) boundary.hasBoundary = true;
     return true;
@@ -270,7 +289,7 @@ export class WorldRenderAnalysis {
     if (!pureTarget && !wrapper) return false;
     const boundary = { hasBoundary: pureTarget };
     if (!this.jsxChildrenBoundary(expression, opening, checker, seen, expectedFile, pureTarget, boundary)) return false;
-    if (!this.jsxAttributesBoundary(opening, checker, seen, expectedFile, boundary)) return false;
+    if (!this.jsxAttributesBoundary(opening, checker, seen, expectedFile, boundary, pureTarget)) return false;
     return boundary.hasBoundary;
   }
 
@@ -286,13 +305,13 @@ export class WorldRenderAnalysis {
     return true;
   }
 
-  jsxAttributesBoundary(opening, checker, seen, expectedFile, boundary) {
+  jsxAttributesBoundary(opening, checker, seen, expectedFile, boundary, pureTarget = false) {
     const ts = this.world.ts;
     return opening.attributes.properties.every(attribute => !ts.isJsxAttribute(attribute) || !attribute.initializer
-      || this.jsxAttributeBoundary(attribute, checker, seen, expectedFile, boundary));
+      || this.jsxAttributeBoundary(attribute, checker, seen, expectedFile, boundary, pureTarget));
   }
 
-  jsxAttributeBoundary(attribute, checker, seen, expectedFile, boundary) {
+  jsxAttributeBoundary(attribute, checker, seen, expectedFile, boundary, pureTarget) {
     const ts = this.world.ts;
     const name = attribute.name.text;
     if (['fallback', 'errorElement'].includes(name)) {
@@ -300,10 +319,10 @@ export class WorldRenderAnalysis {
       if (ts.isJsxExpression(attribute.initializer)
         && !this.renderBoundary(attribute.initializer.expression, checker, seen, true, expectedFile)) return false;
     }
+    if (ts.isJsxExpression(attribute.initializer) && attribute.initializer.expression
+      && !this.propValueBoundary(attribute.initializer.expression, checker, seen, expectedFile, pureTarget)) return false;
     if (ts.isJsxExpression(attribute.initializer) && attribute.initializer.expression
       && this.expressionSuppliesRender(attribute.initializer.expression, checker)) {
-      if (!this.pureRenderTarget(attribute.initializer.expression, checker, expectedFile)
-        && !this.renderBoundary(attribute.initializer.expression, checker, seen, true, expectedFile)) return false;
       if (['component', 'content', 'render', 'view'].includes(name)) boundary.hasBoundary = true;
     }
     return true;

package/runtime/scripts/hfs/architecture/i18n-keys.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { escapeRegExp } from '../../lib/regex.mjs';
 
 /**
  * R106 `i18n-keys` (FE_I18N_KEYS). The catalogs of an app (`apps/<app>/src/modules/i18n/messages/<locale>.json`, slot fe.modules.i18n) and
@@ -12,7 +13,7 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *     own source (both branches of a conditional key are read). A key no locale's catalog holds is FE_I18N_KEYS, once per call. A computed
  *     key (a template with an interpolation, a variable) is not judged here; it counts as a read.
  *   - a key nobody reads is dead: a leaf of the app's catalogs that no string in the app's or the shared packages' source can be reading.
- *     A leaf counts as read when a string literal or a template pattern (each interpolation a wildcard segment) of that source equals a
+ *     A leaf counts as read when a string literal or a template pattern (each interpolation a wildcard within its dotted segment) equals a
  *     tail of its dotted path (`"title"`, `"card.title"`, `"orders.card.title"` all read `orders.card.title`); the test is deliberately loose
  *     so a key handed through props or a table of keys is never reported, and only a key that appears nowhere is.
  *
@@ -39,7 +40,10 @@ const held = (leaves, full) => leaves.has(full) || [...leaves].some(leaf => leaf
 
 // A pattern that is only wildcards (`${a}`, `${a}.${b}`) names nothing: it would read every key, so it reads none.
 const tailMatches = (pattern, leafSegments) => pattern.some(segment => segment !== '*' && segment !== '') && pattern.length <= leafSegments.length
-  && pattern.every((segment, index) => segment === '*' || segment === leafSegments[leafSegments.length - pattern.length + index]);
+  && pattern.every((segment, index) => {
+    const leaf = leafSegments[leafSegments.length - pattern.length + index];
+    return segment instanceof RegExp ? segment.test(leaf) : segment === '*' || segment === leaf;
+  });
 
 function catalogsPerApp(config, graph) {
   const catalogs = new Map();
@@ -56,12 +60,21 @@ function catalogsPerApp(config, graph) {
   return catalogs;
 }
 
+/** Each interpolation can fill part or all of a segment; the template's static fragments keep their literal spelling. */
+function templatePatternOf(node) {
+  return [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.').map(segment => {
+    if (!segment.includes('\u0000')) return segment;
+    const parts = segment.split('\u0000');
+    return parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map(escapeRegExp).join('.*')}$`, 'su');
+  });
+}
+
 function patternsOf(ts, files) {
   const patterns = [];
   for (const file of files) {
     const visit = node => {
       if (ts.isStringLiteralLike(node)) patterns.push(node.text.split('.'));
-      else if (ts.isTemplateExpression(node)) patterns.push([node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').replaceAll('\u0000', '*').split('.'));
+      else if (ts.isTemplateExpression(node)) patterns.push(templatePatternOf(node));
       ts.forEachChild(node, visit);
     };
     visit(file.sourceFile);

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

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { canonical } from './config.mjs';
 import { hasAnyFlag, sourceLocation } from '../../lib/ts-ast.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const HELPER_DEPTH = 4;
 
@@ -110,6 +111,21 @@ const at = (env, rel, sourceFile, node, extra = {}) => ({ path: rel, ...sourceLo
 /** The app root file of an app (apps/<name>/src/app.module.ts), or null when the program does not hold it. */
 const appRoot = (env, name) => graphFile(env, `apps/${name}/src/app.module.ts`);
 
+/**
+ * Whether a repository-relative file is a composition group of an app: `apps/<app>/src/compose/<area>.ts`, the module list of
+ * one area that the app root spreads into its imports (slot allows `compose/<area>.ts` of every be.app.* slot).
+ */
+export const isComposeGroup = rel => /^apps\/[^/]+\/src\/compose\/[^/]+\.ts$/.test(rel) && !/\.(?:spec|d)\.ts$/.test(rel);
+
+/** The app root and the composition groups of an app, in path order (the root first); [] when the program holds no root. */
+const appCompositionFiles = (env, name) => {
+  const root = appRoot(env, name);
+  if (!root) return [];
+  const prefix = `apps/${name}/src/compose/`;
+  const groups = [...env.graph.files.values()].filter(file => file.rel.startsWith(prefix) && isComposeGroup(file.rel));
+  return [root, ...groups.sort((a, b) => byCodeUnit(a.rel, b.rel))];
+};
+
 /** The body a call or a spread identifier resolves to when it is a function or a const declared in a file of the program (not a package), else null. */
 function helperBodyOf(env, checker, node) {
   const { ts } = env;
@@ -200,6 +216,7 @@ export function machineKit({ context, graph }) {
     valueOfProperty: bound(valueOfProperty),
     at: bound(at),
     appRoot: bound(appRoot),
+    appCompositionFiles: bound(appCompositionFiles),
   };
 }
 

package/runtime/scripts/hfs/architecture/module-per-transport.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { machineKit } from './machine-ast.mjs';
+import { isComposeGroup, machineKit } from './machine-ast.mjs';
 import { treeOf } from './required-files.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { trimTrailingSlashes } from '../trailing-slashes.mjs';
@@ -13,8 +13,9 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
  *     anywhere in a feature, and an `@Module` class (or a `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a
  *     feature file that is neither the application module nor the transport module of its own folder are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
- *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root that
- *     lists a feature's application module, or the transport module of another kind, is refused;
+ *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts
+ *     or a composition group of its compose/ folder) that lists a feature's application module, or the transport module
+ *     of another kind, is refused;
  *   - a composed root (an owner slot with `composedBy`, be.cli) holds one static module per folder, named after the folder
  *     (cli.module.ts, <group>/<group>.module.ts); an app of a composing kind lists the root module only, and an app of any
  *     other kind lists none of its modules.
@@ -22,7 +23,6 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
 export const MODULE_PER_TRANSPORT_RULE_IDS = ['BE_MODULE_SHAPE'];
 
 const RULE = 'BE_MODULE_SHAPE';
-const APP_ROOT_FILE = 'app.module.ts';
 
 function featureOwnerOf(resolver, rel) {
   const owner = resolver.ownerOf(rel);
@@ -152,28 +152,37 @@ function inspectModuleDeclarations(checker, target, node, root, app, scan, seen)
   return references;
 }
 
-function inspectAppRoot(app, scan) {
-  const { graph, kit, ts } = scan;
-  const root = graph.files.get(`apps/${app.name}/src/${APP_ROOT_FILE}`);
-  if (!root) return 0;
-  const checker = kit.checkerOf(root.sourceFile);
-  const seen = new Set();
+/** The module references of one composition file: the root's `imports` lists, or every array of a composition group (its module list). */
+function inspectCompositionFile(file, app, scan, seen) {
+  const { kit, ts } = scan;
+  const checker = kit.checkerOf(file.sourceFile);
+  const group = isComposeGroup(file.rel);
   let references = 0;
   const judge = node => {
     const call = ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register';
     if (ts.isCallExpression(node) && !call) return;
     const target = call ? node.expression.expression : node;
-    references += inspectModuleDeclarations(checker, target, node, root, app, scan, seen);
+    references += inspectModuleDeclarations(checker, target, node, file, app, scan, seen);
   };
-  kit.walk(root.sourceFile, node => {
+  kit.walk(file.sourceFile, node => {
     if (ts.isPropertyAssignment(node) && kit.propertyNameText(node.name) === 'imports' && ts.isArrayLiteralExpression(node.initializer)) {
       for (const element of node.initializer.elements) judge(element);
+    } else if (group && ts.isArrayLiteralExpression(node)) {
+      for (const element of node.elements) judge(element);
     } else if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register') judge(node);
     return true;
   });
   return references;
 }
 
+/** The module references of an app: its root `apps/<app>/src/app.module.ts` and the composition groups of `compose/` it spreads. */
+function inspectAppRoot(app, scan) {
+  const seen = new Set();
+  let references = 0;
+  for (const file of scan.kit.appCompositionFiles(app.name)) references += inspectCompositionFile(file, app, scan, seen);
+  return references;
+}
+
 function appModuleReferences(apps, scan) {
   let references = 0;
   for (const app of apps) references += inspectAppRoot(app, scan);

package/runtime/scripts/hfs/architecture/register-once.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { machineKit } from './machine-ast.mjs';
+import { isComposeGroup, machineKit } from './machine-ast.mjs';
 import { callName } from './supabase-ast.mjs';
 import { isTestWorldSlot } from '../test-world-slot.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
@@ -7,7 +7,8 @@ import { byCodeUnit } from '../../lib/list.mjs';
 /**
  * R45 `register-once` (BE_MODULE_SHAPE), the module graph read from the app roots (owner rule of 2026-09-30, the
  * reference's `CodingModule imports DeviceModule` shape). Each capability has one representative module: the only module
- * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`.
+ * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`, or in a
+ * composition group `apps/<app>/src/compose/<area>.ts` the root spreads (an app root here means the root and its groups).
  * It may split itself into sub-modules imported as plain `imports: [Sub]`; a sub-module is never in an app and has one
  * importer, its parent. Over every `@Module` class of the program:
  *
@@ -57,6 +58,7 @@ function enclosingModule(ts, modules, node) {
 /** Records the reference an element of an imports list, or a register call, makes to a module. */
 function noteReference(scan, element, viaImports) {
   const { ts, kit, modules, checker, file, seen, references, isAppRoot } = scan;
+  if (seen.has(element)) return;
   const call = callName(ts, element) === 'register';
   if (ts.isCallExpression(element) && !call) return;
   const target = targetOf(kit, modules, checker, call ? element.expression.expression : element);
@@ -72,14 +74,19 @@ const isImportsList = (scan, node) => scan.ts.isPropertyAssignment(node) && scan
 const isStrayGlobal = (scan, node) => scan.ts.isPropertyAssignment(node) && scan.kit.propertyNameText(node.name) === 'isGlobal'
   && node.initializer.kind === scan.ts.SyntaxKind.TrueKeyword && !scan.isAppRoot(scan.file) && !scan.isWorld(scan.file);
 
+// A composition group's module list is any array of the group: the root spreads it into its imports.
+const isGroupList = (scan, node) => scan.ts.isArrayLiteralExpression(node) && isComposeGroup(scan.file.rel);
+
 function visitReferenceNode(scan, node) {
   if (isImportsList(scan, node)) {
     for (const element of node.initializer.elements) noteReference(scan, element, true);
+  } else if (isGroupList(scan, node)) {
+    for (const element of node.elements) noteReference(scan, element, true);
   } else if (callName(scan.ts, node) === 'register' && !scan.seen.has(node)) {
     noteReference(scan, node, false);
   }
   if (isStrayGlobal(scan, node)) {
-    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts), where the representative module of a capability is registered; a module never decides its own globality.');
+    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts or a group of apps/<app>/src/compose/), where the representative module of a capability is registered; a module never decides its own globality.');
   }
   return true;
 }
@@ -170,11 +177,12 @@ export function checkRegisterOnce(input) {
   const { ts } = 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 isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'app.module.ts';
+  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && (path.posix.basename(file.rel) === 'app.module.ts' || isComposeGroup(file.rel));
   // The test world (slot be.tests.world) is the test composition root: useTestWorld registers capability modules with
   // `isGlobal: true` the way an app root does. A spec (integration, contract, e2e) is not a composition root.
   const isWorld = file => isTestWorldSlot(file.slot);
-  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`)?.name ?? null;
+  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`
+    || (isComposeGroup(file.rel) && file.rel.startsWith(`apps/${app.name}/src/compose/`)))?.name ?? null;
   const modules = moduleDeclarations(graph, kit, ts);
   const references = moduleReferences(graph, kit, ts, modules, isWorld, isAppRoot, report);
   const rootReferences = references.filter(item => item.root);

package/runtime/scripts/hfs/architecture/required-files.mjs

@@ -4,6 +4,7 @@ import { lsFiles } from '../../api/git/ls-files.mjs';
 import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
 import { gitOutputOf } from '../../lib/git.mjs';
 import { trimTrailingSlashes } from '../trailing-slashes.mjs';
+import { requiredFileApplies } from '../slot-required.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
@@ -173,7 +174,7 @@ function requirementExists(tree, target) {
 }
 
 function reportMissingRequirement(requirement, tree, report) {
-  if (requirementExists(tree, requirement.target)) return;
+  if (requirementExists(tree, requirement.target) || !requiredFileApplies(requirement.slot, requirement.target, tree.files)) return;
   const rootExists = !requirement.root || tree.directories.has(requirement.root);
   if (!rootExists) {
     report(ruleFor(requirement.slot, requirement.target, false), requirement.root, requirement.slot, requirement.root, { kind: 'directory' },

package/runtime/scripts/hfs/architecture/staged-consumers.mjs

@@ -0,0 +1,37 @@
+import { catFile } from '../../api/git/cat-file.mjs';
+import { diff } from '../../api/git/diff.mjs';
+import { gitOutputOf } from '../../lib/git.mjs';
+
+/** Eligible additions, copies, edits and rename destinations in the index, read in one blob batch. */
+export function stagedConsumerSources(root, accept) {
+  try {
+    const options = { cwd: root, maxBuffer: 256 * 1024 * 1024 };
+    const files = gitOutputOf(diff(['--cached', '--relative', '--name-only', '--diff-filter=ACMR', '-z', '--', '.'], options))
+      .split('\0').filter(file => file && accept(file));
+    if (!files.length) return [];
+    // :./ keeps paths relative to this side's root even when git's top level is the parent app folder.
+    // -z terminates requests with NUL; output headers and blob trailers still use LF.
+    const bytes = gitOutputOf(catFile(['--batch', '-z'], {
+      ...options, encoding: null, input: files.map(file => `:./${file}\0`).join(''),
+    }));
+    if (!Buffer.isBuffer(bytes)) return [];
+    const sources = [];
+    let cursor = 0;
+    for (const file of files) {
+      const end = bytes.indexOf(10, cursor);
+      if (end < 0) return [];
+      const header = /^[0-9a-f]+ blob (\d+)$/u.exec(bytes.subarray(cursor, end).toString('utf8'));
+      if (!header) return []; // An index changed during the read: discard this supplement, keep disk consumers.
+      const size = Number(header[1]);
+      const start = end + 1;
+      const next = start + size;
+      if (!Number.isSafeInteger(size) || next >= bytes.length || bytes[next] !== 10) return [];
+      sources.push({ file, text: bytes.subarray(start, next).toString('utf8') });
+      cursor = next + 1;
+    }
+    return sources;
+  } catch {
+    // A non-git fixture (or an unavailable index) still uses the existing filesystem consumers.
+    return [];
+  }
+}

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

@@ -1,5 +1,7 @@
 // supabase-ast.mjs - shared TypeScript-symbol and expression helpers for the front-end and back-end Supabase
 // architecture checks. Recognition follows imported declarations and inferred types, never local spelling alone.
+import { unwrapExpression } from '../../lib/ts-analysis.mjs';
+
 export const SUPABASE_MODULES = new Set(['@supabase/ssr', '@supabase/supabase-js']);
 
 export const moduleNameOf = (ts, node) => {
@@ -38,12 +40,7 @@ const signatureFromSupabase = (checker, call) => {
   try { return declarationFromSupabase(checker.getResolvedSignature(call)?.declaration); } catch { return false; }
 };
 
-export const unwrap = (ts, node) => {
-  let current = node;
-  while (current && (ts.isParenthesizedExpression(current) || ts.isAwaitExpression(current) || ts.isAsExpression(current)
-    || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current))) current = current.expression;
-  return current;
-};
+export const unwrap = (ts, node) => unwrapExpression(ts, node, { awaitExpressions: true, satisfiesExpressions: false });
 
 const isSupabaseValue = (kit, checker, node) => {
   const current = unwrap(kit.ts, node);

package/runtime/scripts/hfs/architecture/supabase-be.mjs

@@ -3,6 +3,7 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { importedFrom, reportAt, unwrap } from './supabase-ast.mjs';
+import { accessName } from './backend-app-files.mjs';
 
 const BE_SUPABASE_SLOT = 'be.integrations.supabase';
 const BE_JWT_VERIFIED = 'BE_SUPABASE_JWT_VERIFIED';
@@ -47,12 +48,6 @@ const importedCall = (kit, checker, call) => {
   return owner?.name === 'default' ? { module: owner.module, name: call.expression.name.text } : null;
 };
 
-const accessName = (ts, node) => {
-  if (ts.isPropertyAccessExpression(node)) return node.name.text;
-  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
-  return null;
-};
-
 const requestLike = (ts, node) => {
   const current = unwrap(ts, node);
   if (ts.isIdentifier(current)) return /^(?:req|request)$/iu.test(current.text);

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

@@ -14,8 +14,15 @@ import { byCodeUnit } from '../../lib/list.mjs';
  */
 export const TIER_RULE_IDS = ['BE_TIER_DIRECTION', 'BE_FEATURE_IMPORTS_FEATURE', 'BE_KIND_ISOLATION', 'FE_TIER_DIRECTION', 'FE_APP_ISOLATION', 'ARCH_OWNER_CYCLE'];
 
+function tierDirectionText({ fromTier, toTier, mayImport, kindRestriction, fromKind, toKind }) {
+  if (!kindRestriction) return `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`;
+  const source = fromKind ?? 'no folder kind';
+  const target = toKind ?? 'no folder kind';
+  return `a ${fromTier} may import ${toTier} owners only from kinds ${kindRestriction.from.join(', ')} to kinds ${kindRestriction.to.join(', ')}; it imports ${source} -> ${target}`;
+}
+
 const REASON_TEXT = {
-  tierDirection: ({ fromTier, toTier, mayImport }) => `a ${fromTier} may import only ${mayImport.join(', ') || 'nothing'}; it imports a ${toTier}`,
+  tierDirection: tierDirectionText,
   layerOrder: ({ fromLayer, toLayer }) => `a ${fromLayer} component may import only the layers after it; it imports a ${toLayer}`,
   crossApp: ({ from, to }) => `app ${from} imports app ${to}; apps never import each other, shared code is a packages/<pkg> slot`,
 };

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

@@ -9,6 +9,7 @@ import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule
 import { readJsonFile } from '../../lib/json.mjs';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { locateDeclaration } from '../slots.mjs';
+export { unwrapExpression } from '../../lib/ts-analysis.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const SCRIPT_TAIL = '[cm]?[jt]sx?';
@@ -399,14 +400,6 @@ export function reachableViolation(edges, firstEdge, forbidden, { follow = () =>
 /** A framework identity the checkers cannot prove statically. */
 export const UNPROVEN_FRAMEWORK = '(unproven framework identity)';
 
-/** The expression under parentheses, type assertions, non-null and satisfies wrappers. */
-export function unwrapExpression(ts, expression) {
-  while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
-    || ts.isTypeAssertionExpression(expression) || ts.isNonNullExpression(expression)
-    || (ts.isSatisfiesExpression?.(expression) ?? false))) expression = expression.expression;
-  return expression;
-}
-
 /* ---- the AST walks every architecture checker shares ---- */
 
 /** The names of `expected` an import or re-export statement binds (all of them for a namespace or star form). */

package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs

@@ -4,6 +4,7 @@ import { machineKit } from './machine-ast.mjs';
 import { constructorDependencies } from './constructor-deps.mjs';
 import { treeOf } from './required-files.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { importsOf } from '../../lib/ts-analysis.mjs';
 
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
@@ -25,17 +26,6 @@ export const UNIT_SPEC_PROVIDERS_RULE_IDS = ['BE_SPEC_QUALITY'];
 const RULE = 'BE_SPEC_QUALITY';
 const SPEC_ROOT = /^(?:src|apps)\//u;
 
-/** local name -> {name, module} for every named import of a source file. */
-function importsOf(ts, sourceFile) {
-  const imports = new Map();
-  for (const statement of sourceFile.statements) {
-    const bindings = ts.isImportDeclaration(statement) ? statement.importClause?.namedBindings : null;
-    if (!bindings || !ts.isNamedImports(bindings)) continue;
-    for (const element of bindings.elements) imports.set(element.name.text, { name: (element.propertyName ?? element.name).text, module: statement.moduleSpecifier.text });
-  }
-  return imports;
-}
-
 /** The `Test.createTestingModule(...)` calls of a spec. */
 function testingModules(ts, sourceFile) {
   const calls = [];