@starci/eslint-canon-fe 6.0.2 → 7.1.0

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

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R46 `background-unowned` (BE_BACKGROUND_UNOWNED, BE-CONVENTION 1.6 and 1.13). Background work is a transport that only
+ * a worker app runs:
+ *
+ *   - every job (`*.job.ts`) and consumer (`*.consumer.ts`) is composed by an app of kind `worker`: the file is reachable,
+ *     through runtime imports, from the root module of some worker app declared in hfs.json; one no worker reaches never runs;
+ *   - no scheduler outside `platform/scheduling`: a `@Cron`, `@Interval` or `@Timeout` decorator of `@nestjs/schedule` and a
+ *     `setInterval` call are refused everywhere else (platform/scheduling owns the lease, the fencing and the overlap guard);
+ *   - a method whose name is one of the words the law names (`sweep`, `deliver`, `reconcile`, `retry`, alone or as the
+ *     first word of a camelCase name) in a domain, integrations or feature class is reachable from a composed job or
+ *     consumer: from the job or consumer files and everything they import, and from the files of the feature that holds them
+ *     (its handlers are registered with the command bus, not imported by the job). Mechanisms of platform are exempt.
+ *
+ * Reachability is static (imports, re-exports and the feature of the job); it proves a job or consumer could call the method,
+ * not that it does.
+ */
+export const BACKGROUND_UNOWNED_RULE_IDS = ['BE_BACKGROUND_UNOWNED'];
+
+const RULE = 'BE_BACKGROUND_UNOWNED';
+const BACKGROUND_ROLES = ['job', 'consumer'];
+/** The words the law names for background methods (knowledge/hfs/README.md 5.7). */
+const BACKGROUND_WORDS = ['sweep', 'deliver', 'reconcile', 'retry'];
+const SCHEDULER_DECORATORS = ['Cron', 'Interval', 'Timeout'];
+const SCHEDULER_PACKAGE = '@nestjs/schedule';
+const SCHEDULING_CAPABILITY = 'scheduling';
+
+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;
+};
+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 adjacency = new Map();
+  for (const edge of graph.edges) if (edge.runtime) {
+    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;
+  };
+
+  const workerRoots = resolver.repo.apps.filter(app => app.kind === 'worker').map(app => `apps/${app.name}/src/app.module.ts`).filter(rel => graph.files.has(rel));
+  const composed = closure(workerRoots);
+  const background = [...graph.files.values()].filter(file => roleOf(file.rel) && file.tier === 'feature');
+  const running = background.filter(file => composed.has(file.rel));
+  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 worker app composes${workerRoots.length ? '' : ' (hfs.json declares no worker app)'}; a ${role} runs only when the ${role === 'job' ? 'schedule' : 'message'} module of its feature is imported by the root module of an app of kind worker.`, { role });
+  }
+
+  // Everything a composed job or consumer can reach: its imports, and the files of its own feature (command handlers).
+  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);
+  }
+  const reachable = closure([...roots]);
+
+  let methods = 0;
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    const inScheduling = file.owner?.slot === 'be.platform' && path.posix.basename(file.owner.root) === SCHEDULING_CAPABILITY;
+    const mechanism = file.tier === 'platform';
+    kit.walk(file.sourceFile, node => {
+      if (!inScheduling && ts.isDecorator(node)) {
+        const call = ts.isCallExpression(node.expression) ? node.expression.expression : node.expression;
+        const binding = kit.importBinding(checker, call);
+        if (binding && binding.module === SCHEDULER_PACKAGE && SCHEDULER_DECORATORS.includes(binding.name)) {
+          report(file, node, `@${binding.name} schedules work inside a class outside platform/scheduling. Write a job in transport/schedule/<job>.job.ts that dispatches one command or query, and let platform/scheduling and a worker app run it.`, { scheduler: binding.name });
+        }
+      }
+      if (!inScheduling && ts.isCallExpression(node)) {
+        const callee = node.expression;
+        const bare = ts.isIdentifier(callee) && callee.text === 'setInterval' && kit.declarationsOf(checker, callee).every(declaration => declaration.getSourceFile().isDeclarationFile);
+        const member = ts.isPropertyAccessExpression(callee) && callee.name.text === 'setInterval' && ts.isIdentifier(callee.expression) && ['globalThis', 'window', 'global'].includes(callee.expression.text);
+        const global = bare || member;
+        if (global) report(file, node, 'setInterval starts a scheduler outside platform/scheduling. Write a job in transport/schedule/<job>.job.ts and let platform/scheduling and a worker app run it.', { scheduler: 'setInterval' });
+      }
+      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 job or consumer composed by a worker app can reach. Add a job in transport/schedule or a consumer in transport/message of a feature that runs it, and compose that transport module in a worker app.`, { method: name });
+        }
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', workers: workerRoots.length, jobsAndConsumers: background.length, composed: running.length, backgroundMethods: methods } };
+}

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

@@ -0,0 +1,94 @@
+import { builtinModules } from 'node:module';
+import { sourceLocation } from './typescript.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
+ * 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 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]);
+
+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;
+    }
+    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;
+  };
+
+  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(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];
+      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);
+      }
+    }
+  }
+  return { violations, coverage: { status: 'checked', clientEntries: entries.length } };
+}

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

@@ -0,0 +1,200 @@
+/**
+ * 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, *.job.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.
+ */
+export const CLONE_RULE_IDS = ['HFS_DUPLICATE_CODE'];
+
+const MAX_VIOLATIONS = 200;
+const DOOR_ROLES = new Set(['controller', 'resolver', 'gateway', 'consumer', 'job', 'cli']);
+const APP_ENTRY = 'main.ts';
+const ID = -1;
+const LIT = -2;
+
+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); });
+  };
+  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);
+  }
+  return { kinds: Int32Array.from(kinds), lines: Int32Array.from(lines), types: Uint8Array.from(types) };
+}
+
+/** The app a file belongs to, by the slot binding of the manifest; null for a file of no app. */
+const appOfFile = (resolver, rel) => resolver.classifyPath(rel).bindings?.app ?? null;
+
+/** True for the app entry and the transport doors: their shape is fixed by the convention and their body cannot hold logic. */
+function uniformByDesign(resolver, rel) {
+  const classified = resolver.classifyPath(rel);
+  if (classified.status !== 'owned' || !classified.slot) return false;
+  const slot = resolver.slot(classified.slot);
+  const base = rel.slice(rel.lastIndexOf('/') + 1);
+  if (slot.appKind !== undefined) return base === APP_ENTRY && (slot.requires ?? []).includes(APP_ENTRY);
+  const role = base.split('.').at(-2);
+  return (slot.composedBy?.length ?? 0) > 0 && DOOR_ROLES.has(role) && base.endsWith('.ts');
+}
+
+function homeText(profile, sameOwner, crossApp) {
+  if (crossApp) return 'move it to a package (packages/<pkg>, the shared-code slot of the repository) and import it from both apps';
+  if (sameOwner) return 'extract it once inside the owner and call it from both places';
+  if (profile === 'fe') return 'extract it once inside the app (apps/<app>/src/modules/<capability>/ when pure, apps/<app>/src/hooks/<domain>/ for a React hook) and import it from both';
+  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 B1 = 1000003;
+  const B2 = 92821;
+  let maxTokens = 0;
+  for (const file of entries) maxTokens = Math.max(maxTokens, file.kinds.length);
+  const pow1 = new Int32Array(maxTokens + 1);
+  const pow2 = new Int32Array(maxTokens + 1);
+  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 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 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)];
+    const fileB = entries[Number(bi)];
+    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();
+      start = nextStart; end = nextEnd;
+    }
+    flush();
+  }
+  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) => ({
+    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))}.`,
+  }));
+  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 } : {}) } };
+}

package/runtime/scripts/checks/architecture/config-unread.mjs

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+
+/**
+ * R24 `arch-config-unread` (HFS_ARCH_CONFIG_UNREAD). The machine reads `hfs.json` and nothing else; a config file it
+ * no longer reads is dead text that says a rule is tuned when it is not, and a declaration that yields no analysed file
+ * is a machine that judged nothing. Both are red:
+ *
+ *   - a tracked `architecture.json` (the retired per-repository config; the declaration is hfs.json, the rest is derived
+ *     from the slot manifest);
+ *   - a repository whose declaration and tsconfig load but whose program holds no production source file.
+ */
+export const CONFIG_UNREAD_RULE_IDS = ['HFS_ARCH_CONFIG_UNREAD'];
+
+const RULE = 'HFS_ARCH_CONFIG_UNREAD';
+/** Config file names an earlier machine read and this one never does. */
+const RETIRED_CONFIG_NAMES = ['architecture.json'];
+
+export function checkConfigUnread({ config, context }) {
+  const violations = [];
+  const tree = treeOf(config.root);
+  let retired = 0;
+  for (const file of [...tree.files].sort()) {
+    if (!RETIRED_CONFIG_NAMES.includes(path.posix.basename(file))) continue;
+    retired += 1;
+    violations.push({ ruleId: RULE, path: file, line: 1, column: 1,
+      message: `${file} is a config the architecture machine no longer reads. hfs.json declares the repository; owners, roots, tiers and budgets come from the slot manifest. Delete ${file}.` });
+  }
+  const analysed = context.files.length;
+  if (analysed === 0) {
+    violations.push({ ruleId: RULE, path: 'hfs.json', line: 1, column: 1,
+      message: 'hfs.json and the TypeScript projects load but the machine analysed no production source file, so it judged nothing. Declare the apps that hold source in hfs.json, or fix the tsconfig include so the source is in the program.' });
+  }
+  return { violations, coverage: { status: 'checked', retired, analysed } };
+}