From b55e503cbca485bb58c9da48979c2a96e3b3b9e1 Mon Sep 17 00:00:00 2001
From: "Peter.Morton" <peter.morton@verint.com>
Date: Sat, 7 Mar 2026 11:22:07 -0600
Subject: [PATCH] Update constitution to document loadGlobalVariableFunctions
 pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Version: 1.17.0 → 1.18.0 (MINOR: Function loading pattern documentation)

Changes:
- Document loadGlobalVariableFunctions() generic pattern
- Update VM context injection code example
- Update helpers.js loading documentation
- Document tempContext with full globalVMContext + globalVariableContext
- Fix duplicate req entry and renumber to 11 and 12

Key Documentation Updates:

1. Section I.II - helpers.js Pattern:
   - Loaded by loadGlobalVariableFunctions() which scans ALL .js files
   - Filename determines key: helpers.js → globalVariableContext.helpers
   - Executed in tempContext with full VM globals access

2. Section I.V - VM Context Injection Pattern:
   - Replaced specific helpers loading code with generic pattern
   - Documents loadGlobalVariableFunctions() scanning all .js files
   - Shows tempContext creation with {...globalVMContext, ...globalVariableContext}
   - Documents 4-step loading process with filename-to-key mapping

3. Section I.V - Helper Functions Module:
   - Added Generic Loading Pattern section
   - Documents full access to VM globals (axios, jwt, crypto, etc.)
   - Documents access to previously loaded JSON data and functions
   - Added note about extensibility (utils.js, validators.js, etc.)

Architecture Notes:
- Generic pattern: any .js file in globalVariables/ auto-loaded
- tempContext includes all dependencies from both contexts
- Function modules can access same globals as proxy.js
- Supports multiple function modules without code changes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .specify/memory/constitution.md | 73 +++++++++++++++++++++++++--------
 1 file changed, 57 insertions(+), 16 deletions(-)

diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index b4aa0fe..d139540 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,5 +1,33 @@
 <!--
 Sync Impact Report:
+Version: 1.17.0 → 1.18.0 (MINOR: Updated function loading pattern documentation)
+Modified Principles:
+  - Section I.V: Updated VM context injection pattern to reflect loadGlobalVariableFunctions
+  - Section I.V: Documented generic .js file loading from globalVariables/
+  - Section I.V: Updated tempContext to use full globalVMContext + globalVariableContext
+  - Section I.II: Updated helpers.js documentation to reflect generic pattern
+Architecture Changes:
+  - Renamed loadHelpers() → loadGlobalVariableFunctions()
+  - Generic pattern: loads ALL .js files from globalVariables/ (not just helpers.js)
+  - Filename determines key: helpers.js → globalVariableContext.helpers
+  - tempContext now includes full VM globals and previously loaded data
+  - Function modules can access all dependencies (axios, jwt, etc.)
+Code Changes:
+  - server.js: loadGlobalVariableFunctions() loads all .js files generically
+  - server.js: tempContext uses {...globalVMContext, ...globalVariableContext}
+  - Pattern matches loadGlobalObjects() structure for consistency
+Modified Sections:
+  - Section I.II: Updated file structure and helpers.js pattern documentation
+  - Section I.V: Complete rewrite of function module loading documentation
+  - Section I.V: Updated context injection pattern code example
+Rationale:
+  - Generic pattern supports multiple function modules without code changes
+  - Consistent with loadGlobalObjects() pattern (JSON files)
+  - Function modules can depend on full set of VM globals
+  - Enables complex function modules that need access to libraries
+Templates Status:
+  ✅ All templates - No changes needed (implementation detail)
+Previous Version:
 Version: 1.16.0 → 1.17.0 (MINOR: Helper functions extraction pattern)
 Modified Principles:
   - Section I: Updated to allow helper functions in src/globalVariables/helpers.js
@@ -219,9 +247,12 @@ config/
 - MUST be loaded using `vm.Script` (same isolation as proxy.js)
 - MUST return single object with all helper functions via IIFE
 - MUST have ZERO imports/exports (pure vm.Script execution)
+- Loaded by `loadGlobalVariableFunctions()` which scans for ALL .js files
+- Filename determines global key: `helpers.js` → `globalVariableContext.helpers`
 - Injected as `helpers` global object into VM context
 - Contains ONLY pure utilities: validators, formatters, XML, error mappers
 - MUST NOT contain: authentication, API calls, state, business decisions
+- Executed in tempContext with full access to globalVMContext and globalVariableContext
 
 #### I.III Enforcement
 
@@ -260,6 +291,7 @@ server.js uses a spread operator pattern for cleaner context creation:
 // Define static VM context (libraries and built-ins)
 const globalVMContext = {
   URLSearchParams,
+  URL,
   console: logger,
   crypto,
   axios,
@@ -268,22 +300,25 @@ const globalVMContext = {
   xmlBuilder,
 };
 
-// Load dynamic data from src/globalVariables/ directory into globalVariableContext
-let globalVariableContext = {};  // Populated by loadGlobalObjects()
+// Load dynamic data from src/globalVariables/ directory
+let globalVariableContext = {};  // Populated by loadGlobalObjects() and loadGlobalVariableFunctions()
 
-// Load helpers module via vm.Script
-const helpersScript = new vm.Script(fs.readFileSync('./src/globalVariables/helpers.js', 'utf8'));
-const helpersContext = vm.createContext({
-  crypto,
-  console: logger
-});
-const helpers = helpersScript.runInContext(helpersContext);
+// Load JSON data files at startup
+loadGlobalObjects();  // Loads *.json files
+
+// Load function modules (.js files) at startup
+loadGlobalVariableFunctions();  // Loads *.js files
+// Pattern for loading .js files:
+//   1. Scan globalVariables/ for all *.js files (excluding *.example.js)
+//   2. For each file, create tempContext with {...globalVMContext, ...globalVariableContext}
+//   3. Execute file via vm.Script in tempContext
+//   4. Store returned object in globalVariableContext using filename as key
+//   Example: helpers.js returns object → globalVariableContext.helpers = object
 
 // Per-request: Create fresh context with all dependencies
 const context = vm.createContext({
   ...globalVMContext,           // Spread static dependencies
-  ...globalVariableContext,     // Spread dynamic data (e.g., google_drive_settings)
-  helpers,                      // Helpers object with utility functions
+  ...globalVariableContext,     // Spread dynamic data (JSON + function modules)
   req,                          // Fresh request object
   res                           // Fresh response object
 });
@@ -362,8 +397,14 @@ script.runInContext(context);
     - Purpose: Extracted helper functions for code organization
     - Source: `src/globalVariables/helpers.js` loaded via `vm.Script`
     - Pattern: IIFE returning object with all helper functions
-    - Loading: server.js loads via `vm.Script` at startup (same as proxy.js)
-    - Injection: Direct object injection into VM context
+    - Loading: server.js loads via `loadGlobalVariableFunctions()` at startup
+    - Generic Loading Pattern:
+      - All .js files in globalVariables/ are loaded automatically
+      - Filename determines key: `helpers.js` → `globalVariableContext.helpers`
+      - Executed in tempContext with `{...globalVMContext, ...globalVariableContext}`
+      - Can access all VM globals: axios, jwt, crypto, console, etc.
+      - Can access previously loaded JSON data and function modules
+    - Injection: Spread into VM context via `...globalVariableContext`
     - Usage in src/proxyScripts/proxy.js: `helpers.functionName()` (e.g., `helpers.generateRequestId()`)
     - Contains: Pure utilities only (validators, formatters, XML, error mappers, route parsers)
     - MUST NOT contain: Authentication, API calls, state, business logic
@@ -375,16 +416,16 @@ script.runInContext(context);
       - `helpers.mapDriveErrorToHttp(error)` - Error mapping
       - `helpers.parseRoute(method, url)` - Route parsing
       - `helpers.DocumentCountExceededError` - Custom error class
+    - Generic Pattern Note: You can add more .js files (e.g., `utils.js`, `validators.js`)
+      and they will be automatically loaded as `globalVariableContext.utils`, etc.
 
 **Request/Response Objects:**
 
 11. **req** - HTTP IncomingMessage
-
-10. **req** - HTTP IncomingMessage
     - Purpose: Access request data (URL, method, headers, body)
     - Injected fresh: Per-request from `http.createServer((req, res) => ...)`
 
-11. **res** - HTTP ServerResponse  
+12. **res** - HTTP ServerResponse  
     - Purpose: Send response to client
     - Injected fresh: Per-request from `http.createServer((req, res) => ...)`