@thehoneyjar/sigil-diagnostics 0.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@thehoneyjar/sigil-diagnostics",
+  "version": "0.1.0",
+  "description": "Physics compliance checking and issue detection for Sigil",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@thehoneyjar/sigil-anchor": "4.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xHoneyJar/sigil.git",
+    "directory": "packages/diagnostics"
+  },
+  "bugs": {
+    "url": "https://github.com/0xHoneyJar/sigil/issues"
+  },
+  "homepage": "https://github.com/0xHoneyJar/sigil/tree/main/packages/diagnostics#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/compliance.ts

@@ -0,0 +1,250 @@
+/**
+ * Physics Compliance Checking
+ *
+ * Verify that component physics match expected values for effect type.
+ */
+
+import type {
+  EffectType,
+  ComplianceResult,
+  BehavioralCompliance,
+  AnimationCompliance,
+  MaterialCompliance,
+  DiagnosticIssue,
+} from './types'
+import { getExpectedPhysics } from './detection'
+
+/**
+ * Expected animation values by effect type
+ */
+const EXPECTED_ANIMATION: Record<
+  EffectType,
+  { easing: string; duration: number }
+> = {
+  financial: { easing: 'ease-out', duration: 800 },
+  destructive: { easing: 'ease-out', duration: 600 },
+  'soft-delete': { easing: 'spring(500)', duration: 200 },
+  standard: { easing: 'spring(500)', duration: 200 },
+  navigation: { easing: 'ease', duration: 150 },
+  query: { easing: 'ease-out', duration: 150 },
+  local: { easing: 'spring(700)', duration: 100 },
+}
+
+/**
+ * Expected material values by effect type
+ */
+const EXPECTED_MATERIAL: Record<EffectType, { surface: string; shadow: string }> =
+  {
+    financial: { surface: 'elevated', shadow: 'soft' },
+    destructive: { surface: 'elevated', shadow: 'none' },
+    'soft-delete': { surface: 'flat', shadow: 'none' },
+    standard: { surface: 'elevated', shadow: 'soft' },
+    navigation: { surface: 'flat', shadow: 'none' },
+    query: { surface: 'flat', shadow: 'none' },
+    local: { surface: 'flat', shadow: 'none' },
+  }
+
+/**
+ * Timing tolerance for compliance checking (ms)
+ */
+const TIMING_TOLERANCE = 100
+
+/**
+ * Check behavioral physics compliance
+ */
+export function checkBehavioralCompliance(
+  effect: EffectType,
+  actual: Partial<BehavioralCompliance>
+): BehavioralCompliance {
+  const expected = getExpectedPhysics(effect)
+
+  const syncMatch = actual.sync === expected.sync
+  const timingMatch =
+    actual.timing === undefined ||
+    Math.abs(actual.timing - expected.timing) <= TIMING_TOLERANCE
+  const confirmMatch =
+    actual.confirmation === undefined ||
+    actual.confirmation === expected.confirmation
+
+  const compliant = syncMatch && timingMatch && confirmMatch
+
+  let reason: string | undefined
+  if (!compliant) {
+    const issues: string[] = []
+    if (!syncMatch) {
+      issues.push(`sync should be ${expected.sync}, got ${actual.sync}`)
+    }
+    if (!timingMatch) {
+      issues.push(`timing should be ${expected.timing}ms, got ${actual.timing}ms`)
+    }
+    if (!confirmMatch) {
+      issues.push(
+        `confirmation should be ${expected.confirmation}, got ${actual.confirmation}`
+      )
+    }
+    reason = issues.join('; ')
+  }
+
+  return {
+    sync: actual.sync ?? expected.sync,
+    timing: actual.timing ?? expected.timing,
+    confirmation: actual.confirmation ?? expected.confirmation,
+    compliant,
+    reason,
+  }
+}
+
+/**
+ * Check animation physics compliance
+ */
+export function checkAnimationCompliance(
+  effect: EffectType,
+  actual: Partial<AnimationCompliance>
+): AnimationCompliance {
+  const expected = EXPECTED_ANIMATION[effect]
+
+  // Easing is more flexible - check if it's in the right family
+  const easingMatch =
+    actual.easing === undefined || isCompatibleEasing(actual.easing, expected.easing)
+
+  const durationMatch =
+    actual.duration === undefined ||
+    Math.abs(actual.duration - expected.duration) <= TIMING_TOLERANCE
+
+  const compliant = easingMatch && durationMatch
+
+  let reason: string | undefined
+  if (!compliant) {
+    const issues: string[] = []
+    if (!easingMatch) {
+      issues.push(`easing should be ${expected.easing}, got ${actual.easing}`)
+    }
+    if (!durationMatch) {
+      issues.push(
+        `duration should be ${expected.duration}ms, got ${actual.duration}ms`
+      )
+    }
+    reason = issues.join('; ')
+  }
+
+  return {
+    easing: actual.easing ?? expected.easing,
+    duration: actual.duration ?? expected.duration,
+    compliant,
+    reason,
+  }
+}
+
+/**
+ * Check if easing function is compatible with expected
+ */
+function isCompatibleEasing(actual: string, expected: string): boolean {
+  // Exact match
+  if (actual === expected) return true
+
+  // Spring family
+  if (expected.includes('spring') && actual.includes('spring')) return true
+
+  // Ease family
+  if (expected.includes('ease') && actual.includes('ease')) return true
+
+  return false
+}
+
+/**
+ * Check material physics compliance
+ */
+export function checkMaterialCompliance(
+  effect: EffectType,
+  actual: Partial<MaterialCompliance>
+): MaterialCompliance {
+  const expected = EXPECTED_MATERIAL[effect]
+
+  const surfaceMatch = actual.surface === undefined || actual.surface === expected.surface
+  const shadowMatch = actual.shadow === undefined || actual.shadow === expected.shadow
+
+  const compliant = surfaceMatch && shadowMatch
+
+  let reason: string | undefined
+  if (!compliant) {
+    const issues: string[] = []
+    if (!surfaceMatch) {
+      issues.push(`surface should be ${expected.surface}, got ${actual.surface}`)
+    }
+    if (!shadowMatch) {
+      issues.push(`shadow should be ${expected.shadow}, got ${actual.shadow}`)
+    }
+    reason = issues.join('; ')
+  }
+
+  return {
+    surface: actual.surface ?? expected.surface,
+    shadow: actual.shadow ?? expected.shadow,
+    radius: actual.radius,
+    compliant,
+    reason,
+  }
+}
+
+/**
+ * Check full compliance across all physics layers
+ */
+export function checkCompliance(
+  effect: EffectType,
+  physics: Partial<ComplianceResult>
+): ComplianceResult {
+  return {
+    behavioral: checkBehavioralCompliance(effect, physics.behavioral ?? {}),
+    animation: checkAnimationCompliance(effect, physics.animation ?? {}),
+    material: checkMaterialCompliance(effect, physics.material ?? {}),
+  }
+}
+
+/**
+ * Generate issues from compliance result
+ */
+export function complianceToIssues(
+  compliance: ComplianceResult
+): DiagnosticIssue[] {
+  const issues: DiagnosticIssue[] = []
+
+  if (!compliance.behavioral.compliant && compliance.behavioral.reason) {
+    issues.push({
+      severity: 'error',
+      code: 'BEHAVIORAL_NONCOMPLIANT',
+      message: `Behavioral physics non-compliant: ${compliance.behavioral.reason}`,
+      suggestion: 'Review sync strategy, timing, and confirmation settings',
+    })
+  }
+
+  if (!compliance.animation.compliant && compliance.animation.reason) {
+    issues.push({
+      severity: 'warning',
+      code: 'ANIMATION_NONCOMPLIANT',
+      message: `Animation physics non-compliant: ${compliance.animation.reason}`,
+      suggestion: 'Adjust easing and duration to match effect type',
+    })
+  }
+
+  if (!compliance.material.compliant && compliance.material.reason) {
+    issues.push({
+      severity: 'info',
+      code: 'MATERIAL_NONCOMPLIANT',
+      message: `Material physics non-compliant: ${compliance.material.reason}`,
+      suggestion: 'Consider adjusting surface and shadow properties',
+    })
+  }
+
+  return issues
+}
+
+/**
+ * Check if compliance result is fully compliant
+ */
+export function isFullyCompliant(compliance: ComplianceResult): boolean {
+  return (
+    compliance.behavioral.compliant &&
+    compliance.animation.compliant &&
+    compliance.material.compliant
+  )
+}

package/src/detection.ts

@@ -0,0 +1,373 @@
+/**
+ * Effect Detection
+ *
+ * Detect effect type from keywords, types, and context.
+ */
+
+import type { EffectType } from './types'
+
+/**
+ * Keywords that indicate financial operations
+ */
+const FINANCIAL_KEYWORDS = [
+  'claim',
+  'deposit',
+  'withdraw',
+  'transfer',
+  'swap',
+  'send',
+  'pay',
+  'purchase',
+  'mint',
+  'burn',
+  'stake',
+  'unstake',
+  'bridge',
+  'approve',
+  'redeem',
+  'harvest',
+  'collect',
+  'vest',
+  'unlock',
+  'liquidate',
+  'borrow',
+  'lend',
+  'repay',
+  'airdrop',
+  'delegate',
+  'undelegate',
+  'redelegate',
+  'bond',
+  'unbond',
+  'checkout',
+  'order',
+  'subscribe',
+  'upgrade',
+  'downgrade',
+  'refund',
+]
+
+/**
+ * Keywords that indicate destructive operations
+ */
+const DESTRUCTIVE_KEYWORDS = [
+  'delete',
+  'remove',
+  'destroy',
+  'revoke',
+  'terminate',
+  'purge',
+  'erase',
+  'wipe',
+  'clear',
+  'reset',
+  'ban',
+  'block',
+  'suspend',
+  'deactivate',
+  'cancel',
+  'void',
+  'invalidate',
+  'expire',
+  'kill',
+  'close account',
+  'delete account',
+  'remove access',
+  'revoke permissions',
+]
+
+/**
+ * Keywords that indicate soft delete operations
+ */
+const SOFT_DELETE_KEYWORDS = [
+  'archive',
+  'hide',
+  'trash',
+  'dismiss',
+  'snooze',
+  'mute',
+  'silence',
+  'ignore',
+  'skip',
+  'defer',
+  'postpone',
+  'mark as read',
+  'mark as spam',
+  'move to folder',
+  'soft-delete',
+  'temporary hide',
+  'pause',
+]
+
+/**
+ * Keywords that indicate standard operations
+ */
+const STANDARD_KEYWORDS = [
+  'save',
+  'update',
+  'edit',
+  'create',
+  'add',
+  'like',
+  'follow',
+  'bookmark',
+  'favorite',
+  'star',
+  'pin',
+  'tag',
+  'label',
+  'comment',
+  'share',
+  'repost',
+  'quote',
+  'reply',
+  'mention',
+  'react',
+  'submit',
+  'post',
+  'publish',
+  'upload',
+  'attach',
+  'link',
+  'change',
+  'modify',
+  'set',
+  'configure',
+  'customize',
+  'personalize',
+]
+
+/**
+ * Keywords that indicate local state operations
+ */
+const LOCAL_KEYWORDS = [
+  'toggle',
+  'switch',
+  'expand',
+  'collapse',
+  'select',
+  'focus',
+  'show',
+  'hide',
+  'open',
+  'close',
+  'reveal',
+  'conceal',
+  'check',
+  'uncheck',
+  'enable',
+  'disable',
+  'activate',
+  'sort',
+  'filter',
+  'search',
+  'zoom',
+  'pan',
+  'scroll',
+  'dark mode',
+  'light mode',
+  'theme',
+  'appearance',
+  'display',
+]
+
+/**
+ * Keywords that indicate navigation
+ */
+const NAVIGATION_KEYWORDS = [
+  'navigate',
+  'go',
+  'back',
+  'forward',
+  'link',
+  'route',
+  'visit',
+  'open page',
+  'view',
+  'browse',
+  'explore',
+  'next',
+  'previous',
+  'first',
+  'last',
+  'jump to',
+  'tab',
+  'step',
+  'page',
+  'section',
+  'anchor',
+]
+
+/**
+ * Keywords that indicate query operations
+ */
+const QUERY_KEYWORDS = [
+  'fetch',
+  'load',
+  'get',
+  'list',
+  'search',
+  'find',
+  'query',
+  'lookup',
+  'retrieve',
+  'request',
+  'poll',
+  'refresh',
+  'reload',
+  'sync',
+  'check status',
+  'preview',
+  'peek',
+  'inspect',
+  'examine',
+]
+
+/**
+ * Type patterns that override keyword detection
+ */
+const FINANCIAL_TYPE_PATTERNS = [
+  'Currency',
+  'Money',
+  'Amount',
+  'Wei',
+  'BigInt',
+  'Token',
+  'Balance',
+  'Price',
+  'Fee',
+]
+
+/**
+ * Context phrases that modify detection
+ */
+const SOFT_DELETE_CONTEXT = ['with undo', 'reversible', 'recycle bin', 'can undo']
+
+/**
+ * Check if any keyword matches
+ */
+function matchesKeywords(text: string, keywords: string[]): boolean {
+  const lowerText = text.toLowerCase()
+  return keywords.some((k) => lowerText.includes(k.toLowerCase()))
+}
+
+/**
+ * Check if types indicate financial operations
+ */
+function hasFinancialTypes(types: string[]): boolean {
+  return types.some((t) =>
+    FINANCIAL_TYPE_PATTERNS.some(
+      (pattern) =>
+        t.includes(pattern) || t.toLowerCase().includes(pattern.toLowerCase())
+    )
+  )
+}
+
+/**
+ * Check for soft delete context
+ */
+function hasSoftDeleteContext(text: string): boolean {
+  const lowerText = text.toLowerCase()
+  return SOFT_DELETE_CONTEXT.some((c) => lowerText.includes(c))
+}
+
+/**
+ * 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
+ */
+export function detectEffect(
+  keywords: string[],
+  types: string[] = []
+): EffectType {
+  const combinedText = keywords.join(' ')
+
+  // 1. Type overrides - if financial types present, always financial
+  if (hasFinancialTypes(types)) {
+    return 'financial'
+  }
+
+  // 2. Context check - "with undo" converts destructive to soft-delete
+  if (hasSoftDeleteContext(combinedText)) {
+    // Only if it was going to be destructive
+    if (matchesKeywords(combinedText, DESTRUCTIVE_KEYWORDS)) {
+      return 'soft-delete'
+    }
+  }
+
+  // 3. Keyword detection in priority order
+  if (matchesKeywords(combinedText, FINANCIAL_KEYWORDS)) {
+    return 'financial'
+  }
+
+  if (matchesKeywords(combinedText, DESTRUCTIVE_KEYWORDS)) {
+    return 'destructive'
+  }
+
+  if (matchesKeywords(combinedText, SOFT_DELETE_KEYWORDS)) {
+    return 'soft-delete'
+  }
+
+  if (matchesKeywords(combinedText, LOCAL_KEYWORDS)) {
+    return 'local'
+  }
+
+  if (matchesKeywords(combinedText, NAVIGATION_KEYWORDS)) {
+    return 'navigation'
+  }
+
+  if (matchesKeywords(combinedText, QUERY_KEYWORDS)) {
+    return 'query'
+  }
+
+  if (matchesKeywords(combinedText, STANDARD_KEYWORDS)) {
+    return 'standard'
+  }
+
+  // Default to standard
+  return 'standard'
+}
+
+/**
+ * Get expected physics for an effect type
+ */
+export function getExpectedPhysics(effect: EffectType): {
+  sync: 'optimistic' | 'pessimistic' | 'immediate'
+  timing: number
+  confirmation: boolean
+} {
+  switch (effect) {
+    case 'financial':
+      return { sync: 'pessimistic', timing: 800, confirmation: true }
+    case 'destructive':
+      return { sync: 'pessimistic', timing: 600, confirmation: true }
+    case 'soft-delete':
+      return { sync: 'optimistic', timing: 200, confirmation: false }
+    case 'standard':
+      return { sync: 'optimistic', timing: 200, confirmation: false }
+    case 'navigation':
+      return { sync: 'immediate', timing: 150, confirmation: false }
+    case 'query':
+      return { sync: 'optimistic', timing: 150, confirmation: false }
+    case 'local':
+      return { sync: 'immediate', timing: 100, confirmation: false }
+    default:
+      return { sync: 'optimistic', timing: 200, confirmation: false }
+  }
+}
+
+/**
+ * Export keyword lists for external use
+ */
+export const keywords = {
+  financial: FINANCIAL_KEYWORDS,
+  destructive: DESTRUCTIVE_KEYWORDS,
+  softDelete: SOFT_DELETE_KEYWORDS,
+  standard: STANDARD_KEYWORDS,
+  local: LOCAL_KEYWORDS,
+  navigation: NAVIGATION_KEYWORDS,
+  query: QUERY_KEYWORDS,
+}