@starci/hfs 4.0.10 → 4.2.0

package/runtime/scripts/hfs/architecture/required-files.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { lsFiles } from '../../api/git/ls-files.mjs';
 import { revParseQuery } from '../../api/git/rev-parse-query.mjs';
 import { gitOutputOf } from '../../lib/git.mjs';
+import { trimTrailingSlashes } from '../trailing-slashes.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
@@ -48,8 +49,20 @@ function diskFiles(root, relative = '') {
   return out;
 }
 
-/** The repository tree as file and directory sets over posix relatives. */
-export function treeOf(root) {
+let runTrees = null;
+
+/** Runs `run` with one tree read per root: every checker of one machine run shares the repository listing instead of spawning git again. */
+export function withTreeCache(run) {
+  const outer = runTrees;
+  runTrees = outer ?? new Map();
+  try {
+    return run();
+  } finally {
+    runTrees = outer;
+  }
+}
+
+function readTree(root) {
   const list = gitFiles(root) ?? diskFiles(root);
   const files = new Set(list);
   const directories = new Set();
@@ -60,6 +73,13 @@ export function treeOf(root) {
   return { files, directories };
 }
 
+/** The repository tree as file and directory sets over posix relatives. */
+export function treeOf(root) {
+  if (!runTrees) return readTree(root);
+  if (!runTrees.has(root)) runTrees.set(root, readTree(root));
+  return runTrees.get(root);
+}
+
 /**
  * The prelude every tree-walking architecture checker shares: the input's config/graph/context, the compiler,
  * the slot resolver and the tracked repository tree.
@@ -68,28 +88,27 @@ export function checkerScope({ config, graph, context }) {
   return { config, graph, context, ts: context.ts, resolver: graph.resolver, tree: treeOf(config.root) };
 }
 
-const strip = entry => entry.replace(/\/+$/u, '');
-const rootOfTarget = target => (target.endsWith('/') ? strip(target) : (path.posix.dirname(target) === '.' ? '' : path.posix.dirname(target)));
+const rootOfTarget = target => {
+  if (target.endsWith('/')) return trimTrailingSlashes(target);
+  const parent = path.posix.dirname(target);
+  return parent === '.' ? '' : parent;
+};
 
 function ruleFor(slotId, target, rootExists) {
-  if (slotId === 'fe.app.next' && rootExists && ERROR_BOUNDARY_FILE.test(path.posix.basename(strip(target)))) return 'FE_ERROR_BOUNDARY_MISSING';
+  if (slotId === 'fe.app.next' && rootExists && ERROR_BOUNDARY_FILE.test(path.posix.basename(trimTrailingSlashes(target)))) return 'FE_ERROR_BOUNDARY_MISSING';
   return 'HFS_REQUIRED_FILE_MISSING';
 }
 
-export function checkRequiredFiles({ config, graph }) {
-  const resolver = graph?.resolver ?? config.hfs;
-  const tree = treeOf(config.root);
-  const judged = slotId => {
-    const slot = resolver.slot(slotId);
-    return Boolean(slot) && (slot.tier !== 'none' || ALSO_JUDGED_TIER_NONE.has(slotId));
-  };
+function slotIsJudged(resolver, slotId) {
+  const slot = resolver.slot(slotId);
+  return Boolean(slot) && (slot.tier !== 'none' || ALSO_JUDGED_TIER_NONE.has(slotId));
+}
 
-  const requirements = new Map(); // repository-relative target (as written, dirs end with /) -> {slot, target, root}
-  const instances = new Set();
-  const addRequirement = (slot, target, root) => { if (!requirements.has(target)) requirements.set(target, { slot, target, root }); };
+function addRequirement(requirements, slot, target, root) {
+  if (!requirements.has(target)) requirements.set(target, { slot, target, root });
+}
 
-  // 1. What the repository must hold whatever it contains: fixed instances (requiredInstances, one per declared app).
-  const declared = resolver.requiredPaths();
+function collectDeclaredRequirements(declared, requirements, instances, judged) {
   const currentRoot = new Map();
   for (const item of declared.paths) {
     if (!judged(item.slot)) continue;
@@ -97,84 +116,116 @@ export function checkRequiredFiles({ config, graph }) {
       const root = rootOfTarget(item.path);
       currentRoot.set(item.slot, root);
       instances.add(`${item.slot}|${root}`);
-      addRequirement(item.slot, item.path, root);
+      addRequirement(requirements, item.slot, item.path, root);
     } else {
-      addRequirement(item.slot, item.path, currentRoot.get(item.slot) ?? '');
+      addRequirement(requirements, item.slot, item.path, currentRoot.get(item.slot) ?? '');
     }
   }
+}
+
+function addInstanceRequirements(resolver, classified, representative, requirements, instances, seenInstances, judged) {
+  const { slot: slotId, root } = classified;
+  const key = `${slotId}|${root}`;
+  if (seenInstances.has(key) || !judged(slotId)) return;
+  seenInstances.add(key);
+  instances.add(key);
+  for (const target of resolver.requiredFiles(representative)) addRequirement(requirements, slotId, target, root);
+}
+
+function addOwnerRequirements(resolver, owner, requirements, instances, seenInstances, judged) {
+  const key = `${owner.slot}|${owner.root}`;
+  if (seenInstances.has(key) || !judged(owner.slot) || !resolver.slotEnabled(resolver.slot(owner.slot))) return;
+  seenInstances.add(key);
+  instances.add(key);
+  for (const entry of resolver.slot(owner.slot).requires ?? []) {
+    const rooted = entry.startsWith('/');
+    const filled = (rooted ? entry.slice(1) : entry).replace(/<([A-Za-z][A-Za-z0-9-]*)>/g, (whole, name) => owner.bindings[name] ?? whole);
+    addRequirement(requirements, owner.slot, rooted || !owner.root ? filled : `${owner.root}/${filled}`, owner.root);
+  }
+}
 
-  // 2. What each instance found by walking the tree requires (features, domains, integrations, packages, transports, ...).
+function noteInstance(found, slotId, root) {
+  if (!found.has(slotId)) found.set(slotId, new Set());
+  found.get(slotId).add(root);
+}
+
+function collectTreeRequirements(tree, resolver, requirements, instances, judged) {
   const seenInstances = new Set();
-  const instanceRequires = (slotId, root, representative) => {
-    const key = `${slotId}|${root}`;
-    if (seenInstances.has(key) || !judged(slotId)) return;
-    seenInstances.add(key);
-    instances.add(key);
-    for (const target of resolver.requiredFiles(representative)) addRequirement(slotId, target, root);
-  };
-  const ownerRequires = owner => {
-    const key = `${owner.slot}|${owner.root}`;
-    if (seenInstances.has(key) || !judged(owner.slot) || !resolver.slotEnabled(resolver.slot(owner.slot))) return;
-    seenInstances.add(key);
-    instances.add(key);
-    for (const entry of resolver.slot(owner.slot).requires ?? []) {
-      const rooted = entry.startsWith('/');
-      const filled = (rooted ? entry.slice(1) : entry).replace(/<([A-Za-z][A-Za-z0-9-]*)>/g, (whole, name) => owner.bindings[name] ?? whole);
-      addRequirement(owner.slot, rooted || !owner.root ? filled : `${owner.root}/${filled}`, owner.root);
-    }
-  };
   const found = new Map(); // slot -> Set(root) of instances seen while walking
-  const note = (slotId, root) => {
-    if (!found.has(slotId)) found.set(slotId, new Set());
-    found.get(slotId).add(root);
-  };
   for (const file of tree.files) {
     const classified = resolver.classifyPath(file);
     if (classified.status === 'owned' && classified.slot) {
-      note(classified.slot, classified.root);
-      instanceRequires(classified.slot, classified.root, file);
+      noteInstance(found, classified.slot, classified.root);
+      addInstanceRequirements(resolver, classified, file, requirements, instances, seenInstances, judged);
     }
     const owner = resolver.ownerOf(file);
     if (owner) {
-      note(owner.slot, owner.root);
+      noteInstance(found, owner.slot, owner.root);
       // an owner root may classify to a more specific slot (modules/i18n) or a nested one, so expand the owner slot's own requires
-      ownerRequires(owner);
+      addOwnerRequirements(resolver, owner, requirements, instances, seenInstances, judged);
     }
   }
+  return found;
+}
 
-  const violations = [];
-  const reported = new Set();
-  const report = (ruleId, target, slotId, root, extra, message) => {
-    const key = `${ruleId}|${target}`;
-    if (reported.has(key)) return;
-    reported.add(key);
-    violations.push({ ruleId, path: target, slot: slotId, ...(root ? { root } : {}), ...extra, message });
-  };
-  const exists = target => (target.endsWith('/') ? tree.directories.has(strip(target)) : tree.files.has(target));
-
-  for (const requirement of requirements.values()) {
-    if (exists(requirement.target)) continue;
-    const rootExists = !requirement.root || tree.directories.has(requirement.root);
-    if (!rootExists) {
-      report(ruleFor(requirement.slot, requirement.target, false), requirement.root, requirement.slot, requirement.root, { kind: 'directory' },
-        `Required directory ${requirement.root} (slot ${requirement.slot}) does not exist; the slot manifest requires it, along with what it holds.`);
-      continue;
-    }
-    const kind = requirement.target.endsWith('/') ? 'directory' : 'file';
-    report(ruleFor(requirement.slot, requirement.target, true), strip(requirement.target), requirement.slot, requirement.root, { kind },
-      `Required ${kind} ${strip(requirement.target)} is missing; slot ${requirement.slot} requires it in every instance${requirement.root ? ` (${requirement.root})` : ''}.`);
+function requirementExists(tree, target) {
+  return target.endsWith('/') ? tree.directories.has(trimTrailingSlashes(target)) : tree.files.has(target);
+}
+
+function reportMissingRequirement(requirement, tree, report) {
+  if (requirementExists(tree, requirement.target)) return;
+  const rootExists = !requirement.root || tree.directories.has(requirement.root);
+  if (!rootExists) {
+    report(ruleFor(requirement.slot, requirement.target, false), requirement.root, requirement.slot, requirement.root, { kind: 'directory' },
+      `Required directory ${requirement.root} (slot ${requirement.slot}) does not exist; the slot manifest requires it, along with what it holds.`);
+    return;
   }
+  const kind = requirement.target.endsWith('/') ? 'directory' : 'file';
+  const rootNote = requirement.root ? ` (${requirement.root})` : '';
+  report(ruleFor(requirement.slot, requirement.target, true), trimTrailingSlashes(requirement.target), requirement.slot, requirement.root, { kind },
+    `Required ${kind} ${trimTrailingSlashes(requirement.target)} is missing; slot ${requirement.slot} requires it in every instance${rootNote}.`);
+}
+
+function reportMissingRequirements(requirements, tree, report) {
+  for (const requirement of requirements.values()) reportMissingRequirement(requirement, tree, report);
+}
 
-  // 3. Minimums: at least minInstances instances of a required slot.
-  for (const minimum of declared.minimums) {
+function reportMinimumRequirements(minimums, resolver, judged, found, report) {
+  for (const minimum of minimums) {
     if (!judged(minimum.slot)) continue;
     const count = minimum.appKind !== undefined
       ? resolver.repo.apps.filter(app => app.kind === minimum.appKind).length
       : (found.get(minimum.slot)?.size ?? 0);
     if (count >= minimum.min) continue;
+    const appKindNote = minimum.appKind ? ' (an app of kind ' + minimum.appKind + ' declared in hfs.json)' : '';
     report('HFS_REQUIRED_FILE_MISSING', 'hfs.json', minimum.slot, '', { minimum: minimum.min, found: count },
-      `Slot ${minimum.slot} needs at least ${minimum.min} instance${minimum.min === 1 ? '' : 's'}${minimum.appKind ? ` (an app of kind ${minimum.appKind} declared in hfs.json)` : ''}; the repository has ${count}.`);
+      `Slot ${minimum.slot} needs at least ${minimum.min} instance${minimum.min === 1 ? '' : 's'}${appKindNote}; the repository has ${count}.`);
   }
+}
+
+export function checkRequiredFiles({ config, graph }) {
+  const resolver = graph?.resolver ?? config.hfs;
+  const tree = treeOf(config.root);
+  const judged = slotId => slotIsJudged(resolver, slotId);
+
+  const requirements = new Map(); // repository-relative target (as written, dirs end with /) -> {slot, target, root}
+  const instances = new Set();
+  const declared = resolver.requiredPaths();
+  collectDeclaredRequirements(declared, requirements, instances, judged);
+
+  const found = collectTreeRequirements(tree, resolver, requirements, instances, judged);
+
+  const violations = [];
+  const reported = new Set();
+  const report = (ruleId, target, slotId, root, extra, message) => {
+    const key = `${ruleId}|${target}`;
+    if (reported.has(key)) return;
+    reported.add(key);
+    violations.push({ ruleId, path: target, slot: slotId, ...(root ? { root } : {}), ...extra, message });
+  };
+  reportMissingRequirements(requirements, tree, report);
+
+  reportMinimumRequirements(declared.minimums, resolver, judged, found, report);
 
   return { violations, coverage: { status: 'checked', instances: instances.size, requirements: requirements.size, missing: violations.length } };
 }

package/runtime/scripts/hfs/architecture/route-files-thin.mjs

@@ -24,74 +24,99 @@ const HOOK_ROUTES = new Set([...MOUNTING_ROUTES, 'page']);
 const HOOK_NAME = /^use[A-Z0-9]/u;
 const HOOKS_SLOT = 'fe.hooks';
 
+const isFunction = (ts, node) => ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node);
+const jsxOf = (ts, node) => ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node);
+
+function tagOf(ts, node) {
+  if (ts.isJsxElement(node)) return node.openingElement.tagName;
+  if (ts.isJsxSelfClosingElement(node)) return node.tagName;
+  return null;
+}
+
+function addExportAssignmentDefaults(ts, statement, kit, checker, defaults) {
+  const target = statement.expression;
+  if (!ts.isIdentifier(target)) { defaults.add(target); return; }
+  for (const declaration of kit.declarationsOf(checker, target)) defaults.add(ts.isVariableDeclaration(declaration) ? declaration.initializer ?? declaration : declaration);
+}
+
+function routeDefaults(ts, file, kit, checker) {
+  const defaults = new Set();
+  for (const statement of file.sourceFile.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) defaults.add(statement);
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) addExportAssignmentDefaults(ts, statement, kit, checker, defaults);
+  }
+  return defaults;
+}
+
+/** True when the function contains JSX that is not inside a nested function. */
+function drawsDirectly(ts, fn) {
+  let found = false;
+  const visit = node => {
+    if (found) return;
+    if (node !== fn && isFunction(ts, node)) return;
+    if (jsxOf(ts, node)) { found = true; return; }
+    ts.forEachChild(node, visit);
+  };
+  visit(fn);
+  return found;
+}
+
+function reportRoute(violations, kit, file, stem, node, message, extra = {}) {
+  violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, route: stem, ...extra });
+}
+
+function inspectMountingTag(tag, { graph, kit, ts, file, stem, checker, violations, state }) {
+  if (ts.isIdentifier(tag) && /^[a-z]/u.test(tag.text)) {
+    reportRoute(violations, kit, file, stem, tag, `<${tag.text}> is drawing in a ${stem} route file; a route file mounts one feature and draws nothing. Move the markup into the feature.`);
+  } else if (kit.declarationsOf(checker, ts.isPropertyAccessExpression(tag) ? tag.name : tag).some(declaration => graph.files.get(kit.graphPath(declaration) ?? '')?.tier === 'feature')) {
+    state.owners += 1;
+  }
+}
+
+function inspectHookCall(node, { graph, kit, ts, file, stem, checker, violations }) {
+  const callee = ts.isIdentifier(node.expression) ? node.expression : null;
+  if (!callee || !HOOK_NAME.test(callee.text)) return;
+  const binding = kit.importBinding(checker, callee);
+  const inHooks = kit.declarationsOf(checker, callee).some(declaration => graph.files.get(kit.graphPath(declaration) ?? '')?.slot === HOOKS_SLOT);
+  if (binding || inHooks) reportRoute(violations, kit, file, stem, callee, `${callee.text} is a hook called in a ${stem} route file; a route file is a server adapter and holds no hook. Read the data in the feature it mounts.`);
+}
+
+function inspectRouteNode(node, context) {
+  const { kit, ts, file, stem, mounting, defaults, violations, state } = context;
+  if (jsxOf(ts, node)) state.hasJsx = true;
+  const tag = tagOf(ts, node);
+  if (mounting && tag) inspectMountingTag(tag, context);
+  if (mounting && isFunction(ts, node) && !defaults.has(node) && drawsDirectly(ts, node)) {
+    reportRoute(violations, kit, file, stem, node, `A function other than the default export draws JSX in a ${stem} route file; that is an inline component. Move it into the feature the route mounts.`);
+  }
+  if (ts.isCallExpression(node)) inspectHookCall(node, context);
+  return true;
+}
+
+function inspectRouteFile(graph, kit, file, stem, violations) {
+  const { ts } = kit;
+  const mounting = MOUNTING_ROUTES.has(stem);
+  const checker = kit.checkerOf(file.sourceFile);
+  const defaults = routeDefaults(ts, file, kit, checker);
+  const state = { hasJsx: false, owners: 0 };
+  kit.walk(file.sourceFile, node => inspectRouteNode(node, { graph, kit, ts, file, stem, mounting, checker, defaults, violations, state }));
+  if (mounting && state.hasJsx && state.owners !== 1) {
+    violations.push({ ruleId: RULE, path: file.rel, line: 1, column: 1, route: stem, owners: state.owners,
+      message: `${file.rel} mounts ${state.owners} feature owners; a ${stem} route file mounts exactly one feature (a layouts- or pages-tier component of the app), optionally inside a package shell.` });
+  }
+}
+
 export function checkRouteFilesThin(input) {
   const { graph } = input;
   const kit = machineKit(input);
-  const { ts } = kit;
   const violations = [];
   let routes = 0;
-
   for (const file of graph.files.values()) {
     if (file.slot !== ROUTE_SLOT) continue;
     const stem = path.posix.basename(file.rel).replace(/\.[cm]?[jt]sx?$/u, '');
     if (!HOOK_ROUTES.has(stem)) continue;
     routes += 1;
-    const mounting = MOUNTING_ROUTES.has(stem);
-    const checker = kit.checkerOf(file.sourceFile);
-    const report = (node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, route: stem, ...extra });
-
-    // The default export function: `export default function X`, `export default X` (X a function), `export default () => ...`.
-    const defaults = new Set();
-    for (const statement of file.sourceFile.statements) {
-      if (ts.isFunctionDeclaration(statement) && statement.modifiers?.some(item => item.kind === ts.SyntaxKind.DefaultKeyword)) defaults.add(statement);
-      if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
-        const target = statement.expression;
-        if (ts.isIdentifier(target)) for (const declaration of kit.declarationsOf(checker, target)) defaults.add(ts.isVariableDeclaration(declaration) ? declaration.initializer ?? declaration : declaration);
-        else defaults.add(target);
-      }
-    }
-    const isFunction = node => ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node);
-    const jsxOf = node => ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node);
-    const tagOf = node => (ts.isJsxElement(node) ? node.openingElement.tagName : ts.isJsxSelfClosingElement(node) ? node.tagName : null);
-    /** True when the function contains JSX that is not inside a nested function. */
-    const drawsDirectly = fn => {
-      let found = false;
-      const visit = node => {
-        if (found) return;
-        if (node !== fn && isFunction(node)) return;
-        if (jsxOf(node)) { found = true; return; }
-        ts.forEachChild(node, visit);
-      };
-      visit(fn);
-      return found;
-    };
-
-    let hasJsx = false;
-    let owners = 0;
-    kit.walk(file.sourceFile, node => {
-      if (jsxOf(node)) hasJsx = true;
-      const tag = tagOf(node);
-      if (mounting && tag) {
-        if (ts.isIdentifier(tag) && /^[a-z]/u.test(tag.text)) report(tag, `<${tag.text}> is drawing in a ${stem} route file; a route file mounts one feature and draws nothing. Move the markup into the feature.`);
-        else if (kit.declarationsOf(checker, ts.isPropertyAccessExpression(tag) ? tag.name : tag).some(declaration => graph.files.get(kit.graphPath(declaration) ?? '')?.tier === 'feature')) owners += 1;
-      }
-      if (mounting && isFunction(node) && !defaults.has(node) && drawsDirectly(node)) {
-        report(node, `A function other than the default export draws JSX in a ${stem} route file; that is an inline component. Move it into the feature the route mounts.`);
-      }
-      if (ts.isCallExpression(node)) {
-        const callee = ts.isIdentifier(node.expression) ? node.expression : null;
-        if (callee && HOOK_NAME.test(callee.text)) {
-          const binding = kit.importBinding(checker, callee);
-          const inHooks = kit.declarationsOf(checker, callee).some(declaration => graph.files.get(kit.graphPath(declaration) ?? '')?.slot === HOOKS_SLOT);
-          if (binding || inHooks) report(callee, `${callee.text} is a hook called in a ${stem} route file; a route file is a server adapter and holds no hook. Read the data in the feature it mounts.`);
-        }
-      }
-      return true;
-    });
-    if (mounting && hasJsx && owners !== 1) {
-      violations.push({ ruleId: RULE, path: file.rel, line: 1, column: 1, route: stem, owners,
-        message: `${file.rel} mounts ${owners} feature owners; a ${stem} route file mounts exactly one feature (a layouts- or pages-tier component of the app), optionally inside a package shell.` });
-    }
+    inspectRouteFile(graph, kit, file, stem, violations);
   }
   return { violations, coverage: { status: 'checked', routes } };
 }