🏗️ Architecture: How should we manage console.log statements across the entir...

📋 Decision Context

Question:

How should we manage console.log statements across the entire codebase to control debugging output?

Task: Implement centralized, intelligent logging system to control console noise and enable category-based debugging

🎯 Decision Made

Chosen:

Option 5: Global Log Control System with categories and verbosity levels

Options Considered:

1. 1. Leave console.log scattered throughout files with no control
2. 2. Use localStorage per-file toggles (like theme-logger)
3. 3. Comment out console.log when not needed
4. 4. Use environment variables to control logging
5. 5. Create centralized Global Log Control with categories and verbosity levels

💭 Reasoning

Created a centralized logging system in @libs-dev-tools/debug-utils that provides:

Key Benefits:

1. ONE config file controls ALL logs across the entire codebase
2. Category-based (14 categories: storage, auth, sync, theme, modules, widgets, etc.)
3. Two verbosity modes: 'short' (minimal data) and 'detailed' (full objects)
4. Runtime control via browser console (LogControl.enable('category'))
5. Zero performance overhead when disabled (logs completely skipped)
6. Production-safe (disabled by default)

Implementation:

• File: libs/libs-dev-tools/debug-utils/src/lib/global-log-control.ts
• Usage: const log = createLogger('category', 'Label')
• API: log(), log.short(), log.detailed(), log.emoji(), log.success(), log.error(), log.warn()

Already Applied To:

• gg-storage.ts (6 console.log replaced)
• indexeddb-adapter.ts (4 console.log replaced)
• theme-logger.service.ts (integrated)
• decorator-logger.ts (integrated)

Why This Beats Alternatives:

• vs localStorage per-file: No need to manage multiple keys, one config for everything
• vs comments: Logs stay in code but controlled, can enable instantly for debugging
• vs env vars: Runtime control without rebuilding, can toggle in browser console
• vs scattered: Clean console by default, enable only what you need when debugging

Pattern for Future:

1. Import: import { createLogger } from '@libs-dev-tools/debug-utils'
2. Create: const log = createLogger('category', 'ServiceName')
3. Use: log.emoji('🚀', 'Message:', data) or log.short() / log.detailed()
4. Control: Edit LOG_CONFIG or use LogControl in browser console

Example Migration: Before: console.log('🎯 Creating storage:', config.namespace, {strategy, adapter}) After: log.emoji('🎯', 'Creating storage:', config.namespace) + log.detailed('Config:', {strategy, adapter})

This provides intelligent, lightweight, centralized control over all debugging output while keeping logs available when needed.

📁 Files Involved

• libs/libs-dev-tools/debug-utils/src/lib/global-log-control.ts
• libs/libs-dev-tools/debug-utils/src/lib/console-control.ts
• libs/libs-dev-tools/debug-utils/MIGRATION-GUIDE.md
• libs/libs-dev-tools/debug-utils/QUICK-START.md
• libs/libs-foundational/storage-system/src/core/engine/gg-storage.ts
• libs/libs-foundational/storage-system/src/core/adapters/indexeddb-adapter.ts
• libs/theme-system/theme-runtime/src/lib/utils/theme-logger.service.ts
• libs/core/module-base/src/lib/utils/decorator-logger.ts

🔗 Related

• Decision ID: dev_1767727008188_bv1auji
• Session: 22
• Workspace: editor2

Auto-generated by MCP Smart Consolidation