chore(sync): cascade fleet template@f2ee346

Auto-applied by socket-wheelhouse sync-scaffolding into vscode-socket-security.
4 file(s) touched:
  - .config/oxlint-plugin/lib/iterable-kind.mts
  - .config/oxlint-plugin/rules/no-cached-for-on-iterable.mts
  - .config/oxlint-plugin/rules/prefer-cached-for-loop.mts
  - .config/oxlint-plugin/test/no-cached-for-on-iterable.test.mts

Author: jdalton

.config/oxlint-plugin/lib/iterable-kind.mts

@@ -30,10 +30,33 @@
  *      rule catches. Without this skip, the two rules race each
  *      other and the autofix re-introduces the bug.
  *
- * Both rules register the same visitors (`VariableDeclarator`,
- * `FunctionDeclaration`, `FunctionExpression`,
- * `ArrowFunctionExpression`) and share the resulting per-file map
- * via the helpers in this module.
+ * # Scope handling
+ *
+ * Bindings are resolved by walking the AST `parent` chain from the
+ * USE site upward, stopping at the nearest scope-creating node that
+ * declares the name. A scope-creating node is any of:
+ *
+ *   - `Program` (module / file scope)
+ *   - `BlockStatement` (function body, if/for/while body, bare block)
+ *   - `ForStatement` / `ForOfStatement` / `ForInStatement` (the head
+ *     binding `let i = 0` is scoped to the loop, not the surrounding
+ *     block)
+ *   - any `Function*` node (parameters are scoped to that function)
+ *   - `CatchClause` (the caught-error binding)
+ *
+ * This is the JS `let`/`const` block-scoping model. The fleet's code
+ * uses `const` / `let` exclusively (no `var`), so we don't need to
+ * model `var`'s function-scope hoisting separately.
+ *
+ * Earlier revisions of this module used a single flat `Map<name,
+ * Kind>` populated by visitor side-effect. That model conflated
+ * bindings across scopes — a function-local `const closure = new
+ * Map()` propagated the `map` classification to every other
+ * binding in the file named `closure`, including unrelated arrays
+ * in the parent scope. The scope-walk path fixes that at the cost
+ * of a per-lookup walk; rule lookups happen on `ForStatement` and
+ * `MemberExpression` which are relatively rare, so the overhead is
+ * bounded.
  */
 
 import type { AstNode } from './rule-types.mts'
@@ -57,6 +80,31 @@ export const FLAGGED_KINDS: ReadonlySet<Kind> = new Set([
   'iterable',
 ])
 
+const SCOPE_NODE_TYPES = new Set([
+  'Program',
+  'BlockStatement',
+  'ForStatement',
+  'ForOfStatement',
+  'ForInStatement',
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'TSDeclareFunction',
+  'CatchClause',
+  // Class body has its own lexical environment for method `this` etc.,
+  // but doesn't host `let`/`const` declarations at the body level (only
+  // method definitions). Including it doesn't hurt.
+  'ClassDeclaration',
+  'ClassExpression',
+])
+
+const FUNCTION_NODE_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+  'TSDeclareFunction',
+])
+
 /**
  * Classify a TS type-annotation AST node (the `: T` part of a
  * binding). Returns the kind, or `'unknown'` if the annotation is
@@ -146,67 +194,207 @@ export function classifyInit(init: AstNode | undefined): Kind {
 }
 
 /**
- * Wire the per-file kind-tracking visitors into a rule's visitor
- * map. Returns the kinds Map and a record of visitor handlers the
- * caller should merge into its own visitor return. Use:
+ * Classify a single VariableDeclarator AST node. Type annotation
+ * wins over inferred init kind (explicit > implicit).
+ */
+function classifyVariableDeclarator(declarator: AstNode): Kind {
+  if (!declarator || !declarator.id || declarator.id.type !== 'Identifier') {
+    return 'unknown'
+  }
+  const annotated = classifyTypeAnnotation(declarator.id.typeAnnotation)
+  if (annotated !== 'unknown') {
+    return annotated
+  }
+  return classifyInit(declarator.init)
+}
+
+/**
+ * Find a binding for `name` declared *directly* in the given scope
+ * node (does not recurse into nested scopes). Returns the classified
+ * Kind, or undefined if no such binding exists in this scope.
  *
- *   const { kinds, visitors } = trackKinds()
- *   return {
- *     ...visitors,
- *     ForStatement(node) { … kinds.get(name) … },
- *   }
+ * Each scope-node type stores its declarations differently:
+ *
+ *   - `Program` / `BlockStatement`: scan `body` for top-level
+ *     `VariableDeclaration` and `FunctionDeclaration` nodes.
+ *   - `Function*`: check the function's `params` for an Identifier
+ *     param named `name`. The body BlockStatement is a separate
+ *     scope (visited on the way up).
+ *   - `ForStatement`: check the `init` (a VariableDeclaration whose
+ *     declarators are scoped to the loop).
+ *   - `ForOfStatement` / `ForInStatement`: check the `left` (a
+ *     VariableDeclaration declaring the loop var, scoped to the loop).
+ *   - `CatchClause`: check the `param` Identifier.
  */
-export function trackKinds(): {
-  kinds: Map<string, Kind>
-  visitors: Record<string, (node: AstNode) => void>
-} {
-  const kinds = new Map<string, Kind>()
+function findInScope(scope: AstNode, name: string): Kind | undefined {
+  if (!scope) {
+    return undefined
+  }
 
-  function record(name: string | undefined, kind: Kind): void {
-    if (!name || kind === 'unknown') {
-      return
+  // Function parameter scope.
+  if (FUNCTION_NODE_TYPES.has(scope.type)) {
+    const params: AstNode[] | undefined = scope.params
+    if (params) {
+      for (let i = 0, { length } = params; i < length; i += 1) {
+        const p = params[i]
+        if (p && p.type === 'Identifier' && (p.name as string) === name) {
+          return classifyTypeAnnotation(p.typeAnnotation)
+        }
+      }
     }
-    kinds.set(name, kind)
+    return undefined
   }
 
-  function recordParams(params: AstNode[] | undefined): void {
-    if (!params) {
-      return
+  // Catch clause: single Identifier param.
+  if (scope.type === 'CatchClause') {
+    const p = scope.param
+    if (p && p.type === 'Identifier' && (p.name as string) === name) {
+      return classifyTypeAnnotation(p.typeAnnotation)
     }
-    for (let i = 0, { length } = params; i < length; i += 1) {
-      const p = params[i]
-      if (!p || p.type !== 'Identifier') {
-        continue
+    return undefined
+  }
+
+  // for (let X = …; …; …) — declaration is in scope.init.
+  if (scope.type === 'ForStatement') {
+    const init: AstNode | undefined = scope.init
+    if (init && init.type === 'VariableDeclaration') {
+      const k = findInVariableDeclaration(init, name)
+      if (k !== undefined) {
+        return k
       }
-      const name = p.name as string
-      record(name, classifyTypeAnnotation(p.typeAnnotation))
     }
+    return undefined
   }
 
-  return {
-    kinds,
-    visitors: {
-      VariableDeclarator(node: AstNode) {
-        if (!node.id || node.id.type !== 'Identifier') {
-          return
+  // for (const X of …) / for (const X in …) — declaration is in scope.left.
+  if (
+    scope.type === 'ForOfStatement' ||
+    scope.type === 'ForInStatement'
+  ) {
+    const left: AstNode | undefined = scope.left
+    if (left && left.type === 'VariableDeclaration') {
+      const k = findInVariableDeclaration(left, name)
+      if (k !== undefined) {
+        return k
+      }
+    }
+    return undefined
+  }
+
+  // Program or BlockStatement: scan body for declarations.
+  if (scope.type === 'Program' || scope.type === 'BlockStatement') {
+    const body: AstNode[] | undefined = scope.body
+    if (!body) {
+      return undefined
+    }
+    for (let i = 0, { length } = body; i < length; i += 1) {
+      const stmt = body[i]
+      if (!stmt) {
+        continue
+      }
+      if (stmt.type === 'VariableDeclaration') {
+        const k = findInVariableDeclaration(stmt, name)
+        if (k !== undefined) {
+          return k
         }
-        const name = node.id.name as string
-        const annotated = classifyTypeAnnotation(node.id.typeAnnotation)
-        if (annotated !== 'unknown') {
-          record(name, annotated)
-          return
+      } else if (
+        stmt.type === 'ExportNamedDeclaration' &&
+        stmt.declaration &&
+        stmt.declaration.type === 'VariableDeclaration'
+      ) {
+        const k = findInVariableDeclaration(stmt.declaration, name)
+        if (k !== undefined) {
+          return k
         }
-        record(name, classifyInit(node.init))
-      },
-      FunctionDeclaration(node: AstNode) {
-        recordParams(node.params)
-      },
-      FunctionExpression(node: AstNode) {
-        recordParams(node.params)
-      },
-      ArrowFunctionExpression(node: AstNode) {
-        recordParams(node.params)
-      },
-    },
+      }
+    }
+    return undefined
+  }
+
+  return undefined
+}
+
+/**
+ * Scan a VariableDeclaration node's declarators for one whose id is
+ * `Identifier(name)`. Returns the classified Kind if found, else
+ * undefined.
+ */
+function findInVariableDeclaration(
+  decl: AstNode,
+  name: string,
+): Kind | undefined {
+  const decls: AstNode[] | undefined = decl.declarations
+  if (!decls) {
+    return undefined
+  }
+  for (let i = 0, { length } = decls; i < length; i += 1) {
+    const d = decls[i]
+    if (
+      d &&
+      d.id &&
+      d.id.type === 'Identifier' &&
+      (d.id.name as string) === name
+    ) {
+      return classifyVariableDeclarator(d)
+    }
   }
+  return undefined
+}
+
+/**
+ * Resolve `name` as seen from the use-site `useNode`. Walks the
+ * AST parent chain, checking each scope-creating ancestor for a
+ * direct declaration of `name`. Returns the nearest enclosing
+ * scope's classification, or `'unknown'` if no declaration is
+ * found.
+ *
+ * The walk stops on the first declaring scope (JS lookup
+ * semantics): a function-local `const closure = new Map()` shadows
+ * an outer `const closure = await fn()` even if the inner is
+ * declared "later" in source order, because they live in
+ * different scopes and the use-site picks the nearest declaring
+ * scope on its parent chain.
+ */
+export function resolveKind(useNode: AstNode, name: string): Kind {
+  let cur: AstNode | undefined = useNode
+  while (cur) {
+    if (SCOPE_NODE_TYPES.has(cur.type)) {
+      const k = findInScope(cur, name)
+      if (k !== undefined) {
+        return k
+      }
+    }
+    cur = cur.parent
+  }
+  return 'unknown'
+}
+
+/**
+ * Wire the scope-aware kind resolver into a rule. Returns
+ * `resolveKind(useNode, name)` for the rule to call from its
+ * use-site visitors (e.g. ForStatement / MemberExpression).
+ *
+ * Unlike the older `trackKinds()` API, this returns no visitors:
+ * the resolver walks the AST on-demand instead of building a
+ * pre-populated map. The trade-off is one parent-chain walk per
+ * lookup vs. an O(file-size) population pass at create() time.
+ * Lookups are scoped to rule call sites (ForStatement,
+ * MemberExpression with a Set/Map LHS), so the per-lookup cost
+ * is bounded.
+ *
+ * Usage:
+ *
+ *   const resolveKind = createKindResolver()
+ *   return {
+ *     ForStatement(node) {
+ *       const kind = resolveKind(node, 'someName')
+ *       …
+ *     },
+ *   }
+ */
+export function createKindResolver(): (
+  useNode: AstNode,
+  name: string,
+) => Kind {
+  return resolveKind
 }

.config/oxlint-plugin/rules/no-cached-for-on-iterable.mts

@@ -77,7 +77,10 @@
  * diagnostic message names it explicitly.
  */
 
-import { FLAGGED_KINDS, trackKinds } from '../lib/iterable-kind.mts'
+import {
+  FLAGGED_KINDS,
+  createKindResolver,
+} from '../lib/iterable-kind.mts'
 import type { AstNode, RuleContext } from '../lib/rule-types.mts'
 
 /**
@@ -140,19 +143,21 @@ const rule = {
   },
 
   create(context: RuleContext) {
-    // Per-file kind map + the visitors that populate it. Shared with
-    // prefer-cached-for-loop via lib/iterable-kind.mts so both rules
-    // agree on what "this binding is a Set/Map/Iterable" means.
-    const { kinds, visitors } = trackKinds()
+    // Scope-aware kind resolver. Shared with prefer-cached-for-loop
+    // via lib/iterable-kind.mts so both rules agree on what "this
+    // binding is a Set/Map/Iterable" means — including under
+    // shadowing (a function-local `const closure = new Map()`
+    // does NOT taint an outer-scope `const closure = await fn()`
+    // array binding).
+    const resolveKind = createKindResolver()
 
     return {
-      ...visitors,
       ForStatement(node: AstNode) {
         const iterName = matchCachedForInit(node.init)
         if (!iterName) {
           return
         }
-        const kind = kinds.get(iterName) ?? 'unknown'
+        const kind = resolveKind(node, iterName)
         if (!FLAGGED_KINDS.has(kind)) {
           return
         }
@@ -170,7 +175,7 @@ const rule = {
           return
         }
         const name = node.object.name as string
-        const kind = kinds.get(name) ?? 'unknown'
+        const kind = resolveKind(node, name)
         if (!FLAGGED_KINDS.has(kind)) {
           return
         }