feat(errors): implement error handling and reporting for AutoAtomTransformer (#751)

BloggerBust · web-flow · commit 25082e249c99 · 2025-06-17T08:37:34.000-07:00
* feat(errors): add structured transform error reporting with frontend integration

- Introduced `error_registry.py` to collect structured errors during AST transformation
  - Errors include type, filename, line number, message, and optionally component ID or atom name
  - Thread-safe via lock; supports register/get/clear
- Updated `transform_source` to catch and register `SyntaxError` as transform errors
- Enhanced error handling in `register_display_dependency_resolver` with error registration
- `ScriptRunner` now:
  - Clears previous errors at script start
  - Sends either "components" or "errors:result" message based on presence of errors
- Frontend:
  - Added `ErrorsReport.jsx` component for displaying transform errors
  - Updated `Dashboard.jsx` to render error fragments and align empty state formatting
  - `App.jsx` now handles new `errors:result` message type and routes errors to dashboard

* feat(errors): add structured runtime error reporting and display improvements

- Add `_safe_register_error` method to AST transformer to capture structured transformation errors
- Wrap most lifting and analysis methods with try/except to register errors instead of crashing
- Extend error object metadata to include component ID, atom name, and extra context
- Improve debug logging and error traceability throughout the AST transformer
- Add `has_errors()` to BasePreswaldService for script fallback error checks
- Update ErrorsReport frontend to support collapsible/expandable error lists with CSS transitions
- Style error list in `components.css` and refactor JSX to allow toggling long error output
- Improve resilience and recovery logic in `ScriptRunner.compile_and_run()` when runtime errors occur

* chore(transformer): minor cleanup and import reordering

- Moved `register_error` import closer to usage in `reactive_runtime.py`
- Removed unused imports from `registry.py` and reordered for clarity
- Replaced bare `except` with `except Exception as e` for better debugging
- Added `# noqa` directives for intentional style suppressions
- No functional changes
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
@@ -10,6 +10,7 @@ import { comm } from './utils/websocket';
 const App = () => {
   const [components, setComponents] = useState({ rows: [] });
   const [error, setError] = useState(null);
+  const [transformErrors, setTransformErrors] = useState([]);
   const [config, setConfig] = useState(null);
   const [isConnected, setIsConnected] = useState(false);
   const [areComponentsLoading, setAreComponentsLoading] = useState(true);
@@ -52,6 +53,10 @@ const App = () => {
         handleError(message.content);
         break;
 
+      case 'errors:result':
+        handleTransformErrors(message.errors, message.components);
+        break;
+
       case 'connection_status':
         updateConnectionStatus(message);
         break;
@@ -123,6 +128,15 @@ const App = () => {
     }
   };
 
+  const handleTransformErrors = (errorContents, components = null) => {
+    console.error('[App] Received transform errors:', {errorContents, components});
+    setAreComponentsLoading(false);
+    setTransformErrors(errorContents || []);
+    if (components) {
+      refreshComponentsList(components);
+    }
+  };
+
   const handleComponentUpdate = (componentId, value) => {
     try {
       comm.updateComponentState(componentId, value);
@@ -157,6 +171,7 @@ const App = () => {
           <Dashboard
             components={components}
             error={error}
+            transformErrors={transformErrors}
             handleComponentUpdate={handleComponentUpdate}
           />
         )}
diff --git a/frontend/src/components.css b/frontend/src/components.css
@@ -196,7 +196,11 @@
 }
 
 .dashboard-error {
-  @apply mb-4;
+  @apply w-full text-sm mb-4;
+}
+
+.dashboard-error-fragment {
+  @apply w-full;
 }
 
 .dashboard-loading-container {
@@ -219,6 +223,10 @@
   @apply flex items-center justify-center h-64;
 }
 
+.dashboard-empty-with-errors {
+  @apply flex flex-col items-center justify-center space-y-4 h-64;
+}
+
 .dashboard-empty-text {
   @apply text-sm text-muted-foreground;
 }
@@ -828,3 +836,21 @@
   border-radius: 1px;
   transition: background-color 0.2s ease;
 }
+
+/* Error Report */
+.error-report-container {
+  @apply overflow-y-auto transition-[max-height] duration-300 ease-in-out;
+  max-height: 10rem;
+}
+
+.error-report-container.expanded {
+   max-height: 80vh; /* Limit to 80% of the viewport height */
+}
+
+.error-report-list {
+  @apply list-disc list-inside space-y-1;
+}
+
+.error-report-toggle {
+  @apply text-xs text-muted-foreground hover:underline mt-2 cursor-pointer;
+}
diff --git a/frontend/src/components/ErrorsReport.jsx b/frontend/src/components/ErrorsReport.jsx
@@ -0,0 +1,56 @@
+import React, { useState, useRef, useEffect } from 'react';
+import { Alert, AlertTitle, AlertDescription } from '@/components/ui/alert';
+
+const ErrorsReport = ({ errors }) => {
+  const [expanded, setExpanded] = useState(false);
+  const [wasOverflowingWhenCollapsed, setWasOverflowingWhenCollapsed] = useState(false);
+  const containerRef = useRef(null);
+  const EXPAND_COLLAPSE_TRANSITION_MS = 300; // must match duration in .error-report-container
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    // Only measure overflow when not expanded
+    if (!expanded) {
+      const timeout = setTimeout(() => {
+        const isOverflowing = el.scrollHeight > el.clientHeight;
+        setWasOverflowingWhenCollapsed(isOverflowing);
+      }, EXPAND_COLLAPSE_TRANSITION_MS);
+
+      return () => clearTimeout(timeout);
+    }
+  }, [errors, expanded]);
+
+  if (!errors || errors.length === 0) return null;
+
+  return (
+    <Alert variant="destructive" className="dashboard-error space-y-2">
+      <AlertTitle>Errors detected during source transformation</AlertTitle>
+      <AlertDescription>
+        <div
+          ref={containerRef}
+          className={`error-report-container ${expanded ? 'expanded' : ''}`}
+        >
+          <ul className="error-report-list">
+            {errors.map((err, idx) => (
+              <li key={idx}>
+                <strong>{err.filename}:{err.lineno}</strong> - {err.message}
+              </li>
+            ))}
+          </ul>
+        </div>
+        {wasOverflowingWhenCollapsed && (
+          <button
+            className="error-report-toggle"
+            onClick={() => setExpanded(prev => !prev)}
+          >
+            {expanded ? 'Show less' : 'Show all'}
+          </button>
+        )}
+      </AlertDescription>
+    </Alert>
+  );
+};
+
+export { ErrorsReport as default, ErrorsReport };
diff --git a/frontend/src/components/pages/Dashboard.jsx b/frontend/src/components/pages/Dashboard.jsx
@@ -2,11 +2,12 @@ import React from 'react';
 
 import { Alert, AlertDescription } from '@/components/ui/alert';
 
+import { ErrorsReport } from '../ErrorsReport'
 import DynamicComponents from '../DynamicComponents';
 import LoadingState from '../LoadingState';
 
-const Dashboard = ({ components, error, handleComponentUpdate }) => {
-  console.log('[Dashboard] Rendering with:', { components, error });
+const Dashboard = ({ components, error, transformErrors, handleComponentUpdate }) => {
+  console.log('[Dashboard] Rendering with:', { components, error, transformErrors });
 
   const isValidComponents =
     components &&
@@ -15,34 +16,45 @@ const Dashboard = ({ components, error, handleComponentUpdate }) => {
     components.rows.every((row) => Array.isArray(row));
 
   const renderContent = () => {
-    if (error) {
-      return (
-        <Alert variant="destructive" className="dashboard-error">
-          <AlertDescription>{error}</AlertDescription>
-        </Alert>
-      );
-    }
-
-    if (!isValidComponents) {
-      return (
-        <div className="dashboard-loading-container">
-          <LoadingState
-            isConnected={true}
-            customText={!components ? 'Loading components' : 'Invalid components data'}
-          />
-        </div>
-      );
+    const showTransformErrorBanner = transformErrors && transformErrors.length > 0;
+
+    const errorFragment = showTransformErrorBanner ? (
+      <div className="dashboard-error-fragment">
+        <ErrorsReport errors={transformErrors} />
+      </div>
+    ) : null;
+
+    const emptyWrapperClass = showTransformErrorBanner
+      ? 'dashboard-empty-with-errors' : 'dashboard-empty';
+
+    if (error || !isValidComponents) {
+      const alertMessage = error ?? 'Invalid components data'
+        return (
+          <div className={`${emptyWrapperClass}`}>
+            <Alert variant="destructive" className="dashboard-error">
+              <AlertDescription>{alertMessage}</AlertDescription>
+            </Alert>
+
+            {errorFragment}
+          </div>
+        )
     }
 
     if (components.rows.length === 0) {
       return (
-        <div className="dashboard-empty">
+        <div className={`${emptyWrapperClass}`}>
+          {errorFragment}
           <p className="dashboard-empty-text">No components to display</p>
         </div>
-      );
+      )
     }
 
-    return <DynamicComponents components={components} onComponentUpdate={handleComponentUpdate} />;
+    return (
+      <>
+        {errorFragment}
+        <DynamicComponents components={components} onComponentUpdate={handleComponentUpdate} />
+      </>
+    )
   };
 
   return <div className="dashboard-container">{renderContent()}</div>;
diff --git a/preswald/engine/base_service.py b/preswald/engine/base_service.py
@@ -15,6 +15,7 @@
 )
 from preswald.interfaces.workflow import Workflow, Atom
 from preswald.interfaces.component_return import ComponentReturn
+from preswald.interfaces.render.error_registry import get_errors, clear_errors
 from .managers.data import DataManager
 from .managers.layout import LayoutManager
 
@@ -304,6 +305,15 @@ def get_rendered_components(self):
         rows = self._layout_manager.get_layout()
         return {"rows": rows}
 
+    def get_errors(self, type: str | None = None, filename: str | None = None):
+        return get_errors(type=type, filename=filename)
+
+    def clear_errors(self, type: str | None = None):
+        return clear_errors(type=type)
+
+    def has_errors(self, type: str | None = None, filename: str | None = None):
+        return len(get_errors(type=type, filename=filename))
+
     def get_workflow(self) -> Workflow:
         return self._workflow
 
diff --git a/preswald/engine/runner.py b/preswald/engine/runner.py
@@ -137,7 +137,7 @@ async def rerun(self, new_widget_states: dict[str, Any] | None = None):
             return
 
         if not self._service.is_reactivity_enabled:
-            logger.info("[ScriptRunner] Reactivity disabled — rerunning entire script with updated widget state")
+            logger.info("[ScriptRunner] Reactivity disabled. Rerunning entire script with updated widget state")
             return await self.run_script()
 
         try:
@@ -171,7 +171,7 @@ async def rerun(self, new_widget_states: dict[str, Any] | None = None):
                     workflow.context.set_variable(producer_atom, new_value)
 
             if not changed_atoms and not affected_atoms:
-                logger.warning("[ScriptRunner] No atoms affected — falling back to full script rerun")
+                logger.warning("[ScriptRunner] No atoms affected. Falling back to full script rerun")
                 if logger.isEnabledFor(logging.DEBUG):
                     logger.debug(f"[ScriptRunner] changed_atoms = {changed_atoms}, component_ids = {changed_component_ids}")
 
@@ -324,6 +324,7 @@ async def run_script(self):
         # Ensure we run the script from a clear state
         workflow = self._service.get_workflow()
         workflow.reset()
+        self._service.clear_errors()
 
         logger.info(f"[ScriptRunner] Starting script execution {self.script_path=} {self._run_count=}")
 
@@ -355,16 +356,17 @@ def compile_and_run(src_code, script_path, script_globals, execution_context):
                         # Attempt reactive transformation
                         tree, _ = transform_source(raw_code, filename=self.script_path)
                         self._script_globals["workflow"] = workflow
-                        compile_and_run(tree, self.script_path, self._script_globals, "(reactive)")
-                        workflow.execute_relevant_atoms()
+                        if tree:
+                            compile_and_run(tree, self.script_path, self._script_globals, "(reactive)")
+                            workflow.execute_relevant_atoms()
                     else:
                         compile_and_run(raw_code, self.script_path, self._script_globals, "(non-reactive)")
                         workflow.reset() # just to be safe
 
                 except Exception as transform_error:
                     if logger.isEnabledFor(logging.WARNING):
                         logger.warning(
-                            "[ScriptRunner] AST transform or reactive execution failed — falling back to full script rerun\n%s",
+                            "[ScriptRunner] AST transform or reactive execution failed. Falling back to full script rerun\n%s",
                             traceback.format_exc()
                         )
 
@@ -376,8 +378,12 @@ def compile_and_run(src_code, script_path, script_globals, execution_context):
                         "workflow": workflow,
                         "widget_states": self.widget_states,
                     }
-
-                    compile_and_run(raw_code, self.script_path, self._script_globals, "(fallback, non-reactive)")
+                    try:
+                        compile_and_run(raw_code, self.script_path, self._script_globals, "(fallback, non-reactive)")
+                    except Exception as e:
+                        logger.error('[ScriptRunner] Full script rerun fallback failed', traceback.format_exc() );
+                        if not self._service.has_errors():
+                            raise e
 
                 os.chdir(current_working_dir)
 
@@ -400,8 +406,15 @@ def compile_and_run(src_code, script_path, script_globals, execution_context):
                         logger.warning(f"[ScriptRunner] No producer atom found {component_id=}")
                         continue
 
-            if components:
-                await self.send_message({"type": "components", "components": components})
+            errors = self._service.get_errors(type="ast_transform", filename=self.script_path)
+            message_type = "errors:result" if len(errors) else "components"
+
+            if (components and row_count) or len(errors):
+                await self.send_message({
+                    "type": message_type,
+                    "errors": errors or [],
+                    "components": components or []
+                })
                 if logger.isEnabledFor(logging.DEBUG):
                     logger.debug(f"[ScriptRunner] Components sent to frontend {components=}")
             workflow.debug_print_dag()
diff --git a/preswald/engine/transformers/reactive_runtime.py b/preswald/engine/transformers/reactive_runtime.py
diff --git a/preswald/interfaces/render/error_registry.py b/preswald/interfaces/render/error_registry.py
diff --git a/preswald/interfaces/render/registry.py b/preswald/interfaces/render/registry.py
