@signaltree/guardrails 4.2.1 → 5.0.0

package/dist/lib/guardrails.js

@@ -1,9 +1,6 @@
 function isFunction(value) {
   return typeof value === 'function';
 }
-function isString(value) {
-  return typeof value === 'string';
-}
 function isObjectLike(value) {
   return typeof value === 'object' && value !== null;
 }
@@ -20,10 +17,6 @@ function resolveEnabledFlag(option) {
   }
   return option;
 }
-function supportsMiddleware(tree) {
-  const candidate = tree;
-  return isFunction(candidate.addTap) && isFunction(candidate.removeTap);
-}
 function tryStructuredClone(value) {
   const cloneFn = globalThis.structuredClone;
   if (isFunction(cloneFn)) {
@@ -40,17 +33,13 @@ function isDevEnvironment() {
   return true;
 }
 const MAX_TIMING_SAMPLES = 1000;
-const RECOMPUTATION_WINDOW_MS = 1000;
+const POLLING_INTERVAL_MS = 50;
 function withGuardrails(config = {}) {
   return tree => {
     const enabled = resolveEnabledFlag(config.enabled);
     if (!isDevEnvironment() || !enabled) {
       return tree;
     }
-    if (!supportsMiddleware(tree)) {
-      console.warn('[Guardrails] Tree does not expose middleware hooks; guardrails disabled.');
-      return tree;
-    }
     const stats = createRuntimeStats();
     const context = {
       tree,
@@ -66,20 +55,16 @@ function withGuardrails(config = {}) {
       signalUsage: new Map(),
       memoryHistory: [],
       recomputationLog: [],
+      previousState: tryStructuredClone(tree()),
       disposed: false
     };
-    const middlewareId = `guardrails:${config.treeId ?? 'tree'}:${Math.random().toString(36).slice(2)}`;
-    context.middlewareId = middlewareId;
-    const middleware = createGuardrailsMiddleware(context);
-    tree.addTap(middleware);
+    const stopChangeDetection = startChangeDetection(context);
     const stopMonitoring = startMonitoring(context);
     const teardown = () => {
       if (context.disposed) return;
       context.disposed = true;
+      stopChangeDetection();
       stopMonitoring();
-      try {
-        tree.removeTap(middlewareId);
-      } catch {}
     };
     const originalDestroy = tree.destroy?.bind(tree);
     tree.destroy = () => {
@@ -92,6 +77,78 @@ function withGuardrails(config = {}) {
     return tree;
   };
 }
+function startChangeDetection(context) {
+  try {
+    const unsubscribe = context.tree.subscribe(() => {
+      handleStateChange(context);
+    });
+    return unsubscribe;
+  } catch {
+    return startPollingChangeDetection(context);
+  }
+}
+function handleStateChange(context) {
+  if (context.disposed || context.suppressed) return;
+  const currentState = context.tree();
+  const previousState = context.previousState;
+  if (!previousState) {
+    context.previousState = tryStructuredClone(currentState);
+    return;
+  }
+  const currentJson = JSON.stringify(currentState);
+  const previousJson = JSON.stringify(previousState);
+  if (currentJson !== previousJson) {
+    const startTime = performance.now();
+    const timestamp = Date.now();
+    const changedPaths = detectChangedPaths(previousState, currentState);
+    for (const path of changedPaths) {
+      const detail = {
+        path,
+        segments: path.split('.'),
+        oldValue: getValueAtPath(previousState, path.split('.')),
+        newValue: getValueAtPath(currentState, path.split('.'))
+      };
+      analyzePreUpdate(context, detail, {});
+      const duration = performance.now() - startTime;
+      const diffRatio = calculateDiffRatio(detail.oldValue, detail.newValue);
+      analyzePostUpdate(context, detail, duration, diffRatio);
+      trackHotPath(context, path, duration);
+      trackSignalUsage(context, path, timestamp);
+    }
+    const totalDuration = performance.now() - startTime;
+    updateTimingStats(context, totalDuration);
+    updateSignalStats(context, timestamp);
+    context.previousState = tryStructuredClone(currentState);
+  }
+}
+function startPollingChangeDetection(context) {
+  const pollForChanges = () => {
+    handleStateChange(context);
+  };
+  context.pollingIntervalId = setInterval(pollForChanges, POLLING_INTERVAL_MS);
+  return () => {
+    if (context.pollingIntervalId) {
+      clearInterval(context.pollingIntervalId);
+      context.pollingIntervalId = undefined;
+    }
+  };
+}
+function detectChangedPaths(oldState, newState, prefix = '') {
+  const changes = [];
+  const allKeys = new Set([...Object.keys(oldState || {}), ...Object.keys(newState || {})]);
+  for (const key of allKeys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const oldVal = oldState?.[key];
+    const newVal = newState?.[key];
+    if (oldVal === newVal) continue;
+    if (isObjectLike(oldVal) && isObjectLike(newVal) && !Array.isArray(oldVal) && !Array.isArray(newVal)) {
+      changes.push(...detectChangedPaths(oldVal, newVal, path));
+    } else {
+      changes.push(path);
+    }
+  }
+  return changes;
+}
 function createRuntimeStats() {
   return {
     updateCount: 0,
@@ -111,51 +168,6 @@ function createRuntimeStats() {
     violationCount: 0
   };
 }
-function createGuardrailsMiddleware(context) {
-  return {
-    id: context.middlewareId ?? 'guardrails',
-    before: (action, payload, state) => {
-      if (context.suppressed) {
-        context.currentUpdate = null;
-        return !context.disposed;
-      }
-      const metadata = extractMetadata(payload);
-      if (shouldSuppressUpdate(context, metadata)) {
-        context.currentUpdate = null;
-        return !context.disposed;
-      }
-      const details = collectUpdateDetails(payload, state);
-      context.currentUpdate = {
-        action,
-        startTime: performance.now(),
-        metadata,
-        details
-      };
-      for (const detail of details) {
-        analyzePreUpdate(context, detail, metadata);
-      }
-      return !context.disposed;
-    },
-    after: (_action, _payload, _previousState, newState) => {
-      const pending = context.currentUpdate;
-      if (!pending) return;
-      const duration = Math.max(0, performance.now() - pending.startTime);
-      const timestamp = Date.now();
-      const recomputations = Math.max(0, pending.details.length - 1);
-      updateTimingStats(context, duration);
-      for (const [index, detail] of pending.details.entries()) {
-        const latest = getValueAtPath(newState, detail.segments);
-        const diffRatio = calculateDiffRatio(detail.oldValue, latest);
-        analyzePostUpdate(context, detail, duration, diffRatio, index === 0);
-        trackHotPath(context, detail.path, duration);
-        trackSignalUsage(context, detail.path, timestamp);
-      }
-      updateSignalStats(context, timestamp);
-      recordRecomputations(context, recomputations, timestamp);
-      context.currentUpdate = null;
-    }
-  };
-}
 function updatePercentiles(context) {
   if (context.timings.length === 0) return;
   const sorted = [...context.timings].sort((a, b) => a - b);
@@ -193,7 +205,7 @@ function analyzePreUpdate(context, detail, metadata) {
   }
 }
 function analyzePostUpdate(context, detail, duration, diffRatio, isPrimary) {
-  if (isPrimary && context.config.budgets?.maxUpdateTime && duration > context.config.budgets.maxUpdateTime) {
+  if (context.config.budgets?.maxUpdateTime && duration > context.config.budgets.maxUpdateTime) {
     addIssue(context, {
       type: 'budget',
       severity: 'error',
@@ -278,18 +290,6 @@ function updateSignalStats(context, timestamp) {
   const growth = baseline === 0 ? 0 : (signalCount - baseline) / Math.max(1, baseline);
   context.stats.memoryGrowthRate = growth;
 }
-function recordRecomputations(context, count, timestamp) {
-  if (count > 0) {
-    context.stats.recomputationCount += count;
-    for (let i = 0; i < count; i++) {
-      context.recomputationLog.push(timestamp);
-    }
-  }
-  if (context.recomputationLog.length) {
-    context.recomputationLog = context.recomputationLog.filter(value => timestamp - value <= RECOMPUTATION_WINDOW_MS);
-  }
-  context.stats.recomputationsPerSecond = context.recomputationLog.length;
-}
 function updateHotPath(context, hotPath) {
   const existing = context.hotPaths.find(h => h.path === hotPath.path);
   if (existing) {
@@ -354,15 +354,6 @@ function addIssue(context, issue) {
     throw new Error(`[Guardrails] ${issue.message}`);
   }
 }
-function shouldSuppressUpdate(context, metadata) {
-  if (context.suppressed) return true;
-  if (!metadata) return false;
-  if (metadata.suppressGuardrails && context.config.suppression?.respectMetadata !== false) {
-    return true;
-  }
-  const autoSuppress = new Set(context.config.suppression?.autoSuppress ?? []);
-  return [metadata.intent, metadata.source].some(value => isString(value) && autoSuppress.has(value));
-}
 function startMonitoring(context) {
   const interval = setInterval(() => {
     if (context.disposed) {
@@ -527,55 +518,6 @@ function createAPI(context, teardown) {
     }
   };
 }
-function extractMetadata(payload) {
-  if (!isObjectLike(payload)) return undefined;
-  const candidate = payload['metadata'];
-  return isObjectLike(candidate) ? candidate : undefined;
-}
-function collectUpdateDetails(payload, stateSnapshot) {
-  const details = [];
-  const visit = (value, segments, currentState) => {
-    const path = segments.length ? segments.join('.') : 'root';
-    const oldValue = captureValue(currentState);
-    if (isObjectLike(value)) {
-      details.push({
-        path,
-        segments: [...segments],
-        newValue: value,
-        oldValue
-      });
-      for (const [key, child] of Object.entries(value)) {
-        visit(child, [...segments, key], isObjectLike(currentState) ? currentState[key] : undefined);
-      }
-      return;
-    }
-    details.push({
-      path,
-      segments: [...segments],
-      newValue: value,
-      oldValue
-    });
-  };
-  if (isObjectLike(payload)) {
-    visit(payload, [], stateSnapshot);
-  } else {
-    details.push({
-      path: 'root',
-      segments: [],
-      newValue: payload,
-      oldValue: captureValue(stateSnapshot)
-    });
-  }
-  if (details.length === 0) {
-    details.push({
-      path: 'root',
-      segments: [],
-      newValue: payload,
-      oldValue: captureValue(stateSnapshot)
-    });
-  }
-  return details;
-}
 function getValueAtPath(source, segments) {
   let current = source;
   for (const segment of segments) {
@@ -586,9 +528,6 @@ function getValueAtPath(source, segments) {
   }
   return current;
 }
-function captureValue(value) {
-  return tryStructuredClone(value);
-}
 function isPlainObject(value) {
   if (!value || typeof value !== 'object') return false;
   const proto = Object.getPrototypeOf(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/guardrails",
-  "version": "4.2.1",
+  "version": "5.0.0",
   "description": "Development-only performance monitoring and anti-pattern detection for SignalTree",
   "type": "module",
   "sideEffects": false,
@@ -57,7 +57,7 @@
     "type-check": "tsc --project tsconfig.lib.json --noEmit"
   },
   "peerDependencies": {
-    "@signaltree/core": "^4.2.1",
+    "@signaltree/core": "^5.0.0",
     "tslib": "^2.0.0"
   },
   "devDependencies": {