prev-cli 0.24.18 → 0.24.19

package/src/primitives/template-parser.test.ts

@@ -0,0 +1,297 @@
+// src/primitives/template-parser.test.ts
+import { test, expect, describe } from 'bun:test'
+import {
+  validateTemplate,
+  validateSlots,
+  extractRefs,
+  extractSlotNames,
+} from './template-parser'
+
+describe('validateTemplate', () => {
+  test('validates simple template with string root', () => {
+    const result = validateTemplate({
+      root: 'components/header',
+    })
+    expect(result.valid).toBe(true)
+    expect(result.errors).toHaveLength(0)
+  })
+
+  test('validates template with primitive root', () => {
+    const result = validateTemplate({
+      root: '$col(gap:lg)',
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  test('validates template with container and children', () => {
+    const result = validateTemplate({
+      root: {
+        type: '$col(gap:lg)',
+        children: {
+          header: 'components/header',
+          main: '$slot(main)',
+          footer: 'components/footer',
+        },
+      },
+    })
+    expect(result.valid).toBe(true)
+    expect(result.errors).toHaveLength(0)
+  })
+
+  test('validates nested containers', () => {
+    const result = validateTemplate({
+      root: {
+        type: '$col',
+        children: {
+          card: {
+            type: '$box(padding:lg)',
+            children: {
+              content: 'components/content',
+            },
+          },
+        },
+      },
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  test('rejects template without root', () => {
+    const result = validateTemplate({})
+    expect(result.valid).toBe(false)
+    expect(result.errors[0].message).toContain('root')
+  })
+
+  test('rejects container without type', () => {
+    const result = validateTemplate({
+      root: {
+        children: {
+          header: 'components/header',
+        },
+      },
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors[0].message).toContain('type')
+  })
+
+  test('rejects invalid primitive syntax', () => {
+    const result = validateTemplate({
+      root: '$col(gap:invalid)',
+    })
+    expect(result.valid).toBe(false)
+  })
+
+  test('rejects non-primitive type in container', () => {
+    const result = validateTemplate({
+      root: {
+        type: 'NotAPrimitive',
+        children: {},
+      },
+    })
+    expect(result.valid).toBe(false)
+  })
+
+  test('rejects invalid ref format', () => {
+    const result = validateTemplate({
+      root: 'invalid/path/format',
+    })
+    expect(result.valid).toBe(false)
+  })
+
+  test('rejects non-layout primitive with children', () => {
+    const result = validateTemplate({
+      root: {
+        type: '$text("hello")',
+        children: {
+          child: 'components/button',
+        },
+      },
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors[0].message).toContain('cannot have children')
+  })
+
+  test('rejects $spacer with children', () => {
+    const result = validateTemplate({
+      root: {
+        type: '$spacer',
+        children: {
+          child: 'components/button',
+        },
+      },
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors[0].message).toContain('cannot have children')
+  })
+
+  test('rejects $image with children', () => {
+    const result = validateTemplate({
+      root: {
+        type: '$image(src:url)',
+        children: {
+          child: 'components/button',
+        },
+      },
+    })
+    expect(result.valid).toBe(false)
+  })
+})
+
+describe('validateSlots', () => {
+  test('validates simple slots', () => {
+    const result = validateSlots({
+      main: {
+        default: 'components/home',
+        loading: 'components/spinner',
+      },
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  test('validates slots with defined states', () => {
+    const result = validateSlots(
+      {
+        form: {
+          default: 'components/login-form',
+          error: 'components/error-form',
+        },
+      },
+      ['default', 'error', 'success']
+    )
+    expect(result.valid).toBe(true)
+  })
+
+  test('rejects slots referencing undefined states', () => {
+    const result = validateSlots(
+      {
+        form: {
+          default: 'components/form',
+          nonexistent: 'components/other',
+        },
+      },
+      ['default', 'error']
+    )
+    expect(result.valid).toBe(false)
+    expect(result.errors[0].message).toContain('nonexistent')
+  })
+
+  test('rejects non-string slot content', () => {
+    const result = validateSlots({
+      main: {
+        default: { invalid: 'object' },
+      },
+    })
+    expect(result.valid).toBe(false)
+  })
+
+  test('accepts primitive as slot content', () => {
+    const result = validateSlots({
+      main: {
+        loading: '$text("Loading...")',
+      },
+    })
+    expect(result.valid).toBe(true)
+  })
+
+  test('rejects URL as slot content', () => {
+    const result = validateSlots({
+      main: {
+        default: 'https://example.com/image.jpg',
+      },
+    })
+    expect(result.valid).toBe(false)
+    expect(result.errors[0].message).toContain('Invalid ref format')
+  })
+
+  test('rejects invalid ref pattern in slot', () => {
+    const result = validateSlots({
+      main: {
+        default: 'random/path/with/many/parts',
+      },
+    })
+    expect(result.valid).toBe(false)
+  })
+})
+
+describe('extractRefs', () => {
+  test('extracts refs from template', () => {
+    const refs = extractRefs({
+      root: {
+        type: '$col',
+        children: {
+          header: 'components/header',
+          main: 'screens/main',
+          footer: 'components/footer',
+        },
+      },
+    })
+    expect(refs).toContain('components/header')
+    expect(refs).toContain('screens/main')
+    expect(refs).toContain('components/footer')
+  })
+
+  test('ignores primitives', () => {
+    const refs = extractRefs({
+      root: {
+        type: '$col',
+        children: {
+          spacer: '$spacer(xl)',
+          slot: '$slot(main)',
+        },
+      },
+    })
+    expect(refs).toHaveLength(0)
+  })
+
+  test('deduplicates refs', () => {
+    const refs = extractRefs({
+      root: {
+        type: '$col',
+        children: {
+          header1: 'components/header',
+          header2: 'components/header',
+        },
+      },
+    })
+    expect(refs).toHaveLength(1)
+  })
+})
+
+describe('extractSlotNames', () => {
+  test('extracts slot names from template', () => {
+    const slots = extractSlotNames({
+      root: {
+        type: '$col',
+        children: {
+          header: 'components/header',
+          main: '$slot(main)',
+          sidebar: '$slot(sidebar)',
+        },
+      },
+    })
+    expect(slots).toContain('main')
+    expect(slots).toContain('sidebar')
+    expect(slots).toHaveLength(2)
+  })
+
+  test('extracts slot from container type', () => {
+    const slots = extractSlotNames({
+      root: {
+        type: '$slot(content)',
+      },
+    })
+    expect(slots).toContain('content')
+  })
+
+  test('deduplicates slot names', () => {
+    const slots = extractSlotNames({
+      root: {
+        type: '$col',
+        children: {
+          slot1: '$slot(main)',
+          slot2: '$slot(main)',
+        },
+      },
+    })
+    expect(slots).toHaveLength(1)
+  })
+})

package/src/primitives/template-parser.ts

@@ -0,0 +1,374 @@
+// src/primitives/template-parser.ts
+// Parser for map-based template structures
+
+import {
+  isPrimitive,
+  isRef,
+  isContainerNode,
+  type TemplateNode,
+  type Template,
+} from './types'
+import { parsePrimitive, getPrimitiveType } from './parser'
+
+// Valid container primitive types that can have children
+const CONTAINER_TYPES = new Set(['$col', '$row', '$box'])
+
+// Strict ref pattern: type/id format
+const REF_PATTERN = /^(screens|components|flows|atlas)\/[a-z0-9-]+$/
+
+export interface TemplateParseError {
+  path: string
+  message: string
+}
+
+export interface TemplateParseResult {
+  valid: boolean
+  errors: TemplateParseError[]
+  warnings: TemplateParseError[]
+}
+
+/**
+ * Validate a template structure
+ */
+export function validateTemplate(template: unknown): TemplateParseResult {
+  const errors: TemplateParseError[] = []
+  const warnings: TemplateParseError[] = []
+
+  if (!template || typeof template !== 'object') {
+    errors.push({
+      path: '/template',
+      message: 'Template must be an object',
+    })
+    return { valid: false, errors, warnings }
+  }
+
+  const templateObj = template as Record<string, unknown>
+
+  if (!('root' in templateObj)) {
+    errors.push({
+      path: '/template',
+      message: 'Template must have a root node',
+    })
+    return { valid: false, errors, warnings }
+  }
+
+  // Validate the root node recursively
+  validateNode(templateObj.root, '/template/root', errors, warnings)
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+/**
+ * Validate a single template node (recursive)
+ */
+function validateNode(
+  node: unknown,
+  path: string,
+  errors: TemplateParseError[],
+  warnings: TemplateParseError[]
+): void {
+  // String leaf node: primitive or ref
+  if (typeof node === 'string') {
+    validateLeafValue(node, path, errors, warnings)
+    return
+  }
+
+  // Container node: { type: string, children: Record<string, node> }
+  if (typeof node === 'object' && node !== null) {
+    const nodeObj = node as Record<string, unknown>
+
+    if (!('type' in nodeObj)) {
+      errors.push({
+        path,
+        message: 'Container node must have a "type" field',
+      })
+      return
+    }
+
+    if (typeof nodeObj.type !== 'string') {
+      errors.push({
+        path: `${path}/type`,
+        message: 'Node type must be a string',
+      })
+      return
+    }
+
+    // Validate the type is a valid primitive
+    if (!isPrimitive(nodeObj.type)) {
+      errors.push({
+        path: `${path}/type`,
+        message: `Node type must be a primitive (start with $): ${nodeObj.type}`,
+      })
+    } else {
+      const parseResult = parsePrimitive(nodeObj.type)
+      if (!parseResult.success) {
+        errors.push({
+          path: `${path}/type`,
+          message: parseResult.error.message,
+        })
+      }
+    }
+
+    // Validate children if present
+    if ('children' in nodeObj) {
+      // First check if this primitive type can have children
+      const primitiveType = getPrimitiveType(nodeObj.type)
+      if (primitiveType && !CONTAINER_TYPES.has(primitiveType)) {
+        errors.push({
+          path: `${path}/children`,
+          message: `Primitive ${primitiveType} cannot have children. Only $col, $row, $box support children.`,
+        })
+      }
+
+      if (typeof nodeObj.children !== 'object' || nodeObj.children === null) {
+        errors.push({
+          path: `${path}/children`,
+          message: 'Children must be an object',
+        })
+      } else {
+        const children = nodeObj.children as Record<string, unknown>
+        for (const [childId, childNode] of Object.entries(children)) {
+          validateNode(childNode, `${path}/children/${childId}`, errors, warnings)
+        }
+      }
+    }
+
+    return
+  }
+
+  errors.push({
+    path,
+    message: `Invalid node type: expected string or object, got ${typeof node}`,
+  })
+}
+
+/**
+ * Validate a leaf value (primitive string or component ref)
+ */
+function validateLeafValue(
+  value: string,
+  path: string,
+  errors: TemplateParseError[],
+  warnings: TemplateParseError[]
+): void {
+  if (isPrimitive(value)) {
+    // Validate primitive syntax
+    const parseResult = parsePrimitive(value)
+    if (!parseResult.success) {
+      errors.push({
+        path,
+        message: parseResult.error.message,
+      })
+    }
+  } else if (isRef(value)) {
+    // Validate ref format
+    if (!REF_PATTERN.test(value)) {
+      errors.push({
+        path,
+        message: `Invalid ref format: ${value}. Expected format: type/id (e.g., components/button)`,
+      })
+    }
+  } else {
+    // Unknown format - could be a prop reference or literal
+    // Warn if it doesn't look like either
+    if (!value.match(/^[a-z][a-zA-Z0-9]*$/) && !value.startsWith('"') && !value.startsWith("'")) {
+      warnings.push({
+        path,
+        message: `Ambiguous value: ${value}. Use $primitive, type/ref, or a valid prop name.`,
+      })
+    }
+  }
+}
+
+/**
+ * Validate slots structure
+ */
+export function validateSlots(
+  slots: unknown,
+  definedStates?: string[]
+): TemplateParseResult {
+  const errors: TemplateParseError[] = []
+  const warnings: TemplateParseError[] = []
+
+  if (!slots || typeof slots !== 'object') {
+    errors.push({
+      path: '/slots',
+      message: 'Slots must be an object',
+    })
+    return { valid: false, errors, warnings }
+  }
+
+  const slotsObj = slots as Record<string, unknown>
+
+  for (const [slotName, stateMapping] of Object.entries(slotsObj)) {
+    if (typeof stateMapping !== 'object' || stateMapping === null) {
+      errors.push({
+        path: `/slots/${slotName}`,
+        message: 'Slot state mapping must be an object',
+      })
+      continue
+    }
+
+    const mapping = stateMapping as Record<string, unknown>
+
+    for (const [stateName, content] of Object.entries(mapping)) {
+      // Validate state name exists if states are defined
+      if (definedStates && definedStates.length > 0 && !definedStates.includes(stateName)) {
+        errors.push({
+          path: `/slots/${slotName}/${stateName}`,
+          message: `Unknown state "${stateName}". Defined states: ${definedStates.join(', ')}`,
+        })
+      }
+
+      // Validate content is a string ref or primitive
+      if (typeof content !== 'string') {
+        errors.push({
+          path: `/slots/${slotName}/${stateName}`,
+          message: 'Slot content must be a string (component ref)',
+        })
+      } else if (isPrimitive(content)) {
+        // Valid primitive - check syntax
+        const parseResult = parsePrimitive(content)
+        if (!parseResult.success) {
+          errors.push({
+            path: `/slots/${slotName}/${stateName}`,
+            message: parseResult.error.message,
+          })
+        }
+      } else if (isRef(content)) {
+        // Must match strict ref pattern
+        if (!REF_PATTERN.test(content)) {
+          errors.push({
+            path: `/slots/${slotName}/${stateName}`,
+            message: `Invalid ref format: ${content}. Expected type/id (e.g., components/button)`,
+          })
+        }
+      } else {
+        errors.push({
+          path: `/slots/${slotName}/${stateName}`,
+          message: `Invalid slot content: ${content}. Expected component ref or primitive.`,
+        })
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  }
+}
+
+/**
+ * Extract all component refs from a template
+ */
+export function extractRefs(template: unknown): string[] {
+  const refs: string[] = []
+  extractRefsFromNode(template, refs)
+  return [...new Set(refs)] // Deduplicate
+}
+
+function extractRefsFromNode(node: unknown, refs: string[]): void {
+  if (typeof node === 'string') {
+    if (isRef(node)) {
+      refs.push(node)
+    }
+    return
+  }
+
+  if (typeof node === 'object' && node !== null) {
+    const nodeObj = node as Record<string, unknown>
+
+    // Check root
+    if ('root' in nodeObj) {
+      extractRefsFromNode(nodeObj.root, refs)
+    }
+
+    // Check children
+    if ('children' in nodeObj && typeof nodeObj.children === 'object' && nodeObj.children !== null) {
+      const children = nodeObj.children as Record<string, unknown>
+      for (const childNode of Object.values(children)) {
+        extractRefsFromNode(childNode, refs)
+      }
+    }
+  }
+}
+
+/**
+ * Extract all slot names from a template
+ */
+export function extractSlotNames(template: unknown): string[] {
+  const slots: string[] = []
+  extractSlotsFromNode(template, slots)
+  return [...new Set(slots)]
+}
+
+function extractSlotsFromNode(node: unknown, slots: string[]): void {
+  if (typeof node === 'string') {
+    if (isPrimitive(node)) {
+      const primitiveType = getPrimitiveType(node)
+      if (primitiveType === '$slot') {
+        const parseResult = parsePrimitive(node)
+        if (parseResult.success && parseResult.primitive.type === '$slot') {
+          slots.push(parseResult.primitive.name)
+        }
+      }
+    }
+    return
+  }
+
+  if (typeof node === 'object' && node !== null) {
+    const nodeObj = node as Record<string, unknown>
+
+    // Check type
+    if ('type' in nodeObj && typeof nodeObj.type === 'string' && isPrimitive(nodeObj.type)) {
+      const primitiveType = getPrimitiveType(nodeObj.type)
+      if (primitiveType === '$slot') {
+        const parseResult = parsePrimitive(nodeObj.type)
+        if (parseResult.success && parseResult.primitive.type === '$slot') {
+          slots.push(parseResult.primitive.name)
+        }
+      }
+    }
+
+    // Check root
+    if ('root' in nodeObj) {
+      extractSlotsFromNode(nodeObj.root, slots)
+    }
+
+    // Check children
+    if ('children' in nodeObj && typeof nodeObj.children === 'object' && nodeObj.children !== null) {
+      const children = nodeObj.children as Record<string, unknown>
+      for (const childNode of Object.values(children)) {
+        extractSlotsFromNode(childNode, slots)
+      }
+    }
+  }
+}
+
+/**
+ * Flatten a template into a list of nodes with paths
+ */
+export function flattenTemplate(template: Template): Array<{ path: string; node: TemplateNode }> {
+  const result: Array<{ path: string; node: TemplateNode }> = []
+  flattenNode(template.root, '/root', result)
+  return result
+}
+
+function flattenNode(
+  node: TemplateNode,
+  path: string,
+  result: Array<{ path: string; node: TemplateNode }>
+): void {
+  result.push({ path, node })
+
+  if (isContainerNode(node) && node.children) {
+    for (const [childId, childNode] of Object.entries(node.children)) {
+      flattenNode(childNode, `${path}/${childId}`, result)
+    }
+  }
+}