@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/architecture/next-data.mjs

@@ -3,9 +3,11 @@ import { canonical, isInside } from './config.mjs';
 import { parseContract, installedSWR } from './next-data-contract.mjs';
 import { relativePath, unwrapExpression } from './typescript.mjs';
 import { anyDescendant, normalizedSymbol, normalizedSymbolValue, valueSymbol as sharedValueSymbol } from './ast-walks.mjs';
-import { isConstVariable, sourceLocation } from '../../lib/ts-ast.mjs';
+import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { createNextDataKeyInspector } from './next-data-key.mjs';
+import { functionNode, constInitializer, inferredSymbol } from './next-data-symbols.mjs';
+import { inferredFetcher, inferredIdentities, inferredKeyBindings } from './next-data-inference.mjs';
 export const SWR_KEY_RULE_ID = 'FE_SWR_KEY_IDENTITY';
 export const SWR_MUTATION_RULE_ID = 'FE_SWR_MUTATION_RESOURCE_IDENTITY';
 export const SWR_DATA_RULE_IDS = [SWR_KEY_RULE_ID, SWR_MUTATION_RULE_ID];
@@ -155,15 +157,6 @@ function discoverCalls(config, context, targets) {
   return calls;
 }
 
-function functionNode(ts, declaration) {
-  if (ts.isFunctionDeclaration(declaration) && declaration.body) return declaration;
-  if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
-    const value = unwrapExpression(ts, declaration.initializer);
-    if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) return value;
-  }
-  return null;
-}
-
 function exportedHook(config, context, entry, reasons) {
   const source = context.files.find(candidate => canonical(candidate.fileName) === canonical(path.join(config.root, ...entry.path.split('/'))));
   if (!source) {
@@ -223,19 +216,15 @@ function resolvedIdentities(ts, checker, fn, entry, reasons) {
   return identities.length === entry.identities.length ? identities : null;
 }
 
-function constInitializer(ts, symbol) {
-  const declarations = symbol?.getDeclarations?.() ?? [];
-  if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || !declarations[0].initializer
-    || !isConstVariable(ts, declarations[0])) return null;
-  return declarations[0].initializer;
-}
-
 function violation(config, call, ruleId, message, extra = {}) {
   return { ruleId, path: relativePath(config.root, call.source.fileName), ...sourceLocation(call.source, call.node), message, ...extra };
 }
 
-const inspectKey = createNextDataKeyInspector({ anyDescendant, normalizedSymbol, unwrapExpression, constInitializer, sourceLocation, violation,
-  SWR_KEY_RULE_ID, SWR_MUTATION_RULE_ID });
+const keyInspectorDependencies = { anyDescendant, normalizedSymbol, unwrapExpression, constInitializer, sourceLocation, violation,
+  SWR_KEY_RULE_ID, SWR_MUTATION_RULE_ID };
+const inspectKey = createNextDataKeyInspector(keyInspectorDependencies);
+
+const inspectInferredKey = createNextDataKeyInspector({ ...keyInspectorDependencies, normalizedSymbol: inferredSymbol });
 
 function isUnshadowedCommonJsRequire(ts, checker, expression, seen = new Set(), depth = 0) {
   expression = unwrapExpression(ts, expression);
@@ -372,7 +361,26 @@ function lifecycleCoverage(ruleIds, contract, installed, calls, details) {
       swr: { name: installed.name, version: installed.version, major: installed.major } };
 }
 
-/** Check explicitly declared SWR lifecycle keys against the target program and installed SWR identity. */
+function inspectDefaultLifecycle(config, context, installed, lifecycleCalls, violations, reasons) {
+  for (const call of lifecycleCalls) {
+    const fetcher = inferredFetcher(context.ts, call.checker, call.node.arguments[1]);
+    if (!fetcher) {
+      reasons.push(`${relativePath(config.root, call.source.fileName)}:${sourceLocation(call.source, call.node).line} fetcher inputs cannot be inferred; dataLifecycle is required to declare identities`);
+      continue;
+    }
+    const entry = { id: `swr:${relativePath(config.root, call.source.fileName)}:${sourceLocation(call.source, call.node).line}`,
+      path: relativePath(config.root, call.source.fileName), export: call.owner?.name?.text ?? '<inferred hook>', kind: call.kind };
+    const identities = inferredIdentities(context, call, fetcher, reasons);
+    const selected = new Set(identities.map(identity => identity.id));
+    const findings = [];
+    inspectInferredKey(config, context, entry, call, [...identities, ...inferredKeyBindings(context, call, reasons)], findings, reasons);
+    violations.push(...findings.filter(finding => finding.identity === undefined || selected.has(finding.identity)));
+  }
+  const details = [...new Set(reasons)].sort(byCodeUnit);
+  return { violations, coverage: lifecycleCoverage([...SWR_DATA_RULE_IDS], { hooks: lifecycleCalls }, installed, lifecycleCalls.length, details) };
+}
+
+/** Check declared lifecycles, or infer captured request identities when production SWR has no declaration. */
 export function checkFrontendDataLifecycle(config, context) {
   const ruleIds = [...SWR_DATA_RULE_IDS];
   const references = swrReferences(config, context);
@@ -381,17 +389,17 @@ export function checkFrontendDataLifecycle(config, context) {
     return unavailableDataLifecycle(ruleIds, [String(error.message ?? error)]);
   }
   if (!contract && !references.found) return { violations: [], coverage: { status: 'not-applicable', ruleIds } };
-  if (!contract) return { violations: [], coverage: { status: 'unavailable', ruleIds,
-    details: ['package.json#starci.codePatterns.next.dataLifecycle is required when production source selects SWR', ...references.unsupported] } };
   const reasons = [];
   const violations = [];
   reasons.push(...references.unsupported);
+  if (!contract && references.unsupported.length) reasons.push('package.json#starci.codePatterns.next.dataLifecycle is required for unsupported SWR bindings');
   let installed;
   try { installed = installedSWR(config.packageRoot ?? config.root); } catch (error) {
     return { violations, coverage: { status: 'unavailable', ruleIds, details: [String(error.message ?? error)] } };
   }
-  if (installed.major !== contract.swr.major) reasons.push(`installed swr ${installed.version} does not match declared major ${contract.swr.major}`);
+  if (contract && installed.major !== contract.swr.major) reasons.push(`installed swr ${installed.version} does not match declared major ${contract.swr.major}`);
   const { lifecycleCalls } = lifecycleCallSets(config, context, installed, reasons);
+  if (!contract) return inspectDefaultLifecycle(config, context, installed, lifecycleCalls, violations, reasons);
   const { hookCache, entriesByHook } = hookEntries(config, context, contract, reasons);
   inspectHookLifecycle(config, context, lifecycleCalls, hookCache, entriesByHook, violations, reasons);
   addUndeclaredLifecycleReasons(config, lifecycleCalls, hookCache, reasons);

package/runtime/scripts/hfs/architecture/reachability.mjs

@@ -96,9 +96,23 @@ function checkBackend(graph) {
   const reached = reachFrom(graph, rootFiles);
   const violations = [];
   reportUncomposedBackendOwners(byUnit, reached, roots, counts, violations);
+  reportUncomposedTransports(graph, reached, roots, counts, violations);
   return { violations, coverage: { status: 'checked', ...counts } };
 }
 
+/** A reached feature does not compose its other transport modules. Judge each module's runtime path. */
+function reportUncomposedTransports(graph, reached, roots, counts, violations) {
+  for (const [rel, node] of graph.files) {
+    if (!node.owner || !rel.startsWith('src/features/') || TEST_FILE.test(rel)) continue;
+    if (!/\/transport\/[^/]+\/[^/]+\.module\.[cm]?[jt]sx?$/.test(rel) || reached.has(rel)) continue;
+    counts.notComposed += 1;
+    violations.push({
+      ruleId: 'BE_FEATURE_NOT_COMPOSED', path: rel, owner: node.owner.root, slot: node.slot, appRoots: roots,
+      message: `Transport module ${rel} is not composed into any app: no runtime import path leads from ${roots.join(', ')} to it (a type-only import composes nothing).`,
+    });
+  }
+}
+
 /** Route table of one app: arrays of segments, each {kind:'static'|'dyn'|'catch'|'optcatch', text}. */
 function routeSegmentsOf(parts) {
   const segments = [];

package/runtime/scripts/hfs/architecture/register-once.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { machineKit } from './machine-ast.mjs';
+import { isComposeGroup, machineKit } from './machine-ast.mjs';
 import { callName } from './supabase-ast.mjs';
 import { isTestWorldSlot } from '../test-world-slot.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
@@ -7,14 +7,15 @@ import { byCodeUnit } from '../../lib/list.mjs';
 /**
  * R45 `register-once` (BE_MODULE_SHAPE), the module graph read from the app roots (owner rule of 2026-09-30, the
  * reference's `CodingModule imports DeviceModule` shape). Each capability has one representative module: the only module
- * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`.
- * It may split itself into sub-modules imported as plain `imports: [Sub]`; a sub-module is never in an app and has one
+ * of the capability an app registers, once, in `apps/<app>/src/app.module.ts` as `X.register({ isGlobal: true, ... })`, or in a
+ * composition group `apps/<app>/src/compose/<area>.ts` the root spreads (an app root here means the root and its groups).
+ * It may split itself into sub-modules imported as `imports: [Sub.register({})]`; a sub-module is never in an app and has one
  * importer, its parent. Over every `@Module` class of the program:
  *
  *   - a module in an app root's imports (a `X.register(...)` call or a listed class, helpers of the root included) is
  *     listed once there, is imported by no other module, and, when it is a capability module of src/modules, is registered
  *     with the literal `isGlobal: true` (a bare capability class is not a registration);
- *   - a module imported by a non-app module has exactly one importer and appears in no app root; the one exception is
+ *   - a module imported by a non-app module (as `Sub.register({})`) has exactly one importer and appears in no app root; the one exception is
  *     the feature case: a feature's application module is imported by each protocol module of the same feature;
  *   - `isGlobal: true` appears only in an app root.
  */
@@ -57,6 +58,7 @@ function enclosingModule(ts, modules, node) {
 /** Records the reference an element of an imports list, or a register call, makes to a module. */
 function noteReference(scan, element, viaImports) {
   const { ts, kit, modules, checker, file, seen, references, isAppRoot } = scan;
+  if (seen.has(element)) return;
   const call = callName(ts, element) === 'register';
   if (ts.isCallExpression(element) && !call) return;
   const target = targetOf(kit, modules, checker, call ? element.expression.expression : element);
@@ -72,14 +74,19 @@ const isImportsList = (scan, node) => scan.ts.isPropertyAssignment(node) && scan
 const isStrayGlobal = (scan, node) => scan.ts.isPropertyAssignment(node) && scan.kit.propertyNameText(node.name) === 'isGlobal'
   && node.initializer.kind === scan.ts.SyntaxKind.TrueKeyword && !scan.isAppRoot(scan.file) && !scan.isWorld(scan.file);
 
+// A composition group's module list is any array of the group: the root spreads it into its imports.
+const isGroupList = (scan, node) => scan.ts.isArrayLiteralExpression(node) && isComposeGroup(scan.file.rel);
+
 function visitReferenceNode(scan, node) {
   if (isImportsList(scan, node)) {
     for (const element of node.initializer.elements) noteReference(scan, element, true);
+  } else if (isGroupList(scan, node)) {
+    for (const element of node.elements) noteReference(scan, element, true);
   } else if (callName(scan.ts, node) === 'register' && !scan.seen.has(node)) {
     noteReference(scan, node, false);
   }
   if (isStrayGlobal(scan, node)) {
-    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts), where the representative module of a capability is registered; a module never decides its own globality.');
+    scan.report(scan.file, node, '`isGlobal: true` appears only in the app root (apps/<app>/src/app.module.ts or a group of apps/<app>/src/compose/), where the representative module of a capability is registered; a module never decides its own globality.');
   }
   return true;
 }
@@ -170,11 +177,12 @@ export function checkRegisterOnce(input) {
   const { ts } = kit;
   const violations = [];
   const report = (file, node, message, extra = {}) => violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
-  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && path.posix.basename(file.rel) === 'app.module.ts';
+  const isAppRoot = file => Boolean(file.slot?.startsWith('be.app.')) && (path.posix.basename(file.rel) === 'app.module.ts' || isComposeGroup(file.rel));
   // The test world (slot be.tests.world) is the test composition root: useTestWorld registers capability modules with
   // `isGlobal: true` the way an app root does. A spec (integration, contract, e2e) is not a composition root.
   const isWorld = file => isTestWorldSlot(file.slot);
-  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`)?.name ?? null;
+  const appOf = file => config.apps.find(app => file.rel === `apps/${app.name}/src/app.module.ts`
+    || (isComposeGroup(file.rel) && file.rel.startsWith(`apps/${app.name}/src/compose/`)))?.name ?? null;
   const modules = moduleDeclarations(graph, kit, ts);
   const references = moduleReferences(graph, kit, ts, modules, isWorld, isAppRoot, report);
   const rootReferences = references.filter(item => item.root);

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

@@ -4,6 +4,7 @@ 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';
+import { requiredFileApplies } from '../slot-required.mjs';
 
 /**
  * HFS check 5: the files and directories the slot manifest requires (knowledge/hfs/slots.yaml `requires`,
@@ -173,7 +174,7 @@ function requirementExists(tree, target) {
 }
 
 function reportMissingRequirement(requirement, tree, report) {
-  if (requirementExists(tree, requirement.target)) return;
+  if (requirementExists(tree, requirement.target) || !requiredFileApplies(requirement.slot, requirement.target, tree.files)) 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' },

package/runtime/scripts/hfs/architecture/source-names.mjs

@@ -1,13 +1,14 @@
 import path from 'node:path';
 import { isInside } from './config.mjs';
 import { relativePath, unwrapExpression } from './typescript.mjs';
-import { commonJsRequireReasons, decoratorCallee, moduleExportsOf, nodeDecorators, normalizedSymbol, normalizedSymbolValue, programSourcesOf, returnedExpressions, selectedNode, valueSymbol, violation } from './ast-walks.mjs';
+import { commonJsRequireReasons, constructedDecoratorKind, decoratorCallee, moduleExportsOf, mutableDecoratorKind, nodeDecorators, normalizedSymbol, normalizedSymbolValue, programSourcesOf, returnedExpressions, selectedNode, valueSymbol, violation } from './ast-walks.mjs';
 import { createBackendSourceShapeChecker } from './source-names-shape.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const SOURCE_LAYOUT_RULE_ID = 'BE_FEATURE_LAYOUT_INVALID';
 const SOURCE_NAME_RULE_ID = 'BE_SOURCE_FORM';
 const FRAMEWORK_EXPORTS = new Map([
-  ['@nestjs/graphql', new Set(['Args', 'ArgsType', 'InputType', 'Mutation', 'ObjectType', 'Query', 'registerEnumType'])],
+  ['@nestjs/graphql', new Set(['Args', 'ArgsType', 'InputType', 'Mutation', 'ObjectType', 'Query', 'Subscription', 'registerEnumType'])],
   ['typeorm', new Set(['Entity', 'EntitySchema', 'MigrationInterface', 'ViewEntity'])],
 ]);
 const APPLICATION_ROLES = new Set(['command', 'contracts', 'handler', 'query']);
@@ -237,6 +238,11 @@ function graphqlField({ config, context, sourceFile, node, decorator, kind, nami
   }
   const methodName = node.name && (context.ts.isIdentifier(node.name) || context.ts.isStringLiteralLike(node.name)) ? node.name.text : null;
   const name = selected.status === 'literal' ? selected.value : methodName;
+  if (selected.status === 'literal') {
+    if (!methodName) namingReasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot prove the @${kind} method name`);
+    else if (selected.value !== methodName) violations.push(violation(config, sourceFile, selected.node, SOURCE_NAME_RULE_ID,
+      `GraphQL @${kind} field name ${selected.value} must equal its method name ${methodName}.`));
+  }
   if (!name) namingReasons.push(`${relativePath(config.root, sourceFile.fileName)} cannot prove the @${kind} field name`);
   else if (!camelCase(name)) violations.push(violation(config, sourceFile, selected.node ?? node.name ?? node, SOURCE_NAME_RULE_ID,
     `GraphQL field name ${name} must be camelCase.`));
@@ -316,7 +322,46 @@ const checkBackendSourceShapeImpl = createBackendSourceShapeChecker({
   TRACE_NEW,
 });
 
+function inspectSubscriptionSource({ config, context, sourceFile, checker, framework, configuredRoot, namingReasons, violations }) {
+  const visit = node => {
+    for (const decorator of nodeDecorators(context.ts, node)) {
+      const kind = decoratorKind(context.ts, checker, decorator, framework.bySymbol);
+      if (kind === 'Subscription') graphqlField({ config, context, sourceFile, node, decorator, kind, namingReasons, violations });
+      else if (!kind && !configuredRoot) {
+        const dynamic = mutableDecoratorKind(context.ts, checker, decorator, framework.bySymbol)
+          ?? constructedDecoratorKind(context.ts, checker, decorator, framework.bySymbol, TRACE_NEW);
+        if (['Subscription', 'multiple framework', 'unproven framework'].includes(dynamic)) {
+          namingReasons.push(`${relativePath(config.root, sourceFile.fileName)} uses a mutable or constructed ${dynamic} decorator identity`);
+        }
+      }
+    }
+    context.ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}
+
 export function checkBackendSourceShape(config, context) {
-  return checkBackendSourceShapeImpl(config, context);
+  const result = checkBackendSourceShapeImpl(config, context);
+  const roots = absoluteRoots(config.root, [...config.backend.features, ...config.backend.modules]);
+  const localFiles = new Set(context.files.map(file => canonical(file.fileName)));
+  const frameworkByChecker = new Map();
+  const namingReasons = [];
+  // The shared shape walk dispatches Query and Mutation; subscriptions use the same naming relation here.
+  for (const sourceFile of context.files) {
+    const fileName = canonical(sourceFile.fileName);
+    const configuredRoot = locatedRoot(roots, fileName);
+    const owner = config.hfs?.ownerOf?.(relativePath(config.root, fileName));
+    const slot = owner ? config.hfs.slot(owner.slot) : null;
+    if (!configuredRoot && !(slot?.tier === 'feature' && slot.profiles?.includes('be'))) continue;
+    const checker = context.checkerFor(fileName);
+    if (!frameworkByChecker.has(checker)) frameworkByChecker.set(checker, frameworkTargets(config, context, checker, localFiles));
+    const framework = frameworkByChecker.get(checker);
+    inspectSubscriptionSource({ config, context, sourceFile, checker, framework, configuredRoot, namingReasons, violations: result.violations });
+  }
+  if (namingReasons.length) result.coverage.naming = {
+    status: 'unavailable', reason: 'one or more backend source naming relations are not statically proved',
+    details: [...new Set([...(result.coverage.naming.details ?? []), ...namingReasons])].sort(byCodeUnit),
+  };
+  return result;
 }
 export { SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID };

package/runtime/scripts/hfs/architecture/staged-consumers.mjs

@@ -0,0 +1,37 @@
+import { catFile } from '../../api/git/cat-file.mjs';
+import { diff } from '../../api/git/diff.mjs';
+import { gitOutputOf } from '../../lib/git.mjs';
+
+/** Eligible additions, copies, edits and rename destinations in the index, read in one blob batch. */
+export function stagedConsumerSources(root, accept) {
+  try {
+    const options = { cwd: root, maxBuffer: 256 * 1024 * 1024 };
+    const files = gitOutputOf(diff(['--cached', '--relative', '--name-only', '--diff-filter=ACMR', '-z', '--', '.'], options))
+      .split('\0').filter(file => file && accept(file));
+    if (!files.length) return [];
+    // :./ keeps paths relative to this side's root even when git's top level is the parent app folder.
+    // -z terminates requests with NUL; output headers and blob trailers still use LF.
+    const bytes = gitOutputOf(catFile(['--batch', '-z'], {
+      ...options, encoding: null, input: files.map(file => `:./${file}\0`).join(''),
+    }));
+    if (!Buffer.isBuffer(bytes)) return [];
+    const sources = [];
+    let cursor = 0;
+    for (const file of files) {
+      const end = bytes.indexOf(10, cursor);
+      if (end < 0) return [];
+      const header = /^[0-9a-f]+ blob (\d+)$/u.exec(bytes.subarray(cursor, end).toString('utf8'));
+      if (!header) return []; // An index changed during the read: discard this supplement, keep disk consumers.
+      const size = Number(header[1]);
+      const start = end + 1;
+      const next = start + size;
+      if (!Number.isSafeInteger(size) || next >= bytes.length || bytes[next] !== 10) return [];
+      sources.push({ file, text: bytes.subarray(start, next).toString('utf8') });
+      cursor = next + 1;
+    }
+    return sources;
+  } catch {
+    // A non-git fixture (or an unavailable index) still uses the existing filesystem consumers.
+    return [];
+  }
+}

package/runtime/scripts/hfs/architecture/supabase-ast.mjs

@@ -1,6 +1,10 @@
 // supabase-ast.mjs - shared TypeScript-symbol and expression helpers for the front-end and back-end Supabase
 // architecture checks. Recognition follows imported declarations and inferred types, never local spelling alone.
-export const SUPABASE_MODULES = new Set(['@supabase/ssr', '@supabase/supabase-js']);
+import { unwrapExpression } from '../../lib/ts-analysis.mjs';
+import { accessName as memberName, hasAnyFlag } from '../../lib/ts-ast.mjs';
+export { accessName as memberName } from '../../lib/ts-ast.mjs';
+
+export const SUPABASE_MODULES = Object.freeze({ has: name => typeof name === 'string' && name.startsWith('@supabase/') });
 
 export const moduleNameOf = (ts, node) => {
   if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) return node.moduleSpecifier.text;
@@ -15,7 +19,7 @@ export const importedFrom = (kit, checker, node, modules, names = null) => {
   return Boolean(binding && modules.has(binding.module) && (names === null || names.has(binding.name)));
 };
 
-const declarationFromSupabase = (declaration) => /(?:^|\/)node_modules\/@supabase\/(?:ssr|supabase-js|auth-js|postgrest-js|storage-js)(?:\/|$)/u
+const declarationFromSupabase = (declaration) => /(?:^|\/)node_modules\/@supabase\/[^/]+(?:\/|$)/u
   .test(String(declaration?.getSourceFile?.().fileName ?? '').replaceAll('\\', '/'));
 
 const typeFromSupabase = (checker, node) => {
@@ -38,12 +42,7 @@ const signatureFromSupabase = (checker, call) => {
   try { return declarationFromSupabase(checker.getResolvedSignature(call)?.declaration); } catch { return false; }
 };
 
-export const unwrap = (ts, node) => {
-  let current = node;
-  while (current && (ts.isParenthesizedExpression(current) || ts.isAwaitExpression(current) || ts.isAsExpression(current)
-    || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current))) current = current.expression;
-  return current;
-};
+export const unwrap = (ts, node) => unwrapExpression(ts, node, { awaitExpressions: true, satisfiesExpressions: false });
 
 const isSupabaseValue = (kit, checker, node) => {
   const current = unwrap(kit.ts, node);
@@ -53,23 +52,19 @@ const isSupabaseValue = (kit, checker, node) => {
   return typeFromSupabase(checker, current);
 };
 
-export const callName = (ts, call) => ts.isCallExpression(call) && ts.isPropertyAccessExpression(call.expression) ? call.expression.name.text : null;
+export const callName = (ts, call) => ts.isCallExpression(call) ? memberName(ts, call.expression) : null;
 
 export const chainParts = (ts, expression) => {
   const names = [];
   let current = unwrap(ts, expression);
   while (current) {
     if (ts.isCallExpression(current)) {
-      if (ts.isPropertyAccessExpression(current.expression)) {
-        names.unshift(current.expression.name.text);
-        current = unwrap(ts, current.expression.expression);
-        continue;
-      }
       current = unwrap(ts, current.expression);
       continue;
     }
-    if (ts.isPropertyAccessExpression(current)) {
-      names.unshift(current.name.text);
+    if (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
+      const name = memberName(ts, current);
+      if (name) names.unshift(name);
       current = unwrap(ts, current.expression);
       continue;
     }
@@ -79,7 +74,47 @@ export const chainParts = (ts, expression) => {
 };
 
 export const isSupabaseCall = (kit, checker, node) => kit.ts.isCallExpression(node)
-  && (signatureFromSupabase(checker, node) || isSupabaseValue(kit, checker, kit.ts.isPropertyAccessExpression(node.expression) ? node.expression.expression : node.expression));
+  && (signatureFromSupabase(checker, node) || isSupabaseValue(kit, checker,
+    kit.ts.isPropertyAccessExpression(node.expression) || kit.ts.isElementAccessExpression(node.expression) ? node.expression.expression : node.expression));
+
+const authStorageValue = (kit, checker, expression, seen = new Set()) => {
+  const current = unwrap(kit.ts, expression);
+  if (!current || seen.has(current)) return false;
+  seen.add(current);
+  if (['auth', 'storage'].includes(memberName(kit.ts, current)) && isSupabaseValue(kit, checker, current.expression)) return true;
+  if (checker.getTypeAtLocation(current).symbol?.declarations?.some(declaration =>
+    /\/node_modules\/@supabase\/(?:storage-js|auth-js)\//u.test(String(declaration.getSourceFile().fileName).replaceAll('\\', '/')))) return true;
+  if (!kit.ts.isIdentifier(current)) return false;
+  return kit.declarationsOf(checker, current).some(declaration =>
+    (kit.ts.isVariableDeclaration(declaration) || kit.ts.isPropertyDeclaration(declaration)) && declaration.initializer
+    && authStorageValue(kit, checker, declaration.initializer, seen));
+};
+
+const chainAccesses = (ts, node) => {
+  const accesses = [];
+  let current = unwrap(ts, node);
+  while (current) {
+    if (ts.isCallExpression(current)) current = unwrap(ts, current.expression);
+    else if (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
+      accesses.unshift(current);
+      current = unwrap(ts, current.expression);
+    } else break;
+  }
+  return accesses;
+};
+
+/** The first forbidden SDK access in a call chain, anchored once even when more methods follow it. */
+export const supabaseDataAccess = (kit, checker, node, members, { storageAllowed = false } = {}) => {
+  for (const access of chainAccesses(kit.ts, node)) {
+    const name = memberName(kit.ts, access);
+    if (storageAllowed && (name === 'storage' || name === 'auth')) return null;
+    if (members.has(name) && isSupabaseValue(kit, checker, access.expression)) {
+      if (storageAllowed && authStorageValue(kit, checker, access.expression)) return null;
+      return { name, node: access };
+    }
+  }
+  return null;
+};
 
 export const isDatabaseType = (ts, node) => {
   if (!node) return false;
@@ -109,3 +144,165 @@ export const contextTypesClient = (kit, checker, call) => {
 export const reportAt = (violations, kit, ruleId, file, node, message, extra = {}) => {
   violations.push({ ruleId, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
 };
+
+const declarationsOf = (ts, checker, node) => {
+  const target = ts.isPropertyAccessExpression(node) ? node.name : node;
+  // A shorthand property (`issuer,`) names the variable it reads, not the property it creates.
+  let symbol = ts.isShorthandPropertyAssignment(target.parent ?? {}) && target.parent.name === target
+    ? checker.getShorthandAssignmentValueSymbol(target.parent)
+    : checker.getSymbolAtLocation(target);
+  if (symbol && hasAnyFlag(symbol.flags, ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+  return symbol?.declarations ?? [];
+};
+
+const configType = (checker, node) => {
+  const type = checker.getTypeAtLocation(node);
+  return [type.symbol, type.aliasSymbol].some(symbol => symbol?.declarations?.some(declaration =>
+    /(?:\.config|\.options|\.env)\.ts$|\/modules\/config\/|\/node_modules\/@nestjs\/config\//u.test(String(declaration.getSourceFile().fileName).replaceAll('\\', '/'))
+    || /(?:Config|Options|Env)$/u.test(symbol.name)));
+};
+
+/** Trace issuer construction through configuration values and local URL/string transformations. */
+const issuerFromConfig = (ts, checker, expression, seen = new Set()) => {
+  const node = unwrap(ts, expression);
+  if (!node || seen.has(node)) return false;
+  const next = new Set(seen).add(node);
+  if (ts.isIdentifier(node)) {
+    return declarationsOf(ts, checker, node).some(declaration => {
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer) return issuerFromConfig(ts, checker, declaration.initializer, next);
+      if (ts.isParameter(declaration) || ts.isPropertyDeclaration(declaration)) return configType(checker, node);
+      return /(?:\.config|\.env)\.ts$|\/modules\/config\//u.test(String(declaration.getSourceFile().fileName).replaceAll('\\', '/'));
+    });
+  }
+  if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+    return issuerFromConfig(ts, checker, node.expression, next) || declarationsOf(ts, checker, node).some(declaration =>
+      (ts.isParameter(declaration) || ts.isPropertyDeclaration(declaration)) && !declaration.initializer && configType(checker, node));
+  }
+  if (ts.isTemplateExpression(node)) return node.templateSpans.some(span => issuerFromConfig(ts, checker, span.expression, next));
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    return issuerFromConfig(ts, checker, node.left, next) || issuerFromConfig(ts, checker, node.right, next);
+  }
+  if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+    return issuerFromConfig(ts, checker, node.expression, next) || node.arguments?.some(argument => issuerFromConfig(ts, checker, argument, next));
+  }
+  return false;
+};
+
+const objectValue = (ts, checker, expression) => {
+  const node = unwrap(ts, expression);
+  if (!node) return null;
+  if (ts.isObjectLiteralExpression(node)) return node;
+  if (!ts.isIdentifier(node)) return null;
+  return declarationsOf(ts, checker, node).find(declaration => ts.isVariableDeclaration(declaration)
+    && declaration.initializer && ts.isObjectLiteralExpression(unwrap(ts, declaration.initializer)))?.initializer ?? null;
+};
+
+const literalString = (ts, checker, expression) => {
+  const node = unwrap(ts, expression);
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  const type = checker.getTypeAtLocation(node);
+  return type.isStringLiteral?.() ? type.value : null;
+};
+
+/** A role read must belong to the payload produced by this verification, including destructuring aliases. */
+const verifiedPayload = (ts, checker, expression, call, seen = new Set()) => {
+  const node = unwrap(ts, expression);
+  if (!node || seen.has(node)) return false;
+  const next = new Set(seen).add(node);
+  if ((ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) && memberName(ts, node) === 'payload') {
+    const value = unwrap(ts, node.expression);
+    if (value === call) return true;
+    if (ts.isIdentifier(value)) return declarationsOf(ts, checker, value).some(declaration =>
+      ts.isVariableDeclaration(declaration) && unwrap(ts, declaration.initializer) === call);
+  }
+  if (!ts.isIdentifier(node)) return false;
+  return declarationsOf(ts, checker, node).some(declaration => {
+    if (ts.isVariableDeclaration(declaration)) return declaration.initializer && verifiedPayload(ts, checker, declaration.initializer, call, next);
+    if (!ts.isBindingElement(declaration) || (declaration.propertyName ?? declaration.name).getText() !== 'payload') return false;
+    return unwrap(ts, declaration.parent.parent.initializer) === call;
+  });
+};
+
+const rejects = (ts, statement) => {
+  if (ts.isBlock(statement)) {
+    const exit = statement.statements.find(item => ts.isThrowStatement(item) || ts.isReturnStatement(item));
+    return Boolean(exit && rejects(ts, exit));
+  }
+  if (ts.isThrowStatement(statement)) return true;
+  if (!ts.isReturnStatement(statement)) return false;
+  const value = statement.expression && unwrap(ts, statement.expression);
+  return !value || value.kind === ts.SyntaxKind.NullKeyword || value.kind === ts.SyntaxKind.FalseKeyword
+    || (ts.isCallExpression(value) && /^(?:refused|err|fail|failure)$/u.test(value.expression.getText()));
+};
+
+const roleCondition = (ts, checker, condition, call, equality = false) => {
+  const node = unwrap(ts, condition);
+  if (!node || !ts.isBinaryExpression(node)) return false;
+  const combined = equality ? ts.SyntaxKind.AmpersandAmpersandToken : ts.SyntaxKind.BarBarToken;
+  if (node.operatorToken.kind === combined) return roleCondition(ts, checker, node.left, call, equality) || roleCondition(ts, checker, node.right, call, equality);
+  const operators = equality ? [ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.EqualsEqualsToken]
+    : [ts.SyntaxKind.ExclamationEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken];
+  if (!operators.includes(node.operatorToken.kind)) return false;
+  const role = expression => (ts.isPropertyAccessExpression(expression) || ts.isElementAccessExpression(expression))
+    && memberName(ts, expression) === 'role' && verifiedPayload(ts, checker, expression.expression, call);
+  return (role(node.left) && literalString(ts, checker, node.right) === 'authenticated')
+    || (role(node.right) && literalString(ts, checker, node.left) === 'authenticated');
+};
+
+const returnsPrincipal = (ts, statement) => {
+  let accepted = false;
+  const visit = node => {
+    if (ts.isFunctionLike(node)) return;
+    if (ts.isReturnStatement(node) && !rejects(ts, node)) accepted = true;
+    ts.forEachChild(node, visit);
+  };
+  visit(statement);
+  return accepted;
+};
+
+const statementsAfterVerify = (ts, call) => {
+  let statement = call;
+  while (statement.parent && !ts.isBlock(statement.parent)) statement = statement.parent;
+  const block = statement.parent;
+  if (!block || !ts.isBlock(block)) return [];
+  return block.statements.slice(block.statements.indexOf(statement) + 1);
+};
+
+const rejectsRoleGuard = (ts, checker, statement, call) => {
+  if (!ts.isIfStatement(statement)) return false;
+  if (roleCondition(ts, checker, statement.expression, call) && rejects(ts, statement.thenStatement)) return true;
+  return Boolean(statement.elseStatement && roleCondition(ts, checker, statement.expression, call, true) && rejects(ts, statement.elseStatement));
+};
+
+const rejectsOtherRoles = (ts, checker, call) => {
+  for (const item of statementsAfterVerify(ts, call)) {
+    if (ts.isReturnStatement(item) || ts.isThrowStatement(item)) return false;
+    if (rejectsRoleGuard(ts, checker, item, call)) return true;
+    if (returnsPrincipal(ts, item)) return false;
+  }
+  return false;
+};
+
+/** R260 is shared by the architecture machine and the published typed ESLint rule. */
+export const jwtPolicyProblems = (ts, checker, call) => {
+  const problems = [];
+  const options = objectValue(ts, checker, call.arguments[2]);
+  const property = name => options?.properties.findLast(entry =>
+    (ts.isPropertyAssignment(entry) || ts.isShorthandPropertyAssignment(entry))
+    && (ts.isIdentifier(entry.name) || ts.isStringLiteralLike(entry.name)) && entry.name.text === name);
+  const value = name => {
+    const entry = property(name);
+    return entry && unwrap(ts, ts.isPropertyAssignment(entry) ? entry.initializer : entry.name);
+  };
+  const algorithms = value('algorithms');
+  const secure = new Set(['ES256', 'RS256', 'EdDSA']);
+  if (!algorithms || !ts.isArrayLiteralExpression(algorithms) || !algorithms.elements.length
+    || algorithms.elements.some(item => !ts.isStringLiteralLike(item) || !secure.has(item.text))
+    || options?.properties.some(entry => ts.isSpreadAssignment(entry))) {
+    problems.push('BE_JWT_ALG_PINNED: algorithms must be a non-empty literal subset of ES256, RS256 and EdDSA.');
+  }
+  if (!issuerFromConfig(ts, checker, value('issuer'))) problems.push('BE_JWT_ALG_PINNED: issuer must derive from typed configuration.');
+  if (!rejectsOtherRoles(ts, checker, call)) problems.push('BE_JWT_ALG_PINNED: the verified principal must reject every role other than authenticated before returning it.');
+  return problems;
+};

package/runtime/scripts/hfs/architecture/supabase-be.mjs

@@ -3,6 +3,7 @@
 import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { importedFrom, reportAt, unwrap } from './supabase-ast.mjs';
+import { accessName } from '../../lib/ts-ast.mjs';
 
 const BE_SUPABASE_SLOT = 'be.integrations.supabase';
 const BE_JWT_VERIFIED = 'BE_SUPABASE_JWT_VERIFIED';
@@ -47,12 +48,6 @@ const importedCall = (kit, checker, call) => {
   return owner?.name === 'default' ? { module: owner.module, name: call.expression.name.text } : null;
 };
 
-const accessName = (ts, node) => {
-  if (ts.isPropertyAccessExpression(node)) return node.name.text;
-  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
-  return null;
-};
-
 const requestLike = (ts, node) => {
   const current = unwrap(ts, node);
   if (ts.isIdentifier(current)) return /^(?:req|request)$/iu.test(current.text);