From a080650d4e68e75dd07f4b4f9e0af8a58d5ba75b Mon Sep 17 00:00:00 2001
From: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Date: Tue, 10 Mar 2026 17:37:00 +0000
Subject: [PATCH] docs(linter/plugins): fix documentation of visitor
 compilation (#20202)

Doc comments for visitor compilation had got out of date and contained inaccuracies. Fix that.
---
 apps/oxlint/src-js/plugins/visitor.ts | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/apps/oxlint/src-js/plugins/visitor.ts b/apps/oxlint/src-js/plugins/visitor.ts
index cd27605e5eba7..403cff7e0739c 100644
--- a/apps/oxlint/src-js/plugins/visitor.ts
+++ b/apps/oxlint/src-js/plugins/visitor.ts
@@ -2,11 +2,15 @@
 //
 // # Visitor objects
 //
-// Visitor objects which are generated by rules' `create` functions have keys being either:
-// * Name of an AST type, or selector. or
-// * Name of an AST type or selector, postfixed with `:exit`.
+// Visitor objects which are generated by rules' `create` functions have keys being any of:
 //
-// Each property value must be a function that handles that AST node / selector target.
+// 1. Name of an AST type
+// 2. Arbitrary selector (e.g. `:matches(BinaryExpression, LogicalExpression)`)
+// 3. Name of an AST type, postfixed with `:exit`
+// 4. Arbitrary selector, postfixed with `:exit`
+// 5. CFG handler name (e.g. `onCodePathStart`)
+//
+// Each property value must be a function that handles that AST node / selector target / CFG event arguments.
 //
 // e.g.:
 //
@@ -24,19 +28,23 @@
 //   '*:exit'(node) {
 //     // Called when exiting any node
 //   },
+//   onCodePathStart(codePath, node) {
+//     // Called when CFG event occurs
+//   },
 // }
 // ```
 //
 // # Compiled visitor
 //
-// Compiled visitor is an array with `NODE_TYPES_COUNT` length, keyed by the ID of the node type.
-// `NODE_TYPE_IDS_MAP` maps from type name to ID.
+// Compiled visitor is an array with `TYPE_IDS_COUNT` length, keyed by the ID of the node type / CFG event.
+// `NODE_TYPE_IDS_MAP` maps from type name / CFG event name to ID.
 //
 // Each element of compiled array is one of:
 // * No visitor for this type = `null`.
 // * Visitor for leaf node = visit function.
 // * Visitor for non-leaf node = object of form `{ enter, exit }`,
 //   where each property is either a visitor function or `null`.
+// * Visitor for CFG event = visit function.
 //
 // e.g.:
 //
@@ -52,6 +60,9 @@
 //     exit: null,
 //   },
 //   // ...
+//
+//   // CFG events
+//   function(codePath, node) { /* do stuff */ },
 // ]
 // ```
 //
@@ -71,6 +82,7 @@
 //
 // * `{ enter, exit }` objects which are stored in compiled visitor.
 // * `VisitProp` objects which are used while compiling visitor.
+// * `{ enter: [], exit: [] }` objects which are used while compiling visitor.
 // * Temporary array used to store multiple visit functions in `mergeVisitFns`.
 //
 // The aim is to reduce pressure on the garbage collector. All these recycled objects are long-lived