@lokascript/framework 2.0.0 → 2.1.0

package/src/ir/json-schema.test.ts

@@ -0,0 +1,281 @@
+import { describe, it, expect } from 'vitest';
+import { validateSemanticJSON, jsonToSemanticNode, semanticNodeToJSON } from './json-schema';
+import type { SemanticJSON } from './types';
+import {
+  createCommandNode,
+  createSelector,
+  createLiteral,
+  createReference,
+  createFlag,
+} from '../core/types';
+
+describe('validateSemanticJSON', () => {
+  it('validates a correct input', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: { type: 'selector', value: '.active' },
+      },
+    };
+    expect(validateSemanticJSON(input)).toEqual([]);
+  });
+
+  it('rejects missing action', () => {
+    const input = { roles: {} } as unknown as SemanticJSON;
+    const diags = validateSemanticJSON(input);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].code).toBe('INVALID_ACTION');
+  });
+
+  it('rejects invalid role value', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: 'not-an-object' as unknown as { type: 'selector'; value: string },
+      },
+    };
+    const diags = validateSemanticJSON(input);
+    expect(diags.some(d => d.code === 'INVALID_ROLE_VALUE')).toBe(true);
+  });
+
+  it('rejects invalid value type', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: { type: 'unknown' as 'selector', value: '.active' },
+      },
+    };
+    const diags = validateSemanticJSON(input);
+    expect(diags.some(d => d.code === 'INVALID_VALUE_TYPE')).toBe(true);
+  });
+
+  it('rejects missing value field', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: { type: 'selector' } as unknown as { type: 'selector'; value: string },
+      },
+    };
+    const diags = validateSemanticJSON(input);
+    expect(diags.some(d => d.code === 'MISSING_VALUE')).toBe(true);
+  });
+
+  it('validates trigger', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: { patient: { type: 'selector', value: '.active' } },
+      trigger: { event: '' },
+    };
+    const diags = validateSemanticJSON(input);
+    expect(diags.some(d => d.code === 'INVALID_TRIGGER')).toBe(true);
+  });
+
+  it('accepts valid trigger', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: { patient: { type: 'selector', value: '.active' } },
+      trigger: { event: 'click' },
+    };
+    expect(validateSemanticJSON(input)).toEqual([]);
+  });
+});
+
+describe('jsonToSemanticNode', () => {
+  it('converts a basic command', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: { type: 'selector', value: '.active' },
+      },
+    };
+    const node = jsonToSemanticNode(input);
+    expect(node.kind).toBe('command');
+    expect(node.action).toBe('toggle');
+    expect(node.roles.get('patient')).toMatchObject({ type: 'selector', value: '.active' });
+  });
+
+  it('converts selector values with kind detection', () => {
+    const input: SemanticJSON = {
+      action: 'add',
+      roles: {
+        patient: { type: 'selector', value: '.highlight' },
+        destination: { type: 'selector', value: '#output' },
+      },
+    };
+    const node = jsonToSemanticNode(input);
+    const dest = node.roles.get('destination');
+    expect(dest).toMatchObject({ type: 'selector', value: '#output', selectorKind: 'id' });
+    const pat = node.roles.get('patient');
+    expect(pat).toMatchObject({ type: 'selector', value: '.highlight', selectorKind: 'class' });
+  });
+
+  it('converts literal values', () => {
+    const input: SemanticJSON = {
+      action: 'put',
+      roles: {
+        patient: { type: 'literal', value: 'hello' },
+        quantity: { type: 'literal', value: 42 },
+        flag: { type: 'literal', value: true },
+      },
+    };
+    const node = jsonToSemanticNode(input);
+    expect(node.roles.get('patient')).toMatchObject({
+      type: 'literal',
+      value: 'hello',
+      dataType: 'string',
+    });
+    expect(node.roles.get('quantity')).toMatchObject({
+      type: 'literal',
+      value: 42,
+      dataType: 'number',
+    });
+    expect(node.roles.get('flag')).toMatchObject({
+      type: 'literal',
+      value: true,
+      dataType: 'boolean',
+    });
+  });
+
+  it('converts reference values', () => {
+    const input: SemanticJSON = {
+      action: 'add',
+      roles: {
+        destination: { type: 'reference', value: 'me' },
+      },
+    };
+    const node = jsonToSemanticNode(input);
+    expect(node.roles.get('destination')).toMatchObject({ type: 'reference', value: 'me' });
+  });
+
+  it('converts expression values', () => {
+    const input: SemanticJSON = {
+      action: 'set',
+      roles: {
+        goal: { type: 'expression', value: 'x + 1' },
+      },
+    };
+    const node = jsonToSemanticNode(input);
+    expect(node.roles.get('goal')).toMatchObject({ type: 'expression', raw: 'x + 1' });
+  });
+
+  it('wraps in event handler when trigger is present', () => {
+    const input: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: { type: 'selector', value: '.active' },
+      },
+      trigger: { event: 'click' },
+    };
+    const node = jsonToSemanticNode(input);
+    expect(node.kind).toBe('event-handler');
+    expect(node.action).toBe('on');
+    const eventNode = node as { body: Array<{ action: string; roles: Map<string, unknown> }> };
+    expect(eventNode.body).toHaveLength(1);
+    expect(eventNode.body[0].action).toBe('toggle');
+  });
+
+  it('sets sourceLanguage to json', () => {
+    const node = jsonToSemanticNode({
+      action: 'toggle',
+      roles: { patient: { type: 'selector', value: '.active' } },
+    });
+    expect(node.metadata?.sourceLanguage).toBe('json');
+  });
+});
+
+describe('semanticNodeToJSON', () => {
+  it('converts a basic command', () => {
+    const node = createCommandNode('toggle', {
+      patient: createSelector('.active'),
+    });
+    const json = semanticNodeToJSON(node);
+    expect(json.action).toBe('toggle');
+    expect(json.roles.patient).toEqual({ type: 'selector', value: '.active' });
+    expect(json.trigger).toBeUndefined();
+  });
+
+  it('converts multiple role types', () => {
+    const node = createCommandNode('set', {
+      destination: createLiteral('count', 'string'),
+      goal: createLiteral(42, 'number'),
+    });
+    const json = semanticNodeToJSON(node);
+    expect(json.roles.destination).toEqual({ type: 'literal', value: 'count' });
+    expect(json.roles.goal).toEqual({ type: 'literal', value: 42 });
+  });
+
+  it('handles reference values', () => {
+    const node = createCommandNode('add', {
+      patient: createSelector('.active'),
+      destination: createReference('me'),
+    });
+    const json = semanticNodeToJSON(node);
+    expect(json.roles.destination).toEqual({ type: 'reference', value: 'me' });
+  });
+});
+
+describe('flag support in JSON', () => {
+  it('validates flag type as valid', () => {
+    const input: SemanticJSON = {
+      action: 'column',
+      roles: {
+        'primary-key': { type: 'flag', value: true },
+      },
+    };
+    expect(validateSemanticJSON(input)).toEqual([]);
+  });
+
+  it('converts flag JSON to FlagValue', () => {
+    const input: SemanticJSON = {
+      action: 'column',
+      roles: {
+        name: { type: 'literal', value: 'id' },
+        'primary-key': { type: 'flag', value: true },
+      },
+    };
+    const node = jsonToSemanticNode(input);
+    expect(node.roles.get('primary-key')).toEqual({
+      type: 'flag',
+      name: 'true',
+      enabled: true,
+    });
+  });
+
+  it('converts FlagValue to JSON', () => {
+    const node = createCommandNode('column', {
+      name: createLiteral('id', 'string'),
+      'primary-key': createFlag('primary-key', true),
+      'not-null': createFlag('not-null', true),
+    });
+    const json = semanticNodeToJSON(node);
+    expect(json.roles['primary-key']).toEqual({ type: 'flag', value: true });
+    expect(json.roles['not-null']).toEqual({ type: 'flag', value: true });
+  });
+
+  it('converts disabled FlagValue to JSON', () => {
+    const node = createCommandNode('field', {
+      nullable: createFlag('nullable', false),
+    });
+    const json = semanticNodeToJSON(node);
+    expect(json.roles.nullable).toEqual({ type: 'flag', value: false });
+  });
+});
+
+describe('round-trip: JSON → SemanticNode → JSON', () => {
+  it('preserves command structure', () => {
+    const original: SemanticJSON = {
+      action: 'toggle',
+      roles: {
+        patient: { type: 'selector', value: '.active' },
+        destination: { type: 'selector', value: '#button' },
+      },
+    };
+    const node = jsonToSemanticNode(original);
+    const roundTripped = semanticNodeToJSON(node);
+    expect(roundTripped.action).toBe(original.action);
+    expect(roundTripped.roles.patient.type).toBe('selector');
+    expect(roundTripped.roles.patient.value).toBe('.active');
+    expect(roundTripped.roles.destination.type).toBe('selector');
+    expect(roundTripped.roles.destination.value).toBe('#button');
+  });
+});

package/src/ir/json-schema.ts

@@ -0,0 +1,299 @@
+/**
+ * LLM JSON Schema Conversion (DEPRECATED)
+ *
+ * These functions are superseded by the unified protocol JSON functions in
+ * protocol-json.ts. `fromProtocolJSON()` now accepts optional `kind` (defaults
+ * to "command") and `trigger` sugar, making these wrappers unnecessary.
+ *
+ * Use instead:
+ * - `validateProtocolJSON()` instead of `validateSemanticJSON()`
+ * - `fromProtocolJSON()` instead of `jsonToSemanticNode()`
+ * - `toProtocolJSON()` instead of `semanticNodeToJSON()`
+ *
+ * These functions are kept for backward compatibility and will be removed
+ * in a future major version.
+ */
+
+import type {
+  SemanticNode,
+  SemanticValue,
+  SemanticRole,
+  EventHandlerSemanticNode,
+  CompoundSemanticNode,
+} from '../core/types';
+import {
+  createCommandNode,
+  createEventHandlerNode,
+  createSelector,
+  createLiteral,
+  createReference,
+  createExpression,
+  createFlag,
+} from '../core/types';
+import type { SemanticJSON, SemanticJSONValue, IRDiagnostic } from './types';
+
+// =============================================================================
+// Validation
+// =============================================================================
+
+const VALID_VALUE_TYPES = new Set([
+  'selector',
+  'literal',
+  'reference',
+  'expression',
+  'property-path',
+  'flag',
+]);
+
+/**
+ * Validate LLM JSON input structure.
+ * Returns diagnostics (empty array = valid).
+ * @deprecated Use `validateProtocolJSON()` from `protocol-json.ts` instead.
+ */
+export function validateSemanticJSON(input: SemanticJSON): IRDiagnostic[] {
+  const diagnostics: IRDiagnostic[] = [];
+
+  // Action is required and must be a string
+  if (!input.action || typeof input.action !== 'string') {
+    diagnostics.push({
+      severity: 'error',
+      code: 'INVALID_ACTION',
+      message: 'Field "action" is required and must be a string.',
+      suggestion: 'Provide a command name like "toggle", "add", "set", etc.',
+    });
+    return diagnostics; // Can't proceed without action
+  }
+
+  // Roles validation
+  if (input.roles && typeof input.roles === 'object') {
+    for (const [role, value] of Object.entries(input.roles)) {
+      if (!value || typeof value !== 'object') {
+        diagnostics.push({
+          severity: 'error',
+          code: 'INVALID_ROLE_VALUE',
+          message: `Role "${role}" must be an object with "type" and "value" fields.`,
+          suggestion: 'Use: { "type": "selector", "value": ".active" }',
+        });
+        continue;
+      }
+
+      const v = value as SemanticJSONValue;
+      if (!VALID_VALUE_TYPES.has(v.type)) {
+        diagnostics.push({
+          severity: 'error',
+          code: 'INVALID_VALUE_TYPE',
+          message: `Role "${role}" has invalid type "${v.type}".`,
+          suggestion: 'Valid types: selector, literal, reference, expression, property-path.',
+        });
+      }
+
+      if (v.value === undefined || v.value === null) {
+        diagnostics.push({
+          severity: 'error',
+          code: 'MISSING_VALUE',
+          message: `Role "${role}" is missing the "value" field.`,
+        });
+      }
+    }
+  }
+
+  // Trigger validation (optional)
+  if (input.trigger) {
+    if (!input.trigger.event || typeof input.trigger.event !== 'string') {
+      diagnostics.push({
+        severity: 'error',
+        code: 'INVALID_TRIGGER',
+        message: 'Trigger "event" is required and must be a string.',
+        suggestion: 'Use an event name like "click", "mouseover", "keydown".',
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+// =============================================================================
+// JSON → SemanticNode
+// =============================================================================
+
+/**
+ * Convert validated SemanticJSON to a SemanticNode.
+ *
+ * Returns a properly typed SemanticNode using the framework's factory functions.
+ * If `trigger` is present, wraps the command in an event handler node.
+ * @deprecated Use `fromProtocolJSON()` from `protocol-json.ts` instead.
+ */
+export function jsonToSemanticNode(input: SemanticJSON): SemanticNode {
+  const roles = new Map<SemanticRole, SemanticValue>();
+
+  if (input.roles) {
+    for (const [role, value] of Object.entries(input.roles)) {
+      roles.set(role as SemanticRole, convertJSONValue(value));
+    }
+  }
+
+  // Event handler wrapping
+  if (input.trigger) {
+    // Set the event role
+    roles.set('event' as SemanticRole, createLiteral(input.trigger.event, 'string'));
+
+    // Build body as a single command node
+    const bodyRoles = new Map(roles);
+    bodyRoles.delete('event' as SemanticRole);
+    const bodyNode = createCommandNode(input.action, bodyRoles);
+
+    return createEventHandlerNode(
+      'on',
+      roles,
+      [bodyNode],
+      { sourceLanguage: 'json' },
+      (input.trigger.modifiers as Record<string, unknown> | undefined) ?? {}
+    );
+  }
+
+  return createCommandNode(input.action, roles, {
+    sourceLanguage: 'json',
+  });
+}
+
+// =============================================================================
+// SemanticNode → JSON
+// =============================================================================
+
+/**
+ * Convert a SemanticNode to SemanticJSON format.
+ *
+ * This is the inverse of jsonToSemanticNode(). For event handlers,
+ * the event is extracted into the `trigger` field.
+ * @deprecated Use `toProtocolJSON()` from `protocol-json.ts` instead.
+ */
+export function semanticNodeToJSON(node: SemanticNode): SemanticJSON {
+  if (node.kind === 'compound') {
+    // Compound nodes: use first statement's action, flatten roles
+    const compound = node as CompoundSemanticNode;
+    if (compound.statements.length > 0) {
+      return semanticNodeToJSON(compound.statements[0]);
+    }
+    return { action: 'compound', roles: {} };
+  }
+
+  if (node.kind === 'event-handler') {
+    const eventNode = node as EventHandlerSemanticNode;
+    const bodyAction = eventNode.body?.[0]?.action ?? node.action;
+    const roles: Record<string, SemanticJSONValue> = {};
+
+    // Convert body's roles (not the event handler's)
+    if (eventNode.body?.[0]) {
+      for (const [role, value] of eventNode.body[0].roles) {
+        roles[role] = semanticValueToJSON(value);
+      }
+    }
+
+    // Extract event from roles
+    const eventValue = node.roles.get('event');
+    const eventName = eventValue
+      ? 'value' in eventValue
+        ? String(eventValue.value)
+        : 'raw' in eventValue
+          ? eventValue.raw
+          : 'unknown'
+      : 'unknown';
+
+    const result: SemanticJSON = {
+      action: bodyAction === 'on' ? (eventNode.body?.[0]?.action ?? 'on') : bodyAction,
+      roles,
+      trigger: {
+        event: eventName,
+      },
+    };
+
+    if (eventNode.eventModifiers && Object.keys(eventNode.eventModifiers).length > 0) {
+      result.trigger!.modifiers = eventNode.eventModifiers as Record<string, unknown>;
+    }
+
+    return result;
+  }
+
+  // Regular command
+  const roles: Record<string, SemanticJSONValue> = {};
+  for (const [role, value] of node.roles) {
+    roles[role] = semanticValueToJSON(value);
+  }
+
+  return { action: node.action, roles };
+}
+
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+
+/**
+ * Convert a SemanticJSONValue to a SemanticValue.
+ */
+function convertJSONValue(value: SemanticJSONValue): SemanticValue {
+  switch (value.type) {
+    case 'selector':
+      return createSelector(String(value.value), detectSelectorKind(String(value.value)));
+
+    case 'literal':
+      return createLiteral(
+        value.value,
+        typeof value.value === 'number'
+          ? 'number'
+          : typeof value.value === 'boolean'
+            ? 'boolean'
+            : 'string'
+      );
+
+    case 'reference':
+      return createReference(String(value.value));
+
+    case 'expression':
+      return createExpression(String(value.value));
+
+    case 'property-path':
+      // Property paths in JSON are represented as dot-separated strings
+      return createExpression(String(value.value));
+
+    case 'flag':
+      return createFlag(String(value.value), true);
+
+    default:
+      return createLiteral(String(value.value), 'string');
+  }
+}
+
+/**
+ * Convert a SemanticValue to a SemanticJSONValue.
+ */
+function semanticValueToJSON(value: SemanticValue): SemanticJSONValue {
+  switch (value.type) {
+    case 'selector':
+      return { type: 'selector', value: value.value };
+
+    case 'literal':
+      return { type: 'literal', value: value.value };
+
+    case 'reference':
+      return { type: 'reference', value: value.value };
+
+    case 'expression':
+      return { type: 'expression', value: value.raw };
+
+    case 'property-path':
+      return {
+        type: 'property-path',
+        value: `${semanticValueToJSON(value.object).value}.${value.property}`,
+      };
+
+    case 'flag':
+      return { type: 'flag', value: value.enabled };
+  }
+}
+
+function detectSelectorKind(selector: string): 'id' | 'class' | 'attribute' | 'complex' {
+  if (selector.startsWith('#')) return 'id';
+  if (selector.startsWith('.')) return 'class';
+  if (selector.startsWith('[')) return 'attribute';
+  return 'complex';
+}