@rcrsr/rill 0.16.0 → 0.17.0

package/dist/runtime/ext/test-context.js

@@ -0,0 +1,154 @@
+/**
+ * Test Context Factory
+ *
+ * Creates a pre-wired RuntimeContext from extension value maps.
+ * Designed for testing and lightweight embedding without rill-config.
+ */
+import { parseSource } from '../../ext-parse-bridge.js';
+import { createRuntimeContext } from '../core/context.js';
+import { extResolver } from '../core/resolvers.js';
+import { isCallable } from '../core/callable.js';
+import { formatStructure } from '../core/values.js';
+// ============================================================
+// ERROR CLASS
+// ============================================================
+/**
+ * Error thrown when extension binding generation fails.
+ * Mirrors the ExtensionBindingError in rill-config for core-only usage.
+ */
+export class ExtensionBindingError extends Error {
+    code = 'EXTENSION_BINDING';
+    constructor(message) {
+        super(message);
+        this.name = 'ExtensionBindingError';
+    }
+}
+// ============================================================
+// BINDING GENERATOR
+// ============================================================
+/**
+ * Format a RillParam as a rill source parameter declaration.
+ * Produces `name: type` syntax matching the parser's closure annotation grammar.
+ */
+function formatParam(param) {
+    const typeName = param.type !== undefined ? formatStructure(param.type) : 'any';
+    return `${param.name}: ${typeName}`;
+}
+/**
+ * Check if a RillValue is a plain dict (not a callable, tuple, vector, etc.).
+ */
+function isPlainDict(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !isCallable(value) &&
+        !('__rill_tuple' in value) &&
+        !('__rill_vector' in value) &&
+        !('__rill_ordered' in value) &&
+        !('__rill_type' in value) &&
+        !('__rill_field_descriptor' in value));
+}
+/**
+ * Generate rill source for a nested value tree.
+ * Callable leaves produce `use<ext:path>:|params| :returnType`.
+ * Dict nodes recurse. All other values produce `use<ext:path>`.
+ */
+function buildNestedSource(value, path, indent) {
+    if (isCallable(value)) {
+        const c = value;
+        const paramStr = c.params.map(formatParam).join(', ');
+        const returnSuffix = ` :${formatStructure(c.returnType.structure)}`;
+        return `use<ext:${path}>:|${paramStr}|${returnSuffix}`;
+    }
+    if (isPlainDict(value)) {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return '[:]';
+        const childIndent = indent + '  ';
+        const parts = entries.map(([key, child]) => {
+            const childPath = path.length > 0 ? `${path}.${key}` : key;
+            const childSource = buildNestedSource(child, childPath, childIndent);
+            return `${childIndent}${key}: ${childSource}`;
+        });
+        return `[\n${parts.join(',\n')}\n${indent}]`;
+    }
+    // Scalar, list, tuple, vector: resolve directly via ext resolver
+    return `use<ext:${path}>`;
+}
+/**
+ * Generate rill source bindings from an extension value map.
+ * Returns a rill dict literal suitable for use as module:ext source.
+ *
+ * @throws {ExtensionBindingError} when binding generation fails
+ */
+function buildExtensionBindings(extensions) {
+    try {
+        const entries = Object.entries(extensions);
+        if (entries.length === 0)
+            return '[:]';
+        const parts = entries.map(([name, value]) => {
+            const source = buildNestedSource(value, name, '');
+            return `  ${name}: ${source}`;
+        });
+        return `[\n${parts.join(',\n')}\n]`;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new ExtensionBindingError(`Failed to generate extension bindings: ${reason}`);
+    }
+}
+// ============================================================
+// MODULE RESOLVER FOR EXT BINDINGS
+// ============================================================
+/**
+ * Create a module resolver that serves generated extension binding source.
+ * Handles only the `ext` resource; rejects all other module IDs.
+ */
+function createExtModuleResolver(bindingSource) {
+    return (resource) => {
+        if (resource === 'ext') {
+            return { kind: 'source', text: bindingSource, sourceId: 'module:ext' };
+        }
+        throw new Error(`Unknown module '${resource}'`);
+    };
+}
+// ============================================================
+// PUBLIC API
+// ============================================================
+/**
+ * Create a RuntimeContext pre-wired with extension values.
+ * Builds extension bindings, registers ext and module resolvers,
+ * and returns a context ready for execute().
+ *
+ * @throws {TypeError} when an extension value is undefined (EC-9)
+ * @throws {ExtensionBindingError} when binding generation fails (EC-10)
+ */
+export function createTestContext(extensions) {
+    // EC-9: Validate no undefined extension values
+    for (const [name, entry] of Object.entries(extensions)) {
+        if (entry.value === undefined) {
+            throw new TypeError(`Extension '${name}' has undefined value`);
+        }
+    }
+    // Build ext resolver config: maps extension names to their RillValues
+    const extConfig = {};
+    for (const [name, entry] of Object.entries(extensions)) {
+        extConfig[name] = entry.value;
+    }
+    // Generate rill source bindings (EC-10: propagates ExtensionBindingError)
+    const bindingSource = buildExtensionBindings(extConfig);
+    // Create module resolver for ext bindings
+    const extModuleResolver = createExtModuleResolver(bindingSource);
+    return createRuntimeContext({
+        resolvers: {
+            ext: extResolver,
+            module: extModuleResolver,
+        },
+        configurations: {
+            resolvers: {
+                ext: extConfig,
+            },
+        },
+        parseSource,
+    });
+}

package/dist/runtime/index.d.ts

@@ -18,19 +18,33 @@
  */
 export type { CaptureEvent, ErrorEvent, ExecutionResult, ExecutionStepper, HostCallEvent, FunctionReturnEvent, ObservabilityCallbacks, ResolverResult, RuntimeCallbacks, RuntimeContext, RuntimeOptions, SchemeResolver, StepEndEvent, StepResult, StepStartEvent, } from './core/types.js';
 export type { ApplicationCallable, CallableFn, RillCallable, RillFunction, RillParam, RuntimeCallable, ScriptCallable, } from './core/callable.js';
-export { callable, isApplicationCallable, isCallable, isDict, isRuntimeCallable, isScriptCallable, } from './core/callable.js';
-export type { NativeArray, NativePlainObject, NativeResult, NativeValue, RillFieldDef, RillIterator, RillTuple, RillType, RillTypeValue, RillValue, RillVector, } from './core/values.js';
-/** @deprecated Use RillType instead. Will be removed in the next major version. */
-export type { RillStructuralType } from './core/values.js';
-export { anyTypeValue, commonType, createTuple, createVector, formatStructuralType, inferElementType, inferStructuralType, inferType, isRillIterator, isTuple, isTypeValue, isVector, isReservedMethod, paramToFieldDef, rillTypeToTypeValue, RESERVED_DICT_METHODS, structuralTypeEquals, structuralTypeMatches, toNative, } from './core/values.js';
+export { callable, isApplicationCallable, isCallable, isDict, isRuntimeCallable, isScriptCallable, toCallable, } from './core/callable.js';
+export type { NativeArray, NativePlainObject, NativeResult, NativeValue, RillFieldDef, RillIterator, RillTuple, RillTypeValue, RillValue, RillVector, TypeStructure, } from './core/values.js';
+/** @deprecated Use TypeStructure instead. Will be removed in the next major version. */
+export type { RillType } from './core/values.js';
+export type { TypeDefinition, TypeProtocol, } from './core/type-registrations.js';
+export { anyTypeValue, commonType, createTuple, createVector, formatStructure, inferElementType, inferStructure, inferType, isIterator, isTuple, isTypeValue, isVector, isReservedMethod, paramToFieldDef, structureToTypeValue, RESERVED_DICT_METHODS, structureEquals, structureMatches, toNative, } from './core/values.js';
+/** @deprecated Use formatStructure instead. */
+export { formatStructuralType } from './core/values.js';
+/** @deprecated Use inferStructure instead. */
+export { inferStructuralType } from './core/values.js';
+/** @deprecated Use isIterator instead. */
+export { isRillIterator } from './core/values.js';
+/** @deprecated Use structureToTypeValue instead. */
+export { rillTypeToTypeValue } from './core/values.js';
+/** @deprecated Use structureEquals instead. */
+export { structuralTypeEquals } from './core/values.js';
+/** @deprecated Use structureMatches instead. */
+export { structuralTypeMatches } from './core/values.js';
 export { buildFieldDescriptor } from './core/field-descriptor.js';
 export { BreakSignal, ReturnSignal } from './core/signals.js';
 export type { ExtensionEvent } from './core/types.js';
-export type { ConfigFieldDescriptor, ExtensionConfigSchema, ExtensionFactory, ExtensionManifest, ExtensionResult, FsExtensionContract, HoistedExtension, KvExtensionContract, LlmExtensionContract, VectorExtensionContract, } from './ext/extensions.js';
+export type { ConfigFieldDescriptor, ExtensionConfigSchema, ExtensionFactory, ExtensionFactoryResult, ExtensionManifest, FsExtensionContract, KvExtensionContract, } from './ext/extensions.js';
 export type { SchemaEntry } from '../ext/kv/index.js';
-export { prefixFunctions, emitExtensionEvent, hoistExtension, } from './ext/extensions.js';
+export { emitExtensionEvent } from './ext/extensions.js';
 export { contextResolver, extResolver, moduleResolver, } from './core/resolvers.js';
-export { buildTypeMethodDicts, createRuntimeContext } from './core/context.js';
+export { createRuntimeContext } from './core/context.js';
+export { createTestContext, ExtensionBindingError, } from './ext/test-context.js';
 export type { CallFrame } from '../types.js';
 export { getCallStack, pushCallFrame, popCallFrame } from './core/context.js';
 export { createStepper, execute } from './core/execute.js';

package/dist/runtime/index.js

@@ -16,14 +16,27 @@
  * - ext/: Self-contained extensions
  *   - builtins.ts: Built-in functions and methods
  */
-export { callable, isApplicationCallable, isCallable, isDict, isRuntimeCallable, isScriptCallable, } from './core/callable.js';
-export { anyTypeValue, commonType, createTuple, createVector, formatStructuralType, inferElementType, inferStructuralType, inferType, isRillIterator, isTuple, isTypeValue, isVector, isReservedMethod, paramToFieldDef, rillTypeToTypeValue, RESERVED_DICT_METHODS, structuralTypeEquals, structuralTypeMatches, toNative, } from './core/values.js';
+export { callable, isApplicationCallable, isCallable, isDict, isRuntimeCallable, isScriptCallable, toCallable, } from './core/callable.js';
+export { anyTypeValue, commonType, createTuple, createVector, formatStructure, inferElementType, inferStructure, inferType, isIterator, isTuple, isTypeValue, isVector, isReservedMethod, paramToFieldDef, structureToTypeValue, RESERVED_DICT_METHODS, structureEquals, structureMatches, toNative, } from './core/values.js';
+// Deprecated aliases — old names kept for one release
+/** @deprecated Use formatStructure instead. */
+export { formatStructuralType } from './core/values.js';
+/** @deprecated Use inferStructure instead. */
+export { inferStructuralType } from './core/values.js';
+/** @deprecated Use isIterator instead. */
+export { isRillIterator } from './core/values.js';
+/** @deprecated Use structureToTypeValue instead. */
+export { rillTypeToTypeValue } from './core/values.js';
+/** @deprecated Use structureEquals instead. */
+export { structuralTypeEquals } from './core/values.js';
+/** @deprecated Use structureMatches instead. */
+export { structuralTypeMatches } from './core/values.js';
 export { buildFieldDescriptor } from './core/field-descriptor.js';
 // ============================================================
 // CONTROL FLOW SIGNALS
 // ============================================================
 export { BreakSignal, ReturnSignal } from './core/signals.js';
-export { prefixFunctions, emitExtensionEvent, hoistExtension, } from './ext/extensions.js';
+export { emitExtensionEvent } from './ext/extensions.js';
 // ============================================================
 // BUILT-IN RESOLVERS
 // ============================================================
@@ -31,7 +44,8 @@ export { contextResolver, extResolver, moduleResolver, } from './core/resolvers.
 // ============================================================
 // CONTEXT FACTORY
 // ============================================================
-export { buildTypeMethodDicts, createRuntimeContext } from './core/context.js';
+export { createRuntimeContext } from './core/context.js';
+export { createTestContext, ExtensionBindingError, } from './ext/test-context.js';
 export { getCallStack, pushCallFrame, popCallFrame } from './core/context.js';
 // ============================================================
 // SCRIPT EXECUTION

package/dist/signature-parser.d.ts

@@ -12,13 +12,13 @@
  *   which is NOT in parser/* or lexer/* — boundary preserved.
  */
 import type { RillParam } from './runtime/core/callable.js';
-import type { RillType } from './runtime/core/values.js';
+import type { TypeStructure } from './runtime/core/values.js';
 /**
  * Result of parsing a signature string at registration time.
  */
 export interface ParsedSignature {
     readonly params: RillParam[];
-    readonly returnType: RillType | undefined;
+    readonly returnType: TypeStructure | undefined;
     readonly description: string | undefined;
 }
 /**

package/dist/signature-parser.js

@@ -15,38 +15,38 @@ import { tokenize } from './lexer/index.js';
 import { ParseError, TOKEN_TYPES } from './types.js';
 import { createParserState, advance, check, current, expect, skipNewlines, isAtEnd, parseTypeRef, } from './parser/index.js';
 // ============================================================
-// TypeRef → RillType static conversion
+// TypeRef → TypeStructure static conversion
 // ============================================================
 /**
- * Convert a static TypeRef to a RillType.
+ * Convert a static TypeRef to a TypeStructure.
  *
  * Only handles static refs (type names and unions). Dynamic refs ($var)
  * are not valid in registration-time signatures — they throw Error.
  *
  * @internal
  */
-function staticTypeRefToRillType(typeRef, functionName) {
+function staticTypeRefToTypeStructure(typeRef, functionName) {
     if (typeRef.kind === 'dynamic') {
         throw new Error(`Invalid signature for function '${functionName}': dynamic type references ($variable) are not allowed in signatures`);
     }
     if (typeRef.kind === 'union') {
         return {
-            type: 'union',
-            members: typeRef.members.map((m) => staticTypeRefToRillType(m, functionName)),
+            kind: 'union',
+            members: typeRef.members.map((m) => staticTypeRefToTypeStructure(m, functionName)),
         };
     }
     // static kind
     const { typeName, args } = typeRef;
     if (!args || args.length === 0) {
-        return { type: typeName };
+        return { kind: typeName };
     }
     // Parameterized types
     if (typeName === 'list') {
         if (args.length === 1 &&
             args[0] !== undefined &&
             args[0].name === undefined) {
-            const element = staticTypeRefToRillType(args[0].value, functionName);
-            return { type: 'list', element };
+            const element = staticTypeRefToTypeStructure(args[0].value, functionName);
+            return { kind: 'list', element };
         }
         throw new Error(`Invalid signature for function '${functionName}': list requires exactly one positional type argument`);
     }
@@ -57,17 +57,17 @@ function staticTypeRefToRillType(typeRef, functionName) {
                 throw new Error(`Invalid signature for function '${functionName}': dict type arguments must be named (e.g. dict(key: string))`);
             }
             fields[arg.name] = {
-                type: staticTypeRefToRillType(arg.value, functionName),
+                type: staticTypeRefToTypeStructure(arg.value, functionName),
             };
         }
-        return { type: 'dict', fields };
+        return { kind: 'dict', fields };
     }
     if (typeName === 'tuple') {
         const elements = args.map((arg) => ({
             ...(arg.name !== undefined ? { name: arg.name } : {}),
-            type: staticTypeRefToRillType(arg.value, functionName),
+            type: staticTypeRefToTypeStructure(arg.value, functionName),
         }));
-        return { type: 'tuple', elements };
+        return { kind: 'tuple', elements };
     }
     throw new Error(`Invalid signature for function '${functionName}': type '${typeName}' does not accept type arguments`);
 }
@@ -205,7 +205,7 @@ function parseSignatureBody(state, functionName) {
         advance(state); // consume :
         skipNewlines(state);
         const typeRef = parseTypeRef(state);
-        returnType = staticTypeRefToRillType(typeRef, functionName);
+        returnType = staticTypeRefToTypeStructure(typeRef, functionName);
     }
     // Step 5: Verify no trailing tokens
     if (!isAtEnd(state)) {
@@ -244,7 +244,7 @@ function parseSignatureParam(state, functionName) {
         advance(state); // consume :
         skipNewlines(state);
         const typeRef = parseTypeRef(state, { allowTrailingPipe: true });
-        type = staticTypeRefToRillType(typeRef, functionName);
+        type = staticTypeRefToTypeStructure(typeRef, functionName);
     }
     // Optional default value = literal
     let defaultValue = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcrsr/rill",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Scripting designed for machine-generated code",
   "license": "MIT",
   "author": "Andre Bremer",