|
| 1 | +# HypnoScript Copilot Instructions |
| 2 | + |
| 3 | +## Architecture Overview |
| 4 | + |
| 5 | +HypnoScript is a hypnotically-themed programming language with a pure Rust implementation (Rust 2024 edition). The compilation pipeline flows: |
| 6 | + |
| 7 | +``` |
| 8 | +Source (.hyp) → Lexer → Tokens → Parser → AST → TypeChecker → Interpreter/Compiler |
| 9 | +``` |
| 10 | + |
| 11 | +**Workspace crates (dependency order):** |
| 12 | + |
| 13 | +| Crate | Purpose | Key Exports | |
| 14 | +| -------------------------- | --------------------------- | ------------------------------------------------------------------------ | |
| 15 | +| `hypnoscript-core` | Type system foundation | `HypnoType`, `HypnoBaseType`, `SymbolTable` | |
| 16 | +| `hypnoscript-lexer-parser` | Tokenization & AST | `Lexer`, `Parser`, `AstNode`, `Token` | |
| 17 | +| `hypnoscript-runtime` | 180+ builtins (20+ modules) | `MathBuiltins`, `StringBuiltins`, `ArrayBuiltins`, etc. | |
| 18 | +| `hypnoscript-compiler` | All backends | `Interpreter`, `TypeChecker`, `WasmCodeGenerator`, `NativeCodeGenerator` | |
| 19 | +| `hypnoscript-cli` | CLI + package manager | Commands: `exec`, `lex`, `parse`, `check`, `compile-wasm` | |
| 20 | + |
| 21 | +## Essential Commands |
| 22 | + |
| 23 | +```bash |
| 24 | +# Development cycle |
| 25 | +cargo build --all # Debug build |
| 26 | +cargo run -p hypnoscript-cli -- exec file.hyp # Run .hyp file |
| 27 | +cargo run -p hypnoscript-cli -- exec file.hyp --debug # Interactive debugger |
| 28 | + |
| 29 | +# Testing (185+ tests, run on Windows/Linux/macOS in CI) |
| 30 | +cargo test --all # All tests |
| 31 | +cargo test --package hypnoscript-compiler -- --nocapture # Single crate with output |
| 32 | +cargo test --package hypnoscript-runtime test_math # Specific test |
| 33 | + |
| 34 | +# Pre-commit quality checks (enforced by CI) |
| 35 | +cargo fmt --all -- --check |
| 36 | +cargo clippy --all-targets --all-features -- -D warnings |
| 37 | + |
| 38 | +# Release build (LTO enabled, stripped) |
| 39 | +cargo build --all --release |
| 40 | +``` |
| 41 | + |
| 42 | +## Language Syntax Quick Reference |
| 43 | + |
| 44 | +HypnoScript uses hypnotic-themed keywords. See [token.rs](hypnoscript-lexer-parser/src/token.rs) for complete list. |
| 45 | + |
| 46 | +| HypnoScript | Equivalent | Example | |
| 47 | +| ---------------------------- | ---------- | ---------------------------------------------------------------- | |
| 48 | +| `Focus { } Relax` | program | `Focus { observe "hi"; } Relax` | |
| 49 | +| `induce`/`freeze` | let/const | `induce x: number = 42;` | |
| 50 | +| `suggestion` | function | `suggestion add(a: number, b: number): number { awaken a + b; }` | |
| 51 | +| `session` | class | `session Counter { expose count: number = 0; }` | |
| 52 | +| `observe`/`whisper` | print | `observe "Hello";` (with newline) | |
| 53 | +| `awaken` | return | `awaken result;` | |
| 54 | +| `entrain`/`when`/`otherwise` | match | `entrain x { when 0 => "zero" otherwise => "other" }` | |
| 55 | +| `yourEyesAreGettingHeavy` | >= | `if (x yourEyesAreGettingHeavy 10) deepFocus { }` | |
| 56 | +| `lucidFallback` | ?? | `maybeNull lucidFallback 100` | |
| 57 | + |
| 58 | +## Adding New Builtin Functions |
| 59 | + |
| 60 | +1. **Create module** in `hypnoscript-runtime/src/` (e.g., `my_builtins.rs`) |
| 61 | +2. **Implement trait** `BuiltinModule` from [builtin_trait.rs](hypnoscript-runtime/src/builtin_trait.rs): |
| 62 | + ```rust |
| 63 | + impl BuiltinModule for MyBuiltins { |
| 64 | + fn module_name() -> &'static str { "My" } |
| 65 | + fn description() -> &'static str { "My builtin functions" } |
| 66 | + fn function_names() -> &'static [&'static str] { &["MyFunc1", "MyFunc2"] } |
| 67 | + } |
| 68 | + ``` |
| 69 | +3. **Export** in `hypnoscript-runtime/src/lib.rs` |
| 70 | +4. **Register** in [interpreter.rs](hypnoscript-compiler/src/interpreter.rs) - add match arms in `call_builtin_function()` |
| 71 | +5. **Add tests** as inline `#[cfg(test)] mod tests { }` at file end |
| 72 | + |
| 73 | +## Code Conventions |
| 74 | + |
| 75 | +- **Error handling**: Use `thiserror` with `#[derive(Error)]`. User-facing errors support i18n via `LocalizedMessage` (EN, DE, FR, ES) |
| 76 | +- **AST nodes**: All constructs map to variants in `AstNode` enum ([ast.rs](hypnoscript-lexer-parser/src/ast.rs)) |
| 77 | +- **Tests**: Inline modules at file end with `#[cfg(test)]`. Test `.hyp` files in `hypnoscript-tests/` |
| 78 | +- **Workspace deps**: Shared dependencies defined in root `Cargo.toml` under `[workspace.dependencies]` |
| 79 | + |
| 80 | +## Package Manager (trance.json) |
| 81 | + |
| 82 | +HypnoScript projects use themed manifest keys: |
| 83 | + |
| 84 | +- `ritualName` → package name, `mantra` → version |
| 85 | +- `anchors`/`deepAnchors` → dependencies/devDependencies |
| 86 | +- `suggestions` → npm-style scripts |
| 87 | + |
| 88 | +See [package.rs](hypnoscript-cli/src/package.rs) for schema. |
| 89 | + |
| 90 | +## Key Files Reference |
| 91 | + |
| 92 | +| File | Purpose | |
| 93 | +| ------------------------------------------------------------ | -------------------------------------------- | |
| 94 | +| [interpreter.rs](hypnoscript-compiler/src/interpreter.rs) | Main runtime (3400+ lines), builtin dispatch | |
| 95 | +| [ast.rs](hypnoscript-lexer-parser/src/ast.rs) | All 30+ AST node variants | |
| 96 | +| [token.rs](hypnoscript-lexer-parser/src/token.rs) | Token types & hypnotic keyword mappings | |
| 97 | +| [types.rs](hypnoscript-core/src/types.rs) | `HypnoType` enum, type inference | |
| 98 | +| [builtin_trait.rs](hypnoscript-runtime/src/builtin_trait.rs) | `BuiltinModule` trait for extending runtime | |
0 commit comments