alan-d-mitchell/vypr

Vypr is organized as a Rust workspace with one executable crate and several library crates that form a source-to-VM pipeline.

1. Entry point: cli

- cli/src/main.rs is the user-facing command line binary.

- It likely reads a .vypr source file, invokes the compiler pipeline, and runs the program on the VM.

2. Shared error model: crates/error

- This is a common dependency used across the workspace for diagnostics and failure handling.

- It provides the repository-wide error type so lexer, parser, semantic analysis, IR builders, and VM can report issues consistently.

3. Front end: crates/lexer

- Converts Vypr source text into tokens.

- The presence of token.rs and lexer.rs indicates a standalone lexical stage before parsing.

4. Syntax layer: crates/parser

- Turns tokens into an AST (ast.rs).

- This is the language’s structural model for statements, expressions, literals, function definitions, and other Python-like constructs.

5. Semantic analysis: crates/semantic

- Responsible for scope handling, method resolution, and type-related checks.

- scope.rs and methods.rs show that this crate manages lexical scoping, symbol resolution, and the rules behind gradual typing.

- This is where annotated variables are distinguished from dynamic ones, and where many static errors are detected before execution.

6. First IR layer: crates/vir

- Vypr has an intermediate representation called VIR.

- builder.rs suggests AST-to-VIR lowering, while context.rs likely carries symbol/type state across lowering passes.

- This layer is an architectural boundary between language semantics and VM-oriented representation.

7. Second IR layer: crates/mir

- MIR is a lower-level intermediate form than VIR.

- builder.rs and display.rs indicate another lowering pass plus debugging/inspection support.

- The two-stage IR design suggests the compiler separates high-level language structure from execution-friendly operations.

8. Runtime backend: crates/vm

- This is the execution engine: a custom stack-based virtual machine.

- bytecode.rs, compiler.rs, and vm.rs show the path from lowered IR into executable bytecode and then into runtime interpretation.

- value.rs likely defines the VM’s runtime value model, including typed and dynamic values.

9. Built-ins and standard library: crates/vm/src/stdlib

- Vypr includes native modules for math, time, os, and canvas.

- builtins.rs and methods.rs indicate intrinsic functions and type-specific methods are implemented inside the VM/runtime boundary, not in userland code.

- This is the main external-facing runtime extension surface.

10. Bytecode persistence/support: serializer.rs

- The VM includes serialization support for bytecode or compiled artifacts.

- That implies the runtime can likely persist or reload compiled forms, even if the primary workflow is direct compile-and-run.

11. End-to-end data flow

- Source file → lexer tokens → parser AST → semantic analysis → VIR → MIR → VM bytecode → stack-based execution.

- Type enforcement is split across compile-time semantic checks and runtime enforcement for annotated values, matching the gradual typing model described in the README.

12. Repository boundary and examples

- The examples/ directory is not part of the runtime, but it is important for understanding intended language behavior.

- The sample programs cover gradual typing, coercion, data pipelines, fractals, and error cases, which makes them useful reference points for the language features exercised by the compiler and VM.

13. Diagramming implication

- The cleanest architecture diagram is a left-to-right compiler pipeline feeding a runtime box.

- Keep the compiler frontend, IR lowering stages, and VM/runtime as separate layers, with error and stdlib shown as cross-cutting support components.