@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

package/src/rules/no-sync-result-assumption.ts

@@ -1,45 +1,43 @@
-import type { WardenDiagnostic, WardenRule } from './types.js';
-import {
-  isFrameworkInternalFile,
-  isTestFile,
-  stripQuotedContent,
-} from './scan.js';
-
-const RESULT_ACCESS_PATTERN =
-  /\.(?:isOk|isErr|match|map)\s*\(|\.(?:value|error)\b/;
-const IMPLEMENTATION_CALL_PATTERN = /\.run\s*\(/;
-
-const isAwaitedImplementationCall = (line: string): boolean => {
-  const callIndex = line.indexOf('.run(');
-  if (callIndex === -1) {
-    return false;
-  }
-
-  const awaitIndex = line.indexOf('await');
-  return awaitIndex !== -1 && awaitIndex < callIndex;
-};
-
-const isDirectResultAccess = (line: string): boolean =>
-  IMPLEMENTATION_CALL_PATTERN.test(line) &&
-  RESULT_ACCESS_PATTERN.test(line) &&
-  !isAwaitedImplementationCall(line);
+import { resultAccessorNames } from '@ontrails/core';
 
-const isPendingUse = (line: string, variableName: string): boolean => {
-  const escaped = variableName.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const pendingPattern = new RegExp(
-    `\\b${escaped}\\s*(?:\\.(?:isOk|isErr|match|map)\\s*\\(|\\.(?:value|error)\\b)`
-  );
-  return pendingPattern.test(line);
-};
+import {
+  getNodeAlternate,
+  getNodeArgument,
+  getNodeBodyNode,
+  getNodeBodyStatements,
+  getNodeConsequent,
+  getNodeDeclarations,
+  getNodeElements,
+  getNodeExpression,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeKind,
+  getNodeLeft,
+  getNodeName,
+  getNodeObject,
+  getNodeOperator,
+  getNodeParam,
+  getNodeParams,
+  getNodeProperties,
+  getNodeProperty,
+  getNodeRight,
+  getNodeValueNode,
+  identifierName,
+  isImplementationCall,
+  offsetToLine,
+  parse,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isFrameworkInternalFile, isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
 
-interface PendingCall {
-  line: number;
-  remainingLines: number;
-  variableName: string;
-}
+const RESULT_ACCESSOR_PROPERTIES: ReadonlySet<string> = new Set(
+  resultAccessorNames
+);
 
 const MISSING_AWAIT_MESSAGE =
-  'Missing await: .run() returns Promise<Result> after normalization. Use `const result = await trail.run(input, ctx)`.';
+  'Missing await: .implementation() returns Promise<Result> after normalization. Use `const result = await trail.implementation(input, ctx)`.';
 
 const createMissingAwaitDiagnostic = (
   filePath: string,
@@ -52,105 +50,1150 @@ const createMissingAwaitDiagnostic = (
   severity: 'error',
 });
 
-const trackPendingCall = (line: string): string | undefined => {
-  const match = line.match(
-    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;]*)/
+const isAstLike = (value: unknown): value is AstNode =>
+  !!value && typeof value === 'object' && !!(value as AstNode).type;
+
+/**
+ * Build parent map for a full AST.
+ *
+ * Populates a `WeakMap` directly during traversal so we never materialize a
+ * strong `Map` holding references to every AST node — the WeakMap lets parent
+ * entries be reclaimed alongside their nodes once the rule invocation ends.
+ */
+const buildParentMap = (ast: AstNode): WeakMap<AstNode, AstNode> => {
+  const parents = new WeakMap<AstNode, AstNode>();
+
+  const recordAndVisit = (child: unknown, parent: AstNode): void => {
+    if (isAstLike(child)) {
+      parents.set(child, parent);
+      // eslint-disable-next-line no-use-before-define
+      visit(child);
+    }
+  };
+
+  const visit = (node: AstNode): void => {
+    for (const val of Object.values(node)) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          recordAndVisit(item, node);
+        }
+      } else {
+        recordAndVisit(val, node);
+      }
+    }
+  };
+
+  visit(ast);
+  return parents;
+};
+
+/**
+ * Walk up the parent chain and return true when the expression is awaited
+ * before any result-accessing member access fires on it.
+ *
+ * `await x.implementation(...)` → awaited.
+ * `(await x.implementation(...)).isOk()` → awaited (await wraps before member access).
+ * `x.implementation(...).isOk()` → NOT awaited (member access on raw call).
+ */
+const TRANSPARENT_WRAPPER_TYPES = new Set([
+  'ParenthesizedExpression',
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'TSTypeAssertion',
+]);
+
+const skipParens = (
+  node: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): AstNode => {
+  let current = node;
+  let parent = parents.get(current);
+  while (parent?.type && TRANSPARENT_WRAPPER_TYPES.has(parent.type)) {
+    current = parent;
+    parent = parents.get(current);
+  }
+  return current;
+};
+
+/**
+ * Walk up through any wrapping parentheses and, when the current node sits
+ * in the `consequent` or `alternate` of a `ConditionalExpression`, through
+ * that conditional too. Returns the node whose parent should be inspected.
+ *
+ * Conservative: we only hop across a conditional when the node is one of
+ * its branches (not the `test` position). This lets us treat both
+ * `const r = cond ? x.implementation(...) : fallback` and
+ * `await (cond ? x.implementation(...) : fallback)` correctly without misattributing
+ * calls used as conditions.
+ */
+const isBranchOfConditional = (outer: AstNode, parent: AstNode): boolean => {
+  if (parent.type !== 'ConditionalExpression') {
+    return false;
+  }
+  return (
+    getNodeConsequent(parent) === outer || getNodeAlternate(parent) === outer
   );
-  if (!match?.[1] || !match[2] || !IMPLEMENTATION_CALL_PATTERN.test(match[2])) {
-    return undefined;
+};
+
+/**
+ * Logical expressions (`&&`, `||`, `??`) carry the implementation result through either
+ * side. A `.implementation()` on either operand may be the value ultimately bound to a
+ * declarator (e.g. `const r = cond && trail.implementation(...)`), so we treat both
+ * operands as carriers.
+ */
+const isOperandOfLogical = (outer: AstNode, parent: AstNode): boolean => {
+  if (parent.type !== 'LogicalExpression') {
+    return false;
   }
+  return getNodeLeft(parent) === outer || getNodeRight(parent) === outer;
+};
 
-  if (isAwaitedImplementationCall(match[2])) {
-    return undefined;
+const skipParensAndBranchConditionals = (
+  node: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): AstNode => {
+  let outer = skipParens(node, parents);
+  while (true) {
+    const parent = parents.get(outer);
+    if (!parent) {
+      return outer;
+    }
+    if (
+      !(
+        isBranchOfConditional(outer, parent) ||
+        isOperandOfLogical(outer, parent)
+      )
+    ) {
+      return outer;
+    }
+    outer = skipParens(parent, parents);
+  }
+};
+
+const isAwaited = (
+  node: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): boolean => {
+  // Walk up through parens and any conditional whose branch is the implementation
+  // call. `await (c ? x.implementation(...) : fallback)` awaits the conditional as a
+  // whole, so the implementation call in a branch is effectively awaited.
+  const outer = skipParensAndBranchConditionals(node, parents);
+  return parents.get(outer)?.type === 'AwaitExpression';
+};
+
+const memberPropertyName = (node: AstNode): string | null => {
+  if (
+    node.type !== 'MemberExpression' &&
+    node.type !== 'StaticMemberExpression'
+  ) {
+    return null;
+  }
+  const prop = getNodeProperty(node);
+  if (prop?.type !== 'Identifier') {
+    return null;
+  }
+  return getNodeName(prop) ?? null;
+};
+
+/**
+ * Check if the implementation call is directly consumed by a result accessor
+ * (e.g. `foo.implementation(...).isOk()` or `foo.implementation(...).value`).
+ */
+const hasDirectResultAccess = (
+  implementationCall: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): boolean => {
+  // Unwrap wrapping parentheses, conditional branches, and logical-operator
+  // operands so `(x.implementation(...)).isOk()`,
+  // `(cond ? x.implementation(...) : fb).isOk()`, and
+  // `(cond && x.implementation(...)).isOk()` are all detected the same way as the
+  // bare `x.implementation(...).isOk()` shape.
+  const outer = skipParensAndBranchConditionals(implementationCall, parents);
+  const parent = parents.get(outer);
+  if (!parent) {
+    return false;
   }
+  const property = memberPropertyName(parent);
+  return property !== null && RESULT_ACCESSOR_PROPERTIES.has(property);
+};
 
-  return match[1];
+/**
+ * If the implementation call is the init of a VariableDeclarator (directly, through
+ * parens, or as a branch of a ConditionalExpression init), return the bound
+ * identifier name. Otherwise null.
+ */
+const extractAssignedBinding = (
+  implementationCall: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): string | null => {
+  const outer = skipParensAndBranchConditionals(implementationCall, parents);
+  const parent = parents.get(outer);
+  if (!parent || parent.type !== 'VariableDeclarator') {
+    return null;
+  }
+  const id = getNodeId(parent);
+  return identifierName(id);
 };
 
-const addPendingCall = (
-  pendingCalls: PendingCall[],
-  variableName: string,
-  lineNumber: number
+interface PendingBinding {
+  readonly name: string;
+  readonly declarationNode: AstNode;
+  /** Unique id of the scope frame that owns this binding. */
+  readonly scopeId: number;
+}
+
+const isResultAccessorMember = (node: AstNode): boolean => {
+  if (
+    node.type !== 'MemberExpression' &&
+    node.type !== 'StaticMemberExpression'
+  ) {
+    return false;
+  }
+  const property = memberPropertyName(node);
+  return property !== null && RESULT_ACCESSOR_PROPERTIES.has(property);
+};
+
+const getIdentifierObjectName = (node: AstNode): string | null => {
+  const object = getNodeObject(node);
+  return object?.type === 'Identifier' ? identifierName(object) : null;
+};
+
+// ---------------------------------------------------------------------------
+// Scope tracking
+// ---------------------------------------------------------------------------
+
+const collectIdentifierBinding = (pattern: AstNode, out: Set<string>): void => {
+  const name = identifierName(pattern);
+  if (name) {
+    out.add(name);
+  }
+};
+
+const collectAssignmentPatternBindings = (
+  pattern: AstNode,
+  out: Set<string>
 ): void => {
-  pendingCalls.push({
-    line: lineNumber,
-    remainingLines: 6,
-    variableName,
-  });
+  const left = getNodeLeft(pattern);
+  // eslint-disable-next-line no-use-before-define
+  collectPatternBindings(left, out);
 };
 
-const advancePendingCalls = (
-  line: string,
-  filePath: string,
-  lineNumber: number,
-  pendingCalls: PendingCall[],
-  diagnostics: WardenDiagnostic[]
+const collectRestElementBindings = (
+  pattern: AstNode,
+  out: Set<string>
+): void => {
+  const argument = getNodeArgument(pattern);
+  // eslint-disable-next-line no-use-before-define
+  collectPatternBindings(argument, out);
+};
+
+type PatternHandler = (pattern: AstNode, out: Set<string>) => void;
+
+const PATTERN_HANDLERS: Record<string, PatternHandler> = {
+  // eslint-disable-next-line no-use-before-define
+  ArrayPattern: (p, out) => collectArrayPatternBindings(p, out),
+  AssignmentPattern: collectAssignmentPatternBindings,
+  Identifier: collectIdentifierBinding,
+  // eslint-disable-next-line no-use-before-define
+  ObjectPattern: (p, out) => collectObjectPatternBindings(p, out),
+  RestElement: collectRestElementBindings,
+};
+
+/**
+ * Collect binding names introduced by a destructuring / parameter pattern.
+ * Handles Identifier, AssignmentPattern, ObjectPattern, ArrayPattern,
+ * and RestElement shapes.
+ *
+ * `function` declaration (instead of an arrow) so it can be hoisted for the
+ * mutually recursive calls from the array / object pattern helpers below.
+ */
+// biome-ignore lint/style/useConst: hoisted for mutual recursion
+// eslint-disable-next-line func-style
+function collectPatternBindings(
+  pattern: AstNode | undefined,
+  out: Set<string>
+): void {
+  if (!pattern) {
+    return;
+  }
+  const handler = PATTERN_HANDLERS[pattern.type];
+  if (handler) {
+    handler(pattern, out);
+  }
+}
+
+const collectArrayPatternBindings = (
+  pattern: AstNode,
+  out: Set<string>
+): void => {
+  const elements = getNodeElements(pattern);
+  if (!elements) {
+    return;
+  }
+  for (const element of elements) {
+    if (element) {
+      // eslint-disable-next-line no-use-before-define
+      collectPatternBindings(element, out);
+    }
+  }
+};
+
+const collectObjectPatternBindings = (
+  pattern: AstNode,
+  out: Set<string>
+): void => {
+  const properties = getNodeProperties(pattern);
+  if (!properties) {
+    return;
+  }
+  for (const prop of properties) {
+    if (prop.type === 'RestElement') {
+      // eslint-disable-next-line no-use-before-define
+      collectPatternBindings(prop, out);
+    } else {
+      // Property node: value holds the binding pattern.
+      const value = getNodeValueNode(prop);
+      // eslint-disable-next-line no-use-before-define
+      collectPatternBindings(value, out);
+    }
+  }
+};
+
+const SCOPE_NODE_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'BlockStatement',
+  'StaticBlock',
+  'CatchClause',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+]);
+
+const isScopeBoundary = (node: AstNode): boolean =>
+  SCOPE_NODE_TYPES.has(node.type);
+
+/**
+ * Collect the local binding names introduced directly in this scope's own
+ * declarations (params + var/let/const/catch/for declarations), without
+ * descending into nested function or block scopes.
+ *
+ * For function-like scopes, the body (a BlockStatement) is its own child
+ * scope — we do not merge params into it. Params and body bindings are
+ * treated as sibling frames via the scope walk: when entering the function,
+ * we push a frame with params; when entering its body block, we push another
+ * frame with the block's declarations. Nearest-scope resolution treats them
+ * as a single effective scope chain.
+ */
+const FUNCTION_SCOPE_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+const collectVariableDeclarationBindings = (
+  declNode: AstNode | undefined,
+  out: Set<string>
+): void => {
+  if (!declNode || declNode.type !== 'VariableDeclaration') {
+    return;
+  }
+  const declarators = getNodeDeclarations(declNode);
+  if (!declarators) {
+    return;
+  }
+  for (const d of declarators) {
+    const id = getNodeId(d);
+    collectPatternBindings(id, out);
+  }
+};
+
+const getVariableDeclarationKind = (
+  declNode: AstNode | undefined
+): string | null => {
+  if (!declNode || declNode.type !== 'VariableDeclaration') {
+    return null;
+  }
+  return getNodeKind(declNode) ?? null;
+};
+
+/** True if declaration is `var` (function/program-scoped, hoistable). */
+const isVarDeclaration = (declNode: AstNode | undefined): boolean =>
+  getVariableDeclarationKind(declNode) === 'var';
+
+/** Collect only `let`/`const` declarator bindings (block-scoped). */
+const collectBlockScopedDeclaratorBindings = (
+  declNode: AstNode | undefined,
+  out: Set<string>
 ): void => {
-  for (let j = pendingCalls.length - 1; j >= 0; j -= 1) {
-    const pendingCall = pendingCalls[j];
-    if (pendingCall && isPendingUse(line, pendingCall.variableName)) {
-      diagnostics.push(createMissingAwaitDiagnostic(filePath, lineNumber));
-      pendingCalls.splice(j, 1);
-    } else if (pendingCall) {
-      pendingCall.remainingLines -= 1;
-      if (pendingCall.remainingLines <= 0) {
-        pendingCalls.splice(j, 1);
+  const kind = getVariableDeclarationKind(declNode);
+  if (!kind || kind === 'var') {
+    return;
+  }
+  collectVariableDeclarationBindings(declNode, out);
+};
+
+interface FunctionScopeBindings {
+  readonly bindings: Set<string>;
+  readonly paramBindings: Set<string>;
+}
+
+const collectParamBindings = (scope: AstNode): Set<string> => {
+  const paramBindings = new Set<string>();
+  const params = getNodeParams(scope);
+  if (params) {
+    for (const param of params) {
+      collectPatternBindings(param, paramBindings);
+    }
+  }
+  return paramBindings;
+};
+
+const addHoistedVarsFromBody = (scope: AstNode, out: Set<string>): void => {
+  const body = getNodeBodyNode(scope);
+  if (!(body && isAstLike(body))) {
+    return;
+  }
+  const hoisted = new Set<string>();
+  // eslint-disable-next-line no-use-before-define
+  collectHoistedVarBindings(body, hoisted);
+  for (const name of hoisted) {
+    out.add(name);
+  }
+};
+
+const collectFunctionScopeBindingsEx = (
+  scope: AstNode
+): FunctionScopeBindings => {
+  const paramBindings = collectParamBindings(scope);
+  const bindings = new Set<string>(paramBindings);
+  addHoistedVarsFromBody(scope, bindings);
+  return { bindings, paramBindings };
+};
+
+const collectFunctionScopeBindings = (scope: AstNode): Set<string> =>
+  collectFunctionScopeBindingsEx(scope).bindings;
+
+const collectCatchScopeBindings = (scope: AstNode): Set<string> => {
+  const bindings = new Set<string>();
+  const param = getNodeParam(scope);
+  collectPatternBindings(param, bindings);
+  return bindings;
+};
+
+const collectForScopeBindings = (scope: AstNode): Set<string> => {
+  const bindings = new Set<string>();
+  if (scope.type === 'ForStatement') {
+    const init = getNodeInit(scope);
+    collectBlockScopedDeclaratorBindings(init, bindings);
+  } else {
+    const left = getNodeLeft(scope);
+    collectBlockScopedDeclaratorBindings(left, bindings);
+  }
+  return bindings;
+};
+
+const addFunctionDeclarationName = (stmt: AstNode, out: Set<string>): void => {
+  if (stmt.type !== 'FunctionDeclaration') {
+    return;
+  }
+  const id = getNodeId(stmt);
+  const fnName = identifierName(id);
+  if (fnName) {
+    out.add(fnName);
+  }
+};
+
+const addClassDeclarationName = (stmt: AstNode, out: Set<string>): void => {
+  if (stmt.type !== 'ClassDeclaration') {
+    return;
+  }
+  const id = getNodeId(stmt);
+  const className = identifierName(id);
+  if (className) {
+    out.add(className);
+  }
+};
+
+const collectBlockScopedStatementListBindings = (
+  statements: readonly AstNode[] | undefined,
+  out: Set<string>
+): void => {
+  if (!statements) {
+    return;
+  }
+  for (const stmt of statements) {
+    collectBlockScopedDeclaratorBindings(stmt, out);
+    addFunctionDeclarationName(stmt, out);
+    addClassDeclarationName(stmt, out);
+  }
+};
+
+const collectBlockStatementBindings = (scope: AstNode): Set<string> => {
+  const bindings = new Set<string>();
+  const body = getNodeBodyStatements(scope);
+  collectBlockScopedStatementListBindings(body, bindings);
+  // Static initializer blocks own their own VariableEnvironment (per ES spec),
+  // so `var` declarations inside them do not escape into the enclosing class
+  // or function scope. `collectHoistedVarBindings` correctly refuses to compose
+  // a `StaticBlock` boundary from the outside, which means nothing else will
+  // register these bindings. Hoist them here so `var result = trail.implementation(...)`
+  // inside a `static { ... }` block is tracked against the block itself.
+  if (scope.type === 'StaticBlock') {
+    // `collectHoistedVarBindings` is called with the StaticBlock as the root,
+    // so the own-VariableEnvironment check (which refuses to descend *into* a
+    // nested StaticBlock) does not short-circuit traversal of the node itself.
+    // eslint-disable-next-line no-use-before-define
+    collectHoistedVarBindings(scope, bindings);
+  }
+  return bindings;
+};
+
+/**
+ * Collect the local binding names introduced directly in this scope's own
+ * declarations (params + var/let/const/catch/for declarations), without
+ * descending into nested function or block scopes.
+ */
+const collectScopeBindings = (scope: AstNode): Set<string> => {
+  if (FUNCTION_SCOPE_TYPES.has(scope.type)) {
+    return collectFunctionScopeBindings(scope);
+  }
+  if (scope.type === 'CatchClause') {
+    return collectCatchScopeBindings(scope);
+  }
+  if (
+    scope.type === 'ForStatement' ||
+    scope.type === 'ForInStatement' ||
+    scope.type === 'ForOfStatement'
+  ) {
+    return collectForScopeBindings(scope);
+  }
+  if (scope.type === 'BlockStatement' || scope.type === 'StaticBlock') {
+    return collectBlockStatementBindings(scope);
+  }
+  return new Set();
+};
+
+type ScopeKind = 'program' | 'function' | 'block' | 'for' | 'catch';
+
+interface ScopeFrame {
+  readonly id: number;
+  readonly kind: ScopeKind;
+  readonly bindings: Set<string>;
+  /**
+   * For function frames: names that came from parameters (not hoisted `var`s).
+   * A `var` declaration with the same name as a parameter is redundant in JS —
+   * the parameter is the real binding. We track params separately so we don't
+   * register a pending `.implementation()` binding that is actually shadowed by a param.
+   */
+  readonly paramBindings?: Set<string>;
+}
+
+const scopeKindForNode = (node: AstNode): ScopeKind => {
+  if (FUNCTION_SCOPE_TYPES.has(node.type)) {
+    return 'function';
+  }
+  if (node.type === 'CatchClause') {
+    return 'catch';
+  }
+  if (
+    node.type === 'ForStatement' ||
+    node.type === 'ForInStatement' ||
+    node.type === 'ForOfStatement'
+  ) {
+    return 'for';
+  }
+  return 'block';
+};
+
+/**
+ * True when a nested node owns its own VariableEnvironment and therefore stops
+ * `var` hoisting from composing into the enclosing function/program scope.
+ * Covers function-like nodes and `StaticBlock` (ECMAScript: static blocks
+ * introduce their own LexicalEnvironment and VariableEnvironment).
+ */
+const ownsVariableEnvironment = (node: AstNode): boolean =>
+  FUNCTION_SCOPE_TYPES.has(node.type) || node.type === 'StaticBlock';
+
+const collectHoistedVarBindings = (root: AstNode, out: Set<string>): void => {
+  const visit = (node: AstNode, isRoot: boolean): void => {
+    // Nested var-environment owners (functions, static blocks) do not leak
+    // their `var`s to the enclosing scope.
+    if (!isRoot && ownsVariableEnvironment(node)) {
+      return;
+    }
+    if (node.type === 'VariableDeclaration' && isVarDeclaration(node)) {
+      collectVariableDeclarationBindings(node, out);
+    }
+    for (const val of Object.values(node)) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (isAstLike(item)) {
+            visit(item, false);
+          }
+        }
+      } else if (isAstLike(val)) {
+        visit(val, false);
       }
     }
+  };
+  visit(root, true);
+};
+
+interface AnalyzeState {
+  readonly parents: WeakMap<AstNode, AstNode>;
+  readonly diagnostics: WardenDiagnostic[];
+  readonly sourceCode: string;
+  readonly filePath: string;
+  /** Pending `.implementation()` bindings seen so far, keyed by scope id + name. */
+  readonly pendingByScopeAndName: Map<string, PendingBinding>;
+  readonly scopeStack: ScopeFrame[];
+  readonly reportedAt: Set<number>;
+  /**
+   * Monotonic counter for scope frame ids. Intentionally mutable — every other
+   * field on `AnalyzeState` is `readonly`, but this one is incremented with
+   * `state.nextScopeId += 1` each time a scope frame is pushed so sibling
+   * scopes get distinct ids. Keeping it as a plain number (rather than a
+   * boxed `{ current: number }`) avoids an extra allocation and indirection
+   * on a hot path; the mutability is local to `pushScopeIfBoundary`.
+   */
+  nextScopeId: number;
+}
+
+const pendingKey = (scopeId: number, name: string): string =>
+  `${scopeId}\u0000${name}`;
+
+/**
+ * Resolve an identifier use to the nearest enclosing scope frame that binds
+ * the name. Returns `null` if no frame binds it.
+ */
+const resolveNearestScope = (
+  name: string,
+  stack: readonly ScopeFrame[]
+): ScopeFrame | null => {
+  for (let i = stack.length - 1; i >= 0; i -= 1) {
+    const frame = stack[i];
+    if (frame && frame.bindings.has(name)) {
+      return frame;
+    }
   }
+  return null;
 };
 
-const processLine = (
-  line: string,
-  filePath: string,
-  lineNumber: number,
-  pendingCalls: PendingCall[],
-  diagnostics: WardenDiagnostic[]
+/**
+ * Resolve the implementation call to a `{ name, declarator }` pair when it is the init
+ * of a `VariableDeclarator` (directly, through parens, or as a branch of a
+ * `ConditionalExpression` init). Returns null otherwise.
+ */
+const resolveImplementationBinding = (
+  implementationCall: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): { readonly name: string; readonly declarator: AstNode } | null => {
+  const name = extractAssignedBinding(implementationCall, parents);
+  if (!name) {
+    return null;
+  }
+  // Mirror `extractAssignedBinding`: unwrap parens and branch-position
+  // conditionals so the stored declaration node points at the
+  // `VariableDeclarator`, not at an intermediate `ParenthesizedExpression`
+  // or `ConditionalExpression`.
+  const outer = skipParensAndBranchConditionals(implementationCall, parents);
+  const declarator = parents.get(outer);
+  return declarator ? { declarator, name } : null;
+};
+
+/**
+ * Resolve the implementation call to a `{ name, assignment }` pair when it is the RHS
+ * of a plain `=` `AssignmentExpression` with an `Identifier` LHS (directly,
+ * through parens, or as a branch of a conditional/logical expression).
+ *
+ * Covers patterns like:
+ *   let result;
+ *   result = trail.implementation(input, ctx);
+ *   result.isOk();
+ *
+ * Member-expression LHS (`obj.result = implementation(...)`) is intentionally skipped —
+ * those are property writes, not bare bindings we can track by name.
+ */
+const extractPlainIdentifierAssignmentName = (
+  parent: AstNode | undefined
+): string | null => {
+  if (!parent || parent.type !== 'AssignmentExpression') {
+    return null;
+  }
+  const operator = getNodeOperator(parent);
+  const left = getNodeLeft(parent);
+  // Only plain `=` assignments to a bare identifier. Member-expression LHS
+  // (`obj.result = implementation(...)`) is a property write, not a bare binding we
+  // can track by name.
+  if (operator !== '=' || !left || left.type !== 'Identifier') {
+    return null;
+  }
+  return identifierName(left);
+};
+
+const resolveImplementationAssignment = (
+  implementationCall: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): { readonly name: string; readonly assignment: AstNode } | null => {
+  const outer = skipParensAndBranchConditionals(implementationCall, parents);
+  const parent = parents.get(outer);
+  const name = extractPlainIdentifierAssignmentName(parent);
+  return name && parent ? { assignment: parent, name } : null;
+};
+
+/**
+ * True when `declarator` is a `VariableDeclarator` whose parent
+ * `VariableDeclaration` uses the `var` kind. Such declarators re-initialize
+ * a same-named function parameter rather than shadowing it, because `var`
+ * and parameters share the function's VariableEnvironment.
+ */
+const isVarDeclaratorOfParamName = (
+  declarator: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): boolean => {
+  if (declarator.type !== 'VariableDeclarator') {
+    return false;
+  }
+  const decl = parents.get(declarator);
+  return isVarDeclaration(decl);
+};
+
+/**
+ * True when `node` is a plain `=` `AssignmentExpression` with an `Identifier`
+ * LHS. Such an assignment writes to the existing binding for that name — if
+ * that name is a function parameter, the assignment re-initializes the
+ * parameter's slot in the VariableEnvironment, just like `var <name> = ...`.
+ * Compound assignments (`+=`, `??=`, etc.) are excluded because they do not
+ * unconditionally replace the slot with the implementation result.
+ */
+const isAssignmentToParamName = (node: AstNode): boolean => {
+  if (node.type !== 'AssignmentExpression') {
+    return false;
+  }
+  const operator = getNodeOperator(node);
+  const left = getNodeLeft(node);
+  return operator === '=' && left?.type === 'Identifier';
+};
+
+const recordPendingBinding = (
+  implementationCall: AstNode,
+  state: AnalyzeState
+): void => {
+  const binding =
+    resolveImplementationBinding(implementationCall, state.parents) ??
+    (() => {
+      const asn = resolveImplementationAssignment(
+        implementationCall,
+        state.parents
+      );
+      return asn ? { declarator: asn.assignment, name: asn.name } : null;
+    })();
+  if (!binding) {
+    return;
+  }
+  const { name, declarator } = binding;
+  // The pending binding lives in the nearest scope that declares `name`.
+  // That is always the innermost scope in the current stack, because the
+  // variable declaration's id was contributed to its enclosing scope's
+  // bindings when that scope was entered.
+  const owningFrame = resolveNearestScope(name, state.scopeStack);
+  if (!owningFrame) {
+    return;
+  }
+  // If the name resolves to a function parameter, the `var` that visually
+  // appears to declare it is redundant — the parameter is the real binding,
+  // and parameters are not pending `.implementation()` results.
+  //
+  // Carve-out: a `var <name> = implementation(...)` *initializer* inside the same
+  // function body legitimately re-binds the parameter at that point. `var`
+  // and parameters share the function's VariableEnvironment, so the `var`
+  // writes to the existing parameter slot and the subsequent use resolves
+  // to the freshly-assigned `.implementation()` result. Treat that as a pending
+  // binding.
+  //
+  // The same logic applies to a bare `result = implementation(...)` assignment: it
+  // writes to the parameter's existing slot in the same VariableEnvironment,
+  // so the subsequent `result.isOk()` observes the implementation result. Only
+  // compound assignments (`+=`, `??=`, etc.) and member-expression LHS fall
+  // through the param-shadow suppression, because they do not
+  // unconditionally replace the parameter slot with the implementation result.
+  if (
+    owningFrame.paramBindings?.has(name) &&
+    !isVarDeclaratorOfParamName(declarator, state.parents) &&
+    !isAssignmentToParamName(declarator)
+  ) {
+    return;
+  }
+  state.pendingByScopeAndName.set(pendingKey(owningFrame.id, name), {
+    declarationNode: declarator,
+    name,
+    scopeId: owningFrame.id,
+  });
+};
+
+/**
+ * True when `expr`, descended through wrapping parens, conditional branches,
+ * and logical-operator operands, contains a `.implementation()` call that would be
+ * registered by `recordPendingBinding` for this assignment.
+ *
+ * This mirrors the *upward* carrier walk done by
+ * `skipParensAndBranchConditionals` — if a implementation call is anywhere along a
+ * carrier path descending from `expr`, then visiting that implementation call will
+ * re-register the pending binding, so we must not clear it on the way in.
+ */
+type CarrierChildExtractor = (
+  expr: AstNode
+) => readonly (AstNode | undefined)[];
+
+const CARRIER_CHILDREN: Record<string, CarrierChildExtractor> = {
+  ConditionalExpression: (expr) => [
+    getNodeConsequent(expr),
+    getNodeAlternate(expr),
+  ],
+  LogicalExpression: (expr) => {
+    const left = getNodeLeft(expr);
+    const right = getNodeRight(expr);
+    return [left, right];
+  },
+};
+
+const unwrapTransparentWrapper = (expr: AstNode): AstNode | undefined =>
+  getNodeExpression(expr);
+
+// biome-ignore lint/style/useConst: hoisted for recursive call
+// eslint-disable-next-line func-style
+function rhsCarriesImplementationReinit(expr: AstNode | undefined): boolean {
+  if (!expr) {
+    return false;
+  }
+  if (TRANSPARENT_WRAPPER_TYPES.has(expr.type)) {
+    return rhsCarriesImplementationReinit(unwrapTransparentWrapper(expr));
+  }
+  const extractor = CARRIER_CHILDREN[expr.type];
+  if (extractor) {
+    return extractor(expr).some(rhsCarriesImplementationReinit);
+  }
+  return isImplementationCall(expr);
+}
+
+/**
+ * Nullish/falsy-skip compound assignments (`??=`, `||=`) only write to the slot
+ * when the LHS is nullish or falsy. A pending `.implementation()` binding holds a
+ * truthy `Promise<Result>`, so the RHS never runs and the pending binding must
+ * survive them.
+ *
+ * `&&=` is intentionally excluded: it writes when the LHS is truthy, so a
+ * pending `Promise<Result>` is *always* overwritten by the RHS. That matches
+ * the clearing behavior of mathematical compound operators (`+=`, `-=`, ...).
+ */
+const NULLISH_SKIP_OPERATORS = new Set(['??=', '||=']);
+
+interface IdentifierAssignment {
+  readonly operator: string;
+  readonly name: string;
+  readonly right: AstNode | undefined;
+}
+
+const extractIdentifierAssignment = (
+  node: AstNode
+): IdentifierAssignment | null => {
+  if (node.type !== 'AssignmentExpression') {
+    return null;
+  }
+  const operator = getNodeOperator(node);
+  const left = getNodeLeft(node);
+  const right = getNodeRight(node);
+  if (!(operator && left) || left.type !== 'Identifier') {
+    return null;
+  }
+  const name = identifierName(left);
+  return name ? { name, operator, right } : null;
+};
+
+const resolvePendingKeyFor = (
+  name: string,
+  state: AnalyzeState
+): string | null => {
+  const frame = resolveNearestScope(name, state.scopeStack);
+  if (!frame) {
+    return null;
+  }
+  const key = pendingKey(frame.id, name);
+  return state.pendingByScopeAndName.has(key) ? key : null;
+};
+
+/**
+ * Handle a plain `=` assignment (or clearing compound assignment) to a bare
+ * identifier whose name currently has a pending `.implementation()` binding in scope.
+ *
+ * A plain `=` whose RHS carries another implementation call leaves the pending entry
+ * alone — `recordPendingBinding` will re-register it when the implementation call
+ * itself is visited. Otherwise, clear the pending entry: the identifier has
+ * been overwritten with a non-Result value, so the original
+ * `result.isOk()`-style diagnostic no longer applies.
+ *
+ * Nullish/falsy-skip compound assignments (`??=`, `||=`) are ignored — a
+ * truthy pending `Promise<Result>` causes the RHS to be skipped, so the
+ * pending binding is preserved. `&&=` is *not* in this set: a truthy LHS
+ * causes the RHS to always run, overwriting the pending slot, so it falls
+ * through to the clearing path alongside `+=`, `-=`, etc. Member-expression
+ * LHS is ignored because it writes a property, not the tracked identifier.
+ */
+const handleAssignmentReassignment = (
+  node: AstNode,
+  state: AnalyzeState
 ): void => {
-  if (isDirectResultAccess(line)) {
-    diagnostics.push(createMissingAwaitDiagnostic(filePath, lineNumber));
+  const assignment = extractIdentifierAssignment(node);
+  if (!assignment || NULLISH_SKIP_OPERATORS.has(assignment.operator)) {
+    return;
+  }
+  const key = resolvePendingKeyFor(assignment.name, state);
+  if (!key) {
+    return;
+  }
+  // Plain `=` with a implementation-carrying RHS will re-register via
+  // `recordPendingBinding` when the implementation call itself is visited. Other
+  // compound operators (`+=`, `-=`, `*=`, etc.) produce a primitive value
+  // from the existing slot, so they always clear.
+  if (
+    assignment.operator === '=' &&
+    rhsCarriesImplementationReinit(assignment.right)
+  ) {
+    return;
+  }
+  state.pendingByScopeAndName.delete(key);
+};
+
+const reportMissingAwait = (node: AstNode, state: AnalyzeState): void => {
+  if (state.reportedAt.has(node.start)) {
     return;
   }
+  state.reportedAt.add(node.start);
+  state.diagnostics.push(
+    createMissingAwaitDiagnostic(
+      state.filePath,
+      offsetToLine(state.sourceCode, node.start)
+    )
+  );
+};
+
+const findPendingBindingForUse = (
+  node: AstNode,
+  state: AnalyzeState
+): PendingBinding | null => {
+  if (!isResultAccessorMember(node)) {
+    return null;
+  }
+  const name = getIdentifierObjectName(node);
+  if (!name) {
+    return null;
+  }
+  const frame = resolveNearestScope(name, state.scopeStack);
+  if (!frame) {
+    return null;
+  }
+  return state.pendingByScopeAndName.get(pendingKey(frame.id, name)) ?? null;
+};
+
+const checkPendingAccess = (node: AstNode, state: AnalyzeState): void => {
+  const binding = findPendingBindingForUse(node, state);
+  if (!binding) {
+    return;
+  }
+  // Declaration must precede the use. Use source offsets for ordering.
+  if (node.start < binding.declarationNode.end) {
+    return;
+  }
+  reportMissingAwait(node, state);
+};
 
-  const variableName = trackPendingCall(line);
-  if (variableName) {
-    addPendingCall(pendingCalls, variableName, lineNumber);
+/**
+ * If the implementation call is the init of a VariableDeclarator whose id is an
+ * ObjectPattern that destructures any known Result accessor property,
+ * return the declarator node. Otherwise null.
+ *
+ * Catches the core missing-await shape when written as destructuring:
+ *   `const { isOk } = entityShow.implementation(input, ctx)` — no await, immediate
+ *   access to a Result accessor, should fire.
+ */
+const propertyDestructuresResultAccessor = (prop: AstNode): boolean => {
+  if (prop.type === 'RestElement') {
+    return false;
   }
+  const keyName = identifierName(getNodeKey(prop));
+  return keyName !== null && RESULT_ACCESSOR_PROPERTIES.has(keyName);
+};
 
-  advancePendingCalls(line, filePath, lineNumber, pendingCalls, diagnostics);
+const objectPatternHasResultAccessorKey = (pattern: AstNode): boolean => {
+  const properties = getNodeProperties(pattern);
+  return properties?.some(propertyDestructuresResultAccessor) ?? false;
 };
 
-const scanSourceCode = (
+const getDestructuredResultAccessorDeclarator = (
+  implementationCall: AstNode,
+  parents: WeakMap<AstNode, AstNode>
+): AstNode | null => {
+  // Unwrap any wrapping parentheses and branch-position conditionals so
+  // `const { isOk } = (trail.implementation(...));` and
+  // `const { isOk } = cond ? trail.implementation(...) : fallback;` are treated as
+  // `const { isOk } = trail.implementation(...);`.
+  const outer = skipParensAndBranchConditionals(implementationCall, parents);
+  const parent = parents.get(outer);
+  if (!parent || parent.type !== 'VariableDeclarator') {
+    return null;
+  }
+  const id = getNodeId(parent);
+  if (!id || id.type !== 'ObjectPattern') {
+    return null;
+  }
+  return objectPatternHasResultAccessorKey(id) ? parent : null;
+};
+
+const visitImplementationCall = (node: AstNode, state: AnalyzeState): void => {
+  if (!isImplementationCall(node) || isAwaited(node, state.parents)) {
+    return;
+  }
+  if (hasDirectResultAccess(node, state.parents)) {
+    reportMissingAwait(node, state);
+    return;
+  }
+  const destructuredDeclarator = getDestructuredResultAccessorDeclarator(
+    node,
+    state.parents
+  );
+  if (destructuredDeclarator) {
+    reportMissingAwait(destructuredDeclarator, state);
+    return;
+  }
+  recordPendingBinding(node, state);
+};
+
+const visitNode = (node: AstNode, state: AnalyzeState): void => {
+  visitImplementationCall(node, state);
+  checkPendingAccess(node, state);
+};
+
+/**
+ * Post-order visitor for assignment re-assignment clearing.
+ *
+ * `handleAssignmentReassignment` must run *after* the RHS subtree has been
+ * walked. Otherwise a self-referential `result = result.value` would clear
+ * the pending entry before the RHS `result.value` access is observed — the
+ * missing-await diagnostic would disappear even though the write produced
+ * a non-Result value from the same pending slot.
+ */
+const visitNodePost = (node: AstNode, state: AnalyzeState): void => {
+  handleAssignmentReassignment(node, state);
+};
+
+const pushScopeIfBoundary = (node: AstNode, state: AnalyzeState): boolean => {
+  if (!isScopeBoundary(node)) {
+    return false;
+  }
+  const kind = scopeKindForNode(node);
+  if (kind === 'function') {
+    const { bindings, paramBindings } = collectFunctionScopeBindingsEx(node);
+    state.scopeStack.push({
+      bindings,
+      id: state.nextScopeId,
+      kind,
+      paramBindings,
+    });
+  } else {
+    state.scopeStack.push({
+      bindings: collectScopeBindings(node),
+      id: state.nextScopeId,
+      kind,
+    });
+  }
+  state.nextScopeId += 1;
+  return true;
+};
+
+const walkChild = (child: unknown, state: AnalyzeState): void => {
+  if (child && typeof child === 'object' && (child as AstNode).type) {
+    // eslint-disable-next-line no-use-before-define
+    walkWithScopes(child as AstNode, state);
+  }
+};
+
+const walkChildren = (node: AstNode, state: AnalyzeState): void => {
+  for (const val of Object.values(node)) {
+    if (Array.isArray(val)) {
+      for (const item of val) {
+        walkChild(item, state);
+      }
+    } else {
+      walkChild(val, state);
+    }
+  }
+};
+
+// biome-ignore lint/style/useConst: hoisted for mutual recursion with walkChildren
+// eslint-disable-next-line func-style
+function walkWithScopes(node: AstNode, state: AnalyzeState): void {
+  const pushed = pushScopeIfBoundary(node, state);
+  visitNode(node, state);
+  walkChildren(node, state);
+  visitNodePost(node, state);
+  if (pushed) {
+    state.scopeStack.pop();
+  }
+}
+
+const collectProgramBindings = (ast: AstNode): Set<string> => {
+  const bindings = new Set<string>();
+  const programBody = getNodeBodyStatements(ast);
+  // Top-level `let`/`const`/function declarations.
+  collectBlockScopedStatementListBindings(programBody, bindings);
+  // Top-level `var`s are program-scoped; also hoist any `var`s nested
+  // inside blocks/loops at program level.
+  collectHoistedVarBindings(ast, bindings);
+  return bindings;
+};
+
+const analyze = (
+  ast: AstNode,
   sourceCode: string,
   filePath: string
 ): readonly WardenDiagnostic[] => {
-  const diagnostics: WardenDiagnostic[] = [];
-  const lines = sourceCode.split('\n');
-  const pendingCalls: PendingCall[] = [];
-
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
-    if (!line) {
-      continue;
-    }
-    processLine(line, filePath, i + 1, pendingCalls, diagnostics);
-  }
+  const state: AnalyzeState = {
+    diagnostics: [],
+    filePath,
+    nextScopeId: 1,
+    parents: buildParentMap(ast),
+    pendingByScopeAndName: new Map(),
+    reportedAt: new Set(),
+    scopeStack: [
+      { bindings: collectProgramBindings(ast), id: 0, kind: 'program' },
+    ],
+    sourceCode,
+  };
+
+  walkWithScopes(ast, state);
 
-  return diagnostics;
+  return state.diagnostics;
 };
 
 /**
- * Flags code that assumes `.run()` returns a synchronous result.
+ * Flags code that assumes `.implementation()` returns a synchronous result.
  */
 export const noSyncResultAssumption: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     if (isTestFile(filePath) || isFrameworkInternalFile(filePath)) {
       return [];
     }
-    return scanSourceCode(stripQuotedContent(sourceCode), filePath);
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return analyze(ast, sourceCode, filePath);
   },
   description:
-    'Disallow treating .run() as synchronous after normalization. Always await the returned Promise<Result>.',
+    'Disallow treating .implementation() as synchronous after normalization. Always await the returned Promise<Result>.',
   name: 'no-sync-result-assumption',
   severity: 'error',
 };