From eb7d22f610fb40b8755e50032e35da1d2e355485 Mon Sep 17 00:00:00 2001
From: Slinetrac <realakayuki@gmail.com>
Date: Sat, 6 Dec 2025 11:36:47 +0800
Subject: [PATCH] refactor(debug): simplify toggle flow and unify flag handling

---
 src/utils/debug.ts | 90 +++++++++++++++++++++++-----------------------
 1 file changed, 46 insertions(+), 44 deletions(-)

diff --git a/src/utils/debug.ts b/src/utils/debug.ts
index e57131239..270b2e992 100644
--- a/src/utils/debug.ts
+++ b/src/utils/debug.ts
@@ -1,54 +1,49 @@
-const envVarValue = (import.meta.env.VITE_ENABLE_DEBUG_LOGS ?? "").toString();
+/**
+ * Debug logging is enabled when:
+ * - dev build (`import.meta.env.DEV`)
+ * - env flag `VITE_ENABLE_DEBUG_LOGS` is truthy (1/true/yes)
+ * - page sets `window.__VERGE_ENABLE_DEBUG_LOGS__ = true`
+ * - localStorage item `VERGE_DEBUG_LOGS` is truthy (1/true/yes)
+ * Use `setDebugLoggingEnabled` to force-enable/disable at runtime.
+ */
+let runtimeOverride: boolean | undefined;
+let cachedDebugEnabled: boolean | undefined;
 
-let runtimeOverride: boolean | null = null;
-
-const parseStringFlag = (value: string) => {
-  if (!value) return false;
-  const normalized = value.trim().toLowerCase();
+const parseStringFlag = (value: unknown) => {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  if (!normalized) return false;
   return normalized === "1" || normalized === "true" || normalized === "yes";
 };
 
-let cachedDebugEnabled: boolean | null = null;
-
-const computeDebugEnabled = () => {
-  if (import.meta.env.DEV) {
-    return true;
-  }
-
-  if (parseStringFlag(envVarValue)) {
-    return true;
-  }
-
-  if (typeof window !== "undefined") {
-    const globalFlag = (window as any).__VERGE_ENABLE_DEBUG_LOGS__;
-    if (typeof globalFlag === "boolean") {
-      return globalFlag;
-    }
-
-    try {
-      const stored = window.localStorage?.getItem("VERGE_DEBUG_LOGS");
-      if (stored) {
-        return parseStringFlag(stored);
-      }
-    } catch {
-      // ignore storage access errors
-    }
-  }
-
-  return false;
+const readGlobalFlag = (): boolean | null => {
+  if (typeof window === "undefined") return null;
+  const flag = (window as any).__VERGE_ENABLE_DEBUG_LOGS__;
+  return typeof flag === "boolean" ? flag : null;
 };
 
-const isEnvDebugEnabled = () => {
-  if (runtimeOverride !== null) {
-    return runtimeOverride;
+const readStoredFlag = (): boolean | null => {
+  if (typeof window === "undefined") return null;
+  try {
+    const stored = window.localStorage?.getItem("VERGE_DEBUG_LOGS");
+    return stored ? parseStringFlag(stored) : null;
+  } catch {
+    return null;
   }
+};
 
-  if (cachedDebugEnabled !== null) {
-    return cachedDebugEnabled;
-  }
+const computeDebugEnabled = (): boolean => {
+  if (import.meta.env.DEV) return true;
+  if (parseStringFlag(import.meta.env.VITE_ENABLE_DEBUG_LOGS)) return true;
 
-  cachedDebugEnabled = computeDebugEnabled();
-  return cachedDebugEnabled;
+  const globalFlag = readGlobalFlag();
+  if (globalFlag !== null) return globalFlag;
+
+  const storedFlag = readStoredFlag();
+  if (storedFlag !== null) return storedFlag;
+
+  return false;
 };
 
 export const setDebugLoggingEnabled = (enabled: boolean) => {
@@ -56,9 +51,16 @@ export const setDebugLoggingEnabled = (enabled: boolean) => {
   cachedDebugEnabled = enabled;
 };
 
-export const isDebugLoggingEnabled = () => isEnvDebugEnabled();
+export const isDebugLoggingEnabled = () =>
+  runtimeOverride ??
+  cachedDebugEnabled ??
+  (cachedDebugEnabled = computeDebugEnabled());
 
+/**
+ * Logs to the console only when debug logging is enabled.
+ * Forwards all arguments to `console.log`; does nothing otherwise.
+ */
 export const debugLog = (...args: any[]) => {
-  if (!isEnvDebugEnabled()) return;
+  if (!isDebugLoggingEnabled()) return;
   console.log(...args);
 };