@thehoneyjar/sigil-diagnostics 0.1.0

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @sigil/diagnostics
+ *
+ * Physics compliance checking and issue detection for Sigil.
+ */
+
+// Types
+export type {
+  EffectType,
+  Severity,
+  PatternCategory,
+  DiagnosticIssue,
+  BehavioralCompliance,
+  AnimationCompliance,
+  MaterialCompliance,
+  ComplianceResult,
+  DiagnosticResult,
+  PatternCause,
+  DiagnosticPattern,
+  PatternMatchResult,
+  DiagnosticsConfig,
+  DiagnosticsService,
+} from './types'
+
+export { DiagnosticsError, DiagnosticsErrorCodes } from './types'
+
+// Detection
+export { detectEffect, getExpectedPhysics, keywords } from './detection'
+
+// Compliance
+export {
+  checkBehavioralCompliance,
+  checkAnimationCompliance,
+  checkMaterialCompliance,
+  checkCompliance,
+  complianceToIssues,
+  isFullyCompliant,
+} from './compliance'
+
+// Patterns
+export { PATTERNS, getPatterns, getPatternsByCategory, getPatternById } from './patterns'
+
+// Service
+export {
+  createDiagnosticsService,
+  getDiagnosticsService,
+  resetDiagnosticsService,
+} from './service'

package/src/patterns.ts

@@ -0,0 +1,327 @@
+/**
+ * Known Diagnostic Patterns
+ *
+ * Patterns for detecting common issues in React/Next.js applications.
+ */
+
+import type { DiagnosticPattern } from './types'
+
+/**
+ * Built-in diagnostic patterns
+ */
+export const PATTERNS: DiagnosticPattern[] = [
+  // Hydration Issues
+  {
+    id: 'hydration-media-query',
+    name: 'useMediaQuery Hydration Mismatch',
+    category: 'hydration',
+    severity: 'error',
+    symptoms: [
+      'Text content does not match server-rendered HTML',
+      'Hydration failed because the initial UI does not match',
+      'Component flickers on load',
+      'Different content on refresh vs navigation',
+    ],
+    keywords: ['hydration', 'flicker', 'mismatch', 'ssr', 'server'],
+    causes: [
+      {
+        name: 'useMediaQuery SSR mismatch',
+        signature: 'useMediaQuery returns false on server, true on client',
+        codeSmell: `const isDesktop = useMediaQuery("(min-width: 768px)");
+return isDesktop ? <Dialog /> : <Drawer />;`,
+        solution: `// Option 1: Loading state until mounted
+const [mounted, setMounted] = useState(false);
+useEffect(() => setMounted(true), []);
+if (!mounted) return <Skeleton />;
+
+// Option 2: CSS-only responsive
+<div className="hidden md:block"><Dialog /></div>
+<div className="md:hidden"><Drawer /></div>`,
+      },
+      {
+        name: 'Date/time in render',
+        signature: 'new Date() in render path',
+        codeSmell: `return <span>{new Date().toLocaleString()}</span>`,
+        solution: `const [time, setTime] = useState<string | null>(null);
+useEffect(() => {
+  setTime(new Date().toLocaleString());
+}, []);
+return <span>{time ?? 'Loading...'}</span>;`,
+      },
+      {
+        name: 'Random values in render',
+        signature: 'Math.random() or crypto.randomUUID() in render',
+        solution: `// Use useId() for stable IDs
+const id = useId();
+
+// Or generate once
+const [randomId] = useState(() => crypto.randomUUID());`,
+      },
+    ],
+  },
+
+  // Dialog Issues
+  {
+    id: 'dialog-instability',
+    name: 'Dialog/Modal Instability',
+    category: 'dialog',
+    severity: 'error',
+    symptoms: [
+      "Dialog doesn't open reliably",
+      'Visual glitch during open/close',
+      'Works on desktop, fails on mobile',
+      'Absolute positioned elements misaligned',
+      'Content jumps or shifts',
+    ],
+    keywords: ['dialog', 'modal', 'drawer', 'glitch', 'popup', 'open', 'close'],
+    causes: [
+      {
+        name: 'ResponsiveDialog hydration',
+        signature: 'useMediaQuery controlling Dialog vs Drawer',
+        solution: `// Option 1: CSS container queries
+.dialog-content {
+  @container (min-width: 768px) {
+    /* desktop styles */
+  }
+}
+
+// Option 2: Consistent loading state
+if (!mounted) return <DialogSkeleton />;`,
+      },
+      {
+        name: 'Absolute positioning context mismatch',
+        signature: 'absolute positioning with varying parent chains',
+        codeSmell: `<div className="absolute -top-4">Title</div>`,
+        solution: `// Ensure explicit positioning context
+<div className="relative">
+  <div className="absolute -top-4">Title</div>
+</div>`,
+      },
+      {
+        name: 'CSS overflow conflicts',
+        signature: 'overflow-auto on parent, overflow-visible on child',
+        solution: `// Be explicit at each level
+// Or restructure to avoid conflict
+// Or use style prop for explicit control`,
+      },
+    ],
+  },
+
+  // Performance Issues
+  {
+    id: 'render-performance',
+    name: 'Render Performance Issues',
+    category: 'performance',
+    severity: 'warning',
+    symptoms: [
+      'Laggy interactions',
+      'Delayed response to clicks',
+      'Janky animations',
+      'UI feels heavy',
+      'High INP',
+    ],
+    keywords: ['slow', 'laggy', 'janky', 'performance', 'heavy', 'delay'],
+    causes: [
+      {
+        name: 'Unnecessary re-renders',
+        signature: 'Large component tree re-rendering on state change',
+        solution: `// Memoize expensive children
+const MemoizedChild = memo(Child);
+
+// Colocate state (move it down)
+// Use useMemo for expensive computations
+const processed = useMemo(() => expensiveWork(data), [data]);`,
+      },
+      {
+        name: 'Layout thrashing',
+        signature: 'Reading layout, writing, reading again',
+        solution: `// Batch reads, then batch writes
+// Use requestAnimationFrame
+// Use CSS transforms instead of top/left`,
+      },
+    ],
+  },
+
+  // Layout Shift
+  {
+    id: 'layout-shift',
+    name: 'Cumulative Layout Shift (CLS)',
+    category: 'layout',
+    severity: 'warning',
+    symptoms: [
+      'Content jumps after load',
+      'Buttons move as clicking',
+      'High CLS score',
+      'Page is jumpy',
+    ],
+    keywords: ['jump', 'shift', 'cls', 'move', 'jumpy'],
+    causes: [
+      {
+        name: 'Images without dimensions',
+        signature: '<img> without width/height',
+        solution: `<Image
+  src={src}
+  width={400}
+  height={300}
+  alt="..."
+/>
+
+// Or use aspect-ratio
+<div className="aspect-video">
+  <img className="object-cover" />
+</div>`,
+      },
+      {
+        name: 'Dynamic content without placeholder',
+        signature: 'Content loads and pushes things down',
+        solution: `// Reserve space
+<div className="min-h-[200px]">
+  {loading ? <Skeleton /> : <Content />}
+</div>`,
+      },
+    ],
+  },
+
+  // Server Components
+  {
+    id: 'server-component-error',
+    name: 'Server Component Errors',
+    category: 'server-component',
+    severity: 'error',
+    symptoms: [
+      'useState is not a function',
+      'useEffect is not a function',
+      'Cannot use hooks in Server Component',
+      'Event handlers cannot be passed',
+    ],
+    keywords: ['server', 'component', 'hook', 'usestate', 'useeffect', 'client'],
+    causes: [
+      {
+        name: 'Hooks in Server Component',
+        signature: 'useState/useEffect without "use client"',
+        solution: `// Add at top of file
+'use client';
+
+// Or extract to Client Component`,
+      },
+    ],
+  },
+
+  // React 19
+  {
+    id: 'react-19-changes',
+    name: 'React 19 Breaking Changes',
+    category: 'react-19',
+    severity: 'warning',
+    symptoms: ['forwardRef is deprecated', 'Unexpected behavior after upgrade'],
+    keywords: ['react 19', 'forwardref', 'upgrade', 'deprecated'],
+    causes: [
+      {
+        name: 'forwardRef deprecated',
+        signature: 'Using forwardRef pattern',
+        codeSmell: `const Button = forwardRef((props, ref) => ...);`,
+        solution: `// ref is now a regular prop
+function Button({ ref, ...props }) {
+  return <button ref={ref} {...props} />;
+}`,
+      },
+    ],
+  },
+
+  // Physics Compliance
+  {
+    id: 'physics-financial-optimistic',
+    name: 'Financial Action Using Optimistic Sync',
+    category: 'physics',
+    severity: 'error',
+    symptoms: [
+      'Financial action uses optimistic update',
+      'Money operation without confirmation',
+      'Transaction rolls back after user sees success',
+    ],
+    keywords: [
+      'claim',
+      'deposit',
+      'withdraw',
+      'transfer',
+      'swap',
+      'optimistic',
+    ],
+    causes: [
+      {
+        name: 'Optimistic update on financial mutation',
+        signature: 'onMutate used for financial operations',
+        codeSmell: `useMutation({
+  mutationFn: claimRewards,
+  onMutate: async () => {
+    // Optimistic update - WRONG for financial!
+    queryClient.setQueryData(['balance'], newBalance)
+  }
+})`,
+        solution: `// Use pessimistic sync for financial operations
+useMutation({
+  mutationFn: claimRewards,
+  // NO onMutate - wait for server confirmation
+  onSuccess: () => {
+    queryClient.invalidateQueries(['balance'])
+  }
+})`,
+      },
+    ],
+  },
+
+  {
+    id: 'physics-destructive-no-confirm',
+    name: 'Destructive Action Without Confirmation',
+    category: 'physics',
+    severity: 'error',
+    symptoms: [
+      'Delete button with no confirmation',
+      'Permanent action happens immediately',
+      'No way to undo destructive operation',
+    ],
+    keywords: ['delete', 'remove', 'destroy', 'revoke', 'terminate'],
+    causes: [
+      {
+        name: 'Missing confirmation for destructive action',
+        signature: 'Destructive action without confirmation step',
+        codeSmell: `<button onClick={() => deleteItem()}>Delete</button>`,
+        solution: `// Add confirmation step
+const [showConfirm, setShowConfirm] = useState(false);
+
+return showConfirm ? (
+  <ConfirmDialog
+    message="Are you sure you want to delete?"
+    onConfirm={() => deleteItem()}
+    onCancel={() => setShowConfirm(false)}
+  />
+) : (
+  <button onClick={() => setShowConfirm(true)}>Delete</button>
+);`,
+      },
+    ],
+  },
+]
+
+/**
+ * Get all patterns
+ */
+export function getPatterns(): DiagnosticPattern[] {
+  return PATTERNS
+}
+
+/**
+ * Get patterns by category
+ */
+export function getPatternsByCategory(
+  category: DiagnosticPattern['category']
+): DiagnosticPattern[] {
+  return PATTERNS.filter((p) => p.category === category)
+}
+
+/**
+ * Get pattern by ID
+ */
+export function getPatternById(id: string): DiagnosticPattern | undefined {
+  return PATTERNS.find((p) => p.id === id)
+}

package/src/service.ts

@@ -0,0 +1,330 @@
+/**
+ * Diagnostics Service
+ *
+ * Main service for physics compliance checking and issue detection.
+ */
+
+import type {
+  DiagnosticsService,
+  DiagnosticsConfig,
+  DiagnosticResult,
+  EffectType,
+  ComplianceResult,
+  PatternMatchResult,
+  DiagnosticsError,
+} from './types'
+import { DiagnosticsErrorCodes } from './types'
+import { detectEffect, getExpectedPhysics } from './detection'
+import {
+  checkCompliance,
+  complianceToIssues,
+  isFullyCompliant,
+} from './compliance'
+import { PATTERNS, getPatternById } from './patterns'
+
+/**
+ * Default compliance result for when physics aren't specified
+ */
+function createDefaultCompliance(effect: EffectType): ComplianceResult {
+  const behavioral = getExpectedPhysics(effect)
+  return {
+    behavioral: {
+      ...behavioral,
+      compliant: true,
+    },
+    animation: {
+      easing: 'ease-out',
+      duration: behavioral.timing,
+      compliant: true,
+    },
+    material: {
+      surface: 'elevated',
+      shadow: 'soft',
+      compliant: true,
+    },
+  }
+}
+
+/**
+ * Create a diagnostics service
+ */
+export function createDiagnosticsService(
+  anchorClient?: unknown,
+  config: DiagnosticsConfig = {}
+): DiagnosticsService {
+  const patterns = [...PATTERNS, ...(config.customPatterns ?? [])]
+
+  return {
+    async analyze(component: string, code?: string): Promise<DiagnosticResult> {
+      // Extract keywords from component name and code
+      const keywords = extractKeywords(component, code)
+
+      // Detect effect type
+      const effect = detectEffect(keywords)
+
+      // Get expected physics for this effect
+      const expectedPhysics = getExpectedPhysics(effect)
+
+      // Check compliance (if code is provided, we could parse it for actual values)
+      // For now, we'll use defaults
+      const compliance = createDefaultCompliance(effect)
+
+      // Generate issues from compliance
+      const issues = complianceToIssues(compliance)
+
+      // Match against known patterns if code is provided
+      if (code) {
+        const patternIssues = matchCodePatterns(code, patterns)
+        issues.push(...patternIssues)
+      }
+
+      // Generate suggestions based on effect type
+      const suggestions = generateSuggestions(effect, compliance)
+
+      return {
+        component,
+        effect,
+        issues,
+        compliance,
+        suggestions,
+      }
+    },
+
+    checkCompliance(
+      effect: EffectType,
+      physics: Partial<ComplianceResult>
+    ): boolean {
+      const result = checkCompliance(effect, physics)
+      return isFullyCompliant(result)
+    },
+
+    detectEffect(keywords: string[], types?: string[]): EffectType {
+      return detectEffect(keywords, types)
+    },
+
+    matchPatterns(symptoms: string): PatternMatchResult[] {
+      const results: PatternMatchResult[] = []
+      const lowerSymptoms = symptoms.toLowerCase()
+
+      for (const pattern of patterns) {
+        // Filter by category if specified
+        if (config.categories && !config.categories.includes(pattern.category)) {
+          continue
+        }
+
+        // Check keywords
+        const keywordMatches = pattern.keywords.filter((k) =>
+          lowerSymptoms.includes(k.toLowerCase())
+        )
+
+        if (keywordMatches.length === 0) continue
+
+        // Check symptoms
+        const symptomMatches = pattern.symptoms.filter(
+          (s) =>
+            lowerSymptoms.includes(s.toLowerCase()) ||
+            s
+              .toLowerCase()
+              .split(' ')
+              .some((word) => lowerSymptoms.includes(word))
+        )
+
+        // Calculate confidence
+        const confidence = Math.min(
+          0.95,
+          keywordMatches.length * 0.2 + symptomMatches.length * 0.3
+        )
+
+        if (confidence > 0.3) {
+          // Pick most likely cause
+          const matchedCause = pattern.causes[0]
+
+          results.push({
+            pattern,
+            matchedCause,
+            confidence,
+          })
+        }
+      }
+
+      // Sort by confidence
+      return results.sort((a, b) => b.confidence - a.confidence)
+    },
+
+    diagnose(symptom: string): string {
+      const results = this.matchPatterns(symptom)
+
+      if (results.length === 0) {
+        return "I couldn't match this to a known pattern. Can you describe what's happening in more detail?"
+      }
+
+      const top = results[0]
+      let response = `**Found: ${top.pattern.name}** (${Math.round(top.confidence * 100)}% confidence)\n\n`
+      response += `**Cause:** ${top.matchedCause.name}\n\n`
+
+      if (top.matchedCause.codeSmell) {
+        response += `**Code smell:**\n\`\`\`typescript\n${top.matchedCause.codeSmell}\n\`\`\`\n\n`
+      }
+
+      response += `**Solution:**\n\`\`\`typescript\n${top.matchedCause.solution}\n\`\`\``
+
+      return response.trim()
+    },
+  }
+}
+
+/**
+ * Extract keywords from component name and code
+ */
+function extractKeywords(component: string, code?: string): string[] {
+  const keywords: string[] = []
+
+  // Split component name into words
+  const componentWords = component
+    .replace(/([A-Z])/g, ' $1')
+    .toLowerCase()
+    .split(/[\s_-]+/)
+    .filter(Boolean)
+  keywords.push(...componentWords)
+
+  // Extract keywords from code if provided
+  if (code) {
+    // Look for common patterns
+    const patterns = [
+      /onClick\s*=\s*\{.*?(delete|remove|save|submit|claim|withdraw)/gi,
+      /mutation[Ff]n:\s*.*?(delete|remove|save|submit|claim|withdraw)/gi,
+      /useMutation.*?(delete|remove|save|submit|claim|withdraw)/gi,
+    ]
+
+    for (const pattern of patterns) {
+      const matches = code.match(pattern)
+      if (matches) {
+        keywords.push(...matches)
+      }
+    }
+  }
+
+  return keywords
+}
+
+/**
+ * Match code against known patterns
+ */
+function matchCodePatterns(
+  code: string,
+  patterns: typeof PATTERNS
+): import('./types').DiagnosticIssue[] {
+  const issues: import('./types').DiagnosticIssue[] = []
+
+  // Check for optimistic update on financial operations
+  if (
+    code.includes('onMutate') &&
+    (code.includes('claim') ||
+      code.includes('withdraw') ||
+      code.includes('transfer'))
+  ) {
+    issues.push({
+      severity: 'error',
+      code: 'FINANCIAL_OPTIMISTIC',
+      message:
+        'Detected optimistic update (onMutate) on financial operation. Financial operations should use pessimistic sync.',
+      suggestion:
+        'Remove onMutate and use onSuccess with query invalidation instead.',
+    })
+  }
+
+  // Check for delete without confirmation
+  if (
+    code.includes('delete') &&
+    !code.includes('confirm') &&
+    !code.includes('showConfirm')
+  ) {
+    const hasDirectDelete =
+      /onClick\s*=\s*\{.*?delete/i.test(code) ||
+      /<button[^>]*>.*?[Dd]elete.*?<\/button>/i.test(code)
+
+    if (hasDirectDelete) {
+      issues.push({
+        severity: 'warning',
+        code: 'DESTRUCTIVE_NO_CONFIRM',
+        message:
+          'Delete operation appears to have no confirmation step. Destructive actions should require confirmation.',
+        suggestion:
+          'Add a confirmation dialog before executing the delete operation.',
+      })
+    }
+  }
+
+  // Check for useMediaQuery without mount check
+  if (code.includes('useMediaQuery') && !code.includes('mounted')) {
+    issues.push({
+      severity: 'warning',
+      code: 'HYDRATION_MEDIA_QUERY',
+      message:
+        'useMediaQuery without mount check may cause hydration mismatch.',
+      suggestion:
+        'Add a mounted state check: const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []);',
+    })
+  }
+
+  return issues
+}
+
+/**
+ * Generate suggestions based on effect type and compliance
+ */
+function generateSuggestions(
+  effect: EffectType,
+  compliance: ComplianceResult
+): string[] {
+  const suggestions: string[] = []
+
+  if (effect === 'financial') {
+    suggestions.push('Use pessimistic sync - no onMutate for financial operations')
+    suggestions.push('Show amount and confirmation before executing')
+    suggestions.push('Invalidate queries on success to refresh balances')
+  }
+
+  if (effect === 'destructive') {
+    suggestions.push('Add two-step confirmation before destructive actions')
+    suggestions.push('Use 600ms timing for deliberate feel')
+    suggestions.push('Provide clear description of what will be deleted')
+  }
+
+  if (effect === 'soft-delete') {
+    suggestions.push('Use toast with undo action instead of confirmation dialog')
+    suggestions.push('Optimistic update is safe since operation is reversible')
+  }
+
+  if (!compliance.behavioral.compliant) {
+    suggestions.push(
+      `Consider changing sync to ${compliance.behavioral.sync} for ${effect} operations`
+    )
+  }
+
+  return suggestions
+}
+
+/**
+ * Default diagnostics service singleton
+ */
+let defaultDiagnosticsService: DiagnosticsService | null = null
+
+/**
+ * Get the default diagnostics service
+ */
+export function getDiagnosticsService(
+  anchorClient?: unknown
+): DiagnosticsService {
+  if (!defaultDiagnosticsService) {
+    defaultDiagnosticsService = createDiagnosticsService(anchorClient)
+  }
+  return defaultDiagnosticsService
+}
+
+/**
+ * Reset the default diagnostics service
+ */
+export function resetDiagnosticsService(): void {
+  defaultDiagnosticsService = null
+}