@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/utils/app/appNameResolver.test.ts

@@ -1,10 +1,20 @@
 /**
- * @file App Name Resolver Tests - Behavioral Verification
- * @description Comprehensive behavioral tests for app name resolution
+ * @file App Name Resolver Tests
  * @package @jmruthers/pace-core
+ * @module Utils/AppNameResolver
+ * @since 0.1.0
+ *
+ * Comprehensive tests for app name resolution utility functions covering:
+ * - Resolution from multiple sources (global, build-time, environment, package.json)
+ * - Priority order and fallback behavior
+ * - Helper functions and integration scenarios
+ * - Error handling and edge cases
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+// Following testing standards: use timeout parameter to prevent hanging
+const TEST_TIMEOUT = 10000; // 10 seconds per test
 import {
   getAppNameFromGlobal,
   getAppNameFromEnvironment,
@@ -22,13 +32,11 @@ import {
 describe('App Name Resolver - Behavioral Tests', () => {
   let originalGlobal: any;
   let originalBuildTime: any;
-  let originalEnv: Record<string, any>;
 
   beforeEach(() => {
     // Save original values
     originalGlobal = (globalThis as any).RBAC_APP_NAME;
     originalBuildTime = (globalThis as any).__RBAC_APP_NAME__;
-    originalEnv = { ...import.meta.env };
 
     // Clear all values
     delete (globalThis as any).RBAC_APP_NAME;
@@ -53,7 +61,7 @@ describe('App Name Resolver - Behavioral Tests', () => {
   describe('getAppNameFromGlobal', () => {
     it('returns null when global variable is not set', () => {
       expect(getAppNameFromGlobal()).toBeNull();
-    });
+    }, TEST_TIMEOUT);
 
     it('returns trimmed value when global variable is set', () => {
       (globalThis as any).RBAC_APP_NAME = '  test-app  ';
@@ -63,17 +71,17 @@ describe('App Name Resolver - Behavioral Tests', () => {
     it('returns null when global variable is empty string', () => {
       (globalThis as any).RBAC_APP_NAME = '';
       expect(getAppNameFromGlobal()).toBeNull();
-    });
+    }, TEST_TIMEOUT);
 
     it('returns null when global variable is only whitespace', () => {
       (globalThis as any).RBAC_APP_NAME = '   \n\t  ';
       expect(getAppNameFromGlobal()).toBeNull();
-    });
+    }, TEST_TIMEOUT);
 
     it('handles non-string values gracefully', () => {
       (globalThis as any).RBAC_APP_NAME = 123;
       expect(getAppNameFromGlobal()).toBeNull();
-    });
+    }, TEST_TIMEOUT);
   });
 
   describe('getAppNameFromBuildTime', () => {
@@ -327,13 +335,13 @@ describe('App Name Resolver - Behavioral Tests', () => {
     it('handles undefined global variable gracefully', () => {
       expect(() => getAppNameFromGlobal()).not.toThrow();
       expect(getAppNameFromGlobal()).toBeNull();
-    });
+    }, TEST_TIMEOUT);
 
     it('handles null global variable gracefully', () => {
       (globalThis as any).RBAC_APP_NAME = null;
       expect(() => getAppNameFromGlobal()).not.toThrow();
       expect(getAppNameFromGlobal()).toBeNull();
-    });
+    }, TEST_TIMEOUT);
 
     it('handles undefined environment variables gracefully', () => {
       // Note: import.meta.env is read-only, so we can't clear it

package/src/utils/app/appNameResolver.ts

@@ -22,7 +22,9 @@ export function getAppNameFromPackageJson(): string | null {
     try {
       // Try to read package.json from the current working directory
       // This works in most Node.js environments
+      // eslint-disable-next-line @typescript-eslint/no-var-requires -- Intentional: Dynamic require for Node.js environment detection
       const fs = require('fs');
+      // eslint-disable-next-line @typescript-eslint/no-var-requires -- Intentional: Dynamic require for Node.js environment detection
       const path = require('path');
       
       // Look for package.json in common locations
@@ -46,7 +48,7 @@ export function getAppNameFromPackageJson(): string | null {
               return name;
             }
           }
-        } catch (error) {
+        } catch (_error) {
           // Continue to next path
           continue;
         }
@@ -72,12 +74,12 @@ export function getAppNameFromBuildTime(): string | null {
   if (typeof window !== 'undefined') {
     // Try to access build-time injected variables
     try {
-      // @ts-ignore - These are injected at build time
-      const buildTimeEnv = (globalThis as any).__RBAC_APP_NAME__;
+      // These are injected at build time
+      const buildTimeEnv = (globalThis as { __RBAC_APP_NAME__?: string }).__RBAC_APP_NAME__;
       if (buildTimeEnv && buildTimeEnv.trim()) {
         return buildTimeEnv.trim();
       }
-    } catch (error) {
+    } catch (_error) {
       // Build-time injection not available
     }
   }
@@ -93,12 +95,12 @@ export function getAppNameFromGlobal(): string | null {
   if (typeof window !== 'undefined') {
     // Check for global app name set by consuming app
     try {
-      // @ts-ignore - This is set by the consuming app
-      const globalAppName = (globalThis as any).RBAC_APP_NAME;
+      // This is set by the consuming app
+      const globalAppName = (globalThis as { RBAC_APP_NAME?: string }).RBAC_APP_NAME;
       if (globalAppName && globalAppName.trim()) {
         return globalAppName.trim();
       }
-    } catch (error) {
+    } catch (_error) {
       // Global variable not set
     }
   }
@@ -181,8 +183,8 @@ export function getCurrentAppName(): string | null {
  */
 export function setRBACAppName(appName: string): void {
   if (typeof window !== 'undefined') {
-    // @ts-ignore - Setting global variable
-    (globalThis as any).RBAC_APP_NAME = appName.trim();
+    // Setting global variable
+    (globalThis as { RBAC_APP_NAME?: string }).RBAC_APP_NAME = appName.trim();
   }
 }
 

package/src/utils/app/appPortMap.test.ts

@@ -0,0 +1,125 @@
+/**
+ * @file appPortMap Utility Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/App
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getAppPort, getAllAppPorts, DEFAULT_APP_PORT_MAP } from './appPortMap';
+
+// Following testing standards: use timeout parameter to prevent hanging
+const TEST_TIMEOUT = 10000; // 10 seconds per test
+
+describe('appPortMap', () => {
+  describe('getAppPort', () => {
+    it('should return port for known app (uppercase)', () => {
+      expect(getAppPort('CORE')).toBe(8080);
+      expect(getAppPort('CAKE')).toBe(8083);
+      expect(getAppPort('TRAC')).toBe(8088);
+    }, TEST_TIMEOUT);
+
+    it('should return port for known app (lowercase)', () => {
+      expect(getAppPort('cake')).toBe(8083);
+      expect(getAppPort('trac')).toBe(8088);
+    }, TEST_TIMEOUT);
+
+    it('should return port for known app (mixed case)', () => {
+      expect(getAppPort('Cake')).toBe(8083);
+      expect(getAppPort('TrAc')).toBe(8088);
+    }, TEST_TIMEOUT);
+
+    it('should return undefined for unknown app', () => {
+      expect(getAppPort('UNKNOWN')).toBeUndefined();
+      expect(getAppPort('unknown-app')).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should handle empty string', () => {
+      expect(getAppPort('')).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should handle whitespace-only strings', () => {
+      expect(getAppPort('   ')).toBeUndefined();
+      expect(getAppPort('\t\n')).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should handle strings with leading/trailing whitespace (converted to uppercase)', () => {
+      // getAppPort converts to uppercase but doesn't trim, so whitespace becomes part of the key
+      expect(getAppPort('  CAKE  ')).toBeUndefined(); // '  CAKE  ' != 'CAKE'
+      expect(getAppPort('\tCORE\n')).toBeUndefined(); // '\tCORE\n' != 'CORE'
+    }, TEST_TIMEOUT);
+
+    it('should handle all registered apps', () => {
+      const allApps = Object.keys(DEFAULT_APP_PORT_MAP);
+      allApps.forEach(appName => {
+        expect(getAppPort(appName)).toBe(DEFAULT_APP_PORT_MAP[appName]);
+        expect(getAppPort(appName.toLowerCase())).toBe(DEFAULT_APP_PORT_MAP[appName]);
+      });
+    }, TEST_TIMEOUT);
+
+    it('should handle special characters in app name', () => {
+      expect(getAppPort('CAKE-APP')).toBeUndefined();
+      expect(getAppPort('CAKE_APP')).toBeUndefined();
+      expect(getAppPort('CAKE.APP')).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should handle very long app names', () => {
+      const longName = 'A'.repeat(1000);
+      expect(getAppPort(longName)).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should handle numeric strings', () => {
+      expect(getAppPort('123')).toBeUndefined();
+      expect(getAppPort('8080')).toBeUndefined();
+    }, TEST_TIMEOUT);
+  });
+
+  describe('getAllAppPorts', () => {
+    it('should return all app ports', () => {
+      const ports = getAllAppPorts();
+      
+      expect(ports).toEqual(DEFAULT_APP_PORT_MAP);
+      expect(ports.CORE).toBe(8080);
+      expect(ports.CAKE).toBe(8083);
+      expect(ports.TRAC).toBe(8088);
+    }, TEST_TIMEOUT);
+
+    it('should return a copy, not the original', () => {
+      const ports = getAllAppPorts();
+      ports.TEST = 9999;
+      
+      expect(DEFAULT_APP_PORT_MAP.TEST).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should return all expected apps', () => {
+      const ports = getAllAppPorts();
+      const expectedApps = ['CORE', 'ADMIN', 'BASE', 'CAKE', 'GEAR', 'MINT', 'PORTAL', 'PUMP', 'TRAC'];
+      
+      expectedApps.forEach(app => {
+        expect(ports[app]).toBeDefined();
+        expect(typeof ports[app]).toBe('number');
+        expect(ports[app]).toBeGreaterThan(0);
+      });
+    }, TEST_TIMEOUT);
+
+    it('should return immutable copy (modifications do not affect original)', () => {
+      const ports1 = getAllAppPorts();
+      const ports2 = getAllAppPorts();
+      
+      ports1.MODIFIED = 9999;
+      
+      expect(ports2.MODIFIED).toBeUndefined();
+      expect(DEFAULT_APP_PORT_MAP.MODIFIED).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('should return ports with correct types', () => {
+      const ports = getAllAppPorts();
+      
+      Object.values(ports).forEach(port => {
+        expect(typeof port).toBe('number');
+        expect(Number.isInteger(port)).toBe(true);
+        expect(port).toBeGreaterThan(0);
+        expect(port).toBeLessThan(65536); // Valid port range
+      });
+    }, TEST_TIMEOUT);
+  });
+});

package/src/utils/app/appPortMap.ts

@@ -0,0 +1,51 @@
+/**
+ * @file App Port Map Configuration
+ * @package @jmruthers/pace-core
+ * @module Utils/App
+ * @since 0.6.0
+ *
+ * Maps app names to development server ports.
+ * Used by buildAppUrl to construct localhost URLs in development.
+ */
+
+/**
+ * Default port mapping for pace apps in development.
+ * Maps app names (uppercase) to their development server ports.
+ */
+export const DEFAULT_APP_PORT_MAP: Record<string, number> = {
+  'CORE': 8080,
+  'ADMIN': 8081,
+  'BASE': 8082,
+  'CAKE': 8083,
+  'GEAR': 8084,
+  'MINT': 8085,
+  'PORTAL': 8086,
+  'PUMP': 8087,
+  'TRAC': 8088
+};
+
+/**
+ * Get the port for an app in development.
+ * 
+ * @param appName - The app name (case-insensitive)
+ * @returns The port number, or undefined if not found
+ * 
+ * @example
+ * ```ts
+ * const port = getAppPort('CAKE'); // Returns 8091
+ * const port = getAppPort('cake'); // Returns 8091 (case-insensitive)
+ * ```
+ */
+export function getAppPort(appName: string): number | undefined {
+  const upperAppName = appName.toUpperCase();
+  return DEFAULT_APP_PORT_MAP[upperAppName];
+}
+
+/**
+ * Get all registered app ports.
+ * 
+ * @returns Record of app names to ports
+ */
+export function getAllAppPorts(): Record<string, number> {
+  return { ...DEFAULT_APP_PORT_MAP };
+}

package/src/utils/app/buildAppUrl.test.ts

@@ -0,0 +1,273 @@
+/**
+ * @file buildAppUrl Utility Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/App
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { buildAppUrl } from './buildAppUrl';
+
+// Following testing standards: use timeout parameter to prevent hanging
+const TEST_TIMEOUT = 10000; // 10 seconds per test
+
+describe('buildAppUrl', () => {
+  const originalLocation = window.location;
+
+  beforeEach(() => {
+    // Mock window.location
+    delete (window as { location?: Location }).location;
+    (window as { location: Location }).location = {
+      ...originalLocation,
+      hostname: 'localhost',
+      port: '3000',
+      protocol: 'http:',
+    } as Location;
+  });
+
+  afterEach(() => {
+    window.location = originalLocation;
+    vi.restoreAllMocks();
+  });
+
+  describe('development environment', () => {
+    it('should build port-based URL for localhost', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE' });
+      
+      expect(url).toBe('http://localhost:8083/');
+    }, TEST_TIMEOUT);
+
+    it('should build port-based URL for 127.0.0.1', () => {
+      (window.location as Location).hostname = '127.0.0.1';
+      
+      const url = buildAppUrl({ appName: 'TRAC' });
+      
+      expect(url).toBe('http://localhost:8088/');
+    }, TEST_TIMEOUT);
+
+    it('should build port-based URL for IPv6 localhost', () => {
+      (window.location as Location).hostname = '[::1]';
+      
+      const url = buildAppUrl({ appName: 'CAKE' });
+      
+      expect(url).toBe('http://localhost:8083/');
+    }, TEST_TIMEOUT);
+
+    it('should use custom port when provided', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', port: 9000 });
+      
+      expect(url).toBe('http://localhost:9000/');
+    }, TEST_TIMEOUT);
+
+    it('should include custom path', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '/dashboard' });
+      
+      expect(url).toBe('http://localhost:8083/dashboard');
+    }, TEST_TIMEOUT);
+
+    it('should handle path with trailing slash', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '/dashboard/' });
+      
+      expect(url).toBe('http://localhost:8083/dashboard/');
+    }, TEST_TIMEOUT);
+
+    it('should handle path without leading slash (appended as-is)', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: 'dashboard' });
+      
+      // buildAppUrl doesn't add leading slash, so path is appended as-is
+      expect(url).toBe('http://localhost:8083dashboard');
+    }, TEST_TIMEOUT);
+
+    it('should handle empty path', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '' });
+      
+      expect(url).toBe('http://localhost:8083');
+    }, TEST_TIMEOUT);
+
+    it('should handle path with query parameters', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '/dashboard?tab=settings&id=123' });
+      
+      expect(url).toBe('http://localhost:8083/dashboard?tab=settings&id=123');
+    }, TEST_TIMEOUT);
+
+    it('should handle path with hash fragment', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '/dashboard#section' });
+      
+      expect(url).toBe('http://localhost:8083/dashboard#section');
+    }, TEST_TIMEOUT);
+
+    it('should handle path with special characters (URL encoding)', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '/dashboard/user%20profile' });
+      
+      expect(url).toBe('http://localhost:8083/dashboard/user%20profile');
+    }, TEST_TIMEOUT);
+
+    it('should fallback to current port if app not in map', () => {
+      (window.location as Location).hostname = 'localhost';
+      (window.location as Location).port = '3000';
+      
+      const url = buildAppUrl({ appName: 'UNKNOWN_APP' });
+      
+      expect(url).toBe('http://localhost:3000/');
+    }, TEST_TIMEOUT);
+
+    it('should fallback to default port 3000 if current port is empty', () => {
+      (window.location as Location).hostname = 'localhost';
+      (window.location as Location).port = '';
+      
+      const url = buildAppUrl({ appName: 'UNKNOWN_APP' });
+      
+      expect(url).toBe('http://localhost:3000/');
+    }, TEST_TIMEOUT);
+
+    it('should handle all registered apps in development', () => {
+      (window.location as Location).hostname = 'localhost';
+      const apps = ['CORE', 'ADMIN', 'BASE', 'CAKE', 'GEAR', 'MINT', 'PORTAL', 'PUMP', 'TRAC'];
+      
+      apps.forEach(app => {
+        const url = buildAppUrl({ appName: app });
+        expect(url).toMatch(/^http:\/\/localhost:\d+\/$/);
+      });
+    }, TEST_TIMEOUT);
+  });
+
+  describe('production environment', () => {
+    beforeEach(() => {
+      (window.location as Location).hostname = 'cake.example.com';
+      (window.location as Location).protocol = 'https:';
+    });
+
+    it('should build subdomain URL from current domain', () => {
+      const url = buildAppUrl({ appName: 'TRAC' });
+      
+      expect(url).toBe('https://trac.example.com/');
+    }, TEST_TIMEOUT);
+
+    it('should preserve protocol from current URL', () => {
+      (window.location as Location).protocol = 'http:';
+      
+      const url = buildAppUrl({ appName: 'CAKE' });
+      
+      expect(url).toBe('http://cake.example.com/');
+    }, TEST_TIMEOUT);
+
+    it('should include custom path in production', () => {
+      const url = buildAppUrl({ appName: 'TRAC', path: '/dashboard' });
+      
+      expect(url).toBe('https://trac.example.com/dashboard');
+    }, TEST_TIMEOUT);
+
+    it('should handle domain without subdomain', () => {
+      (window.location as Location).hostname = 'example.com';
+      
+      const url = buildAppUrl({ appName: 'CAKE' });
+      
+      expect(url).toBe('https://cake.example.com/');
+    }, TEST_TIMEOUT);
+
+    it('should handle multi-level subdomains correctly', () => {
+      (window.location as Location).hostname = 'admin.cake.example.com';
+      
+      const url = buildAppUrl({ appName: 'TRAC' });
+      
+      expect(url).toBe('https://trac.cake.example.com/');
+    }, TEST_TIMEOUT);
+
+    it('should handle path with query parameters in production', () => {
+      const url = buildAppUrl({ appName: 'TRAC', path: '/dashboard?tab=settings' });
+      
+      expect(url).toBe('https://trac.example.com/dashboard?tab=settings');
+    }, TEST_TIMEOUT);
+
+    it('should handle path with hash fragment in production', () => {
+      const url = buildAppUrl({ appName: 'TRAC', path: '/dashboard#section' });
+      
+      expect(url).toBe('https://trac.example.com/dashboard#section');
+    }, TEST_TIMEOUT);
+
+    it('should convert app name to lowercase in subdomain', () => {
+      const url = buildAppUrl({ appName: 'CAKE' });
+      
+      expect(url).toBe('https://cake.example.com/');
+    }, TEST_TIMEOUT);
+
+    it('should handle app names with mixed case', () => {
+      const url = buildAppUrl({ appName: 'TrAc' });
+      
+      expect(url).toBe('https://trac.example.com/');
+    }, TEST_TIMEOUT);
+
+    it('should handle complex domain structures', () => {
+      (window.location as Location).hostname = 'app.staging.example.co.uk';
+      
+      const url = buildAppUrl({ appName: 'CAKE' });
+      
+      expect(url).toBe('https://cake.staging.example.co.uk/');
+    }, TEST_TIMEOUT);
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle empty app name', () => {
+      (window.location as Location).hostname = 'localhost';
+      (window.location as Location).port = '3000';
+      
+      const url = buildAppUrl({ appName: '' });
+      
+      expect(url).toBe('http://localhost:3000/');
+    }, TEST_TIMEOUT);
+
+    it('should handle app name with whitespace (falls back to current port)', () => {
+      (window.location as Location).hostname = 'localhost';
+      (window.location as Location).port = '3000';
+      
+      // App name with whitespace won't match port map, so falls back to current port
+      const url = buildAppUrl({ appName: '  CAKE  ' });
+      
+      expect(url).toBe('http://localhost:3000/');
+    }, TEST_TIMEOUT);
+
+    it('should handle very long paths', () => {
+      (window.location as Location).hostname = 'localhost';
+      const longPath = '/' + 'a'.repeat(1000);
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: longPath });
+      
+      expect(url).toBe(`http://localhost:8083${longPath}`);
+    }, TEST_TIMEOUT);
+
+    it('should handle root path explicitly', () => {
+      (window.location as Location).hostname = 'localhost';
+      
+      const url = buildAppUrl({ appName: 'CAKE', path: '/' });
+      
+      expect(url).toBe('http://localhost:8083/');
+    }, TEST_TIMEOUT);
+
+    it('should handle custom port override in production (ignored)', () => {
+      (window.location as Location).hostname = 'cake.example.com';
+      (window.location as Location).protocol = 'https:';
+      
+      const url = buildAppUrl({ appName: 'TRAC', port: 9000 });
+      
+      // Port should be ignored in production
+      expect(url).toBe('https://trac.example.com/');
+    }, TEST_TIMEOUT);
+  });
+});