refactor(traverse): harden soundness of Traverse and document safet…

…y invariants better (#8507)

Harden soundness of `Traverse` by:

1. Not exposing `walk_*` methods outside of `walk.rs`.
2. Adding more debug assertions.
3. Adding `#[must_use]` to `TraverseAncestry::push_stack`, so we'll get a lint error if codegen-ed code pushes to `TraverseAncestry`'s stack and doesn't pop it off again.

Document the safety invariants better.

crates/oxc_traverse/scripts/lib/walk.mjs

@@ -42,9 +42,24 @@ export default function generateWalkFunctionsCode(types) {
 
     use crate::{ancestor::{self, AncestorType}, Ancestor, Traverse, TraverseCtx};
 
+    /// Walk AST with \`Traverse\` impl.
+    ///
+    /// SAFETY:
+    /// * \`program\` must be a pointer to a valid \`Program\` which has lifetime \`'a\`
+    ///   (\`Program<'a>\`).
+    /// * \`ctx\` must contain a \`TraverseAncestry<'a>\` with single \`Ancestor::None\` on its stack.
+    #[inline]
+    pub(crate) unsafe fn walk_ast<'a, Tr: Traverse<'a>>(
+      traverser: &mut Tr,
+      program: *mut Program<'a>,
+      ctx: &mut TraverseCtx<'a>,
+    ) {
+      walk_program(traverser, program, ctx);
+    }
+
     ${walkMethods}
 
-    pub(crate) unsafe fn walk_statements<'a, Tr: Traverse<'a>>(
+    unsafe fn walk_statements<'a, Tr: Traverse<'a>>(
       traverser: &mut Tr,
       stmts: *mut Vec<'a, Statement<'a>>,
       ctx: &mut TraverseCtx<'a>
@@ -254,7 +269,7 @@ function generateWalkForStruct(type, types) {
 
   const typeSnakeName = camelToSnake(type.name);
   return `
-    pub(crate) unsafe fn walk_${typeSnakeName}<'a, Tr: Traverse<'a>>(
+    unsafe fn walk_${typeSnakeName}<'a, Tr: Traverse<'a>>(
       traverser: &mut Tr,
       node: *mut ${type.rawName},
       ctx: &mut TraverseCtx<'a>
@@ -319,7 +334,7 @@ function generateWalkForEnum(type, types) {
 
   const typeSnakeName = camelToSnake(type.name);
   return `
-    pub(crate) unsafe fn walk_${typeSnakeName}<'a, Tr: Traverse<'a>>(
+    unsafe fn walk_${typeSnakeName}<'a, Tr: Traverse<'a>>(
       traverser: &mut Tr,
       node: *mut ${type.rawName},
       ctx: &mut TraverseCtx<'a>

crates/oxc_traverse/src/context/ancestry.rs

@@ -147,6 +147,7 @@ impl<'a> TraverseAncestry<'a> {
     /// # SAFETY
     /// This method must not be public outside this crate, or consumer could break safety invariants.
     #[inline]
+    #[must_use] // `PopToken` must be passed to `pop_stack` to pop this entry off the stack again
     pub(crate) fn push_stack(&mut self, ancestor: Ancestor<'a, 'static>) -> PopToken {
         self.stack.push(ancestor);