@lokascript/framework 2.0.0

package/src/schema/command-schema.ts

@@ -0,0 +1,118 @@
+/**
+ * Command Schema Types
+ *
+ * Defines the structure of DSL commands for pattern generation.
+ * These schemas are language-neutral and describe the semantic structure
+ * of commands rather than their surface syntax.
+ */
+
+import type { ActionType, SemanticRole, SemanticValue, ExpectedType } from '../core/types';
+
+/**
+ * Command schema - defines a DSL command's structure.
+ */
+export interface CommandSchema {
+  /** The action type (command name) */
+  readonly action: ActionType;
+
+  /** Human-readable description */
+  readonly description: string;
+
+  /** Roles this command accepts */
+  readonly roles: RoleSpec[];
+
+  /** The primary role (what the command acts on) */
+  readonly primaryRole: SemanticRole;
+
+  /** Category for grouping (DSL-specific) */
+  readonly category: string;
+
+  /** Whether this command typically has a body (like event handlers, blocks) */
+  readonly hasBody?: boolean;
+
+  /** Notes about special handling or usage */
+  readonly notes?: string;
+}
+
+/**
+ * Role specification - defines a semantic role in a command.
+ */
+export interface RoleSpec {
+  /** The semantic role */
+  readonly role: SemanticRole;
+
+  /** Description of what this role represents */
+  readonly description: string;
+
+  /** Whether this role is required */
+  readonly required: boolean;
+
+  /** Expected value types */
+  readonly expectedTypes: Array<ExpectedType>;
+
+  /** Default value if not provided */
+  readonly default?: SemanticValue;
+
+  /** Position hint for SVO languages (higher = earlier) */
+  readonly svoPosition?: number;
+
+  /** Position hint for SOV languages (higher = earlier) */
+  readonly sovPosition?: number;
+
+  /**
+   * Override the default role marker for this command.
+   * Maps language code to the marker to use (e.g., { en: 'from', ja: 'から' }).
+   * If not specified, uses the language profile's default roleMarker.
+   */
+  readonly markerOverride?: Record<string, string>;
+
+  /**
+   * Override the rendering marker separately from parsing.
+   * Used when the parsing grammar differs from rendered output.
+   * Maps language code to the rendering marker.
+   */
+  readonly renderOverride?: Record<string, string>;
+
+  /**
+   * When true, this role captures all remaining tokens until the next
+   * recognized marker keyword or end of input, joining their values
+   * with spaces into a single ExpressionValue.
+   *
+   * Only meaningful for the last role in a sequence or a role followed
+   * by a marked role. Default: false.
+   */
+  readonly greedy?: boolean;
+}
+
+/**
+ * Helper to create a command schema with sensible defaults.
+ * Provides defaults for description, category, and primaryRole.
+ */
+export function defineCommand(
+  schema: Partial<CommandSchema> & Pick<CommandSchema, 'action' | 'roles'>
+): CommandSchema {
+  return {
+    description: schema.description || `${schema.action} command`,
+    category: schema.category || 'general',
+    primaryRole: schema.primaryRole || schema.roles[0]?.role || 'patient',
+    ...schema,
+    action: schema.action,
+    roles: schema.roles,
+  } as CommandSchema;
+}
+
+/**
+ * Helper to create a role spec with sensible defaults.
+ * Provides default for description.
+ */
+export function defineRole(
+  role: Partial<RoleSpec> & Pick<RoleSpec, 'role' | 'required' | 'expectedTypes'>
+): RoleSpec {
+  return {
+    description: role.description || `${role.role} role`,
+    ...role,
+    role: role.role,
+    required: role.required,
+    expectedTypes: role.expectedTypes,
+  };
+}

package/src/schema/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Schema types for defining DSL commands
+ */
+
+export * from './command-schema';

package/src/test-setup.ts

@@ -0,0 +1,45 @@
+/**
+ * Global test setup for @lokascript/framework
+ * Runs before each test file to provide a clean testing environment
+ */
+
+import { beforeEach, afterEach, vi } from 'vitest';
+
+// Mock console methods to reduce test output noise
+const consoleMethods = ['log', 'error', 'warn', 'info', 'debug'] as const;
+
+beforeEach(() => {
+  // Reset all mocks before each test
+  vi.clearAllMocks();
+
+  // Mock console methods for cleaner test output
+  // Tests that specifically need console output can restore these
+  consoleMethods.forEach(method => {
+    if (method in console) {
+      vi.spyOn(console, method).mockImplementation(() => {});
+    }
+  });
+});
+
+afterEach(() => {
+  // Restore console methods after each test
+  consoleMethods.forEach(method => {
+    if (method in console) {
+      const spy = vi.mocked(console[method]);
+      if (spy && spy.mockRestore) {
+        spy.mockRestore();
+      }
+    }
+  });
+
+  // Clean up timers
+  vi.clearAllTimers();
+});
+
+/**
+ * Cleanup utility for manual cleanup in tests
+ */
+export function cleanupGlobalState(): void {
+  vi.clearAllMocks();
+  vi.clearAllTimers();
+}

package/src/testing/index.ts

@@ -0,0 +1,137 @@
+/**
+ * @lokascript/framework/testing — Test utilities for domain packages
+ *
+ * Provides assertion helpers and type guards for testing domain DSLs
+ * built on the framework. Import from '@lokascript/framework/testing'
+ * in test files only (requires vitest as a peer dependency).
+ *
+ * @example
+ * ```typescript
+ * import { expectSemanticNode, isLiteralValue } from '@lokascript/framework/testing';
+ *
+ * test('parses select command', () => {
+ *   const node = dsl.parse('select name from users', 'en');
+ *   expectSemanticNode(node, 'select', { columns: 'name', source: 'users' });
+ * });
+ * ```
+ */
+
+import { expect } from 'vitest';
+import type {
+  SemanticNode,
+  CommandSemanticNode,
+  SemanticValue,
+  LiteralValue,
+  SelectorValue,
+  ExpressionValue,
+  ReferenceValue,
+} from '../core/types';
+
+// =============================================================================
+// Assertion Helpers
+// =============================================================================
+
+/**
+ * Assert that a semantic node has the expected action and role values.
+ * Role values can be strings (matched against `value` or `raw`) or full SemanticValue objects.
+ */
+export function expectSemanticNode(
+  node: SemanticNode,
+  action: string,
+  roles: Record<string, string | SemanticValue>
+): void {
+  expect(node.kind).toBe('command');
+  expect(node.action).toBe(action);
+
+  const commandNode = node as CommandSemanticNode;
+
+  for (const [role, expectedValue] of Object.entries(roles)) {
+    const actualValue = commandNode.roles.get(role);
+    expect(actualValue, `Role '${role}' should be defined`).toBeDefined();
+
+    if (typeof expectedValue === 'string') {
+      if (actualValue && 'value' in actualValue) {
+        expect(actualValue.value).toBe(expectedValue);
+      } else if (actualValue && 'raw' in actualValue) {
+        expect(actualValue.raw).toBe(expectedValue);
+      }
+    } else {
+      expect(actualValue).toEqual(expectedValue);
+    }
+  }
+}
+
+/**
+ * Assert that a value is a literal semantic value with the expected value.
+ */
+export function expectLiteralValue(
+  value: SemanticValue | undefined,
+  expectedValue: string | number | boolean
+): void {
+  expect(value).toBeDefined();
+  expect(value).toHaveProperty('type', 'literal');
+  expect(value).toHaveProperty('value', expectedValue);
+}
+
+/**
+ * Assert that a value is a selector semantic value.
+ */
+export function expectSelectorValue(
+  value: SemanticValue | undefined,
+  expectedSelector: string,
+  expectedKind?: SelectorValue['selectorKind']
+): void {
+  expect(value).toBeDefined();
+  expect(value).toHaveProperty('type', 'selector');
+  expect(value).toHaveProperty('value', expectedSelector);
+  if (expectedKind) {
+    expect(value).toHaveProperty('selectorKind', expectedKind);
+  }
+}
+
+/**
+ * Assert that a value is an expression semantic value.
+ */
+export function expectExpressionValue(value: SemanticValue | undefined, expectedRaw: string): void {
+  expect(value).toBeDefined();
+  expect(value).toHaveProperty('type', 'expression');
+  expect(value).toHaveProperty('raw', expectedRaw);
+}
+
+/**
+ * Assert that a value is a reference semantic value.
+ */
+export function expectReferenceValue(value: SemanticValue | undefined, expectedRef: string): void {
+  expect(value).toBeDefined();
+  expect(value).toHaveProperty('type', 'reference');
+  expect(value).toHaveProperty('value', expectedRef);
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/** Type guard for LiteralValue */
+export function isLiteralValue(value: SemanticValue): value is LiteralValue {
+  return value.type === 'literal';
+}
+
+/** Type guard for SelectorValue */
+export function isSelectorValue(value: SemanticValue): value is SelectorValue {
+  return value.type === 'selector';
+}
+
+/** Type guard for ExpressionValue */
+export function isExpressionValue(value: SemanticValue): value is ExpressionValue {
+  return value.type === 'expression';
+}
+
+/** Type guard for ReferenceValue */
+export function isReferenceValue(value: SemanticValue): value is ReferenceValue {
+  return value.type === 'reference';
+}
+
+/** Type guard for CommandSemanticNode */
+export function isCommandNode(node: SemanticNode): node is CommandSemanticNode {
+  return node.kind === 'command';
+}