Host Resolver Registration

import { moduleResolver, extResolver, createRuntimeContext } from '@rcrsr/rill';
import { myQdrantExtension } from './qdrant';

const ctx = createRuntimeContext({
  resolvers: {
    host: moduleResolver,
    ext: extResolver,
  },
  configurations: {
    resolvers: {
      host: {
        utils: './utils.rill',
      },
      ext: {
        qdrant: myQdrantExtension,
      },
    },
  },
});

use<host:utils>
use<ext:qdrant>
use<ext:qdrant.search>

import type { SchemeResolver } from '@rcrsr/rill';

const myResolver: SchemeResolver = async (resource, config) => {
  const source = await loadSource(resource);
  return { kind: 'source', text: source };
};

const ctx = createRuntimeContext({
  resolvers: { custom: myResolver },
  configurations: {
    resolvers: {
      custom: { /* your config */ },
    },
  },
});

import { moduleResolver, createRuntimeContext } from '@rcrsr/rill';

const ctx = createRuntimeContext({
  resolvers: { host: moduleResolver },
  configurations: {
    resolvers: {
      host: {
        utils: './utils.rill',
        helpers: './lib/helpers.rill',
      },
    },
  },
});

// Scripts can now use: use<host:utils>

import { extResolver, createRuntimeContext } from '@rcrsr/rill';
import { qdrantExtension } from './my-qdrant-ext';

const ctx = createRuntimeContext({
  resolvers: { ext: extResolver },
  configurations: {
    resolvers: {
      ext: {
        qdrant: qdrantExtension,
      },
    },
  },
});

// Scripts can now use: use<ext:qdrant> or use<ext:qdrant.search>

interface RillOrdered {
  __rill_ordered: true;
  entries: [string, RillValue][];
}
// Created by: ordered[a: 1, b: 2]

interface RillTuple {
  __rill_tuple: true;
  entries: RillValue[];    // positional values, 0-indexed
}

interface RillTypeValue {
  __rill_type: true;
  name: string;                    // coarse name: "list", "dict", "number", etc.
  structure: TypeStructure;        // full structural type
}

type TypeStructure =
  | { kind: 'number' }
  | { kind: 'string' }
  | { kind: 'bool' }
  | { kind: 'vector' }
  | { kind: 'type' }
  | { kind: 'any' }
  | { kind: 'dict';    fields?: Record<string, TypeStructure> }
  | { kind: 'list';    element?: TypeStructure }
  | { kind: 'closure'; params?: [string, TypeStructure][]; ret?: TypeStructure }
  | { kind: 'tuple';   elements?: TypeStructure[] }
  | { kind: 'ordered'; fields?: [string, TypeStructure][] }

// Script closure returned from execute():
// |x: number, y: string| x -> :>string

const closure = result.result; // RillCallable (ScriptCallable)
// $fn.^input -> ordered[x: ^number, y: ^string]
// Host side: RillOrdered with entries [["x", RillTypeValue], ["y", RillTypeValue]]
// entries[0][1].structure -> { kind: 'number' }
// entries[1][1].structure -> { kind: 'string' }

// Parameterized closure: |x: list(string), y: number| { $x }
// entries[0][1].structure -> { kind: 'list', element: { kind: 'string' } }
// entries[1][1].structure -> { kind: 'number' }
//
// Use structure.element to inspect the list's element type:
// if (entries[0][1].structure.kind === 'list') {
//   const elementType = entries[0][1].structure.element; // { kind: 'string' }
// }

// Closure with declared return: |x: number| :string -> ...
// $fn.^output -> ^string
// Host side: RillTypeValue with structure { kind: 'string' }

// Closure with no declared return type:
// $fn.^output -> ^any
// Host side: RillTypeValue with structure { kind: 'any' }

import { toNative } from '@rcrsr/rill';

const nativeResult = toNative(executionResult.result);
console.log(nativeResult.rillTypeName);      // e.g. "string", "list", "ordered"
console.log(nativeResult.rillTypeSignature); // e.g. "string", "list(number)"
console.log(nativeResult.value);             // JS-native value, always populated

interface NativeResult {
  /** Base rill type name — "string", "number", "bool", "list", "dict",
   *  "tuple", "ordered", "closure", "vector", "type", or "iterator" */
  rillTypeName: string;
  /** Full structural type signature from formatStructure,
   *  e.g. "list(number)", "dict(a: number, b: string)", "|x: number| :string" */
  rillTypeSignature: string;
  /** JS-native representation. Always populated — never undefined.
   *  Non-native types produce descriptor objects (see Descriptor shapes below). */
  value: NativeValue;
}

type NativeValue = string | number | boolean | null | NativeValue[] | { [key: string]: NativeValue };

const result = toNative(closureValue);
// result.rillTypeName      -> "closure"
// result.rillTypeSignature -> "|x: number| :string"
// result.value             -> { signature: "|x: number| :string" }

const result = toNative(vectorValue);
// result.rillTypeName      -> "vector"
// result.rillTypeSignature -> "vector"
// result.value             -> { model: "text-embedding-3-small", dimensions: 1536 }

const result = toNative(typeValue);
// result.rillTypeName      -> "type"
// result.rillTypeSignature -> "list(number)"
// result.value             -> { name: "list", signature: "list(number)" }

const result = toNative(iteratorValue);
// result.rillTypeName      -> "iterator"
// result.rillTypeSignature -> "iterator"
// result.value             -> { done: false }

import { createRuntimeContext, getFunctions } from '@rcrsr/rill';

const ctx = createRuntimeContext({
  functions: {
    greet: {
      params: [
        { name: 'name', type: { kind: 'string' }, annotations: { description: 'Person to greet' } },
      ],
      description: 'Generate a greeting message',
      fn: (args) => `Hello, ${args[0]}!`,
    },
  },
});

const functions = getFunctions(ctx);
// [
//   {
//     name: 'greet',
//     description: 'Generate a greeting message',
//     params: [{ name: 'name', type: 'string', description: 'Person to greet', defaultValue: undefined }]
//   },
//   ... built-in functions
// ]

import { getLanguageReference } from '@rcrsr/rill';

const reference = getLanguageReference();
// Returns complete language reference text (syntax, operators, types, etc.)

// Use in LLM system prompts:
const systemPrompt = `You are a rill script assistant.

${reference}

Help the user write rill scripts.`;

import { VERSION, VERSION_INFO } from '@rcrsr/rill';

// VERSION: Semver string for display
console.log(`Running rill ${VERSION}`);  // "Running rill 0.5.0"

// VERSION_INFO: Structured components for programmatic comparison
if (VERSION_INFO.major === 0 && VERSION_INFO.minor < 4) {
  console.warn('rill version too old, upgrade required');
}

// Log full version info
console.log('Runtime:', {
  version: VERSION,
  major: VERSION_INFO.major,
  minor: VERSION_INFO.minor,
  patch: VERSION_INFO.patch,
  prerelease: VERSION_INFO.prerelease,
});

import { VERSION_INFO } from '@rcrsr/rill';

function checkCompatibility(): boolean {
  const required = { major: 0, minor: 4, patch: 0 };

  if (VERSION_INFO.major !== required.major) {
    return false; // Breaking change
  }

  if (VERSION_INFO.minor < required.minor) {
    return false; // Missing features
  }

  return true;
}

if (!checkCompatibility()) {
  throw new Error(`Requires rill >= 0.4.0, found ${VERSION}`);
}

import { createRuntimeContext, getDocumentationCoverage } from '@rcrsr/rill';

const ctx = createRuntimeContext({
  functions: {
    documented: {
      params: [{ name: 'x', type: { kind: 'string' }, annotations: { description: 'Input value' } }],
      description: 'A documented function',
      fn: (args) => args[0],
    },
    undocumented: {
      params: [{ name: 'x', type: { kind: 'string' } }],
      fn: (args) => args[0],
    },
  },
});

const result = getDocumentationCoverage(ctx);
// { total: 2, documented: 1, percentage: 50 }

interface FunctionMetadata {
  readonly name: string;        // Function name (e.g., "math::add")
  readonly description: string; // Human-readable description
  readonly params: readonly ParamMetadata[];
  readonly returnType: string;  // Return type (default: 'any')
}

interface ParamMetadata {
  readonly name: string;                    // Parameter name
  readonly type: string;                    // Type constraint (e.g., "string")
  readonly description: string;             // Parameter description
  readonly defaultValue: RillValue | undefined; // Default if optional
}

interface DocumentationCoverageResult {
  readonly total: number;       // Total function count
  readonly documented: number;  // Functions with complete documentation
  readonly percentage: number;  // Percentage (0-100), rounded to 2 decimals
}

interface VersionInfo {
  readonly major: number;        // Major version (breaking changes)
  readonly minor: number;        // Minor version (new features)
  readonly patch: number;        // Patch version (bug fixes)
  readonly prerelease?: string;  // Prerelease tag if present
}