@lokascript/semantic 1.3.0 → 2.0.0

package/src/interchange/types.ts

@@ -0,0 +1,186 @@
+/**
+ * AST Interchange Format Types (Semantic-local copy)
+ *
+ * These are structurally identical to the canonical types in
+ * @hyperfixi/core/ast-utils/interchange/types.ts
+ *
+ * Duplicated here because the semantic package has no dependency on core.
+ * TypeScript's structural typing ensures these are assignable to the
+ * core package's versions when both are used by a consumer (e.g. AOT compiler).
+ */
+
+// =============================================================================
+// BASE TYPE
+// =============================================================================
+
+export type InterchangeNode =
+  | EventNode
+  | CommandNode
+  | LiteralNode
+  | IdentifierNode
+  | SelectorNode
+  | VariableNode
+  | BinaryNode
+  | UnaryNode
+  | MemberNode
+  | PossessiveNode
+  | CallNode
+  | IfNode
+  | RepeatNode
+  | ForEachNode
+  | WhileNode
+  | PositionalNode;
+
+/**
+ * Position fields are optional — present when the source parser provides them,
+ * absent for synthetically constructed nodes.
+ */
+export interface BaseNode {
+  readonly type: string;
+  /** Byte offset of node start in source (0-indexed). */
+  readonly start?: number;
+  /** Byte offset of node end in source (0-indexed, exclusive). */
+  readonly end?: number;
+  /** Source line number (1-indexed). */
+  readonly line?: number;
+  /** Column offset within line (0-indexed). */
+  readonly column?: number;
+}
+
+// =============================================================================
+// EXPRESSION NODES
+// =============================================================================
+
+export interface LiteralNode extends BaseNode {
+  readonly type: 'literal';
+  readonly value: string | number | boolean | null;
+}
+
+export interface IdentifierNode extends BaseNode {
+  readonly type: 'identifier';
+  readonly value: string;
+  readonly name?: string;
+}
+
+export interface SelectorNode extends BaseNode {
+  readonly type: 'selector';
+  readonly value: string;
+}
+
+export interface VariableNode extends BaseNode {
+  readonly type: 'variable';
+  readonly name: string;
+  readonly scope: 'local' | 'global' | 'element';
+}
+
+export interface BinaryNode extends BaseNode {
+  readonly type: 'binary';
+  readonly operator: string;
+  readonly left: InterchangeNode;
+  readonly right: InterchangeNode;
+}
+
+export interface UnaryNode extends BaseNode {
+  readonly type: 'unary';
+  readonly operator: string;
+  readonly operand: InterchangeNode;
+}
+
+export interface MemberNode extends BaseNode {
+  readonly type: 'member';
+  readonly object: InterchangeNode;
+  readonly property: string | InterchangeNode;
+  readonly computed?: boolean;
+}
+
+export interface PossessiveNode extends BaseNode {
+  readonly type: 'possessive';
+  readonly object: InterchangeNode;
+  readonly property: string;
+}
+
+export interface CallNode extends BaseNode {
+  readonly type: 'call';
+  readonly callee: InterchangeNode;
+  readonly args?: InterchangeNode[];
+}
+
+export interface PositionalNode extends BaseNode {
+  readonly type: 'positional';
+  readonly position: 'first' | 'last' | 'next' | 'previous' | 'closest' | 'parent' | 'random';
+  readonly target?: InterchangeNode;
+}
+
+// =============================================================================
+// COMMAND & EVENT NODES
+// =============================================================================
+
+export interface CommandNode extends BaseNode {
+  readonly type: 'command';
+  readonly name: string;
+  readonly args?: InterchangeNode[];
+  readonly target?: InterchangeNode;
+  readonly modifiers?: Record<string, unknown>;
+  /** Semantic roles from the semantic parser (patient, destination, source, etc.). */
+  readonly roles?: Readonly<Record<string, InterchangeNode>>;
+}
+
+export interface EventNode extends BaseNode {
+  readonly type: 'event';
+  readonly event: string;
+  readonly modifiers?: EventModifiers;
+  readonly body?: InterchangeNode[];
+  readonly target?: InterchangeNode;
+}
+
+// =============================================================================
+// CONTROL FLOW NODES
+// =============================================================================
+
+export interface IfNode extends BaseNode {
+  readonly type: 'if';
+  readonly condition: InterchangeNode;
+  readonly thenBranch: InterchangeNode[];
+  readonly elseBranch?: InterchangeNode[];
+  readonly elseIfBranches?: ReadonlyArray<{
+    readonly condition: InterchangeNode;
+    readonly body: InterchangeNode[];
+  }>;
+}
+
+export interface RepeatNode extends BaseNode {
+  readonly type: 'repeat';
+  readonly count?: number | InterchangeNode;
+  readonly whileCondition?: InterchangeNode;
+  readonly untilEvent?: string;
+  readonly body: InterchangeNode[];
+}
+
+export interface ForEachNode extends BaseNode {
+  readonly type: 'foreach';
+  readonly itemName: string;
+  readonly indexName?: string;
+  readonly collection: InterchangeNode;
+  readonly body: InterchangeNode[];
+}
+
+export interface WhileNode extends BaseNode {
+  readonly type: 'while';
+  readonly condition: InterchangeNode;
+  readonly body: InterchangeNode[];
+}
+
+// =============================================================================
+// EVENT MODIFIERS
+// =============================================================================
+
+export interface EventModifiers {
+  readonly prevent?: boolean;
+  readonly stop?: boolean;
+  readonly once?: boolean;
+  readonly passive?: boolean;
+  readonly capture?: boolean;
+  readonly debounce?: number;
+  readonly throttle?: number;
+  readonly from?: string;
+}

package/src/parser/pattern-matcher.ts

@@ -9,12 +9,19 @@ import type {
   LanguagePattern,
   PatternToken,
   PatternMatchResult,
+  ReferenceValue,
   SemanticRole,
   SemanticValue,
   TokenStream,
   LanguageToken,
 } from '../types';
-import { createSelector, createLiteral, createReference, createPropertyPath } from '../types';
+import {
+  createSelector,
+  createLiteral,
+  createReference,
+  createPropertyPath,
+  isValidReference,
+} from '../types';
 import { isTypeCompatible } from './utils/type-validation';
 import { getPossessiveReference } from './utils/possessive-keywords';
 import type { LanguageProfile } from '../generators/profiles/types';
@@ -341,17 +348,52 @@ export class PatternMatcher {
       return null;
     }
 
-    // Property should be an identifier, keyword (not structural), or selector (for style props)
-    // Examples: "my value", "my innerHTML", "my *background", "my *opacity"
+    // Property should be an identifier, keyword (not structural), or selector (for style/dot/attr)
+    // Examples: "my value", "my innerHTML", "my *background", "my *opacity", "my @data-count"
+    // Also handles dot-property access: "my.textContent" tokenized as "my" + ".textContent"
     if (
       propertyToken.kind === 'identifier' ||
       (propertyToken.kind === 'keyword' && !this.isStructuralKeyword(propertyToken.value)) ||
-      (propertyToken.kind === 'selector' && propertyToken.value.startsWith('*'))
+      (propertyToken.kind === 'selector' && propertyToken.value.startsWith('*')) ||
+      (propertyToken.kind === 'selector' && propertyToken.value.startsWith('@')) ||
+      (propertyToken.kind === 'selector' &&
+        propertyToken.value.startsWith('.') &&
+        /^\.[a-zA-Z_]\w*/.test(propertyToken.value))
     ) {
       tokens.advance();
 
+      // For dot-property selectors (.textContent), strip the leading dot
+      let propertyName = propertyToken.value;
+      if (
+        propertyToken.kind === 'selector' &&
+        propertyName.startsWith('.') &&
+        /^\.[a-zA-Z_]\w*/.test(propertyName)
+      ) {
+        propertyName = propertyName.substring(1);
+      }
+
+      // Consume chained dot-property access (.parentElement.style.display)
+      let chainedProps = propertyName;
+      while (
+        tokens.peek()?.kind === 'selector' &&
+        tokens.peek()!.value.startsWith('.') &&
+        /^\.[a-zA-Z_]\w*/.test(tokens.peek()!.value)
+      ) {
+        chainedProps += tokens.peek()!.value; // keep the dots for chaining
+        tokens.advance();
+      }
+
+      // Check for method call — next token is '(' in the value (e.g., .getAttribute("data-id"))
+      const nextPeek = tokens.peek();
+      if (nextPeek?.kind === 'literal' && nextPeek.value.startsWith('(')) {
+        // Consume method args
+        chainedProps += nextPeek.value;
+        tokens.advance();
+      }
+
       // Create property-path: my value -> { object: me, property: 'value' }
-      return createPropertyPath(createReference(baseRef as any), propertyToken.value);
+      // baseRef from getPossessiveReference is always a valid reference ('me', 'you', 'it', etc.)
+      return createPropertyPath(createReference(baseRef as ReferenceValue['value']), chainedProps);
     }
 
     // Not a valid property, revert
@@ -747,20 +789,22 @@ export class PatternMatcher {
       case 'keyword':
         // Keywords might be references or values
         const lower = (token.normalized || token.value).toLowerCase();
-        if (['me', 'you', 'it', 'result', 'event', 'target', 'body'].includes(lower)) {
-          return createReference(lower as any);
+        if (isValidReference(lower)) {
+          return createReference(lower);
         }
         return createLiteral(token.normalized || token.value);
 
       case 'identifier':
         // Check if it's a variable reference (:varname)
+        // Note: :varname doesn't match the ReferenceValue union but is used as a
+        // reference token downstream — this cast preserves existing behavior
         if (token.value.startsWith(':')) {
-          return createReference(token.value as any);
+          return createReference(token.value as ReferenceValue['value']);
         }
         // Check if it's a built-in reference
         const identLower = token.value.toLowerCase();
-        if (['me', 'you', 'it', 'result', 'event', 'target', 'body'].includes(identLower)) {
-          return createReference(identLower as any);
+        if (isValidReference(identLower)) {
+          return createReference(identLower);
         }
         // Regular identifiers are variable references - use 'expression' type
         // which gets converted to 'identifier' AST nodes by semantic-integration.ts
@@ -816,15 +860,20 @@ export class PatternMatcher {
   }
 
   /**
-   * Apply extraction rules to fill in default values for missing roles.
+   * Apply extraction rules to fill in static values and defaults for missing roles.
    */
   private applyExtractionRules(
     pattern: LanguagePattern,
     captured: Map<SemanticRole, SemanticValue>
   ): void {
     for (const [role, rule] of Object.entries(pattern.extraction)) {
-      if (!captured.has(role as SemanticRole) && rule.default) {
-        captured.set(role as SemanticRole, rule.default);
+      if (!captured.has(role as SemanticRole)) {
+        if (rule.value !== undefined) {
+          // Static value extraction (e.g., action: { value: "toggle" })
+          captured.set(role as SemanticRole, { type: 'literal', value: rule.value });
+        } else if (rule.default) {
+          captured.set(role as SemanticRole, rule.default);
+        }
       }
     }
   }
@@ -833,7 +882,7 @@ export class PatternMatcher {
    * Check if a pattern token is optional.
    */
   private isOptional(patternToken: PatternToken): boolean {
-    return (patternToken as any).optional === true;
+    return patternToken.type !== 'literal' && patternToken.optional === true;
   }
 
   /**
@@ -1028,7 +1077,8 @@ export class PatternMatcher {
 
       // Check if the value has preposition metadata (from Arabic tokenizer)
       // This metadata is attached when a preposition particle token is consumed
-      const metadata = (value as any).metadata;
+      const metadata =
+        'metadata' in value ? (value as { metadata: Record<string, unknown> }).metadata : undefined;
       if (metadata && typeof metadata.prepositionValue === 'string') {
         const usedPreposition = metadata.prepositionValue;