From 6a3797983a555fc808cec9eec600e880c1d9523b Mon Sep 17 00:00:00 2001
From: fisker Cheung <lionkay@gmail.com>
Date: Fri, 17 Oct 2025 20:57:52 +0800
Subject: [PATCH] Improve types for visitor keys (#18095)

---
 src/language-js/utils/index.js       |  6 +++---
 src/utils/ast-utils.js               | 31 ++++++++++++++--------------
 src/utils/create-get-visitor-keys.js | 12 +++++++++++
 3 files changed, 30 insertions(+), 19 deletions(-)

diff --git a/src/language-js/utils/index.js b/src/language-js/utils/index.js
index c6644e2cd..61672144d 100644
--- a/src/language-js/utils/index.js
+++ b/src/language-js/utils/index.js
@@ -15,9 +15,9 @@ import isNodeMatches from "./is-node-matches.js";
 import isTsKeywordType from "./is-ts-keyword-type.js";
 
 /**
- * @import * as Estree from "../types/estree.js"
- * @import AstPath from "../../common/ast-path.js"
- */
+@import * as Estree from "../types/estree.js"
+@import AstPath from "../../common/ast-path.js"
+*/
 
 /**
  * @param {Estree.Node} node
diff --git a/src/utils/ast-utils.js b/src/utils/ast-utils.js
index f204bfe38..7d73e9dfe 100644
--- a/src/utils/ast-utils.js
+++ b/src/utils/ast-utils.js
@@ -1,15 +1,14 @@
 import isObject from "./is-object.js";
 
 /**
- * @typedef {NonNullable<object>} Node
- * @typedef {(unknown) => string[]} GetVisitorKeys
- * @typedef {(unknown) => boolean} Predicate
- */
+@import {GetVisitorKeys, Node} from "../utils/create-get-visitor-keys.js"
+@typedef {(node: Node) => boolean} Predicate
+*/
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
- */
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
+*/
 function* getChildren(node, options) {
   const { getVisitorKeys, filter = () => true } = options;
   const isMatchedNode = (node) => isObject(node) && filter(node);
@@ -30,9 +29,9 @@ function* getChildren(node, options) {
 }
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
- */
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
+*/
 function* getDescendants(node, options) {
   const queue = [node];
   for (let index = 0; index < queue.length; index++) {
@@ -46,17 +45,17 @@ function* getDescendants(node, options) {
 }
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys}} options
- */
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys}} options
+*/
 function isLeaf(node, options) {
   return getChildren(node, options).next().done;
 }
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys, predicate: Predicate}} options
- */
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys, predicate: Predicate}} options
+*/
 function hasDescendant(node, { getVisitorKeys, predicate }) {
   for (const descendant of getDescendants(node, { getVisitorKeys })) {
     if (predicate(descendant)) {
diff --git a/src/utils/create-get-visitor-keys.js b/src/utils/create-get-visitor-keys.js
index de6920a2d..3a4664ecf 100644
--- a/src/utils/create-get-visitor-keys.js
+++ b/src/utils/create-get-visitor-keys.js
@@ -1,8 +1,20 @@
 import toFastProperties from "to-fast-properties";
 
+/**
+@typedef {(node: Node) => VisitorKeys} GetVisitorKeys
+@typedef {NonNullable<object>} Node
+@typedef {readonly string[]} VisitorKeys
+*/
+
+/**
+@param {Record<string, VisitorKeys>} visitorKeys
+@param {string} [typeProperty="type"]
+@returns {GetVisitorKeys}
+*/
 function createGetVisitorKeys(visitorKeys, typeProperty = "type") {
   toFastProperties(visitorKeys);
 
+  /** @type {GetVisitorKeys} */
   function getVisitorKeys(node) {
     const type = node[typeProperty];