@starci/hfs 4.0.10 → 4.1.0

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

@@ -1,19 +1,20 @@
 // 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 { sourceLocation } from '../../lib/ts-ast.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) {
-  while (expression && predicates.some((predicate) => predicate?.(expression))) expression = expression.expression;
-  return expression;
+  let current = expression;
+  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) {
-  let symbol = value ?? null;
+export function normalizedSymbolValue(ts, checker, value = null) {
+  let symbol = value;
   const seen = new Set();
-  while (symbol && (symbol.flags & ts.SymbolFlags.Alias) && !seen.has(symbol)) {
+  while (symbol && hasAnyFlag(symbol.flags, ts.SymbolFlags.Alias) && !seen.has(symbol)) {
     seen.add(symbol);
     const target = checker.getAliasedSymbol(symbol);
     if (!target || target === symbol) break;
@@ -48,7 +49,7 @@ export function valueSymbol(ts, checker, node, seen = new Set(), { unselected =
   seen.add(symbol);
   const declarations = symbol.getDeclarations?.() ?? [];
   if (declarations.length === 1 && ts.isVariableDeclaration(declarations[0]) && declarations[0].initializer
-    && (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) {
+    && isConstVariable(ts, declarations[0])) {
     return valueSymbol(ts, checker, declarations[0].initializer, seen, { unselected });
   }
   return symbol;
@@ -102,50 +103,59 @@ export function anyDescendant(ts, node, match) {
  * 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 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 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 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 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]);
-  expression = unwrapExpression(ts, expression);
-  const selected = selectedNode(ts, expression);
+  const unwrapped = unwrapExpression(ts, expression);
+  const selected = selectedNode(ts, unwrapped);
   const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
-  const direct = symbol ? (directOf ?? ((ts2, c, { symbol: s, targets: t }) => t.get(s) ?? null))(ts, checker, { symbol, selected, targets }) : null;
+  const direct = symbol ? (directOf ?? defaultDirectOf)(ts, checker, { symbol, selected, targets }) : null;
   if (direct) return new Set([direct]);
-  const opts = { depth: depth + 1, directOf, shorthandOf, newExpression };
-  if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
-    const kinds = new Set();
-    for (const returned of returnedExpressions(ts, expression)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, { ...opts, seen })) kinds.add(kind);
-    }
-    return kinds;
-  }
-  if (ts.isCallExpression(expression)) {
-    const kinds = tracedFrameworkKinds(ts, checker, expression.expression, targets, { ...opts, seen });
+  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(expression)) {
-    return tracedFrameworkKinds(ts, checker, expression.expression, targets, { ...opts, seen });
-  }
+  if (newExpression && ts.isNewExpression(unwrapped))
+    return tracedFrameworkKinds(ts, checker, unwrapped.expression, targets, { ...options, seen });
   if (!symbol || seen.has(symbol)) return new Set();
-  const nextSeen = new Set(seen).add(symbol);
-  const kinds = new Set();
-  for (const declaration of symbol.getDeclarations?.() ?? []) {
-    if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
-    }
-    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)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, declaration.initializer, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
-    }
-    for (const returned of returnedExpressions(ts, declaration)) {
-      for (const kind of tracedFrameworkKinds(ts, checker, returned, targets, { ...opts, seen: nextSeen })) kinds.add(kind);
-    }
-  }
-  return kinds;
+  return kindsFromSymbol(ts, checker, symbol, targets, seen, options);
 }
 
 /** 'unproven framework' | 'multiple framework' | the one kind | null, for a decorator whose expression constructs. */
@@ -153,7 +163,8 @@ export function constructedDecoratorKind(ts, checker, decorator, targets, traceO
   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';
-  return kinds.size === 1 ? [...kinds][0] : kinds.size ? 'multiple framework' : null;
+  if (kinds.size === 1) return [...kinds][0];
+  return kinds.size ? 'multiple framework' : null;
 }
 
 /** The target a decorator resolves to through a `let`/`var` alias's single initializer, or null. */
@@ -163,7 +174,7 @@ export function mutableDecoratorKind(ts, checker, decorator, targets) {
   const symbol = selected ? normalizedSymbol(ts, checker, selected) : null;
   const declarations = symbol?.getDeclarations?.() ?? [];
   if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
-    || (ts.getCombinedNodeFlags(declarations[0].parent) & ts.NodeFlags.Const)) return null;
+    || isConstVariable(ts, declarations[0])) return null;
   return targets.get(valueSymbol(ts, checker, declarations[0].initializer)) ?? null;
 }
 
@@ -178,11 +189,12 @@ export function decoratorCallee(ts, decorator) {
  * not resolve. Null when the statement names no static specifier.
  */
 export function moduleExportsOf(ts, checker, statement) {
-  const moduleSpecifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
-    && statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier : null;
-  const importEquals = ts.isImportEqualsDeclaration(statement) && ts.isExternalModuleReference(statement.moduleReference)
-    && statement.moduleReference.expression && ts.isStringLiteralLike(statement.moduleReference.expression)
-    ? statement.moduleReference.expression : null;
+  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;
@@ -208,7 +220,8 @@ export function programSourcesOf(context, checker, localFiles, { root = 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 function commonJsRequireReasons(ts, checker, sourceFile, accepted, reasons, filePath, detail, label = null) {
+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)) {

package/runtime/scripts/hfs/architecture/automatic-gates.mjs

@@ -0,0 +1,96 @@
+import { readTextFile } from '../../lib/read-text.mjs';
+
+// Owner ruling 2026-09-29 (layout 2026-09-30): integration, e2e and contract run MANUALLY only. No hook, default typecheck,
+// coverage run or automatic CI trigger may include those trees or run those projects. Linting the e2e files is not running them: ESLint reads them
+// as syntax in the one repository-wide lint run (the factory's e2e block), so no `lint:e2e` command exists to judge.
+const E2E_COMMAND = new RegExp([
+  String.raw`\btest:(?:e2e|integration|contract)\b|`,
+  String.raw`\btypecheck:tests\b|`,
+  String.raw`--selectProjects\s+(?:e2e|integration|contract)\b|`,
+  String.raw`src\/tests\/(?:world|integration|e2e|contract)\b|`,
+  String.raw`jest[^\n|&;]*(?:e2e|integration|contract)`,
+].join(''), 'u');
+const UNIT_RUN_SCRIPTS = ['test', 'test:unit', 'test:ci', 'test:affected', 'test:coverage', 'test:cov'];
+
+const runsE2e = text => E2E_COMMAND.test(String(text).replace(/--ignore-pattern[= ]+(?:"[^"]*"|'[^']*'|\S+)/gu, ''));
+const withoutComments = text => text.split('\n').filter(line => !/^\s*#/u.test(line)).join('\n');
+
+function inspectHooks(state) {
+  for (const hook of ['.husky/pre-commit', '.husky/pre-push']) {
+    const text = readTextFile(state.root, hook);
+    if (text === null) continue;
+    const body = withoutComments(text);
+    if (runsE2e(body)) state.finding(state.rule, hook, `${hook} runs integration, e2e or contract. They are manual only; hooks run unit, lint and typecheck.`);
+    for (const match of body.matchAll(/npm\s+run\s+([\w:.-]+)/gu)) state.pending.push(match[1]);
+  }
+}
+
+function inspectLintStaged(state) {
+  const lintStaged = state.pkg?.['lint-staged'];
+  if (lintStaged && runsE2e(Object.values(lintStaged).flat().join('\n')))
+    state.finding(state.rule, 'package.json', 'lint-staged runs an integration, e2e or contract command. They are manual only.');
+}
+
+function inspectHookScripts(state) {
+  for (const name of state.pending) {
+    if (state.called.has(name)) continue;
+    state.called.add(name);
+    const command = state.scripts[name];
+    if (typeof command !== 'string') continue;
+    if (runsE2e(command)) state.finding(state.rule, 'package.json', `Script ${name} is run by a husky hook and touches integration, e2e or contract. They are manual only.`);
+    for (const match of command.matchAll(/npm\s+run\s+([\w:.-]+)/gu)) state.pending.push(match[1]);
+  }
+}
+
+function inspectUnitGates(state) {
+  if (!state.tree.hasFile(state.jestConfig)) return;
+  for (const name of UNIT_RUN_SCRIPTS) {
+    const command = state.scripts[name];
+    if (typeof command === 'string' && /\bjest\b/u.test(command) && !/--selectProjects\s+unit\b/u.test(command))
+      state.finding(state.rule, 'package.json', `Script ${name} runs jest without --selectProjects unit and would run the integration, e2e or contract project.`);
+  }
+  const jestText = readTextFile(state.root, state.jestConfig) ?? '';
+  if (/collectCoverageFrom/u.test(jestText) && !/!src\/tests\/(?:\*\*|e2e)/u.test(jestText))
+    state.finding(state.rule, state.jestConfig, 'collectCoverageFrom must exclude src/tests/** so no integration, e2e or contract file counts toward coverage.');
+}
+
+function inspectWorkflows(state) {
+  for (const file of state.tree.files().filter(entry => /^\.github\/workflows\/[^/]+\.ya?ml$/u.test(entry))) {
+    const text = readTextFile(state.root, file);
+    if (text === null) continue;
+    const trigger = /^on:.*(?:\n(?:[ \t].*)?$)*/mu.exec(text)?.[0] ?? '';
+    if (!/\b(?:push|pull_request)\b/u.test(trigger)) continue;
+    if (runsE2e(withoutComments(text)))
+      state.finding(state.rule, file, `${file} runs e2e on push or pull_request. Move the e2e job to its own workflow with on: workflow_dispatch only.`);
+  }
+}
+
+/** Check hooks, transitive hook scripts, unit scripts, coverage and automatic workflows. */
+export function e2eInAutomaticGate({ root, tree, jestConfig, finding }) {
+  const rule = 'HFS_E2E_IN_AUTOMATIC_GATE';
+  let pkg = null;
+  try { pkg = JSON.parse(readTextFile(root, 'package.json') ?? ''); } catch { /* the package checks own invalid JSON */ }
+  const state = { root, tree, jestConfig, finding, rule, pkg, scripts: pkg?.scripts ?? {}, pending: [], called: new Set() };
+  inspectHooks(state);
+  inspectLintStaged(state);
+  inspectHookScripts(state);
+  inspectUnitGates(state);
+  inspectWorkflows(state);
+}
+
+/** The be side's default tsconfig excludes the world, integration, e2e and contract trees (they are checked by src/tests/tsconfig.json). */
+export function testTreesOutOfDefaultProgram({ root, tree, finding }) {
+  const rule = 'HFS_E2E_IN_AUTOMATIC_GATE';
+  const tsconfigText = readTextFile(root, 'tsconfig.json');
+  let tsconfig = null;
+  try { tsconfig = tsconfigText === null ? null : JSON.parse(tsconfigText); } catch { /* the typecheck itself owns parsing */ }
+  if (tsconfig) {
+    const excludedText = JSON.stringify(tsconfig.exclude ?? []);
+    const excludesTestTrees = ['world', 'integration', 'e2e', 'contract'].every(tree => excludedText.includes(`src/tests/${tree}`));
+    const defaultAll = tsconfig.include === undefined && tsconfig.files === undefined;
+    const files = tree.files();
+    if (files.some(file => /^src\/tests\/(?:world|integration|e2e|contract)\/.+\.[cm]?tsx?$/u.test(file)) && !excludesTestTrees &&
+        (defaultAll || JSON.stringify(tsconfig.include ?? []).includes('src')))
+      finding(rule, 'tsconfig.json', 'The default tsconfig includes src/tests/{world,integration,e2e,contract}/**. Exclude those trees and check them with src/tests/tsconfig.json (typecheck:tests).');
+  }
+}