@crimsonsunset/jsg-logger 1.6.0 → 1.7.2

package/CHANGELOG.md

@@ -5,16 +5,185 @@ All notable changes to the JSG Logger project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.7.0] - 2025-01-XX 🎯 **Config-Driven Tree-Shaking & Enhanced Logging**
+
+### Added
+- **Config-Driven Tree-Shaking** - DevTools panel tree-shaking now based on default config at module load time
+  - Tree-shaking determined by `defaultConfig.devtools.enabled` (default: `false`)
+  - When disabled, devtools code completely tree-shaken (zero bundle impact)
+  - When enabled via runtime config, loads dynamically on demand
+  - Static import analysis allows bundlers to eliminate unused code paths
+- **Comprehensive DevTools Logging** - Added detailed logging throughout DevTools lifecycle
+  - Module load: logs default config tree-shaking status
+  - Config loading: logs when devtools enabled/disabled via user config
+  - DevTools activation: logs pre-load status, dynamic loading, and initialization steps
+  - Config merge: logs devtools status changes between defaults and user config
+
+### Changed
+- **DevTools Import Strategy** - Simplified to relative path imports
+  - Removed complex Function constructor + package export path logic
+  - Uses simple relative path: `./devtools/dist/panel-entry.js`
+  - Works in production builds, requires `server.fs.allow: ['..']` for npm link dev
+- **Config Loading Logging** - Enhanced visibility into config loading process
+  - Logs config source (file path vs inline object)
+  - Logs devtools status before/after config merge
+  - Logs initialization start with config source information
+
+### Fixed
+- **Tree-Shaking Detection** - Bundlers can now properly analyze and eliminate devtools code when disabled
+- **DevTools Pre-loading** - Non-blocking pre-load when default config enables devtools
+- **Runtime Config Override** - Dynamic loading works correctly when runtime config enables devtools but default disabled
+
+### Technical Details
+- **File**: `index.js`
+  - Added conditional static import based on `defaultConfig.devtools.enabled`
+  - Lazy initialization pattern to avoid top-level await
+  - Enhanced `enableDevPanel()` with comprehensive logging
+  - Pre-loads devtools module when default config enables it
+  
+- **File**: `config/config-manager.js`
+  - Added logging for config loading (file vs inline)
+  - Added devtools status logging before/after config merge
+  - Enhanced visibility into config changes
+
+### Migration Notes
+No breaking changes. Existing code continues to work.
+
+**For consumers:**
+- DevTools code tree-shaken by default (zero bundle impact)
+- Enable via runtime config: `{ devtools: { enabled: true } }`
+- DevTools loads dynamically when `enableDevPanel()` called
+- No special Vite config needed for production builds
+- npm link users: add `server.fs.allow: ['..']` to Vite config for dev
+
+## [1.7.1] - 2025-11-05 🎯 **TypeScript Support & Zero-Optional-Chaining API**
+
+### Added
+- **TypeScript Definitions** - Full TypeScript support with `index.d.ts`
+  - Complete type definitions for all logger interfaces
+  - `LoggerInstance`, `LoggerComponents`, `LoggerInstanceType` interfaces
+  - Proper exports configuration in `package.json` with `types` field
+- **Safe Component Getters** - Component getters initialized in constructor
+  - `_initializeSafeComponentGetters()` ensures components accessible before initialization
+  - Common components (reactComponents, astroComponents, etc.) always available
+  - Returns no-op logger factories if logger not initialized yet
+
+### Changed
+- **getComponent Always Available** - `getComponent` is now non-optional in TypeScript types
+  - Removed `?` optional marker from `getComponent` in `LoggerInstanceType`
+  - Always returns a logger instance (no-op if not initialized)
+  - Consumers can call `loggerInstance.getComponent('componentName')` without optional chaining
+- **Fallback Logger Enhancement** - `createFallbackLogger()` now includes `getComponent`
+  - Ensures `getComponent` exists even when initialization fails
+  - Returns no-op logger factory for safe fallback behavior
+- **Enhanced getComponent Safety** - Improved error handling and edge cases
+  - Returns no-op logger if instance not initialized
+  - Returns no-op logger if logger creation fails
+  - Prevents crashes when logger unavailable
+
+### Fixed
+- **Optional Chaining Burden** - Eliminated need for `?.` optional chaining in consumer code
+  - Consumers can now use `loggerInstance.getComponent('componentName').debug(...)` directly
+  - No more `loggerInstance?.getComponent?.('componentName')?.debug(...)` chains
+  - TypeScript types guarantee `getComponent` always exists
+
+### Technical Details
+- **File**: `index.d.ts` (NEW)
+  - Complete TypeScript definitions for the logger package
+  - Non-optional `getComponent` method signature
+  - Proper interface documentation
+  
+- **File**: `index.js`
+  - Added `_initializeSafeComponentGetters()` method called in constructor
+  - Enhanced `getComponent()` to always return logger (no-op fallback)
+  - Added `_createNoOpLogger()` private method for safe fallbacks
+  - Updated `createFallbackLogger()` to include `getComponent`
+  - Modified `_createAutoDiscoveryGetters()` to preserve safe getters
+
+- **File**: `package.json`
+  - Added `"types": "./index.d.ts"` field
+  - Added `index.d.ts` to `files` array
+  - Updated `exports` to include proper TypeScript types export
+
+### Migration Notes
+No breaking changes. Existing code continues to work, but optional chaining is now optional (pun intended).
+
+**For consumers:**
+- Can now use `loggerInstance.getComponent('componentName')` without `?.`
+- TypeScript users get full type safety and autocomplete
+- No-op logger returned if logger not initialized (safe to call)
+- Recommended: Use `getInstanceSync()` for synchronous access instead of `getInstance()` when possible
+
+## [1.7.0] - 2025-01-XX 🎯 **Config-Driven Tree-Shaking & Enhanced Logging**
 
 ### Added
-- None
+- **Config-Driven Tree-Shaking** - DevTools panel tree-shaking now based on default config at module load time
+  - Tree-shaking determined by `defaultConfig.devtools.enabled` (default: `false`)
+  - When disabled, devtools code completely tree-shaken (zero bundle impact)
+  - When enabled via runtime config, loads dynamically on demand
+  - Static import analysis allows bundlers to eliminate unused code paths
+- **Comprehensive DevTools Logging** - Added detailed logging throughout DevTools lifecycle
+  - Module load: logs default config tree-shaking status
+  - Config loading: logs when devtools enabled/disabled via user config
+  - DevTools activation: logs pre-load status, dynamic loading, and initialization steps
+  - Config merge: logs devtools status changes between defaults and user config
 
-### Changed  
-- None
+### Changed
+- **DevTools Import Strategy** - Simplified to relative path imports
+  - Removed complex Function constructor + package export path logic
+  - Uses simple relative path: `./devtools/dist/panel-entry.js`
+  - Works in production builds, requires `server.fs.allow: ['..']` for npm link dev
+- **Config Loading Logging** - Enhanced visibility into config loading process
+  - Logs config source (file path vs inline object)
+  - Logs devtools status before/after config merge
+  - Logs initialization start with config source information
 
 ### Fixed
-- None
+- **Tree-Shaking Detection** - Bundlers can now properly analyze and eliminate devtools code when disabled
+- **DevTools Pre-loading** - Non-blocking pre-load when default config enables devtools
+- **Runtime Config Override** - Dynamic loading works correctly when runtime config enables devtools but default disabled
+
+### Technical Details
+- **File**: `index.js`
+  - Added conditional static import based on `defaultConfig.devtools.enabled`
+  - Lazy initialization pattern to avoid top-level await
+  - Enhanced `enableDevPanel()` with comprehensive logging
+  - Pre-loads devtools module when default config enables it
+  
+- **File**: `config/config-manager.js`
+  - Added logging for config loading (file vs inline)
+  - Added devtools status logging before/after config merge
+  - Enhanced visibility into config changes
+
+### Migration Notes
+No breaking changes. Existing code continues to work.
+
+**For consumers:**
+- DevTools code tree-shaken by default (zero bundle impact)
+- Enable via runtime config: `{ devtools: { enabled: true } }`
+- DevTools loads dynamically when `enableDevPanel()` called
+- No special Vite config needed for production builds
+- npm link users: add `server.fs.allow: ['..']` to Vite config for dev
+
+## [Unreleased]
+
+## [1.5.2] - 2025-10-25 🐛 **PATCH: CLI Formatter Custom Component Display**
+
+### Technical Changes
+- `formatters/cli-formatter.js` - Use `configManager.getComponentConfig()` instead of static `COMPONENT_SCHEME`
+- `formatters/browser-formatter.js` - Remove redundant name transformation
+- `tests/custom-components.test.js` - Added Test 6 for formatter output validation
+
+## [1.5.1] - 2025-10-25 🔧 **PATCH: Component Initialization Optimization**
+
+### Fixed
+- **Component initialization pollution** - `getAvailableComponents()` no longer initializes all 13 default COMPONENT_SCHEME components when user defines custom components (3 defined → 3 initialized instead of 16)
+- **Component name formatting** - Changed from PascalCase (`MyComponent`) to uppercase with separators (`MY-COMPONENT`)
+
+### Technical Changes
+- `config/config-manager.js` - Return only user components when defined, fallback to COMPONENT_SCHEME if empty; components replaced instead of merged; enhanced `_formatComponentName()`
+- `index.js` - Clean reinitialization: reset config, clear loggers, normalize inline config
+- `tests/custom-components.test.js` - New comprehensive test suite (5 tests)
 
 ## [1.5.0] - 2025-10-25 🎯 **CRITICAL FIX: CLI Tool Support**
 

package/README.md

@@ -4,16 +4,19 @@
 
 A sophisticated, fully generic logging system that automatically detects its environment (browser, CLI, server) and provides optimal logging experience for any JavaScript project, with powerful file-level overrides and granular control.
 
+> 🎮 **[Try the Interactive DevTools Playground →](https://logger.joesangiorgio.com/)**  
+> Test all features in your browser with live examples and real-time controls!
+
 ## ✨ Features
 
-- 🎯 **100% Generic** - *New in v1.2.0!* Zero hardcoded assumptions, works with any project type
+- 🎯 **100% Generic** - Zero hardcoded assumptions, works with any project type
 - 🚀 **Zero-Boilerplate Integration** - Eliminates 200+ lines of project setup code
 - 🔧 **Auto-Discovery Components** - Both camelCase and kebab-case component access  
 - ⚡ **Built-in Performance Logging** - Static utilities with auto-getInstance
 - 🛡️ **Non-Destructive Error Handling** - Missing components log but don't break apps
-- 🎨 **Custom Component Names** - *New in v1.5.0!* Use ANY component name, auto-generated styling
-- 🔧 **Force Environment Override** - *New in v1.5.0!* Override auto-detection for CLI tools
-- 🧠 **Enhanced Environment Detection** - *New in v1.5.0!* Robust CLI detection with fallbacks
+- 🎨 **Custom Component Names** - Use ANY component name, auto-generated styling
+- 🔧 **Force Environment Override** - Override auto-detection for CLI tools
+- 🧠 **Enhanced Environment Detection** - Robust CLI detection with fallbacks
 - 🎨 **Beautiful Visual Output** - Emoji, colors, and structured context display
 - 📱 **Multi-Environment** - Browser console, terminal, and production JSON
 - 🏪 **Log Store** - In-memory storage for debugging and popup interfaces
@@ -27,14 +30,12 @@ A sophisticated, fully generic logging system that automatically detects its env
 
 ## 🚀 Quick Start
 
-### **v1.5.0: Custom Components & Force Environment - Perfect for CLI Tools!**
-
-> **✨ New in v1.5.0:** Use ANY component name (not just pre-defined ones) and force CLI mode for terminal applications!
+### **Custom Components & Force Environment for CLI Tools**
 
 ```javascript
 import JSGLogger from '@crimsonsunset/jsg-logger';
 
-// ✨ NEW: Force environment for CLI tools (fixes terminal detection)
+// Force environment for CLI tools (fixes terminal detection)
 const logger = JSGLogger.getInstanceSync({
   forceEnvironment: 'cli',  // Forces pretty terminal output
   globalLevel: 'info',
@@ -46,7 +47,7 @@ const logger = JSGLogger.getInstanceSync({
   }
 });
 
-// ✨ NEW: Custom components work immediately
+// Custom components work immediately
 const sysLog = logger.getComponent('system');
 sysLog.info('✓ macOS version compatible', { version: '14.2', build: '23C64' });
 // Output: Pretty formatted terminal output with colors AND context data!
@@ -59,12 +60,10 @@ installLog.info('✓ Applications installed', { installed: 25, duration: '5m' })
 // 21:32:11.8 📦 [INSTALLER] ✓ Applications installed
 //    ├─ installed: 25
 //    └─ duration: 5m
-// No more JSON blobs in terminal! 🎉
+// No more JSON blobs in terminal!
 ```
 
-### **v1.2.0: Fully Generic Design - Works with Any Project!**  
-
-> **⚠️ Breaking Change:** v1.2.0 requires defining components in your logger-config.json. The logger is now 100% generic with no hardcoded assumptions. 
+### **Standard Usage**
 
 ```javascript
 import JSGLogger from '@crimsonsunset/jsg-logger';
@@ -84,12 +83,12 @@ const startTime = performance.now();
 // ... do work ...
 JSGLogger.logPerformance('Page Generation', startTime, 'api');
 
-// ✨ NEW: Custom components auto-created on demand
+// Custom components auto-created on demand
 const dynamicLogger = logger.getComponent('new-feature');
 dynamicLogger.info('Auto-created component!'); // Works immediately
 ```
 
-### **Traditional Usage (Still Supported)**
+### **Alternative Usage**
 
 ```javascript
 import logger from '@crimsonsunset/jsg-logger';
@@ -119,7 +118,7 @@ This allows surgical debugging - you can turn on trace logging for just one prob
 
 ## ⚙️ **Advanced Configuration**
 
-### **Force Environment Override** ✨ *New in v1.5.0*
+### **Force Environment Override**
 
 Perfect for CLI tools that get mis-detected as "server" mode:
 
@@ -153,7 +152,7 @@ Or in `logger-config.json`:
 - Testing different output formats
 - Production deployments with specific requirements
 
-### **Custom Component Names** ✨ *New in v1.5.0*
+### **Custom Component Names**
 
 Use ANY component name - no need to pre-define in COMPONENT_SCHEME:
 
@@ -229,6 +228,9 @@ log4.info('This works!'); // Uses auto-generated styling
         "jsonPayload": false
       }
     }
+  },
+  "devtools": {
+    "enabled": false
   }
 }
 ```
@@ -351,7 +353,7 @@ logger.controls.addFileOverride('src/popup.js', {
 
 ### **Context Data**
 
-✨ **New in v1.5.0:** Context data now displays in CLI/terminal mode with tree formatting!
+Context data displays in CLI/terminal mode with tree formatting:
 
 ```javascript
 logger.api.error('Request failed', {
@@ -414,12 +416,10 @@ logger.controls.getTimestampMode()                   // Get current mode
 logger.controls.getTimestampModes()                  // List available modes
 ```
 
-### **System Controls**
+### **DevTools Panel Controls**
 ```javascript
-logger.controls.refresh()                            // Refresh all loggers
-logger.controls.reset()                              // Reset to defaults
-logger.controls.getConfigSummary()                   // Get config summary
-logger.controls.getStats()                           // Get logging stats
+logger.controls.enableDevPanel()   // Enable DevTools panel (requires devtools.enabled: true)
+logger.controls.disableDevPanel()   // Disable DevTools panel
 ```
 
 ## 📊 **Log Store & Statistics**
@@ -509,26 +509,15 @@ The logger automatically detects its environment and uses optimal implementation
 - **CLI**: Uses pino-colada for beautiful terminal output  
 - **Server**: Uses structured JSON for production logging
 
-### **Enhanced CLI Detection** ✨ *Improved in v1.5.0*
+### **Enhanced CLI Detection**
 
-The CLI detection now checks multiple signals:
+The CLI detection checks multiple signals:
 1. **TTY Check**: `process.stdout.isTTY` or `process.stderr.isTTY`
 2. **Terminal Environment**: `process.env.TERM` or `process.env.COLORTERM`
 3. **Non-CI Context**: Not running in CI/GitHub Actions
 
 This fixes detection issues in various terminal contexts where `isTTY` may be undefined.
 
-### **Force Environment Override** ✨ *New in v1.5.0*
-
-If auto-detection fails, you can force the environment:
-
-```javascript
-const logger = JSGLogger.getInstanceSync({
-  forceEnvironment: 'cli',  // Override auto-detection
-  // ... rest of config
-});
-```
-
 **Why Browser is Different:**
 Our testing revealed that Pino's browser detection was interfering with custom formatters, especially in Chrome extensions. By creating a custom direct browser logger that bypasses Pino entirely, we achieved:
 - Perfect emoji and color display
@@ -567,6 +556,64 @@ logger.controls.addFileOverride('src/popup.js', {           // Debug popup
 });
 ```
 
+## 🎛️ **DevTools Panel (Optional)**
+
+JSG Logger includes an optional DevTools panel for visual debugging. The panel is **disabled by default** to keep bundle size minimal.
+
+### **How Tree-Shaking Works**
+
+Tree-shaking is based on the **default config** (`devtools.enabled: false` by default). This means:
+
+- **Default behavior**: DevTools code is completely tree-shaken out, resulting in zero bundle impact
+- **Consumer config override**: If you enable devtools in your runtime config (`{ devtools: { enabled: true } }`), it loads dynamically when needed
+- **Best of both worlds**: Zero bundle by default, but runtime flexibility when needed
+
+### **Enabling DevTools**
+
+1. **Enable in config:**
+```json
+{
+  "devtools": {
+    "enabled": true
+  }
+}
+```
+
+Or enable at runtime:
+```javascript
+const logger = JSGLogger.getInstance({
+  devtools: { enabled: true }
+});
+```
+
+2. **Enable the panel:**
+```javascript
+// Enable DevTools panel (only works if devtools.enabled: true in config)
+await logger.controls.enableDevPanel();
+```
+
+### **DevTools Features**
+
+- 🎛️ Visual component filter controls
+- 📊 Real-time log statistics
+- 🔧 Runtime level adjustment
+- ⚙️ Display option toggles
+- 📈 Component-level monitoring
+
+**Bundle Size:**
+- When `devtools.enabled: false` (default): Zero bundle impact (tree-shaken)
+- When enabled: ~81KB gzipped (includes Preact + Evergreen UI, self-contained)
+
+**Note for npm link users:** When developing with `npm link`, ensure your Vite config includes:
+```typescript
+server: {
+  fs: {
+    allow: ['..']
+  }
+}
+```
+This allows Vite to serve files from the symlinked package directory.
+
 ## 🔧 **Browser Developer Tools**
 
 In browser environments, runtime controls are available globally:
@@ -577,6 +624,7 @@ JSG_Logger.enableDebugMode();
 JSG_Logger.setDisplayOption('level', true);
 JSG_Logger.addFileOverride('src/popup.js', { level: 'trace' });
 JSG_Logger.getStats();
+JSG_Logger.enableDevPanel(); // Enable DevTools panel (requires devtools.enabled: true)
 ```
 
 ## ⚠️ **Disclaimer**

package/config/config-manager.js

@@ -25,18 +25,35 @@ export class ConfigManager {
 
             if (typeof configSource === 'string') {
                 // Load from file path - handle all path formats
+                console.log(`[JSG-LOGGER] Loading config from file: ${configSource}`);
                 externalConfig = await this._loadConfigFromPath(configSource);
             } else if (typeof configSource === 'object') {
                 // Direct config object
+                console.log('[JSG-LOGGER] Loading inline config object:', Object.keys(configSource));
                 externalConfig = configSource;
             }
 
             // Normalize external config to match expected structure
             const normalizedConfig = this._normalizeConfigStructure(externalConfig);
             
+            // Log devtools status before merge
+            const devtoolsBefore = this.config.devtools?.enabled ?? false;
+            const devtoolsAfter = normalizedConfig.devtools?.enabled ?? devtoolsBefore;
+            
             // Merge configurations - project configs override defaults
             this.config = this.mergeConfigs(this.config, normalizedConfig);
 
+            // Log devtools activation status
+            const finalDevtoolsEnabled = this.config.devtools?.enabled ?? false;
+            if (finalDevtoolsEnabled !== devtoolsBefore) {
+                console.log(`[JSG-LOGGER] DevTools ${finalDevtoolsEnabled ? 'ENABLED' : 'DISABLED'} via user config (was ${devtoolsBefore ? 'enabled' : 'disabled'} in defaults)`);
+                if (finalDevtoolsEnabled) {
+                    console.log('[JSG-LOGGER] DevTools will be available when enableDevPanel() is called');
+                }
+            } else {
+                console.log(`[JSG-LOGGER] DevTools status: ${finalDevtoolsEnabled ? 'ENABLED' : 'DISABLED'} (using default config)`);
+            }
+
             return this.config;
         } catch (error) {
             console.error('ConfigManager: Error loading configuration:', error);
@@ -133,7 +150,7 @@ export class ConfigManager {
         
         try {
             // Try dynamic import first (works with ES modules)
-            const module = await import(path, { assert: { type: 'json' } });
+            const module = await import(/* @vite-ignore */ path, { assert: { type: 'json' } });
             return module.default || module;
         } catch (error) {
             try {
@@ -156,7 +173,7 @@ export class ConfigManager {
     async _loadConfigBrowserImport(path) {
         try {
             // Some bundlers can handle dynamic imports of JSON files
-            const module = await import(path);
+            const module = await import(/* @vite-ignore */ path);
             return module.default || module;
         } catch (error) {
             return null;
@@ -292,10 +309,16 @@ export class ConfigManager {
      * @private
      */
     _formatComponentName(componentName) {
+        // If already uppercase, return as-is
+        if (componentName === componentName.toUpperCase()) {
+            return componentName;
+        }
+        
+        // Convert to uppercase and preserve separators for readability
         return componentName
-            .split('-')
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-            .join('');
+            .replace(/([a-z])([A-Z])/g, '$1-$2')  // camelCase → kebab-case
+            .replace(/_/g, '-')  // snake_case → kebab-case
+            .toUpperCase();
     }
 
     /**
@@ -315,7 +338,11 @@ export class ConfigManager {
 
         for (const key in override) {
             if (override.hasOwnProperty(key)) {
-                if (typeof override[key] === 'object' && !Array.isArray(override[key])) {
+                // Special case: 'components' should be replaced, not merged
+                // This allows users to define their own components without getting defaults
+                if (key === 'components' && typeof override[key] === 'object') {
+                    merged[key] = override[key];
+                } else if (typeof override[key] === 'object' && !Array.isArray(override[key])) {
                     merged[key] = this.mergeConfigs(merged[key] || {}, override[key]);
                 } else {
                     merged[key] = override[key];
@@ -419,7 +446,7 @@ export class ConfigManager {
             baseComponent = {
                 emoji: '📦',
                 color: '#999999',
-                name: componentName.toUpperCase().replace(/-/g, '-'),
+                name: this._formatComponentName(componentName),
                 level: this.config.globalLevel || 'info'
             };
         }
@@ -539,10 +566,14 @@ export class ConfigManager {
      */
     getAvailableComponents() {
         const configComponents = Object.keys(this.config.components || {});
-        const schemeComponents = Object.keys(COMPONENT_SCHEME);
-
-        // Combine and deduplicate
-        return [...new Set([...configComponents, ...schemeComponents])];
+        
+        // If user has defined components, only return those
+        if (configComponents.length > 0) {
+            return configComponents;
+        }
+        
+        // Fallback to COMPONENT_SCHEME if no components configured (backward compatibility)
+        return Object.keys(COMPONENT_SCHEME);
     }
 
     /**

package/config/default-config.json

@@ -33,5 +33,8 @@
     }
   },
   "fileOverrides": {
+  },
+  "devtools": {
+    "enabled": false
   }
 }