lil-mocky 1.4.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,191 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+lil-mocky is a lightweight JavaScript mocking library for testing. It provides builders for creating mock functions, objects, and classes with call tracking and return value control. It also includes a spy function for tracking calls to existing methods.
+
+## Development Commands
+
+### Testing
+```bash
+npm test                    # Run all tests with Mocha
+npm test -- --grep "pattern" # Run specific tests matching pattern
+./test-docker.sh            # Run tests in Docker
+```
+
+### Docker
+```bash
+docker build -t lil-mocky .
+docker run lil-mocky npm test
+./test-docker.sh            # Convenience script
+```
+
+## Architecture
+
+### Core Builder Pattern
+
+The library uses a fluent builder pattern where each builder type (function, object, class) implements a `build()` method that returns a "wired" mock with testing utilities.
+
+**Builder Flow**: `builder.build() -> wire*(mock, state) -> mock`
+
+**Standard usage**: Call `.build()` on any builder to create a mock:
+```javascript
+const mock = mocky.function().args('x').build();
+```
+
+Each builder:
+1. Accepts configuration through chainable methods
+2. Creates the underlying mock structure via `build()`
+3. Gets "wired" with helper methods (`ret()`, `calls()`, `reset()`, etc.)
+4. Returns a mock that tracks interactions
+
+### Function Mocks (functionBuilder)
+
+Function mocks support:
+- **Named arguments**: `.args('arg1', { arg2: 'default' })` - Maps positional arguments to named properties
+- **Argument selection**: `.argSelect(0, 2)` - Only capture specific argument positions
+- **Custom body**: Pass a function receiving `{self, state, call, args, rawArgs, original, ret}` context
+- **Async functions**: `.async()` flag creates async mock
+- **Original function**: `.original(fn)` - Stores the original function in context (used by spy)
+
+**Context object properties**:
+- `self` - The `this` context
+- `state` - Internal state object
+- `call` - Call number (1-indexed)
+- `args` - Processed arguments (based on `.args()` configuration)
+- `rawArgs` - Unprocessed arguments array
+- `original` - Original function (if set via `.original()`)
+- `ret` - Configured return value (if set via `.ret()`)
+
+**Call tracking**: Function state includes `state.calls` array where each entry contains the processed arguments for that call.
+
+**Return values**: Set via `mock.ret(value, callIndex)` or `mock.onRet(handler, callIndex)`. Call index 0 is the default for all calls.
+
+### Object Mocks (objectBuilder)
+
+Objects are containers for properties that can be:
+- Nested builders (function, object) - automatically built
+- Plain values - assigned directly
+
+The `reset()` method:
+- Recursively calls `reset()` on all nested mocks
+- Restores plain properties to their initial values
+- Deletes properties added after creation
+
+### Class Mocks (classBuilder)
+
+Classes use a special instance management system:
+- **Instance descriptions**: `state.descriptions[index]` holds the member structure for each instance
+- **Lazy creation**: Descriptions are created on-demand when an instance is constructed or accessed via `Mock.inst(index)`
+- **Shared state per instance**: All instances share the same descriptions array, allowing pre-configuration before instantiation
+
+Example: `Mock.inst(0).method.ret('value')` configures the first instance's method before calling `new Mock()`.
+
+**Direct instance access**: Mock helpers (`.calls()`, `.ret()`, `.reset()`) are accessible directly on instance methods:
+```javascript
+const inst = new Mock();
+inst.method('test');
+inst.method.calls(0);  // Works! Returns call arguments
+inst.method.ret('value');  // Configure via instance
+```
+
+### State Management
+
+Each mock type maintains internal state through closures:
+- **Function state**: `{calls: [], rets: [], retHandlers: [], data: {}}`
+- **Class state**: `{descriptions: [], numInstances: 0, data: {}}`
+- **Object state**: Tracks `initialMocks` (Set) and `initialValues` (Map) for reset functionality
+
+The `state.data` object is available for custom builders to store arbitrary data.
+
+### Argument Processing
+
+`getFunctionArgs()` handles four modes:
+1. **Single select**: `.argSelect(2)` returns `callArgs[2]` directly
+2. **Named args**: `.args('a', 'b')` returns `{a: callArgs[0], b: callArgs[1]}`
+3. **Named with selection**: `.args('a', 'b').argSelect(1)` returns `{b: callArgs[1]}`
+4. **No configuration**: Returns raw arguments as array (e.g., `['val1', 'val2']`)
+
+**Breaking change**: Previously, no configuration returned `null`. Now returns an array to support spy functionality. This may affect existing code that expects `null` in `calls()` for unconfigured functions.
+
+Arguments are deep cloned before storage to prevent mutation issues.
+
+### Spy Function
+
+The `spy()` function is a non-builder API for tracking calls to existing methods while optionally replacing their implementation.
+
+**Signature**: `mocky.spy(object, methodName, replacement?)`
+
+**Parameters**:
+- `object` - The object containing the method to spy on
+- `methodName` - The name of the method to spy on
+- `replacement` - Optional `functionBuilder` to replace the method
+
+**Behavior**:
+- Without replacement: Calls through to original method by default
+- The spy IS a mock function with all standard methods (`.ret()`, `.calls()`, `.reset()`)
+- Setting `.ret()` overrides the call-through behavior
+- The `replacement` builder (if provided) receives `context.original` automatically
+- Call `.restore()` to put back the original method
+
+**Examples**:
+
+```javascript
+// Basic spy - tracks calls, calls through to original
+const spy = mocky.spy(obj, 'method');
+obj.method('test');
+spy.calls(0);  // ['test']
+
+// Override return value
+spy.ret('mocked');
+
+// Spy with custom replacement
+const spy = mocky.spy(obj, 'method', mocky.function((context) => {
+  const result = context.original.apply(context.self, context.rawArgs);
+  return result * 2;  // Modify original behavior
+}).args('x', 'y'));
+
+// Restore original
+spy.restore();
+
+// Works with prototypes, classes, etc.
+mocky.spy(MyClass.prototype, 'method');
+```
+
+**Use cases**:
+- Track calls to existing methods without modifying behavior
+- Temporarily override method behavior for testing
+- Spy on class prototype methods to affect all instances
+- Wrap existing functions with additional logic
+
+## Testing Patterns
+
+Tests use Chai's `expect` assertions. Common patterns:
+
+```javascript
+// Create and configure mocks
+const mock = mocky.function().args('arg').build();
+mock.ret('testRet');
+
+// Verify calls
+expect(mock.calls(0)).to.deep.equal({ arg: 'value' });
+expect(mock.calls().length).to.equal(1);
+
+// Class instance access
+const Mock = mocky.class({ method: mocky.function() }).build();
+Mock.inst().method.ret('value');  // Configure first instance
+expect(Mock.inst().constructor.calls(0)).to.deep.equal({ initArg: 'value' });
+
+// Spy on existing method
+const spy = mocky.spy(obj, 'method');
+obj.method('test');
+expect(spy.calls(0)).to.deep.equal(['test']);
+spy.restore();
+```
+
+## File Structure
+
+- `src/lil-mocky.js` - All implementation code (single file architecture)
+- `test/lilMockyTest.js` - Mocha/Chai test suite

package/Dockerfile

@@ -0,0 +1,2 @@
+FROM node:20.17.0
+WORKDIR /app