@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/architecture/test-world-files.mjs

@@ -5,7 +5,6 @@ import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService,
 import { unwrapEach } from './ast-walks.mjs';
 import { hasAnyFlag, nameText, sourceLocation } from '../../lib/ts-ast.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
-
 /**
  * R47 `test-world-files` (BE_TEST_TOPOLOGY). Judgements over the test world, read through slots, the repository's own
  * stack definition (`.starcistacks/<env>`, scripts/lib/stack-services.mjs) and the world's declaration
@@ -33,7 +32,6 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *    nothing else of it.
  */
 export const TEST_WORLD_FILES_RULE_IDS = ['BE_TEST_TOPOLOGY'];
-
 const RULE = 'BE_TEST_TOPOLOGY';
 const WORLD_SLOT = 'be.tests.world';
 const FAKES_DIRECTORY = 'fakes/';
@@ -42,193 +40,205 @@ const DEFINE = 'defineTestWorld';
 const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-
 const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
-const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameText(ts, property.name) === key)?.initializer ?? null;
+const propertyOf = (ts, literal, key) => literal.properties.find((property) => ts.isPropertyAssignment(property) && nameText(ts, property.name) === key)?.initializer ?? null;
 const isExported = (ts, statement) => (statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
-
 /** The object literal of `defineTestWorld(<object literal>)`, or null. */
 function defineLiteral(ts, expression) {
-  const call = unwrap(ts, expression);
-  if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== DEFINE) return null;
-  const [first] = call.arguments;
-  const literal = first ? unwrap(ts, first) : null;
-  return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
+    const call = unwrap(ts, expression);
+    if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== DEFINE)
+        return null;
+    const [first] = call.arguments;
+    const literal = first ? unwrap(ts, first) : null;
+    return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
 }
-
 /** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
 function configLiteral(ts, sourceFile) {
-  for (const statement of sourceFile.statements) {
-    if (!ts.isVariableStatement(statement) || !isExported(ts, statement)) continue;
-    if (!hasAnyFlag(statement.declarationList.flags, ts.NodeFlags.Const)) continue;
-    for (const declaration of statement.declarationList.declarations) {
-      const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
-      if (literal) return literal;
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+            continue;
+        if (!hasAnyFlag(statement.declarationList.flags, ts.NodeFlags.Const))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
+            if (literal)
+                return literal;
+        }
     }
-  }
-  return null;
+    return null;
 }
-
 /** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
 function environmentOf(ts, literal) {
-  const node = literal ? propertyOf(ts, literal, 'stack') : null;
-  const value = node ? unwrap(ts, node) : null;
-  if (!value || !ts.isStringLiteralLike(value)) return null;
-  return value.text.split(/[\\/]+/u).filter(Boolean).findLast(Boolean) ?? null;
+    const node = literal ? propertyOf(ts, literal, 'stack') : null;
+    const value = node ? unwrap(ts, node) : null;
+    if (!value || !ts.isStringLiteralLike(value))
+        return null;
+    return value.text.split(/[\\/]+/u).filter(Boolean).findLast(Boolean) ?? null;
 }
-
 /** The keys of the declaration's `fakes` object literal, with their positions. */
 function fakeEntriesOf(ts, sourceFile, literal) {
-  const node = literal ? propertyOf(ts, literal, 'fakes') : null;
-  const value = node ? unwrap(ts, node) : null;
-  if (!value || !ts.isObjectLiteralExpression(value)) return [];
-  return value.properties
-    .map(property => ({ name: nameText(ts, property.name), ...sourceLocation(sourceFile, property) }))
-    .filter(entry => entry.name);
-}
-
+    const node = literal ? propertyOf(ts, literal, 'fakes') : null;
+    const value = node ? unwrap(ts, node) : null;
+    if (!value || !ts.isObjectLiteralExpression(value))
+        return [];
+    return value.properties
+        .map(property => ({ name: nameText(ts, property.name), ...sourceLocation(sourceFile, property) }))
+        .filter((entry) => Boolean(entry.name));
+}
 /** The `fakedBy` entry of one `stacks` property, or null when the property does not declare one. */
 function fakedByEntry(ts, sourceFile, property) {
-  if (!ts.isPropertyAssignment(property)) return null;
-  const body = unwrap(ts, property.initializer);
-  if (!body || !ts.isObjectLiteralExpression(body)) return null;
-  const fake = propertyOf(ts, body, 'fakedBy');
-  if (!fake) return null;
-  const reason = propertyOf(ts, body, 'reason');
-  return {
-    service: nameText(ts, property.name),
-    fake: ts.isStringLiteralLike(fake) ? fake.text : '',
-    reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
-    ...sourceLocation(sourceFile, property),
-  };
-}
-
+    if (!ts.isPropertyAssignment(property))
+        return null;
+    const body = unwrap(ts, property.initializer);
+    if (!body || !ts.isObjectLiteralExpression(body))
+        return null;
+    const fake = propertyOf(ts, body, 'fakedBy');
+    if (!fake)
+        return null;
+    const reason = propertyOf(ts, body, 'reason');
+    return {
+        service: nameText(ts, property.name),
+        fake: ts.isStringLiteralLike(fake) ? fake.text : '',
+        reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
+        ...sourceLocation(sourceFile, property),
+    };
+}
 /** The `stacks` entries that declare `fakedBy`: [{service, fake, reason, line, column}]; a value the reader cannot read statically has an empty fake and reason. */
 function fakedByOf(ts, sourceFile, literal) {
-  const node = literal ? propertyOf(ts, literal, 'stacks') : null;
-  const value = node ? unwrap(ts, node) : null;
-  if (!value || !ts.isObjectLiteralExpression(value)) return [];
-  return value.properties.map(property => fakedByEntry(ts, sourceFile, property)).filter(Boolean);
+    const node = literal ? propertyOf(ts, literal, 'stacks') : null;
+    const value = node ? unwrap(ts, node) : null;
+    if (!value || !ts.isObjectLiteralExpression(value))
+        return [];
+    return value.properties.map(property => fakedByEntry(ts, sourceFile, property)).filter((entry) => entry !== null);
 }
-
 function registerFakeProvider(fakeProviders, relative, file) {
-  if (!relative.startsWith(FAKES_DIRECTORY)) return;
-  const [provider, ...rest] = relative.slice(FAKES_DIRECTORY.length).split('/');
-  if (rest.length > 0 && !fakeProviders.has(provider)) fakeProviders.set(provider, file);
+    if (!relative.startsWith(FAKES_DIRECTORY))
+        return;
+    const [provider, ...rest] = relative.slice(FAKES_DIRECTORY.length).split('/');
+    if (provider !== undefined && rest.length > 0 && !fakeProviders.has(provider))
+        fakeProviders.set(provider, file);
 }
-
 function isRoleFileAtRoot(relative, suffixes) {
-  const parts = relative.slice(0, -'.ts'.length).split('.');
-  return !relative.includes('/') && parts.length >= 2 && parts.every(part => KEBAB.test(part)) && suffixes.includes(parts.at(-1));
+    const parts = relative.slice(0, -'.ts'.length).split('.');
+    return !relative.includes('/') && parts.length >= 2 && parts.every(part => KEBAB.test(part)) && suffixes.includes(parts.at(-1) ?? '');
 }
-
 function collectWorldFiles(resolver, tree, suffixes, violations) {
-  const fakeProviders = new Map();
-  let worldRoot = null;
-  let files = 0;
-  for (const file of [...tree.files].sort(byCodeUnit)) {
-    if (!file.endsWith('.ts')) continue;
-    const verdict = allowsFile(resolver, file);
-    if (verdict?.slot !== WORLD_SLOT) continue;
-    files += 1;
-    worldRoot ??= file.slice(0, file.length - verdict.relative.length);
-    registerFakeProvider(fakeProviders, verdict.relative, file);
-    if (verdict.allowed || isRoleFileAtRoot(verdict.relative, suffixes)) continue;
-    violations.push({
-      ruleId: RULE, path: file, line: 1, column: 1,
-      message: `${file} is not allowed in the test world; src/tests/world/ holds only ${verdict.allows.join(', ')} and role-suffixed files (<name>.<role>.ts) at its root. Move it to fakes/ or kit/ (be.tests.world.kit), give it a role suffix, or delete it.`,
-      slot: verdict.slot,
-    });
-  }
-  return { fakeProviders, worldRoot, files };
-}
-
-function worldDeclaration(config, graph, ts, worldRoot, violations) {
-  const configPath = worldRoot === null ? null : `${worldRoot}${CONFIG_FILE}`;
-  const configFile = configPath === null ? null : graph.files.get(configPath) ?? null;
-  const literal = configFile ? configLiteral(ts, configFile.sourceFile) : null;
-  if (configFile && !literal) {
-    violations.push({
-      ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
-      message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
-    });
-  }
-  return { configPath, configFile, literal };
-}
-
+    const fakeProviders = new Map();
+    let worldRoot = null;
+    let files = 0;
+    for (const file of [...tree.files].sort(byCodeUnit)) {
+        if (!file.endsWith('.ts'))
+            continue;
+        const verdict = allowsFile(resolver, file);
+        if (verdict?.slot !== WORLD_SLOT)
+            continue;
+        files += 1;
+        worldRoot ??= file.slice(0, file.length - verdict.relative.length);
+        registerFakeProvider(fakeProviders, verdict.relative, file);
+        if (verdict.allowed || isRoleFileAtRoot(verdict.relative, suffixes))
+            continue;
+        violations.push({
+            ruleId: RULE, path: file, line: 1, column: 1,
+            message: `${file} is not allowed in the test world; src/tests/world/ holds only ${verdict.allows.join(', ')} and role-suffixed files (<name>.<role>.ts) at its root. Move it to fakes/ or kit/ (be.tests.world.kit), give it a role suffix, or delete it.`,
+            slot: verdict.slot,
+        });
+    }
+    return { fakeProviders, worldRoot, files };
+}
+function worldDeclaration(graph, ts, worldRoot, violations) {
+    const configPath = worldRoot === null ? null : `${worldRoot}${CONFIG_FILE}`;
+    const configFile = configPath === null ? null : graph.files.get(configPath) ?? null;
+    const literal = configFile ? configLiteral(ts, configFile.sourceFile) : null;
+    if (configFile && !literal) {
+        violations.push({
+            ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
+            message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
+        });
+    }
+    return { configPath, configFile, literal };
+}
 function stackServices(config, environments) {
-  const services = [];
-  for (const environment of environments) {
-    let stack = null;
-    // The stack is the app root's .starcistacks: the side folder the machine judges reads its app's (locateDeclaration).
-    try { stack = readStack({ root: locateDeclaration(config.root).appRoot, environment }); } catch { stack = null; }
-    for (const service of stack?.services ?? []) if (service.role !== 'service' && !services.some(known => known.name === service.name)) services.push({ ...service, environment });
-  }
-  return services;
-}
-
+    const services = [];
+    for (const environment of environments) {
+        let stack = null;
+        // The stack is the app root's .starcistacks: the side folder the machine judges reads its app's (locateDeclaration).
+        try {
+            stack = readStack({ root: locateDeclaration(config.root).appRoot, environment });
+        }
+        catch {
+            stack = null;
+        }
+        for (const service of stack?.services ?? [])
+            if (service.role !== 'service' && !services.some(known => known.name === service.name))
+                services.push({ ...service, environment });
+    }
+    return services;
+}
 function statefulWhy(service) {
-  if (STATEFUL_KINDS.has(service.kind)) return `a ${service.kind} holds data the app reads back`;
-  return service.persistent ? 'the stack gives it a persistent volume' : null;
+    if (STATEFUL_KINDS.has(service.kind))
+        return `a ${service.kind} holds data the app reads back`;
+    return service.persistent ? 'the stack gives it a persistent volume' : null;
 }
-
 function reportDeclaredFakeProblems(declared, services, fakeProviders, fakeEntries, configPath, stackHint, violations) {
-  for (const entry of declared) {
-    const service = services.find(candidate => candidate.name === entry.service);
-    const problems = [];
-    if (!service) problems.push(`${stackHint} declares no service ${entry.service}`);
-    else if (statefulWhy(service)) problems.push(`${service.name} is stateful (${statefulWhy(service)}) and always runs real`);
-    if (!fakeProviders.has(entry.fake) && !fakeEntries.some(fake => fake.name === entry.fake)) problems.push(`there is no fakes entry and no fakes/${entry.fake || '<fake>'}/ folder of that name`);
-    if (entry.reason === '') problems.push('the reason is empty');
-    if (problems.length > 0) {
-      violations.push({
-        ruleId: RULE, path: configPath, line: entry.line, column: entry.column, slot: WORLD_SLOT,
-        message: `${configPath} declares ${entry.service} as faked by ${entry.fake || '(no fake)'}, but ${problems.join('; ')}. The exception covers only stateless compute that needs special hardware or an external model, with a reason; everything else in the stack runs real.`,
-      });
+    for (const entry of declared) {
+        const service = services.find(candidate => candidate.name === entry.service);
+        const problems = [];
+        if (!service)
+            problems.push(`${stackHint} declares no service ${entry.service}`);
+        else if (statefulWhy(service))
+            problems.push(`${service.name} is stateful (${statefulWhy(service)}) and always runs real`);
+        if (!fakeProviders.has(entry.fake) && !fakeEntries.some(fake => fake.name === entry.fake))
+            problems.push(`there is no fakes entry and no fakes/${entry.fake || '<fake>'}/ folder of that name`);
+        if (entry.reason === '')
+            problems.push('the reason is empty');
+        if (problems.length > 0) {
+            violations.push({
+                ruleId: RULE, path: configPath, line: entry.line, column: entry.column, slot: WORLD_SLOT,
+                message: `${configPath} declares ${entry.service} as faked by ${entry.fake || '(no fake)'}, but ${problems.join('; ')}. The exception covers only stateless compute that needs special hardware or an external model, with a reason; everything else in the stack runs real.`,
+            });
+        }
     }
-  }
 }
-
 function worldFakes(fakeProviders, fakeEntries, configPath) {
-  return [
-    ...[...fakeProviders].map(([provider, file]) => ({ name: provider, path: file, line: 1, column: 1, what: `fakes/${provider}/` })),
-    ...fakeEntries.filter(entry => !fakeProviders.has(entry.name)).map(entry => ({ name: entry.name, path: configPath, line: entry.line, column: entry.column, what: `the fakes entry ${entry.name}` })),
-  ].sort((a, b) => a.name.localeCompare(b.name));
+    return [
+        ...[...fakeProviders].map(([provider, file]) => ({ name: provider, path: file, line: 1, column: 1, what: `fakes/${provider}/` })),
+        ...fakeEntries.filter(entry => !fakeProviders.has(entry.name)).map(entry => ({ name: entry.name, path: configPath, line: entry.line, column: entry.column, what: `the fakes entry ${entry.name}` })),
+    ].sort((a, b) => a.name.localeCompare(b.name));
 }
-
 function reportServiceFakes(fakes, services, declared, configPath, stackHint, violations) {
-  for (const fake of fakes) {
-    const service = services.find(candidate => namesOfService(candidate).includes(fake.name));
-    if (!service) continue;
-    if (declared.some(entry => entry.service === service.name && entry.fake === fake.name)) continue; // judged on its stacks entry above
-    const why = statefulWhy(service);
-    let reason = `${service.name} is stateful (${why}), so no exception applies. `;
-    if (!why) {
-      const worldConfig = configPath ?? `${CONFIG_FILE} in the world`;
-      reason = `Only stateless compute that needs special hardware or an external model may be faked, and only when ${worldConfig} declares it in its stacks entry ({ fakedBy, reason }). `;
+    for (const fake of fakes) {
+        const service = services.find(candidate => namesOfService(candidate).includes(fake.name));
+        if (!service)
+            continue;
+        if (declared.some(entry => entry.service === service.name && entry.fake === fake.name))
+            continue; // judged on its stacks entry above
+        const why = statefulWhy(service);
+        let reason = `${service.name} is stateful (${why}), so no exception applies. `;
+        if (!why) {
+            const worldConfig = configPath ?? `${CONFIG_FILE} in the world`;
+            reason = `Only stateless compute that needs special hardware or an external model may be faked, and only when ${worldConfig} declares it in its stacks entry ({ fakedBy, reason }). `;
+        }
+        violations.push({
+            ruleId: RULE, path: fake.path, line: fake.line, column: fake.column, slot: WORLD_SLOT,
+            message: `${fake.what} fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${reason}Delete the fake and let the world run the real service; fakes are otherwise only for external SaaS the team does not operate.`,
+        });
     }
-    violations.push({
-      ruleId: RULE, path: fake.path, line: fake.line, column: fake.column, slot: WORLD_SLOT,
-      message: `${fake.what} fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${reason}Delete the fake and let the world run the real service; fakes are otherwise only for external SaaS the team does not operate.`,
-    });
-  }
 }
-
 export function checkTestWorldFiles(input) {
-  const { config, graph, ts, resolver, tree } = checkerScope(input);
-  const { suffixes } = resolver.ruleParams();
-  const violations = [];
-  const { fakeProviders, worldRoot, files } = collectWorldFiles(resolver, tree, suffixes, violations);
-  const { configPath, configFile, literal } = worldDeclaration(config, graph, ts, worldRoot, violations);
-  const environments = [(literal ? environmentOf(ts, literal) : null) ?? defaultEnvironment];
-  const services = stackServices(config, environments);
-  const stackHint = `${STACKS_DIRECTORY}/${environments.join(', ')}`;
-  const declared = literal ? fakedByOf(ts, configFile.sourceFile, literal) : [];
-  const fakeEntries = literal ? fakeEntriesOf(ts, configFile.sourceFile, literal) : [];
-  reportDeclaredFakeProblems(declared, services, fakeProviders, fakeEntries, configPath, stackHint, violations);
-
-  // Every fake the world runs: the repository's fakes/<provider>/ folders and the fakes entries of the declaration.
-  const fakes = worldFakes(fakeProviders, fakeEntries, configPath);
-  reportServiceFakes(fakes, services, declared, configPath, stackHint, violations);
-  return { violations, coverage: { status: 'checked', files } };
+    const { config, graph, ts, resolver, tree } = checkerScope(input);
+    const suffixes = graph.resolver.ruleParams()?.suffixes ?? [];
+    const violations = [];
+    const { fakeProviders, worldRoot, files } = collectWorldFiles(resolver, tree, suffixes, violations);
+    const { configPath, configFile, literal } = worldDeclaration(graph, ts, worldRoot, violations);
+    const environments = [(literal ? environmentOf(ts, literal) : null) ?? defaultEnvironment];
+    const services = stackServices(config, environments);
+    const stackHint = `${STACKS_DIRECTORY}/${environments.join(', ')}`;
+    const worldSource = configFile?.sourceFile;
+    const declared = literal && worldSource ? fakedByOf(ts, worldSource, literal) : [];
+    const fakeEntries = literal && worldSource ? fakeEntriesOf(ts, worldSource, literal) : [];
+    reportDeclaredFakeProblems(declared, services, fakeProviders, fakeEntries, configPath, stackHint, violations);
+    // Every fake the world runs: the repository's fakes/<provider>/ folders and the fakes entries of the declaration.
+    const fakes = worldFakes(fakeProviders, fakeEntries, configPath);
+    reportServiceFakes(fakes, services, declared, configPath, stackHint, violations);
+    return { violations, coverage: { status: 'checked', files } };
 }

package/runtime/scripts/hfs/architecture/tiers.d.mts

@@ -0,0 +1,29 @@
+import type { ArchitectureViolation, HfsGraph } from './hfs-graph.mjs';
+/**
+ * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
+ *   1. the tier direction matrix: every import, re-export and type-only import between two owners must go from a tier to
+ *      a tier its `mayImport` lists (BE_TIER_DIRECTION / FE_TIER_DIRECTION); a backend feature importing another feature
+ *      is the one direction with its own code (BE_FEATURE_IMPORTS_FEATURE, R28), never BE_TIER_DIRECTION, and a feature of one trigger
+ *      kind (slot field `trigger`: api, webhooks, realtime, saga, reactors, jobs, cli) importing a feature of another is
+ *      BE_KIND_ISOLATION, whose fix is the event bus,
+ *      an app never imports another app (BE_SERVICE_ISOLATION / FE_APP_ISOLATION), and a component layer imports only the layers after it;
+ *      the entity registry naming a capability's `<c>Entities` from its public entry is the one platform-to-domain edge (entity-registry.mjs);
+ *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE), the entity
+ *      registry counted as a unit of its own,
+ *      reported with the cycle path and the import that closes each hop.
+ * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
+ */
+export declare const TIER_RULE_IDS: string[];
+export declare function checkTiers(graph: HfsGraph): {
+    violations: ArchitectureViolation[];
+    coverage: {
+        tierDirection: number;
+        layerOrder: number;
+        crossApp: number;
+        ownerUnits: number;
+        cycles: number;
+        edgesChecked: number;
+        unclassifiedEdges: number;
+        status: string;
+    };
+};