@variojs/core 0.1.0

package/__tests__/README.md

@@ -0,0 +1,101 @@
+# Vario Core 测试说明
+
+## 快速开始
+
+```bash
+# 运行所有测试
+pnpm test
+
+# 监听模式
+pnpm test:watch
+
+# 生成覆盖率
+pnpm test -- --coverage
+```
+
+## 测试结构
+
+```
+__tests__/
+├── runtime/              # RuntimeContext 相关测试
+│   └── create-context.test.ts
+├── expression/           # 表达式系统测试
+│   ├── evaluate.test.ts  # 表达式求值
+│   ├── parser.test.ts    # 表达式解析
+│   ├── whitelist.test.ts # AST 白名单验证
+│   └── cache.test.ts     # 表达式缓存
+└── vm/                   # Instruction VM 测试
+    ├── executor.test.ts  # 指令执行器
+    └── handlers/
+        └── call.test.ts  # call 指令处理器
+```
+
+## 测试编写要点
+
+### 1. 测试命名
+- 使用中文描述测试行为（符合项目规范）
+- 格式：`应该 + 行为描述`
+
+### 2. 测试组织
+- 使用 `describe` 组织相关测试
+- 使用 `beforeEach` 共享测试设置
+- 每个测试独立，不依赖其他测试
+
+### 3. 常见测试模式
+
+#### 正常流程测试
+```typescript
+it('应该执行 set 指令', async () => {
+  await execute([{ op: 'set', path: 'count', value: 10 }], ctx)
+  expect(ctx.count).toBe(10)
+})
+```
+
+#### 错误处理测试
+```typescript
+it('应该在未知指令时抛出错误', async () => {
+  await expect(
+    execute([{ op: 'unknown' }], ctx)
+  ).rejects.toThrow('Unknown op')
+})
+```
+
+#### 边界条件测试
+```typescript
+it('应该处理空数组', () => {
+  const result = evaluate('items.length', ctx)
+  expect(result).toBe(0)
+})
+```
+
+## 运行特定测试
+
+```bash
+# 运行单个文件
+pnpm test __tests__/runtime/create-context.test.ts
+
+# 运行匹配的测试
+pnpm test -- -t "应该创建基本的运行时上下文"
+
+# 详细输出
+pnpm test -- --reporter=verbose
+```
+
+## 调试测试
+
+在测试中使用 `console.log` 或断点调试：
+
+```typescript
+it('调试测试', () => {
+  console.log('调试信息:', ctx)
+  debugger  // 在支持的环境中会暂停
+  expect(ctx.user).toBeDefined()
+})
+```
+
+## 注意事项
+
+1. **测试隔离**: 每个测试应该独立运行，不依赖执行顺序
+2. **清理状态**: 使用 `beforeEach` 重置状态，避免测试间污染
+3. **异步测试**: 使用 `async/await` 处理异步操作
+4. **类型安全**: 测试代码也应该遵循 TypeScript 类型检查

package/__tests__/errors.test.ts

@@ -0,0 +1,139 @@
+/**
+ * 错误处理体系测试
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  VarioError,
+  ActionError,
+  ExpressionError,
+  ServiceError,
+  BatchError,
+  ErrorCodes
+} from '../src/errors.js'
+import type { Action } from '../src/types.js'
+
+describe('错误处理体系', () => {
+  describe('VarioError', () => {
+    it('应该创建基础错误', () => {
+      const error = new VarioError('Test error', 'TEST_ERROR', {
+        metadata: { key: 'value' }
+      })
+      
+      expect(error.message).toBe('Test error')
+      expect(error.code).toBe('TEST_ERROR')
+      expect(error.context.metadata).toEqual({ key: 'value' })
+      expect(error.name).toBe('VarioError')
+    })
+
+    it('应该生成友好的错误消息', () => {
+      const error = new VarioError('Test error', 'TEST_ERROR', {
+        schemaPath: 'events.click[0]',
+        expression: 'user.name',
+        action: { type: 'set' } as Action
+      })
+      
+      const friendly = error.getFriendlyMessage()
+      expect(friendly).toContain('Test error')
+      expect(friendly).toContain('Schema 路径: events.click[0]')
+      expect(friendly).toContain('表达式: user.name')
+      expect(friendly).toContain('动作类型: set')
+    })
+
+    it('应该转换为 JSON', () => {
+      const error = new VarioError('Test error', 'TEST_ERROR', {
+        metadata: { key: 'value' }
+      })
+      
+      const json = error.toJSON()
+      expect(json.name).toBe('VarioError')
+      expect(json.message).toBe('Test error')
+      expect(json.code).toBe('TEST_ERROR')
+      expect(json.context).toBeDefined()
+    })
+  })
+
+  describe('ActionError', () => {
+    it('应该创建动作错误', () => {
+      const action: Action = { type: 'set', path: 'count' }
+      const error = new ActionError(
+        action,
+        'Action failed',
+        ErrorCodes.ACTION_EXECUTION_ERROR,
+        { metadata: { param: 'path' } }
+      )
+      
+      expect(error.message).toBe('Action failed')
+      expect(error.code).toBe(ErrorCodes.ACTION_EXECUTION_ERROR)
+      expect(error.context.action).toBe(action)
+      expect(error.context.metadata).toEqual({ param: 'path' })
+    })
+  })
+
+  describe('ExpressionError', () => {
+    it('应该创建表达式错误', () => {
+      const error = new ExpressionError(
+        'user.name',
+        'Expression failed',
+        ErrorCodes.EXPRESSION_EVALUATION_ERROR,
+        { metadata: { nodeType: 'Identifier' } }
+      )
+      
+      expect(error.message).toBe('Expression failed')
+      expect(error.code).toBe(ErrorCodes.EXPRESSION_EVALUATION_ERROR)
+      expect(error.context.expression).toBe('user.name')
+      expect(error.context.metadata).toEqual({ nodeType: 'Identifier' })
+    })
+  })
+
+  describe('ServiceError', () => {
+    it('应该创建服务错误', () => {
+      const originalError = new Error('Original error')
+      const error = new ServiceError(
+        'test.service',
+        'Service call failed',
+        originalError,
+        { metadata: { method: 'test.service' } }
+      )
+      
+      expect(error.service).toBe('test.service')
+      expect(error.message).toBe('Service call failed')
+      expect(error.originalError).toBe(originalError)
+      expect(error.context.metadata).toEqual({ method: 'test.service' })
+    })
+  })
+
+  describe('BatchError', () => {
+    it('应该创建批量错误', () => {
+      const action1: Action = { type: 'set', path: 'a' }
+      const action2: Action = { type: 'set', path: 'b' }
+      const error1 = new Error('Error 1')
+      const error2 = new Error('Error 2')
+      
+      const error = new BatchError(
+        [
+          { action: action1, error: error1 },
+          { action: action2, error: error2 }
+        ],
+        'Batch failed',
+        { metadata: { failedCount: 2 } }
+      )
+      
+      expect(error.message).toBe('Batch failed')
+      expect(error.failedActions).toHaveLength(2)
+      expect(error.failedActions[0].action).toBe(action1)
+      expect(error.failedActions[1].action).toBe(action2)
+    })
+  })
+
+  describe('ErrorCodes', () => {
+    it('应该包含所有错误码', () => {
+      expect(ErrorCodes.ACTION_UNKNOWN_TYPE).toBe('ACTION_UNKNOWN_TYPE')
+      expect(ErrorCodes.ACTION_EXECUTION_ERROR).toBe('ACTION_EXECUTION_ERROR')
+      expect(ErrorCodes.EXPRESSION_PARSE_ERROR).toBe('EXPRESSION_PARSE_ERROR')
+      expect(ErrorCodes.EXPRESSION_VALIDATION_ERROR).toBe('EXPRESSION_VALIDATION_ERROR')
+      expect(ErrorCodes.SERVICE_NOT_FOUND).toBe('SERVICE_NOT_FOUND')
+      expect(ErrorCodes.BATCH_ERROR).toBe('BATCH_ERROR')
+    })
+  })
+})

package/__tests__/expression/cache.test.ts

@@ -0,0 +1,118 @@
+/**
+ * 表达式缓存系统测试
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createRuntimeContext } from '../../src/runtime/create-context'
+import { evaluate } from '../../src/expression/evaluate'
+import {
+  getCachedExpression,
+  setCachedExpression,
+  invalidateCache,
+  clearCache
+} from '../../src/expression/cache'
+import { registerBuiltinMethods } from '../../src/vm/handlers'
+
+describe('表达式缓存系统', () => {
+  let ctx: ReturnType<typeof createRuntimeContext>
+  
+  beforeEach(() => {
+    ctx = createRuntimeContext({
+      user: { name: 'John', age: 30 },
+      items: [1, 2, 3],
+      count: 0
+    })
+    registerBuiltinMethods(ctx)
+  })
+  
+  it('应该缓存表达式结果', () => {
+    const expr = 'user.age + 10'
+    const result = evaluate(expr, ctx)
+    
+    // 第二次求值应该使用缓存
+    const cached = getCachedExpression(expr, ctx)
+    expect(cached).toBe(result)
+    expect(cached).toBe(40)
+  })
+  
+  it('应该手动设置缓存', () => {
+    const expr = 'test.expression'
+    const result = 123
+    const dependencies = ['user.name']
+    
+    setCachedExpression(expr, result, dependencies, ctx)
+    
+    const cached = getCachedExpression(expr, ctx)
+    expect(cached).toBe(123)
+  })
+  
+  it('应该在依赖变化时使缓存失效', () => {
+    const expr = 'user.name'
+    const result1 = evaluate(expr, ctx)
+    expect(result1).toBe('John')
+    
+    // 验证缓存存在
+    const cached1 = getCachedExpression(expr, ctx)
+    expect(cached1).toBe('John')
+    
+    // 修改依赖的状态
+    ctx._set('user.name', 'Jane')
+    invalidateCache('user.name', ctx)
+    
+    // 缓存应该失效
+    const cached2 = getCachedExpression(expr, ctx)
+    expect(cached2).toBeNull()
+  })
+  
+  it('应该支持通配符依赖失效', () => {
+    const expr = 'items[0]'
+    evaluate(expr, ctx)  // 创建缓存，依赖 items.*
+    
+    // 验证缓存存在
+    const cached1 = getCachedExpression(expr, ctx)
+    expect(cached1).toBe(1)
+    
+    // 修改数组元素
+    ctx._set('items.0', 999)
+    invalidateCache('items.0', ctx)
+    
+    // 缓存应该失效
+    const cached2 = getCachedExpression(expr, ctx)
+    expect(cached2).toBeNull()
+  })
+  
+  it('应该清除所有缓存', () => {
+    const expr1 = 'user.name'
+    const expr2 = 'user.age'
+    
+    evaluate(expr1, ctx)
+    evaluate(expr2, ctx)
+    
+    // 验证缓存存在
+    expect(getCachedExpression(expr1, ctx)).not.toBeNull()
+    expect(getCachedExpression(expr2, ctx)).not.toBeNull()
+    
+    // 清除所有缓存
+    clearCache(ctx)
+    
+    // 缓存应该都被清除
+    expect(getCachedExpression(expr1, ctx)).toBeNull()
+    expect(getCachedExpression(expr2, ctx)).toBeNull()
+  })
+  
+  it('应该在缓存已满时使用 LRU 淘汰', () => {
+    // 创建超过 MAX_CACHE_SIZE (100) 的缓存
+    for (let i = 0; i < 110; i++) {
+      const expr = `test.${i}`
+      setCachedExpression(expr, i, [], ctx)
+    }
+    
+    // 最旧的缓存应该被淘汰
+    const oldest = getCachedExpression('test.0', ctx)
+    expect(oldest).toBeNull()
+    
+    // 最新的缓存应该存在
+    const newest = getCachedExpression('test.109', ctx)
+    expect(newest).toBe(109)
+  })
+})

package/__tests__/expression/compiler.test.ts

@@ -0,0 +1,111 @@
+/**
+ * 表达式编译器测试
+ */
+
+import { describe, it, expect } from 'vitest'
+import { parseExpression } from '../../src/expression/parser.js'
+import {
+  compileSimpleExpression,
+  getCompiledExpression,
+  clearCompiledCache
+} from '../../src/expression/compiler.js'
+import { createRuntimeContext } from '../../src/runtime/create-context.js'
+
+describe('表达式编译器', () => {
+  beforeEach(() => {
+    clearCompiledCache()
+  })
+
+  describe('compileSimpleExpression', () => {
+    it('应该编译字面量表达式', () => {
+      const ast = parseExpression('42')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).not.toBeNull()
+      const ctx = createRuntimeContext()
+      expect(compiled!(ctx)).toBe(42)
+    })
+
+    it('应该编译字符串字面量', () => {
+      const ast = parseExpression('"hello"')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).not.toBeNull()
+      const ctx = createRuntimeContext()
+      expect(compiled!(ctx)).toBe('hello')
+    })
+
+    it('应该编译标识符表达式', () => {
+      const ast = parseExpression('user')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).not.toBeNull()
+      const ctx = createRuntimeContext({ user: { name: 'John' } })
+      expect(compiled!(ctx)).toEqual({ name: 'John' })
+    })
+
+    it('应该编译静态成员访问', () => {
+      const ast = parseExpression('user.name')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).not.toBeNull()
+      const ctx = createRuntimeContext({ user: { name: 'John' } })
+      expect(compiled!(ctx)).toBe('John')
+    })
+
+    it('应该编译嵌套成员访问', () => {
+      const ast = parseExpression('user.profile.avatar')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).not.toBeNull()
+      const ctx = createRuntimeContext({
+        user: { profile: { avatar: 'url' } }
+      })
+      expect(compiled!(ctx)).toBe('url')
+    })
+
+    it('应该编译数组索引访问', () => {
+      // 使用方括号语法，因为 items.0 在 JavaScript 中不是有效的属性访问
+      const ast = parseExpression('items[0]')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).not.toBeNull()
+      const ctx = createRuntimeContext({ items: ['a', 'b', 'c'] })
+      expect(compiled!(ctx)).toBe('a')
+    })
+
+    it('应该拒绝编译复杂表达式', () => {
+      const ast = parseExpression('user.name + 1')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).toBeNull()
+    })
+
+    it('应该拒绝编译函数调用', () => {
+      const ast = parseExpression('Math.max(1, 2)')
+      const compiled = compileSimpleExpression(ast)
+      
+      expect(compiled).toBeNull()
+    })
+  })
+
+  describe('getCompiledExpression', () => {
+    it('应该缓存编译结果', () => {
+      const expr = 'user.name'
+      const ast = parseExpression(expr)
+      
+      const compiled1 = getCompiledExpression(expr, ast)
+      const compiled2 = getCompiledExpression(expr, ast)
+      
+      expect(compiled1).toBe(compiled2)
+    })
+
+    it('应该为无法编译的表达式返回 null', () => {
+      const expr = 'user.name + 1'
+      const ast = parseExpression(expr)
+      
+      const compiled = getCompiledExpression(expr, ast)
+      expect(compiled).toBeNull()
+    })
+  })
+})

package/__tests__/expression/evaluate.test.ts

@@ -0,0 +1,95 @@
+/**
+ * 表达式求值测试
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createRuntimeContext } from '../../src/runtime/create-context'
+import { evaluate } from '../../src/expression/evaluate'
+import { registerBuiltinMethods } from '../../src/vm/handlers'
+
+describe('表达式求值', () => {
+  let ctx: ReturnType<typeof createRuntimeContext>
+  
+  beforeEach(() => {
+    ctx = createRuntimeContext({
+      user: { name: 'John', age: 30 },
+      items: [1, 2, 3],
+      count: 0
+    })
+    registerBuiltinMethods(ctx)
+  })
+  
+  it('应该求值字面量', () => {
+    expect(evaluate('123', ctx)).toBe(123)
+    expect(evaluate('"hello"', ctx)).toBe('hello')
+    expect(evaluate('true', ctx)).toBe(true)
+  })
+  
+  it('应该求值标识符（直接属性访问）', () => {
+    expect(evaluate('user.name', ctx)).toBe('John')
+    expect(evaluate('user.age', ctx)).toBe(30)
+    expect(evaluate('count', ctx)).toBe(0)
+  })
+  
+  it('应该求值成员访问', () => {
+    expect(evaluate('user.name', ctx)).toBe('John')
+    expect(evaluate('items[0]', ctx)).toBe(1)
+  })
+  
+  it('应该求值二元运算', () => {
+    expect(evaluate('1 + 2', ctx)).toBe(3)
+    expect(evaluate('user.age > 18', ctx)).toBe(true)
+    expect(evaluate('user.age === 30', ctx)).toBe(true)
+  })
+  
+  it('应该求值逻辑运算', () => {
+    expect(evaluate('true && false', ctx)).toBe(false)
+    expect(evaluate('true || false', ctx)).toBe(true)
+    expect(evaluate('user.age > 18 && user.name === "John"', ctx)).toBe(true)
+  })
+  
+  it('应该求值三元表达式', () => {
+    expect(evaluate('user.age > 18 ? "adult" : "minor"', ctx)).toBe('adult')
+  })
+  
+  it('应该求值空值合并', () => {
+    expect(evaluate('user.name ?? "unknown"', ctx)).toBe('John')
+    expect(evaluate('user.email ?? "no-email"', ctx)).toBe('no-email')
+  })
+  
+  it('应该求值函数调用（白名单）', () => {
+    expect(evaluate('Math.max(1, 2, 3)', ctx)).toBe(3)
+    expect(evaluate('Array.isArray(items)', ctx)).toBe(true)
+    expect(evaluate('String(user.age)', ctx)).toBe('30')
+  })
+  
+  it('应该拒绝禁止的语法', () => {
+    expect(() => evaluate('user.name = "Jane"', ctx)).toThrow()  // 赋值
+    expect(() => evaluate('user.age++', ctx)).toThrow()  // 自增
+    expect(() => evaluate('() => {}', ctx)).toThrow()  // 箭头函数
+  })
+  
+  it('应该拒绝访问全局对象', () => {
+    expect(() => evaluate('window', ctx)).toThrow()
+    expect(() => evaluate('document', ctx)).toThrow()
+  })
+
+  it('默认应拒绝未白名单的全局函数调用', () => {
+    ;(globalThis as any).__testFn = () => 42
+    expect(() => evaluate('__testFn()', ctx)).toThrow()
+    delete (globalThis as any).__testFn
+  })
+
+  it('开启 allowGlobals 时应允许任意全局函数调用', () => {
+    ;(globalThis as any).__testFn = () => 42
+    expect(evaluate('__testFn()', ctx, { allowGlobals: true })).toBe(42)
+    delete (globalThis as any).__testFn
+  })
+
+  it('开启 allowGlobals 时允许访问全局对象属性', () => {
+    ;(globalThis as any).__testVal = 7
+    expect(() => evaluate('globalThis.__testVal', ctx)).toThrow()
+    expect(evaluate('globalThis.__testVal', ctx, { allowGlobals: true })).toBe(7)
+    delete (globalThis as any).__testVal
+  })
+})

package/__tests__/expression/parser.test.ts

@@ -0,0 +1,57 @@
+/**
+ * 表达式解析器测试
+ */
+
+import { describe, it, expect } from 'vitest'
+import { parseExpression } from '../../src/expression/parser'
+import { ExpressionError } from '../../src/types'
+
+describe('表达式解析器', () => {
+  it('应该解析简单表达式', () => {
+    const ast = parseExpression('1 + 2')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('BinaryExpression')
+  })
+  
+  it('应该解析成员访问表达式', () => {
+    const ast = parseExpression('user.name')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('MemberExpression')
+  })
+  
+  it('应该解析函数调用表达式', () => {
+    const ast = parseExpression('Math.max(1, 2, 3)')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('CallExpression')
+  })
+  
+  it('应该解析三元表达式', () => {
+    const ast = parseExpression('age > 18 ? "adult" : "minor"')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('ConditionalExpression')
+  })
+  
+  it('应该在解析失败时抛出错误', () => {
+    expect(() => {
+      parseExpression('invalid syntax {')
+    }).toThrow()
+  })
+  
+  it('应该解析逻辑表达式', () => {
+    const ast = parseExpression('a && b || c')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('LogicalExpression')
+  })
+  
+  it('应该解析数组表达式', () => {
+    const ast = parseExpression('[1, 2, 3]')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('ArrayExpression')
+  })
+  
+  it('应该解析对象表达式', () => {
+    const ast = parseExpression('{ a: 1, b: 2 }')
+    expect(ast).toBeDefined()
+    expect(ast.type).toBe('ObjectExpression')
+  })
+})

package/__tests__/expression/whitelist.test.ts

@@ -0,0 +1,59 @@
+/**
+ * AST 白名单验证器测试
+ */
+
+import { describe, it, expect } from 'vitest'
+import { parseExpression } from '../../src/expression/parser'
+import { validateAST } from '../../src/expression/whitelist'
+import { ExpressionError } from '../../src/types'
+
+describe('AST 白名单验证', () => {
+  it('应该允许安全的表达式', () => {
+    const safeExpressions = [
+      '1 + 2',
+      'user.name',
+      'items[0]',
+      'age > 18',
+      'user.name ?? "unknown"',
+      'Math.max(1, 2)',
+      '[1, 2, 3]',
+      '{ a: 1, b: 2 }'
+    ]
+    
+    safeExpressions.forEach(expr => {
+      const ast = parseExpression(expr)
+      expect(() => validateAST(ast)).not.toThrow()
+    })
+  })
+  
+  it('应该拒绝赋值表达式', () => {
+    const ast = parseExpression('user.name = "Jane"')
+    expect(() => validateAST(ast)).toThrow(ExpressionError)
+  })
+  
+  it('应该拒绝自增/自减表达式', () => {
+    const ast = parseExpression('count++')
+    expect(() => validateAST(ast)).toThrow(ExpressionError)
+  })
+  
+  it('应该拒绝箭头函数', () => {
+    const ast = parseExpression('() => {}')
+    expect(() => validateAST(ast)).toThrow(ExpressionError)
+  })
+  
+  it('应该拒绝函数表达式', () => {
+    const ast = parseExpression('function() {}')
+    expect(() => validateAST(ast)).toThrow(ExpressionError)
+  })
+  
+  it('应该拒绝 new 表达式', () => {
+    const ast = parseExpression('new Date()')
+    expect(() => validateAST(ast)).toThrow(ExpressionError)
+  })
+  
+  it('应该拒绝 this 表达式', () => {
+    // this 在表达式上下文中可能无法解析，但如果有，应该被拒绝
+    // 注意：实际测试中，this 可能无法作为独立表达式解析
+    // 这里主要验证白名单机制工作正常
+  })
+})