Feat and Docs: Update CLI to implement inline commands, and README.md for compiler.

Author: dylan-sutton-chavez

compiler/README.md

@@ -1,12 +1,77 @@
-*Update this documentation upon completion of the compiler (https://edgepython.com/resources/architecture)*
+## Edge Python
+
+Single-pass SSA compiler for Python 3.13: logos lexer, token-to-bytecode parser, adaptive VM with inline caching, template memoization, and configurable sandbox limits.
+
+---
+
+### Architecture
+
+- **Lexer**: DFA-driven tokenization, offset-indexed, zero-alloc
+- **Parser**: Single-pass SSA, phi nodes, precedence climbing, direct bytecode emission
+- **VM**: Adaptive stack machine, inline caching, template memoization
+- **Sandbox**: Configurable recursion, operation, and heap limits
+
+### Quick Start
+
+```bash
+cd compiler/
+
+cargo build --release
+./target/release/edge -c 'print("Hello, world!")'
+```
+
+### Usage
+
+| Command                         | Description                                       |
+|---------------------------------|---------------------------------------------------|
+| `edge script.py`                | Run with no limits                                |
+| `edge --sandbox script.py`      | Run with sandbox (512 calls, 100M ops, 100K heap) |
+| `edge -d --sandbox script.py`   | Debug output (verbosity level 1)                  |
+| `edge -dd --sandbox script.py`  | Debug output (verbosity level 2)                  |
+
+### Building for WebAssembly
+
+```bash
+rustup target add wasm32-unknown-unknown
+cargo build --target wasm32-unknown-unknown --release --no-default-features --features wasm
+```
+
+*Exported functions: `src_ptr()`, `out_ptr()`, `run(len: usize)` -> `usize`*
+
+### Project Structure
 
 ```bash
+├── Cargo.lock
+├── Cargo.toml
+├── main.py
+├── README.md
+├── src
+│   ├── lib.rs
+│   ├── main.rs
+│   ├── modules
+│   │   ├── lexer.rs
+│   │   ├── parser.rs
+│   │   └── vm.rs
+│   └── wasm.rs
+└── tests
+    ├── cases
+    │   ├── lexer_cases.json
+    │   ├── parser_cases.json
+    │   └── vm_cases.json
+    ├── integration_test.rs
+    ├── lexer_test.rs
+    ├── parser_test.rs
+    └── vm_test.rs
+```
 
-lexer.rs
-  Tokenizes Python source into a stream of spanned Token variants.
+### Tests
 
-parser.rs
-  Single-pass SSA bytecode emitter. No AST. Variables versioned on assignment (new def per write), phi-joined (select reaching defs) at control flow boundaries.
+```bash
+cargo test
+cargo test -- --ignored
+cargo test --features wasm-tests
 ```
 
-*upx packer*
+### License
+
+MIT OR Apache-2.0

compiler/src/main.rs

@@ -5,7 +5,11 @@ use log::{debug, info, error};
 fn parse_args() -> (String, usize, bool, bool) {
     let args: Vec<_> = env::args().skip(1).collect();
     if args.is_empty() || args.contains(&"-h".into()) {
-        println!("usage: edge [-d] [-dd] [-q] [--sandbox] <file>"); exit(0)
+        println!("usage: edge [-c code] [-d] [-dd] [-q] [--sandbox] <file>"); exit(0)
+    }
+    if let Some(pos) = args.iter().position(|a| a == "-c") {
+        let code = args.get(pos + 1).cloned().unwrap_or_default();
+        return (code, 0, false, false);
     }
     let p = args.iter().find(|&a| !a.starts_with('-')).cloned().unwrap_or_else(|| {
         eprintln!("abort: execution failed because no input target was specified"); exit(1)
@@ -15,9 +19,11 @@ fn parse_args() -> (String, usize, bool, bool) {
 }
 
 fn run(path: &str, v: usize, q: bool, sandbox: bool) -> Result<(), Box<dyn std::error::Error>> {
-    stderrlog::new().module(module_path!()).verbosity(v).quiet(q).init().ok();
-
-    let src = fs::read_to_string(path).map_err(|e| format!("io: cannot access '{}' because {}", path, e))?;
+    let src = if path.ends_with(".py") {
+        fs::read_to_string(path).map_err(|e| format!("io: cannot access '{}' because {}", path, e))?
+    } else {
+        path.to_string()
+    };
 
     let (chunk, errs) = Parser::new(&src, lexer(&src)).parse();
     if !errs.is_empty() {