@zhin.js/core 1.0.25 → 1.0.27

package/tests/cron.test.ts

@@ -276,13 +276,102 @@ describe('Cron定时任务系统测试', () => {
   })
 
   describe('Cron错误处理', () => {
-    it('should throw error for invalid cron expression that cannot determine next run', () => {
-      // 创建一个永远不会执行的 cron 表达式
-      // 例如：2月30日（不存在的日期）
+    it('should throw error for truly invalid cron expression', () => {
+      // 完全无效的 cron 表达式应该抛出错误
       expect(() => {
-        cron = new Cron('0 0 30 2 *', mockCallback)
-        cron.start()
+        cron = new Cron('not a valid cron', mockCallback)
+        cron.run()
       }).toThrow()
     })
+
+    it('should accept edge-case cron expression like Feb 30 without throwing', () => {
+      // 2月30日虽然不存在，但 cron 库接受该表达式（不会抛错）
+      expect(() => {
+        cron = new Cron('0 0 30 2 *', mockCallback)
+        cron.run()
+      }).not.toThrow()
+    })
+  })
+})
+
+// ============================================================================
+// CronFeature 补全测试
+// ============================================================================
+describe('CronFeature', () => {
+  let feature: import('../src/built/cron.js').CronFeature
+  let mockCallback: ReturnType<typeof vi.fn>
+
+  beforeEach(async () => {
+    vi.useFakeTimers()
+    mockCallback = vi.fn()
+    const { CronFeature } = await import('../src/built/cron.js')
+    feature = new CronFeature()
+  })
+
+  afterEach(() => {
+    feature?.dispose()
+    vi.useRealTimers()
+  })
+
+  it('add 应自动启动任务', () => {
+    const cron = new Cron('* * * * * *', mockCallback)
+    feature.add(cron, 'test-plugin')
+    expect(cron.running).toBe(true)
+    expect(feature.items).toHaveLength(1)
+  })
+
+  it('add 应返回 dispose 函数', () => {
+    const cron = new Cron('* * * * * *', mockCallback)
+    const dispose = feature.add(cron, 'test-plugin')
+    expect(typeof dispose).toBe('function')
+  })
+
+  it('remove 应自动停止任务', () => {
+    const cron = new Cron('* * * * * *', mockCallback)
+    feature.add(cron, 'test-plugin')
+    feature.remove(cron)
+    expect(cron.running).toBe(false)
+    expect(feature.items).toHaveLength(0)
+  })
+
+  it('stopAll 应停止所有任务', () => {
+    const cron1 = new Cron('* * * * * *', mockCallback)
+    const cron2 = new Cron('*/2 * * * * *', mockCallback)
+    feature.add(cron1, 'p1')
+    feature.add(cron2, 'p2')
+
+    feature.stopAll()
+    expect(cron1.running).toBe(false)
+    expect(cron2.running).toBe(false)
+  })
+
+  it('startAll 应启动所有已停止的任务', () => {
+    const cron1 = new Cron('* * * * * *', mockCallback)
+    const cron2 = new Cron('*/2 * * * * *', mockCallback)
+    feature.add(cron1, 'p1')
+    feature.add(cron2, 'p2')
+    feature.stopAll()
+
+    feature.startAll()
+    expect(cron1.running).toBe(true)
+    expect(cron2.running).toBe(true)
+  })
+
+  it('toJSON 应返回正确结构', () => {
+    const cron = new Cron('* * * * * *', mockCallback)
+    feature.add(cron, 'test-plugin')
+    const json = feature.toJSON()
+    expect(json.name).toBe('cron')
+    expect(json.icon).toBe('Clock')
+    expect(json.count).toBe(1)
+    expect(json.items[0]).toHaveProperty('expression')
+    expect(json.items[0]).toHaveProperty('running', true)
+  })
+
+  it('dispose 应停止所有任务', () => {
+    const cron = new Cron('* * * * * *', mockCallback)
+    feature.add(cron, 'test-plugin')
+    feature.dispose()
+    expect(cron.running).toBe(false)
   })
 })

package/tests/dispatcher.test.ts

@@ -0,0 +1,146 @@
+/**
+ * MessageDispatcher 测试
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createMessageDispatcher, type MessageDispatcherService, type RouteResult } from '../src/built/dispatcher.js';
+import type { Message } from '../src/message.js';
+
+function makeMessage(text: string, overrides: Partial<Message<any>> = {}): Message<any> {
+  return {
+    $id: '1',
+    $content: [{ type: 'text', data: { text } }],
+    $raw: text,
+    $sender: { id: 'user1', name: 'User' },
+    $channel: { id: 'ch1', type: 'group' },
+    $adapter: 'test',
+    $bot: 'bot1',
+    $timestamp: Date.now(),
+    $reply: vi.fn(),
+    $recall: vi.fn(),
+    ...overrides,
+  } as any;
+}
+
+describe('createMessageDispatcher', () => {
+  let context: ReturnType<typeof createMessageDispatcher>;
+  let service: MessageDispatcherService;
+
+  beforeEach(() => {
+    context = createMessageDispatcher();
+    service = context.value;
+  });
+
+  it('应返回正确的 context 结构', () => {
+    expect(context.name).toBe('dispatcher');
+    expect(context.description).toContain('消息调度器');
+    expect(context.value).toBeDefined();
+    expect(typeof context.value.dispatch).toBe('function');
+    expect(typeof context.value.addGuardrail).toBe('function');
+    expect(typeof context.value.setCommandMatcher).toBe('function');
+    expect(typeof context.value.setAITriggerMatcher).toBe('function');
+    expect(typeof context.value.setAIHandler).toBe('function');
+    expect(typeof context.value.hasAIHandler).toBe('function');
+  });
+
+  describe('Guardrail', () => {
+    it('应能添加和移除 Guardrail', () => {
+      const guardrail = vi.fn(async (_msg: any, next: any) => next());
+      const remove = service.addGuardrail(guardrail);
+
+      expect(typeof remove).toBe('function');
+      remove();
+    });
+
+    it('Guardrail 应在 dispatch 中执行', async () => {
+      const calls: string[] = [];
+
+      service.addGuardrail(async (_msg, next) => {
+        calls.push('g1');
+        await next();
+      });
+      service.addGuardrail(async (_msg, next) => {
+        calls.push('g2');
+        await next();
+      });
+
+      const msg = makeMessage('hello');
+      await service.dispatch(msg);
+
+      expect(calls).toEqual(['g1', 'g2']);
+    });
+
+    it('Guardrail 抛异常应拦截消息', async () => {
+      service.addGuardrail(async () => {
+        throw new Error('blocked');
+      });
+
+      const aiHandler = vi.fn();
+      service.setAIHandler(aiHandler);
+      service.setAITriggerMatcher(() => ({ triggered: true, content: 'test' }));
+
+      const msg = makeMessage('hello');
+      await service.dispatch(msg);
+
+      expect(aiHandler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('AI Handler', () => {
+    it('初始无 AI handler', () => {
+      expect(service.hasAIHandler()).toBe(false);
+    });
+
+    it('注册后 hasAIHandler 返回 true', () => {
+      service.setAIHandler(async () => {});
+      expect(service.hasAIHandler()).toBe(true);
+    });
+
+    it('AI 触发时应调用 handler', async () => {
+      const handler = vi.fn();
+      service.setAIHandler(handler);
+      service.setAITriggerMatcher((msg) => ({
+        triggered: true,
+        content: 'processed content',
+      }));
+
+      const msg = makeMessage('你好');
+      await service.dispatch(msg);
+
+      expect(handler).toHaveBeenCalledWith(msg, 'processed content');
+    });
+
+    it('AI 不触发时不应调用 handler', async () => {
+      const handler = vi.fn();
+      service.setAIHandler(handler);
+      service.setAITriggerMatcher(() => ({ triggered: false, content: '' }));
+
+      const msg = makeMessage('random');
+      await service.dispatch(msg);
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Command Matcher', () => {
+    it('自定义命令匹配器应优先', async () => {
+      const aiHandler = vi.fn();
+      service.setAIHandler(aiHandler);
+      service.setAITriggerMatcher(() => ({ triggered: true, content: '' }));
+
+      // 设置命令匹配器：以 / 开头视为命令
+      service.setCommandMatcher((text) => text.startsWith('/'));
+
+      const msg = makeMessage('/help');
+      await service.dispatch(msg);
+
+      // 命令路径不应触发 AI
+      expect(aiHandler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('extensions', () => {
+    it('应提供 addGuardrail 扩展', () => {
+      expect(typeof context.extensions.addGuardrail).toBe('function');
+    });
+  });
+});

package/tests/feature.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Feature 基类测试
+ */
+import { describe, it, expect } from 'vitest';
+import { Feature, FeatureJSON } from '../src/feature.js';
+
+// 创建一个具体的 Feature 子类用于测试
+class TestFeature extends Feature<{ id: string; value: number }> {
+  readonly name = 'test';
+  readonly icon = 'TestIcon';
+  readonly desc = '测试 Feature';
+
+  toJSON(pluginName?: string): FeatureJSON {
+    const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+    return {
+      name: this.name,
+      icon: this.icon,
+      desc: this.desc,
+      count: list.length,
+      items: list.map(item => ({ id: item.id, value: item.value })),
+    };
+  }
+}
+
+describe('Feature 基类', () => {
+  describe('add / remove / getAll', () => {
+    it('应该能添加 item 并返回 dispose 函数', () => {
+      const feature = new TestFeature();
+      const item = { id: 'a', value: 1 };
+      const dispose = feature.add(item, 'plugin-a');
+
+      expect(feature.items).toHaveLength(1);
+      expect(feature.items[0]).toBe(item);
+      expect(typeof dispose).toBe('function');
+    });
+
+    it('dispose 函数应移除 item', () => {
+      const feature = new TestFeature();
+      const item = { id: 'a', value: 1 };
+      const dispose = feature.add(item, 'plugin-a');
+
+      dispose();
+      expect(feature.items).toHaveLength(0);
+    });
+
+    it('remove 应返回 true 并移除 item', () => {
+      const feature = new TestFeature();
+      const item = { id: 'a', value: 1 };
+      feature.add(item, 'plugin-a');
+
+      const result = feature.remove(item);
+      expect(result).toBe(true);
+      expect(feature.items).toHaveLength(0);
+    });
+
+    it('remove 不存在的 item 应返回 false', () => {
+      const feature = new TestFeature();
+      const result = feature.remove({ id: 'nonexistent', value: 0 });
+      expect(result).toBe(false);
+    });
+
+    it('应支持多个 item', () => {
+      const feature = new TestFeature();
+      feature.add({ id: 'a', value: 1 }, 'plugin-a');
+      feature.add({ id: 'b', value: 2 }, 'plugin-b');
+      feature.add({ id: 'c', value: 3 }, 'plugin-a');
+
+      expect(feature.items).toHaveLength(3);
+      expect(feature.count).toBe(3);
+    });
+  });
+
+  describe('插件追踪: getByPlugin / countByPlugin', () => {
+    it('应按插件名分组 items', () => {
+      const feature = new TestFeature();
+      feature.add({ id: 'a', value: 1 }, 'plugin-a');
+      feature.add({ id: 'b', value: 2 }, 'plugin-b');
+      feature.add({ id: 'c', value: 3 }, 'plugin-a');
+
+      const pluginAItems = feature.getByPlugin('plugin-a');
+      expect(pluginAItems).toHaveLength(2);
+      expect(pluginAItems.map(i => i.id)).toEqual(['a', 'c']);
+
+      const pluginBItems = feature.getByPlugin('plugin-b');
+      expect(pluginBItems).toHaveLength(1);
+      expect(pluginBItems[0].id).toBe('b');
+    });
+
+    it('不存在的插件应返回空数组', () => {
+      const feature = new TestFeature();
+      expect(feature.getByPlugin('nonexistent')).toEqual([]);
+    });
+
+    it('countByPlugin 应返回正确数量', () => {
+      const feature = new TestFeature();
+      feature.add({ id: 'a', value: 1 }, 'plugin-a');
+      feature.add({ id: 'b', value: 2 }, 'plugin-a');
+
+      expect(feature.countByPlugin('plugin-a')).toBe(2);
+      expect(feature.countByPlugin('plugin-b')).toBe(0);
+    });
+
+    it('remove 应同时从 pluginItems 中移除', () => {
+      const feature = new TestFeature();
+      const item = { id: 'a', value: 1 };
+      feature.add(item, 'plugin-a');
+      feature.remove(item);
+
+      expect(feature.getByPlugin('plugin-a')).toHaveLength(0);
+    });
+  });
+
+  describe('toJSON 序列化', () => {
+    it('无参数时返回全部 items', () => {
+      const feature = new TestFeature();
+      feature.add({ id: 'a', value: 1 }, 'plugin-a');
+      feature.add({ id: 'b', value: 2 }, 'plugin-b');
+
+      const json = feature.toJSON();
+      expect(json.name).toBe('test');
+      expect(json.icon).toBe('TestIcon');
+      expect(json.desc).toBe('测试 Feature');
+      expect(json.count).toBe(2);
+      expect(json.items).toHaveLength(2);
+    });
+
+    it('传 pluginName 时只返回该插件的 items', () => {
+      const feature = new TestFeature();
+      feature.add({ id: 'a', value: 1 }, 'plugin-a');
+      feature.add({ id: 'b', value: 2 }, 'plugin-b');
+
+      const json = feature.toJSON('plugin-a');
+      expect(json.count).toBe(1);
+      expect(json.items).toHaveLength(1);
+      expect(json.items[0].id).toBe('a');
+    });
+  });
+
+  describe('extensions getter', () => {
+    it('默认返回空对象', () => {
+      const feature = new TestFeature();
+      expect(feature.extensions).toEqual({});
+    });
+  });
+});

package/tests/features-builtin.test.ts

@@ -0,0 +1,191 @@
+/**
+ * 内置 Feature 测试
+ * DatabaseFeature / PermissionFeature / ComponentFeature
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { PermissionFeature, Permissions } from '../src/built/permission.js';
+import { ComponentFeature } from '../src/built/component.js';
+import type { Message, MessageBase } from '../src/message.js';
+
+// ============================================================================
+// PermissionFeature 测试
+// ============================================================================
+
+describe('PermissionFeature', () => {
+  let feature: PermissionFeature;
+
+  beforeEach(() => {
+    feature = new PermissionFeature();
+  });
+
+  function makeMessage(overrides: Partial<MessageBase> = {}): Message<any> {
+    return {
+      $id: '1',
+      $adapter: 'test' as any,
+      $bot: 'bot1',
+      $content: [],
+      $raw: '',
+      $sender: { id: 'user1', name: 'User' },
+      $channel: { id: 'ch1', type: 'group' },
+      $timestamp: Date.now(),
+      $reply: vi.fn(),
+      $recall: vi.fn(),
+      ...overrides,
+    } as any;
+  }
+
+  it('应有正确的元数据', () => {
+    expect(feature.name).toBe('permission');
+    expect(feature.icon).toBe('Shield');
+    expect(feature.desc).toBe('权限');
+  });
+
+  it('构造时应注册内置权限检查器', () => {
+    // 构造时已注册 adapter(), group(), private(), channel(), user() 检查器
+    expect(feature.items.length).toBeGreaterThanOrEqual(5);
+  });
+
+  describe('check', () => {
+    it('adapter() 匹配应返回 true', async () => {
+      const msg = makeMessage({ $adapter: 'qq' as any });
+      expect(await feature.check('adapter(qq)', msg)).toBe(true);
+    });
+
+    it('adapter() 不匹配应返回 false', async () => {
+      const msg = makeMessage({ $adapter: 'qq' as any });
+      expect(await feature.check('adapter(discord)', msg)).toBe(false);
+    });
+
+    it('group() 匹配应返回 true', async () => {
+      const msg = makeMessage({ $channel: { id: 'g1', type: 'group' } });
+      expect(await feature.check('group(g1)', msg)).toBe(true);
+    });
+
+    it('group(*) 通配应返回 true', async () => {
+      const msg = makeMessage({ $channel: { id: 'g123', type: 'group' } });
+      expect(await feature.check('group(*)', msg)).toBe(true);
+    });
+
+    it('private() 匹配应返回 true', async () => {
+      const msg = makeMessage({ $channel: { id: 'p1', type: 'private' } });
+      expect(await feature.check('private(p1)', msg)).toBe(true);
+    });
+
+    it('user() 匹配应返回 true', async () => {
+      const msg = makeMessage({ $sender: { id: 'u1', name: 'U' } });
+      expect(await feature.check('user(u1)', msg)).toBe(true);
+    });
+
+    it('user() 不匹配应返回 false', async () => {
+      const msg = makeMessage({ $sender: { id: 'u1', name: 'U' } });
+      expect(await feature.check('user(u2)', msg)).toBe(false);
+    });
+
+    it('未注册的权限名应返回 false', async () => {
+      const msg = makeMessage();
+      expect(await feature.check('unknown_permission', msg)).toBe(false);
+    });
+  });
+
+  describe('自定义权限', () => {
+    it('应能添加自定义权限检查器', async () => {
+      const perm = Permissions.define('admin', (_name, msg) => {
+        return msg.$sender.id === 'admin_user';
+      });
+
+      feature.add(perm, 'test-plugin');
+
+      const adminMsg = makeMessage({ $sender: { id: 'admin_user', name: 'Admin' } });
+      const normalMsg = makeMessage({ $sender: { id: 'normal_user', name: 'Normal' } });
+
+      expect(await feature.check('admin', adminMsg)).toBe(true);
+      expect(await feature.check('admin', normalMsg)).toBe(false);
+    });
+  });
+
+  describe('toJSON', () => {
+    it('应序列化所有权限', () => {
+      const json = feature.toJSON();
+      expect(json.name).toBe('permission');
+      expect(json.count).toBeGreaterThan(0);
+    });
+
+    it('应按插件名过滤', () => {
+      feature.add(Permissions.define('custom', () => true), 'my-plugin');
+      const json = feature.toJSON('my-plugin');
+      expect(json.count).toBe(1);
+    });
+  });
+});
+
+// ============================================================================
+// ComponentFeature 测试
+// ============================================================================
+
+describe('ComponentFeature', () => {
+  let feature: ComponentFeature;
+
+  beforeEach(() => {
+    feature = new ComponentFeature();
+  });
+
+  const mockComponent = {
+    name: 'test-component',
+    render: () => ({ type: 'text', data: { text: 'test' } }),
+  } as any;
+
+  it('应有正确的元数据', () => {
+    expect(feature.name).toBe('component');
+    expect(feature.icon).toBe('Box');
+    expect(feature.desc).toBe('组件');
+  });
+
+  it('add 应添加组件', () => {
+    feature.add(mockComponent, 'test-plugin');
+    expect(feature.items).toHaveLength(1);
+    expect(feature.byName.get('test-component')).toBe(mockComponent);
+  });
+
+  it('remove 应移除组件', () => {
+    feature.add(mockComponent, 'test-plugin');
+    feature.remove(mockComponent);
+    expect(feature.items).toHaveLength(0);
+    expect(feature.byName.has('test-component')).toBe(false);
+  });
+
+  it('get 应按名称获取', () => {
+    feature.add(mockComponent, 'test-plugin');
+    expect(feature.get('test-component')).toBe(mockComponent);
+    expect(feature.get('nonexistent')).toBeUndefined();
+  });
+
+  it('getAllNames 应返回所有名称', () => {
+    feature.add(mockComponent, 'test-plugin');
+    feature.add({ name: 'another', render: () => null } as any, 'test-plugin');
+    expect(feature.getAllNames()).toEqual(['test-component', 'another']);
+  });
+
+  describe('toJSON', () => {
+    it('应返回正确结构', () => {
+      feature.add(mockComponent, 'test-plugin');
+      const json = feature.toJSON();
+      expect(json.name).toBe('component');
+      expect(json.count).toBe(1);
+      expect(json.items[0]).toEqual({ name: 'test-component', type: 'component' });
+    });
+
+    it('按插件名过滤', () => {
+      feature.add(mockComponent, 'plugin-a');
+      feature.add({ name: 'other', render: () => null } as any, 'plugin-b');
+      const json = feature.toJSON('plugin-a');
+      expect(json.count).toBe(1);
+    });
+  });
+});
+
+// ============================================================================
+// DatabaseFeature 说明
+// ============================================================================
+// DatabaseFeature 需要实际数据库连接（sqlite3 等），测试跳过。
+// 其核心逻辑（add/remove/toJSON）已由 Feature 基类测试覆盖。
+// 数据库相关测试见 basic/database/ 目录。