@starci/eslint-canon-fe 7.1.2 → 8.0.1

package/runtime/packages/hfs/templates/app/package-scripts/package.json

@@ -0,0 +1,22 @@
+{
+  "scripts": {
+    "prepare": "husky",
+    {{appScripts}}
+    "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:fe": "{{buildFe}}",
+    "codegen": "node scripts/codegen.mjs",
+    "typecheck": "{{typecheck}}",
+    "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
+    "lint": "npm run codegen --silent && hfs lint",
+    "lint:fix": "npm run codegen --silent && hfs lint --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "cd be && jest --selectProjects unit --coverage",
+    "test:affected": "cd be && jest --selectProjects unit --passWithNoTests",
+    "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
+    "test:e2e": "npm run typecheck:tests && cd be && jest --selectProjects e2e",
+    "test:contract": "npm run typecheck:tests && cd be && jest --selectProjects contract",
+    "test:stack": "cd be && starci-test-stack",
+    "contract:emit": "hfs emit-contracts"
+  }
+}

package/runtime/scripts/checks/architecture/config.mjs

@@ -61,7 +61,12 @@ function existingRegularFile(root, relative) {
   }
 }
 
-function workspaceDirectories(root) {
+/**
+ * The npm workspaces below `root`. The one package.json of an app is at `packageRoot` (the app root; `root` is its side folder):
+ * its workspace patterns under `<side>/` are this side's, read relative to the side folder, and every other pattern is the other
+ * side's.
+ */
+function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side = null } = {}) {
   const directories = new Set();
   const queue = [root];
   const visited = new Set();
@@ -89,11 +94,14 @@ function workspaceDirectories(root) {
     const packageRoot = queue.shift();
     if (visited.has(packageRoot)) continue;
     visited.add(packageRoot);
-    const pkg = readJson(path.join(packageRoot, 'package.json'));
+    const sideRoot = side !== null && packageRoot === root;
+    const pkg = readJson(path.join(sideRoot ? appPackageRoot : packageRoot, 'package.json'));
     const patterns = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
     for (const pattern of Array.isArray(patterns) ? patterns : []) {
       if (typeof pattern !== 'string' || !pattern.trim()) throw Error('package.json workspace entries must be non-empty paths.');
-      const normalized = slash(pattern.trim()).replace(/^\.\//, '');
+      const written = slash(pattern.trim()).replace(/^\.\//, '');
+      if (sideRoot && !written.startsWith(`${side}/`)) continue;
+      const normalized = sideRoot ? written.slice(side.length + 1) : written;
       const segments = normalized.split('/');
       if (path.isAbsolute(normalized) || segments.some(segment => segment === '..' || (segment.includes('*') && segment !== '*'))) {
         throw Error(`Unsupported local workspace pattern: ${normalized}.`);
@@ -121,7 +129,10 @@ function workspaceDirectories(root) {
     for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
       for (const [name, value] of Object.entries(pkg?.[section] ?? {})) {
         if (typeof value !== 'string' || !value.startsWith('file:')) continue;
-        const absolute = path.resolve(packageRoot, value.slice('file:'.length));
+        const absolute = path.resolve(sideRoot ? appPackageRoot : packageRoot, value.slice('file:'.length));
+        // The app's one package.json also lists the other side's file dependencies (inside the app, outside this side): not this
+        // side's. A path that leaves the app is judged like any other: a package of the same repository, or refused.
+        if (sideRoot && !isInside(root, absolute) && isInside(appPackageRoot, absolute)) continue;
         const label = `${section}.${name} file dependency`;
         if (isInside(root, absolute)) { admit(absolute, label, true); continue; }
         // A sibling package of the same repository: this project consumes it, so the path is real and
@@ -248,15 +259,19 @@ const GRAMMAR_PACKAGE = '@starci/grammar';
  * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
  * a globals.css to judge (the contract is then reported unavailable, never passed).
  */
-function derivedGrammar(root, apps, workspaces) {
+function derivedGrammar(root, packageRoot, workspaces, apps = []) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
-  const consumerManifests = apps.map(app => `apps/${app.name}/package.json`).filter(relative => existingRegularFile(root, relative));
+  // The apps have no package.json of their own: the app root's one manifest declares their dependencies, and it is a consumer
+  // when it declares the Grammar package; so is every workspace package that does.
+  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
+  const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
+  const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
     if (!workspace.startsWith('packages/')) continue;
     const manifest = `${workspace}/package.json`;
     const pkg = readJson(path.join(root, ...manifest.split('/')));
-    if (pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE))) consumerManifests.push(manifest);
+    if (declaresGrammar(pkg)) consumerManifests.push(manifest);
   }
   if (!consumerManifests.length) return null;
   return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react'] };
@@ -272,10 +287,14 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
   if (!fs.lstatSync(root).isDirectory()) throw Error('Repository root must be a directory.');
   const opened = hfs ?? openHfs({ repoRoot: root });
   const { profile, apps } = opened.repo;
-  const workspaces = workspaceDirectories(root);
-  const inferred = inferredLayout(root, [...new Set([...workspaces, ...apps.map(app => `apps/${app.name}`)])].sort());
+  // A side of an app (the side folder is the root the machine judges) keeps its dependencies in the app root's one package.json.
+  const side = opened.repo.side ?? null;
+  const packageRoot = side === null ? root : path.dirname(root);
+  const workspaces = workspaceDirectories(root, { packageRoot, side });
+  const appDirs = apps.map(app => `apps/${app.name}`);
+  const inferred = inferredLayout(root, [...new Set([...workspaces, ...appDirs])].sort());
   const kinds = [profile === 'be' ? 'backend' : 'frontend'];
-  const projects = discoveredProjects(root, workspaces);
+  const projects = discoveredProjects(root, [...new Set([...workspaces, ...appDirs])].sort());
   if (!projects.length) throw Error('The repository has no tsconfig.json to derive a TypeScript project from.');
   const backend = {
     modules: ['src/modules'],
@@ -290,11 +309,12 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
     hooks: inferred.hooks,
     modules: inferred.modules,
     transport: inferred.transport,
-    grammar: profile === 'fe' ? derivedGrammar(root, apps, workspaces) : null,
+    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
   };
   if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
   return {
     root,
+    packageRoot,
     repository: enclosingRepository(root),
     kinds,
     projects,

package/runtime/scripts/checks/architecture/contracts.mjs

@@ -276,7 +276,7 @@ function contractTypeStatusFromType(ts, checker, type, seen = new Set(), depth =
   }
   for (const anonymous of ['Record', 'Partial', 'Pick', 'Omit', 'Required']) if (builtinSymbol(ts, named, anonymous)) return 'inline';
   if (type.aliasSymbol) return 'named';
-  if (type.symbol?.getDeclarations?.().some(declaration => ts.isEnumDeclaration(declaration))) return 'named';
+  if ((type.symbol?.getDeclarations?.() ?? []).some(declaration => ts.isEnumDeclaration(declaration))) return 'named';
   if (type.flags & ts.TypeFlags.TypeParameter) return 'named';
   if (type.flags & ts.TypeFlags.Boolean) return 'scalar';
   if (type.flags & (ts.TypeFlags.Union | ts.TypeFlags.Intersection)) return 'inline';
@@ -590,7 +590,7 @@ function checkMessageReadonly(config, context, checker, declaration, localFiles,
     }
     const type = classInstanceType(ts, checker, selected);
     for (const base of type && checker.getBaseTypes ? checker.getBaseTypes(type) : []) {
-      const declarations = base.symbol?.getDeclarations?.().filter(item => ts.isClassDeclaration(item)) ?? [];
+      const declarations = (base.symbol?.getDeclarations?.() ?? []).filter(item => ts.isClassDeclaration(item)) ?? [];
       if (declarations.length !== 1) {
         reasons.push(`${relativePath(config.root, sourceFile.fileName)} inherits message fields from a class outside the checked production program`);
       } else if (localFiles.has(canonical(declarations[0].getSourceFile().fileName))) visitClass(declarations[0]);
@@ -654,7 +654,7 @@ function checkInjectedClass(config, context, checker, declaration, classKind, ta
   if (classKind) {
     const type = classInstanceType(ts, checker, declaration);
     for (const base of type && checker.getBaseTypes ? checker.getBaseTypes(type) : []) {
-      const declarations = base.symbol?.getDeclarations?.().filter(item => ts.isClassDeclaration(item)) ?? [];
+      const declarations = (base.symbol?.getDeclarations?.() ?? []).filter(item => ts.isClassDeclaration(item)) ?? [];
       if (declarations.length !== 1) {
         reasons.push(`${relativePath(config.root, sourceFile.fileName)} inherits an injected constructor from a class outside the checked production program`);
       } else if (localFiles.has(canonical(declarations[0].getSourceFile().fileName))) {
@@ -709,7 +709,7 @@ export function checkBackendContracts(config, context) {
       publicReasons.push(`${owner.entry} uses export =, so named capability API discovery is unavailable`);
     }
     for (const symbol of exportedSymbols(ts, checker, entry)) {
-      const declarations = symbol.getDeclarations?.().filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName))) ?? [];
+      const declarations = (symbol.getDeclarations?.() ?? []).filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName))) ?? [];
       if (!declarations.length) continue;
       const representative = declarations[0];
       if (isFrameworkHelper(representative.getSourceFile(), representative, framework)) continue;

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

@@ -1,14 +1,17 @@
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { isFeTestPath } from '../../lib/hfs-rules/fe-no-tests.mjs';
 
 /**
  * R94 `fe-slot-allows` (FE_SLOT_FILE_ROLE). A front-end slot that owns a whole directory (`fe.route`, `fe.feature`,
  * `fe.components`, `fe.hooks`, `fe.modules.api`) also says what its instances hold (`allows` in knowledge/hfs/slots.yaml).
  * Every tracked file of such a slot is matched against the `requires` and `allows` entries of its slot; a file no entry names is a
- * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a `.test.tsx` beside a component, a stray file at
- * a feature root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
+ * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a stray file beside a component or at a feature
+ * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
  * Files no slot owns are HFS_PATH_NO_SLOT's (`hfs check`), so together every front-end file is placed by exactly one slot and
- * named by it.
+ * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
+ * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * HFS_PATH_NO_SLOT does (scripts/lib/hfs-path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];
 
@@ -21,6 +24,7 @@ export function checkFeSlotAllows({ config, graph }) {
   let files = 0;
   const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
   for (const file of [...tree.files].sort()) {
+    if (isFeTestPath(file)) continue;   // FE_NO_TESTS's, the one finding of that file
     const classified = resolver.classifyPath(file);
     if (classified.status !== 'owned') continue;
     const slot = resolver.slot(classified.slot);

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

@@ -1,14 +1,11 @@
 // framework-pinned.mjs - the Next.js files that only load from a source root (the directory holding
-// app/), and the export names the framework mandates in them. Authored once in
-// knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles, frameworkPinnedRootExports),
-// never hard-coded here (supervisor rulings, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4 and
-// inc-846867b9a34e). Read by the architecture check (FE_SOURCE_LAYOUT_INVALID) and the Next name-shape
-// check (FE_SOURCE_NAME_SHAPE).
+// app/). Authored once in knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles), never
+// hard-coded here (supervisor ruling, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4). Read by the architecture
+// check (FE_SOURCE_LAYOUT_INVALID).
 //
-// An unreadable or malformed list is a broken install, not "no pinned files": both readers throw
+// An unreadable or malformed list is a broken install, not "no pinned files": the reader throws
 // ARCH_KNOWLEDGE_UNAVAILABLE so the caller reports an error instead of judging with a different contract.
 import fs from 'node:fs';
-import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../../engine/yaml.mjs';
 
@@ -21,11 +18,6 @@ function unavailable(file, detail) {
   return Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
 }
 
-/** The file stem Next.js keys a pinned file by: `middleware.ts` -> `middleware`, `next-env.d.ts` -> `next-env`. */
-export function pinnedStem(fileName) {
-  return path.basename(fileName).replace(/(?:\.d)?\.[cm]?[jt]sx?$/i, '');
-}
-
 function load(file) {
   if (cache.has(file)) return cache.get(file);
   let rule;
@@ -38,21 +30,7 @@ function load(file) {
   if (!Array.isArray(list) || !list.length || list.some(name => typeof name !== 'string' || !EXACT_NAME.test(name))) {
     throw unavailable(file, 'FE-FOLDER-1 frameworkPinnedRootFiles must be a nonempty list of exact file names.');
   }
-  const files = new Set(list);
-  const stems = new Set(list.map(pinnedStem));
-  const declared = rule.frameworkPinnedRootExports;
-  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) {
-    throw unavailable(file, 'FE-FOLDER-1 frameworkPinnedRootExports must map a pinned file stem to its framework-mandated export names.');
-  }
-  const exports = new Map();
-  for (const [stem, names] of Object.entries(declared)) {
-    if (!stems.has(stem)) throw unavailable(file, `FE-FOLDER-1 frameworkPinnedRootExports names ${stem}, which no frameworkPinnedRootFiles entry pins.`);
-    if (!Array.isArray(names) || !names.length || names.some(name => typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name))) {
-      throw unavailable(file, `FE-FOLDER-1 frameworkPinnedRootExports.${stem} must be a nonempty list of export identifiers.`);
-    }
-    exports.set(stem, new Set(names));
-  }
-  const loaded = { files, exports };
+  const loaded = { files: new Set(list) };
   if (file === FRAMEWORK_PINNED_KNOWLEDGE) cache.set(file, loaded);
   return loaded;
 }
@@ -61,23 +39,3 @@ function load(file) {
 export function frameworkPinnedRootFiles(file = FRAMEWORK_PINNED_KNOWLEDGE) {
   return load(file).files;
 }
-
-/** Map of pinned file stem to the export names the framework mandates there. */
-export function frameworkPinnedRootExports(file = FRAMEWORK_PINNED_KNOWLEDGE) {
-  return load(file).exports;
-}
-
-/**
- * The framework-mandated export names for an absolute source file when it is a pinned file sitting
- * directly in a Next source root (its directory holds an app/ directory), else null.
- */
-export function frameworkMandatedExports(absoluteFile, file = FRAMEWORK_PINNED_KNOWLEDGE) {
-  const { files, exports } = load(file);
-  if (!files.has(path.basename(absoluteFile))) return null;
-  try {
-    if (!fs.statSync(path.join(path.dirname(absoluteFile), 'app')).isDirectory()) return null;
-  } catch {
-    return null;
-  }
-  return exports.get(pinnedStem(absoluteFile)) ?? new Set();
-}

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

@@ -108,13 +108,15 @@ function checkGrammar(config, context) {
   // 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
   // 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;
   const installedFrom = (from) => {
-    for (let dir = from; isInside(config.root, dir); dir = path.dirname(dir)) {
+    for (let dir = from; isInside(installRoot, dir); dir = path.dirname(dir)) {
       const candidate = path.join(dir, 'node_modules', ...grammar.package.split('/'));
       if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
-      if (dir === config.root || path.dirname(dir) === dir) break;
+      if (dir === installRoot || path.dirname(dir) === dir) break;
     }
-    return path.join(config.root, 'node_modules', ...grammar.package.split('/'));
+    return path.join(installRoot, 'node_modules', ...grammar.package.split('/'));
   };
   const consumers = grammar.consumerManifests.map(relative => {
     const root = path.dirname(path.join(config.root, ...relative.split('/')));
@@ -123,7 +125,7 @@ function checkGrammar(config, context) {
       manifest: readJson(path.join(config.root, ...relative.split('/'))) ?? {} };
   });
   const installs = [...new Map(consumers.map(consumer => [consumer.packageRoot, consumer])).values()];
-  const packageRoot = installs[0]?.packageRoot ?? local?.root ?? path.join(config.root, 'node_modules', ...grammar.package.split('/'));
+  const packageRoot = installs[0]?.packageRoot ?? local?.root ?? path.join(installRoot, 'node_modules', ...grammar.package.split('/'));
   const manifestFile = path.join(packageRoot, 'package.json');
   const manifest = readJson(manifestFile);
   const ownerOf = (fileName) => consumers.filter(consumer => isInside(consumer.root, fileName))

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

@@ -41,10 +41,6 @@ export const HFS_RULE_IDS = [
   'HFS_WORK_IN_FE',
 ];
 
-const REQUIRED_COMMON = ['.gitattributes', '.github', '.gitignore', '.husky', 'hfs.json',
-  'eslint.config.mjs', 'package-lock.json', 'package.json', 'README.md',
-  'sonar-project.properties', 'tsconfig.json'];
-const REQUIRED_BACKEND = ['.sops.yaml', '.starcistacks', '.starciwork', 'jest.config.js', 'nest-cli.json', 'src'];
 const NON_NPM_ENTRIES = new Set(['pnpm-lock.yaml', 'pnpm-workspace.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb']);
 const RUNTIME_ROOT_MARKDOWN = new Set(['README.md', 'CONTEXT.md', 'CONTRIBUTING.md', 'CHANGELOG.md', 'THIRD_PARTY_NOTICES.md']);
 const PRODUCT_ROOT_MARKDOWN = new Set(['README.md']);
@@ -57,18 +53,21 @@ const RETIRED_TEST_FOLDER = /^src\/tests\/(?:harness|live|e2e\/live)(?:\/|$)/u;
 const EXTRA_TEST_CONFIG = /(?:^|\/)(?:jest[.-][^/]*(?:config\.[cm]?[jt]s|\.json)|jest-(?:e2e|int|integration|harness)[^/]*)$/u;
 const NODE_ENTRIES_SKIPPED = new Set(['node_modules', '.git']);
 
-/** The slot resolver of a repository: the caller's, else the one its hfs.json declares, else the profile's slots with no app declared. */
+/** The slot resolver of a side folder: the caller's, else the side view its app's hfs.json declares, else the profile's slots with no app declared. */
 function resolverOf(root, profile, given) {
   if (given) return given;
   try { return openHfs({ repoRoot: root }); } catch { /* an invalid hfs.json is HFS_DECLARATION_INVALID's finding, judged elsewhere */ }
-  return createSlotResolver(loadSlotManifest(), { profile, apps: [], optionalSlots: [], connections: [] });
+  return createSlotResolver(loadSlotManifest(), { profile, side: profile, apps: [], optionalSlots: [], connections: [], reads: [] });
 }
 
-/** The first path segment of every slot of the profile that may exist: the repository root entries (contracts/, docs/, src/ ...). */
-function slotRootEntries(resolver) {
-  const roots = new Set(['apps']);
+/**
+ * The first path segment of every slot of the scope that may exist: the root entries of a side (contracts/, docs/, src/ ...) or of
+ * the app (be/, fe/, .github/ ...). `scope` is the profile whose slots count (the app resolver answers for the sides too).
+ */
+function slotRootEntries(resolver, scope) {
+  const roots = new Set(scope === 'app' ? [] : ['apps']);
   for (const slot of resolver.slots()) {
-    if (slot.presence === 'forbidden') continue;
+    if (slot.presence === 'forbidden' || !slot.profiles.includes(scope)) continue;
     for (const variant of braceVariants(slot.path)) {
       const first = variant.split('/')[0];
       if (first && !/[*?<%]/u.test(first)) roots.add(first);
@@ -77,6 +76,11 @@ function slotRootEntries(resolver) {
   return roots;
 }
 
+/** The root entries the scope's required slots name (the first segment of every required path of the scope): hfs.json, be/, .starcistacks/ ... */
+function requiredRootEntries(resolver) {
+  return new Set(resolver.requiredPaths().paths.filter((entry) => !entry.side).map((entry) => entry.path.split('/')[0]));
+}
+
 /** The folders directly below src/tests/ that the be.tests.* slots declare (world, fixtures, integration, e2e, contract). */
 function slotTestChildren(resolver) {
   const children = new Set();
@@ -145,25 +149,28 @@ function fsFiles(root, relative = '') {
   return out;
 }
 
+/** The tree view of a list of tracked paths (posix, root-relative): what the git view answers, for a list already in hand. */
+export function trackedTreeView(tracked) {
+  const files = new Set(tracked);
+  return {
+    source: 'git',
+    top: [...new Set(tracked.map(file => file.split('/')[0]))],
+    children: dir => {
+      const prefix = `${dir}/`;
+      const names = new Set();
+      for (const file of tracked) if (file.startsWith(prefix)) names.add(file.slice(prefix.length).split('/')[0]);
+      return [...names];
+    },
+    hasDir: dir => tracked.some(file => file.startsWith(`${dir}/`)),
+    hasFile: file => files.has(file),
+    files: () => tracked,
+  };
+}
+
 /** Uniform tree view: top entries plus children(dir)/hasDir/hasFile answers over posix relatives. */
 function treeView(root) {
   const tracked = gitPaths(root);
-  if (tracked !== null) {
-    const files = new Set(tracked);
-    return {
-      source: 'git',
-      top: [...new Set(tracked.map(file => file.split('/')[0]))],
-      children: dir => {
-        const prefix = `${dir}/`;
-        const names = new Set();
-        for (const file of tracked) if (file.startsWith(prefix)) names.add(file.slice(prefix.length).split('/')[0]);
-        return [...names];
-      },
-      hasDir: dir => tracked.some(file => file.startsWith(`${dir}/`)),
-      hasFile: file => files.has(file),
-      files: () => tracked,
-    };
-  }
+  if (tracked !== null) return trackedTreeView(tracked);
   return {
     source: 'fs',
     top: fsChildren(root, '.'),
@@ -211,7 +218,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 = 'be' }) {
+export function checkRepoPresentation({ root, runtime = false, tree = treeView(root), profile = 'app' }) {
   const violations = [];
   const finding = (ruleId, entry, message, line = 1) => violations.push({ ruleId, path: entry, line, column: 1, message });
   for (const entry of tree.top) {
@@ -333,7 +340,11 @@ function hooksPathNotRedirected({ root, finding }) {
   return { status: 'checked' };
 }
 
-function e2eInAutomaticGate({ root, tree, backend, finding }) {
+/**
+ * The app root's automatic gates never run integration, e2e or contract: the husky hooks and the root scripts they call, the unit
+ * scripts over the be side's jest configuration (`jestConfig`, app-relative), and the workflows that start on push or pull_request.
+ */
+function e2eInAutomaticGate({ root, tree, jestConfig, finding }) {
   const rule = 'HFS_E2E_IN_AUTOMATIC_GATE';
   let pkg = null;
   try { pkg = JSON.parse(readText(root, 'package.json') ?? ''); } catch { /* the package checks own invalid JSON */ }
@@ -358,18 +369,31 @@ function e2eInAutomaticGate({ root, tree, backend, finding }) {
     if (runsE2e(command)) finding(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)) pending.push(match[1]);
   }
-  // 2. Unit and coverage scripts on a jest repository select the unit project only and exclude src/tests.
-  if (backend && tree.hasFile('jest.config.js')) {
+  // 2. Unit and coverage scripts over the be side's jest configuration select the unit project only and exclude src/tests.
+  if (tree.hasFile(jestConfig)) {
     for (const name of UNIT_RUN_SCRIPTS) {
       const command = scripts[name];
       if (typeof command === 'string' && /\bjest\b/u.test(command) && !/--selectProjects\s+unit\b/u.test(command))
         finding(rule, 'package.json', `Script ${name} runs jest without --selectProjects unit and would run the integration, e2e or contract project.`);
     }
-    const jestConfig = readText(root, 'jest.config.js') ?? '';
-    if (/collectCoverageFrom/u.test(jestConfig) && !/!src\/tests\/(?:\*\*|e2e)/u.test(jestConfig))
-      finding(rule, 'jest.config.js', 'collectCoverageFrom must exclude src/tests/** so no integration, e2e or contract file counts toward coverage.');
+    const jestText = readText(root, jestConfig) ?? '';
+    if (/collectCoverageFrom/u.test(jestText) && !/!src\/tests\/(?:\*\*|e2e)/u.test(jestText))
+      finding(rule, jestConfig, 'collectCoverageFrom must exclude src/tests/** so no integration, e2e or contract file counts toward coverage.');
+  }
+  // 3. A workflow that starts on push or pull_request never runs e2e.
+  for (const file of tree.files().filter(entry => /^\.github\/workflows\/[^/]+\.ya?ml$/u.test(entry))) {
+    const text = readText(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)))
+      finding(rule, file, `${file} runs e2e on push or pull_request. Move the e2e job to its own workflow with on: workflow_dispatch only.`);
   }
-  // 3. A back end's default tsconfig excludes the world, integration, e2e and contract trees.
+}
+
+/** The be side's default tsconfig excludes the world, integration, e2e and contract trees (they are checked by src/tests/tsconfig.json). */
+function testTreesOutOfDefaultProgram({ root, tree, finding }) {
+  const rule = 'HFS_E2E_IN_AUTOMATIC_GATE';
   const tsconfigText = readText(root, 'tsconfig.json');
   let tsconfig = null;
   try { tsconfig = tsconfigText === null ? null : JSON.parse(tsconfigText); } catch { /* the typecheck itself owns parsing */ }
@@ -378,19 +402,10 @@ function e2eInAutomaticGate({ root, tree, backend, finding }) {
     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 (backend && files.some(file => /^src\/tests\/(?:world|integration|e2e|contract)\/.+\.[cm]?tsx?$/u.test(file)) && !excludesTestTrees &&
+    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).');
   }
-  // 4. A workflow that starts on push or pull_request never runs e2e.
-  for (const file of tree.files().filter(entry => /^\.github\/workflows\/[^/]+\.ya?ml$/u.test(entry))) {
-    const text = readText(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)))
-      finding(rule, file, `${file} runs e2e on push or pull_request. Move the e2e job to its own workflow with on: workflow_dispatch only.`);
-  }
 }
 
 export function checkHfs(config) {
@@ -401,29 +416,27 @@ export function checkHfs(config) {
   const tree = treeView(config.root);
   const violations = [];
   const finding = (ruleId, entry, message) => violations.push({ ruleId, path: entry, line: 1, column: 1, message });
-  const resolver = resolverOf(config.root, backend ? 'be' : 'fe', config.hfs);
-  const presentation = checkRepoPresentation({ root: config.root, tree, profile: backend ? 'be' : 'fe' });
-  violations.push(...presentation.violations);
-
-  const allowed = slotRootEntries(resolver);
+  const profile = backend ? 'be' : 'fe';
+  const resolver = resolverOf(config.root, profile, config.hfs);
+  // The README, the hooks, the workflows and the scripts are the app root's (checkAppRoot); a side folder is judged as the old
+  // repository root it stands for, less those.
+  const allowed = slotRootEntries(resolver, profile);
   for (const entry of [...tree.top].sort()) {
     if (NON_NPM_ENTRIES.has(entry) || /\.md$/iu.test(entry)) continue;
     if (frontend && !backend) {
-      if (entry === '.starciwork') { finding('HFS_WORK_IN_FE', entry, 'A frontend repository must not hold a .starciwork tree; Work records live in the backend repository.'); continue; }
-      if (entry === '.starcistacks') { finding('HFS_STACKS_IN_FE', entry, 'A frontend repository must not hold .starcistacks; stack declarations live in the backend repository.'); continue; }
-      if (entry === 'src') { finding('HFS_ROOT_SRC_FORBIDDEN_FE', entry, 'A frontend repository keeps source only under apps/<app>/src; the root src/ tree must move.'); continue; }
+      if (entry === '.starciwork') { finding('HFS_WORK_IN_FE', entry, 'The fe side must not hold a .starciwork tree; Work records live in the app root .starciwork.'); continue; }
+      if (entry === '.starcistacks') { finding('HFS_STACKS_IN_FE', entry, 'The fe side must not hold .starcistacks; stack declarations live in be/.starcistacks.'); continue; }
+      if (entry === 'src') { finding('HFS_ROOT_SRC_FORBIDDEN_FE', entry, 'The fe side keeps source only under apps/<app>/src; the fe/src/ tree must move.'); continue; }
     }
     if (frontend && !backend && (isFeTestPath(entry) || isFeTestPath(`${entry}/x`))) continue;   // a test entry of a front end is FE_NO_TESTS's, the one finding of that path
     if (!allowed.has(entry)) {
-      finding('HFS_ROOT_ENTRY_FORBIDDEN', entry, `Root entry ${entry} is not in the HFS ${backend ? 'backend' : 'frontend'} allowlist.`);
+      finding('HFS_ROOT_ENTRY_FORBIDDEN', entry, `Root entry ${entry} of the ${profile} side is not in the slots of the ${profile} side.`);
     }
   }
 
-  const required = new Set(REQUIRED_COMMON);
-  if (backend) for (const entry of REQUIRED_BACKEND) required.add(entry);
-  for (const entry of [...required].sort()) {
-    if (entry === 'apps' || entry === 'README.md' || entry === '.gitattributes') continue;
-    if (!tree.top.includes(entry)) finding('HFS_ROOT_ENTRY_MISSING', entry, `The ${backend ? 'backend' : 'frontend'} HFS tree requires root entry ${entry}.`);
+  for (const entry of [...requiredRootEntries(resolver)].sort()) {
+    if (entry === 'apps') continue;
+    if (!tree.top.includes(entry)) finding('HFS_ROOT_ENTRY_MISSING', entry, `The ${profile} side requires root entry ${entry}.`);
   }
 
   const apps = tree.children('apps').sort();
@@ -444,8 +457,9 @@ export function checkHfs(config) {
     }
     // next-env.d.ts is generated by Next and commonly ignored by Git; it is not
     // a reliable tracked-tree input.
-    if (frontend) for (const entry of ['package.json', 'next.config.ts', 'tsconfig.json', 'postcss.config.mjs']) {
-      if (!tree.hasFile(`apps/${app}/${entry}`)) missing.push(entry);
+    // A front-end app holds the files its slot requires at its own root (next.config.ts, tsconfig.json, ...; it has no package.json).
+    if (frontend) for (const required of resolver.requiredFiles(`apps/${app}/next.config.ts`).filter(entry => !entry.slice(`apps/${app}/`.length).includes('/'))) {
+      if (!tree.hasFile(required)) missing.push(required.slice(`apps/${app}/`.length));
     }
     if (missing.length) finding('HFS_APP_LAYOUT_INVALID', `apps/${app}`, `Application apps/${app} lacks ${missing.join(', ')} required by the HFS app layout.`);
   }
@@ -481,15 +495,13 @@ export function checkHfs(config) {
       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.`);
   }
 
-  e2eInAutomaticGate({ root: config.root, tree, backend, finding });
-  const hooksPath = hooksPathNotRedirected({ root: config.root, finding });
+  if (backend) testTreesOutOfDefaultProgram({ root: config.root, tree, finding });
 
   return {
     violations,
     coverage: {
       status: 'checked',
       source: tree.source,
-      hooksPath,
       rootEntries: tree.top.length,
       apps,
       ruleIds: [...HFS_RULE_IDS],
@@ -497,6 +509,30 @@ 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
+ * 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);
+  const allowed = slotRootEntries(resolver, 'app');
+  for (const entry of [...tree.top].sort()) {
+    if (NON_NPM_ENTRIES.has(entry) || /\.md$/iu.test(entry)) continue;
+    if (!allowed.has(entry)) finding('HFS_ROOT_ENTRY_FORBIDDEN', entry, `Root entry ${entry} is not in the slots of the app root.`);
+  }
+  for (const entry of [...requiredRootEntries(resolver)].sort()) {
+    if (entry === 'README.md' || entry === '.gitattributes') continue;   // checkRepoPresentation reports these two
+    if (!tree.top.includes(entry)) finding('HFS_ROOT_ENTRY_MISSING', entry, `The app root requires root entry ${entry}.`);
+  }
+  const jestConfig = resolver.sides ? `be/${[...braceVariants(resolver.slot('be.tool-config').path)].find(file => file.startsWith('jest.config.'))}` : null;
+  e2eInAutomaticGate({ root, tree, jestConfig, finding });
+  const hooksPath = hooksPathNotRedirected({ root, finding });
+  return { violations, coverage: { status: 'checked', source: tree.source, hooksPath, rootEntries: tree.top.length } };
+}
+
 /** Keep tree findings visible even when the TypeScript architecture config is invalid. */
 export function checkHfsWithoutConfig(repositoryRoot) {
   let root;
@@ -505,9 +541,11 @@ export function checkHfsWithoutConfig(repositoryRoot) {
   }
   let kinds = [];
   try {
-    const authored = JSON.parse(fs.readFileSync(path.resolve(root, 'hfs.json'), 'utf8'));
-    if (authored.profile === 'be') kinds = ['backend'];
-    else if (authored.profile === 'fe') kinds = ['frontend'];
+    const opened = openHfs({ repoRoot: root });
+    // The app root is judged by checkAppRoot; a side folder by its side's tree check.
+    if (opened.repo.profile === 'app') return checkAppRoot({ root, resolver: opened });
+    if (opened.repo.profile === 'be') kinds = ['backend'];
+    else if (opened.repo.profile === 'fe') kinds = ['frontend'];
   } catch { /* A malformed hfs.json remains an HFS_DECLARATION_INVALID error. */ }
   if (!kinds.length) {
     try {

package/runtime/scripts/checks/architecture/next-data.mjs

@@ -37,7 +37,8 @@ function relativeSource(repository, value, label) {
 }
 
 function parseContract(config) {
-  const manifest = JSON.parse(fs.readFileSync(path.join(config.root, 'package.json'), 'utf8'));
+  // The contract is declared in the app's one package.json (the app root; config.root is the fe side folder).
+  const manifest = JSON.parse(fs.readFileSync(path.join(config.packageRoot ?? config.root, 'package.json'), 'utf8'));
   const next = manifest?.starci?.codePatterns?.next;
   const value = next?.dataLifecycle;
   if (value === undefined) return null;
@@ -711,7 +712,7 @@ export function checkFrontendDataLifecycle(config, context) {
     details: ['package.json#starci.codePatterns.next.dataLifecycle is required when production source selects SWR', ...references.unsupported] } };
   reasons.push(...references.unsupported);
   let installed;
-  try { installed = installedSWR(config.root); } catch (error) {
+  try { installed = installedSWR(config.packageRoot ?? config.root); } catch (error) {
     return { violations, coverage: { status: 'unavailable', ruleIds, details: [String(error.message ?? error)] } };
   }
   if (installed.major !== contract.swr.major) reasons.push(`installed swr ${installed.version} does not match declared major ${contract.swr.major}`);

package/runtime/scripts/checks/architecture/registration.mjs

@@ -115,7 +115,7 @@ function frameworkTargets(config, context, checker, localFiles) {
 
 function classToken(ts, checker, node, localFiles) {
   const symbol = valueSymbol(ts, checker, node);
-  const declarations = symbol?.getDeclarations?.().filter(declaration => ts.isClassDeclaration(declaration)) ?? [];
+  const declarations = (symbol?.getDeclarations?.() ?? []).filter(declaration => ts.isClassDeclaration(declaration)) ?? [];
   const local = declarations.filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName)));
   const keys = [...new Set(local.map(declaration => `${canonical(declaration.getSourceFile().fileName)}#${declaration.getStart(declaration.getSourceFile())}`))];
   return { key: keys.length === 1 ? keys[0] : null, external: declarations.length > 0 && local.length === 0 };