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

package/dist/rules/implementation-returns-result.js

@@ -5,30 +5,20 @@
  * every return statement returns Result.ok(), Result.err(), ctx.cross(),
  * or a tracked Result-typed variable.
  */
-import { findBlazeBodies, findTrailDefinitions, offsetToLine, parse, walk, } from './ast.js';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { collectScopeFrameBindings, findBlazeBodies, findTrailDefinitions, getMemberExpression, identifierName, offsetToLine, parse, walk, walkWithScopes, } from './ast.js';
 import { isTestFile } from './scan.js';
 // ---------------------------------------------------------------------------
 // Member expression helpers
 // ---------------------------------------------------------------------------
-/** Extract object.property names from a MemberExpression callee. */
-const extractMemberNames = (callee) => {
-    const obj = callee.object;
-    const prop = callee.property;
-    const objName = obj?.type === 'Identifier'
-        ? obj.name
-        : undefined;
-    const propName = prop?.type === 'Identifier'
-        ? prop.name
-        : undefined;
-    return { objName, propName };
-};
-const isMemberExpression = (callee) => callee.type === 'StaticMemberExpression' ||
-    callee.type === 'MemberExpression';
 const isResultMemberCall = (callee) => {
-    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;
     }
@@ -55,8 +45,34 @@ const isResultExpression = (node) => {
     }
     return false;
 };
+/**
+ * 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, namespaceHelpers, scopes = []) => {
+    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, helperNames) => {
+const isHelperCall = (node, helperNames, namespaceHelpers = new Map(), scopes = []) => {
     const target = node.type === 'AwaitExpression'
         ? (node.argument ?? null)
         : node;
@@ -68,7 +84,9 @@ const isHelperCall = (node, helperNames) => {
         const { name } = callee;
         return helperNames.has(name);
     }
-    return false;
+    return callee
+        ? isNamespaceHelperMemberCall(callee, namespaceHelpers, scopes)
+        : false;
 };
 /** Unwrap an optional AwaitExpression to get the inner identifier name. */
 const resolveIdentifierName = (node) => {
@@ -84,11 +102,11 @@ const resolveIdentifierName = (node) => {
     return null;
 };
 /** Check if a return argument is an allowed Result value. */
-const isAllowedReturnArgument = (argument, helperNames, resultVars) => {
+const isAllowedReturnArgument = (argument, helperNames, resultVars, namespaceHelpers, scopes = []) => {
     if (isResultExpression(argument)) {
         return true;
     }
-    if (isHelperCall(argument, helperNames)) {
+    if (isHelperCall(argument, helperNames, namespaceHelpers, scopes)) {
         return true;
     }
     const varName = resolveIdentifierName(argument);
@@ -109,58 +127,13 @@ const trackResultVariable = (node, resultVars) => {
     }
 };
 // ---------------------------------------------------------------------------
-// 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) => !!val &&
-    typeof val === 'object' &&
-    FUNCTION_BOUNDARY_TYPES.has(val.type);
-/** Recurse into a single AST property value, skipping function boundaries. */
-const visitValue = (val, visit, recurse) => {
-    if (Array.isArray(val)) {
-        for (const item of val) {
-            if (!isFunctionBoundary(item)) {
-                recurse(item, visit);
-            }
-        }
-    }
-    else if (val &&
-        typeof val === 'object' &&
-        val.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, visit) => {
-    if (!node || typeof node !== 'object') {
-        return;
-    }
-    const n = node;
-    if (n.type) {
-        visit(n);
-    }
-    for (const val of Object.values(n)) {
-        visitValue(val, visit, walkShallow);
-    }
-};
-// ---------------------------------------------------------------------------
 // Return statement checking
 // ---------------------------------------------------------------------------
 /** Check return statements in a block body for non-Result returns. */
-const checkReturnStatements = (blockBody, trailInfo, filePath, sourceCode, helperNames, diagnostics) => {
+const checkReturnStatements = (blockBody, trailInfo, filePath, sourceCode, helperNames, namespaceHelpers, diagnostics, implScope = new Set()) => {
     const resultVars = new Set();
-    walkShallow(blockBody, (node) => {
+    const initialScopes = implScope.size > 0 ? [implScope] : [];
+    walkWithScopes(blockBody, (node, currentScopes) => {
         if (node.type === 'VariableDeclarator') {
             trackResultVariable(node, resultVars);
         }
@@ -172,7 +145,7 @@ const checkReturnStatements = (blockBody, trailInfo, filePath, sourceCode, helpe
         if (!argument) {
             return;
         }
-        if (isAllowedReturnArgument(argument, helperNames, resultVars)) {
+        if (isAllowedReturnArgument(argument, helperNames, resultVars, namespaceHelpers, currentScopes)) {
             return;
         }
         diagnostics.push({
@@ -182,7 +155,7 @@ const checkReturnStatements = (blockBody, trailInfo, filePath, sourceCode, helpe
             rule: 'implementation-returns-result',
             severity: 'error',
         });
-    });
+    }, { initialScopes, stopAtNestedFunctions: true });
 };
 // ---------------------------------------------------------------------------
 // Result helper name collection
@@ -221,18 +194,606 @@ const collectResultHelperNames = (ast, sourceCode) => {
     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();
+/**
+ * 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 = () => {
+    targetFileResultExportCache.clear();
+};
+const getImportSourceValue = (node) => {
+    const sourceNode = node.source;
+    const sourceValue = sourceNode
+        ? sourceNode.value
+        : undefined;
+    return typeof sourceValue === 'string' ? sourceValue : null;
+};
+const extractIdentifierName = (node) => node?.type === 'Identifier'
+    ? (node.name ?? null)
+    : null;
+const buildDefaultImportBinding = (specifier, source) => {
+    const { local } = specifier;
+    const localName = extractIdentifierName(local);
+    if (!localName) {
+        return null;
+    }
+    return { importedName: 'default', localName, source };
+};
+const buildNamedImportBinding = (specifier, source) => {
+    const { local, imported } = specifier;
+    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, source) => {
+    if (specifier.type === 'ImportDefaultSpecifier') {
+        return buildDefaultImportBinding(specifier, source);
+    }
+    if (specifier.type === 'ImportSpecifier') {
+        return buildNamedImportBinding(specifier, source);
+    }
+    return null;
+};
+const collectBindingsFromImportDeclaration = (node) => {
+    const source = getImportSourceValue(node);
+    if (!source) {
+        return [];
+    }
+    const specifiers = node['specifiers'] ?? [];
+    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) => {
+    const imports = [];
+    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) => {
+    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, fromFile) => {
+    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) => {
+    if (node.type !== 'ExportNamedDeclaration') {
+        return null;
+    }
+    const decl = node.declaration;
+    return decl ?? null;
+};
+const addExportedVariableResultHelper = (decl, source, collected) => {
+    const declarations = decl['declarations'] ?? [];
+    for (const declarator of declarations) {
+        const { id, init } = declarator;
+        const name = extractIdentifierName(id);
+        if (name &&
+            init &&
+            isFunctionLikeExpression(init) &&
+            hasResultReturnType(init, source)) {
+            collected.add(name);
+        }
+    }
+};
+const addExportedFunctionResultHelper = (decl, source, collected) => {
+    const name = extractIdentifierName(decl.id);
+    if (name && hasResultReturnType(decl, source)) {
+        collected.add(name);
+    }
+};
+const indexVariableDeclarationInto = (decl, index) => {
+    const declarators = decl['declarations'] ?? [];
+    for (const declarator of declarators) {
+        const { id, init } = declarator;
+        const name = extractIdentifierName(id);
+        if (name && init && isFunctionLikeExpression(init)) {
+            index.set(name, init);
+        }
+    }
+};
+const indexFunctionDeclarationInto = (decl, index) => {
+    const name = extractIdentifierName(decl.id);
+    if (name) {
+        index.set(name, decl);
+    }
+};
+const indexDeclarationInto = (decl, index) => {
+    if (!decl) {
+        return;
+    }
+    if (decl.type === 'VariableDeclaration') {
+        indexVariableDeclarationInto(decl, index);
+    }
+    else if (decl.type === 'FunctionDeclaration') {
+        indexFunctionDeclarationInto(decl, index);
+    }
+};
+const indexBodyNodeInto = (node, index) => {
+    if (node.type === 'ExportNamedDeclaration') {
+        indexDeclarationInto(getExportedDeclaration(node), index);
+        return;
+    }
+    indexDeclarationInto(node, index);
+};
+const indexLocalDeclarations = (ast) => {
+    const index = new Map();
+    const program = ast;
+    const bodyNodes = program.body ?? [];
+    for (const node of bodyNodes) {
+        indexBodyNodeInto(node, index);
+    }
+    return index;
+};
+const getSpecifierNameNode = (spec, key) => {
+    const node = spec[key];
+    if (!node) {
+        return null;
+    }
+    if (node.type === 'Identifier') {
+        return node.name ?? null;
+    }
+    // Support string-literal specifiers (`export { "default" as X }`, etc).
+    const { value } = node;
+    return typeof value === 'string' ? value : null;
+};
+const buildExportSpecifierInfo = (spec) => {
+    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) => {
+    const program = ast;
+    const bodyNodes = program.body ?? [];
+    for (const node of bodyNodes) {
+        if (node.type === 'ExportDefaultDeclaration') {
+            const decl = node.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, source) => {
+    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, targetSource, targetLocalDeclarations) => {
+    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;
+};
+const loadTargetFile = (targetPath) => {
+    try {
+        const source = readFileSync(targetPath, 'utf8');
+        const ast = parse(targetPath, source);
+        if (!ast) {
+            return null;
+        }
+        return {
+            ast,
+            localDeclarations: indexLocalDeclarations(ast),
+            source,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+const applyDefaultSpecifier = (info, loadedTarget, collected) => {
+    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, ctx, collected) => {
+    if (info.isDefault) {
+        applyDefaultSpecifier(info, ctx.loadedTarget, collected);
+        return;
+    }
+    if (ctx.downstreamResultNames.has(info.localName)) {
+        collected.add(info.exportedName);
+    }
+};
+const resolveReExportTargetPath = (node, targetPath, visited, depth) => {
+    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, specifierInfos, targetPath, visited, depth) => {
+    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, specifiers, targetPath, visited, depth, collected) => {
+    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, localDeclarations, source, collected) => {
+    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, source, collected) => {
+    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, source, targetPath, visited, depth, localDeclarations, collected) => {
+    const exportedDecl = getExportedDeclaration(node);
+    if (exportedDecl &&
+        processInlineExportedDeclaration(exportedDecl, source, collected)) {
+        return;
+    }
+    const specifiers = node['specifiers'] ?? [];
+    if (specifiers.length === 0) {
+        return;
+    }
+    if (getImportSourceValue(node)) {
+        resolveReExportWithSource(node, specifiers, targetPath, visited, depth, collected);
+        return;
+    }
+    resolveReExportWithoutSource(specifiers, localDeclarations, source, collected);
+};
+const processExportDefaultDeclaration = (node, source, localDeclarations, collected) => {
+    const defaultDecl = node
+        .declaration;
+    if (!defaultDecl) {
+        return;
+    }
+    if (checkDefaultDeclarationIsResultHelper(defaultDecl, source, localDeclarations)) {
+        collected.add('default');
+    }
+};
+const collectExportedResultHelpersFromAst = (ast, source, targetPath, visited, depth, preloadedLocalDeclarations = null) => {
+    const collected = new Set();
+    // 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;
+    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, targetPath, visited, depth, collected) => {
+    const { exportKind } = node;
+    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, visited, depth, preloaded = null) => {
+    const loaded = preloaded ?? loadTargetFile(targetPath);
+    if (!loaded) {
+        return new Set();
+    }
+    return collectExportedResultHelpersFromAst(loaded.ast, loaded.source, targetPath, visited, depth, loaded.localDeclarations);
+};
+const buildVisitedPathSet = (parentVisited, targetPath, parentPath) => {
+    const seeds = [...parentVisited, targetPath];
+    if (parentPath) {
+        seeds.push(parentPath);
+    }
+    return new Set(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, parentVisited) => {
+    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, parentVisited = new Set(), parentPath, depth = 0, preloaded = null) {
+    if (parentVisited.has(targetPath)) {
+        return new Set();
+    }
+    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, filePath) => {
+    const names = new Set();
+    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;
+};
+/** Extract a namespace specifier's local name if it is a namespace import. */
+const getNamespaceLocalName = (spec) => {
+    if (spec.type !== 'ImportNamespaceSpecifier') {
+        return null;
+    }
+    const { local } = spec;
+    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, source, filePath) => {
+    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, filePath) => {
+    const source = getImportSourceValue(node);
+    if (!source) {
+        return [];
+    }
+    const specifiers = node['specifiers'] ?? [];
+    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, filePath) => {
+    const map = new Map();
+    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, sourceCode, filePath) => {
+    const local = collectResultHelperNames(ast, sourceCode);
+    const imported = collectImportedResultHelperNames(ast, filePath);
+    if (imported.size === 0) {
+        return local;
+    }
+    const merged = new Set(local);
+    for (const name of imported) {
+        merged.add(name);
+    }
+    return merged;
+};
+// ---------------------------------------------------------------------------
 // Per-implementation checking
 // ---------------------------------------------------------------------------
-const checkImplementation = (implValue, info, filePath, sourceCode, helperNames, diagnostics) => {
+const checkImplementation = (implValue, info, filePath, sourceCode, helperNames, namespaceHelpers, diagnostics) => {
     const fnBody = implValue.body;
     if (!fnBody) {
         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, info, filePath, sourceCode, helperNames, diagnostics);
+        checkReturnStatements(fnBody, info, filePath, sourceCode, helperNames, namespaceHelpers, diagnostics, implScope);
         return;
     }
-    if (!isResultExpression(fnBody) && !isHelperCall(fnBody, helperNames)) {
+    const conciseScopes = implScope.size > 0 ? [implScope] : [];
+    if (!isResultExpression(fnBody) &&
+        !isHelperCall(fnBody, helperNames, namespaceHelpers, conciseScopes)) {
         diagnostics.push({
             filePath,
             line: offsetToLine(sourceCode, implValue.start),
@@ -247,11 +808,12 @@ const checkImplementation = (implValue, info, filePath, sourceCode, helperNames,
 // ---------------------------------------------------------------------------
 const checkAllDefinitions = (ast, filePath, sourceCode) => {
     const diagnostics = [];
-    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' };
         for (const implValue of findBlazeBodies(def.config)) {
-            checkImplementation(implValue, info, filePath, sourceCode, helperNames, diagnostics);
+            checkImplementation(implValue, info, filePath, sourceCode, helperNames, namespaceHelpers, diagnostics);
         }
     }
     return diagnostics;