@user-synax/synax 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synax contributors
+
+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,91 @@
+# Synax
+
+Synax is a custom scripting language that transpiles to JavaScript. You write
+Synax source; the `synax` CLI compiles it down to plain, readable JavaScript.
+
+The language is still being designed — the authoritative description of its
+grammar and semantics lives in [SPEC.md](./SPEC.md). There is also
+[synax.html](./synax.html): a single-file docs page with a live in-browser
+playground (the whole compiler is inlined — open it, no server needed).
+
+## Status
+
+The pipeline is implemented end to end: source is lexed, parsed into an AST, and
+compiled to JavaScript. See SPEC.md §9 for what is deliberately out of scope.
+
+Two semantics were decided while building the code generator:
+
+- `for i in 1..5` is **inclusive** of the upper bound (compiles to `i <= 5`).
+- `+` keeps JavaScript's coercion, so `"n=" + 5` concatenates rather than
+erroring.
+
+## Requirements
+
+- [Bun](https://bun.sh) — package manager, test runner, and runtime
+
+No external dependencies are used; everything runs on the Bun standard library.
+
+## Install
+
+The package ships a `synax` binary and a typed library API:
+
+```sh
+bun add synax          # or: npm install synax
+```
+
+Compile a file with the CLI:
+
+```sh
+synax program.snx                # prints JavaScript to stdout
+synax examples/loop.snx          # ships with the package
+```
+
+Or use it from code:
+
+```ts
+import { generate, Lexer, Parser } from "synax";
+
+const source = 'print "Hello, World!"';
+const js = generate(new Parser(new Lexer(source).tokenize()).parse());
+```
+
+## Getting started (from source)
+
+```sh
+bun install                       # install dependencies (none yet)
+bun test                          # run the test suite
+bun run src/cli.ts <file>         # compile a Synax source file to stdout
+bun run src/cli.ts examples/loop.snx
+bun run build                     # bundle the CLI and library into dist/
+bun run docs                      # regenerate synax.html (docs + playground)
+```
+
+The compiler prints JavaScript to stdout and diagnostics to stderr, exiting
+non-zero on a lexer, parser, or file error, so it works in a shell pipeline.
+Diagnostics point at the source:
+
+```
+examples/bad.snx:1:7: error: Unexpected character "@"
+  1 | print @
+    |       ^
+```
+
+Set `SYNAX_DEBUG=1` to include a stack trace for an internal compiler error.
+
+There is also a `bun run build` script that bundles the CLI into `dist/`.
+
+## Project layout
+
+| Path             | Purpose                              |
+| ---------------- | ------------------------------------ |
+| `src/lexer.ts`   | Source text → tokens                 |
+| `src/ast.ts`     | AST node type definitions            |
+| `src/parser.ts`  | Tokens → AST                         |
+| `src/codegen.ts` | AST → JavaScript                     |
+| `src/diagnostics.ts` | Positioned errors → code frames  |
+| `src/cli.ts`     | Command-line entrypoint              |
+| `src/index.ts`   | Public API re-exports                |
+| `examples/`      | Sample `.snx` programs               |
+| `tests/`         | Test suite (`bun test`)              |
+| `SPEC.md`        | Language specification               |
+| `synax.d.ts`     | Type declarations for the published package |

package/SPEC.md

@@ -0,0 +1,159 @@
+# <Synax> — Language Specification
+
+---
+
+## 1. Overview
+
+- **Name:** [ Synax ]
+- **File extension:** [ .snx ]
+- **One-line philosophy:** [ "Reads closer to plain English than Python, no braces, no semicolons" ]
+
+---
+
+## 2. Design Principles
+
+1. [ No curly braces — use a closing keyword instead ]
+2. [ No semicolons, ever ]
+3. [ One way to write a thing, not several ]
+4. [ Prefer a plain-English keyword over a symbol when both are equally clear ]
+
+---
+
+## 3. Lexical Grammar (Tokens)
+
+| Category    | Rule                                                              | Example                                    |
+| ----------- | ----------------------------------------------------------------- | ------------------------------------------ |
+| Keywords    | [set, print, if, else, end, fn, for, in]                          | `set`, `if`, `fn`, `end`                   |
+| Identifiers | [ starts with letter/underscore, then letters/digits/underscore ] | `name`, `age`, `greet`, i                  |
+| Numbers     | [ int and float literals]                                         | `42`, `3.14`                               |
+| Strings     | [ double-quoted, + used for concat, no interpolation used yet ]   | `"Hello, World!"`                          |
+| Comments    | [ single-line # multi-line syntax /# #/ ]                         | `# single line comment, /# #/ double line` |
+| Operators   | [ = assign, + concat/add, >= compare, .. range ]                  | `=`, `+`, `>=`, `..`                       |
+
+---
+
+## 4. Grammar Rules
+
+```
+program     := statement*
+
+statement   := varDecl | printStmt | ifStmt | fnDecl | forStmt | exprStmt
+
+varDecl     := "set" IDENT "=" expression
+printStmt   := "print" expression
+ifStmt      := "if" expression statement* ("else" statement*)? "end"
+fnDecl      := "fn" IDENT "(" paramList? ")" statement* "end"
+forStmt     := "for" IDENT "in" expression ".." expression statement* "end"
+exprStmt    := expression
+
+paramList   := IDENT ("," IDENT)*
+argList     := expression ("," expression)*
+
+expression  := comparison
+comparison  := term ((">=" | "<=" | ">" | "<" | "==" | "!=") term)*
+term        := factor (("+" | "-") factor)*
+factor      := primary (("*" | "/") primary)*
+primary     := NUMBER | STRING | IDENT | "(" expression ")" | functionCall
+functionCall:= IDENT "(" argList? ")"
+```
+
+---
+
+## 5. Operator Precedence
+
+Highest binds tightest. Fill top to bottom.
+
+| Rank | Operator(s)         | Associativity |
+| ---- | ------------------- | ------------- |
+| 1    | [ == != > < >= <= ] | [ left ]      |
+| 2    | [ + - ]             | [ left ]      |
+| 3    | [ * / ]             | [ left ]      |
+
+---
+
+## 6. Semantics
+
+Scoping: function-scoped — name in greet(name) only exists inside that fn ... end block. (Not directly tested by your examples, but matches your "keep it minimal" principle — confirm this is what you want.)
+Typing: dynamic — no type annotations anywhere in your examples.
+Truthy/falsy: not shown yet — decide what if treats as false (usually 0, "", and a null-type value).
+Mutability: set used for both set x = 5 and set age = 19 — simplest option is set also handles reassignment (no separate const), matching your minimal-syntax goal. Flag it if you want an immutable-by-default version instead.
+
+---
+
+## 7. Standard Library (MVP only)
+
+The bare minimum to run a real program. Add nothing beyond this list for v1.
+
+- [ ] `print(...)`
+- [ ] string/number conversion
+- [ ] [ ]
+
+---
+
+    ## 8. Example Programs
+
+    Write these by hand in your syntax. This is the most important section — do it before section 4.
+
+    **Hello World**
+
+    ```
+    [ print "Hello, World!" ]
+    ```
+
+    **Variable + print**
+
+    ```
+    [
+        set x = 5
+        print x
+    ]
+    ```
+
+    **If / else**
+
+    ```
+    [
+        set age = 19
+
+        if age >= 18
+            print "adult"
+        else
+            print "minor"
+        end
+
+    ]
+    ```
+
+    **Function**
+
+    ```
+    [
+        fn greet(name)
+            print "Hello, " + name
+        end
+
+        greet("Ayush")
+    ]
+    ```
+
+    **Loop**
+
+    ```
+    [
+        for i in 1..5
+            print i
+        end
+    ]
+    ```
+
+    ---
+
+## 9. Non-Goals for v1
+
+Explicitly out of scope — revisit after the MVP works.
+
+- Classes / OOP
+- Modules / imports
+- Async
+- Generics / static type checking
+- [ ]