@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/architecture/ast-walks.d.mts

@@ -0,0 +1,89 @@
+import type { Decorator, Expression, Identifier, Node, PrivateIdentifier, Program, SourceFile, StringLiteralLike, Symbol as TsSymbol, TypeChecker } from 'typescript';
+import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+import type { ArchitectureViolation } from './hfs-graph.mjs';
+/** One finding row: rule id, root-relative path, node position and message, plus rule extras. */
+export type Violation = ArchitectureViolation;
+/** The compiler programs a checker context owns (what `programSourcesOf` searches). */
+export interface ProgramContext {
+    programs: Program[];
+}
+/** What `tracedFrameworkKinds` hands a `directOf` callback for one selected node. */
+export interface DirectOfInput {
+    symbol: TsSymbol;
+    selected: Node;
+    targets: Map<TsSymbol, string>;
+}
+/** Maps a selected node's symbol to a framework kind, or null. */
+export type DirectOf = (ts: TypeScriptApi, checker: TypeChecker, input: DirectOfInput) => string | null | undefined;
+/** Maps a shorthand-property's value symbol to a framework kind, or null. */
+export type ShorthandOf = (ts: TypeScriptApi, checker: TypeChecker, target: TsSymbol | null | undefined, targets: Map<TsSymbol, string>) => string | null | undefined;
+/** The options `tracedFrameworkKinds` takes (`seen` and `depth` are its own recursion state). */
+export interface TraceOptions {
+    seen?: Set<TsSymbol>;
+    depth?: number;
+    directOf?: DirectOf | null;
+    shorthandOf?: ShorthandOf | null;
+    newExpression?: boolean;
+}
+/** The module a statement statically binds (see `moduleExportsOf`). */
+export interface ModuleExports {
+    specifierNode: StringLiteralLike;
+    specifier: string;
+    symbol: TsSymbol | null;
+    exports: Map<string, TsSymbol | null>;
+}
+/** `expression` unwrapped by the caller's own predicate set (a predicate absent on an older ts reads as never). */
+export declare function unwrapEach(_ts: TypeScriptApi, expression: Node | null | undefined, predicates: readonly (((node: Node) => boolean) | null | undefined)[]): Node | null | undefined;
+/** `value` with every TS alias hop resolved (a re-exported import reads as its target symbol). */
+export declare function normalizedSymbolValue(ts: TypeScriptApi, checker: TypeChecker, value?: TsSymbol | null | undefined): TsSymbol | null | undefined;
+/** The symbol `node` names, aliases resolved. */
+export declare function normalizedSymbol(ts: TypeScriptApi, checker: TypeChecker, node: Node): TsSymbol | null | undefined;
+/** The identifier or member-name node an expression selects through unwrapExpression, or null. */
+export declare function selectedNode(ts: TypeScriptApi, expression: Node): Identifier | PrivateIdentifier | StringLiteralLike | null;
+/**
+ * The symbol `node` ultimately evaluates to: its own symbol, followed through a single `const` variable
+ * initializer (and so on). `unselected: 'null'` answers null when `node` selects no name at all.
+ */
+export declare function valueSymbol(ts: TypeScriptApi, checker: TypeChecker, node: Node, seen?: Set<TsSymbol>, { unselected }?: {
+    unselected?: 'node' | 'null';
+}): TsSymbol | null | undefined;
+/**
+ * The expressions `declaration` returns: its body when it is an expression-bodied arrow/function, else every
+ * `return`'s argument without descending into nested functions. `functionLike` overrides which node kinds bound
+ * that descent (default the four callable declaration kinds; pass `ts.isFunctionLike` for the wider set).
+ */
+export declare function returnedExpressions(ts: TypeScriptApi, declaration: Node, { functionLike }?: {
+    functionLike?: ((node: Node) => boolean) | null;
+}): Expression[];
+/** A node's decorators across TS versions (ts.getDecorators, else the legacy `decorators` property). */
+export declare function nodeDecorators(ts: TypeScriptApi, node: Node): readonly Decorator[];
+/** One finding row: rule id, root-relative path, node position and message, plus rule extras. */
+export declare function violation(config: ArchitectureConfig, sourceFile: SourceFile, node: Node, ruleId: string, message: string, extra?: Record<string, unknown>): Violation;
+/** Whether `match` holds for `node` or a descendant (the walk stops at the first match). */
+export declare function anyDescendant(ts: TypeScriptApi, node: Node, match: (node: Node) => boolean): boolean;
+export declare function tracedFrameworkKinds(ts: TypeScriptApi, checker: TypeChecker, expression: Node | null | undefined, targets: Map<TsSymbol, string>, { seen, depth, directOf, shorthandOf, newExpression }?: TraceOptions): Set<string>;
+/** 'unproven framework' | 'multiple framework' | the one kind | null, for a decorator whose expression constructs. */
+export declare function constructedDecoratorKind(ts: TypeScriptApi, checker: TypeChecker, decorator: Decorator, targets: Map<TsSymbol, string>, traceOpts?: TraceOptions): string | null;
+/** The target a decorator resolves to through a `let`/`var` alias's single initializer, or null. */
+export declare function mutableDecoratorKind(ts: TypeScriptApi, checker: TypeChecker, decorator: Decorator, targets: Map<TsSymbol, string>): string | null;
+/** The callee expression of a decorator (the called expression of `@x(...)`, else the expression itself). */
+export declare function decoratorCallee(ts: TypeScriptApi, decorator: Decorator): Expression;
+/**
+ * The module `statement` (import, export-from or import-equals) statically binds: its specifier text, the
+ * module's symbol and its exported symbols by name (aliases resolved); `symbol` is null when the module does
+ * not resolve. Null when the statement names no static specifier.
+ */
+export declare function moduleExportsOf(ts: TypeScriptApi, checker: TypeChecker, statement: Node): ModuleExports | null;
+/**
+ * The program source files a framework-target scan of `checker` judges: every file in `localFiles`, plus (when
+ * `root` is given) declaration files inside the root but outside node_modules. Null when no program of the
+ * context owns the checker.
+ */
+export declare function programSourcesOf(context: ProgramContext, checker: TypeChecker, localFiles: ReadonlySet<string>, { root }?: {
+    root?: string | null;
+}): SourceFile[] | null;
+/**
+ * The CommonJS require() caveat every framework scan reports: each `require('<specifier>')` `accepted` pushes
+ * `${filePath} uses a CommonJS <label ?? specifier> <detail>` (the import-shape reasoning cannot prove that binding).
+ */
+export declare function commonJsRequireReasons(ts: TypeScriptApi, checker: TypeChecker, sourceFile: SourceFile, accepted: (specifier: string) => boolean, reasons: string[], filePath: string, detail: string, labelArgument?: string | null): void;

package/runtime/scripts/hfs/architecture/ast-walks.mjs

@@ -1,233 +1,250 @@
-// ast-walks.mjs - AST walks the architecture checkers share (moved out of typescript.mjs, which keeps the program loading and module resolution).
 import { canonical, isInside } from './config.mjs';
 import { hasAnyFlag, isConstVariable, sourceLocation } from '../../lib/ts-ast.mjs';
 import { UNPROVEN_FRAMEWORK, isUnshadowedCommonJsRequire, relativePath, unwrapExpression } from './typescript.mjs';
-
 /** `expression` unwrapped by the caller's own predicate set (a predicate absent on an older ts reads as never). */
-export function unwrapEach(ts, expression, predicates) {
-  let current = expression;
-  while (current && predicates.some((predicate) => predicate?.(current))) current = current.expression;
-  return current;
+export function unwrapEach(_ts, expression, predicates) {
+    let current = expression;
+    // The predicates the caller passes select wrapper nodes, which all carry an `expression` child.
+    while (current && predicates.some((predicate) => predicate?.(current)))
+        current = current.expression;
+    return current;
 }
-
 /** `value` with every TS alias hop resolved (a re-exported import reads as its target symbol). */
 export function normalizedSymbolValue(ts, checker, value = null) {
-  let symbol = value;
-  const seen = new Set();
-  while (symbol && hasAnyFlag(symbol.flags, ts.SymbolFlags.Alias) && !seen.has(symbol)) {
-    seen.add(symbol);
-    const target = checker.getAliasedSymbol(symbol);
-    if (!target || target === symbol) break;
-    symbol = target;
-  }
-  return symbol;
+    let symbol = value;
+    const seen = new Set();
+    while (symbol && hasAnyFlag(symbol.flags, ts.SymbolFlags.Alias) && !seen.has(symbol)) {
+        seen.add(symbol);
+        const target = checker.getAliasedSymbol(symbol);
+        if (!target || target === symbol)
+            break;
+        symbol = target;
+    }
+    return symbol;
 }
-
 /** The symbol `node` names, aliases resolved. */
 export function normalizedSymbol(ts, checker, node) {
-  return normalizedSymbolValue(ts, checker, checker?.getSymbolAtLocation(node) ?? null);
+    return normalizedSymbolValue(ts, checker, checker?.getSymbolAtLocation(node) ?? null);
 }
-
 /** The identifier or member-name node an expression selects through unwrapExpression, or null. */
 export function selectedNode(ts, expression) {
-  expression = unwrapExpression(ts, expression);
-  if (ts.isIdentifier(expression)) return expression;
-  if (ts.isPropertyAccessExpression(expression)) return expression.name;
-  if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression)) return expression.argumentExpression;
-  return null;
+    const unwrapped = unwrapExpression(ts, expression);
+    if (ts.isIdentifier(unwrapped))
+        return unwrapped;
+    if (ts.isPropertyAccessExpression(unwrapped))
+        return unwrapped.name;
+    if (ts.isElementAccessExpression(unwrapped) && ts.isStringLiteralLike(unwrapped.argumentExpression))
+        return unwrapped.argumentExpression;
+    return null;
 }
-
 /**
  * The symbol `node` ultimately evaluates to: its own symbol, followed through a single `const` variable
  * initializer (and so on). `unselected: 'null'` answers null when `node` selects no name at all.
  */
 export function valueSymbol(ts, checker, node, seen = new Set(), { unselected = 'node' } = {}) {
-  const selected = selectedNode(ts, node);
-  if (!selected && unselected === 'null') return null;
-  const symbol = normalizedSymbol(ts, checker, selected ?? node);
-  if (!symbol || seen.has(symbol)) return symbol;
-  seen.add(symbol);
-  const declarations = symbol.getDeclarations?.() ?? [];
-  if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
-    && isConstVariable(ts, declarations[0])) {
-    return valueSymbol(ts, checker, declarations[0].initializer, seen, { unselected });
-  }
-  return symbol;
-}
-
+    const selected = selectedNode(ts, node);
+    if (!selected && unselected === 'null')
+        return null;
+    const symbol = normalizedSymbol(ts, checker, selected ?? node);
+    if (!symbol || seen.has(symbol))
+        return symbol;
+    seen.add(symbol);
+    const declarations = symbol.getDeclarations?.() ?? [];
+    const [only] = declarations;
+    if (declarations.length === 1 && only && ts.isVariableDeclaration(only) && only.initializer
+        && isConstVariable(ts, only)) {
+        return valueSymbol(ts, checker, only.initializer, seen, { unselected });
+    }
+    return symbol;
+}
 /**
  * The expressions `declaration` returns: its body when it is an expression-bodied arrow/function, else every
  * `return`'s argument without descending into nested functions. `functionLike` overrides which node kinds bound
  * that descent (default the four callable declaration kinds; pass `ts.isFunctionLike` for the wider set).
  */
 export function returnedExpressions(ts, declaration, { functionLike = null } = {}) {
-  const boundary = functionLike ?? ((node) => ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)
-    || ts.isArrowFunction(node) || ts.isFunctionExpression(node));
-  if ((ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration)) && !ts.isBlock(declaration.body)) return [declaration.body];
-  const body = boundary(declaration) ? declaration.body : null;
-  if (!body || !ts.isBlock(body)) return [];
-  const returned = [];
-  const visit = (node) => {
-    if (node !== body && boundary(node)) return;
-    if (ts.isReturnStatement(node) && node.expression) returned.push(node.expression);
-    else ts.forEachChild(node, visit);
-  };
-  visit(body);
-  return returned;
-}
-
+    const boundary = functionLike ?? ((node) => ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)
+        || ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+    if ((ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration)) && !ts.isBlock(declaration.body))
+        return [declaration.body];
+    // A node the boundary predicate accepts is a function-like, which carries a `body`.
+    const body = boundary(declaration) ? declaration.body : null;
+    if (!body || !ts.isBlock(body))
+        return [];
+    const returned = [];
+    const visit = (node) => {
+        if (node !== body && boundary(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression)
+            returned.push(node.expression);
+        else
+            ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return returned;
+}
 /** A node's decorators across TS versions (ts.getDecorators, else the legacy `decorators` property). */
 export function nodeDecorators(ts, node) {
-  return ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
+    return ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : node.decorators ?? [];
 }
-
 /** One finding row: rule id, root-relative path, node position and message, plus rule extras. */
 export function violation(config, sourceFile, node, ruleId, message, extra = {}) {
-  return { ruleId, path: relativePath(config.root, sourceFile.fileName), ...sourceLocation(sourceFile, node), message, ...extra };
+    return { ruleId, path: relativePath(config.root, sourceFile.fileName), ...sourceLocation(sourceFile, node), message, ...extra };
 }
-
 /** Whether `match` holds for `node` or a descendant (the walk stops at the first match). */
 export function anyDescendant(ts, node, match) {
-  let found = false;
-  const visit = (current) => {
-    if (found) return;
-    if (match(current)) { found = true; return; }
-    ts.forEachChild(current, visit);
-  };
-  visit(node);
-  return found;
-}
-
+    let found = false;
+    const visit = (current) => {
+        if (found)
+            return;
+        if (match(current)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+}
 /**
  * The framework kinds `expression` can produce: `directOf(ts, checker, {symbol, selected, targets})` maps a
  * selected node's symbols to a kind (default `targets.get(symbol)`); `shorthandOf` (when set) also resolves
  * shorthand-property declarations and descends property assignments; `newExpression` descends `new X()` callees.
  */
-const addKinds = (target, source) => { for (const kind of source) target.add(kind); };
-
+const addKinds = (target, source) => { for (const kind of source)
+    target.add(kind); };
 const kindsFromReturns = (ts, checker, declaration, targets, options) => {
-  const kinds = new Set();
-  for (const returned of returnedExpressions(ts, declaration)) addKinds(kinds, tracedFrameworkKinds(ts, checker, returned, targets, options));
-  return kinds;
+    const kinds = new Set();
+    for (const returned of returnedExpressions(ts, declaration))
+        addKinds(kinds, tracedFrameworkKinds(ts, checker, returned, targets, options));
+    return kinds;
 };
-
 const kindsFromDeclaration = (ts, checker, declaration, targets, options, shorthandOf) => {
-  const kinds = new Set();
-  if (ts.isVariableDeclaration(declaration) && declaration.initializer)
-    addKinds(kinds, tracedFrameworkKinds(ts, checker, declaration.initializer, targets, options));
-  if (shorthandOf && ts.isShorthandPropertyAssignment(declaration)) {
-    const target = normalizedSymbolValue(ts, checker, checker.getShorthandAssignmentValueSymbol?.(declaration));
-    const kind = shorthandOf(ts, checker, target, targets);
-    if (kind) kinds.add(kind);
-  }
-  if (shorthandOf && ts.isPropertyAssignment(declaration))
-    addKinds(kinds, tracedFrameworkKinds(ts, checker, declaration.initializer, targets, options));
-  addKinds(kinds, kindsFromReturns(ts, checker, declaration, targets, options));
-  return kinds;
+    const kinds = new Set();
+    if (ts.isVariableDeclaration(declaration) && declaration.initializer)
+        addKinds(kinds, tracedFrameworkKinds(ts, checker, declaration.initializer, targets, options));
+    if (shorthandOf && ts.isShorthandPropertyAssignment(declaration)) {
+        const target = normalizedSymbolValue(ts, checker, checker.getShorthandAssignmentValueSymbol?.(declaration));
+        const kind = shorthandOf(ts, checker, target, targets);
+        if (kind)
+            kinds.add(kind);
+    }
+    if (shorthandOf && ts.isPropertyAssignment(declaration))
+        addKinds(kinds, tracedFrameworkKinds(ts, checker, declaration.initializer, targets, options));
+    addKinds(kinds, kindsFromReturns(ts, checker, declaration, targets, options));
+    return kinds;
 };
-
 const kindsFromSymbol = (ts, checker, symbol, targets, seen, options) => {
-  const nextSeen = new Set(seen).add(symbol);
-  const declarationOptions = { ...options, seen: nextSeen };
-  const kinds = new Set();
-  for (const declaration of symbol.getDeclarations?.() ?? [])
-    addKinds(kinds, kindsFromDeclaration(ts, checker, declaration, targets, declarationOptions, options.shorthandOf));
-  return kinds;
+    const nextSeen = new Set(seen).add(symbol);
+    const declarationOptions = { ...options, seen: nextSeen };
+    const kinds = new Set();
+    for (const declaration of symbol.getDeclarations?.() ?? [])
+        addKinds(kinds, kindsFromDeclaration(ts, checker, declaration, targets, declarationOptions, options.shorthandOf));
+    return kinds;
 };
-
-const defaultDirectOf = (ts, checker, { symbol, targets }) => targets.get(symbol) ?? null;
-
-export function tracedFrameworkKinds(ts, checker, expression, targets,
-  { seen = new Set(), depth = 0, directOf = null, shorthandOf = null, newExpression = false } = {}) {
-  if (!expression) return new Set();
-  if (depth > 10) return new Set([UNPROVEN_FRAMEWORK]);
-  const unwrapped = unwrapExpression(ts, expression);
-  const selected = selectedNode(ts, unwrapped);
-  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const direct = symbol ? (directOf ?? defaultDirectOf)(ts, checker, { symbol, selected, targets }) : null;
-  if (direct) return new Set([direct]);
-  const options = { depth: depth + 1, directOf, shorthandOf, newExpression };
-  if (ts.isArrowFunction(unwrapped) || ts.isFunctionExpression(unwrapped)) return kindsFromReturns(ts, checker, unwrapped, targets, { ...options, seen });
-  if (ts.isCallExpression(unwrapped)) {
-    const kinds = tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
-    if (kinds.size) return kinds;
-  }
-  if (newExpression && ts.isNewExpression(unwrapped))
-    return tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
-  if (!symbol || seen.has(symbol)) return new Set();
-  return kindsFromSymbol(ts, checker, symbol, targets, seen, options);
-}
-
+const defaultDirectOf = (_ts, _checker, { symbol, targets }) => targets.get(symbol) ?? null;
+export function tracedFrameworkKinds(ts, checker, expression, targets, { seen = new Set(), depth = 0, directOf = null, shorthandOf = null, newExpression = false } = {}) {
+    if (!expression)
+        return new Set();
+    if (depth > 10)
+        return new Set([UNPROVEN_FRAMEWORK]);
+    const unwrapped = unwrapExpression(ts, expression);
+    const selected = selectedNode(ts, unwrapped);
+    const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
+    const direct = symbol && selected ? (directOf ?? defaultDirectOf)(ts, checker, { symbol, selected, targets }) : null;
+    if (direct)
+        return new Set([direct]);
+    const options = { depth: depth + 1, directOf, shorthandOf, newExpression };
+    if (ts.isArrowFunction(unwrapped) || ts.isFunctionExpression(unwrapped))
+        return kindsFromReturns(ts, checker, unwrapped, targets, { ...options, seen });
+    if (ts.isCallExpression(unwrapped)) {
+        const kinds = tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
+        if (kinds.size)
+            return kinds;
+    }
+    if (newExpression && ts.isNewExpression(unwrapped))
+        return tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
+    if (!symbol || seen.has(symbol))
+        return new Set();
+    return kindsFromSymbol(ts, checker, symbol, targets, seen, options);
+}
 /** 'unproven framework' | 'multiple framework' | the one kind | null, for a decorator whose expression constructs. */
 export function constructedDecoratorKind(ts, checker, decorator, targets, traceOpts = {}) {
-  const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
-  const kinds = tracedFrameworkKinds(ts, checker, callee, targets, traceOpts);
-  if (kinds.has(UNPROVEN_FRAMEWORK)) return 'unproven framework';
-  if (kinds.size === 1) return [...kinds][0];
-  return kinds.size ? 'multiple framework' : null;
+    const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+    const kinds = tracedFrameworkKinds(ts, checker, callee, targets, traceOpts);
+    if (kinds.has(UNPROVEN_FRAMEWORK))
+        return 'unproven framework';
+    if (kinds.size === 1)
+        return [...kinds][0] ?? null;
+    return kinds.size ? 'multiple framework' : null;
 }
-
 /** The target a decorator resolves to through a `let`/`var` alias's single initializer, or null. */
 export function mutableDecoratorKind(ts, checker, decorator, targets) {
-  const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
-  const selected = selectedNode(ts, callee);
-  const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const declarations = symbol?.getDeclarations?.() ?? [];
-  if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
-    || isConstVariable(ts, declarations[0])) return null;
-  return targets.get(valueSymbol(ts, checker, declarations[0].initializer)) ?? null;
-}
-
+    const callee = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+    const selected = selectedNode(ts, callee);
+    const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
+    const declarations = symbol?.getDeclarations?.() ?? [];
+    const [only] = declarations;
+    if (declarations.length !== 1 || !only || !ts.isVariableDeclaration(only) || !only.initializer
+        || isConstVariable(ts, only))
+        return null;
+    const resolved = valueSymbol(ts, checker, only.initializer);
+    return (resolved ? targets.get(resolved) : undefined) ?? null;
+}
 /** The callee expression of a decorator (the called expression of `@x(...)`, else the expression itself). */
 export function decoratorCallee(ts, decorator) {
-  return ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+    return ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
 }
-
 /**
  * The module `statement` (import, export-from or import-equals) statically binds: its specifier text, the
  * module's symbol and its exported symbols by name (aliases resolved); `symbol` is null when the module does
  * not resolve. Null when the statement names no static specifier.
  */
 export function moduleExportsOf(ts, checker, statement) {
-  let moduleSpecifier = null;
-  if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
-    && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier)) moduleSpecifier = statement.moduleSpecifier;
-  let importEquals = null;
-  if (ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)
-    && statement.moduleReference.expression && ts.isStringLiteralLike(statement.moduleReference.expression)) importEquals = statement.moduleReference.expression;
-  const specifierNode = moduleSpecifier ?? importEquals;
-  const specifier = specifierNode?.text;
-  if (specifier == null) return null;
-  const symbol = checker.getSymbolAtLocation(specifierNode) ?? null;
-  const exports = new Map((symbol ? checker.getExportsOfModule(symbol) : []).map(item => [item.getName(), normalizedSymbolValue(ts, checker, item)]));
-  return { specifierNode, specifier, symbol, exports };
-}
-
+    let moduleSpecifier = null;
+    if ((ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
+        && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier))
+        moduleSpecifier = statement.moduleSpecifier;
+    let importEquals = null;
+    if (ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)
+        && statement.moduleReference.expression && ts.isStringLiteralLike(statement.moduleReference.expression))
+        importEquals = statement.moduleReference.expression;
+    const specifierNode = moduleSpecifier ?? importEquals;
+    if (!specifierNode)
+        return null;
+    const specifier = specifierNode.text;
+    const symbol = checker.getSymbolAtLocation(specifierNode) ?? null;
+    const exports = new Map((symbol ? checker.getExportsOfModule(symbol) : [])
+        .map((item) => [item.getName(), normalizedSymbolValue(ts, checker, item) ?? null]));
+    return { specifierNode, specifier, symbol, exports };
+}
 /**
  * The program source files a framework-target scan of `checker` judges: every file in `localFiles`, plus (when
  * `root` is given) declaration files inside the root but outside node_modules. Null when no program of the
  * context owns the checker.
  */
 export function programSourcesOf(context, checker, localFiles, { root = null } = {}) {
-  const program = context.programs.find(candidate => candidate.getTypeChecker() === checker) ?? null;
-  if (!program) return null;
-  return program.getSourceFiles().filter(sourceFile => localFiles.has(canonical(sourceFile.fileName))
-    || (root && sourceFile.isDeclarationFile && isInside(root, sourceFile.fileName)
-      && !sourceFile.fileName.replaceAll('\\', '/').includes('/node_modules/')));
+    const program = context.programs.find(candidate => candidate.getTypeChecker() === checker) ?? null;
+    if (!program)
+        return null;
+    return program.getSourceFiles().filter(sourceFile => localFiles.has(canonical(sourceFile.fileName))
+        || (root && sourceFile.isDeclarationFile && isInside(root, sourceFile.fileName)
+            && !sourceFile.fileName.replaceAll('\\', '/').includes('/node_modules/')));
 }
-
 /**
  * The CommonJS require() caveat every framework scan reports: each `require('<specifier>')` `accepted` pushes
  * `${filePath} uses a CommonJS <label ?? specifier> <detail>` (the import-shape reasoning cannot prove that binding).
  */
-export function commonJsRequireReasons(ts, checker, sourceFile, accepted, reasons, filePath, detail) {
-  const label = arguments[7] ?? null;
-  const visit = node => {
-    if (ts.isCallExpression(node) && isUnshadowedCommonJsRequire(ts, checker, node.expression)
-      && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0]) && accepted(node.arguments[0].text)) {
-      reasons.push(`${filePath} uses a CommonJS ${label ?? node.arguments[0].text} ${detail}`);
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
+export function commonJsRequireReasons(ts, checker, sourceFile, accepted, reasons, filePath, detail, labelArgument) {
+    const label = labelArgument ?? null;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isUnshadowedCommonJsRequire(ts, checker, node.expression) && node.arguments.length === 1) {
+            const [argument] = node.arguments;
+            if (argument && ts.isStringLiteralLike(argument) && accepted(argument.text)) {
+                reasons.push(`${filePath} uses a CommonJS ${label ?? argument.text} ${detail}`);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
 }

package/runtime/scripts/hfs/architecture/automatic-gates.d.mts

@@ -0,0 +1,21 @@
+/** The tracked-file view the callers hand in. */
+interface GateTree {
+    files(): string[];
+    hasFile(file: string): boolean;
+}
+/** Records one finding of `rule` at `file`. */
+type GateFinding = (rule: string, file: string, message: string) => void;
+/** Check hooks, transitive hook scripts, unit scripts, coverage and automatic workflows. */
+export declare function e2eInAutomaticGate({ root, tree, jestConfig, finding }: {
+    root: string;
+    tree: GateTree;
+    jestConfig: string | null;
+    finding: GateFinding;
+}): void;
+/** The be side's default tsconfig excludes the world, integration, e2e and contract trees (they are checked by src/tests/tsconfig.json). */
+export declare function testTreesOutOfDefaultProgram({ root, tree, finding }: {
+    root: string;
+    tree: GateTree;
+    finding: GateFinding;
+}): void;
+export {};