@unrdf/kgc-runtime 26.4.2

package/test/plugin-isolation.test.mjs

@@ -0,0 +1,109 @@
+/**
+ * Plugin Isolation Tests
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PluginIsolation, createPublicAPI } from '../src/plugin-isolation.mjs';
+
+describe('PluginIsolation', () => {
+  let isolation;
+
+  beforeEach(() => {
+    isolation = new PluginIsolation();
+  });
+
+  // Test 11: Capability Checking
+  it('should allow whitelisted capabilities', () => {
+    const allowed = isolation.checkCapability('receipt:generate');
+    expect(allowed).toBe(true);
+  });
+
+  it('should block non-whitelisted capabilities in strict mode', () => {
+    const denied = isolation.checkCapability('filesystem:write');
+    expect(denied).toBe(false);
+  });
+
+  it('should always block dangerous capabilities', () => {
+    isolation.grantCapability('custom:action'); // This works
+
+    // But blocked capabilities are never allowed
+    expect(() => {
+      isolation.grantCapability('process:spawn');
+    }).toThrow(/Cannot grant blocked capability/);
+  });
+
+  // Test 12: Isolated Execution
+  it('should execute functions with required capabilities', async () => {
+    const result = await isolation.executeIsolated(
+      async () => {
+        return { data: 42 };
+      },
+      ['receipt:generate']
+    );
+
+    expect(result.data).toBe(42);
+  });
+
+  it('should reject execution if capabilities are denied', async () => {
+    await expect(
+      isolation.executeIsolated(
+        async () => {
+          return { data: 42 };
+        },
+        ['filesystem:write']
+      )
+    ).rejects.toThrow(/Capability denied/);
+  });
+
+  // Test 13: Access Logging
+  it('should log all capability access attempts', () => {
+    isolation.checkCapability('receipt:generate');
+    isolation.checkCapability('filesystem:write');
+
+    const accessLog = isolation.getAccessLog();
+
+    expect(accessLog.length).toBeGreaterThanOrEqual(2);
+    expect(accessLog.some(entry => entry.capability === 'receipt:generate')).toBe(true);
+    expect(accessLog.some(entry => entry.capability === 'filesystem:write')).toBe(true);
+  });
+
+  it('should track usage statistics', () => {
+    isolation.checkCapability('receipt:generate');
+    isolation.checkCapability('receipt:generate');
+    isolation.checkCapability('receipt:validate');
+
+    const stats = isolation.getUsageStats();
+
+    expect(stats['receipt:generate']).toBe(2);
+    expect(stats['receipt:validate']).toBe(1);
+  });
+
+  // Test 14: Plugin Capability Validation
+  it('should validate plugin manifest capabilities', () => {
+    const validation = isolation.validatePluginCapabilities([
+      'receipt:generate',
+      'custom:action',
+      'filesystem:write',
+    ]);
+
+    expect(validation.allowed).toContain('receipt:generate');
+    expect(validation.denied).toContain('custom:action');
+    expect(validation.blocked).toContain('filesystem:write');
+  });
+});
+
+describe('createPublicAPI', () => {
+  it('should create proxy with only whitelisted methods', () => {
+    const fullAPI = {
+      publicMethod: () => 'public',
+      privateMethod: () => 'private',
+      data: { value: 42 },
+    };
+
+    const publicAPI = createPublicAPI(fullAPI, ['publicMethod', 'data']);
+
+    expect(publicAPI.publicMethod()).toBe('public');
+    expect(publicAPI.privateMethod).toBeUndefined();
+    expect(publicAPI.data.value).toBe(42);
+  });
+});

package/test/plugin-manager.test.mjs

@@ -0,0 +1,208 @@
+/**
+ * Plugin Manager Tests
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PluginManager, PLUGIN_STATES } from '../src/plugin-manager.mjs';
+
+describe('PluginManager', () => {
+  let manager;
+
+  beforeEach(() => {
+    manager = new PluginManager();
+  });
+
+  // Test 1: Plugin Registration
+  it('should register a valid plugin', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      description: 'Test plugin',
+      entryPoint: './test.mjs',
+      capabilities: ['receipt:generate'],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+
+    expect(pluginId).toBe('test-plugin@1.0.0');
+    expect(manager.getPluginState(pluginId)).toBe(PLUGIN_STATES.REGISTERED);
+  });
+
+  // Test 2: Plugin Loading
+  it('should load a registered plugin', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+    await manager.loadPlugin(pluginId);
+
+    expect(manager.getPluginState(pluginId)).toBe(PLUGIN_STATES.LOADED);
+  });
+
+  // Test 3: Plugin Activation
+  it('should activate a loaded plugin', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+    await manager.loadPlugin(pluginId);
+    await manager.activatePlugin(pluginId);
+
+    expect(manager.getPluginState(pluginId)).toBe(PLUGIN_STATES.EXECUTING);
+  });
+
+  // Test 4: Plugin Deactivation
+  it('should deactivate an executing plugin', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+    await manager.loadPlugin(pluginId);
+    await manager.activatePlugin(pluginId);
+    await manager.deactivatePlugin(pluginId);
+
+    expect(manager.getPluginState(pluginId)).toBe(PLUGIN_STATES.LOADED);
+  });
+
+  // Test 5: Invalid State Transition
+  it('should reject invalid state transitions', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+
+    // Cannot activate without loading
+    await expect(manager.activatePlugin(pluginId)).rejects.toThrow(
+      /Cannot activate plugin in state/
+    );
+  });
+
+  // Test 6: Parallel Loading
+  it('should support parallel plugin loading', async () => {
+    const manager = new PluginManager({ parallelLoading: true });
+
+    const plugins = ['plugin-1', 'plugin-2', 'plugin-3'];
+
+    for (const name of plugins) {
+      await manager.registerPlugin({
+        name,
+        version: '1.0.0',
+        entryPoint: './test.mjs',
+        capabilities: [],
+        api_version: '5.0.1',
+      });
+    }
+
+    const pluginIds = plugins.map(name => `${name}@1.0.0`);
+    const result = await manager.loadPluginsParallel(pluginIds);
+
+    expect(result.success).toHaveLength(3);
+    expect(result.failed).toHaveLength(0);
+  });
+
+  // Test 7: Audit Log
+  it('should maintain audit log of all operations', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+    await manager.loadPlugin(pluginId);
+
+    const auditLog = manager.getAuditLog({ pluginId });
+
+    expect(auditLog.length).toBeGreaterThan(0);
+    expect(auditLog.some(entry => entry.action === 'register')).toBe(true);
+    expect(auditLog.some(entry => entry.action === 'load')).toBe(true);
+  });
+
+  // Test 8: State Transition Count
+  it('should track state transition count', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const initialCount = manager.getTransitionCount();
+
+    const pluginId = await manager.registerPlugin(manifest);
+    await manager.loadPlugin(pluginId);
+    await manager.activatePlugin(pluginId);
+
+    const finalCount = manager.getTransitionCount();
+
+    expect(finalCount).toBe(initialCount + 3); // register, load, activate
+  });
+
+  // Test 9: List Plugins by State
+  it('should list plugins by state', async () => {
+    await manager.registerPlugin({
+      name: 'plugin-1',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    });
+
+    await manager.registerPlugin({
+      name: 'plugin-2',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    });
+
+    await manager.loadPlugin('plugin-1@1.0.0');
+
+    const registered = manager.listPluginsByState(PLUGIN_STATES.REGISTERED);
+    const loaded = manager.listPluginsByState(PLUGIN_STATES.LOADED);
+
+    expect(registered).toHaveLength(1);
+    expect(loaded).toHaveLength(1);
+  });
+
+  // Test 10: Plugin Uninstall
+  it('should uninstall a plugin completely', async () => {
+    const manifest = {
+      name: 'test-plugin',
+      version: '1.0.0',
+      entryPoint: './test.mjs',
+      capabilities: [],
+      api_version: '5.0.1',
+    };
+
+    const pluginId = await manager.registerPlugin(manifest);
+    await manager.uninstallPlugin(pluginId);
+
+    expect(manager.getPlugin(pluginId)).toBeNull();
+    expect(manager.getPluginState(pluginId)).toBeNull();
+  });
+});

package/test/projections-api.test.mjs

@@ -0,0 +1,293 @@
+/**
+ * Tests for API Projections (Π_api)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  projectReceiptsToREST,
+  projectWorkItemsToGraphQL,
+  projectResourceToJSONAPI,
+  applyFilters,
+  applySorting,
+  applyPagination,
+  buildHATEOASLinks,
+  APIProjectionSchema,
+} from '../src/projections-api.mjs';
+
+describe('Π_api - API Projections', () => {
+  describe('projectReceiptsToREST', () => {
+    it('should project receipts to paginated REST format', () => {
+      const receipts = [
+        { id: '1', timestamp: '2024-01-01', operation: 'op1', hash: 'a'.repeat(64) },
+        { id: '2', timestamp: '2024-01-02', operation: 'op2', hash: 'b'.repeat(64) },
+        { id: '3', timestamp: '2024-01-03', operation: 'op3', hash: 'c'.repeat(64) },
+      ];
+
+      const projection = projectReceiptsToREST(
+        receipts,
+        { page: 1, pageSize: 2 }
+      );
+
+      expect(projection.type).toBe('api');
+      expect(projection.format).toBe('rest');
+      expect(projection.data).toHaveLength(2);
+      expect(projection.meta.pagination.total).toBe(3);
+      expect(projection.meta.pagination.totalPages).toBe(2);
+      expect(projection.links.next).toContain('page=2');
+
+      // Validate schema
+      APIProjectionSchema.parse(projection);
+    });
+
+    it('should apply filters to receipts', () => {
+      const receipts = [
+        { id: '1', operation: 'create', hash: 'a'.repeat(64) },
+        { id: '2', operation: 'update', hash: 'b'.repeat(64) },
+        { id: '3', operation: 'create', hash: 'c'.repeat(64) },
+      ];
+
+      const projection = projectReceiptsToREST(
+        receipts,
+        { page: 1, pageSize: 10 },
+        { operation: 'create' }
+      );
+
+      expect(projection.data).toHaveLength(2);
+      expect(projection.meta.filters.operation).toBe('create');
+    });
+
+    it('should apply sorting to receipts', () => {
+      const receipts = [
+        { id: '3', timestamp: '2024-01-03', hash: 'c'.repeat(64) },
+        { id: '1', timestamp: '2024-01-01', hash: 'a'.repeat(64) },
+        { id: '2', timestamp: '2024-01-02', hash: 'b'.repeat(64) },
+      ];
+
+      const projection = projectReceiptsToREST(
+        receipts,
+        { page: 1, pageSize: 10 },
+        {},
+        [{ field: 'timestamp', direction: 'asc' }]
+      );
+
+      expect(projection.data[0].id).toBe('1');
+      expect(projection.data[1].id).toBe('2');
+      expect(projection.data[2].id).toBe('3');
+    });
+  });
+
+  describe('projectWorkItemsToGraphQL', () => {
+    it('should project work items to GraphQL format', () => {
+      const workItems = [
+        { id: '1', goal: 'Task 1', state: 'pending', priority: 1 },
+        { id: '2', goal: 'Task 2', state: 'running', priority: 2 },
+      ];
+
+      const projection = projectWorkItemsToGraphQL(workItems);
+
+      expect(projection.type).toBe('api');
+      expect(projection.format).toBe('graphql');
+      expect(projection.data.workItems).toHaveLength(2);
+      expect(projection.data.totalCount).toBe(2);
+    });
+
+    it('should apply GraphQL where filters', () => {
+      const workItems = [
+        { id: '1', goal: 'Task 1', state: 'pending' },
+        { id: '2', goal: 'Task 2', state: 'completed' },
+        { id: '3', goal: 'Task 3', state: 'pending' },
+      ];
+
+      const projection = projectWorkItemsToGraphQL(workItems, {
+        where: { state: 'pending' },
+      });
+
+      expect(projection.data.workItems).toHaveLength(2);
+      expect(projection.data.filteredCount).toBe(2);
+    });
+
+    it('should apply GraphQL ordering', () => {
+      const workItems = [
+        { id: '3', goal: 'Task 3', priority: 3 },
+        { id: '1', goal: 'Task 1', priority: 1 },
+        { id: '2', goal: 'Task 2', priority: 2 },
+      ];
+
+      const projection = projectWorkItemsToGraphQL(workItems, {
+        orderBy: { field: 'priority', direction: 'ASC' },
+      });
+
+      expect(projection.data.workItems[0].id).toBe('1');
+      expect(projection.data.workItems[2].id).toBe('3');
+    });
+
+    it('should apply skip and take pagination', () => {
+      const workItems = Array.from({ length: 10 }, (_, i) => ({
+        id: String(i + 1),
+        goal: `Task ${i + 1}`,
+        state: 'pending',
+      }));
+
+      const projection = projectWorkItemsToGraphQL(workItems, {
+        skip: 2,
+        take: 3,
+      });
+
+      expect(projection.data.workItems).toHaveLength(3);
+      expect(projection.data.workItems[0].id).toBe('3');
+    });
+  });
+
+  describe('projectResourceToJSONAPI', () => {
+    it('should project resource to JSON:API format', () => {
+      const resource = {
+        id: 'user-123',
+        name: 'Alice',
+        email: 'alice@example.com',
+      };
+
+      const projection = projectResourceToJSONAPI(resource, 'user');
+
+      expect(projection.type).toBe('api');
+      expect(projection.format).toBe('json-api');
+      expect(projection.data.type).toBe('user');
+      expect(projection.data.id).toBe('user-123');
+      expect(projection.data.attributes.name).toBe('Alice');
+      expect(projection.links.self).toBe('/user/user-123');
+    });
+
+    it('should include relationships', () => {
+      const resource = { id: '1', title: 'Post' };
+      const relationships = {
+        author: { type: 'user', id: 'user-123' },
+        comments: [
+          { type: 'comment', id: 'c1' },
+          { type: 'comment', id: 'c2' },
+        ],
+      };
+
+      const projection = projectResourceToJSONAPI(resource, 'post', relationships);
+
+      expect(projection.data.relationships.author.data).toEqual({
+        type: 'user',
+        id: 'user-123',
+      });
+      expect(projection.data.relationships.comments.data).toHaveLength(2);
+    });
+  });
+
+  describe('applyFilters', () => {
+    it('should filter with equality', () => {
+      const items = [
+        { id: 1, status: 'active' },
+        { id: 2, status: 'inactive' },
+        { id: 3, status: 'active' },
+      ];
+
+      const filtered = applyFilters(items, { status: 'active' });
+
+      expect(filtered).toHaveLength(2);
+    });
+
+    it('should filter with operators', () => {
+      const items = [
+        { id: 1, count: 5 },
+        { id: 2, count: 10 },
+        { id: 3, count: 15 },
+      ];
+
+      const filtered = applyFilters(items, { count: { gt: 7 } });
+
+      expect(filtered).toHaveLength(2);
+      expect(filtered[0].count).toBe(10);
+    });
+
+    it('should filter with contains operator', () => {
+      const items = [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' },
+        { id: 3, name: 'Charlie' },
+      ];
+
+      const filtered = applyFilters(items, { name: { contains: 'li' } });
+
+      expect(filtered).toHaveLength(2); // Alice, Charlie
+    });
+  });
+
+  describe('applySorting', () => {
+    it('should sort ascending', () => {
+      const items = [
+        { id: 3, value: 30 },
+        { id: 1, value: 10 },
+        { id: 2, value: 20 },
+      ];
+
+      const sorted = applySorting(items, [{ field: 'value', direction: 'asc' }]);
+
+      expect(sorted[0].value).toBe(10);
+      expect(sorted[2].value).toBe(30);
+    });
+
+    it('should sort descending', () => {
+      const items = [
+        { id: 1, value: 10 },
+        { id: 3, value: 30 },
+        { id: 2, value: 20 },
+      ];
+
+      const sorted = applySorting(items, [{ field: 'value', direction: 'desc' }]);
+
+      expect(sorted[0].value).toBe(30);
+      expect(sorted[2].value).toBe(10);
+    });
+
+    it('should handle multi-field sorting', () => {
+      const items = [
+        { category: 'A', priority: 2 },
+        { category: 'B', priority: 1 },
+        { category: 'A', priority: 1 },
+      ];
+
+      const sorted = applySorting(items, [
+        { field: 'category', direction: 'asc' },
+        { field: 'priority', direction: 'asc' },
+      ]);
+
+      expect(sorted[0]).toEqual({ category: 'A', priority: 1 });
+      expect(sorted[1]).toEqual({ category: 'A', priority: 2 });
+    });
+  });
+
+  describe('applyPagination', () => {
+    it('should paginate items', () => {
+      const items = Array.from({ length: 10 }, (_, i) => ({ id: i + 1 }));
+
+      const result = applyPagination(items, { page: 2, pageSize: 3 });
+
+      expect(result.data).toHaveLength(3);
+      expect(result.data[0].id).toBe(4);
+      expect(result.meta.pagination.total).toBe(10);
+      expect(result.meta.pagination.totalPages).toBe(4);
+    });
+  });
+
+  describe('buildHATEOASLinks', () => {
+    it('should build HATEOAS links', () => {
+      const links = buildHATEOASLinks('users', '123');
+
+      expect(links.self).toBe('/users/123');
+      expect(links.collection).toBe('/users');
+    });
+
+    it('should include additional links', () => {
+      const links = buildHATEOASLinks('users', '123', [
+        { rel: 'posts', href: '/users/123/posts' },
+        { rel: 'profile', href: '/users/123/profile' },
+      ]);
+
+      expect(links.posts).toBe('/users/123/posts');
+      expect(links.profile).toBe('/users/123/profile');
+    });
+  });
+});