@morphql/language-definitions 0.1.3

package/README.md

@@ -0,0 +1,146 @@
+# @morphql/language-definitions
+
+**Single source of truth** for MorphQL language definitions across all platforms.
+
+## Purpose
+
+This package centralizes all MorphQL language definitions (keywords, functions, operators, documentation) in TypeScript, eliminating duplication across:
+
+- VSCode extension
+- Monaco Editor (playground)
+- Documentation
+
+## Installation
+
+```bash
+npm install @morphql/language-definitions
+```
+
+## Usage
+
+### Get Language Data
+
+```typescript
+import {
+  KEYWORDS,
+  FUNCTIONS,
+  OPERATORS,
+  getKeywordNames,
+  getFunctionNames,
+  getOperatorSymbols,
+} from "@morphql/language-definitions";
+
+// Get all keyword names
+const keywords = getKeywordNames();
+// ['from', 'to', 'transform', 'set', ...]
+
+// Get all function names
+const functions = getFunctionNames();
+// ['substring', 'split', 'replace', ...]
+
+// Get documentation for a keyword
+import { getKeywordDoc } from "@morphql/language-definitions";
+const doc = getKeywordDoc("set");
+// { signature: 'set <target> = <expression>', description: '...', ... }
+```
+
+### Generate VSCode TextMate Grammar
+
+```typescript
+import { generateTextMateKeywordsPattern } from "@morphql/language-definitions";
+
+const keywordsPattern = generateTextMateKeywordsPattern();
+// Use in morphql.tmLanguage.json
+```
+
+### Generate Monaco Language Config
+
+```typescript
+import { generateMonacoLanguageConfig } from "@morphql/language-definitions";
+
+const monacoConfig = generateMonacoLanguageConfig();
+monaco.languages.register({ id: "morphql" });
+monaco.languages.setMonarchTokensProvider("morphql", monacoConfig);
+```
+
+### Generate Hover Documentation
+
+```typescript
+import { generateHoverDocs } from "@morphql/language-definitions";
+
+const { keywordDocs, functionDocs } = generateHoverDocs();
+// Use in VSCode HoverProvider or Monaco HoverProvider
+```
+
+## Adding New Language Features
+
+### 1. Add to This Package
+
+Edit the appropriate file:
+
+- **Keywords**: `src/keywords.ts`
+- **Functions**: `src/functions.ts`
+- **Operators**: `src/operators.ts`
+
+### 2. Update the Lexer
+
+Update `@morphql/core/src/core/lexer.ts` with the new token.
+
+### 3. Rebuild
+
+```bash
+npm run build
+```
+
+### 4. Update Consumers
+
+The VSCode extension and playground will automatically use the new definitions on their next build.
+
+## Structure
+
+```
+src/
+├── types.ts       # TypeScript interfaces
+├── keywords.ts    # Keyword definitions + docs
+├── functions.ts   # Function definitions + docs
+├── operators.ts   # Operator definitions
+└── index.ts       # Exports + generators
+```
+
+## Benefits
+
+✅ **Single source of truth** - Edit once, use everywhere  
+✅ **Type-safe** - Full TypeScript support  
+✅ **Auto-generated** - Configs generated from definitions  
+✅ **Consistent** - No more sync issues between platforms  
+✅ **Documented** - All definitions include documentation
+
+## Example: Adding a New Keyword
+
+```typescript
+// 1. Edit src/keywords.ts
+export const KEYWORDS: KeywordDef[] = [
+  // ... existing keywords ...
+  {
+    name: "loop",
+    category: "control",
+    doc: {
+      signature: "loop <count> ( <actions> )",
+      description: "Repeats actions a specified number of times.",
+      parameters: [
+        { name: "count", description: "Number of iterations" },
+        { name: "actions", description: "Actions to repeat" },
+      ],
+      example: "loop 5 (\n  set item = value\n)",
+    },
+  },
+];
+
+// 2. Update lexer in @morphql/core
+// 3. Rebuild this package: npm run build
+// 4. VSCode and Monaco will pick it up automatically!
+```
+
+## License
+
+MIT

package/export-json.ts

@@ -0,0 +1,107 @@
+import { MORPHQL_LANGUAGE } from "./src/index";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const distDir = path.resolve(__dirname, "dist");
+if (!fs.existsSync(distDir)) {
+  fs.mkdirSync(distDir, { recursive: true });
+}
+
+// 1. Export JSON
+const jsonPath = path.resolve(distDir, "morphql-lang.json");
+fs.writeFileSync(jsonPath, JSON.stringify(MORPHQL_LANGUAGE, null, 2));
+console.log(`Language definitions exported to ${jsonPath}`);
+
+// 2. Export Kotlin Constants
+const constantsPath = path.resolve(
+  __dirname,
+  "../jetbrains-extension/src/main/kotlin/org/morphql/jetbrains/MorphQLConstants.kt",
+);
+
+const keywords = MORPHQL_LANGUAGE.keywords.map((k) => k.name);
+const functions = MORPHQL_LANGUAGE.functions.map((f) => f.name);
+const operators = MORPHQL_LANGUAGE.operators.map((o) => o.symbol);
+
+const constantsContent = `package org.morphql.jetbrains
+
+/**
+ * GENERATED FILE - DO NOT EDIT MANUALLY
+ * Generated by packages/language-definitions/export-json.ts
+ */
+object MorphQLConstants {
+    val KEYWORDS = setOf(
+${keywords.map((k) => `        "${k}"`).join(",\n")}
+    )
+
+    val FUNCTIONS = setOf(
+${functions.map((f) => `        "${f}"`).join(",\n")}
+    )
+
+    val OPERATORS = setOf(
+${operators.map((o) => `        "${o}"`).join(",\n")}
+    )
+}
+`;
+
+if (fs.existsSync(path.dirname(constantsPath))) {
+  fs.writeFileSync(constantsPath, constantsContent);
+  console.log(`Kotlin constants exported to ${constantsPath}`);
+}
+
+// 3. Export Kotlin Documentation
+const docsPath = path.resolve(
+  __dirname,
+  "../jetbrains-extension/src/main/kotlin/org/morphql/jetbrains/MorphQLDocumentation.kt",
+);
+
+const allDocs: Record<string, any> = {};
+MORPHQL_LANGUAGE.keywords.forEach((k) => {
+  allDocs[k.name] = k.doc;
+});
+MORPHQL_LANGUAGE.functions.forEach((f) => {
+  allDocs[f.name] = f.doc;
+});
+
+const escapeQuotes = (str: string) =>
+  str.replace(/"/g, '\\"').replace(/\n/g, "\\n");
+
+const docsEntries = Object.entries(allDocs)
+  .map(([name, doc]) => {
+    return `        "${name}" to """
+            <b>${doc.signature}</b><br/>
+            ${doc.description}<br/><br/>
+            ${
+              doc.parameters && doc.parameters.length > 0
+                ? `<b>Parameters:</b><ul>${doc.parameters
+                    .map(
+                      (p: any) => `<li><b>${p.name}:</b> ${p.description}</li>`,
+                    )
+                    .join("")}</ul>`
+                : ""
+            }
+            ${doc.example ? `<b>Example:</b><pre>${doc.example}</pre>` : ""}
+        """.trimIndent()`;
+  })
+  .join(",\n");
+
+const docsContent = `package org.morphql.jetbrains
+
+/**
+ * GENERATED FILE - DO NOT EDIT MANUALLY
+ * Generated by packages/language-definitions/export-json.ts
+ */
+object MorphQLDocumentation {
+    val DOCS = mapOf(
+${docsEntries}
+    )
+}
+`;
+
+if (fs.existsSync(path.dirname(docsPath))) {
+  fs.writeFileSync(docsPath, docsContent);
+  console.log(`Kotlin documentation exported to ${docsPath}`);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@morphql/language-definitions",
+  "version": "0.1.3",
+  "description": "Shared language definitions for MorphQL across VSCode, Monaco, and documentation",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean && npm run export-json",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "export-json": "tsx export-json.ts"
+  },
+  "keywords": [
+    "morphql",
+    "language",
+    "definitions",
+    "vscode",
+    "monaco"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/functions.ts

@@ -0,0 +1,170 @@
+import { FunctionDef } from "./types";
+
+/**
+ * MorphQL Functions - Single source of truth
+ *
+ * When adding a new function:
+ * 1. Add it here
+ * 2. Implement in @morphql/core/src/functions.ts
+ * 3. Run build to regenerate VSCode/Monaco configs
+ */
+export const FUNCTIONS: FunctionDef[] = [
+  {
+    name: "substring",
+    doc: {
+      signature: "substring(str, start, [length])",
+      description: "Extracts a portion of a string. Supports negative indices.",
+      parameters: [
+        { name: "str", description: "The source string" },
+        {
+          name: "start",
+          description: "Starting index (0-based, negative counts from end)",
+        },
+        {
+          name: "length",
+          description: "(Optional) Number of characters to extract",
+        },
+      ],
+      returns: "string",
+      example:
+        'substring("Hello World", 0, 5)  // "Hello"\nsubstring("Hello World", -5)     // "World"',
+    },
+  },
+  {
+    name: "split",
+    doc: {
+      signature: "split(str, [separator], [limit])",
+      description: "Splits a string into an array.",
+      parameters: [
+        { name: "str", description: "The string to split" },
+        {
+          name: "separator",
+          description: '(Optional) Delimiter string. Default: ""',
+        },
+        { name: "limit", description: "(Optional) Maximum number of splits" },
+      ],
+      returns: "array",
+      example: 'split("a,b,c", ",")  // ["a", "b", "c"]',
+    },
+  },
+  {
+    name: "replace",
+    doc: {
+      signature: "replace(str, search, replacement)",
+      description: "Replaces occurrences in a string.",
+      parameters: [
+        { name: "str", description: "The source string" },
+        { name: "search", description: "The substring to find" },
+        { name: "replacement", description: "The replacement string" },
+      ],
+      returns: "string",
+      example: 'replace("Hello World", "World", "MorphQL")  // "Hello MorphQL"',
+    },
+  },
+  {
+    name: "text",
+    doc: {
+      signature: "text(value)",
+      description: "Converts a value to a string.",
+      parameters: [{ name: "value", description: "The value to convert" }],
+      returns: "string",
+      example: 'text(123)  // "123"',
+    },
+  },
+  {
+    name: "number",
+    doc: {
+      signature: "number(value)",
+      description: "Converts a value to a number.",
+      parameters: [{ name: "value", description: "The value to convert" }],
+      returns: "number",
+      example: 'number("42")  // 42',
+    },
+  },
+  {
+    name: "uppercase",
+    doc: {
+      signature: "uppercase(str)",
+      description: "Converts a string to uppercase.",
+      parameters: [{ name: "str", description: "The string to convert" }],
+      returns: "string",
+      example: 'uppercase("hello")  // "HELLO"',
+    },
+  },
+  {
+    name: "lowercase",
+    doc: {
+      signature: "lowercase(str)",
+      description: "Converts a string to lowercase.",
+      parameters: [{ name: "str", description: "The string to convert" }],
+      returns: "string",
+      example: 'lowercase("HELLO")  // "hello"',
+    },
+  },
+  {
+    name: "extractnumber",
+    doc: {
+      signature: "extractnumber(str)",
+      description: "Extracts the first numeric sequence from a string.",
+      parameters: [{ name: "str", description: "The string to extract from" }],
+      returns: "number",
+      example: 'extractnumber("Price: 100USD")  // 100',
+    },
+  },
+  {
+    name: "xmlnode",
+    doc: {
+      signature: "xmlnode(value, [attrKey, attrVal, ...])",
+      description: "Wraps a value for XML output with optional attributes.",
+      parameters: [
+        { name: "value", description: "The node content" },
+        {
+          name: "attrKey, attrVal",
+          description: "(Optional) Pairs of attribute keys and values",
+        },
+      ],
+      returns: "XML node",
+      example: 'xmlnode(content, "id", 1, "type", "text")',
+    },
+  },
+  {
+    name: "to_base64",
+    doc: {
+      signature: "to_base64(value)",
+      description: "Encodes a string value to Base64.",
+      parameters: [{ name: "value", description: "The string to encode" }],
+      returns: "string",
+      example: 'to_base64("hello")  // "aGVsbG8="',
+    },
+  },
+  {
+    name: "from_base64",
+    doc: {
+      signature: "from_base64(value)",
+      description: "Decodes a Base64 string value.",
+      parameters: [
+        { name: "value", description: "The Base64 string to decode" },
+      ],
+      returns: "string",
+      example: 'from_base64("aGVsbG8=")  // "hello"',
+    },
+  },
+  {
+    name: "aslist",
+    doc: {
+      signature: "aslist(value)",
+      description:
+        "Ensures a value is an array. Useful for XML nodes that might be a single object or an array.",
+      parameters: [{ name: "value", description: "The value to normalize" }],
+      returns: "array",
+      example: "aslist(items)  // Always returns an array",
+    },
+  },
+];
+
+// Helper to get all function names
+export const getFunctionNames = () => FUNCTIONS.map((f) => f.name);
+
+// Helper to get function documentation
+export const getFunctionDoc = (name: string) =>
+  FUNCTIONS.find((f) => f.name.toLowerCase() === name.toLowerCase())?.doc;

package/src/index.ts

@@ -0,0 +1,202 @@
+import {
+  KEYWORDS,
+  getKeywordNames,
+  getKeywordsByCategory,
+  getKeywordDoc,
+} from "./keywords";
+import { FUNCTIONS, getFunctionNames, getFunctionDoc } from "./functions";
+import {
+  OPERATORS,
+  getOperatorsByCategory,
+  getOperatorSymbols,
+  getMultiCharOperators,
+  getSingleCharOperators,
+} from "./operators";
+import type {
+  LanguageDefinition,
+  KeywordDef,
+  FunctionDef,
+  OperatorDef,
+  DocEntry,
+} from "./types";
+
+/**
+ * Complete MorphQL language definition
+ */
+export const MORPHQL_LANGUAGE: LanguageDefinition = {
+  keywords: KEYWORDS,
+  functions: FUNCTIONS,
+  operators: OPERATORS,
+  comments: {
+    line: "//",
+    blockStart: "/*",
+    blockEnd: "*/",
+  },
+};
+
+// Re-export everything
+export {
+  // Data
+  KEYWORDS,
+  FUNCTIONS,
+  OPERATORS,
+
+  // Helpers
+  getKeywordNames,
+  getKeywordsByCategory,
+  getKeywordDoc,
+  getFunctionNames,
+  getFunctionDoc,
+  getOperatorsByCategory,
+  getOperatorSymbols,
+  getMultiCharOperators,
+  getSingleCharOperators,
+
+  // Types
+  type LanguageDefinition,
+  type KeywordDef,
+  type FunctionDef,
+  type OperatorDef,
+  type DocEntry,
+};
+
+/**
+ * Generators for different platforms
+ */
+
+/**
+ * Generate TextMate grammar keywords pattern
+ */
+export function generateTextMateKeywordsPattern(): string {
+  const controlKeywords = getKeywordsByCategory("control").map((k) => k.name);
+  const actionKeywords = getKeywordsByCategory("action").map((k) => k.name);
+
+  return JSON.stringify(
+    {
+      patterns: [
+        {
+          name: "keyword.control.morphql",
+          match: `\\b(${controlKeywords.join("|")})\\b`,
+        },
+        {
+          name: "keyword.other.morphql",
+          match: `\\b(${actionKeywords.join("|")})\\b`,
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * Generate TextMate grammar functions pattern
+ */
+export function generateTextMateFunctionsPattern(): string {
+  const functionNames = getFunctionNames();
+
+  return JSON.stringify(
+    {
+      patterns: [
+        {
+          name: "entity.name.function.morphql",
+          match: `\\b(${functionNames.join("|")})(?=\\s*\\()`,
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+/**
+ * Generate Monaco language configuration
+ */
+export function generateMonacoLanguageConfig() {
+  return {
+    keywords: getKeywordNames(),
+    builtinFunctions: getFunctionNames(),
+    operators: getOperatorSymbols(),
+    symbols: /[=><!~?:&|+\-*\/\^%]+/,
+    escapes:
+      /\\(?:[abfnrtv\\"']|x[0-9A-Fa-f]{1,4}|u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8})/,
+
+    tokenizer: {
+      root: [
+        // Comments
+        [/\/\/.*$/, "comment"],
+        [/\/\*/, "comment", "@comment"],
+
+        // Keywords
+        [
+          /[a-zA-Z_$][\w$]*/,
+          {
+            cases: {
+              "@keywords": "keyword",
+              "@builtinFunctions": "predefined",
+              "@default": "identifier",
+            },
+          },
+        ],
+
+        // Strings
+        [/"([^"\\]|\\.)*$/, "string.invalid"],
+        [/'([^'\\]|\\.)*$/, "string.invalid"],
+        [/"/, "string", "@string_double"],
+        [/'/, "string", "@string_single"],
+
+        // Numbers
+        [/-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/, "number"],
+
+        // Operators
+        [/[{}()\[\]]/, "@brackets"],
+        [
+          /@symbols/,
+          {
+            cases: {
+              "@operators": "operator",
+              "@default": "",
+            },
+          },
+        ],
+      ],
+
+      comment: [
+        [/[^\/*]+/, "comment"],
+        [/\*\//, "comment", "@pop"],
+        [/[\/*]/, "comment"],
+      ],
+
+      string_double: [
+        [/[^\\"]+/, "string"],
+        [/@escapes/, "string.escape"],
+        [/\\./, "string.escape.invalid"],
+        [/"/, "string", "@pop"],
+      ],
+
+      string_single: [
+        [/[^\\']+/, "string"],
+        [/@escapes/, "string.escape"],
+        [/\\./, "string.escape.invalid"],
+        [/'/, "string", "@pop"],
+      ],
+    },
+  };
+}
+
+/**
+ * Generate hover documentation map for VSCode
+ */
+export function generateHoverDocs() {
+  const keywordDocs: Record<string, DocEntry> = {};
+  KEYWORDS.forEach((k) => {
+    keywordDocs[k.name] = k.doc;
+  });
+
+  const functionDocs: Record<string, DocEntry> = {};
+  FUNCTIONS.forEach((f) => {
+    functionDocs[f.name] = f.doc;
+  });
+
+  return { keywordDocs, functionDocs };
+}

package/src/keywords.ts

@@ -0,0 +1,196 @@
+import { KeywordDef } from "./types";
+
+/**
+ * MorphQL Keywords - Single source of truth
+ *
+ * When adding a new keyword:
+ * 1. Add it here
+ * 2. Update the lexer in @morphql/core
+ * 3. Run build to regenerate VSCode/Monaco configs
+ */
+export const KEYWORDS: KeywordDef[] = [
+  {
+    name: "from",
+    category: "control",
+    doc: {
+      signature: "from <format>",
+      description: "Specifies the input data format.",
+      parameters: [
+        {
+          name: "format",
+          description:
+            "If used as first keyword: The starting format, one of `json`, `xml`, or `object`. When used after a section, defines its source",
+        },
+      ],
+      example: "from json to xml",
+    },
+  },
+  {
+    name: "to",
+    category: "control",
+    doc: {
+      signature: "to <format>",
+      description: "Specifies the output data format.",
+      parameters: [
+        { name: "format", description: "One of: `json`, `xml`, or `object`" },
+      ],
+      example: "from json to xml",
+    },
+  },
+  {
+    name: "transform",
+    category: "control",
+    doc: {
+      signature: "transform",
+      description: "Begins the transformation block containing actions.",
+      example: "transform\n  set name = firstName",
+    },
+  },
+  {
+    name: "set",
+    category: "action",
+    doc: {
+      signature: "set <target> = <expression>",
+      description: "Assigns a value to a field in the output.",
+      parameters: [
+        { name: "target", description: "The field name to set" },
+        {
+          name: "expression",
+          description: "The value or expression to assign",
+        },
+      ],
+      example: 'set fullName = firstName + " " + lastName',
+    },
+  },
+  {
+    name: "section",
+    category: "action",
+    doc: {
+      signature:
+        "section [multiple] <name>( [subquery] <actions> ) [from <path>]",
+      description:
+        "Creates a nested object or array in the output. Can optionally include a subquery for format conversion.",
+      parameters: [
+        { name: "multiple", description: "(Optional) Treat as array mapping" },
+        { name: "name", description: "The section/field name" },
+        {
+          name: "subquery",
+          description:
+            "(Optional) Nested query: from <format> to <format> [transform]",
+        },
+        {
+          name: "actions",
+          description: "Actions to perform within the section",
+        },
+        {
+          name: "from",
+          description: "(Optional) Source path for the section data",
+        },
+      ],
+      example:
+        "section metadata(\n  from xml to object\n  transform\n    set name = root.productName\n) from xmlString",
+    },
+  },
+  {
+    name: "multiple",
+    category: "action",
+    doc: {
+      signature: "section multiple <name>(...)",
+      description: "Modifier for `section` to map over an array.",
+      example: "section multiple items(\n  set id = itemId\n) from products",
+    },
+  },
+  {
+    name: "clone",
+    category: "action",
+    doc: {
+      signature: "clone([field1, field2, ...])",
+      description: "Copies fields from the source to the output.",
+      parameters: [
+        {
+          name: "fields",
+          description:
+            "(Optional) Specific fields to clone. If omitted, clones all fields.",
+        },
+      ],
+      example: "clone(id, name, email)",
+    },
+  },
+  {
+    name: "delete",
+    category: "action",
+    doc: {
+      signature: "delete <field>",
+      description: "Removes a field from the output (useful after `clone`).",
+      parameters: [{ name: "field", description: "The field name to delete" }],
+      example: "clone()\ndelete password",
+    },
+  },
+  {
+    name: "define",
+    category: "action",
+    doc: {
+      signature: "define <alias> = <expression>",
+      description:
+        "Creates a local variable/alias for use in subsequent expressions.",
+      parameters: [
+        { name: "alias", description: "The variable name" },
+        { name: "expression", description: "The value to assign" },
+      ],
+      example:
+        "define taxRate = 0.22\nset totalWithTax = total * (1 + taxRate)",
+    },
+  },
+  {
+    name: "if",
+    category: "control",
+    doc: {
+      signature: "if (condition) ( actions ) [else ( actions )]",
+      description: "Conditional execution of action blocks.",
+      parameters: [
+        { name: "condition", description: "Boolean expression" },
+        { name: "actions", description: "Actions to execute if true/false" },
+      ],
+      example:
+        'if (age >= 18) (\n  set status = "adult"\n) else (\n  set status = "minor"\n)',
+    },
+  },
+  {
+    name: "else",
+    category: "control",
+    doc: {
+      signature: "else ( actions )",
+      description: "Defines the else branch of an `if` statement.",
+      example: "if (condition) (\n  ...\n) else (\n  ...\n)",
+    },
+  },
+  {
+    name: "modify",
+    category: "action",
+    doc: {
+      signature: "modify <target> = <expression>",
+      description:
+        "Modifies a field in the output by reading from the target (not source). Useful for post-processing already-mapped values.",
+      parameters: [
+        { name: "target", description: "The field name to modify" },
+        {
+          name: "expression",
+          description:
+            "The expression to assign (reads from target, not source)",
+        },
+      ],
+      example: "set total = price * quantity\nmodify total = total * 1.10",
+    },
+  },
+];
+
+// Helper to get keywords by category
+export const getKeywordsByCategory = (category: "control" | "action") =>
+  KEYWORDS.filter((k) => k.category === category);
+
+// Helper to get all keyword names
+export const getKeywordNames = () => KEYWORDS.map((k) => k.name);
+
+// Helper to get keyword documentation
+export const getKeywordDoc = (name: string) =>
+  KEYWORDS.find((k) => k.name.toLowerCase() === name.toLowerCase())?.doc;

package/src/operators.ts

@@ -0,0 +1,50 @@
+import { OperatorDef } from "./types";
+
+/**
+ * MorphQL Operators - Single source of truth
+ *
+ * When adding a new operator:
+ * 1. Add it here
+ * 2. Update the lexer in @morphql/core (MIND THE ORDER!)
+ * 3. Run build to regenerate VSCode/Monaco configs
+ */
+export const OPERATORS: OperatorDef[] = [
+  // Comparison operators
+  { symbol: "===", category: "comparison", precedence: 7 },
+  { symbol: "!==", category: "comparison", precedence: 7 },
+  { symbol: "==", category: "comparison", precedence: 7 },
+  { symbol: "!=", category: "comparison", precedence: 7 },
+  { symbol: "<=", category: "comparison", precedence: 6 },
+  { symbol: ">=", category: "comparison", precedence: 6 },
+  { symbol: "<", category: "comparison", precedence: 6 },
+  { symbol: ">", category: "comparison", precedence: 6 },
+
+  // Logical operators
+  { symbol: "&&", category: "logical", precedence: 5 },
+  { symbol: "||", category: "logical", precedence: 4 },
+  { symbol: "!", category: "logical", precedence: 9 },
+
+  // Arithmetic operators
+  { symbol: "+", category: "arithmetic", precedence: 10 },
+  { symbol: "-", category: "arithmetic", precedence: 10 },
+  { symbol: "*", category: "arithmetic", precedence: 11 },
+  { symbol: "/", category: "arithmetic", precedence: 11 },
+
+  // Assignment
+  { symbol: "=", category: "assignment", precedence: 1 },
+];
+
+// Helper to get operators by category
+export const getOperatorsByCategory = (category: OperatorDef["category"]) =>
+  OPERATORS.filter((op) => op.category === category);
+
+// Helper to get all operator symbols
+export const getOperatorSymbols = () => OPERATORS.map((op) => op.symbol);
+
+// Helper to get multi-character operators (for lexer ordering)
+export const getMultiCharOperators = () =>
+  OPERATORS.filter((op) => op.symbol.length > 1).map((op) => op.symbol);
+
+// Helper to get single-character operators
+export const getSingleCharOperators = () =>
+  OPERATORS.filter((op) => op.symbol.length === 1).map((op) => op.symbol);

package/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Documentation entry for a keyword or function
+ */
+export interface DocEntry {
+  signature: string;
+  description: string;
+  parameters?: { name: string; description: string }[];
+  returns?: string;
+  example?: string;
+  category?: "control" | "action" | "function" | "operator";
+}
+
+/**
+ * Keyword definition
+ */
+export interface KeywordDef {
+  name: string;
+  category: "control" | "action";
+  doc: DocEntry;
+}
+
+/**
+ * Function definition
+ */
+export interface FunctionDef {
+  name: string;
+  doc: DocEntry;
+}
+
+/**
+ * Operator definition
+ */
+export interface OperatorDef {
+  symbol: string;
+  category: "arithmetic" | "comparison" | "logical" | "assignment";
+  precedence?: number;
+}
+
+/**
+ * Complete language definition
+ */
+export interface LanguageDefinition {
+  keywords: KeywordDef[];
+  functions: FunctionDef[];
+  operators: OperatorDef[];
+  comments: {
+    line: string;
+    blockStart: string;
+    blockEnd: string;
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}