@lokascript/framework 2.0.0 → 2.1.0

package/src/ir/types.ts

@@ -0,0 +1,181 @@
+/**
+ * IR (Intermediate Representation) Types
+ *
+ * Types for the explicit bracket syntax, LLM JSON format, and
+ * schema-based validation. These are domain-agnostic — they work
+ * for any DSL built on the framework.
+ */
+
+import type { CommandSchema } from '../schema/command-schema';
+
+// =============================================================================
+// LLM JSON Format
+// =============================================================================
+
+/**
+ * Structured input format for LLMs.
+ * No parsing ambiguity — action and roles are explicitly typed.
+ *
+ * @example
+ * ```json
+ * {
+ *   "action": "toggle",
+ *   "roles": { "patient": { "type": "selector", "value": ".active" } },
+ *   "trigger": { "event": "click" }
+ * }
+ * ```
+ */
+export interface SemanticJSON {
+  /** The command/action name */
+  action: string;
+  /** Named semantic roles with typed values */
+  roles: Record<string, SemanticJSONValue>;
+  /** Optional event trigger (wraps command in event handler) */
+  trigger?: {
+    event: string;
+    modifiers?: Record<string, unknown>;
+  };
+}
+
+/**
+ * A typed value in the LLM JSON format.
+ */
+export interface SemanticJSONValue {
+  type: 'selector' | 'literal' | 'reference' | 'expression' | 'property-path' | 'flag';
+  value: string | number | boolean;
+}
+
+// =============================================================================
+// Schema Lookup
+// =============================================================================
+
+/**
+ * Interface for optional schema-based role validation in the explicit parser.
+ * Consumers provide this to validate roles against command definitions.
+ *
+ * When not provided, the parser accepts any role names.
+ */
+export interface SchemaLookup {
+  getSchema(action: string): CommandSchema | undefined;
+}
+
+/**
+ * Options for parseExplicit().
+ */
+export interface ParseExplicitOptions {
+  /** Optional schema lookup for role validation */
+  schemaLookup?: SchemaLookup;
+  /** Custom set of valid reference names (defaults to DEFAULT_REFERENCES) */
+  referenceSet?: ReadonlySet<string>;
+}
+
+// =============================================================================
+// Diagnostics
+// =============================================================================
+
+/**
+ * A diagnostic message from IR validation.
+ *
+ * Uses required `code` field (compatible with both framework Diagnostic
+ * and compilation-service Diagnostic types via structural typing).
+ */
+export interface IRDiagnostic {
+  severity: 'error' | 'warning' | 'info';
+  code: string;
+  message: string;
+  suggestion?: string;
+}
+
+// =============================================================================
+// Protocol Full-Fidelity JSON Format
+// =============================================================================
+// These types match the wire format spec (protocol/spec/wire-format.md).
+// Wire format has 3 node kinds; TS-only kinds (conditional, loop) are losslessly
+// encoded as command nodes with v1.1 extension fields.
+// property-path is flattened to expression.
+
+export type ProtocolNodeKind = 'command' | 'event-handler' | 'compound';
+export type ProtocolChainType = 'then' | 'and' | 'async' | 'sequential' | 'pipe';
+
+/**
+ * A typed semantic value in the protocol full-fidelity JSON format.
+ * Matches protocol/spec/wire-format.md "Value Shapes" table.
+ */
+export interface ProtocolValueJSON {
+  type: 'selector' | 'literal' | 'reference' | 'expression' | 'property-path' | 'flag';
+  value?: string | number | boolean;
+  dataType?: 'string' | 'number' | 'boolean' | 'duration';
+  raw?: string; // expression only
+  name?: string; // flag only
+  enabled?: boolean; // flag only
+  selectorKind?: 'id' | 'class' | 'attribute' | 'element' | 'complex'; // selector only, optional
+}
+
+/**
+ * Protocol JSON node — matches protocol/spec/wire-format.md.
+ * Produced by toProtocolJSON() and consumed by fromProtocolJSON().
+ *
+ * `kind` defaults to `"command"` when omitted.
+ * `trigger` is convenience sugar that wraps a command in an event handler.
+ */
+export interface ProtocolNodeJSON {
+  kind?: ProtocolNodeKind; // defaults to "command" when absent
+  action: string;
+  roles: Record<string, ProtocolValueJSON>;
+  trigger?: { event: string; modifiers?: Record<string, unknown> }; // convenience sugar
+  body?: ProtocolNodeJSON[]; // event-handler body OR try body (v1.2)
+  statements?: ProtocolNodeJSON[]; // compound only
+  chainType?: ProtocolChainType; // compound only
+  // Conditional fields (v1.1)
+  thenBranch?: ProtocolNodeJSON[];
+  elseBranch?: ProtocolNodeJSON[];
+  // Loop fields (v1.1)
+  loopVariant?: 'forever' | 'times' | 'for' | 'while' | 'until';
+  loopBody?: ProtocolNodeJSON[];
+  loopVariable?: string;
+  indexVariable?: string;
+  // Type constraint diagnostics (v1.2)
+  diagnostics?: ProtocolDiagnosticJSON[];
+  // Metadata annotations (v1.2)
+  annotations?: AnnotationJSON[];
+  // Error handling: try/catch/finally (v1.2)
+  catchBranch?: ProtocolNodeJSON[];
+  finallyBranch?: ProtocolNodeJSON[];
+  // Async coordination: all/race (v1.2)
+  asyncVariant?: 'all' | 'race';
+  asyncBody?: ProtocolNodeJSON[];
+  // Pattern matching: match/arms (v1.2)
+  arms?: MatchArmJSON[];
+  defaultArm?: ProtocolNodeJSON[];
+}
+
+// =============================================================================
+// v1.2 Sub-types
+// =============================================================================
+
+/** A type constraint diagnostic in protocol wire format (v1.2). */
+export interface ProtocolDiagnosticJSON {
+  level: 'error' | 'warning';
+  role: string;
+  message: string;
+  code: string;
+}
+
+/** A metadata annotation in protocol wire format (v1.2). */
+export interface AnnotationJSON {
+  name: string;
+  value?: string;
+}
+
+/** A match arm in protocol wire format (v1.2). */
+export interface MatchArmJSON {
+  pattern: ProtocolValueJSON;
+  body: ProtocolNodeJSON[];
+}
+
+/** Versioned envelope for multi-node LSE documents (v1.2). */
+export interface LSEEnvelopeJSON {
+  lseVersion: string;
+  features?: string[];
+  nodes: ProtocolNodeJSON[];
+}

package/src/prompts/index.ts

@@ -0,0 +1,15 @@
+/**
+ * LLM Prompt Generation
+ *
+ * Auto-generates system prompts from CommandSchema[] for teaching LLMs
+ * to output valid LokaScript Explicit Syntax.
+ */
+
+export type {
+  PromptGeneratorConfig,
+  GeneratedPrompt,
+  PromptSection,
+  PromptMetadata,
+} from './types';
+
+export { generatePrompt, generateExamples, generateProtocolReference } from './prompt-generator';

package/src/prompts/prompt-generator.test.ts

@@ -0,0 +1,386 @@
+/**
+ * Tests for LLM Prompt Generator
+ */
+
+import { describe, it, expect } from 'vitest';
+import { generatePrompt, generateExamples, generateProtocolReference } from './prompt-generator';
+import type { PromptGeneratorConfig } from './types';
+import { defineCommand, defineRole } from '../schema/command-schema';
+import type { CommandSchema } from '../schema/command-schema';
+
+// =============================================================================
+// Test Schemas (mimics domain-flow patterns)
+// =============================================================================
+
+const fetchSchema: CommandSchema = defineCommand({
+  action: 'fetch',
+  description: 'Fetch data from a URL and deliver to a target element',
+  category: 'source',
+  primaryRole: 'source',
+  roles: [
+    defineRole({
+      role: 'source',
+      description: 'URL to fetch from',
+      required: true,
+      expectedTypes: ['expression'],
+    }),
+    defineRole({
+      role: 'style',
+      description: 'Response format (json, html, text)',
+      required: false,
+      expectedTypes: ['expression'],
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'Target element to deliver data to',
+      required: false,
+      expectedTypes: ['selector', 'expression'],
+    }),
+  ],
+});
+
+const submitSchema: CommandSchema = defineCommand({
+  action: 'submit',
+  description: 'Submit form data to a URL',
+  category: 'action',
+  primaryRole: 'patient',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'Form element to submit',
+      required: true,
+      expectedTypes: ['selector', 'expression'],
+    }),
+    defineRole({
+      role: 'destination',
+      description: 'URL to submit to',
+      required: true,
+      expectedTypes: ['expression'],
+    }),
+    defineRole({
+      role: 'style',
+      description: 'Request encoding (json, form, multipart)',
+      required: false,
+      expectedTypes: ['expression'],
+    }),
+  ],
+});
+
+const toggleSchema: CommandSchema = defineCommand({
+  action: 'toggle',
+  description: 'Toggle a class or attribute on an element',
+  category: 'dom',
+  primaryRole: 'patient',
+  roles: [
+    defineRole({
+      role: 'patient',
+      description: 'The CSS selector to toggle',
+      required: true,
+      expectedTypes: ['selector'],
+    }),
+  ],
+});
+
+const testSchemas: readonly CommandSchema[] = [fetchSchema, submitSchema, toggleSchema];
+
+function makeConfig(overrides?: Partial<PromptGeneratorConfig>): PromptGeneratorConfig {
+  return {
+    domain: 'test',
+    description: 'Test domain for unit testing',
+    schemas: testSchemas,
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// generatePrompt()
+// =============================================================================
+
+describe('generatePrompt', () => {
+  it('returns a GeneratedPrompt with all sections', () => {
+    const result = generatePrompt(makeConfig());
+    expect(result.text).toBeTruthy();
+    expect(result.sections.length).toBeGreaterThanOrEqual(4);
+    expect(result.metadata.domain).toBe('test');
+  });
+
+  it('includes protocol section', () => {
+    const result = generatePrompt(makeConfig());
+    const protocol = result.sections.find(s => s.id === 'protocol');
+    expect(protocol).toBeDefined();
+    expect(protocol!.content).toContain('[command role1:value1');
+    expect(protocol!.content).toContain('lowercased');
+  });
+
+  it('includes value types section', () => {
+    const result = generatePrompt(makeConfig());
+    const types = result.sections.find(s => s.id === 'value-types');
+    expect(types).toBeDefined();
+    expect(types!.content).toContain('Selector');
+    expect(types!.content).toContain('Duration');
+    expect(types!.content).toContain('Reference');
+  });
+
+  it('includes commands section with all schemas', () => {
+    const result = generatePrompt(makeConfig());
+    const commands = result.sections.find(s => s.id === 'commands');
+    expect(commands).toBeDefined();
+    expect(commands!.content).toContain('`fetch`');
+    expect(commands!.content).toContain('`submit`');
+    expect(commands!.content).toContain('`toggle`');
+  });
+
+  it('includes output format section', () => {
+    const result = generatePrompt(makeConfig());
+    const format = result.sections.find(s => s.id === 'output-format');
+    expect(format).toBeDefined();
+  });
+
+  it('includes error recovery section', () => {
+    const result = generatePrompt(makeConfig());
+    const recovery = result.sections.find(s => s.id === 'error-recovery');
+    expect(recovery).toBeDefined();
+    expect(recovery!.content).toContain('Unknown command');
+  });
+
+  it('counts commands and roles in metadata', () => {
+    const result = generatePrompt(makeConfig());
+    expect(result.metadata.commandCount).toBe(3);
+    // fetch: 3 roles, submit: 3 roles, toggle: 1 role = 7
+    expect(result.metadata.roleCount).toBe(7);
+  });
+
+  it('estimates approximate tokens', () => {
+    const result = generatePrompt(makeConfig());
+    expect(result.metadata.approximateTokens).toBeGreaterThan(0);
+    // Roughly chars/4
+    expect(result.metadata.approximateTokens).toBe(Math.ceil(result.text.length / 4));
+  });
+
+  // --- Output Format Variants ---
+
+  it('generates explicit-only format', () => {
+    const result = generatePrompt(makeConfig({ outputFormat: 'explicit' }));
+    const format = result.sections.find(s => s.id === 'output-format');
+    expect(format!.content).toContain('bracket syntax');
+    expect(format!.content).toContain('Do NOT output JSON');
+  });
+
+  it('generates json-only format', () => {
+    const result = generatePrompt(makeConfig({ outputFormat: 'json' }));
+    const format = result.sections.find(s => s.id === 'output-format');
+    expect(format!.content).toContain('JSON');
+    expect(format!.content).toContain('Do NOT output bracket syntax');
+  });
+
+  it('generates both format', () => {
+    const result = generatePrompt(makeConfig({ outputFormat: 'both' }));
+    const format = result.sections.find(s => s.id === 'output-format');
+    expect(format!.content).toContain('EITHER format');
+  });
+
+  // --- Command Documentation ---
+
+  it('documents required and optional roles', () => {
+    const result = generatePrompt(makeConfig());
+    const commands = result.sections.find(s => s.id === 'commands')!;
+    // fetch has 1 required (source) and 2 optional (style, destination)
+    expect(commands.content).toContain('**Required roles:**');
+    expect(commands.content).toContain('**Optional roles:**');
+    expect(commands.content).toContain('`source`');
+    expect(commands.content).toContain('`style`');
+    expect(commands.content).toContain('`destination`');
+  });
+
+  it('includes role type information', () => {
+    const result = generatePrompt(makeConfig());
+    const commands = result.sections.find(s => s.id === 'commands')!;
+    expect(commands.content).toContain('(type: expression)');
+    expect(commands.content).toContain('(type: selector)');
+  });
+
+  it('includes bracket syntax examples', () => {
+    const result = generatePrompt(makeConfig({ outputFormat: 'explicit' }));
+    const commands = result.sections.find(s => s.id === 'commands')!;
+    expect(commands.content).toContain('[fetch');
+    expect(commands.content).toContain('[submit');
+    expect(commands.content).toContain('[toggle');
+  });
+
+  it('includes JSON examples when format is json or both', () => {
+    const result = generatePrompt(makeConfig({ outputFormat: 'json' }));
+    const commands = result.sections.find(s => s.id === 'commands')!;
+    expect(commands.content).toContain('"action": "fetch"');
+    expect(commands.content).toContain('"roles"');
+  });
+
+  // --- Token Budget ---
+
+  it('truncates to maxTokens budget', () => {
+    const full = generatePrompt(makeConfig());
+    const truncated = generatePrompt(makeConfig({ maxTokens: 100 }));
+
+    expect(truncated.sections.length).toBeLessThanOrEqual(full.sections.length);
+    expect(truncated.text.length).toBeLessThan(full.text.length);
+  });
+
+  it('includes truncation marker when budget is exceeded', () => {
+    const result = generatePrompt(makeConfig({ maxTokens: 100 }));
+    // Either fewer sections or truncation marker
+    const hasFewerSections = result.sections.length < 5;
+    const hasTruncationMarker = result.text.includes('*(truncated)*');
+    expect(hasFewerSections || hasTruncationMarker).toBe(true);
+  });
+
+  // --- Examples Per Command ---
+
+  it('respects examplesPerCommand setting', () => {
+    const result1 = generatePrompt(makeConfig({ examplesPerCommand: 1 }));
+    const result3 = generatePrompt(makeConfig({ examplesPerCommand: 3 }));
+    // More examples = longer text
+    expect(result3.text.length).toBeGreaterThan(result1.text.length);
+  });
+});
+
+// =============================================================================
+// generateExamples()
+// =============================================================================
+
+describe('generateExamples', () => {
+  it('generates examples for a command with required + optional roles', () => {
+    const examples = generateExamples(fetchSchema, 3);
+    expect(examples.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('generates valid bracket syntax', () => {
+    const examples = generateExamples(fetchSchema, 2);
+    for (const ex of examples) {
+      expect(ex.explicit).toMatch(/^\[fetch\s/);
+      expect(ex.explicit).toMatch(/\]$/);
+    }
+  });
+
+  it('generates valid JSON format', () => {
+    const examples = generateExamples(fetchSchema, 2);
+    for (const ex of examples) {
+      expect(ex.json.action).toBe('fetch');
+      expect(ex.json.roles).toBeDefined();
+      expect(typeof ex.json.roles).toBe('object');
+    }
+  });
+
+  it('always includes required roles', () => {
+    const examples = generateExamples(fetchSchema, 3);
+    for (const ex of examples) {
+      // source is required
+      expect(ex.json.roles['source']).toBeDefined();
+    }
+  });
+
+  it('generates selector values for selector-typed roles', () => {
+    const examples = generateExamples(toggleSchema, 1);
+    const patientValue = examples[0].json.roles['patient'];
+    expect(patientValue).toBeDefined();
+    expect(patientValue.type).toBe('selector');
+    expect(String(patientValue.value)).toMatch(/^[#.@*\[]/);
+  });
+
+  it('generates expression values for expression-typed roles', () => {
+    const examples = generateExamples(fetchSchema, 1);
+    const sourceValue = examples[0].json.roles['source'];
+    expect(sourceValue).toBeDefined();
+    expect(sourceValue.type).toBe('expression');
+  });
+
+  it('limits output to requested count', () => {
+    const one = generateExamples(fetchSchema, 1);
+    expect(one.length).toBe(1);
+  });
+
+  it('handles schema with no optional roles', () => {
+    const examples = generateExamples(toggleSchema, 3);
+    // toggle has only 1 required role, so only 1 combination
+    expect(examples.length).toBe(1);
+  });
+
+  it('handles schema with all required roles', () => {
+    const examples = generateExamples(submitSchema, 3);
+    // submit: 2 required + 1 optional = combos: [req], [req+opt1], total 2
+    expect(examples.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('generates unique combinations', () => {
+    const examples = generateExamples(fetchSchema, 4);
+    const explicits = examples.map(e => e.explicit);
+    const unique = new Set(explicits);
+    expect(unique.size).toBe(examples.length);
+  });
+});
+
+// =============================================================================
+// generateProtocolReference()
+// =============================================================================
+
+describe('generateProtocolReference', () => {
+  it('returns a markdown string with protocol info', () => {
+    const ref = generateProtocolReference();
+    expect(ref).toContain('LokaScript Explicit Syntax');
+    expect(ref).toContain('[command');
+  });
+
+  it('includes value type information', () => {
+    const ref = generateProtocolReference();
+    expect(ref).toContain('Selector');
+    expect(ref).toContain('Duration');
+    expect(ref).toContain('Boolean');
+    expect(ref).toContain('Reference');
+  });
+
+  it('returns non-empty string', () => {
+    const ref = generateProtocolReference();
+    expect(ref.length).toBeGreaterThan(100);
+  });
+});
+
+// =============================================================================
+// Edge Cases
+// =============================================================================
+
+describe('edge cases', () => {
+  it('handles empty schemas array', () => {
+    const result = generatePrompt(makeConfig({ schemas: [] }));
+    expect(result.metadata.commandCount).toBe(0);
+    expect(result.metadata.roleCount).toBe(0);
+    expect(result.text).toBeTruthy();
+  });
+
+  it('handles schema with no roles', () => {
+    const noRoleSchema = defineCommand({
+      action: 'noop',
+      roles: [],
+      primaryRole: 'patient',
+    });
+    const examples = generateExamples(noRoleSchema, 2);
+    expect(examples.length).toBeGreaterThanOrEqual(0);
+  });
+
+  it('handles schema with only optional roles', () => {
+    const optionalOnlySchema = defineCommand({
+      action: 'log',
+      roles: [
+        defineRole({ role: 'patient', required: false, expectedTypes: ['expression'] }),
+        defineRole({ role: 'style', required: false, expectedTypes: ['literal'] }),
+      ],
+      primaryRole: 'patient',
+    });
+    const examples = generateExamples(optionalOnlySchema, 3);
+    expect(examples.length).toBeGreaterThan(0);
+  });
+
+  it('handles very small maxTokens', () => {
+    const result = generatePrompt(makeConfig({ maxTokens: 10 }));
+    // Should still produce something
+    expect(result.text.length).toBeGreaterThan(0);
+    expect(result.sections.length).toBeGreaterThanOrEqual(1);
+  });
+});