hindicode 1.3.0 → 1.4.0

package/README.md

@@ -1,97 +1,90 @@
-# HindiCode - हिंदी में जावास्क्रिप्ट लिखें! 🚀
-> Write JavaScript in Hindi with Industrial-Grade Robustness.
+# HindiCode - हिंदी में जावास्क्रिप्ट लिखें!
 
----
+Hindicode is evolving from a runtime keyword translator into a Hindi-first JavaScript compiler pipeline.
 
-## 🌍 [HI] परिचय (Introduction)
-**HindiCode** एक आधुनिक NPM पैकेज है जो आपको **हिंदी में जावास्क्रिप्ट** लिखने की सुविधा देता है। यह कोड को रन-टाइम पर पार्स करता है और हिंदी के कीवर्ड्स को जावास्क्रिप्ट में बदल देता है।
+## What Hindicode Supports Today
 
-**HindiCode** is a modern NPM package that lets you **write JavaScript in Hindi**. It transpiles Hindi keywords into JavaScript at runtime, enabling a seamless native coding experience.
+- `.hindi.js` runtime execution in Node
+- `hindicode run`, `hindicode check`, and `hindicode transpile`
+- multi-file CommonJS-style Hindicode programs
+- browser-targeted transpilation experiments
+- structured diagnostics for compile-time syntax failures
 
-### 🔹 Example (उदाहरण)
-```javascript
-स्थिर x = 10;
-अगर (x > 5) {
-    दिखाओ("x बड़ा है!");
-} अन्यथा {
-    दिखाओ("x छोटा है!");
-}
-```
-
----
-
-## 🌟 Features (विशेषताएँ)
-- **Industrial-Grade Protection**: 
-  - **🛡️ Comment Protection**: Keywords inside `//` or `/* */` are never translated.
-  - **🛡️ String Protection**: Your text inside `" "` or `' '` stays exactly as written.
-  - **🛡️ Regex Protection**: Search patterns like `/अगर/g` are preserved perfectly.
-- **Smart Template Literals**: Supports full `${}` interpolation with recursive translation.
-- **Unicode Boundaries**: Professional word boundaries ensure `नम` doesn't break `नमस्ते`.
-- **Zero Configuration**: Just register the hook and run `.hindi.js` files.
-
----
-
-## 🔧 Installation (स्थापना)
-```sh
-npm install hindicode
-```
-
----
-
-## 🚀 Usage (उपयोग)
+## Quick Example
 
-### 1. Register the Transpiler
-Add this to your entry point (e.g., `index.js`):
 ```javascript
-require('hindicode');
-require('./your-file.hindi.js');
-```
-
-### 2. Write in Hindi (`.hindi.js`)
-```javascript
-// app.hindi.js
-नया नाम = "अर्जुन";
-दिखाओ(`नमस्ते ${नाम}!`);
+स्थिर नाम = "अर्जुन";
 
-कार्य जोड़(अ, ब) {
-    लौटाओ अ + ब;
+कार्य स्वागत(व्यक्ति) {
+    लौटाओ `नमस्ते ${व्यक्ति}`;
 }
 
-दिखाओ("योग:", जोड़(10, 20));
+दिखाओ(स्वागत(नाम));
 ```
 
----
-
-## 📖 Keyword Mapping (कीवर्ड्स)
-| Hindi | JavaScript | Hindi | JavaScript |
-| :--- | :--- | :--- | :--- |
-| अगर | if | अन्य | else |
-| दिखाओ | console.log | कार्य | function |
-| लौटाओ | return | चलाओ | for |
-| जबतक | while | नया | let |
-| स्थिर | const | सही | true |
-| गलत | false | असांयकालिक | async |
-| प्रतीक्षा | await | त्रुटि | Error |
-
-*(Check `index.js` for the full dictionary of over 90+ terms!)*
-
----
+## Install
 
-## 🗺️ Roadmap (भविष्य की योजना)
-- [ ] **Hindi Variables**: Support for non-keyword Hindi tokens as identifiers.
-- [ ] **Hindi CLI**: A dedicated runner (`hindicode my-file.hindi.js`).
-- [ ] **VS Code Extension**: Syntax highlighting and snippets for `.hindi.js`.
-- [ ] **Hindi Error Messages**: Localized compiler errors.
-- [ ] **Hindi-DOM**: Support for `दस्तावेज़` (document) and `खिड़की` (window).
-
----
-
-## 💖 Contribute (योगदान)
-We welcome contributions! Star the repo and join the movement to make coding accessible in every language. 
+```powershell
+npm install hindicode
+```
 
-👉 **Support Us**: [Patreon](https://www.patreon.com/c/BABU_ISHU)
+## CLI
 
----
+```powershell
+hindicode run app.hindi.js
+hindicode check app.hindi.js
+hindicode transpile app.hindi.js
+```
 
-## 📜 License
-Released under the **MIT License**. 😊
+## Compiler Direction
+
+Phase 1 now includes:
+- keyword inventory module
+- tokenizer
+- parser-strategy layer
+- compiler contract
+- runtime registration module
+- CLI entrypoints
+- parser, CLI, integration, and scenario coverage
+
+## Best-Supported Phase 1 Use Cases
+
+- learning JavaScript in Hindi
+- Node scripts and utilities
+- multi-file CommonJS projects
+- browser-oriented transpilation with mocked or real browser globals
+
+## Current Limits
+
+Not yet fully promised in Phase 1:
+- full ESM runtime execution
+- React/Angular integrations
+- source maps
+- framework loaders
+- full AST parser behavior
+
+## Important Docs
+
+- `PHASE_ONE_PLAN.md`
+- `PHASE_ONE_CHECKLIST.md`
+- `PHASE_TWO_PLAN.md`
+- `PHASE_TWO_CHECKLIST.md`
+- `VISION.md`
+- `ROADMAP.md`
+- `docs/getting-started.md`
+- `docs/cli-usage.md`
+- `docs/cli-quick-reference.md`
+- `docs/language-spec-v1.md`
+- `docs/compiler-contract.md`
+- `docs/runtime-support.md`
+- `docs/source-map-design.md`
+- `docs/contributor-guide.md`
+- `docs/how-to-add-keyword.md`
+
+## Contributing
+
+If you add language features, please update tests and docs together. Phase 1 is focused on correctness, diagnostics, and compiler structure.
+
+## License
+
+MIT

package/bin/hindicode.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/cli/main");
+
+process.exitCode = runCli(process.argv, console);

package/index.js

@@ -1,239 +1,14 @@
-const fs = require("fs");
-const Module = require("module");
-const path = require("path");
-
-const hindiToJS = {
-    // ── Multi-word phrases FIRST (longest → shortest to avoid partial matches) ──
-    "नहीं तो": "else",
-    "के रूप में": "as",
-    "का प्रकार": "typeof",
-    "नया बनाओ": "new",
-    "कम या बराबर": "<=",
-    "ज्यादा या बराबर": ">=",
-    "बराबर नहीं": "!==",
-
-    // ── Control Flow ─────────────────────────────────
-    "अगर": "if",
-    "वरना": "else",
-    "करो": "do",
-    "जबतक": "while",
-    "केलिए": "for",
-    "स्विच": "switch",
-    "मामला": "case",
-    "रोकें": "break",
-    "जारी": "continue",
-    "लौटाओ": "return",
-    "फेंको": "throw",
-
-    // ── Declarations ─────────────────────────────────
-    "नया": "let",
-    "स्थिर": "const",
-    "पुराना": "var",
-    "कार्य": "function",
-    "वर्ग": "class",
-
-    // ── Async ─────────────────────────────────────────
-    "असिंक": "async",
-    "इंतज़ार": "await",
-
-    // ── Literals ─────────────────────────────────────
-    "सच": "true",
-    "झूठ": "false",
-    "खाली": "null",
-    "अपरिभाषित": "undefined",
-
-    // ── OOP ──────────────────────────────────────────
-    "विस्तार": "extends",
-    "सुपर": "super",
-    "यह": "this",
-    "हटाओ": "delete",
-    "प्रोटो": "prototype",
-    "में": "in",
-    "सत्यापित": "instanceof",
-    "वापसी": "yield",
-
-    // ── Modules ──────────────────────────────────────
-    "आयात": "import",
-    "निर्यात": "export",
-    "डिफ़ॉल्ट": "default",
-    "से": "from",
-    "मांगो": "require",
-    "मॉड्यूल": "module",
-
-    // ── Operators ────────────────────────────────────
-    "और": "&&",
-    "या": "||",
-    "नहीं": "!",
-    "बराबर": "===",
-    "छोटा": "<",
-    "बड़ा": ">",
-
-    // ── Error Handling ────────────────────────────────
-    "कोशिश": "try",
-    "पकड़ो": "catch",
-    "पकड़": "catch",
-    "अंततः": "finally",
-    "त्रुटि": "Error",
-
-    // ── Console ──────────────────────────────────────
-    "दिखाओ": "console.log",
-    "गलती": "console.error",
-    "चेतावनी": "console.warn",
-    "जानकारी": "console.info",
-    "कंसोल": "console",
-
-    // ── Array Methods ────────────────────────────────
-    "पुश": "push",
-    "पॉप": "pop",
-    "शिफ्ट": "shift",
-    "अनशिफ्ट": "unshift",
-    "स्लाइस": "slice",
-    "जोड़ो": "concat",
-    "शामिल": "includes",
-    "ढूँढो": "find",
-    "मानचित्र": "map",
-    "फ़िल्टर": "filter",
-    "कमकरो": "reduce",
-    "हरएक": "forEach",
-    "लंबाई": "length",
-    "इंडेक्स": "indexOf",
-    "उलटाओ": "reverse",
-    "क्रमित": "sort",
-
-    // ── Object Methods ────────────────────────────────
-    "कुंजियाँ": "keys",
-    "मूल्य": "values",
-    "प्रविष्टियाँ": "entries",
-    "बनाएँ": "create",
-    "मिलाओ": "assign",
-    "जमाओ": "freeze",
-
-    // ── Map / Set ─────────────────────────────────────
-    "नक्शा": "Map",
-    "है": "has",
-    "प्राप्त": "get",
-    "रखो": "set",
-    "साफ़": "clear",
-    "आकार": "size",
-    "डालो": "add",
-
-    // ── Promise ───────────────────────────────────────
-    "फिर": "then",
-    "सभी": "all",
-    "हल": "resolve",
-    "अस्वीकार": "reject",
-    "प्रॉमिस": "Promise",
-
-    // ── Browser APIs ──────────────────────────────────
-    "विंडो": "window",
-    "दस्तावेज": "document",
-    "ब्राउज़र": "navigator",
-    "स्थान": "location",
-    "इतिहास": "history",
-    "संग्रह": "localStorage",
-    "सत्र_संग्रह": "sessionStorage",
-    "चेतावनी_डिब्बा": "alert",
-    "पूछो": "prompt",
-    "पक्का_करो": "confirm",
-    "लाओ": "fetch",
-    "समय_बाद": "setTimeout",
-    "बार_बार": "setInterval",
-    "समय_रोकें": "clearTimeout",
-    "बार_रोकें": "clearInterval",
-
-    // ── Node.js ───────────────────────────────────────
-    "प्रक्रिया": "process",
-    "__नाम": "__filename",
-    "__डायरेक्टरी": "__dirname",
-    "बफर": "Buffer",
-
-    // ── Built-ins ─────────────────────────────────────
-    "ऑब्जेक्ट": "Object",
-    "ऐरे": "Array",
-    "सेट": "Set",
-    "स्ट्रिंग": "String",
-    "टेक्स्ट": "String",
-    "नंबर": "Number",
-    "बूलियन": "Boolean",
-    "डेट": "Date",
-    "तारीख": "Date",
-    "गणित": "Math",
-    "जेसन": "JSON",
-    "रेगएक्स": "RegExp",
-    "अनंत": "Infinity",
-    "त्रुटि": "Error",
-    "प्रॉमिस": "Promise",
-
-    // ── Math Shortcuts ────────────────────────────────
-    "गोलाई": "Math.round",
-    "ऊपर": "Math.ceil",
-    "नीचे": "Math.floor",
-    "अधिकतम": "Math.max",
-    "न्यूनतम": "Math.min",
-    "यादृच्छ": "Math.random",
-    "वर्गमूल": "Math.sqrt",
-    "पाई": "Math.PI",
-
-    // ── JSON Shortcuts ────────────────────────────────
-    "पार्स": "JSON.parse",
-    "तार_बनाओ": "JSON.stringify",
-
-    // ── String Methods ────────────────────────────────
-    "बड़े_अक्षर": "toUpperCase",
-    "छोटे_अक्षर": "toLowerCase",
-    "काटो": "trim",
-    "विभाजन": "split",
-    "बदलो": "replace",
-    "खोजो": "search",
-    "शुरू_से": "startsWith",
-    "खत्म_से": "endsWith",
-    "दोहराओ": "repeat",
-    "हिस्सा": "substring",
+const { compileHindiJS, tokenizeSource, translateHindiJS } = require("./src/compiler/compile");
+const { registerHindiExtension } = require("./src/runtime/register");
+const { hindiToJS, sortedKeywords } = require("./src/language/keywords");
+
+registerHindiExtension();
+
+module.exports = {
+    compileHindiJS,
+    hindiToJS,
+    registerHindiExtension,
+    sortedKeywords,
+    tokenizeSource,
+    translateHindiJS,
 };
-
-function translateHindiJS(code) {
-    const sortedKeywords = Object.keys(hindiToJS).sort((a, b) => b.length - a.length);
-
-    const parts = [
-        /(?<BLOCK>\/\*[\s\S]*?\*\/)/.source,
-        /(?<LINE>\/\/.*)/.source,
-        /(?<STRING_DBL>"(?:[^"\\]|\\.)*")/.source,
-        /(?<STRING_SGL>'(?:[^'\\]|\\.)*')/.source,
-        /(?<BACKTICK>`[\s\S]*?`)/.source,
-        /(?<REGEX>\/(?![*\/])(?:[^\/\\\n]|\\.)*?\/[gimuy]*)/.source,
-        `(?<KEYWORD>(?<![\\u0900-\\u097F\\w$])(?:${sortedKeywords.join("|")})(?![\\u0900-\\u097F\\w$]))`
-    ];
-
-    const masterRegex = new RegExp(parts.join("|"), "g");
-
-    return code.replace(masterRegex, (...args) => {
-        const groups = args[args.length - 1];
-        const { BACKTICK, KEYWORD } = groups;
-
-        if (KEYWORD && hindiToJS[KEYWORD]) {
-            return hindiToJS[KEYWORD];
-        }
-
-        if (BACKTICK) {
-            return BACKTICK.replace(/\${([\s\S]*?)}/g, (m, inner) => {
-                return `${"$"}{${translateHindiJS(inner)}}`;
-            });
-        }
-
-        return args[0];
-    });
-}
-
-// Custom require hook for `.hindi.js` files
-require.extensions[".hindi.js"] = function (module, filename) {
-    try {
-        let content = fs.readFileSync(filename, "utf8").trim();
-        content = translateHindiJS(content);
-        module._compile(content, filename);
-    } catch (error) {
-        console.error("❌ Hindi Transpiler Error:", error);
-        throw error; // Re-throw to allow runners to detect failure
-    }
-};
-
-module.exports = { translateHindiJS };

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "hindicode",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Run JavaScript with Hindi keywords",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "hindicode": "./bin/hindicode.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node tests/tokenizer_runner.js && node tests/parser_runner.js && node tests/public_api_runner.js && node tests/cli_runner.js && node tests/integration_runner.js && node tests/spec_runner.js && node runner.js"
   },
   "keywords": [
     "hindi",
@@ -27,8 +30,10 @@
   },
   "homepage": "https://github.com/Ujjwal-08/hindicode#readme",
   "files": [
+    "bin",
     "index.js",
     "index.d.ts",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/cli/index.js

@@ -0,0 +1,77 @@
+const fs = require("fs");
+const path = require("path");
+
+const { compileHindiJS } = require("../compiler/compile");
+const { createDiagnostic, formatDiagnostic } = require("../diagnostics");
+const { registerHindiExtension } = require("../runtime/register");
+
+function printHelp() {
+    console.log(`hindicode <command> <file>
+
+Commands:
+  run <file>         Run a Hindicode file
+  transpile <file>   Print transpiled JavaScript
+  check <file>       Validate a Hindicode file compiles
+`);
+}
+
+function resolveInputFile(filePath) {
+    if (!filePath) {
+        throw createDiagnostic({
+            code: "HC_CLI_NO_INPUT",
+            message: "No input file provided.",
+            hint: "Use hindicode <command> <file>.",
+        });
+    }
+
+    const resolved = path.resolve(process.cwd(), filePath);
+    if (!fs.existsSync(resolved)) {
+        throw createDiagnostic({
+            code: "HC_CLI_FILE_NOT_FOUND",
+            file: resolved,
+            message: "Input file does not exist.",
+            hint: "Check the path or run the command from the project root.",
+        });
+    }
+
+    return resolved;
+}
+
+function runCommand(command, filePath) {
+    if (!command || command === "--help" || command === "-h") {
+        printHelp();
+        return 0;
+    }
+
+    const resolved = resolveInputFile(filePath);
+
+    if (command === "run") {
+        registerHindiExtension();
+        require(resolved);
+        return 0;
+    }
+
+    const source = fs.readFileSync(resolved, "utf8");
+    const result = compileHindiJS(source, { filename: resolved, mode: command });
+
+    if (command === "transpile") {
+        process.stdout.write(result.code);
+        return 0;
+    }
+
+    if (command === "check") {
+        console.log(`OK: ${path.basename(resolved)}`);
+        return 0;
+    }
+
+    throw createDiagnostic({
+        code: "HC_CLI_UNKNOWN_COMMAND",
+        message: `Unknown command: ${command}`,
+        hint: "Use --help to see supported commands.",
+    });
+}
+
+module.exports = {
+    formatDiagnostic,
+    runCommand,
+};

package/src/cli/main.js

@@ -0,0 +1,20 @@
+const { formatDiagnostic, runCommand } = require("./index");
+
+function runCli(argv = process.argv, io = console) {
+    try {
+        const [, , command, filePath] = argv;
+        const exitCode = runCommand(command, filePath);
+        return typeof exitCode === "number" ? exitCode : 0;
+    } catch (error) {
+        if (error && error.code && error.message) {
+            io.error(formatDiagnostic(error));
+        } else {
+            io.error(error.message);
+        }
+        return 1;
+    }
+}
+
+module.exports = {
+    runCli,
+};

package/src/compiler/compile.js

@@ -0,0 +1,108 @@
+const vm = require("vm");
+const { createDiagnostic } = require("../diagnostics");
+const { tokenizeSource } = require("./tokenizer");
+const { parseSource } = require("../parser");
+
+function translateHindiJS(source, options = {}) {
+    const tokens = tokenizeSource(source);
+    const parseResult = parseSource({
+        source,
+        tokens,
+        filename: options.filename || null,
+        recursiveTransform: (innerSource) => translateHindiJS(innerSource, options),
+    });
+
+    return parseResult.transformedCode;
+}
+
+function extractLocationFromSyntaxError(stackText, filename) {
+    const lines = String(stackText || "").split(/\r?\n/);
+    const header = lines.find((line) => line.startsWith(`${filename}:`)) || "";
+    const match = header.match(/:(\d+)$/);
+    const line = match ? Number(match[1]) : 1;
+
+    const caretLine = lines.find((lineText) => /\^/.test(lineText)) || "^";
+    const column = Math.max(caretLine.indexOf("^") + 1, 1);
+
+    return {
+        line,
+        column,
+    };
+}
+
+function validateGeneratedJavaScript(code, filename) {
+    try {
+        new vm.Script(code, { filename });
+        return [];
+    } catch (error) {
+        const location = extractLocationFromSyntaxError(error.stack, filename || "inline.hindi.js");
+        return [
+            createDiagnostic({
+                code: "HC_JS_SYNTAX_ERROR",
+                file: filename || null,
+                message: error.message,
+                start: {
+                    line: location.line,
+                    column: location.column,
+                    index: 0,
+                },
+                end: {
+                    line: location.line,
+                    column: location.column,
+                    index: 0,
+                },
+                hint: "Run hindicode transpile to inspect generated JavaScript around this location.",
+            }),
+        ];
+    }
+}
+
+function compileHindiJS(source, options = {}) {
+    let parseResult;
+
+    try {
+        const tokens = tokenizeSource(source);
+        parseResult = parseSource({
+            source,
+            tokens,
+            filename: options.filename || null,
+            recursiveTransform: (innerSource) => translateHindiJS(innerSource, options),
+        });
+    } catch (error) {
+        const diagnostic = createDiagnostic({
+            code: "HC_COMPILE_FAILURE",
+            file: options.filename || null,
+            message: error.message,
+            hint: "Inspect the source near the reported location or use hindicode transpile for debugging.",
+        });
+        throw diagnostic;
+    }
+
+    const diagnostics = [
+        ...parseResult.diagnostics,
+        ...validateGeneratedJavaScript(parseResult.transformedCode, options.filename || "inline.hindi.js"),
+    ];
+
+    if (diagnostics.length > 0) {
+        throw diagnostics[0];
+    }
+
+    return {
+        code: parseResult.transformedCode,
+        map: null,
+        diagnostics,
+        meta: {
+            filename: options.filename || null,
+            mode: options.mode || "runtime",
+            parserStrategy: parseResult.strategy,
+            parserStage: parseResult.meta.parserStage,
+        },
+        parseResult,
+    };
+}
+
+module.exports = {
+    compileHindiJS,
+    tokenizeSource,
+    translateHindiJS,
+};

package/src/compiler/tokenizer.js

@@ -0,0 +1,219 @@
+const TOKEN_TYPES = {
+    CODE: "code",
+    LINE_COMMENT: "line_comment",
+    BLOCK_COMMENT: "block_comment",
+    STRING_SINGLE: "string_single",
+    STRING_DOUBLE: "string_double",
+    TEMPLATE: "template",
+    REGEX: "regex",
+};
+
+function isEscaped(source, index) {
+    let backslashes = 0;
+    for (let i = index - 1; i >= 0 && source[i] === "\\"; i--) {
+        backslashes++;
+    }
+    return backslashes % 2 === 1;
+}
+
+function isRegexAllowedAfter(previousNonWhitespace) {
+    if (!previousNonWhitespace) {
+        return true;
+    }
+
+    return /[=([{:,;!?&|+\-*/%^<>~]/.test(previousNonWhitespace);
+}
+
+function readQuoted(source, start, quote) {
+    let index = start + 1;
+
+    while (index < source.length) {
+        if (source[index] === quote && !isEscaped(source, index)) {
+            return index + 1;
+        }
+        index++;
+    }
+
+    return source.length;
+}
+
+function readLineComment(source, start) {
+    let index = start + 2;
+    while (index < source.length && source[index] !== "\n") {
+        index++;
+    }
+    return index;
+}
+
+function readBlockComment(source, start) {
+    let index = start + 2;
+    while (index < source.length) {
+        if (source[index] === "*" && source[index + 1] === "/") {
+            return index + 2;
+        }
+        index++;
+    }
+    return source.length;
+}
+
+function readRegex(source, start) {
+    let index = start + 1;
+    let inCharClass = false;
+
+    while (index < source.length) {
+        const char = source[index];
+
+        if (char === "[" && !isEscaped(source, index)) {
+            inCharClass = true;
+        } else if (char === "]" && !isEscaped(source, index)) {
+            inCharClass = false;
+        } else if (char === "/" && !inCharClass && !isEscaped(source, index)) {
+            index++;
+            while (/[a-z]/i.test(source[index] || "")) {
+                index++;
+            }
+            return index;
+        }
+
+        index++;
+    }
+
+    return source.length;
+}
+
+function readTemplate(source, start) {
+    let index = start + 1;
+
+    while (index < source.length) {
+        const char = source[index];
+
+        if (char === "`" && !isEscaped(source, index)) {
+            return index + 1;
+        }
+
+        if (char === "$" && source[index + 1] === "{" && !isEscaped(source, index)) {
+            index += 2;
+            let depth = 1;
+
+            while (index < source.length && depth > 0) {
+                const inner = source[index];
+
+                if ((inner === "'" || inner === '"') && !isEscaped(source, index)) {
+                    index = readQuoted(source, index, inner);
+                    continue;
+                }
+
+                if (inner === "`" && !isEscaped(source, index)) {
+                    index = readTemplate(source, index);
+                    continue;
+                }
+
+                if (inner === "{" && !isEscaped(source, index)) {
+                    depth++;
+                } else if (inner === "}" && !isEscaped(source, index)) {
+                    depth--;
+                }
+
+                index++;
+            }
+
+            continue;
+        }
+
+        index++;
+    }
+
+    return source.length;
+}
+
+function getLocation(source, index) {
+    let line = 1;
+    let column = 1;
+
+    for (let i = 0; i < index; i++) {
+        if (source[i] === "\n") {
+            line++;
+            column = 1;
+        } else {
+            column++;
+        }
+    }
+
+    return { line, column, index };
+}
+
+function createToken(source, type, start, end) {
+    return {
+        type,
+        value: source.slice(start, end),
+        start,
+        end,
+        startLoc: getLocation(source, start),
+        endLoc: getLocation(source, end),
+    };
+}
+
+function tokenizeSource(source) {
+    const tokens = [];
+    let codeStart = 0;
+    let index = 0;
+    let previousNonWhitespace = "";
+
+    const pushCode = (end) => {
+        if (end > codeStart) {
+            tokens.push(createToken(source, TOKEN_TYPES.CODE, codeStart, end));
+        }
+    };
+
+    const pushProtected = (type, start, end) => {
+        pushCode(start);
+        tokens.push(createToken(source, type, start, end));
+        codeStart = end;
+        index = end;
+    };
+
+    while (index < source.length) {
+        const char = source[index];
+        const next = source[index + 1];
+
+        if (char === "/" && next === "/") {
+            pushProtected(TOKEN_TYPES.LINE_COMMENT, index, readLineComment(source, index));
+            continue;
+        }
+
+        if (char === "/" && next === "*") {
+            pushProtected(TOKEN_TYPES.BLOCK_COMMENT, index, readBlockComment(source, index));
+            continue;
+        }
+
+        if (char === "'" || char === '"') {
+            const type = char === "'" ? TOKEN_TYPES.STRING_SINGLE : TOKEN_TYPES.STRING_DOUBLE;
+            pushProtected(type, index, readQuoted(source, index, char));
+            continue;
+        }
+
+        if (char === "`") {
+            pushProtected(TOKEN_TYPES.TEMPLATE, index, readTemplate(source, index));
+            continue;
+        }
+
+        if (char === "/" && isRegexAllowedAfter(previousNonWhitespace)) {
+            pushProtected(TOKEN_TYPES.REGEX, index, readRegex(source, index));
+            continue;
+        }
+
+        if (!/\s/.test(char)) {
+            previousNonWhitespace = char;
+        }
+
+        index++;
+    }
+
+    pushCode(source.length);
+    return tokens;
+}
+
+module.exports = {
+    TOKEN_TYPES,
+    tokenizeSource,
+};

package/src/diagnostics/index.js

@@ -0,0 +1,45 @@
+const DiagnosticSeverity = {
+    INFO: "info",
+    WARNING: "warning",
+    ERROR: "error",
+};
+
+function createSourceLocation(line = 1, column = 1, index = 0) {
+    return { line, column, index };
+}
+
+function createDiagnostic({
+    code,
+    message,
+    severity = DiagnosticSeverity.ERROR,
+    file = null,
+    start = createSourceLocation(),
+    end = start,
+    hint = null,
+}) {
+    return {
+        code,
+        message,
+        severity,
+        file,
+        start,
+        end,
+        hint,
+    };
+}
+
+function formatDiagnostic(diagnostic) {
+    const location = diagnostic.file
+        ? `${diagnostic.file}:${diagnostic.start.line}:${diagnostic.start.column}`
+        : `line ${diagnostic.start.line}, column ${diagnostic.start.column}`;
+
+    const hint = diagnostic.hint ? `\nHint: ${diagnostic.hint}` : "";
+    return `[${diagnostic.severity}] ${diagnostic.code} at ${location}: ${diagnostic.message}${hint}`;
+}
+
+module.exports = {
+    createDiagnostic,
+    createSourceLocation,
+    DiagnosticSeverity,
+    formatDiagnostic,
+};

package/src/language/keywords.js

@@ -0,0 +1,209 @@
+const hindiToJS = {
+    // Multi-word phrases FIRST (longest -> shortest to avoid partial matches)
+    "नहीं तो": "else",
+    "अन्यथा": "else",
+    "के रूप में": "as",
+    "का प्रकार": "typeof",
+    "नया बनाओ": "new",
+    "कम या बराबर": "<=",
+    "ज्यादा या बराबर": ">=",
+    "बराबर नहीं": "!==",
+
+    // Control flow
+    "अगर": "if",
+    "वरना": "else",
+    "करो": "do",
+    "जबतक": "while",
+    "केलिए": "for",
+    "स्विच": "switch",
+    "मामला": "case",
+    "रोकें": "break",
+    "जारी": "continue",
+    "लौटाओ": "return",
+    "फेंको": "throw",
+
+    // Declarations
+    "नया": "let",
+    "स्थिर": "const",
+    "पुराना": "var",
+    "कार्य": "function",
+    "वर्ग": "class",
+
+    // Async
+    "असिंक": "async",
+    "इंतज़ार": "await",
+
+    // Literals
+    "सच": "true",
+    "सत्य": "true",
+    "झूठ": "false",
+    "असत्य": "false",
+    "खाली": "null",
+    "अपरिभाषित": "undefined",
+
+    // OOP
+    "विस्तार": "extends",
+    "सुपर": "super",
+    "यह": "this",
+    "हटाओ": "delete",
+    "प्रोटो": "prototype",
+    "में": "in",
+    "सत्यापित": "instanceof",
+    "वापसी": "yield",
+
+    // Modules
+    "आयात": "import",
+    "निर्यात": "export",
+    "डिफ़ॉल्ट": "default",
+    "डिफॉल्ट": "default",
+    "से": "from",
+    "मांगो": "require",
+    "अनुरोध": "require",
+    "मॉड्यूल": "module",
+
+    // Operators
+    "और": "&&",
+    "या": "||",
+    "नहीं": "!",
+    "बराबर": "===",
+    "छोटा": "<",
+    "बड़ा": ">",
+
+    // Error handling
+    "कोशिश": "try",
+    "पकड़ो": "catch",
+    "पकड़": "catch",
+    "अंततः": "finally",
+    "त्रुटि": "Error",
+
+    // Console
+    "दिखाओ": "console.log",
+    "गलती": "console.error",
+    "चेतावनी": "console.warn",
+    "जानकारी": "console.info",
+    "कंसोल": "console",
+
+    // Array methods
+    "पुश": "push",
+    "पॉप": "pop",
+    "शिफ्ट": "shift",
+    "अनशिफ्ट": "unshift",
+    "स्लाइस": "slice",
+    "जोड़ो": "concat",
+    "शामिल": "includes",
+    "ढूँढो": "find",
+    "मानचित्र": "map",
+    "फ़िल्टर": "filter",
+    "कमकरो": "reduce",
+    "हरएक": "forEach",
+    "लंबाई": "length",
+    "लम्बाई": "length",
+    "इंडेक्स": "indexOf",
+    "उलटाओ": "reverse",
+    "क्रमित": "sort",
+
+    // Object methods
+    "कुंजियाँ": "keys",
+    "मूल्य": "values",
+    "प्रविष्टियाँ": "entries",
+    "बनाएँ": "create",
+    "मिलाओ": "assign",
+    "जमाओ": "freeze",
+
+    // Map / Set
+    "नक्शा": "Map",
+    "है": "has",
+    "प्राप्त": "get",
+    "रखो": "set",
+    "साफ़": "clear",
+    "आकार": "size",
+    "डालो": "add",
+
+    // Promise
+    "फिर": "then",
+    "सभी": "all",
+    "हल": "resolve",
+    "अस्वीकार": "reject",
+    "प्रॉमिस": "Promise",
+
+    // Browser APIs
+    "विंडो": "window",
+    "दस्तावेज": "document",
+    "दस्तावेज़": "document",
+    "ब्राउज़र": "navigator",
+    "स्थान": "location",
+    "इतिहास": "history",
+    "संग्रह": "localStorage",
+    "सत्र_संग्रह": "sessionStorage",
+    "चेतावनी_डिब्बा": "alert",
+    "पूछो": "prompt",
+    "पक्का_करो": "confirm",
+    "लाओ": "fetch",
+    "समय_बाद": "setTimeout",
+    "बार_बार": "setInterval",
+    "समय_रोकें": "clearTimeout",
+    "बार_रोकें": "clearInterval",
+    "तत्व_ढूँढो_आईडी_से": "getElementById",
+    "तत्व_ढूँढो": "querySelector",
+    "सभी_तत्व_ढूँढो": "querySelectorAll",
+    "घटना_सुनो": "addEventListener",
+    "तत्व_बनाओ": "createElement",
+    "बच्चा_जोड़ो": "appendChild",
+
+    // Node.js
+    "प्रक्रिया": "process",
+    "__नाम": "__filename",
+    "__डायरेक्टरी": "__dirname",
+    "बफर": "Buffer",
+
+    // Built-ins
+    "ऑब्जेक्ट": "Object",
+    "ऐरे": "Array",
+    "सेट": "Set",
+    "स्ट्रिंग": "String",
+    "टेक्स्ट": "String",
+    "नंबर": "Number",
+    "बूलियन": "Boolean",
+    "डेट": "Date",
+    "तारीख": "Date",
+    "गणित": "Math",
+    "जेसन": "JSON",
+    "जेसन_डेटा": "json",
+    "जीसन": "JSON",
+    "जोड़ें": "join",
+    "रेगएक्स": "RegExp",
+    "अनंत": "Infinity",
+
+    // Math shortcuts
+    "गोलाई": "Math.round",
+    "ऊपर": "Math.ceil",
+    "नीचे": "Math.floor",
+    "अधिकतम": "Math.max",
+    "न्यूनतम": "Math.min",
+    "यादृच्छ": "Math.random",
+    "वर्गमूल": "Math.sqrt",
+    "पाई": "Math.PI",
+
+    // JSON shortcuts
+    "पार्स": "JSON.parse",
+    "तार_बनाओ": "JSON.stringify",
+
+    // String methods
+    "बड़े_अक्षर": "toUpperCase",
+    "छोटे_अक्षर": "toLowerCase",
+    "काटो": "trim",
+    "विभाजन": "split",
+    "बदलो": "replace",
+    "खोजो": "search",
+    "शुरू_से": "startsWith",
+    "खत्म_से": "endsWith",
+    "दोहराओ": "repeat",
+    "हिस्सा": "substring",
+};
+
+const sortedKeywords = Object.keys(hindiToJS).sort((a, b) => b.length - a.length);
+
+module.exports = {
+    hindiToJS,
+    sortedKeywords,
+};

package/src/parser/index.js

@@ -0,0 +1,66 @@
+const { TOKEN_TYPES } = require("../compiler/tokenizer");
+const { sortedKeywords, hindiToJS } = require("../language/keywords");
+
+function escapeForRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const keywordRegex = new RegExp(
+    `(?<![\\u0900-\\u097F\\w$])(?:${sortedKeywords.map(escapeForRegex).join("|")})(?![\\u0900-\\u097F\\w$])`,
+    "g"
+);
+
+function transformCodeSegment(code) {
+    return code.replace(keywordRegex, (match) => hindiToJS[match] || match);
+}
+
+function transformTokens(tokens, recursiveTransform) {
+    return tokens
+        .map((token) => {
+            if (token.type === TOKEN_TYPES.CODE) {
+                return transformCodeSegment(token.value);
+            }
+
+            if (token.type === TOKEN_TYPES.TEMPLATE) {
+                return token.value.replace(/\${([\s\S]*?)}/g, (fullMatch, expression) => {
+                    return `${"$"}{${recursiveTransform(expression)}}`;
+                });
+            }
+
+            return token.value;
+        })
+        .join("");
+}
+
+function createParseResult({ source, tokens, transformedCode, filename = null }) {
+    return {
+        source,
+        tokens,
+        transformedCode,
+        ast: null,
+        diagnostics: [],
+        strategy: "token-transform",
+        meta: {
+            filename,
+            parserStage: "phase-one-token-transform",
+        },
+    };
+}
+
+function parseSource({ source, tokens, recursiveTransform, filename = null }) {
+    const transformedCode = transformTokens(tokens, recursiveTransform);
+
+    return createParseResult({
+        source,
+        tokens,
+        transformedCode,
+        filename,
+    });
+}
+
+module.exports = {
+    createParseResult,
+    parseSource,
+    transformCodeSegment,
+    transformTokens,
+};

package/src/runtime/register.js

@@ -0,0 +1,24 @@
+const fs = require("fs");
+const { compileHindiJS } = require("../compiler/compile");
+const { formatDiagnostic } = require("../diagnostics");
+
+function registerHindiExtension() {
+    require.extensions[".hindi.js"] = function loadHindiModule(module, filename) {
+        try {
+            const content = fs.readFileSync(filename, "utf8").trim();
+            const compiled = compileHindiJS(content, { filename, mode: "runtime" });
+            module._compile(compiled.code, filename);
+        } catch (error) {
+            if (error && error.code && error.message) {
+                console.error("❌ Hindi Transpiler Error:", formatDiagnostic(error));
+            } else {
+                console.error("❌ Hindi Transpiler Error:", error);
+            }
+            throw error;
+        }
+    };
+}
+
+module.exports = {
+    registerHindiExtension,
+};