@lokascript/framework 2.3.0 → 2.4.0

package/src/ir/references.ts

@@ -1,33 +1,5 @@
 /**
- * Reference Validation
- *
- * Configurable validation for reference values (me, you, it, result, etc.).
- * Domain DSLs can provide custom reference sets.
+ * Reference Validation — re-exported from @lokascript/intent
  */
 
-/**
- * Default set of valid references.
- * Covers the common hyperscript references; domain DSLs can extend or replace.
- */
-export const DEFAULT_REFERENCES: ReadonlySet<string> = new Set([
-  'me',
-  'you',
-  'it',
-  'result',
-  'event',
-  'target',
-  'body',
-]);
-
-/**
- * Check if a value is a valid reference name.
- *
- * @param value - The string to check
- * @param referenceSet - Custom reference set (defaults to DEFAULT_REFERENCES)
- */
-export function isValidReference(
-  value: string,
-  referenceSet: ReadonlySet<string> = DEFAULT_REFERENCES
-): boolean {
-  return referenceSet.has(value);
-}
+export { DEFAULT_REFERENCES, isValidReference } from '@lokascript/intent';

package/src/ir/types.ts

@@ -1,191 +1,19 @@
 /**
- * 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>;
-  /**
-   * When true, validation errors are collected as diagnostics on the
-   * returned node instead of throwing. Fatal parse errors (missing brackets,
-   * empty input) still throw. Default: false.
-   */
-  collectDiagnostics?: boolean;
-}
-
-// =============================================================================
-// 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 diagnostic in protocol wire format (v1.2, extended v1.2.1). */
-export interface ProtocolDiagnosticJSON {
-  level: 'error' | 'warning' | 'info';
-  role?: string;
-  message: string;
-  code?: string;
-  /** v1.2.1: source parser/stage that produced this diagnostic. */
-  source?: string;
-  /** v1.2.1: actionable fix suggestions. */
-  suggestions?: 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[];
-}
+ * IR Types — re-exported from @lokascript/intent
+ */
+
+export type {
+  SemanticJSON,
+  SemanticJSONValue,
+  SchemaLookup,
+  ParseExplicitOptions,
+  IRDiagnostic,
+  ProtocolNodeKind,
+  ProtocolChainType,
+  ProtocolValueJSON,
+  ProtocolNodeJSON,
+  ProtocolDiagnosticJSON,
+  AnnotationJSON,
+  MatchArmJSON,
+  LSEEnvelopeJSON,
+} from '@lokascript/intent';

package/src/schema/command-schema.ts

@@ -1,137 +1,6 @@
 /**
- * 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.
+ * Command Schema Types — re-exported from @lokascript/intent
  */
 
-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>;
-
-  /**
-   * Override the marker position for this role in the generated pattern.
-   * 'before' = marker precedes the role value (preposition: "set X").
-   * 'after'  = marker follows the role value (postposition: "X から").
-   * If not set, falls back to the language profile's roleMarkers position,
-   * then to the word-order default (SOV='after', else='before').
-   */
-  readonly markerPosition?: 'before' | 'after';
-
-  /**
-   * 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;
-
-  /**
-   * Restricts which selector subtypes are valid for this role (v1.2).
-   * Only meaningful when expectedTypes includes 'selector'.
-   * If omitted, all selector kinds are accepted.
-   *
-   * Example: `selectorKinds: ['class', 'attribute']` means only `.class`
-   * and `[attr]` selectors are valid, not `#id` or `*wildcard`.
-   */
-  readonly selectorKinds?: ReadonlyArray<'id' | 'class' | 'attribute' | 'element' | 'complex'>;
-}
-
-/**
- * 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,
-  };
-}
+export type { CommandSchema, RoleSpec } from '@lokascript/intent';
+export { defineCommand, defineRole, getRoleSpec } from '@lokascript/intent';