@devlens/core 1.0.0

package/dist/index.js

@@ -0,0 +1,651 @@
+'use strict';
+
+// src/network/interceptor.ts
+function matchesPattern(url, patterns) {
+  return patterns.some(
+    (p) => typeof p === "string" ? url.includes(p) : p.test(url)
+  );
+}
+function generateIssueId(method, url, status) {
+  return `network:${method}:${url}:${status}`;
+}
+function severityFromStatus(status) {
+  if (status >= 500) return "error";
+  if (status >= 400) return "warn";
+  return "info";
+}
+function buildSuggestion(method, url, status) {
+  if (status >= 500)
+    return `Server returned ${status} for ${method} ${url} \u2014 check server logs`;
+  if (status === 404)
+    return `Endpoint ${url} not found \u2014 verify the URL is correct`;
+  if (status === 401 || status === 403)
+    return `Authentication/authorization failed for ${url} \u2014 check credentials or permissions`;
+  if (status >= 400)
+    return `Client error ${status} for ${method} ${url} \u2014 check request parameters`;
+  return `Request to ${url} completed with status ${status}`;
+}
+function createNetworkInterceptor(engine, config) {
+  const resolvedConfig = typeof config === "boolean" || config === void 0 ? {} : config;
+  const interceptFetch = resolvedConfig.fetch !== false;
+  const interceptXhr = resolvedConfig.xhr !== false;
+  const ignoreUrls = resolvedConfig.ignoreUrls ?? [];
+  const logSuccess = resolvedConfig.logSuccess ?? false;
+  let originalFetch = null;
+  let originalXhrOpen = null;
+  let originalXhrSend = null;
+  function shouldIgnore(url) {
+    return ignoreUrls.length > 0 && matchesPattern(url, ignoreUrls);
+  }
+  function reportNetworkIssue(method, url, status, statusText, duration, error) {
+    if (!engine.isEnabled()) return;
+    const severity = error ? "error" : severityFromStatus(status);
+    if (severity === "info" && !logSuccess) return;
+    const issue = {
+      id: generateIssueId(method, url, status),
+      timestamp: Date.now(),
+      severity,
+      category: "network",
+      message: error ? `${method} ${url} failed: ${error.message}` : `${method} ${url} returned ${status} ${statusText}`,
+      details: {
+        url,
+        method,
+        status,
+        statusText,
+        duration: `${duration}ms`
+      },
+      suggestion: error ? `Network request to ${url} failed \u2014 check if the server is running and the URL is correct` : buildSuggestion(method, url, status),
+      stack: error?.stack,
+      source: "NetworkInterceptor"
+    };
+    engine.report(issue);
+  }
+  function installFetchInterceptor() {
+    if (typeof globalThis.fetch === "undefined") return;
+    originalFetch = globalThis.fetch;
+    const savedFetch = originalFetch;
+    globalThis.fetch = async function devlensFetch(input, init) {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      const method = init?.method ?? "GET";
+      if (shouldIgnore(url)) {
+        return savedFetch.call(globalThis, input, init);
+      }
+      const start = performance.now();
+      try {
+        const response = await savedFetch.call(globalThis, input, init);
+        const duration = Math.round(performance.now() - start);
+        if (!response.ok || logSuccess) {
+          reportNetworkIssue(
+            method.toUpperCase(),
+            url,
+            response.status,
+            response.statusText,
+            duration
+          );
+        }
+        return response;
+      } catch (err) {
+        const duration = Math.round(performance.now() - start);
+        reportNetworkIssue(
+          method.toUpperCase(),
+          url,
+          0,
+          "Network Error",
+          duration,
+          err instanceof Error ? err : new Error(String(err))
+        );
+        throw err;
+      }
+    };
+  }
+  function installXhrInterceptor() {
+    if (typeof XMLHttpRequest === "undefined") return;
+    originalXhrOpen = XMLHttpRequest.prototype.open;
+    originalXhrSend = XMLHttpRequest.prototype.send;
+    const savedOpen = originalXhrOpen;
+    const savedSend = originalXhrSend;
+    XMLHttpRequest.prototype.open = function devlensXhrOpen(method, url, ...rest) {
+      this._devlens_method = method;
+      this._devlens_url = typeof url === "string" ? url : url.toString();
+      return savedOpen.apply(
+        this,
+        [method, url, ...rest]
+      );
+    };
+    XMLHttpRequest.prototype.send = function devlensXhrSend(body) {
+      const xhr = this;
+      const method = xhr._devlens_method ?? "GET";
+      const url = xhr._devlens_url ?? "";
+      if (shouldIgnore(url)) {
+        return savedSend.call(this, body);
+      }
+      const start = performance.now();
+      const onLoadEnd = () => {
+        const duration = Math.round(performance.now() - start);
+        if (xhr.status >= 400 || logSuccess) {
+          reportNetworkIssue(
+            method.toUpperCase(),
+            url,
+            xhr.status,
+            xhr.statusText,
+            duration
+          );
+        }
+        xhr.removeEventListener("loadend", onLoadEnd);
+        xhr.removeEventListener("error", onError);
+      };
+      const onError = () => {
+        const duration = Math.round(performance.now() - start);
+        reportNetworkIssue(
+          method.toUpperCase(),
+          url,
+          0,
+          "Network Error",
+          duration,
+          new Error("XMLHttpRequest network error")
+        );
+        xhr.removeEventListener("loadend", onLoadEnd);
+        xhr.removeEventListener("error", onError);
+      };
+      xhr.addEventListener("loadend", onLoadEnd);
+      xhr.addEventListener("error", onError);
+      return savedSend.call(this, body);
+    };
+  }
+  function install() {
+    if (typeof window === "undefined") return;
+    if (interceptFetch) installFetchInterceptor();
+    if (interceptXhr) installXhrInterceptor();
+  }
+  function uninstall() {
+    if (originalFetch) {
+      globalThis.fetch = originalFetch;
+      originalFetch = null;
+    }
+    if (originalXhrOpen) {
+      XMLHttpRequest.prototype.open = originalXhrOpen;
+      originalXhrOpen = null;
+    }
+    if (originalXhrSend) {
+      XMLHttpRequest.prototype.send = originalXhrSend;
+      originalXhrSend = null;
+    }
+  }
+  return { install, uninstall };
+}
+
+// src/guardian/data-guardian.ts
+var SKIP_PROPERTIES = /* @__PURE__ */ new Set([
+  "constructor",
+  "prototype",
+  "__proto__",
+  "toJSON",
+  "toString",
+  "valueOf",
+  "length",
+  "then",
+  "catch",
+  "finally",
+  "$$typeof",
+  "_owner",
+  "_store",
+  "ref",
+  "key",
+  "_self",
+  "_source",
+  "displayName",
+  "nodeType"
+]);
+var NON_PROXYABLE_TYPES = /* @__PURE__ */ new Set([
+  "[object Date]",
+  "[object RegExp]",
+  "[object Map]",
+  "[object Set]",
+  "[object WeakMap]",
+  "[object WeakSet]",
+  "[object Error]",
+  "[object Promise]",
+  "[object ArrayBuffer]",
+  "[object DataView]",
+  "[object Int8Array]",
+  "[object Uint8Array]",
+  "[object Float32Array]",
+  "[object Float64Array]"
+]);
+function isProxyable(value) {
+  if (value === null || value === void 0) return false;
+  if (typeof value !== "object" && typeof value !== "function") return false;
+  const tag = Object.prototype.toString.call(value);
+  return !NON_PROXYABLE_TYPES.has(tag);
+}
+function createDataGuardian(engine, config) {
+  const resolvedConfig = typeof config === "boolean" || config === void 0 ? {} : config;
+  const maxDepth = resolvedConfig.maxDepth ?? 5;
+  const ignorePaths = new Set(resolvedConfig.ignorePaths ?? []);
+  const verbose = resolvedConfig.verbose ?? false;
+  const proxyCache = /* @__PURE__ */ new WeakMap();
+  function shouldIgnorePath(path) {
+    if (ignorePaths.size === 0) return false;
+    return ignorePaths.has(path);
+  }
+  function reportAccess(path, value, label) {
+    if (!engine.isEnabled()) return;
+    if (shouldIgnorePath(path)) return;
+    const isNull = value === null;
+    const category = isNull ? "null-access" : "undefined-data";
+    const prop = path.split(".").pop() ?? path;
+    const issue = {
+      id: `${category}:${path}`,
+      timestamp: Date.now(),
+      severity: "warn",
+      category,
+      message: `Property "${prop}" is ${isNull ? "null" : "undefined"} at path "${path}"`,
+      path,
+      foundValue: value,
+      expectedType: "non-nullish value",
+      source: label,
+      suggestion: `Check if "${prop}" is loaded/initialized before accessing. Full path: ${path}`
+    };
+    engine.report(issue);
+  }
+  function createProxy(target, label, parentPath, depth) {
+    if (depth > maxDepth) return target;
+    const cached = proxyCache.get(target);
+    if (cached) return cached;
+    const proxy = new Proxy(target, {
+      get(obj, prop, receiver) {
+        if (typeof prop === "symbol") {
+          return Reflect.get(obj, prop, receiver);
+        }
+        if (SKIP_PROPERTIES.has(prop)) {
+          return Reflect.get(obj, prop, receiver);
+        }
+        const currentPath = parentPath ? `${parentPath}.${prop}` : prop;
+        const value = Reflect.get(obj, prop, receiver);
+        if (value === null || value === void 0) {
+          const hasOwn = Object.prototype.hasOwnProperty.call(obj, prop) || prop in obj;
+          if (hasOwn) {
+            reportAccess(currentPath, value, label);
+          } else if (verbose) {
+            reportAccess(currentPath, value, label);
+          }
+          return value;
+        }
+        if (typeof value === "function") {
+          return value;
+        }
+        if (isProxyable(value)) {
+          return createProxy(
+            value,
+            label,
+            currentPath,
+            depth + 1
+          );
+        }
+        return value;
+      },
+      has(obj, prop) {
+        return Reflect.has(obj, prop);
+      },
+      ownKeys(obj) {
+        return Reflect.ownKeys(obj);
+      },
+      getOwnPropertyDescriptor(obj, prop) {
+        return Reflect.getOwnPropertyDescriptor(obj, prop);
+      },
+      set(obj, prop, value, receiver) {
+        return Reflect.set(obj, prop, value, receiver);
+      },
+      deleteProperty(obj, prop) {
+        return Reflect.deleteProperty(obj, prop);
+      }
+    });
+    proxyCache.set(target, proxy);
+    return proxy;
+  }
+  function guard(target, label) {
+    if (target === null || target === void 0) {
+      const nullLabel = label ?? "unknown";
+      const issue = {
+        id: `null-access:${nullLabel}:root`,
+        timestamp: Date.now(),
+        severity: "error",
+        category: target === null ? "null-access" : "undefined-data",
+        message: `Attempted to guard a ${target === null ? "null" : "undefined"} value (label: "${nullLabel}")`,
+        path: nullLabel,
+        foundValue: target,
+        source: nullLabel,
+        suggestion: `The value passed to guard() is ${target === null ? "null" : "undefined"}. Ensure data is loaded before guarding.`
+      };
+      engine.report(issue);
+      return target;
+    }
+    if (!isProxyable(target)) return target;
+    return createProxy(target, label ?? "guarded", "", 0);
+  }
+  function guardDeep(target, label) {
+    if (target === null || target === void 0) return guard(target, label);
+    if (!isProxyable(target)) return target;
+    const seen = /* @__PURE__ */ new WeakSet();
+    const resolvedLabel = label ?? "guarded";
+    function walkAndProxy(obj, path, depth) {
+      if (depth > maxDepth) return;
+      if (seen.has(obj)) return;
+      seen.add(obj);
+      const keys = Object.keys(obj);
+      for (const key of keys) {
+        const value = obj[key];
+        if (value !== null && value !== void 0 && isProxyable(value)) {
+          const childPath = path ? `${path}.${key}` : key;
+          createProxy(value, resolvedLabel, childPath, depth + 1);
+          walkAndProxy(value, childPath, depth + 1);
+        }
+      }
+    }
+    walkAndProxy(target, "", 0);
+    return createProxy(target, resolvedLabel, "", 0);
+  }
+  function unguardAll() {
+  }
+  return { guard, guardDeep, unguardAll };
+}
+
+// src/catcher/global-catcher.ts
+function createGlobalCatcher(engine, config) {
+  const resolvedConfig = typeof config === "boolean" || config === void 0 ? {} : config;
+  const catchWindowErrors = resolvedConfig.windowErrors !== false;
+  const catchRejections = resolvedConfig.unhandledRejections !== false;
+  const catchConsoleErrors = resolvedConfig.consoleErrors === true;
+  let originalConsoleError = null;
+  function handleWindowError(event) {
+    if (!engine.isEnabled()) return;
+    const issue = {
+      id: `unhandled-error:${event.message}:${event.filename ?? ""}:${event.lineno ?? 0}`,
+      timestamp: Date.now(),
+      severity: "error",
+      category: "unhandled-error",
+      message: event.message || "Unknown error",
+      details: {
+        filename: event.filename,
+        lineno: event.lineno,
+        colno: event.colno
+      },
+      stack: event.error?.stack,
+      source: event.filename ? `${event.filename}:${event.lineno}:${event.colno}` : "unknown",
+      suggestion: event.filename ? `Unhandled error at ${event.filename}:${event.lineno} \u2014 wrap in try/catch or add error boundary` : "Unhandled error \u2014 add error handling to locate the source"
+    };
+    engine.report(issue);
+  }
+  function handleUnhandledRejection(event) {
+    if (!engine.isEnabled()) return;
+    const reason = event.reason;
+    const message = reason instanceof Error ? reason.message : typeof reason === "string" ? reason : "Unknown rejection reason";
+    const issue = {
+      id: `unhandled-rejection:${message}`,
+      timestamp: Date.now(),
+      severity: "error",
+      category: "unhandled-rejection",
+      message: `Unhandled Promise rejection: ${message}`,
+      details: {
+        reason: reason instanceof Error ? { name: reason.name, message: reason.message } : reason
+      },
+      stack: reason instanceof Error ? reason.stack : void 0,
+      source: "Promise",
+      suggestion: "Add .catch() to the Promise or use try/catch with await"
+    };
+    engine.report(issue);
+  }
+  function installConsoleInterceptor() {
+    if (typeof console === "undefined") return;
+    originalConsoleError = console.error;
+    const saved = originalConsoleError;
+    console.error = function devlensConsoleError(...args) {
+      saved.apply(console, args);
+      if (!engine.isEnabled()) return;
+      const message = args.map(
+        (arg) => typeof arg === "string" ? arg : JSON.stringify(arg)
+      ).join(" ");
+      const issue = {
+        id: `unhandled-error:console:${message.slice(0, 100)}`,
+        timestamp: Date.now(),
+        severity: "error",
+        category: "unhandled-error",
+        message: `console.error: ${message}`,
+        details: { args },
+        source: "console.error",
+        suggestion: "A console.error was detected \u2014 investigate the error above"
+      };
+      engine.report(issue);
+    };
+  }
+  function install() {
+    if (typeof window === "undefined") return;
+    if (catchWindowErrors) {
+      window.addEventListener("error", handleWindowError);
+    }
+    if (catchRejections) {
+      window.addEventListener(
+        "unhandledrejection",
+        handleUnhandledRejection
+      );
+    }
+    if (catchConsoleErrors) {
+      installConsoleInterceptor();
+    }
+  }
+  function uninstall() {
+    if (typeof window !== "undefined") {
+      window.removeEventListener("error", handleWindowError);
+      window.removeEventListener(
+        "unhandledrejection",
+        handleUnhandledRejection
+      );
+    }
+    if (originalConsoleError) {
+      console.error = originalConsoleError;
+      originalConsoleError = null;
+    }
+  }
+  return { install, uninstall };
+}
+
+// src/reporter/console-reporter.ts
+var CATEGORY_ICONS = {
+  "network": "\u{1F310}",
+  "null-access": "\u{1F480}",
+  "undefined-data": "\u{1F47B}",
+  "render-data": "\u{1F3A8}",
+  "unhandled-error": "\u{1F4A5}",
+  "unhandled-rejection": "\u26A1",
+  "type-mismatch": "\u{1F500}"
+};
+var SEVERITY_COLORS = {
+  error: "#ff4444",
+  warn: "#ffaa00",
+  info: "#4488ff"
+};
+var SEVERITY_LABELS = {
+  error: "ERROR",
+  warn: "WARN",
+  info: "INFO"
+};
+function formatDetails(issue) {
+  const lines = [];
+  if (issue.path) {
+    lines.push(`  \u251C\u2500 Path: ${issue.path}`);
+  }
+  if (issue.foundValue !== void 0) {
+    lines.push(
+      `  \u251C\u2500 Value: ${issue.foundValue === null ? "null" : String(issue.foundValue)}`
+    );
+  }
+  if (issue.details) {
+    const entries = Object.entries(issue.details);
+    for (const [key, value] of entries) {
+      lines.push(`  \u251C\u2500 ${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+    }
+  }
+  if (issue.source) {
+    lines.push(`  \u251C\u2500 Source: ${issue.source}`);
+  }
+  if (issue.suggestion) {
+    lines.push(`  \u251C\u2500 Suggestion: ${issue.suggestion}`);
+  }
+  if (issue.stack) {
+    const stackPreview = issue.stack.split("\n").slice(0, 3).join("\n");
+    lines.push(`  \u2514\u2500 Stack:
+${stackPreview}`);
+  } else if (lines.length > 0) {
+    const lastIdx = lines.length - 1;
+    lines[lastIdx] = lines[lastIdx].replace("\u251C\u2500", "\u2514\u2500");
+  }
+  return lines;
+}
+function createConsoleReporter() {
+  function report(issue) {
+    const icon = CATEGORY_ICONS[issue.category] ?? "\u{1F50D}";
+    const color = SEVERITY_COLORS[issue.severity];
+    const label = SEVERITY_LABELS[issue.severity];
+    const header = `${icon} DevLens [${label}] ${issue.category}: ${issue.message}`;
+    const details = formatDetails(issue);
+    const consoleFn = issue.severity === "error" ? console.error : issue.severity === "warn" ? console.warn : console.log;
+    console.groupCollapsed(
+      `%c${header}`,
+      `color: ${color}; font-weight: bold;`
+    );
+    for (const line of details) {
+      consoleFn(line);
+    }
+    consoleFn(
+      `%cTimestamp: ${new Date(issue.timestamp).toISOString()}`,
+      "color: #888;"
+    );
+    console.groupEnd();
+  }
+  function reportBatch(issues) {
+    if (issues.length === 0) return;
+    console.groupCollapsed(
+      `%c\u{1F50D} DevLens \u2014 ${issues.length} issue(s) detected`,
+      "color: #ff4444; font-weight: bold; font-size: 12px;"
+    );
+    for (const issue of issues) {
+      report(issue);
+    }
+    console.groupEnd();
+  }
+  function clear() {
+    console.clear();
+  }
+  return { report, reportBatch, clear };
+}
+
+// src/engine/detection-engine.ts
+var SEVERITY_RANK = {
+  info: 0,
+  warn: 1,
+  error: 2
+};
+function matchesAnyPattern(value, patterns) {
+  if (!value || patterns.length === 0) return false;
+  return patterns.some(
+    (p) => typeof p === "string" ? value.includes(p) : p.test(value)
+  );
+}
+function createDetectionEngine(config = {}) {
+  const resolvedConfig = {
+    enabled: config.enabled ?? true,
+    minSeverity: config.minSeverity ?? "info",
+    throttleMs: config.throttleMs ?? 1e3,
+    maxIssues: config.maxIssues ?? 100,
+    ...config
+  };
+  const reporter = resolvedConfig.reporter ?? createConsoleReporter();
+  const issues = [];
+  const subscribers = /* @__PURE__ */ new Set();
+  const lastReportedAt = /* @__PURE__ */ new Map();
+  function isEnabled() {
+    if (!resolvedConfig.enabled) return false;
+    if (typeof window === "undefined") return false;
+    try {
+      if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") {
+        return false;
+      }
+    } catch {
+    }
+    return true;
+  }
+  function meetsMinSeverity(severity) {
+    return SEVERITY_RANK[severity] >= SEVERITY_RANK[resolvedConfig.minSeverity];
+  }
+  function isThrottled(id, now) {
+    const lastTime = lastReportedAt.get(id);
+    if (lastTime === void 0) return false;
+    return now - lastTime < resolvedConfig.throttleMs;
+  }
+  function isIgnored(issue) {
+    const ignore = resolvedConfig.ignore;
+    if (!ignore) return false;
+    if (ignore.urls && matchesAnyPattern(
+      issue.details?.url,
+      ignore.urls
+    )) {
+      return true;
+    }
+    if (ignore.paths && matchesAnyPattern(issue.path, ignore.paths)) {
+      return true;
+    }
+    if (ignore.messages && matchesAnyPattern(issue.message, ignore.messages)) {
+      return true;
+    }
+    return false;
+  }
+  function addToBuffer(issue) {
+    issues.push(issue);
+    if (issues.length > resolvedConfig.maxIssues) {
+      issues.shift();
+    }
+  }
+  function report(issue) {
+    if (!isEnabled()) return;
+    if (!meetsMinSeverity(issue.severity)) return;
+    const now = Date.now();
+    if (isThrottled(issue.id, now)) return;
+    if (isIgnored(issue)) return;
+    lastReportedAt.set(issue.id, now);
+    addToBuffer(issue);
+    reporter.report(issue);
+    for (const callback of subscribers) {
+      try {
+        callback(issue);
+      } catch {
+      }
+    }
+  }
+  function getConfig() {
+    return Object.freeze({ ...resolvedConfig });
+  }
+  function getIssues() {
+    return [...issues];
+  }
+  function subscribe(callback) {
+    subscribers.add(callback);
+    return () => {
+      subscribers.delete(callback);
+    };
+  }
+  return {
+    report,
+    getConfig,
+    getIssues,
+    subscribe,
+    isEnabled
+  };
+}
+
+exports.createConsoleReporter = createConsoleReporter;
+exports.createDataGuardian = createDataGuardian;
+exports.createDetectionEngine = createDetectionEngine;
+exports.createGlobalCatcher = createGlobalCatcher;
+exports.createNetworkInterceptor = createNetworkInterceptor;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map