fusion-lang 0.0.1.alpha1 → 0.0.1.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0d1da5a83d2c41381cc04c4fd850a157469fdf91718dc306ed0ef3149ce9259
-  data.tar.gz: 6c39994be87efa19c5a6dda7e4c61b9325dfb91b13f1a9c25999ec0435e22a09
+  metadata.gz: 4300463df5e82850cc75d27151c01a6b83e3cd66b90a5c820d40f27d54787250
+  data.tar.gz: 044f7a4883952b56aa4336067c994ab78a7dd84e8116f68501c229414c91512e
 SHA512:
-  metadata.gz: e268696a925a14546b58fa19ab7f474fc7235b88051910ff861cb649fb6b6842ada3a62cbaf11b2f823026b86debf7431c4b95117b83b9b35f1e6f6601219cc1
-  data.tar.gz: 539eb8f3e2f7de51f882c83aa4af6bde340aae4d4312d066ca05d7fc8151adf0a765565d1c8622d26ee2645a44e3cee3a50d8bc129562b876e58ce0c8b34eaf3
+  metadata.gz: 0d0cd98c87c04c9cc88694ad3d4e926103334fd03d5bfadcf147050c41f63bdb17b4b1bfaad9a5cd9bc456d5ea3ec17ded24db02e4d83d4035d1f403d4d669d6
+  data.tar.gz: 38d2637d43d8cbc5c17423a329e64605cde2cb2d154207174ec482611df43b1bc1f5d8435bd1bda751528bdc4a7d029b751b0e5f3fa11d10731afe82044b745a

data/README.md

@@ -59,12 +59,16 @@ echo '5' | fusion examples/factorial.fsn        # => 120
 echo '15' | fusion examples/fizzbuzz.fsn        # => "FizzBuzz"
 fusion examples/factorial.fsn 5                 # => 120 (input as an argument)
 fusion -e '(n => [n,2] | @multiply)' 21         # => 42 (inline program)
+printf '[1, 2]\n[3, 4]\n' | fusion --stream examples/double.fsn   # => [2,4] [6,8] (NDJSON, one value per line)
+fusion --repl                                   # interactive expressions and `name = expression`
 ```
 
 - Input is read from stdin (or the 2nd CLI arg) as JSON and parsed into a Fusion value.
 - The file's function gets applied to this value: `value | function`
 - The result gets printed as JSON to stdout.
 - Errors get printed to stderr instead and set exit code `1`.
+- How errors cross the boundary is configurable per side (`--input` / `--output`);
+  see the [reference](docs/user/reference.md) §9.4.
 
 ## Documentation
 
@@ -74,6 +78,14 @@ Refer to the [Documentation](docs/index.md) for further information.
 
 After checking out the repo, run `bin/setup` to install dependencies. Run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Tests
+
+```sh
+bundle exec rspec                    # fast suite (default) — skips the slow specs
+bundle exec rspec spec/cli_spec.rb   # naming a slow file runs it anyway
+bundle exec rake spec:all            # everything, including the slow specs
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -3,6 +3,15 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
+# task :spec (skips slow files, see .rspec)
 RSpec::Core::RakeTask.new(:spec)
 
+namespace :spec do
+  # task :all
+  desc "Run all specs, including the slow ones (real binary / pty)"
+  RSpec::Core::RakeTask.new(:all) do |task|
+    task.rspec_opts = "--options .rspec-ci"
+  end
+end
+
 task default: :spec

data/docs/lang/design.md

@@ -137,6 +137,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - 🧑 ✅ Every function takes exactly one argument and returns one value.
 - 🧑 ✅ A function literal is `(pattern => result, pattern => result, ...)`.
 - 🧑 ✅ Clauses are tried top to bottom; the first match wins.
+- 🧑 ✅ The clause list may be empty: `()` is the empty function (not an empty/invalid grouping).
 
 ### Alternatives
 
@@ -216,6 +217,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - 🧑 ✅ Predicate functions double as a runtime type system: the built-in "types" (`Integer`, `String`, …) are ordinary predicate functions, so `a ? @Integer` matches only integers (inspired by the Ruby gem "literal").
 - 🔢 ✅ The `?` refinement may follow *any* pattern, not just a lone binder; the clause then matches iff the pattern matches structurally **and** the matched value piped into the predicate yields `true` (Claude offered a restrictive per-binder form vs. this permissive any-pattern form; the designer chose permissive).
 - 🧑 ✅ The predicate is any function.
+- 🧑 ✅ A predicate may be a `|` chain of functions, the matched value flowing in from the left: `a ? b | c` matches when `a` matches and `a | b | c` is truthy. The grammar's `predicate` is a full `pipe` (was a single `prefix`).
 
 ### Alternatives
 
@@ -223,12 +225,14 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - 🤖 ❌ Typed pattern keywords (`n: int`).
 - 🤖 💭 A separate static type system.
 - 🤖 ❌ `if`-style guards with arbitrary boolean expressions.
+- 🤖 💭 Keep predicates single-function and compose via an inline `(x => x | b | c)`. Rejected: pure noise next to `b | c`.
 
 ### Pros
 
 - Unifies three things (structural matching, type checks, value guards) into one mechanism.
 - The "type system" is user-extensible with ordinary functions.
 - Nothing new to learn beyond `?`.
+- Predicates compose directly (`a ? @ends | @equals`) instead of requiring a wrapping function (`a ? (x => x | @ends | @equals)`).
 
 ### Cons
 
@@ -292,7 +296,7 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 ### Cons
 
 - `_` does not mean "literally anything" (it excludes `!`), a subtle asymmetry.
-- 🩹 An uncaught error can travel far from its origin, which can make debugging harder (mitigated by `FUSION_DEBUG`, by the payload from 2.8, and by potential future diagnostics tracked in the roadmap).
+- 🩹 An uncaught error can travel far from its origin, which can make debugging harder. Partially mitigated by more detailed error payloads in 2.9. Could be improved further with stack traces, see roadmap.
 
 ---
 
@@ -352,16 +356,117 @@ Future work and open questions are tracked separately in our [Roadmap](./roadmap
 - The catch site can dispatch on the error kind (`(!{"kind":"missing_key"} => ..., !msg => !msg)`).
 - Construction and matching are syntactically symmetric (`!42` builds on the right of `=>`, matches on the left).
 - Propagation remains uniform, with no carve-outs to remember.
+- The previous error model with the single error value `!` can still be emulated:
+  - The expression `!` is equivalent to `!null`.
+  - The pattern `!` is equivalent to `!_`.
 
 ### Cons
 
-- The payload format is part of the language's surface — built-ins use string payloads (`"divide: division by zero"`) while runtime mechanics use structured object payloads (`{"kind": ...}`), an inconsistency tracked in the roadmap.
+- 🩹 The payload format is part of the language's surface. Builtins used string payloads (`"divide: division by zero"`) while the standard library used structured object payloads (`{"kind": ...}`). This inconsistency was resolved in 2.9.
 - A payload that itself contains sensitive data becomes part of the program's stderr stream.
 - The bare-`!`-means-`!null` rule preserves a simple expression form but means a careless `_ => !` clause gives a maximally unhelpful error.
 - Inspecting an error's payload requires a small catch-and-rebind (`(!a => a)`) rather than direct comparison.
 
 ---
 
+## 2.9 Standardized error payloads
+
+### Decisions
+
+- 🧑 ✅ Every error payload produced by "the runtime" (the interpreter or a built-in function) has the **same shape**. This shape is enforced by constructing "internal errors" via `ErrorVal.internal`. The full schema is documented in [reference §6.5](../user/reference.md#65-the-standardized-error-payload).
+- 🤖 ✅ The stdlib is "ordinary unpriviledged Fusion code" and doesn't produce internal errors.
+- 🧑 ✅ However, all stdlib functions mirror the built-in error shape.
+- 🔢 ✅ During function application we differentiate between:
+  - `argument_error`: bad *input shape* (e.g. the wrong number of inputs). Constraints that could be expressed as a pattern without `?`.
+  - `type_error`: unsupported *input type* (e.g. string instead of number) or constraints between multiple inputs. Usually would require a `?` to express as a pattern.
+- 🧑 ✅ Member/index access reserves `access_error` for exactly `missing key` and `index out of range`:
+  - Accessing a member of a non-object or indexing with a wrong-typed key is a `type_error` instead.
+  - File-system access failures ("missing file", "directory instead of file", "permission denied") are a `reference_error` instead.
+
+### Alternatives
+
+- 🔢 ⏪ Keep the previous split between builtin errors (string payload) and stdlib errors (object payloads). Only document the rule.
+- 🧑 💭 Don't standardize the error payloads at all.
+
+### Pros
+
+- Every catch site (`!` pattern) can rely on this default shape.
+- The structured fields make errors self-describing (what failed, where, on what input).
+
+### Cons
+
+- The new structured payloads are more verbose than the old bare strings.
+- Some converted Ruby messages still leak host detail (e.g. an `Errno` message). Pending per-case cleanup.
+
+---
+
+## 2.10 Disallow duplicate binders
+
+### Decisions
+
+- 🧑 ✅ Binding the same identifier twice in one clause is a `binding_error`.
+- 🤖 ✅ It is detected in `match` as the binding is produced, so it surfaces only when the clause's shape otherwise matches. A non-matching shape just means the clause does not apply.
+
+### Alternatives
+
+- 🧑 ❌ Binding the same identifier twice is a non-linear "must be equal". The pattern only matches, if all parts with the same identifier have the same value.
+
+### Pros
+
+- Less implementation effort than "equal identifiers mean equal value". Already solved by fully generic `?` predicates.
+- Runtime detection fits to this language's dynamic nature.
+
+### Cons
+
+- Slightly less expressive pattern language.
+- Invalid patterns will only raise an error as soon as a value actually matches. No static guarantees.
+
+---
+
+## 2.11 Stricter objects: unique keys, rest last, closed by default
+
+### Decisions
+
+- 🧑 ✅ A fixed object key may not repeat (in expressions and patterns). Keys arriving via `...spread` / `...rest` are dynamic and not checked.
+- 🧑 ✅ In an object pattern, `...rest` must come last.
+- 🧑 ✅ An object pattern without a `...rest` is *closed*. It matches only an object whose keys are *exactly* the pattern's
+
+### Alternatives
+
+- 🤖 💭 Last-write-wins for duplicate literal keys (JSON behavior). Rejected: silently dropping a written key hides mistakes.
+- 🧑 ⏪ Object patterns always open — extra keys ignored regardless of a rest. Superseded: it gave no way to assert "exactly these keys".
+
+### Pros
+
+- Duplicate keys and misplaced rests are caught statically with a precise message.
+- Closed matching regains full-shape matching, with `...` the explicit opt-in to extra keys — symmetric with arrays.
+
+### Cons
+
+- More verbose common case: ignoring extra keys now needs a trailing `...`.
+
+---
+
+## 2.12 Switching to Ruby's truthiness model
+
+### Decisions
+
+- 🧑 ✅ Truthiness is Ruby-style: every value is truthy except `false` and `null`. This applies to the `@and`/`@or`/`@not` built-ins and `?` predicates.
+
+### Alternatives
+
+- 🧑 ⏪ The builtins `@and`/`@or`/`@not` are strict and return a `type_error` for non booleans. Predicates match only on exactly `true`.
+
+### Pros
+
+- Booleans operations return `type_error`s less frequently and are more useful. A lot more functions work as predicates.
+
+### Cons
+
+- If you really wanted "strict booleans", you'd now need to build them yourselves.
+
+---
+
 # 3. @ references
 
 ## 3.1 A file contains exactly one value
@@ -560,7 +665,103 @@ All access goes through `@`:
 ### Cons
 
 - No streaming; whole input must be buffered and parsed.
-- 🩹 A bare `!` with nonzero exit gives little diagnostic detail (mitigated by `FUSION_DEBUG`).
+- 🩹 A bare `!` with nonzero exit gives little diagnostic detail. Mitigated for internal errors by more detailed error payloads in 2.9.
+
+---
+
+## 4.2 No raw Ruby errors reach the user
+
+### Decisions
+
+- 🧑 ✅ The CLI contract already spends stdout (the result) and stderr (the error payload). There is **no third channel**, so a raw Ruby backtrace on stderr would corrupt the contract. Fusion therefore **catches every Ruby error a program can trigger and converts it to a standardized payload**.
+- 🔢 ✅ Conversion happens *both* **deep** (so an error becomes catchable by other code as soon as possible) *and* at a **top-level net** (so nothing escapes). Notably `SystemStackError` becomes a regular error value `stack_error` on stderr.
+- 🧑 ✅ The internal "assertions" (`raise Unreachable`) are a deliberate exception. Reaching them is an interpreter bug. Interpreter bugs should surface and are allowed to violate our CLI contract.
+- 🧑 ✅ The old `FUSION_DEBUG` env var (which wrote to stderr via `warn`) is removed entirely.
+
+### Alternatives
+
+- 🤖 ❌ A top-level net only — rejected because a mid-program Ruby error would then become a final result rather than a catchable `!`.
+- 🤖 💭 An `internal_error` kind for the invariant asserts. Rejected, because interpreter bugs shouldn't be catchable and shouldn't be a seemingly regular final result.
+
+### Pros
+
+- The CLI contract holds unconditionally. A program can even crash the interpreter's host language via infinite recursion and the user still gets a clean JSON payload and exit `1`.
+
+### Cons
+
+- Implementation effort.
+- Might hide valuable debugging information. However, the "top-level net" could be made opt-out.
+- The `location` for a stack overflow is only `"interpreter"`. No single owning file is knowable at that point.
+
+---
+
+## 4.3 Internal errors and lenient JSON serialization
+
+### Decisions
+
+- 🔢 ✅ To serialize values without a valid JSON representation, we introduce "lenient serialization". Values without JSON representation get turned into string representations (`"<function>"` and `"<Infinity>"`/`"<-Infinity>"`/`"<NaN>"`).
+- 🧑 ✅ The remaining data structure gets preserved.
+- 🔢 ✅ Internal errors (`ErrorVal.internal_error?`) get serialized leniently by default, so their info isn't obscured by a `serialization_error`.
+- 🤖 ✅ The stdlib doesn't produce internal errors.
+- 🧑 ✅ However, all stdlib functions use `@sanitize` to mimick the lenient JSON serialization and preserve as much info as possible.
+- 🧑 ✅ Ordinary values and user errors are serialized strictly to avoid surprising type conversions. If they fail to serialize, they get turned into an internal `serialization_error` and will subsequently get serialized leniently.
+
+### Alternatives
+
+- 🤖 ❌ The standard library could create real "internal errors" via a dedicated `@raise` primitive. Declined, because it offers little over the `!` prefix and would let any code (not just the stdlib) create internal errors. The main reason for internal errors (apart from enforcing a consistent shape) is lenient serialization.
+- 🧑 ❌ Internal errors also serialize strictly by default. Rejected, because this would turn too many errors into a `serialization_error` and would lose too much information.
+- 🧑 💭 All errors serialize leniently by default. Rejected, because this hides real errors (e.g. `NaN` or a function as a result) behind an automatic type conversion.
+
+---
+
+## 4.4 CLI use cases and I/O modes
+
+Extends the single runtime contract of 4.1 into three use cases and four ways an
+error value can cross the boundary.
+
+### Decisions
+
+**Use cases:**
+
+- 🧑 ✅ The CLI supports three use cases: **pipe** (apply the program to one input — the 4.1 model, the default), **stream** (apply it to each line of an NDJSON stream), **repl** (interactive).
+- 🧑 ✅ **stream** keeps errors in-band and always exits `0`; a failing record (including a stack overflow) becomes that record's output line and the stream continues. Blank input lines are skipped.
+
+**I/O modes** — how an error is marked crossing the boundary; `--input` and `--output` are independent:
+
+- 🧑 ✅ Four modes: **unix** (plain JSON; value → stdout/exit 0, error → stderr/exit 1, as in 4.1), **bang** (a leading `!` marks an error), **array** (`[0, value]` / `[1, payload]`), **object** (`{"value": _}` / `{"error": _}`).
+- 🧑 ✅ The `-!` flag (unix input only) makes the whole input an error value.
+- 🧑 ✅ pipe supports all four modes; stream all but unix; repl has none.
+- 🤖 ✅ Defaults: pipe = unix/unix, stream = bang/bang. The non-unix modes always print to stdout and exit `0`.
+- 🤖 ✅ Empty input is `null` in every input mode; `-!` on empty input is `!null`.
+- 🤖 ✅ A malformed `array`/`object` input envelope is a catchable `argument_error` at `location: "input"` (the array tag must be exactly the integer `0`/`1`), flowing into the program like any input error.
+
+**REPL:**
+
+- 🧑 ✅ An entry is an **expression** (evaluated and printed) or a **statement** `identifier = expression` (evaluated, printed, and bound for later entries). The statement is the only construct that is not an expression.
+- 🧑 ✅ An entry is evaluated only once it parses as a whole statement/expression; an incomplete or invalid buffer keeps the entry open to finish or correct.
+- 🧑 ✅ A statement binds its identifier to the result **including an error result**; reading it back later propagates the error, exactly like reading an `@`-reference that resolved to one.
+- 🤖 ✅ Results print leniently (a function as `"<function>"`, etc.); entries report errors at `location: "code <inline>"`, like `-e`.
+- 🤖 ✅ Results go to stdout; the prompt and echoed input go to stderr (like a shell prompt), so stdout is a clean stream of results.
+- 🤖 ✅ A command-line misuse (unknown flag, unsupported mode combination, missing program) is plain usage text on stderr with exit `1` — it precedes the I/O contract, so it is not a payloaded error.
+
+### Alternatives
+
+- 🧑 ⏪ REPL accepts only statements (the original "introduces a single statement" sketch); widened so a bare expression is also an entry.
+- 🧑 ⏪ Statements terminated by `;` (so several could share a line); dropped — completeness is decided by parsing, so a line that parses is submitted and no terminator is needed.
+- 🤖 ⏪ A statement does **not** bind an error result (mirroring pattern binders, which never capture an error). Flipped: a statement is an assignment, not a pattern match; binding an error is harmless and needs no special case.
+- 🤖 ❌ unix mode for stream — one exit code and one stdout/stderr pair cannot mark errors per record.
+- 🤖 💭 A single `--mode` controlling both directions — input and output modes are deliberately independent.
+
+### Pros
+
+- One small flag surface spans first-class Unix filters (pipe), bulk processing (stream), and interactive exploration (repl).
+- Errors cross the boundary in whatever shape the surrounding tool wants — exit code, `!` sentinel, or envelope — with input and output chosen independently.
+- The REPL reuses the whole language: an entry is just an expression, with assignment the one addition, and a bound error propagates like any other value-or-error (no carve-out).
+
+### Cons
+
+- Four error-marking modes are more surface than the original single unix contract.
+- Completeness-by-parsing submits a complete-but-maybe-unintended line (e.g. `x = 5` when more was meant) as-is.
 
 ---
 

data/docs/lang/roadmap.md

@@ -22,26 +22,6 @@ a directory, since shadowing is invisible at the call site.
 
 ## 2. Error model
 
-**Payload shape consistency** *(open)*. The payload *shape* is inconsistent:
-built-ins use bare strings (`"divide: division by zero"`) while runtime
-mechanics use structured objects (`{"kind":"missing_key","key":"foo"}`). The
-string form is human-friendlier; the structured form is machine-friendlier
-(catchable via `!{"kind": k}`). Three plausible resolutions:
-
-- (a) all errors get structured payloads with a `kind` and an optional `message`;
-- (b) all errors get human strings, and structured matching is left to user code;
-- (c) keep both, document the rule that built-in operations use strings and
-  runtime mechanics use objects.
-
-This is a small but irreversible decision (it shapes how catch clauses are
-written) and should be decided before any external code grows that depends on
-the current shapes.
-
-**Better diagnostics.** `FUSION_DEBUG` exists for file/parse errors; extend
-principled diagnostics to runtime error origins (where did this error first
-arise?). One option: attaching a source position to the payload (an extra
-`"at": "file.fsn:L:C"` field) when `FUSION_DEBUG` is set.
-
 **Stack traces** *(deferred)*. A propagated error tells you what happened, but
 not the chain of function applications it passed through. A capped trace
 (last N frames, accessible as an extra payload field, opt-in via env) would
@@ -54,7 +34,7 @@ help in deep pipelines.
 Populate Tier 1 (written in Fusion): `filter`, `reduce`/`fold`, `reverse`,
 `head`, `tail`, `last`, `init`, `take`, `drop`, `zip`, `flatten`, `member`,
 `find`, `all`, `any`, `count`; comparison derivatives `lessEq`, `greaterThan`,
-`greaterEq`, `notEquals`; object helpers `entries`, `get`, `set`, `merge`; an
+`greaterEq`, `notEquals`; object helpers `entries`, `merge`; an
 `if` helper. This is also the best stress test of whether the language is
 pleasant to *write* in, not just to implement.
 
@@ -62,7 +42,6 @@ pleasant to *write* in, not just to implement.
 
 ## 4. Runtime and tooling
 
-- **Streaming I/O** (NDJSON): map a program over a stream of JSON values.
 - **A faster implementation** once semantics are frozen.
 
 ## 5. Open semantic questions to settle

data/docs/user/how-to-guides.md

@@ -8,18 +8,12 @@ basics. Scan for the problem you have and copy the solution.*
 ## Diagnose a program that returns an error unexpectedly
 
 When you run a program and see an error payload on stderr, the payload itself
-usually tells you what went wrong (e.g. `"divide: division by zero"` or
-`{"kind":"missing_key","key":"email"}`). For errors arising *during reference
-resolution* — typically a missing file or a parse error in an `@`-referenced file —
-enable extra diagnostics:
+tells you what went wrong. Interpreter errors carry a standardized object whose
+fields (`kind`, `location`, `operation`, `input`, `message`) are documented in
+[reference §6.5](./reference.md#65-the-standardized-error-payload).
 
-```sh
-FUSION_DEBUG=1 fusion program.fsn '...'
-```
-
-With `FUSION_DEBUG` set, the interpreter prints to stderr the exact path it failed
-to find or the parse error it hit. The most common cause is that the `stdlib/`
-folder is not where the interpreter expects it, so `@`-references can't be resolved.
+For a missing file or a parse error in an `@`-referenced file, the `location` and
+`input` fields name the exact path that failed.
 
 ---