@ezetgalaxy/cxr 1.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, Ezet Galaxy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+
+# CXR - Email Rule eXecutor
+
+**CXR** is a production-ready, open-source rule engine / compiler for email filtering logic, written in JavaScript (Node.js, ESM).
+It parses a custom `.cxr` domain language and executes deterministically against normalized email objects.
+
+## Features
+
+- **Safe**: No `eval`, no `Function`, purely AST-based execution.
+- **Deterministic**: Input -> Output is always the same.
+- **Explainable**: Returns metadata and logs of all actions taken.
+- **Extensible**: Pure JSON output format.
+- **Zero Dependencies**: Lightweight and fast.
+- **Flexible Loading**: Load rules from strings, files (`.cxr`), or combine multiple sources.
+
+## Installation
+
+```bash
+npm install @ezetgalaxy/cxr
+```
+
+## Usage
+
+```javascript
+import cxr from "@ezetgalaxy/cxr";
+
+// 1. Prepare email objects
+const emails = [
+    {
+        id: "1",
+        from: "notifications@github.com",
+        subject: "New login from Chrome",
+        body: "...",
+        unread: true,
+        receivedAt: Date.now()
+    }
+];
+
+// 2. Execute using file path
+const result = cxr.init({
+    rules: "./rules/alerts.cxr", // Path to .cxr file
+    emails
+});
+
+// Or combine multiple files/strings
+const resultCombined = cxr.init({
+    rules: [
+        "./rules/alerts.cxr", 
+        "./rules/personal.cxr",
+        `Folder Temporary WHEN subject contains "urgent" THEN notify`
+    ],
+    emails
+});
+
+
+console.log("Folders:", result.folders);
+console.log("Actions Log:", result.actionsLog);
+```
+
+## Output Example
+
+The `result` object is pure JSON, making it easy to consume:
+
+```json
+{
+  "folders": {
+    "Inbox": [],
+    "Alerts": [
+      {
+        "id": "1",
+        "from": "notifications@github.com",
+        "subject": "New login from Chrome",
+        "unread": true
+      }
+    ]
+  },
+  "actionsLog": [
+    {
+      "emailId": "1",
+      "folder": "Alerts",
+      "actions": ["move to Alerts", "notify", "mark as unread"]
+    }
+  ],
+  "meta": {
+    "engine": "cxr",
+    "version": "1.0.0",
+    "processedAt": 1700000000000,
+    "ruleCount": 5,
+    "emailCount": 1
+  }
+}
+```
+
+## UI Integration Example (React)
+
+Because CXR returns structured data, building a UI is straightforward.
+
+```jsx
+import React from 'react';
+import cxr from 'cxr';
+
+function EmailClient({ rules, rawEmails }) {
+  // 1. Run the engine
+  const { folders } = cxr.init({ rules, emails: rawEmails });
+
+  return (
+    <div className="email-client">
+      {Object.entries(folders).map(([folderName, emails]) => (
+        <div key={folderName} className="folder">
+          <h3>📂 {folderName} <span className="count">({emails.length})</span></h3>
+          
+          <ul className="email-list">
+            {emails.map(email => (
+              <li key={email.id} className={email.unread ? 'unread' : ''}>
+                <span className="sender">{email.from}</span>
+                <span className="subject">{email.subject}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+
+## Language Syntax
+
+See [GRAMMAR.md](./grammar.md) for full specification.
+
+### File Extension
+
+```
+.cxr
+```
+
+### Example Rule File (`alerts.cxr`)
+
+```
+Folder Alerts
+
+WHEN sender contains "github"
+OR subject contains "login"
+AND NOT sender contains "newsletter"
+
+THEN move to Alerts
+AND notify
+AND mark as unread
+
+Folder Personal
+
+WHEN sender IN ["mom@family.com", "dad@family.com"]
+THEN move to Personal
+AND mark as read
+```
+
+## API
+
+### `cxr.init(config)`
+
+- `config.rules` (string | string[]): 
+    - A string containing rule content.
+    - A string containing a file path (must end in `.cxr`).
+    - An array of strings (content or file paths).
+
+- `config.emails` (Array): List of email objects.
+    - Each email must have: `id`, `from`, `subject`, `body`, `unread`, `receivedAt` (by default).
+- `config.schema` (Object, optional): Custom field mapping.
+    - Maps rule field names (e.g., `sender`) to your email object keys (e.g., `from_address`).
+    - Default: `{ sender: 'from', subject: 'subject', body: 'body' }`
+
+### Custom Schema Example
+
+If your email objects look different, you can map the fields:
+
+```javascript
+/* Email Object:
+{
+  id: '1',
+  author: 'admin@site.com', // Instead of 'from'
+  content: 'Text...',       // Instead of 'body'
+  'X-Priority': 'High'      // Custom header
+}
+*/
+
+/* Rule:
+Folder Urgent
+WHEN priority contains "High" AND sender contains "admin"
+THEN move to Urgent
+*/
+
+cxr.init({
+  rules: rules,
+  emails: myEmails,
+  schema: {
+    sender: 'author',
+    body:   'content',
+    priority: 'X-Priority'
+  }
+});
+```
+
+
+Returns an object with:
+- `folders`: Mapping of folder names to arrays of matched emails.
+
+- `actionsLog`: Array of action records per email.
+- `meta`: Execution metadata (engine name: "cxr").
+
+## VS Code Extension
+
+Included in this repository is a VS Code extension for `.cxr` files.
+
+**Features:**
+- Syntax Highlighting for Keywords, Actions, and Fields.
+- Autocomplete / IntelliSense for rule structures.
+- Snippets for quick rule creation.
+
+
+**Installation (Manual):**
+1.  **Download**: Get the `cxr-language-support-0.0.1.vsix` file from this repository.
+2.  **Open VS Code / Cursor**:
+    - Go to the **Extensions View** (Ctrl+Shift+X).
+    - Click the **... (More Actions)** menu (top right of the pane).
+    - Select **Install from VSIX...**.
+3.  **Select File**: Choose the `.vsix` file you downloaded.
+4.  **Restart**: Reload the window to activate full support.
+
+*Note: This extension is not yet published to the Visual Studio Marketplace so it will not appear in search results.*
+
+
+## License
+
+ISC

package/grammar.md

@@ -0,0 +1,150 @@
+
+# CXR Grammar Specification
+
+This document defines the formal grammar and syntax for the `.cxr` file format.
+
+## Language Overview
+
+A `.cxr` file consists of one or more **Folder** definitions. Each folder contains a set of **Rules** that determine which emails should be sorted into that folder.
+
+The engine evaluates rules from top to bottom. The **first matching folder wins**.
+
+---
+
+## Basic Structure
+
+```
+Folder <FolderName>
+
+WHEN <Condition>
+THEN <Actions>
+```
+
+### Example
+
+```text
+Folder "Important"
+
+WHEN sender contains "boss"
+THEN move to "Important"
+AND notify
+```
+
+---
+
+## 1. Folder Definition
+
+Every rule block must start with a `Folder` declaration.
+
+- **Syntax**: `Folder <Name>`
+- **Name**: Can be a simple word (`Alerts`) or a quoted string (`"My Alerts"`).
+
+```text
+Folder Personal
+Folder "Work Projects"
+```
+
+---
+
+## 2. Conditions (`WHEN`)
+
+The `WHEN` clause defines the logic for matching an email.
+
+### Fields
+- `sender`: The email address of the sender (mapped to `from`).
+- `subject`: The subject line.
+- `body`: The email body content.
+
+### Operators
+- `contains`: Checks if the field contains a substring (case-insensitive).
+- `IN`: Checks if the field matches any value in a list.
+
+### Examples
+
+**Simple Match:**
+```text
+WHEN subject contains "urgent"
+```
+
+**List Match:**
+```text
+WHEN sender IN ["mom@family.com", "dad@family.com"]
+```
+
+**Logical Operators:**
+- `AND`: Both conditions must be true.
+- `OR`: At least one condition must be true.
+- `NOT`: The condition must be false.
+
+**Complex Logic:**
+```text
+WHEN (sender contains "github" OR subject contains "login")
+AND NOT sender contains "newsletter"
+```
+
+*Note: You can use parentheses `()` to group logic.*
+
+---
+
+## 3. Actions (`THEN`)
+
+The `THEN` clause defines what happens when a rule matches. Multiple actions can be chained with `AND`.
+
+### Supported Actions
+
+| Action | Description |
+| :--- | :--- |
+| `move to <Folder>` | Sorts the email into the specified folder. |
+| `remove from <Folder>` | (Metadata) Indicates removal from a source folder. |
+| `notify` | Flags the email for a notification. |
+| `call` | Flags the email for a phone call alert. |
+| `remind` | Sets a reminder flag. |
+| `mark as read` | Marks the email as read. |
+| `mark as unread` | Marks the email as unread. |
+| `auto` | Generic automation flag. |
+
+### Example
+
+```text
+THEN move to "Finance"
+AND notify
+AND mark as read
+```
+
+---
+
+## Formal EBNF Grammar
+
+For parser implementers, here is the Extended Backus-Naur Form (EBNF) grammar:
+
+```ebnf
+program         = { folder_block } ;
+folder_block    = "Folder" , identifier , { rule } ;
+rule            = "WHEN" , condition_expr , "THEN" , action_list ;
+
+condition_expr  = or_term ;
+or_term         = and_term , { "OR" , and_term } ;
+and_term        = not_factor , { "AND" , not_factor } ;
+not_factor      = [ "NOT" ] , factor ;
+factor          = "(" , condition_expr , ")" | predicate ;
+
+predicate       = field , op_contains , string_literal
+                | field , "IN" , ( string_literal | string_list ) ;
+
+field           = "sender" | "subject" | "body" ;
+op_contains     = "contains" ;
+
+action_list     = action , { "AND" , action } ;
+action          = "move to" , identifier
+                | "remove from" , identifier
+                | "notify"
+                | "call"
+                | "remind"
+                | "mark as read"
+                | "mark as unread"
+                | "auto" ;
+
+identifier      = ? alphanumeric string or quoted string ? ;
+string_literal  = '"' , { ? characters ? } , '"' ;
+string_list     = "[" , string_literal , { "," , string_literal } , "]" ;
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ezetgalaxy/cxr",
+  "version": "1.1.0",
+  "description": "CXR - Email Rule eXecutor. A safe, deterministic, and explainable rule engine for email filtering.",
+  "type": "module",
+  "publisher": "ezetgalaxy",
+  "author": "Ezet Galaxy",
+  "main": "src/index.js",
+  "exports": "./src/index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "email",
+    "rule-engine",
+    "compiler",
+    "automation",
+    "filtering",
+    "cxr"
+  ],
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/executor.js

@@ -0,0 +1,159 @@
+
+import { Parser } from './parser.js';
+import { Lexer } from './lexer.js';
+
+export class Executor {
+    constructor() {
+    }
+
+
+    static execute(rulesContent, emails, schema = {}) {
+        // 1. Lex & Parse
+        const lexer = new Lexer(rulesContent);
+        const tokens = lexer.tokenize();
+        const parser = new Parser(tokens);
+        const ast = parser.parse();
+
+        // 2. Prepare Output Structures
+        const folders = {
+            Inbox: []
+        };
+        const actionsLog = [];
+        let ruleCount = 0;
+
+        // Initialize folder buckets
+        for (const folder of ast.folders) {
+            // Ensure folder buckets exist, even if empty
+            if (!folders[folder.name]) {
+                folders[folder.name] = [];
+            }
+            ruleCount += folder.rules.length;
+        }
+
+        const customSchema = {
+            sender: 'from',
+            subject: 'subject',
+            body: 'body',
+            ...schema
+        };
+
+        // 3. Process Emails
+        for (const email of emails) {
+            let matched = false;
+            let targetFolder = 'Inbox';
+            let emailActions = [];
+            let matchedFolderName = null;
+
+            // Iterate Folders
+            for (const folder of ast.folders) {
+                // Iterate Rules in Folder
+                for (const rule of folder.rules) {
+                    if (Executor.evaluateCondition(rule.condition, email, customSchema)) {
+                        matched = true;
+                        matchedFolderName = folder.name;
+
+                        // Execute Actions
+                        for (const actionNode of rule.actions) {
+                            if (actionNode.action === 'move') {
+                                targetFolder = actionNode.target;
+                            }
+                            // Add to log
+                            emailActions.push(Executor.serializeAction(actionNode));
+                        }
+                        break; // Stop checking rules in this folder
+                    }
+                }
+                if (matched) break; // Stop checking other folders (First matching folder wins)
+            }
+
+            // Assign to bucket
+            if (!folders[targetFolder]) {
+                folders[targetFolder] = [];
+            }
+            folders[targetFolder].push(email);
+
+            // Log actions if matched
+            if (matched) {
+                actionsLog.push({
+                    emailId: email.id,
+                    folder: matchedFolderName,
+                    actions: emailActions
+                });
+            }
+        }
+
+        return {
+            folders,
+            actionsLog,
+            meta: {
+                engine: "cxr",
+                version: "1.0.0",
+                processedAt: Date.now(),
+                ruleCount,
+                emailCount: emails.length
+            }
+        };
+    }
+
+    static evaluateCondition(node, email, schema) {
+        switch (node.type) {
+            case 'BinaryExpression':
+                if (node.operator === 'AND') {
+                    return Executor.evaluateCondition(node.left, email, schema) && Executor.evaluateCondition(node.right, email, schema);
+                } else if (node.operator === 'OR') {
+                    return Executor.evaluateCondition(node.left, email, schema) || Executor.evaluateCondition(node.right, email, schema);
+                }
+                throw new Error(`Unknown binary operator: ${node.operator}`);
+
+            case 'UnaryExpression':
+                if (node.operator === 'NOT') {
+                    return !Executor.evaluateCondition(node.argument, email, schema);
+                }
+                throw new Error(`Unknown unary operator: ${node.operator}`);
+
+            case 'Predicate':
+                return Executor.evaluatePredicate(node, email, schema);
+
+            case 'InPredicate':
+                return Executor.evaluateInPredicate(node, email, schema);
+
+            default:
+                throw new Error(`Unknown condition node type: ${node.type}`);
+        }
+    }
+
+    static evaluatePredicate(node, email, schema) {
+        const fieldName = schema[node.field] || node.field;
+        const value = (email[fieldName] || '').toString();
+        const target = node.value;
+
+        if (node.operator === 'contains') {
+            return value.toLowerCase().includes(target.toLowerCase());
+        }
+        return false;
+    }
+
+    static evaluateInPredicate(node, email, schema) {
+        const fieldName = schema[node.field] || node.field;
+        const value = (email[fieldName] || '').toString();
+        const targets = node.value; // Array of strings
+
+        const lowerValue = value.toLowerCase();
+        // Check if value includes any of the target strings (case-insensitive)
+        return targets.some(target => lowerValue.includes(target.toLowerCase()));
+    }
+
+    static serializeAction(actionNode) {
+        switch (actionNode.action) {
+            case 'move': return `move to ${actionNode.target}`;
+            case 'remove': return `remove from ${actionNode.target}`;
+            case 'notify': return 'notify';
+            case 'call': return 'call';
+            case 'remind': return 'remind';
+            case 'mark_read': return 'mark as read';
+            case 'mark_unread': return 'mark as unread';
+            case 'auto': return 'auto';
+            default: return actionNode.action;
+        }
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,141 @@
+
+export interface Email {
+    id: string;
+    from: string; // Mapped from 'sender' in rules
+    subject: string;
+    body: string;
+    unread: boolean;
+    receivedAt: number;
+    [key: string]: any; // Allow other properties
+}
+
+export interface ActionLog {
+    emailId: string;
+    folder: string;
+    actions: string[];
+}
+
+export interface ResultMeta {
+    engine: string;
+    version: string;
+    processedAt: number;
+    ruleCount: number;
+    emailCount: number;
+}
+
+export interface ExecutionResult {
+    folders: Record<string, Email[]>;
+    actionsLog: ActionLog[];
+    meta: ResultMeta;
+}
+
+export interface InitConfig {
+    /**
+     * Rule content or file paths.
+     * Can be a single string (content or .cxr path) or an array of strings.
+     * If a string ends with '.cxr', it is treated as a file path and read from disk.
+     * 
+     * @example
+     * // Load from file
+     * rules: "./rules/alerts.cxr"
+     * 
+     * @example
+     * // Inline content
+     * rules: `Folder Alerts WHEN sender contains "github" THEN move to Alerts`
+     * 
+     * @example
+     * // Combined
+     * rules: ["./common.cxr", "./personal.cxr"]
+     */
+    rules: string | string[];
+
+    /**
+     * List of email objects to process.
+     * Each email object must minimally contain: id, from, subject, body, unread, receivedAt.
+     */
+    emails: Email[];
+
+    /**
+     * Optional custom schema mapping.
+     * Maps rule field names to email object property names.
+     * Default schema: { sender: 'from', subject: 'subject', body: 'body' }
+     * 
+     * @example
+     * // Map 'priority' in rules to 'X-Priority' in email object
+     * schema: { priority: 'X-Priority' }
+     */
+    schema?: Record<string, string>;
+}
+
+/**
+ * Initialize the CXR engine with rules and emails.
+ * 
+ * This is the main entry point. It parses the provided rules (from strings or files)
+ * and executes them against the provided list of emails.
+ * 
+ * @param config Configuration object containing rules and emails.
+ * @returns The classification result and action logs.
+ * 
+ * @example
+ * const result = cxr.init({
+ *   rules: "./my-rules.cxr",
+ *   emails: myEmails
+ * });
+ * console.log(result.folders);
+ */
+export function init(config: InitConfig): ExecutionResult;
+
+/**
+ * **CXR - Email Rule eXecutor**
+ * 
+ * A rule engine / compiler for email filtering logic.
+ * 
+ * CXR parses a custom `.cxr` domain language and executes deterministically against normalized email objects without mutation.
+ * 
+ * ### Features
+ * - **Safe**: No `eval`, no `Function`, purely AST-based execution.
+ * - **Deterministic**: Input -> Output is always the same.
+ * - **Explainable**: Returns metadata and logs of all actions taken.
+ * - **Extensible**: Pure JSON output format.
+ * - **Zero Dependencies**: Lightweight and fast.
+ * 
+ * ### Example Usage
+ * ```javascript
+ * import cxr from "cxr";
+ * 
+ * // 1. Define Rules (.cxr content)
+ * const rules = `
+ * Folder "Important"
+ * WHEN sender contains "boss"
+ * THEN move to "Important"
+ * AND notify
+ * `;
+ * 
+ * // 2. Run Engine
+ * const result = cxr.init({
+ *   rules,
+ *   emails: [{ 
+ *     id: '1', 
+ *     from: 'boss@company.com', 
+ *     subject: 'Urgent', 
+ *     body: 'Read this', 
+ *     unread: true, 
+ *     receivedAt: Date.now() 
+ *   }]
+ * });
+ * 
+ * // 3. Use Results
+ * console.log(result.folders['Important']); // [ { id: '1', ... } ]
+ * ```
+ */
+declare const cxr: {
+    /**
+     * Initialize the CXR engine.
+     * 
+     * @param config {InitConfig} Configuration object containing rules and emails.
+     * @returns {ExecutionResult} The classification result and action logs.
+     */
+    init: typeof init;
+};
+
+export default cxr;

package/src/index.js

@@ -0,0 +1,56 @@
+
+import { Executor } from './executor.js';
+import fs from 'node:fs';
+
+/**
+ * CXR Main Entry Point
+ */
+const cxr = {
+    /**
+     * Initialize result engine with rules and emails.
+     * @param {Object} config
+     * @param {string|string[]} config.rules - The .cxr rules content or file path(s)
+     * @param {Array} config.emails - Array of email objects
+     * @returns {Object} Result object containing folders and actionsLog
+     */
+    init: function (config) {
+        if (!config || !config.rules) {
+            throw new Error("Invalid configuration: 'rules' is required (string or array).");
+        }
+        if (!Array.isArray(config.emails)) {
+            throw new Error("Invalid configuration: 'emails' array is required.");
+        }
+
+
+        // Resolve Rules (Handle Strings and File Paths)
+        const inputs = Array.isArray(config.rules) ? config.rules : [config.rules];
+        const combinedRules = inputs.map(input => {
+            if (typeof input !== 'string') {
+                throw new Error("Invalid rule format: expected string content or file path.");
+            }
+
+
+            // Heuristic: If string ends with .cxr, treat as file path.
+            if (input.trim().endsWith('.cxr')) {
+                try {
+                    if (fs.existsSync(input)) {
+                        return fs.readFileSync(input, 'utf8');
+                    }
+                    throw new Error(`Rule file not found: ${input}`);
+                } catch (err) {
+                    throw err;
+                }
+            }
+
+            return input;
+        }).join('\n'); // Combine with newline for separation
+
+        try {
+            return Executor.execute(combinedRules, config.emails, config.schema);
+        } catch (error) {
+            throw error;
+        }
+    }
+};
+
+export default cxr;

package/src/lexer.js

@@ -0,0 +1,188 @@
+
+/**
+ * TokenType definitions
+ */
+export const TokenType = {
+    // Structural
+    FOLDER: 'FOLDER',
+    WHEN: 'WHEN',
+    THEN: 'THEN',
+
+    // Logic
+    AND: 'AND',
+    OR: 'OR',
+    NOT: 'NOT',
+    IN: 'IN',
+    CONTAINS: 'CONTAINS', // Although 'contains' acts like an operator
+
+    // Fields
+    FIELD_SENDER: 'FIELD_SENDER',
+    FIELD_SUBJECT: 'FIELD_SUBJECT',
+    FIELD_BODY: 'FIELD_BODY',
+
+    // Actions (Start words)
+    KW_MOVE: 'KW_MOVE',
+    KW_REMOVE: 'KW_REMOVE',
+    KW_NOTIFY: 'KW_NOTIFY',
+    KW_CALL: 'KW_CALL',
+    KW_REMIND: 'KW_REMIND',
+    KW_MARK: 'KW_MARK',
+    KW_AUTO: 'KW_AUTO',
+
+    // Prepositions / Helpers
+    KW_TO: 'KW_TO',
+    KW_FROM: 'KW_FROM',
+    KW_AS: 'KW_AS',
+    KW_READ: 'KW_READ',
+    KW_UNREAD: 'KW_UNREAD',
+
+    // Literals
+    STRING: 'STRING',
+    IDENTIFIER: 'IDENTIFIER',
+
+    // Symbols
+    LPAREN: 'LPAREN',
+    RPAREN: 'RPAREN',
+    LBRACKET: 'LBRACKET',
+    RBRACKET: 'RBRACKET',
+    COMMA: 'COMMA',
+
+    EOF: 'EOF'
+};
+
+class Token {
+    constructor(type, value, line, column) {
+        this.type = type;
+        this.value = value;
+        this.line = line;
+        this.column = column;
+    }
+}
+
+export class Lexer {
+    constructor(input) {
+        this.input = input;
+        this.pos = 0;
+        this.line = 1;
+        this.column = 1;
+        this.tokens = [];
+    }
+
+    tokenize() {
+        while (this.pos < this.input.length) {
+            const char = this.input[this.pos];
+
+            // Handle whitespace
+            if (/\s/.test(char)) {
+                if (char === '\n') {
+                    this.line++;
+                    this.column = 1;
+                } else {
+                    this.column++;
+                }
+                this.pos++;
+                continue;
+            }
+
+            // Handle strings
+            if (char === '"') {
+                this.readString();
+                continue;
+            }
+
+            // Handle symbols
+            if (char === '(') { this.addToken(TokenType.LPAREN, '('); this.pos++; this.column++; continue; }
+            if (char === ')') { this.addToken(TokenType.RPAREN, ')'); this.pos++; this.column++; continue; }
+            if (char === '[') { this.addToken(TokenType.LBRACKET, '['); this.pos++; this.column++; continue; }
+            if (char === ']') { this.addToken(TokenType.RBRACKET, ']'); this.pos++; this.column++; continue; }
+            if (char === ',') { this.addToken(TokenType.COMMA, ','); this.pos++; this.column++; continue; }
+
+            // Handle keywords and identifiers
+            if (/[a-zA-Z0-9_]/.test(char)) {
+                this.readIdentifierOrKeyword();
+                continue;
+            }
+
+            // If we reach here, it's an unexpected character
+            throw new Error(`Unexpected character '${char}' at line ${this.line}, column ${this.column}`);
+        }
+
+        this.addToken(TokenType.EOF, null);
+        return this.tokens;
+    }
+
+    addToken(type, value) {
+        this.tokens.push(new Token(type, value, this.line, this.column));
+    }
+
+    readString() {
+        let value = '';
+        const startColumn = this.column;
+        this.pos++; // Skip opening quote
+        this.column++;
+
+        while (this.pos < this.input.length && this.input[this.pos] !== '"') {
+            value += this.input[this.pos];
+            this.pos++;
+            this.column++;
+        }
+
+        if (this.pos >= this.input.length) {
+            throw new Error(`Unterminated string starting at line ${this.line}, column ${startColumn}`);
+        }
+
+        this.pos++; // Skip closing quote
+        this.column++;
+        this.tokens.push(new Token(TokenType.STRING, value, this.line, startColumn));
+    }
+
+    readIdentifierOrKeyword() {
+        let value = '';
+        const startColumn = this.column;
+
+        // Read word
+        while (this.pos < this.input.length && /[a-zA-Z0-9_]/.test(this.input[this.pos])) {
+            value += this.input[this.pos];
+            this.pos++;
+            this.column++;
+        }
+
+        const key = value.toLowerCase();
+
+        // Mapping of keywords to TokenTypes
+        const KEYWORDS = {
+            'folder': TokenType.FOLDER,
+            'when': TokenType.WHEN,
+            'then': TokenType.THEN,
+            'and': TokenType.AND,
+            'or': TokenType.OR,
+            'not': TokenType.NOT,
+            'in': TokenType.IN,
+            'contains': TokenType.CONTAINS,
+
+            'sender': TokenType.FIELD_SENDER,
+            'subject': TokenType.FIELD_SUBJECT,
+            'body': TokenType.FIELD_BODY,
+
+            'move': TokenType.KW_MOVE,
+            'remove': TokenType.KW_REMOVE,
+            'notify': TokenType.KW_NOTIFY,
+            'call': TokenType.KW_CALL,
+            'remind': TokenType.KW_REMIND,
+            'mark': TokenType.KW_MARK,
+            'auto': TokenType.KW_AUTO,
+
+            'to': TokenType.KW_TO,
+            'from': TokenType.KW_FROM,
+            'as': TokenType.KW_AS,
+            'read': TokenType.KW_READ,
+            'unread': TokenType.KW_UNREAD
+        };
+
+        if (KEYWORDS.hasOwnProperty(key)) {
+            this.addToken(KEYWORDS[key], value);
+        } else {
+            this.addToken(TokenType.IDENTIFIER, value);
+        }
+    }
+}

package/src/parser.js

@@ -0,0 +1,246 @@
+
+import { TokenType } from './lexer.js';
+
+export class Parser {
+    constructor(tokens) {
+        this.tokens = tokens;
+        this.pos = 0;
+    }
+
+    parse() {
+        const folders = [];
+        while (this.peek().type !== TokenType.EOF) {
+            if (this.peek().type === TokenType.FOLDER) {
+                folders.push(this.parseFolder());
+            } else {
+                throw this.error(`Expected 'Folder' declaration, found ${this.peek().value}`);
+            }
+        }
+        return { type: 'Program', folders };
+    }
+
+    parseFolder() {
+        this.consume(TokenType.FOLDER);
+        const name = this.parseTarget();
+
+        const rules = [];
+        while (this.peek().type === TokenType.WHEN) {
+            rules.push(this.parseRule());
+        }
+
+        if (rules.length === 0) {
+            throw this.error(`Folder '${name}' must have at least one rule.`);
+        }
+
+        return { type: 'Folder', name, rules };
+    }
+
+    parseRule() {
+        this.consume(TokenType.WHEN);
+        const condition = this.parseCondition();
+
+        this.consume(TokenType.THEN);
+        const actions = this.parseActions();
+
+        return { type: 'Rule', condition, actions };
+    }
+
+    parseCondition() {
+        return this.parseOr();
+    }
+
+    parseOr() {
+        let left = this.parseAnd();
+
+        while (this.match(TokenType.OR)) {
+            const right = this.parseAnd();
+            left = {
+                type: 'BinaryExpression',
+                operator: 'OR',
+                left,
+                right
+            };
+        }
+        return left;
+    }
+
+    parseAnd() {
+        let left = this.parseNot();
+
+        while (this.match(TokenType.AND)) {
+            const right = this.parseNot();
+            left = {
+                type: 'BinaryExpression',
+                operator: 'AND',
+                left,
+                right
+            };
+        }
+        return left;
+    }
+
+    parseNot() {
+        if (this.match(TokenType.NOT)) {
+            return {
+                type: 'UnaryExpression',
+                operator: 'NOT',
+                argument: this.parseNot()
+            };
+        }
+        return this.parseFactor();
+    }
+
+    parseFactor() {
+        if (this.match(TokenType.LPAREN)) {
+            const expr = this.parseCondition();
+            this.consume(TokenType.RPAREN, "Expected ')'");
+            return expr;
+        }
+
+        const field = this.parseField();
+
+        if (this.match(TokenType.CONTAINS)) {
+            const valueToken = this.consume(TokenType.STRING, "Expected string literal after 'contains'");
+            return {
+                type: 'Predicate',
+                field: field.value,
+                operator: 'contains',
+                value: valueToken.value
+            };
+        }
+
+        if (this.match(TokenType.IN)) {
+            if (this.peek().type === TokenType.STRING) {
+                const val = this.consume(TokenType.STRING).value;
+                return {
+                    type: 'InPredicate',
+                    field: field.value,
+                    value: [val]
+                };
+            } else if (this.match(TokenType.LBRACKET)) {
+                const values = [];
+                do {
+                    const val = this.consume(TokenType.STRING, "Expected string in list").value;
+                    values.push(val);
+                } while (this.match(TokenType.COMMA));
+                this.consume(TokenType.RBRACKET, "Expected ']'");
+                return {
+                    type: 'InPredicate',
+                    field: field.value,
+                    value: values
+                };
+            } else {
+                throw this.error("Expected string or list after 'IN'");
+            }
+        }
+
+        throw this.error(`Unexpected token in condition: ${this.peek().value}`);
+    }
+
+    parseField() {
+        if (this.check(TokenType.FIELD_SENDER) ||
+            this.check(TokenType.FIELD_SUBJECT) ||
+            this.check(TokenType.FIELD_BODY) ||
+            this.check(TokenType.IDENTIFIER)) {
+            return this.advance();
+        }
+        throw this.error("Expected field (sender, subject, body, or custom field)");
+    }
+
+    parseActions() {
+        const actions = [];
+        actions.push(this.parseAction());
+
+        while (this.match(TokenType.AND)) {
+            actions.push(this.parseAction());
+        }
+        return actions;
+    }
+
+    parseTarget() {
+        if (this.check(TokenType.IDENTIFIER) || this.check(TokenType.STRING)) {
+            return this.advance().value;
+        }
+        throw this.error("Expected folder name (identifier or string)");
+    }
+
+    parseAction() {
+        const token = this.peek();
+
+        if (this.match(TokenType.KW_MOVE)) {
+            this.consume(TokenType.KW_TO, "Expected 'to' after 'move'");
+            const folder = this.parseTarget();
+            return { type: 'Action', action: 'move', target: folder };
+        }
+
+        if (this.match(TokenType.KW_REMOVE)) {
+            this.consume(TokenType.KW_FROM, "Expected 'from' after 'remove'");
+            const folder = this.parseTarget();
+            return { type: 'Action', action: 'remove', target: folder };
+        }
+
+        if (this.match(TokenType.KW_NOTIFY)) {
+            return { type: 'Action', action: 'notify' };
+        }
+
+        if (this.match(TokenType.KW_CALL)) {
+            return { type: 'Action', action: 'call' };
+        }
+
+        if (this.match(TokenType.KW_REMIND)) {
+            return { type: 'Action', action: 'remind' };
+        }
+
+        if (this.match(TokenType.KW_AUTO)) {
+            return { type: 'Action', action: 'auto' };
+        }
+
+        if (this.match(TokenType.KW_MARK)) {
+            if (this.match(TokenType.KW_AS)) {
+                if (this.match(TokenType.KW_READ)) {
+                    return { type: 'Action', action: 'mark_read' };
+                } else if (this.match(TokenType.KW_UNREAD)) {
+                    return { type: 'Action', action: 'mark_unread' };
+                }
+            }
+            throw this.error("Expected 'as read' or 'as unread' after 'mark'");
+        }
+
+        throw this.error(`Unknown or invalid action start: ${token.value}`);
+    }
+
+    peek() {
+        return this.tokens[this.pos];
+    }
+
+    advance() {
+        if (this.pos < this.tokens.length - 1) {
+            this.pos++;
+        }
+        return this.tokens[this.pos - 1];
+    }
+
+    check(type) {
+        return this.peek().type === type;
+    }
+
+    match(type) {
+        if (this.check(type)) {
+            this.advance();
+            return true;
+        }
+        return false;
+    }
+
+    consume(type, errorMessage) {
+        if (this.check(type)) {
+            return this.advance();
+        }
+        throw this.error(errorMessage || `Expected ${type}, found ${this.peek().type}`);
+    }
+
+    error(message) {
+        const token = this.peek();
+        return new Error(`Parser Error at line ${token.line}, column ${token.column}: ${message}`);
+    }
+}