@starci/hfs 4.0.9 → 4.1.0

package/runtime/scripts/hfs/architecture/default-deny.mjs

@@ -19,111 +19,136 @@ const ORIGIN_HEADERS = new Set(['origin', 'referer', 'referrer']);
 const METADATA_READERS = new Set(['get', 'getAll', 'getAllAndMerge', 'getAllAndOverride']);
 const LABEL = { throttler: 'the throttler guard', csrf: 'the CSRF origin guard of platform/http-security', auth: 'AuthGuard of domain/identity' };
 
+const keySymbol = (kit, checker, node) => (node ? kit.aliased(checker, kit.symbolAt(checker, node)) ?? null : null);
+
+const extendsThrottlerType = (kit, checker, declaration, type, depth) => {
+  if (kit.isImportOf(checker, type.expression, 'ThrottlerGuard', '@nestjs/throttler')) return true;
+  return kit.declarationsOf(checker, type.expression).some(parent => parent !== declaration && extendsThrottler(kit, parent, depth + 1));
+};
+
+function extendsThrottler(kit, declaration, depth = 0) {
+  if (!kit.ts.isClassDeclaration(declaration) || depth > 8) return false;
+  const checker = kit.checkerOf(declaration.getSourceFile());
+  if (!checker) return false;
+  const types = (declaration.heritageClauses ?? []).flatMap(clause => [...clause.types]);
+  return types.some(type => extendsThrottlerType(kit, checker, declaration, type, depth));
+}
+
+const collectSetMetadataKeys = (kit, file, keys) => {
+  const { ts } = kit;
+  const checker = kit.checkerOf(file.sourceFile);
+  if (!checker) return;
+  kit.walk(file.sourceFile, node => {
+    if (ts.isCallExpression(node) && kit.isImportOf(checker, node.expression, 'SetMetadata', '@nestjs/common')) {
+      const key = keySymbol(kit, checker, node.arguments[0]);
+      if (key) keys.add(key);
+    }
+    return true;
+  });
+};
+
+/** The symbols a SetMetadata call of the owner writes as metadata keys: what its door decorators (`@RateLimit(tier)`) attach. */
+const writtenKeys = (kit, graph, owner, cache) => {
+  if (cache.has(owner.root)) return cache.get(owner.root);
+  const keys = new Set();
+  for (const file of graph.files.values()) {
+    if (file.owner?.root === owner.root) collectSetMetadataKeys(kit, file, keys);
+  }
+  cache.set(owner.root, keys);
+  return keys;
+};
+
+/** True when the class reads a request origin or referer header (the origin/referer allowlist of the CSRF guard). */
+const readsOrigin = (kit, declaration) => {
+  const { ts } = kit;
+  let found = false;
+  kit.walk(declaration, node => {
+    let name = null;
+    if (ts.isPropertyAccessExpression(node)) name = node.name.text;
+    else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) name = node.argumentExpression.text;
+    if (name && ORIGIN_HEADERS.has(name.toLowerCase())) found = true;
+    return !found;
+  });
+  return found;
+};
+
+const isMetadataRead = (ts, node) => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && METADATA_READERS.has(node.expression.name.text);
+
+/** True when the class reads, through a metadata getter, a key its own capability's SetMetadata decorators write. */
+const readsDoorMetadata = (kit, graph, keyCache, declaration, owner) => {
+  const checker = kit.checkerOf(declaration.getSourceFile());
+  if (!checker) return false;
+  const keys = writtenKeys(kit, graph, owner, keyCache);
+  let found = false;
+  kit.walk(declaration, node => {
+    if (isMetadataRead(kit.ts, node)) {
+      const key = keySymbol(kit, checker, node.arguments[0]);
+      if (key && keys.has(key)) found = true;
+    }
+    return !found;
+  });
+  return found;
+};
+
+const classifyDeclaration = (kit, graph, keyCache, declaration) => {
+  const { ts } = kit;
+  const owner = kit.ownerOfDeclaration(declaration);
+  if (owner?.tier === 'platform' && owner.name === 'http-security' && ts.isClassDeclaration(declaration)) {
+    if (readsOrigin(kit, declaration)) return 'csrf';
+    if (readsDoorMetadata(kit, graph, keyCache, declaration, owner)) return 'throttler';
+  }
+  if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'AuthGuard') return 'auth';
+  return null;
+};
+
+const classify = (kit, graph, keyCache, checker, node) => {
+  if (!node) return null;
+  if (kit.importBinding(checker, node)?.module === '@nestjs/throttler') return 'throttler';
+  const declarations = kit.declarationsOf(checker, node);
+  if (declarations.some(declaration => extendsThrottler(kit, declaration))) return 'throttler';
+  for (const declaration of declarations) {
+    const role = classifyDeclaration(kit, graph, keyCache, declaration);
+    if (role) return role;
+  }
+  return null;
+};
+
+const roleMessages = (app, roles, anchor) => {
+  const out = [];
+  for (const role of ORDER) {
+    const entries = roles.filter(item => item.role === role);
+    if (entries.length === 0) out.push({ node: anchor, message: `App ${app.name} does not provide ${LABEL[role]} as an APP_GUARD; an api app is denied by default: throttler, then CSRF origin guard, then AuthGuard.` });
+    else if (entries.length > 1) out.push({ node: entries[1].guard.node, message: `App ${app.name} provides ${LABEL[role]} more than once as an APP_GUARD.` });
+  }
+  return out;
+};
+
+const orderMessages = (app, roles) => {
+  const indexes = ORDER.map(role => roles.findIndex(item => item.role === role));
+  if (!indexes.every(index => index >= 0)) return [];
+  const out = [];
+  for (let i = 1; i < indexes.length; i += 1) {
+    if (indexes[i] < indexes[i - 1]) out.push({ node: roles[indexes[i]].guard.node, message: `App ${app.name} provides ${LABEL[ORDER[i]]} before ${LABEL[ORDER[i - 1]]}; the APP_GUARD order is throttler, CSRF origin guard, AuthGuard.` });
+  }
+  return out;
+};
+
 export function checkDefaultDeny(input) {
   const { config } = input;
   const kit = machineKit(input);
-  const { ts } = kit;
   const violations = [];
-  let apps = 0;
-
-  const extendsThrottler = (declaration, depth = 0) => {
-    if (!ts.isClassDeclaration(declaration) || depth > 8) return false;
-    const checker = kit.checkerOf(declaration.getSourceFile());
-    if (!checker) return false;
-    for (const clause of declaration.heritageClauses ?? []) {
-      for (const type of clause.types) {
-        if (kit.isImportOf(checker, type.expression, 'ThrottlerGuard', '@nestjs/throttler')) return true;
-        if (kit.declarationsOf(checker, type.expression).some(parent => parent !== declaration && extendsThrottler(parent, depth + 1))) return true;
-      }
-    }
-    return false;
-  };
-
-  const keySymbol = (checker, node) => (node ? kit.aliased(checker, kit.symbolAt(checker, node)) ?? null : null);
-
-  /** The symbols a SetMetadata call of the owner writes as metadata keys: what its door decorators (`@RateLimit(tier)`) attach. */
-  const writtenKeys = (owner, cache = new Map()) => {
-    if (cache.has(owner.root)) return cache.get(owner.root);
-    const keys = new Set();
-    for (const file of input.graph.files.values()) {
-      if (file.owner?.root !== owner.root) continue;
-      const checker = kit.checkerOf(file.sourceFile);
-      if (!checker) continue;
-      kit.walk(file.sourceFile, node => {
-        if (ts.isCallExpression(node) && kit.isImportOf(checker, node.expression, 'SetMetadata', '@nestjs/common')) {
-          const key = keySymbol(checker, node.arguments[0]);
-          if (key) keys.add(key);
-        }
-        return true;
-      });
-    }
-    cache.set(owner.root, keys);
-    return keys;
-  };
   const keyCache = new Map();
-
-  /** True when the class reads a request origin or referer header (the origin/referer allowlist of the CSRF guard). */
-  const readsOrigin = declaration => {
-    let found = false;
-    kit.walk(declaration, node => {
-      if (ts.isPropertyAccessExpression(node) && ORIGIN_HEADERS.has(node.name.text.toLowerCase())) found = true;
-      else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression) && ORIGIN_HEADERS.has(node.argumentExpression.text.toLowerCase())) found = true;
-      return !found;
-    });
-    return found;
-  };
-
-  /** True when the class reads, through a metadata getter, a key its own capability's SetMetadata decorators write. */
-  const readsDoorMetadata = (declaration, owner) => {
-    const checker = kit.checkerOf(declaration.getSourceFile());
-    if (!checker) return false;
-    const keys = writtenKeys(owner, keyCache);
-    let found = false;
-    kit.walk(declaration, node => {
-      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && METADATA_READERS.has(node.expression.name.text)) {
-        const key = keySymbol(checker, node.arguments[0]);
-        if (key && keys.has(key)) found = true;
-      }
-      return !found;
-    });
-    return found;
-  };
-
-  const classify = (checker, node) => {
-    if (!node) return null;
-    if (kit.importBinding(checker, node)?.module === '@nestjs/throttler') return 'throttler';
-    const declarations = kit.declarationsOf(checker, node);
-    if (declarations.some(declaration => extendsThrottler(declaration))) return 'throttler';
-    for (const declaration of declarations) {
-      const owner = kit.ownerOfDeclaration(declaration);
-      if (owner?.tier === 'platform' && owner.name === 'http-security' && ts.isClassDeclaration(declaration)) {
-        if (readsOrigin(declaration)) return 'csrf';
-        if (readsDoorMetadata(declaration, owner)) return 'throttler';
-      }
-      if (owner?.tier === 'domain' && owner.name === 'identity' && ts.isClassDeclaration(declaration) && declaration.name?.text === 'AuthGuard') return 'auth';
-    }
-    return null;
-  };
+  let apps = 0;
 
   for (const app of config.apps.filter(item => item.kind === 'api')) {
     const root = kit.appRoot(app.name);
     if (!root) continue;
     apps += 1;
     const guards = kit.providersOf(root, 'APP_GUARD', '@nestjs/core');
-    const roles = guards.map(guard => ({ guard, role: classify(guard.checker, guard.useClass) }));
+    const roles = guards.map(guard => ({ guard, role: classify(kit, input.graph, keyCache, guard.checker, guard.useClass) }));
     const anchor = guards[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
-    const finding = (node, message) => violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, node), app: app.name, message });
-    for (const role of ORDER) {
-      const entries = roles.filter(item => item.role === role);
-      if (entries.length === 0) finding(anchor, `App ${app.name} does not provide ${LABEL[role]} as an APP_GUARD; an api app is denied by default: throttler, then CSRF origin guard, then AuthGuard.`);
-      else if (entries.length > 1) finding(entries[1].guard.node, `App ${app.name} provides ${LABEL[role]} more than once as an APP_GUARD.`);
-    }
-    const indexes = ORDER.map(role => roles.findIndex(item => item.role === role));
-    if (indexes.every(index => index >= 0)) {
-      for (let i = 1; i < indexes.length; i += 1) {
-        if (indexes[i] < indexes[i - 1]) finding(roles[indexes[i]].guard.node, `App ${app.name} provides ${LABEL[ORDER[i]]} before ${LABEL[ORDER[i - 1]]}; the APP_GUARD order is throttler, CSRF origin guard, AuthGuard.`);
-      }
-    }
+    const messages = [...roleMessages(app, roles, anchor), ...orderMessages(app, roles)];
+    for (const { node, message } of messages) violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, node), app: app.name, message });
   }
   return { violations, coverage: { status: 'checked', apps } };
 }

package/runtime/scripts/hfs/architecture/doc-language.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { treeOf } from './required-files.mjs';
 import { documentLanguageHits, isDocument, isLocalizedDataFile } from '../../lib/language.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R96 `doc-language` (HFS_DOC_NOT_ENGLISH). Every Markdown and YAML document under knowledge/, docs/, src/ and apps/ is English:
@@ -23,7 +24,7 @@ export function checkDocLanguage({ config, graph }) {
   const tree = treeOf(config.root);
   const violations = [];
   let files = 0;
-  for (const file of [...tree.files].sort()) {
+  for (const file of [...tree.files].sort(byCodeUnit)) {
     if (!DOCUMENT_ROOTS.includes(file.split('/')[0]) || !isDocument(file) || file.split('/').includes('node_modules')) continue;
     const classified = resolver.classifyPath(file);
     if (isLocalizedDataFile(file, classified.status === 'owned' ? classified.slot : null)) continue;

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

@@ -16,43 +16,58 @@ export const ENTRYPOINT_RULE_IDS = ['BE_ENTRYPOINT_ONLY_IN_APPS'];
 
 const RULE = 'BE_ENTRYPOINT_ONLY_IN_APPS';
 
+const TRANSPARENT = ['isVoidExpression', 'isAwaitExpression', 'isParenthesizedExpression', 'isNonNullExpression'];
+
+/** The identifier a top-level statement calls: `bootstrap()`, `void bootstrap()`, `bootstrap().catch(...)`. */
+function calledIdentifier(ts, expression) {
+  let current = expression;
+  for (;;) {
+    if (TRANSPARENT.some(test => ts[test](current))) current = current.expression;
+    else if (ts.isCallExpression(current)) {
+      if (ts.isIdentifier(current.expression)) return current.expression;
+      current = current.expression;
+    } else if (ts.isPropertyAccessExpression(current)) current = current.expression;
+    else return null;
+  }
+}
+
+const isNestFactoryCreate = (kit, ts, checker, node) => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text.startsWith('create')
+  && kit.isImportOf(checker, node.expression.expression, 'NestFactory', '@nestjs/core');
+
+const isMainFile = file => (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || isTestWorldSlot(file.slot);
+
+/** Counts the NestFactory.create* calls of an entrypoint owner and reports them in any other file. */
+function inspectFactoryCalls(kit, file, isMain, report) {
+  const { ts } = kit;
+  const checker = kit.checkerOf(file.sourceFile);
+  let entrypoints = 0;
+  kit.walk(file.sourceFile, node => {
+    if (!isNestFactoryCreate(kit, ts, checker, node)) return;
+    if (isMain) entrypoints += 1;
+    else report(node, `NestFactory.${node.expression.name.text}() starts a process outside apps/<app>/src/main.ts; entrypoints live in an app's main.ts only.`);
+  });
+  return entrypoints;
+}
+
+function inspectBootstrapCalls(ts, file, report) {
+  for (const statement of file.sourceFile.statements) {
+    if (!ts.isExpressionStatement(statement)) continue;
+    if (calledIdentifier(ts, statement.expression)?.text === 'bootstrap') {
+      report(statement, "A top-level bootstrap() call starts a process outside apps/<app>/src/main.ts; entrypoints live in an app's main.ts only.");
+    }
+  }
+}
+
 export function checkEntrypoints(input) {
   const { graph } = input;
   const kit = machineKit(input);
-  const { ts } = kit;
   const violations = [];
   let entrypoints = 0;
-  /** The identifier a top-level statement calls: `bootstrap()`, `void bootstrap()`, `bootstrap().catch(...)`. */
-  const calledIdentifier = expression => {
-    let current = expression;
-    for (;;) {
-      if (ts.isVoidExpression(current) || ts.isAwaitExpression(current) || ts.isParenthesizedExpression(current) || ts.isNonNullExpression(current)) current = current.expression;
-      else if (ts.isCallExpression(current)) {
-        if (ts.isIdentifier(current.expression)) return current.expression;
-        current = current.expression;
-      } else if (ts.isPropertyAccessExpression(current)) current = current.expression;
-      else return null;
-    }
-  };
   for (const file of graph.files.values()) {
-    const isMain = (Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'main.ts') || isTestWorldSlot(file.slot);
-    const checker = kit.checkerOf(file.sourceFile);
+    const isMain = isMainFile(file);
     const report = (node, message) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message });
-    kit.walk(file.sourceFile, node => {
-      if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text.startsWith('create')
-        && kit.isImportOf(checker, node.expression.expression, 'NestFactory', '@nestjs/core')) {
-        if (isMain) entrypoints += 1;
-        else report(node, `NestFactory.${node.expression.name.text}() starts a process outside apps/<app>/src/main.ts; entrypoints live in an app's main.ts only.`);
-      }
-      return true;
-    });
-    if (isMain) continue;
-    for (const statement of file.sourceFile.statements) {
-      if (!ts.isExpressionStatement(statement)) continue;
-      if (calledIdentifier(statement.expression)?.text === 'bootstrap') {
-        report(statement, "A top-level bootstrap() call starts a process outside apps/<app>/src/main.ts; entrypoints live in an app's main.ts only.");
-      }
-    }
+    entrypoints += inspectFactoryCalls(kit, file, isMain, report);
+    if (!isMain) inspectBootstrapCalls(kit.ts, file, report);
   }
   return { violations, coverage: { status: 'checked', entrypoints } };
 }

package/runtime/scripts/hfs/architecture/error-codes.mjs

@@ -11,6 +11,24 @@ export const ERROR_CODE_RULE_IDS = ['BE_ERROR_HOME'];
 
 const RULE = 'BE_ERROR_HOME';
 
+// Judge each member of one <C>ErrorCode enum; returns how many string-literal codes it held.
+const checkEnumCodes = (statement, { file, capability, shape, kit, ts, seen, violations }) => {
+  let checked = 0;
+  for (const member of statement.members) {
+    const report = message => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, member), message });
+    const name = kit.propertyNameText(member.name) ?? '?';
+    const value = member.initializer && ts.isStringLiteralLike(member.initializer) ? member.initializer.text : null;
+    if (value === null) { report(`${statement.name.text}.${name} must be a string literal code (\`${capability}_<WHAT>\`); a computed or numeric code cannot be checked or told apart in a log.`); continue; }
+    checked += 1;
+    if (!shape.test(value) || /_(?:ERROR|EXCEPTION)$/u.test(value)) {
+      report(`${statement.name.text}.${name} = "${value}" must match ${capability}_<WHAT> in UPPER_SNAKE with the capability prefix and no _ERROR or _EXCEPTION suffix.`);
+    }
+    if (seen.has(value)) report(`Error code "${value}" is already declared in ${seen.get(value)}; a code is unique across the repository.`);
+    else seen.set(value, file.rel);
+  }
+  return checked;
+};
+
 export function checkErrorCodes(input) {
   const { graph } = input;
   const kit = machineKit(input);
@@ -27,18 +45,7 @@ export function checkErrorCodes(input) {
     for (const statement of file.sourceFile.statements) {
       if (!ts.isEnumDeclaration(statement) || !statement.name.text.endsWith('ErrorCode')) continue;
       enums += 1;
-      for (const member of statement.members) {
-        const report = message => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, member), message });
-        const name = kit.propertyNameText(member.name) ?? '?';
-        const value = member.initializer && ts.isStringLiteralLike(member.initializer) ? member.initializer.text : null;
-        if (value === null) { report(`${statement.name.text}.${name} must be a string literal code (\`${capability}_<WHAT>\`); a computed or numeric code cannot be checked or told apart in a log.`); continue; }
-        codes += 1;
-        if (!shape.test(value) || /_(?:ERROR|EXCEPTION)$/u.test(value)) {
-          report(`${statement.name.text}.${name} = "${value}" must match ${capability}_<WHAT> in UPPER_SNAKE with the capability prefix and no _ERROR or _EXCEPTION suffix.`);
-        }
-        if (seen.has(value)) report(`Error code "${value}" is already declared in ${seen.get(value)}; a code is unique across the repository.`);
-        else seen.set(value, file.rel);
-      }
+      codes += checkEnumCodes(statement, { file, capability, shape, kit, ts, seen, violations });
     }
   }
   return { violations, coverage: { status: 'checked', enums, codes } };

package/runtime/scripts/hfs/architecture/error-masked.mjs

@@ -10,50 +10,63 @@ export const ERROR_MASKED_RULE_IDS = ['BE_ERROR_MASKED'];
 
 const RULE = 'BE_ERROR_MASKED';
 
+const inErrorsOf = kit => (checker, node) => kit.declarationsOf(checker, node).map(kit.ownerOfDeclaration).some(owner => owner?.tier === 'platform' && owner.name === 'errors');
+
+function appFilterViolations(kit, inErrors, app, root) {
+  const violations = [];
+  const filters = kit.providersOf(root, 'APP_FILTER', '@nestjs/core');
+  const anchor = filters[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
+  if (filters.length !== 1) {
+    violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, anchor), app: app.name,
+      message: `App ${app.name} provides ${filters.length} APP_FILTER entries; an api app provides exactly one, the ExceptionFilter of platform/errors.` });
+  }
+  for (const filter of filters) {
+    if (!filter.useClass || !inErrors(filter.checker, filter.useClass)) {
+      violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, filter.node), app: app.name,
+        message: 'The APP_FILTER must be `useClass` of the filter declared in platform/errors; any other filter can let an undeclared error reach the client unmasked.' });
+    }
+  }
+  return violations;
+}
+
+const isGraphqlRegistration = (kit, checker, node) => kit.ts.isCallExpression(node) && kit.ts.isPropertyAccessExpression(node.expression)
+  && ['forRoot', 'forRootAsync'].includes(node.expression.name.text)
+  && kit.isImportOf(checker, node.expression.expression, 'GraphQLModule', '@nestjs/graphql');
+
+function passesMaskedFormatError(kit, inErrors, checker, call) {
+  const { ts } = kit;
+  let masked = false;
+  for (const argument of call.arguments) {
+    kit.walk(argument, inner => {
+      if ((ts.isPropertyAssignment(inner) || ts.isShorthandPropertyAssignment(inner)) && kit.propertyNameText(inner.name) === 'formatError'
+        && inErrors(checker, kit.valueOfProperty(inner))) masked = true;
+    });
+  }
+  return masked;
+}
+
 export function checkErrorMasked(input) {
   const { config, graph } = input;
   const kit = machineKit(input);
-  const { ts } = kit;
   const violations = [];
-  const inErrors = (checker, node) => kit.declarationsOf(checker, node).map(kit.ownerOfDeclaration).some(owner => owner && owner.tier === 'platform' && owner.name === 'errors');
+  const inErrors = inErrorsOf(kit);
   let apps = 0;
   for (const app of config.apps.filter(item => item.kind === 'api')) {
     const root = kit.appRoot(app.name);
     if (!root) continue;
     apps += 1;
-    const filters = kit.providersOf(root, 'APP_FILTER', '@nestjs/core');
-    const anchor = filters[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
-    if (filters.length !== 1) {
-      violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, anchor), app: app.name,
-        message: `App ${app.name} provides ${filters.length} APP_FILTER entries; an api app provides exactly one, the ExceptionFilter of platform/errors.` });
-    }
-    for (const filter of filters) {
-      if (!filter.useClass || !inErrors(filter.checker, filter.useClass)) {
-        violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, filter.node), app: app.name,
-          message: 'The APP_FILTER must be `useClass` of the filter declared in platform/errors; any other filter can let an undeclared error reach the client unmasked.' });
-      }
-    }
+    violations.push(...appFilterViolations(kit, inErrors, app, root));
   }
   let graphql = 0;
   for (const file of graph.files.values()) {
     const checker = kit.checkerOf(file.sourceFile);
     kit.walk(file.sourceFile, node => {
-      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ['forRoot', 'forRootAsync'].includes(node.expression.name.text)
-        && kit.isImportOf(checker, node.expression.expression, 'GraphQLModule', '@nestjs/graphql'))) return true;
+      if (!isGraphqlRegistration(kit, checker, node)) return;
       graphql += 1;
-      let masked = false;
-      for (const argument of node.arguments) {
-        kit.walk(argument, inner => {
-          if ((ts.isPropertyAssignment(inner) || ts.isShorthandPropertyAssignment(inner)) && kit.propertyNameText(inner.name) === 'formatError'
-            && inErrors(checker, kit.valueOfProperty(inner))) masked = true;
-          return true;
-        });
-      }
-      if (!masked) {
+      if (!passesMaskedFormatError(kit, inErrors, checker, node)) {
         violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node),
           message: `GraphQLModule.${node.expression.name.text} must pass the \`formatError\` exported by platform/errors; without it a resolver error reaches the client with its internal message.` });
       }
-      return true;
     });
   }
   return { violations, coverage: { status: 'checked', apps, graphqlRegistrations: graphql } };

package/runtime/scripts/hfs/architecture/fe-slot-allows.mjs

@@ -1,6 +1,7 @@
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../allows.mjs';
 import { isFeTestPath } from '../rules/fe-no-tests.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R94 `fe-slot-allows` (FE_SLOT_FILE_ROLE). A front-end slot that owns a whole directory (`fe.route`, `fe.feature`,
@@ -10,7 +11,7 @@ import { isFeTestPath } from '../rules/fe-no-tests.mjs';
  * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
  * Files no slot owns are HFS_PATH_NO_SLOT's (`starci app check`), so together every front-end file is placed by exactly one slot and
  * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
- * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * (R97 FE_NO_TESTS): that rule is the one finding of such a file, so this check leaves it alone, as
  * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];
@@ -23,7 +24,7 @@ export function checkFeSlotAllows({ config, graph }) {
   const violations = [];
   let files = 0;
   const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
-  for (const file of [...tree.files].sort()) {
+  for (const file of [...tree.files].sort(byCodeUnit)) {
     if (isFeTestPath(file)) continue;   // FE_NO_TESTS's, the one finding of that file
     const classified = resolver.classifyPath(file);
     if (classified.status !== 'owned') continue;

package/runtime/scripts/hfs/architecture/feature-shape.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../allows.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R29 `feature-shape` (BE_FEATURE_SHAPE). A feature root holds `index.ts`, `<feature>.module.ts`, `application/`,
@@ -14,6 +15,28 @@ export const FEATURE_SHAPE_RULE_IDS = ['BE_FEATURE_SHAPE'];
 
 const RULE = 'BE_FEATURE_SHAPE';
 
+// {message, extra} for one feature file the slot answer refuses, or null when it sits where a slot allows it.
+const featureFileFinding = (file, owner, verdict) => {
+  const feature = path.posix.basename(owner.root);
+  if (verdict.slot === owner.slot) {
+    // A file the feature root slot itself allows is in place (the cli feature root allows its <group>/ folders); any other file
+    // deeper than the root sits in a directory no slot claims.
+    // A directory entry (`transport/`, `application/`) is held by its own slots: below it, only those slots admit a file.
+    if (verdict.allowed && !String(verdict.entry ?? '').endsWith('/')) return null;
+    if (verdict.relative.includes('/')) {
+      const folder = verdict.relative.split('/')[0];
+      return { message: `${file} sits in ${owner.root}/${folder}/, which no slot owns; a feature root holds only ${verdict.allows.join(', ')}, and transport/ holds one folder per protocol a slot names. Move it to application/ or a transport/<protocol>/ folder, or delete it.`,
+        extra: { feature, folder } };
+    }
+    if (verdict.allowed) return null;
+    return { message: `${file} is not allowed at the root of feature ${feature}; the root holds only ${verdict.allows.join(', ')}. Move it under application/ or transport/<protocol>/.`, extra: { feature } };
+  }
+  if (verdict.allowed) return null;
+  const where = `${verdict.slot} (${verdict.root})`;
+  const forbidden = verdict.forbiddenBy ? ` ${verdict.forbiddenBy} is forbidden there;` : '';
+  return { message: `${file} is not allowed in ${where};${forbidden} that folder holds only ${verdict.allows.join(', ')}. Rename it to an allowed role or move it to the folder its role belongs to.`, extra: { feature, slot: verdict.slot } };
+};
+
 export function checkFeatureShape({ config, graph }) {
   const resolver = graph.resolver;
   const tree = treeOf(config.root);
@@ -21,32 +44,15 @@ export function checkFeatureShape({ config, graph }) {
   const features = new Set();
   let files = 0;
   const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
-  for (const file of [...tree.files].sort()) {
+  for (const file of [...tree.files].sort(byCodeUnit)) {
     const owner = resolver.ownerOf(file);
     if (!owner || resolver.slot(owner.slot)?.tier !== 'feature') continue;
     features.add(owner.root);
     files += 1;
     const verdict = allowsFile(resolver, file);
     if (!verdict) continue;
-    const feature = path.posix.basename(owner.root);
-    const where = `${verdict.slot} (${verdict.root})`;
-    if (verdict.slot === owner.slot) {
-      // A file the feature root slot itself allows is in place (the cli feature root allows its <group>/ folders); any other file
-      // deeper than the root sits in a directory no slot claims.
-      // A directory entry (`transport/`, `application/`) is held by its own slots: below it, only those slots admit a file.
-      if (verdict.allowed && !String(verdict.entry ?? '').endsWith('/')) continue;
-      if (verdict.relative.includes('/')) {
-        const folder = verdict.relative.split('/')[0];
-        report(file, `${file} sits in ${owner.root}/${folder}/, which no slot owns; a feature root holds only ${verdict.allows.join(', ')}, and transport/ holds one folder per protocol a slot names. Move it to application/ or a transport/<protocol>/ folder, or delete it.`,
-          { feature, folder });
-      } else if (!verdict.allowed) {
-        report(file, `${file} is not allowed at the root of feature ${feature}; the root holds only ${verdict.allows.join(', ')}. Move it under application/ or transport/<protocol>/.`, { feature });
-      }
-      continue;
-    }
-    if (verdict.allowed) continue;
-    const forbidden = verdict.forbiddenBy ? ` ${verdict.forbiddenBy} is forbidden there;` : '';
-    report(file, `${file} is not allowed in ${where};${forbidden} that folder holds only ${verdict.allows.join(', ')}. Rename it to an allowed role or move it to the folder its role belongs to.`, { feature, slot: verdict.slot });
+    const finding = featureFileFinding(file, owner, verdict);
+    if (finding) report(file, finding.message, finding.extra);
   }
   return { violations, coverage: { status: 'checked', features: features.size, files } };
 }

package/runtime/scripts/hfs/architecture/framework-pinned.mjs

@@ -15,7 +15,7 @@ const cache = new Map(); // only the installed knowledge file is cached; an expl
 const EXACT_NAME = /^[^\\/*?[\]{}\s]+$/;
 
 function unavailable(file, detail) {
-  return Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
+  return new Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
 }
 
 function load(file) {