state-surgeon 1.1.0 → 2.0.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { v4 } from 'uuid';
-import express, { Router } from 'express';
+import express from 'express';
 import { WebSocketServer } from 'ws';
 
 var __defProp = Object.defineProperty;
@@ -14,6 +14,320 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/core/analyzer.ts
+var StateAnalyzer = class {
+  constructor() {
+    this.invariants = [];
+    this.updateTimestamps = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register custom invariant rules
+   */
+  addInvariant(invariant) {
+    this.invariants.push(invariant);
+  }
+  /**
+   * Analyze a single mutation for issues
+   */
+  analyzeMutation(mutation, index, timeline) {
+    const issues = [];
+    if (mutation.diff) {
+      for (const diff of mutation.diff) {
+        if (diff.operation === "REMOVE") {
+          issues.push({
+            id: `issue_${mutation.id}_${diff.path}_loss`,
+            category: "state-loss",
+            severity: "critical",
+            title: `State field removed: ${diff.path}`,
+            description: `The field "${diff.path}" was removed from state. This may indicate an overwrite instead of a merge.`,
+            mutationId: mutation.id,
+            mutationIndex: index,
+            path: diff.path,
+            previousValue: diff.oldValue,
+            currentValue: void 0,
+            suggestion: "Use spread operator to preserve existing fields: setState(prev => ({ ...prev, newField }))",
+            timestamp: mutation.timestamp
+          });
+        }
+        if (diff.operation !== "REMOVE") {
+          const invalidIssue = this.checkInvalidValue(diff, mutation, index);
+          if (invalidIssue) {
+            issues.push(invalidIssue);
+          }
+        }
+        if (diff.operation === "UPDATE") {
+          const typeIssue = this.checkTypeChange(diff, mutation, index);
+          if (typeIssue) {
+            issues.push(typeIssue);
+          }
+        }
+      }
+    }
+    if (this.isNoOpUpdate(mutation)) {
+      issues.push({
+        id: `issue_${mutation.id}_noop`,
+        category: "no-op-update",
+        severity: "info",
+        title: "Redundant state update",
+        description: "This mutation did not change any values. Consider memoizing or adding conditions.",
+        mutationId: mutation.id,
+        mutationIndex: index,
+        suggestion: "Add a condition before updating: if (newValue !== currentValue) setState(newValue)",
+        timestamp: mutation.timestamp
+      });
+    }
+    const excessiveIssue = this.checkExcessiveUpdates(mutation, index);
+    if (excessiveIssue) {
+      issues.push(excessiveIssue);
+    }
+    for (const invariant of this.invariants) {
+      const violation = this.checkInvariant(invariant, mutation, index);
+      if (violation) {
+        issues.push(violation);
+      }
+    }
+    return issues;
+  }
+  /**
+   * Check for invalid values (NaN, unexpected undefined/null)
+   */
+  checkInvalidValue(diff, mutation, index) {
+    const value = diff.newValue;
+    if (typeof value === "number" && isNaN(value)) {
+      return {
+        id: `issue_${mutation.id}_${diff.path}_nan`,
+        category: "invalid-value",
+        severity: "critical",
+        title: `NaN value at: ${diff.path}`,
+        description: `The value at "${diff.path}" became NaN. This usually indicates a calculation with undefined/null.`,
+        mutationId: mutation.id,
+        mutationIndex: index,
+        path: diff.path,
+        previousValue: diff.oldValue,
+        currentValue: value,
+        suggestion: "Check for undefined/null values before calculation. Use default values: (value ?? 0)",
+        timestamp: mutation.timestamp
+      };
+    }
+    if (value === void 0 && diff.oldValue !== void 0 && diff.operation === "UPDATE") {
+      return {
+        id: `issue_${mutation.id}_${diff.path}_undefined`,
+        category: "invalid-value",
+        severity: "critical",
+        title: `Value became undefined: ${diff.path}`,
+        description: `The field "${diff.path}" changed from a defined value to undefined.`,
+        mutationId: mutation.id,
+        mutationIndex: index,
+        path: diff.path,
+        previousValue: diff.oldValue,
+        currentValue: void 0,
+        suggestion: "Ensure the value is always defined or explicitly handle undefined cases.",
+        timestamp: mutation.timestamp
+      };
+    }
+    return null;
+  }
+  /**
+   * Check for unexpected type changes
+   */
+  checkTypeChange(diff, mutation, index) {
+    if (diff.oldValue === void 0 || diff.oldValue === null) return null;
+    if (diff.newValue === void 0 || diff.newValue === null) return null;
+    const oldType = typeof diff.oldValue;
+    const newType = typeof diff.newValue;
+    if (oldType !== newType) {
+      return {
+        id: `issue_${mutation.id}_${diff.path}_type`,
+        category: "type-change",
+        severity: "warning",
+        title: `Type changed: ${diff.path}`,
+        description: `The type of "${diff.path}" changed from ${oldType} to ${newType}.`,
+        mutationId: mutation.id,
+        mutationIndex: index,
+        path: diff.path,
+        previousValue: diff.oldValue,
+        currentValue: diff.newValue,
+        suggestion: "Ensure consistent types. Use TypeScript or runtime validation.",
+        timestamp: mutation.timestamp
+      };
+    }
+    return null;
+  }
+  /**
+   * Check if mutation is a no-op (no actual changes)
+   */
+  isNoOpUpdate(mutation) {
+    if (!mutation.diff || mutation.diff.length === 0) {
+      return true;
+    }
+    return mutation.diff.every((d) => {
+      if (d.operation !== "UPDATE") return false;
+      return JSON.stringify(d.oldValue) === JSON.stringify(d.newValue);
+    });
+  }
+  /**
+   * Check for excessive updates in short time period
+   */
+  checkExcessiveUpdates(mutation, index) {
+    const key = mutation.component || mutation.source;
+    const timestamps = this.updateTimestamps.get(key) || [];
+    timestamps.push(mutation.timestamp);
+    const cutoff = mutation.timestamp - 100;
+    const recentTimestamps = timestamps.filter((t) => t >= cutoff);
+    this.updateTimestamps.set(key, recentTimestamps);
+    if (recentTimestamps.length > 5) {
+      return {
+        id: `issue_${mutation.id}_excessive`,
+        category: "excessive-updates",
+        severity: "warning",
+        title: `Excessive updates from: ${key}`,
+        description: `${recentTimestamps.length} mutations in 100ms from "${key}". This may cause performance issues.`,
+        mutationId: mutation.id,
+        mutationIndex: index,
+        suggestion: "Use debouncing, batching, or memoization to reduce update frequency.",
+        timestamp: mutation.timestamp
+      };
+    }
+    return null;
+  }
+  /**
+   * Check custom invariant rule
+   */
+  checkInvariant(invariant, mutation, index) {
+    if (!mutation.nextState) return null;
+    const value = getValueAtPath(mutation.nextState, invariant.path);
+    try {
+      const isValid = invariant.rule(value);
+      if (!isValid) {
+        return {
+          id: `issue_${mutation.id}_invariant_${invariant.name}`,
+          category: "broken-invariant",
+          severity: "critical",
+          title: `Invariant violated: ${invariant.name}`,
+          description: invariant.message,
+          mutationId: mutation.id,
+          mutationIndex: index,
+          path: invariant.path,
+          currentValue: value,
+          suggestion: `Ensure the invariant "${invariant.name}" is always maintained.`,
+          timestamp: mutation.timestamp
+        };
+      }
+    } catch (e) {
+      return null;
+    }
+    return null;
+  }
+  /**
+   * Analyze entire timeline for issues
+   */
+  analyzeTimeline(timeline) {
+    const allIssues = [];
+    this.updateTimestamps.clear();
+    for (let i = 0; i < timeline.length; i++) {
+      const issues = this.analyzeMutation(timeline[i], i, timeline);
+      allIssues.push(...issues);
+    }
+    return allIssues;
+  }
+  /**
+   * Build dependency graph showing which components touch which state paths
+   */
+  buildDependencyGraph(timeline) {
+    const nodes = /* @__PURE__ */ new Map();
+    for (const mutation of timeline) {
+      if (!mutation.diff) continue;
+      const component = mutation.component || mutation.source || "unknown";
+      for (const diff of mutation.diff) {
+        const existing = nodes.get(diff.path);
+        if (existing) {
+          existing.components.add(component);
+          existing.mutationCount++;
+          existing.lastMutationId = mutation.id;
+        } else {
+          nodes.set(diff.path, {
+            path: diff.path,
+            components: /* @__PURE__ */ new Set([component]),
+            mutationCount: 1,
+            lastMutationId: mutation.id
+          });
+        }
+      }
+    }
+    const couplings = [];
+    for (const [path, node] of nodes) {
+      if (node.components.size > 1) {
+        couplings.push({
+          path,
+          components: Array.from(node.components),
+          severity: node.components.size > 2 ? "critical" : "warning"
+        });
+      }
+    }
+    return { nodes, couplings };
+  }
+  /**
+   * Find causal chain - which mutations caused downstream effects
+   */
+  findCausalChain(mutationId, timeline) {
+    const rootIndex = timeline.findIndex((m) => m.id === mutationId);
+    if (rootIndex === -1) return null;
+    const root = timeline[rootIndex];
+    const effects = [];
+    if (!root.diff) return { rootMutation: root, effects };
+    const changedPaths = new Set(root.diff.map((d) => d.path));
+    for (let i = rootIndex + 1; i < timeline.length; i++) {
+      const mutation = timeline[i];
+      if (!mutation.diff) continue;
+      for (const diff of mutation.diff) {
+        for (const changedPath of changedPaths) {
+          if (diff.path.startsWith(changedPath) || changedPath.startsWith(diff.path)) {
+            effects.push({
+              mutation,
+              causedBy: root.id,
+              reason: `Uses path "${diff.path}" which was affected by "${changedPath}"`
+            });
+            break;
+          }
+        }
+      }
+    }
+    return { rootMutation: root, effects };
+  }
+  /**
+   * Find the first mutation that corrupted state
+   * Uses binary search for efficiency
+   */
+  findCorruptionPoint(timeline, validator) {
+    let left = 0;
+    let right = timeline.length - 1;
+    let result = null;
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2);
+      const mutation = timeline[mid];
+      if (mutation.nextState && !validator(mutation.nextState)) {
+        result = { mutation, index: mid };
+        right = mid - 1;
+      } else {
+        left = mid + 1;
+      }
+    }
+    return result;
+  }
+};
+function getValueAtPath(obj, path) {
+  if (!path) return obj;
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === void 0) return void 0;
+    if (typeof current !== "object") return void 0;
+    current = current[part];
+  }
+  return current;
+}
+var analyzer = new StateAnalyzer();
+
 // src/core/diff.ts
 function deepClone(obj) {
   if (obj === null || typeof obj !== "object") {
@@ -114,7 +428,7 @@ function applyDiff(state, diffs) {
   }
   return result;
 }
-function getValueAtPath(obj, path) {
+function getValueAtPath2(obj, path) {
   if (!path || path === "root") return obj;
   const parts = parsePath(path);
   let current = obj;
@@ -1056,6 +1370,8 @@ __export(recorder_exports, {
   createAPIRoutes: () => createAPIRoutes,
   createRecorderServer: () => createRecorderServer
 });
+
+// src/recorder/api.ts
 function createAPIRoutes(store, reconstructor) {
   const router = Router();
   router.get("/health", (_req, res) => {
@@ -1306,8 +1622,8 @@ var TimelineReconstructor = class {
           }
         }
       } else {
-        const prevValue = getValueAtPath(mutation.previousState, path);
-        const nextValue = getValueAtPath(mutation.nextState, path);
+        const prevValue = getValueAtPath2(mutation.previousState, path);
+        const nextValue = getValueAtPath2(mutation.nextState, path);
         if (prevValue !== nextValue) {
           result.push(mutation);
         }
@@ -1793,6 +2109,6 @@ function createRecorderServer(options = {}) {
   return server;
 }
 
-export { applyDiff, calculateDiff, compress, createMutation, debounce, decompress, deepClone, deepEqual, deepMerge, formatBytes, formatDuration, generateSessionId, getLogicalClock, getValueAtPath, instrument_exports as instrument, isBrowser, isNode, parseCallStack, recorder_exports as recorder, resetLogicalClock, safeParse, safeStringify, setValueAtPath, simpleHash, throttle };
+export { StateAnalyzer, analyzer, applyDiff, calculateDiff, compress, createMutation, debounce, decompress, deepClone, deepEqual, deepMerge, formatBytes, formatDuration, generateSessionId, getLogicalClock, getValueAtPath2 as getValueAtPath, instrument_exports as instrument, isBrowser, isNode, parseCallStack, recorder_exports as recorder, resetLogicalClock, safeParse, safeStringify, setValueAtPath, simpleHash, throttle };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map