ttsc/lib/TtscCompiler.d.ts

General-purpose TypeScript-Go compiler, runtime, plugin host, and LSP host.

import type { ITtscCompilerContext } from "./structures/ITtscCompilerContext";
import type { ITtscCompilerResult } from "./structures/ITtscCompilerResult";
import type { ITtscCompilerTransformation } from "./structures/ITtscCompilerTransformation";
/**
 * Programmatic compiler host for the `ttsc` TypeScript-Go pipeline.
 *
 * `TtscCompiler` is the root JavaScript API exported by the `ttsc` package. It
 * represents one resolved project context: a working directory, an optional
 * project config path, an optional native toolchain override, an environment, a
 * cache root, and a plugin list. Those values are captured by the constructor
 * and are intentionally not replaceable per method call.
 *
 * The class exposes only the operations that make sense for an embedded
 * compiler host:
 *
 * - {@link TtscCompiler.prepare}: build configured Go source plugins into the
 *   cache before a later compile.
 * - {@link TtscCompiler.clean}: remove the cache owned by this compiler context.
 * - {@link TtscCompiler.compile}: compile the configured project and return a
 *   structured result instead of terminal text.
 * - {@link TtscCompiler.transform}: transform the configured project and return an
 *   embed-style transformation result.
 */
export declare class TtscCompiler {
    private readonly context;
    /**
     * Create a new compiler instance bound to the given project context.
     *
     * The context is defensively copied: mutations to the original object after
     * construction do not affect this instance. Omit `context` (or pass `{}`) to
     * inherit all defaults from the running process.
     */
    constructor(context?: ITtscCompilerContext);
    /**
     * Build every configured source plugin into the instance cache.
     *
     * This method loads the project plugin descriptors, resolves their
     * {@link ITtscPlugin.source} paths, and compiles those Go command packages
     * into the ttsc cache. It is useful when a host application wants to pay the
     * lazy build cost before the first compile call.
     *
     * `prepare()` is not a project check. It does not create a TypeScript-Go
     * Program, does not run diagnostics, and does not emit output files.
     *
     * @returns Compiled native plugin binary paths.
     */
    prepare(): string[];
    /**
     * Remove compiled cache artifacts for this compiler instance.
     *
     * Removes the resolved cache root (which holds both the plugin binaries and,
     * when ttsc-owned, the Go build cache), a ttsc-owned Go build cache that
     * lives outside that root (`TTSC_GO_CACHE_DIR`), and the two legacy
     * project-local caches. A user-provided `GOCACHE` is never removed. The cache
     * location comes from this instance's `cacheDir` and environment
     * (`TTSC_CACHE_DIR` / `TTSC_GO_CACHE_DIR`), defaulting to
     * `<workspaceRoot>/node_modules/.cache/ttsc`. An explicit cache directory
     * that equals or contains the project, or names a filesystem root, is
     * rejected before any directory is removed.
     *
     * @returns Cache directories that were removed.
     */
    clean(): string[];
    /**
     * Compile the configured project.
     *
     * The public API does not write emitted files into the caller's project tree.
     * For projects without plugins, ttsc uses its native TypeScript-Go host's
     * `WriteFile` callback to capture output in memory. For projects with native
     * plugins, ttsc runs the plugin pipeline against a temporary output
     * directory, reads the generated text artifacts, and removes the temporary
     * directory before returning.
     *
     * The result uses an `embed-typescript`-style discriminated union: `success`
     * for clean compiles, `failure` for compiler diagnostics or plugin failures
     * that reached the build pipeline, and `exception` for host failures that
     * prevent any project check from running.
     *
     * @returns Structured compilation result containing diagnostics or output.
     */
    compile(): ITtscCompilerResult;
    /**
     * Transform the configured project and return TypeScript text by file path.
     *
     * This is the source-to-source API for plugin authors. It must not return
     * JavaScript emit, declaration files, or source maps; those artifacts belong
     * to {@link TtscCompiler.compile}. A transform native source is expected to
     * write JSON shaped as `{ "typescript": { "src/file.ts": "..." } }` to
     * stdout. When no transform native source is configured, ttsc returns the
     * TypeScript files loaded by the TypeScript-Go Program together with normal
     * diagnostics.
     *
     * The returned shape mirrors `embed-typescript`'s transformation API:
     * `success` and `failure` carry a `typescript` map, while unexpected host
     * errors return `exception`.
     *
     * @returns Transformation result containing TypeScript text or diagnostics.
     */
    transform(): ITtscCompilerTransformation;
    private compilerContext;
    private resolveProjectExecution;
    private resolveCleanProjectRoot;
    private resolveCwd;
    private resolveCacheDir;
    private resolvePluginCacheDir;
    /**
     * The effective environment for this instance's source-plugin builds and
     * clean targets: `context.env` merged over `process.env`, matching the
     * documented {@link ITtscCompilerContext.env} contract that child compiler,
     * native-plugin, and native-host processes already receive. Returned as a
     * fresh object so callers never mutate the shared `process.env`; when no
     * `context.env` was supplied this is a plain copy of `process.env`, so CLI /
     * default behavior is unchanged.
     */
    private resolveEffectiveEnv;
}