@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/rules/implementation-returns-result.ts

@@ -6,57 +6,34 @@
  * or a tracked Result-typed variable.
  */
 
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import type { AstNode } from './ast.js';
 import {
+  collectScopeFrameBindings,
   findBlazeBodies,
   findTrailDefinitions,
+  getMemberExpression,
+  identifierName,
   offsetToLine,
   parse,
   walk,
+  walkWithScopes,
 } from './ast.js';
 import { isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface AstNode {
-  readonly type: string;
-  readonly start: number;
-  readonly end: number;
-  readonly [key: string]: unknown;
-}
-
 // ---------------------------------------------------------------------------
 // Member expression helpers
 // ---------------------------------------------------------------------------
 
-/** Extract object.property names from a MemberExpression callee. */
-const extractMemberNames = (
-  callee: AstNode
-): { objName: string | undefined; propName: string | undefined } => {
-  const obj = (callee as unknown as { object?: AstNode }).object;
-  const prop = (callee as unknown as { property?: AstNode }).property;
-  const objName =
-    obj?.type === 'Identifier'
-      ? (obj as unknown as { name: string }).name
-      : undefined;
-  const propName =
-    prop?.type === 'Identifier'
-      ? (prop as unknown as { name: string }).name
-      : undefined;
-  return { objName, propName };
-};
-
-const isMemberExpression = (callee: AstNode): boolean =>
-  callee.type === 'StaticMemberExpression' ||
-  callee.type === 'MemberExpression';
-
 const isResultMemberCall = (callee: AstNode): boolean => {
-  if (!isMemberExpression(callee)) {
+  const member = getMemberExpression(callee);
+  if (!member) {
     return false;
   }
-  const { objName, propName } = extractMemberNames(callee);
+  const objName = identifierName(member.object) ?? undefined;
+  const propName = identifierName(member.property) ?? undefined;
   if (objName === 'Result' && (propName === 'ok' || propName === 'err')) {
     return true;
   }
@@ -88,10 +65,46 @@ const isResultExpression = (node: AstNode): boolean => {
   return false;
 };
 
+/** Map of namespace-import local name to the set of Result-helper names exported by the target module. */
+type NamespaceHelperMap = ReadonlyMap<string, ReadonlySet<string>>;
+
+/**
+ * Check whether a namespace-member call like `ns.helper(...)` resolves to a
+ * known Result helper.
+ *
+ * When a non-empty `scopes` stack is provided, the namespace binding must not
+ * be shadowed by a parameter or local declaration in any enclosing scope at
+ * the call site. Without this check, any local `ns` (e.g. a blaze parameter
+ * named `ns`, or `const ns = ...` inside the body) would be misread as the
+ * module-scope namespace import.
+ */
+const isNamespaceHelperMemberCall = (
+  callee: AstNode,
+  namespaceHelpers: NamespaceHelperMap,
+  scopes: readonly ReadonlySet<string>[] = []
+): boolean => {
+  const member = getMemberExpression(callee);
+  if (!member) {
+    return false;
+  }
+  const objName = identifierName(member.object) ?? undefined;
+  const propName = identifierName(member.property) ?? undefined;
+  if (!(objName && propName)) {
+    return false;
+  }
+  // Nearest binding is a local, not the namespace import.
+  if (scopes.some((scope) => scope.has(objName))) {
+    return false;
+  }
+  return namespaceHelpers.get(objName)?.has(propName) ?? false;
+};
+
 /** Check if a node is a call to a known Result-returning helper. */
 const isHelperCall = (
   node: AstNode,
-  helperNames: ReadonlySet<string>
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap = new Map(),
+  scopes: readonly ReadonlySet<string>[] = []
 ): boolean => {
   const target =
     node.type === 'AwaitExpression'
@@ -108,7 +121,9 @@ const isHelperCall = (
     return helperNames.has(name);
   }
 
-  return false;
+  return callee
+    ? isNamespaceHelperMemberCall(callee, namespaceHelpers, scopes)
+    : false;
 };
 
 /** Unwrap an optional AwaitExpression to get the inner identifier name. */
@@ -129,12 +144,14 @@ const resolveIdentifierName = (node: AstNode): string | null => {
 const isAllowedReturnArgument = (
   argument: AstNode,
   helperNames: ReadonlySet<string>,
-  resultVars: ReadonlySet<string>
+  resultVars: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  scopes: readonly ReadonlySet<string>[] = []
 ): boolean => {
   if (isResultExpression(argument)) {
     return true;
   }
-  if (isHelperCall(argument, helperNames)) {
+  if (isHelperCall(argument, helperNames, namespaceHelpers, scopes)) {
     return true;
   }
 
@@ -158,63 +175,6 @@ const trackResultVariable = (node: AstNode, resultVars: Set<string>): void => {
   }
 };
 
-// ---------------------------------------------------------------------------
-// Shallow walk (stops at nested function boundaries)
-// ---------------------------------------------------------------------------
-
-const FUNCTION_BOUNDARY_TYPES = new Set([
-  'ArrowFunctionExpression',
-  'FunctionExpression',
-  'FunctionDeclaration',
-]);
-
-/** Check if a value is a function-boundary AST node that should not be recursed into. */
-const isFunctionBoundary = (val: unknown): boolean =>
-  !!val &&
-  typeof val === 'object' &&
-  FUNCTION_BOUNDARY_TYPES.has((val as AstNode).type);
-
-/** Recurse into a single AST property value, skipping function boundaries. */
-const visitValue = (
-  val: unknown,
-  visit: (node: AstNode) => void,
-  recurse: (node: unknown, visit: (node: AstNode) => void) => void
-): void => {
-  if (Array.isArray(val)) {
-    for (const item of val) {
-      if (!isFunctionBoundary(item)) {
-        recurse(item, visit);
-      }
-    }
-  } else if (
-    val &&
-    typeof val === 'object' &&
-    (val as AstNode).type &&
-    !isFunctionBoundary(val)
-  ) {
-    recurse(val, visit);
-  }
-};
-
-/**
- * Walk an AST node tree without recursing into nested function bodies.
- *
- * This ensures that return statements inside `.map()`, `.filter()`, `.then()`
- * callbacks etc. are not mistakenly checked as implementation-level returns.
- */
-const walkShallow = (node: unknown, visit: (node: AstNode) => void): void => {
-  if (!node || typeof node !== 'object') {
-    return;
-  }
-  const n = node as AstNode;
-  if (n.type) {
-    visit(n);
-  }
-  for (const val of Object.values(n)) {
-    visitValue(val, visit, walkShallow);
-  }
-};
-
 // ---------------------------------------------------------------------------
 // Return statement checking
 // ---------------------------------------------------------------------------
@@ -226,37 +186,52 @@ const checkReturnStatements = (
   filePath: string,
   sourceCode: string,
   helperNames: ReadonlySet<string>,
-  diagnostics: WardenDiagnostic[]
+  namespaceHelpers: NamespaceHelperMap,
+  diagnostics: WardenDiagnostic[],
+  implScope: ReadonlySet<string> = new Set<string>()
 ): void => {
   const resultVars = new Set<string>();
+  const initialScopes = implScope.size > 0 ? [implScope] : [];
 
-  walkShallow(blockBody, (node) => {
-    if (node.type === 'VariableDeclarator') {
-      trackResultVariable(node, resultVars);
-    }
+  walkWithScopes(
+    blockBody,
+    (node, currentScopes) => {
+      if (node.type === 'VariableDeclarator') {
+        trackResultVariable(node, resultVars);
+      }
 
-    if (node.type !== 'ReturnStatement') {
-      return;
-    }
+      if (node.type !== 'ReturnStatement') {
+        return;
+      }
 
-    const { argument } = node as unknown as { argument?: AstNode };
-    // Bare return — not a value return
-    if (!argument) {
-      return;
-    }
+      const { argument } = node as unknown as { argument?: AstNode };
+      // Bare return — not a value return
+      if (!argument) {
+        return;
+      }
 
-    if (isAllowedReturnArgument(argument, helperNames, resultVars)) {
-      return;
-    }
+      if (
+        isAllowedReturnArgument(
+          argument,
+          helperNames,
+          resultVars,
+          namespaceHelpers,
+          currentScopes
+        )
+      ) {
+        return;
+      }
 
-    diagnostics.push({
-      filePath,
-      line: offsetToLine(sourceCode, node.start),
-      message: `${trailInfo.label} "${trailInfo.id}" implementation must return Result.ok(...) or Result.err(...), not a raw value.`,
-      rule: 'implementation-returns-result',
-      severity: 'error',
-    });
-  });
+      diagnostics.push({
+        filePath,
+        line: offsetToLine(sourceCode, node.start),
+        message: `${trailInfo.label} "${trailInfo.id}" implementation must return Result.ok(...) or Result.err(...), not a raw value.`,
+        rule: 'implementation-returns-result',
+        severity: 'error',
+      });
+    },
+    { initialScopes, stopAtNestedFunctions: true }
+  );
 };
 
 // ---------------------------------------------------------------------------
@@ -308,6 +283,937 @@ const collectResultHelperNames = (
   return names;
 };
 
+// ---------------------------------------------------------------------------
+// Imported Result helper resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-target-file cache of exported Result-helper names keyed by the absolute
+ * target path. Saves re-parsing when multiple rule invocations resolve the
+ * same file during a single warden run.
+ *
+ * @remarks
+ * Long-running processes calling `implementationReturnsResult.check` after
+ * source files change (e.g. watch mode, editor language servers) should call
+ * `clearImplementationReturnsResultCache()` between runs to avoid returning
+ * stale helper-name sets. The cache is intentionally not auto-invalidated per
+ * invocation — that would defeat its purpose within a single warden run.
+ */
+const targetFileResultExportCache = new Map<string, ReadonlySet<string>>();
+
+/**
+ * Clear the module-level cache used by the `implementation-returns-result`
+ * rule to remember which exported names on a target file carry a `Result<...>`
+ * return annotation.
+ *
+ * Call this between runs in long-lived processes where the set of Trails
+ * source files may have changed on disk since the last check.
+ */
+export const clearImplementationReturnsResultCache = (): void => {
+  targetFileResultExportCache.clear();
+};
+
+interface ImportBinding {
+  /** Local alias used in the importing file. */
+  readonly localName: string;
+  /** Original exported name from the target module. */
+  readonly importedName: string;
+  /** Raw import source specifier (e.g. './foo.js'). */
+  readonly source: string;
+}
+
+const getImportSourceValue = (node: AstNode): string | null => {
+  const sourceNode = (node as unknown as { source?: AstNode }).source;
+  const sourceValue = sourceNode
+    ? (sourceNode as unknown as { value?: unknown }).value
+    : undefined;
+  return typeof sourceValue === 'string' ? sourceValue : null;
+};
+
+const extractIdentifierName = (node: AstNode | undefined): string | null =>
+  node?.type === 'Identifier'
+    ? ((node as unknown as { name: string }).name ?? null)
+    : null;
+
+const buildDefaultImportBinding = (
+  specifier: AstNode,
+  source: string
+): ImportBinding | null => {
+  const { local } = specifier as unknown as { local?: AstNode };
+  const localName = extractIdentifierName(local);
+  if (!localName) {
+    return null;
+  }
+  return { importedName: 'default', localName, source };
+};
+
+const buildNamedImportBinding = (
+  specifier: AstNode,
+  source: string
+): ImportBinding | null => {
+  const { local, imported } = specifier as unknown as {
+    local?: AstNode;
+    imported?: AstNode;
+  };
+  const localName = extractIdentifierName(local);
+  const importedName = extractIdentifierName(imported) ?? localName;
+  if (!(localName && importedName)) {
+    return null;
+  }
+  return { importedName, localName, source };
+};
+
+/**
+ * @remarks
+ * `import foo from './bar.js'` is treated as a re-export of `default` so the
+ * target file's `export default` declaration is considered as a potential
+ * Result helper. `import * as ns from './bar.js'` is handled separately by
+ * `collectNamespaceHelperImports`, which maps the namespace binding to the
+ * target's exported Result-helper names so `ns.helper(...)` member calls are
+ * recognized.
+ */
+const buildImportBinding = (
+  specifier: AstNode,
+  source: string
+): ImportBinding | null => {
+  if (specifier.type === 'ImportDefaultSpecifier') {
+    return buildDefaultImportBinding(specifier, source);
+  }
+  if (specifier.type === 'ImportSpecifier') {
+    return buildNamedImportBinding(specifier, source);
+  }
+  return null;
+};
+
+const collectBindingsFromImportDeclaration = (
+  node: AstNode
+): readonly ImportBinding[] => {
+  const source = getImportSourceValue(node);
+  if (!source) {
+    return [];
+  }
+  const specifiers =
+    (node['specifiers'] as readonly AstNode[] | undefined) ?? [];
+  return specifiers.flatMap((specifier) => {
+    const binding = buildImportBinding(specifier, source);
+    return binding ? [binding] : [];
+  });
+};
+
+/** Collect `import { foo as bar } from './...'` bindings keyed by local name. */
+const collectResolvableImports = (ast: AstNode): readonly ImportBinding[] => {
+  const imports: ImportBinding[] = [];
+  walk(ast, (node) => {
+    if (node.type === 'ImportDeclaration') {
+      imports.push(...collectBindingsFromImportDeclaration(node));
+    }
+  });
+  return imports;
+};
+
+/**
+ * Resolve a relative import source specifier to an absolute on-disk file path,
+ * or null when the source is not a relative path we can resolve locally.
+ *
+ * Handles `.js` -> `.ts` rewriting (the convention in this repo), plain `.ts`
+ * imports, and extensionless paths.
+ */
+const buildResolutionCandidates = (resolved: string): readonly string[] => {
+  if (resolved.endsWith('.ts') || resolved.endsWith('.tsx')) {
+    return [resolved];
+  }
+  if (resolved.endsWith('.js')) {
+    return [
+      resolved.replace(/\.js$/, '.ts'),
+      resolved.replace(/\.js$/, '.tsx'),
+      resolved,
+    ];
+  }
+  if (resolved.endsWith('.jsx')) {
+    return [resolved.replace(/\.jsx$/, '.tsx'), resolved];
+  }
+  return [`${resolved}.ts`, `${resolved}.tsx`];
+};
+
+const resolveRelativeImportPath = (
+  source: string,
+  fromFile: string
+): string | null => {
+  if (!(source.startsWith('./') || source.startsWith('../'))) {
+    return null;
+  }
+  const baseDir = isAbsolute(fromFile)
+    ? dirname(fromFile)
+    : dirname(resolve(fromFile));
+  const resolved = resolve(baseDir, source);
+  return (
+    buildResolutionCandidates(resolved).find((candidate) =>
+      existsSync(candidate)
+    ) ?? null
+  );
+};
+
+/** Extract the declaration wrapped by an ExportNamedDeclaration, if any. */
+const getExportedDeclaration = (node: AstNode): AstNode | null => {
+  if (node.type !== 'ExportNamedDeclaration') {
+    return null;
+  }
+  const decl = (node as unknown as { declaration?: AstNode }).declaration;
+  return decl ?? null;
+};
+
+const addExportedVariableResultHelper = (
+  decl: AstNode,
+  source: string,
+  collected: Set<string>
+): void => {
+  const declarations =
+    (decl['declarations'] as readonly AstNode[] | undefined) ?? [];
+  for (const declarator of declarations) {
+    const { id, init } = declarator as unknown as {
+      id?: AstNode;
+      init?: AstNode;
+    };
+    const name = extractIdentifierName(id);
+    if (
+      name &&
+      init &&
+      isFunctionLikeExpression(init) &&
+      hasResultReturnType(init, source)
+    ) {
+      collected.add(name);
+    }
+  }
+};
+
+const addExportedFunctionResultHelper = (
+  decl: AstNode,
+  source: string,
+  collected: Set<string>
+): void => {
+  const name = extractIdentifierName((decl as unknown as { id?: AstNode }).id);
+  if (name && hasResultReturnType(decl, source)) {
+    collected.add(name);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Same-file declaration index (for specifier re-exports without a source)
+// ---------------------------------------------------------------------------
+
+/**
+ * Index a file's top-level function-like declarations (both exported-inline
+ * and plain) by name to the declaration node, so we can look up the original
+ * binding referenced by a specifier re-export like `export { helper }`.
+ *
+ * Each entry carries the init/declaration node so the caller can check the
+ * return-type annotation without re-walking.
+ */
+type DeclarationIndex = ReadonlyMap<string, AstNode>;
+
+const indexVariableDeclarationInto = (
+  decl: AstNode,
+  index: Map<string, AstNode>
+): void => {
+  const declarators =
+    (decl['declarations'] as readonly AstNode[] | undefined) ?? [];
+  for (const declarator of declarators) {
+    const { id, init } = declarator as unknown as {
+      id?: AstNode;
+      init?: AstNode;
+    };
+    const name = extractIdentifierName(id);
+    if (name && init && isFunctionLikeExpression(init)) {
+      index.set(name, init);
+    }
+  }
+};
+
+const indexFunctionDeclarationInto = (
+  decl: AstNode,
+  index: Map<string, AstNode>
+): void => {
+  const name = extractIdentifierName((decl as unknown as { id?: AstNode }).id);
+  if (name) {
+    index.set(name, decl);
+  }
+};
+
+const indexDeclarationInto = (
+  decl: AstNode | null | undefined,
+  index: Map<string, AstNode>
+): void => {
+  if (!decl) {
+    return;
+  }
+  if (decl.type === 'VariableDeclaration') {
+    indexVariableDeclarationInto(decl, index);
+  } else if (decl.type === 'FunctionDeclaration') {
+    indexFunctionDeclarationInto(decl, index);
+  }
+};
+
+const indexBodyNodeInto = (
+  node: AstNode,
+  index: Map<string, AstNode>
+): void => {
+  if (node.type === 'ExportNamedDeclaration') {
+    indexDeclarationInto(getExportedDeclaration(node), index);
+    return;
+  }
+  indexDeclarationInto(node, index);
+};
+
+const indexLocalDeclarations = (ast: AstNode): DeclarationIndex => {
+  const index = new Map<string, AstNode>();
+  const program = ast as unknown as { body?: readonly AstNode[] };
+  const bodyNodes = program.body ?? [];
+  for (const node of bodyNodes) {
+    indexBodyNodeInto(node, index);
+  }
+  return index;
+};
+
+// ---------------------------------------------------------------------------
+// Export-specifier handling
+// ---------------------------------------------------------------------------
+
+interface ExportSpecifierInfo {
+  /** Name this export is exposed as to consumers (after `as` alias). */
+  readonly exportedName: string;
+  /** Name referenced inside the re-export (`helper` in `export { helper }`). */
+  readonly localName: string;
+  /** True when the specifier is `default` (i.e. `export { default as X }`). */
+  readonly isDefault: boolean;
+}
+
+const getSpecifierNameNode = (
+  spec: AstNode,
+  key: 'exported' | 'local'
+): string | null => {
+  const node = (spec as unknown as Record<string, AstNode | undefined>)[key];
+  if (!node) {
+    return null;
+  }
+  if (node.type === 'Identifier') {
+    return (node as unknown as { name?: string }).name ?? null;
+  }
+  // Support string-literal specifiers (`export { "default" as X }`, etc).
+  const { value } = node as unknown as { value?: unknown };
+  return typeof value === 'string' ? value : null;
+};
+
+const buildExportSpecifierInfo = (
+  spec: AstNode
+): ExportSpecifierInfo | null => {
+  if (spec.type !== 'ExportSpecifier') {
+    return null;
+  }
+  const localName = getSpecifierNameNode(spec, 'local');
+  const exportedName = getSpecifierNameNode(spec, 'exported') ?? localName;
+  if (!(localName && exportedName)) {
+    return null;
+  }
+  return {
+    exportedName,
+    isDefault: localName === 'default',
+    localName,
+  };
+};
+
+const getExportDefaultDeclaration = (ast: AstNode): AstNode | null => {
+  const program = ast as unknown as { body?: readonly AstNode[] };
+  const bodyNodes = program.body ?? [];
+  for (const node of bodyNodes) {
+    if (node.type === 'ExportDefaultDeclaration') {
+      const decl = (node as unknown as { declaration?: AstNode }).declaration;
+      return decl ?? null;
+    }
+  }
+  return null;
+};
+
+// Bounded recursion: one transitive hop through `export { ... } from`.
+const MAX_RERESOLVE_DEPTH = 1;
+
+/** Check whether a local declaration node has a `Result<...>` return annotation. */
+const isResultHelperDeclaration = (
+  declarationNode: AstNode | undefined,
+  source: string
+): boolean => {
+  if (!declarationNode) {
+    return false;
+  }
+  if (isFunctionLikeExpression(declarationNode)) {
+    return hasResultReturnType(declarationNode, source);
+  }
+  if (declarationNode.type === 'FunctionDeclaration') {
+    return hasResultReturnType(declarationNode, source);
+  }
+  return false;
+};
+
+/** Resolve an `export default ...` declaration, following one identifier hop. */
+const checkDefaultDeclarationIsResultHelper = (
+  defaultDecl: AstNode,
+  targetSource: string,
+  targetLocalDeclarations: DeclarationIndex
+): boolean => {
+  if (isResultHelperDeclaration(defaultDecl, targetSource)) {
+    return true;
+  }
+  if (defaultDecl.type === 'Identifier') {
+    const name = extractIdentifierName(defaultDecl);
+    const referenced = name ? targetLocalDeclarations.get(name) : undefined;
+    return isResultHelperDeclaration(referenced, targetSource);
+  }
+  return false;
+};
+
+interface LoadedTargetFile {
+  readonly ast: AstNode;
+  readonly source: string;
+  readonly localDeclarations: DeclarationIndex;
+}
+
+const loadTargetFile = (targetPath: string): LoadedTargetFile | null => {
+  try {
+    const source = readFileSync(targetPath, 'utf8');
+    const ast = parse(targetPath, source) as AstNode | null;
+    if (!ast) {
+      return null;
+    }
+    return {
+      ast,
+      localDeclarations: indexLocalDeclarations(ast),
+      source,
+    };
+  } catch {
+    return null;
+  }
+};
+
+interface ReExportContext {
+  readonly loadedTarget: LoadedTargetFile | null;
+  readonly downstreamResultNames: ReadonlySet<string>;
+}
+
+const applyDefaultSpecifier = (
+  info: ExportSpecifierInfo,
+  loadedTarget: LoadedTargetFile | null,
+  collected: Set<string>
+): void => {
+  if (!loadedTarget) {
+    return;
+  }
+  const defaultDecl = getExportDefaultDeclaration(loadedTarget.ast);
+  if (!defaultDecl) {
+    return;
+  }
+  if (
+    checkDefaultDeclarationIsResultHelper(
+      defaultDecl,
+      loadedTarget.source,
+      loadedTarget.localDeclarations
+    )
+  ) {
+    collected.add(info.exportedName);
+  }
+};
+
+const applySpecifierInfo = (
+  info: ExportSpecifierInfo,
+  ctx: ReExportContext,
+  collected: Set<string>
+): void => {
+  if (info.isDefault) {
+    applyDefaultSpecifier(info, ctx.loadedTarget, collected);
+    return;
+  }
+  if (ctx.downstreamResultNames.has(info.localName)) {
+    collected.add(info.exportedName);
+  }
+};
+
+const resolveReExportTargetPath = (
+  node: AstNode,
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number
+): string | null => {
+  if (depth >= MAX_RERESOLVE_DEPTH) {
+    return null;
+  }
+  const reSource = getImportSourceValue(node);
+  if (!reSource) {
+    return null;
+  }
+  const reTargetPath = resolveRelativeImportPath(reSource, targetPath);
+  if (!reTargetPath || visited.has(reTargetPath)) {
+    return null;
+  }
+  return reTargetPath;
+};
+
+const buildReExportContext = (
+  reTargetPath: string,
+  specifierInfos: readonly ExportSpecifierInfo[],
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number
+): ReExportContext => {
+  const needsDefault = specifierInfos.some((info) => info.isDefault);
+  // Load once when the default specifier branch needs the target AST; the
+  // same loaded object is threaded into the downstream walk so it isn't
+  // read and parsed a second time within this check() call.
+  const loadedTarget = needsDefault ? loadTargetFile(reTargetPath) : null;
+  // eslint-disable-next-line no-use-before-define
+  const downstreamResultNames = collectTargetExportedResultHelperNames(
+    reTargetPath,
+    visited,
+    targetPath,
+    depth + 1,
+    loadedTarget
+  );
+  return {
+    downstreamResultNames,
+    loadedTarget,
+  };
+};
+
+/**
+ * Resolve a re-export with source (`export { ... } from './x.js'`) by pulling
+ * the matching names off the target file, honoring aliases and `default`.
+ */
+const resolveReExportWithSource = (
+  node: AstNode,
+  specifiers: readonly AstNode[],
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number,
+  collected: Set<string>
+): void => {
+  const reTargetPath = resolveReExportTargetPath(
+    node,
+    targetPath,
+    visited,
+    depth
+  );
+  if (!reTargetPath) {
+    return;
+  }
+  const specifierInfos = specifiers.flatMap((spec) => {
+    const info = buildExportSpecifierInfo(spec);
+    return info ? [info] : [];
+  });
+  const ctx = buildReExportContext(
+    reTargetPath,
+    specifierInfos,
+    targetPath,
+    visited,
+    depth
+  );
+  for (const info of specifierInfos) {
+    applySpecifierInfo(info, ctx, collected);
+  }
+};
+
+/** Resolve a specifier-only re-export (`export { helper };`) against same-file declarations. */
+const resolveReExportWithoutSource = (
+  specifiers: readonly AstNode[],
+  localDeclarations: DeclarationIndex,
+  source: string,
+  collected: Set<string>
+): void => {
+  for (const spec of specifiers) {
+    const info = buildExportSpecifierInfo(spec);
+    if (!info || info.isDefault) {
+      continue;
+    }
+    if (
+      isResultHelperDeclaration(localDeclarations.get(info.localName), source)
+    ) {
+      collected.add(info.exportedName);
+    }
+  }
+};
+
+const processInlineExportedDeclaration = (
+  exportedDecl: AstNode,
+  source: string,
+  collected: Set<string>
+): boolean => {
+  if (exportedDecl.type === 'VariableDeclaration') {
+    addExportedVariableResultHelper(exportedDecl, source, collected);
+    return true;
+  }
+  if (exportedDecl.type === 'FunctionDeclaration') {
+    addExportedFunctionResultHelper(exportedDecl, source, collected);
+    return true;
+  }
+  return false;
+};
+
+const processExportNamedDeclaration = (
+  node: AstNode,
+  source: string,
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number,
+  localDeclarations: DeclarationIndex,
+  collected: Set<string>
+): void => {
+  const exportedDecl = getExportedDeclaration(node);
+  if (
+    exportedDecl &&
+    processInlineExportedDeclaration(exportedDecl, source, collected)
+  ) {
+    return;
+  }
+  const specifiers =
+    (node['specifiers'] as readonly AstNode[] | undefined) ?? [];
+  if (specifiers.length === 0) {
+    return;
+  }
+  if (getImportSourceValue(node)) {
+    resolveReExportWithSource(
+      node,
+      specifiers,
+      targetPath,
+      visited,
+      depth,
+      collected
+    );
+    return;
+  }
+  resolveReExportWithoutSource(
+    specifiers,
+    localDeclarations,
+    source,
+    collected
+  );
+};
+
+const processExportDefaultDeclaration = (
+  node: AstNode,
+  source: string,
+  localDeclarations: DeclarationIndex,
+  collected: Set<string>
+): void => {
+  const defaultDecl = (node as unknown as { declaration?: AstNode })
+    .declaration;
+  if (!defaultDecl) {
+    return;
+  }
+  if (
+    checkDefaultDeclarationIsResultHelper(
+      defaultDecl,
+      source,
+      localDeclarations
+    )
+  ) {
+    collected.add('default');
+  }
+};
+
+const collectExportedResultHelpersFromAst = (
+  ast: AstNode,
+  source: string,
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number,
+  preloadedLocalDeclarations: DeclarationIndex | null = null
+): ReadonlySet<string> => {
+  const collected = new Set<string>();
+  // Reuse the preloaded declaration index when available (e.g., threaded in
+  // from `loadTargetFile`) to avoid re-walking the same AST.
+  const localDeclarations =
+    preloadedLocalDeclarations ?? indexLocalDeclarations(ast);
+  const program = ast as unknown as { body?: readonly AstNode[] };
+  const bodyNodes = program.body ?? [];
+
+  for (const node of bodyNodes) {
+    if (node.type === 'ExportNamedDeclaration') {
+      processExportNamedDeclaration(
+        node,
+        source,
+        targetPath,
+        visited,
+        depth,
+        localDeclarations,
+        collected
+      );
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      processExportDefaultDeclaration(
+        node,
+        source,
+        localDeclarations,
+        collected
+      );
+    } else if (node.type === 'ExportAllDeclaration') {
+      // eslint-disable-next-line no-use-before-define
+      processExportAllDeclaration(node, targetPath, visited, depth, collected);
+    }
+  }
+
+  return collected;
+};
+
+/**
+ * Handle `export * from './x.js'` by recursing into the target module and
+ * unioning its exported Result-helper names. Type-only re-exports
+ * (`export type * from '...'`) contribute nothing. Bounded by
+ * `MAX_RERESOLVE_DEPTH` and the visited-set cycle guard shared with the
+ * specifier re-export path.
+ */
+const processExportAllDeclaration = (
+  node: AstNode,
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number,
+  collected: Set<string>
+): void => {
+  const { exportKind } = node as unknown as { exportKind?: string };
+  if (exportKind === 'type') {
+    return;
+  }
+  const reTargetPath = resolveReExportTargetPath(
+    node,
+    targetPath,
+    visited,
+    depth
+  );
+  if (!reTargetPath) {
+    return;
+  }
+  // eslint-disable-next-line no-use-before-define
+  const downstream = collectTargetExportedResultHelperNames(
+    reTargetPath,
+    visited,
+    targetPath,
+    depth + 1
+  );
+  // `export * from` does NOT re-export the default binding, so we union
+  // only the named Result helpers from the downstream module.
+  for (const name of downstream) {
+    if (name !== 'default') {
+      collected.add(name);
+    }
+  }
+};
+
+const parseTargetResultHelperNames = (
+  targetPath: string,
+  visited: ReadonlySet<string>,
+  depth: number,
+  preloaded: LoadedTargetFile | null = null
+): ReadonlySet<string> => {
+  const loaded = preloaded ?? loadTargetFile(targetPath);
+  if (!loaded) {
+    return new Set<string>();
+  }
+  return collectExportedResultHelpersFromAst(
+    loaded.ast,
+    loaded.source,
+    targetPath,
+    visited,
+    depth,
+    loaded.localDeclarations
+  );
+};
+
+const buildVisitedPathSet = (
+  parentVisited: ReadonlySet<string>,
+  targetPath: string,
+  parentPath: string | undefined
+): ReadonlySet<string> => {
+  const seeds = [...parentVisited, targetPath];
+  if (parentPath) {
+    seeds.push(parentPath);
+  }
+  return new Set<string>(seeds);
+};
+
+/**
+ * Collect the set of exported names from a target file whose declaration has
+ * an explicit `Result<...>` / `Promise<Result<...>>` return annotation.
+ *
+ * Uses a visited-set on the recursion path to guard against `export { ... }
+ * from` import cycles between files. Depth is capped at a single transitive
+ * hop (see `MAX_RERESOLVE_DEPTH`) — deeper chains silently fall back.
+ */
+// Only the direct-import path (no parents visited) is safe to cache: the
+// computed set is a function of (targetPath, parentVisited), and
+// cycle-truncated results from transitive walks must not bleed into later
+// direct lookups. See PR #204 review.
+const readCachedResultExports = (
+  targetPath: string,
+  parentVisited: ReadonlySet<string>
+): ReadonlySet<string> | undefined => {
+  if (parentVisited.size !== 0) {
+    return;
+  }
+  return targetFileResultExportCache.get(targetPath);
+};
+
+// biome-ignore lint/style/useConst: declared as a function so hoisting lets `buildReExportContext` (a const declared earlier) reference it before its textual definition
+// eslint-disable-next-line func-style, no-use-before-define
+function collectTargetExportedResultHelperNames(
+  targetPath: string,
+  parentVisited: ReadonlySet<string> = new Set<string>(),
+  parentPath?: string,
+  depth = 0,
+  preloaded: LoadedTargetFile | null = null
+): ReadonlySet<string> {
+  if (parentVisited.has(targetPath)) {
+    return new Set<string>();
+  }
+  const cached = readCachedResultExports(targetPath, parentVisited);
+  if (cached) {
+    return cached;
+  }
+  const visited = buildVisitedPathSet(parentVisited, targetPath, parentPath);
+  const names = parseTargetResultHelperNames(
+    targetPath,
+    visited,
+    depth,
+    preloaded
+  );
+  if (parentVisited.size === 0) {
+    targetFileResultExportCache.set(targetPath, names);
+  }
+  return names;
+}
+
+/**
+ * Extend a local-helper-name set with Result-returning helpers imported from
+ * relative modules. Falls back silently on any resolution/parse failure.
+ */
+const collectImportedResultHelperNames = (
+  ast: AstNode,
+  filePath: string
+): ReadonlySet<string> => {
+  const names = new Set<string>();
+
+  for (const binding of collectResolvableImports(ast)) {
+    const targetPath = resolveRelativeImportPath(binding.source, filePath);
+    if (!targetPath) {
+      continue;
+    }
+    const exportedResultNames =
+      collectTargetExportedResultHelperNames(targetPath);
+    if (exportedResultNames.has(binding.importedName)) {
+      names.add(binding.localName);
+    }
+  }
+
+  return names;
+};
+
+interface NamespaceEntry {
+  readonly localName: string;
+  readonly names: ReadonlySet<string>;
+}
+
+/** Extract a namespace specifier's local name if it is a namespace import. */
+const getNamespaceLocalName = (spec: AstNode): string | null => {
+  if (spec.type !== 'ImportNamespaceSpecifier') {
+    return null;
+  }
+  const { local } = spec as unknown as { local?: AstNode };
+  return extractIdentifierName(local);
+};
+
+/**
+ * Resolve a single namespace specifier to (localName, resultHelperNames), or
+ * null when the specifier is not a resolvable namespace import.
+ *
+ * We intentionally record the namespace even when the target file exports no
+ * Result helpers (empty set). `isNamespaceHelperMemberCall` can then identify
+ * `ns.anything()` as a namespace member call against a non-Result-helper
+ * target — which correctly falls through to the general return-value
+ * diagnostic path. Dropping the entry would misclassify the call as a
+ * *non-namespace* member call and skip the namespace-shadowing scope check.
+ */
+const resolveNamespaceSpecifier = (
+  spec: AstNode,
+  source: string,
+  filePath: string
+): NamespaceEntry | null => {
+  const localName = getNamespaceLocalName(spec);
+  if (!localName) {
+    return null;
+  }
+  const targetPath = resolveRelativeImportPath(source, filePath);
+  if (!targetPath) {
+    return null;
+  }
+  const names = collectTargetExportedResultHelperNames(targetPath);
+  return { localName, names };
+};
+
+/** Extract namespace helper entries from a single ImportDeclaration node. */
+const namespaceEntriesFromImport = (
+  node: AstNode,
+  filePath: string
+): readonly NamespaceEntry[] => {
+  const source = getImportSourceValue(node);
+  if (!source) {
+    return [];
+  }
+  const specifiers =
+    (node['specifiers'] as readonly AstNode[] | undefined) ?? [];
+  return specifiers.flatMap((spec) => {
+    const entry = resolveNamespaceSpecifier(spec, source, filePath);
+    return entry ? [entry] : [];
+  });
+};
+
+/**
+ * Collect `import * as ns from './foo.js'` bindings and map each local
+ * namespace name to the set of Result-returning helper names exported by the
+ * resolved target module. Returns an empty map if no namespace imports are
+ * found or none resolve to local files.
+ */
+const collectNamespaceHelperImports = (
+  ast: AstNode,
+  filePath: string
+): NamespaceHelperMap => {
+  const map = new Map<string, ReadonlySet<string>>();
+  walk(ast, (node) => {
+    if (node.type !== 'ImportDeclaration') {
+      return;
+    }
+    for (const { localName, names } of namespaceEntriesFromImport(
+      node,
+      filePath
+    )) {
+      map.set(localName, names);
+    }
+  });
+  return map;
+};
+
+/**
+ * Combine same-file helper names with helpers imported from relative modules.
+ */
+const collectAllResultHelperNames = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string
+): ReadonlySet<string> => {
+  const local = collectResultHelperNames(ast, sourceCode);
+  const imported = collectImportedResultHelperNames(ast, filePath);
+  if (imported.size === 0) {
+    return local;
+  }
+  const merged = new Set<string>(local);
+  for (const name of imported) {
+    merged.add(name);
+  }
+  return merged;
+};
+
 // ---------------------------------------------------------------------------
 // Per-implementation checking
 // ---------------------------------------------------------------------------
@@ -318,6 +1224,7 @@ const checkImplementation = (
   filePath: string,
   sourceCode: string,
   helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
   diagnostics: WardenDiagnostic[]
 ): void => {
   const fnBody = (implValue as unknown as { body?: AstNode }).body;
@@ -325,6 +1232,10 @@ const checkImplementation = (
     return;
   }
 
+  // Seed analysis with the implementation's own bindings so parameter names
+  // and hoisted vars shadow namespace imports in both block and concise bodies.
+  const implScope = collectScopeFrameBindings(implValue);
+
   if (fnBody.type === 'BlockStatement' || fnBody.type === 'FunctionBody') {
     checkReturnStatements(
       fnBody,
@@ -332,12 +1243,19 @@ const checkImplementation = (
       filePath,
       sourceCode,
       helperNames,
-      diagnostics
+      namespaceHelpers,
+      diagnostics,
+      implScope
     );
     return;
   }
 
-  if (!isResultExpression(fnBody) && !isHelperCall(fnBody, helperNames)) {
+  const conciseScopes: readonly ReadonlySet<string>[] =
+    implScope.size > 0 ? [implScope] : [];
+  if (
+    !isResultExpression(fnBody) &&
+    !isHelperCall(fnBody, helperNames, namespaceHelpers, conciseScopes)
+  ) {
     diagnostics.push({
       filePath,
       line: offsetToLine(sourceCode, implValue.start),
@@ -358,7 +1276,8 @@ const checkAllDefinitions = (
   sourceCode: string
 ): WardenDiagnostic[] => {
   const diagnostics: WardenDiagnostic[] = [];
-  const helperNames = collectResultHelperNames(ast, sourceCode);
+  const helperNames = collectAllResultHelperNames(ast, sourceCode, filePath);
+  const namespaceHelpers = collectNamespaceHelperImports(ast, filePath);
 
   for (const def of findTrailDefinitions(ast)) {
     const info = { id: def.id, label: 'Trail' };
@@ -369,6 +1288,7 @@ const checkAllDefinitions = (
         filePath,
         sourceCode,
         helperNames,
+        namespaceHelpers,
         diagnostics
       );
     }