@pennyfarthing/core 11.4.0 → 12.0.0

package/packages/core/src/public/hooks/useDataSource.ts

@@ -0,0 +1,273 @@
+/**
+ * useDataSource<T> — Generic React hook for WebSocket-based DataSource<T>.
+ *
+ * Story 124-3: Replaces direct WebSocket boilerplate in panel hooks.
+ * Handles connection lifecycle, reconnection, message parsing, and cleanup.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export interface UseDataSourceOptions<R, T> {
+  /** WebSocket endpoint path, e.g. '/ws/sprint' */
+  endpoint: string;
+  /** Transform raw message to typed data */
+  transform?: (raw: R) => T;
+  /** Merge partial updates with existing data */
+  merge?: (prev: T | null, update: T) => T;
+  /** Message types to accept (default: ['init', 'update']) */
+  acceptTypes?: string[];
+  /** Reconnect delay in ms (default: 2000) */
+  reconnectMs?: number;
+}
+
+export interface UseDataSourceResult<T> {
+  data: T | null;
+  isLoading: boolean;
+  error: Error | null;
+  /** Send a message to the WebSocket (for bidirectional DataSource communication) */
+  send: (message: unknown) => void;
+}
+
+/**
+ * Generic hook wrapping the DataSource<T> pattern for WebSocket endpoints.
+ * All WebSocket panel hooks should use this instead of raw WebSocket.
+ */
+export function useDataSource<R = unknown, T = R>(
+  options: UseDataSourceOptions<R, T>
+): UseDataSourceResult<T> {
+  const { endpoint, transform, merge, reconnectMs = 2000 } = options;
+  const acceptTypes = options.acceptTypes ?? ['init', 'update'];
+
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+  const isMountedRef = useRef(true);
+
+  const send = useCallback((message: unknown) => {
+    if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
+      wsRef.current.send(JSON.stringify(message));
+    }
+  }, []);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${window.location.host}${endpoint}`;
+
+    const connect = () => {
+      if (!isMountedRef.current) return;
+
+      try {
+        wsRef.current = new WebSocket(wsUrl);
+
+        wsRef.current.onmessage = (event) => {
+          try {
+            const raw = JSON.parse(event.data);
+            if (raw.type && acceptTypes.includes(raw.type)) {
+              const transformed = transform ? transform(raw) : (raw as unknown as T);
+              setData((prev) => merge ? merge(prev, transformed) : transformed);
+              setIsLoading(false);
+              setError(null);
+            }
+          } catch (err) {
+            console.error(`[useDataSource ${endpoint}] Parse error:`, err);
+          }
+        };
+
+        wsRef.current.onclose = () => {
+          if (isMountedRef.current) {
+            reconnectTimeoutRef.current = setTimeout(connect, reconnectMs);
+          }
+        };
+
+        wsRef.current.onerror = () => {
+          setError(new Error('WebSocket connection failed'));
+        };
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error('Failed to connect'));
+        setIsLoading(false);
+      }
+    };
+
+    connect();
+
+    return () => {
+      isMountedRef.current = false;
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, [endpoint]);
+
+  return { data, isLoading, error, send };
+}
+
+/**
+ * useRestDataSource<T> — Generic hook for REST/fetch-based DataSource<T>.
+ *
+ * Replaces direct fetch boilerplate in panel hooks.
+ */
+export interface UseRestDataSourceOptions {
+  /** REST endpoint path, e.g. '/api/code-markers' */
+  endpoint: string;
+  /** Query parameters */
+  params?: Record<string, string>;
+  /** Whether to auto-fetch on mount (default: true) */
+  autoFetch?: boolean;
+}
+
+export interface UseRestDataSourceResult<T> {
+  data: T | null;
+  isLoading: boolean;
+  error: Error | null;
+  /** Manually trigger a fetch */
+  refresh: () => void;
+}
+
+/**
+ * Generic hook wrapping the DataSource<T> pattern for REST endpoints.
+ * All fetch-based panel hooks should use this instead of raw fetch.
+ */
+export function useRestDataSource<T>(
+  options: UseRestDataSourceOptions
+): UseRestDataSourceResult<T> {
+  const { endpoint, params, autoFetch = true } = options;
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const refresh = useCallback(() => {
+    if (abortRef.current) abortRef.current.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setIsLoading(true);
+    setError(null);
+
+    let url = endpoint;
+    if (params && Object.keys(params).length > 0) {
+      url += `?${new URLSearchParams(params).toString()}`;
+    }
+
+    fetch(url, { signal: controller.signal })
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((json) => {
+        setData(json as T);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (err.name === 'AbortError') return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+  }, [endpoint, params ? JSON.stringify(params) : '']);
+
+  useEffect(() => {
+    if (autoFetch) refresh();
+    return () => {
+      if (abortRef.current) abortRef.current.abort();
+    };
+  }, [refresh]);
+
+  return { data, isLoading, error, refresh };
+}
+
+// =============================================================================
+// useRawDataSource — Low-level WebSocket DataSource for custom message handling
+// =============================================================================
+
+export interface UseRawDataSourceOptions {
+  /** WebSocket endpoint path */
+  endpoint: string;
+  /** Called with each parsed JSON message */
+  onMessage: (data: unknown) => void;
+  /** Called on WebSocket close */
+  onClose?: () => void;
+  /** Called on WebSocket error */
+  onError?: (error: Error) => void;
+  /** Reconnect delay in ms (default: 2000) */
+  reconnectMs?: number;
+}
+
+/**
+ * Low-level DataSource hook for WebSocket endpoints with custom message handling.
+ * Use this when useDataSource's transform/merge pattern is too constraining.
+ */
+export function useRawDataSource(options: UseRawDataSourceOptions): {
+  send: (message: unknown) => void;
+} {
+  const { endpoint, onMessage, onClose, onError, reconnectMs = 2000 } = options;
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+  const isMountedRef = useRef(true);
+  const onMessageRef = useRef(onMessage);
+  const onCloseRef = useRef(onClose);
+  const onErrorRef = useRef(onError);
+  onMessageRef.current = onMessage;
+  onCloseRef.current = onClose;
+  onErrorRef.current = onError;
+
+  const send = useCallback((message: unknown) => {
+    if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
+      wsRef.current.send(JSON.stringify(message));
+    }
+  }, []);
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${window.location.host}${endpoint}`;
+
+    const connect = () => {
+      if (!isMountedRef.current) return;
+
+      try {
+        wsRef.current = new WebSocket(wsUrl);
+
+        wsRef.current.onmessage = (event) => {
+          try {
+            const data = JSON.parse(event.data);
+            onMessageRef.current(data);
+          } catch (err) {
+            console.error(`[useRawDataSource ${endpoint}] Parse error:`, err);
+          }
+        };
+
+        wsRef.current.onclose = () => {
+          onCloseRef.current?.();
+          if (isMountedRef.current) {
+            reconnectTimeoutRef.current = setTimeout(connect, reconnectMs);
+          }
+        };
+
+        wsRef.current.onerror = () => {
+          onErrorRef.current?.(new Error('WebSocket connection failed'));
+        };
+      } catch {
+        // Connection failed
+      }
+    };
+
+    connect();
+
+    return () => {
+      isMountedRef.current = false;
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, [endpoint]);
+
+  return { send };
+}

package/packages/core/src/public/hooks/useDeadCode.ts

@@ -1,3 +1,4 @@
+// Story 124-3: REST-based DataSource<T> variant
 import { useState, useCallback, useRef, useEffect } from 'react';
 
 export interface StaleFile {

package/packages/core/src/public/hooks/useDependencies.ts

@@ -1,3 +1,4 @@
+// Story 124-3: REST-based DataSource<T> variant
 import { useState, useCallback, useRef, useEffect } from 'react';
 
 export interface OutdatedPackage {

package/packages/core/src/public/hooks/useDiffs.ts

@@ -1,14 +1,14 @@
 /**
  * useDiffs Hook
  *
- * React hook for subscribing to diff data via WebSocket.
+ * React hook for subscribing to diff data via DataSource.
  * Story MSSCI-12717 - React Migration
  * Story MSSCI-14238 - Git-based diffs (replaces OTEL-based extraction)
- *
- * IPC DEPRECATED - Now uses WebSocket /ws/diffs
+ * Story 124-3 - Refactored to use DataSource<T> pattern
  */
 
-import { useState, useEffect, useCallback, useRef } from 'react';
+import { useState, useCallback } from 'react';
+import { useRawDataSource } from './useDataSource.js';
 
 export interface DiffData {
   id?: string;
@@ -36,95 +36,53 @@ interface UseDiffsResult {
   clearDiffs: () => void;
 }
 
-const WS_RECONNECT_DELAY = 2000;
-
 export function useDiffs(): UseDiffsResult {
   const [diffs, setDiffs] = useState<DiffData[]>([]);
   const [selectedDiff, setSelectedDiff] = useState<DiffData | null>(null);
-  const wsRef = useRef<WebSocket | null>(null);
-
-  useEffect(() => {
-    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-    let mounted = true;
-
-    const connect = () => {
-      const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-      const ws = new WebSocket(`${protocol}//${window.location.host}/ws/diffs`);
-      wsRef.current = ws;
-
-      ws.onopen = () => {
-        console.log('[useDiffs] WebSocket connected');
-      };
-
-      ws.onmessage = (event) => {
-        try {
-          const data = JSON.parse(event.data);
-
-          if (data.type === 'init') {
-            // Initial load of existing diffs
-            const initialDiffs = (data.diffs || []) as DiffData[];
-            setDiffs(initialDiffs);
-            if (initialDiffs.length > 0) {
-              setSelectedDiff(initialDiffs[initialDiffs.length - 1]);
-            }
-          } else if (data.type === 'diff') {
-            // New diff arrived
-            const diffData = data.diff as DiffData;
-            setDiffs(prev => {
-              // Update or add diff
-              const existing = prev.findIndex(d => d.path === diffData.path);
-              if (existing >= 0) {
-                const updated = [...prev];
-                updated[existing] = diffData;
-                return updated;
-              }
-              return [...prev, diffData];
-            });
-            // Auto-select new diff
-            setSelectedDiff(diffData);
-          } else if (data.type === 'refresh') {
-            // Full refresh of diffs (MSSCI-14238: git cache refresh)
-            const refreshedDiffs = (data.diffs || []) as DiffData[];
-            setDiffs(refreshedDiffs);
-            // Keep current selection if it still exists
-            if (refreshedDiffs.length > 0) {
-              setSelectedDiff(prev => {
-                if (prev) {
-                  const stillExists = refreshedDiffs.find(d => d.path === prev.path);
-                  if (stillExists) return stillExists;
-                }
-                return refreshedDiffs[refreshedDiffs.length - 1];
-              });
-            } else {
-              setSelectedDiff(null);
-            }
-          }
-        } catch (err) {
-          console.error('[useDiffs] Failed to parse message:', err);
-        }
-      };
 
-      ws.onclose = () => {
-        if (mounted) {
-          reconnectTimer = setTimeout(connect, WS_RECONNECT_DELAY);
+  const handleMessage = useCallback((data: unknown) => {
+    const msg = data as { type: string; diffs?: DiffData[]; diff?: DiffData };
+
+    if (msg.type === 'init') {
+      const initialDiffs = msg.diffs || [];
+      setDiffs(initialDiffs);
+      if (initialDiffs.length > 0) {
+        setSelectedDiff(initialDiffs[initialDiffs.length - 1]);
+      }
+    } else if (msg.type === 'diff') {
+      const diffData = msg.diff as DiffData;
+      setDiffs(prev => {
+        const existing = prev.findIndex(d => d.path === diffData.path);
+        if (existing >= 0) {
+          const updated = [...prev];
+          updated[existing] = diffData;
+          return updated;
         }
-      };
-
-      ws.onerror = (err) => {
-        console.error('[useDiffs] WebSocket error:', err);
-        ws.close();
-      };
-    };
-
-    connect();
-
-    return () => {
-      mounted = false;
-      if (reconnectTimer) clearTimeout(reconnectTimer);
-      wsRef.current?.close();
-    };
+        return [...prev, diffData];
+      });
+      setSelectedDiff(diffData);
+    } else if (msg.type === 'refresh') {
+      const refreshedDiffs = msg.diffs || [];
+      setDiffs(refreshedDiffs);
+      if (refreshedDiffs.length > 0) {
+        setSelectedDiff(prev => {
+          if (prev) {
+            const stillExists = refreshedDiffs.find(d => d.path === prev.path);
+            if (stillExists) return stillExists;
+          }
+          return refreshedDiffs[refreshedDiffs.length - 1];
+        });
+      } else {
+        setSelectedDiff(null);
+      }
+    }
   }, []);
 
+  const { send } = useRawDataSource({
+    endpoint: '/ws/diffs',
+    onMessage: handleMessage,
+  });
+
   const selectDiff = useCallback((path: string) => {
     const diff = diffs.find(d => d.path === path);
     setSelectedDiff(diff || null);
@@ -133,11 +91,8 @@ export function useDiffs(): UseDiffsResult {
   const clearDiffs = useCallback(() => {
     setDiffs([]);
     setSelectedDiff(null);
-    // Send clear message to server
-    if (wsRef.current?.readyState === WebSocket.OPEN) {
-      wsRef.current.send(JSON.stringify({ type: 'clear' }));
-    }
-  }, []);
+    send({ type: 'clear' });
+  }, [send]);
 
   return { diffs, selectedDiff, selectDiff, clearDiffs };
 }

package/packages/core/src/public/hooks/useGitStatus.ts

@@ -6,11 +6,13 @@
  * Story MSSCI-12781 - Fixed to handle multi-repo response format
  * Story MSSCI-12798 - Expose full repo array for stacked display
  * Story MSSCI-12860 - IPC to WebSocket Migration (Phase 1)
+ * Story 124-3 - Refactored to use DataSource<T> pattern
  *
- * Uses WebSocket /ws/git for real-time updates (no polling).
+ * Uses DataSource via useDataSource for real-time updates (no polling).
  */
 
-import { useState, useEffect, useRef } from 'react';
+import { useState, useEffect } from 'react';
+import { useDataSource } from './useDataSource.js';
 
 export interface GitStatusData {
   branch: string;
@@ -71,23 +73,15 @@ function countFilesByType(dirtyFiles: DirtyFile[]): { staged: number; modified:
   let untracked = 0;
 
   for (const file of dirtyFiles) {
-    // Git status codes:
-    // First char = staging area, Second char = working tree
-    // M = modified, A = added (staged), D = deleted, ? = untracked
     const indexStatus = file.status[0] || ' ';
     const workTreeStatus = file.status[1] || ' ';
 
-    // Staged files (anything in the index that's not space or ?)
     if (indexStatus !== ' ' && indexStatus !== '?') {
       staged++;
     }
-
-    // Modified in working tree (not staged)
     if (workTreeStatus === 'M' || workTreeStatus === 'D') {
       modified++;
     }
-
-    // Untracked files
     if (indexStatus === '?' && workTreeStatus === '?') {
       untracked++;
     }
@@ -100,9 +94,7 @@ function countFilesByType(dirtyFiles: DirtyFile[]): { staged: number; modified:
  * Transform raw git response to per-repo status array for stacked display
  */
 function transformToRepoArray(repos: RepoGitInfo[]): RepoStatusData[] {
-  if (!repos?.length) {
-    return [];
-  }
+  if (!repos?.length) return [];
 
   return repos.map(repo => {
     const counts = countFilesByType(repo.dirtyFiles);
@@ -124,17 +116,11 @@ function transformToRepoArray(repos: RepoGitInfo[]): RepoStatusData[] {
 
 /**
  * Transform raw git response to GitStatusData for display (legacy aggregated view)
- * Uses first repo for branch info, aggregates file counts across all repos
  */
 function transformGitResponse(repos: RepoGitInfo[]): GitStatusData | null {
-  if (!repos?.length) {
-    return null;
-  }
+  if (!repos?.length) return null;
 
-  // Use first repo as primary (usually the orchestrator or main repo)
   const primaryRepo = repos[0];
-
-  // Count file types across all repos
   let staged = 0;
   let modified = 0;
   let untracked = 0;
@@ -146,7 +132,6 @@ function transformGitResponse(repos: RepoGitInfo[]): GitStatusData | null {
     untracked += counts.untracked;
   }
 
-  // Check if any repo is dirty
   const isDirty = repos.some(repo => !repo.clean);
 
   return {
@@ -170,64 +155,18 @@ interface UseGitStatusResult {
 export function useGitStatus(): UseGitStatusResult {
   const [gitStatus, setGitStatus] = useState<GitStatusData | null>(null);
   const [repos, setRepos] = useState<RepoStatusData[]>([]);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const wsRef = useRef<WebSocket | null>(null);
-  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
-
-  useEffect(() => {
-    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-    const wsUrl = `${protocol}//${window.location.host}/ws/git`;
-
-    const connect = () => {
-      try {
-        wsRef.current = new WebSocket(wsUrl);
-
-        wsRef.current.onopen = () => {
-          console.debug('[useGitStatus] WebSocket connected');
-        };
-
-        wsRef.current.onmessage = (event) => {
-          try {
-            const msg = JSON.parse(event.data) as GitMessage;
-            if (msg.type === 'init' || msg.type === 'update') {
-              setGitStatus(transformGitResponse(msg.repos));
-              setRepos(transformToRepoArray(msg.repos));
-              setIsLoading(false);
-              setError(null);
-            }
-          } catch (err) {
-            console.error('[useGitStatus] Failed to parse message:', err);
-          }
-        };
-
-        wsRef.current.onclose = () => {
-          console.debug('[useGitStatus] WebSocket closed, reconnecting...');
-          reconnectTimeoutRef.current = setTimeout(connect, 2000);
-        };
-
-        wsRef.current.onerror = (err) => {
-          console.error('[useGitStatus] WebSocket error:', err);
-          setError(new Error('WebSocket connection failed'));
-        };
-      } catch (err) {
-        console.error('[useGitStatus] WebSocket init failed:', err);
-        setError(err instanceof Error ? err : new Error('Failed to connect'));
-        setIsLoading(false);
-      }
-    };
 
-    connect();
+  const { data, isLoading, error } = useDataSource<GitMessage, RepoGitInfo[]>({
+    endpoint: '/ws/git',
+    transform: (msg) => msg.repos,
+  });
 
-    return () => {
-      if (reconnectTimeoutRef.current) {
-        clearTimeout(reconnectTimeoutRef.current);
-      }
-      if (wsRef.current) {
-        wsRef.current.close();
-      }
-    };
-  }, []);
+  useEffect(() => {
+    if (data) {
+      setGitStatus(transformGitResponse(data));
+      setRepos(transformToRepoArray(data));
+    }
+  }, [data]);
 
   return { gitStatus, repos, isLoading, error };
 }

package/packages/core/src/public/hooks/useHealthScore.ts

@@ -1,3 +1,4 @@
+// Story 124-3: REST-based DataSource<T> variant
 import { useState, useCallback, useRef, useEffect } from 'react';
 
 export interface HealthScoreDimension {

package/packages/core/src/public/hooks/useHotspots.ts

@@ -1,3 +1,4 @@
+// Story 124-3: REST-based DataSource<T> variant
 import { useState, useCallback, useRef, useEffect } from 'react';
 
 // Types matching Python HotspotResult / MultiRepoHotspotResult