@thehoneyjar/sigil-diagnostics 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# @sigil/diagnostics
+
+Physics compliance checking and issue detection for Sigil.
+
+## Installation
+
+```bash
+pnpm add @sigil/diagnostics
+```
+
+## Usage
+
+### Quick Diagnosis
+
+```typescript
+import { createDiagnosticsService } from '@sigil/diagnostics'
+
+const diagnosticsService = createDiagnosticsService()
+
+// Diagnose a symptom
+const diagnosis = diagnosticsService.diagnose('dialog flickers on open')
+console.log(diagnosis)
+// **Found: Dialog/Modal Instability** (70% confidence)
+// **Cause:** ResponsiveDialog hydration
+// ...
+```
+
+### Effect Detection
+
+```typescript
+import { detectEffect, getExpectedPhysics } from '@sigil/diagnostics'
+
+// Detect effect from keywords
+const effect = detectEffect(['claim', 'button'])
+console.log(effect) // 'financial'
+
+// Get expected physics for effect
+const physics = getExpectedPhysics('financial')
+console.log(physics)
+// { sync: 'pessimistic', timing: 800, confirmation: true }
+```
+
+### Compliance Checking
+
+```typescript
+import { checkCompliance, isFullyCompliant } from '@sigil/diagnostics'
+
+const compliance = checkCompliance('financial', {
+  behavioral: {
+    sync: 'optimistic', // Wrong! Should be pessimistic
+    timing: 200,
+    confirmation: false,
+  },
+})
+
+console.log(isFullyCompliant(compliance)) // false
+console.log(compliance.behavioral.reason)
+// 'sync should be pessimistic, got optimistic; ...'
+```
+
+### Pattern Matching
+
+```typescript
+import { createDiagnosticsService } from '@sigil/diagnostics'
+
+const diagnosticsService = createDiagnosticsService()
+
+// Match symptoms to patterns
+const matches = diagnosticsService.matchPatterns('hydration mismatch flicker')
+
+for (const match of matches) {
+  console.log(`${match.pattern.name}: ${match.confidence * 100}%`)
+  console.log(match.matchedCause.solution)
+}
+```
+
+## API
+
+### Service
+
+| Method | Description |
+|--------|-------------|
+| `analyze(component, code?)` | Analyze component for issues |
+| `checkCompliance(effect, physics)` | Check physics compliance |
+| `detectEffect(keywords, types?)` | Detect effect type |
+| `matchPatterns(symptoms)` | Match symptoms to patterns |
+| `diagnose(symptom)` | Get quick diagnosis |
+
+### Detection
+
+| Function | Description |
+|----------|-------------|
+| `detectEffect(keywords, types?)` | Detect effect from keywords/types |
+| `getExpectedPhysics(effect)` | Get expected physics for effect |
+
+### Compliance
+
+| Function | Description |
+|----------|-------------|
+| `checkBehavioralCompliance(effect, actual)` | Check behavioral physics |
+| `checkAnimationCompliance(effect, actual)` | Check animation physics |
+| `checkMaterialCompliance(effect, actual)` | Check material physics |
+| `checkCompliance(effect, physics)` | Check all physics |
+| `isFullyCompliant(compliance)` | Check if fully compliant |
+
+### Patterns
+
+| Function | Description |
+|----------|-------------|
+| `PATTERNS` | Array of all diagnostic patterns |
+| `getPatterns()` | Get all patterns |
+| `getPatternsByCategory(category)` | Get patterns by category |
+| `getPatternById(id)` | Get pattern by ID |
+
+## Built-in Patterns
+
+- `hydration-media-query` - useMediaQuery hydration mismatch
+- `dialog-instability` - Dialog/modal glitches
+- `render-performance` - Performance issues
+- `layout-shift` - CLS issues
+- `server-component-error` - Server component hook errors
+- `react-19-changes` - React 19 breaking changes
+- `physics-financial-optimistic` - Financial with wrong sync
+- `physics-destructive-no-confirm` - Destructive without confirm
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+/**
+ * @sigil/diagnostics
+ *
+ * Types for physics compliance checking and issue detection.
+ */
+/**
+ * Effect types that determine physics behavior
+ */
+type EffectType = 'financial' | 'destructive' | 'soft-delete' | 'standard' | 'local' | 'navigation' | 'query';
+/**
+ * Issue severity levels
+ */
+type Severity = 'error' | 'warning' | 'info';
+/**
+ * Pattern categories for diagnostics
+ */
+type PatternCategory = 'hydration' | 'dialog' | 'performance' | 'layout' | 'server-component' | 'react-19' | 'physics';
+/**
+ * A diagnostic issue found during analysis
+ */
+interface DiagnosticIssue {
+    /** Severity level */
+    severity: Severity;
+    /** Unique code for this issue type */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Source location if available */
+    location?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+    /** Suggested fix */
+    suggestion?: string;
+}
+/**
+ * Behavioral physics compliance check result
+ */
+interface BehavioralCompliance {
+    /** Sync strategy: optimistic, pessimistic, or immediate */
+    sync: 'optimistic' | 'pessimistic' | 'immediate';
+    /** Expected timing in ms */
+    timing: number;
+    /** Whether confirmation is required */
+    confirmation: boolean;
+    /** Whether current implementation is compliant */
+    compliant: boolean;
+    /** Reason for non-compliance */
+    reason?: string;
+}
+/**
+ * Animation physics compliance check result
+ */
+interface AnimationCompliance {
+    /** Easing function used */
+    easing: string;
+    /** Duration in ms */
+    duration: number;
+    /** Whether current implementation is compliant */
+    compliant: boolean;
+    /** Reason for non-compliance */
+    reason?: string;
+}
+/**
+ * Material physics compliance check result
+ */
+interface MaterialCompliance {
+    /** Surface type */
+    surface: string;
+    /** Shadow style */
+    shadow: string;
+    /** Border radius */
+    radius?: string;
+    /** Whether current implementation is compliant */
+    compliant: boolean;
+    /** Reason for non-compliance */
+    reason?: string;
+}
+/**
+ * Complete compliance result across all physics layers
+ */
+interface ComplianceResult {
+    /** Behavioral physics compliance */
+    behavioral: BehavioralCompliance;
+    /** Animation physics compliance */
+    animation: AnimationCompliance;
+    /** Material physics compliance */
+    material: MaterialCompliance;
+}
+/**
+ * Full diagnostic result for a component
+ */
+interface DiagnosticResult {
+    /** Component name or identifier */
+    component: string;
+    /** Detected effect type */
+    effect: EffectType;
+    /** Issues found during analysis */
+    issues: DiagnosticIssue[];
+    /** Physics compliance results */
+    compliance: ComplianceResult;
+    /** Improvement suggestions */
+    suggestions: string[];
+}
+/**
+ * Pattern cause for matching symptoms
+ */
+interface PatternCause {
+    /** Cause name */
+    name: string;
+    /** Signature/pattern to look for */
+    signature: string;
+    /** Example of problematic code */
+    codeSmell?: string;
+    /** Solution code or explanation */
+    solution: string;
+}
+/**
+ * Diagnostic pattern for matching known issues
+ */
+interface DiagnosticPattern {
+    /** Unique pattern ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Category of issue */
+    category: PatternCategory;
+    /** Severity level */
+    severity: Severity;
+    /** Symptoms that indicate this pattern */
+    symptoms: string[];
+    /** Keywords to match against */
+    keywords: string[];
+    /** Possible causes and solutions */
+    causes: PatternCause[];
+}
+/**
+ * Result of pattern matching
+ */
+interface PatternMatchResult {
+    /** Matched pattern */
+    pattern: DiagnosticPattern;
+    /** Most likely cause */
+    matchedCause: PatternCause;
+    /** Confidence score 0-1 */
+    confidence: number;
+}
+/**
+ * Configuration for the diagnostics service
+ */
+interface DiagnosticsConfig {
+    /** Enable strict mode (more warnings) */
+    strict?: boolean;
+    /** Custom patterns to include */
+    customPatterns?: DiagnosticPattern[];
+    /** Pattern categories to check */
+    categories?: PatternCategory[];
+}
+/**
+ * Diagnostics service interface
+ */
+interface DiagnosticsService {
+    /**
+     * Analyze a component for physics compliance and issues
+     */
+    analyze(component: string, code?: string): Promise<DiagnosticResult>;
+    /**
+     * Check if physics settings comply with effect type
+     */
+    checkCompliance(effect: EffectType, physics: Partial<ComplianceResult>): boolean;
+    /**
+     * Detect effect type from keywords and types
+     */
+    detectEffect(keywords: string[], types?: string[]): EffectType;
+    /**
+     * Match symptoms to known patterns
+     */
+    matchPatterns(symptoms: string): PatternMatchResult[];
+    /**
+     * Get quick diagnosis from symptom description
+     */
+    diagnose(symptom: string): string;
+}
+/**
+ * Error codes for diagnostics package
+ */
+declare const DiagnosticsErrorCodes: {
+    readonly ANALYSIS_FAILED: "ANALYSIS_FAILED";
+    readonly PATTERN_NOT_FOUND: "PATTERN_NOT_FOUND";
+    readonly INVALID_EFFECT: "INVALID_EFFECT";
+    readonly ANCHOR_NOT_AVAILABLE: "ANCHOR_NOT_AVAILABLE";
+};
+/**
+ * Diagnostics error class
+ */
+declare class DiagnosticsError extends Error {
+    code: keyof typeof DiagnosticsErrorCodes;
+    recoverable: boolean;
+    constructor(message: string, code: keyof typeof DiagnosticsErrorCodes, recoverable?: boolean);
+}
+
+/**
+ * Effect Detection
+ *
+ * Detect effect type from keywords, types, and context.
+ */
+
+/**
+ * Detect effect type from keywords and types
+ *
+ * Priority:
+ * 1. Types override keywords (Currency, Wei, etc. → Financial)
+ * 2. Context can modify detection (with undo → Soft Delete)
+ * 3. Keywords determine base effect
+ */
+declare function detectEffect(keywords: string[], types?: string[]): EffectType;
+/**
+ * Get expected physics for an effect type
+ */
+declare function getExpectedPhysics(effect: EffectType): {
+    sync: 'optimistic' | 'pessimistic' | 'immediate';
+    timing: number;
+    confirmation: boolean;
+};
+/**
+ * Export keyword lists for external use
+ */
+declare const keywords: {
+    financial: string[];
+    destructive: string[];
+    softDelete: string[];
+    standard: string[];
+    local: string[];
+    navigation: string[];
+    query: string[];
+};
+
+/**
+ * Physics Compliance Checking
+ *
+ * Verify that component physics match expected values for effect type.
+ */
+
+/**
+ * Check behavioral physics compliance
+ */
+declare function checkBehavioralCompliance(effect: EffectType, actual: Partial<BehavioralCompliance>): BehavioralCompliance;
+/**
+ * Check animation physics compliance
+ */
+declare function checkAnimationCompliance(effect: EffectType, actual: Partial<AnimationCompliance>): AnimationCompliance;
+/**
+ * Check material physics compliance
+ */
+declare function checkMaterialCompliance(effect: EffectType, actual: Partial<MaterialCompliance>): MaterialCompliance;
+/**
+ * Check full compliance across all physics layers
+ */
+declare function checkCompliance(effect: EffectType, physics: Partial<ComplianceResult>): ComplianceResult;
+/**
+ * Generate issues from compliance result
+ */
+declare function complianceToIssues(compliance: ComplianceResult): DiagnosticIssue[];
+/**
+ * Check if compliance result is fully compliant
+ */
+declare function isFullyCompliant(compliance: ComplianceResult): boolean;
+
+/**
+ * Known Diagnostic Patterns
+ *
+ * Patterns for detecting common issues in React/Next.js applications.
+ */
+
+/**
+ * Built-in diagnostic patterns
+ */
+declare const PATTERNS: DiagnosticPattern[];
+/**
+ * Get all patterns
+ */
+declare function getPatterns(): DiagnosticPattern[];
+/**
+ * Get patterns by category
+ */
+declare function getPatternsByCategory(category: DiagnosticPattern['category']): DiagnosticPattern[];
+/**
+ * Get pattern by ID
+ */
+declare function getPatternById(id: string): DiagnosticPattern | undefined;
+
+/**
+ * Diagnostics Service
+ *
+ * Main service for physics compliance checking and issue detection.
+ */
+
+/**
+ * Create a diagnostics service
+ */
+declare function createDiagnosticsService(anchorClient?: unknown, config?: DiagnosticsConfig): DiagnosticsService;
+/**
+ * Get the default diagnostics service
+ */
+declare function getDiagnosticsService(anchorClient?: unknown): DiagnosticsService;
+/**
+ * Reset the default diagnostics service
+ */
+declare function resetDiagnosticsService(): void;
+
+export { type AnimationCompliance, type BehavioralCompliance, type ComplianceResult, type DiagnosticIssue, type DiagnosticPattern, type DiagnosticResult, type DiagnosticsConfig, DiagnosticsError, DiagnosticsErrorCodes, type DiagnosticsService, type EffectType, type MaterialCompliance, PATTERNS, type PatternCategory, type PatternCause, type PatternMatchResult, type Severity, checkAnimationCompliance, checkBehavioralCompliance, checkCompliance, checkMaterialCompliance, complianceToIssues, createDiagnosticsService, detectEffect, getDiagnosticsService, getExpectedPhysics, getPatternById, getPatterns, getPatternsByCategory, isFullyCompliant, keywords, resetDiagnosticsService };