@starci/hfs 4.0.10 → 4.1.0

package/runtime/scripts/hfs/architecture/background-unowned.mjs

@@ -20,70 +20,105 @@ import { machineKit } from './machine-ast.mjs';
 export const BACKGROUND_UNOWNED_RULE_IDS = ['BE_BACKGROUND_UNOWNED'];
 
 const RULE = 'BE_BACKGROUND_UNOWNED';
-const BACKGROUND_ROLES = ['processor', 'consumer'];
+const BACKGROUND_ROLES = new Set(['processor', 'consumer']);
 /** The words the law names for background methods (knowledge/hfs/README.md 5.7). */
 const BACKGROUND_WORDS = ['sweep', 'deliver', 'reconcile', 'retry'];
 
 const roleOf = rel => {
   const parts = path.posix.basename(rel).split('.');
-  return parts.length >= 3 && parts.at(-1) === 'ts' && BACKGROUND_ROLES.includes(parts.at(-2)) ? parts.at(-2) : null;
+  return parts.length >= 3 && parts.at(-1) === 'ts' && BACKGROUND_ROLES.has(parts.at(-2)) ? parts.at(-2) : null;
 };
 const isBackgroundName = name => BACKGROUND_WORDS.some(word => name === word || (name.startsWith(word) && /[A-Z]/u.test(name[word.length] ?? '')));
 
-export function checkBackgroundUnowned(input) {
-  const { graph } = input;
-  const kit = machineKit(input);
-  const { ts, resolver } = kit;
-  const violations = [];
-  const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
-
+const adjacencyOf = edges => {
   const adjacency = new Map();
-  for (const edge of graph.edges) if (edge.runtime) {
+  for (const edge of edges) {
+    if (!edge.runtime) continue;
     if (!adjacency.has(edge.from)) adjacency.set(edge.from, []);
     adjacency.get(edge.from).push(edge.to);
   }
-  const closure = starts => {
-    const seen = new Set(starts);
-    const queue = [...starts];
-    while (queue.length) for (const next of adjacency.get(queue.shift()) ?? []) if (!seen.has(next)) { seen.add(next); queue.push(next); }
-    return seen;
-  };
+  return adjacency;
+};
 
+const closureOf = (adjacency, starts) => {
+  const seen = new Set(starts);
+  const queue = [...starts];
+  while (queue.length) {
+    for (const next of adjacency.get(queue.shift()) ?? []) {
+      if (seen.has(next)) continue;
+      seen.add(next);
+      queue.push(next);
+    }
+  }
+  return seen;
+};
+
+const appRootsOf = (apps, graph) => {
   const rootOf = app => `apps/${app.name}/src/app.module.ts`;
-  const workerRoots = resolver.repo.apps.filter(app => app.kind === 'worker').map(rootOf).filter(rel => graph.files.has(rel));
-  const composed = closure([...workerRoots, ...resolver.repo.apps.filter(app => app.kind === 'api').map(rootOf).filter(rel => graph.files.has(rel))]);
-  const background = [...graph.files.values()].filter(file => roleOf(file.rel) && file.tier === 'feature');
-  const running = background.filter(file => composed.has(file.rel));
+  const workers = apps.filter(app => app.kind === 'worker').map(rootOf).filter(rel => graph.files.has(rel));
+  const services = apps.filter(app => app.kind === 'api').map(rootOf).filter(rel => graph.files.has(rel));
+  return { workers, composed: [...workers, ...services] };
+};
+
+const backgroundFilesOf = graph => [...graph.files.values()].filter(file => roleOf(file.rel) && file.tier === 'feature');
+
+const reportUncomposedFiles = (background, composed, workerRoots, report) => {
   for (const file of background) {
     if (composed.has(file.rel)) continue;
     const role = roleOf(file.rel);
     report(file, file.sourceFile, `${file.rel} is a ${role} that no service app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; a ${role} runs only when the ${role === 'processor' ? 'job' : 'message'} module of its feature is imported by the root module of an app of kind worker or api.`, { role });
   }
+};
 
-  // Everything a composed processor or consumer can reach: its imports, and the files of its own feature (command handlers).
+const rootsOfRunningFeatures = (running, files) => {
   const roots = new Set();
   for (const file of running) {
     roots.add(file.rel);
     const owner = file.owner?.root;
-    if (owner) for (const other of graph.files.values()) if (other.owner?.root === owner) roots.add(other.rel);
+    if (owner) for (const other of files.values()) if (other.owner?.root === owner) roots.add(other.rel);
   }
-  const reachable = closure([...roots]);
+  return roots;
+};
+
+const backgroundMethodsOf = (node, kit, ts) => node.members.flatMap(member => {
+  if (!ts.isMethodDeclaration(member) || !member.name) return [];
+  const name = kit.propertyNameText(member.name);
+  return name && isBackgroundName(name) ? [{ name, node: member.name }] : [];
+});
 
+const checkBackgroundMethods = ({ graph, kit, ts, reachable, report }) => {
   let methods = 0;
+  const reportMethod = (file, method) => {
+    methods += 1;
+    if (!reachable.has(file.rel)) report(file, method.node, `${method.name} is background work (a ${BACKGROUND_WORDS.join(', ')} method) that no processor or consumer composed by a worker or api app can reach. Add a processor in features/jobs/<job> or a consumer in transport/message of a feature that runs it, and compose its module in a worker or api app.`, { method: method.name });
+  };
   for (const file of graph.files.values()) {
-    const mechanism = file.tier === 'platform';
+    if (file.tier === 'platform') continue;
     kit.walk(file.sourceFile, node => {
-      if (!mechanism && ts.isClassDeclaration(node)) {
-        for (const member of node.members) {
-          if (!ts.isMethodDeclaration(member) || !member.name) continue;
-          const name = kit.propertyNameText(member.name);
-          if (!name || !isBackgroundName(name)) continue;
-          methods += 1;
-          if (!reachable.has(file.rel)) report(file, member.name, `${name} is background work (a ${BACKGROUND_WORDS.join(', ')} method) that no processor or consumer composed by a worker or api app can reach. Add a processor in features/jobs/<job> or a consumer in transport/message of a feature that runs it, and compose its module in a worker or api app.`, { method: name });
-        }
-      }
-      return true;
+      if (ts.isClassDeclaration(node)) for (const method of backgroundMethodsOf(node, kit, ts)) reportMethod(file, method);
     });
   }
+  return methods;
+};
+
+export function checkBackgroundUnowned(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts, resolver } = kit;
+  const violations = [];
+  const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+
+  const adjacency = adjacencyOf(graph.edges);
+  const closure = starts => closureOf(adjacency, starts);
+  const { workers: workerRoots, composed: appRoots } = appRootsOf(resolver.repo.apps, graph);
+  const composed = closure(appRoots);
+  const background = backgroundFilesOf(graph);
+  const running = background.filter(file => composed.has(file.rel));
+  reportUncomposedFiles(background, composed, workerRoots, report);
+
+  // Everything a composed processor or consumer can reach: its imports, and the files of its own feature (command handlers).
+  const roots = rootsOfRunningFeatures(running, graph.files);
+  const reachable = closure([...roots]);
+  const methods = checkBackgroundMethods({ graph, kit, ts, reachable, report });
   return { violations, coverage: { status: 'checked', workers: workerRoots.length, jobsAndConsumers: background.length, composed: running.length, backgroundMethods: methods } };
 }

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

@@ -22,41 +22,61 @@ const SERVER_MODULES = new Set(['server-only', 'next/headers', 'next/server', 'n
 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 isClientEntry = (ts, file) => {
+  const first = file.sourceFile.statements[0];
+  return Boolean(first) && ts.isExpressionStatement(first) && ts.isStringLiteral(first.expression) && first.expression.text === 'use client';
+};
 
-export function checkClientReachesServer({ graph, context }) {
-  const ts = context.ts;
-  const isClientEntry = file => {
-    const first = file.sourceFile.statements[0];
-    return Boolean(first) && ts.isExpressionStatement(first) && ts.isStringLiteral(first.expression) && first.expression.text === 'use client';
-  };
-  /** True when the import or re-export declaration reaches the bundle: not `import type`, not all-`type` specifiers. */
-  const reachesBundle = 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);
-      }
-      return true;
+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);
     }
-    return !declaration.isTypeOnly;
-  };
-  /** The server-only specifiers a file imports, with the node to point at. */
-  const serverImports = file => {
-    const found = [];
-    const visit = node => {
-      const specifier = (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && reachesBundle(node) ? node.moduleSpecifier
-        : ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require')) ? node.arguments[0]
-          : null;
-      if (specifier && ts.isStringLiteralLike(specifier) && isServerSpecifier(specifier.text)) found.push({ specifier: specifier.text, node });
-      ts.forEachChild(node, visit);
-    };
-    visit(file.sourceFile);
-    return found;
+    return true;
+  }
+  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 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) {
+    if (isServerActionModule(ts, graph.files.get(rel).sourceFile)) continue;
+    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);
+    }
+  }
+};
 
+export function checkClientReachesServer({ graph, context }) {
+  const ts = context.ts;
   const runtime = new Map();
   for (const edge of graph.edges) {
     if (!edge.runtime) continue;
@@ -65,32 +85,13 @@ export function checkClientReachesServer({ graph, context }) {
   }
   const serverByFile = new Map();
   const serverOf = rel => {
-    if (!serverByFile.has(rel)) serverByFile.set(rel, serverImports(graph.files.get(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(isClientEntry).sort((a, b) => a.rel.localeCompare(b.rel));
-  for (const entry of entries) {
-    const seen = new Map([[entry.rel, { chain: [entry.rel], first: null }]]);
-    const queue = [entry.rel];
-    for (let head = 0; head < queue.length; head += 1) {
-      const rel = queue[head];
-      if (isServerActionModule(ts, graph.files.get(rel).sourceFile)) continue;
-      const state = seen.get(rel);
-      for (const hit of 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.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 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 } };
 }

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

@@ -22,6 +22,8 @@
  * 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.
  */
+import { byCodeUnit } from '../../lib/list.mjs';
+
 export const CLONE_RULE_IDS = ['HFS_DUPLICATE_CODE'];
 
 const MAX_VIOLATIONS = 200;
@@ -30,39 +32,54 @@ const APP_ENTRY = 'main.ts';
 const ID = -1;
 const LIT = -2;
 
+const literalKindSet = (SyntaxKind) => new Set([SyntaxKind.StringLiteral, SyntaxKind.NumericLiteral, SyntaxKind.BigIntLiteral, SyntaxKind.RegularExpressionLiteral,
+  SyntaxKind.NoSubstitutionTemplateLiteral, SyntaxKind.TemplateHead, SyntaxKind.TemplateMiddle, SyntaxKind.TemplateTail, SyntaxKind.JsxText]);
+
+function lineOfPosition(lineStarts, position) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low < high) {
+    const mid = (low + high + 1) >> 1;
+    if (lineStarts[mid] <= position) low = mid; else high = mid - 1;
+  }
+  return low + 1;
+}
+
+/** True for the nodes that carry no token: documentation comments and whitespace-only JSX text. */
+function isTriviaNode(SyntaxKind, node) {
+  const kind = node.kind;
+  if (kind >= SyntaxKind.FirstJSDocNode && kind <= SyntaxKind.LastJSDocNode) return true;
+  return kind === SyntaxKind.JsxText && Boolean(node.containsOnlyTriviaWhiteSpaces);
+}
+
+function normalizedKindOf(SyntaxKind, literalKinds, kind) {
+  if (kind === SyntaxKind.Identifier || kind === SyntaxKind.PrivateIdentifier) return ID;
+  return literalKinds.has(kind) ? LIT : kind;
+}
+
+function visitToken(walk, node, inType) {
+  const { ts, sourceFile, kinds, lines, types, lineStarts, literalKinds } = walk;
+  const { SyntaxKind } = ts;
+  if (isTriviaNode(SyntaxKind, node)) 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);
+  ts.forEachChild(node, (child) => { visitToken(walk, child, typeScope); });
+}
+
+/** Leading import and export-from statements repeat legitimately and are not tokenised. */
+const isDroppedStatement = (SyntaxKind, statement) => statement.kind === SyntaxKind.ImportDeclaration || statement.kind === SyntaxKind.ImportEqualsDeclaration
+  || (statement.kind === SyntaxKind.ExportDeclaration && statement.moduleSpecifier);
+
 export function tokenize(ts, sourceFile) {
   const { SyntaxKind } = ts;
-  const literalKinds = new Set([SyntaxKind.StringLiteral, SyntaxKind.NumericLiteral, SyntaxKind.BigIntLiteral, SyntaxKind.RegularExpressionLiteral,
-    SyntaxKind.NoSubstitutionTemplateLiteral, SyntaxKind.TemplateHead, SyntaxKind.TemplateMiddle, SyntaxKind.TemplateTail, SyntaxKind.JsxText]);
-  const kinds = [];
-  const lines = [];
-  const types = [];
-  const lineStarts = sourceFile.getLineStarts();
-  const lineOf = (position) => {
-    let low = 0;
-    let high = lineStarts.length - 1;
-    while (low < high) {
-      const mid = (low + high + 1) >> 1;
-      if (lineStarts[mid] <= position) low = mid; else high = mid - 1;
-    }
-    return low + 1;
-  };
-  const visit = (node, inType) => {
-    const kind = node.kind;
-    if (kind >= SyntaxKind.FirstJSDocNode && kind <= SyntaxKind.LastJSDocNode) return;
-    if (kind === SyntaxKind.JsxText && node.containsOnlyTriviaWhiteSpaces) return;
-    const typeScope = inType || kind === SyntaxKind.InterfaceDeclaration || kind === SyntaxKind.TypeAliasDeclaration;
-    kinds.push(kind === SyntaxKind.Identifier || kind === SyntaxKind.PrivateIdentifier ? ID : literalKinds.has(kind) ? LIT : kind);
-    lines.push(lineOf(node.getStart(sourceFile)));
-    types.push(typeScope ? 1 : 0);
-    ts.forEachChild(node, (child) => { visit(child, typeScope); });
-  };
+  const walk = { ts, sourceFile, kinds: [], lines: [], types: [], lineStarts: sourceFile.getLineStarts(), literalKinds: literalKindSet(SyntaxKind) };
   for (const statement of sourceFile.statements) {
-    if (statement.kind === SyntaxKind.ImportDeclaration || statement.kind === SyntaxKind.ImportEqualsDeclaration
-      || (statement.kind === SyntaxKind.ExportDeclaration && statement.moduleSpecifier)) continue;
-    visit(statement, false);
+    if (!isDroppedStatement(SyntaxKind, statement)) visitToken(walk, statement, false);
   }
-  return { kinds: Int32Array.from(kinds), lines: Int32Array.from(lines), types: Uint8Array.from(types) };
+  return { kinds: Int32Array.from(walk.kinds), lines: Int32Array.from(walk.lines), types: Uint8Array.from(walk.types) };
 }
 
 /** The app a file belongs to, by the slot binding of the manifest; null for a file of no app. */
@@ -86,17 +103,7 @@ function homeText(profile, sameOwner, crossApp) {
   return "move the shared helper to src/modules/platform/primitives/ or into the owning capability's src/modules/domain/<capability>/ and import it from both";
 }
 
-export function checkClones({ config, context, graph } = {}) {
-  const { lines: N, tokens: T } = graph.resolver.ruleParams().duplicateBlock;
-  const ts = context.ts ?? context.loaded.ts;
-  const entries = [];
-  for (const rel of [...graph.files.keys()].sort()) {
-    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) });
-  }
-  // Rolling hash: two independent 32-bit polynomial prefix hashes, verified by token comparison on every match.
+const cloneBuckets = (entries, N, T) => {
   const B1 = 1000003;
   const B2 = 92821;
   let maxTokens = 0;
@@ -106,63 +113,109 @@ export function checkClones({ config, context, graph } = {}) {
   pow1[0] = 1; pow2[0] = 1;
   for (let i = 1; i <= maxTokens; i += 1) { pow1[i] = Math.imul(pow1[i - 1], B1); pow2[i] = Math.imul(pow2[i - 1], B2); }
   const buckets = new Map();
-  entries.forEach((file, fileIndex) => {
-    const { kinds, lines } = file;
-    const count = kinds.length;
-    const pre1 = new Int32Array(count + 1);
-    const pre2 = new Int32Array(count + 1);
-    for (let i = 0; i < count; i += 1) {
-      pre1[i + 1] = (Math.imul(pre1[i], B1) + kinds[i] + 3) | 0;
-      pre2[i + 1] = (Math.imul(pre2[i], B2) + kinds[i] + 7) | 0;
-    }
-    let end = 0;
-    for (let start = 0; start < count; start += 1) {
-      if (start > 0 && lines[start] === lines[start - 1]) continue;
-      const limit = lines[start] + N;
-      if (end < start) end = start;
-      while (end < count && lines[end] < limit) end += 1;
-      if (end === start || lines[end - 1] - lines[start] + 1 < N) continue;
-      const length = end - start;
-      if (length < T) continue;
-      const key = `${(pre1[end] - Math.imul(pre1[start], pow1[length])) | 0}:${(pre2[end] - Math.imul(pre2[start], pow2[length])) | 0}:${length}`;
-      const list = buckets.get(key);
-      const item = [fileIndex, start, end];
-      if (list) list.push(item); else buckets.set(key, [item]);
-    }
-  });
-  const same = (a, b) => {
-    const ka = entries[a[0]].kinds;
-    const kb = entries[b[0]].kinds;
-    for (let i = 0; i < a[2] - a[1]; i += 1) if (ka[a[1] + i] !== kb[b[1] + i]) return false;
-    return true;
-  };
-  // Hits per (file a, file b, offset): merged into maximal blocks below.
+  const hashing = { pow1, pow2, B1, B2 };
+  entries.forEach((file, fileIndex) => addFileWindows(buckets, file, fileIndex, N, T, hashing));
+  return buckets;
+};
+
+function signedInt32(value) {
+  return Math.imul(value, 1);
+}
+
+const prefixHashes = (kinds, B1, B2) => {
+  const count = kinds.length;
+  const pre1 = new Int32Array(count + 1);
+  const pre2 = new Int32Array(count + 1);
+  for (let i = 0; i < count; i += 1) {
+    pre1[i + 1] = Math.imul(pre1[i], B1) + kinds[i] + 3;
+    pre2[i + 1] = Math.imul(pre2[i], B2) + kinds[i] + 7;
+  }
+  return { pre1, pre2 };
+};
+
+const windowKey = (pre, pow, start, end) => signedInt32(pre[end] - Math.imul(pre[start], pow[end - start]));
+
+const addToBucket = (buckets, key, item) => {
+  const list = buckets.get(key);
+  if (list) list.push(item); else buckets.set(key, [item]);
+};
+
+const addFileWindows = (buckets, file, fileIndex, N, T, hashing) => {
+  const { pow1, pow2, B1, B2 } = hashing;
+  const { kinds, lines } = 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;
+    const limit = lines[start] + N;
+    if (end < start) end = start;
+    while (end < count && lines[end] < limit) end += 1;
+    if (end === start || lines[end - 1] - lines[start] + 1 < N) continue;
+    const length = end - start;
+    if (length < T) continue;
+    const key = `${windowKey(pre1, pow1, start, end)}:${windowKey(pre2, pow2, start, end)}:${length}`;
+    addToBucket(buckets, key, [fileIndex, start, end]);
+  }
+};
+
+const sameTokens = (entries, a, b) => {
+  const ka = entries[a[0]].kinds;
+  const kb = entries[b[0]].kinds;
+  for (let i = 0; i < a[2] - a[1]; i += 1) if (ka[a[1] + i] !== kb[b[1] + i]) return false;
+  return true;
+};
+
+/** The first other occurrence is the partner; overlapping windows of one file are one occurrence, not a copy. */
+const partnerOf = (list, item) => list.find((other) => other !== item && (other[0] !== item[0] || other[1] >= item[2] || item[1] >= other[2]));
+
+const orderedPair = (entries, item, partner) => {
+  const sameFile = entries[item[0]].rel === entries[partner[0]].rel;
+  const itemFirst = sameFile ? item[1] < partner[1] : entries[item[0]].rel < entries[partner[0]].rel;
+  return itemFirst ? [item, partner] : [partner, item];
+};
+
+const addHit = (hits, a, b) => {
+  const key = `${a[0]}|${b[0]}|${b[1] - a[1]}`;
+  const group = hits.get(key);
+  if (group) group.push([a[1], a[2]]); else hits.set(key, [[a[1], a[2]]]);
+};
+
+const cloneHits = (entries, buckets) => {
   const hits = new Map();
   for (const list of buckets.values()) {
     if (list.length < 2) continue;
     for (const item of list) {
-      // The first other occurrence is the partner; overlapping windows of one file are one occurrence, not a copy.
-      const partner = list.find((other) => other !== item && (other[0] !== item[0] || other[1] >= item[2] || item[1] >= other[2]));
-      if (!partner || !same(item, partner)) continue;
-      const order = entries[item[0]].rel === entries[partner[0]].rel ? item[1] < partner[1] : entries[item[0]].rel < entries[partner[0]].rel;
-      const [a, b] = order ? [item, partner] : [partner, item];
-      const key = `${a[0]}|${b[0]}|${b[1] - a[1]}`;
-      const group = hits.get(key);
-      if (group) group.push([a[1], a[2]]); else hits.set(key, [[a[1], a[2]]]);
+      const partner = partnerOf(list, item);
+      if (!partner || !sameTokens(entries, item, partner)) continue;
+      const [a, b] = orderedPair(entries, item, partner);
+      addHit(hits, a, b);
     }
   }
+  return hits;
+};
+
+const blockShape = (file, start, end) => {
+  const nonType = new Set();
+  const shapes = new Map();
+  for (let i = start; i < end; i += 1) {
+    if (!file.types[i]) nonType.add(file.lines[i]);
+    shapes.set(file.lines[i], signedInt32((shapes.get(file.lines[i]) ?? 7) * 31 + file.kinds[i] + 5));
+  }
+  return { nonType: nonType.size, distinct: new Set(shapes.values()).size };
+};
+
+const appendCloneBlock = (blocks, fileA, fileB, start, end, diag, N) => {
+  const shape = blockShape(fileA, start, end);
+  if (shape.nonType < Math.ceil(N / 2) || shape.distinct < Math.ceil(N / 3)) return;
+  const lineA = fileA.lines[start];
+  const endA = fileA.lines[end - 1];
+  blocks.push({ a: fileA, b: fileB, line: lineA, endLine: endA, lines: endA - lineA + 1,
+    twin: { path: fileB.rel, line: fileB.lines[start + diag], endLine: fileB.lines[end - 1 + diag] } });
+};
+
+const cloneBlocks = (entries, hits, N) => {
   const blocks = [];
-  // Shape of a block: the lines outside type declarations and the number of distinct line shapes (a field list of
-  // one decorated DTO shape repeated N times is boilerplate, not a copied helper).
-  const blockShape = (file, start, end) => {
-    const nonType = new Set();
-    const shapes = new Map();
-    for (let i = start; i < end; i += 1) {
-      if (!file.types[i]) nonType.add(file.lines[i]);
-      shapes.set(file.lines[i], ((shapes.get(file.lines[i]) ?? 7) * 31 + file.kinds[i] + 5) | 0);
-    }
-    return { nonType: nonType.size, distinct: new Set(shapes.values()).size };
-  };
   for (const [key, group] of hits) {
     const [ai, bi, diagText] = key.split('|');
     const fileA = entries[Number(ai)];
@@ -170,31 +223,51 @@ export function checkClones({ config, context, graph } = {}) {
     const diag = Number(diagText);
     group.sort((x, y) => x[0] - y[0]);
     let [start, end] = group[0];
-    const flush = () => {
-      const shape = blockShape(fileA, start, end);
-      if (shape.nonType < Math.ceil(N / 2) || shape.distinct < Math.ceil(N / 3)) return;
-      const lineA = fileA.lines[start];
-      const endA = fileA.lines[end - 1];
-      blocks.push({ a: fileA, b: fileB, line: lineA, endLine: endA, lines: endA - lineA + 1,
-        twin: { path: fileB.rel, line: fileB.lines[start + diag], endLine: fileB.lines[end - 1 + diag] } });
-    };
     for (const [nextStart, nextEnd] of group.slice(1)) {
       if (nextStart <= end) { end = Math.max(end, nextEnd); continue; }
-      flush();
+      appendCloneBlock(blocks, fileA, fileB, start, end, diag, N);
       start = nextStart; end = nextEnd;
     }
-    flush();
+    appendCloneBlock(blocks, fileA, fileB, start, end, diag, N);
   }
+  return blocks;
+};
+
+const differentApps = (resolver, a, b) => {
+  const left = appOfFile(resolver, a);
+  const right = appOfFile(resolver, b);
+  return left !== null && right !== null && left !== right;
+};
+
+const cloneViolations = (blocks, resolver, profile, N, T) => {
   blocks.sort((x, y) => x.a.rel.localeCompare(y.a.rel) || x.line - y.line || x.b.rel.localeCompare(y.b.rel));
-  const profile = graph.profile;
-  const differentApps = (a, b) => { const left = appOfFile(graph.resolver, a); const right = appOfFile(graph.resolver, b); return left !== null && right !== null && left !== right; };
-  const violations = blocks.slice(0, MAX_VIOLATIONS).map((block) => ({
+  return blocks.slice(0, MAX_VIOLATIONS).map((block) => ({
     ruleId: 'HFS_DUPLICATE_CODE', path: block.a.rel, line: block.line, endLine: block.endLine, twin: block.twin, lines: block.lines,
-    message: `${block.a.rel}:${block.line}-${block.endLine} duplicates ${block.twin.path}:${block.twin.line}-${block.twin.endLine} (${block.lines} lines, threshold ${N} lines / ${T} tokens, identifiers and literals ignored); ${homeText(profile, block.a.unit === block.b.unit, differentApps(block.a.rel, block.b.rel))}.`,
+    message: `${block.a.rel}:${block.line}-${block.endLine} duplicates ${block.twin.path}:${block.twin.line}-${block.twin.endLine} (${block.lines} lines, threshold ${N} lines / ${T} tokens, identifiers and literals ignored); ${homeText(profile, block.a.unit === block.b.unit, differentApps(resolver, block.a.rel, block.b.rel))}.`,
   }));
+};
+
+const cloneCoverage = (entries, blocks, N, T) => {
   const owners = new Set();
   let duplicatedLines = 0;
   for (const block of blocks) { owners.add(block.a.unit); owners.add(block.b.unit); duplicatedLines += block.lines; }
-  return { violations, coverage: { status: 'checked', minLines: N, minTokens: T, files: entries.length, cloneBlocks: blocks.length, ownersInvolved: owners.size, duplicatedLines,
-    ...(blocks.length > MAX_VIOLATIONS ? { truncated: true } : {}) } };
+  return { status: 'checked', minLines: N, minTokens: T, files: entries.length, cloneBlocks: blocks.length, ownersInvolved: owners.size, duplicatedLines,
+    ...(blocks.length > MAX_VIOLATIONS ? { truncated: true } : {}) };
+};
+
+export function checkClones({ config, context, graph } = {}) {
+  const { lines: N, tokens: T } = graph.resolver.ruleParams().duplicateBlock;
+  const ts = context.ts ?? context.loaded.ts;
+  const entries = [];
+  for (const rel of [...graph.files.keys()].sort(byCodeUnit)) {
+    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 buckets = cloneBuckets(entries, N, T);
+  const blocks = cloneBlocks(entries, cloneHits(entries, buckets), N);
+  const profile = graph.profile;
+  const violations = cloneViolations(blocks, graph.resolver, profile, N, T);
+  return { violations, coverage: cloneCoverage(entries, blocks, N, T) };
 }