@starci/hfs 2.0.2 → 4.0.0

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, '.'),
@@ -189,7 +196,7 @@ 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:check', 'build', 'test'];
+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();
@@ -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/index.mjs

@@ -15,7 +15,6 @@ import { checkTiers, TIER_RULE_IDS } from './tiers.mjs';
 import { checkReachability, REACHABILITY_RULE_IDS } from './reachability.mjs';
 import { checkDeadExports, DEAD_EXPORT_RULE_IDS } from './dead-exports.mjs';
 import { checkRequiredFiles, REQUIRED_FILE_RULE_IDS } from './required-files.mjs';
-import { checkSizeGrowth, SIZE_GROWTH_RULE_IDS } from './size-growth.mjs';
 import { checkClones, CLONE_RULE_IDS } from './clones.mjs';
 import { checkSymbols, SYMBOL_RULE_IDS } from './symbols.mjs';
 import { checkConnectionMap, CONNECTION_RULE_IDS } from './connection-map.mjs';
@@ -43,6 +42,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 { LINT_CODES, onLintSurface } from './surface.mjs';
 
 export { REGISTRATION_RULE_IDS, SWR_DATA_RULE_IDS };
 
@@ -138,13 +138,12 @@ export const ERROR_RULE_IDS = Object.freeze([
 ]);
 
 const machineIds = () => [
-  ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS, ...DEAD_EXPORT_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...SIZE_GROWTH_RULE_IDS, ...CLONE_RULE_IDS, ...SYMBOL_RULE_IDS,
+  ...TIER_RULE_IDS, ...REACHABILITY_RULE_IDS, ...DEAD_EXPORT_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...CLONE_RULE_IDS, ...SYMBOL_RULE_IDS,
   ...Object.values(BACKEND_MACHINE).flatMap(([, ids]) => ids), ...Object.values(FRONTEND_MACHINE).flatMap(([, ids]) => ids),
 ];
 /**
- * The rules only the HFS machine emits: the tier, reachability, dead-export, required-file, size, clone and symbol checks and the
- * backend composition and data machine and frontend repository machine. A rule id an ordinary check also emits (the composition
- * spec and the app-composition check both report BE_APP_COMPOSITION_ONLY) is not here. A spec about another rule judges its own
+ * The rules only the HFS machine emits: the tier, reachability, dead-export, required-file, clone and symbol checks and the
+ * backend composition and data machine and frontend repository machine. A spec about another rule judges its own
  * report without these (they have their own specs); every one of them is in ARCHITECTURE_RULE_IDS.
  */
 export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
@@ -156,7 +155,7 @@ export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
 /** Every code the machine can emit, derived from the rule id lists of its checks (`hfs 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, ...SIZE_GROWTH_RULE_IDS, ...CLONE_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS,
+  ...DEAD_EXPORT_RULE_IDS, ...DOC_LANGUAGE_RULE_IDS, ...REQUIRED_FILE_RULE_IDS, ...CLONE_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS,
   ...REGISTRATION_RULE_IDS, ...SWR_DATA_RULE_IDS, ...SYMBOL_RULE_IDS, SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID, PUBLIC_CONTRACT_RULE_ID,
   READONLY_BOUNDARY_RULE_ID, ...ERROR_RULE_IDS, ...CONFIG_UNREAD_RULE_IDS, ...Object.values(BACKEND_MACHINE).flatMap(([, ids]) => ids), ...Object.values(FRONTEND_MACHINE).flatMap(([, ids]) => ids),
 ])].sort());
@@ -169,7 +168,8 @@ function stable(items) {
  * Check a target repository. injectedTypeScript exists only for hermetic rule fixtures. `fast` leaves out the checks
  * that read the whole repository to answer (clones, dead exports, repository-wide symbols); the pre-push check of the changed owners uses it.
  */
-export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths = [], base, fast = false, hfs: openedHfs } = {}) {
+export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths = [], base, fast = false, hfs: openedHfs, surface = 'all' } = {}) {
+  if (!['all', 'lint', 'check'].includes(surface)) throw new Error(`unknown surface ${surface}`);
   let config;
   try {
     config = loadArchitectureConfig(repositoryRoot, { hfs: openedHfs });
@@ -233,24 +233,30 @@ export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths =
   }
   // HFS machine: the slot-driven graph checks read the whole program, also when the caller asked for one path.
   const hfsContext = paths.length ? buildTypeScriptContext(config, injectedTypeScript) : context;
-  const hfsChecks = { tiers: null, reachability: null, deadExports: null, requiredFiles: null, sizeGrowth: null, clones: null, symbols: null, docLanguage: null };
+  const hfsChecks = { tiers: null, reachability: null, deadExports: null, requiredFiles: null, clones: null, symbols: null, docLanguage: null };
   if (hfsContext.program) {
     const graph = buildHfsGraph(config, hfsContext);
     const input = { config, context: hfsContext, graph, base };
     const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
-      requiredFiles: () => checkRequiredFiles(input), sizeGrowth: () => checkSizeGrowth(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
+      requiredFiles: () => checkRequiredFiles(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
     if (graph.profile === 'be') for (const [name, [check]] of Object.entries(BACKEND_MACHINE)) runs[name] = () => check(input);
     if (graph.profile === 'fe') for (const [name, [check]] of Object.entries(FRONTEND_MACHINE)) runs[name] = () => check(input);
     if (fast) { delete runs.deadExports; delete runs.clones; delete runs.symbols; }
     for (const [name, run] of Object.entries(runs)) {
       const result = run();
-      violations.push(...result.violations);
+      violations.push(...result.violations.map(violation => ({ ...violation, check: name })));
       hfsChecks[name] = result.coverage;
     }
   }
   const inScope = item => !paths.length || (item.path && paths.some(prefix => sameOrUnder(item.path, prefix.replace(/\/$/, ''))));
-  const errors = stable(context.errors.filter(item => item.ruleId.startsWith('ARCH_TSCONFIG_') || !item.path || inScope(item)));
-  const scopedViolations = stable(violations.filter(inScope));
+  // Two findings travel as context errors (package boundary edges); they are obligations of the lint surface like any other finding.
+  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.
+  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));
   const sourceFiles = new Set(context.files.map(file => canonical(file.fileName)));
   const missingOwnerEntries = config.owners?.filter(owner => !sourceFiles.has(canonical(path.resolve(config.root, ...owner.entry.split('/'))))) ?? [];
   const coverage = {
@@ -282,7 +288,6 @@ export function checkArchitecture({ repositoryRoot, injectedTypeScript, paths =
     ...(hfsChecks.reachability?.status === 'checked' ? REACHABILITY_RULE_IDS : []),
     ...(hfsChecks.deadExports?.status === 'checked' ? DEAD_EXPORT_RULE_IDS : []),
     ...(hfsChecks.requiredFiles?.status === 'checked' ? REQUIRED_FILE_RULE_IDS : []),
-    ...(hfsChecks.sizeGrowth?.status === 'checked' ? SIZE_GROWTH_RULE_IDS : []),
     ...(hfsChecks.clones?.status === 'checked' ? CLONE_RULE_IDS : []),
     ...(hfsChecks.symbols?.status === 'checked' ? SYMBOL_RULE_IDS : []),
     ...(hfsChecks.docLanguage?.status === 'checked' ? DOC_LANGUAGE_RULE_IDS : []),

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/owners.mjs

@@ -1,14 +1,20 @@
 import path from 'node:path';
 import { canonical, isInside } from './config.mjs';
-import { relativePath, sourceLocation } from './typescript.mjs';
+import { relativePath, sourceLocation, workspaceExportSources } from './typescript.mjs';
 
 function absolute(root, relative) {
   return canonical(path.resolve(root, ...relative.split('/')));
 }
 
-function ownerDeclarations(config) {
-  return config.owners.map(owner => ({ ...owner, root: absolute(config.root, owner.root), entry: absolute(config.root, owner.entry) }))
-    .sort((a, b) => b.root.length - a.root.length);
+/** The owner's public entries: its declared entry, plus every source file its package.json `exports` maps when the owner is a workspace package. */
+function ownerDeclarations(config, context) {
+  return config.owners.map(owner => {
+    const root = absolute(config.root, owner.root);
+    const entry = absolute(config.root, owner.entry);
+    const workspace = context.workspaces?.find(item => item.root === root);
+    const entries = new Set([entry, ...(workspace ? workspaceExportSources(context.ts, workspace) : [])]);
+    return { ...owner, root, entry, entries };
+  }).sort((a, b) => b.root.length - a.root.length);
 }
 
 function ownerOf(owners, file) {
@@ -24,7 +30,7 @@ function privateOwnerChain(context, owners, edge) {
     if (visited.has(current.file)) continue;
     visited.add(current.file);
     const owner = ownerOf(owners, current.file);
-    if (owner && sourceOwner?.id !== owner.id) return current.file === owner.entry ? null : { owner, chain: current.chain };
+    if (owner && sourceOwner?.id !== owner.id) return owner.entries.has(current.file) ? null : { owner, chain: current.chain };
     for (const candidate of context.edges.get(current.file) ?? []) if (candidate.reexport) {
       queue.push({ file: candidate.to, chain: [...current.chain, candidate.to] });
     }
@@ -46,7 +52,7 @@ function arrangesSchema(config, from, to) {
 /** Enforce explicit same-source owner entries without constraining imports inside one owner. */
 export function checkOwners(config, context) {
   if (!config.owners?.length) return [];
-  const owners = ownerDeclarations(config);
+  const owners = ownerDeclarations(config, context);
   const violations = [];
   const sourceFiles = new Map(context.files.map(file => [canonical(file.fileName), file]));
   for (const owner of owners) {

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 };

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

@@ -0,0 +1,91 @@
+/**
+ * The lint surface: which architecture-machine findings an ESLint rule judges instead of `hfs check`.
+ * Single source of truth. Each enforcer id is the rules.yaml enforcer; `codes` are the exact violation.ruleId strings its
+ * check file emits on source files. plugins: 'be' = back-end profile repos, 'fe' = front-end profile, graph checks run for both.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BE = ['be'];
+const FE = ['fe'];
+const BOTH = ['be', 'fe'];
+
+// `via` names the machine check (the key of its run in index.mjs) when two enforcers share a code; `origin: 'repo'` marks a finding of the
+// slot manifest's per-path judgement (hfs-path-findings.mjs) instead of the machine. A finding reaches exactly one rule.
+const enforcer = (id, plugins, codes, description, extra = {}) => Object.freeze({ id, plugins: Object.freeze(plugins), codes: Object.freeze(codes), description, ...extra });
+
+export const LINT_ENFORCERS = Object.freeze([
+  enforcer('duplicate-code', BOTH, ['HFS_DUPLICATE_CODE'], 'A block of production code never repeats elsewhere in the owner graph.'),
+  enforcer('duplicate-symbol', BOTH, ['HFS_DUPLICATE_SYMBOL'], 'A symbol name is declared once across the production source.'),
+  enforcer('alias-reexport', BOTH, ['HFS_ALIAS_REEXPORT'], 'An owner entry re-exports a symbol under its own name, never through a const alias.'),
+  // cross-app-duplicate emits only FE_CROSS_APP_DUPLICATE today; HFS_DUPLICATE_CODE is named in its comment only.
+  enforcer('cross-app-duplicate', FE, ['FE_CROSS_APP_DUPLICATE'], 'A file is never copied between apps; shared code lives in a package.'),
+  enforcer('dead-exports', BOTH, ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'], 'Every owner export and every production file is reached by a root.'),
+  enforcer('tier-direction', BOTH, ['BE_TIER_DIRECTION', 'FE_TIER_DIRECTION'], 'An import goes only to a tier the slot matrix allows.'),
+  enforcer('owner-cycle', BOTH, ['ARCH_OWNER_CYCLE'], 'Owners never import each other in a cycle.'),
+  enforcer('feature-imports-feature', BE, ['BE_FEATURE_IMPORTS_FEATURE'], 'A feature never imports another feature.'),
+  enforcer('app-isolation', FE, ['FE_APP_ISOLATION'], 'An app never imports another app.'),
+  enforcer('feature-layout', BE, ['BE_FEATURE_LAYOUT_INVALID'], 'A feature file sits in the folder its role names.'),
+  enforcer('application-never-imports-transport', BE, ['BE_APPLICATION_IMPORTS_TRANSPORT', 'BE_APPLICATION_TRANSPORT_FRAMEWORK'], 'Application code never imports transport code, directly or through a chain.'),
+  enforcer('owner-export-bypass', BOTH, ['ARCH_OWNER_EXPORT_BYPASS', 'ARCH_OWNER_EXPORT_STAR'], 'Another owner is imported only through its index entry, and an entry never uses export star.'),
+  enforcer('feature-not-composed', BE, ['BE_FEATURE_NOT_COMPOSED'], 'Every feature owner is composed into an app.'),
+  enforcer('owner-reachable', FE, ['FE_OWNER_REACHABLE', 'FE_HREF_RESOLVES'], 'Every owner is mounted by a route and every href resolves to a route.'),
+  enforcer('app-composition-only', BE, ['BE_APP_COMPOSITION_ONLY', 'BE_APP_BUSINESS_ROLE'], 'An app only composes modules and holds no business role.'),
+  enforcer('entrypoint-only-in-apps', BE, ['BE_ENTRYPOINT_ONLY_IN_APPS'], 'NestFactory and bootstrap live only in an app main file.'),
+  enforcer('schema-owner', BE, ['BE_SCHEMA_OWNER'], 'Each entity array is registered by one owner across all apps.'),
+  enforcer('error-code-unique', BE, ['BE_ERROR_HOME'], 'An error code is declared once in the repository.'),
+  enforcer('error-masked', BE, ['BE_ERROR_MASKED'], 'Every app wires the error filter that masks internal errors.'),
+  enforcer('default-deny-app-guard', BE, ['BE_DEFAULT_DENY'], 'Every app registers the default-deny guard before any other guard.'),
+  // BE_MODULE_SHAPE is emitted by both register-once and module-per-transport.
+  enforcer('register-once', BE, ['BE_MODULE_SHAPE'], 'A module is registered once and imported by one module.', { via: 'registerOnce' }),
+  enforcer('module-per-transport', BE, ['BE_MODULE_SHAPE'], 'An app imports transport modules only.', { via: 'modulePerTransport' }),
+  enforcer('module-registration', BE, ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'], 'Every handler is registered by a module and no provider is registered twice.'),
+  enforcer('background-unowned', BE, ['BE_BACKGROUND_UNOWNED'], 'Every background job is reachable from a worker app.'),
+  enforcer('test-world-files', BE, ['BE_TEST_TOPOLOGY'], 'The test world files match the stack declaration.'),
+  enforcer('unit-spec-providers', BE, ['BE_SPEC_QUALITY'], 'A unit spec provides exactly the dependencies its service constructor takes.'),
+  enforcer('transport-owner', FE, ['FE_TRANSPORT_OWNER'], 'One client and one outcome type own the transport of the repository.'),
+  enforcer('swr-data-lifecycle', FE, ['FE_SWR_KEY_IDENTITY', 'FE_SWR_MUTATION_RESOURCE_IDENTITY'], 'SWR keys and mutations share one resource identity.'),
+  enforcer('route-files-thin', FE, ['FE_ROUTE_FILES_THIN'], 'A route file only mounts one feature owner.'),
+  enforcer('route-adapter', FE, ['FE_ROUTE_ONE_PAGE', 'FE_ROUTE_DRAWING_DECISION', 'FE_ROUTE_CLIENT_BOUNDARY', 'FE_ROUTE_CLIENT_HOOK', 'FE_ROUTE_DEFAULT_EXPORT'], 'A page route is a server adapter that mounts one pages-tier component.'),
+  enforcer('client-reaches-server', FE, ['FE_CLIENT_REACHES_SERVER'], 'Client code never reaches server-only code through any import chain.'),
+  enforcer('hooks-are-hooks', FE, ['FE_HOOKS_ARE_HOOKS'], 'A hooks folder holds hooks only, one shared file per domain.'),
+  enforcer('hook-location', FE, ['FE_CUSTOM_HOOK_LOCATION', 'FE_BLOCK_PRODUCT_HOOK_DEFINITION', 'FE_COMPONENT_DEEP_HOOK_IMPORT'], 'A custom hook is defined in the hooks folder and imported through its entry.'),
+  enforcer('connection-map', BE, ['BE_CONNECTION_DUPLICATE'], 'Each database connection is declared once and matches the connection map.'),
+  enforcer('injection-token-exported', BE, ['BE_RAW_INJECT'], 'An injection token is exported by its owner and never injected raw.'),
+  enforcer('sql-owner', BE, ['BE_SQL_TABLE_OWNER'], 'A SQL table is touched only by the owner of its entity.'),
+  enforcer('readonly-boundary', BE, ['BE_READONLY_BOUNDARY'], 'Messages and injected classes crossing a boundary are readonly.'),
+  enforcer('source-names', BE, ['BE_SOURCE_FORM'], 'Names and forms inside a source file follow its role.'),
+  enforcer('public-contract-form', BE, ['BE_PUBLIC_CONTRACT_FORM'], 'A public signature is typed by a named contract, never inline or untyped.'),
+  enforcer('frontend-source-layout', FE, ['FE_SOURCE_LAYOUT_INVALID'], 'A front-end source file sits in a tier folder.'),
+  enforcer('component-purity', FE, ['FE_COMPONENT_WORLD_OWNERSHIP', 'FE_WORLD_OWNER_RENDER_BOUNDARY', 'FE_CONNECTED_BLOCK_RENDER_PAIR', 'FE_PURE_REACHES_DATA', 'FE_PURE_WORLD_HOOK', 'FE_PURE_WORLD_IMPORT'], 'A pure component reaches no data or world state; its connected entry owns them.'),
+  enforcer('grammar-entry', FE, ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'], 'Vendor grammar is reached only through its owner entry.'),
+  enforcer('i18n-keys', FE, ['FE_I18N_KEYS'], 'Translation keys read by source and keys held by catalogs agree both ways.'),
+  // The per-path judgements of the slot manifest (scripts/lib/hfs-path-findings.mjs), on a tracked TypeScript file.
+  enforcer('slot-undeclared', BOTH, ['HFS_SLOT_UNDECLARED', 'HFS_SLOT_AMBIGUOUS', 'HFS_SLOT_NOT_ENABLED'], 'A TypeScript file is owned by exactly one slot of the repository.', { origin: 'repo' }),
+  enforcer('source-suffix', BE, ['BE_SOURCE_FORM'], 'A source file name is index.ts, main.ts, a migration or <kebab-name>.<suffix>.ts with a suffix of the closed list.', { origin: 'repo' }),
+  enforcer('spec-placement', BE, ['BE_SPEC_PLACEMENT'], 'A spec file lives in one of the four test layers and nowhere else.', { origin: 'repo' }),
+  // The two below are emitted into context.errors today, not into violations.
+  enforcer('package-imports-app', BOTH, ['ARCH_PACKAGE_IMPORTS_APP'], 'A package never imports an app.'),
+  enforcer('package-export-bypass', BOTH, ['ARCH_PACKAGE_EXPORT_BYPASS'], 'A package is imported only through its declared exports.'),
+]);
+
+export const LINT_CODES = new Set(LINT_ENFORCERS.flatMap(e => e.codes));
+
+export const TS_SOURCE = /\.(?:[cm]?tsx?)$/;
+
+/** True when a finding sits on an existing TypeScript file of the repository: the only findings an editor can show on a line. */
+export function attachesToSource(repositoryRoot, violation) {
+  const file = violation?.path;
+  if (typeof file !== 'string' || !TS_SOURCE.test(file)) return false;
+  return fs.existsSync(path.join(repositoryRoot, ...file.split('/')));
+}
+
+/** The finding's code: a machine violation spells it `ruleId`, a repository finding `code`. */
+export const codeOf = (finding) => finding?.ruleId ?? finding?.code;
+
+/** Whether `finding` (with its origin and check tags) belongs to `enforcer`. */
+export const belongsTo = (enforcer, finding) => enforcer.codes.includes(codeOf(finding))
+  && (finding.origin ?? 'machine') === (enforcer.origin ?? 'machine') && (enforcer.via === undefined || finding.check === enforcer.via);
+
+/** True when some lint rule owns the finding and it sits on an existing TypeScript file: it is an ESLint report, not a `hfs check` finding. */
+export const onLintSurface = (repositoryRoot, finding) => LINT_ENFORCERS.some(enforcer => belongsTo(enforcer, finding)) && attachesToSource(repositoryRoot, finding);

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

@@ -8,7 +8,9 @@
  *                         exported `const Y = X` / `const Y = X.y` (a bare identifier or member that resolves to a function,
  *                         class, const or enum of the repository), `type Y = X` and `interface Y extends X {}` (no body, no
  *                         type arguments, no type parameters): a second name for one declaration. Rename the declaration,
- *                         or import it by its name.
+ *                         or import it by its name. A route file (slot fe.route) binding a declaration to a name Next.js
+ *                         requires of a route segment (generateMetadata, generateStaticParams, ...) is not a second name: the
+ *                         framework fixes that name, so no rename can remove it.
  * Specs and tests are not in the graph. The public entry of an owner is found the way dead-exports.mjs finds it.
  */
 import { canonical } from './config.mjs';
@@ -145,14 +147,23 @@ function declarationAliases(ts, checker, graph, statement) {
   return found;
 }
 
+/** The names Next.js reads from a route segment file (layout, page, route, ...): the framework fixes them. */
+const NEXT_SEGMENT_EXPORTS = new Set([
+  'generateMetadata', 'metadata', 'generateViewport', 'viewport', 'generateStaticParams', 'generateImageMetadata', 'generateSitemaps',
+  'dynamic', 'dynamicParams', 'revalidate', 'fetchCache', 'runtime', 'preferredRegion', 'maxDuration',
+]);
+const ROUTE_SLOT = 'fe.route';
+
 function aliasReexports({ context, graph }) {
   const kind = context.ts.SyntaxKind;
   const violations = [];
   for (const [rel, node] of graph.files) {
+    const frameworkName = name => node.slot === ROUTE_SLOT && NEXT_SEGMENT_EXPORTS.has(name);
     const point = target => node.sourceFile.getLineAndCharacterOfPosition(target.getStart(node.sourceFile));
     const checker = context.checkerFor(node.abs);
     for (const statement of node.sourceFile.statements) {
       for (const alias of declarationAliases(context.ts, checker, graph, statement)) {
+        if (frameworkName(alias.name)) continue;
         const at = point(alias.node);
         violations.push({
           ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1, name: alias.name, aliasOf: alias.of,
@@ -170,7 +181,7 @@ function aliasReexports({ context, graph }) {
         continue;
       }
       for (const element of clause.elements) {
-        if (!element.propertyName || element.propertyName.text === element.name.text) continue;
+        if (!element.propertyName || element.propertyName.text === element.name.text || frameworkName(element.name.text)) continue;
         const at = point(element);
         violations.push({
           ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1,