@lokascript/semantic 1.0.0

package/src/generators/profiles/ukrainian.ts

@@ -0,0 +1,270 @@
+/**
+ * Ukrainian Language Profile
+ *
+ * SVO word order, prepositions, space-separated.
+ * Ukrainian is a fusional language with rich verb conjugation.
+ * Uses infinitive form in software UI (industry standard).
+ */
+
+import type { LanguageProfile } from './types';
+
+export const ukrainianProfile: LanguageProfile = {
+  code: 'uk',
+  name: 'Ukrainian',
+  nativeName: 'Українська',
+  direction: 'ltr',
+  wordOrder: 'SVO',
+  markingStrategy: 'preposition',
+  usesSpaces: true,
+  defaultVerbForm: 'infinitive',
+  verb: {
+    position: 'start',
+    subjectDrop: true,
+    suffixes: ['ти', 'тися', 'ити', 'итися', 'ати', 'атися', 'іти', 'ітися'],
+  },
+  references: {
+    me: 'я',
+    it: 'це',
+    you: 'ти',
+    result: 'результат',
+    event: 'подія',
+    target: 'ціль',
+    body: 'body',
+  },
+  possessive: {
+    marker: '',
+    markerPosition: 'after-object',
+    usePossessiveAdjectives: true,
+    specialForms: {
+      me: 'мій',
+      it: 'його',
+      you: 'твій',
+    },
+    keywords: {
+      // "my" variants (masculine/feminine/neuter/plural)
+      мій: 'me',
+      моя: 'me',
+      моє: 'me',
+      мої: 'me',
+      // "your" variants
+      твій: 'you',
+      твоя: 'you',
+      твоє: 'you',
+      твої: 'you',
+      // "its/his/her" forms
+      його: 'it', // his/its
+      її: 'it', // her/its (feminine)
+    },
+  },
+  roleMarkers: {
+    destination: { primary: 'в', alternatives: ['на', 'до'], position: 'before' },
+    source: { primary: 'з', alternatives: ['від', 'із'], position: 'before' },
+    patient: { primary: '', position: 'before' },
+    style: { primary: 'з', alternatives: ['із'], position: 'before' },
+  },
+  keywords: {
+    // Class/Attribute operations (infinitive form)
+    toggle: {
+      primary: 'перемкнути',
+      alternatives: ['перемкни'],
+      normalized: 'toggle',
+      form: 'infinitive',
+    },
+    add: { primary: 'додати', alternatives: ['додай'], normalized: 'add', form: 'infinitive' },
+    remove: {
+      primary: 'видалити',
+      alternatives: ['видали', 'прибрати', 'прибери'],
+      normalized: 'remove',
+      form: 'infinitive',
+    },
+    // Content operations
+    put: {
+      primary: 'покласти',
+      alternatives: ['поклади', 'помістити', 'помісти', 'вставити', 'встав'],
+      normalized: 'put',
+      form: 'infinitive',
+    },
+    append: {
+      primary: 'додати_в_кінець',
+      alternatives: ['дописати'],
+      normalized: 'append',
+      form: 'infinitive',
+    },
+    prepend: { primary: 'додати_на_початок', normalized: 'prepend', form: 'infinitive' },
+    take: { primary: 'взяти', alternatives: ['візьми'], normalized: 'take', form: 'infinitive' },
+    make: { primary: 'створити', alternatives: ['створи'], normalized: 'make', form: 'infinitive' },
+    clone: {
+      primary: 'клонувати',
+      alternatives: ['клонуй'],
+      normalized: 'clone',
+      form: 'infinitive',
+    },
+    swap: {
+      primary: 'поміняти',
+      alternatives: ['поміняй'],
+      normalized: 'swap',
+      form: 'infinitive',
+    },
+    morph: {
+      primary: 'трансформувати',
+      alternatives: ['трансформуй'],
+      normalized: 'morph',
+      form: 'infinitive',
+    },
+    // Variable operations
+    set: {
+      primary: 'встановити',
+      alternatives: ['встанови', 'задати', 'задай'],
+      normalized: 'set',
+      form: 'infinitive',
+    },
+    get: { primary: 'отримати', alternatives: ['отримай'], normalized: 'get', form: 'infinitive' },
+    increment: {
+      primary: 'збільшити',
+      alternatives: ['збільш'],
+      normalized: 'increment',
+      form: 'infinitive',
+    },
+    decrement: {
+      primary: 'зменшити',
+      alternatives: ['зменш'],
+      normalized: 'decrement',
+      form: 'infinitive',
+    },
+    log: { primary: 'записати', alternatives: ['запиши'], normalized: 'log', form: 'infinitive' },
+    // Visibility
+    show: { primary: 'показати', alternatives: ['покажи'], normalized: 'show', form: 'infinitive' },
+    hide: {
+      primary: 'сховати',
+      alternatives: ['сховай', 'приховати', 'приховай'],
+      normalized: 'hide',
+      form: 'infinitive',
+    },
+    transition: {
+      primary: 'анімувати',
+      alternatives: ['анімуй'],
+      normalized: 'transition',
+      form: 'infinitive',
+    },
+    // Events
+    on: { primary: 'при', alternatives: ['коли'], normalized: 'on' },
+    trigger: {
+      primary: 'викликати',
+      alternatives: ['виклич'],
+      normalized: 'trigger',
+      form: 'infinitive',
+    },
+    send: {
+      primary: 'надіслати',
+      alternatives: ['надішли'],
+      normalized: 'send',
+      form: 'infinitive',
+    },
+    // DOM focus
+    focus: {
+      primary: 'сфокусувати',
+      alternatives: ['сфокусуй', 'фокус'],
+      normalized: 'focus',
+      form: 'infinitive',
+    },
+    blur: {
+      primary: 'розфокусувати',
+      alternatives: ['розфокусуй'],
+      normalized: 'blur',
+      form: 'infinitive',
+    },
+    // Navigation
+    go: {
+      primary: 'перейти',
+      alternatives: ['перейди', 'йти', 'йди'],
+      normalized: 'go',
+      form: 'infinitive',
+    },
+    // Async
+    wait: {
+      primary: 'чекати',
+      alternatives: ['чекай', 'зачекай'],
+      normalized: 'wait',
+      form: 'infinitive',
+    },
+    fetch: {
+      primary: 'завантажити',
+      alternatives: ['завантаж'],
+      normalized: 'fetch',
+      form: 'infinitive',
+    },
+    settle: { primary: 'стабілізувати', normalized: 'settle', form: 'infinitive' },
+    // Control flow
+    if: { primary: 'якщо', normalized: 'if' },
+    when: { primary: 'коли', normalized: 'when' },
+    where: { primary: 'де', normalized: 'where' },
+    else: { primary: 'інакше', normalized: 'else' },
+    repeat: {
+      primary: 'повторити',
+      alternatives: ['повтори'],
+      normalized: 'repeat',
+      form: 'infinitive',
+    },
+    for: { primary: 'для', alternatives: ['кожний'], normalized: 'for' },
+    while: { primary: 'поки', normalized: 'while' },
+    continue: {
+      primary: 'продовжити',
+      alternatives: ['продовжуй'],
+      normalized: 'continue',
+      form: 'infinitive',
+    },
+    halt: {
+      primary: 'зупинити',
+      alternatives: ['зупинись', 'стоп'],
+      normalized: 'halt',
+      form: 'infinitive',
+    },
+    throw: { primary: 'кинути', alternatives: ['кинь'], normalized: 'throw', form: 'infinitive' },
+    call: {
+      primary: 'викликати',
+      alternatives: ['виклич'],
+      normalized: 'call',
+      form: 'infinitive',
+    },
+    return: {
+      primary: 'повернути',
+      alternatives: ['поверни'],
+      normalized: 'return',
+      form: 'infinitive',
+    },
+    then: { primary: 'потім', alternatives: ['далі', 'тоді'], normalized: 'then' },
+    and: { primary: 'і', alternatives: ['та'], normalized: 'and' },
+    end: { primary: 'кінець', normalized: 'end' },
+    // Advanced
+    js: { primary: 'js', normalized: 'js' },
+    async: { primary: 'асинхронно', alternatives: ['async'], normalized: 'async' },
+    tell: { primary: 'сказати', alternatives: ['скажи'], normalized: 'tell', form: 'infinitive' },
+    default: { primary: 'за_замовчуванням', normalized: 'default' },
+    init: {
+      primary: 'ініціалізувати',
+      alternatives: ['ініціалізуй'],
+      normalized: 'init',
+      form: 'infinitive',
+    },
+    behavior: { primary: 'поведінка', normalized: 'behavior' },
+    install: { primary: 'встановити_пакет', normalized: 'install', form: 'infinitive' },
+    measure: {
+      primary: 'виміряти',
+      alternatives: ['виміряй'],
+      normalized: 'measure',
+      form: 'infinitive',
+    },
+    // Modifiers
+    into: { primary: 'в', alternatives: ['у'], normalized: 'into' },
+    before: { primary: 'до', alternatives: ['перед'], normalized: 'before' },
+    after: { primary: 'після', normalized: 'after' },
+    // Event modifiers
+    until: { primary: 'до', alternatives: ['поки_не'], normalized: 'until' },
+    event: { primary: 'подія', normalized: 'event' },
+    from: { primary: 'з', alternatives: ['від', 'із'], normalized: 'from' },
+  },
+  eventHandler: {
+    keyword: { primary: 'при', alternatives: ['коли'], normalized: 'on' },
+    sourceMarker: { primary: 'на', alternatives: ['в', 'при'], position: 'before' },
+  },
+};

package/src/generators/profiles/vietnamese.ts

@@ -0,0 +1,133 @@
+/**
+ * Vietnamese Language Profile
+ *
+ * SVO word order, prepositions, space-separated.
+ * Vietnamese is an isolating (analytic) language with no inflection.
+ * Uses Latin script with extensive diacritics for tone marking.
+ */
+
+import type { LanguageProfile } from './types';
+
+export const vietnameseProfile: LanguageProfile = {
+  code: 'vi',
+  name: 'Vietnamese',
+  nativeName: 'Tiếng Việt',
+  direction: 'ltr',
+  wordOrder: 'SVO',
+  markingStrategy: 'preposition',
+  usesSpaces: true,
+  // Vietnamese uses base/dictionary form for commands
+  defaultVerbForm: 'base',
+  verb: {
+    position: 'start',
+    subjectDrop: true,
+  },
+  references: {
+    me: 'tôi', // "I/me"
+    it: 'nó', // "it"
+    you: 'bạn', // "you"
+    result: 'kết quả',
+    event: 'sự kiện',
+    target: 'mục tiêu',
+    body: 'body',
+  },
+  possessive: {
+    marker: 'của', // Vietnamese uses "của" for possession (của tôi = my)
+    markerPosition: 'between',
+    specialForms: {
+      me: 'của tôi', // "my"
+      it: 'của nó', // "its"
+      you: 'của bạn', // "your"
+    },
+    keywords: {
+      // Multi-word possessive phrases
+      // Note: These may require tokenizer support for multi-word recognition
+      'của tôi': 'me', // my
+      'của bạn': 'you', // your (informal)
+      'của anh': 'you', // your (male speaker, formal)
+      'của chị': 'you', // your (female speaker, formal)
+      'của nó': 'it', // its
+    },
+  },
+  roleMarkers: {
+    destination: { primary: 'vào', alternatives: ['cho', 'đến'], position: 'before' },
+    source: { primary: 'từ', alternatives: ['khỏi'], position: 'before' },
+    patient: { primary: '', position: 'before' },
+    style: { primary: 'với', position: 'before' },
+  },
+  keywords: {
+    // Class/Attribute operations
+    toggle: { primary: 'chuyển đổi', alternatives: ['bật tắt', 'chuyển'], normalized: 'toggle' },
+    add: { primary: 'thêm', alternatives: ['bổ sung'], normalized: 'add' },
+    remove: { primary: 'xóa', alternatives: ['gỡ bỏ', 'loại bỏ', 'bỏ'], normalized: 'remove' },
+    // Content operations
+    put: { primary: 'đặt', alternatives: ['để', 'đưa'], normalized: 'put' },
+    append: { primary: 'nối', normalized: 'append' },
+    prepend: { primary: 'thêm vào đầu', normalized: 'prepend' },
+    take: { primary: 'lấy', normalized: 'take' },
+    make: { primary: 'tạo', normalized: 'make' },
+    clone: { primary: 'sao chép', normalized: 'clone' },
+    swap: { primary: 'hoán đổi', normalized: 'swap' },
+    morph: { primary: 'biến đổi', normalized: 'morph' },
+    // Variable operations
+    set: { primary: 'gán', alternatives: ['thiết lập', 'đặt'], normalized: 'set' },
+    get: { primary: 'lấy giá trị', alternatives: ['nhận', 'lấy'], normalized: 'get' },
+    increment: { primary: 'tăng', alternatives: ['tăng lên'], normalized: 'increment' },
+    decrement: { primary: 'giảm', alternatives: ['giảm đi'], normalized: 'decrement' },
+    log: { primary: 'in ra', normalized: 'log' },
+    // Visibility
+    show: { primary: 'hiển thị', alternatives: ['hiện'], normalized: 'show' },
+    hide: { primary: 'ẩn', alternatives: ['che', 'giấu'], normalized: 'hide' },
+    transition: { primary: 'chuyển tiếp', normalized: 'transition' },
+    // Events
+    on: { primary: 'khi', alternatives: ['lúc', 'trên'], normalized: 'on' },
+    trigger: { primary: 'kích hoạt', normalized: 'trigger' },
+    send: { primary: 'gửi', normalized: 'send' },
+    // DOM focus
+    focus: { primary: 'tập trung', normalized: 'focus' },
+    blur: { primary: 'mất tập trung', normalized: 'blur' },
+    // Navigation
+    go: { primary: 'đi đến', alternatives: ['đi'], normalized: 'go' },
+    // Async
+    wait: { primary: 'chờ', alternatives: ['đợi'], normalized: 'wait' },
+    fetch: { primary: 'tải', normalized: 'fetch' },
+    settle: { primary: 'ổn định', normalized: 'settle' },
+    // Control flow
+    if: { primary: 'nếu', normalized: 'if' },
+    when: { primary: 'khi', normalized: 'when' },
+    where: { primary: 'ở_đâu', normalized: 'where' },
+    else: { primary: 'không thì', alternatives: ['nếu không'], normalized: 'else' },
+    repeat: { primary: 'lặp lại', normalized: 'repeat' },
+    for: { primary: 'với mỗi', normalized: 'for' },
+    while: { primary: 'trong khi', normalized: 'while' },
+    continue: { primary: 'tiếp tục', normalized: 'continue' },
+    halt: { primary: 'dừng', alternatives: ['dừng lại'], normalized: 'halt' },
+    throw: { primary: 'ném', normalized: 'throw' },
+    call: { primary: 'gọi', normalized: 'call' },
+    return: { primary: 'trả về', normalized: 'return' },
+    then: { primary: 'rồi', alternatives: ['sau đó', 'thì'], normalized: 'then' },
+    and: { primary: 'và', normalized: 'and' },
+    end: { primary: 'kết thúc', normalized: 'end' },
+    // Advanced
+    js: { primary: 'js', normalized: 'js' },
+    async: { primary: 'bất đồng bộ', normalized: 'async' },
+    tell: { primary: 'nói với', normalized: 'tell' },
+    default: { primary: 'mặc định', normalized: 'default' },
+    init: { primary: 'khởi tạo', normalized: 'init' },
+    behavior: { primary: 'hành vi', normalized: 'behavior' },
+    install: { primary: 'cài đặt', normalized: 'install' },
+    measure: { primary: 'đo lường', normalized: 'measure' },
+    // Modifiers
+    into: { primary: 'vào', alternatives: ['vào trong'], normalized: 'into' },
+    before: { primary: 'trước', alternatives: ['trước khi'], normalized: 'before' },
+    after: { primary: 'sau', alternatives: ['sau khi'], normalized: 'after' },
+    // Event modifiers
+    until: { primary: 'cho đến khi', normalized: 'until' },
+    event: { primary: 'sự kiện', normalized: 'event' },
+    from: { primary: 'từ', alternatives: ['khỏi'], normalized: 'from' },
+  },
+  eventHandler: {
+    keyword: { primary: 'khi', alternatives: ['lúc', 'trên'], normalized: 'on' },
+    sourceMarker: { primary: 'trên', alternatives: ['tại'], position: 'before' },
+  },
+};

package/src/generators/schema-error-codes.ts

@@ -0,0 +1,160 @@
+/**
+ * Schema Error Codes
+ *
+ * Provides machine-readable error codes for schema validation.
+ * These codes enable LLMs and tooling to programmatically identify
+ * and respond to specific validation issues.
+ */
+
+import type { SemanticRole } from '../types';
+
+/**
+ * Severity levels for schema validation items.
+ */
+export type SchemaValidationSeverity = 'error' | 'warning' | 'note';
+
+/**
+ * A structured validation item with machine-readable code.
+ */
+export interface SchemaValidationItem {
+  /** Machine-readable error code */
+  code: string;
+  /** Human-readable message */
+  message: string;
+  /** Severity level */
+  severity: SchemaValidationSeverity;
+  /** Affected role, if applicable */
+  role?: SemanticRole;
+  /** Suggested fix */
+  suggestion?: string;
+}
+
+/**
+ * Schema error codes organized by category.
+ */
+export const SchemaErrorCodes = {
+  // Type ambiguity issues
+  AMBIGUOUS_TYPE_LITERAL_SELECTOR: 'SCHEMA_AMBIGUOUS_TYPE_LITERAL_SELECTOR',
+  TOO_MANY_EXPECTED_TYPES: 'SCHEMA_TOO_MANY_EXPECTED_TYPES',
+  MULTI_TYPE_PATIENT_EXPECTED: 'SCHEMA_MULTI_TYPE_PATIENT_EXPECTED',
+
+  // Role issues
+  NO_REQUIRED_ROLES: 'SCHEMA_NO_REQUIRED_ROLES',
+  NO_REQUIRED_ROLES_EXPECTED: 'SCHEMA_NO_REQUIRED_ROLES_EXPECTED',
+
+  // Transition command
+  TRANSITION_PATIENT_ACCEPTS_SELECTOR: 'SCHEMA_TRANSITION_PATIENT_ACCEPTS_SELECTOR',
+  TRANSITION_MISSING_GOAL: 'SCHEMA_TRANSITION_MISSING_GOAL',
+
+  // Event handler command
+  EVENT_HANDLER_MISSING_EVENT: 'SCHEMA_EVENT_HANDLER_MISSING_EVENT',
+  EVENT_HANDLER_EVENT_NOT_REQUIRED: 'SCHEMA_EVENT_HANDLER_EVENT_NOT_REQUIRED',
+
+  // Conditional commands
+  CONDITIONAL_MISSING_CONDITION: 'SCHEMA_CONDITIONAL_MISSING_CONDITION',
+  CONDITIONAL_CONDITION_NOT_REQUIRED: 'SCHEMA_CONDITIONAL_CONDITION_NOT_REQUIRED',
+
+  // Loop commands
+  FOR_LOOP_MISSING_SOURCE: 'SCHEMA_FOR_LOOP_MISSING_SOURCE',
+  WHILE_LOOP_MISSING_CONDITION: 'SCHEMA_WHILE_LOOP_MISSING_CONDITION',
+} as const;
+
+export type SchemaErrorCode = (typeof SchemaErrorCodes)[keyof typeof SchemaErrorCodes];
+
+/**
+ * Message templates for each error code.
+ * Use {role}, {command}, {count} placeholders for dynamic values.
+ */
+export const SchemaErrorMessages: Record<SchemaErrorCode, string> = {
+  // Type ambiguity
+  [SchemaErrorCodes.AMBIGUOUS_TYPE_LITERAL_SELECTOR]:
+    "Role '{role}' accepts both 'literal' and 'selector'. This may cause ambiguous type inference for values starting with special characters (* . # etc.).",
+  [SchemaErrorCodes.TOO_MANY_EXPECTED_TYPES]:
+    "Role '{role}' accepts {count} different types. This may make type inference unreliable.",
+  [SchemaErrorCodes.MULTI_TYPE_PATIENT_EXPECTED]:
+    "Role '{role}' accepts multiple types (expected for {command} command).",
+
+  // Role issues
+  [SchemaErrorCodes.NO_REQUIRED_ROLES]: 'Command has no required roles. Is this intentional?',
+  [SchemaErrorCodes.NO_REQUIRED_ROLES_EXPECTED]:
+    'Command has no required roles (expected for {command}).',
+
+  // Transition
+  [SchemaErrorCodes.TRANSITION_PATIENT_ACCEPTS_SELECTOR]:
+    "Transition command 'patient' role (CSS property name) should only accept 'literal', not 'selector'. CSS property names like 'background-color' are strings, not CSS selectors.",
+  [SchemaErrorCodes.TRANSITION_MISSING_GOAL]:
+    "Transition command requires a 'goal' role for the target value (to <value>). Without it, there's no way to specify what value to transition to.",
+
+  // Event handler
+  [SchemaErrorCodes.EVENT_HANDLER_MISSING_EVENT]:
+    "Event handler command should have an 'event' role to specify which event to listen for.",
+  [SchemaErrorCodes.EVENT_HANDLER_EVENT_NOT_REQUIRED]:
+    'Event role should be required - every event handler needs an event to listen for.',
+
+  // Conditionals
+  [SchemaErrorCodes.CONDITIONAL_MISSING_CONDITION]:
+    "Conditional command should have a 'condition' role for the boolean expression.",
+  [SchemaErrorCodes.CONDITIONAL_CONDITION_NOT_REQUIRED]:
+    'Condition role should be required - conditionals need a condition to evaluate.',
+
+  // Loops
+  [SchemaErrorCodes.FOR_LOOP_MISSING_SOURCE]:
+    "For-loop should have a 'source' role for the collection to iterate over.",
+  [SchemaErrorCodes.WHILE_LOOP_MISSING_CONDITION]:
+    "While-loop should have a 'condition' role for the loop condition.",
+};
+
+/**
+ * Suggested fixes for each error code.
+ */
+export const SchemaErrorSuggestions: Partial<Record<SchemaErrorCode, string>> = {
+  [SchemaErrorCodes.AMBIGUOUS_TYPE_LITERAL_SELECTOR]:
+    'Consider being more specific about which type is expected, or use explicit type markers.',
+  [SchemaErrorCodes.TOO_MANY_EXPECTED_TYPES]:
+    'Consider narrowing the accepted types to improve type inference reliability.',
+  [SchemaErrorCodes.TRANSITION_PATIENT_ACCEPTS_SELECTOR]:
+    "Remove 'selector' from expectedTypes and only accept 'literal'.",
+  [SchemaErrorCodes.TRANSITION_MISSING_GOAL]:
+    "Add a 'goal' role with expectedTypes ['literal', 'variable'].",
+  [SchemaErrorCodes.EVENT_HANDLER_MISSING_EVENT]:
+    "Add an 'event' role with expectedTypes ['literal'].",
+  [SchemaErrorCodes.EVENT_HANDLER_EVENT_NOT_REQUIRED]: "Set required: true on the 'event' role.",
+  [SchemaErrorCodes.CONDITIONAL_MISSING_CONDITION]:
+    "Add a 'condition' role with expectedTypes ['expression'].",
+  [SchemaErrorCodes.CONDITIONAL_CONDITION_NOT_REQUIRED]:
+    "Set required: true on the 'condition' role.",
+  [SchemaErrorCodes.FOR_LOOP_MISSING_SOURCE]:
+    "Add a 'source' role for the collection to iterate over.",
+  [SchemaErrorCodes.WHILE_LOOP_MISSING_CONDITION]:
+    "Add a 'condition' role for the loop continuation condition.",
+};
+
+/**
+ * Interpolate placeholders in a message template.
+ */
+function interpolate(template: string, params: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (_, key) => String(params[key] ?? `{${key}}`));
+}
+
+/**
+ * Create a schema validation item with proper interpolation.
+ */
+export function createSchemaValidationItem(
+  code: SchemaErrorCode,
+  severity: SchemaValidationSeverity,
+  params: Record<string, string | number> = {},
+  role?: SemanticRole
+): SchemaValidationItem {
+  const messageTemplate = SchemaErrorMessages[code];
+  const message = interpolate(messageTemplate, params);
+  const suggestionTemplate = SchemaErrorSuggestions[code];
+  const suggestion = suggestionTemplate ? interpolate(suggestionTemplate, params) : undefined;
+
+  return {
+    code,
+    message,
+    severity,
+    ...(role && { role }),
+    ...(suggestion && { suggestion }),
+  };
+}