casper-context 0.1.0

package/src/visitors/AssignmentExpression.js

@@ -0,0 +1,100 @@
+/**
+ * @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.
+ */
+import { IDENTIFIER, _CCTX_EMPTY } from '../utils/constants';
+
+/**
+ * Utility & Validation Helpers
+ * @description
+ * - findContextByVar: Maps a `_$_` variable to its corresponding Context instance name.
+ * - isExcludeFile: Security/Performance gate to prevent processing ignored files.
+ */
+import { findContextByVar, isExcludeFile } from '../utils/utilityHelpers';
+
+/**
+ * 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.
+ */
+import { buildSpreadObject, replaceWithSetState, buildUseContextInstance, replaceWithContextSetState, getComponentName, getRootParentComponent } from '../utils/astHelpers';
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+import { log } from '../utils/utilityHelpers';
+
+/**
+ * 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.
+ */
+export default function assignmentExpressionVisitor(path, state, t, virtualRegistry) {
+    try {
+        const fileName = state.filename || _CCTX_EMPTY;
+        if (!isExcludeFile(fileName, this.opts)) return;
+        if (path.node.left.type === IDENTIFIER) {
+            if (path.node.left.name?.startsWith(state.casperConfig.prefix)) {
+                state.needsGblContext = true;
+                const ctxName = findContextByVar(path.node.left.name, virtualRegistry);
+                if (!ctxName) return;
+                let { currentFuncParent, componentName } = 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 = buildSpreadObject(path, t);
+                if (isSameCMP) {
+                    replaceWithSetState(path, t, ctxName, updateFunction);
+                } else {
+                    buildUseContextInstance(currentFuncParent, state, t, ctxName);
+                    replaceWithContextSetState(path, t, ctxName, updateFunction);
+                }
+
+            }
+        }
+    } catch (e) {
+        log('error', '[::assignmentExpressionVisitor::]', e.message);
+    }
+}

package/src/visitors/FunctionDeclaration.js

@@ -0,0 +1,114 @@
+/**
+ * @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.
+ */
+import { isExcludeFile, getFilePathHASH } from '../utils/utilityHelpers';
+
+/**
+ * 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.
+ */
+import { functionReturnVariableDelarationVisitor } from './VariableDeclaration';
+import { functionDeclarationReturnStatementVisitor } from './ReturnStatement';
+
+/**
+ * AST Construction Helpers
+ * @description
+ * - buildCtxUseStateDeclaration: Physically constructs and injects the `useState` 
+ * node into the Abstract Syntax Tree.
+ */
+import { buildCtxUseStateDeclaration } from '../utils/astHelpers';
+
+/**
+ * Core Constants
+ * @description
+ * - _CCTX_EMPTY: Provides a safe string fallback for file naming and path resolution.
+ */
+import { _CCTX_EMPTY } from '../utils/constants';
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+import { log } from '../utils/utilityHelpers';
+
+/**
+ * @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
+ * ```
+ */
+export function functionDeclarationExit(path, state, t, virtualRegistry) {
+    try {
+        const fileName = state.filename || _CCTX_EMPTY;
+        if (!isExcludeFile(fileName, this.opts)) return;
+        const name = path.node.id?.name;
+        if (!name) return;
+        const filePathHASH = getFilePathHASH(fileName);
+        const key = `${name}_${filePathHASH}`;
+        const entry = virtualRegistry[key];
+        if (!entry || !entry.varNames.length) return;
+        const localStateVars = [];
+        path.traverse({
+            VariableDeclarator(varPath) {
+                functionReturnVariableDelarationVisitor.call(this, varPath, state, t, localStateVars);
+            },
+            ReturnStatement(retPath) {
+                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())
+        );
+        buildCtxUseStateDeclaration(path, t, state, objProps, key);
+
+    } catch (e) {
+        log('error', '[::functionDeclarationExit::]', e.message);
+    }
+}

package/src/visitors/Identifier.js

@@ -0,0 +1,142 @@
+/**
+ * @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.
+ */
+import {
+    VARIABLE_DECLARATOR, // Target for initial variable definitions
+    _CCTX_ID,            // Key for the identifier in a declaration
+    ASSIGNMENT_EXPRESSION, // Target for variable updates
+    _CCTX_LEFT,          // The 'write' side of an assignment
+    UPDATE_EXPRESSION,   // Target for increments/decrements (e.g., ++, --)
+    _CCTX_ARGUMENT,      // The variable inside an update expression
+    _CCTX_KEY,           // Property key in object patterns
+    _CCTX_UNKNOW,        // Fallback for unresolved identifiers
+    _CCTX_EMPTY          // Default string initializer
+} from '../utils/constants';
+
+/**
+ * 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.
+ */
+import { isExcludeFile, findContextByVar } from '../utils/utilityHelpers';
+
+/**
+ * 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.
+ */
+import { replaceWithContextState, replaceWithState, buildUseContextInstance, getRootParentComponent } from '../utils/astHelpers';
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+import { log } from '../utils/utilityHelpers';
+
+/**
+ * @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
+ * ```
+ */
+export default function identifierVisitor (path, state, t, seen, virtualRegistry) {
+    try {
+        const fileName = state.filename || _CCTX_EMPTY;
+        if (!isExcludeFile(fileName, this.opts)) return;
+        if (path.node?.name?.startsWith(state.casperConfig.prefix)) {
+            if (
+                (path.parent.type === VARIABLE_DECLARATOR && path.parentKey === _CCTX_ID) ||
+                (path.parent.type === ASSIGNMENT_EXPRESSION && path.parentKey === _CCTX_LEFT) ||
+                (path.parent.type === UPDATE_EXPRESSION && path.parentKey === _CCTX_ARGUMENT)
+            ) return;
+            if (
+                path.parentPath.isObjectProperty() &&
+                path.parentKey === _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} = getRootParentComponent(path);
+                const ctxName = 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) {
+                    replaceWithState(path, t, ctxName);
+                } else {
+                    buildUseContextInstance(currentFuncParent, state, t, ctxName);
+                    replaceWithContextState(path, t, ctxName);
+                }
+            }
+        }
+    } catch (e) {
+        log('error', '[::identifierVisitor::]', e.message);
+    }
+}

package/src/visitors/Program.js

@@ -0,0 +1,280 @@
+/**
+ * @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.
+ */
+import {
+    _CCTX_REACT,                       // Internal alias for the React object
+    _CCTX_EMPTY,                       // Safe string fallback for paths/names
+    _CCTX_UNDUS_CORE_REACT,            // Normalized identifier for the React import
+    _CCTX_UNDUS_CORE_GBL_CONTEXT,      // Identifier for the auto-generated global context
+    REACT_IMPORT_CORE_NAME,            // Literal 'react' package name
+    REACT_IMPORT_USE_STATE_HOOKS_NAME  // Literal 'useState' hook name
+} from '../utils/constants';
+
+/**
+ * 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.
+ */
+import { CONTEXT_FILE_PATH, resetVarsForFile, isExcludeFile, getFilePathHASH } from '../utils/utilityHelpers';
+
+/**
+ * AST Injection Helpers
+ * @description
+ * - buildRequireDeclaration: Injects CommonJS `require` statements at the top of the file.
+ */
+import { buildRequireDeclaration } from '../utils/astHelpers';
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+import { log } from '../utils/utilityHelpers';
+
+/**
+ * @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 !== 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 === 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) {
+        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 || _CCTX_EMPTY;
+        if (!isExcludeFile(fileName, this.opts)) return;
+        const hash = getFilePathHASH(fileName);
+        resetVarsForFile(virtualRegistry, hash);
+    } catch (e) {
+        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
+ * ```
+ */
+export function programEnter(path, state, t, virtualRegistry, config) {
+    try {
+        state.casperConfig = config
+        importStateResolver(path, state, t);
+        resetRegisteryProcess.call(this, state, virtualRegistry);
+    } catch (e) {
+        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) buildRequireDeclaration(path, t, _CCTX_UNDUS_CORE_REACT, _CCTX_REACT);
+        if (state?.needsGblContext) buildRequireDeclaration(path, t, _CCTX_UNDUS_CORE_GBL_CONTEXT, CONTEXT_FILE_PATH);
+    } catch (e) {
+        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
+ * ```
+ */
+export function programExit(path, state, t) {
+    try {
+        bindMissingImport(path, state, t);
+    } catch (e) {
+        log('error', '[::programExit::]', e.message);
+    }
+}