@starci/hfs 4.11.21 → 4.12.0

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

@@ -1,143 +1,176 @@
-/** 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);
-  }
+    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 });
-  }
+    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;
-  };
+    const scopes = new WeakMap();
+    const root = { parent: null, bindings: new Map(), functionScope: null };
+    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);
+    node = unwrap(ts, node);
+    if (ts.isIdentifier(node))
+        return bindingOf(node)?.kind === 'translation-factory';
+    if (!(ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && TRANSLATION_FACTORIES.has(node.name.text)))
+        return false;
+    const namespace = bindingOf(node.expression);
+    return namespace?.kind === 'namespace' && TRANSLATION_MODULES.has(namespace.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));
+    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';
+    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);
+    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);
+    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);
+    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);
     }
-  } 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;
+    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.d.mts

@@ -0,0 +1,28 @@
+import type { TypeScriptApi } from './config.mjs';
+import type { ArchitectureViolation, HfsGraph } from './hfs-graph.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 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`;
+ *   - a Node built-in: `node:*` and every bare name of `module.builtinModules` (`fs`, `path`, `crypto`, ...).
+ *
+ * The finding sits on the client entry, names the shortest import chain from it to the offending module (multi-hop) and the
+ * specifier. Only imports that reach the client bundle count: `import type`, an import whose every named specifier is
+ * `type`, and `export type` re-exports are skipped.
+ */
+export declare const CLIENT_REACHES_SERVER_RULE_IDS: string[];
+export declare function checkClientReachesServer({ graph, context }: {
+    graph: HfsGraph;
+    context: {
+        ts: TypeScriptApi;
+    };
+}): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        clientEntries: number;
+    };
+};

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

@@ -1,6 +1,5 @@
 import { builtinModules } from 'node:module';
 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
@@ -15,84 +14,89 @@ import { sourceLocation } from '../../lib/ts-ast.mjs';
  * `type`, and `export type` re-exports are skipped.
  */
 export const CLIENT_REACHES_SERVER_RULE_IDS = ['FE_CLIENT_REACHES_SERVER'];
-
 const RULE = 'FE_CLIENT_REACHES_SERVER';
 const SERVER_MODULES = new Set(['server-only', 'next/headers', 'next/server', 'next-intl/server']);
 const NODE_BUILTINS = new Set(builtinModules.map(name => name.replace(/^node:/u, '').split('/')[0]));
-
-const isServerSpecifier = specifier => SERVER_MODULES.has(specifier) || specifier.startsWith('node:') || NODE_BUILTINS.has(specifier.split('/')[0]);
+const isServerSpecifier = (specifier) => SERVER_MODULES.has(specifier) || specifier.startsWith('node:') || NODE_BUILTINS.has(specifier.split('/')[0]);
 const isClientEntry = (ts, file) => {
-  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;
+    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) => {
-  if (ts.isImportDeclaration(declaration)) {
-    const clause = declaration.importClause;
-    if (!clause) return true;
-    if (clause.isTypeOnly) return false;
-    if (!clause.name && clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
-      const elements = clause.namedBindings.elements;
-      return elements.length === 0 || !elements.every(element => element.isTypeOnly);
+    if (ts.isImportDeclaration(declaration)) {
+        const clause = declaration.importClause;
+        if (!clause)
+            return true;
+        if (clause.isTypeOnly)
+            return false;
+        if (!clause.name && clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+            const elements = clause.namedBindings.elements;
+            return elements.length === 0 || !elements.every(element => element.isTypeOnly);
+        }
+        return true;
     }
-    return true;
-  }
-  return !declaration.isTypeOnly;
+    return !declaration.isTypeOnly;
 };
-
 const serverImports = (ts, file) => {
-  const found = [];
-  const visit = node => {
-    let specifier = null;
-    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && reachesBundle(ts, node)) specifier = node.moduleSpecifier;
-    else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) specifier = node.arguments[0];
-    if (specifier && ts.isStringLiteralLike(specifier) && isServerSpecifier(specifier.text)) found.push({ specifier: specifier.text, node });
-    ts.forEachChild(node, visit);
-  };
-  visit(file.sourceFile);
-  return found;
+    const found = [];
+    const visit = (node) => {
+        let specifier = null;
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && reachesBundle(ts, node))
+            specifier = node.moduleSpecifier;
+        else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require')))
+            specifier = node.arguments[0];
+        if (specifier && ts.isStringLiteralLike(specifier) && isServerSpecifier(specifier.text))
+            found.push({ specifier: specifier.text, node });
+        ts.forEachChild(node, visit);
+    };
+    visit(file.sourceFile);
+    return found;
 };
-
-const scanClientEntry = (entry, { ts, graph, runtime, violations }) => {
-  const seen = new Map([[entry.rel, { chain: [entry.rel], first: null }]]);
-  const queue = [entry.rel];
-  for (const rel of queue) {
-    const state = seen.get(rel);
-    for (const hit of runtime.serverOf(rel)) {
-      const at = state.first ?? sourceLocation(graph.files.get(rel).sourceFile, hit.node);
-      violations.push({
-        ruleId: RULE, path: entry.rel, line: at.line, column: at.column, clientEntry: entry.rel, importer: rel, specifier: hit.specifier, dependencyChain: state.chain,
-        message: `${entry.rel} is a client module ("use client") and reaches ${hit.specifier} through ${[...state.chain, hit.specifier].join(' -> ')}; a server-only surface never enters the client bundle. Read on the server and pass the value down, or move the import out of the client graph.`,
-      });
-    }
-    for (const edge of runtime.edges.get(rel) ?? []) {
-      if (seen.has(edge.to)) continue;
-      seen.set(edge.to, { chain: [...state.chain, edge.to], first: state.first ?? { line: edge.line, column: edge.column } });
-      queue.push(edge.to);
+const scanClientEntry = (entry, { graph, runtime, violations }) => {
+    const seen = new Map([[entry.rel, { chain: [entry.rel], first: null }]]);
+    const queue = [entry.rel];
+    for (const rel of queue) {
+        const state = seen.get(rel); // every queued module was recorded in `seen` when it was queued
+        for (const hit of runtime.serverOf(rel)) {
+            const at = state.first ?? sourceLocation(graph.files.get(rel).sourceFile, hit.node);
+            violations.push({
+                ruleId: RULE, path: entry.rel, line: at.line, column: at.column, clientEntry: entry.rel, importer: rel, specifier: hit.specifier, dependencyChain: state.chain,
+                message: `${entry.rel} is a client module ("use client") and reaches ${hit.specifier} through ${[...state.chain, hit.specifier].join(' -> ')}; a server-only surface never enters the client bundle. Read on the server and pass the value down, or move the import out of the client graph.`,
+            });
+        }
+        for (const edge of runtime.edges.get(rel) ?? []) {
+            if (seen.has(edge.to))
+                continue;
+            seen.set(edge.to, { chain: [...state.chain, edge.to], first: state.first ?? { line: edge.line, column: edge.column } });
+            queue.push(edge.to);
+        }
     }
-  }
 };
-
 export function checkClientReachesServer({ graph, context }) {
-  const ts = context.ts;
-  const runtime = new Map();
-  for (const edge of graph.edges) {
-    if (!edge.runtime) continue;
-    if (!runtime.has(edge.from)) runtime.set(edge.from, []);
-    runtime.get(edge.from).push(edge);
-  }
-  const serverByFile = new Map();
-  const serverOf = rel => {
-    if (!serverByFile.has(rel)) serverByFile.set(rel, serverImports(ts, graph.files.get(rel)));
-    return serverByFile.get(rel);
-  };
-
-  const violations = [];
-  const entries = [...graph.files.values()].filter(file => isClientEntry(ts, file)).sort((a, b) => a.rel.localeCompare(b.rel));
-  const scanRuntime = { ts, graph, edges: runtime, serverOf, violations };
-  for (const entry of entries) scanClientEntry(entry, { ts, graph, runtime: scanRuntime, violations });
-  return { violations, coverage: { status: 'checked', clientEntries: entries.length } };
+    const ts = context.ts;
+    const runtime = new Map();
+    for (const edge of graph.edges) {
+        if (!edge.runtime)
+            continue;
+        if (!runtime.has(edge.from))
+            runtime.set(edge.from, []);
+        runtime.get(edge.from)?.push(edge);
+    }
+    const serverByFile = new Map();
+    const serverOf = (rel) => {
+        if (!serverByFile.has(rel))
+            serverByFile.set(rel, serverImports(ts, graph.files.get(rel)));
+        return serverByFile.get(rel);
+    };
+    const violations = [];
+    const entries = [...graph.files.values()].filter(file => isClientEntry(ts, file)).sort((a, b) => a.rel.localeCompare(b.rel));
+    const scanRuntime = { ts, graph, edges: runtime, serverOf, violations };
+    for (const entry of entries)
+        scanClientEntry(entry, { graph, runtime: scanRuntime, violations });
+    return { violations, coverage: { status: 'checked', clientEntries: entries.length } };
 }

package/runtime/scripts/hfs/architecture/clones.d.mts

@@ -0,0 +1,54 @@
+/**
+ * HFS check 7, R21 duplicate code (knowledge/hfs/slots.yaml ruleParams.<profile>.duplicateBlock = {lines: N, tokens: T},
+ * the one definition of the threshold): a token-normalised block of at least N source lines and T tokens that appears
+ * twice in the production program - in two owners, in two files of one owner, or twice in one file - is code copied
+ * instead of shared.
+ *
+ * Normalisation: every production file is flattened into its syntax-node sequence (the compiler's parsed tree, walked in
+ * source order; comments and whitespace do not exist in it), identifiers become one ID kind, string, template, numeric,
+ * bigint and regex literals become one LIT kind, keywords and operators keep their own kind. Leading import and
+ * export-from statements are dropped (imports repeat legitimately). A window is the run of tokens on N consecutive
+ * physical lines starting at a line start whose last token reaches line N; windows are hashed with a rolling polynomial
+ * hash (O(total tokens)), equal windows of two different owners are verified token by token, and overlapping hits on the
+ * same file pair and offset merge into one maximal block. A block whose lines are mostly type declarations
+ * (fewer than N/2 lines outside interface and type alias declarations) or of fewer than N/3 distinct line shapes
+ * (a decorated DTO field list repeating one shape) is ignored.
+ *
+ * Two kinds of file are uniform by design and are not compared, both found through the slot resolver: the entry main.ts of
+ * an app (slot appKind + its required main.ts) and the transport doors of a feature (a *.controller.ts, *.resolver.ts,
+ * *.gateway.ts, *.consumer.ts, *.processor.ts or *.cli.ts of a slot that a protocol app composes). This is not a loophole: logic
+ * cannot live in either. A door body is dispatch only (eslint transport-is-thin, R88), and main.ts cannot share a
+ * 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 type { Node, SourceFile } from 'typescript';
+import type { TypeScriptApi } from './config.mjs';
+import type { ArchitectureViolation, CheckInput } from './hfs-graph.mjs';
+export declare const CLONE_RULE_IDS: string[];
+/** The token streams of one file: normalised kind, physical line, in-type flag and exclusion segment per token. */
+export interface TokenizedFile {
+    kinds: Int32Array;
+    lines: Int32Array;
+    types: Uint8Array;
+    segments: Int32Array;
+}
+export declare function tokenize(ts: TypeScriptApi, sourceFile: SourceFile, { excluded }?: {
+    excluded?: Set<Node> | null;
+}): TokenizedFile;
+export declare function checkClones({ context, graph }: CheckInput): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        truncated?: boolean;
+        status: string;
+        minLines: number;
+        minTokens: number;
+        files: number;
+        cloneBlocks: number;
+        ownersInvolved: number;
+        duplicatedLines: number;
+    };
+};