import type { Declarable } from "../declarable.js";
import type { DiscoveryError } from "../errors.js";
import type { IntrinsicDef } from "../lexicon.js";
import type { BuildParamProvenance } from "../provenance.js";
/**
 * Per-file fold-vs-run outcome (chant #1022, epic #1019), populated only
 * when {@link DiscoveryOptions.fold} was requested. Lets a caller (`chant
 * build --fold`) report which files skipped module execution and which
 * fell back to the run path, and why.
 */
export interface FoldDecision {
    /** Absolute path of the source file this decision covers. */
    file: string;
    /** "fold" — folded statically, zero execution. "run" — imported/executed as before. */
    mode: "fold" | "run";
    /** Why the file fell back to run. Present only when `mode === "run"` and fold was requested. */
    reason?: string;
    /** Number of entities the fold produced. Present only when `mode === "fold"`. */
    resourceCount?: number;
}
/**
 * Optional inputs to {@link discover}.
 */
export interface DiscoveryOptions {
    /**
     * chant #1022/#1023 (epic #1019) — opt-in: for each source file, try to
     * fold it to `Declarable`/`CompositeInstance` entities statically (no
     * module execution) before falling back to importing/running it. Anything
     * the folder can't represent (a non-`new`, non-composite-call export, a
     * cross-file-only reference, …) falls back per-file — see
     * {@link planFoldTaint} for the one case where a file that WOULD fold in
     * isolation is still forced back to run, to keep fold and run from ever
     * disagreeing about a shared entity's identity. Default `false` — behavior
     * is unchanged unless requested.
     */
    fold?: boolean;
    /**
     * chant #1039 — lexicon-registered intrinsic tags (e.g. AWS's `Sub`) to
     * recognize while folding. Threaded down to `tryFoldFile`/the static
     * folder so a registered tagged template folds instead of falling back to
     * run. Only meaningful when {@link fold} is set; ignored otherwise.
     * Default: none (an intrinsic-using file still folds up to that point,
     * then falls back to run at the unregistered tag).
     */
    intrinsics?: IntrinsicDef[];
    /**
     * chant #1063 — the lexicon NAMES loaded for this build (`["aws", "k8s"]`),
     * i.e. what `resolveProjectLexicons()` returned and `loadPlugins()` then
     * imported. Threaded into the fold session as the ALLOWLIST of packages a
     * bare import specifier may be resolved into, so a lexicon's plain data
     * exports (`Azure`/`GCP`'s pseudo-parameter namespaces, AWS's `S3Actions`,
     * gitlab's `CI`) fold as identifier values instead of failing the file.
     * Only meaningful when {@link fold} is set. Default: none — a caller that
     * doesn't say which lexicons are active gets no bare-specifier resolution
     * at all, rather than a looser fallback.
     */
    lexicons?: readonly string[];
    /**
     * chant #1045 Phase 2 — opt-in: whatever would otherwise reach the
     * in-process `importModule` step (every file, when {@link fold} isn't set;
     * only the per-file run-fallback remainder, when it is) instead runs
     * together, isolated, in one sandboxed child process — see
     * `./sandbox/run.ts`.
     *
     * chant #1093 — this ALSO tightens what fold itself may do in this process.
     * Fold executes none of a file's own top-level code, but it does import and
     * invoke the module behind a composite factory / resource constructor /
     * intrinsic tag; when that module is project-owned, a file reported as
     * "folded" still ran project code here. With `sandbox` set, fold refuses
     * any import outside chant's own packages and this build's active lexicons,
     * and the file demotes to the (sandboxed) run path instead — so the
     * security property is uniform: under `sandbox`, project source executes
     * only inside the child, folded or not. Fold COVERAGE is therefore lower
     * under `sandbox` than under plain `fold` — deliberately.
     *
     * Default `false` — behavior, including performance (no bundling, no child
     * process, no IPC) and fold coverage, is unchanged unless requested.
     */
    sandbox?: boolean;
    /**
     * chant #1064 — this build's resolved build-time parameter values (see
     * ../build-params.ts's `resolveBuildParams`, driven by the CLI's
     * `--param`/`--params-file`/declared `env` mapping/`chant.config.ts`
     * defaults). Populated into `../params.ts`'s shared `params` object
     * (`setBuildParams`, below) before any project file is imported or folded,
     * and threaded into the fold session so a `params.<name>` reference
     * resolves to a literal instead of an unresolved identifier. Default: none
     * — `params` stays empty, matching a project that declares no
     * `buildParams` at all.
     */
    buildParams?: BuildParamProvenance[];
}
/**
 * Result of the discovery process
 */
export interface DiscoveryResult {
    /** Map of entity name to Declarable entity */
    entities: Map<string, Declarable>;
    /** Map of entity name to set of entity names it depends on */
    dependencies: Map<string, Set<string>>;
    /** Array of source file paths that were processed */
    sourceFiles: string[];
    /** Array of errors encountered during discovery */
    errors: DiscoveryError[];
    /**
     * Per-file fold-vs-run decisions (#1022). Empty unless
     * {@link DiscoveryOptions.fold} was set.
     */
    foldDecisions: FoldDecision[];
}
/**
 * Discovers all declarable entities in a directory by scanning files,
 * importing modules, collecting entities, resolving references, and building
 * a dependency graph.
 *
 * @param path - The directory path to discover entities in
 * @param options - Optional discovery behavior, e.g. {@link DiscoveryOptions.fold}
 * @returns DiscoveryResult with entities, dependencies, sourceFiles, and errors
 */
export declare function discover(path: string, options?: DiscoveryOptions): Promise<DiscoveryResult>;
//# sourceMappingURL=index.d.ts.map