@starci/hfs 3.0.0 → 4.0.0

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

@@ -5,6 +5,7 @@ import { canonical, isInside, slash } from './config.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
+import { locateDeclaration } from '../../lib/hfs-slots.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;
@@ -16,14 +17,14 @@ export const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.outpu
 export function isGeneratedPath(root, fileName) {
   return slash(path.relative(root, fileName)).split('/').slice(0, -1).some(segment => GENERATED_SEGMENTS.has(segment));
 }
-// A `<tool>.config.*` or `<tool>.setup.*` module beside a package manifest (next.config.ts,
-// postcss.config.mjs) is build tooling a broad `**/*.ts` include pulls in; a `*.config.ts` inside a source tree
-// (src/config/database.config.ts) has no manifest beside it and stays source. The architecture program still
-// reads tooling modules (a profile may declare one as source); check-scoped-lint does not make one a canon
-// lint subject unless the profile's sourceGlobs name it.
+// A `<tool>.config.*` or `<tool>.setup.*` module at the root of a project (beside a package manifest or a tsconfig.json:
+// next.config.ts and postcss.config.mjs of an app, which has no package.json of its own) is build tooling a broad `**/*.ts`
+// include pulls in; a `*.config.ts` inside a source tree (src/config/database.config.ts) has neither beside it and stays source.
+// The architecture program still reads tooling modules (a profile may declare one as source); the lint (hfs lint) judges one only
+// through the repository's own eslint.config.
 const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
 export function isToolingModule(fileName) {
-  return TOOLING_MODULE.test(path.basename(fileName)) && fs.existsSync(path.join(path.dirname(fileName), 'package.json'));
+  return TOOLING_MODULE.test(path.basename(fileName)) && ['package.json', 'tsconfig.json'].some((manifest) => fs.existsSync(path.join(path.dirname(fileName), manifest)));
 }
 
 function diagnosticMessage(ts, diagnostic) {
@@ -48,9 +49,12 @@ function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_IN
   };
 }
 
-/** Load TypeScript through the target package boundary, never through StarCi's own dependency graph. */
+/**
+ * Load TypeScript through the target package boundary, never through StarCi's own dependency graph. A side folder of an app has no
+ * package.json of its own: the app root's one manifest is the boundary its TypeScript is installed under.
+ */
 export function loadTargetTypeScript(repositoryRoot) {
-  const packageFile = path.join(repositoryRoot, 'package.json');
+  const packageFile = path.join(locateDeclaration(repositoryRoot).appRoot, 'package.json');
   if (!fs.existsSync(packageFile)) throw Error('ARCH_TYPESCRIPT_MISSING: target package.json is required to resolve target-installed TypeScript.');
   const targetRequire = createRequire(packageFile);
   let resolved;
@@ -189,7 +193,8 @@ function workspaceMetadata(config) {
         || backendAppRoots.some(appRoot => isInside(appRoot, root) || isInside(root, appRoot)) };
   };
   const roots = config.workspaces.map(create);
-  const rootPackage = readJson(path.join(config.root, 'package.json'));
+  // A side of an app has no package.json: the app root's one manifest names the package the side's root files belong to.
+  const rootPackage = readJson(path.join(config.packageRoot ?? config.root, 'package.json')) ?? {};
   roots.push({ root: canonical(config.root), relative: '.', name: typeof rootPackage.name === 'string' ? rootPackage.name : null, exports: rootPackage.exports,
     app: config.frontend.routes.some(item => isInside(config.root, path.join(config.root, ...item.split('/')))) || config.kinds.includes('backend') });
   return roots.sort((a, b) => b.root.length - a.root.length);
@@ -415,20 +420,29 @@ function typeScriptContext(config, loaded, paths) {
       .map(item => compilerError(ts, config.root, item, relative, 'ARCH_SYNTAX_INVALID')));
     projects.push({ relative, program, options: parsed.options });
   }
-  const fileMap = new Map();
-  const checkerByFile = new Map();
   const occurrences = new Map();
+  const sourceIn = new Map();
   for (const project of projects) {
     for (const sourceFile of project.program.getSourceFiles().filter(file => isProductionSource(config.root, file))) {
       const name = canonical(sourceFile.fileName);
-      if (!fileMap.has(name)) {
-        fileMap.set(name, sourceFile);
-        checkerByFile.set(name, project.program.getTypeChecker());
-      }
       if (!occurrences.has(name)) occurrences.set(name, []);
       occurrences.get(name).push(project);
+      sourceIn.set(`${project.relative}|${name}`, sourceFile);
     }
   }
+  // The deepest project directory holding a file owns it: its source file, its checker and its resolution. A side or repository
+  // root tsconfig without paths must not shadow the app project whose aliases (`@/*`) the file actually uses.
+  const owningProject = (candidates, file) => candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), file))
+    .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+  const fileMap = new Map();
+  const checkerByFile = new Map();
+  const ownerByFile = new Map();
+  for (const [name, candidates] of occurrences) {
+    const owner = owningProject(candidates, name);
+    ownerByFile.set(name, owner);
+    fileMap.set(name, sourceIn.get(`${owner.relative}|${name}`));
+    checkerByFile.set(name, owner.program.getTypeChecker());
+  }
   const files = [...fileMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, file]) => file);
   const edges = new Map([...fileMap.keys()].map(file => [file, []]));
   for (const [file, sourceFile] of fileMap) {
@@ -441,11 +455,7 @@ function typeScriptContext(config, loaded, paths) {
   const workspaceNames = new Set(workspaces.map(item => item.name).filter(Boolean));
   for (const [from, sourceFile] of fileMap) {
     const owningWorkspace = workspaceOf(workspaces, from);
-    const candidates = occurrences.get(from) ?? [];
-    // The deepest project directory holding the file owns its resolution: a root tsconfig without paths must not
-    // shadow the app project whose aliases the file actually uses.
-    const project = candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), from))
-      .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+    const project = ownerByFile.get(from);
     if (!project) continue;
     const references = moduleReferences(ts, sourceFile, project.program.getTypeChecker());
     for (const item of references.unproven) errors.push({
@@ -485,6 +495,21 @@ function typeScriptContext(config, loaded, paths) {
       // project is then the boundary it always was.
       const reviewable = isInside(config.root, actualTarget)
         || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
+      // A side of an app (config.root is be/ or fe/) imports nothing of the app outside itself: the root holds no source, the other
+      // side is another program, and a declared read (sides.fe.reads, be/contracts/) is codegen input, never an import.
+      const crossesSide = config.packageRoot !== undefined && config.packageRoot !== config.root
+        && isInside(config.packageRoot, actualTarget) && !isInside(config.root, actualTarget) && !slash(actualTarget).includes('/node_modules/');
+      if (internal && crossesSide) {
+        errors.push({
+          ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
+          project: project.relative,
+          path: relativePath(config.root, sourceFile.fileName),
+          ...sourceLocation(sourceFile, reference.node),
+          specifier: reference.specifier,
+          message: `Internal import ${reference.specifier} leaves the ${path.basename(config.root)} side for ${slash(path.relative(config.packageRoot, actualTarget))}; nothing crosses the sides of an app.`,
+        });
+        continue;
+      }
       if (internal && !reviewable) {
         errors.push({
           ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',

package/runtime/scripts/checks/typescript-programs.mjs

@@ -4,8 +4,8 @@ import path from 'node:path';
 
 // One TypeScript program per (compiler, root names, compiler options, project references) inside a program run, and
 // one value per (kind, compiler, input) for what callers derive from those programs (the architecture context).
-// check-scoped-lint opens one run around its architecture check and its script checkers and releases it before
-// ESLint and the base measurement, so nothing built here outlives the run that built it. Outside a run every call
+// A caller (canon-scan's architecture machine, a script checker) opens one run around its work and releases it after,
+// so nothing built here outlives the run that built it. Outside a run every call
 // builds afresh.
 const runs = new AsyncLocalStorage();
 

package/runtime/scripts/lib/hfs-check.mjs

@@ -1,9 +1,9 @@
-// hfs-check.mjs - the HFS repository check, behind `hfs check | init | explain` (packages/hfs) and reusable by any
-// runtime check. It reads three things and nothing else: the repository's hfs.json, the slot manifest
+// hfs-check.mjs - the HFS app check, behind `hfs check | explain` (packages/hfs) and reusable by any
+// runtime check. It reads three things and nothing else: the app's hfs.json, the slot manifest
 // (knowledge/hfs/slots.yaml through scripts/lib/hfs-slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
 // writes to the repository it inspects.
 //
-// checkRepo() answers, for the tracked paths of one repository (git ls-files):
+// checkRepo() answers, for the tracked paths of one app (git ls-files), per scope (the app root and each side folder):
 //   HFS_SLOT_UNDECLARED              a tracked path no slot owns (the nearest slot is named)
 //   HFS_SLOT_NOT_ENABLED          a tracked path in an opt-in slot the repository did not declare
 //   HFS_SLOT_AMBIGUOUS            two slots of equal specificity own the path (a manifest gap, reported not guessed)
@@ -26,6 +26,7 @@
 //   HFS_REPO_LOCAL_CHECK          (R103, hfs-rules/repo-local-checks.mjs) a local eslint rule or plugin, a `check-*` script, a relative import in eslint.config
 //   HFS_LINT_SUPPRESSION_FILE     (R104, hfs-rules/lint-suppression.mjs) an eslint suppressions file, script or option
 //   HFS_PROOF_COMMAND_FILE_MISSING (R105, hfs-rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
+//   HFS_PEER_INTEGRATION_MISSING  (R111, hfs-rules/peer-integrations.mjs) the app root package.json lacks the runtime peer a driver integration needs
 //   FE_WIRE_GENERATED, FE_I18N_PLACEMENT, FE_I18N_CATALOG   (R52, R59, R60, hfs-rules/frontend.mjs) the front-end tree of each app
 //   HFS_GITIGNORE_BLOCK_DRIFT, HFS_SONAR_CONFIG   (R04, R11) produced by packages/hfs/sync/managed.mjs, which renders the templates
 //   HFS_FORMAT                    (R19) produced by packages/hfs/sync/format.mjs, which runs the repository's own prettier
@@ -45,16 +46,16 @@ import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from '../checks/architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { HFS_DECLARATION_FILE, HfsSlotsError, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
+import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
 import { allowsFile } from './hfs-allows.mjs';
-import { isDir } from './fs-kind.mjs';
 import { gitOutput } from './git.mjs';
 import { posixPath } from './path-key.mjs';
 import { readTree, treeFacts, untrackedEntries } from './hfs-tree.mjs';
 import { contractFindings } from './hfs-rules/contract.mjs';
 import { depFindings } from './hfs-rules/deps.mjs';
-import { frontendFindings } from './hfs-rules/frontend.mjs';
+import { appFrontendFindings, frontendFindings } from './hfs-rules/frontend.mjs';
 import { lintSuppressionFindings } from './hfs-rules/lint-suppression.mjs';
+import { peerIntegrationFindings } from './hfs-rules/peer-integrations.mjs';
 import { pipelineFindings } from './hfs-rules/pipeline.mjs';
 import { proofCommandFindings } from './hfs-rules/proof-commands.mjs';
 import { repoLocalCheckFindings } from './hfs-rules/repo-local-checks.mjs';
@@ -62,6 +63,7 @@ import { readJson } from './hfs-rules/read.mjs';
 import { secretFindings } from './hfs-rules/secrets.mjs';
 import { pathFindings } from './hfs-path-findings.mjs';
 import { onLintSurface } from '../checks/architecture/surface.mjs';
+import { checkAppRoot, trackedTreeView } from '../checks/architecture/hfs.mjs';
 import { stacksFindings } from './hfs-rules/stacks.mjs';
 import { testTopologyFindings } from './hfs-rules/test-topology.mjs';
 import { feNoTestsFindings, isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
@@ -69,11 +71,11 @@ import { feNoTestsFindings, isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
 export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
 /**
- * The codes `hfs check` and `hfs init` report when they cannot judge (an unreadable repository, a refused declaration or
- * manifest, an init that cannot proceed): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
+ * The codes `hfs check` reports when it cannot judge (an unreadable repository, a refused declaration or manifest, a missing
+ * formatter): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
  */
 export const REFUSAL_CODES = Object.freeze([
-  'HFS_INIT_EXISTS', 'HFS_INIT_UNDETECTED', 'HFS_REPO_UNREADABLE',
+  'HFS_REPO_UNREADABLE',
   'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING',
 ]);
 /** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
@@ -82,7 +84,7 @@ export const CHECK_CODES = Object.freeze([
   'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
   'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
   'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT',
-  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
+  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
   'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_FORMAT',
   'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
   ...REFUSAL_CODES,
@@ -137,7 +139,8 @@ function pinFindings({ repoRoot, files, profile, pins, only }) {
     let pkg;
     try { pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, file), 'utf8')); } catch { continue; }
     for (const [name, pin] of Object.entries(pins)) {
-      if (pin.side !== 'both' && pin.side !== profile) continue;
+      // The app root's one package.json carries the pins of both sides.
+      if (profile !== APP_SCOPE && pin.side !== 'both' && pin.side !== profile) continue;
       for (const section of DEP_SECTIONS) {
         const spec = pkg[section]?.[name];
         if (spec === undefined) continue;
@@ -211,35 +214,24 @@ function treeFindings({ repoRoot, resolver }) {
   return findings;
 }
 
+/** A side-relative path (or null) as an app-relative one. */
+const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
+
 /**
- * The check of one repository. `declaration` overrides hfs.json (a dry run over a repository that has none); `files`
- * overrides git ls-files (specs). `only` (a list of paths) limits the per-path checks (slot, pin, size) to those paths; the
- * checks of the tree as a whole (required files, minimum instances, empty directories, untracked entries) are not
- * per-path. `tree: false` skips the file-system checks (empty directories, ghosts, untracked); they also do not run
- * over `files`, which is a dry run. `extraFindings` are findings another emitter produced for the same repository (the
- * managed files), judged and counted with this module's own. Returns {ok, profile, apps, manifest, tracked, findings,
- * counts}; a missing or invalid hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never
- * an exception.
+ * The findings of one scope: the app root (profile app; its own files, and the rules of the files only the root holds: the one
+ * package.json and lockfile, CI, hooks, .starciwork) or one side (profile be or fe; the side folder is `repoRoot` and every path is
+ * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
+ * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
  */
-export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all' }) {
-  const why = readWhy(root);
-  let repo;
-  try {
-    repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
-  } catch (error) {
-    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH'].includes(error.code)) throw error;
-    const findings = withWhy([{ code: error.code, level: 'error', path: HFS_DECLARATION_FILE, message: error.message.replace(/^[A-Z_]+: /, ''), problems: error.details.problems }], why);
-    return { ok: false, repoRoot, manifest: manifest.version, profile: null, apps: [], tracked: 0, findings, counts: summarize(findings) };
-  }
-  const resolver = createSlotResolver(manifest, repo);
-  const tracked = files ?? trackedFiles(repoRoot);
-  const trackedSet = new Set(tracked);
-  const present = (p) => (p.endsWith('/') ? tracked.some((f) => f.startsWith(p)) : trackedSet.has(p));
-  const findings = [];
-  const scoped = only ? new Set(only) : null;
+function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped }) {
   const inScope = (file) => !scoped || scoped.has(file);
+  // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
+  const trackedSet = new Set(all);
+  const present = (p) => (p.endsWith('/') ? all.some((f) => f.startsWith(p)) : trackedSet.has(p));
+  const findings = [];
+  const isRoot = repo.profile === APP_SCOPE;
 
-  findings.push(...pathFindings({ files: tracked.filter(inScope), resolver, profile: repo.profile }));
+  findings.push(...pathFindings({ files: files.filter(inScope), resolver, profile: repo.profile }));
 
   const required = resolver.requiredPaths();
   const missing = new Set();
@@ -250,46 +242,104 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
     const app = appOf(p);
     findings.push({ code: 'HFS_SLOT_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${app ? ` (app ${app})` : ''}, which is not tracked` });
   };
-  for (const entry of required.paths) missingFile(entry.slot, entry.path, entry.via);
-  const instances = instancesOf(resolver, tracked);
+  // The app's own required paths; each side reports its own (the resolver of the app lists them too, with their side).
+  for (const entry of required.paths) if (!entry.side) missingFile(entry.slot, entry.path, entry.via);
+  const instances = instancesOf(resolver, files);
   for (const instance of instances) for (const p of requiredOf(resolver.slot(instance.slot), instance)) missingFile(instance.slot, p, 'requires');
-  for (const { slot, min, appKind } of required.minimums) {
-    if (appKind !== undefined) continue;     // an app-kind minimum is checked by requiredPaths (one path set per declared app)
+  for (const { slot, min, appKind, side } of required.minimums) {
+    if (appKind !== undefined || side) continue;     // an app-kind minimum is checked by requiredPaths (one path set per declared app)
     const count = instances.filter((i) => i.slot === slot).length;
     if (count < min) findings.push({ code: 'HFS_MIN_INSTANCES', level: 'error', path: resolver.slot(slot).path, slot, min, count, message: `${slot} needs at least ${min} instance${min === 1 ? '' : 's'} (${resolver.slot(slot).path}), found ${count}` });
   }
 
   const pins = readPins(root);
-  findings.push(...pinFindings({ repoRoot, files: tracked, profile: repo.profile, pins, only: scoped }));
+  findings.push(...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }));
 
-  // The tree checks of the rules that read file content or configuration (hfs-rules/*): whole-repository, cheap, no tool run.
-  const secrets = secretFindings({ repoRoot, files: tracked.filter(inScope), resolver });
-  const declared = declaration === undefined ? readJson(repoRoot, 'hfs.json') : declaration;
+  // The tree checks of the rules that read file content or configuration (hfs-rules/*): whole-scope, cheap, no tool run.
   findings.push(
-    ...secrets,
-    ...depFindings({ repoRoot, files: tracked }),
-    ...pipelineFindings({ repoRoot, files: tracked, pins }),
-    ...contractFindings({ repoRoot, files: tracked, repo, resolver, stacks: declared?.stacks }),
-    ...repoLocalCheckFindings({ repoRoot, files: tracked }),
-    ...lintSuppressionFindings({ repoRoot, files: tracked }),
-    ...(repo.profile === 'be' ? [...stacksFindings({ repoRoot, files: tracked, resolver }), ...testTopologyFindings({ repoRoot, files: tracked }), ...proofCommandFindings({ repoRoot, files: tracked, resolver })] : [...frontendFindings({ repoRoot, files: tracked, repo }), ...feNoTestsFindings({ repoRoot, files: tracked.filter(inScope) })]),
-    ...extraFindings,
+    ...secretFindings({ repoRoot, files: files.filter(inScope), resolver }),
+    ...repoLocalCheckFindings({ repoRoot, files }),
+    ...lintSuppressionFindings({ repoRoot, files }),
   );
+  if (isRoot) {
+    findings.push(
+      ...depFindings({ repoRoot, files: all }),
+      ...peerIntegrationFindings({ repoRoot, files: all }),
+      ...pipelineFindings({ repoRoot, files, pins }),
+      ...testTopologyFindings({ repoRoot, files }),
+      ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),
+      ...appFrontendFindings({ repoRoot, files: all, repo }),
+      // The tree check of the app root the machine runs per side for a side folder: README, root entries, automatic gates, hooks path.
+      ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
+    );
+  } else if (repo.profile === 'be') {
+    findings.push(...contractFindings({ files, repo, resolver }), ...stacksFindings({ repoRoot, files, resolver }), ...testTopologyFindings({ repoRoot, files }));
+  } else {
+    findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter(inScope) }));
+  }
 
-  const soft = resolver.ruleParams().fileLines.soft;
-  for (const file of tracked) {
-    if (!inScope(file) || !SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
-    let lines;
-    try { lines = fs.readFileSync(path.join(repoRoot, file), 'utf8').split('\n').length; } catch { continue; }
-    if (lines > soft) findings.push({ code: 'HFS_SIZE_SOFT_BACKLOG', level: 'info', path: file, lines, soft, message: `${file} has ${lines} lines, above the soft size ${soft}; report only` });
+  if (!isRoot) {
+    const soft = resolver.ruleParams().fileLines.soft;
+    for (const file of files) {
+      if (!inScope(file) || !SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
+      let lines;
+      try { lines = fs.readFileSync(path.join(repoRoot, file), 'utf8').split('\n').length; } catch { continue; }
+      if (lines > soft) findings.push({ code: 'HFS_SIZE_SOFT_BACKLOG', level: 'info', path: file, lines, soft, message: `${file} has ${lines} lines, above the soft size ${soft}; report only` });
+    }
   }
+  return findings;
+}
 
+/**
+ * The check of one app. `repoRoot` is the app root (a side folder is checked as that side alone). `declaration` overrides hfs.json
+ * (a dry run over an app that has none); `files` overrides git ls-files (specs), app-relative. `only` (a list of app-relative paths)
+ * limits the per-path checks (slot, pin, size) to those paths; the checks of the tree as a whole (required files, minimum instances,
+ * empty directories, untracked entries) are not per-path. `tree: false` skips the file-system checks (empty directories, ghosts,
+ * untracked); they also do not run over `files`, which is a dry run. `extraFindings` are findings another emitter produced for the
+ * same app (the managed files, the formatter, the contract emit), app-relative, judged and counted with this module's own.
+ * The root scope and each side run their own rules over their own files (hfs checks per side, the side folder as the old repository
+ * root, plus the root checks); every finding path is app-relative. Returns {ok, profile, apps, manifest, tracked, findings, counts};
+ * a missing or invalid hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never an exception.
+ */
+export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all' }) {
+  const why = readWhy(root);
+  let repo;
+  try {
+    repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
+  } catch (error) {
+    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH'].includes(error.code)) throw error;
+    const findings = withWhy([{ code: error.code, level: 'error', path: HFS_DECLARATION_FILE, message: error.message.replace(/^[A-Z_]+: /, ''), problems: error.details.problems }], why);
+    return { ok: false, repoRoot, manifest: manifest.version, profile: null, apps: [], tracked: 0, findings, counts: summarize(findings) };
+  }
+  const resolver = createSlotResolver(manifest, repo);
+  const tracked = files ?? trackedFiles(repoRoot);
+  const scoped = only ? new Set(only) : null;
+  const findings = [];
+  // `hfs check` leaves to the lint canon the per-path findings that sit on an existing TypeScript file (hfs-path-findings.mjs).
+  const keep = (list, scopeRoot) => (surface === 'check' ? list.filter((finding) => !(finding.origin === 'repo' && onLintSurface(scopeRoot, finding))) : list);
+  if (repo.profile === APP_SCOPE) {
+    const own = tracked.filter((file) => resolver.sideOf(file) === null);
+    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: own, all: tracked, scoped }), repoRoot));
+    for (const side of SIDES) {
+      const prefix = `${side}/`;
+      const sideRoot = path.join(repoRoot, side);
+      const sideFiles = tracked.filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length));
+      const sideScoped = scoped ? new Set([...scoped].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length))) : null;
+      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped });
+      const message = appRelativeMessages(side, sideRoot);
+      findings.push(...keep(sideFindings, sideRoot).map((finding) => ({ ...finding, side, path: onSide(side, finding.path), message: message(finding.message) })));
+    }
+  } else {
+    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: tracked, scoped }), repoRoot));
+  }
+  findings.push(...extraFindings);
   if (tree) findings.push(...treeFindings({ repoRoot, resolver }));
 
-  // `hfs check` leaves to the lint canon the per-path findings that sit on an existing TypeScript file (hfs-path-findings.mjs).
-  const finished = withWhy(surface === 'check' ? findings.filter((finding) => !(finding.origin === 'repo' && onLintSurface(repoRoot, finding))) : findings, why);
+  // The app-root tree check reports machine codes: their why is read with the check's own.
+  const finished = withWhy(findings, { ...why, ...readWhy(root, [...new Set(findings.map((f) => f.code).filter((code) => !why[code]))]) });
   const counts = summarize(finished);
-  return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps: repo.apps, tracked: tracked.length, findings: finished, counts };
+  const apps = repo.profile === APP_SCOPE ? SIDES.flatMap((side) => repo.sides[side].apps.map((app) => ({ ...app, side }))) : repo.apps;
+  return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps, tracked: tracked.length, findings: finished, counts };
 }
 
 // ------------------------------------------------------------------------------------------ the whole check
@@ -326,45 +376,66 @@ function machineFindings(report) {
 }
 
 /**
- * The whole `hfs check` of one repository: checkRepo() (slots, pins, size, tree) and then the architecture machine over the
- * same work tree, its violations and errors merged in as findings with the Vietnamese why of their codes. `fast` judges
- * only what changed since the merge-base (`base` names another ref): the per-path slot and pin checks on the changed
- * paths, the machine on the owners of the changed source files without clones and dead exports, and no file-system tree
- * checks. `extraFindings` are the findings of the emitters that render templates or run the repository's formatter
- * (packages/hfs/sync), judged with checkRepo's own. `machine` is injectable for specs. A missing merge-base under `fast` is an Error, never a silent full pass.
+ * The whole `hfs check` of one app: checkRepo() (the root and both sides: slots, pins, size, tree) and then the architecture machine
+ * over each side folder (the side as the repository root it judges), its violations and errors merged in as findings with the
+ * Vietnamese why of their codes and the side prefixed onto their paths. `fast` judges only what changed since the merge-base (`base`
+ * names another ref): the per-path slot and pin checks on the changed paths, the machine on the owners of the changed source files
+ * without clones and dead exports, and no file-system tree checks. `extraFindings` are the findings of the emitters that render
+ * templates or run the formatter (packages/hfs/sync), judged with checkRepo's own. `machine` is injectable for specs. A missing
+ * merge-base under `fast` is an Error, never a silent full pass. `repoRoot` may also be a side folder: that side alone is checked.
  */
 export function checkRepository({ repoRoot, root = skillRoot, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture }) {
   const changed = fast ? changedSince(repoRoot, base) : null;
-  const baseSha = changed?.base;
   const slotResult = checkRepo({ repoRoot, root, manifest, extraFindings, surface: 'check', ...(changed ? { only: changed.files, tree: false } : {}) });
   if (slotResult.profile === null) return { ...slotResult, machine: { status: 'skipped', reason: 'hfs.json is not valid' } };
-
-  let paths;
-  if (changed) {
-    const resolver = createSlotResolver(manifest, readRepoDeclaration(manifest, repoRoot));
-    paths = [...new Set(changed.files.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort();
-    if (!paths.length) return { ...slotResult, machine: { status: 'skipped', reason: 'no changed source file', base: changed.base }, fast: { base: changed.base, changed: changed.files.length } };
-  }
-  let report;
-  try {
-    report = machine({ repositoryRoot: repoRoot, base: baseSha, surface: 'check', ...(changed ? { paths, fast: true } : {}) });
-  } catch (error) {
-    report = { ok: false, files: 0, kinds: [], violations: [], errors: [{ ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error) }] };
+  const repo = readRepoDeclaration(manifest, repoRoot);
+  const scopes = repo.profile === APP_SCOPE
+    ? SIDES.map((side) => ({ side, repoRoot: path.join(repoRoot, side), prefix: `${side}/` }))
+    : [{ side: null, repoRoot, prefix: '' }];
+  const runs = [];
+  const found = [];
+  for (const scope of scopes) {
+    const run = machineOver({ scope, manifest, machine, changed });
+    runs.push(run.info);
+    found.push(...run.findings);
   }
-  const found = machineFindings(report);
   const why = readWhy(root, [...new Set(found.map((f) => f.code))]);
   const findings = [...slotResult.findings, ...withWhy(found, why)];
   const counts = summarize(findings);
+  const ran = runs.filter((info) => info.status === 'ran');
   return {
     ...slotResult,
     ok: counts.error === 0,
     findings,
     counts,
-    machine: { status: 'ran', files: report.files, kinds: report.kinds, ...(changed ? { paths, base: changed.base } : {}) },
+    machine: ran.length
+      ? { status: 'ran', files: ran.reduce((sum, info) => sum + info.files, 0), kinds: [...new Set(ran.flatMap((info) => info.kinds ?? []))], sides: runs, ...(changed ? { paths: ran.flatMap((info) => info.paths ?? []), base: changed.base } : {}) }
+      : { status: 'skipped', reason: runs.map((info) => info.reason).join('; '), sides: runs, ...(changed ? { base: changed.base } : {}) },
     ...(changed ? { fast: { base: changed.base, changed: changed.files.length } } : {}),
   };
 }
 
+/** The architecture machine over one scope (a side folder): `{ info, findings }`, finding paths app-relative. */
+function machineOver({ scope, manifest, machine, changed }) {
+  const { side, prefix } = scope;
+  const label = side ?? 'repository';
+  let paths;
+  if (changed) {
+    const resolver = createSlotResolver(manifest, readRepoDeclaration(manifest, scope.repoRoot));
+    const mine = changed.files.filter((f) => f.startsWith(prefix)).map((f) => f.slice(prefix.length));
+    paths = [...new Set(mine.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort();
+    if (!paths.length) return { info: { side, status: 'skipped', reason: `no changed source file in ${label}` }, findings: [] };
+  }
+  let report;
+  try {
+    report = machine({ repositoryRoot: scope.repoRoot, base: changed?.base, surface: 'check', ...(changed ? { paths, fast: true } : {}) });
+  } catch (error) {
+    report = { ok: false, files: 0, kinds: [], violations: [], errors: [{ ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error) }] };
+  }
+  const message = side ? appRelativeMessages(side, scope.repoRoot) : null;
+  const findings = machineFindings(report).map((finding) => (side ? { ...finding, side, message: message(finding.message), ...(finding.path ? { path: onSide(side, finding.path) } : {}) } : finding));
+  return { info: { side, status: 'ran', files: report.files, kinds: report.kinds, ...(paths ? { paths: paths.map((p) => `${prefix}${p}`) } : {}) }, findings };
+}
 // --------------------------------------------------------------------------------------------------- explain
 
 const TEST_KIND = {
@@ -386,7 +457,9 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
   const slot = resolver.slot(c.slot);
   const tier = resolver.tierOf(c.path);
   const owner = resolver.ownerOf(c.path);
-  const mayImport = tier && tier !== 'none' ? resolver.allowedImports(tier) : null;
+  // A path of a side imports by its side's direction matrix; the app root has none of its own.
+  const scope = c.side ? resolver.sides[c.side] : resolver;
+  const mayImport = tier && tier !== 'none' ? scope.allowedImports(tier) : null;
   return {
     path: c.path,
     status: c.status,
@@ -407,61 +480,3 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
     ...(c.status === 'not-enabled' ? { code: 'HFS_SLOT_NOT_ENABLED', titleVi: why.HFS_SLOT_NOT_ENABLED.titleVi, whyVi: why.HFS_SLOT_NOT_ENABLED.whyVi } : {}),
   };
 }
-
-// ------------------------------------------------------------------------------------------------- init
-
-const SLUG_SUFFIX = /-(backend|be|frontend|fe|api|web|app)$/;
-const exists = (p) => fs.existsSync(p);
-const readPackage = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { return null; } };
-const depsOf = (pkg) => ({ ...pkg?.devDependencies, ...pkg?.dependencies });
-
-/**
- * A starter hfs.json by detection: profile from the dependencies (next -> fe, @nestjs/core -> be, over the root and
- * every apps/<name>), apps from the apps/<name> directories (fe: kind next; be: worker/migrate/cli by name, else api).
- * optionalSlots are the opt-in slots (not implied by an app kind) that tracked files already occupy. Connections are not guessed; a repository that keeps a database declares them by hand and gains the migrate app.
- * A repository the detection cannot classify is HFS_INIT_UNDETECTED, never a guess.
- */
-export function detectDeclaration({ repoRoot, manifest }) {
-  const appsDir = path.join(repoRoot, 'apps');
-  const names = isDir(appsDir) ? fs.readdirSync(appsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== 'node_modules').map((e) => e.name).sort() : [];
-  const rootPkg = readPackage(repoRoot);
-  const all = { ...depsOf(rootPkg) };
-  for (const name of names) Object.assign(all, depsOf(readPackage(path.join(appsDir, name))));
-  const isFe = 'next' in all || names.some((n) => ['next.config.ts', 'next.config.js', 'next.config.mjs'].some((f) => exists(path.join(appsDir, n, f))));
-  const isBe = '@nestjs/core' in all || exists(path.join(repoRoot, 'nest-cli.json'));
-  if (isFe === isBe) refuse('HFS_INIT_UNDETECTED', `cannot tell the profile of ${repoRoot}: ${isFe ? 'both next and Nest are present' : 'neither next nor @nestjs/core is declared'}`, { repoRoot });
-  const profile = isFe ? 'fe' : 'be';
-  const apps = names.map((name) => {
-    if (profile === 'fe') return { name, kind: 'next' };
-    if (!isDir(path.join(appsDir, name, 'src'))) return null;
-    const kind = /migrat/.test(name) ? 'migrate' : (/worker/.test(name) ? 'worker' : (/(^|-)cli($|-)/.test(name) ? 'cli' : 'api'));
-    return { name, kind };
-  }).filter(Boolean).filter((a) => manifest.appKinds[profile].includes(a.kind));
-  if (!apps.length) refuse('HFS_INIT_UNDETECTED', `${repoRoot} has no apps/<name> ${profile === 'fe' ? 'Next application' : 'Nest application with a src directory'} to declare`, { repoRoot, profile });
-  const project = String(rootPkg?.name ?? path.basename(repoRoot)).replace(/^@[^/]+\//, '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').replace(SLUG_SUFFIX, '');
-  const declaration = { hfs: manifest.major, profile, project: /^[a-z]/.test(project) ? project : `p-${project}`, apps };
-  const optionalSlots = occupiedOptInSlots({ repoRoot, manifest, declaration });
-  return optionalSlots.length ? { ...declaration, optionalSlots } : declaration;
-}
-
-/** The opt-in slots (not enabled by an app kind) that at least one tracked file falls in, found by enabling them all for a look. */
-function occupiedOptInSlots({ repoRoot, manifest, declaration }) {
-  let files;
-  try { files = trackedFiles(repoRoot); } catch (error) { if (error.code === 'HFS_REPO_UNREADABLE') return []; throw error; }
-  const optIn = manifest.slots.filter((s) => s.profiles.includes(declaration.profile) && s.presence === 'opt-in' && s.appKind === undefined).map((s) => s.id);
-  const everything = createSlotResolver(manifest, resolveRepoDeclaration(manifest, { ...declaration, optionalSlots: optIn }));
-  const used = new Set();
-  for (const file of files) { const c = everything.classifyPath(file); if (c.status === 'owned' && optIn.includes(c.slot)) used.add(c.slot); }
-  return optIn.filter((id) => used.has(id));
-}
-
-/** Write hfs.json unless one exists (HFS_INIT_EXISTS); `write: false` returns the text only. */
-export function initRepo({ repoRoot, root = skillRoot, write = true, manifest = loadSlotManifest({ root }) }) {
-  const file = path.join(repoRoot, HFS_DECLARATION_FILE);
-  if (write && exists(file)) refuse('HFS_INIT_EXISTS', `${file} already exists; init never rewrites a declaration`, { file });
-  const declaration = detectDeclaration({ repoRoot, manifest });
-  resolveRepoDeclaration(manifest, declaration);
-  const text = `${JSON.stringify(declaration, null, 2)}\n`;
-  if (write) fs.writeFileSync(file, text);
-  return { file, declaration, text, written: write };
-}

package/runtime/scripts/lib/hfs-path-findings.mjs

@@ -8,11 +8,18 @@ import { allowsFile } from './hfs-allows.mjs';
 import { isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
 import { slotOwnsSecrets } from './hfs-rules/secrets.mjs';
 import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+import { APP_SCOPE } from './hfs-slots.mjs';
 
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const SOURCE_ROOT = /^(?:src|apps)\//;
 const FREE_NAMES = new Set(['index.ts', 'main.ts']);
 const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
+/**
+ * Where the work of a banned data-access suffix goes. The suffix is banned by the manifest (ruleParams.be.bannedSuffixes);
+ * this only adds the convention's home to the finding, so a file that is a repository or a store is told what replaces it.
+ */
+const DATA_ACCESS_HOME = 'SQL text is a constant in <name>.sql.ts of the capability persistence/ folder, and data access is the capability *.service.ts (or the application *.handler.ts) calling the shared EntityManager through its Inject<Conn>EntityManager()';
+const BANNED_SUFFIX_HOME = Object.freeze({ repository: DATA_ACCESS_HOME, store: DATA_ACCESS_HOME });
 
 /**
  * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
@@ -39,14 +46,16 @@ function sourceFormFindings({ files, resolver }) {
     // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
     const slot = resolver.slot(c.slot);
     if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
-    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
+    // So is an allows entry below the slot root whose last segment is that literal name (be.tests.world fakes/<provider>/server.ts).
     const admitted = allowsFile(resolver, file);
+    if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) continue;
+    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
     if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
     if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
     const parts = base.slice(0, -'.ts'.length).split('.');
     const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
     if (banned) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})` });
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})${BANNED_SUFFIX_HOME[banned] ? `. ${BANNED_SUFFIX_HOME[banned]}` : ''}` });
     } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
       findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
     } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
@@ -79,6 +88,8 @@ export function pathFindings({ files, resolver, profile }) {
   }
 
   if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
+  // The app root (scripts/, CI, hooks) holds no test layer: a spec there is the same finding as a spec of an operational script.
+  else if (profile === APP_SCOPE) findings.push(...specPlacementFindings({ files, resolver }));
   // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
   return findings.map((finding) => ({ ...finding, origin: 'repo' }));
 }