@mdxui/terminal 2.0.0

package/src/__tests__/core/parser.test.ts

@@ -0,0 +1,785 @@
+/**
+ * @mdxui/terminal JSON → UINode Parser Tests (RED phase)
+ *
+ * TDD RED Phase: These tests define the contract for JSON/YAML parsing
+ * functionality that converts JSON strings and objects into UINode structures.
+ *
+ * The parser must handle:
+ * - Valid JSON object → UINode conversion
+ * - Nested structure parsing with recursive children
+ * - Array children parsing
+ * - Schema validation using UINodeSchema
+ * - Comprehensive error handling for invalid JSON
+ * - Comprehensive error handling for invalid UINode structures
+ * - Optional: YAML string parsing support
+ *
+ * NOTE: These tests are expected to FAIL until the parser implementation
+ * is complete. Run: pnpm --filter @mdxui/terminal test
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { z } from 'zod'
+
+// ============================================================================
+// These imports WILL FAIL until src/core/parser.ts is implemented
+// ============================================================================
+import { parseUINode, parseUINodeFromJSON, ParseError } from '../../core/parser'
+
+import type { UINode } from '../../core/types'
+import { UINodeSchema } from '../../core/types'
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+/**
+ * Helper to create a valid minimal UINode for testing
+ */
+function createNode(
+  type: string,
+  props: Record<string, unknown> = {},
+  children?: UINode[],
+  data?: unknown,
+  key?: string
+): UINode {
+  return { type, props, ...(children && { children }), ...(data && { data }), ...(key && { key }) }
+}
+
+// ============================================================================
+// parseUINode Function Tests - Valid Parsing
+// ============================================================================
+
+describe('parseUINode function', () => {
+  describe('valid JSON string parsing', () => {
+    it('parses minimal valid JSON string to UINode', () => {
+      const json = '{"type":"text","props":{}}'
+      const result = parseUINode(json)
+
+      expect(result).toBeDefined()
+      expect(result.type).toBe('text')
+      expect(result.props).toEqual({})
+    })
+
+    it('parses JSON string with props', () => {
+      const json = '{"type":"box","props":{"padding":2,"border":"single"}}'
+      const result = parseUINode(json)
+
+      expect(result.type).toBe('box')
+      expect(result.props.padding).toBe(2)
+      expect(result.props.border).toBe('single')
+    })
+
+    it('parses JSON string with empty children array', () => {
+      const json = '{"type":"box","props":{},"children":[]}'
+      const result = parseUINode(json)
+
+      expect(result.children).toEqual([])
+    })
+
+    it('parses JSON string with single child', () => {
+      const json =
+        '{"type":"box","props":{},"children":[{"type":"text","props":{"content":"Child"}}]}'
+      const result = parseUINode(json)
+
+      expect(result.children).toHaveLength(1)
+      expect(result.children![0].type).toBe('text')
+      expect(result.children![0].props.content).toBe('Child')
+    })
+
+    it('parses JSON string with multiple children', () => {
+      const json =
+        '{"type":"box","props":{},"children":[{"type":"text","props":{"content":"First"}},{"type":"text","props":{"content":"Second"}}]}'
+      const result = parseUINode(json)
+
+      expect(result.children).toHaveLength(2)
+      expect(result.children![0].props.content).toBe('First')
+      expect(result.children![1].props.content).toBe('Second')
+    })
+
+    it('parses JSON string with data field', () => {
+      const json = '{"type":"table","props":{},"data":{"rows":[{"id":1,"name":"Alice"}]}}'
+      const result = parseUINode(json)
+
+      expect(result.type).toBe('table')
+      expect(result.data).toBeDefined()
+      expect((result.data as any).rows).toHaveLength(1)
+    })
+
+    it('parses JSON string with key field', () => {
+      const json = '{"type":"item","props":{},"key":"item-123"}'
+      const result = parseUINode(json)
+
+      expect(result.key).toBe('item-123')
+    })
+
+    it('parses JSON string with all optional fields', () => {
+      const json =
+        '{"type":"complex","props":{"flag":true},"children":[{"type":"child","props":{}}],"data":{"value":42},"key":"unique"}'
+      const result = parseUINode(json)
+
+      expect(result.type).toBe('complex')
+      expect(result.props.flag).toBe(true)
+      expect(result.children).toHaveLength(1)
+      expect(result.data).toEqual({ value: 42 })
+      expect(result.key).toBe('unique')
+    })
+
+    it('parses JSON with whitespace and newlines', () => {
+      const json = `{
+        "type": "text",
+        "props": {
+          "content": "Hello"
+        }
+      }`
+      const result = parseUINode(json)
+
+      expect(result.type).toBe('text')
+      expect(result.props.content).toBe('Hello')
+    })
+  })
+
+  describe('valid parsed object parsing', () => {
+    it('accepts pre-parsed JavaScript object', () => {
+      const obj: UINode = {
+        type: 'text',
+        props: { content: 'Direct object' },
+      }
+      const result = parseUINode(obj)
+
+      expect(result.type).toBe('text')
+      expect(result.props.content).toBe('Direct object')
+    })
+
+    it('accepts object with nested children', () => {
+      const obj: UINode = {
+        type: 'box',
+        props: {},
+        children: [{ type: 'text', props: { content: 'Nested' } }],
+      }
+      const result = parseUINode(obj)
+
+      expect(result.children![0].type).toBe('text')
+    })
+  })
+
+  describe('deeply nested structure parsing', () => {
+    it('parses 2-level nested structure', () => {
+      const json = `{
+        "type": "box",
+        "props": {},
+        "children": [
+          {
+            "type": "panel",
+            "props": { "title": "Panel" },
+            "children": [
+              { "type": "text", "props": { "content": "Nested" } }
+            ]
+          }
+        ]
+      }`
+      const result = parseUINode(json)
+
+      expect(result.children![0].type).toBe('panel')
+      expect(result.children![0].children![0].type).toBe('text')
+    })
+
+    it('parses 3-level nested structure', () => {
+      const json = `{
+        "type": "container",
+        "props": {},
+        "children": [
+          {
+            "type": "row",
+            "props": {},
+            "children": [
+              {
+                "type": "column",
+                "props": {},
+                "children": [
+                  { "type": "text", "props": { "content": "Deep" } }
+                ]
+              }
+            ]
+          }
+        ]
+      }`
+      const result = parseUINode(json)
+
+      expect(result.children![0].children![0].children![0].type).toBe('text')
+    })
+
+    it('parses complex nested tree with multiple branches', () => {
+      const json = `{
+        "type": "root",
+        "props": {},
+        "children": [
+          {
+            "type": "branch1",
+            "props": {},
+            "children": [
+              { "type": "leaf1a", "props": {} },
+              { "type": "leaf1b", "props": {} }
+            ]
+          },
+          {
+            "type": "branch2",
+            "props": {},
+            "children": [
+              { "type": "leaf2a", "props": {} }
+            ]
+          }
+        ]
+      }`
+      const result = parseUINode(json)
+
+      expect(result.children).toHaveLength(2)
+      expect(result.children![0].children).toHaveLength(2)
+      expect(result.children![1].children).toHaveLength(1)
+    })
+  })
+
+  describe('array children parsing', () => {
+    it('handles empty children array', () => {
+      const json = '{"type":"box","props":{},"children":[]}'
+      const result = parseUINode(json)
+
+      expect(Array.isArray(result.children)).toBe(true)
+      expect(result.children).toHaveLength(0)
+    })
+
+    it('handles children with mixed prop types', () => {
+      const json = `{
+        "type": "container",
+        "props": {},
+        "children": [
+          { "type": "node1", "props": { "string": "text", "number": 42, "bool": true } },
+          { "type": "node2", "props": { "array": [1,2,3], "obj": { "nested": true } } }
+        ]
+      }`
+      const result = parseUINode(json)
+
+      expect(result.children![0].props.string).toBe('text')
+      expect(result.children![0].props.number).toBe(42)
+      expect(result.children![0].props.bool).toBe(true)
+      expect(Array.isArray(result.children![1].props.array)).toBe(true)
+      expect(typeof result.children![1].props.obj).toBe('object')
+    })
+
+    it('preserves child order', () => {
+      const json = `{
+        "type": "list",
+        "props": {},
+        "children": [
+          { "type": "item", "props": { "index": 0 } },
+          { "type": "item", "props": { "index": 1 } },
+          { "type": "item", "props": { "index": 2 } }
+        ]
+      }`
+      const result = parseUINode(json)
+
+      expect(result.children![0].props.index).toBe(0)
+      expect(result.children![1].props.index).toBe(1)
+      expect(result.children![2].props.index).toBe(2)
+    })
+  })
+
+  describe('schema validation', () => {
+    it('validates parsed node against UINodeSchema', () => {
+      const json = '{"type":"text","props":{"content":"Valid"}}'
+      const result = parseUINode(json)
+
+      const validation = UINodeSchema.safeParse(result)
+      expect(validation.success).toBe(true)
+    })
+
+    it('validates nested children against UINodeSchema', () => {
+      const json = `{
+        "type": "box",
+        "props": {},
+        "children": [
+          { "type": "text", "props": {} }
+        ]
+      }`
+      const result = parseUINode(json)
+
+      const validation = UINodeSchema.safeParse(result)
+      expect(validation.success).toBe(true)
+    })
+
+    it('ensures all required fields are present after parsing', () => {
+      const json = '{"type":"component","props":{"prop1":"value"}}'
+      const result = parseUINode(json)
+
+      expect(result.type).toBeDefined()
+      expect(typeof result.type).toBe('string')
+      expect(result.props).toBeDefined()
+      expect(typeof result.props).toBe('object')
+    })
+  })
+})
+
+// ============================================================================
+// parseUINode Function Tests - Invalid Input Handling
+// ============================================================================
+
+describe('parseUINode error handling', () => {
+  describe('invalid JSON strings', () => {
+    it('throws ParseError for malformed JSON', () => {
+      const invalidJson = '{type: "text"}'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for incomplete JSON', () => {
+      const invalidJson = '{"type":"text"'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for trailing comma in JSON', () => {
+      const invalidJson = '{"type":"text","props":{},}'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for single quotes in JSON', () => {
+      const invalidJson = "{'type':'text'}"
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for undefined value in JSON', () => {
+      const invalidJson = '{"type":"text","props":undefined}'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for JSON array as root', () => {
+      const invalidJson = '[{"type":"text","props":{}}]'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for null value', () => {
+      const invalidJson = 'null'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for JSON string', () => {
+      const invalidJson = '"just a string"'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for JSON number', () => {
+      const invalidJson = '42'
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for empty string', () => {
+      const invalidJson = ''
+      expect(() => parseUINode(invalidJson)).toThrow(ParseError)
+    })
+  })
+
+  describe('invalid UINode structure', () => {
+    it('throws ParseError for missing type field', () => {
+      const json = '{"props":{}}'
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+
+    it('accepts missing props field (props is optional)', () => {
+      const json = '{"type":"text"}'
+      const result = parseUINode(json)
+      expect(result.type).toBe('text')
+    })
+
+    it('throws ParseError for non-string type', () => {
+      const json = '{"type":123,"props":{}}'
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for non-object props', () => {
+      const json = '{"type":"text","props":"invalid"}'
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for array props', () => {
+      const json = '{"type":"text","props":[]}'
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+
+    it('accepts string children (children can be string or array)', () => {
+      const json = '{"type":"box","props":{},"children":"string content"}'
+      const result = parseUINode(json)
+      expect(result.children).toBe('string content')
+    })
+
+    it('throws ParseError for invalid child in children array', () => {
+      const json = `{
+        "type": "box",
+        "props": {},
+        "children": [
+          { "type": "valid", "props": {} },
+          "invalid child",
+          { "props": {} }
+        ]
+      }`
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for non-string key', () => {
+      const json = '{"type":"item","props":{},"key":123}'
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for deeply nested invalid child', () => {
+      const json = `{
+        "type": "root",
+        "props": {},
+        "children": [
+          {
+            "type": "parent",
+            "props": {},
+            "children": [
+              { "invalid": true }
+            ]
+          }
+        ]
+      }`
+      expect(() => parseUINode(json)).toThrow(ParseError)
+    })
+  })
+
+  describe('error information', () => {
+    it('ParseError contains helpful message for missing type', () => {
+      const json = '{"props":{}}'
+      try {
+        parseUINode(json)
+        expect.fail('Should have thrown ParseError')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ParseError)
+        expect((error as ParseError).message).toContain('type')
+      }
+    })
+
+    it('ParseError contains helpful message for invalid JSON', () => {
+      const json = '{invalid}'
+      try {
+        parseUINode(json)
+        expect.fail('Should have thrown ParseError')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ParseError)
+        expect((error as ParseError).message).toBeDefined()
+      }
+    })
+
+    it('ParseError includes parsing context', () => {
+      const json = '{"type":"test","props":{"nested":{"value":incomplete}}}'
+      try {
+        parseUINode(json)
+        expect.fail('Should have thrown ParseError')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ParseError)
+      }
+    })
+  })
+})
+
+// ============================================================================
+// parseUINodeFromJSON Helper Function Tests
+// ============================================================================
+
+describe('parseUINodeFromJSON function', () => {
+  describe('parsing from JSON string', () => {
+    it('parses valid JSON string', () => {
+      const json = '{"type":"text","props":{}}'
+      const result = parseUINodeFromJSON(json)
+
+      expect(result).toBeDefined()
+      expect(result.type).toBe('text')
+    })
+
+    it('parses JSON with complex props', () => {
+      const json = `{
+        "type": "component",
+        "props": {
+          "title": "Example",
+          "count": 5,
+          "active": true,
+          "tags": ["a", "b", "c"],
+          "metadata": { "key": "value" }
+        }
+      }`
+      const result = parseUINodeFromJSON(json)
+
+      expect(result.props.title).toBe('Example')
+      expect(result.props.count).toBe(5)
+      expect(result.props.active).toBe(true)
+      expect(Array.isArray(result.props.tags)).toBe(true)
+      expect(typeof result.props.metadata).toBe('object')
+    })
+  })
+
+  describe('error handling for JSON string', () => {
+    it('throws ParseError for invalid JSON', () => {
+      const json = '{type: "invalid"}'
+      expect(() => parseUINodeFromJSON(json)).toThrow(ParseError)
+    })
+
+    it('throws ParseError for non-object JSON', () => {
+      const json = '[1, 2, 3]'
+      expect(() => parseUINodeFromJSON(json)).toThrow(ParseError)
+    })
+  })
+})
+
+// ============================================================================
+// Edge Cases and Special Scenarios
+// ============================================================================
+
+describe('edge cases', () => {
+  describe('special prop values', () => {
+    it('handles null props values', () => {
+      const json = '{"type":"component","props":{"nullable":null}}'
+      const result = parseUINode(json)
+
+      expect(result.props.nullable).toBeNull()
+    })
+
+    it('handles boolean props', () => {
+      const json = '{"type":"component","props":{"disabled":false,"enabled":true}}'
+      const result = parseUINode(json)
+
+      expect(result.props.disabled).toBe(false)
+      expect(result.props.enabled).toBe(true)
+    })
+
+    it('handles numeric props (integers and floats)', () => {
+      const json = '{"type":"component","props":{"integer":42,"float":3.14}}'
+      const result = parseUINode(json)
+
+      expect(result.props.integer).toBe(42)
+      expect(result.props.float).toBe(3.14)
+    })
+
+    it('handles string props with special characters', () => {
+      const json = '{"type":"component","props":{"text":"Hello\\nWorld\\t!"}}'
+      const result = parseUINode(json)
+
+      expect(result.props.text).toContain('Hello')
+    })
+
+    it('handles empty string props', () => {
+      const json = '{"type":"component","props":{"empty":""}}'
+      const result = parseUINode(json)
+
+      expect(result.props.empty).toBe('')
+    })
+
+    it('handles array props', () => {
+      const json = '{"type":"component","props":{"items":[1,2,3,{"nested":true}]}}'
+      const result = parseUINode(json)
+
+      expect(Array.isArray(result.props.items)).toBe(true)
+      expect(result.props.items).toHaveLength(4)
+    })
+
+    it('handles object props with nested structure', () => {
+      const json =
+        '{"type":"component","props":{"config":{"level1":{"level2":{"level3":"deep"}}}}}'
+      const result = parseUINode(json)
+
+      expect((result.props.config as any).level1.level2.level3).toBe('deep')
+    })
+  })
+
+  describe('data field variations', () => {
+    it('handles data as array', () => {
+      const json = '{"type":"list","props":{},"data":[1,2,3]}'
+      const result = parseUINode(json)
+
+      expect(Array.isArray(result.data)).toBe(true)
+    })
+
+    it('handles data as object', () => {
+      const json = '{"type":"table","props":{},"data":{"rows":[],"cols":[]}}'
+      const result = parseUINode(json)
+
+      expect(typeof result.data).toBe('object')
+    })
+
+    it('handles data as primitive', () => {
+      const json = '{"type":"counter","props":{},"data":42}'
+      const result = parseUINode(json)
+
+      expect(result.data).toBe(42)
+    })
+
+    it('handles data as string', () => {
+      const json = '{"type":"text","props":{},"data":"bound data"}'
+      const result = parseUINode(json)
+
+      expect(result.data).toBe('bound data')
+    })
+  })
+
+  describe('Unicode and internationalization', () => {
+    it('handles Unicode characters in strings', () => {
+      const json = '{"type":"text","props":{"content":"Hello 世界 مرحبا"}}'
+      const result = parseUINode(json)
+
+      expect(result.props.content).toContain('世界')
+    })
+
+    it('handles emoji in props', () => {
+      const json = '{"type":"component","props":{"icon":"🎉"}}'
+      const result = parseUINode(json)
+
+      expect(result.props.icon).toBe('🎉')
+    })
+  })
+
+  describe('large and complex structures', () => {
+    it('handles large number of children', () => {
+      const childrenJson = Array.from({ length: 100 }, (_, i) =>
+        `{"type":"item","props":{"index":${i}}}`
+      ).join(',')
+      const json = `{"type":"list","props":{},"children":[${childrenJson}]}`
+
+      const result = parseUINode(json)
+      expect(result.children).toHaveLength(100)
+    })
+
+    it('handles deeply nested structure (10+ levels)', () => {
+      let json = '{"type":"root","props":{},"children":[{'
+      for (let i = 0; i < 10; i++) {
+        json += `"type":"level${i}","props":{},"children":[{`
+      }
+      json += '"type":"leaf","props":{}'
+      for (let i = 0; i < 10; i++) {
+        json += '}]'
+      }
+      json += '}]}'
+
+      const result = parseUINode(json)
+      let current = result
+      // Traverse 11 levels: root -> level0 -> level1 -> ... -> level9 -> leaf
+      for (let i = 0; i < 11; i++) {
+        expect(current.children).toBeDefined()
+        current = current.children![0]
+      }
+      expect(current.type).toBe('leaf')
+    })
+  })
+})
+
+// ============================================================================
+// Optional: YAML Parsing Support
+// ============================================================================
+
+describe('YAML parsing (optional)', () => {
+  describe('parseUINode with YAML input', () => {
+    it('parses YAML string to UINode', () => {
+      const yaml = `
+type: text
+props:
+  content: Hello
+`
+      // This test may be skipped if YAML support is not implemented
+      try {
+        const result = parseUINode(yaml)
+        expect(result.type).toBe('text')
+        expect(result.props.content).toBe('Hello')
+      } catch (error) {
+        // YAML support is optional, so we don't fail the test suite
+        console.log('YAML support not implemented (optional)')
+      }
+    })
+
+    it('parses YAML with nested children', () => {
+      const yaml = `
+type: box
+props:
+  padding: 2
+children:
+  - type: text
+    props:
+      content: Child
+`
+      try {
+        const result = parseUINode(yaml)
+        expect(result.type).toBe('box')
+        expect(result.children![0].type).toBe('text')
+      } catch (error) {
+        console.log('YAML support not implemented (optional)')
+      }
+    })
+
+    it('handles YAML multiline strings', () => {
+      const yaml = `
+type: text
+props:
+  content: |
+    Line 1
+    Line 2
+    Line 3
+`
+      try {
+        const result = parseUINode(yaml)
+        expect((result.props.content as string).includes('Line 1')).toBe(true)
+      } catch (error) {
+        console.log('YAML support not implemented (optional)')
+      }
+    })
+  })
+
+  describe('YAML error handling', () => {
+    it('throws ParseError for invalid YAML', () => {
+      const invalidYaml = `
+type: box
+props:
+  - invalid list syntax
+`
+      try {
+        expect(() => parseUINode(invalidYaml)).toThrow()
+      } catch (error) {
+        console.log('YAML support not implemented (optional)')
+      }
+    })
+  })
+})
+
+// ============================================================================
+// Roundtrip / Idempotency Tests
+// ============================================================================
+
+describe('parsing idempotency', () => {
+  it('parsing JSON-stringified UINode produces equivalent UINode', () => {
+    const original: UINode = {
+      type: 'box',
+      props: { padding: 2 },
+      children: [{ type: 'text', props: { content: 'Test' } }],
+      data: { value: 42 },
+      key: 'test-key',
+    }
+
+    const json = JSON.stringify(original)
+    const parsed = parseUINode(json)
+
+    expect(parsed.type).toBe(original.type)
+    expect(parsed.props).toEqual(original.props)
+    expect(parsed.children).toEqual(original.children)
+    expect(parsed.data).toEqual(original.data)
+    expect(parsed.key).toEqual(original.key)
+  })
+
+  it('validates parsed result against schema', () => {
+    const json = `{
+      "type": "component",
+      "props": { "prop1": "value" },
+      "children": [
+        { "type": "child", "props": {} }
+      ],
+      "data": { "records": [] },
+      "key": "unique-id"
+    }`
+
+    const parsed = parseUINode(json)
+    const validation = UINodeSchema.safeParse(parsed)
+
+    expect(validation.success).toBe(true)
+  })
+})