ttsc 0.6.0 → 0.7.0

package/lib/{plugin.js → plugin/internal/loadProjectPlugins.js}

@@ -3,19 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.definePlugin = definePlugin;
 exports.loadProjectPlugins = loadProjectPlugins;
 const node_module_1 = require("node:module");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const native_1 = require("./native");
-const project_1 = require("./project");
-const source_build_1 = require("./source-build");
-function definePlugin(plugin) {
-    return plugin;
-}
+const readProjectConfig_1 = require("../../compiler/internal/project/readProjectConfig");
+const buildSourcePlugin_1 = require("./buildSourcePlugin");
 function loadProjectPlugins(options) {
-    const project = (0, project_1.readProjectConfig)({
+    const project = (0, readProjectConfig_1.readProjectConfig)({
         cwd: options.cwd,
         file: options.file,
         tsconfig: options.tsconfig,
@@ -25,11 +20,7 @@ function loadProjectPlugins(options) {
         : [...(options.entries ?? project.compilerOptions.plugins)].filter((entry) => entry.enabled !== false);
     if (entries.length === 0) {
         return {
-            compatibilityFallback: false,
-            nativeBinary: null,
-            nativeBinaries: [],
             nativePlugins: [],
-            plugins: [],
             project,
         };
     }
@@ -44,39 +35,24 @@ function loadProjectPlugins(options) {
     const ttscVersion = readTtscVersion();
     const tsgoVersion = readTsgoVersion(context.projectRoot);
     plugins.forEach((plugin, index) => {
-        let backend = (0, native_1.resolveNativeBackend)(plugin);
-        if (!backend) {
-            return;
-        }
-        if (backend.source && !backend.binary) {
-            const built = (0, source_build_1.buildSourcePlugin)({
-                baseDir: context.projectRoot,
-                pluginName: plugin.name,
-                source: backend.source,
-                ttscVersion,
-                tsgoVersion,
-            });
-            backend = { ...backend, binary: built };
-        }
-        nativePlugins.push({ backend, config: entries[index], name: plugin.name });
+        validatePluginSource(plugin);
+        const binary = (0, buildSourcePlugin_1.buildSourcePlugin)({
+            baseDir: context.projectRoot,
+            cacheDir: options.cacheDir,
+            pluginName: plugin.name,
+            source: plugin.source,
+            ttscVersion,
+            tsgoVersion,
+        });
+        nativePlugins.push({
+            binary,
+            config: entries[index],
+            name: plugin.name,
+            stage: resolvePluginStage(plugin),
+        });
     });
-    if (nativePlugins.length !== plugins.length) {
-        const missing = plugins
-            .filter((plugin) => !(0, native_1.resolveNativeBackend)(plugin))
-            .map((plugin) => plugin.name)
-            .join(", ");
-        throw new Error(`ttsc: every plugin must declare a native backend; missing native for ${missing}`);
-    }
     return {
-        compatibilityFallback: false,
-        nativeBinary: nativePlugins[0]?.backend.binary ?? null,
-        nativeBinaries: [
-            ...new Set(nativePlugins
-                .map((plugin) => plugin.backend.binary)
-                .filter((binary) => typeof binary === "string")),
-        ],
         nativePlugins,
-        plugins,
         project,
     };
 }
@@ -116,6 +92,23 @@ function rejectJsTransformHooks(specifier, candidate) {
             "declare a native backend instead");
     }
 }
+function resolvePluginStage(plugin) {
+    if (plugin.stage === undefined) {
+        return "transform";
+    }
+    if (!isPluginStage(plugin.stage)) {
+        throw new Error(`ttsc: plugin "${plugin.name}" requested unsupported stage ${JSON.stringify(plugin.stage)}`);
+    }
+    return plugin.stage;
+}
+function validatePluginSource(plugin) {
+    if (typeof plugin.source !== "string" || plugin.source.length === 0) {
+        throw new Error(`ttsc: plugin "${plugin.name}" must declare source`);
+    }
+}
+function isPluginStage(value) {
+    return value === "transform" || value === "check" || value === "output";
+}
 function resolvePluginRequest(specifier, projectRoot) {
     if (node_path_1.default.isAbsolute(specifier)) {
         return specifier;
@@ -123,16 +116,7 @@ function resolvePluginRequest(specifier, projectRoot) {
     if (isRelativePluginSpecifier(specifier)) {
         return node_path_1.default.resolve(projectRoot, specifier);
     }
-    try {
-        return require.resolve(specifier, { paths: [projectRoot] });
-    }
-    catch (error) {
-        const sourceFallback = resolveSourceCheckoutPlugin(specifier, projectRoot);
-        if (sourceFallback) {
-            return sourceFallback;
-        }
-        throw error;
-    }
+    return require.resolve(specifier, { paths: [projectRoot] });
 }
 function isRelativePluginSpecifier(specifier) {
     return (specifier === "." ||
@@ -142,35 +126,13 @@ function isRelativePluginSpecifier(specifier) {
         specifier.startsWith(".\\") ||
         specifier.startsWith("..\\"));
 }
-function resolveSourceCheckoutPlugin(specifier, projectRoot) {
-    const normalized = specifier.replace(/\\/g, "/");
-    const match = normalized.match(/^(.*)\/lib\/transform$/);
-    if (!match) {
-        return null;
-    }
-    try {
-        const packageJson = require.resolve(`${match[1]}/package.json`, {
-            paths: [projectRoot],
-        });
-        const packageRoot = node_path_1.default.dirname(packageJson);
-        const candidates = [
-            node_path_1.default.join(packageRoot, "lib", "transform.js"),
-            node_path_1.default.join(packageRoot, "src", "transform.ts"),
-            node_path_1.default.join(packageRoot, "bin", "ttsc-plugin.cjs"),
-        ];
-        return candidates.find((candidate) => node_fs_1.default.existsSync(candidate)) ?? null;
-    }
-    catch {
-        return null;
-    }
-}
 let cachedTtscVersion = null;
 function readTtscVersion() {
     if (cachedTtscVersion !== null) {
         return cachedTtscVersion;
     }
     try {
-        const file = node_path_1.default.resolve(__dirname, "..", "package.json");
+        const file = node_path_1.default.resolve(__dirname, "..", "..", "..", "package.json");
         const pkg = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
         cachedTtscVersion = pkg.version ?? "0.0.0";
     }
@@ -190,4 +152,4 @@ function readTsgoVersion(projectRoot) {
         return "unknown";
     }
 }
-//# sourceMappingURL=plugin.js.map
+//# sourceMappingURL=loadProjectPlugins.js.map

package/lib/plugin/internal/loadProjectPlugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadProjectPlugins.js","sourceRoot":"","sources":["../../../src/plugin/internal/loadProjectPlugins.ts"],"names":[],"mappings":"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"}

package/lib/structures/ITtscCompilerContext.d.ts

@@ -0,0 +1,78 @@
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+/**
+ * Constructor context for {@link TtscCompiler}.
+ *
+ * Represents the project environment owned by a programmatic ttsc compiler
+ * instance. The context is fixed when the class is constructed: compile,
+ * prepare, and clean operations all use the same working directory, project
+ * config, native toolchain, environment, cache root, and plugin list.
+ *
+ * Keeping this context immutable prevents one `TtscCompiler` object from
+ * silently compiling different projects across calls. Create another compiler
+ * instance when any of these fields must change.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ITtscCompilerContext {
+    /**
+     * The working directory for this compiler instance.
+     *
+     * Used to discover `tsconfig.json`, resolve relative `tsconfig` paths,
+     * resolve project source files, resolve plugin packages, and resolve relative
+     * cache paths.
+     *
+     * @default process.cwd()
+     */
+    cwd?: string;
+    /**
+     * The project configuration file for this compiler instance.
+     *
+     * Relative paths are resolved from {@link ITtscCompilerContext.cwd}. When this
+     * field is omitted, ttsc discovers the nearest owning `tsconfig.json` or
+     * `jsconfig.json` from the working directory.
+     */
+    tsconfig?: string;
+    /**
+     * Explicit TypeScript-Go executable for controlled embedding.
+     *
+     * Normal consumers should leave this unset. ttsc resolves the installed or
+     * bundled toolchain needed for each compile path. This field is intended for
+     * tests, pinned toolchains, and embedding environments that need plugin or
+     * CLI-compatible paths to use a specific TypeScript-Go binary.
+     *
+     * The no-plugin in-memory API path is hosted by ttsc's native compiler host
+     * so it can return structured diagnostics and output. Plugin-backed paths
+     * pass this binary through to the TypeScript-Go execution layer.
+     */
+    binary?: string;
+    /**
+     * Additional environment variables for child compiler processes.
+     *
+     * Values are merged over `process.env` before ttsc starts TypeScript-Go,
+     * native plugin binaries, or the native compiler host used by
+     * {@link TtscCompiler.compile}.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Root directory for compiled ttsc artifacts.
+     *
+     * Relative paths are resolved from {@link ITtscCompilerContext.cwd}. When
+     * omitted, ttsc uses its normal cache location: `TTSC_CACHE_DIR` when
+     * present, otherwise `node_modules/.ttsc` or `.ttsc` under the project root.
+     *
+     * The same cache stores source-plugin binaries and the lazily built native
+     * compiler host used for in-memory API compilation.
+     */
+    cacheDir?: string;
+    /**
+     * Plugin entries for this compiler instance.
+     *
+     * - `undefined`: read `compilerOptions.plugins` from the project config.
+     * - `false`: ignore project plugins for this compiler instance.
+     * - array: use these plugin entries instead of the project config entries.
+     *
+     * Plugin entries are resolved once per operation from this instance context.
+     * Per-call plugin overrides are intentionally not part of the public API.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+}

package/lib/structures/ITtscCompilerContext.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ITtscCompilerContext.js.map

package/lib/structures/ITtscCompilerContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscCompilerContext.js","sourceRoot":"","sources":["../../src/structures/ITtscCompilerContext.ts"],"names":[],"mappings":""}

package/lib/structures/ITtscCompilerDiagnostic.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Diagnostic information from the ttsc TypeScript-Go compiler.
+ *
+ * Represents standardized diagnostic information produced during a
+ * TypeScript-Go compilation. This interface provides a simplified and
+ * consistent representation of TypeScript's diagnostic structure without
+ * requiring callers to depend on TypeScript-Go's internal Go types or parse
+ * terminal output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ITtscCompilerDiagnostic {
+    /**
+     * The filename where the diagnostic originated, or null if not
+     * file-specific.
+     *
+     * Global diagnostics such as invalid compiler options or host-level failures
+     * are reported with `null` because they are not tied to a single source file.
+     */
+    file: string | null;
+    /**
+     * The severity category of the diagnostic.
+     *
+     * Values follow TypeScript's diagnostic categories: error, warning,
+     * suggestion, and message.
+     */
+    category: ITtscCompilerDiagnostic.Category;
+    /**
+     * The error code or identifier associated with this diagnostic.
+     *
+     * TypeScript diagnostics normally use numeric codes such as `2322`. Native
+     * plugins may use stable string identifiers for plugin-defined diagnostics.
+     */
+    code: number | string;
+    /**
+     * The starting position of the issue in the source file, if available.
+     *
+     * TypeScript-Go reports this as a zero-based character offset. It is omitted
+     * for global diagnostics or messages that do not expose a source offset.
+     */
+    start?: number;
+    /**
+     * The length of the problematic section in the source file, if available.
+     *
+     * Omitted when TypeScript-Go or a native plugin reports only a point
+     * location, or when the diagnostic is not tied to a source file.
+     */
+    length?: number;
+    /**
+     * 1-based line number where the diagnostic starts, if available.
+     *
+     * This follows TypeScript's display convention rather than TypeScript-Go's
+     * zero-based internal line index.
+     */
+    line?: number;
+    /**
+     * 1-based character (column) position where the diagnostic starts, if
+     * available.
+     *
+     * This follows TypeScript's display convention rather than TypeScript-Go's
+     * zero-based internal column index.
+     */
+    character?: number;
+    /**
+     * The human-readable diagnostic message describing the issue.
+     *
+     * Message chains are flattened into text so callers do not need to depend on
+     * TypeScript-Go's internal diagnostic representation.
+     */
+    messageText: string;
+}
+export declare namespace ITtscCompilerDiagnostic {
+    /**
+     * Possible severity categories for diagnostics.
+     *
+     * - `"warning"`: issues that might cause problems but do not necessarily
+     *   prevent compilation.
+     * - `"error"`: issues that prevent successful compilation.
+     * - `"suggestion"`: recommendations for code improvement.
+     * - `"message"`: informational notes without warning or error severity.
+     */
+    type Category = "warning" | "error" | "suggestion" | "message";
+}

package/lib/structures/ITtscCompilerDiagnostic.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ITtscCompilerDiagnostic.js.map

package/lib/structures/ITtscCompilerDiagnostic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscCompilerDiagnostic.js","sourceRoot":"","sources":["../../src/structures/ITtscCompilerDiagnostic.ts"],"names":[],"mappings":""}

package/lib/structures/ITtscCompilerResult.d.ts

@@ -0,0 +1,83 @@
+import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
+/**
+ * Result of a ttsc TypeScript-Go compilation operation.
+ *
+ * Represents the possible outcomes of {@link TtscCompiler.compile}, which can
+ * be either a successful compilation, a compilation that completed with
+ * diagnostics, or an unexpected host error during the compilation process.
+ *
+ * This type follows the legacy `embed-typescript` result model, but stores all
+ * emitted text artifacts in {@link ITtscCompilerResult.ISuccess.output} and
+ * {@link ITtscCompilerResult.IFailure.output}. TypeScript-Go may emit
+ * JavaScript, declaration files, source maps, and declaration maps from one
+ * compile operation, so the public result is not limited to JavaScript.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ITtscCompilerResult = ITtscCompilerResult.ISuccess | ITtscCompilerResult.IFailure | ITtscCompilerResult.IException;
+export declare namespace ITtscCompilerResult {
+    /**
+     * Represents a successful ttsc compilation result.
+     *
+     * This interface is returned when TypeScript-Go completes without
+     * diagnostics, containing every text output captured from the native
+     * compiler host's `WriteFile` callback.
+     */
+    interface ISuccess {
+        /**
+         * Indicates that the compilation was successful.
+         */
+        type: "success";
+        /**
+         * The generated compiler output.
+         *
+         * A record mapping project-relative output file paths to their generated
+         * text content. This includes JavaScript, declaration files, source maps,
+         * declaration maps, and any other text artifact emitted through
+         * TypeScript-Go's `WriteFile` callback.
+         */
+        output: Record<string, string>;
+    }
+    /**
+     * Represents a ttsc compilation that completed but had diagnostics.
+     *
+     * This interface is returned when the compiler reports errors, warnings, or
+     * other diagnostics during normal compilation. It contains both structured
+     * diagnostic information and any output that was still generated despite the
+     * diagnostics.
+     */
+    interface IFailure {
+        /**
+         * Indicates that compilation completed with diagnostics.
+         */
+        type: "failure";
+        /**
+         * Array of diagnostic messages describing the compilation issues.
+         */
+        diagnostics: ITtscCompilerDiagnostic[];
+        /**
+         * Any compiler output that was generated despite the diagnostics.
+         *
+         * This may be partial or empty depending on the severity of the issues and
+         * how far TypeScript-Go progressed before returning diagnostics.
+         */
+        output: Record<string, string>;
+    }
+    /**
+     * Represents an unexpected error during the compilation process.
+     *
+     * This interface is returned when ttsc cannot prepare, build, or spawn the
+     * native compiler host. Normal TypeScript diagnostics are represented by
+     * {@link IFailure}; this variant is reserved for host-level exceptions.
+     */
+    interface IException {
+        /**
+         * Indicates that an unexpected host error occurred.
+         */
+        type: "exception";
+        /**
+         * The error that was thrown while preparing or running the compiler host.
+         */
+        error: unknown;
+    }
+}

package/lib/structures/{ITtscCacheKeyInput.js → ITtscCompilerResult.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ITtscCacheKeyInput.js.map
+//# sourceMappingURL=ITtscCompilerResult.js.map

package/lib/structures/ITtscCompilerResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscCompilerResult.js","sourceRoot":"","sources":["../../src/structures/ITtscCompilerResult.ts"],"names":[],"mappings":""}

package/lib/structures/ITtscPlugin.d.ts

@@ -1,10 +1,55 @@
-import type { ITtscNativeBackend } from "./ITtscNativeBackend";
-import type { ITtscNativeRewriteMode } from "./ITtscNativeRewriteMode";
+import type { TtscPluginStage } from "./TtscPluginStage";
+/**
+ * Runtime descriptor returned by a ttsc plugin module.
+ *
+ * A JavaScript plugin entry in `compilerOptions.plugins[]` is only the loading
+ * point. After ttsc resolves that JavaScript module, the module must return an
+ * `ITtscPlugin` descriptor either directly, as `default`, as `plugin`, or from
+ * `createTtscPlugin(context)`.
+ *
+ * The descriptor tells ttsc which Go command package implements the native
+ * sidecar and where that sidecar participates in the TypeScript-Go pipeline.
+ * ttsc then builds the Go source lazily with the bundled Go toolchain and
+ * passes the original project plugin config to the sidecar through
+ * `--plugins-json`.
+ */
 export interface ITtscPlugin {
+    /**
+     * Stable plugin name used in diagnostics, build messages, and native plugin
+     * manifests.
+     *
+     * Keep this stable across releases. Native sidecars and downstream tooling
+     * can use the name to select their own config from the ordered
+     * `--plugins-json` payload.
+     */
     name: string;
-    native?: ITtscNativeBackend;
-    /** @deprecated Use `native.mode` instead. */
-    nativeMode?: ITtscNativeRewriteMode;
-    /** @deprecated Use `native.binary` instead. */
-    nativeBinary?: string;
+    /**
+     * Go command package directory, or a `go.mod` file, that ttsc lazily builds.
+     *
+     * ttsc accepts source only. It does not accept a prebuilt binary path: the
+     * package-local Go compiler builds this source into the ttsc plugin cache on
+     * demand.
+     *
+     * Directory sources search upward at most 3 parent directories for `go.mod`;
+     * direct `go.mod` sources build the module root as `.`.
+     *
+     * Common layouts:
+     *
+     * - `source: "src"` when the plugin package keeps its Go command in `src`.
+     * - `source: "plugin"` when the repository has a dedicated Go plugin folder.
+     * - `source: "lib"` only when the published package intentionally ships Go
+     *   source under `lib` instead of compiled JavaScript.
+     * - `source: "go.mod"` when the module root itself is the command package.
+     */
+    source: string;
+    /**
+     * Pipeline stage implemented by the sidecar.
+     *
+     * Omit this field for normal compiler-transform plugins. Explicit stages are
+     * intended for tools that only validate (`"check"`) or rewrite already
+     * emitted files (`"output"`).
+     *
+     * @default "transform"
+     */
+    stage?: TtscPluginStage;
 }

package/lib/structures/ITtscPluginFactoryContext.d.ts

@@ -1,8 +1,55 @@
 import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+/**
+ * Project context passed to `createTtscPlugin()` factories.
+ *
+ * Plugin packages may export a static {@link ITtscPlugin} descriptor when the
+ * descriptor never depends on the consuming project. Export a
+ * `createTtscPlugin(context)` factory instead when the descriptor needs to
+ * inspect the original plugin config, the resolved tsconfig path, or the
+ * project root.
+ *
+ * The factory runs in Node.js while ttsc is loading `compilerOptions.plugins`.
+ * It should only create the descriptor. Heavy validation and TypeScript-Go
+ * work belong in the Go sidecar selected by {@link ITtscPlugin.source}.
+ */
 export interface ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
+    /**
+     * Absolute ttsc native helper binary selected for this invocation.
+     *
+     * This is the package's own native helper, not the plugin sidecar and not the
+     * JavaScript launcher. Most plugins do not need it; it is provided for
+     * advanced factories that need to derive behavior from the active ttsc
+     * native host.
+     */
     binary: string;
+    /**
+     * Current working directory requested by the caller.
+     *
+     * This is the cwd used for project discovery and relative command-line
+     * inputs. It can differ from {@link ITtscPluginFactoryContext.projectRoot}
+     * when the caller points at a tsconfig in another directory.
+     */
     cwd: string;
+    /**
+     * Original `compilerOptions.plugins[]` entry that loaded this plugin.
+     *
+     * ttsc reserves `transform` and `enabled`. Every other property is
+     * plugin-owned config and is later serialized unchanged into the native
+     * sidecar manifest.
+     */
     plugin: T;
+    /**
+     * Directory containing the resolved tsconfig/jsconfig.
+     *
+     * Relative plugin module specifiers and plugin source paths are resolved from
+     * this directory, matching TypeScript plugin config behavior.
+     */
     projectRoot: string;
+    /**
+     * Absolute path to the resolved tsconfig/jsconfig.
+     *
+     * Factories can use this to select descriptor variants for monorepos or
+     * multiple project configs without reparsing command-line arguments.
+     */
     tsconfig: string;
 }

package/lib/structures/ITtscProjectPluginConfig.d.ts

@@ -1,5 +1,46 @@
+/**
+ * Raw `compilerOptions.plugins[]` entry read from tsconfig/jsconfig.
+ *
+ * This is the project-facing config shape that users write in
+ * `tsconfig.json`. ttsc deliberately keeps it open-ended because plugin
+ * packages own their own config fields.
+ *
+ * ttsc interprets only two properties:
+ *
+ * - `transform`: the JavaScript module specifier used to load the plugin
+ *   descriptor or factory.
+ * - `enabled`: an opt-out switch that keeps the config entry in the file while
+ *   preventing ttsc from loading it.
+ *
+ * Every other property is preserved as plugin config. After ttsc loads and
+ * builds the plugin, the original entry is serialized into the native sidecar
+ * manifest so Go code can read exactly the same plugin-specific options.
+ */
 export interface ITtscProjectPluginConfig {
+    /**
+     * Set to `false` to keep the entry while disabling it for ttsc.
+     *
+     * This is useful for sharing one tsconfig across environments while turning
+     * selected plugins on or off without deleting their config.
+     */
     enabled?: boolean;
+    /**
+     * Plugin module specifier, relative path, or absolute path to load.
+     *
+     * Relative paths are resolved from the resolved project root, which is the
+     * directory containing the active tsconfig/jsconfig. Package specifiers are
+     * resolved with Node's package resolution from that same project root.
+     *
+     * The loaded JavaScript module must export an {@link ITtscPlugin} descriptor
+     * or a `createTtscPlugin(context)` factory. The Go implementation itself is
+     * declared by the descriptor's {@link ITtscPlugin.source} field.
+     */
     transform?: string;
+    /**
+     * Plugin-specific config passed through unchanged to the native sidecar.
+     *
+     * ttsc does not validate these fields. Plugin packages should document their
+     * own config contract and validate it inside their factory or Go sidecar.
+     */
     [key: string]: unknown;
 }

package/lib/structures/TtscPluginStage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pipeline stage where a plugin's lazily built Go sidecar participates.
+ *
+ * - `"transform"`: owns the TypeScript-Go emit pass. This is the default and
+ *   is the right stage for compiler-transform plugins such as typia-style
+ *   source rewrites. A transform sidecar receives the ordered plugin manifest
+ *   and is responsible for producing the project's emitted output.
+ * - `"check"`: runs before emit and reports diagnostics only. Use this for
+ *   lint or validation plugins that should fail the compile before JavaScript
+ *   or declaration output is generated.
+ * - `"output"`: runs after emit for each emitted output file. Use this for
+ *   post-processing plugins such as banner insertion, import-path rewriting,
+ *   or output stripping that operate on `.js`, `.d.ts`, or map files.
+ */
+export type TtscPluginStage = "transform" | "check" | "output";

package/lib/structures/{ITtscBuildResult.js → TtscPluginStage.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=ITtscBuildResult.js.map
+//# sourceMappingURL=TtscPluginStage.js.map

package/lib/structures/TtscPluginStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscPluginStage.js","sourceRoot":"","sources":["../../src/structures/TtscPluginStage.ts"],"names":[],"mappings":""}

package/lib/structures/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./ITtscCompilerContext";
+export * from "./ITtscCompilerDiagnostic";
+export * from "./ITtscCompilerResult";
+export * from "./ITtscPlugin";
+export * from "./ITtscPluginFactoryContext";
+export * from "./ITtscProjectPluginConfig";
+export * from "./TtscPluginStage";