Rewrite the interpreter and rebuild the site

.cargo/config.toml

@@ -1,2 +1,5 @@
-[target.wasm32-unknown-emscripten]
-rustflags = ["-C", "link-args=--js-library lib.js -O3 -s MODULARIZE=1 -s EXPORT_NAME=MeowScript -s -s EXPORTED_RUNTIME_METHODS=[FS,intArrayFromString,writeArrayToMemory,_malloc,UTF8ToString]"]
+# The interpreter recurses on the stack, so give the WebAssembly build
+# more room than the 1 MiB default. Linear memory grows on demand, so the
+# cost is reserved address space, not RAM.
+[target.wasm32-unknown-unknown]
+rustflags = ["-C", "link-arg=-zstack-size=33554432"]

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{ts,tsx,js,mjs,json,css,md,yml,yaml}]
+indent_size = 2
+
+[*.meow]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: Interpreter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - name: Format
+        run: cargo fmt --all --check
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      - name: Clippy (wasm)
+        run: cargo clippy -p meowscript-wasm --target wasm32-unknown-unknown -- -D warnings
+      - name: Test
+        run: cargo test --workspace
+      - name: Generated site tables are up to date
+        working-directory: site
+        run: |
+          node scripts/sync-examples.mjs
+          node scripts/sync-stdlib.mjs
+          git diff --exit-code -- src/generated
+
+  site:
+    name: Site
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: site
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: site/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm lint
+      - run: pnpm build

.gitignore

@@ -1,2 +1,4 @@
 /target
-.vscode
+.vscode
+.idea
+*.tsbuildinfo

CONTRIBUTING.md

@@ -1,49 +1,64 @@
-# Contributing to Meowscript 🐾
+# Contributing to MeowScript
 
-## Getting Started
+How the project fits together, and how to change it without breaking anything.
 
-1. **Fork the Repository**: 
-   - Navigate to the [Meowscript GitHub repository](https://github.com/AlenVelocity/MeowScript).
-   - Click on the "Fork" button in the top right corner to create a copy of the repository in your GitHub account.
+## Setup
 
-2. **Clone Your Fork**:
-   ```bash
-   git clone https://github.com/<your-github-username>/MeowScript
-   cd MeowScript
-   ```
+You need a Rust toolchain (stable, 1.88 or newer) and, for the site, Node 22 with pnpm. On Windows the GNU toolchain works without Visual Studio: `rustup-init --default-host x86_64-pc-windows-gnu`.
 
-3. **Create a New Branch**:
-   ```bash
-   git checkout -b <branch-name>
-   ```
+```bash
+git clone https://github.com/AlenVelocity/MeowScript
+cd MeowScript
+cargo test --workspace
+```
+
+## Where things live
+
+| Path | What |
+| --- | --- |
+| `crates/meowscript/src/lexer.rs` | text to tokens, with byte spans |
+| `crates/meowscript/src/parser.rs` | tokens to AST (`ast.rs`); Pratt parser for operators |
+| `crates/meowscript/src/interpreter.rs` | evaluates the AST; control flow travels as `Interrupt` |
+| `crates/meowscript/src/value.rs` | runtime values and how they print |
+| `crates/meowscript/src/stdlib/` | the prelude and the `nya:` pawckages, one file each |
+| `crates/meowscript/src/host.rs` | the `Host` trait: printing, files, sleeping, randomness |
+| `crates/meowscript-cli` | the `meowscript` binary |
+| `crates/meowscript-wasm` | the browser entry point (`run`, `version`, `keywords`) |
+| `examples/` | programs run by the test suite; a `.out` file is a snapshot |
+| `site/` | the Next.js playground and docs |
+
+## Making changes
 
-## Writing Code
+**Keywords and syntax.** Add the token in `token.rs` (both `keyword()` and `KEYWORDS`), lex it, parse it, evaluate it, and add a test next to the others in each file. Then add it to the cheat sheet in `site/src/components/CheatSheet.tsx`, the reference in `site/content/docs.md`, and the highlighter's keyword list in `site/src/lib/meowscript-language.ts`.
 
-- Ensure your code adheres to the cat-themed nature of Meowscript, replacing traditional keywords with feline-inspired terms.
-- Maintain the paw-some (although not easily readable) syntax of Meowscript.
-- Feel free to expand the standard library with more cat-themed functions and utilities.
-- Before pushing code, ensure it is well-commented and consistent with the existing code style.
+**Built-in functions.** Add a row to the right pawckage's table in `crates/meowscript/src/stdlib/`. The `arity` is checked before your function runs, so indexing `args` inside it is safe. The helpers in `stdlib/mod.rs` (`number`, `string`, `array`, `callable`) pull typed arguments with consistent error messages. Functions that take callbacks call `interp.call(f, args, None)`. The docs site generates its library reference from these tables, so the `doc` string is what people read.
 
-## Submitting Changes
+**Examples.** Drop a `.meow` file in `examples/`. Run `UPDATE_SNAPSHOTS=1 cargo test -p meowscript --test examples` to write its `.out` file, then read the `.out` to check it is what you meant. Programs that sleep or read input get a `// test: skip` comment instead. To show it in the playground, add its name to `ORDER` in `site/scripts/sync-examples.mjs`.
 
-1. **Commit Your Changes**:
-   ```bash
-   git commit -m "Describe your changes"
-   ```
+**Error messages.** They start with a cat exclamation chosen by `ErrorKind`, then say what went wrong and, where possible, what to do instead.
 
-2. **Push Your Changes**:
-   ```bash
-   git push origin <branch-name>
-   ```
+**Comments.** Only where the code can't say why. A comment that repeats the function name or the next line gets removed in review.
 
-3. **Open a Pull Request**:
-   - Navigate to the [Meowscript GitHub repository](https://github.com/AlenVelocity/MeowScript).
-   - Click on "New Pull Request" and compare your branch to the main Meowscript repository.
-   - Provide a detailed description of your changes.
+## Before you push
 
-## Code Review
+```bash
+cargo fmt --all
+cargo clippy --workspace --all-targets -- -D warnings
+cargo clippy -p meowscript-wasm --target wasm32-unknown-unknown -- -D warnings
+cargo test --workspace
+```
 
-- Once your pull request is submitted, maintainers and contributors can review your proposed changes and request any necessary modifications.
+If you touched the interpreter or the standard library, also refresh what the site ships:
 
-Thank you for contributing to Meowscript! Your efforts help make coding a paw-sitive experience.
+```bash
+cd site
+pnpm build:wasm     # needs wasm-pack
+pnpm sync           # regenerates src/generated/*
+pnpm typecheck && pnpm lint && pnpm build
 ```
+
+and commit the results in `site/public/wasm` and `site/src/generated`. CI checks that the generated tables match the code.
+
+## Pull requests
+
+Say what changed and why. If it changes the language, show a before and after.