@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/architecture/canon-clones.mjs

@@ -0,0 +1,240 @@
+/**
+ * The repeated shapes taught by the BE scaffold are wiring, not copied decisions. Match their imported
+ * ports and their small bodies, never a filename suffix or an entire decorated class: a custom method
+ * or an extra statement still goes through the clone check.
+ */
+import { nameText } from '../../lib/ts-ast.mjs';
+import { importsOf, unwrapExpression } from '../../lib/ts-analysis.mjs';
+import { nodeDecorators } from './ast-walks.mjs';
+import { canonJsxCloneNodes } from './canon-jsx-clones.mjs';
+
+const READ_METHODS = new Set(['find', 'findBy', 'findAndCount', 'findOne', 'findOneBy', 'findOneOrFail', 'findOneByOrFail']);
+
+const unwrap = (ts, node) => unwrapExpression(ts, node, { awaitExpressions: true, typeAssertions: false });
+
+const imported = (env, node, name, source) => {
+  if (!node || !env.ts.isIdentifier(node)) return false;
+  const binding = env.imports.get(node.text);
+  return binding?.name === name && binding.source === source;
+};
+
+const decoratorsHave = (env, node, name, source) => nodeDecorators(env.ts, node)
+  .some(decorator => imported(env, env.ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression, name, source));
+
+const portType = (env, node, name, source) => Boolean(node && env.ts.isTypeReferenceNode(node) && imported(env, node.typeName, name, source));
+
+/** Data moves between shapes here; operators, arbitrary calls and executable callbacks remain compared. */
+function mapping(env, input, allowCall = () => false) {
+  const { ts } = env;
+  const node = unwrap(ts, input);
+  if (!node) return false;
+  if (ts.isIdentifier(node) || ts.isLiteralExpression(node) || [ts.SyntaxKind.NullKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.ThisKeyword].includes(node.kind)) return true;
+  if (ts.isPropertyAccessExpression(node)) return mapping(env, node.expression, allowCall);
+  if (ts.isObjectLiteralExpression(node)) return node.properties.every(property => {
+    if (ts.isShorthandPropertyAssignment(property)) return !property.objectAssignmentInitializer;
+    if (ts.isSpreadAssignment(property)) return mapping(env, property.expression, allowCall);
+    return ts.isPropertyAssignment(property) && nameText(ts, property.name) !== null && mapping(env, property.initializer, allowCall);
+  });
+  if (ts.isArrayLiteralExpression(node)) return node.elements.every(item => mapping(env, ts.isSpreadElement(item) ? item.expression : item, allowCall));
+  return ts.isCallExpression(node) && allowCall(node);
+}
+
+const parameterNames = (ts, method) => new Set(method.parameters.filter(parameter => ts.isIdentifier(parameter.name)).map(parameter => parameter.name.text));
+const propertyParameters = (ts, constructor) => new Set((constructor?.parameters ?? []).filter(parameter => parameter.modifiers?.length && ts.isIdentifier(parameter.name)).map(parameter => parameter.name.text));
+const inertParameters = (ts, constructor) => constructor.parameters.every(parameter => ts.isIdentifier(parameter.name) && !parameter.initializer);
+
+function receiverMember(ts, call) {
+  if (!ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression)) return null;
+  const receiver = call.expression.expression;
+  return ts.isPropertyAccessExpression(receiver) && receiver.expression.kind === ts.SyntaxKind.ThisKeyword ? receiver.name.text : null;
+}
+
+const statementCall = (ts, statement) => (ts.isReturnStatement(statement) || ts.isExpressionStatement(statement)) ? unwrap(ts, statement.expression) : null;
+
+function delegation(env, method, statement, members, allowCall = () => false) {
+  const call = statementCall(env.ts, statement);
+  return Boolean(call && env.ts.isCallExpression(call) && members.has(receiverMember(env.ts, call))
+    && call.arguments.every(argument => mapping(env, argument, allowCall)));
+}
+
+function canonicalConstructor(env, constructor, logger = false) {
+  if (!constructor?.body || !inertParameters(env.ts, constructor)) return false;
+  if (!logger) return constructor.body.statements.length === 0;
+  const parameters = constructor.parameters.filter(parameter => decoratorsHave(env, parameter, 'InjectLogger', '@modules/platform/logging'));
+  if (parameters.length !== 1 || constructor.body.statements.length !== 1) return false;
+  const call = statementCall(env.ts, constructor.body.statements[0]);
+  return Boolean(call && env.ts.isCallExpression(call) && call.expression.kind === env.ts.SyntaxKind.SuperKeyword
+    && call.arguments.length === 1 && env.ts.isIdentifier(call.arguments[0]) && call.arguments[0].text === parameters[0].name.text);
+}
+
+function hasHeritage(env, declaration, name, source, kind) {
+  return declaration.heritageClauses?.some(clause => clause.token === kind && clause.types.some(type => imported(env, type.expression, name, source))) ?? false;
+}
+
+function fenceStatement(env, statement, claims, job) {
+  const call = statementCall(env.ts, statement);
+  if (!call || !env.ts.isCallExpression(call) || receiverMember(env.ts, call) !== claims || call.expression.name.text !== 'advance' || call.arguments.length !== 1) return false;
+  const options = unwrap(env.ts, call.arguments[0]);
+  if (!env.ts.isObjectLiteralExpression(options) || options.properties.length !== 3) return false;
+  const properties = new Map(options.properties.filter(env.ts.isPropertyAssignment).map(property => [nameText(env.ts, property.name), property.initializer]));
+  const jobField = (node, field) => env.ts.isPropertyAccessExpression(node) && env.ts.isIdentifier(node.expression) && node.expression.text === job && node.name.text === field;
+  return jobField(properties.get('jobId') ?? {}, 'jobId') && jobField(properties.get('expectedFencingToken') ?? {}, 'fencingToken')
+    && mapping(env, properties.get('step'));
+}
+
+function jobMethods(env, declaration, constructor, excluded) {
+  const claims = constructor?.parameters.find(parameter => portType(env, parameter.type, 'JobClaims', '@modules/platform/jobs')
+    && decoratorsHave(env, parameter, 'InjectJobClaims', '@modules/platform/jobs'));
+  if (!claims || !env.ts.isIdentifier(claims.name)) return;
+  const members = propertyParameters(env.ts, constructor);
+  const runKey = call => receiverMember(env.ts, call) === claims.name.text && call.expression.name.text === 'runKey'
+    && call.arguments.length === 2 && call.arguments.every(argument => mapping(env, argument));
+  for (const method of declaration.members) {
+    if (!env.ts.isMethodDeclaration(method) || nameText(env.ts, method.name) !== 'run' || !method.body || method.parameters.length !== 1
+      || !portType(env, method.parameters[0].type, 'ClaimedJob', '@modules/platform/jobs')) continue;
+    const statements = method.body.statements;
+    const job = [...parameterNames(env.ts, method)][0];
+    if (!statements.length || !fenceStatement(env, statements[0], claims.name.text, job)) continue;
+    if (statements.length === 1 || (statements.length === 2 && delegation(env, method, statements[1], members, runKey))) excluded.add(method);
+    else excluded.add(statements[0]);
+  }
+  if (canonicalConstructor(env, constructor)) excluded.add(constructor);
+}
+
+function queueMethods(env, declaration, constructor, excluded) {
+  const outbox = constructor?.parameters.find(parameter => portType(env, parameter.type, 'QueueOutbox', '@modules/platform/queue')
+    && decoratorsHave(env, parameter, 'InjectQueueOutbox', '@modules/platform/queue'));
+  if (!outbox || !env.ts.isIdentifier(outbox.name)) return;
+  for (const method of declaration.members) {
+    if (!env.ts.isMethodDeclaration(method) || !method.body || method.body.statements.length !== 1) continue;
+    const call = statementCall(env.ts, method.body.statements[0]);
+    if (call && env.ts.isCallExpression(call) && receiverMember(env.ts, call) === outbox.name.text && call.expression.name.text === 'write'
+      && call.arguments.length === 3 && call.arguments.every(argument => mapping(env, argument))) excluded.add(method);
+  }
+  if (canonicalConstructor(env, constructor)) excluded.add(constructor);
+}
+
+function rowMapper(env, call, row) {
+  const { ts } = env;
+  if (!call) return false;
+  if (ts.isObjectLiteralExpression(unwrap(ts, call))) return mapping(env, call, iso => ts.isPropertyAccessExpression(iso.expression)
+    && iso.expression.name.text === 'toISOString' && iso.arguments.length === 0 && mapping(env, iso.expression.expression));
+  if (!ts.isCallExpression(call) || call.arguments.length !== 1 || !ts.isIdentifier(call.arguments[0]) || call.arguments[0].text !== row || !ts.isIdentifier(call.expression)) return false;
+  const binding = env.imports.get(call.expression.text);
+  return Boolean(binding && /\.rows(?:\.[cm]?ts)?$/.test(binding.source)) || env.mappers.has(call.expression.text);
+}
+
+function readResult(env, expression, row) {
+  const { ts } = env;
+  const node = unwrap(ts, expression);
+  if (!node) return false;
+  if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'map'
+    && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === row && node.arguments.length === 1) {
+    const mapper = unwrap(ts, node.arguments[0]);
+    if (ts.isIdentifier(mapper)) return env.mappers.has(mapper.text) || /\.rows(?:\.[cm]?ts)?$/.test(env.imports.get(mapper.text)?.source ?? '');
+    return ts.isArrowFunction(mapper) && mapper.parameters.length === 1 && !ts.isBlock(mapper.body) && rowMapper(env, unwrap(ts, mapper.body), mapper.parameters[0].name.text);
+  }
+  if (!ts.isConditionalExpression(node)) return rowMapper(env, node, row);
+  const condition = unwrap(ts, node.condition);
+  const simpleNull = ts.isBinaryExpression(condition) && [ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(condition.operatorToken.kind)
+    && ts.isIdentifier(condition.left) && condition.left.text === row && condition.right.kind === ts.SyntaxKind.NullKeyword;
+  if (!(simpleNull || (ts.isIdentifier(condition) && condition.text === row))) return false;
+  return [node.whenTrue, node.whenFalse].every(branch => unwrap(ts, branch).kind === ts.SyntaxKind.NullKeyword || rowMapper(env, unwrap(ts, branch), row));
+}
+
+function readCall(env, call, managers) {
+  const { ts } = env;
+  if (!ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression) || !managers.has(receiverMember(ts, call))) return false;
+  if (READ_METHODS.has(call.expression.name.text)) return call.arguments.length <= 2 && call.arguments.every(argument => mapping(env, argument));
+  const sql = call.arguments[0];
+  return call.expression.name.text === 'query' && sql && ts.isIdentifier(sql) && /^(?:FIND|LIST)_/.test(sql.text)
+    && /\.sql(?:\.[cm]?ts)?$/.test(env.imports.get(sql.text)?.source ?? '') && call.arguments.every(argument => mapping(env, argument));
+}
+
+function ownedRead(env, statement) {
+  const { ts } = env;
+  const call = statementCall(ts, statement);
+  if (!call || !ts.isCallExpression(call) || !imported(env, call.expression, 'requireOwnedRow', '@modules/platform/database') || call.arguments.length !== 5) return false;
+  if (!call.arguments.slice(0, 4).every(argument => mapping(env, argument))) return false;
+  const callback = unwrap(ts, call.arguments[4]);
+  if (!ts.isArrowFunction(callback) || callback.parameters.length || !ts.isBlock(callback.body) || callback.body.statements.length !== 1) return false;
+  const thrown = callback.body.statements[0];
+  if (!ts.isThrowStatement(thrown) || !thrown.expression || !ts.isNewExpression(thrown.expression) || thrown.expression.arguments?.length !== 1) return false;
+  const options = thrown.expression.arguments[0];
+  if (!ts.isObjectLiteralExpression(options) || !mapping(env, options)) return false;
+  const code = options.properties.find(property => ts.isPropertyAssignment(property) && nameText(ts, property.name) === 'code');
+  return Boolean(code && ts.isPropertyAccessExpression(code.initializer) && code.initializer.name.text === 'NotFound');
+}
+
+function readMethods(env, declaration, constructor, excluded) {
+  const managers = new Set((constructor?.parameters ?? []).filter(parameter => portType(env, parameter.type, 'EntityManager', 'typeorm')
+    && nodeDecorators(env.ts, parameter).some(decorator => {
+      const call = env.ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+      const binding = env.ts.isIdentifier(call) ? env.imports.get(call.text) : null;
+      return binding?.source === '@modules/platform/database' && /^Inject.*EntityManager$/.test(binding.name);
+    })).map(parameter => parameter.name.text));
+  for (const method of declaration.members) {
+    if (!env.ts.isMethodDeclaration(method) || !method.body) continue;
+    const statements = method.body.statements;
+    if (statements.length === 1 && ownedRead(env, statements[0])) { excluded.add(method); continue; }
+    if (statements.length !== 2 || !env.ts.isVariableStatement(statements[0]) || !env.ts.isReturnStatement(statements[1])) continue;
+    const variables = statements[0].declarationList.declarations;
+    if (variables.length !== 1 || !env.ts.isIdentifier(variables[0].name) || !variables[0].initializer) continue;
+    const call = unwrap(env.ts, variables[0].initializer);
+    if (readCall(env, call, managers) && readResult(env, statements[1].expression, variables[0].name.text)) excluded.add(method);
+  }
+  if (managers.size && canonicalConstructor(env, constructor)) excluded.add(constructor);
+}
+
+function queueDefinition(env, node) {
+  const { ts } = env;
+  if (!env.topLevelVariables.has(node) || !node.initializer) return false;
+  const value = unwrap(ts, node.initializer);
+  if (ts.isCallExpression(value) && imported(env, value.expression, 'defineQueue', '@modules/platform/queue'))
+    return value.arguments.length === 1 && ts.isObjectLiteralExpression(unwrap(ts, value.arguments[0])) && mapping(env, value.arguments[0]);
+  if (!ts.isArrowFunction(value) || !portType(env, value.type, 'QueueSchedulerDefinition', '@modules/platform/queue')) return false;
+  const body = ts.isBlock(value.body) && value.body.statements.length === 1 && ts.isReturnStatement(value.body.statements[0]) ? value.body.statements[0].expression : value.body;
+  const object = unwrap(ts, body);
+  return Boolean(object && ts.isObjectLiteralExpression(object) && mapping(env, object));
+}
+
+function canonEnvironment(ts, sourceFile) {
+  const env = { ts, imports: importsOf(ts, sourceFile, { moduleKey: 'source', stringLiteralsOnly: true }), mappers: new Set(), topLevelVariables: new Set(), topLevelClasses: new Set(sourceFile.statements.filter(ts.isClassDeclaration)) };
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const variable of statement.declarationList.declarations) {
+      env.topLevelVariables.add(variable);
+      const value = variable.initializer && unwrap(ts, variable.initializer);
+      if (ts.isIdentifier(variable.name) && value && ts.isArrowFunction(value) && ts.isObjectLiteralExpression(unwrap(ts, value.body)) && mapping(env, value.body)) env.mappers.add(variable.name.text);
+    }
+  }
+  return env;
+}
+
+function classScaffolding(env, node, excluded) {
+  const { ts } = env;
+  const constructor = node.members.find(ts.isConstructorDeclaration);
+  if (hasHeritage(env, node, 'ICQRSHandler', '@modules/platform/cqrs', ts.SyntaxKind.ExtendsKeyword)
+    && ['CommandHandler', 'QueryHandler'].some(name => decoratorsHave(env, node, name, '@nestjs/cqrs'))) {
+    if (canonicalConstructor(env, constructor, true)) excluded.add(constructor);
+    const members = propertyParameters(ts, constructor);
+    for (const method of node.members) if (ts.isMethodDeclaration(method) && nameText(ts, method.name) === 'process'
+      && method.body?.statements.length === 1 && delegation(env, method, method.body.statements[0], members)) excluded.add(method);
+  }
+  if (hasHeritage(env, node, 'JobStep', '@modules/platform/jobs', ts.SyntaxKind.ImplementsKeyword)) jobMethods(env, node, constructor, excluded);
+  queueMethods(env, node, constructor, excluded);
+  readMethods(env, node, constructor, excluded);
+}
+
+export function canonCloneNodes(ts, sourceFile, profile) {
+  if (profile === 'fe') return canonJsxCloneNodes(ts, sourceFile);
+  const excluded = new Set();
+  const env = canonEnvironment(ts, sourceFile);
+  const visit = node => {
+    if (queueDefinition(env, node)) { excluded.add(node); return; }
+    if (env.topLevelClasses.has(node)) classScaffolding(env, node, excluded);
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return excluded;
+}

package/runtime/scripts/hfs/architecture/canon-jsx-clones.mjs

@@ -0,0 +1,143 @@
+/** Imported JSX components receive repeated data contracts; executable prop values remain compared. */
+import { unwrapExpression as unwrap } from '../../lib/ts-analysis.mjs';
+
+const TRANSLATION_MODULES = new Set(['next-intl', 'next-intl/server']);
+const TRANSLATION_FACTORIES = new Set(['useTranslations', 'getTranslations']);
+const uppercase = (name) => /^[A-Z]/.test(name);
+
+function bindName(ts, scope, name, binding) {
+  if (ts.isIdentifier(name)) scope.bindings.set(name.text, binding);
+  else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+    for (const element of name.elements) if (ts.isBindingElement(element)) bindName(ts, scope, element.name, binding);
+  }
+}
+
+function importBindings(ts, scope, statement) {
+  const clause = statement.importClause;
+  if (!clause || clause.isTypeOnly || !ts.isStringLiteral(statement.moduleSpecifier)) return;
+  const module = statement.moduleSpecifier.text;
+  if (clause.name) scope.bindings.set(clause.name.text, { kind: 'component' });
+  const named = clause.namedBindings;
+  if (!named) return;
+  if (ts.isNamespaceImport(named)) scope.bindings.set(named.name.text, { kind: 'namespace', module });
+  else for (const element of named.elements) {
+    if (element.isTypeOnly) continue;
+    const imported = element.propertyName?.text ?? element.name.text;
+    const kind = TRANSLATION_MODULES.has(module) && TRANSLATION_FACTORIES.has(imported) ? 'translation-factory' : 'component';
+    scope.bindings.set(element.name.text, { kind });
+  }
+}
+
+function lexicalBindings(ts, sourceFile) {
+  const scopes = new WeakMap();
+  const root = { parent: null, bindings: new Map() };
+  root.functionScope = root;
+  const visit = (node, outer) => {
+    if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) bindName(ts, outer, node.name, { kind: 'local' });
+    const functionScope = ts.isFunctionLike(node);
+    const nested = functionScope || ts.isBlock(node) || ts.isCatchClause(node) || ts.isClassExpression(node)
+      || ts.isForStatement(node) || ts.isForOfStatement(node) || ts.isForInStatement(node);
+    const scope = nested ? { parent: outer, bindings: new Map(), functionScope: functionScope ? null : outer.functionScope } : outer;
+    if (functionScope) scope.functionScope = scope;
+    scopes.set(node, scope);
+    if (ts.isImportDeclaration(node)) importBindings(ts, scope, node);
+    if (ts.isParameter(node)) bindName(ts, scope, node.name, { kind: 'local' });
+    if (ts.isFunctionExpression(node) && node.name) bindName(ts, scope, node.name, { kind: 'local' });
+    if (ts.isVariableDeclaration(node)) {
+      const flags = node.parent?.flags ?? ts.NodeFlags.Const;
+      bindName(ts, flags & ts.NodeFlags.BlockScoped ? scope : scope.functionScope, node.name,
+        { kind: flags & ts.NodeFlags.Const ? 'constant' : 'local', declaration: node });
+    }
+    ts.forEachChild(node, (child) => { visit(child, scope); });
+  };
+  visit(sourceFile, root);
+  return (identifier) => {
+    for (let scope = scopes.get(identifier); scope; scope = scope.parent) {
+      if (scope.bindings.has(identifier.text)) return scope.bindings.get(identifier.text);
+    }
+    return null;
+  };
+}
+
+function translationFactory(ts, node, bindingOf) {
+  node = unwrap(ts, node);
+  if (ts.isIdentifier(node)) return bindingOf(node)?.kind === 'translation-factory';
+  return ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)
+    && TRANSLATION_FACTORIES.has(node.name.text) && bindingOf(node.expression)?.kind === 'namespace'
+    && TRANSLATION_MODULES.has(bindingOf(node.expression).module);
+}
+
+function translator(ts, node, bindingOf) {
+  if (!ts.isIdentifier(node)) return false;
+  const binding = bindingOf(node);
+  if (binding?.kind !== 'constant') return false;
+  let initializer = unwrap(ts, binding.declaration.initializer);
+  if (initializer && ts.isAwaitExpression(initializer)) initializer = unwrap(ts, initializer.expression);
+  return Boolean(initializer && ts.isCallExpression(initializer) && translationFactory(ts, initializer.expression, bindingOf));
+}
+
+function importedComponent(ts, tag, bindingOf) {
+  if (ts.isIdentifier(tag)) return uppercase(tag.text) && bindingOf(tag)?.kind === 'component';
+  if (!ts.isPropertyAccessExpression(tag) || !uppercase(tag.name.text)) return false;
+  let root = tag.expression;
+  while (ts.isPropertyAccessExpression(root)) root = root.expression;
+  return ts.isIdentifier(root) && bindingOf(root)?.kind === 'namespace';
+}
+
+function dataProperty(ts, property, mapping) {
+  if (ts.isSpreadAssignment(property)) return mapping(property.expression);
+  if (ts.isShorthandPropertyAssignment(property)) return !property.objectAssignmentInitializer;
+  if (!ts.isPropertyAssignment(property)) return false;
+  return (!ts.isComputedPropertyName(property.name) || mapping(property.name.expression)) && mapping(property.initializer);
+}
+
+function dataMapping(ts, expression, bindingOf) {
+  const node = unwrap(ts, expression);
+  if (!node) return false;
+  const mapping = (value) => dataMapping(ts, value, bindingOf);
+  if (ts.isIdentifier(node) || ts.isLiteralExpression(node) || node.kind === ts.SyntaxKind.TrueKeyword
+    || node.kind === ts.SyntaxKind.FalseKeyword || node.kind === ts.SyntaxKind.NullKeyword || node.kind === ts.SyntaxKind.ThisKeyword) return true;
+  if (ts.isPropertyAccessExpression(node)) return mapping(node.expression);
+  if (ts.isElementAccessExpression(node)) return mapping(node.expression) && mapping(node.argumentExpression);
+  if (ts.isObjectLiteralExpression(node)) return node.properties.every((property) => dataProperty(ts, property, mapping));
+  if (ts.isArrayLiteralExpression(node)) return node.elements.every((element) => ts.isOmittedExpression(element)
+    || mapping(ts.isSpreadElement(element) ? element.expression : element));
+  if (ts.isTemplateExpression(node)) return node.templateSpans.every((span) => mapping(span.expression));
+  if (ts.isPrefixUnaryExpression(node)) return [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(node.operator)
+    && ts.isNumericLiteral(node.operand);
+  return ts.isCallExpression(node) && translator(ts, node.expression, bindingOf) && node.arguments.every(mapping);
+}
+
+/** Only object/array values belong to the prop contract; do not descend into a call or function body. */
+function nestedDataObjects(ts, expression, bindingOf, excluded) {
+  const node = unwrap(ts, expression);
+  if (!node) return;
+  if (ts.isObjectLiteralExpression(node)) {
+    if (dataMapping(ts, node, bindingOf)) { excluded.add(node); return; }
+    for (const property of node.properties) if (ts.isPropertyAssignment(property)) {
+      nestedDataObjects(ts, property.initializer, bindingOf, excluded);
+    }
+  } else if (ts.isArrayLiteralExpression(node)) {
+    for (const element of node.elements) if (!ts.isSpreadElement(element)) nestedDataObjects(ts, element, bindingOf, excluded);
+  }
+}
+
+/** Canon data prop objects qualify through an imported component binding, never its chosen name or file path. */
+export function canonJsxCloneNodes(ts, sourceFile) {
+  const bindingOf = lexicalBindings(ts, sourceFile);
+  const excluded = new Set();
+  const visit = (node) => {
+    if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && importedComponent(ts, node.tagName, bindingOf)) {
+      for (const attribute of node.attributes.properties) {
+        if (!ts.isJsxAttribute(attribute) || !attribute.initializer || !ts.isJsxExpression(attribute.initializer)) continue;
+        const value = unwrap(ts, attribute.initializer.expression);
+        if (!value || !ts.isObjectLiteralExpression(value)) continue;
+        if (dataMapping(ts, value, bindingOf)) excluded.add(attribute);
+        else nestedDataObjects(ts, value, bindingOf, excluded);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return excluded;
+}

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

@@ -4,7 +4,7 @@ import { sourceLocation } from '../../lib/ts-ast.mjs';
 /**
  * R55 `client-reaches-server` (FE_CLIENT_REACHES_SERVER), the repository half of the eslint rule `client-no-server-import`,
  * which sees one hop from a file that carries the directive. The machine walks the resolved import graph from every module
- * whose first statement is the `"use client"` directive, over runtime edges only (a type-only import vanishes at build), and
+ * whose directive prologue contains `"use client"`, over runtime edges only (a type-only import vanishes at build), and
  * reports any reachable module (the entry itself included) that imports a server-only surface:
  *
  *   - `server-only`, `next/headers`, `next/server`, `next-intl/server`;
@@ -22,8 +22,11 @@ const NODE_BUILTINS = new Set(builtinModules.map(name => name.replace(/^node:/u,
 
 const isServerSpecifier = specifier => SERVER_MODULES.has(specifier) || specifier.startsWith('node:') || NODE_BUILTINS.has(specifier.split('/')[0]);
 const isClientEntry = (ts, file) => {
-  const first = file.sourceFile.statements[0];
-  return Boolean(first) && ts.isExpressionStatement(first) && ts.isStringLiteral(first.expression) && first.expression.text === 'use client';
+  for (const statement of file.sourceFile.statements) {
+    if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression)) return false;
+    if (statement.expression.text === 'use client') return true;
+  }
+  return false;
 };
 
 const reachesBundle = (ts, declaration) => {

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

@@ -21,8 +21,12 @@
  * helper because NestFactory is allowed only in main.ts (BE_ENTRYPOINT_ONLY_IN_APPS), so what repeats there is the
  * canonical shape of section 5 of BE-CONVENTION. A door or main.ts that grows logic is refused by those enforcers, not
  * excused here; every other file of the same slots (mappers, dto, app.module.ts) stays compared.
+ * Canon scaffold subtrees (job fences, read/mapping methods, queue producers/definitions, CQRS wiring and data
+ * props of imported JSX frames) are also dropped through their imported shape markers. Each exclusion ends a
+ * token segment, so a window cannot join unrelated code across omitted scaffold lines. Custom bodies stay compared.
  */
 import { byCodeUnit } from '../../lib/list.mjs';
+import { canonCloneNodes } from './canon-clones.mjs';
 
 export const CLONE_RULE_IDS = ['HFS_DUPLICATE_CODE'];
 
@@ -61,11 +65,13 @@ function visitToken(walk, node, inType) {
   const { ts, sourceFile, kinds, lines, types, lineStarts, literalKinds } = walk;
   const { SyntaxKind } = ts;
   if (isTriviaNode(SyntaxKind, node)) return;
+  if (walk.excluded?.has(node)) { walk.segment += 1; return; }
   const kind = node.kind;
   const typeScope = inType || kind === SyntaxKind.InterfaceDeclaration || kind === SyntaxKind.TypeAliasDeclaration;
   kinds.push(normalizedKindOf(SyntaxKind, literalKinds, kind));
   lines.push(lineOfPosition(lineStarts, node.getStart(sourceFile)));
   types.push(typeScope ? 1 : 0);
+  walk.segments.push(walk.segment);
   ts.forEachChild(node, (child) => { visitToken(walk, child, typeScope); });
 }
 
@@ -73,13 +79,14 @@ function visitToken(walk, node, inType) {
 const isDroppedStatement = (SyntaxKind, statement) => statement.kind === SyntaxKind.ImportDeclaration || statement.kind === SyntaxKind.ImportEqualsDeclaration
   || (statement.kind === SyntaxKind.ExportDeclaration && statement.moduleSpecifier);
 
-export function tokenize(ts, sourceFile) {
+export function tokenize(ts, sourceFile, { excluded = null } = {}) {
   const { SyntaxKind } = ts;
-  const walk = { ts, sourceFile, kinds: [], lines: [], types: [], lineStarts: sourceFile.getLineStarts(), literalKinds: literalKindSet(SyntaxKind) };
+  const walk = { ts, sourceFile, kinds: [], lines: [], types: [], segments: [], segment: 0, excluded,
+    lineStarts: sourceFile.getLineStarts(), literalKinds: literalKindSet(SyntaxKind) };
   for (const statement of sourceFile.statements) {
     if (!isDroppedStatement(SyntaxKind, statement)) visitToken(walk, statement, false);
   }
-  return { kinds: Int32Array.from(walk.kinds), lines: Int32Array.from(walk.lines), types: Uint8Array.from(walk.types) };
+  return { kinds: Int32Array.from(walk.kinds), lines: Int32Array.from(walk.lines), types: Uint8Array.from(walk.types), segments: Int32Array.from(walk.segments) };
 }
 
 /** The app a file belongs to, by the slot binding of the manifest; null for a file of no app. */
@@ -142,15 +149,15 @@ const addToBucket = (buckets, key, item) => {
 
 const addFileWindows = (buckets, file, fileIndex, N, T, hashing) => {
   const { pow1, pow2, B1, B2 } = hashing;
-  const { kinds, lines } = file;
+  const { kinds, lines, segments } = file;
   const count = kinds.length;
   const { pre1, pre2 } = prefixHashes(kinds, B1, B2);
   let end = 0;
   for (let start = 0; start < count; start += 1) {
-    if (start > 0 && lines[start] === lines[start - 1]) continue;
+    if (start > 0 && lines[start] === lines[start - 1] && segments[start] === segments[start - 1]) continue;
     const limit = lines[start] + N;
     if (end < start) end = start;
-    while (end < count && lines[end] < limit) end += 1;
+    while (end < count && lines[end] < limit && segments[end] === segments[start]) end += 1;
     if (end === start || lines[end - 1] - lines[start] + 1 < N) continue;
     const length = end - start;
     if (length < T) continue;
@@ -224,7 +231,8 @@ const cloneBlocks = (entries, hits, N) => {
     group.sort((x, y) => x[0] - y[0]);
     let [start, end] = group[0];
     for (const [nextStart, nextEnd] of group.slice(1)) {
-      if (nextStart <= end) { end = Math.max(end, nextEnd); continue; }
+      if (nextStart <= end && fileA.segments[nextStart] === fileA.segments[start]
+        && fileB.segments[nextStart + diag] === fileB.segments[start + diag]) { end = Math.max(end, nextEnd); continue; }
       appendCloneBlock(blocks, fileA, fileB, start, end, diag, N);
       start = nextStart; end = nextEnd;
     }
@@ -263,7 +271,8 @@ export function checkClones({ config, context, graph } = {}) {
     if (/\.d\.[cm]?tsx?$/.test(rel) || uniformByDesign(graph.resolver, rel)) continue;
     const unit = graph.unit(rel);
     if (!unit) continue;
-    entries.push({ rel, unit, ...tokenize(ts, graph.files.get(rel).sourceFile) });
+    const sourceFile = graph.files.get(rel).sourceFile;
+    entries.push({ rel, unit, ...tokenize(ts, sourceFile, { excluded: canonCloneNodes(ts, sourceFile, graph.profile) }) });
   }
   const buckets = cloneBuckets(entries, N, T);
   const blocks = cloneBlocks(entries, cloneHits(entries, buckets), N);

package/runtime/scripts/hfs/architecture/connection-map.mjs

@@ -226,18 +226,20 @@ const passConnections = (argument, scope) => {
 const checkAppRegistrations = (config, kit, ts, byName, report) => {
   let registrations = 0;
   for (const app of config.apps) {
-    const root = kit.appRoot(app.name);
-    if (!root) continue;
-    const checker = kit.checkerOf(root.sourceFile);
-    const scope = { ts, kit, checker, byName, passed: new Map(), root, app, report };
-    kit.walk(root.sourceFile, node => {
-      const receiver = registerReceiver(ts, node);
-      if (!receiver) return;
-      const owner = kit.declarationsOf(checker, receiver).map(kit.ownerOfDeclaration).find(Boolean);
-      if (owner?.tier !== 'platform' || owner.name !== 'database') return;
-      registrations += 1;
-      for (const argument of node.arguments) passConnections(argument, scope);
-    });
+    // The root and its composition groups (compose/<area>.ts) are one composition: a connection is passed once across them.
+    const passed = new Map();
+    for (const root of kit.appCompositionFiles(app.name)) {
+      const checker = kit.checkerOf(root.sourceFile);
+      const scope = { ts, kit, checker, byName, passed, root, app, report };
+      kit.walk(root.sourceFile, node => {
+        const receiver = registerReceiver(ts, node);
+        if (!receiver) return;
+        const owner = kit.declarationsOf(checker, receiver).map(kit.ownerOfDeclaration).find(Boolean);
+        if (owner?.tier !== 'platform' || owner.name !== 'database') return;
+        registrations += 1;
+        for (const argument of node.arguments) passConnections(argument, scope);
+      });
+    }
   }
   return registrations;
 };

package/runtime/scripts/hfs/architecture/context-map.mjs

@@ -74,10 +74,16 @@ const nameFromIdentifier = (ctx, checker, node, depth) => {
     ? nameOfExpression(ctx, kit.checkerOf(declaration.getSourceFile()), declaration.initializer, depth + 1) : null;
 };
 
+/** True when `declaration` is a property of the `<app>.env.ts` reader's own interface that sits beside the options file declaring `target`: the reader feeds the options value, so its property is the same slot. */
+const feedsOptions = (declaration, target) => {
+  const home = declaration?.getSourceFile().fileName ?? '';
+  return home.endsWith('.env.ts') && path.posix.dirname(home) === path.posix.dirname(target.getSourceFile().fileName);
+};
+
 const nameFromProperty = (ctx, checker, node, depth) => {
   const target = ctx.kit.declarationsOf(checker, node.name)[0];
   if (!target) return null;
-  const names = new Set(assignmentsOf(ctx, node.name.text).filter(item => item.declaration === target)
+  const names = new Set(assignmentsOf(ctx, node.name.text).filter(item => item.declaration === target || feedsOptions(item.declaration, target))
     .map(item => nameOfExpression(ctx, item.checker, item.initializer, depth + 1)).filter(Boolean));
   return names.size === 1 ? [...names][0] : null;
 };
@@ -282,30 +288,35 @@ const composedConnection = (kit, declared, checker, inner) => {
   return value !== null && declared.has(value) ? value : null;
 };
 
-const collectComposedConnections = (kit, declared, checker, call, items) => {
+const collectComposedConnections = (kit, declared, checker, call, file, items) => {
   for (const argument of call.arguments) {
     kit.walk(argument, inner => {
       const value = composedConnection(kit, declared, checker, inner);
       if (value === null) return true;
-      items.push({ connection: value, node: inner });
+      items.push({ connection: value, node: inner, file });
       return false;
     });
   }
 };
 
-/** The declared connection names the composition root of `app` passes to the database module registration, as [{connection, node}] in source order. */
+/**
+ * The declared connection names the composition of `app` (its root app.module.ts and the composition groups of compose/) passes to
+ * the database module registration, as [{connection, node, file}] in path then source order.
+ */
 export function connectionsComposedBy(kit, app) {
   const { ts } = kit;
-  const root = kit.appRoot(app);
-  if (!root) return { root: null, items: [] };
+  const files = kit.appCompositionFiles(app);
+  if (!files.length) return { root: null, items: [] };
   const declared = new Set(kit.resolver.repo.connections.map(connection => connection.name));
-  const checker = kit.checkerOf(root.sourceFile);
   const items = [];
-  kit.walk(root.sourceFile, node => {
-    if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register')) return;
-    const owner = kit.declarationsOf(checker, node.expression.expression).map(kit.ownerOfDeclaration).find(Boolean);
-    if (owner?.tier !== 'platform' || owner.name !== 'database') return;
-    collectComposedConnections(kit, declared, checker, node, items);
-  });
-  return { root, items };
+  for (const file of files) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'register')) return;
+      const owner = kit.declarationsOf(checker, node.expression.expression).map(kit.ownerOfDeclaration).find(Boolean);
+      if (owner?.tier !== 'platform' || owner.name !== 'database') return;
+      collectComposedConnections(kit, declared, checker, node, file, items);
+    });
+  }
+  return { root: files[0], items };
 }

package/runtime/scripts/hfs/architecture/context-owner.mjs

@@ -23,8 +23,7 @@ const RUNNER_KINDS = new Set(['migrate', 'cli']);
 const compositionsOf = (kit, resolver, model, appOf) => {
   const composed = new Map(resolver.repo.apps.map(app => [app.name, { items: [], unresolved: false }]));
   for (const app of resolver.repo.apps) {
-    const { root, items } = connectionsComposedBy(kit, app.name);
-    for (const item of items) composed.get(app.name).items.push({ ...item, file: root });
+    for (const item of connectionsComposedBy(kit, app.name).items) composed.get(app.name).items.push(item);
   }
   for (const site of model.registrations) {
     const app = appOf(site.file.rel);