hakmem/core/hakmem_debug_master.h

// hakmem_debug_master.h - Master Debug Control
//
// ENV Cleanup Phase 4b: Add master debug level control
// Updated 2025-11-29: Expanded to 0-5 levels, replaces individual debug ENVs
//
// Usage:
//   HAKMEM_DEBUG_ALL=1      Enable ALL debug output modules
//   HAKMEM_DEBUG_LEVEL=N    Set debug level (0=off, 1=error, 2=warn, 3=info, 4=debug, 5=trace)
//   HAKMEM_QUIET=1          Suppress all debug output (overrides DEBUG_ALL/LEVEL)
//
// Level Definitions:
//   0 = OFF       Production mode (all debug disabled)
//   1 = ERROR     Critical errors only
//   2 = WARN      Warnings + errors
//   3 = INFO      Allocation paths, header validation, stats
//   4 = DEBUG     Guard instrumentation, failfast
//   5 = TRACE     Verbose tracing (all debug output)
//
// Priority (highest to lowest):
//   1. HAKMEM_QUIET=1 → suppress all (returns 0)
//   2. Specific module ENV (e.g., HAKMEM_SFC_DEBUG=1) → use that value
//   3. HAKMEM_DEBUG_ALL=1 → enable all (returns 1)
//   4. HAKMEM_DEBUG_LEVEL >= threshold → enable (returns 1)
//   5. Default → disabled (returns 0)
//
// Integration example:
//   Old: static int dbg = -1;
//        if (dbg==-1) { const char* e = getenv("HAKMEM_FOO_DEBUG"); dbg = (e && *e != '0') ? 1 : 0; }
//        if (dbg) { fprintf(stderr, "..."); }
//
//   New: static int dbg = -1;
//        if (dbg==-1) { dbg = hak_debug_check("HAKMEM_FOO_DEBUG"); }
//        if (dbg) { fprintf(stderr, "..."); }

#ifndef HAKMEM_DEBUG_MASTER_H
#define HAKMEM_DEBUG_MASTER_H

#include <stdlib.h>
#include <string.h>

// Master debug state (cached at first access)
// Level: -1 = uninitialized, 0-5 = off/error/warn/info/debug/trace
static int g_debug_master_level = -1;
static int g_debug_all = -1;
static int g_debug_quiet = -1;

// Initialize master debug settings (called once, lazily)
static inline void hak_debug_master_init(void) {
    if (__builtin_expect(g_debug_master_level >= 0, 1)) return;

    // Check HAKMEM_QUIET first (highest priority)
    const char* quiet = getenv("HAKMEM_QUIET");
    g_debug_quiet = (quiet && *quiet && *quiet != '0') ? 1 : 0;

    // Check HAKMEM_DEBUG_ALL
    const char* all = getenv("HAKMEM_DEBUG_ALL");
    g_debug_all = (all && *all && *all != '0') ? 1 : 0;

    // Check HAKMEM_DEBUG_LEVEL
    const char* lvl = getenv("HAKMEM_DEBUG_LEVEL");
    if (lvl && *lvl) {
        int v = atoi(lvl);
        if (v < 0) v = 0;
        if (v > 5) v = 5;  // Expanded to 0-5 range
        g_debug_master_level = v;
    } else {
        g_debug_master_level = g_debug_all ? 3 : 0;  // DEBUG_ALL → INFO level
    }
}

// Check if a specific debug module should be enabled
// Returns: 1 if debug should be enabled, 0 otherwise
static inline int hak_debug_check(const char* env_name) {
    hak_debug_master_init();

    // HAKMEM_QUIET overrides everything
    if (g_debug_quiet) return 0;

    // Check specific ENV first (allows explicit enable/disable)
    const char* e = getenv(env_name);
    if (e && *e) {
        return (*e != '0') ? 1 : 0;
    }

    // Fall back to master controls
    if (g_debug_all) return 1;
    if (g_debug_master_level >= 2) return 1;

    return 0;
}

// Check if debug should be enabled at a given level
// level: 1=critical, 2=normal, 3=verbose
static inline int hak_debug_check_level(const char* env_name, int level) {
    hak_debug_master_init();

    // HAKMEM_QUIET overrides everything
    if (g_debug_quiet) return 0;

    // Check specific ENV first
    const char* e = getenv(env_name);
    if (e && *e) {
        int v = atoi(e);
        return (v >= level) ? 1 : 0;
    }

    // Fall back to master level
    return (g_debug_master_level >= level) ? 1 : 0;
}

// Quick check if quiet mode is enabled (for performance-critical paths)
static inline int hak_is_quiet(void) {
    hak_debug_master_init();
    return g_debug_quiet;
}

#endif // HAKMEM_DEBUG_MASTER_H