import type { BuildParamProvenance } from "./provenance.js";
/**
 * Build-time parameter declaration + resolution (chant #1064, follow-up to
 * epic #1019's fold work — see issue #1064's "DECISION: option 1" comment).
 *
 * A build-time parameter is declared in `chant.config.ts`'s `buildParams`
 * (name, type, optional `default`/`enum`/`env` mapping), supplied to `chant
 * build` (a `--param name=value` flag, a `--params-file` JSON file, or a
 * declared `env` var), and referenced from source as `params.<name>` (see
 * ./params.ts) — never as an ambient `process.env` read. This module owns
 * declaration + precedence + validation; ./params.ts is the plain runtime
 * object source references; ../discovery/fold-import.ts is what makes a
 * `params.<name>` reference fold to a literal instead of a symbolic node.
 *
 * This is NOT the deploy-time `Parameter` class (`lexicons/aws/src/parameter.ts`)
 * — that resolves when a CloudFormation stack deploys; this resolves before
 * the template is even synthesized, so its value can change which resources
 * are produced at all. See ./params.ts's module doc for the full distinction.
 */
/** A build-time parameter's resolved (and declared-default/enum) value — always a scalar. */
export type BuildParamValue = string | number | boolean;
/**
 * One declared build-time parameter (`chant.config.ts`'s `buildParams.<name>`).
 */
export interface BuildParamDef {
    /** The value's declared type — supplied strings (CLI flags, env vars, JSON-file strings) are coerced to it. */
    type: "string" | "number" | "boolean";
    /** Value used when no `--param`/`--params-file`/declared `env` var supplies one. Omit to require an explicit value every build. */
    default?: BuildParamValue;
    /**
     * Allowed values — a resolved value outside this list is a build error
     * naming the parameter (never a thrown error from user source). Replaces
     * the hand-written `if (!VALID.includes(raw)) throw ...` pattern loomster's
     * `params.ts` files used before migrating to this mechanism.
     */
    enum?: readonly BuildParamValue[];
    /**
     * Opt-in, EXPLICITLY declared environment-variable fallback — e.g. `env:
     * "LOOM_TIER"`. This is the only place an env var may feed a build-time
     * parameter: reading `process.env` directly from project source is never
     * supported (see ./params.ts's module doc and ../fold/fold.ts's pointed
     * error for a bare `process` reference). Consulted only when no
     * `--param`/`--params-file` value was supplied for this parameter.
     */
    env?: string;
    /**
     * Set `false` to make an unresolved value NOT a build error: `params.<name>`
     * is simply omitted (reads as plain JS `undefined` — a normal, un-erroring
     * property access on an object missing that key), instead of the default
     * behavior of requiring every declared parameter to resolve to something.
     * For a value that is genuinely optional with no meaningful default (an ARN
     * that references an existing resource only on some deploys, a CIDR
     * override, a JSON blob) — the same "unset means the composite decides"
     * shape a hand-written `process.env.X || undefined` used to express.
     * Default `true` (a declared parameter must resolve to a value).
     */
    required?: boolean;
    /** Human-readable description, surfaced in error messages and docs generation. */
    description?: string;
}
/** A project's full set of declared build-time parameters, keyed by name. */
export type BuildParamsConfig = Record<string, BuildParamDef>;
/** Raw, not-yet-validated inputs {@link resolveBuildParams} resolves against a project's declared {@link BuildParamsConfig}. */
export interface BuildParamsInput {
    /** `--param name=value` flags, repeated — highest precedence. */
    cli?: Record<string, string>;
    /** Parsed contents of a `--params-file` JSON file — second precedence. */
    fromFile?: Record<string, unknown>;
    /** The process environment, consulted only for a parameter that declares an `env` mapping, and only once `cli`/`fromFile` have no value for it. */
    env?: Record<string, string | undefined>;
}
/** Result of resolving a project's declared parameters against one build invocation's inputs. */
export interface BuildParamsResolution {
    /** Every successfully resolved parameter — see {@link BuildParamProvenance}. Empty when the project declares none. */
    provenance: BuildParamProvenance[];
    /**
     * Validation failures, each naming the offending parameter — an unknown
     * `--param`/`--params-file` key, a missing required value, a type mismatch,
     * or a value outside a declared `enum`. Reported by the CLI as a build
     * error (chant #1064's acceptance criterion: "not a thrown error inside
     * user source"); never thrown from here.
     */
    errors: string[];
}
/**
 * Resolve a project's declared build-time parameters against one build's
 * supplied inputs. Precedence per parameter, most to least specific:
 * `cli` (`--param name=value`) > `fromFile` (`--params-file`) > the
 * parameter's own declared `env` mapping (only if set) > `def.default`.
 *
 * A parameter with no declared `default` and no value from any source is a
 * build error, not a silently-`undefined` value — a build-time parameter
 * exists specifically so a project never has an invisible dependency on
 * ambient state; leaving one unresolved would just reintroduce that under a
 * different name. Every failure is collected (not thrown), each naming the
 * offending parameter, so a single invocation reports every problem at once.
 *
 * The one opt-out is `def.required: false` — for a parameter that is
 * genuinely optional with no meaningful default (an ARN that only applies to
 * a reference-existing deploy, a CIDR override), an unresolved value is
 * simply omitted from `provenance`/`params` rather than an error; source
 * reads it as plain `undefined`, same as before migrating off
 * `process.env.X || undefined`.
 */
export declare function resolveBuildParams(defs: BuildParamsConfig | undefined, input: BuildParamsInput): BuildParamsResolution;
/** Project the resolved provenance records down to a plain `{ name: value }` map — what actually gets bound to `params.<name>` (see ./params.ts). */
export declare function buildParamValues(provenance: readonly BuildParamProvenance[]): Record<string, BuildParamValue>;
//# sourceMappingURL=build-params.d.ts.map