SESI PROGRAMMING LANGUAGE DOCS
⌕

Contributing to Sesi

First off, thank you for considering contributing to Sesi! Sesi is building natively concise programming layers, and community contributions are incredibly valuable.

Setting Up Your Development Environment

To start developing Sesi locally, you'll need Node.js and TypeScript installed.

  1. Clone the repository:

bash

git clone https://github.com/Misterscan/sesi.git

cd Sesi

  1. Install dependencies:

bash

npm install

  1. Build the project:

The Sesi core is written in TypeScript. You must compile it to generate the executable engine.

bash

npm run build

  1. Install the CLI globally (optional but recommended):

bash

npm install -g .

Now you can use the sesi command anywhere.

  1. Set up your environment variables:

Create a .env file in the root directory for Gemini access:

env

GEMINI_API_KEY="your_api_key_here"

Understanding the Architecture

Before making changes, we highly recommend reading the following documentation:

Core Guidelines

  • AST Modifications: If you add syntax, you must update src/lexer.ts, src/parser.ts, and src/types.ts. Then update src/compiler.ts to emit the correct OpCodes for the new construct. Only modify src/interpreter.ts if the construct is not yet handled by the compiler (fallback path).
  • TypeScript Settings: Do not remove import { type ... } statements, as they are mandatory for type narrowing.
  • VM & Compiler Logic: The compiler (compiler.ts) performs a single-pass AST lowering; the VM (vm.ts) dispatches OpCode instructions. Keep these two in sync when adding new language constructs.
  • Interpreter Logic (Fallback): The tree-walking interpreter in interpreter.ts uses dynamic casting and any types by design. This is intentional for functional execution; do not attempt to "clean up" the dynamic any casts in the interpreter core.

Testing Your Changes

Testing in Sesi involves both internal TypeScript testing and Sesi script execution.

  1. Run Unit Tests: The core engine logic is tested via automated TypeScript tests found in the tests/ directory

bash

npm test

  1. Run Sesi Integration Scripts: After making a change, rebuild the project and run the testing scripts inside the main/tests/ or examples/ directories to verify feature behavior end-to-end:

bash

npm run build

sesi examples/main/01_hello.sesi

sesi main/tests/test_syntax.sesi

Creating & Importing Third-Party Sesi Libraries

Sesi has built-in support for sharing and importing third-party libraries using a git-centric, zero-registry package system.

1. Sesi Package Structure

To build a Sesi library that can be imported by other developers:

  • Entry point: Your repository must expose one of these two main entry points in the root directory:

- index.sesi (Recommended)

- main.sesi

  • Exports: Ensure all variables, configurations, or functions you wish to share are marked with the export keyword:

sesi

export let lib_version = "1.0.0"

export fn compute(val) {

return val * 10

}

2. Hosting & Versioning

Since Sesi uses direct Git resolution:

  1. Publish your library source code to a public Git repository (e.g
  2. Create Git tags or releases (e.g., v1.0.0, v1.1.0) so users can pin specific versions of your library.

3. Installing & Importing Packages

Developers can import your library inside their projects as follows:

  • Install:

bash

sesi install username/repo#ref

This creates/updates sesi.json and extracts the library into sesi_modules/repo.

  • Import:

sesi

allow "repo" in as MyLib

show MyLib.compute(42)

Submitting a Pull Request

  1. Fork the repository and create your branch from main.
  2. Ensure you have run npm run build to verify your TypeScript compiles.
  3. Write Unit Tests: If you are adding a new core feature, built-in, or fixing a bug, you must write automated TypeScript unit tests in the tests/ directory to cover your logic.
  4. Write Integration Scripts: Write or update .sesi test scripts in main/tests/ to demonstrate your feature or bug fix functioning end-to-end.
  5. Follow standard conventional commits for your commit messages.
  6. Create a descriptive Pull Request explaining the why and how of your changes

Issues and Feature Requests

If you find a bug or have a proposal for the language's roadmap, please open an issue. Provide as much context as possible, including system details, error output, and stripped-down reproducible .sesi scripts!