@unrdf/kgc-runtime 26.4.2

package/test/projections-cli.test.mjs

@@ -0,0 +1,204 @@
+/**
+ * Tests for CLI Projections (Π_cli)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  projectReceiptToCLI,
+  projectWorkItemsToCLI,
+  projectObjectToTree,
+  projectArrayToList,
+  flattenForCLI,
+  CLIProjectionSchema,
+} from '../src/projections-cli.mjs';
+
+describe('Π_cli - CLI Projections', () => {
+  describe('projectReceiptToCLI', () => {
+    it('should project receipt to CLI format with colors', () => {
+      const receipt = {
+        id: 'receipt-001',
+        timestamp: '2024-01-01T00:00:00Z',
+        operation: 'test-operation',
+        inputs: { x: 1 },
+        outputs: { y: 2 },
+        hash: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+      };
+
+      const projection = projectReceiptToCLI(receipt, true);
+
+      expect(projection.type).toBe('cli');
+      expect(projection.format).toBe('summary');
+      expect(projection.colored).toBe(true);
+      expect(projection.content).toContain('receipt-001');
+      expect(projection.content).toContain('test-operation');
+      expect(projection.metadata.receiptId).toBe('receipt-001');
+
+      // Validate schema
+      CLIProjectionSchema.parse(projection);
+    });
+
+    it('should project receipt without colors', () => {
+      const receipt = {
+        id: 'receipt-002',
+        timestamp: '2024-01-01T00:00:00Z',
+        operation: 'test-op',
+        inputs: {},
+        outputs: {},
+        hash: 'a'.repeat(64),
+      };
+
+      const projection = projectReceiptToCLI(receipt, false);
+
+      expect(projection.colored).toBe(false);
+      expect(projection.content).not.toContain('\x1b['); // No ANSI codes
+    });
+
+    it('should include parent hash if present', () => {
+      const receipt = {
+        id: 'receipt-003',
+        timestamp: '2024-01-01T00:00:00Z',
+        operation: 'test',
+        inputs: {},
+        outputs: {},
+        hash: 'a'.repeat(64),
+        parentHash: 'b'.repeat(64),
+      };
+
+      const projection = projectReceiptToCLI(receipt, false);
+
+      expect(projection.content).toContain('Parent:');
+      expect(projection.content).toContain('bbbbbbbbbbbbbbbb');
+    });
+  });
+
+  describe('projectWorkItemsToCLI', () => {
+    it('should project work items to table format', () => {
+      const workItems = [
+        { id: 'item-001', goal: 'Process data', state: 'completed', priority: 1 },
+        { id: 'item-002', goal: 'Generate report', state: 'running', priority: 2 },
+        { id: 'item-003', goal: 'Send notification', state: 'failed', priority: 0 },
+      ];
+
+      const projection = projectWorkItemsToCLI(workItems, false);
+
+      expect(projection.type).toBe('cli');
+      expect(projection.format).toBe('table');
+      expect(projection.content).toContain('ID');
+      expect(projection.content).toContain('Goal');
+      expect(projection.content).toContain('State');
+      expect(projection.content).toContain('Priority');
+      expect(projection.metadata.count).toBe(3);
+    });
+
+    it('should handle empty work items array', () => {
+      const projection = projectWorkItemsToCLI([], false);
+
+      expect(projection.content).toContain('No work items');
+    });
+
+    it('should use colors for different states', () => {
+      const workItems = [
+        { id: 'item-001', goal: 'Task', state: 'completed', priority: 1 },
+      ];
+
+      const projection = projectWorkItemsToCLI(workItems, true);
+
+      expect(projection.colored).toBe(true);
+      expect(projection.content).toContain('\x1b['); // Has ANSI codes
+    });
+  });
+
+  describe('projectObjectToTree', () => {
+    it('should project nested object to tree format', () => {
+      const obj = {
+        root: {
+          child1: {
+            grandchild: 'value',
+          },
+          child2: 'simple',
+        },
+        array: [1, 2, 3],
+      };
+
+      const projection = projectObjectToTree(obj, false);
+
+      expect(projection.type).toBe('cli');
+      expect(projection.format).toBe('tree');
+      expect(projection.content).toContain('root');
+      expect(projection.content).toContain('child1');
+      expect(projection.content).toContain('grandchild');
+      expect(projection.content).toContain('└──');
+    });
+
+    it('should handle arrays in tree', () => {
+      const obj = {
+        items: [1, 2, 3],
+      };
+
+      const projection = projectObjectToTree(obj, false);
+
+      expect(projection.content).toContain('[3 items]');
+    });
+  });
+
+  describe('projectArrayToList', () => {
+    it('should project string array to numbered list', () => {
+      const items = ['First item', 'Second item', 'Third item'];
+
+      const projection = projectArrayToList(items, false);
+
+      expect(projection.type).toBe('cli');
+      expect(projection.format).toBe('list');
+      expect(projection.content).toContain('1. First item');
+      expect(projection.content).toContain('2. Second item');
+      expect(projection.content).toContain('3. Third item');
+      expect(projection.metadata.count).toBe(3);
+    });
+
+    it('should project object array with labels and descriptions', () => {
+      const items = [
+        { label: 'Task 1', description: 'Do something' },
+        { label: 'Task 2', description: 'Do something else' },
+      ];
+
+      const projection = projectArrayToList(items, false);
+
+      expect(projection.content).toContain('Task 1');
+      expect(projection.content).toContain('Do something');
+      expect(projection.content).toContain('Task 2');
+    });
+  });
+
+  describe('flattenForCLI', () => {
+    it('should flatten nested object with dot notation', () => {
+      const obj = {
+        user: {
+          name: 'Alice',
+          address: {
+            city: 'NYC',
+            zip: '10001',
+          },
+        },
+        count: 42,
+      };
+
+      const flattened = flattenForCLI(obj);
+
+      expect(flattened['user.name']).toBe('Alice');
+      expect(flattened['user.address.city']).toBe('NYC');
+      expect(flattened['user.address.zip']).toBe('10001');
+      expect(flattened['count']).toBe(42);
+    });
+
+    it('should handle arrays without flattening', () => {
+      const obj = {
+        items: [1, 2, 3],
+      };
+
+      const flattened = flattenForCLI(obj);
+
+      expect(Array.isArray(flattened.items)).toBe(true);
+      expect(flattened.items).toEqual([1, 2, 3]);
+    });
+  });
+});

package/test/projections-docs.test.mjs

@@ -0,0 +1,173 @@
+/**
+ * Tests for Documentation Projections (Π_docs)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  projectReceiptToDocs,
+  projectSchemaToDocs,
+  projectFunctionToDocs,
+  projectWorkflowToDocs,
+  generateCrossRefs,
+  generateTableOfContents,
+  DocsProjectionSchema,
+} from '../src/projections-docs.mjs';
+import { z } from 'zod';
+
+describe('Π_docs - Documentation Projections', () => {
+  describe('projectReceiptToDocs', () => {
+    it('should project receipt to markdown documentation', () => {
+      const receipt = {
+        id: 'receipt-001',
+        timestamp: '2024-01-01T00:00:00Z',
+        operation: 'test-operation',
+        inputs: { x: 1, y: 2 },
+        outputs: { result: 3 },
+        hash: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+      };
+
+      const projection = projectReceiptToDocs(receipt);
+
+      expect(projection.type).toBe('docs');
+      expect(projection.format).toBe('markdown');
+      expect(projection.content).toContain('# Receipt Documentation');
+      expect(projection.content).toContain('receipt-001');
+      expect(projection.content).toContain('test-operation');
+      expect(projection.frontMatter.id).toBe('receipt-001');
+      expect(projection.sections).toHaveLength(4);
+
+      // Validate schema
+      DocsProjectionSchema.parse(projection);
+    });
+
+    it('should include parent hash if present', () => {
+      const receipt = {
+        id: 'receipt-002',
+        timestamp: '2024-01-01T00:00:00Z',
+        operation: 'test',
+        inputs: {},
+        outputs: {},
+        hash: 'a'.repeat(64),
+        parentHash: 'b'.repeat(64),
+      };
+
+      const projection = projectReceiptToDocs(receipt);
+
+      expect(projection.content).toContain('Parent Hash');
+    });
+  });
+
+  describe('projectSchemaToDocs', () => {
+    it('should project Zod schema to documentation', () => {
+      const TestSchema = z.object({
+        name: z.string(),
+        age: z.number(),
+      });
+
+      const example = { name: 'Alice', age: 30 };
+
+      const projection = projectSchemaToDocs('TestSchema', TestSchema, example);
+
+      expect(projection.type).toBe('docs');
+      expect(projection.content).toContain('# TestSchema Documentation');
+      expect(projection.content).toContain('```json');
+      expect(projection.content).toContain('Alice');
+      expect(projection.content).toContain('## Example');
+      expect(projection.content).toContain('## Usage');
+      expect(projection.frontMatter.schema).toBe('TestSchema');
+    });
+
+    it('should generate docs without example', () => {
+      const TestSchema = z.string();
+
+      const projection = projectSchemaToDocs('SimpleSchema', TestSchema);
+
+      expect(projection.content).toContain('# SimpleSchema Documentation');
+      expect(projection.content).not.toContain('## Example');
+    });
+  });
+
+  describe('projectFunctionToDocs', () => {
+    it('should project function to API documentation', () => {
+      const fnInfo = {
+        name: 'calculateSum',
+        description: 'Calculates the sum of two numbers',
+        params: [
+          { name: 'a', type: 'number', description: 'First number' },
+          { name: 'b', type: 'number', description: 'Second number' },
+        ],
+        returns: { type: 'number', description: 'The sum of a and b' },
+        example: 'const result = calculateSum(1, 2); // 3',
+      };
+
+      const projection = projectFunctionToDocs(null, fnInfo);
+
+      expect(projection.type).toBe('docs');
+      expect(projection.content).toContain('# calculateSum()');
+      expect(projection.content).toContain('## Description');
+      expect(projection.content).toContain('## Parameters');
+      expect(projection.content).toContain('## Returns');
+      expect(projection.content).toContain('## Example');
+      expect(projection.content).toContain('First number');
+      expect(projection.frontMatter.function).toBe('calculateSum');
+    });
+  });
+
+  describe('projectWorkflowToDocs', () => {
+    it('should project workflow to documentation', () => {
+      const workflow = {
+        id: 'wf-001',
+        name: 'Data Processing Workflow',
+        description: 'Processes incoming data through multiple stages',
+        steps: [
+          { id: 'step-1', type: 'validate', description: 'Validate input data' },
+          { id: 'step-2', type: 'transform', description: 'Transform data format' },
+          { id: 'step-3', type: 'store', description: 'Store in database' },
+        ],
+      };
+
+      const projection = projectWorkflowToDocs(workflow);
+
+      expect(projection.type).toBe('docs');
+      expect(projection.content).toContain('# Data Processing Workflow');
+      expect(projection.content).toContain('## Workflow Steps');
+      expect(projection.content).toContain('1. **validate**');
+      expect(projection.content).toContain('Validate input data');
+      expect(projection.crossRefs).toHaveLength(3);
+      expect(projection.frontMatter.workflowId).toBe('wf-001');
+    });
+  });
+
+  describe('generateCrossRefs', () => {
+    it('should generate markdown links for references', () => {
+      const text = 'See Receipt and WorkItem for details';
+      const refMap = new Map([
+        ['Receipt', '/docs/receipt'],
+        ['WorkItem', '/docs/work-item'],
+      ]);
+
+      const result = generateCrossRefs(text, refMap);
+
+      expect(result).toContain('[Receipt](/docs/receipt)');
+      expect(result).toContain('[WorkItem](/docs/work-item)');
+    });
+  });
+
+  describe('generateTableOfContents', () => {
+    it('should generate TOC from sections', () => {
+      const sections = [
+        { title: 'Introduction', level: 1 },
+        { title: 'Getting Started', level: 2 },
+        { title: 'Installation', level: 3 },
+        { title: 'Usage', level: 2 },
+      ];
+
+      const toc = generateTableOfContents(sections);
+
+      expect(toc).toContain('## Table of Contents');
+      expect(toc).toContain('[Introduction](#introduction)');
+      expect(toc).toContain('  [Getting Started](#getting-started)');
+      expect(toc).toContain('    [Installation](#installation)');
+    });
+  });
+});

package/test/projections-ide.test.mjs

@@ -0,0 +1,230 @@
+/**
+ * Tests for IDE Metadata Projections (Π_ide)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  projectFunctionToHover,
+  projectSchemaToCompletions,
+  projectToDefinition,
+  projectToDiagnostic,
+  projectToSymbol,
+  projectToCodeAction,
+  projectToCodeLens,
+  projectToSignatureHelp,
+  projectToSemanticTokens,
+  IDEProjectionSchema,
+} from '../src/projections-ide.mjs';
+
+describe('Π_ide - IDE Metadata Projections', () => {
+  describe('projectFunctionToHover', () => {
+    it('should project function to LSP hover information', () => {
+      const fnInfo = {
+        name: 'calculateSum',
+        signature: 'function calculateSum(a: number, b: number): number',
+        documentation: 'Calculates the sum of two numbers',
+        parameters: [
+          { name: 'a', type: 'number', description: 'First number' },
+          { name: 'b', type: 'number', description: 'Second number' },
+        ],
+        returns: { type: 'number', description: 'The sum' },
+      };
+
+      const projection = projectFunctionToHover(fnInfo);
+
+      expect(projection.type).toBe('ide');
+      expect(projection.format).toBe('hover');
+      expect(projection.content.kind).toBe('markdown');
+      expect(projection.content.value).toContain('calculateSum');
+      expect(projection.content.value).toContain('@param');
+      expect(projection.content.value).toContain('@returns');
+
+      // Validate schema
+      IDEProjectionSchema.parse(projection);
+    });
+  });
+
+  describe('projectSchemaToCompletions', () => {
+    it('should project schema to LSP completions', () => {
+      const fields = {
+        name: { type: 'string', description: 'User name' },
+        age: { type: 'number', description: 'User age' },
+        email: { type: 'string', description: 'User email address' },
+      };
+
+      const projection = projectSchemaToCompletions('UserSchema', fields);
+
+      expect(projection.type).toBe('ide');
+      expect(projection.format).toBe('completion');
+      expect(projection.content.items).toHaveLength(3);
+      expect(projection.content.items[0].label).toBe('name');
+      expect(projection.content.items[0].kind).toBe(10); // Property
+      expect(projection.content.isIncomplete).toBe(false);
+    });
+  });
+
+  describe('projectToDefinition', () => {
+    it('should project to LSP definition location', () => {
+      const location = {
+        uri: 'file:///home/user/project/src/main.mjs',
+        range: {
+          start: { line: 10, character: 5 },
+          end: { line: 10, character: 20 },
+        },
+      };
+
+      const projection = projectToDefinition(location);
+
+      expect(projection.type).toBe('ide');
+      expect(projection.format).toBe('definition');
+      expect(projection.uri).toBe(location.uri);
+      expect(projection.range).toEqual(location.range);
+      expect(projection.content.uri).toBe(location.uri);
+    });
+  });
+
+  describe('projectToDiagnostic', () => {
+    it('should project to LSP diagnostic (error)', () => {
+      const issue = {
+        message: 'Variable not defined',
+        severity: 'error',
+        range: {
+          start: { line: 5, character: 10 },
+          end: { line: 5, character: 15 },
+        },
+        code: 'E001',
+      };
+
+      const diagnostic = projectToDiagnostic(issue);
+
+      expect(diagnostic.message).toBe('Variable not defined');
+      expect(diagnostic.severity).toBe(1); // Error
+      expect(diagnostic.code).toBe('E001');
+      expect(diagnostic.source).toBe('kgc-runtime');
+    });
+
+    it('should handle warning severity', () => {
+      const issue = {
+        message: 'Unused variable',
+        severity: 'warning',
+        range: {
+          start: { line: 0, character: 0 },
+          end: { line: 0, character: 1 },
+        },
+      };
+
+      const diagnostic = projectToDiagnostic(issue);
+
+      expect(diagnostic.severity).toBe(2); // Warning
+    });
+  });
+
+  describe('projectToSymbol', () => {
+    it('should project to LSP document symbol', () => {
+      const symbolInfo = {
+        name: 'calculateSum',
+        kind: 'function',
+        containerName: 'math.utils',
+        location: {
+          uri: 'file:///project/math.mjs',
+          range: {
+            start: { line: 10, character: 0 },
+            end: { line: 15, character: 1 },
+          },
+        },
+      };
+
+      const symbol = projectToSymbol(symbolInfo);
+
+      expect(symbol.name).toBe('calculateSum');
+      expect(symbol.kind).toBe(12); // Function
+      expect(symbol.containerName).toBe('math.utils');
+    });
+  });
+
+  describe('projectToCodeAction', () => {
+    it('should project to LSP code action', () => {
+      const actionInfo = {
+        title: 'Fix import statement',
+        kind: 'quickfix',
+        edit: {
+          changes: {
+            'file:///project/main.mjs': [
+              {
+                range: { start: { line: 0, character: 0 }, end: { line: 0, character: 10 } },
+                newText: 'import { x } from "./utils.mjs"',
+              },
+            ],
+          },
+        },
+        isPreferred: true,
+      };
+
+      const codeAction = projectToCodeAction(actionInfo);
+
+      expect(codeAction.title).toBe('Fix import statement');
+      expect(codeAction.kind).toBe('quickfix');
+      expect(codeAction.isPreferred).toBe(true);
+    });
+  });
+
+  describe('projectToCodeLens', () => {
+    it('should project work item to code lens', () => {
+      const workItem = {
+        id: 'item-001',
+        goal: 'Run tests',
+      };
+
+      const range = {
+        start: { line: 5, character: 0 },
+        end: { line: 5, character: 20 },
+      };
+
+      const codeLens = projectToCodeLens(workItem, range);
+
+      expect(codeLens.range).toEqual(range);
+      expect(codeLens.command.title).toContain('Run tests');
+      expect(codeLens.command.command).toBe('kgc.executeWorkItem');
+      expect(codeLens.command.arguments).toEqual(['item-001']);
+    });
+  });
+
+  describe('projectToSignatureHelp', () => {
+    it('should project to LSP signature help', () => {
+      const fnInfo = {
+        name: 'processData',
+        documentation: 'Processes data with options',
+        parameters: [
+          { name: 'data', type: 'any', description: 'Data to process' },
+          { name: 'options', type: 'object', description: 'Processing options' },
+        ],
+        returns: { type: 'Promise<any>', description: 'Processed data' },
+      };
+
+      const projection = projectToSignatureHelp(fnInfo, 1);
+
+      expect(projection.type).toBe('ide');
+      expect(projection.format).toBe('lsp');
+      expect(projection.content.signatures).toHaveLength(1);
+      expect(projection.content.activeParameter).toBe(1);
+      expect(projection.content.signatures[0].parameters).toHaveLength(2);
+    });
+  });
+
+  describe('projectToSemanticTokens', () => {
+    it('should project to LSP semantic tokens', () => {
+      const tokens = [
+        { line: 0, char: 0, length: 6, tokenType: 'function' },
+        { line: 0, char: 7, length: 4, tokenType: 'variable' },
+        { line: 1, char: 2, length: 5, tokenType: 'class', modifiers: ['declaration'] },
+      ];
+
+      const semanticTokens = projectToSemanticTokens(tokens);
+
+      expect(Array.isArray(semanticTokens.data)).toBe(true);
+      expect(semanticTokens.data.length).toBeGreaterThan(0);
+      // Delta encoding: [deltaLine, deltaChar, length, typeIndex, modifierBits]
+      expect(semanticTokens.data.length % 5).toBe(0);
+    });
+  });
+});