@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/architecture/error-codes.mjs

@@ -1,6 +1,5 @@
 import path from 'node:path';
 import { machineKit, upperSnake } from './machine-ast.mjs';
-
 /**
  * R38 error codes (BE_ERROR_HOME, machine half; the eslint half judges the error classes). The string value of every
  * member of a `<C>ErrorCode` enum in a capability's `errors/<c>.error.ts` is a string literal shaped
@@ -8,45 +7,48 @@ import { machineKit, upperSnake } from './machine-ast.mjs';
  * whole repository, so a code names one refusal and one capability for the client and the log.
  */
 export const ERROR_CODE_RULE_IDS = ['BE_ERROR_HOME'];
-
 const RULE = 'BE_ERROR_HOME';
-
 // Judge each member of one <C>ErrorCode enum; returns how many string-literal codes it held.
 const checkEnumCodes = (statement, { file, capability, shape, kit, ts, seen, violations }) => {
-  let checked = 0;
-  for (const member of statement.members) {
-    const report = message => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, member), message });
-    const name = kit.propertyNameText(member.name) ?? '?';
-    const value = member.initializer && ts.isStringLiteralLike(member.initializer) ? member.initializer.text : null;
-    if (value === null) { report(`${statement.name.text}.${name} must be a string literal code (\`${capability}_<WHAT>\`); a computed or numeric code cannot be checked or told apart in a log.`); continue; }
-    checked += 1;
-    if (!shape.test(value) || /_(?:ERROR|EXCEPTION)$/u.test(value)) {
-      report(`${statement.name.text}.${name} = "${value}" must match ${capability}_<WHAT> in UPPER_SNAKE with the capability prefix and no _ERROR or _EXCEPTION suffix.`);
+    let checked = 0;
+    for (const member of statement.members) {
+        const report = (message) => { violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, member), message }); };
+        const name = kit.propertyNameText(member.name) ?? '?';
+        const value = member.initializer && ts.isStringLiteralLike(member.initializer) ? member.initializer.text : null;
+        if (value === null) {
+            report(`${statement.name.text}.${name} must be a string literal code (\`${capability}_<WHAT>\`); a computed or numeric code cannot be checked or told apart in a log.`);
+            continue;
+        }
+        checked += 1;
+        if (!shape.test(value) || /_(?:ERROR|EXCEPTION)$/u.test(value)) {
+            report(`${statement.name.text}.${name} = "${value}" must match ${capability}_<WHAT> in UPPER_SNAKE with the capability prefix and no _ERROR or _EXCEPTION suffix.`);
+        }
+        if (seen.has(value))
+            report(`Error code "${value}" is already declared in ${seen.get(value)}; a code is unique across the repository.`);
+        else
+            seen.set(value, file.rel);
     }
-    if (seen.has(value)) report(`Error code "${value}" is already declared in ${seen.get(value)}; a code is unique across the repository.`);
-    else seen.set(value, file.rel);
-  }
-  return checked;
+    return checked;
 };
-
 export function checkErrorCodes(input) {
-  const { graph } = input;
-  const kit = machineKit(input);
-  const { ts } = kit;
-  const violations = [];
-  const seen = new Map();
-  let enums = 0;
-  let codes = 0;
-  const files = [...graph.files.values()].filter(file => file.slot === 'be.errors' && file.owner && path.posix.basename(file.rel).endsWith('.error.ts'))
-    .sort((a, b) => a.rel.localeCompare(b.rel));
-  for (const file of files) {
-    const capability = upperSnake(path.posix.basename(file.owner.root));
-    const shape = new RegExp(`^${capability}_[A-Z0-9]+(?:_[A-Z0-9]+)*$`, 'u');
-    for (const statement of file.sourceFile.statements) {
-      if (!ts.isEnumDeclaration(statement) || !statement.name.text.endsWith('ErrorCode')) continue;
-      enums += 1;
-      codes += checkEnumCodes(statement, { file, capability, shape, kit, ts, seen, violations });
+    const { graph } = input;
+    const kit = machineKit(input);
+    const { ts } = kit;
+    const violations = [];
+    const seen = new Map();
+    let enums = 0;
+    let codes = 0;
+    const files = [...graph.files.values()].filter((file) => file.slot === 'be.errors' && file.owner !== null && path.posix.basename(file.rel).endsWith('.error.ts'))
+        .sort((a, b) => a.rel.localeCompare(b.rel));
+    for (const file of files) {
+        const capability = upperSnake(path.posix.basename(file.owner.root));
+        const shape = new RegExp(`^${capability}_[A-Z0-9]+(?:_[A-Z0-9]+)*$`, 'u');
+        for (const statement of file.sourceFile.statements) {
+            if (!ts.isEnumDeclaration(statement) || !statement.name.text.endsWith('ErrorCode'))
+                continue;
+            enums += 1;
+            codes += checkEnumCodes(statement, { file, capability, shape, kit, ts, seen, violations });
+        }
     }
-  }
-  return { violations, coverage: { status: 'checked', enums, codes } };
+    return { violations, coverage: { status: 'checked', enums, codes } };
 }

package/runtime/scripts/hfs/architecture/error-masked.d.mts

@@ -0,0 +1,16 @@
+import type { ArchitectureViolation, CheckInput } from './hfs-graph.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 declare const ERROR_MASKED_RULE_IDS: string[];
+export declare function checkErrorMasked(input: CheckInput): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        status: string;
+        apps: number;
+        graphqlRegistrations: number;
+    };
+};

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

@@ -1,5 +1,4 @@
 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
@@ -7,76 +6,73 @@ import { machineKit } from './machine-ast.mjs';
  * 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';
-
-const inErrorsOf = kit => (checker, node) => kit.declarationsOf(checker, node).map(kit.ownerOfDeclaration).some(owner => owner?.tier === 'platform' && owner.name === 'errors');
-
+const inErrorsOf = (kit) => (checker, node) => kit.declarationsOf(checker, node).map(kit.ownerOfDeclaration).some(owner => owner?.tier === 'platform' && owner.name === 'errors');
 function appFilterViolations(kit, inErrors, app, root) {
-  const violations = [];
-  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.' });
+    const violations = [];
+    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, ...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.` });
     }
-  }
-  return violations;
+    for (const filter of filters) {
+        if (!filter.useClass || !inErrors(filter.checker, filter.useClass)) {
+            violations.push({ ruleId: RULE, ...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.' });
+        }
+    }
+    return violations;
 }
-
 const isGraphqlRegistration = (kit, checker, node) => kit.ts.isCallExpression(node) && kit.ts.isPropertyAccessExpression(node.expression)
-  && ['forRoot', 'forRootAsync'].includes(node.expression.name.text)
-  && kit.isImportOf(checker, node.expression.expression, 'GraphQLModule', '@nestjs/graphql');
-
+    && ['forRoot', 'forRootAsync'].includes(node.expression.name.text)
+    && kit.isImportOf(checker, node.expression.expression, 'GraphQLModule', '@nestjs/graphql');
 /**
  * The formatter a `formatError` value names: the value itself, or the callee of an arrow whose body only calls it (an arrow that
  * binds the errors service, `(formatted, error) => formatGraphqlError(errors, formatted, error)`).
  */
 function formatterOf(ts, value) {
-  if (value && ts.isArrowFunction(value) && ts.isCallExpression(value.body)) return value.body.expression;
-  return value;
+    if (value && ts.isArrowFunction(value) && ts.isCallExpression(value.body))
+        return value.body.expression;
+    return value;
 }
-
 function passesMaskedFormatError(kit, inErrors, checker, call) {
-  const { ts } = kit;
-  let masked = false;
-  for (const argument of call.arguments) {
-    kit.walk(argument, inner => {
-      if ((ts.isPropertyAssignment(inner) || ts.isShorthandPropertyAssignment(inner)) && kit.propertyNameText(inner.name) === 'formatError'
-        && inErrors(checker, formatterOf(ts, kit.valueOfProperty(inner)))) masked = true;
-    });
-  }
-  return masked;
+    const { ts } = kit;
+    let masked = false;
+    for (const argument of call.arguments) {
+        kit.walk(argument, (inner) => {
+            if ((ts.isPropertyAssignment(inner) || ts.isShorthandPropertyAssignment(inner)) && kit.propertyNameText(inner.name) === 'formatError'
+                && inErrors(checker, formatterOf(ts, kit.valueOfProperty(inner))))
+                masked = true;
+        });
+    }
+    return masked;
 }
-
 export function checkErrorMasked(input) {
-  const { config, graph } = input;
-  const kit = machineKit(input);
-  const violations = [];
-  const inErrors = inErrorsOf(kit);
-  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;
-    violations.push(...appFilterViolations(kit, inErrors, app, root));
-  }
-  let graphql = 0;
-  for (const file of graph.files.values()) {
-    const checker = kit.checkerOf(file.sourceFile);
-    kit.walk(file.sourceFile, node => {
-      if (!isGraphqlRegistration(kit, checker, node)) return;
-      graphql += 1;
-      if (!passesMaskedFormatError(kit, inErrors, checker, node)) {
-        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 { violations, coverage: { status: 'checked', apps, graphqlRegistrations: graphql } };
+    const { config, graph } = input;
+    const kit = machineKit(input);
+    const violations = [];
+    const inErrors = inErrorsOf(kit);
+    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;
+        violations.push(...appFilterViolations(kit, inErrors, app, root));
+    }
+    let graphql = 0;
+    for (const file of graph.files.values()) {
+        const checker = kit.checkerOf(file.sourceFile);
+        kit.walk(file.sourceFile, (node) => {
+            if (!isGraphqlRegistration(kit, checker, node))
+                return;
+            graphql += 1;
+            if (!passesMaskedFormatError(kit, inErrors, checker, node)) {
+                violations.push({ ruleId: RULE, ...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 { violations, coverage: { status: 'checked', apps, graphqlRegistrations: graphql } };
 }

package/runtime/scripts/hfs/architecture/fe-slot-allows.d.mts

@@ -0,0 +1,38 @@
+import type { ArchitectureConfig } from './config.mjs';
+import type { Resolver } from '../slots.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 stray file beside a component or at a feature
+ * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
+ * Files no slot owns are HFS_PATH_NO_SLOT's (`starci app check`), so together every front-end file is placed by exactly one slot and
+ * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
+ * (R97 FE_NO_TESTS): that rule is the one finding of such a file, so this check leaves it alone, as
+ * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
+ */
+export declare const FE_SLOT_ALLOWS_RULE_IDS: string[];
+/** One finding of this check. */
+interface SlotFileViolation {
+    ruleId: string;
+    path: string;
+    line: number;
+    column: number;
+    message: string;
+    slot?: string;
+}
+/** The checker input this check reads: the layout contract and the resolver-bearing graph. */
+interface FeSlotAllowsInput {
+    config: ArchitectureConfig;
+    graph: {
+        resolver: Resolver;
+    };
+}
+export declare function checkFeSlotAllows({ config, graph }: FeSlotAllowsInput): {
+    violations: SlotFileViolation[];
+    coverage: {
+        status: string;
+        files: number;
+    };
+};
+export {};

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

@@ -2,7 +2,6 @@ import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../allows.mjs';
 import { isFeTestPath } from '../rules/fe-no-tests.mjs';
 import { byCodeUnit } from '../../lib/list.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).
@@ -15,29 +14,31 @@ import { byCodeUnit } from '../../lib/list.mjs';
  * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
  */
 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(byCodeUnit)) {
-    if (isFeTestPath(file)) continue;   // FE_NO_TESTS's, the one finding of that file
-    const classified = resolver.classifyPath(file);
-    if (classified.status !== 'owned') continue;
-    const slot = resolver.slot(classified.slot);
-    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 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(byCodeUnit)) {
+        if (isFeTestPath(file))
+            continue; // FE_NO_TESTS's, the one finding of that file
+        const classified = resolver.classifyPath(file);
+        if (classified.status !== 'owned')
+            continue;
+        const slot = resolver.slot(classified.slot);
+        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 });
     }
-    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 } };
+    return { violations, coverage: { status: 'checked', files } };
 }

package/runtime/scripts/hfs/architecture/feature-shape.d.mts

@@ -0,0 +1,26 @@
+import type { ArchitectureConfig } from './config.mjs';
+import type { Violation } from './ast-walks.mjs';
+import type { Resolver } from '../slots.mjs';
+export interface FeatureShapeResult {
+    violations: Violation[];
+    coverage: {
+        status: 'checked';
+        features: number;
+        files: number;
+    };
+}
+/**
+ * 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.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 declare const FEATURE_SHAPE_RULE_IDS: string[];
+export declare function checkFeatureShape({ config, graph }: {
+    config: ArchitectureConfig;
+    graph: {
+        resolver: Resolver;
+    };
+}): FeatureShapeResult;

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

@@ -2,7 +2,6 @@ import path from 'node:path';
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../allows.mjs';
 import { byCodeUnit } from '../../lib/list.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/
@@ -12,47 +11,50 @@ import { byCodeUnit } from '../../lib/list.mjs';
  * `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';
-
 // {message, extra} for one feature file the slot answer refuses, or null when it sits where a slot allows it.
 const featureFileFinding = (file, owner, verdict) => {
-  const feature = path.posix.basename(owner.root);
-  if (verdict.slot === owner.slot) {
-    // A file the feature root slot itself allows is in place (the cli feature root allows its <group>/ folders); any other file
-    // deeper than the root sits in a directory no slot claims.
-    // A directory entry (`transport/`, `application/`) is held by its own slots: below it, only those slots admit a file.
-    if (verdict.allowed && !String(verdict.entry ?? '').endsWith('/')) return null;
-    if (verdict.relative.includes('/')) {
-      const folder = verdict.relative.split('/')[0];
-      return { message: `${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.`,
-        extra: { feature, folder } };
+    const feature = path.posix.basename(owner.root);
+    if (verdict.slot === owner.slot) {
+        // A file the feature root slot itself allows is in place (the cli feature root allows its <group>/ folders); any other file
+        // deeper than the root sits in a directory no slot claims.
+        // A directory entry (`transport/`, `application/`) is held by its own slots: below it, only those slots admit a file.
+        if (verdict.allowed && !String(verdict.entry ?? '').endsWith('/'))
+            return null;
+        if (verdict.relative.includes('/')) {
+            const folder = verdict.relative.split('/')[0] ?? '';
+            return { message: `${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.`,
+                extra: { feature, folder } };
+        }
+        if (verdict.allowed)
+            return null;
+        return { message: `${file} is not allowed at the root of feature ${feature}; the root holds only ${verdict.allows.join(', ')}. Move it under application/ or transport/<protocol>/.`, extra: { feature } };
     }
-    if (verdict.allowed) return null;
-    return { message: `${file} is not allowed at the root of feature ${feature}; the root holds only ${verdict.allows.join(', ')}. Move it under application/ or transport/<protocol>/.`, extra: { feature } };
-  }
-  if (verdict.allowed) return null;
-  const where = `${verdict.slot} (${verdict.root})`;
-  const forbidden = verdict.forbiddenBy ? ` ${verdict.forbiddenBy} is forbidden there;` : '';
-  return { message: `${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.`, extra: { feature, slot: verdict.slot } };
+    if (verdict.allowed)
+        return null;
+    const where = `${verdict.slot} (${verdict.root})`;
+    const forbidden = verdict.forbiddenBy ? ` ${verdict.forbiddenBy} is forbidden there;` : '';
+    return { message: `${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.`, extra: { feature, slot: verdict.slot } };
 };
-
 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(byCodeUnit)) {
-    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 finding = featureFileFinding(file, owner, verdict);
-    if (finding) report(file, finding.message, finding.extra);
-  }
-  return { violations, coverage: { status: 'checked', features: features.size, files } };
+    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(byCodeUnit)) {
+        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 finding = featureFileFinding(file, owner, verdict);
+        if (finding)
+            report(file, finding.message, finding.extra);
+    }
+    return { violations, coverage: { status: 'checked', features: features.size, files } };
 }

package/runtime/scripts/hfs/architecture/framework-pinned.d.mts

@@ -0,0 +1,3 @@
+export declare const FRAMEWORK_PINNED_KNOWLEDGE: string;
+/** Exact basenames Next.js loads only from the source root. */
+export declare function frameworkPinnedRootFiles(file?: string): Set<string>;

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

@@ -8,34 +8,34 @@
 import fs from 'node:fs';
 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 new Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
+    return new Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
 }
-
 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 loaded = { files: new Set(list) };
-  if (file === FRAMEWORK_PINNED_KNOWLEDGE) cache.set(file, loaded);
-  return loaded;
+    const cached = cache.get(file);
+    if (cached)
+        return cached;
+    // reason: parsed-YAML boundary; the rule row is validated field by field below.
+    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 loaded = { files: new Set(list) };
+    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;
+    return load(file).files;
 }

package/runtime/scripts/hfs/architecture/frontend-block-render.d.mts

@@ -0,0 +1,26 @@
+import type { CallExpression, JsxElement, JsxFragment, JsxSelfClosingElement, Node, Symbol as TsSymbol, TypeChecker } from 'typescript';
+import type { WorldFunction } from './frontend-world.mjs';
+import type { WorldRenderAnalysis } from './frontend-world-render.mjs';
+/** The world analysis that owns the renderer, with the component-tier helper the block checks also read. */
+type BlockWorld = WorldRenderAnalysis['world'] & {
+    tierOf: (componentRoots: string[], fileName: string) => {
+        tier: string;
+    } | null;
+};
+/** Feature composition may inject block renders into a pure view without making the view a world owner. */
+export declare class BlockRenderAnalysis {
+    readonly renderer: WorldRenderAnalysis;
+    readonly world: BlockWorld;
+    constructor(renderer: WorldRenderAnalysis);
+    featureComposition(expression: Node | null | undefined, expectedFile: string | null | undefined): boolean;
+    renderProp(expression: Node | null | undefined, checker: TypeChecker, expectedFile: string | null | undefined): boolean;
+    blockTarget(expression: Node, checker: TypeChecker): boolean;
+    callbacksRender(functions: WorldFunction[], checker: TypeChecker, seen?: Set<TsSymbol>): boolean;
+    renderValue(input: Node | null | undefined, checker: TypeChecker, seen?: Set<TsSymbol>): boolean;
+    fragmentBlocks(value: JsxFragment, checker: TypeChecker, seen: Set<TsSymbol>): boolean;
+    jsxBlock(value: JsxElement | JsxSelfClosingElement, checker: TypeChecker, seen: Set<TsSymbol>): boolean;
+    mappedBlocks(value: CallExpression, checker: TypeChecker, seen: Set<TsSymbol>): boolean;
+    createdBlock(value: CallExpression, checker: TypeChecker, seen: Set<TsSymbol>): boolean;
+    referencedBlocks(value: Node, checker: TypeChecker, seen: Set<TsSymbol>): boolean;
+}
+export {};