@ugo-studio/jspp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emmanuel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# JSPP (JavaScript++)
+
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/ugo-studio/jspp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**JSPP is a modern, experimental transpiler that converts JavaScript code into high-performance, standard C++23.**
+
+The primary goal of this project is to achieve a near-perfect translation of JavaScript's dynamic nature and core features into the statically-typed, compiled world of C++, exploring modern C++ capabilities to bridge the gap between these two powerful languages.
+
+## About The Project
+
+JavaScript is flexible and dynamic; C++ is performant and type-safe. JSPP aims to offer the best of both worlds. By transpiling JS to C++, we can potentially run JavaScript logic in environments where C++ is native, with significant performance gains and opportunities for low-level interoperability.
+
+This project serves as a deep dive into compiler design, language semantics, and the expressive power of modern C++. The current implementation translates an entire JavaScript file into a single C++ `main` function, cleverly using `std::shared_ptr<std::any>` to replicate JavaScript's dynamic typing, garbage-collection-like memory management, and complex features like closures.
+
+## Features
+
+JSPP currently supports a foundational set of JavaScript features:
+
+- **Dynamic Variables:** Declaration (`let`, `const` and `var`), assignment, and type changes at runtime.
+- **Primitive Types:** `undefined`, `null`, `boolean`, `number`, `string`, `object` and `array`.
+- **Functions:**
+  - Function declarations and arrow functions.
+  - Correct hoisting for both variables and functions.
+  - Closures with proper lexical scoping and lifetime management.
+- **Operators:** All arithmetic (`+`, `-`, `*`) and assignment (`=`) operators.
+- **Control Flow:** `void` operator.
+- **Built-in APIs:** A `console` object with `log()`, `warn()`, `error()`, and `time()` methods.
+
+## Reserved Keywords
+
+JSPP reserves certain keywords to avoid conflicts with the generated C++ code and internal mechanisms. The following keywords are reserved and cannot be used as variable names:
+
+- `std`: Reserved to prevent conflicts with the C++ standard library namespace.
+- `jspp`: Reserved for internal use by the JSPP transpiler.
+
+Using these keywords as variable names will result in a `SyntaxError`.
+
+## How It Works
+
+The transpilation process is a classic three-stage pipeline:
+
+1.  **Parsing:** The incoming JavaScript code is parsed into an Abstract Syntax Tree (AST) using the powerful TypeScript compiler API. This gives us a structured, traversable representation of the code.
+
+2.  **Analysis:** The `TypeAnalyzer` traverses the AST. While it doesn't perform traditional static type checking, it plays a crucial role in understanding the code's structure. It identifies scopes (global, function, block) and detects when variables are "captured" by closures.
+
+3.  **Code Generation:** The `CodeGenerator` performs a final traversal of the AST. It translates each node into its C++ equivalent.
+    - All variables are declared as `std::shared_ptr<AnyValue>` (where `AnyValue` uses a [Tagged Union](https://en.wikipedia.org/wiki/Tagged_union) system for managing dynamic types like JavaScript). This approach elegantly mimics JavaScript's dynamic types and reference-based memory model.
+    - Closures are implemented as C++ lambdas that capture `shared_ptr`s by value, ensuring variable lifetimes are correctly extended beyond their original scope.
+    - The entire script is wrapped into a single `main` function, with hoisting logic carefully replicated to ensure correct execution order.
+
+## Installation
+
+To use JSPP as a command-line tool, install it globally via npm:
+
+```sh
+npm install -g  @ugo-studio/jspp
+```
+
+## For Developers
+
+To contribute to JSPP or run its test suite, follow these steps:
+
+### Prerequisites
+
+- **Bun:** This project uses Bun for package management and script execution.
+  - [Install Bun](https://bun.sh/docs/installation)
+- **C++ Compiler:** A compiler with support for C++23 is required. This project is tested with `g++`.
+  - `g++` (MinGW on Windows, or available via build-essentials on Linux)
+
+### Setup
+
+1.  Clone the repo:
+    ```sh
+    git clone https://github.com/ugo-studio/jspp.git
+    ```
+2.  Install dependencies:
+    ```sh
+    bun install
+    ```
+
+## Usage
+
+The primary way to use JSPP is via its command-line interface. This will transpile your `.js` file to C++, compile it, and execute the resulting binary.
+
+```sh
+jspp <path-to-your-js-file>
+```
+
+**Example:**
+
+To run a sample JavaScript file located at `my-code/hello.js`:
+
+```sh
+jspp my-code/hello.js
+```
+
+The transpiled C++ file and executable will be generated in the same directory as the input file and cleaned up after execution.
+
+You can also run the test suite, which will transpile all the JavaScript test cases in `test/cases/`, build the resulting C++ files, and run them.
+
+```sh
+bun run test
+```
+
+## Roadmap
+
+This project is ambitious, and there is a long and exciting road ahead. Here is a high-level overview of the planned features and the project's current standing.
+
+---
+
+### **Phase 1: Core Language Features**
+
+This phase focuses on building a solid foundation that correctly models JavaScript's core runtime behavior.
+
+- [x] Dynamic Variables & Primitives (`let`, `const`, `var`, `undefined`, `null`, `string`, `number`, `boolean`, etc.)
+- [x] Function Declarations & Arrow Functions
+- [x] Correct Hoisting for Variables and Functions
+- [x] Closures & Lexical Scoping (via `std::shared_ptr` capture)
+- [x] `if-elseif-else` conditions
+- [x] Basic `console` API
+
+---
+
+### **Phase 2: Expanded Language Support**
+
+This phase will broaden the range of supported JavaScript syntax and features.
+
+- [x] **Error Handling**: `try`/`catch`/`finally` blocks and `throw`.
+- [x] **Objects:** Literals, property access (dot and bracket notation), methods.
+- [x] **Arrays:** Literals, indexing, and core methods (`.push`, `.pop`, `.length`, etc.).
+- [x] **Operators:** Full suite of arithmetic, logical, and comparison operators.
+- [ ] **Control Flow:** tenary operators, `for` loops, `while` loops, `switch`.
+
+### **Phase 3: Interoperability & Standard Library**
+
+This phase will focus on building out the standard library and enabling modular code.
+
+- [ ] **JS Standard Library:** Implementation of common built-in objects and functions (`Math`, `Date`, `String.prototype.*`, `Array.prototype.*`).
+- [ ] **Module System:** Support for `import` and `export` to transpile multi-file projects.
+- [ ] **Asynchronous Operations:** A C++ implementation of the JavaScript event loop, `Promise`, and `async/await`.
+
+### **Phase 4: Optimization & Advanced Features**
+
+With a feature-complete transpiler, the focus will shift to performance and advanced capabilities.
+
+- [ ] **Performance Benchmarking:** Create a suite to compare transpiled C++ performance against V8 and other JS engines.
+- [ ] **C++ Interoperability:** Define a clear API for calling C++ functions from the transpiled JavaScript and vice-versa.
+
+## Contributing
+
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+1.  Fork the Project
+2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4.  Push to the Branch (`git push origin feature/AmazingFeature`)
+5.  Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

package/dist/analysis/scope.js

@@ -0,0 +1,77 @@
+const RESERVED_KEYWORDS = ["std", "jspp"];
+// Represents a single scope (e.g., a function body or a block statement)
+export class Scope {
+    parent;
+    symbols = new Map();
+    constructor(parent) {
+        this.parent = parent;
+    }
+    // Defines a variable in this scope.
+    define(name, type) {
+        if (this.symbols.has(name)) {
+            return false; // Already defined in this scope
+        }
+        this.symbols.set(name, type);
+        return true;
+    }
+    // Finds the scope where a variable is defined, walking up the chain.
+    findScopeFor(name) {
+        if (this.symbols.has(name)) {
+            return this;
+        }
+        return this.parent ? this.parent.findScopeFor(name) : null;
+    }
+}
+// Manages the hierarchy of scopes during analysis.
+export class ScopeManager {
+    currentScope;
+    allScopes = []; // Array to store all created scopes
+    reservedKeywords = new Set(RESERVED_KEYWORDS);
+    constructor() {
+        const rootScope = new Scope(null); // The global scope
+        this.currentScope = rootScope;
+        this.allScopes.push(rootScope); // Add the root scope to our list
+        this.define("undefined", {
+            type: "undefined",
+            isConst: true,
+            isBuiltin: true,
+        });
+        this.define("null", {
+            type: "null",
+            isConst: true,
+            isBuiltin: true,
+        });
+    }
+    // Enters a new, nested scope.
+    enterScope() {
+        const newScope = new Scope(this.currentScope);
+        this.currentScope = newScope;
+        this.allScopes.push(newScope); // Add every new scope to the list
+    }
+    // Exits the current scope, returning to the parent.
+    exitScope() {
+        if (this.currentScope.parent) {
+            this.currentScope = this.currentScope.parent;
+        }
+    }
+    // Defines a variable in the current scope.
+    define(name, type) {
+        if (this.reservedKeywords.has(name) && !type.isBuiltin) {
+            throw new Error(`SyntaxError: Unexpected reserved word "${name}"`);
+        }
+        this.currentScope.define(name, type);
+    }
+    // Looks up a variable's type information from the current scope upwards.
+    lookup(name) {
+        const scope = this.currentScope.findScopeFor(name);
+        return scope ? scope.symbols.get(name) ?? null : null;
+    }
+    lookupFromScope(name, scope) {
+        const definingScope = scope.findScopeFor(name);
+        return definingScope ? definingScope.symbols.get(name) ?? null : null;
+    }
+    // The missing method to retrieve all scopes for the generator.
+    getAllScopes() {
+        return this.allScopes;
+    }
+}

package/dist/analysis/typeAnalyzer.js

@@ -0,0 +1,224 @@
+import * as ts from "typescript";
+import { Traverser } from "../core/traverser";
+import { Scope, ScopeManager } from "./scope";
+export class TypeAnalyzer {
+    traverser = new Traverser();
+    scopeManager = new ScopeManager();
+    functionTypeInfo = new Map();
+    functionStack = [];
+    nodeToScope = new Map();
+    analyze(ast) {
+        this.nodeToScope.set(ast, this.scopeManager.currentScope);
+        const visitor = {
+            // Enter new scope for any block-like structure
+            Block: {
+                enter: (node, parent) => {
+                    this.scopeManager.enterScope();
+                    this.nodeToScope.set(node, this.scopeManager.currentScope);
+                    if (parent && ts.isCatchClause(parent) &&
+                        parent.variableDeclaration) {
+                        if (ts.isIdentifier(parent.variableDeclaration.name)) {
+                            const name = parent.variableDeclaration.name
+                                .getText();
+                            // The type is basically 'any' or 'string' from the .what()
+                            const typeInfo = {
+                                type: "string",
+                                declaration: parent.variableDeclaration,
+                            };
+                            this.scopeManager.define(name, typeInfo);
+                        }
+                        // TODO: handle binding patterns in catch clause
+                    }
+                },
+                exit: () => this.scopeManager.exitScope(),
+            },
+            ForStatement: {
+                enter: (node) => {
+                    this.scopeManager.enterScope();
+                    this.nodeToScope.set(node, this.scopeManager.currentScope);
+                },
+                exit: () => this.scopeManager.exitScope(),
+            },
+            ForOfStatement: {
+                enter: (node) => {
+                    this.scopeManager.enterScope();
+                    this.nodeToScope.set(node, this.scopeManager.currentScope);
+                },
+                exit: () => this.scopeManager.exitScope(),
+            },
+            ForInStatement: {
+                enter: (node) => {
+                    this.scopeManager.enterScope();
+                    this.nodeToScope.set(node, this.scopeManager.currentScope);
+                    const forIn = node;
+                    if (ts.isVariableDeclarationList(forIn.initializer)) {
+                        const varDecl = forIn.initializer.declarations[0];
+                        if (varDecl) {
+                            const name = varDecl.name.getText();
+                            const isConst = (varDecl.parent.flags & ts.NodeFlags.Const) !== 0;
+                            const typeInfo = {
+                                type: "string", // Keys are always strings
+                                declaration: varDecl,
+                                isConst,
+                            };
+                            this.scopeManager.define(name, typeInfo);
+                        }
+                    }
+                    else if (ts.isIdentifier(forIn.initializer)) {
+                        // If it's an existing identifier, we don't redefine it, but ensure it's in scope.
+                        // The generator will handle assigning to it.
+                    }
+                },
+                exit: () => this.scopeManager.exitScope(),
+            },
+            ArrowFunction: {
+                enter: (node) => {
+                    if (ts.isArrowFunction(node)) {
+                        const funcType = {
+                            type: "function",
+                            isClosure: false,
+                            captures: new Map(),
+                        };
+                        this.functionTypeInfo.set(node, funcType);
+                        this.scopeManager.enterScope();
+                        this.nodeToScope.set(node, this.scopeManager.currentScope);
+                        // Define parameters in the new scope
+                        node.parameters.forEach((p) => this.scopeManager.define(p.name.getText(), {
+                            type: "auto",
+                            isParameter: true,
+                            declaration: p,
+                        }));
+                        this.functionStack.push(node);
+                    }
+                },
+                exit: (node) => {
+                    if (ts.isArrowFunction(node)) {
+                        this.functionStack.pop();
+                    }
+                    this.scopeManager.exitScope();
+                },
+            },
+            FunctionExpression: {
+                enter: (node) => {
+                    if (ts.isFunctionExpression(node)) {
+                        const funcType = {
+                            type: "function",
+                            isClosure: false,
+                            captures: new Map(),
+                            declaration: node,
+                        };
+                        this.functionTypeInfo.set(node, funcType);
+                        this.scopeManager.enterScope();
+                        this.nodeToScope.set(node, this.scopeManager.currentScope);
+                        // If the function expression is named, define the name within its own scope for recursion.
+                        if (node.name) {
+                            this.scopeManager.define(node.name.getText(), funcType);
+                        }
+                        // Define parameters in the new scope
+                        node.parameters.forEach((p) => this.scopeManager.define(p.name.getText(), {
+                            type: "auto",
+                            isParameter: true,
+                            declaration: p,
+                        }));
+                        this.functionStack.push(node);
+                    }
+                },
+                exit: (node) => {
+                    if (ts.isFunctionExpression(node)) {
+                        this.functionStack.pop();
+                    }
+                    this.scopeManager.exitScope();
+                },
+            },
+            FunctionDeclaration: {
+                enter: (node) => {
+                    if (ts.isFunctionDeclaration(node)) {
+                        // Define the function in the current scope.
+                        if (node.name) {
+                            const funcName = node.name.getText();
+                            const funcType = {
+                                type: "function",
+                                isClosure: false,
+                                captures: new Map(),
+                                declaration: node,
+                            };
+                            this.scopeManager.define(funcName, funcType);
+                            this.functionTypeInfo.set(node, funcType);
+                        }
+                        this.scopeManager.enterScope();
+                        this.nodeToScope.set(node, this.scopeManager.currentScope);
+                        // Define parameters in the new scope
+                        node.parameters.forEach((p) => this.scopeManager.define(p.name.getText(), {
+                            type: "auto",
+                            isParameter: true,
+                            declaration: p,
+                        }));
+                        this.functionStack.push(node);
+                    }
+                },
+                exit: (node) => {
+                    if (ts.isFunctionDeclaration(node)) {
+                        this.functionStack.pop();
+                    }
+                    this.scopeManager.exitScope();
+                },
+            },
+            VariableDeclaration: {
+                enter: (node) => {
+                    if (ts.isVariableDeclaration(node)) {
+                        const name = node.name.getText();
+                        const isConst = (node.parent.flags & ts.NodeFlags.Const) !== 0;
+                        let type = "auto";
+                        if (node.initializer) {
+                            if (ts.isArrayLiteralExpression(node.initializer)) {
+                                type = "array";
+                            }
+                        }
+                        const typeInfo = {
+                            type,
+                            declaration: node,
+                            isConst,
+                        };
+                        this.scopeManager.define(name, typeInfo);
+                    }
+                },
+            },
+            Identifier: {
+                enter: (node, parent) => {
+                    if (ts.isIdentifier(node)) {
+                        if (node.text === "console") {
+                            return;
+                        }
+                        const currentFuncNode = this.functionStack[this.functionStack.length - 1];
+                        if (currentFuncNode &&
+                            (ts.isFunctionDeclaration(currentFuncNode) ||
+                                ts.isFunctionExpression(currentFuncNode)) &&
+                            node.text === currentFuncNode.name?.getText()) {
+                            return; // Don't treat recursive call as capture
+                        }
+                        // Check if this identifier is being used as a variable (not a function name, etc.)
+                        // And see if it belongs to an outer scope
+                        const definingScope = this.scopeManager.currentScope
+                            .findScopeFor(node.text);
+                        if (definingScope &&
+                            definingScope !== this.scopeManager.currentScope) {
+                            // This is a potential capture!
+                            // Find which function we are currently in and mark the capture.
+                            if (currentFuncNode) {
+                                const type = this.scopeManager.lookup(node.text);
+                                if (type) {
+                                    const info = this.functionTypeInfo.get(currentFuncNode);
+                                    if (info) {
+                                        info.isClosure = true;
+                                        info.captures?.set(node.text, type);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+            },
+        };
+        this.traverser.traverse(ast, visitor);
+    }
+}

package/dist/ast/types.js

@@ -0,0 +1 @@
+import * as ts from "typescript";

package/dist/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+import fs from "fs/promises";
+import path from "path";
+import { Interpreter } from "./index";
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.error("Usage: jspp <path-to-js-file>");
+        process.exit(1);
+    }
+    const jsFilePath = path.resolve(process.cwd(), args[0]);
+    const jsFileName = path.basename(jsFilePath, ".js");
+    const outputDir = path.dirname(jsFilePath);
+    const cppFilePath = path.join(outputDir, `${jsFileName}.cpp`);
+    const exeFilePath = path.join(outputDir, `${jsFileName}.exe`);
+    try {
+        const jsCode = await fs.readFile(jsFilePath, "utf-8");
+        const interpreter = new Interpreter();
+        const { cppCode, preludePath } = interpreter.interpret(jsCode);
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.writeFile(cppFilePath, cppCode);
+        console.log(`Compiling ${cppFilePath}...`);
+        const compile = Bun.spawnSync({
+            cmd: [
+                "g++",
+                "-std=c++20",
+                cppFilePath,
+                "-o",
+                exeFilePath,
+                "-I",
+                preludePath,
+                "-O2",
+                "-DNDEBUG",
+                // "-include",
+                // path.join(process.cwd(), "prelude-build", "index.hpp"),
+            ],
+            stdout: "inherit",
+            stderr: "inherit",
+        });
+        if (compile.exitCode !== 0) {
+            console.error(`Compilation failed for ${jsFileName}.js`);
+            process.exit(1);
+        }
+        console.log(`Running ${exeFilePath}...`);
+        console.log("\x1b[32m\n------start------\x1b[0m");
+        const run = Bun.spawnSync({
+            cmd: [exeFilePath],
+            stdout: "inherit",
+            stderr: "inherit",
+        });
+        console.log("\x1b[32m\n------end--------\x1b[0m");
+        if (run.exitCode !== 0) {
+            console.error(`Execution failed for ${jsFileName}.js`);
+            process.exit(1);
+        }
+        console.log(`Successfully ran ${jsFileName}.js`);
+    }
+    catch (error) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+main();

package/dist/core/codegen/declaration-handlers.js

@@ -0,0 +1,49 @@
+import ts from "typescript";
+import { CodeGenerator } from "./";
+export function visitVariableDeclarationList(node, context) {
+    return node.declarations
+        .map((d) => this.visit(d, context))
+        .filter(Boolean)
+        .join(", ");
+}
+export function visitVariableDeclaration(node, context) {
+    const varDecl = node;
+    const name = varDecl.name.getText();
+    let initializer = "";
+    if (varDecl.initializer) {
+        const initExpr = varDecl.initializer;
+        let initText = this.visit(initExpr, context);
+        if (ts.isIdentifier(initExpr)) {
+            const scope = this.getScopeForNode(initExpr);
+            const typeInfo = this.typeAnalyzer.scopeManager.lookupFromScope(initExpr.text, scope);
+            const varName = this.getJsVarName(initExpr);
+            if (typeInfo && !typeInfo.isParameter && !typeInfo.isBuiltin) {
+                initText = `jspp::Access::deref(${initText}, ${varName})`;
+            }
+        }
+        initializer = " = " + initText;
+    }
+    const isLetOrConst = (varDecl.parent.flags & (ts.NodeFlags.Let | ts.NodeFlags.Const)) !== 0;
+    if (isLetOrConst) {
+        // If there's no initializer, it should be assigned undefined.
+        if (!initializer)
+            return `*${name} = jspp::AnyValue::make_undefined()`;
+        return `*${name}${initializer}`;
+    }
+    // For 'var', it's a bit more complex.
+    // If we are in a non-function-body block, 'var' is hoisted, so it's an assignment.
+    // If we are at the top level or in a function body, it's a declaration if not already hoisted.
+    // The current logic hoists at the function level, so we need to decide if this is the *hoisting* declaration or a later assignment.
+    // The `isAssignmentOnly` flag helps here.
+    if (context.isAssignmentOnly) {
+        if (!initializer)
+            return "";
+        return `*${name}${initializer}`;
+    }
+    else {
+        const initValue = initializer
+            ? initializer.substring(3)
+            : "jspp::AnyValue::make_undefined()";
+        return `auto ${name} = std::make_shared<jspp::AnyValue>(${initValue})`;
+    }
+}