From 5d333646e746427beb45434eed52a848cc5f951d Mon Sep 17 00:00:00 2001
From: "Peter.Morton" <peter.morton@verint.com>
Date: Sat, 7 Mar 2026 12:33:36 -0600
Subject: [PATCH] Update constitution: Document literal function body pattern
 (v1.20.0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated constitution.md to reflect the new loading pattern for global variables:

Version: 1.19.0 → 1.20.0 (MINOR)

Changes documented:

1. Section I.II: Updated googleDriveAdapterHelper.js pattern
   - Files contain LITERAL BODY of a function
   - Use bare 'return {...}' statement (NOT valid standalone JS)
   - server.js wraps code in IIFE: (function() { <code> })()
   - Clear separation: file = content, server = wrapper

2. Section I.V: Updated loadGlobalVariables() pattern
   - Shows wrapping logic with code examples
   - Explains IIFE creation and execution
   - Documents context creation and object capture

3. Added comprehensive examples:
   - Example file structure showing literal function body
   - Example server.js wrapping logic with vm.Script
   - Shows how return statement exports object

4. Version history updated:
   - Documented architecture changes
   - Explained rationale for pattern
   - Listed benefits of approach

Key pattern documented:
✅ .js files in globalVariables/ contain function bodies with return
✅ Files are NOT valid standalone JavaScript (intentional)
✅ server.js wraps them: '(function() { <code> })()'
✅ Wrapping creates IIFE that executes and returns object
✅ Pattern applies to ALL .js files in globalVariables/

Benefits explained:
- Clear separation of content vs execution wrapper
- Explicit return statement documents exports
- Wrapping logic centralized in server.js
- Consistent pattern across all global variable functions
- Files clearly show their purpose (function bodies)

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

diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index b4e10c1..b170cea 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,5 +1,44 @@
 <!--
 Sync Impact Report:
+Version: 1.19.0 → 1.20.0 (MINOR: Literal function body pattern for global variables)
+Modified Principles:
+  - Section I.II: Updated googleDriveAdapterHelper.js pattern to use literal function body with return statement
+  - Section I.V: Updated to document function body wrapping pattern in loadGlobalVariables()
+  - Overall: Established clear pattern where files contain function bodies, server handles wrapping
+Architecture Changes:
+  - googleDriveAdapterHelper.js: Changed from object literal to literal function body with return
+  - server.js: Wraps loaded .js code in IIFE: (function() { <code> })()
+  - Pattern applies to ALL .js files in globalVariables/ directory
+Code Changes:
+  - googleDriveAdapterHelper.js:
+    * Changed from `({...})` pattern to `return {...}` pattern
+    * File now contains LITERAL BODY of a function (NOT valid standalone JS)
+    * Updated header comment to explain literal function body pattern
+    * Has bare return statement (intentional - wrapped by server)
+  - server.js: loadGlobalVariables():
+    * Wraps code: `const wrappedCode = '(function() {\n' + code + '\n})()'`
+    * Creates IIFE that executes function body
+    * Captures returned object from function execution
+    * Pattern centralizes wrapping logic in server
+Modified Sections:
+  - Section I.II: Updated googleDriveAdapterHelper.js pattern documentation
+  - Section I.V: Updated to show literal function body loading pattern
+  - Throughout: Clarified that .js files contain function bodies, not complete modules
+Rationale:
+  - Clear separation: file content (function body) vs execution wrapper (server)
+  - Files represent what goes INSIDE a function
+  - Explicit return statement shows what's exported
+  - Wrapping logic centralized in one place (server.js)
+  - Consistent pattern for all global variable functions
+Benefits:
+  - Files clearly show their purpose (function bodies)
+  - Explicit return statement documents exports
+  - Easier to understand: file = body, server = wrapper
+  - Single place to modify wrapping behavior
+  - Consistent pattern across all .js files in globalVariables/
+Templates Status:
+  ✅ All templates - No changes needed (implementation pattern only)
+Previous Version:
 Version: 1.18.0 → 1.19.0 (MINOR: Code simplification and optimization)
 Modified Principles:
   - Section I.V: Updated to document unified loadGlobalVariables() function
@@ -289,9 +328,11 @@ config/
 └── default.json          # Infrastructure settings
 ```
 
-**googleDriveAdapterHelper.js Pattern**:
+**googleDriveAdapterHelper.js Pattern (Literal Function Body)**:
 - MUST be loaded using `vm.Script` (same isolation as proxy.js)
-- MUST evaluate to a single JavaScript object (not wrapped in IIFE)
+- MUST contain LITERAL FUNCTION BODY with `return` statement (NOT valid standalone JS)
+- server.js wraps it: `(function() { <file contents> })()`
+- Function body returns a single JavaScript object containing all exports
 - MUST have ZERO imports/exports (pure vm.Script execution)
 - Loaded by `loadGlobalVariables()` which scans for both JSON and JS files
 - Filename determines global key: `googleDriveAdapterHelper.js` → `globalVariableContext.googleDriveAdapterHelper`
@@ -442,9 +483,47 @@ script.runInContext(context);
     - Purpose: Extracted helper functions for code organization
     - Source: `src/globalVariables/googleDriveAdapterHelper.js` loaded via `vm.Script`
     - Loading: server.js loads via `loadGlobalVariables()` at startup
+    - **Literal Function Body Pattern**:
+      - File contains LITERAL BODY of a function (NOT valid standalone JavaScript)
+      - Uses bare `return {...}` statement to export object
+      - server.js wraps it: `const wrappedCode = '(function() {\n' + code + '\n})()'`
+      - Creates IIFE that executes function body and captures returned object
+      - Pattern separates content (file) from execution wrapper (server)
+      - Example file structure:
+        ```javascript
+        // File: src/globalVariables/googleDriveAdapterHelper.js
+        // This is a LITERAL FUNCTION BODY (not valid standalone JS)
+        
+        class DocumentCountExceededError extends Error {
+          constructor(message) {
+            super(message);
+            this.name = 'DocumentCountExceededError';
+          }
+        }
+        
+        function generateRequestId() {
+          return `req_${crypto.randomUUID()}`;
+        }
+        
+        // ... more functions ...
+        
+        return {
+          DocumentCountExceededError,
+          generateRequestId,
+          // ... all exports
+        };
+        ```
+      - server.js wrapping logic:
+        ```javascript
+        const wrappedCode = `(function() {\n${code}\n})()`;
+        const script = new vm.Script(wrappedCode, { filename: file });
+        const context = vm.createContext({...globalVMContext, ...globalVariableContext});
+        const returnedObject = script.runInContext(context);
+        globalVariableContext[varName] = returnedObject;
+        ```
     - Generic Loading Pattern:
       - All .js files in globalVariables/ are loaded automatically
-      - Filename determines key: `googleDriveAdapterHelper.js` → `globalVariableContext.helpers`
+      - Filename determines key: `googleDriveAdapterHelper.js` → `globalVariableContext.googleDriveAdapterHelper`
       - 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