@user-synax/synax 0.0.1

package/examples/fizzbuzz.snx

@@ -0,0 +1,34 @@
+# FizzBuzz for 1..15.
+#
+# Synax has no `%` operator, so divisibility is tracked with two counters that
+# wrap around at 3 and 5. After the wrap, a zero counter means "divisible by".
+
+set fizz = 0
+set buzz = 0
+
+for i in 1..15
+    set fizz = fizz + 1
+    set buzz = buzz + 1
+
+    if fizz == 3
+        set fizz = 0
+    end
+
+    if buzz == 5
+        set buzz = 0
+    end
+
+    if fizz == 0
+        if buzz == 0
+            print "FizzBuzz"
+        else
+            print "Fizz"
+        end
+    else
+        if buzz == 0
+            print "Buzz"
+        else
+            print i
+        end
+    end
+end

package/examples/greet.snx

@@ -0,0 +1,5 @@
+fn greet(name)
+    print "Hello, " + name
+end
+
+greet("Ayush")

package/examples/hello.snx

@@ -0,0 +1 @@
+print "Hello, World!"

package/examples/if-else.snx

@@ -0,0 +1,7 @@
+set age = 19
+
+if age >= 18
+    print "adult"
+else
+    print "minor"
+end

package/examples/loop.snx

@@ -0,0 +1,3 @@
+for i in 1..5
+    print i
+end

package/examples/variables.snx

@@ -0,0 +1,2 @@
+set x = 5
+print x

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@user-synax/synax",
+  "version": "0.0.1",
+  "description": "A small scripting language that transpiles to JavaScript.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "language",
+    "compiler",
+    "transpiler",
+    "javascript",
+    "bun",
+    "synax"
+  ],
+  "bin": {
+    "synax": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./synax.d.ts",
+  "exports": {
+    ".": {
+      "types": "./synax.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "synax.d.ts",
+    "synax.html",
+    "README.md",
+    "LICENSE",
+    "SPEC.md"
+  ],
+  "scripts": {
+    "build": "bun build src/cli.ts src/index.ts --outdir dist --target bun",
+    "docs": "bun run scripts/build-docs.ts",
+    "dev": "bun run --watch src/cli.ts",
+    "prepublishOnly": "bun test && bun run typecheck && bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/ast.ts

@@ -0,0 +1,151 @@
+/**
+ * Synax abstract syntax tree.
+ *
+ * The parser (`src/parser.ts`) turns a flat token stream into these nodes; the
+ * code generator (`src/codegen.ts`) walks them. Every node carries a 1-based
+ * `line` — the line of the node's first token — so later stages can report
+ * positioned errors without re-deriving them from the source.
+ *
+ * Note: `Token` / `TokenType` deliberately still live in `src/lexer.ts` (see the
+ * NOTE at the top of that file). This module defines only the tree itself, so it
+ * has no imports.
+ */
+
+// ---------------------------------------------------------------------------
+// Expressions
+// ---------------------------------------------------------------------------
+
+/** The operator spellings shared by every binary expression. */
+export type BinaryOperator =
+  | "=="
+  | "!="
+  | ">"
+  | "<"
+  | ">="
+  | "<="
+  | "+"
+  | "-"
+  | "*"
+  | "/";
+
+export interface NumberLiteral {
+  readonly kind: "NumberLiteral";
+  readonly value: number;
+  readonly line: number;
+}
+
+export interface StringLiteral {
+  readonly kind: "StringLiteral";
+  /** The decoded value (escapes already applied), without the quotes. */
+  readonly value: string;
+  readonly line: number;
+}
+
+export interface Identifier {
+  readonly kind: "Identifier";
+  readonly name: string;
+  readonly line: number;
+}
+
+/**
+ * `left <operator> right`. `line` is the line of the left-most operand, i.e. the
+ * first token of the whole expression.
+ */
+export interface BinaryExpr {
+  readonly kind: "BinaryExpr";
+  readonly operator: BinaryOperator;
+  readonly left: Expression;
+  readonly right: Expression;
+  readonly line: number;
+}
+
+/** `callee(arg, ...)`. Per the grammar the callee is always a bare identifier. */
+export interface FunctionCall {
+  readonly kind: "FunctionCall";
+  readonly callee: string;
+  readonly args: Expression[];
+  readonly line: number;
+}
+
+export type Expression =
+  | NumberLiteral
+  | StringLiteral
+  | Identifier
+  | BinaryExpr
+  | FunctionCall;
+
+// ---------------------------------------------------------------------------
+// Statements
+// ---------------------------------------------------------------------------
+
+/** `set name = expression` — also used for reassignment (see SPEC.md §6). */
+export interface VarDecl {
+  readonly kind: "VarDecl";
+  readonly name: string;
+  readonly value: Expression;
+  readonly line: number;
+}
+
+/** `print expression`. */
+export interface PrintStmt {
+  readonly kind: "PrintStmt";
+  readonly argument: Expression;
+  readonly line: number;
+}
+
+/** `if condition <thenBranch> (else <elseBranch>)? end`. */
+export interface IfStmt {
+  readonly kind: "IfStmt";
+  readonly condition: Expression;
+  readonly thenBranch: Statement[];
+  /** `null` when the `if` has no `else` — distinct from an empty else block. */
+  readonly elseBranch: Statement[] | null;
+  readonly line: number;
+}
+
+/** `fn name(params) <body> end`. */
+export interface FnDecl {
+  readonly kind: "FnDecl";
+  readonly name: string;
+  readonly params: string[];
+  readonly body: Statement[];
+  readonly line: number;
+}
+
+/** `for variable in start..end <body> end`. */
+export interface ForStmt {
+  readonly kind: "ForStmt";
+  readonly variable: string;
+  readonly start: Expression;
+  readonly end: Expression;
+  readonly body: Statement[];
+  readonly line: number;
+}
+
+/** A bare expression used as a statement, e.g. a function call. */
+export interface ExprStmt {
+  readonly kind: "ExprStmt";
+  readonly expression: Expression;
+  readonly line: number;
+}
+
+export type Statement =
+  | VarDecl
+  | PrintStmt
+  | IfStmt
+  | FnDecl
+  | ForStmt
+  | ExprStmt;
+
+// ---------------------------------------------------------------------------
+// Root
+// ---------------------------------------------------------------------------
+
+export interface Program {
+  readonly kind: "Program";
+  readonly body: Statement[];
+  readonly line: number;
+}
+
+/** Any node in the tree. */
+export type Node = Program | Statement | Expression;

package/src/cli.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env bun
+/**
+ * Synax CLI entrypoint.
+ *
+ * Usage:
+ *   bun run src/cli.ts <file>
+ *
+ * Reads a Synax source file, runs it through the pipeline
+ * (`Lexer` -> `Parser` -> `generate`) and writes the resulting JavaScript to
+ * stdout.
+ *
+ * Diagnostics go to stderr as a positioned message plus a code frame, with a
+ * non-zero exit code — never a raw stack trace:
+ *
+ *   examples/bad.snx:1:7: error: Unexpected character "@"
+ *     1 | print @
+ *       |       ^
+ *
+ * Set `SYNAX_DEBUG=1` to include the stack for an internal compiler error.
+ */
+import { generate } from "./codegen";
+import { formatDiagnostic } from "./diagnostics";
+import { Lexer, LexerError } from "./lexer";
+import { Parser, ParserError } from "./parser";
+
+const USAGE = "Usage: synax <file>";
+
+export async function main(
+  argv: readonly string[] = Bun.argv.slice(2),
+): Promise<void> {
+  const filePath = argv[0];
+
+  if (filePath === undefined) {
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  let source: string;
+  try {
+    source = await Bun.file(filePath).text();
+  } catch (error) {
+    console.error(
+      `synax: cannot read '${filePath}': ${describeReadFailure(error)}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const tokens = new Lexer(source).tokenize();
+    const ast = new Parser(tokens).parse();
+    console.log(generate(ast));
+  } catch (error) {
+    process.exitCode = 1;
+
+    // Expected diagnostics: a positioned message and a code frame.
+    if (error instanceof LexerError || error instanceof ParserError) {
+      console.error(
+        formatDiagnostic(
+          {
+            file: filePath,
+            line: error.line,
+            column: error.column,
+            length: error.length,
+            reason: error.reason,
+          },
+          source,
+        ),
+      );
+      return;
+    }
+
+    // A bug in the compiler rather than in the input. Keep it to one line by
+    // default so it reads as a diagnostic, not a crash.
+    console.error(`synax: internal error: ${describeError(error)}`);
+    if (process.env["SYNAX_DEBUG"]) console.error(error);
+  }
+}
+
+/** Turn a filesystem error into a short, human-readable reason. */
+function describeReadFailure(error: unknown): string {
+  switch ((error as { code?: unknown }).code) {
+    case "ENOENT":
+      return "no such file";
+    case "EISDIR":
+      return "is a directory";
+    case "EACCES":
+      return "permission denied";
+    default:
+      return "could not be read";
+  }
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+if (import.meta.main) {
+  await main();
+}

package/src/codegen.ts

@@ -0,0 +1,236 @@
+/**
+ * Synax code generator — walks the AST and prints equivalent JavaScript.
+ *
+ * Mapping (SPEC.md §8 examples drive most of this):
+ *   set x = 5      ->  let x = 5;        (assignment on reassignment, see below)
+ *   print e        ->  console.log(e);
+ *   if/else/end    ->  if (cond) { ... } else { ... }
+ *   fn/end         ->  function name(params) { ... }
+ *   for i in a..b  ->  for (let i = a; i <= b; i++) { ... }   (INCLUSIVE)
+ *
+ * Two semantics decided with the spec's author:
+ *   - `a..b` is INCLUSIVE of `b`, so the emitted loop test is `i <= b`.
+ *   - `+` keeps JavaScript's coercion, so `"n=" + 5` concatenates rather than
+ *     erroring. That matches SPEC.md §3 ("+ used for concat").
+ *
+ * `set` both declares and reassigns (SPEC.md §6). JavaScript's `let` cannot be
+ * redeclared, so the generator tracks which names are already in scope and
+ * emits `name = value;` for a rebind instead of a second `let`.
+ *
+ * Known limitation: Synax scoping is function-scoped (§6), but a `let` emitted
+ * inside an `if`/`for` block is block-scoped in JS. A name first `set` inside a
+ * nested block therefore will not be visible after that block. Hoisting
+ * declarations (or emitting `var`) would fix this; neither example in §8 needs
+ * it. Flag it if you want it addressed.
+ */
+import type {
+  BinaryExpr,
+  BinaryOperator,
+  Expression,
+  FnDecl,
+  ForStmt,
+  IfStmt,
+  PrintStmt,
+  Program,
+  Statement,
+  VarDecl,
+} from "./ast";
+
+/** Indentation unit for emitted blocks. */
+const INDENT = "  ";
+
+/**
+ * Binding strength by operator, loosest to tightest (SPEC.md §5). Used only to
+ * decide where parentheses are actually required — every emitted expression
+ * also has to match JS's own precedence, which is identical for these
+ * operators.
+ */
+const PRECEDENCE: Record<BinaryOperator, number> = {
+  "==": 1,
+  "!=": 1,
+  ">": 1,
+  "<": 1,
+  ">=": 1,
+  "<=": 1,
+  "+": 2,
+  "-": 2,
+  "*": 3,
+  "/": 3,
+};
+
+/**
+ * Translate a parsed `Program` into JavaScript source.
+ *
+ * @returns JS source with no trailing newline; `""` for an empty program.
+ */
+export function generate(program: Program): string {
+  return new Generator().program(program);
+}
+
+class Generator {
+  private indentLevel = 0;
+
+  /**
+   * Names already declared in the current function scope. `set` on a name that
+   * is already here becomes a plain assignment instead of a second `let`.
+   */
+  private scope = new Set<string>();
+
+  program(node: Program): string {
+    return node.body.map((statement) => this.statement(statement)).join("\n");
+  }
+
+  // -------------------------------------------------------------------------
+  // Statements
+  // -------------------------------------------------------------------------
+
+  private statement(node: Statement): string {
+    switch (node.kind) {
+      case "VarDecl":
+        return this.varDecl(node);
+      case "PrintStmt":
+        return this.printStmt(node);
+      case "IfStmt":
+        return this.ifStmt(node);
+      case "FnDecl":
+        return this.fnDecl(node);
+      case "ForStmt":
+        return this.forStmt(node);
+      case "ExprStmt":
+        return `${this.indent()}${this.expression(node.expression)};`;
+    }
+  }
+
+  /** `set name = value` — declares on first use, assigns thereafter. */
+  private varDecl(node: VarDecl): string {
+    const value = this.expression(node.value);
+
+    if (this.scope.has(node.name)) {
+      return `${this.indent()}${node.name} = ${value};`;
+    }
+
+    this.scope.add(node.name);
+    return `${this.indent()}let ${node.name} = ${value};`;
+  }
+
+  private printStmt(node: PrintStmt): string {
+    return `${this.indent()}console.log(${this.expression(node.argument)});`;
+  }
+
+  private ifStmt(node: IfStmt): string {
+    const header = `${this.indent()}if (${this.expression(node.condition)}) `;
+
+    let output = header + this.block(node.thenBranch);
+    if (node.elseBranch !== null) {
+      output += ` else ` + this.block(node.elseBranch);
+    }
+
+    return output;
+  }
+
+  private fnDecl(node: FnDecl): string {
+    const header = `${this.indent()}function ${node.name}(${node.params.join(", ")}) `;
+
+    // A function introduces a fresh scope; its parameters are already declared.
+    const outer = this.scope;
+    this.scope = new Set(node.params);
+    const body = this.block(node.body);
+    this.scope = outer;
+
+    return header + body;
+  }
+
+  /**
+   * `for i in start..end` — INCLUSIVE of `end` (decided for this project), so
+   * the emitted test is `i <= end`.
+   */
+  private forStmt(node: ForStmt): string {
+    const { variable } = node;
+    const start = this.expression(node.start);
+    const end = this.expression(node.end);
+
+    const header = `${this.indent()}for (let ${variable} = ${start}; ${variable} <= ${end}; ${variable}++) `;
+
+    // `variable` is intentionally not added to the enclosing scope: JS's
+    // `let` in the for-head already scopes it to the loop.
+    return header + this.block(node.body);
+  }
+
+  // -------------------------------------------------------------------------
+  // Expressions
+  // -------------------------------------------------------------------------
+
+  private expression(node: Expression): string {
+    switch (node.kind) {
+      case "NumberLiteral":
+        return String(node.value);
+      case "StringLiteral":
+        // Reuse JSON's string escaping: it matches JS string syntax exactly.
+        return JSON.stringify(node.value);
+      case "Identifier":
+        return node.name;
+      case "BinaryExpr":
+        return this.binary(node, 0, false);
+      case "FunctionCall":
+        return `${node.callee}(${node.args
+          .map((argument) => this.expression(argument))
+          .join(", ")})`;
+    }
+  }
+
+  /**
+   * Emit a binary expression, parenthesizing only where required.
+   *
+   * All Synax binary operators are left-associative, so a right-hand child of
+   * equal precedence needs parentheses (`1 - (2 - 3)`) while a left-hand child
+   * does not (`1 - 2 - 3`).
+   */
+  private binary(
+    node: BinaryExpr,
+    parentPrecedence: number,
+    isRightChild: boolean,
+  ): string {
+    const precedence = PRECEDENCE[node.operator];
+
+    const left = this.operand(node.left, precedence, false);
+    const right = this.operand(node.right, precedence, true);
+    const text = `${left} ${node.operator} ${right}`;
+
+    const needsParens =
+      precedence < parentPrecedence ||
+      (precedence === parentPrecedence && isRightChild);
+
+    return needsParens ? `(${text})` : text;
+  }
+
+  /** Emit a binary operand, telling it where it sits in the tree. */
+  private operand(
+    node: Expression,
+    parentPrecedence: number,
+    isRightChild: boolean,
+  ): string {
+    if (node.kind === "BinaryExpr") {
+      return this.binary(node, parentPrecedence, isRightChild);
+    }
+    return this.expression(node);
+  }
+
+  // -------------------------------------------------------------------------
+  // Helpers
+  // -------------------------------------------------------------------------
+
+  /** Emit `{ ... }` with the body one level deeper. */
+  private block(statements: readonly Statement[]): string {
+    if (statements.length === 0) return "{}";
+
+    this.indentLevel++;
+    const body = statements.map((statement) => this.statement(statement)).join("\n");
+    this.indentLevel--;
+
+    return `{\n${body}\n${this.indent()}}`;
+  }
+
+  private indent(): string {
+    return INDENT.repeat(this.indentLevel);
+  }
+}

package/src/diagnostics.ts

@@ -0,0 +1,63 @@
+/**
+ * Diagnostic rendering.
+ *
+ * Turns a positioned compiler error into a readable message that points at the
+ * offending line of Synax source:
+ *
+ *   examples/bad.snx:1:7: error: Unexpected character "@"
+ *     1 | print @
+ *       |       ^
+ *
+ * This module is deliberately dependency-free: it renders a plain `Diagnostic`,
+ * so the lexer/parser error classes do not need to be imported here.
+ */
+
+/** A positioned error, ready to render. All positions are 1-based. */
+export interface Diagnostic {
+  readonly file: string;
+  /** 1-based line. */
+  readonly line: number;
+  /** 1-based column. */
+  readonly column: number;
+  /** Characters to underline; at least 1. */
+  readonly length: number;
+  /** The message, without any positional suffix. */
+  readonly reason: string;
+}
+
+/** Indentation before the line-number gutter. */
+const LEAD = "  ";
+
+/**
+ * Render `diagnostic` against `source`, including a code frame when the line
+ * can be located.
+ *
+ * @returns A multi-line string with no trailing newline.
+ */
+export function formatDiagnostic(diagnostic: Diagnostic, source: string): string {
+  const { file, line, column, length, reason } = diagnostic;
+  const header = `${file}:${line}:${column}: error: ${reason}`;
+
+  // Split on \r?\n so CRLF files do not leave a stray \r in the frame.
+  const sourceLine = source.split(/\r?\n/)[line - 1];
+
+  // Nothing useful to show for a missing line, or the empty line that EOF
+  // errors point at when the file ends with a newline.
+  if (sourceLine === undefined || sourceLine.trim() === "") return header;
+
+  // Clamp to the line: an EOF error points one past the last character.
+  const start = Math.max(0, Math.min(column - 1, sourceLine.length));
+  const span = Math.max(1, Math.min(length, sourceLine.length - start));
+
+  const number = String(line);
+  const gutter = " ".repeat(number.length);
+
+  // Replace every non-tab character with a space so the caret keeps whatever
+  // tab alignment the rendered line above it has.
+  const padding = sourceLine.slice(0, start).replace(/[^\t]/g, " ");
+
+  const rendered = `${LEAD}${number} | ${sourceLine}`;
+  const caretLine = `${LEAD}${gutter} | ${padding}${"^".repeat(span)}`;
+
+  return `${header}\n${rendered}\n${caretLine}`;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Synax public API surface.
+ *
+ * TODO: re-export the AST node types from `./ast` once they are defined (they
+ * will need `export type { ... }` under `verbatimModuleSyntax`).
+ */
+export { generate } from "./codegen";
+export { formatDiagnostic } from "./diagnostics";
+export type { Diagnostic } from "./diagnostics";
+export { Lexer, LexerError } from "./lexer";
+export { Parser, ParserError } from "./parser";