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

package/dist/rules/no-sync-result-assumption.js

@@ -1,22 +1,13 @@
-import { isFrameworkInternalFile, isTestFile, stripQuotedContent, } from './scan.js';
-const RESULT_ACCESS_PATTERN = /\.(?:isOk|isErr|match|map)\s*\(|\.(?:value|error)\b/;
-const IMPLEMENTATION_CALL_PATTERN = /\.blaze\s*\(/;
-const isAwaitedImplementationCall = (line) => {
-    const callIndex = line.indexOf('.blaze(');
-    if (callIndex === -1) {
-        return false;
-    }
-    const awaitIndex = line.indexOf('await');
-    return awaitIndex !== -1 && awaitIndex < callIndex;
-};
-const isDirectResultAccess = (line) => IMPLEMENTATION_CALL_PATTERN.test(line) &&
-    RESULT_ACCESS_PATTERN.test(line) &&
-    !isAwaitedImplementationCall(line);
-const isPendingUse = (line, variableName) => {
-    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 { identifierName, isBlazeCall, offsetToLine, parse } from './ast.js';
+import { isFrameworkInternalFile, isTestFile } from './scan.js';
+const RESULT_ACCESSOR_PROPERTIES = new Set([
+    'error',
+    'isErr',
+    'isOk',
+    'map',
+    'match',
+    'value',
+]);
 const MISSING_AWAIT_MESSAGE = 'Missing await: .blaze() returns Promise<Result> after normalization. Use `const result = await trail.blaze(input, ctx)`.';
 const createMissingAwaitDiagnostic = (filePath, line) => ({
     filePath,
@@ -25,61 +16,875 @@ const createMissingAwaitDiagnostic = (filePath, line) => ({
     rule: 'no-sync-result-assumption',
     severity: 'error',
 });
-const trackPendingCall = (line) => {
-    const match = line.match(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;]*)/);
-    if (!match?.[1] || !match[2] || !IMPLEMENTATION_CALL_PATTERN.test(match[2])) {
-        return undefined;
+const isAstLike = (value) => !!value && typeof value === 'object' && !!value.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) => {
+    const parents = new WeakMap();
+    const recordAndVisit = (child, parent) => {
+        if (isAstLike(child)) {
+            parents.set(child, parent);
+            // eslint-disable-next-line no-use-before-define
+            visit(child);
+        }
+    };
+    const visit = (node) => {
+        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.blaze(...)` → awaited.
+ * `(await x.blaze(...)).isOk()` → awaited (await wraps before member access).
+ * `x.blaze(...).isOk()` → NOT awaited (member access on raw call).
+ */
+const TRANSPARENT_WRAPPER_TYPES = new Set([
+    'ParenthesizedExpression',
+    'TSAsExpression',
+    'TSSatisfiesExpression',
+    'TSNonNullExpression',
+    'TSTypeAssertion',
+]);
+const skipParens = (node, parents) => {
+    let current = node;
+    let parent = parents.get(current);
+    while (parent?.type && TRANSPARENT_WRAPPER_TYPES.has(parent.type)) {
+        current = parent;
+        parent = parents.get(current);
     }
-    if (isAwaitedImplementationCall(match[2])) {
-        return undefined;
+    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.blaze(...) : fallback` and
+ * `await (cond ? x.blaze(...) : fallback)` correctly without misattributing
+ * calls used as conditions.
+ */
+const isBranchOfConditional = (outer, parent) => {
+    if (parent.type !== 'ConditionalExpression') {
+        return false;
     }
-    return match[1];
+    const cond = parent;
+    return cond.consequent === outer || cond.alternate === outer;
 };
-const addPendingCall = (pendingCalls, variableName, lineNumber) => {
-    pendingCalls.push({
-        line: lineNumber,
-        remainingLines: 6,
-        variableName,
-    });
+/**
+ * Logical expressions (`&&`, `||`, `??`) carry the blaze result through either
+ * side. A `.blaze()` on either operand may be the value ultimately bound to a
+ * declarator (e.g. `const r = cond && trail.blaze(...)`), so we treat both
+ * operands as carriers.
+ */
+const isOperandOfLogical = (outer, parent) => {
+    if (parent.type !== 'LogicalExpression') {
+        return false;
+    }
+    const logical = parent;
+    return logical.left === outer || logical.right === outer;
+};
+const skipParensAndBranchConditionals = (node, parents) => {
+    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, parents) => {
+    // Walk up through parens and any conditional whose branch is the blaze
+    // call. `await (c ? x.blaze(...) : fallback)` awaits the conditional as a
+    // whole, so the blaze call in a branch is effectively awaited.
+    const outer = skipParensAndBranchConditionals(node, parents);
+    return parents.get(outer)?.type === 'AwaitExpression';
+};
+const memberPropertyName = (node) => {
+    if (node.type !== 'MemberExpression' &&
+        node.type !== 'StaticMemberExpression') {
+        return null;
+    }
+    const prop = node.property;
+    if (prop?.type !== 'Identifier') {
+        return null;
+    }
+    return prop.name ?? null;
+};
+/**
+ * Check if the blaze call is directly consumed by a result accessor
+ * (e.g. `foo.blaze(...).isOk()` or `foo.blaze(...).value`).
+ */
+const hasDirectResultAccess = (blazeCall, parents) => {
+    // Unwrap wrapping parentheses, conditional branches, and logical-operator
+    // operands so `(x.blaze(...)).isOk()`,
+    // `(cond ? x.blaze(...) : fb).isOk()`, and
+    // `(cond && x.blaze(...)).isOk()` are all detected the same way as the
+    // bare `x.blaze(...).isOk()` shape.
+    const outer = skipParensAndBranchConditionals(blazeCall, parents);
+    const parent = parents.get(outer);
+    if (!parent) {
+        return false;
+    }
+    const property = memberPropertyName(parent);
+    return property !== null && RESULT_ACCESSOR_PROPERTIES.has(property);
+};
+/**
+ * If the blaze 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 = (blazeCall, parents) => {
+    const outer = skipParensAndBranchConditionals(blazeCall, parents);
+    const parent = parents.get(outer);
+    if (!parent || parent.type !== 'VariableDeclarator') {
+        return null;
+    }
+    const { id } = parent;
+    return identifierName(id);
+};
+const isResultAccessorMember = (node) => {
+    if (node.type !== 'MemberExpression' &&
+        node.type !== 'StaticMemberExpression') {
+        return false;
+    }
+    const property = memberPropertyName(node);
+    return property !== null && RESULT_ACCESSOR_PROPERTIES.has(property);
+};
+const getIdentifierObjectName = (node) => {
+    const { object } = node;
+    return object?.type === 'Identifier' ? identifierName(object) : null;
+};
+// ---------------------------------------------------------------------------
+// Scope tracking
+// ---------------------------------------------------------------------------
+const collectIdentifierBinding = (pattern, out) => {
+    const name = identifierName(pattern);
+    if (name) {
+        out.add(name);
+    }
+};
+const collectAssignmentPatternBindings = (pattern, out) => {
+    const { left } = pattern;
+    // eslint-disable-next-line no-use-before-define
+    collectPatternBindings(left, out);
+};
+const collectRestElementBindings = (pattern, out) => {
+    const { argument } = pattern;
+    // eslint-disable-next-line no-use-before-define
+    collectPatternBindings(argument, out);
+};
+const PATTERN_HANDLERS = {
+    // 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, out) {
+    if (!pattern) {
+        return;
+    }
+    const handler = PATTERN_HANDLERS[pattern.type];
+    if (handler) {
+        handler(pattern, out);
+    }
+}
+const collectArrayPatternBindings = (pattern, out) => {
+    const { elements } = 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, out) => {
+    const { properties } = 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 } = 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) => 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, out) => {
+    if (!declNode || declNode.type !== 'VariableDeclaration') {
+        return;
+    }
+    const declarators = declNode.declarations;
+    if (!declarators) {
+        return;
+    }
+    for (const d of declarators) {
+        const { id } = d;
+        collectPatternBindings(id, out);
+    }
+};
+const getVariableDeclarationKind = (declNode) => {
+    if (!declNode || declNode.type !== 'VariableDeclaration') {
+        return null;
+    }
+    return declNode.kind ?? null;
+};
+/** True if declaration is `var` (function/program-scoped, hoistable). */
+const isVarDeclaration = (declNode) => getVariableDeclarationKind(declNode) === 'var';
+/** Collect only `let`/`const` declarator bindings (block-scoped). */
+const collectBlockScopedDeclaratorBindings = (declNode, out) => {
+    const kind = getVariableDeclarationKind(declNode);
+    if (!kind || kind === 'var') {
+        return;
+    }
+    collectVariableDeclarationBindings(declNode, out);
+};
+const collectParamBindings = (scope) => {
+    const paramBindings = new Set();
+    const { params } = scope;
+    if (params) {
+        for (const param of params) {
+            collectPatternBindings(param, paramBindings);
+        }
+    }
+    return paramBindings;
+};
+const addHoistedVarsFromBody = (scope, out) => {
+    const { body } = scope;
+    if (!(body && isAstLike(body))) {
+        return;
+    }
+    const hoisted = new Set();
+    // eslint-disable-next-line no-use-before-define
+    collectHoistedVarBindings(body, hoisted);
+    for (const name of hoisted) {
+        out.add(name);
+    }
+};
+const collectFunctionScopeBindingsEx = (scope) => {
+    const paramBindings = collectParamBindings(scope);
+    const bindings = new Set(paramBindings);
+    addHoistedVarsFromBody(scope, bindings);
+    return { bindings, paramBindings };
+};
+const collectFunctionScopeBindings = (scope) => collectFunctionScopeBindingsEx(scope).bindings;
+const collectCatchScopeBindings = (scope) => {
+    const bindings = new Set();
+    const { param } = scope;
+    collectPatternBindings(param, bindings);
+    return bindings;
+};
+const collectForScopeBindings = (scope) => {
+    const bindings = new Set();
+    if (scope.type === 'ForStatement') {
+        const { init } = scope;
+        collectBlockScopedDeclaratorBindings(init, bindings);
+    }
+    else {
+        const { left } = scope;
+        collectBlockScopedDeclaratorBindings(left, bindings);
+    }
+    return bindings;
+};
+const addFunctionDeclarationName = (stmt, out) => {
+    if (stmt.type !== 'FunctionDeclaration') {
+        return;
+    }
+    const { id } = stmt;
+    const fnName = identifierName(id);
+    if (fnName) {
+        out.add(fnName);
+    }
+};
+const addClassDeclarationName = (stmt, out) => {
+    if (stmt.type !== 'ClassDeclaration') {
+        return;
+    }
+    const { id } = stmt;
+    const className = identifierName(id);
+    if (className) {
+        out.add(className);
+    }
+};
+const collectBlockScopedStatementListBindings = (statements, out) => {
+    if (!statements) {
+        return;
+    }
+    for (const stmt of statements) {
+        collectBlockScopedDeclaratorBindings(stmt, out);
+        addFunctionDeclarationName(stmt, out);
+        addClassDeclarationName(stmt, out);
+    }
+};
+const collectBlockStatementBindings = (scope) => {
+    const bindings = new Set();
+    const { body } = 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 cross
+    // a `StaticBlock` boundary from the outside, which means nothing else will
+    // register these bindings. Hoist them here so `var result = trail.blaze(...)`
+    // 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) => {
+    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();
 };
-const advancePendingCalls = (line, filePath, lineNumber, pendingCalls, diagnostics) => {
-    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 scopeKindForNode = (node) => {
+    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 crossing into the enclosing function/program scope.
+ * Covers function-like nodes and `StaticBlock` (ECMAScript: static blocks
+ * introduce their own LexicalEnvironment and VariableEnvironment).
+ */
+const ownsVariableEnvironment = (node) => FUNCTION_SCOPE_TYPES.has(node.type) || node.type === 'StaticBlock';
+const collectHoistedVarBindings = (root, out) => {
+    const visit = (node, isRoot) => {
+        // 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);
+};
+const pendingKey = (scopeId, name) => `${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, stack) => {
+    for (let i = stack.length - 1; i >= 0; i -= 1) {
+        const frame = stack[i];
+        if (frame && frame.bindings.has(name)) {
+            return frame;
+        }
+    }
+    return null;
+};
+/**
+ * Resolve the blaze 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 resolveBlazeBinding = (blazeCall, parents) => {
+    const name = extractAssignedBinding(blazeCall, 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(blazeCall, parents);
+    const declarator = parents.get(outer);
+    return declarator ? { declarator, name } : null;
+};
+/**
+ * Resolve the blaze 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.blaze(input, ctx);
+ *   result.isOk();
+ *
+ * Member-expression LHS (`obj.result = blaze(...)`) is intentionally skipped —
+ * those are property writes, not bare bindings we can track by name.
+ */
+const extractPlainIdentifierAssignmentName = (parent) => {
+    if (!parent || parent.type !== 'AssignmentExpression') {
+        return null;
+    }
+    const { operator, left } = parent;
+    // Only plain `=` assignments to a bare identifier. Member-expression LHS
+    // (`obj.result = blaze(...)`) 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 resolveBlazeAssignment = (blazeCall, parents) => {
+    const outer = skipParensAndBranchConditionals(blazeCall, 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, parents) => {
+    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 blaze result.
+ */
+const isAssignmentToParamName = (node) => {
+    if (node.type !== 'AssignmentExpression') {
+        return false;
+    }
+    const { operator, left } = node;
+    return operator === '=' && left?.type === 'Identifier';
+};
+const recordPendingBinding = (blazeCall, state) => {
+    const binding = resolveBlazeBinding(blazeCall, state.parents) ??
+        (() => {
+            const asn = resolveBlazeAssignment(blazeCall, 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 `.blaze()` results.
+    //
+    // Carve-out: a `var <name> = blaze(...)` *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 `.blaze()` result. Treat that as a pending
+    // binding.
+    //
+    // The same logic applies to a bare `result = blaze(...)` assignment: it
+    // writes to the parameter's existing slot in the same VariableEnvironment,
+    // so the subsequent `result.isOk()` observes the blaze 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 blaze 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,
+    });
+};
+const CARRIER_CHILDREN = {
+    ConditionalExpression: (expr) => {
+        const { consequent, alternate } = expr;
+        return [consequent, alternate];
+    },
+    LogicalExpression: (expr) => {
+        const { left, right } = expr;
+        return [left, right];
+    },
+};
+const unwrapTransparentWrapper = (expr) => expr.expression;
+// biome-ignore lint/style/useConst: hoisted for recursive call
+// eslint-disable-next-line func-style
+function rhsCarriesBlazeReinit(expr) {
+    if (!expr) {
+        return false;
+    }
+    if (TRANSPARENT_WRAPPER_TYPES.has(expr.type)) {
+        return rhsCarriesBlazeReinit(unwrapTransparentWrapper(expr));
+    }
+    const extractor = CARRIER_CHILDREN[expr.type];
+    if (extractor) {
+        return extractor(expr).some(rhsCarriesBlazeReinit);
+    }
+    return isBlazeCall(expr);
+}
+/**
+ * Nullish/falsy-skip compound assignments (`??=`, `||=`) only write to the slot
+ * when the LHS is nullish or falsy. A pending `.blaze()` 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(['??=', '||=']);
+const extractIdentifierAssignment = (node) => {
+    if (node.type !== 'AssignmentExpression') {
+        return null;
     }
+    const { operator, left, right } = node;
+    if (!(operator && left) || left.type !== 'Identifier') {
+        return null;
+    }
+    const name = identifierName(left);
+    return name ? { name, operator, right } : null;
+};
+const resolvePendingKeyFor = (name, state) => {
+    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 `.blaze()` binding in scope.
+ *
+ * A plain `=` whose RHS carries another blaze call leaves the pending entry
+ * alone — `recordPendingBinding` will re-register it when the blaze 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, state) => {
+    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 blaze-carrying RHS will re-register via
+    // `recordPendingBinding` when the blaze call itself is visited. Other
+    // compound operators (`+=`, `-=`, `*=`, etc.) produce a primitive value
+    // from the existing slot, so they always clear.
+    if (assignment.operator === '=' && rhsCarriesBlazeReinit(assignment.right)) {
+        return;
+    }
+    state.pendingByScopeAndName.delete(key);
+};
+const reportMissingAwait = (node, state) => {
+    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, state) => {
+    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, state) => {
+    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);
+};
+/**
+ * If the blaze 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.blaze(input, ctx)` — no await, immediate
+ *   access to a Result accessor, should fire.
+ */
+const propertyDestructuresResultAccessor = (prop) => {
+    if (prop.type === 'RestElement') {
+        return false;
+    }
+    const { key } = prop;
+    const keyName = identifierName(key);
+    return keyName !== null && RESULT_ACCESSOR_PROPERTIES.has(keyName);
 };
-const processLine = (line, filePath, lineNumber, pendingCalls, diagnostics) => {
-    if (isDirectResultAccess(line)) {
-        diagnostics.push(createMissingAwaitDiagnostic(filePath, lineNumber));
+const objectPatternHasResultAccessorKey = (pattern) => {
+    const { properties } = pattern;
+    return properties?.some(propertyDestructuresResultAccessor) ?? false;
+};
+const getDestructuredResultAccessorDeclarator = (blazeCall, parents) => {
+    // Unwrap any wrapping parentheses and branch-position conditionals so
+    // `const { isOk } = (trail.blaze(...));` and
+    // `const { isOk } = cond ? trail.blaze(...) : fallback;` are treated as
+    // `const { isOk } = trail.blaze(...);`.
+    const outer = skipParensAndBranchConditionals(blazeCall, parents);
+    const parent = parents.get(outer);
+    if (!parent || parent.type !== 'VariableDeclarator') {
+        return null;
+    }
+    const { id } = parent;
+    if (!id || id.type !== 'ObjectPattern') {
+        return null;
+    }
+    return objectPatternHasResultAccessorKey(id) ? parent : null;
+};
+const visitBlazeCall = (node, state) => {
+    if (!isBlazeCall(node) || isAwaited(node, state.parents)) {
+        return;
+    }
+    if (hasDirectResultAccess(node, state.parents)) {
+        reportMissingAwait(node, state);
         return;
     }
-    const variableName = trackPendingCall(line);
-    if (variableName) {
-        addPendingCall(pendingCalls, variableName, lineNumber);
+    const destructuredDeclarator = getDestructuredResultAccessorDeclarator(node, state.parents);
+    if (destructuredDeclarator) {
+        reportMissingAwait(destructuredDeclarator, state);
+        return;
     }
-    advancePendingCalls(line, filePath, lineNumber, pendingCalls, diagnostics);
+    recordPendingBinding(node, state);
 };
-const scanSourceCode = (sourceCode, filePath) => {
-    const diagnostics = [];
-    const lines = sourceCode.split('\n');
-    const pendingCalls = [];
-    for (let i = 0; i < lines.length; i += 1) {
-        const line = lines[i];
-        if (!line) {
-            continue;
+const visitNode = (node, state) => {
+    visitBlazeCall(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, state) => {
+    handleAssignmentReassignment(node, state);
+};
+const pushScopeIfBoundary = (node, state) => {
+    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, state) => {
+    if (child && typeof child === 'object' && child.type) {
+        // eslint-disable-next-line no-use-before-define
+        walkWithScopes(child, state);
+    }
+};
+const walkChildren = (node, state) => {
+    for (const val of Object.values(node)) {
+        if (Array.isArray(val)) {
+            for (const item of val) {
+                walkChild(item, state);
+            }
         }
-        processLine(line, filePath, i + 1, pendingCalls, diagnostics);
+        else {
+            walkChild(val, state);
+        }
+    }
+};
+// biome-ignore lint/style/useConst: hoisted for mutual recursion with walkChildren
+// eslint-disable-next-line func-style
+function walkWithScopes(node, state) {
+    const pushed = pushScopeIfBoundary(node, state);
+    visitNode(node, state);
+    walkChildren(node, state);
+    visitNodePost(node, state);
+    if (pushed) {
+        state.scopeStack.pop();
     }
-    return diagnostics;
+}
+const collectProgramBindings = (ast) => {
+    const bindings = new Set();
+    const programBody = ast.body;
+    // 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, sourceCode, filePath) => {
+    const state = {
+        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 state.diagnostics;
 };
 /**
  * Flags code that assumes `.blaze()` returns a synchronous result.
@@ -89,7 +894,11 @@ export const noSyncResultAssumption = {
         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 .blaze() as synchronous after normalization. Always await the returned Promise<Result>.',
     name: 'no-sync-result-assumption',