@starci/hfs 4.11.21 → 4.12.0

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

@@ -1,96 +1,103 @@
 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)`,
+    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: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');
-
+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]);
-  }
+    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.');
+    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]);
-  }
+    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.');
+    if (state.jestConfig === null || !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.`);
-  }
+    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);
+    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).');
-  }
+    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).');
+    }
 }

package/runtime/scripts/hfs/architecture/backend-app-files.d.mts

@@ -0,0 +1,10 @@
+import type { SourceFile, TypeChecker } from 'typescript';
+import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+import type { ArchitectureViolation } from './hfs-graph.mjs';
+/** The part of the TypeScript context this check reads. */
+export interface ApplicationEnvironmentContext {
+    ts: TypeScriptApi;
+    checkerFor: (fileName: string) => TypeChecker;
+}
+/** Composition groups and options consume parsed options; only the app's matching env role and main read them. */
+export declare function checkApplicationEnvironment(config: ArchitectureConfig, context: ApplicationEnvironmentContext, sourceFile: SourceFile, fileName: string, violations: ArchitectureViolation[]): void;

package/runtime/scripts/hfs/architecture/backend-app-files.mjs

@@ -2,102 +2,113 @@ import path from 'node:path';
 import { allowsFile } from '../allows.mjs';
 import { relativePath, unwrapExpression } from './typescript.mjs';
 import { accessName, sourceLocation } from '../../lib/ts-ast.mjs';
-
 const PROCESS_MODULES = new Set(['process', 'node:process']);
 const PROCESS_GLOBAL = new Set(['process']);
 const GLOBAL_HOLDERS = new Set(['globalThis', 'global']);
 const REFLECT_GLOBAL = new Set(['Reflect']);
-
 function bindingName(ts, element) {
-  const name = element.propertyName ?? element.name;
-  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
-  return ts.isComputedPropertyName(name) && ts.isStringLiteralLike(name.expression) ? name.expression.text : null;
+    const name = element.propertyName ?? element.name;
+    if (ts.isIdentifier(name) || ts.isStringLiteralLike(name))
+        return name.text;
+    return ts.isComputedPropertyName(name) && ts.isStringLiteralLike(name.expression) ? name.expression.text : null;
 }
-
 /** A global name is not a same-named local variable or parameter. */
 function isGlobalName(ts, checker, node, names) {
-  if (!ts.isIdentifier(node) || !names.has(node.text)) return false;
-  const declarations = checker?.getSymbolAtLocation(node)?.getDeclarations() ?? [];
-  return declarations.every(declaration => declaration.getSourceFile().isDeclarationFile);
+    if (!ts.isIdentifier(node) || !names.has(node.text))
+        return false;
+    const declarations = checker?.getSymbolAtLocation(node)?.getDeclarations() ?? [];
+    return declarations.every(declaration => declaration.getSourceFile().isDeclarationFile);
 }
-
 function recordProcessBindings(ts, clause, add, report) {
-  if (clause?.name) add(clause.name);
-  const bindings = clause?.namedBindings;
-  if (bindings && ts.isNamespaceImport(bindings)) add(bindings.name);
-  if (!bindings || !ts.isNamedImports(bindings)) return;
-  for (const element of bindings.elements) {
-    const name = (element.propertyName ?? element.name).text;
-    if (name === 'env') report(element);
-    else if (name === 'default') add(element.name);
-  }
+    if (clause?.name)
+        add(clause.name);
+    const bindings = clause?.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings))
+        add(bindings.name);
+    if (!bindings || !ts.isNamedImports(bindings))
+        return;
+    for (const element of bindings.elements) {
+        const name = (element.propertyName ?? element.name).text;
+        if (name === 'env')
+            report(element);
+        else if (name === 'default')
+            add(element.name);
+    }
 }
-
 function processImportSymbols(ts, checker, sourceFile, report) {
-  const imports = new Set();
-  const add = name => {
-    const symbol = checker.getSymbolAtLocation(name);
-    if (symbol) imports.add(symbol);
-  };
-  for (const statement of sourceFile.statements) {
-    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)
-      || !PROCESS_MODULES.has(statement.moduleSpecifier.text)) continue;
-    recordProcessBindings(ts, statement.importClause, add, report);
-  }
-  return imports;
+    const imports = new Set();
+    const add = (name) => {
+        const symbol = checker.getSymbolAtLocation(name);
+        if (symbol)
+            imports.add(symbol);
+    };
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteralLike(statement.moduleSpecifier)
+            || !PROCESS_MODULES.has(statement.moduleSpecifier.text))
+            continue;
+        recordProcessBindings(ts, statement.importClause, add, report);
+    }
+    return imports;
 }
-
 /** Process bindings are resolved by symbol, so a nested parameter cannot masquerade as an imported process. */
 function processAccess(ts, checker, sourceFile, report) {
-  const imports = processImportSymbols(ts, checker, sourceFile, report);
-  const isProcess = expression => {
-    const node = unwrapExpression(ts, expression);
-    if (!node) return false;
-    if (ts.isIdentifier(node)) return imports.has(checker.getSymbolAtLocation(node))
-      || isGlobalName(ts, checker, node, PROCESS_GLOBAL);
-    return accessName(ts, node) === 'process'
-      && isGlobalName(ts, checker, node.expression, GLOBAL_HOLDERS);
-  };
-  return node => {
-    if (accessName(ts, node) === 'env' && isProcess(node.expression)) report(node);
-    if (ts.isVariableDeclaration(node) && node.initializer && isProcess(node.initializer) && ts.isObjectBindingPattern(node.name)
-      && node.name.elements.some(element => bindingName(ts, element) === 'env')) report(node);
-    if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'get'
-      && isGlobalName(ts, checker, node.expression.expression, REFLECT_GLOBAL)
-      && isProcess(node.arguments[0]) && node.arguments[1] && ts.isStringLiteralLike(node.arguments[1]) && node.arguments[1].text === 'env') report(node);
-  };
+    const imports = processImportSymbols(ts, checker, sourceFile, report);
+    const isProcess = (expression) => {
+        const node = unwrapExpression(ts, expression);
+        if (!node)
+            return false;
+        if (ts.isIdentifier(node)) {
+            const symbol = checker.getSymbolAtLocation(node);
+            return (symbol !== undefined && imports.has(symbol)) || isGlobalName(ts, checker, node, PROCESS_GLOBAL);
+        }
+        return accessName(ts, node) === 'process'
+            && isGlobalName(ts, checker, node.expression, GLOBAL_HOLDERS); // reason: accessName names only property and element accesses
+    };
+    return (node) => {
+        if (accessName(ts, node) === 'env' && isProcess(node.expression))
+            report(node); // reason: accessName names only property and element accesses
+        if (ts.isVariableDeclaration(node) && node.initializer && isProcess(node.initializer) && ts.isObjectBindingPattern(node.name)
+            && node.name.elements.some(element => bindingName(ts, element) === 'env'))
+            report(node);
+        if (ts.isCallExpression(node) && accessName(ts, node.expression) === 'get'
+            && isGlobalName(ts, checker, node.expression.expression, REFLECT_GLOBAL)
+            && isProcess(node.arguments[0]) && node.arguments[1] && ts.isStringLiteralLike(node.arguments[1]) && node.arguments[1].text === 'env')
+            report(node);
+    };
 }
-
 /** The declaration, rather than the caller's name, identifies EnvSource readers and configuration helpers. */
 function appEnvironmentCall(config, ts, checker, call) {
-  const declaration = checker.getResolvedSignature(call)?.declaration;
-  if (!declaration) return false;
-  const relative = relativePath(config.root, declaration.getSourceFile().fileName);
-  if (ts.isMethodDeclaration(declaration) && ts.isClassDeclaration(declaration.parent) && declaration.parent.name?.text === 'EnvSource') {
-    return config.hfs.tierOf(relative) === 'platform' && path.posix.basename(config.hfs.ownerOf(relative)?.root ?? '') === 'config';
-  }
-  if (!ts.isFunctionDeclaration(declaration) && !ts.isArrowFunction(declaration) && !ts.isFunctionExpression(declaration)) return false;
-  return allowsFile(config.hfs, relative)?.entry === '<app>.env.ts'
-    || (path.posix.basename(relative).endsWith('.config.ts') && config.hfs.slotOf(relative) !== null);
+    const declaration = checker.getResolvedSignature(call)?.declaration;
+    if (!declaration)
+        return false;
+    const relative = relativePath(config.root, declaration.getSourceFile().fileName);
+    if (ts.isMethodDeclaration(declaration) && ts.isClassDeclaration(declaration.parent) && declaration.parent.name?.text === 'EnvSource') {
+        return config.hfs.tierOf(relative) === 'platform' && path.posix.basename(config.hfs.ownerOf(relative)?.root ?? '') === 'config';
+    }
+    if (!ts.isFunctionDeclaration(declaration) && !ts.isArrowFunction(declaration) && !ts.isFunctionExpression(declaration))
+        return false;
+    return allowsFile(config.hfs, relative)?.entry === '<app>.env.ts'
+        || (path.posix.basename(relative).endsWith('.config.ts') && config.hfs.slotOf(relative) !== null);
 }
-
 /** Composition groups and options consume parsed options; only the app's matching env role and main read them. */
 export function checkApplicationEnvironment(config, context, sourceFile, fileName, violations) {
-  const role = allowsFile(config.hfs, relativePath(config.root, fileName));
-  if (role?.allowed && (role.entry === 'main.ts' || role.entry === '<app>.env.ts')) return;
-  const { ts } = context;
-  const checker = context.checkerFor(fileName);
-  const report = node => violations.push({
-    ruleId: 'BE_APP_COMPOSITION_ONLY',
-    path: relativePath(config.root, fileName),
-    ...sourceLocation(sourceFile, node),
-    message: "Application environment reads live in main.ts or the matching <app>.env.ts. Options files and compose/<area>.ts receive the typed result of read<App>Env(env: EnvSource).",
-  });
-  const checkProcess = processAccess(ts, checker, sourceFile, report);
-  const visit = node => {
-    checkProcess(node);
-    if (ts.isCallExpression(node) && appEnvironmentCall(config, ts, checker, node)) report(node);
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
+    const role = allowsFile(config.hfs, relativePath(config.root, fileName));
+    if (role?.allowed && (role.entry === 'main.ts' || role.entry === '<app>.env.ts'))
+        return;
+    const { ts } = context;
+    const checker = context.checkerFor(fileName);
+    const report = node => violations.push({
+        ruleId: 'BE_APP_COMPOSITION_ONLY',
+        path: relativePath(config.root, fileName),
+        ...sourceLocation(sourceFile, node),
+        message: "Application environment reads live in main.ts or the matching <app>.env.ts. Options files and compose/<area>.ts receive the typed result of read<App>Env(env: EnvSource).",
+    });
+    const checkProcess = processAccess(ts, checker, sourceFile, report);
+    const visit = (node) => {
+        checkProcess(node);
+        if (ts.isCallExpression(node) && appEnvironmentCall(config, ts, checker, node))
+            report(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
 }

package/runtime/scripts/hfs/architecture/backend.d.mts

@@ -0,0 +1,5 @@
+import type { ArchitectureConfig } from './config.mjs';
+import type { ArchitectureViolation } from './hfs-graph.mjs';
+import type { TypeContext } from './type-context.mjs';
+/** Enforce backend direction and keep executable apps as measurable composition roots. */
+export declare function checkBackend(config: ArchitectureConfig, context: TypeContext): ArchitectureViolation[];