@rcrsr/rill 0.1.0 → 0.2.0

package/docs/14_host-integration.md

@@ -15,9 +15,11 @@ const source = `
 const ast = parse(source);
 const ctx = createRuntimeContext({
   functions: {
-    prompt: async (args) => {
-      const text = String(args[0]);
-      return await callYourLLM(text);
+    prompt: {
+      params: [{ name: 'text', type: 'string' }],
+      fn: async (args) => {
+        return await callYourLLM(args[0]);
+      },
     },
   },
 });
@@ -33,7 +35,7 @@ The `createRuntimeContext()` function accepts these options:
 | Option | Type | Description |
 |--------|------|-------------|
 | `variables` | `Record<string, RillValue>` | Initial variables accessible as `$name` |
-| `functions` | `Record<string, CallableFn \| HostFunctionDefinition>` | Custom functions callable as `name()` |
+| `functions` | `Record<string, HostFunctionDefinition>` | Custom functions callable as `name()` |
 | `callbacks` | `Partial<RuntimeCallbacks>` | I/O callbacks (e.g., `onLog`) |
 | `observability` | `ObservabilityCallbacks` | Execution monitoring hooks |
 | `timeout` | `number` | Timeout in ms for async functions |
@@ -51,18 +53,24 @@ Host functions must follow these rules to ensure correct script behavior:
 ```typescript
 // WRONG: Mutates input array
 functions: {
-  addItem: (args) => {
-    const list = args[0] as unknown[];
-    list.push('new');  // DON'T DO THIS
-    return list;
+  addItem: {
+    params: [{ name: 'list', type: 'list' }],
+    fn: (args) => {
+      const list = args[0] as unknown[];
+      list.push('new');  // DON'T DO THIS
+      return list;
+    },
   },
 }
 
 // CORRECT: Return new value
 functions: {
-  addItem: (args) => {
-    const list = args[0] as unknown[];
-    return [...list, 'new'];  // Create new array
+  addItem: {
+    params: [{ name: 'list', type: 'list' }],
+    fn: (args) => {
+      const list = args[0] as unknown[];
+      return [...list, 'new'];  // Create new array
+    },
   },
 }
 ```
@@ -75,9 +83,12 @@ For maximum safety, consider freezing values passed to host functions:
 import { deepFreeze } from './utils'; // Your utility
 
 functions: {
-  process: (args) => {
-    const frozen = deepFreeze(args[0]);
-    return transform(frozen);  // Any mutation throws
+  process: {
+    params: [{ name: 'input', type: 'string' }],
+    fn: (args) => {
+      const frozen = deepFreeze(args[0]);
+      return transform(frozen);  // Any mutation throws
+    },
   },
 }
 ```
@@ -96,31 +107,40 @@ Functions are called by name: `functionName(arg1, arg2)`.
 const ctx = createRuntimeContext({
   functions: {
     // Sync function
-    add: (args) => {
-      const a = typeof args[0] === 'number' ? args[0] : 0;
-      const b = typeof args[1] === 'number' ? args[1] : 0;
-      return a + b;
+    add: {
+      params: [
+        { name: 'a', type: 'number' },
+        { name: 'b', type: 'number' },
+      ],
+      fn: (args) => args[0] + args[1],
     },
 
     // Async function
-    fetch: async (args, ctx, location) => {
-      const url = String(args[0]);
-      const response = await fetch(url);
-      return await response.text();
+    fetch: {
+      params: [{ name: 'url', type: 'string' }],
+      fn: async (args, ctx, location) => {
+        const response = await fetch(args[0]);
+        return await response.text();
+      },
     },
 
     // Function with context access
-    getVar: (args, ctx) => {
-      const name = String(args[0]);
-      return ctx.variables.get(name) ?? null;
+    getVar: {
+      params: [{ name: 'name', type: 'string' }],
+      fn: (args, ctx) => {
+        return ctx.variables.get(args[0]) ?? null;
+      },
     },
 
     // Function with location for error reporting
-    validate: (args, ctx, location) => {
-      if (!args[0]) {
-        throw new Error(`Validation failed at line ${location?.line}`);
-      }
-      return args[0];
+    validate: {
+      params: [{ name: 'value', type: 'string' }],
+      fn: (args, ctx, location) => {
+        if (!args[0]) {
+          throw new Error(`Validation failed at line ${location?.line}`);
+        }
+        return args[0];
+      },
     },
   },
 });
@@ -134,14 +154,41 @@ Use `::` to organize functions into namespaces:
 const ctx = createRuntimeContext({
   functions: {
     // Namespaced functions use :: separator
-    'math::add': (args) => (args[0] as number) + (args[1] as number),
-    'math::multiply': (args) => (args[0] as number) * (args[1] as number),
-    'str::upper': (args) => String(args[0]).toUpperCase(),
-    'str::lower': (args) => String(args[0]).toLowerCase(),
+    'math::add': {
+      params: [
+        { name: 'a', type: 'number' },
+        { name: 'b', type: 'number' },
+      ],
+      fn: (args) => args[0] + args[1],
+    },
+    'math::multiply': {
+      params: [
+        { name: 'a', type: 'number' },
+        { name: 'b', type: 'number' },
+      ],
+      fn: (args) => args[0] * args[1],
+    },
+    'str::upper': {
+      params: [{ name: 'text', type: 'string' }],
+      fn: (args) => args[0].toUpperCase(),
+    },
+    'str::lower': {
+      params: [{ name: 'text', type: 'string' }],
+      fn: (args) => args[0].toLowerCase(),
+    },
 
     // Multi-level namespaces
-    'io::file::read': async (args) => fs.readFile(String(args[0]), 'utf-8'),
-    'io::file::write': async (args) => fs.writeFile(String(args[0]), String(args[1])),
+    'io::file::read': {
+      params: [{ name: 'path', type: 'string' }],
+      fn: async (args) => fs.readFile(args[0], 'utf-8'),
+    },
+    'io::file::write': {
+      params: [
+        { name: 'path', type: 'string' },
+        { name: 'content', type: 'string' },
+      ],
+      fn: async (args) => fs.writeFile(args[0], args[1]),
+    },
   },
 });
 ```
@@ -159,6 +206,8 @@ Namespaces help organize host APIs and avoid name collisions without requiring t
 
 ### CallableFn Signature
 
+The `fn` property in `HostFunctionDefinition` uses the `CallableFn` type:
+
 ```typescript
 type CallableFn = (
   args: RillValue[],
@@ -169,17 +218,17 @@ type CallableFn = (
 
 | Parameter | Description |
 |-----------|-------------|
-| `args` | Positional arguments passed to the function |
+| `args` | Positional arguments passed to the function (already validated against `params`) |
 | `ctx` | Runtime context with variables, pipeValue, etc. |
 | `location` | Source location of the call site (for error reporting) |
 
-## Typed Host Functions
+## Host Function Type Declarations
 
-Host functions can declare parameter types and defaults. The runtime validates arguments before calling your function, eliminating manual type checking.
+All host functions must declare parameter types and optional defaults using the `HostFunctionDefinition` interface. The runtime validates arguments before calling your function, eliminating manual type checking.
 
-### Basic Type Declarations
+### Parameter Type Declarations
 
-Declare parameter types using the `HostFunctionDefinition` interface:
+Declare parameter types in the `params` array:
 
 ```typescript
 const ctx = createRuntimeContext({
@@ -254,62 +303,6 @@ Error details include:
 - Expected type
 - Actual type received
 
-### Migration from Untyped Functions
-
-Typed function declarations are optional. Existing untyped functions continue working without changes.
-
-**Before (manual validation):**
-
-```typescript
-functions: {
-  repeat: (args) => {
-    const str = typeof args[0] === 'string' ? args[0] : '';
-    const count = typeof args[1] === 'number' ? args[1] : 1;
-    return str.repeat(count);
-  },
-}
-```
-
-**After (declarative validation):**
-
-```typescript
-functions: {
-  repeat: {
-    params: [
-      { name: 'str', type: 'string' },
-      { name: 'count', type: 'number', defaultValue: 1 },
-    ],
-    fn: (args) => args[0].repeat(args[1]), // Types guaranteed
-  },
-}
-```
-
-Benefits of migration:
-
-- Eliminates manual type checking code
-- Provides clear error messages to script authors
-- Documents expected types in function signature
-- Reduces bugs from incorrect type coercion
-
-### Mixed Function Definitions
-
-You can mix typed and untyped functions in the same context:
-
-```typescript
-const ctx = createRuntimeContext({
-  functions: {
-    // Untyped (legacy)
-    'legacy::func': (args) => args[0],
-
-    // Typed (new)
-    'typed::func': {
-      params: [{ name: 'x', type: 'string' }],
-      fn: (args) => args[0],
-    },
-  },
-});
-```
-
 ### HostFunctionDefinition Interface
 
 ```typescript
@@ -439,9 +432,12 @@ const controller = new AbortController();
 const ctx = createRuntimeContext({
   signal: controller.signal,
   functions: {
-    longTask: async () => {
-      await new Promise((r) => setTimeout(r, 10000));
-      return 'done';
+    longTask: {
+      params: [],
+      fn: async () => {
+        await new Promise((r) => setTimeout(r, 10000));
+        return 'done';
+      },
     },
   },
 });
@@ -620,10 +616,13 @@ Set a timeout for async operations:
 const ctx = createRuntimeContext({
   timeout: 30000, // 30 seconds
   functions: {
-    slowOperation: async () => {
-      // Will throw TimeoutError if exceeds 30s
-      await longRunningTask();
-      return 'done';
+    slowOperation: {
+      params: [],
+      fn: async () => {
+        // Will throw TimeoutError if exceeds 30s
+        await longRunningTask();
+        return 'done';
+      },
     },
   },
 });
@@ -640,10 +639,13 @@ const ctx = createRuntimeContext({
     'FATAL',         // Matches "FATAL" anywhere
   ],
   functions: {
-    process: (args) => {
-      // If this returns "error: invalid input",
-      // execution halts with AutoExceptionError
-      return externalProcess(args[0]);
+    process: {
+      params: [{ name: 'input', type: 'string' }],
+      fn: (args) => {
+        // If this returns "error: invalid input",
+        // execution halts with AutoExceptionError
+        return externalProcess(args[0]);
+      },
     },
   },
 });
@@ -749,9 +751,12 @@ const ctx = createRuntimeContext({
   },
 
   functions: {
-    prompt: async (args, ctx, location) => {
-      console.log(`[prompt at line ${location?.line}]`);
-      return await callLLM(String(args[0]));
+    prompt: {
+      params: [{ name: 'text', type: 'string' }],
+      fn: async (args, ctx, location) => {
+        console.log(`[prompt at line ${location?.line}]`);
+        return await callLLM(args[0]);
+      },
     },
   },
 

package/docs/15_grammar.ebnf

@@ -188,7 +188,7 @@ body   = block | grouped-expr | postfix-expr ;
 closure = "|" , [ closure-param , { "," , closure-param } ] , "|" , body ;
 
 string        = '"' , { char | escape | brace-escape | interpolation } , '"'
-              | "<<" , delimiter , newline , heredoc-body , delimiter ;
+              | '"""' , { char | escape | brace-escape | interpolation } , '"""' ;
 
 char          = letter | digit | " " | "!" | "#" | "$" | "%" | "&" | "'" | "(" | ")"
               | "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" | "=" | ">"
@@ -196,10 +196,6 @@ char          = letter | digit | " " | "!" | "#" | "$" | "%" | "&" | "'" | "(" |
               (* excludes " \ { } which have special meaning in strings *)
 escape        = "\\" , ( "n" | "r" | "t" | "\\" | '"' ) ;
 brace-escape  = "{{" | "}}" ;   (* {{ -> literal {, }} -> literal } *)
-delimiter     = identifier ;
-heredoc-body  = { heredoc-line } ;    (* heredocs also support interpolation *)
-heredoc-line  = { heredoc-char | interpolation | brace-escape } , newline ;
-heredoc-char  = char | '"' | "\\" ;   (* excludes { } which have special meaning *)
 
 interpolation = "{" , expression , "}" ;
 

package/docs/16_conventions.md

@@ -318,16 +318,15 @@ parseJson($input):dict :> $data
 
 ## String Handling
 
-### Use heredocs for multiline content
+### Use triple-quotes for multiline content
 
 ```text
-prompt(<<EOF
+"""
 Analyze this content:
 {$content}
 
 Provide a summary.
-EOF
-)
+"""
 ```
 
 ### Use .empty for emptiness checks

package/docs/17_cli-tools.md

@@ -0,0 +1,184 @@
+# CLI Tools
+
+rill ships three command-line tools for running and validating scripts.
+
+## rill-exec
+
+Execute a rill script file with arguments.
+
+```text
+rill-exec <script.rill> [args...]
+rill-exec -                         # Read from stdin
+rill-exec --help
+rill-exec --version
+```
+
+### Arguments
+
+Positional arguments pass to the script as a string list in `$` (pipe value).
+
+```bash
+rill-exec greet.rill alice bob
+# Inside script: $ == ["alice", "bob"]
+```
+
+### Stdin
+
+Use `-` to read a script from standard input:
+
+```bash
+echo 'log("hello")' | rill-exec -
+```
+
+### Frontmatter Modules
+
+Scripts with `use:` frontmatter load modules before execution:
+
+```text
+---
+use:
+  - utils: ./lib/utils.rill
+---
+
+$utils.helper("input")
+```
+
+### Exit Codes
+
+| Return Value | Exit Code |
+|-------------|-----------|
+| `true` or non-empty string | 0 |
+| `false` or empty string | 1 |
+| `[0, "message"]` | 0 (prints message) |
+| `[1, "message"]` | 1 (prints message) |
+
+## rill-eval
+
+Evaluate a single rill expression. No file context or module loading.
+
+```text
+rill-eval <expression>
+rill-eval --help
+rill-eval --version
+```
+
+### Examples
+
+```bash
+rill-eval '"hello".len'
+# 5
+
+rill-eval '5 + 3'
+# 8
+
+rill-eval '[1, 2, 3] -> map |x|($x * 2)'
+# [2, 4, 6]
+```
+
+## rill-check
+
+Static analysis tool that validates rill scripts against lint rules.
+
+```text
+rill-check [options] <file>
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--fix` | Apply automatic fixes to the source file |
+| `--format text` | Human-readable output (default) |
+| `--format json` | Machine-readable JSON output |
+| `--verbose` | Include rule category in JSON output |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No issues found |
+| 1 | Diagnostics reported (or argument error) |
+| 2 | File not found or unreadable |
+| 3 | Parse error in source file |
+
+### Output Formats
+
+**Text** (default): one line per diagnostic.
+
+```text
+script.rill:5:3: warning: message (RULE_CODE)
+```
+
+**JSON**: structured output with summary.
+
+```json
+{
+  "file": "script.rill",
+  "errors": [
+    {
+      "location": { "line": 5, "column": 3, "offset": 42 },
+      "severity": "warning",
+      "code": "RULE_CODE",
+      "message": "description"
+    }
+  ],
+  "summary": { "total": 1, "errors": 0, "warnings": 1, "info": 0 }
+}
+```
+
+### Configuration
+
+Place a `.rill-check.json` file in the project root to configure rules:
+
+```json
+{
+  "rules": {
+    "NAMING_SNAKE_CASE": "on",
+    "SPACING_OPERATOR": "off",
+    "COMPLEX_CONDITION": "warn"
+  },
+  "severity": {
+    "AVOID_REASSIGNMENT": "error"
+  }
+}
+```
+
+Rule states: `"on"` (enabled), `"off"` (disabled), `"warn"` (downgrade to warning).
+
+### Lint Rules
+
+| Code | Category | Default | Description |
+|------|----------|---------|-------------|
+| `NAMING_SNAKE_CASE` | naming | error | Variable names must use snake_case |
+| `AVOID_REASSIGNMENT` | anti-patterns | warning | Avoid reassigning captured variables |
+| `COMPLEX_CONDITION` | anti-patterns | info | Condition expression is complex |
+| `LOOP_OUTER_CAPTURE` | anti-patterns | warning | Loop body captures to outer variable |
+| `USE_EMPTY_METHOD` | strings | warning | Use `.empty` instead of `.len == 0` |
+| `UNNECESSARY_ASSERTION` | types | info | Type assertion on a literal value |
+| `VALIDATE_EXTERNAL` | types | info | External data lacks type validation |
+| `CAPTURE_INLINE_CHAIN` | flow | info | Capture breaks a pipe chain |
+| `CAPTURE_BEFORE_BRANCH` | flow | info | Capture value before branching |
+| `LOOP_ACCUMULATOR` | loops | info | Use accumulator `$@` pattern |
+| `PREFER_DO_WHILE` | loops | info | Consider do-while for init-then-loop |
+| `USE_EACH` | loops | info | Use `each` instead of while loop |
+| `BREAK_IN_PARALLEL` | collections | error | `break` inside `map` or `filter` |
+| `PREFER_MAP` | collections | info | Use `map` when body has no side effects |
+| `FOLD_INTERMEDIATES` | collections | info | `fold` discards intermediate results |
+| `FILTER_NEGATION` | collections | warning | Negated filter condition |
+| `METHOD_SHORTHAND` | collections | info | Use method reference shorthand |
+| `USE_DEFAULT_OPERATOR` | conditionals | info | Use `??` instead of conditional |
+| `CONDITION_TYPE` | conditionals | warning | Condition not boolean |
+| `CLOSURE_BARE_DOLLAR` | closures | warning | Stored closure uses bare `$` |
+| `CLOSURE_BRACES` | closures | info | Multi-statement closure needs braces |
+| `CLOSURE_LATE_BINDING` | closures | warning | Closure captures late-bound variable |
+| `SPACING_OPERATOR` | formatting | info | Operators need surrounding spaces |
+| `SPACING_BRACES` | formatting | info | Braces need inner spacing |
+| `SPACING_BRACKETS` | formatting | info | Brackets need consistent spacing |
+| `SPACING_CLOSURE` | formatting | info | Closure params need spacing |
+| `INDENT_CONTINUATION` | formatting | info | Continuation line indentation |
+| `IMPLICIT_DOLLAR_METHOD` | formatting | info | Prefer implicit `$` for methods |
+| `IMPLICIT_DOLLAR_FUNCTION` | formatting | info | Prefer implicit `$` for functions |
+| `IMPLICIT_DOLLAR_CLOSURE` | formatting | info | Prefer implicit `$` for closures |
+| `THROWAWAY_CAPTURE` | formatting | info | Captured variable never used |

package/docs/99_llm-reference.txt

@@ -67,10 +67,17 @@ CRITICAL DIFFERENCES FROM MAINSTREAM LANGUAGES
    "hello" :> $x
    42 :> $x        # ERROR: cannot assign number to string variable
 
-5. NO VARIABLE SHADOWING
+5. NO VARIABLE SHADOWING (CRITICAL FOR LOOPS)
    Child scopes can READ parent variables but cannot WRITE or redeclare them.
    Variables created inside blocks/loops do NOT leak out.
 
+   WRONG - this pattern NEVER works:
+     0 :> $count
+     [1, 2, 3] -> each { $count + 1 :> $count }  # creates LOCAL $count
+     $count                                       # still 0!
+
+   RIGHT - use $ or $@ as state carrier (see LOOP STATE PATTERNS below)
+
 6. NO EXCEPTIONS
    Errors halt execution. No try/catch. Use conditionals for error handling.
    Script-level exit functions (error, stop) must be host-provided.
@@ -80,7 +87,7 @@ SYNTAX QUICK REFERENCE
 
 Variables:     $name (always prefixed with $)
 Strings:       "hello {$var}"          # interpolation with {}
-               <<EOF ... EOF           # heredoc (also interpolates)
+               """..."""               # multiline (also interpolates)
 Numbers:       42, 3.14, -7
 Booleans:      true, false
 Lists:         [1, 2, 3]
@@ -118,10 +125,10 @@ Conditional (if-else):
 Piped conditional ($ becomes condition):
   value -> ? then_expr ! else_expr
 
-While loop:
+Condition loop (NO "while" keyword - use @ operator):
   init_value -> ($ < 10) @ { $ + 1 }  # $ is accumulator
 
-Do-while loop (body runs at least once):
+Do-condition loop (body runs at least once):
   init_value -> @ { $ + 1 } ? ($ < 10)
 
 Break (exits loop, returns collected results before break):
@@ -131,6 +138,39 @@ Return (exits block or script with value):
   { 5 :> $x; ($x > 3) ? ("big" -> return); "small" }  # returns "big"
   "done" -> return                                     # exits script with "done"
 
+LOOP STATE PATTERNS (CRITICAL)
+------------------------------
+Rill loops CANNOT modify outer variables. All state must flow through $ or $@.
+
+WRONG - outer variable modification (NEVER works):
+  0 :> $sum
+  [1, 2, 3] -> each { $sum + $ :> $sum }  # $sum unchanged!
+
+WRONG - "while" keyword does not exist:
+  while ($i < 10) { $i + 1 :> $i }        # SYNTAX ERROR
+
+RIGHT - use fold for reduction:
+  [1, 2, 3] -> fold(0) { $@ + $ }         # 6 ($@ is accumulator)
+
+RIGHT - use each(init) when you need both results AND accumulator:
+  [1, 2, 3] -> each(0) { $@ + $ }         # [1, 3, 6] (running totals)
+
+RIGHT - use (cond) @ { } with $ as state dict for multiple values:
+  [iter: 0, max: 3, text: $input, done: false]
+    -> (!$.done && $.iter < $.max) @ {
+      $.iter + 1 :> $i
+      process($.text) :> $result
+      $result.finished ? [iter: $i, max: $.max, text: $.text, done: true]
+                       ! [iter: $i, max: $.max, text: $result.text, done: false]
+    }
+  # Access final state: $.text, $.iter
+
+Pattern summary:
+  - Single value accumulation     -> fold(init) { $@ + $ }
+  - Per-item results + running    -> each(init) { ... $@ ... }
+  - Multiple state values / while -> (cond) @ { } with $ as state dict
+  - "while" and "for" keywords    -> DO NOT EXIST
+
 COLLECTION OPERATORS
 --------------------
 
@@ -286,10 +326,11 @@ COMMON MISTAKES
 2. Using || for defaults           -> use ?? instead
 3. Assuming truthiness             -> explicit boolean checks required
 4. Breaking from map/filter        -> only works in each/fold
-5. Expecting variable shadowing    -> not allowed
+5. Modifying outer vars in loops   -> use fold/$@ or $ as state dict (see LOOP STATE PATTERNS)
 6. Expecting variables to leak     -> block scope is strict
 7. Forgetting () on methods        -> .upper() not .upper (unless property)
 8. Reassigning different type      -> variables lock to first type
+9. Using while/for keywords        -> use (cond) @ { } or -> each { } instead
 
 SCRIPT RETURN VALUES
 --------------------