@lokascript/semantic 1.0.0

package/src/parser/utils/marker-resolution.ts

@@ -0,0 +1,111 @@
+/**
+ * Marker Resolution Utility
+ *
+ * Shared utilities for resolving role markers from language profiles.
+ * Used by pattern-generator to build tokens and extraction rules.
+ */
+
+import type { SemanticRole } from '../../types';
+import type { LanguageProfile, RoleMarker } from '../../generators/language-profiles';
+
+/**
+ * Minimum interface for role specs that can have marker resolution.
+ * Compatible with the RoleSpec type from command-schemas.
+ */
+export interface RoleSpecWithMarker {
+  role: SemanticRole;
+  markerOverride?: Record<string, string | undefined>;
+}
+
+/**
+ * Resolved marker information for a role.
+ */
+export interface ResolvedMarker {
+  /** Primary marker string (may be empty string for no marker) */
+  primary: string;
+  /** Alternative markers */
+  alternatives?: string[];
+  /** Position relative to role value */
+  position: 'before' | 'after';
+  /** Whether this is an override marker */
+  isOverride: boolean;
+}
+
+/**
+ * Resolve the marker for a role in a specific language.
+ *
+ * Checks for command-specific marker overrides first,
+ * then falls back to the default marker from the language profile.
+ *
+ * @param roleSpec Role specification with optional override
+ * @param profile Language profile with role markers
+ * @returns Resolved marker info, or null if no marker
+ */
+export function resolveMarkerForRole(
+  roleSpec: RoleSpecWithMarker,
+  profile: LanguageProfile
+): ResolvedMarker | null {
+  // Check for command-specific marker override first
+  const overrideMarker = roleSpec.markerOverride?.[profile.code];
+  const defaultMarker = profile.roleMarkers[roleSpec.role];
+
+  if (overrideMarker !== undefined) {
+    // Use override marker (can be empty string to suppress default marker)
+    return {
+      primary: overrideMarker,
+      position: defaultMarker?.position ?? 'before',
+      isOverride: true,
+    };
+  }
+
+  if (defaultMarker && defaultMarker.primary) {
+    const result: ResolvedMarker = {
+      primary: defaultMarker.primary,
+      position: defaultMarker.position,
+      isOverride: false,
+    };
+    if (defaultMarker.alternatives) {
+      result.alternatives = defaultMarker.alternatives;
+    }
+    return result;
+  }
+
+  return null;
+}
+
+/**
+ * Get all markers (primary + alternatives) for a role.
+ *
+ * @param roleSpec Role specification
+ * @param profile Language profile
+ * @returns Array of marker strings, or empty array if no markers
+ */
+export function getAllMarkersForRole(
+  roleSpec: RoleSpecWithMarker,
+  profile: LanguageProfile
+): string[] {
+  const resolved = resolveMarkerForRole(roleSpec, profile);
+  if (!resolved || !resolved.primary) {
+    return [];
+  }
+
+  const markers = [resolved.primary];
+  if (resolved.alternatives) {
+    markers.push(...resolved.alternatives);
+  }
+  return markers;
+}
+
+/**
+ * Get the default role marker from a language profile.
+ *
+ * @param profile Language profile
+ * @param role Semantic role
+ * @returns Role marker or undefined
+ */
+export function getDefaultRoleMarker(
+  profile: LanguageProfile,
+  role: SemanticRole
+): RoleMarker | undefined {
+  return profile.roleMarkers[role];
+}

package/src/parser/utils/possessive-keywords.ts

@@ -0,0 +1,43 @@
+/**
+ * Possessive Keywords Utility
+ *
+ * Provides functions to look up possessive keywords from language profiles.
+ * Used by pattern-matcher to recognize possessive expressions like "my value".
+ */
+
+import type { LanguageProfile } from '../../generators/profiles/types';
+
+/**
+ * Get the reference for a possessive keyword from a language profile.
+ *
+ * @param profile Language profile
+ * @param keyword Possessive keyword (e.g., 'my', 'your', 'its')
+ * @returns The reference (e.g., 'me', 'you', 'it') or undefined if not found
+ */
+export function getPossessiveReference(
+  profile: LanguageProfile,
+  keyword: string
+): string | undefined {
+  return profile.possessive?.keywords?.[keyword];
+}
+
+/**
+ * Check if a keyword is a possessive keyword in the given profile.
+ *
+ * @param profile Language profile
+ * @param keyword Keyword to check
+ * @returns True if the keyword is a possessive keyword
+ */
+export function isPossessiveKeyword(profile: LanguageProfile, keyword: string): boolean {
+  return profile.possessive?.keywords?.[keyword] !== undefined;
+}
+
+/**
+ * Get all possessive keywords from a language profile.
+ *
+ * @param profile Language profile
+ * @returns Record of possessive keywords to references, or empty object
+ */
+export function getAllPossessiveKeywords(profile: LanguageProfile): Record<string, string> {
+  return profile.possessive?.keywords ?? {};
+}

package/src/parser/utils/role-positioning.ts

@@ -0,0 +1,70 @@
+/**
+ * Role Positioning Utility
+ *
+ * Shared utilities for sorting and positioning semantic roles based on word order.
+ * Used by pattern-generator and pattern-matcher to ensure consistent behavior.
+ */
+
+import type { SemanticRole } from '../../types';
+import type { WordOrder } from '../../generators/profiles/types';
+
+/**
+ * Priority order for semantic roles used in pattern matching.
+ * Lower number = higher priority (comes first in pattern).
+ * Only includes roles commonly used in patterns.
+ */
+export const ROLE_PRIORITY: Partial<Record<SemanticRole, number>> = {
+  patient: 1,
+  destination: 2,
+  source: 3,
+  style: 4,
+  manner: 5,
+  goal: 6,
+};
+
+/**
+ * Get the priority of a semantic role.
+ * Returns 99 for unknown/unlisted roles.
+ */
+export function getRolePriority(role: SemanticRole): number {
+  return ROLE_PRIORITY[role] ?? 99;
+}
+
+/**
+ * Sort semantic roles by their priority.
+ * Patient comes first, then destination, source, etc.
+ */
+export function sortRolesByPriority(roles: SemanticRole[]): SemanticRole[] {
+  return [...roles].sort((a, b) => getRolePriority(a) - getRolePriority(b));
+}
+
+// Re-export for convenience
+export type { WordOrder };
+
+/**
+ * Minimum interface for roles that can be sorted by position.
+ */
+export interface RoleWithPosition {
+  role: SemanticRole;
+  sovPosition?: number;
+  svoPosition?: number;
+}
+
+/**
+ * Sort roles by their position for a given word order.
+ *
+ * @param roles Array of role specs with position info
+ * @param wordOrder The word order to use (SVO, SOV, VSO)
+ * @returns Sorted array of roles
+ */
+export function sortRolesByWordOrder<T extends RoleWithPosition>(
+  roles: readonly T[],
+  wordOrder: WordOrder
+): T[] {
+  const sortKey = wordOrder === 'SOV' ? 'sovPosition' : 'svoPosition';
+  return [...roles].sort((a, b) => {
+    const aPos = a[sortKey] ?? 99;
+    const bPos = b[sortKey] ?? 99;
+    return aPos - bPos;
+  });
+}

package/src/parser/utils/type-validation.ts

@@ -0,0 +1,134 @@
+/**
+ * Type Validation Utility
+ *
+ * Shared utilities for validating semantic value types against expected types.
+ * Used by pattern-matcher to validate captured role values.
+ */
+
+import type { SemanticValue } from '../../types';
+
+/**
+ * Semantic value type strings.
+ */
+export type SemanticValueType = SemanticValue['type'];
+
+/**
+ * Check if a value type matches any of the expected types.
+ *
+ * The 'expression' type is treated as a wildcard that matches any value.
+ * The 'property-path' type is compatible with selector, reference, and expression.
+ *
+ * @param actualType The actual type of the value
+ * @param expectedTypes Array of expected types
+ * @returns True if the type is compatible
+ */
+export function isTypeCompatible(
+  actualType: SemanticValueType | string,
+  expectedTypes: (SemanticValueType | string)[]
+): boolean {
+  // Empty expected types means any type is valid
+  if (!expectedTypes || expectedTypes.length === 0) {
+    return true;
+  }
+
+  // Direct match
+  if (expectedTypes.includes(actualType)) {
+    return true;
+  }
+
+  // 'expression' is always compatible (wildcard)
+  if (expectedTypes.includes('expression')) {
+    return true;
+  }
+
+  // 'property-path' is compatible with selector, reference, and expression
+  if (actualType === 'property-path') {
+    return expectedTypes.some(t => ['selector', 'reference', 'expression'].includes(t));
+  }
+
+  return false;
+}
+
+/**
+ * Validate a semantic value against expected types.
+ *
+ * @param value The semantic value to validate
+ * @param expectedTypes Array of expected types (empty means any type is valid)
+ * @returns True if the value type is valid
+ */
+export function validateValueType(
+  value: SemanticValue,
+  expectedTypes?: (SemanticValueType | string)[]
+): boolean {
+  if (!expectedTypes || expectedTypes.length === 0) {
+    return true;
+  }
+
+  return isTypeCompatible(value.type, expectedTypes);
+}
+
+/**
+ * Check if a value is a CSS selector.
+ */
+export function isCSSSelector(value: string): boolean {
+  return value.startsWith('.') || value.startsWith('#') || value.startsWith('<');
+}
+
+/**
+ * Check if a value is a class name (starts with .).
+ */
+export function isClassName(value: string): boolean {
+  return value.startsWith('.');
+}
+
+/**
+ * Check if a value is an ID selector (starts with #).
+ */
+export function isIdSelector(value: string): boolean {
+  return value.startsWith('#');
+}
+
+/**
+ * Check if a value is a CSS property reference (starts with *).
+ */
+export function isCSSPropertyRef(value: string): boolean {
+  return value.startsWith('*');
+}
+
+/**
+ * Check if a value is a numeric value.
+ */
+export function isNumericValue(value: string): boolean {
+  // Handle duration values (e.g., "100ms", "2s")
+  const durationMatch = value.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (durationMatch) {
+    return true;
+  }
+
+  // Plain number
+  const num = parseFloat(value);
+  return !isNaN(num) && isFinite(num);
+}
+
+/**
+ * Check if a value is a property name (identifier-like).
+ */
+export function isPropertyName(value: string): boolean {
+  // Property names are identifiers (start with letter or _, contain alphanumeric)
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value);
+}
+
+/**
+ * Check if a value is a variable reference (starts with :).
+ */
+export function isVariableRef(value: string): boolean {
+  return value.startsWith(':');
+}
+
+/**
+ * Check if a value is a built-in reference (me, you, it, etc.).
+ */
+export function isBuiltInReference(value: string): boolean {
+  const builtIns = new Set(['me', 'you', 'it', 'result', 'event', 'target', 'body']);
+  return builtIns.has(value.toLowerCase());
+}

package/src/patterns/add/ar.ts

@@ -0,0 +1,71 @@
+/**
+ * Arabic Add Patterns
+ *
+ * Hand-crafted patterns for "add" command.
+ * Arabic uses VSO order: أضف {patient} إلى {target}
+ */
+
+import type { LanguagePattern } from '../../types';
+
+/**
+ * Get Arabic add patterns.
+ */
+export function getAddPatternsAr(): LanguagePattern[] {
+  return [
+    {
+      id: 'add-ar-full',
+      language: 'ar',
+      command: 'add',
+      priority: 100,
+      template: {
+        format: 'أضف {patient} إلى {destination}',
+        tokens: [
+          { type: 'literal', value: 'أضف', alternatives: ['اضف', 'أضيف', 'اضافة'] },
+          { type: 'role', role: 'patient' },
+          { type: 'literal', value: 'إلى', alternatives: ['الى', 'ل', 'لـ'] },
+          { type: 'role', role: 'destination' },
+        ],
+      },
+      extraction: {
+        patient: { position: 1 },
+        destination: { marker: 'إلى', markerAlternatives: ['الى', 'ل', 'لـ'] },
+      },
+    },
+    {
+      id: 'add-ar-simple',
+      language: 'ar',
+      command: 'add',
+      priority: 90,
+      template: {
+        format: 'أضف {patient}',
+        tokens: [
+          { type: 'literal', value: 'أضف', alternatives: ['اضف', 'أضيف'] },
+          { type: 'role', role: 'patient' },
+        ],
+      },
+      extraction: {
+        patient: { position: 1 },
+        destination: { default: { type: 'reference', value: 'me' } },
+      },
+    },
+    {
+      id: 'add-ar-with-على',
+      language: 'ar',
+      command: 'add',
+      priority: 95,
+      template: {
+        format: 'أضف {patient} على {destination}',
+        tokens: [
+          { type: 'literal', value: 'أضف', alternatives: ['اضف'] },
+          { type: 'role', role: 'patient' },
+          { type: 'literal', value: 'على' },
+          { type: 'role', role: 'destination' },
+        ],
+      },
+      extraction: {
+        patient: { position: 1 },
+        destination: { marker: 'على' },
+      },
+    },
+  ];
+}

package/src/patterns/add/bn.ts

@@ -0,0 +1,70 @@
+/**
+ * Bengali Add Patterns
+ *
+ * Patterns for parsing "add" command in Bengali.
+ */
+
+import type { LanguagePattern } from '../../types';
+
+export function getAddPatternsBn(): LanguagePattern[] {
+  return [
+    // Full pattern: .active কে যোগ করুন
+    {
+      id: 'add-bn-full',
+      language: 'bn',
+      command: 'add',
+      priority: 100,
+      template: {
+        format: '{patient} কে যোগ করুন',
+        tokens: [
+          { type: 'role', role: 'patient' },
+          { type: 'literal', value: 'কে' },
+          { type: 'literal', value: 'যোগ' },
+          { type: 'literal', value: 'করুন' },
+        ],
+      },
+      extraction: {
+        patient: { position: 0 },
+      },
+    },
+    // Simple pattern: যোগ .active
+    {
+      id: 'add-bn-simple',
+      language: 'bn',
+      command: 'add',
+      priority: 90,
+      template: {
+        format: 'যোগ {patient}',
+        tokens: [
+          { type: 'literal', value: 'যোগ' },
+          { type: 'role', role: 'patient' },
+        ],
+      },
+      extraction: {
+        patient: { position: 1 },
+      },
+    },
+    // With destination: #button এ .active কে যোগ করুন
+    {
+      id: 'add-bn-with-dest',
+      language: 'bn',
+      command: 'add',
+      priority: 95,
+      template: {
+        format: '{destination} এ {patient} কে যোগ করুন',
+        tokens: [
+          { type: 'role', role: 'destination' },
+          { type: 'literal', value: 'এ', alternatives: ['তে'] },
+          { type: 'role', role: 'patient' },
+          { type: 'literal', value: 'কে' },
+          { type: 'literal', value: 'যোগ' },
+          { type: 'literal', value: 'করুন' },
+        ],
+      },
+      extraction: {
+        destination: { position: 0 },
+        patient: { position: 2 },
+      },
+    },
+  ];
+}

package/src/patterns/add/hi.ts

@@ -0,0 +1,69 @@
+/**
+ * Hindi Add Patterns
+ *
+ * Patterns for parsing "add" command in Hindi.
+ */
+
+import type { LanguagePattern } from '../../types';
+
+export function getAddPatternsHi(): LanguagePattern[] {
+  return [
+    // Full pattern: .class को #element में जोड़ें
+    {
+      id: 'add-hi-full',
+      language: 'hi',
+      command: 'add',
+      priority: 100,
+      template: {
+        format: '{patient} को {destination} में जोड़ें',
+        tokens: [
+          { type: 'role', role: 'patient' },
+          { type: 'literal', value: 'को' },
+          { type: 'role', role: 'destination' },
+          { type: 'literal', value: 'में' },
+          { type: 'literal', value: 'जोड़ें', alternatives: ['जोड़'] },
+        ],
+      },
+      extraction: {
+        patient: { position: 0 },
+        destination: { marker: 'में', position: 3 },
+      },
+    },
+    // Simple pattern: .class जोड़ें
+    {
+      id: 'add-hi-simple',
+      language: 'hi',
+      command: 'add',
+      priority: 90,
+      template: {
+        format: '{patient} जोड़ें',
+        tokens: [
+          { type: 'role', role: 'patient' },
+          { type: 'literal', value: 'जोड़ें', alternatives: ['जोड़'] },
+        ],
+      },
+      extraction: {
+        patient: { position: 0 },
+        destination: { default: { type: 'reference', value: 'me' } },
+      },
+    },
+    // Bare pattern: जोड़ें .class
+    {
+      id: 'add-hi-bare',
+      language: 'hi',
+      command: 'add',
+      priority: 80,
+      template: {
+        format: 'जोड़ें {patient}',
+        tokens: [
+          { type: 'literal', value: 'जोड़ें', alternatives: ['जोड़'] },
+          { type: 'role', role: 'patient' },
+        ],
+      },
+      extraction: {
+        patient: { position: 1 },
+        destination: { default: { type: 'reference', value: 'me' } },
+      },
+    },
+  ];
+}

package/src/patterns/add/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Add Command Patterns
+ *
+ * Hand-crafted patterns for "add" command across languages.
+ *
+ * @generated This file is auto-generated. Do not edit manually.
+ */
+
+import type { LanguagePattern } from '../../types';
+
+import { getAddPatternsAr } from './ar';
+import { getAddPatternsBn } from './bn';
+import { getAddPatternsHi } from './hi';
+import { getAddPatternsIt } from './it';
+import { getAddPatternsJa } from './ja';
+import { getAddPatternsKo } from './ko';
+import { getAddPatternsMs } from './ms';
+import { getAddPatternsPl } from './pl';
+import { getAddPatternsRu } from './ru';
+import { getAddPatternsTh } from './th';
+import { getAddPatternsTl } from './tl';
+import { getAddPatternsTr } from './tr';
+import { getAddPatternsUk } from './uk';
+import { getAddPatternsVi } from './vi';
+import { getAddPatternsZh } from './zh';
+
+/**
+ * Get add patterns for a specific language.
+ */
+export function getAddPatternsForLanguage(language: string): LanguagePattern[] {
+  switch (language) {
+    case 'ar':
+      return getAddPatternsAr();
+    case 'bn':
+      return getAddPatternsBn();
+    case 'hi':
+      return getAddPatternsHi();
+    case 'it':
+      return getAddPatternsIt();
+    case 'ja':
+      return getAddPatternsJa();
+    case 'ko':
+      return getAddPatternsKo();
+    case 'ms':
+      return getAddPatternsMs();
+    case 'pl':
+      return getAddPatternsPl();
+    case 'ru':
+      return getAddPatternsRu();
+    case 'th':
+      return getAddPatternsTh();
+    case 'tl':
+      return getAddPatternsTl();
+    case 'tr':
+      return getAddPatternsTr();
+    case 'uk':
+      return getAddPatternsUk();
+    case 'vi':
+      return getAddPatternsVi();
+    case 'zh':
+      return getAddPatternsZh();
+    default:
+      return [];
+  }
+}
+
+// Re-export language-specific getters for tree-shaking
+export { getAddPatternsAr } from './ar';
+export { getAddPatternsBn } from './bn';
+export { getAddPatternsHi } from './hi';
+export { getAddPatternsIt } from './it';
+export { getAddPatternsJa } from './ja';
+export { getAddPatternsKo } from './ko';
+export { getAddPatternsMs } from './ms';
+export { getAddPatternsPl } from './pl';
+export { getAddPatternsRu } from './ru';
+export { getAddPatternsTh } from './th';
+export { getAddPatternsTl } from './tl';
+export { getAddPatternsTr } from './tr';
+export { getAddPatternsUk } from './uk';
+export { getAddPatternsVi } from './vi';
+export { getAddPatternsZh } from './zh';
+
+/**
+ * Languages that have hand-crafted add patterns.
+ */
+export const addPatternLanguages = ['ar', 'bn', 'hi', 'it', 'ja', 'ko', 'ms', 'pl', 'ru', 'th', 'tl', 'tr', 'uk', 'vi', 'zh'];