casper-context 0.1.0

package/dist/visitors/AssignmentExpression.js

@@ -0,0 +1,104 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = assignmentExpressionVisitor;
+var _constants = require("../utils/constants");
+var _utilityHelpers = require("../utils/utilityHelpers");
+var _astHelpers = require("../utils/astHelpers");
+/**
+ * @fileoverview Transformation Logic & Node Orchestration.
+ * This module integrates AST helpers with utility validators to perform 
+ * the actual replacement of custom global variables (`_$_`) with 
+ * React-compatible State and Context setters.
+ */
+
+/**
+ * Core Constants
+ * @description
+ * - IDENTIFIER: Used to validate if the left-hand side of an assignment is a variable.
+ * - _CCTX_EMPTY: Fallback value for filenames or uninitialized state strings.
+ */
+
+/**
+ * Utility & Validation Helpers
+ * @description
+ * - findContextByVar: Maps a `_$_` variable to its corresponding Context instance name.
+ * - isExcludeFile: Security/Performance gate to prevent processing ignored files.
+ */
+
+/**
+ * AST Transformation Utilities
+ * @description The functional "engine" of the plugin that manipulates the Babel tree.
+ * - buildSpreadObject: Creates the updated state object for setters.
+ * - replaceWithSetState: Handles local component state updates.
+ * - buildUseContextInstance: Injects `useContext` hooks when variables are cross-component.
+ * - replaceWithContextSetState: Handles global/context-based state updates.
+ * - getComponentName: Identifies the immediate parent function.
+ * - getRootParentComponent: Recursively climbs the tree to find the top-level React Component.
+ */
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+
+/**
+ * Babel visitor function for handling assignment expressions in the AST.
+ *
+ * This visitor inspects assignments in the code and replaces or augments them
+ * with state/context updates for variables registered in the `virtualRegistry`.
+ * It handles both direct component state updates and global/shared context updates.
+ *
+ * @param {NodePath} path - The Babel AST path representing the current node.
+ * @param {Object} state - Plugin state, including file info, config, and import metadata.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate AST nodes.
+ * @param {Object<string, Object>} virtualRegistry - Registry of components and their
+ *   registered variables/context info.
+ *
+ * @returns {void}
+ * Updates AST nodes in place and sets plugin state flags; no return value.
+ *
+ * @important
+ * - Only handles assignments where the left-hand identifier starts with the configured prefix.
+ * - Supports both direct component `useState` updates and context-based updates.
+ * - Automatically marks that a global context is needed (`state.needsGblContext = true`).
+ * - Injects `useState` import if missing.
+ * - Silent error handling; consider logging `e` for debugging.
+ */
+function assignmentExpressionVisitor(path, state, t, virtualRegistry) {
+  try {
+    const fileName = state.filename || _constants._CCTX_EMPTY;
+    if (!(0, _utilityHelpers.isExcludeFile)(fileName, this.opts)) return;
+    if (path.node.left.type === _constants.IDENTIFIER) {
+      if (path.node.left.name?.startsWith(state.casperConfig.prefix)) {
+        state.needsGblContext = true;
+        const ctxName = (0, _utilityHelpers.findContextByVar)(path.node.left.name, virtualRegistry);
+        if (!ctxName) return;
+        let {
+          currentFuncParent,
+          componentName
+        } = (0, _astHelpers.getRootParentComponent)(path);
+        if (!componentName) return;
+        let isSameCMP = false;
+        if (ctxName.startsWith(componentName)) {
+          isSameCMP = true;
+        }
+        state.needsGblContext = true;
+        if (!state.importState.reactId && !state.importState.useStateId) {
+          state.needUseStateImport = true;
+        }
+        const updateFunction = (0, _astHelpers.buildSpreadObject)(path, t);
+        if (isSameCMP) {
+          (0, _astHelpers.replaceWithSetState)(path, t, ctxName, updateFunction);
+        } else {
+          (0, _astHelpers.buildUseContextInstance)(currentFuncParent, state, t, ctxName);
+          (0, _astHelpers.replaceWithContextSetState)(path, t, ctxName, updateFunction);
+        }
+      }
+    }
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::assignmentExpressionVisitor::]', e.message);
+  }
+}

package/dist/visitors/CallExpression.js

@@ -0,0 +1 @@
+"use strict";

package/dist/visitors/FunctionDeclaration.js

@@ -0,0 +1,116 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.functionDeclarationExit = functionDeclarationExit;
+var _utilityHelpers = require("../utils/utilityHelpers");
+var _VariableDeclaration = require("./VariableDeclaration");
+var _ReturnStatement = require("./ReturnStatement");
+var _astHelpers = require("../utils/astHelpers");
+var _constants = require("../utils/constants");
+/**
+ * @fileoverview Logic Orchestration for Function Transformation.
+ * This module coordinates the 'Exit' phase of function traversal. It integrates 
+ * specialized visitors for variable declarations and return statements to 
+ * aggregate state metadata before injecting final React Hook declarations.
+ */
+
+/**
+ * Validation & Hashing Utilities
+ * @description
+ * - isExcludeFile: Determines if the current file should be bypassed based on plugin configuration.
+ * - getFilePathHASH: Generates a unique identifier based on the file path to prevent naming collisions.
+ */
+
+/**
+ * Specialized Sub-Visitors
+ * @description These visitors are manually invoked during the function's traversal 
+ * to target specific node types within the component body.
+ * - functionReturnVariableDelarationVisitor: Extracts state-relevant variable data.
+ * - functionDeclarationReturnStatementVisitor: Processes JSX or return values for context binding.
+ */
+
+/**
+ * AST Construction Helpers
+ * @description
+ * - buildCtxUseStateDeclaration: Physically constructs and injects the `useState` 
+ * node into the Abstract Syntax Tree.
+ */
+
+/**
+ * Core Constants
+ * @description
+ * - _CCTX_EMPTY: Provides a safe string fallback for file naming and path resolution.
+ */
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+
+/**
+ * @important
+ * The coordination between these imports ensures that state is only injected 
+ * once per component, and only if the component contains variables prefixed 
+ * with the library's global identifier.
+ */
+
+/**
+ * Babel visitor exit handler for `FunctionDeclaration` nodes.
+ *
+ * This function is invoked when exiting a function declaration during AST traversal.
+ * It inspects the function for any state variables registered in the `virtualRegistry`
+ * and transforms them into React `useState` declarations or context state as needed.
+ *
+ * @param {NodePath} path - The Babel AST path representing the current function declaration.
+ * @param {Object} state - Plugin state, including file info, config, and import metadata.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate AST nodes.
+ * @param {Object<string, Object>} virtualRegistry - Registry of components and their
+ *   registered variables/context info. Each key is `${componentName}_${fileHash}`.
+ *
+ * @returns {void}
+ * Modifies AST nodes in place to inject state declarations and context usage;
+ * does not return a value.
+ *
+ * @important
+ * - Skips files excluded by `isExcludeFile`.
+ * - Only processes functions with a valid name.
+ * - Collects local state variable declarations and return statements using
+ *   `functionReturnVariableDelarationVisitor` and `functionDeclarationReturnStatementVisitor`.
+ * - Converts collected variables into an object expression for `buildCtxUseStateDeclaration`.
+ * - Silent error handling; errors are caught but ignored.
+ *
+ * @example
+ * ```js
+ * // During Babel traversal:
+ * functionDeclarationExit(path, state, t, virtualRegistry);
+ * // Injects useState or context declarations for local state variables in the function
+ * ```
+ */
+function functionDeclarationExit(path, state, t, virtualRegistry) {
+  try {
+    const fileName = state.filename || _constants._CCTX_EMPTY;
+    if (!(0, _utilityHelpers.isExcludeFile)(fileName, this.opts)) return;
+    const name = path.node.id?.name;
+    if (!name) return;
+    const filePathHASH = (0, _utilityHelpers.getFilePathHASH)(fileName);
+    const key = `${name}_${filePathHASH}`;
+    const entry = virtualRegistry[key];
+    if (!entry || !entry.varNames.length) return;
+    const localStateVars = [];
+    path.traverse({
+      VariableDeclarator(varPath) {
+        _VariableDeclaration.functionReturnVariableDelarationVisitor.call(this, varPath, state, t, localStateVars);
+      },
+      ReturnStatement(retPath) {
+        _ReturnStatement.functionDeclarationReturnStatementVisitor.call(this, retPath, state, t, entry);
+      }
+    });
+    if (localStateVars.length === 0) return;
+    const objProps = localStateVars.map(v => t.objectProperty(t.identifier(v.name), v.init || t.nullLiteral()));
+    (0, _astHelpers.buildCtxUseStateDeclaration)(path, t, state, objProps, key);
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::functionDeclarationExit::]', e.message);
+  }
+}

package/dist/visitors/Identifier.js

@@ -0,0 +1,123 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = identifierVisitor;
+var _constants = require("../utils/constants");
+var _utilityHelpers = require("../utils/utilityHelpers");
+var _astHelpers = require("../utils/astHelpers");
+/**
+ * @fileoverview Variable Reference & Usage Orchestration.
+ * This module manages the detection and transformation of custom context variables 
+ * when they are referenced in expressions. It handles the replacement of `_$_` 
+ * identifiers with either local state accessors or injected Context hooks.
+ */
+
+/**
+ * AST Node & Property Constants
+ * @description Identifiers for specific nodes and keys used to navigate the AST 
+ * during variable resolution and replacement.
+ */
+
+/**
+ * Validation & Discovery Utilities
+ * @description 
+ * - isExcludeFile: Ensures the transformation doesn't run on ignored directories.
+ * - findContextByVar: Locates the specific Context instance associated with a variable name.
+ */
+
+/**
+ * AST Transformation & Scope Helpers
+ * @description Functions that physically modify the code and resolve component hierarchy.
+ * - replaceWithContextState: Replaces a reference with a Context-based accessor.
+ * - replaceWithState: Replaces a reference with a local `useState` accessor.
+ * - buildUseContextInstance: Injects the `useContext` hook if the variable is defined elsewhere.
+ * - getRootParentComponent: Finds the top-level React Component to ensure hooks are valid.
+ */
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+
+/**
+ * @important
+ * This module is highly sensitive to Scope. It must distinguish between a variable 
+ * being "written to" (Assignment) and "read from" (Reference) to prevent 
+ * infinite loops in the Babel transformation.
+ */
+
+/**
+ * Babel visitor for handling identifier nodes in the AST.
+ *
+ * This visitor inspects identifiers that start with the configured Casper prefix.
+ * It determines whether the identifier corresponds to a registered component or
+ * context variable and replaces it with the appropriate state or context access
+ * expression. This handles both component-local state and global/shared context usage.
+ *
+ * @param {NodePath} path - The Babel AST path representing the current identifier node.
+ * @param {Object} state - Plugin state, including file info, configuration, and import metadata.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate AST nodes.
+ * @param {Set<Node>} seen - A Set tracking identifiers that have already been processed to avoid duplicates.
+ * @param {Object<string, Object>} virtualRegistry - Registry of components and their
+ *   registered variables/context info.
+ *
+ * @returns {void}
+ * Modifies AST nodes in place by replacing identifiers with either direct state access
+ * or context-based access. Does not return a value.
+ *
+ * @important
+ * - Skips identifiers that are part of declarations, assignments, object keys, or JSX expressions.
+ * - Only processes referenced identifiers matching the configured Casper prefix.
+ * - Sets `state.needsGblContext` when global context usage is required.
+ * - Automatically injects `useState` import if missing.
+ * - Differentiates between same-component state and context usage across components.
+ * - Errors are silently caught.
+ *
+ * @example
+ * ```js
+ * import identifierVisitor from './identifierVisitor';
+ *
+ * identifierVisitor(path, state, t, seen, virtualRegistry);
+ * // Replaces matching identifiers with state or context references
+ * ```
+ */
+function identifierVisitor(path, state, t, seen, virtualRegistry) {
+  try {
+    const fileName = state.filename || _constants._CCTX_EMPTY;
+    if (!(0, _utilityHelpers.isExcludeFile)(fileName, this.opts)) return;
+    if (path.node?.name?.startsWith(state.casperConfig.prefix)) {
+      if (path.parent.type === _constants.VARIABLE_DECLARATOR && path.parentKey === _constants._CCTX_ID || path.parent.type === _constants.ASSIGNMENT_EXPRESSION && path.parentKey === _constants._CCTX_LEFT || path.parent.type === _constants.UPDATE_EXPRESSION && path.parentKey === _constants._CCTX_ARGUMENT) return;
+      if (path.parentPath.isObjectProperty() && path.parentKey === _constants._CCTX_KEY && !path.parent.computed) return;
+      if (path.findParent(p => p.isJSXExpressionContainer() || p.isJSXAttribute() || p.isJSXOpeningElement() || p.isJSXClosingElement() || p.isJSXMemberExpression())) return;
+      if (!path.isReferencedIdentifier()) return;
+      if (!seen.has(path.node)) {
+        seen.add(path.node);
+        state.needsGblContext = true;
+        let {
+          currentFuncParent,
+          componentName
+        } = (0, _astHelpers.getRootParentComponent)(path);
+        const ctxName = (0, _utilityHelpers.findContextByVar)(path.node.name, virtualRegistry);
+        if (!ctxName) return;
+        let isSameCMP = false;
+        if (ctxName.startsWith(componentName)) {
+          isSameCMP = true;
+        }
+        state.needsGblContext = true;
+        if (!state.importState.reactId && !state.importState.useStateId) {
+          state.needUseStateImport = true;
+        }
+        if (isSameCMP) {
+          (0, _astHelpers.replaceWithState)(path, t, ctxName);
+        } else {
+          (0, _astHelpers.buildUseContextInstance)(currentFuncParent, state, t, ctxName);
+          (0, _astHelpers.replaceWithContextState)(path, t, ctxName);
+        }
+      }
+    }
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::identifierVisitor::]', e.message);
+  }
+}

package/dist/visitors/JSXElement.js

@@ -0,0 +1 @@
+"use strict";

package/dist/visitors/Program.js

@@ -0,0 +1,278 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.programEnter = programEnter;
+exports.programExit = programExit;
+var _constants = require("../utils/constants");
+var _utilityHelpers = require("../utils/utilityHelpers");
+var _astHelpers = require("../utils/astHelpers");
+/**
+ * @fileoverview Library Initialization & Dependency Injection Orchestrator.
+ * This module manages the "Prep Phase" of the transformation, ensuring that
+ * required React hooks and internal global context bridges are correctly 
+ * imported or required before any code modifications occur.
+ */
+
+/**
+ * Dependency & Alias Constants
+ * @description Identifiers for React and internal library references used to 
+ * avoid naming collisions with user-defined variables.
+ */
+
+/**
+ * File System & Lifecycle Utilities
+ * @description 
+ * - CONTEXT_FILE_PATH: The absolute path to the generated context bridge.
+ * - resetVarsForFile: Cleanup utility to clear tracking caches between file traversals.
+ * - isExcludeFile: Security gate to prevent transformation of ignored files.
+ * - getFilePathHASH: Generates a unique, stable ID for the current file's state bucket.
+ */
+
+/**
+ * AST Injection Helpers
+ * @description
+ * - buildRequireDeclaration: Injects CommonJS `require` statements at the top of the file.
+ */
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+
+/**
+ * @important
+ * This module is responsible for "Stateful Reset." Every time a new file is 
+ * entered, `resetVarsForFile` must be called to ensure that context variables 
+ * from the previous file do not leak into the current transformation scope.
+ */
+
+/**
+ * Resolves and collects React import information from a file's AST.
+ *
+ * This function inspects all import declarations in the given file's AST
+ * and identifies the React import. It tracks whether React was imported as
+ * a default import, named import, or namespace import, and whether `useState`
+ * is explicitly imported.
+ *
+ * @param {NodePath} path - The Babel AST path representing the file/program node.
+ * @param {Object} state - Plugin state object where resolved import information
+ *   will be stored under `state.importState`.
+ * @param {Object} t - Babel types helper (`@babel/types`) used for AST type checks.
+ *
+ * @returns {void}
+ * Updates `state.importState` with the following structure:
+ * ```js
+ * {
+ *   reactId: Identifier | null,        // Local identifier for React import
+ *   useStateId: Identifier | null,     // Local identifier for useState import
+ *   isDefault: boolean,                // True if React is default-imported
+ *   isNamed: boolean,                  // True if useState is explicitly named-imported
+ *   isNamespace: boolean,              // True if React is namespace-imported
+ *   reactImportPath: ImportDeclaration | null, // AST node of React import
+ * }
+ * ```
+ *
+ * @important
+ * - Only resolves imports where `source.value` equals `REACT_IMPORT_CORE_NAME`.
+ * - Handles three import forms:
+ *   - `import React from 'react'`
+ *   - `import { useState } from 'react'`
+ *   - `import * as ReactNS from 'react'`
+ * - Errors are silently caught; unresolved imports will leave `state.importState` with nulls.
+ *
+ * @example
+ * ```js
+ * importStateResolver(path, state, t);
+ * console.log(state.importState.reactId); // Identifier for React import
+ * console.log(state.importState.useStateId); // Identifier for useState if imported
+ * ```
+ */
+function importStateResolver(path, state, t) {
+  try {
+    const importState = {
+      reactId: null,
+      useStateId: null,
+      isDefault: false,
+      isNamed: false,
+      isNamespace: false,
+      reactImportPath: null
+    };
+    path.node.body.forEach(node => {
+      if (!t.isImportDeclaration(node)) return;
+      if (node.source.value !== _constants.REACT_IMPORT_CORE_NAME) return;
+      importState.reactImportPath = node;
+      node.specifiers.forEach(spec => {
+        // import React from 'react'
+        if (t.isImportDefaultSpecifier(spec)) {
+          importState.reactId = spec.local;
+          importState.isDefault = true;
+        }
+
+        // import { useState } from 'react'
+        if (t.isImportSpecifier(spec)) {
+          if (spec.imported.name === _constants.REACT_IMPORT_USE_STATE_HOOKS_NAME) {
+            importState.useStateId = spec.local;
+            importState.isNamed = true;
+          }
+        }
+
+        // import * as ReactNS from 'react'
+        if (t.isImportNamespaceSpecifier(spec)) {
+          importState.reactId = spec.local;
+          importState.isNamespace = true;
+        }
+      });
+    });
+    state.importState = importState;
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::importStateResolver::]', e.message);
+  }
+}
+
+/**
+ * Resets the variable registry for the current file during AST traversal.
+ *
+ * This function clears any registered state variables in the `virtualRegistry`
+ * that are associated with the current file. It is useful for ensuring that
+ * state tracking does not leak across files when processing multiple files
+ * in the plugin.
+ *
+ * @param {Object} state - Plugin state, including the filename and plugin options.
+ * @param {Object<string, Object>} virtualRegistry - Registry of components and
+ *   their registered variables/context info.
+ *
+ * @returns {void}
+ * Updates the `virtualRegistry` in place, resetting all variable names and
+ * default values associated with the current file.
+ *
+ * @important
+ * - Skips files excluded by `isExcludeFile`.
+ * - Uses a hash of the filename to identify the relevant registry entries.
+ * - Errors are silently caught.
+ *
+ * @example
+ * ```js
+ * resetRegisteryProcess(state, virtualRegistry);
+ * // Clears all state variables for the current file in the virtualRegistry
+ * ```
+ */
+function resetRegisteryProcess(state, virtualRegistry) {
+  try {
+    const fileName = state.filename || _constants._CCTX_EMPTY;
+    if (!(0, _utilityHelpers.isExcludeFile)(fileName, this.opts)) return;
+    const hash = (0, _utilityHelpers.getFilePathHASH)(fileName);
+    (0, _utilityHelpers.resetVarsForFile)(virtualRegistry, hash);
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::resetRegisteryProcess::]', e.message);
+  }
+}
+
+/**
+ * Babel visitor handler for the `Program` node when entering a file.
+ *
+ * This function initializes plugin state for the file, resolves React imports,
+ * and resets the variable registry for the current file. It is typically used
+ * at the beginning of processing each file to ensure a clean state.
+ *
+ * @param {NodePath} path - The Babel AST path representing the Program node.
+ * @param {Object} state - Plugin state, including filename, import metadata, and configuration.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate or check AST nodes.
+ * @param {Object<string, Object>} virtualRegistry - Registry of components and their
+ *   registered variables/context info.
+ * @param {Object} config - The plugin configuration for the current file.
+ *
+ * @returns {void}
+ * - Updates `state.casperConfig` with the provided config.
+ * - Populates `state.importState` with resolved React imports.
+ * - Resets the variable registry for the current file in `virtualRegistry`.
+ *
+ * @important
+ * - Must be called at the entry of each Program node to ensure correct setup.
+ * - Errors are silently caught; consider logging during debugging.
+ *
+ * @example
+ * ```js
+ * programEnter(path, state, t, virtualRegistry, pluginConfig);
+ * // Initializes plugin state, resolves React imports, resets file-specific registry
+ * ```
+ */
+function programEnter(path, state, t, virtualRegistry, config) {
+  try {
+    state.casperConfig = config;
+    importStateResolver(path, state, t);
+    resetRegisteryProcess.call(this, state, virtualRegistry);
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::programEnter::]', e.message);
+  }
+}
+
+/**
+ * Injects required imports for React and global context if they are missing.
+ *
+ * This function ensures that the necessary modules are imported at the top of
+ * the file when the AST traversal detects that `useState` or global context usage
+ * is needed. It adds the imports only when required, avoiding duplicate or
+ * unnecessary imports.
+ *
+ * @param {NodePath} path - The Babel AST path where imports should be injected.
+ * @param {Object} state - Plugin state, containing flags `needUseStateImport` and `needsGblContext`.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate AST nodes.
+ *
+ * @returns {void}
+ * - Conditionally injects `React` import if `useState` is required.
+ * - Conditionally injects global context import if any global context is used.
+ * - Uses `buildRequireDeclaration` to insert the import statements at the top of the file.
+ *
+ * @important
+ * - Checks `state.needUseStateImport` and `state.needsGblContext` to determine necessity.
+ * - Errors are silently caught; no exception is thrown if import insertion fails.
+ *
+ * @example
+ * ```js
+ * bindMissingImport(path, state, t);
+ * // Injects React and global context imports if they are missing
+ * ```
+ */
+function bindMissingImport(path, state, t) {
+  try {
+    if (state?.needUseStateImport) (0, _astHelpers.buildRequireDeclaration)(path, t, _constants._CCTX_UNDUS_CORE_REACT, _constants._CCTX_REACT);
+    if (state?.needsGblContext) (0, _astHelpers.buildRequireDeclaration)(path, t, _constants._CCTX_UNDUS_CORE_GBL_CONTEXT, _utilityHelpers.CONTEXT_FILE_PATH);
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::bindMissingImport::]', e.message);
+  }
+}
+
+/**
+ * Babel visitor handler for the `Program` node when exiting a file.
+ *
+ * This function is called after the AST traversal of the entire file is complete.
+ * Its primary purpose is to inject any missing imports for React or global context
+ * that were flagged as required during traversal.
+ *
+ * @param {NodePath} path - The Babel AST path representing the Program node.
+ * @param {Object} state - Plugin state, including flags `needUseStateImport` and `needsGblContext`.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate AST nodes.
+ *
+ * @returns {void}
+ * Modifies the AST in place by calling `bindMissingImport` to insert necessary imports.
+ *
+ * @important
+ * - Should be paired with `programEnter` at the start of traversal.
+ * - Only injects imports if flagged during traversal (`state.needUseStateImport` or `state.needsGblContext`).
+ * - Errors are silently caught; AST modifications fail gracefully if errors occur.
+ *
+ * @example
+ * ```js
+ * programExit(path, state, t);
+ * // Ensures React and global context imports are added if needed
+ * ```
+ */
+function programExit(path, state, t) {
+  try {
+    bindMissingImport(path, state, t);
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::programExit::]', e.message);
+  }
+}