@rangka/core 0.0.1

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

@@ -0,0 +1,273 @@
+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

@@ -0,0 +1,275 @@
+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

@@ -0,0 +1,42 @@
+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

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

package/src/plugins/index.ts

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,27 @@
+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) ?? [];
+  }
+}