@starci/hfs 4.0.8 → 4.0.9

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

@@ -3,7 +3,9 @@ import path from 'node:path';
 import { canonical, isInside } from './config.mjs';
 import { readJsonFile as readJson } from '../../lib/json.mjs';
 import { frameworkPinnedRootFiles } from './framework-pinned.mjs';
-import { isUnshadowedCommonJsRequire, reachableViolation, relativePath, sourceLocation, unwrapExpression } from './typescript.mjs';
+import { exportTargetStrings, isUnshadowedCommonJsRequire, reachableViolation, relativePath, unwrapExpression } from './typescript.mjs';
+import { normalizedSymbolValue, returnedExpressions as sharedReturnedExpressions } from './ast-walks.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 const FEATURE_TIERS = new Set(['pages', 'layouts', 'overlays']);
 const COMPONENT_TIERS = new Set(['blocks', 'composites', 'branches', 'leaves']);
@@ -52,23 +54,16 @@ function violation(config, sourceFile, node, ruleId, message, extra = {}) {
   };
 }
 
-function exportTargets(value) {
-  if (typeof value === 'string') return [value];
-  if (Array.isArray(value)) return value.flatMap(exportTargets);
-  if (value && typeof value === 'object' && !Array.isArray(value)) return Object.values(value).flatMap(exportTargets);
-  return [];
-}
-
 function grammarExport(manifest, packageName, specifier) {
   const key = specifier === packageName ? '.' : `.${specifier.slice(packageName.length)}`;
   const value = manifest?.exports?.[key];
-  const targets = exportTargets(value);
+  const targets = exportTargetStrings(value);
   return targets.length > 0 && targets.every(target => target.startsWith('./') && !target.includes('\\') && !target.split('/').includes('..'));
 }
 
 function grammarExportTargets(manifest, packageRoot, packageName, specifier) {
   const key = specifier === packageName ? '.' : `.${specifier.slice(packageName.length)}`;
-  return exportTargets(manifest?.exports?.[key]).filter(target => target.startsWith('./') && !target.includes('\\') && !target.split('/').includes('..'))
+  return exportTargetStrings(manifest?.exports?.[key]).filter(target => target.startsWith('./') && !target.includes('\\') && !target.split('/').includes('..'))
     .map(target => canonical(path.resolve(packageRoot, target)));
 }
 
@@ -106,7 +101,7 @@ function checkGrammar(config, context) {
   const violations = [];
   const local = context.workspaces.find(workspace => workspace.name === grammar.package);
   // Node resolution per consumer: in an npm-workspaces monorepo a consumer whose range differs from the
-  // hoisted copy gets its own apps/<app>/node_modules/<package> (nivo-fe: apps/app on 0.5.0 beside a hoisted
+  // hoisted copy gets its own apps/<app>/node_modules/<package> (one consumer: apps/app on 0.5.0 beside a hoisted
   // 0.4.11). Every consumer is judged against the copy it actually resolves, never the hoisted one alone.
   // An app installs once, at its root (config.packageRoot): a side folder has no node_modules of its own.
   const installRoot = config.packageRoot ?? config.root;
@@ -391,7 +386,7 @@ function checkCustomHookLocations(config, context, sourceFile, roots) {
   const violations = [];
   const seen = new Set();
   const report = (symbol, node) => {
-    const identity = unaliasSymbol(ts, checker, symbol) ?? symbol;
+    const identity = normalizedSymbolValue(ts, checker, symbol) ?? symbol;
     if (!identity || seen.has(identity) || checker.getTypeOfSymbolAtLocation(identity, node).getCallSignatures().length === 0) return;
     seen.add(identity);
     violations.push(violation(config, sourceFile, node, 'FE_CUSTOM_HOOK_LOCATION',
@@ -411,7 +406,7 @@ function checkCustomHookLocations(config, context, sourceFile, roots) {
   const module = checker.getSymbolAtLocation(sourceFile);
   for (const exposed of module ? checker.getExportsOfModule(module) : []) {
     if (!/^use[A-Z0-9]/.test(exposed.name)) continue;
-    const identity = unaliasSymbol(ts, checker, exposed);
+    const identity = normalizedSymbolValue(ts, checker, exposed);
     for (const declaration of identity?.getDeclarations?.() ?? []) if (declaration.getSourceFile() === sourceFile) {
       const node = declarationName(ts, declaration) ?? declaration;
       report(identity, node);
@@ -473,17 +468,6 @@ function checkPureAndData(config, context, sourceFile, roots) {
   return violations;
 }
 
-function unaliasSymbol(ts, checker, value) {
-  let symbol = value ?? null;
-  const seen = new Set();
-  while (symbol && (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;
-}
 
 function selectedSymbol(ts, checker, expression) {
   const selected = unwrapExpression(ts, expression);
@@ -498,19 +482,9 @@ function selectedSymbol(ts, checker, expression) {
   return null;
 }
 
-function returnedExpressions(ts, declaration) {
-  if ((ts.isArrowFunction(declaration) || ts.isFunctionExpression(declaration)) && !ts.isBlock(declaration.body)) return [declaration.body];
-  const body = ts.isFunctionLike(declaration) ? declaration.body : null;
-  if (!body || !ts.isBlock(body)) return [];
-  const returned = [];
-  const visit = node => {
-    if (node !== body && ts.isFunctionLike(node)) return;
-    if (ts.isReturnStatement(node) && node.expression) returned.push(node.expression);
-    else ts.forEachChild(node, visit);
-  };
-  visit(body);
-  return returned;
-}
+/* The wider boundary set: `ts.isFunctionLike` (includes call signatures' declarations) rather than the
+ * four default callable kinds. */
+const returnedExpressions = (ts, declaration) => sharedReturnedExpressions(ts, declaration, { functionLike: ts.isFunctionLike });
 
 function knownWorldImport(specifier, imported) {
   if (specifier === 'next-intl') return WORLD_INTL_CALLS.has(imported);
@@ -611,7 +585,7 @@ function checkWorldRenderBoundaries(config, context, roots) {
   };
 
   const intrinsicUiHookSymbol = (symbol, checker) => {
-    const identity = unaliasSymbol(ts, checker, symbol);
+    const identity = normalizedSymbolValue(ts, checker, symbol);
     const declarations = identity?.getDeclarations?.() ?? [];
     return declarations.length > 0 && declarations.every(declaration => intrinsicUiHookFile(declaration.getSourceFile().fileName));
   };
@@ -668,7 +642,7 @@ function checkWorldRenderBoundaries(config, context, roots) {
         : ts.isPropertyAccessExpression(selected) ? selected.name.text : null;
       if (['forwardRef', 'memo'].includes(name) && expression.arguments[0]) return expressionFunctions(expression.arguments[0], checker, seen);
     }
-    const symbol = unaliasSymbol(ts, checker, selectedSymbol(ts, checker, expression));
+    const symbol = normalizedSymbolValue(ts, checker, selectedSymbol(ts, checker, expression));
     if (!symbol || seen.has(symbol)) return [];
     const nextSeen = new Set(seen).add(symbol);
     const functions = [];
@@ -692,7 +666,7 @@ function checkWorldRenderBoundaries(config, context, roots) {
     for (const [namespace, declaration] of info.namespaces) if (namespace === raw) {
       return declaration.worldEdge || knownWorldImport(declaration.specifier, propertyName ?? '');
     }
-    const identity = unaliasSymbol(ts, info.checker, raw);
+    const identity = normalizedSymbolValue(ts, info.checker, raw);
     return (identity?.getDeclarations?.() ?? []).some(declaration => {
       const fileName = declaration.getSourceFile().fileName;
       return insideAny(roots.hooks, fileName) || insideAny(roots.transport, fileName);
@@ -716,7 +690,7 @@ function checkWorldRenderBoundaries(config, context, roots) {
       if (namespaceIsWorld(namespace, sourceFile, property)) return true;
       if (symbolIsWorld(selectedSymbol(ts, checker, expression), sourceFile)) return true;
     }
-    const symbol = unaliasSymbol(ts, checker, selectedSymbol(ts, checker, expression));
+    const symbol = normalizedSymbolValue(ts, checker, selectedSymbol(ts, checker, expression));
     if (!symbol || seen.has(symbol)) return false;
     const nextSeen = new Set(seen).add(symbol);
     const declarations = symbol.getDeclarations?.() ?? [];
@@ -763,7 +737,7 @@ function checkWorldRenderBoundaries(config, context, roots) {
       if (name === 'map' && expression.arguments[0]) return expressionFunctions(expression.arguments[0], checker)
         .some(fn => functionHasRender(fn, checker, seen));
     }
-    const symbol = unaliasSymbol(ts, checker, selectedSymbol(ts, checker, ts.isCallExpression(expression) ? expression.expression : expression));
+    const symbol = normalizedSymbolValue(ts, checker, selectedSymbol(ts, checker, ts.isCallExpression(expression) ? expression.expression : expression));
     if (!symbol || seen.has(symbol)) return false;
     const nextSeen = new Set(seen).add(symbol);
     if (ts.isIdentifier(expression)) for (const declaration of symbol.getDeclarations?.() ?? []) {
@@ -839,7 +813,7 @@ function checkWorldRenderBoundaries(config, context, roots) {
     if (ts.isArrayLiteralExpression(expression)) return expression.elements.length > 0
       && expression.elements.every(item => renderBoundary(item, checker, seen, allowEmpty, expectedFile));
     if (ts.isIdentifier(expression)) {
-      const symbol = unaliasSymbol(ts, checker, checker.getSymbolAtLocation(expression));
+      const symbol = normalizedSymbolValue(ts, checker, checker.getSymbolAtLocation(expression));
       if (!symbol || seen.has(symbol)) return false;
       const nextSeen = new Set(seen).add(symbol);
       const values = (symbol.getDeclarations?.() ?? []).flatMap(declaration => ts.isVariableDeclaration(declaration) && declaration.initializer

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

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { isIP } from 'node:net';
-import { gitOutput } from '../../api/git/lib.mjs';
+import { lsFiles } from '../../api/git/ls-files.mjs'; import { revParseQuery } from '../../api/git/rev-parse-query.mjs'; import { configGet } from '../../api/git/config-get.mjs'; import { gitOutputOf } from '../../lib/git.mjs';
 import { repositoryName } from '../repo-identity.mjs';
 import { braceVariants } from '../../lib/glob.mjs';
 import { createSlotResolver, loadSlotManifest, openHfs } from '../slots.mjs';
 import { isFeTestPath } from '../rules/fe-no-tests.mjs';
+import { readTextFile } from '../../lib/read-text.mjs';
+import { managedScriptNames } from './managed-scripts.mjs';
 
 /**
  * HFS repository-tree check (knowledge/hfs/README.md): every StarCi repository is an
@@ -17,6 +18,7 @@ import { isFeTestPath } from '../rules/fe-no-tests.mjs';
  */
 
 export const HFS_RULE_IDS = [
+  'BE_TEST_TOPOLOGY',
   'HFS_APPS_REQUIRED',
   'HFS_APP_LAYOUT_INVALID',
   'HFS_E2E_IN_AUTOMATIC_GATE',
@@ -37,7 +39,6 @@ export const HFS_RULE_IDS = [
   'HFS_ROOT_SRC_FORBIDDEN_FE',
   'HFS_SRC_LAYOUT_INVALID',
   'HFS_STACKS_IN_SIDE',
-  'HFS_TEST_KIND_RETIRED',
   'HFS_WORK_IN_FE',
 ];
 
@@ -46,7 +47,7 @@ const RUNTIME_ROOT_MARKDOWN = new Set(['README.md', 'CONTEXT.md', 'CONTRIBUTING.
 const PRODUCT_ROOT_MARKDOWN = new Set(['README.md']);
 const README_SECTIONS = ['Overview', 'Stack', 'Repository layout', 'Development'];
 const BACKEND_SRC_CHILDREN = new Set(['features', 'modules', 'tests']);
-const MODULE_TIERS = new Set(['domain', 'integrations', 'platform']);
+const moduleTiersOf = resolver => new Set(resolver.slots().filter(slot => slot.profiles.includes('be')).flatMap(slot => braceVariants(slot.path)).map(variant => /^src\/modules\/([a-z][a-z-]*)\//.exec(variant)?.[1]).filter(Boolean)); // the folders of src/modules/ the slot manifest knows (domain, platform, integrations, events, queues, projections)
 // Owner test layout 2026-09-30: unit `<name>.spec.ts`, integration, e2e and contract by folder and suffix; int-spec and harness-spec stay banned.
 const RETIRED_TEST_SUFFIX = /\.(?:int|harness)-spec\.[cm]?[jt]sx?$/u;
 const RETIRED_TEST_FOLDER = /^src\/tests\/(?:harness|live|e2e\/live)(?:\/|$)/u;
@@ -100,7 +101,7 @@ function slotTestChildren(resolver) {
  */
 function ownsGitTopLevel(root) {
   try {
-    const top = gitOutput(['rev-parse', '--show-toplevel'], { cwd: root }).trim();
+    const top = gitOutputOf(revParseQuery(['--show-toplevel'], { cwd: root }), 'git rev-parse --show-toplevel').trim();
     const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
     return same(fs.realpathSync(path.resolve(top)), fs.realpathSync(path.resolve(root)));
   } catch {
@@ -113,8 +114,8 @@ function gitPaths(root) {
   try {
     // An empty index is still a Git tree. Falling back to disk in that case would count
     // untracked build output as repository content.
-    gitOutput(['rev-parse', '--is-inside-work-tree'], { cwd: root });
-    const out = gitOutput(['ls-files', '--cached', '-z', '--', '.'], { cwd: root, maxBuffer: 256 * 1024 * 1024 });
+    gitOutputOf(revParseQuery(['--is-inside-work-tree'], { cwd: root }), 'git rev-parse --is-inside-work-tree');
+    const out = gitOutputOf(lsFiles(['--cached', '-z', '--', '.'], { cwd: root, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files');
     return out.split('\0').filter(Boolean);
   } catch {
     return null;
@@ -181,11 +182,12 @@ function treeView(root) {
   };
 }
 
+// `hostname` is a WHATWG URL hostname: a name never holds ':', so after the brackets go only an IPv6 literal does.
 function privateHost(hostname) {
   const host = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
   if (host === 'localhost' || host === '::1' || host === '0.0.0.0' ||
       /(?:\.localhost|\.local|\.internal|\.lan)$/u.test(host)) return true;
-  if (isIP(host) === 6) return /^(?:::|f[cd][0-9a-f]*:|fe[89ab][0-9a-f]*:)/iu.test(host);
+  if (host.includes(':')) return /^(?:::|f[cd][0-9a-f]*:|fe[89ab][0-9a-f]*:)/iu.test(host);
   if (!host.includes('.')) return true;
   const octets = host.split('.');
   if (octets.length !== 4 || !octets.every(part => /^\d{1,3}$/u.test(part) && Number(part) <= 255)) return false;
@@ -197,20 +199,6 @@ function privateHost(hostname) {
 // The scripts the README Development section shows; each is required only when the managed package-scripts template of the
 // profile (packages/hfs/templates/<profile>/package-scripts/package.json, the one source of the managed script names) has it.
 const DEVELOPMENT_SCRIPTS = ['typecheck', 'lint', 'build', 'test'];
-// The templates sit beside the runtime in a checkout (packages/hfs/templates) and one level above the bundled runtime of @starci/hfs.
-const TEMPLATE_ROOTS = [path.resolve(import.meta.dirname, '..', '..', '..', 'packages', 'hfs', 'templates'), path.resolve(import.meta.dirname, '..', '..', '..', '..', 'templates')];
-const managedScriptCache = new Map();
-
-/** The script names of the managed package-scripts template of a profile. The template holds a {{appScripts}} placeholder, so it is read by key, not parsed as JSON. */
-function managedScriptNames(profile) {
-  if (!managedScriptCache.has(profile)) {
-    const file = TEMPLATE_ROOTS.map(dir => path.join(dir, profile, 'package-scripts', 'package.json')).find(candidate => fs.existsSync(candidate));
-    if (!file) throw Error(`The managed package-scripts template of profile ${profile} cannot be found next to the runtime.`);
-    managedScriptCache.set(profile, new Set([...fs.readFileSync(file, 'utf8').matchAll(/^\s*"([A-Za-z0-9:_.-]+)":\s*"/gmu)].map(match => match[1])));
-  }
-  return managedScriptCache.get(profile);
-}
-
 /** The README command that runs a managed script: `npm test` for test, `npm run <name>` for the others (never a longer script name that starts with it). */
 function scriptCommand(name) {
   const escaped = name.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
@@ -218,7 +206,7 @@ function scriptCommand(name) {
 }
 
 /** Presentation checks shared by the product HFS gate and this runtime's own standalone gate. */
-export function checkRepoPresentation({ root, runtime = false, tree = treeView(root), profile = 'app' }) {
+export function checkRepoPresentation({ root, runtime = false, tree = treeView(root), profile = 'app', edition = 'full' }) {
   const violations = [];
   const finding = (ruleId, entry, message, line = 1) => violations.push({ ruleId, path: entry, line, column: 1, message });
   for (const entry of tree.top) {
@@ -268,7 +256,7 @@ export function checkRepoPresentation({ root, runtime = false, tree = treeView(r
   };
   if (!runtime && headings.some(item => item.name === 'Development')) {
     const development = sectionBody('Development');
-    const scripts = DEVELOPMENT_SCRIPTS.filter(name => managedScriptNames(profile).has(name));
+    const scripts = DEVELOPMENT_SCRIPTS.filter(name => managedScriptNames(profile, edition).has(name));
     const commands = [/npm (?:ci|install)/u, ...scripts.map(scriptCommand)];
     if (commands.some(command => !command.test(development)))
       finding('HFS_README_DEVELOPMENT_INCOMPLETE', 'README.md',
@@ -319,9 +307,7 @@ const UNIT_RUN_SCRIPTS = ['test', 'test:unit', 'test:ci', 'test:affected', 'test
 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 readText(root, relative) {
-  try { return fs.readFileSync(path.join(root, ...relative.split('/')), 'utf8'); } catch { return null; }
-}
+const readText = readTextFile;
 
 // A repository-local core.hooksPath that points anywhere but husky's own directory switches the commit and push
 // hooks off for that clone (a lane once redirected it to skip husky), so the gate every other clone runs never ran.
@@ -331,10 +317,9 @@ const HUSKY_HOOKS_PATH = /^\.husky(?:\/_)?\/?$/u;
 /** A directory that is not the top level of its own work tree has no hooks of its own: the check is not applicable there. */
 function hooksPathNotRedirected({ root, finding }) {
   if (!ownsGitTopLevel(root)) return { status: 'not-applicable', reason: 'the checked root is not the top level of its own Git work tree, so it has no hooks of its own' };
-  let value = '';
-  try {
-    value = gitOutput(['config', '--local', '--get', 'core.hooksPath'], { cwd: root }).trim();
-  } catch { return { status: 'checked' }; } // key not set: nothing is redirected
+  const set = configGet(root, 'core.hooksPath', { local: true });
+  if (!set.ok) return { status: 'checked' }; // key not set: nothing is redirected
+  const value = set.stdout;
   if (value && !HUSKY_HOOKS_PATH.test(value.replaceAll('\\', '/')))
     finding('HFS_HOOKS_PATH_REDIRECTED', '.git/config', `core.hooksPath is set to ${value} in this clone. Unset it (git config --local --unset core.hooksPath) and let husky own the hooks; a redirected path skips the pre-commit and pre-push gates.`);
   return { status: 'checked' };
@@ -450,7 +435,7 @@ export function checkHfs(config) {
       continue;
     }
     if (!tree.hasDir(`apps/${app}/src`)) missing.push('src/');
-    // A back-end app must hold exactly what the slot of its kind requires (be.app.migrate has no app.module.ts).
+    // A back-end app must hold exactly what the slot of its kind requires (each kind's slot names its own requires).
     if (backend) for (const required of resolver.requiredFiles(`apps/${app}/src/main.ts`)) {
       const directory = required.endsWith('/');
       if (!(directory ? tree.hasDir(required.slice(0, -1)) : tree.hasFile(required))) missing.push(required.slice(`apps/${app}/`.length));
@@ -471,8 +456,8 @@ export function checkHfs(config) {
       }
     }
     for (const tier of tree.children('src/modules').sort()) {
-      if (!MODULE_TIERS.has(tier)) {
-        finding('HFS_MODULE_TIER_INVALID', `src/modules/${tier}`, `Module tier ${tier} is not one of domain, platform, integrations.`);
+      if (!moduleTiersOf(resolver).has(tier)) {
+        finding('HFS_MODULE_TIER_INVALID', `src/modules/${tier}`, `Module tier ${tier} is not one of ${[...moduleTiersOf(resolver)].sort().join(', ')}.`);
       }
     }
     const testChildren = slotTestChildren(resolver);
@@ -488,11 +473,11 @@ export function checkHfs(config) {
   // live/; a backend spec sits by its kind (beside its subject, or under src/tests/{integration,e2e,contract}/).
   for (const file of tree.files()) {
     if (RETIRED_TEST_SUFFIX.test(file))
-      finding('HFS_TEST_KIND_RETIRED', file, `${file} uses a retired test kind. Only unit *.spec.ts, *.integration-spec.ts, *.e2e-spec.ts and *.contract-spec.ts exist, each in its own folder under src/tests/.`);
+      finding('BE_TEST_TOPOLOGY', file, `${file} uses a retired test kind. Only unit *.spec.ts, *.integration-spec.ts, *.e2e-spec.ts and *.contract-spec.ts exist, each in its own folder under src/tests/.`);
     else if (backend && RETIRED_TEST_FOLDER.test(file))
-      finding('HFS_TEST_KIND_RETIRED', file, `${file} sits in a retired test folder. Unit specs sit beside their subject, flows go under src/tests/e2e/<area>/ and test infrastructure under src/tests/world/.`);
+      finding('BE_TEST_TOPOLOGY', file, `${file} sits in a retired test folder. Unit specs sit beside their subject, flows go under src/tests/e2e/<area>/ and test infrastructure under src/tests/world/.`);
     else if (backend && /^src\/tests\//u.test(file) && EXTRA_TEST_CONFIG.test(file))
-      finding('HFS_TEST_KIND_RETIRED', file, `${file} is a per-lane test config. One root jest.config.js declares exactly the unit, integration, e2e and contract projects.`);
+      finding('BE_TEST_TOPOLOGY', file, `${file} is a per-lane test config. One root jest.config.js declares exactly the unit, integration, e2e and contract projects.`);
   }
 
   if (backend) testTreesOutOfDefaultProgram({ root: config.root, tree, finding });
@@ -511,13 +496,13 @@ export function checkHfs(config) {
 
 /**
  * The HFS tree check of the app root (`resolver` is the app's): the README, the root entries the app-root slots allow and require,
- * the automatic gates (hooks, the root scripts they call, the workflows) and the hooks path. `hfs check` runs it once per app; the
+ * the automatic gates (hooks, the root scripts they call, the workflows) and the hooks path. `starci app check` runs it once per app; the
  * machine runs checkHfs once per side folder.
  */
 export function checkAppRoot({ root, resolver, tree = treeView(root) }) {
   const violations = [];
   const finding = (ruleId, entry, message) => violations.push({ ruleId, path: entry, line: 1, column: 1, message });
-  violations.push(...checkRepoPresentation({ root, tree, profile: 'app' }).violations);
+  violations.push(...checkRepoPresentation({ root, tree, profile: 'app', edition: resolver.repo?.edition ?? 'full' }).violations);
   const allowed = slotRootEntries(resolver, 'app');
   for (const entry of [...tree.top].sort()) {
     if (NON_NPM_ENTRIES.has(entry) || /\.md$/iu.test(entry)) continue;

package/runtime/scripts/hfs/architecture/i18n-keys.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 
 /**
  * R106 `i18n-keys` (FE_I18N_KEYS). The catalogs of an app (`apps/<app>/src/modules/i18n/messages/<locale>.json`, slot fe.modules.i18n) and
- * the source that reads them agree, both ways. The key sets of the locales agree with each other (FE_I18N_CATALOG, `hfs check`); this
+ * the source that reads them agree, both ways. The key sets of the locales agree with each other (FE_I18N_CATALOG, `starci app check`); this
  * rule holds the source to the catalogs:
  *
  *   - a key read with a literal is in every locale: `useTranslations("ns")` / `getTranslations("ns")` (also `{ namespace }`, `await`)

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

@@ -31,6 +31,11 @@ import { checkUnitSpecProviders, UNIT_SPEC_PROVIDERS_RULE_IDS } from './unit-spe
 import { checkInjectionTokenExported, INJECTION_TOKEN_EXPORTED_RULE_IDS } from './injection-token-exported.mjs';
 import { checkContractFixtureGuard, CONTRACT_FIXTURE_GUARD_RULE_IDS } from './contract-fixture-guard.mjs';
 import { checkSchemaOwner, SCHEMA_OWNER_RULE_IDS } from './schema-owner.mjs';
+import { checkSqlReturning, SQL_RETURNING_RULE_IDS } from './sql-returning.mjs';
+import { checkContextOwner, CONTEXT_OWNER_RULE_IDS } from './context-owner.mjs';
+import { checkContextCoupling, CONTEXT_COUPLING_RULE_IDS } from './context-coupling.mjs';
+import { checkContextTransaction, CONTEXT_TRANSACTION_RULE_IDS } from './context-transaction.mjs';
+import { checkContextPlatformTables, CONTEXT_PLATFORM_TABLES_RULE_IDS } from './context-platform-tables.mjs';
 import { checkModulePerTransport, MODULE_PER_TRANSPORT_RULE_IDS } from './module-per-transport.mjs';
 import { checkBackgroundUnowned, BACKGROUND_UNOWNED_RULE_IDS } from './background-unowned.mjs';
 import { checkTransportOwner, TRANSPORT_OWNER_RULE_IDS } from './transport-owner.mjs';
@@ -42,6 +47,7 @@ import { checkPackageShape, PACKAGE_SHAPE_RULE_IDS } from './package-shape.mjs';
 import { checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS } from './fe-slot-allows.mjs';
 import { checkI18nKeys, I18N_KEYS_RULE_IDS } from './i18n-keys.mjs';
 import { checkDocLanguage, DOC_LANGUAGE_RULE_IDS } from './doc-language.mjs';
+import { checkBackendSupabase, checkFrontendSupabase, BACKEND_SUPABASE_RULE_IDS, FRONTEND_SUPABASE_RULE_IDS } from './supabase.mjs';
 import { LINT_CODES, onLintSurface } from './surface.mjs';
 
 export { REGISTRATION_RULE_IDS, SWR_DATA_RULE_IDS };
@@ -68,10 +74,16 @@ const BACKEND_MACHINE = {
   unitSpecProviders: [checkUnitSpecProviders, UNIT_SPEC_PROVIDERS_RULE_IDS],
   injectionTokenExported: [checkInjectionTokenExported, INJECTION_TOKEN_EXPORTED_RULE_IDS],
   schemaOwner: [checkSchemaOwner, SCHEMA_OWNER_RULE_IDS],
+  sqlReturning: [checkSqlReturning, SQL_RETURNING_RULE_IDS],
+  contextOwner: [checkContextOwner, CONTEXT_OWNER_RULE_IDS],
+  contextCoupling: [checkContextCoupling, CONTEXT_COUPLING_RULE_IDS],
+  contextTransaction: [checkContextTransaction, CONTEXT_TRANSACTION_RULE_IDS],
+  contextPlatformTables: [checkContextPlatformTables, CONTEXT_PLATFORM_TABLES_RULE_IDS],
   modulePerTransport: [checkModulePerTransport, MODULE_PER_TRANSPORT_RULE_IDS],
   backgroundUnowned: [checkBackgroundUnowned, BACKGROUND_UNOWNED_RULE_IDS],
   testWorldFiles: [checkTestWorldFiles, TEST_WORLD_FILES_RULE_IDS],
   contractFixtureGuard: [checkContractFixtureGuard, CONTRACT_FIXTURE_GUARD_RULE_IDS],
+  supabaseBackend: [checkBackendSupabase, BACKEND_SUPABASE_RULE_IDS],
 };
 
 // The frontend repository machine (R21, R50, R54, R55, R56, R63, R94, R106): same shape, run for a front-end repository only.
@@ -84,6 +96,7 @@ const FRONTEND_MACHINE = {
   crossAppDuplicate: [checkCrossAppDuplicate, CROSS_APP_DUPLICATE_RULE_IDS],
   feSlotAllows: [checkFeSlotAllows, FE_SLOT_ALLOWS_RULE_IDS],
   i18nKeys: [checkI18nKeys, I18N_KEYS_RULE_IDS],
+  supabaseFrontend: [checkFrontendSupabase, FRONTEND_SUPABASE_RULE_IDS],
 };
 
 /** Errors the machine reports when a program cannot be built or an edge cannot be proven: it cannot judge, so it refuses. */
@@ -125,8 +138,8 @@ const FRONTEND_RULE_IDS = [
   'FE_SOURCE_LAYOUT_INVALID',
   'FE_WORLD_OWNER_RENDER_BOUNDARY',
 ];
-export const OWNER_RULE_IDS = ['ARCH_OWNER_EXPORT_BYPASS', 'ARCH_OWNER_EXPORT_STAR'];
-export const GRAMMAR_RULE_IDS = ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'];
+const OWNER_RULE_IDS = ['ARCH_OWNER_EXPORT_BYPASS', 'ARCH_OWNER_EXPORT_STAR'];
+const GRAMMAR_RULE_IDS = ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'];
 
 /**
  * Every code the machine reports as an error because it cannot judge (a check that cannot run is an error, never a pass).
@@ -152,7 +165,7 @@ export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
   return [...new Set(machineIds().filter((id) => !ordinary.has(id)))].sort();
 })());
 
-/** Every code the machine can emit, derived from the rule id lists of its checks (`hfs check` ships exactly these why entries). */
+/** Every code the machine can emit, derived from the rule id lists of its checks (`starci app check` ships exactly these why entries). */
 export const ARCHITECTURE_RULE_IDS = Object.freeze([...new Set([
   ...COMMON_RULE_IDS, ...BACKEND_RULE_IDS, ...FRONTEND_RULE_IDS, ...HFS_RULE_IDS, ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS,
   ...DEAD_EXPORT_RULE_IDS, ...DOC_LANGUAGE_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...CLONE_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS,
@@ -253,7 +266,7 @@ export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths =
   const asViolation = item => LINT_CODES.has(item.ruleId);
   const allErrors = context.errors.filter(item => item.ruleId.startsWith('ARCH_TSCONFIG_') || !item.path || inScope(item));
   const obligations = surface === 'all' ? violations : [...violations, ...context.errors.filter(asViolation).filter(inScope)];
-  // The lint surface is what an editor can show on a line of a TypeScript file; `hfs check` keeps every other finding of the machine.
+  // The lint surface is what an editor can show on a line of a TypeScript file; `starci app check` keeps every other finding of the machine.
   const onSurface = item => surface === 'all' || onLintSurface(config.root, item) === (surface === 'lint');
   const errors = stable(surface === 'all' ? allErrors : allErrors.filter(item => !asViolation(item)));
   const scopedViolations = stable(obligations.filter(inScope).filter(onSurface));

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

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { canonical } from './config.mjs';
-import { sourceLocation } from './typescript.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 
 /**
  * The small TypeScript reading kit the R33/R38/R39/R41/R45/R84/R86 machine checks share (connection-map, sql-owner,
@@ -115,18 +115,51 @@ export function machineKit({ config, context, graph }) {
   };
 
   /** The `{ provide: <token>, ... }` provider literals of `file` whose token is `name` imported from `moduleName`, in source order. */
+  const HELPER_DEPTH = 4;
+
+  /** The body a call or a spread identifier resolves to when it is a function or a const declared in a file of the program (not a package), else null. */
+  const helperBodyOf = (checker, node) => {
+    const target = ts.isCallExpression(node) ? node.expression : node;
+    for (const declaration of declarationsOf(checker, ts.isPropertyAccessExpression(target) ? target.name : target)) {
+      if (!graphPath(declaration)) continue;
+      if (ts.isFunctionDeclaration(declaration) && declaration.body) return { declaration, body: declaration.body };
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer) return { declaration, body: declaration.initializer };
+    }
+    return null;
+  };
+
+  /**
+   * The `{ provide: <token>, ... }` provider literals of `file` whose token is `name` imported from `moduleName`, in source order.
+   * A call or a spread of a function or a const declared in another file of the program is followed (to a depth of four), so a
+   * helper that builds the `APP_GUARD` or `APP_FILTER` entries outside the app root file is read too: the entry's `node` is then the
+   * call or spread inside the app root (where the entry is provided), its `useClass` and `checker` those of the helper's file.
+   */
   const providersOf = (file, name, moduleName) => {
-    const checker = checkerOf(file.sourceFile);
     const found = [];
-    walk(file.sourceFile, node => {
-      if (!ts.isObjectLiteralExpression(node)) return true;
-      const provide = propertyOf(node, 'provide');
-      if (provide && isImportOf(checker, valueOfProperty(provide), name, moduleName)) {
-        const use = propertyOf(node, 'useClass');
-        found.push({ node, useClass: use ? valueOfProperty(use) : null, checker });
-      }
-      return true;
-    });
+    const seen = new Set();
+    const scan = (root, anchor, depth) => {
+      const checker = checkerOf(root.getSourceFile());
+      walk(root, node => {
+        if (ts.isObjectLiteralExpression(node)) {
+          const provide = propertyOf(node, 'provide');
+          if (provide && isImportOf(checker, valueOfProperty(provide), name, moduleName)) {
+            const use = propertyOf(node, 'useClass');
+            found.push({ node: anchor ?? node, useClass: use ? valueOfProperty(use) : null, checker });
+          }
+          return true;
+        }
+        const reference = ts.isSpreadElement(node) ? node.expression : (ts.isCallExpression(node) ? node : null);
+        if (reference && depth < HELPER_DEPTH) {
+          const helper = helperBodyOf(checker, reference);
+          if (helper && !seen.has(helper.declaration)) {
+            seen.add(helper.declaration);
+            scan(helper.body, anchor ?? node, depth + 1);
+          }
+        }
+        return true;
+      });
+    };
+    scan(file.sourceFile, null, 0);
     return found.sort((a, b) => a.node.getStart() - b.node.getStart());
   };
 

package/runtime/scripts/hfs/architecture/managed-scripts.mjs

@@ -0,0 +1,27 @@
+// managed-scripts.mjs - reads the script names from the managed package-script template for one HFS profile and
+// edition. Templates stay the source of truth; README presentation checks consume only this cached name set.
+import fs from 'node:fs';
+import path from 'node:path';
+import { managedGroupOf } from '../edition-slots.mjs';
+import { loadSlotManifest } from '../slots.mjs';
+
+const TEMPLATE_ROOTS = [
+  path.resolve(import.meta.dirname, '..', '..', '..', 'packages', 'hfs', 'templates'),
+  path.resolve(import.meta.dirname, '..', '..', '..', '..', 'templates'),
+];
+const managedScriptCache = new Map();
+
+/** The script names of a profile/edition template after its partials are expanded. */
+export function managedScriptNames(profile, edition = 'full') {
+  const key = `${profile}:${edition}`;
+  if (!managedScriptCache.has(key)) {
+    const slot = loadSlotManifest().slots.find((entry) => entry.id === `${profile}.package-manifest`);
+    const group = slot && managedGroupOf(slot, edition);
+    const templates = group && TEMPLATE_ROOTS.find((dir) => fs.existsSync(path.join(dir, profile, group, 'package.json')));
+    if (!templates) throw Error(`The managed package-scripts template of profile ${profile} cannot be found next to the runtime.`);
+    const text = fs.readFileSync(path.join(templates, profile, group, 'package.json'), 'utf8')
+      .replace(/^\{\{> ([\w./-]+)\}\}\r?\n/gmu, (_, partial) => fs.readFileSync(path.join(templates, partial), 'utf8'));
+    managedScriptCache.set(key, new Set([...text.matchAll(/^\s*"([A-Za-z0-9:_.-]+)":\s*"/gmu)].map((match) => match[1])));
+  }
+  return managedScriptCache.get(key);
+}

package/runtime/scripts/hfs/architecture/module-per-transport.mjs

@@ -11,8 +11,11 @@ import { treeOf } from './required-files.mjs';
  *     anywhere in a feature, and an `@Module` class (or a `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a
  *     feature file that is neither the application module nor the transport module of its own folder are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
- *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message; cli: cli). An app root that
- *     lists a feature's application module, or the transport module of another kind, is refused.
+ *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root that
+ *     lists a feature's application module, or the transport module of another kind, is refused;
+ *   - a composed root (an owner slot with `composedBy`, be.cli) holds one static module per folder, named after the folder
+ *     (cli.module.ts, <group>/<group>.module.ts); an app of a composing kind lists the root module only, and an app of any
+ *     other kind lists none of its modules.
  */
 export const MODULE_PER_TRANSPORT_RULE_IDS = ['BE_MODULE_SHAPE'];
 
@@ -31,18 +34,30 @@ export function checkModulePerTransport(input) {
     const owner = resolver.ownerOf(rel);
     return owner && resolver.slot(owner.slot)?.tier === 'feature' ? owner : null;
   };
-  /** {feature, root, protocol} of a file inside a feature: protocol is the transport folder, null for the application side. */
+  /**
+   * {feature, root, protocol, composed} of a file inside a feature: protocol is the transport folder, null for the application
+   * side. composed is set for a composed root, an owner slot with `composedBy` (be.cli): an app of those kinds lists its root
+   * module, and every folder of the root holds one static module named after the folder.
+   */
   const placeOf = rel => {
     const owner = featureOf(rel);
     if (!owner) return null;
+    const slot = resolver.slot(owner.slot);
     const below = rel.slice(owner.root.length + 1).split('/');
-    return { root: owner.root, feature: path.posix.basename(owner.root), protocol: below[0] === 'transport' && below.length > 2 ? below[1] : null, below };
+    const feature = path.posix.basename(owner.root);
+    if (slot.composedBy) return { root: owner.root, feature, protocol: null, below, composed: slot };
+    return { root: owner.root, feature, protocol: below[0] === 'transport' && below.length > 2 ? below[1] : null, below, composed: null };
+  };
+  /** The one module file a folder of a composed root may hold: <folder>/<folder>.module.ts. */
+  const composedModuleOf = rel => {
+    const dir = path.posix.dirname(rel);
+    return `${dir}/${path.posix.basename(dir)}.module.ts`;
   };
 
   // The transport slots and the app kinds that compose them, by protocol folder name.
   const composedBy = new Map();
   for (const slot of resolver.slots()) {
-    if (!slot.composedBy) continue;
+    if (!slot.composedBy || slot.owner) continue;
     composedBy.set(path.posix.basename(slot.path.replace(/\/+$/u, '')), slot.composedBy);
   }
 
@@ -74,6 +89,11 @@ export function checkModulePerTransport(input) {
       if (!isModule) continue;
       modules.set(statement, { name: statement.name.text, file });
       if (!place) continue;
+      if (place.composed) {
+        const own = composedModuleOf(file.rel);
+        if (file.rel !== own) report(file, statement.name, `${statement.name.text} is a Nest module declared in ${file.rel}; every folder of ${place.root} holds exactly one static module named after it (${own}), never a module per command.`, { feature: place.feature });
+        continue;
+      }
       const own = place.protocol === null
         ? `${place.root}/${place.feature}.module.ts`
         : `${place.root}/transport/${place.protocol}/${place.feature}-${place.protocol}.module.ts`;
@@ -111,7 +131,11 @@ export function checkModulePerTransport(input) {
         if (!place || seen.has(node)) continue;
         seen.add(node);
         references += 1;
-        if (place.protocol === null) {
+        if (place.composed) {
+          const rootModule = `${place.root}/${place.feature}.module.ts`;
+          if (!place.composed.composedBy.includes(app.kind)) report(root, node, `App ${app.name} is of kind ${app.kind} and lists ${module.name} from ${place.root}; only an app of kind ${place.composed.composedBy.join(', ')} composes that root.`, { app: app.name, module: module.name });
+          else if (module.file.rel !== rootModule) report(root, node, `App ${app.name} lists ${module.name}, a group module inside ${place.root}; the app lists the root module (${rootModule}), which imports every group module.`, { app: app.name, module: module.name });
+        } else if (place.protocol === null) {
           report(root, node, `App ${app.name} lists ${module.name}, the application module of feature ${place.feature}; apps import only transport modules (${place.feature}-<protocol>.module.ts), which import the application module themselves.`, { app: app.name, module: module.name });
         } else if (!(composedBy.get(place.protocol) ?? []).includes(app.kind)) {
           const allowed = [...composedBy].filter(([, kinds]) => kinds.includes(app.kind)).map(([protocol]) => protocol).sort();