import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
/**
 * Result of a TypeScript source-to-source transformation operation.
 *
 * This mirrors `embed-typescript`'s `IEmbedTypeScriptTransformation` model.
 * Unlike {@link ITtscCompilerResult}, this contract is not an emit contract: the
 * `typescript` map must contain TypeScript source text, not generated
 * JavaScript, declaration files, or source maps.
 */
export type ITtscCompilerTransformation = ITtscCompilerTransformation.ISuccess | ITtscCompilerTransformation.IFailure | ITtscCompilerTransformation.IException;
export declare namespace ITtscCompilerTransformation {
    /**
     * Host-owned reference graph of the transformed program, mirroring the
     * envelope's optional `graph` section.
     *
     * The graph is the language-semantic input bound of the transform under `tsc
     * --incremental` semantics: any symbol a file can reference is reachable
     * through its import/reference closure or is ambient. Bundler adapters
     * register, per transformed file `F`, the reachability closure of
     * {@link edges} from `F` together with {@link globals} and {@link configs}, so
     * persistent caches and watch graphs invalidate soundly without per-plugin
     * dependency reporting.
     *
     * Keys and values follow the same convention as {@link ISuccess.typescript}:
     * project-relative slash paths, falling back to absolute slash paths outside
     * the project root.
     */
    interface IReferenceGraph {
        /**
         * Direct resolved references per file: imports, re-exports, `///
         * <reference>` targets, and type reference directives — type-only edges
         * included. Direct edges only; consumers compute transitive reachability
         * themselves.
         */
        edges: Record<string, string[]>;
        /**
         * Files contributing to the global scope (ambient declaration files, script
         * files, global augmentations, `typeRoots` entries). A change to any of
         * them can affect every file in the program.
         */
        globals: string[];
        /** The project tsconfig followed by its `extends` ancestry. */
        configs: string[];
        /**
         * Resolution candidates that would outrank the selected target, keyed by
         * importing file. The compiler already resolved the import to a graph edge;
         * a listed path can be absent now or can be an existing unsuccessful probe,
         * and its appearance or change can alter that edge without editing the
         * importer or a recorded file.
         *
         * Hosts watch and hash these paths in addition to realized graph members. A
         * candidate strictly below the selected target is deliberately absent: its
         * creation cannot change resolution and must not invalidate a cache.
         *
         * A host with nothing to report leaves the whole property out rather than
         * sending an empty map, so `undefined` and "no superseding candidate" are
         * the same observation on the wire and after decoding.
         */
        candidates?: Record<string, string[]>;
    }
    /** Successful source-to-source transformation result. */
    interface ISuccess {
        /** Indicates that transformation completed without diagnostics. */
        type: "success";
        /** Non-fatal diagnostics reported during transformation. */
        diagnostics?: ITtscCompilerDiagnostic[];
        /**
         * Transformed TypeScript source text keyed by project-relative file path.
         *
         * Values are TypeScript source text, never JavaScript, declaration files,
         * or source maps. When no transform native source is configured, this map
         * contains the unmodified TypeScript files loaded by the TypeScript-Go
         * Program.
         */
        typescript: Record<string, string>;
        /**
         * Source files the transform consulted per transformed file, keyed the same
         * way as {@link typescript}. Each entry lists the project-relative or
         * absolute paths whose content influenced that output beyond the file
         * itself — e.g. the declaration files a type-driven code generator read.
         *
         * Optional: only present when the transform native source reported a
         * `dependencies` object in its stdout envelope. Bundler adapters use it to
         * register watch files so type-only imports participate in HMR
         * invalidation. ttsc passes the paths through verbatim.
         */
        dependencies?: Record<string, string[]>;
        /**
         * Transformed files (keyed like {@link typescript}) whose
         * {@link dependencies} entry the transform host declares **complete**: every
         * input beyond the file itself and the universal
         * {@link IReferenceGraph.configs} chain is listed there.
         *
         * The declaration narrows invalidation. For a listed file a consumer uses
         * `dependencies[F] ∪ graph.configs` instead of the union with the
         * host-owned `reach(graph.edges, F) ∪ graph.globals` bound, so a change to
         * a file the transform never consulted no longer re-runs it. Unlisted files
         * keep the union, so a mixed envelope composes per file.
         *
         * This is a responsibility transfer, not a hint: an omission makes the
         * consumer serve stale output, and that is a defect of the declaring plugin
         * rather than of the host. Producers list a file only when the reported set
         * is derived from what the transform actually consulted (a Checker-driven
         * generator's per-file consulted-declaration list). When several plugin
         * entries contribute to one file, the envelope's author may list it only if
         * every contributing entry declared its own list complete for it.
         *
         * The config chain a listed file keeps is {@link graph}'s, so a host that
         * declares completeness should stamp {@link graph} too; without it a listed
         * file retains no universal input at all.
         *
         * Optional, and never required for correctness: an envelope without this
         * field keeps the sound host-owned bound. A file that is both listed here
         * and in {@link volatile} keeps the union, since the two claims contradict
         * and the conservative one wins.
         */
        dependenciesComplete?: string[];
        /**
         * Host-owned reference graph of the transformed program.
         *
         * Optional: only present when the transform host stamped a `graph` section
         * into its stdout envelope (the built-in native host and the linked-plugin
         * host always do; external sidecars adopt through the driver SDK).
         * Malformed sections are dropped, never fatal — the field is advisory
         * invalidation metadata, not output.
         */
        graph?: IReferenceGraph;
        /**
         * Transformed files (keyed like {@link typescript}) whose output depends on
         * non-file inputs (environment, time, network) as declared by the transform
         * plugin via the envelope's optional `volatile` list. No file-dependency
         * scheme can represent such inputs, so consumers must exclude these files
         * from caching instead of watching more files.
         */
        volatile?: string[];
    }
    /** Source-to-source transformation result that completed with diagnostics. */
    interface IFailure {
        /** Indicates that transformation completed with diagnostics. */
        type: "failure";
        /**
         * Transformed or partially transformed TypeScript source text keyed by
         * project-relative file path.
         *
         * May be empty or partial when diagnostics prevented the transform native
         * source from completing its pass.
         */
        typescript: Record<string, string>;
        /** Diagnostics reported during transformation. */
        diagnostics: ITtscCompilerDiagnostic[];
        /**
         * Source files the transform consulted per transformed file. Same shape and
         * semantics as {@link ISuccess.dependencies}; may be partial when the
         * transform did not complete its pass.
         */
        dependencies?: Record<string, string[]>;
        /**
         * Files whose reported dependency list the host declares complete. Same
         * shape and semantics as {@link ISuccess.dependenciesComplete}; may be
         * partial when the transform did not complete its pass.
         */
        dependenciesComplete?: string[];
        /**
         * Host-owned reference graph. Same shape and semantics as
         * {@link ISuccess.graph}; may be absent when diagnostics prevented the host
         * from loading the program.
         */
        graph?: IReferenceGraph;
        /**
         * Volatile transformed files. Same shape and semantics as
         * {@link ISuccess.volatile}.
         */
        volatile?: string[];
    }
    /** Unexpected host-level error during transformation. */
    interface IException {
        /** Indicates that transformation could not complete normally. */
        type: "exception";
        /**
         * Optional classifier so embedders can branch on the failure mode without
         * pattern-matching error messages. Omitted when ttsc cannot determine the
         * origin. Treat as `"unknown"` when missing.
         *
         * - `"plugin"`: a native plugin sidecar crashed or exited non-zero.
         * - `"host"`: the TypeScript-Go host could not start (missing binary, cache
         *   lock, invalid config).
         * - `"unknown"`: any other host-level failure.
         */
        kind?: "plugin" | "host" | "unknown";
        /** Raw error thrown by the ttsc host. */
        error: unknown;
    }
}