Decode/Encode to the next level

.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; if [[ \"$f\" == *.res ]]; then npx rescript format \"$f\" > /dev/null; fi; } 2>/dev/null || true",
+            "statusMessage": "Formatting ReScript..."
+          }
+        ]
+      }
+    ]
+  }
+}

.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wallaby": {
+      "command": "node",
+      "args": ["~/.wallaby/mcp/"]
+    }
+  }
+}

.cursor/skills/testing-wallaby/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: testing-wallaby
+description: Debug and fix failing tests using Wallaby.js MCP tools. Use when investigating test failures, debugging test errors, inspecting runtime values, checking code coverage, or updating snapshots.
+---
+
+# Testing with Wallaby
+
+Use Wallaby MCP tools as the primary way to work with tests. Fall back to terminal only if Wallaby is unavailable.
+
+## Debug Workflow
+
+### 1. Identify failures
+
+- **Broad**: `wallaby_failingTests` — all failing tests in the project
+- **By file**: `wallaby_failingTestsForFile` — failures related to a specific source or test file
+- **By line**: `wallaby_failingTestsForFileAndLine` — failures covering a specific line
+
+Each returns test name, test ID, errors with stack traces, runtime logs, and coverage percentage.
+
+### 2. Narrow down with coverage
+
+- `wallaby_coveredLinesForFile` — which lines a file has covered, optionally filtered by test ID
+- `wallaby_coveredLinesForTest` — all files/lines a specific test covers
+
+Use coverage to find the implementation code a failing test actually executes.
+
+### 3. Inspect runtime values
+
+- `wallaby_runtimeValues` — value of an expression at a file/line across all tests
+- `wallaby_runtimeValuesByTest` — value of an expression at a file/line for a specific test
+
+Required params: `file`, `line` (1-based, count blank lines), `lineContent`, `expression`. For `runtimeValuesByTest`, also `testId`.
+
+### 4. Fix the code
+
+Apply the fix based on evidence from steps 1-3.
+
+### 5. Verify the fix
+
+- `wallaby_testById` — re-check a specific test by its ID
+- `wallaby_failingTests` — confirm no remaining failures
+
+Iterate steps 3-5 until the test passes.
+
+### 6. Update snapshots (if needed)
+
+- `wallaby_updateTestSnapshots` — update snapshots for one test (by test ID)
+- `wallaby_updateFileSnapshots` — update all snapshots in/covering a file
+- `wallaby_updateProjectSnapshots` — update every snapshot in the project
+
+## Discovery Tools
+
+Use these when exploring tests, not just debugging failures:
+
+- `wallaby_allTests` — list every test in the project
+- `wallaby_allTestsForFile` — tests related to a specific file
+- `wallaby_allTestsForFileAndLine` — tests covering a specific file and line
+
+## Principles
+
+- Always cite runtime values and coverage data to justify conclusions.
+- Explain reasoning step by step.
+- Keep iterating with updated Wallaby data until the test passes.

CLAUDE.md

@@ -0,0 +1,104 @@
+# Sury Architecture
+
+## Schema Input and Output Types
+
+A schema represents two types: Input and Output.
+
+### Example 1: Same Input and Output
+
+```typescript
+S.string
+// Input: string
+// Output: string
+```
+
+### Example 2: Different Input and Output
+
+```typescript
+S.schema({
+  foo: S.string.with(S.to, S.number)
+})
+// Input: { foo: string }
+// Output: { foo: number }
+```
+
+The input and output differ because nested items have transformations, even though the schema itself does not have a `.to` property.
+
+## Modifying a Schema
+
+When modifying a schema, the modification applies to the output type.
+
+```typescript
+S.schema({
+  foo: S.string.with(S.to, S.number)
+}).with(S.refine, () => {...})
+```
+
+Since this schema does not have `.to`, `inputRefiner` and `refiner` must be stored separately to support `S.reverse`. Every schema should be reversible from Input→Output to Output→Input, unless explicitly prevented.
+
+For modifications like `name` or built-in refinements that do not affect nested items, they apply to both input and output without differentiation.
+
+## Decode Function
+
+The decode function is created from a single schema and transforms the schema's Input to Output. When multiple schemas are joined by the `.to` property, they are automatically combined into a single transformation pipeline.
+
+## Schema Properties and Execution Order
+
+Schema properties are executed in the following order:
+
+1. **decoder** - If input val differs from the schema, decode it to the schema's input type. May skip directly to schema output if there is no inputRefiner.
+
+2. **inputRefiner** - Custom validations on the input part of the schema value.
+
+3. **decoder** - Decodes input to output for the current schema. Typically required to decode nested items such as object fields.
+
+4. **refiner** - Custom validations on the output part of the schema value.
+
+### If Schema Has `.to` Property
+
+5. **parser** - Custom transformation logic to the `.to` schema. The serializer is the reverse of parser.
+
+### If There Is No Parser
+
+5. **encoder** - Transformation logic from the current schema's output to the `.to` schema's input.
+
+6. **.to.decoder** - Starts the cycle from the beginning with the `.to` schema.
+
+## Reversal with S.reverse
+
+`S.reverse` swaps:
+
+- `inputRefiner` ↔ `refiner`
+- `parser` ↔ `serializer`
+- Reverses the `.to` chain direction
+
+## Async Support
+
+Every transformation may return an async value. To continue the transformation chain:
+
+1. Append `.then()` and continue the logic in the callback function.
+2. For nested items (e.g., object fields, array items), create a promise that collects all inner items with `Promise.all()`.
+
+## Val
+
+The `val` represents a value at a specific point in time during compilation. Each `val` reflects a specific value type at that moment.
+
+Key properties:
+
+- `schema` - The actual type of the value at this point
+- `expected` - The schema to build decoder for
+- `var` - Returns the variable name in generated code
+- `inline` - The value as an inline code expression
+- `path` - Current location in the data structure (for error messages)
+
+Transformation tracking (relative to `.prev`):
+
+- `prev` - The previous val in the chain, indicating where this value originated from
+- `code` - Generated code describing the transformation from `.prev` to this val
+- `validation` - Type check condition from `.prev` (e.g., `typeof x === "string"`). Different from custom refiners.
+
+This design allows tracing back through the transformation history, where each step records what code was generated and what validations were applied to get from the previous state to the current one.
+
+- `B.refine` allows to modify the value, by cloning, while keeping the var allocation link.
+
+- `skipTo` is used to abort the parse after finishing current decoder. Ideally to get rid of it and use `val.expected` instead.

CONTRIBUTING.md

@@ -17,6 +17,127 @@ The following steps will get you setup to contribute changes to this repo:
 5. Run `pnpm res` to run ReScript compiler
 6. Run `pnpm test` for tests or use Wallaby.js
 
+## Architecture
+
+This section describes the internal architecture of Sury to help with understanding and contributing to the codebase.
+
+### Core Concepts
+
+#### Schema (internal type)
+
+The internal representation of a type schema, containing:
+
+- `tag`: Type identifier (e.g., `stringTag`, `objectTag`, `arrayTag`)
+- `decoder`: Builder function for input validation (type checking)
+- `encoder`: Builder function for converting from different schema types
+- `parser`: Builder function for transformations after decoding (used by `S.shape`, `S.to`)
+- `serializer`: Builder function for reverse transformations
+- `to`: Target schema for transformations (set by `S.shape`, `S.to`)
+- `from`: Path array indicating where this value comes from in shaped schemas
+- `properties`: For object schemas, a dict of field name to schema
+- `items`: For array/tuple schemas, an array of item schemas
+
+#### Builder
+
+A builder is a function with signature `(~input: val, ~selfSchema: internal) => val`. Builders generate JavaScript code at compile time by manipulating `val` objects. They are created using `Builder.make`:
+
+```rescript
+let myBuilder = Builder.make((~input, ~selfSchema) => {
+  // Generate code and return output val
+  let output = input->B.val(`someTransform(${input.var()})`, ~schema=selfSchema)
+  output
+})
+```
+
+#### Val (Value)
+
+A compilation-time representation of a value being processed. Key fields:
+
+- `inline`: The generated code expression (e.g., `i["foo"]`, `v0`)
+- `var()`: Function to allocate/retrieve a variable name (use when value is referenced multiple times)
+- `schema`: The schema of the current value
+- `expected`: The schema we're trying to parse/convert into
+- `from`: Link to the input val (for code merging)
+- `code`: Generated code statements
+- `validation`: Optional validation function to generate type checks
+- `skipTo`: When `Some(true)`, prevents `parse` from following the `.to` chain
+- `global`: Shared compilation context containing:
+  - `embeded`: Array of embedded values (functions, constants) accessible as `e[n]`
+  - `varCounter`: Counter for generating unique variable names
+
+### Compilation Flow
+
+When a schema operation is compiled (e.g., `parseOrThrow`), the following happens:
+
+```
+Input Schema
+     │
+     ▼
+┌─────────────────────────────────────────────────────────┐
+│  parse(val) function                                    │
+│                                                         │
+│  1. Encoder (if input.schema !== expected)              │
+│     - Converts between different schema types           │
+│                                                         │
+│  2. Decoder (always runs)                               │
+│     - Validates input type (e.g., typeof === "string")  │
+│     - Generates validation code                         │
+│                                                         │
+│  3. Parser (if expected.parser exists)                  │
+│     - Applies transformations (S.transform, S.shape)    │
+│                                                         │
+│  4. Recursive parse (if expected.to exists)             │
+│     - Follows transformation chain                      │
+│     - Skipped if val.skipTo === Some(true)              │
+└─────────────────────────────────────────────────────────┘
+     │
+     ▼
+Output Val with merged code
+     │
+     ▼
+B.merge() → JavaScript function string
+```
+
+### Code Generation Example
+
+For `S.object(s => s.field("foo", S.string))`:
+
+```javascript
+// Generated parse function:
+(i) => {
+  if (typeof i !== "object" || !i) {
+    e[0](i);
+  } // Object validation
+  let v0 = i["foo"]; // Field access
+  if (typeof v0 !== "string") {
+    e[1](v0);
+  } // String validation
+  return v0; // Return parsed value
+};
+```
+
+Where:
+
+- `i` is the input argument
+- `e` is the embedded values array (error throwers, transformers)
+- `v0`, `v1`, etc. are allocated variables
+
+### Key Functions
+
+- `parse(val)`: Main compilation function that walks through encoder → decoder → parser → to chain
+- `B.merge(val)`: Collects all generated code from the val chain into a single string
+- `B.Val.cleanValFrom(val)`: Creates a clean copy of val for new code generation while preserving variable binding
+- `B.embed(val, value)`: Embeds a runtime value (function, object) and returns reference like `e[0]`
+
+### Shaped Schemas (S.shape, S.object with definer)
+
+Shaped schemas use a proxy-based approach to track how values are used:
+
+1. During schema definition, field accesses are tracked via `proxifyShapedSchema`
+2. Each accessed field gets `from` set to its path (e.g., `["foo"]` for `s.field("foo", ...)`)
+3. During parsing, `shapedParser` traverses the target structure and maps values from input
+4. During serialization, `shapedSerializer` builds an accumulator (`acc`) that maps output paths to input vals, then `getShapedSerializerOutput` reconstructs the original structure
+
 ## PPX
 
 ### With Dune