@tsomaiatech/moxite 1.0.0 → 1.0.1

package/README.md

@@ -1,18 +1,18 @@
 # Moxite Template Engine
 
-Moxite is an extremely fast, structural, and strictly evaluated template engine designed to be completely **indestructible**.
+Moxite is a fast, structural, and strictly evaluated template engine designed to enforce a clear separation between application logic and the presentation layer.
 
-Drawing inspiration from modern control flows like Angular 19, Moxite enforces a separation of logic and presentation through a pristine, character-by-character parsed Abstract Syntax Tree (AST). It completely eliminates the use of fuzzy Regular Expressions for parsing, meaning it is impossible to crash the engine with malformed overlapping templates, escaped quotes, or structural injection attacks.
+Moxite approaches template parsing through a dedicated, character-by-character Lexer and a recursive descent Abstract Syntax Tree (AST) Parser, moving away from string-replacement or Regex-heavy architectures.
 
-## Why Moxite?
+By evaluating an isolated AST, Moxite cleanly scopes template logic and ensures high reliability when parsing complex, overlapping data structures.
 
-Modern template engines (like Jinja, EJS, and Handlebars) rely heavily on Regular Expressions and have slowly mutated into sprawling, poorly-implemented programming languages that execute inline logic, define JSON objects inline, and succumb to context leaks.
+## Design Philosophy
 
-Moxite takes a diametrically opposed approach:
-1. **Zero Regex Parsing**: Every token is mapped through a strict, atomic Lexical State machine and evaluated via a recursive descent Parser.
-2. **Zero Inline Objects**: The Expression Lexer intentionally forbids array closures `[1, 2]` or object structures `{k: v}` to prevent Turing-complete bloat and force developers to construct their data in the core application logic (e.g. TypeScript/Java), not in the view layer.
-3. **Implicit Safe Navigation**: The engine automatically protects against `null` or `undefined` property access without throwing exceptions, turning `{{ user.profile.name }}` into an implicit `{{ user?.profile?.name }}`.
-4. **Absolute Polyglot Isolation**: Moxite's domain syntax (`@` and `{{ }}`) will perfectly isolate itself even when overlapping natively with 10 other template engines or syntaxes in the exact same file (C# Razor, PHP, Bash, JSON-LD, etc.).
+The core philosophy of Moxite is to keep templates simple and focused purely on rendering:
+
+1. **Explicit Lexing**: Every template token is mapped through an atomic Lexical State machine and evaluated via a recursive descent Parser, ensuring predictable boundaries even when templates overlap with other syntaxes like JSON, bash scripts, or nested code blocks.
+2. **Strict Expression Evaluation**: The expression parser deliberately limits complex inline operations. Features like inline array definitions `[1, 2]` or JSON closures `{key: val}` are intentionally unsupported, encouraging developers to construct their data payloads cleanly in the upstream application code.
+3. **Implicit Safe Navigation**: The engine automatically protects against `null` or `undefined` property access without throwing verbose errors. For example, `{{ user.profile.name }}` is implicitly handled as `user?.profile?.name` under the hood.
 
 ## Syntax Outline
 
@@ -40,7 +40,7 @@ Implicit Safe Output: {{ user.deep.missing.path.shouldNotCrash }}
 @endfor
 ```
 
-### Immutable Block Scoping (`@const`)
+### Block Scoping (`@const`)
 ```mx
 @const greeting = "Hello"
 @const role = user.role
@@ -49,7 +49,7 @@ Implicit Safe Output: {{ user.deep.missing.path.shouldNotCrash }}
 ```
 
 ### Pipes (`|`)
-Pipes allow you to pass values through pure formatting functions registered in the evaluation context.
+Pipes allow you to pass variables through formatting functions registered in your evaluation context.
 ```mx
 {{ user.name | upper }}
 {{ total | currency: "USD" }}
@@ -58,4 +58,4 @@ Pipes allow you to pass values through pure formatting functions registered in t
 ## Structure
 
 - `src/`: Contains the pure TypeScript reference implementation of the strict Lexer, AST Parser, and Evaluator (`template-engine.ts`).
-- `idea-plugin/`: An independent Gradle project containing the IntelliJ IDEA plugin. Utilizing Grammar-Kit and JFlex, it tokenizes `.mx` files with the exact deterministic boundary rules as the TypeScript engine, providing native JetBrains syntax highlighting and completion.
+- `idea-plugin/`: A Gradle project containing the IntelliJ IDEA plugin. Powered by Grammar-Kit and JFlex, this plugin provides native JetBrains syntax highlighting, completion, and semantic validation for `.mx` files using the exact same DFA token boundaries as the TypeScript engine.

package/dist/__tests__/template-engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/template-engine.test.js

@@ -0,0 +1,389 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const template_engine_1 = require("../template-engine");
+describe('Template Engine', () => {
+    it('renders text only', () => {
+        const tpl = 'Hello world';
+        expect((0, template_engine_1.render)(tpl, {})).toBe('Hello world');
+    });
+    it('handles interpolation & implicit safe chaining', () => {
+        const tpl = 'Hello {{ user.profile.name }}!';
+        const ctx = { user: { profile: { name: 'Alice' } } };
+        expect((0, template_engine_1.render)(tpl, ctx)).toBe('Hello Alice!');
+        // Safe chaining
+        const ctxBad = {};
+        expect((0, template_engine_1.render)(tpl, ctxBad)).toBe('Hello !');
+    });
+    it('applies pipes correctly', () => {
+        const tpl = 'Hello {{ name | upper }} - {{ num | add: "5" }}';
+        const ctx = { name: 'bob', num: 10 };
+        const pipes = {
+            upper: (val) => val.toUpperCase(),
+            add: (val, amt) => val + Number(amt)
+        };
+        expect((0, template_engine_1.render)(tpl, ctx, pipes)).toBe('Hello BOB - 15');
+    });
+    it('evaluates @if / @else if / @else', () => {
+        const tpl = `
+@if (user.isAdmin)
+Admin
+@else if (user.isGuest === "yes")
+Guest
+@else if (user.age > 18)
+Adult
+@else
+User
+@endif
+`.trim();
+        expect((0, template_engine_1.render)(tpl, { user: { isAdmin: true } }).trim()).toBe('Admin');
+        expect((0, template_engine_1.render)(tpl, { user: { isGuest: "yes" } }).trim()).toBe('Guest');
+        expect((0, template_engine_1.render)(tpl, { user: { age: 20 } }).trim()).toBe('Adult');
+        expect((0, template_engine_1.render)(tpl, { user: { age: 10 } }).trim()).toBe('User');
+    });
+    it('runs @for loops', () => {
+        const tpl = `
+@for (item of items)
+- {{ item.name }}
+@endfor
+`.trim();
+        const ctx = { items: [{ name: 'A' }, { name: 'B' }] };
+        expect((0, template_engine_1.render)(tpl, ctx).trim()).toBe('- A\n- B');
+    });
+    it('supports @const block-level scoping', () => {
+        const tpl = `
+@const a = 1
+@if (true)
+@const b = 2
+{{ a }} - {{ b }}
+@endif
+@if (true)
+@const b = 3
+{{ a }} - {{ b }}
+@endif
+`.trim();
+        const ctx = {};
+        expect((0, template_engine_1.render)(tpl, ctx).trim()).toBe('1 - 2\n1 - 3');
+    });
+    it('executes complex battle test (Nested @for, @if, @const, Pipes)', () => {
+        const tpl = `
+@const roleName = user.role
+@if (user.isActive)
+  @for (project of user.projects)
+    @const projectStatus = project.status
+    @if (projectStatus === "active")
+      Active Project [{{ roleName | upper | prefix: ">> " }}]: {{ project.name }}
+      @for (task of project.tasks)
+         - {{ task.title }} ({{ task.priority | upper }})
+      @endfor
+    @else if (projectStatus === "archived")
+      Archived Project [{{ roleName | upper }}]: {{ project.name }}
+    @else
+      Unknown Project Status
+    @endif
+  @endfor
+@else
+  Inactive User
+@endif
+`.trim();
+        const ctx = {
+            user: {
+                isActive: true,
+                role: 'engineer',
+                projects: [
+                    {
+                        name: 'Relay Engine',
+                        status: 'active',
+                        tasks: [
+                            { title: 'Write lexer', priority: 'high' },
+                            { title: 'Write parser', priority: 'medium' }
+                        ]
+                    },
+                    {
+                        name: 'Old Project',
+                        status: 'archived',
+                        tasks: []
+                    }
+                ]
+            }
+        };
+        const pipes = {
+            upper: (val) => val.toUpperCase(),
+            prefix: (val, p) => p + val
+        };
+        const expected = `
+      Active Project [>> ENGINEER]: Relay Engine
+      
+         - Write lexer (HIGH)
+      
+         - Write parser (MEDIUM)
+      
+    
+      Archived Project [ENGINEER]: Old Project
+    `.replace(/^\s+/gm, '').trim();
+        const result = (0, template_engine_1.render)(tpl, ctx, pipes).replace(/^\s+/gm, '').trim();
+        expect(result).toBe(expected);
+    });
+    it('handles edge cases with empty lists and nested object paths', () => {
+        const tpl = `
+@if (user.isNotSet)
+  Should not render
+@else if (user.count === 0)
+  Zero Count: {{ user.metadata.tags[0] }}
+@endif
+@for (item of emptyList)
+  Should not render
+@endfor
+Done
+`.trim();
+        const ctx = { user: { count: 0, metadata: { tags: ['admin'] } }, emptyList: [] };
+        expect((0, template_engine_1.render)(tpl, ctx).trim()).toBe('Zero Count: admin\nDone');
+    });
+    it('Deep nesting, parallel scopes, falsy values, pipe chains', () => {
+        const tpl = `
+@const globalPrefix = ">>"
+@if (payload.isValid === false)
+  Payload Invalid. Error: {{ payload.error | upper }}
+@else
+  @for (org of payload.organizations)
+    ORGANIZATION: {{ org.name }}
+    @const orgStatus = org.isActive
+    @if (orgStatus)
+      @const memberCount = org.members.length
+      @if (memberCount === 0)
+        No members in active org.
+      @else
+        Members ({{ memberCount }}):
+        @for (member of org.members)
+          @const prefix = globalPrefix | concat: " " | concat: member.role
+          @if (member.isBanned)
+            [BANNED] {{ prefix }} - {{ member.name }}
+          @else if (member.age < 18)
+            [MINOR] {{ prefix }} - {{ member.name }}
+          @else
+            [ACTIVE] {{ prefix }} - {{ member.name }} | Data: {{ member.deep.missing.path.shouldNotCrash }}
+          @endif
+        @endfor
+      @endif
+    @else
+      Organization {{ org.name }} is INACTIVE.
+    @endif
+    ---
+  @endfor
+@endif
+`.trim();
+        const ctx = {
+            payload: {
+                isValid: true,
+                error: null,
+                organizations: [
+                    {
+                        name: 'Alpha Corp',
+                        isActive: false,
+                        members: []
+                    },
+                    {
+                        name: 'Beta LLC',
+                        isActive: true,
+                        members: []
+                    },
+                    {
+                        name: 'Gamma Inc',
+                        isActive: true,
+                        members: [
+                            { name: 'Alice', role: 'ADMIN', isBanned: false, age: 30, deep: {} },
+                            { name: 'Bob', role: 'USER', isBanned: true, age: 25 },
+                            { name: 'Charlie', role: 'GUEST', isBanned: false, age: 16 }
+                        ]
+                    }
+                ]
+            }
+        };
+        const pipes = {
+            upper: (val) => val ? val.toUpperCase() : '',
+            concat: (val, extra) => val + extra
+        };
+        const expected = `
+ORGANIZATION: Alpha Corp
+Organization Alpha Corp is INACTIVE.
+---
+ORGANIZATION: Beta LLC
+No members in active org.
+---
+ORGANIZATION: Gamma Inc
+Members (3):
+[ACTIVE] >> ADMIN - Alice | Data: 
+[BANNED] >> USER - Bob
+[MINOR] >> GUEST - Charlie
+---
+    `.trim().replace(/^\s+/gm, '');
+        const result = (0, template_engine_1.render)(tpl, ctx, pipes).trim().replace(/^\s+/gm, '');
+        expect(result).toBe(expected);
+    });
+    it('Resilience against malformed tokens (throws correctly or ignores)', () => {
+        const unclosedTpl = 'Hello {{ user.name';
+        expect(() => (0, template_engine_1.render)(unclosedTpl, {})).toThrow(/Unclosed interpolation/);
+        const malformedConst = '@const user.name = "bob"';
+        expect(() => (0, template_engine_1.render)(malformedConst, {})).toThrow(/Malformed @const/);
+        const badPipe = '{{ user.name | unknownPipe }}';
+        expect(() => (0, template_engine_1.render)(badPipe, { user: { name: 'bob' } })).toThrow(/Unknown pipe: unknownPipe/);
+        // Shadowing constant should throw
+        const shadowTpl = `
+@const a = 1
+@const a = 2
+`;
+        expect(() => (0, template_engine_1.render)(shadowTpl, {})).toThrow(/Cannot shadow or redefine constant 'a'/);
+    });
+    it('Extreme Edge Cases & Parser Torment', () => {
+        // 1. Whitespace Chaos
+        const tpl1 = `
+@if       ( 
+  user . age 
+  === 
+  20 
+  )
+Yes
+@endif`.trim();
+        expect((0, template_engine_1.render)(tpl1, { user: { age: 20 } }).trim()).toBe('Yes');
+        // 2. Computed Properties with crazy names
+        const tpl2 = `{{ data["crazy-key-with space"] }}`;
+        expect((0, template_engine_1.render)(tpl2, { data: { "crazy-key-with space": "works" } })).toBe('works');
+        // 3. String literals containing template syntax (Lexer should not interpolate inner strings)
+        const tpl3 = `{{ "{{ not an interpolation }}" }}`;
+        expect((0, template_engine_1.render)(tpl3, {})).toBe('{{ not an interpolation }}');
+        // 4. Dangling blocks
+        expect(() => (0, template_engine_1.render)('@else', {})).toThrow(/Unexpected block tag: @else/);
+        expect(() => (0, template_engine_1.render)('@endif', {})).toThrow(/Unexpected block tag: @endif/);
+        expect(() => (0, template_engine_1.render)('@endfor', {})).toThrow(/Unexpected block tag: @endfor/);
+    });
+    it('The Unhandled JS Idioms (Breaking the engine!)', () => {
+        // These are scenarios I know the strict Lexer cannot handle yet because they are complex JS idioms
+        // 1. Escaped Quotes inside strings: The lexer will stop at the first internal quote.
+        const tplEscaped = `{{ "He said \\"Hello\\"" }}`;
+        expect(() => (0, template_engine_1.render)(tplEscaped, {})).toThrow();
+        // 2. Negative Numbers: Lexer only recognizes digits, not the minus operator as part of a number or unary.
+        const tplNegative = `@const temp = -10`;
+        expect(() => (0, template_engine_1.render)(tplNegative, {})).toThrow(/Unexpected character in expression.*-/);
+        // 3. Unary Operators (boolean NOT):
+        const tplUnary = `@if (!user.isActive) \n inactive \n @endif`;
+        expect(() => (0, template_engine_1.render)(tplUnary, { user: { isActive: false } })).toThrow(/Unexpected character in expression.*!/);
+        // 4. Unorthodox 'of' usage in @for loops
+        const tplForOf = `@for (item of ["string of doom", "other"]) \n {{ item }} \n @endfor`;
+        // Throws because our strict expression parser intentionally does not support Array literals `[`
+        expect(() => (0, template_engine_1.render)(tplForOf, {})).toThrow();
+        // It works because indexOf(' of ') finds the first instance, but what if the item name has "of" with spaces around it?
+        // User names a variable `list of things`. Invalid identifier but interesting break!
+        expect(() => (0, template_engine_1.render)(`@for (list of things of items)`, {})).toThrow();
+    });
+    it('False positives and overlapping data structures', () => {
+        // 1. JSON-LD and Emails (False positive tags)
+        // The engine must NOT crash when encountering `@context`, `@id`, `user@email.com`, or `@iframe`.
+        const tpl1 = `{
+  "@context": "https://json-ld.org/contexts/person.jsonld",
+  "@id": "http://dbpedia.org/resource/John_Lennon",
+  "email": "john@beatles.com",
+  "handle": "@johnlennon",
+  "tagLike": "@iframe width=100"
+}`;
+        expect((0, template_engine_1.render)(tpl1, {})).toBe(tpl1);
+        // 2. Data that generates another template (Template Inception)
+        const tpl2 = `
+@const open = "{{"
+@const close = "}}"
+Code: {{ open }} user.name {{ close }}
+`.trim();
+        expect((0, template_engine_1.render)(tpl2, {})).toBe('Code: {{ user.name }}');
+        // 3. String literals containing structural AST tokens
+        const tpl3 = `
+@if (user.status === "ACTIVE (ignore this)")
+  @const message = "Status is: @if(true) nested @endif"
+  {{ message }}
+@endif
+`.trim();
+        expect((0, template_engine_1.render)(tpl3, { user: { status: "ACTIVE (ignore this)" } }).trim()).toBe("Status is: @if(true) nested @endif");
+    });
+    it('Syntax Polyglot & Cross-Language Interference', () => {
+        // These tests mix syntaxes from other engines (Jinja, Razor, Blade, Handlebars, JSX)
+        // and structural languages (Python, PHP, C#, Bash) to prove our engine only executes its own domain.
+        // (@Model.User)
+        // Our Lexer must ignore `@Model` because it doesn't match `@if`, `@for`, etc.
+        const razorTpl = `<div>@Model.UserName - @if(user.exists) FOUND @endif</div>`;
+        expect((0, template_engine_1.render)(razorTpl, { user: { exists: true } })).toBe('<div>@Model.UserName -  FOUND </div>');
+        // ({% if %}, {# comment #})
+        const pythonTpl = `
+def print_user():
+    # {% if user.is_active %}
+    print("{{ user.name }}") # Outputs native interpolation
+    # {% endif %}
+    @const result = user.name
+    return "{{ result }}"
+`;
+        const expectedPython = `def print_user(): # {% if user.is_active %} print("Alice") # Outputs native interpolation # {% endif %} return "Alice"`;
+        expect((0, template_engine_1.render)(pythonTpl, { user: { name: "Alice" } }).replace(/\s+/g, ' ').trim()).toBe(expectedPython);
+        // ({user.name} vs {{user.name}})
+        // Only double braces get executed, single braces get passed as text.
+        const jsxTpl = `<div className={styles.container}>{user.name} is actually {{ user.name }}</div>`;
+        expect((0, template_engine_1.render)(jsxTpl, { user: { name: "Alice" } })).toBe('<div className={styles.container}>{user.name} is actually Alice</div>');
+        // Engine must ignore @foreach and <?php tags.
+        const bladeTpl = `
+<?php echo $var; ?>
+@foreach($users as $u)
+  @for (u of users)
+    {{ u }}
+  @endfor
+@endforeach
+`;
+        const expectedBlade = `<?php echo $var; ?> @foreach($users as $u) Bob @endforeach`;
+        expect((0, template_engine_1.render)(bladeTpl, { users: ["Bob"] }).replace(/\s+/g, ' ').trim()).toBe(expectedBlade);
+        // Bash script Interference ($USER, ${USER})
+        const bashTpl = `
+#!/bin/bash
+export THE_USER="{{ sys.user }}"
+echo $THE_USER
+echo \${THE_USER}
+@if (sys.isRoot)
+sudo rm -rf /
+@endif
+`;
+        const expectedBash = `#!/bin/bash export THE_USER="admin" echo $THE_USER echo \${THE_USER} sudo rm -rf /`;
+        expect((0, template_engine_1.render)(bashTpl, { sys: { user: "admin", isRoot: true } }).replace(/\s+/g, ' ').trim()).toBe(expectedBash);
+        // Triple Curly Interference ({{{ user.name }}})
+        // Emulates Vue's v-html raw injection braces.
+        // Our lexer matches the outermost {{ and }} and passes `{ param }` to the expression parser.
+        // Since our strict expression parser explicitly forbids JSON objects (no Javascript `{` or `}`), this safely throws a syntax error!
+        const handlebarsTpl = `{{{ param }}}`;
+        expect(() => (0, template_engine_1.render)(handlebarsTpl, { param: "value" })).toThrow(/Unexpected character in expression at index 0: \{/);
+        const erbTpl = `<%= user.id %> / <%- @for (num of arr) -%>{{ num }}<%- @endfor -%>`;
+        // Note: The space after `)` in `@for (num of arr) -%>` is preserved as text
+        const expectedErb = `<%= user.id %> / <%-  -%>1<%- -%>`;
+        expect((0, template_engine_1.render)(erbTpl, { arr: [1] })).toBe(expectedErb);
+        const jsTpl = `
+const greeting = \`Hello \${user.name}\`;
+@const name = "Bob"
+const override = \`Hello {{ name }}\`;
+`;
+        const expectedJs = `const greeting = \`Hello \${user.name}\`; const override = \`Hello Bob\`;`;
+        expect((0, template_engine_1.render)(jsTpl, {}).replace(/\s+/g, ' ').trim()).toBe(expectedJs);
+        const mdTpl = `
+\`\`\`ts
+@for (item of items)
+console.log("{{ item }}");
+@endfor
+\`\`\`
+`;
+        const expectedMd = `\`\`\`ts console.log("X"); \`\`\``;
+        expect((0, template_engine_1.render)(mdTpl, { items: ["X"] }).replace(/\s+/g, ' ').trim()).toBe(expectedMd);
+        const javaTpl = `
+@RestController
+@RequestMapping("/api")
+public class App {
+  @Autowired
+  private Service service;
+  // @if (java.generateSetter)
+  public void setService(Service s) { this.service = s; }
+  // @endif
+}
+`;
+        const expectedJava = `@RestController @RequestMapping("/api") public class App { @Autowired private Service service; // public void setService(Service s) { this.service = s; } // }`;
+        expect((0, template_engine_1.render)(javaTpl, { java: { generateSetter: true } }).replace(/\s+/g, ' ').trim()).toBe(expectedJava);
+    });
+});

package/dist/template-engine.d.ts

@@ -0,0 +1,80 @@
+export type Context = Record<string, any>;
+export type PipeFunction = (value: any, ...args: any[]) => any;
+export type PipeRegistry = Record<string, PipeFunction>;
+export type ExprToken = {
+    type: 'Identifier';
+    value: string;
+} | {
+    type: 'Number';
+    value: number;
+} | {
+    type: 'String';
+    value: string;
+} | {
+    type: 'Operator';
+    value: string;
+} | {
+    type: 'Punctuation';
+    value: string;
+};
+export declare function tokenizeExpression(source: string): ExprToken[];
+export type ExprAST = {
+    type: 'Literal';
+    value: any;
+} | {
+    type: 'Identifier';
+    name: string;
+} | {
+    type: 'Member';
+    object: ExprAST;
+    property: string | ExprAST;
+    computed: boolean;
+} | {
+    type: 'Binary';
+    operator: string;
+    left: ExprAST;
+    right: ExprAST;
+} | {
+    type: 'Pipe';
+    base: ExprAST;
+    name: string;
+    args: ExprAST[];
+};
+export declare function parseExpression(source: string): ExprAST;
+export type TemplateToken = {
+    type: 'TEXT';
+    value: string;
+} | {
+    type: 'INTERPOLATION';
+    value: string;
+} | {
+    type: 'TAG';
+    name: string;
+    inner: string | null;
+};
+export declare function tokenizeTemplate(source: string): TemplateToken[];
+export type ASTNode = {
+    type: 'TEXT';
+    content: string;
+} | {
+    type: 'INTERPOLATION';
+    expression: ExprAST;
+} | {
+    type: 'CONST';
+    name: string;
+    expression: ExprAST;
+} | {
+    type: 'IF';
+    condition: ExprAST;
+    consequence: ASTNode[];
+    alternate: ASTNode[] | null;
+} | {
+    type: 'FOR';
+    itemName: string;
+    listExpression: ExprAST;
+    body: ASTNode[];
+};
+export declare function parseTemplate(tokens: TemplateToken[]): ASTNode[];
+export declare function evaluateExprAST(ast: ExprAST, context: Context, pipes?: PipeRegistry): any;
+export declare function evaluateTemplate(nodes: ASTNode[], context: Context, pipes?: PipeRegistry): string;
+export declare function render(templateStr: string, context: Context, pipes?: PipeRegistry): string;