casper-context 0.1.0

package/dist/visitors/ReturnStatement.js

@@ -0,0 +1,81 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.functionDeclarationReturnStatementVisitor = functionDeclarationReturnStatementVisitor;
+var _constants = require("../utils/constants");
+var _astHelpers = require("../utils/astHelpers");
+var _utilityHelpers = require("../utils/utilityHelpers");
+/**
+ * @fileoverview Application Root & Provider Orchestration.
+ * This module manages the final wrapping phase of the AST transformation. 
+ * It ensures that the transformed component tree is encapsulated within 
+ * the custom Casper Context Provider, enabling global state distribution.
+ */
+
+/**
+ * Core Logic Constants
+ * @description
+ * - _CCTX_CMP_NAME_PREFIX: The prefix used to identify and generate unique 
+ * Context Provider instances (e.g., '_$_ctx_').
+ * - _CCTX_EMPTY: A safe fallback initializer for string-based AST properties.
+ */
+
+/**
+ * AST Transformation Helpers
+ * @description
+ * - buildCtxProvider: A structural helper that wraps a JSX element or 
+ * Function body with a `<Context.Provider>` component, mapping internal 
+ * state to the Provider's `value` prop.
+ */
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+
+/**
+ * @important
+ * The `buildCtxProvider` function is typically invoked during the `Program.exit` 
+ * or `ExportDefaultDeclaration` phase to ensure all nested transformations 
+ * are complete before the final Provider wrapping occurs.
+ */
+
+/**
+ * Visitor for `ReturnStatement` nodes inside a function declaration.
+ *
+ * This function inspects the return statement of a component function
+ * and wraps its returned JSX or value with the corresponding context provider.
+ * It ensures that the component correctly provides state and context to its children.
+ *
+ * @param {NodePath} path - The Babel AST path representing the `ReturnStatement` node.
+ * @param {Object} state - Plugin state, including import information and configuration.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to generate AST nodes.
+ * @param {Object} entry - Registry entry for the component, containing `ctxName` and variable names.
+ *
+ * @returns {void}
+ * Modifies the return statement node in place, replacing it with a `React.createElement`
+ * call that wraps the original return value with a context provider.
+ *
+ * @important
+ * - Only processes return statements that have a non-null argument.
+ * - Uses `buildCtxProvider` to generate the provider wrapper.
+ * - Errors are silently caught; no changes occur if an exception is thrown.
+ *
+ * @example
+ * ```js
+ * functionDeclarationReturnStatementVisitor(path, state, t, entry);
+ * // Wraps the return value of a component function with its context provider
+ * ```
+ */
+function functionDeclarationReturnStatementVisitor(path, state, t, entry) {
+  try {
+    const returnNode = path.node.argument;
+    if (!returnNode) return;
+    const stateName = entry.ctxName.replace(_constants._CCTX_CMP_NAME_PREFIX, _constants._CCTX_EMPTY);
+    (0, _astHelpers.buildCtxProvider)(path, t, returnNode, state, stateName);
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::functionDeclarationReturnStatementVisitor::]', e.message);
+  }
+}

package/dist/visitors/VariableDeclaration.js

@@ -0,0 +1,209 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = variableDeclarationVisitor;
+exports.functionReturnVariableDelarationVisitor = functionReturnVariableDelarationVisitor;
+var _constants = require("../utils/constants");
+var _utilityHelpers = require("../utils/utilityHelpers");
+var _astHelpers = require("../utils/astHelpers");
+/**
+ * @fileoverview Variable Registration & Classification Logic.
+ * This module is responsible for the initial discovery phase of the transformation.
+ * It identifies custom context variables during their declaration, classifies their 
+ * initial values, and registers them within the global tracking registry.
+ */
+
+/**
+ * AST Literal & Expression Constants
+ * @description These constants are used to evaluate the 'init' value of a variable.
+ * Your library uses these to distinguish between simple state and complex logic.
+ */
+
+/**
+ * Registration & Lifecycle Utilities
+ * @description
+ * - isExcludeFile: Prevents tracking variables in ignored files or directories.
+ * - registerVariable: The core method that saves variable metadata to the virtualRegistry.
+ * - getFilePathHASH: Ensures variables are scoped to a unique file ID to prevent collisions.
+ */
+
+/**
+ * Scope & Inheritance Helpers
+ * @description
+ * - getInheritantDecComponent: Traverses upward from a variable declaration to find 
+ * the parent component name, ensuring the variable is correctly scoped to its owner.
+ */
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+
+/**
+ * @important
+ * **Classification Note:** When a variable is registered, its "Literal Type" determines 
+ * how the subsequent `useState` hook is initialized. Non-literal initializers 
+ * may require different handling during the `functionDeclarationExit` phase.
+ */
+
+/**
+ * Extracts the initial value of a variable from a Babel AST `VariableDeclarator` node.
+ *
+ * This function inspects the `init` property of a variable declaration and
+ * attempts to determine its literal value. It handles primitive literals,
+ * arrays, and objects with literal values. Non-literal or complex expressions
+ * are flagged as `NON_LITERAL`.
+ *
+ * @param {NodePath} path - Babel AST path for a `VariableDeclarator` node.
+ *
+ * @returns {any} The initial value of the variable:
+ * - `number` for numeric literals
+ * - `string` for string literals
+ * - `boolean` for boolean literals
+ * - `Array` of literal values for array expressions
+ * - `Object` of literal key-value pairs for object expressions
+ * - `NON_LITERAL` for other expressions or complex initializers
+ * - `undefined` if the variable has no initializer
+ *
+ * @important
+ * - Only inspects direct literal values. Nested expressions inside arrays or objects
+ *   that are not literals will be ignored or marked as `null`.
+ * - Errors during traversal or invalid AST nodes will return the current `initValue`.
+ *
+ * @example
+ * ```js
+ * // For "const a = 5;" → returns 5
+ * // For "const b = [1, 2];" → returns [1, 2]
+ * // For "const c = { x: 1, y: 'a' };" → returns { x: 1, y: 'a' }
+ * ```
+ */
+function getVariableInitValue(path) {
+  let initValue = undefined;
+  try {
+    if (path.node.init) {
+      const valNode = path.node.init;
+      if (valNode.type === _constants.NUMERIC_LITERAL || valNode.type === _constants.STRING_LITERAL || valNode.type === _constants.BOOLEAN_LITERAL) {
+        initValue = valNode.value;
+      } else if (valNode.type === _constants.ARRAY_EXPRESSION) {
+        initValue = valNode.elements.map(e => e.value ?? null);
+      } else if (valNode.type === _constants.OBJECT_EXPRESSION) {
+        const obj = {};
+        for (const prop of valNode.properties) {
+          if (prop.key && prop.value && prop.value.value !== undefined) {
+            obj[prop.key.name || prop.key.value] = prop.value.value;
+          }
+        }
+        initValue = obj;
+      } else {
+        initValue = NON_LITERAL;
+      }
+    }
+    return initValue;
+  } catch (e) {
+    return initValue;
+  }
+}
+
+/**
+ * Visitor for `VariableDeclarator` nodes to register state variables in the virtual registry.
+ *
+ * This function checks if a variable's name matches the plugin's configured prefix.
+ * If so, it extracts the initial value, identifies the enclosing component, and
+ * registers the variable in the `virtualRegistry`. It also ensures React and global
+ * context imports are flagged if needed.
+ *
+ * @param {NodePath} path - Babel AST path for a `VariableDeclarator` node.
+ * @param {Object} state - Plugin state, including filename, import metadata, and configuration flags.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to inspect or create AST nodes.
+ * @param {Object<string, Object>} virtualRegistry - Registry of components and their registered variables.
+ *
+ * @returns {void}
+ * - Registers the variable in the `virtualRegistry` under the component hash.
+ * - Sets `state.needsGblContext` if the variable belongs to a global context.
+ * - Flags `state.needUseStateImport` if `useState` is not yet imported.
+ *
+ * @important
+ * - Only processes variables whose names start with the configured prefix.
+ * - Uses `getVariableInitValue` to determine the variable's initial value.
+ * - Errors are silently caught; no action is taken if an exception occurs.
+ *
+ * @example
+ * ```js
+ * variableDeclarationVisitor(path, state, t, virtualRegistry);
+ * // Registers a prefixed variable in the virtual registry with its initial value
+ * ```
+ */
+function variableDeclarationVisitor(path, state, t, virtualRegistry) {
+  try {
+    const fileName = state.filename || _constants._CCTX_EMPTY;
+    if (!(0, _utilityHelpers.isExcludeFile)(fileName, this.opts)) return;
+    if (path.node.id.name?.startsWith(state.casperConfig.prefix)) {
+      const inheritantCMP = (0, _astHelpers.getInheritantDecComponent)(path);
+      if (!inheritantCMP) return;
+      const filePathHash = (0, _utilityHelpers.getFilePathHASH)(fileName);
+      let _init_value = getVariableInitValue(path);
+      state.needsGblContext = true;
+      if (!state.importState.reactId && !state.importState.useStateId) {
+        state.needUseStateImport = true;
+      }
+      (0, _utilityHelpers.registerVariable)(`${inheritantCMP}_${filePathHash}`, path.node.id.name, _init_value, virtualRegistry);
+    }
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::variableDeclarationVisitor::]', e.message);
+  }
+}
+
+/**
+ * Visitor for `VariableDeclarator` nodes inside a function's body to collect state variables.
+ *
+ * This function inspects variable declarations within a component function and collects
+ * those whose names start with the plugin's configured prefix. Collected variables are
+ * added to `localStateVars` for later use in context or state initialization.
+ * The original declaration line is removed from the AST to prevent duplication.
+ *
+ * @param {NodePath} path - Babel AST path for a `VariableDeclarator` node.
+ * @param {Object} state - Plugin state, containing the configuration and flags.
+ * @param {Object} t - Babel types helper (`@babel/types`) used to inspect and manipulate AST nodes.
+ * @param {Array<Object>} localStateVars - Array to collect state variables with `{ name, init }`.
+ *
+ * @returns {void}
+ * - Pushes matched variables into `localStateVars`.
+ * - Removes the original variable declaration or the specific declarator from the AST.
+ *
+ * @important
+ * - Only processes identifiers whose names match the configured prefix.
+ * - Safely handles declarations with multiple declarators by removing only the matched one.
+ * - Errors are silently caught; no action occurs if an exception is thrown.
+ *
+ * @example
+ * ```js
+ * const localStateVars = [];
+ * functionReturnVariableDelarationVisitor(path, state, t, localStateVars);
+ * // localStateVars now contains the prefixed variables from the function
+ * ```
+ */
+function functionReturnVariableDelarationVisitor(path, state, t, localStateVars) {
+  try {
+    const id = path.node.id;
+    const init = path.node.init;
+    if (!t.isIdentifier(id)) return;
+    if (id.name.startsWith(state.casperConfig.prefix)) {
+      localStateVars.push({
+        name: id.name,
+        init
+      });
+      // remove declaration line
+      if (t.isVariableDeclaration(path.parent)) {
+        if (path.parent.declarations.length === 1) {
+          path.parentPath.remove();
+        } else {
+          path.remove();
+        }
+      }
+    }
+  } catch (e) {
+    (0, _utilityHelpers.log)('error', '[::functionReturnVariableDelarationVisitor::]', e.message);
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "casper-context",
+  "version": "0.1.0",
+  "description": "CasperContext - the friendly, invisible React Context API via Babel. Declare a variable, use it globally.",
+  "author": "Ruwan Chamara",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "babel-plugin",
+    "babel",
+    "react",
+    "react-context",
+    "global-state",
+    "casper-context",
+    "casper",
+    "react-casper-context",
+    "react-casper",
+    "compiler",
+    "ast",
+    "transform",
+    "state-management"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/casper-context.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourname/casper-context/issues"
+  },
+  "homepage": "https://github.com/yourname/casper-context#readme",
+  "scripts": {
+    "build": "babel src --out-dir dist --extensions .ts,.js",
+    "dev": "babel src --out-dir dist --extensions .ts,.js --watch",
+    "clean": "rm -rf dist",
+    "test": "node tests/run.js",
+    "lint": "eslint src --ext .ts,.js",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "@babel/core": "^7.0.0"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.25.0",
+    "@babel/core": "^7.25.0",
+    "@babel/parser": "^7.25.0",
+    "@babel/preset-env": "^7.25.0",
+    "@babel/preset-typescript": "^7.25.0",
+    "@babel/traverse": "^7.25.0",
+    "@babel/types": "^7.25.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+import plugin from './plugin';
+export default plugin;

package/src/lifecycle/post.js

@@ -0,0 +1,237 @@
+/**
+ * @fileoverview Environment Initialization and File Orchestration.
+ * This module is responsible for the physical creation and synchronization of 
+ * the Casper Context infrastructure, including the global context bridge and 
+ * ESLint configuration overrides.
+ */
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Path Utilities & Constants
+ * @description Leverages resolved system paths and core constants to ensure 
+ * write operations target the correct project directories.
+ */
+import { CONTEXT_FILE_PATH, ESLINT_GLOBAL_JS_PATH } from '../utils/utilityHelpers';
+
+import { _CCTX_CMP_NAME_PREFIX, _CCTX_EMPTY, _CCTX_UNDEFINED, UNICODE_UTF8, CASPER_READ_ONLY_TYPE, ESLINT_RC_FILE } from '../utils/constants';
+
+/**
+ * @module Logger
+ * @description Provides a controlled logging interface for the Babel transformation process.
+ */
+import { log } from '../utils/utilityHelpers';
+
+/**
+ * @important
+ * The following imports are critical for the library's lifecycle:
+ * - `CONTEXT_FILE_PATH`: The destination for the auto-generated React Context logic.
+ * - `ESLINT_GLOBAL_JS_PATH`: The file that prevents 'no-undef' errors for _$_ variables.
+ * - `UNICODE_UTF8`: Standard encoding used for all `fs.writeFileSync` operations.
+ */
+
+/**
+ * Generates a JavaScript module file that exports React context instances
+ * based on the registered variables in the `virtualRegistry`.
+ *
+ * This function creates or overwrites the file at `CONTEXT_FILE_PATH`, injecting
+ * `'use strict'` directives, ES module compatibility boilerplate, and context
+ * initialization code. Each registered component context is turned into a
+ * `React.createContext` with default values derived from the registry.
+ *
+ * @param {Object<string, Object>} virtualRegistry - The in-memory registry mapping
+ *   component hashes to their context metadata:
+ *   ```js
+ *   {
+ *     [componentHash]: {
+ *       ctxName: string,       // Generated context name
+ *       varNames: string[],    // List of variable names registered for this context
+ *       defaults: Record<string, any> // Default values for each variable
+ *     }
+ *   }
+ *   ```
+ *
+ * @returns {void}
+ * This function writes to the filesystem directly and does not return a value.
+ *
+ * @important
+ * - The generated module follows CommonJS export style with ES module compatibility.
+ * - All variables registered in `virtualRegistry` are included in their respective
+ *   `createContext` objects. Variables without a default value are set to `_CCTX_UNDEFINED`.
+ * - The function overwrites any existing file at `CONTEXT_FILE_PATH`.
+ * - React is imported as `_react` and used for `createContext` calls.
+ * - The `_CCTX_CMP_NAME_PREFIX` is stripped from exported context names for clarity.
+ * - Errors are silently caught; consider adding logging for debugging or dev builds.
+ * - The generated content is formatted with line breaks and indentation for readability.
+ *
+ * @example
+ * ```js
+ * const virtualRegistry = {
+ *   'abc123': {
+ *     ctxName: '_CCTX_abc123',
+ *     varNames: ['count', 'enabled'],
+ *     defaults: { count: 0, enabled: true }
+ *   }
+ * };
+ * generateContextContent(virtualRegistry);
+ * // Produces a file exporting a React context with default { count: 0, enabled: true }
+ * ```
+ */
+function generateContextContent(virtualRegistry) {
+    try {
+        fs.writeFileSync(CONTEXT_FILE_PATH, _CCTX_EMPTY, UNICODE_UTF8);
+        let contextNames = [];
+        let content = `'use strict';\n\nObject.defineProperty(exports, '__esModule', {\n  value: true\n});\n`;
+        if (Object.keys(virtualRegistry).length === 0) return
+        Object.values(virtualRegistry).forEach(entry => {
+            if (!entry.ctxName) return;
+            contextNames.push(entry.ctxName.replace(_CCTX_CMP_NAME_PREFIX, _CCTX_EMPTY));
+        });
+
+        content += `exports.${contextNames.join(' = exports.')} = void 0;\n`;
+        content += `var _react = require('react');\n`;
+
+        Object.values(virtualRegistry).forEach(entry => {
+            if (!entry.ctxName) return;
+            const { ctxName, varNames, defaults } = entry;
+            const defaultObjProps = varNames.map(name => {
+                const val = defaults[name] !== undefined ? JSON.stringify(defaults[name]) : _CCTX_UNDEFINED;
+                return `  ${name}: ${val}`;
+            }).join(',\n');
+            content += `const ${ctxName.replace(_CCTX_CMP_NAME_PREFIX, _CCTX_EMPTY)} = exports.${ctxName.replace(_CCTX_CMP_NAME_PREFIX, _CCTX_EMPTY)} = /*#__PURE__*/(0, _react.createContext)({\n${defaultObjProps}\n});\n`;
+        });
+        fs.writeFileSync(CONTEXT_FILE_PATH, content, UNICODE_UTF8);
+    } catch (e) {
+        log('error', '[::generateContextContent::]', e.message);
+    }
+}
+
+/**
+ * Generates or updates the ESLint global variables configuration file
+ * based on the current virtual registry.
+ *
+ * This function reads all variable names registered in `virtualRegistry`
+ * and writes them as read-only globals in a JavaScript module (`ESLINT_GLOBAL_JS_PATH`).
+ * It compares the newly generated content with the existing file and only
+ * overwrites if changes are detected. Finally, it updates the modification
+ * timestamp of the ESLint configuration file to trigger linting updates if needed.
+ *
+ * @param {Object<string, Object>} virtualRegistry - The in-memory registry of component
+ *   variables. Each entry should contain:
+ *   ```js
+ *   {
+ *     varNames: string[],   // List of variable names for the component/context
+ *     ctxName?: string,     // Optional context name
+ *     defaults?: Record<string, any> // Optional default values
+ *   }
+ *   ```
+ * @param {Object<string, Object>} [prevVirtualRegistrySnap] - Optional snapshot of
+ *   the previous virtual registry state. Currently unused, but can be used
+ *   to detect changes or optimize writes.
+ *
+ * @returns {void}
+ * Writes or updates the ESLint global JS file on disk and updates the
+ * corresponding ESLint configuration file's timestamps.
+ *
+ * @important
+ * - All variables are marked as read-only in the ESLint globals (`CASPER_READ_ONLY_TYPE`).
+ * - File writes are **atomic**: the target file is cleared before writing new content.
+ * - If no variables exist in the registry, the function exits early without writing.
+ * - Errors are silently caught; consider adding logging for development.
+ * - Changes are only applied if the content differs from the current file, avoiding
+ *   unnecessary filesystem writes.
+ * - The file starts with a comment indicating it is auto-generated by CasperContext.
+ *
+ * @example
+ * ```js
+ * const virtualRegistry = {
+ *   'abc123': {
+ *     varNames: ['count', 'enabled'],
+ *     ctxName: '_CCTX_abc123',
+ *     defaults: { count: 0, enabled: true }
+ *   }
+ * };
+ * generateLintGlobalJS(virtualRegistry);
+ * // Writes ESLint globals file:
+ * // module.exports = {
+ * //   "count": "readonly",
+ * //   "enabled": "readonly"
+ * // };
+ * ```
+ */
+function generateLintGlobalJS(virtualRegistry, prevVirtualRegistrySnap) {
+    try {
+        if (Object.keys(virtualRegistry).length === 0) return
+        const currentCnt = fs.readFileSync(ESLINT_GLOBAL_JS_PATH, UNICODE_UTF8);
+        const content = Object.values(virtualRegistry)
+            .flatMap(entry => entry.varNames || [])
+            .map(name => `  "${name}": "${CASPER_READ_ONLY_TYPE}"`)
+            .join(',\n');
+        const fileContent = `// ****** generated by CasperContext ******
+module.exports = {\n${content}\n};\n`;
+        if (currentCnt !== fileContent) {
+            fs.writeFileSync(ESLINT_GLOBAL_JS_PATH, _CCTX_EMPTY, UNICODE_UTF8);
+            fs.writeFileSync(ESLINT_GLOBAL_JS_PATH, fileContent, UNICODE_UTF8);
+            fs.utimesSync(path.join(process.cwd(), ESLINT_RC_FILE), new Date(), new Date());
+        }
+
+    } catch (e) {
+        log('error', '[::generateLintGlobalJS::]', e.message);
+    }
+}
+
+
+/**
+ * Performs post-processing steps after AST transformations on a file.
+ *
+ * This function generates or updates auxiliary files based on the current
+ * state of the virtual registry. Specifically:
+ * 1. `generateContextContent` – creates the module exporting React context
+ *    instances with default values.
+ * 2. `generateLintGlobalJS` – updates the ESLint global variables file
+ *    with read-only entries for all registered variables.
+ *
+ * @param {string} file - The path of the file that was processed. Currently unused,
+ *   but provided for future enhancements or logging purposes.
+ * @param {Object} t - Babel types helper (`@babel/types`) used in AST operations.
+ * @param {Object<string, Object>} virtualRegistry - The in-memory registry
+ *   of component/context variables, structured as:
+ *   ```js
+ *   {
+ *     [componentHash]: {
+ *       ctxName: string,
+ *       varNames: string[],
+ *       defaults: Record<string, any>
+ *     }
+ *   }
+ *   ```
+ * @param {Object<string, Object>} [prevVirtualRegistrySnap] - Optional snapshot
+ *   of the previous virtual registry state, used to detect changes and optimize writes.
+ *
+ * @returns {void}
+ * This function does not return a value; its effect is to update filesystem
+ * files (`CONTEXT_FILE_PATH` and `ESLINT_GLOBAL_JS_PATH`) based on the registry.
+ *
+ * @important
+ * - Errors are silently caught; consider adding logging for debugging.
+ * - Both `generateContextContent` and `generateLintGlobalJS` may overwrite
+ *   existing files.
+ * - The `file` parameter is not currently used internally but is included
+ *   for potential future processing logic.
+ *
+ * @example
+ * ```js
+ * import postProcess from './postProcess';
+ *
+ * postProcess('src/App.js', t, virtualRegistry, prevVirtualRegistrySnap);
+ * // Generates context and ESLint globals files based on the current registry
+ * ```
+ */
+export default function postProcess(file, t, virtualRegistry, prevVirtualRegistrySnap) {
+    try {
+        generateContextContent(virtualRegistry)
+        generateLintGlobalJS(virtualRegistry, prevVirtualRegistrySnap)
+    } catch (e) {
+        log('error', '[::postProcess::]', e.message)
+    }
+}