import type { AgencyProgram, FunctionDefinition } from "../types.js";
import type { ImportedFunctionSignature } from "../compilationUnit.js";
/**
 * Preprocessor pass: inject `schema(T)` arguments at call sites whose
 * target function declares a `Schema<...>` parameter that the caller
 * did not supply explicitly. The expected type `T` is derived from
 * the call's context: the LHS annotation of a `const`/`let`, or the
 * enclosing function's declared return type when the call is the
 * value of a `return` statement.
 *
 * Why a preprocessor pass:
 *   - Keeps the type checker simple (a Schema param is treated as
 *     "always optional" — see `paramListSignature`).
 *   - Keeps the TypeScript builder simple — calls reach the builder
 *     with all arguments explicit. Downstream tools (`agency fmt`,
 *     `pnpm run ast`) still see the original user-written AST because
 *     this pass runs only inside the TS preprocessor.
 *   - The injected node is a regular `schemaExpression`, so codegen
 *     for it already works (it's the same node `schema(T)` produces).
 *
 * Rules:
 *   - At most one Schema-typed parameter per function. Enforced once
 *     up front by `validateSchemaParamUniqueness`, so the error fires
 *     at declaration time regardless of whether the function is ever
 *     called from an injection-eligible context.
 *   - If the caller passes the Schema arg explicitly (positional or
 *     named), no injection happens.
 *   - If no expected type is available, no injection happens. The
 *     type checker also skips Schema params in its arity check, so
 *     the missing argument is *not* surfaced as a compile error —
 *     the function will fail at runtime when it tries to use the
 *     undefined schema. The documentation in
 *     `docs/site/appendix/schema-parameter-injection.md` describes
 *     this contract for users.
 */
export declare function injectSchemaArgsInProgram(program: AgencyProgram, functionDefinitions: Record<string, FunctionDefinition>, importedFunctions: Record<string, ImportedFunctionSignature>): void;