casper-context 0.1.0

package/src/lifecycle/pre.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview File System Orchestration for Casper Context.
+ * This module manages the lifecycle of the generated context files, handling
+ * the reading, writing, and directory verification required to sync the 
+ * Babel transformation with the physical project structure.
+ */
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Path & State Dependencies
+ * @description 
+ * - CONTEXT_FILE_PATH: The absolute resolved destination for the generated React Context.
+ * - _CCTX_EMPTY: Used as a safe fallback or initializer for file content buffers.
+ */
+import { CONTEXT_FILE_PATH } from '../utils/utilityHelpers';
+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
+ * All file operations in this module should prioritize synchronous methods (`fs.writeFileSync`, etc.)
+ * during the Babel build-step to ensure the file system is in sync before the 
+ * bundling process (Webpack/Vite) begins.
+ */
+
+/**
+ * Initializes the scope context file and directory for Casper context tracking.
+ *
+ * This function ensures that the directory containing the context file exists,
+ * and then creates an empty context file at `CONTEXT_FILE_PATH` if it does not
+ * already exist. It is intended to prepare the filesystem for storing generated
+ * React context instances and related metadata.
+ *
+ * @returns {void}
+ * This function does not return a value; its effect is purely filesystem-based.
+ *
+ * @important
+ * - Uses `fs.mkdirSync` with `{ recursive: true }` to create parent directories as needed.
+ * - Writes an empty file at `CONTEXT_FILE_PATH` with the `{ flag: 'wx' }` option,
+ *   which means the file is only created if it does not already exist.
+ * - Errors are silently caught, so existing files or directories will not cause failures.
+ * - Intended to be called before processing files (`preProcess`) or generating context content.
+ *
+ * @example
+ * ```js
+ * createScopeContext();
+ * // Ensures the context directory and empty context file exist
+ * ```
+ */
+function createScopeContext() {
+    try {
+        const dirPath = path.dirname(CONTEXT_FILE_PATH);
+        fs.mkdirSync(dirPath, { recursive: true });
+        fs.writeFileSync(CONTEXT_FILE_PATH, _CCTX_EMPTY, { flag: 'wx' });
+    } catch (e) {
+        log('error', '[::createScopeContext::]', e.message);
+    }
+}
+
+/**
+ * Performs pre-processing steps before AST transformations on a file.
+ *
+ * This function sets up the necessary runtime or plugin context before
+ * any file transformations occur. Currently, it calls `createScopeContext()`
+ * to initialize the global scope or virtual registry for tracking component
+ * variables and contexts.
+ *
+ * @param {string} file - The path of the file that will be processed. Currently unused,
+ *   but provided for future enhancements or logging purposes.
+ * @param {Object} t - Babel types helper (`@babel/types`) used for AST operations.
+ *
+ * @returns {void}
+ * This function does not return a value; its effect is to initialize internal
+ * context structures for later processing.
+ *
+ * @important
+ * - Errors are silently caught; consider adding logging for debugging.
+ * - Currently, the function only calls `createScopeContext()`, but can be
+ *   extended for additional pre-processing tasks.
+ * - The `file` parameter is not used internally but may be relevant in
+ *   future versions for file-specific setup.
+ *
+ * @example
+ * ```js
+ * import preProcess from './preProcess';
+ *
+ * preProcess('src/App.js', t);
+ * // Initializes context for virtual registry and component tracking
+ * ```
+ */
+export default function preProcess(file, t) {
+    try {
+        createScopeContext()
+    } catch (e) {
+        log('error', '[::preProcess::]', e.message);
+    }
+}

package/src/plugin.js

@@ -0,0 +1,51 @@
+import { PLUGIN_NAME } from './utils/constants';
+import preProcess from './lifecycle/pre';
+import postProcess from './lifecycle/post';
+import variableDeclarationVisitor from './visitors/VariableDeclaration';
+import assignmentExpressionVisitor from './visitors/AssignmentExpression';
+import identifierVisitor from './visitors/Identifier';
+import { programExit, programEnter } from './visitors/Program';
+import { functionDeclarationExit } from './visitors/FunctionDeclaration';
+import { readCasperConfig } from './utils/utilityHelpers';
+
+const virtualRegistry = {};
+const prevVirtualRegistrySnap = {}
+
+export default function ({ types: t }) {
+    const config = readCasperConfig();
+    const seen = new WeakSet();
+    return {
+        name: PLUGIN_NAME,
+        pre(file) {
+            preProcess.call(this, file, t);
+        },
+        visitor: {
+            Program: {
+                enter(path, state) {
+                    programEnter.call(this, path, state, t, virtualRegistry, config);
+                },
+                exit(path, state) {
+                    programExit.call(this, path, state, t);
+                }
+            },
+            VariableDeclarator (path, state) {
+                variableDeclarationVisitor.call(this, path, state, t, virtualRegistry);
+            },
+            AssignmentExpression (path, state) {
+                assignmentExpressionVisitor.call(this, path, state, t, virtualRegistry);
+            },
+            Identifier (path, state) {
+                identifierVisitor.call(this, path, state, t, seen, virtualRegistry);
+            },
+            FunctionDeclaration: {
+                exit (path, state) {
+        
+                    functionDeclarationExit.call(this, path, state, t, virtualRegistry);
+                }
+            }
+        },
+        post(file) {
+            postProcess.call(this, file, t, virtualRegistry, prevVirtualRegistrySnap);
+        }
+    }
+}