@starci/hfs 1.0.1 → 2.0.1

package/runtime/scripts/checks/architecture/error-masked.mjs

@@ -0,0 +1,60 @@
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R39 `error-masked` (BE_ERROR_MASKED). Every api app root provides exactly one `APP_FILTER`, its class declared in
+ * platform/errors (the one ExceptionFilter that masks everything that is not a DomainError), and every GraphQL module
+ * registration of the program passes the `formatError` platform/errors exports. Filters and format functions defined
+ * anywhere else, a second filter, or a GraphQL registration without `formatError` leak internal errors to the client.
+ */
+export const ERROR_MASKED_RULE_IDS = ['BE_ERROR_MASKED'];
+
+const RULE = 'BE_ERROR_MASKED';
+
+export function checkErrorMasked(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  const inErrors = (checker, node) => kit.declarationsOf(checker, node).map(kit.ownerOfDeclaration).some(owner => owner && owner.tier === 'platform' && owner.name === 'errors');
+  let apps = 0;
+  for (const app of config.apps.filter(item => item.kind === 'api')) {
+    const root = kit.appRoot(app.name);
+    if (!root) continue;
+    apps += 1;
+    const filters = kit.providersOf(root, 'APP_FILTER', '@nestjs/core');
+    const anchor = filters[0]?.node ?? root.sourceFile.statements[0] ?? root.sourceFile;
+    if (filters.length !== 1) {
+      violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, anchor), app: app.name,
+        message: `App ${app.name} provides ${filters.length} APP_FILTER entries; an api app provides exactly one, the ExceptionFilter of platform/errors.` });
+    }
+    for (const filter of filters) {
+      if (!filter.useClass || !inErrors(filter.checker, filter.useClass)) {
+        violations.push({ ruleId: RULE, path: root.rel, ...kit.at(root.rel, root.sourceFile, filter.node), app: app.name,
+          message: 'The APP_FILTER must be `useClass` of the filter declared in platform/errors; any other filter can let an undeclared error reach the client unmasked.' });
+      }
+    }
+  }
+  let graphql = 0;
+  for (const file of graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!(ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ['forRoot', 'forRootAsync'].includes(node.expression.name.text)
+        && kit.isImportOf(checker, node.expression.expression, 'GraphQLModule', '@nestjs/graphql'))) return true;
+      graphql += 1;
+      let masked = false;
+      for (const argument of node.arguments) {
+        kit.walk(argument, inner => {
+          if ((ts.isPropertyAssignment(inner) || ts.isShorthandPropertyAssignment(inner)) && kit.propertyNameText(inner.name) === 'formatError'
+            && inErrors(checker, kit.valueOfProperty(inner))) masked = true;
+          return true;
+        });
+      }
+      if (!masked) {
+        violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node),
+          message: `GraphQLModule.${node.expression.name.text} must pass the \`formatError\` exported by platform/errors; without it a resolver error reaches the client with its internal message.` });
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', apps, graphqlRegistrations: graphql } };
+}

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

@@ -0,0 +1,38 @@
+import { treeOf } from './required-files.mjs';
+import { allowsFile } from '../../lib/hfs-allows.mjs';
+
+/**
+ * R94 `fe-slot-allows` (FE_SLOT_FILE_ROLE). A front-end slot that owns a whole directory (`fe.route`, `fe.feature`,
+ * `fe.components`, `fe.hooks`, `fe.modules.api`) also says what its instances hold (`allows` in knowledge/hfs/slots.yaml).
+ * Every tracked file of such a slot is matched against the `requires` and `allows` entries of its slot; a file no entry names is a
+ * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a `.test.tsx` beside a component, a stray file at
+ * a feature root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
+ * Files no slot owns are HFS_PATH_NO_SLOT's (`hfs check`), so together every front-end file is placed by exactly one slot and
+ * named by it.
+ */
+export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];
+
+const RULE = 'FE_SLOT_FILE_ROLE';
+
+export function checkFeSlotAllows({ config, graph }) {
+  const resolver = graph.resolver;
+  const tree = treeOf(config.root);
+  const violations = [];
+  let files = 0;
+  const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
+  for (const file of [...tree.files].sort()) {
+    const classified = resolver.classifyPath(file);
+    if (classified.status !== 'owned') continue;
+    const slot = resolver.slot(classified.slot);
+    if (!slot?.allows?.length) continue;
+    files += 1;
+    if (slot.owner === true && classified.root === classified.path) {
+      report(file, `${file} sits where slot ${slot.id} expects a folder (${slot.path}); it holds ${slot.allows.join(', ')} inside a folder of its own. Move it into one.`, { slot: slot.id });
+      continue;
+    }
+    const verdict = allowsFile(resolver, file);
+    if (!verdict || verdict.allowed) continue;
+    report(file, `${file} is not allowed in ${verdict.slot} (${verdict.root}); that slot holds only ${verdict.allows.join(', ')}. Rename it to an allowed role or move it to the slot it belongs to.`, { slot: verdict.slot });
+  }
+  return { violations, coverage: { status: 'checked', files } };
+}

package/runtime/scripts/checks/architecture/feature-shape.mjs

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { treeOf } from './required-files.mjs';
+import { allowsFile } from '../../lib/hfs-allows.mjs';
+
+/**
+ * R29 `feature-shape` (BE_FEATURE_SHAPE). A feature root holds `index.ts`, `<feature>.module.ts`, `application/`,
+ * `transport/<protocol>/` and `messages/` only, and each of those folders holds only what its slot `allows` (knowledge/hfs/
+ * slots.yaml: be.feature, be.feature.application, be.feature.application.support, be.transport.*, be.feature.transport.cli,
+ * be.feature.messages). Every tracked file below a feature root is classified by the slot resolver and matched against
+ * the `requires` and `allows` entries of the slot that owns it; a directory that no slot owns (an unknown protocol under
+ * `transport/`, a `graphql/` folder under `application/`) is refused because its files fall back to the feature root slot.
+ */
+export const FEATURE_SHAPE_RULE_IDS = ['BE_FEATURE_SHAPE'];
+
+const RULE = 'BE_FEATURE_SHAPE';
+
+export function checkFeatureShape({ config, graph }) {
+  const resolver = graph.resolver;
+  const tree = treeOf(config.root);
+  const violations = [];
+  const features = new Set();
+  let files = 0;
+  const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
+  for (const file of [...tree.files].sort()) {
+    const owner = resolver.ownerOf(file);
+    if (!owner || resolver.slot(owner.slot)?.tier !== 'feature') continue;
+    features.add(owner.root);
+    files += 1;
+    const verdict = allowsFile(resolver, file);
+    if (!verdict) continue;
+    const feature = path.posix.basename(owner.root);
+    const where = `${verdict.slot} (${verdict.root})`;
+    if (verdict.slot === owner.slot) {
+      // The feature root slot owns only the files at the root; anything deeper sits in a directory no slot claims.
+      if (verdict.relative.includes('/')) {
+        const folder = verdict.relative.split('/')[0];
+        report(file, `${file} sits in ${owner.root}/${folder}/, which no slot owns; a feature root holds only ${verdict.allows.join(', ')}, and transport/ holds one folder per protocol a slot names. Move it to application/ or a transport/<protocol>/ folder, or delete it.`,
+          { feature, folder });
+      } else if (!verdict.allowed) {
+        report(file, `${file} is not allowed at the root of feature ${feature}; the root holds only ${verdict.allows.join(', ')}. Move it under application/ or transport/<protocol>/.`, { feature });
+      }
+      continue;
+    }
+    if (verdict.allowed) continue;
+    const forbidden = verdict.forbiddenBy ? ` ${verdict.forbiddenBy} is forbidden there;` : '';
+    report(file, `${file} is not allowed in ${where};${forbidden} that folder holds only ${verdict.allows.join(', ')}. Rename it to an allowed role or move it to the folder its role belongs to.`, { feature, slot: verdict.slot });
+  }
+  return { violations, coverage: { status: 'checked', features: features.size, files } };
+}

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

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