@lokascript/framework 2.0.0

package/dist/core/types.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Generic Semantic Types for Multilingual DSLs
+ *
+ * This module defines the canonical semantic representation that all languages
+ * parse to and render from. The semantic layer is language-neutral - it captures
+ * the MEANING of DSL commands independent of surface syntax.
+ *
+ * These types are domain-agnostic - they work for any DSL (SQL, animations, etc.)
+ */
+/**
+ * Action type represents the command/operation in a DSL.
+ * This is generic - each DSL defines its own set of actions.
+ *
+ * Examples:
+ * - Hyperscript: 'toggle', 'add', 'remove', 'fetch'
+ * - SQL: 'select', 'insert', 'update', 'delete'
+ * - Animation: 'animate', 'fade', 'slide', 'rotate'
+ */
+export type ActionType = string;
+/**
+ * Semantic role represents the grammatical function of a part of a command.
+ * This is generic - each DSL can define its own roles, though common ones include:
+ *
+ * Common roles across DSLs:
+ * - action: The verb/command
+ * - patient: What is being acted upon
+ * - destination: Where something goes
+ * - source: Where something comes from
+ * - condition: Boolean expressions
+ * - quantity: Numeric amounts
+ * - duration: Time spans
+ *
+ * Examples:
+ * - Hyperscript: 'patient', 'destination', 'source', 'event', 'style'
+ * - SQL: 'columns', 'table', 'condition', 'orderBy', 'limit'
+ * - Animation: 'target', 'duration', 'easing', 'delay'
+ */
+export type SemanticRole = string;
+/**
+ * A semantic value represents a typed piece of data in a semantic node.
+ * Values are language-neutral - they capture what something IS, not how it's written.
+ */
+export type SemanticValue = LiteralValue | SelectorValue | ReferenceValue | PropertyPathValue | ExpressionValue;
+/**
+ * Expected value types for role tokens.
+ * Shared between RoleSpec (command-schemas) and RolePatternToken.
+ */
+export type ExpectedType = SemanticValue['type'];
+export interface LiteralValue {
+    readonly type: 'literal';
+    readonly value: string | number | boolean;
+    readonly dataType?: 'string' | 'number' | 'boolean' | 'duration';
+}
+export interface SelectorValue {
+    readonly type: 'selector';
+    readonly value: string;
+    readonly selectorKind?: 'id' | 'class' | 'attribute' | 'element' | 'complex' | 'identifier';
+}
+export interface ReferenceValue {
+    readonly type: 'reference';
+    readonly value: string;
+}
+export interface PropertyPathValue {
+    readonly type: 'property-path';
+    readonly object: SemanticValue;
+    readonly property: string;
+}
+export interface ExpressionValue {
+    readonly type: 'expression';
+    /** Raw expression string for complex expressions that need further parsing */
+    readonly raw: string;
+}
+/**
+ * Base interface for all semantic nodes.
+ * Semantic nodes capture the MEANING of DSL constructs.
+ */
+export interface SemanticNode {
+    readonly kind: 'command' | 'event-handler' | 'conditional' | 'compound' | 'loop';
+    readonly action: ActionType;
+    readonly roles: ReadonlyMap<SemanticRole, SemanticValue>;
+    readonly metadata?: SemanticMetadata;
+}
+/**
+ * Metadata about the source of a semantic node.
+ * Useful for debugging, error messages, and round-trip conversion.
+ */
+export interface SemanticMetadata {
+    readonly sourceLanguage?: string;
+    readonly sourceText?: string;
+    readonly sourcePosition?: SourcePosition;
+    readonly patternId?: string;
+    /**
+     * Confidence score for the parse (0-1).
+     * Higher values indicate more certain matches.
+     * - 1.0: Exact match with all roles captured
+     * - 0.8-0.99: High confidence with minor uncertainty
+     * - 0.6-0.8: Medium confidence (normalization, defaults applied)
+     * - <0.6: Low confidence (may need fallback)
+     */
+    readonly confidence?: number;
+}
+export interface SourcePosition {
+    readonly start: number;
+    readonly end: number;
+    readonly line?: number;
+    readonly column?: number;
+}
+/**
+ * A command semantic node - represents a single DSL command.
+ */
+export interface CommandSemanticNode extends SemanticNode {
+    readonly kind: 'command';
+}
+/**
+ * An event handler semantic node - represents trigger-based commands.
+ * E.g., "on click [commands]" in hyperscript, or "when condition [commands]" in other DSLs.
+ */
+export interface EventHandlerSemanticNode extends SemanticNode {
+    readonly kind: 'event-handler';
+    readonly body: SemanticNode[];
+    readonly eventModifiers?: EventModifiers;
+    readonly additionalEvents?: readonly SemanticValue[];
+    readonly parameterNames?: readonly string[];
+}
+export interface EventModifiers {
+    readonly once?: boolean;
+    readonly debounce?: number;
+    readonly throttle?: number;
+    readonly queue?: 'first' | 'last' | 'all' | 'none';
+    readonly from?: SemanticValue;
+}
+/**
+ * A conditional semantic node - represents "if [condition] then [body] else [body]".
+ */
+export interface ConditionalSemanticNode extends SemanticNode {
+    readonly kind: 'conditional';
+    readonly thenBranch: SemanticNode[];
+    readonly elseBranch?: SemanticNode[];
+}
+/**
+ * A compound semantic node - represents multiple chained statements.
+ */
+export interface CompoundSemanticNode extends SemanticNode {
+    readonly kind: 'compound';
+    readonly statements: SemanticNode[];
+    readonly chainType: 'then' | 'and' | 'async' | 'sequential';
+}
+/**
+ * Loop variant discriminant for different loop types.
+ */
+export type LoopVariant = 'forever' | 'times' | 'for' | 'while' | 'until';
+/**
+ * A loop semantic node - represents repeat/for/while loops.
+ */
+export interface LoopSemanticNode extends SemanticNode {
+    readonly kind: 'loop';
+    readonly loopVariant: LoopVariant;
+    readonly body: SemanticNode[];
+    readonly loopVariable?: string;
+    readonly indexVariable?: string;
+}
+/**
+ * Token kind - categorizes what type of token this is.
+ */
+export type TokenKind = 'keyword' | 'selector' | 'literal' | 'particle' | 'conjunction' | 'event-modifier' | 'identifier' | 'operator' | 'punctuation' | 'url';
+/**
+ * A language token - the result of tokenization.
+ */
+export interface LanguageToken {
+    readonly value: string;
+    readonly kind: TokenKind;
+    readonly position: SourcePosition;
+    /** Normalized form from explicit keyword map */
+    readonly normalized?: string;
+    /** Morphologically normalized stem */
+    readonly stem?: string;
+    /** Confidence in the morphological stem (0.0-1.0) */
+    readonly stemConfidence?: number;
+    /** Additional metadata for specific token types */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Token stream - provides sequential access to tokens with backtracking.
+ */
+export interface TokenStream {
+    readonly tokens: readonly LanguageToken[];
+    readonly language: string;
+    /** Look at token at current position + offset without consuming */
+    peek(offset?: number): LanguageToken | null;
+    /** Consume and return current token, advance position */
+    advance(): LanguageToken;
+    /** Check if we've consumed all tokens */
+    isAtEnd(): boolean;
+    /** Save current position for backtracking */
+    mark(): StreamMark;
+    /** Restore to a saved position */
+    reset(mark: StreamMark): void;
+    /** Get current position */
+    position(): number;
+}
+/**
+ * Stream mark for backtracking during parsing.
+ */
+export interface StreamMark {
+    readonly position: number;
+}
+/**
+ * Language tokenizer interface - converts text to tokens.
+ */
+export interface LanguageTokenizer {
+    readonly language: string;
+    readonly direction: 'ltr' | 'rtl';
+    /** Convert input string to token stream */
+    tokenize(input: string): TokenStream;
+    /** Classify a single token */
+    classifyToken(token: string): TokenKind;
+}
+/**
+ * A language pattern defines how a semantic structure appears in a specific language.
+ */
+export interface LanguagePattern {
+    /** Unique identifier for this pattern */
+    readonly id: string;
+    /** ISO 639-1 language code */
+    readonly language: string;
+    /** Which command this pattern matches */
+    readonly command: ActionType;
+    /** Priority for disambiguation (higher = checked first) */
+    readonly priority: number;
+    /** The pattern template with role placeholders */
+    readonly template: PatternTemplate;
+    /** Rules for extracting semantic roles from matched tokens */
+    readonly extraction: ExtractionRules;
+    /** Optional constraints on when this pattern applies */
+    readonly constraints?: PatternConstraints;
+}
+/**
+ * Pattern template - defines expected token sequence.
+ */
+export interface PatternTemplate {
+    /** Human-readable template string */
+    readonly format: string;
+    /** Parsed token sequence for matching */
+    readonly tokens: PatternToken[];
+}
+/**
+ * Pattern token - literal, role placeholder, or group.
+ */
+export type PatternToken = LiteralPatternToken | RolePatternToken | GroupPatternToken;
+export interface LiteralPatternToken {
+    readonly type: 'literal';
+    readonly value: string;
+    /** Alternative spellings/forms that also match */
+    readonly alternatives?: string[];
+}
+export interface RolePatternToken {
+    readonly type: 'role';
+    readonly role: SemanticRole;
+    readonly optional?: boolean;
+    /** Expected value types (for validation) */
+    readonly expectedTypes?: Array<ExpectedType>;
+    /** When true, captures all remaining tokens until next marker or end */
+    readonly greedy?: boolean;
+}
+export interface GroupPatternToken {
+    readonly type: 'group';
+    readonly tokens: PatternToken[];
+    readonly optional?: boolean;
+}
+/**
+ * Rules for extracting semantic values from matched tokens.
+ */
+export interface ExtractionRules {
+    readonly [role: string]: ExtractionRule;
+}
+export interface ExtractionRule {
+    /** Position-based extraction (0-indexed from pattern start) */
+    readonly position?: number;
+    /** Marker-based extraction (find value after this marker) */
+    readonly marker?: string;
+    /** Alternative markers that also work */
+    readonly markerAlternatives?: string[];
+    /** Transform the extracted value */
+    readonly transform?: (raw: string) => SemanticValue;
+    /** Default value if not found (for optional roles) */
+    readonly default?: SemanticValue;
+    /** Static value extraction */
+    readonly value?: string;
+    /** Extract value from a pattern role by name */
+    readonly fromRole?: string;
+}
+/**
+ * Additional constraints on pattern applicability.
+ */
+export interface PatternConstraints {
+    /** Required roles that must be present */
+    readonly requiredRoles?: SemanticRole[];
+    /** Roles that must NOT be present */
+    readonly forbiddenRoles?: SemanticRole[];
+    /** Valid selector types for the patient role */
+    readonly validPatientTypes?: Array<SelectorValue['selectorKind']>;
+    /** Pattern IDs this conflicts with */
+    readonly conflictsWith?: string[];
+}
+/**
+ * Result of matching a pattern against tokens.
+ */
+export interface PatternMatchResult {
+    readonly pattern: LanguagePattern;
+    readonly captured: ReadonlyMap<SemanticRole, SemanticValue>;
+    readonly consumedTokens: number;
+    readonly confidence: number;
+}
+/**
+ * Error when pattern matching fails.
+ */
+export interface PatternMatchError {
+    readonly message: string;
+    readonly position: SourcePosition;
+    readonly expectedPatterns?: string[];
+    readonly partialMatch?: Partial<PatternMatchResult>;
+}
+/**
+ * Create a literal value
+ */
+export declare function createLiteral(value: string | number | boolean, dataType?: 'string' | 'number' | 'boolean' | 'duration'): LiteralValue;
+/**
+ * Create a selector value
+ */
+export declare function createSelector(value: string, selectorKind?: SelectorValue['selectorKind']): SelectorValue;
+/**
+ * Create a reference value
+ */
+export declare function createReference(value: string): ReferenceValue;
+/**
+ * Create a property path value
+ */
+export declare function createPropertyPath(object: SemanticValue, property: string): PropertyPathValue;
+/**
+ * Create an expression value
+ */
+export declare function createExpression(raw: string): ExpressionValue;
+/**
+ * Create a command semantic node
+ */
+export declare function createCommandNode(action: ActionType, roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>, metadata?: SemanticMetadata): CommandSemanticNode;
+/**
+ * Create an event handler semantic node
+ */
+export declare function createEventHandlerNode(action: ActionType, roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>, body: SemanticNode[], metadata?: SemanticMetadata, eventModifiers?: EventModifiers): EventHandlerSemanticNode;
+/**
+ * Create a conditional semantic node
+ */
+export declare function createConditionalNode(action: ActionType, roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>, thenBranch: SemanticNode[], elseBranch?: SemanticNode[], metadata?: SemanticMetadata): ConditionalSemanticNode;
+/**
+ * Create a compound semantic node
+ */
+export declare function createCompoundNode(statements: SemanticNode[], chainType?: CompoundSemanticNode['chainType'], metadata?: SemanticMetadata): CompoundSemanticNode;
+/**
+ * Extract a string value from a SemanticValue.
+ *
+ * Handles all value types in the SemanticValue union:
+ * - ExpressionValue: returns `raw`
+ * - LiteralValue/SelectorValue/ReferenceValue: returns `value` as string
+ * - PropertyPathValue: returns `object.property` path
+ *
+ * This is the standard way to get a display string from any semantic value,
+ * eliminating the need for `as any` casts in domain code generators.
+ */
+export declare function extractValue(value: SemanticValue): string;
+/**
+ * Extract a string value from a named role on a SemanticNode.
+ *
+ * Convenience wrapper: looks up the role, returns empty string if missing.
+ * Eliminates the common `const x = node.roles.get('role'); const val = x ? extractValue(x as any) : '';` pattern.
+ */
+export declare function extractRoleValue(node: SemanticNode, role: string): string;
+/**
+ * Create a loop semantic node
+ */
+export declare function createLoopNode(action: ActionType, roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>, loopVariant: LoopVariant, body: SemanticNode[], loopVariable?: string, indexVariable?: string, metadata?: SemanticMetadata): LoopSemanticNode;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1,108 @@
+// src/core/types.ts
+function createLiteral(value, dataType) {
+  return dataType ? { type: "literal", value, dataType } : { type: "literal", value };
+}
+function createSelector(value, selectorKind) {
+  return selectorKind ? { type: "selector", value, selectorKind } : { type: "selector", value };
+}
+function createReference(value) {
+  return { type: "reference", value };
+}
+function createPropertyPath(object, property) {
+  return { type: "property-path", object, property };
+}
+function createExpression(raw) {
+  return { type: "expression", raw };
+}
+function createCommandNode(action, roles, metadata) {
+  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));
+  const node = {
+    kind: "command",
+    action,
+    roles: rolesMap
+  };
+  if (metadata) {
+    return { ...node, metadata };
+  }
+  return node;
+}
+function createEventHandlerNode(action, roles, body, metadata, eventModifiers) {
+  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));
+  const base = {
+    kind: "event-handler",
+    action,
+    roles: rolesMap,
+    body
+  };
+  return {
+    ...base,
+    ...eventModifiers && { eventModifiers },
+    ...metadata && { metadata }
+  };
+}
+function createConditionalNode(action, roles, thenBranch, elseBranch, metadata) {
+  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));
+  const base = {
+    kind: "conditional",
+    action,
+    roles: rolesMap,
+    thenBranch
+  };
+  return {
+    ...base,
+    ...elseBranch && { elseBranch },
+    ...metadata && { metadata }
+  };
+}
+function createCompoundNode(statements, chainType = "sequential", metadata) {
+  const base = {
+    kind: "compound",
+    action: "compound",
+    roles: /* @__PURE__ */ new Map(),
+    statements,
+    chainType
+  };
+  return metadata ? { ...base, metadata } : base;
+}
+function extractValue(value) {
+  if ("raw" in value && value.raw !== void 0) return String(value.raw);
+  if ("value" in value && value.value !== void 0) return String(value.value);
+  if (value.type === "property-path") return `${extractValue(value.object)}.${value.property}`;
+  return "";
+}
+function extractRoleValue(node, role) {
+  const value = node.roles.get(role);
+  if (!value) return "";
+  return extractValue(value);
+}
+function createLoopNode(action, roles, loopVariant, body, loopVariable, indexVariable, metadata) {
+  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));
+  const base = {
+    kind: "loop",
+    action,
+    roles: rolesMap,
+    loopVariant,
+    body
+  };
+  return {
+    ...base,
+    ...loopVariable && { loopVariable },
+    ...indexVariable && { indexVariable },
+    ...metadata && { metadata }
+  };
+}
+export {
+  createCommandNode,
+  createCompoundNode,
+  createConditionalNode,
+  createEventHandlerNode,
+  createExpression,
+  createLiteral,
+  createLoopNode,
+  createPropertyPath,
+  createReference,
+  createSelector,
+  extractRoleValue,
+  extractValue
+};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/types.ts"],"sourcesContent":["/**\n * Generic Semantic Types for Multilingual DSLs\n *\n * This module defines the canonical semantic representation that all languages\n * parse to and render from. The semantic layer is language-neutral - it captures\n * the MEANING of DSL commands independent of surface syntax.\n *\n * These types are domain-agnostic - they work for any DSL (SQL, animations, etc.)\n */\n\n// =============================================================================\n// Action Types (Generic)\n// =============================================================================\n\n/**\n * Action type represents the command/operation in a DSL.\n * This is generic - each DSL defines its own set of actions.\n *\n * Examples:\n * - Hyperscript: 'toggle', 'add', 'remove', 'fetch'\n * - SQL: 'select', 'insert', 'update', 'delete'\n * - Animation: 'animate', 'fade', 'slide', 'rotate'\n */\nexport type ActionType = string;\n\n/**\n * Semantic role represents the grammatical function of a part of a command.\n * This is generic - each DSL can define its own roles, though common ones include:\n *\n * Common roles across DSLs:\n * - action: The verb/command\n * - patient: What is being acted upon\n * - destination: Where something goes\n * - source: Where something comes from\n * - condition: Boolean expressions\n * - quantity: Numeric amounts\n * - duration: Time spans\n *\n * Examples:\n * - Hyperscript: 'patient', 'destination', 'source', 'event', 'style'\n * - SQL: 'columns', 'table', 'condition', 'orderBy', 'limit'\n * - Animation: 'target', 'duration', 'easing', 'delay'\n */\nexport type SemanticRole = string;\n\n// =============================================================================\n// Semantic Values\n// =============================================================================\n\n/**\n * A semantic value represents a typed piece of data in a semantic node.\n * Values are language-neutral - they capture what something IS, not how it's written.\n */\nexport type SemanticValue =\n  | LiteralValue\n  | SelectorValue\n  | ReferenceValue\n  | PropertyPathValue\n  | ExpressionValue;\n\n/**\n * Expected value types for role tokens.\n * Shared between RoleSpec (command-schemas) and RolePatternToken.\n */\nexport type ExpectedType = SemanticValue['type'];\n\nexport interface LiteralValue {\n  readonly type: 'literal';\n  readonly value: string | number | boolean;\n  readonly dataType?: 'string' | 'number' | 'boolean' | 'duration';\n}\n\nexport interface SelectorValue {\n  readonly type: 'selector';\n  readonly value: string; // The selector: #id, .class, [attr], table-name, etc.\n  readonly selectorKind?: 'id' | 'class' | 'attribute' | 'element' | 'complex' | 'identifier';\n}\n\nexport interface ReferenceValue {\n  readonly type: 'reference';\n  readonly value: string; // Generic reference name (DSL-specific)\n}\n\nexport interface PropertyPathValue {\n  readonly type: 'property-path';\n  readonly object: SemanticValue;\n  readonly property: string;\n}\n\nexport interface ExpressionValue {\n  readonly type: 'expression';\n  /** Raw expression string for complex expressions that need further parsing */\n  readonly raw: string;\n}\n\n// =============================================================================\n// Semantic Nodes\n// =============================================================================\n\n/**\n * Base interface for all semantic nodes.\n * Semantic nodes capture the MEANING of DSL constructs.\n */\nexport interface SemanticNode {\n  readonly kind: 'command' | 'event-handler' | 'conditional' | 'compound' | 'loop';\n  readonly action: ActionType;\n  readonly roles: ReadonlyMap<SemanticRole, SemanticValue>;\n  readonly metadata?: SemanticMetadata;\n}\n\n/**\n * Metadata about the source of a semantic node.\n * Useful for debugging, error messages, and round-trip conversion.\n */\nexport interface SemanticMetadata {\n  readonly sourceLanguage?: string;\n  readonly sourceText?: string;\n  readonly sourcePosition?: SourcePosition;\n  readonly patternId?: string;\n  /**\n   * Confidence score for the parse (0-1).\n   * Higher values indicate more certain matches.\n   * - 1.0: Exact match with all roles captured\n   * - 0.8-0.99: High confidence with minor uncertainty\n   * - 0.6-0.8: Medium confidence (normalization, defaults applied)\n   * - <0.6: Low confidence (may need fallback)\n   */\n  readonly confidence?: number;\n}\n\nexport interface SourcePosition {\n  readonly start: number;\n  readonly end: number;\n  readonly line?: number;\n  readonly column?: number;\n}\n\n/**\n * A command semantic node - represents a single DSL command.\n */\nexport interface CommandSemanticNode extends SemanticNode {\n  readonly kind: 'command';\n}\n\n/**\n * An event handler semantic node - represents trigger-based commands.\n * E.g., \"on click [commands]\" in hyperscript, or \"when condition [commands]\" in other DSLs.\n */\nexport interface EventHandlerSemanticNode extends SemanticNode {\n  readonly kind: 'event-handler';\n  readonly body: SemanticNode[];\n  readonly eventModifiers?: EventModifiers;\n  readonly additionalEvents?: readonly SemanticValue[];\n  readonly parameterNames?: readonly string[];\n}\n\nexport interface EventModifiers {\n  readonly once?: boolean;\n  readonly debounce?: number;\n  readonly throttle?: number;\n  readonly queue?: 'first' | 'last' | 'all' | 'none';\n  readonly from?: SemanticValue;\n}\n\n/**\n * A conditional semantic node - represents \"if [condition] then [body] else [body]\".\n */\nexport interface ConditionalSemanticNode extends SemanticNode {\n  readonly kind: 'conditional';\n  readonly thenBranch: SemanticNode[];\n  readonly elseBranch?: SemanticNode[];\n}\n\n/**\n * A compound semantic node - represents multiple chained statements.\n */\nexport interface CompoundSemanticNode extends SemanticNode {\n  readonly kind: 'compound';\n  readonly statements: SemanticNode[];\n  readonly chainType: 'then' | 'and' | 'async' | 'sequential';\n}\n\n/**\n * Loop variant discriminant for different loop types.\n */\nexport type LoopVariant = 'forever' | 'times' | 'for' | 'while' | 'until';\n\n/**\n * A loop semantic node - represents repeat/for/while loops.\n */\nexport interface LoopSemanticNode extends SemanticNode {\n  readonly kind: 'loop';\n  readonly loopVariant: LoopVariant;\n  readonly body: SemanticNode[];\n  readonly loopVariable?: string;\n  readonly indexVariable?: string;\n}\n\n// =============================================================================\n// Tokenization Types\n// =============================================================================\n\n/**\n * Token kind - categorizes what type of token this is.\n */\nexport type TokenKind =\n  | 'keyword' // Command or modifier keyword\n  | 'selector' // CSS selector or identifier (#id, .class, table-name)\n  | 'literal' // String or number literal\n  | 'particle' // Grammatical particle (を, に, من)\n  | 'conjunction' // Grammatical conjunction\n  | 'event-modifier' // Event modifier (.once, .debounce(300))\n  | 'identifier' // Generic identifier\n  | 'operator' // Operators (., +, -, etc.)\n  | 'punctuation' // Punctuation (parentheses, etc.)\n  | 'url'; // URL or path\n\n/**\n * A language token - the result of tokenization.\n */\nexport interface LanguageToken {\n  readonly value: string;\n  readonly kind: TokenKind;\n  readonly position: SourcePosition;\n  /** Normalized form from explicit keyword map */\n  readonly normalized?: string;\n  /** Morphologically normalized stem */\n  readonly stem?: string;\n  /** Confidence in the morphological stem (0.0-1.0) */\n  readonly stemConfidence?: number;\n  /** Additional metadata for specific token types */\n  readonly metadata?: Record<string, unknown>;\n}\n\n/**\n * Token stream - provides sequential access to tokens with backtracking.\n */\nexport interface TokenStream {\n  readonly tokens: readonly LanguageToken[];\n  readonly language: string;\n\n  /** Look at token at current position + offset without consuming */\n  peek(offset?: number): LanguageToken | null;\n\n  /** Consume and return current token, advance position */\n  advance(): LanguageToken;\n\n  /** Check if we've consumed all tokens */\n  isAtEnd(): boolean;\n\n  /** Save current position for backtracking */\n  mark(): StreamMark;\n\n  /** Restore to a saved position */\n  reset(mark: StreamMark): void;\n\n  /** Get current position */\n  position(): number;\n}\n\n/**\n * Stream mark for backtracking during parsing.\n */\nexport interface StreamMark {\n  readonly position: number;\n}\n\n/**\n * Language tokenizer interface - converts text to tokens.\n */\nexport interface LanguageTokenizer {\n  readonly language: string;\n  readonly direction: 'ltr' | 'rtl';\n\n  /** Convert input string to token stream */\n  tokenize(input: string): TokenStream;\n\n  /** Classify a single token */\n  classifyToken(token: string): TokenKind;\n}\n\n// =============================================================================\n// Pattern Matching Types\n// =============================================================================\n\n/**\n * A language pattern defines how a semantic structure appears in a specific language.\n */\nexport interface LanguagePattern {\n  /** Unique identifier for this pattern */\n  readonly id: string;\n  /** ISO 639-1 language code */\n  readonly language: string;\n  /** Which command this pattern matches */\n  readonly command: ActionType;\n  /** Priority for disambiguation (higher = checked first) */\n  readonly priority: number;\n  /** The pattern template with role placeholders */\n  readonly template: PatternTemplate;\n  /** Rules for extracting semantic roles from matched tokens */\n  readonly extraction: ExtractionRules;\n  /** Optional constraints on when this pattern applies */\n  readonly constraints?: PatternConstraints;\n}\n\n/**\n * Pattern template - defines expected token sequence.\n */\nexport interface PatternTemplate {\n  /** Human-readable template string */\n  readonly format: string;\n  /** Parsed token sequence for matching */\n  readonly tokens: PatternToken[];\n}\n\n/**\n * Pattern token - literal, role placeholder, or group.\n */\nexport type PatternToken = LiteralPatternToken | RolePatternToken | GroupPatternToken;\n\nexport interface LiteralPatternToken {\n  readonly type: 'literal';\n  readonly value: string;\n  /** Alternative spellings/forms that also match */\n  readonly alternatives?: string[];\n}\n\nexport interface RolePatternToken {\n  readonly type: 'role';\n  readonly role: SemanticRole;\n  readonly optional?: boolean;\n  /** Expected value types (for validation) */\n  readonly expectedTypes?: Array<ExpectedType>;\n  /** When true, captures all remaining tokens until next marker or end */\n  readonly greedy?: boolean;\n}\n\nexport interface GroupPatternToken {\n  readonly type: 'group';\n  readonly tokens: PatternToken[];\n  readonly optional?: boolean;\n}\n\n/**\n * Rules for extracting semantic values from matched tokens.\n */\nexport interface ExtractionRules {\n  readonly [role: string]: ExtractionRule;\n}\n\nexport interface ExtractionRule {\n  /** Position-based extraction (0-indexed from pattern start) */\n  readonly position?: number;\n  /** Marker-based extraction (find value after this marker) */\n  readonly marker?: string;\n  /** Alternative markers that also work */\n  readonly markerAlternatives?: string[];\n  /** Transform the extracted value */\n  readonly transform?: (raw: string) => SemanticValue;\n  /** Default value if not found (for optional roles) */\n  readonly default?: SemanticValue;\n  /** Static value extraction */\n  readonly value?: string;\n  /** Extract value from a pattern role by name */\n  readonly fromRole?: string;\n}\n\n/**\n * Additional constraints on pattern applicability.\n */\nexport interface PatternConstraints {\n  /** Required roles that must be present */\n  readonly requiredRoles?: SemanticRole[];\n  /** Roles that must NOT be present */\n  readonly forbiddenRoles?: SemanticRole[];\n  /** Valid selector types for the patient role */\n  readonly validPatientTypes?: Array<SelectorValue['selectorKind']>;\n  /** Pattern IDs this conflicts with */\n  readonly conflictsWith?: string[];\n}\n\n/**\n * Result of matching a pattern against tokens.\n */\nexport interface PatternMatchResult {\n  readonly pattern: LanguagePattern;\n  readonly captured: ReadonlyMap<SemanticRole, SemanticValue>;\n  readonly consumedTokens: number;\n  readonly confidence: number; // 0-1, how well the pattern matched\n}\n\n/**\n * Error when pattern matching fails.\n */\nexport interface PatternMatchError {\n  readonly message: string;\n  readonly position: SourcePosition;\n  readonly expectedPatterns?: string[];\n  readonly partialMatch?: Partial<PatternMatchResult>;\n}\n\n// =============================================================================\n// Helper Functions\n// =============================================================================\n\n/**\n * Create a literal value\n */\nexport function createLiteral(\n  value: string | number | boolean,\n  dataType?: 'string' | 'number' | 'boolean' | 'duration'\n): LiteralValue {\n  return dataType ? { type: 'literal', value, dataType } : { type: 'literal', value };\n}\n\n/**\n * Create a selector value\n */\nexport function createSelector(\n  value: string,\n  selectorKind?: SelectorValue['selectorKind']\n): SelectorValue {\n  return selectorKind ? { type: 'selector', value, selectorKind } : { type: 'selector', value };\n}\n\n/**\n * Create a reference value\n */\nexport function createReference(value: string): ReferenceValue {\n  return { type: 'reference', value };\n}\n\n/**\n * Create a property path value\n */\nexport function createPropertyPath(object: SemanticValue, property: string): PropertyPathValue {\n  return { type: 'property-path', object, property };\n}\n\n/**\n * Create an expression value\n */\nexport function createExpression(raw: string): ExpressionValue {\n  return { type: 'expression', raw };\n}\n\n/**\n * Create a command semantic node\n */\nexport function createCommandNode(\n  action: ActionType,\n  roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>,\n  metadata?: SemanticMetadata\n): CommandSemanticNode {\n  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));\n  const node: CommandSemanticNode = {\n    kind: 'command',\n    action,\n    roles: rolesMap,\n  };\n  if (metadata) {\n    return { ...node, metadata };\n  }\n  return node;\n}\n\n/**\n * Create an event handler semantic node\n */\nexport function createEventHandlerNode(\n  action: ActionType,\n  roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>,\n  body: SemanticNode[],\n  metadata?: SemanticMetadata,\n  eventModifiers?: EventModifiers\n): EventHandlerSemanticNode {\n  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));\n  const base = {\n    kind: 'event-handler' as const,\n    action,\n    roles: rolesMap,\n    body,\n  };\n  return {\n    ...base,\n    ...(eventModifiers && { eventModifiers }),\n    ...(metadata && { metadata }),\n  };\n}\n\n/**\n * Create a conditional semantic node\n */\nexport function createConditionalNode(\n  action: ActionType,\n  roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>,\n  thenBranch: SemanticNode[],\n  elseBranch?: SemanticNode[],\n  metadata?: SemanticMetadata\n): ConditionalSemanticNode {\n  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));\n  const base = {\n    kind: 'conditional' as const,\n    action,\n    roles: rolesMap,\n    thenBranch,\n  };\n  return {\n    ...base,\n    ...(elseBranch && { elseBranch }),\n    ...(metadata && { metadata }),\n  };\n}\n\n/**\n * Create a compound semantic node\n */\nexport function createCompoundNode(\n  statements: SemanticNode[],\n  chainType: CompoundSemanticNode['chainType'] = 'sequential',\n  metadata?: SemanticMetadata\n): CompoundSemanticNode {\n  const base = {\n    kind: 'compound' as const,\n    action: 'compound' as const,\n    roles: new Map(),\n    statements,\n    chainType,\n  };\n  return metadata ? { ...base, metadata } : base;\n}\n\n/**\n * Extract a string value from a SemanticValue.\n *\n * Handles all value types in the SemanticValue union:\n * - ExpressionValue: returns `raw`\n * - LiteralValue/SelectorValue/ReferenceValue: returns `value` as string\n * - PropertyPathValue: returns `object.property` path\n *\n * This is the standard way to get a display string from any semantic value,\n * eliminating the need for `as any` casts in domain code generators.\n */\nexport function extractValue(value: SemanticValue): string {\n  if ('raw' in value && value.raw !== undefined) return String(value.raw);\n  if ('value' in value && value.value !== undefined) return String(value.value);\n  if (value.type === 'property-path') return `${extractValue(value.object)}.${value.property}`;\n  return '';\n}\n\n/**\n * Extract a string value from a named role on a SemanticNode.\n *\n * Convenience wrapper: looks up the role, returns empty string if missing.\n * Eliminates the common `const x = node.roles.get('role'); const val = x ? extractValue(x as any) : '';` pattern.\n */\nexport function extractRoleValue(node: SemanticNode, role: string): string {\n  const value = node.roles.get(role);\n  if (!value) return '';\n  return extractValue(value);\n}\n\n/**\n * Create a loop semantic node\n */\nexport function createLoopNode(\n  action: ActionType,\n  roles: Record<SemanticRole, SemanticValue> | Map<SemanticRole, SemanticValue>,\n  loopVariant: LoopVariant,\n  body: SemanticNode[],\n  loopVariable?: string,\n  indexVariable?: string,\n  metadata?: SemanticMetadata\n): LoopSemanticNode {\n  const rolesMap = roles instanceof Map ? roles : new Map(Object.entries(roles));\n  const base = {\n    kind: 'loop' as const,\n    action,\n    roles: rolesMap,\n    loopVariant,\n    body,\n  };\n  return {\n    ...base,\n    ...(loopVariable && { loopVariable }),\n    ...(indexVariable && { indexVariable }),\n    ...(metadata && { metadata }),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/generation/diagnostics.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Structured Error Diagnostics
+ *
+ * Framework-level diagnostic types for reporting errors, warnings, and hints
+ * during parsing, validation, and compilation. These provide richer feedback
+ * than simple error strings, enabling:
+ *
+ * - Severity levels (error, warning, info)
+ * - Machine-readable error codes
+ * - Source location tracking
+ * - Actionable suggestions
+ * - Programmatic fix lookup
+ */
+/**
+ * Severity level for a diagnostic.
+ */
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+/**
+ * A structured diagnostic message.
+ *
+ * Diagnostics provide rich error information beyond simple strings.
+ * They're used for parser errors, validation warnings, and hints.
+ */
+export interface Diagnostic {
+    /** Human-readable message */
+    readonly message: string;
+    /** Severity level */
+    readonly severity: DiagnosticSeverity;
+    /** Machine-readable code for programmatic handling (e.g., 'parse-error', 'missing-role') */
+    readonly code?: string;
+    /** 1-based line number in source */
+    readonly line?: number;
+    /** 0-based column offset in line */
+    readonly column?: number;
+    /** Original source text that triggered the diagnostic */
+    readonly source?: string;
+    /** Actionable suggestions for fixing the issue */
+    readonly suggestions?: readonly string[];
+}
+/**
+ * Result of a diagnostic-aware validation.
+ */
+export interface DiagnosticResult {
+    /** Whether validation passed (no errors, though warnings/info may exist) */
+    readonly ok: boolean;
+    /** All diagnostics, including errors, warnings, and info */
+    readonly diagnostics: readonly Diagnostic[];
+    /** Convenience: count of each severity level */
+    readonly summary: DiagnosticSummary;
+}
+/**
+ * Summary counts by severity.
+ */
+export interface DiagnosticSummary {
+    readonly errors: number;
+    readonly warnings: number;
+    readonly infos: number;
+}
+/**
+ * Collects diagnostics during a parsing/validation/compilation pass.
+ *
+ * Use this in your domain's validate() or parse() to accumulate
+ * structured feedback instead of throwing on the first error.
+ *
+ * @example
+ * ```typescript
+ * const collector = createDiagnosticCollector();
+ *
+ * // During parsing:
+ * collector.error('Unknown command: foo', { code: 'unknown-command', line: 3 });
+ * collector.warning('Low confidence match', { code: 'low-confidence', line: 5 });
+ * collector.info('Consider using "select" instead of "get"', { line: 5 });
+ *
+ * // Get result:
+ * const result = collector.toResult();
+ * // { ok: false, diagnostics: [...], summary: { errors: 1, warnings: 1, infos: 1 } }
+ * ```
+ */
+export interface DiagnosticCollector {
+    /** Add an error diagnostic */
+    error(message: string, options?: DiagnosticOptions): void;
+    /** Add a warning diagnostic */
+    warning(message: string, options?: DiagnosticOptions): void;
+    /** Add an info diagnostic */
+    info(message: string, options?: DiagnosticOptions): void;
+    /** Add a diagnostic with explicit severity */
+    add(diagnostic: Diagnostic): void;
+    /** Whether any errors have been collected */
+    hasErrors(): boolean;
+    /** Get all collected diagnostics */
+    getDiagnostics(): readonly Diagnostic[];
+    /** Build a DiagnosticResult from collected diagnostics */
+    toResult(): DiagnosticResult;
+}
+/**
+ * Options for adding a diagnostic via the collector's convenience methods.
+ */
+export interface DiagnosticOptions {
+    readonly code?: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly source?: string;
+    readonly suggestions?: readonly string[];
+}
+/**
+ * Create a new diagnostic collector.
+ */
+export declare function createDiagnosticCollector(): DiagnosticCollector;
+/**
+ * Create a diagnostic from an Error object.
+ * Useful for converting caught exceptions into structured diagnostics.
+ */
+export declare function fromError(error: unknown, options?: Omit<DiagnosticOptions, 'code'> & {
+    code?: string;
+}): Diagnostic;
+/**
+ * Filter diagnostics by severity.
+ */
+export declare function filterBySeverity(diagnostics: readonly Diagnostic[], severity: DiagnosticSeverity): readonly Diagnostic[];
+//# sourceMappingURL=diagnostics.d.ts.map