/**
 * Runtime Introspection API
 *
 * Functions for inspecting runtime context at runtime.
 * These enable host applications to discover available functions and their signatures.
 */
import type { RuntimeContext } from './types/runtime.js';
import type { RillValue } from './types/structures.js';
import type { ScriptNode } from '../../types.js';
/**
 * Metadata describing a function's signature and documentation.
 * Returned by introspection APIs like getFunctions().
 */
export interface FunctionMetadata {
    /** Function name (including namespace if applicable, e.g., "math::add") */
    readonly name: string;
    /** Human-readable description of what the function does */
    readonly description: string;
    /** Parameter metadata in declaration order */
    readonly params: readonly ParamMetadata[];
    /** Return type (default: 'any' for unspecified) */
    readonly returnType: string;
}
/**
 * Metadata describing a single function parameter.
 */
export interface ParamMetadata {
    /** Parameter name */
    readonly name: string;
    /** Type constraint (e.g., "string", "number", "list") */
    readonly type: string;
    /** Human-readable description of the parameter's purpose */
    readonly description: string;
    /** Default value if parameter is optional (undefined if required) */
    readonly defaultValue: RillValue | undefined;
}
/**
 * Enumerate all callable functions registered in runtime context.
 *
 * Returns flat list combining host functions, built-ins, and script closures.
 * Namespaced functions preserve `::` separator in name field.
 * Malformed entries silently skipped (valid entries returned).
 * Script closures: reads `^(description: "...")` (including the bare-string
 * shorthand) or, when absent, the legacy `^(doc: "...")` annotation for description.
 * Script closures: returnType reflects the closure's declared/inferred return type,
 * falling back to 'any' only when genuinely unspecified.
 * Script closures: excludes nested closures in dicts/lists.
 *
 * Order: host functions, then built-ins, then script closures.
 *
 * @param ctx Runtime context
 * @returns Array of function metadata
 */
export declare function getFunctions(ctx: RuntimeContext): FunctionMetadata[];
/**
 * Generate a rill manifest file from the registered host functions in ctx.
 *
 * Returns a string containing a valid rill file: a dict literal of
 * string-keyed closure type signatures followed by `-> export`.
 *
 * Only `ApplicationCallable` entries with `params !== undefined` are included.
 * `RuntimeCallable` entries are excluded. Built-in functions (by registered builtin name) are excluded.
 * `ApplicationCallable` entries with `params: undefined` are skipped silently.
 *
 * Empty function map produces `[:]` followed by `-> export`.
 *
 * @param ctx Runtime context
 * @returns Rill manifest file content as a string
 */
export declare function generateManifest(ctx: RuntimeContext): string;
/**
 * Documentation coverage metrics for runtime context.
 * Used to assess quality of function documentation.
 */
export interface DocumentationCoverageResult {
    /** Total function count */
    readonly total: number;
    /** Functions with complete documentation */
    readonly documented: number;
    /** Percentage (0-100), rounded to 2 decimal places */
    readonly percentage: number;
}
/**
 * Analyze documentation coverage of functions in runtime context.
 *
 * Counts function as documented when:
 * - Has non-empty description string (after trim)
 * - All parameters have non-empty description string (after trim)
 *
 * Script closures with `^(doc: "...")` annotation count as having description.
 * Whitespace-only descriptions count as undocumented.
 * Empty context returns `{ total: 0, documented: 0, percentage: 100 }`.
 *
 * @param ctx Runtime context
 * @returns Documentation coverage metrics
 */
export declare function getDocumentationCoverage(ctx: RuntimeContext): DocumentationCoverageResult;
/**
 * Return complete rill language reference for LLM prompt context.
 *
 * Returns bundled content from `docs/ref-llm.txt`.
 * Content includes syntax, operators, control flow, type system.
 * Always succeeds at runtime (content embedded at build time).
 *
 * @returns Language reference text
 */
export declare function getLanguageReference(): string;
/**
 * Static metadata for a single closure parameter, extracted from the AST.
 * No script execution required.
 */
export interface HandlerParamStatic {
    /** Parameter name */
    readonly name: string;
    /** Type annotation string, or 'any' when absent */
    readonly type: string;
    /** True when no default value expression exists */
    readonly required: boolean;
    /** Description from parameter annotation, when present */
    readonly description?: string;
    /** Literal default value (undefined for non-literal or complex expressions) */
    readonly defaultValue?: unknown;
}
/**
 * Static metadata for a handler closure, extracted from the AST.
 * No script execution required.
 */
export interface HandlerMetadataStatic {
    /** Description from annotation on the closure statement */
    readonly description?: string;
    /** Parameter metadata in declaration order */
    readonly params: ReadonlyArray<HandlerParamStatic>;
    /**
     * Closure return type annotation, formatted with the same grammar as
     * parameter type strings. `undefined` when the closure has no `:T` suffix.
     * Stream returns are rendered as `stream(<chunk>):<ret>` (omitting the
     * trailing `:<ret>` when no resolution type is declared).
     */
    readonly returnType?: string;
}
/**
 * Extract static handler metadata from a parsed AST without executing the script.
 *
 * Walks statements to find a pipe chain with a capture to `handlerName`.
 * Captures may appear as CaptureNode entries in either the pipes array or the
 * terminator.
 * Extracts the ClosureNode and reads parameter types, defaults, and descriptions
 * from AST nodes directly.
 *
 * @param ast - Parsed script AST
 * @param handlerName - Capture variable name (e.g., 'run' for `=> $run`)
 * @returns Handler metadata, or null when no matching handler found
 */
export declare function introspectHandlerFromAST(ast: ScriptNode, handlerName: string): HandlerMetadataStatic | null;