@rangka/core 0.1.0 → 0.1.2

package/src/plugins/__tests__/loader.test.ts

@@ -1,273 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import {
-  loadPlugins,
-  DuplicatePluginError,
-  PluginConfigError,
-  MissingAdapterImplementationError,
-} from '../loader.js';
-import type { PluginDefinition, DataAdapter } from '../types.js';
-
-function makeAdapter(overrides?: Partial<DataAdapter>): DataAdapter {
-  return {
-    async get(_model: string, _id: string) {
-      return { id: '1' };
-    },
-    ...overrides,
-  };
-}
-
-describe('loadPlugins', () => {
-  describe('basic boot', () => {
-    it('calls boot on each plugin', async () => {
-      const boot = vi.fn();
-      const plugin: PluginDefinition = {
-        name: 'test-plugin',
-        version: '1.0.0',
-        boot,
-      };
-
-      await loadPlugins({ plugins: [plugin] });
-      expect(boot).toHaveBeenCalledOnce();
-    });
-
-    it('boots multiple plugins in order', async () => {
-      const order: string[] = [];
-      const pluginA: PluginDefinition = {
-        name: 'a',
-        version: '1.0.0',
-        boot() {
-          order.push('a');
-        },
-      };
-      const pluginB: PluginDefinition = {
-        name: 'b',
-        version: '1.0.0',
-        boot() {
-          order.push('b');
-        },
-      };
-
-      await loadPlugins({ plugins: [pluginA, pluginB] });
-      expect(order).toEqual(['a', 'b']);
-    });
-
-    it('supports async boot functions', async () => {
-      const plugin: PluginDefinition = {
-        name: 'async-plugin',
-        version: '1.0.0',
-        async boot() {
-          await new Promise((r) => setTimeout(r, 5));
-        },
-      };
-
-      await expect(loadPlugins({ plugins: [plugin] })).resolves.toBeDefined();
-    });
-  });
-
-  describe('config resolution', () => {
-    it('passes user config to boot context', async () => {
-      let receivedConfig: Record<string, unknown> = {};
-      const plugin: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        config: {
-          secretKey: { type: 'string', required: true },
-        },
-        boot(ctx) {
-          receivedConfig = ctx.config;
-        },
-      };
-
-      await loadPlugins({
-        plugins: [plugin],
-        config: { stripe: { secretKey: 'sk_test_123' } },
-      });
-
-      expect(receivedConfig).toEqual({ secretKey: 'sk_test_123' });
-    });
-
-    it('applies default values when user config is missing', async () => {
-      let receivedConfig: Record<string, unknown> = {};
-      const plugin: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        config: {
-          apiVersion: { type: 'string', default: '2024-12-18' },
-        },
-        boot(ctx) {
-          receivedConfig = ctx.config;
-        },
-      };
-
-      await loadPlugins({ plugins: [plugin] });
-      expect(receivedConfig).toEqual({ apiVersion: '2024-12-18' });
-    });
-
-    it('throws PluginConfigError when required field is missing', async () => {
-      const plugin: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        config: {
-          secretKey: { type: 'string', required: true },
-        },
-        boot() {},
-      };
-
-      await expect(loadPlugins({ plugins: [plugin] })).rejects.toThrow(PluginConfigError);
-      await expect(loadPlugins({ plugins: [plugin] })).rejects.toThrow(
-        'Plugin "stripe" requires config field "secretKey"',
-      );
-    });
-
-    it('allows extra config fields not in schema', async () => {
-      let receivedConfig: Record<string, unknown> = {};
-      const plugin: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        config: {
-          secretKey: { type: 'string', required: true },
-        },
-        boot(ctx) {
-          receivedConfig = ctx.config;
-        },
-      };
-
-      await loadPlugins({
-        plugins: [plugin],
-        config: { stripe: { secretKey: 'sk_test', extra: 'value' } },
-      });
-
-      expect(receivedConfig).toEqual({ secretKey: 'sk_test', extra: 'value' });
-    });
-  });
-
-  describe('adapter registration', () => {
-    it('provides adapter implement function in boot context', async () => {
-      const adapter = makeAdapter();
-      const plugin: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        provides: {
-          adapters: [{ name: 'stripe', capabilities: ['read', 'list'] }],
-        },
-        boot(ctx) {
-          ctx.adapters.stripe.implement(adapter);
-        },
-      };
-
-      const { adapterRegistry } = await loadPlugins({ plugins: [plugin] });
-      expect(adapterRegistry.has('stripe')).toBe(true);
-      expect(adapterRegistry.get('stripe')).toBe(adapter);
-    });
-
-    it('supports multiple adapters from one plugin', async () => {
-      const plugin: PluginDefinition = {
-        name: 'multi',
-        version: '1.0.0',
-        provides: {
-          adapters: [
-            { name: 'stripe', capabilities: ['read'] },
-            { name: 'hubspot', capabilities: ['read', 'list'] },
-          ],
-        },
-        boot(ctx) {
-          ctx.adapters.stripe.implement(makeAdapter());
-          ctx.adapters.hubspot.implement(makeAdapter());
-        },
-      };
-
-      const { adapterRegistry } = await loadPlugins({ plugins: [plugin] });
-      expect(adapterRegistry.has('stripe')).toBe(true);
-      expect(adapterRegistry.has('hubspot')).toBe(true);
-    });
-
-    it('throws MissingAdapterImplementationError when adapter not implemented', async () => {
-      const plugin: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        provides: {
-          adapters: [{ name: 'stripe', capabilities: ['read'] }],
-        },
-        boot() {
-          // does not call ctx.adapters.stripe.implement()
-        },
-      };
-
-      await expect(loadPlugins({ plugins: [plugin] })).rejects.toThrow(
-        MissingAdapterImplementationError,
-      );
-      await expect(loadPlugins({ plugins: [plugin] })).rejects.toThrow(
-        'Plugin "stripe" declares adapter "stripe" in provides but did not implement it during boot',
-      );
-    });
-  });
-
-  describe('lifecycle hooks', () => {
-    it('registers lifecycle handlers via ctx.on', async () => {
-      const handler = vi.fn().mockResolvedValue(undefined);
-      const plugin: PluginDefinition = {
-        name: 'test',
-        version: '1.0.0',
-        boot(ctx) {
-          ctx.on('afterBoot', handler);
-        },
-      };
-
-      const { lifecycleManager } = await loadPlugins({ plugins: [plugin] });
-      expect(lifecycleManager.getHandlers('afterBoot')).toContain(handler);
-    });
-
-    it('supports multiple lifecycle events from one plugin', async () => {
-      const beforeHandler = vi.fn().mockResolvedValue(undefined);
-      const afterHandler = vi.fn().mockResolvedValue(undefined);
-      const plugin: PluginDefinition = {
-        name: 'test',
-        version: '1.0.0',
-        boot(ctx) {
-          ctx.on('beforeBoot', beforeHandler);
-          ctx.on('afterBoot', afterHandler);
-        },
-      };
-
-      const { lifecycleManager } = await loadPlugins({ plugins: [plugin] });
-      expect(lifecycleManager.getHandlers('beforeBoot')).toContain(beforeHandler);
-      expect(lifecycleManager.getHandlers('afterBoot')).toContain(afterHandler);
-    });
-  });
-
-  describe('duplicate detection', () => {
-    it('throws DuplicatePluginError for same plugin name', async () => {
-      const pluginA: PluginDefinition = {
-        name: 'stripe',
-        version: '1.0.0',
-        boot() {},
-      };
-      const pluginB: PluginDefinition = {
-        name: 'stripe',
-        version: '2.0.0',
-        boot() {},
-      };
-
-      await expect(loadPlugins({ plugins: [pluginA, pluginB] })).rejects.toThrow(
-        DuplicatePluginError,
-      );
-      await expect(loadPlugins({ plugins: [pluginA, pluginB] })).rejects.toThrow(
-        'Plugin "stripe" is already registered',
-      );
-    });
-  });
-
-  describe('return value', () => {
-    it('returns adapterRegistry and lifecycleManager', async () => {
-      const plugin: PluginDefinition = {
-        name: 'test',
-        version: '1.0.0',
-        boot() {},
-      };
-
-      const result = await loadPlugins({ plugins: [plugin] });
-      expect(result).toHaveProperty('adapterRegistry');
-      expect(result).toHaveProperty('lifecycleManager');
-    });
-  });
-});

package/src/plugins/__tests__/validator.test.ts

@@ -1,275 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { validatePluginSetup } from '../validator.js';
-import { AdapterRegistry } from '../adapter-registry.js';
-import type { PluginDefinition, DataAdapter, AdapterCapability } from '../types.js';
-import type { ResolvedModel } from '../../schema/types.js';
-
-function makeAdapter(overrides?: Partial<DataAdapter>): DataAdapter {
-  return {
-    async get(_model, _id) {
-      return { id: '1' };
-    },
-    ...overrides,
-  };
-}
-
-function makeExternalModel(name: string, source: string): ResolvedModel {
-  return {
-    qualifiedName: `billing.${name}`,
-    app: 'billing-app',
-    module: 'billing',
-    name,
-    auditLog: false,
-    traits: [],
-    fields: [],
-    indexes: [],
-    source,
-  };
-}
-
-function makePlugin(name: string, adapters?: string[]): PluginDefinition {
-  return {
-    name,
-    version: '1.0.0',
-    provides: adapters
-      ? { adapters: adapters.map((a) => ({ name: a, capabilities: ['read'] as const })) }
-      : undefined,
-    boot() {},
-  };
-}
-
-describe('validatePluginSetup', () => {
-  describe('valid setup', () => {
-    it('returns valid with no plugins and no external models', () => {
-      const registry = new AdapterRegistry();
-      const result = validatePluginSetup(registry, [], []);
-      expect(result.valid).toBe(true);
-      expect(result.errors).toEqual([]);
-    });
-
-    it('returns valid when all adapters are registered and sources resolved', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-
-      const models = [makeExternalModel('Customer', 'stripe')];
-      const plugins = [makePlugin('stripe', ['stripe'])];
-
-      const result = validatePluginSetup(registry, models, plugins);
-      expect(result.valid).toBe(true);
-      expect(result.errors).toEqual([]);
-    });
-  });
-
-  describe('duplicate plugin detection', () => {
-    it('detects duplicate plugin names', () => {
-      const registry = new AdapterRegistry();
-      const plugins = [makePlugin('stripe'), makePlugin('stripe')];
-
-      const result = validatePluginSetup(registry, [], plugins);
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].type).toBe('DUPLICATE_PLUGIN');
-      expect(result.errors[0].message).toContain('stripe');
-    });
-
-    it('allows different plugin names', () => {
-      const registry = new AdapterRegistry();
-      const plugins = [makePlugin('stripe'), makePlugin('hubspot')];
-
-      const result = validatePluginSetup(registry, [], plugins);
-      expect(result.valid).toBe(true);
-    });
-  });
-
-  describe('missing adapter implementation', () => {
-    it('detects when declared adapter is not registered', () => {
-      const registry = new AdapterRegistry();
-      const plugins = [makePlugin('stripe', ['stripe'])];
-
-      const result = validatePluginSetup(registry, [], plugins);
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].type).toBe('MISSING_ADAPTER_IMPL');
-      expect(result.errors[0].plugin).toBe('stripe');
-      expect(result.errors[0].message).toContain('stripe');
-    });
-
-    it('passes when declared adapter is registered', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const plugins = [makePlugin('stripe', ['stripe'])];
-
-      const result = validatePluginSetup(registry, [], plugins);
-      expect(result.valid).toBe(true);
-    });
-  });
-
-  describe('unresolved external model source', () => {
-    it('detects when external model references unregistered adapter', () => {
-      const registry = new AdapterRegistry();
-      const models = [makeExternalModel('Customer', 'stripe')];
-
-      const result = validatePluginSetup(registry, models, []);
-      expect(result.valid).toBe(false);
-      expect(result.errors).toHaveLength(1);
-      expect(result.errors[0].type).toBe('UNRESOLVED_SOURCE');
-      expect(result.errors[0].model).toBe('billing.Customer');
-      expect(result.errors[0].message).toContain('stripe');
-    });
-
-    it('passes when source adapter is registered', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const models = [makeExternalModel('Customer', 'stripe')];
-
-      const result = validatePluginSetup(registry, models, []);
-      expect(result.valid).toBe(true);
-    });
-
-    it('skips models without source', () => {
-      const registry = new AdapterRegistry();
-      const internalModel: ResolvedModel = {
-        qualifiedName: 'sales.Order',
-        app: 'sales-app',
-        module: 'sales',
-        name: 'Order',
-        auditLog: false,
-        traits: [],
-        fields: [],
-        indexes: [],
-      };
-
-      const result = validatePluginSetup(registry, [internalModel], []);
-      expect(result.valid).toBe(true);
-    });
-  });
-
-  describe('batchGet warnings', () => {
-    it('warns when adapter lacks batchGet', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const models = [makeExternalModel('Customer', 'stripe')];
-
-      const result = validatePluginSetup(registry, models, []);
-      expect(result.warnings).toHaveLength(1);
-      expect(result.warnings[0]).toContain('batchGet');
-      expect(result.warnings[0]).toContain('N+1');
-    });
-
-    it('no warning when adapter has batchGet', () => {
-      const registry = new AdapterRegistry();
-      registry.register(
-        'stripe',
-        makeAdapter({
-          async batchGet(_model, ids) {
-            return ids.map((id) => ({ id }));
-          },
-        }),
-      );
-      const models = [makeExternalModel('Customer', 'stripe')];
-
-      const result = validatePluginSetup(registry, models, []);
-      expect(result.warnings).toHaveLength(0);
-    });
-
-    it('skips warning when adapter is not registered', () => {
-      const registry = new AdapterRegistry();
-      const models = [makeExternalModel('Customer', 'missing')];
-
-      const result = validatePluginSetup(registry, models, []);
-      expect(result.warnings).toHaveLength(0);
-    });
-  });
-
-  describe('aggregated errors', () => {
-    it('collects multiple errors from different checks', () => {
-      const registry = new AdapterRegistry();
-      const plugins = [makePlugin('stripe', ['stripe']), makePlugin('stripe', ['hubspot'])];
-      const models = [makeExternalModel('Customer', 'missing')];
-
-      const result = validatePluginSetup(registry, models, plugins);
-      expect(result.valid).toBe(false);
-      expect(result.errors.length).toBeGreaterThan(1);
-
-      const types = result.errors.map((e) => e.type);
-      expect(types).toContain('DUPLICATE_PLUGIN');
-      expect(types).toContain('MISSING_ADAPTER_IMPL');
-      expect(types).toContain('UNRESOLVED_SOURCE');
-    });
-  });
-
-  describe('capability violations', () => {
-    it('errors when adapter lacks required read capability', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const models = [makeExternalModel('Customer', 'stripe')];
-      const capabilities: Record<string, AdapterCapability[]> = { stripe: ['list'] };
-
-      const result = validatePluginSetup(registry, models, [], capabilities);
-      expect(result.valid).toBe(false);
-      expect(result.errors).toContainEqual(
-        expect.objectContaining({
-          type: 'CAPABILITY_VIOLATION',
-          model: 'billing.Customer',
-          message: expect.stringContaining('read'),
-        }),
-      );
-    });
-
-    it('errors when adapter lacks list capability', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const models = [makeExternalModel('Customer', 'stripe')];
-      const capabilities: Record<string, AdapterCapability[]> = { stripe: ['read'] };
-
-      const result = validatePluginSetup(registry, models, [], capabilities);
-      expect(result.valid).toBe(false);
-      expect(result.errors).toContainEqual(
-        expect.objectContaining({
-          type: 'CAPABILITY_VIOLATION',
-          message: expect.stringContaining('list'),
-        }),
-      );
-    });
-
-    it('passes when adapter has read and list', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const models = [makeExternalModel('Customer', 'stripe')];
-      const capabilities: Record<string, AdapterCapability[]> = { stripe: ['read', 'list'] };
-
-      const result = validatePluginSetup(registry, models, [], capabilities);
-      const capErrors = result.errors.filter((e) => e.type === 'CAPABILITY_VIOLATION');
-      expect(capErrors).toHaveLength(0);
-    });
-
-    it('skips check when no capabilities declared for adapter', () => {
-      const registry = new AdapterRegistry();
-      registry.register('stripe', makeAdapter());
-      const models = [makeExternalModel('Customer', 'stripe')];
-
-      const result = validatePluginSetup(registry, models, [], {});
-      const capErrors = result.errors.filter((e) => e.type === 'CAPABILITY_VIOLATION');
-      expect(capErrors).toHaveLength(0);
-    });
-
-    it('skips internal models', () => {
-      const registry = new AdapterRegistry();
-      const internalModel: ResolvedModel = {
-        qualifiedName: 'sales.Order',
-        app: 'test',
-        module: 'sales',
-        name: 'Order',
-        auditLog: false,
-        traits: [],
-        fields: [],
-        indexes: [],
-      };
-      const capabilities: Record<string, AdapterCapability[]> = { stripe: ['read'] };
-
-      const result = validatePluginSetup(registry, [internalModel], [], capabilities);
-      const capErrors = result.errors.filter((e) => e.type === 'CAPABILITY_VIOLATION');
-      expect(capErrors).toHaveLength(0);
-    });
-  });
-});

package/src/plugins/adapter-registry.ts

@@ -1,42 +0,0 @@
-import type { DataAdapter } from './types.js';
-
-export class AdapterNotFoundError extends Error {
-  constructor(public readonly adapterName: string) {
-    super(`Adapter "${adapterName}" is not registered`);
-    this.name = 'AdapterNotFoundError';
-  }
-}
-
-export class DuplicateAdapterError extends Error {
-  constructor(public readonly adapterName: string) {
-    super(`Adapter "${adapterName}" is already registered`);
-    this.name = 'DuplicateAdapterError';
-  }
-}
-
-export class AdapterRegistry {
-  private adapters = new Map<string, DataAdapter>();
-
-  register(name: string, adapter: DataAdapter): void {
-    if (this.adapters.has(name)) {
-      throw new DuplicateAdapterError(name);
-    }
-    this.adapters.set(name, adapter);
-  }
-
-  has(name: string): boolean {
-    return this.adapters.has(name);
-  }
-
-  get(name: string): DataAdapter {
-    const adapter = this.adapters.get(name);
-    if (!adapter) {
-      throw new AdapterNotFoundError(name);
-    }
-    return adapter;
-  }
-
-  getAll(): Array<{ name: string; adapter: DataAdapter }> {
-    return [...this.adapters.entries()].map(([name, adapter]) => ({ name, adapter }));
-  }
-}

package/src/plugins/define.ts

@@ -1,5 +0,0 @@
-import type { PluginDefinition } from './types.js';
-
-export function definePlugin(definition: PluginDefinition): PluginDefinition {
-  return definition;
-}

package/src/plugins/index.ts

@@ -1,28 +0,0 @@
-export { definePlugin } from './define.js';
-export {
-  AdapterRegistry,
-  AdapterNotFoundError,
-  DuplicateAdapterError,
-} from './adapter-registry.js';
-export { PluginLifecycleManager } from './lifecycle.js';
-export {
-  loadPlugins,
-  DuplicatePluginError,
-  PluginConfigError,
-  MissingAdapterImplementationError,
-} from './loader.js';
-export { validatePluginSetup } from './validator.js';
-export type {
-  DataAdapter,
-  AdapterCapability,
-  PluginDefinition,
-  PluginBootContext,
-  PluginLifecycleEvent,
-  PluginProvides,
-  PluginConfigField,
-  ListQuery,
-  ListResult,
-  FilterExpression,
-  LifecycleHandler,
-} from './types.js';
-export type { ValidationResult, PluginValidationError } from './validator.js';

package/src/plugins/lifecycle.ts

@@ -1,27 +0,0 @@
-import type { PluginLifecycleEvent, LifecycleHandler } from './types.js';
-
-export class PluginLifecycleManager {
-  private handlers: Map<PluginLifecycleEvent, LifecycleHandler[]>;
-
-  constructor(handlers?: Map<PluginLifecycleEvent, LifecycleHandler[]>) {
-    this.handlers = handlers ?? new Map();
-  }
-
-  register(event: PluginLifecycleEvent, handler: LifecycleHandler): void {
-    const list = this.handlers.get(event) ?? [];
-    list.push(handler);
-    this.handlers.set(event, list);
-  }
-
-  async emit(event: PluginLifecycleEvent, ...args: unknown[]): Promise<void> {
-    const list = this.handlers.get(event);
-    if (!list) return;
-    for (const handler of list) {
-      await handler(...args);
-    }
-  }
-
-  getHandlers(event: PluginLifecycleEvent): LifecycleHandler[] {
-    return this.handlers.get(event) ?? [];
-  }
-}