ttsc 0.16.2 → 0.16.5

package/shim/ast/shim.go

@@ -189,6 +189,12 @@ func NewNodeVisitor(visit func(node *Node) *Node, factory *NodeFactory, options
   return innerast.NewNodeVisitor(visit, factory, options)
 }
 
+// GetCombinedModifierFlags returns syntactic modifiers combined across wrappers
+// such as variable statements and their declaration lists.
+func GetCombinedModifierFlags(node *Node) ModifierFlags {
+  return innerast.GetCombinedModifierFlags(node)
+}
+
 // IsFunctionLike reports whether node is any function-like construct
 // (function declaration, arrow function, method, constructor, accessor, etc.).
 func IsFunctionLike(node *Node) bool {

package/shim/checker/shim.go

@@ -81,7 +81,7 @@ func Checker_getPropertiesOfType(recv *innerchecker.Checker, t *innerchecker.Typ
 }
 
 // Checker_getApparentProperties returns the properties visible on t after
-// resolving primitive wrapper types (e.g. string → String).
+// resolving primitive wrapper types (e.g. string to String).
 func Checker_getApparentProperties(recv *innerchecker.Checker, t *innerchecker.Type) []*innerast.Symbol {
   return recv.GetApparentProperties(t)
 }
@@ -149,6 +149,16 @@ func Checker_getAliasedSymbol(recv *innerchecker.Checker, symbol *innerast.Symbo
   return recv.GetAliasedSymbol(symbol)
 }
 
+// Checker_getExportsOfModule returns the exported symbols of a source-file or
+// namespace module symbol, resolving export-star aggregation the same way the
+// checker does for emit and services.
+func Checker_getExportsOfModule(recv *innerchecker.Checker, symbol *innerast.Symbol) []*innerast.Symbol {
+  if recv == nil || symbol == nil {
+    return nil
+  }
+  return recv.GetExportsOfModule(symbol)
+}
+
 //go:linkname checkerResolveEntityName github.com/microsoft/typescript-go/internal/checker.(*Checker).resolveEntityName
 func checkerResolveEntityName(
   recv *innerchecker.Checker,
@@ -215,8 +225,8 @@ func Checker_getBaseTypes(recv *innerchecker.Checker, t *innerchecker.Type) []*i
 func checkerGetDeclaredTypeOfSymbol(recv *innerchecker.Checker, symbol *innerast.Symbol) *innerchecker.Type
 
 // Checker_getDeclaredTypeOfSymbol returns the declared (instance) type of a
-// class or interface symbol. Unlike Checker_getTypeOfSymbol — which yields the
-// constructor (static) type of a class symbol — the result IS a
+// class or interface symbol. Unlike Checker_getTypeOfSymbol, which yields the
+// constructor (static) type of a class symbol, the result IS a
 // ClassOrInterface type and is therefore safe to feed back into
 // Checker_getBaseTypes. This lets a consumer resolve a generic base's symbol to
 // its declared type and keep walking the base chain past the generic boundary
@@ -275,10 +285,10 @@ func Checker_getReturnTypeOfSignature(recv *innerchecker.Checker, signature *inn
 // parameter is excluded (it is held separately from the value parameters).
 //
 // Checker_getMinArgumentCount alone cannot tell a zero-parameter signature
-// (`()` — minimum 0) from a single-optional-parameter one (`(x?)` — also
+// (`()` minimum 0) from a single-optional-parameter one (`(x?)` also
 // minimum 0). A type-transform plugin needs that distinction to replicate the
-// type-level "single meaningful argument" rule — a FIRST parameter must exist
-// and every later parameter must be optional or rest — as
+// type-level "single meaningful argument" rule: a FIRST parameter must exist
+// and every later parameter must be optional or rest, as
 // `Signature_parameterCount(sig) >= 1 && Checker_getMinArgumentCount(c, sig) <= 1`.
 // Without it the `new C(x)` / `C.from(x)` strategies silently fall back to field
 // copy for every optional-first constructor or factory. Returns 0 if signature
@@ -297,7 +307,7 @@ func Signature_parameterCount(signature *innerchecker.Signature) int {
 // yields the seed TYPE the plugin must decode before constructing the instance.
 //
 // Signature_parameterCount is len() of this slice; the slice itself is needed
-// because detection (count + min-args) is not enough — emission requires the
+// because detection (count + min-args) is not enough; emission requires the
 // seed parameter's type. Returns nil if signature is nil.
 func Signature_parameters(signature *innerchecker.Signature) []*innerast.Symbol {
   if signature == nil {
@@ -308,8 +318,8 @@ func Signature_parameters(signature *innerchecker.Signature) []*innerast.Symbol
 
 // Signature_hasRestParameter reports whether the signature's last value
 // parameter is a rest parameter (`...xs: S[]`). It is the signal a from/new
-// transform needs to tell a rest-only single-seed call `(...xs: S[])` — whose
-// seed is the ELEMENT S — from a genuine array-typed parameter `(seed: S[])` —
+// transform needs to tell a rest-only single-seed call `(...xs: S[])`, whose
+// seed is the ELEMENT S, from a genuine array-typed parameter `(seed: S[])`,
 // whose seed is the array S[]: getTypeOfSymbol yields `S[]` for BOTH, so without
 // this flag they are indistinguishable and the rest case decodes the wrong
 // shape.
@@ -317,8 +327,8 @@ func Signature_parameters(signature *innerchecker.Signature) []*innerast.Symbol
 // The rest ELEMENT is the seed ONLY when the rest parameter is the sole value
 // parameter, i.e. `Signature_hasRestParameter(sig) && Signature_parameterCount(sig) == 1`.
 // A leading-required + rest-tail signature `(s: S, ...r: R[])` also has a rest
-// parameter (this returns true), but its seed is the FIRST parameter S — read it
-// from Signature_parameters(sig)[0], NOT the rest element — matching
+// parameter (this returns true), but its seed is the FIRST parameter S. Read it
+// from Signature_parameters(sig)[0], NOT the rest element, matching
 // ClassifiableSeed, whose `[infer P, ...Rest]` arm picks P=S there. Returns
 // false if signature is nil.
 func Signature_hasRestParameter(signature *innerchecker.Signature) bool {
@@ -330,7 +340,7 @@ func Signature_hasRestParameter(signature *innerchecker.Signature) bool {
 
 // Checker_getRestTypeOfSignature returns the ELEMENT type of the signature's
 // rest parameter (`...xs: S[]` -> S; a tuple rest unwraps to its element too),
-// which is the seed type for a rest-ONLY single-argument constructor/factory —
+// which is the seed type for a rest-ONLY single-argument constructor/factory,
 // matching ClassifiableSeed, which unwraps the rest to its element. When the
 // signature has NO rest parameter it falls back to `any` upstream; and a
 // leading-required + rest-tail `(s: S, ...r: R[])` has a rest parameter yet its

package/src/TtscService.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+
+import type { ResidentTransformProcess } from "./compiler/internal/residentTransformProcess";
+import { startResidentTransform } from "./compiler/internal/startResidentTransform";
+import type { ITtscCompilerContext } from "./structures/ITtscCompilerContext";
+
+/**
+ * Resident, incremental transform service for the `ttsc` TypeScript-Go
+ * pipeline.
+ *
+ * Where {@link TtscCompiler.transform} spawns a fresh process and recompiles the
+ * whole project on every call, `TtscService` keeps one long-lived host warm: it
+ * compiles the project once and then answers per-file transform requests from
+ * that warm program. A single service instance transforms many files (a watch
+ * server, an editor session, a codegen tool) while paying the project compile
+ * once instead of once per file. Sharing one host across separate worker
+ * processes (a Metro worker pool) is tracked in samchon/ttsc#255.
+ *
+ * The shape mirrors a legacy TypeScript `LanguageService`: construct it against
+ * a project context, ask it to transform individual files, and dispose it when
+ * done. Construction is synchronous (it launches the host); the host compiles
+ * in the background, so the first {@link transformFile} resolves once that
+ * compile lands.
+ *
+ * Resident mode runs through the linked-plugin shared host, so the project must
+ * declare at least one transform-stage plugin; the constructor throws
+ * otherwise. It does not run check-stage plugins (unlike
+ * {@link TtscCompiler.transform}); only the program's own type-checking gates an
+ * {@link updateFile}.
+ */
+export class TtscService {
+  private readonly resident: ResidentTransformProcess;
+  private readonly projectRoot: string;
+
+  /**
+   * Create a service bound to the given project context and launch its resident
+   * host. The context is the same shape {@link TtscCompiler} accepts; it is not
+   * replaceable per call.
+   */
+  public constructor(context: ITtscCompilerContext = {}) {
+    const started = startResidentTransform({
+      ...context,
+      env: context.env ? { ...context.env } : undefined,
+      plugins: Array.isArray(context.plugins)
+        ? [...context.plugins]
+        : context.plugins,
+    });
+    this.resident = started.process;
+    this.projectRoot = started.projectRoot;
+  }
+
+  /**
+   * Return the transformed TypeScript source for one file, or `undefined` when
+   * the resident program does not contain it (for example a file excluded from
+   * the tsconfig). A relative `fileName` is resolved against the project root.
+   *
+   * Rejects when the resident host failed to compile the project; the rejection
+   * carries the host's diagnostics so callers can surface a real build error.
+   */
+  public async transformFile(fileName: string): Promise<string | undefined> {
+    const reply = await this.resident.request({
+      file: this.absolutePath(fileName),
+    });
+    return reply.found === true && typeof reply.typescript === "string"
+      ? reply.typescript
+      : undefined;
+  }
+
+  /**
+   * Apply new in-memory content for one file and re-transform the project, so a
+   * subsequent {@link transformFile} reflects the edit without restarting the
+   * host. Returns whether the re-transform succeeded; `false` means the edit
+   * did not compile and the previous transform is still in effect. A relative
+   * `fileName` is resolved against the project root.
+   */
+  public async updateFile(fileName: string, content: string): Promise<boolean> {
+    const reply = await this.resident.request({
+      content,
+      update: this.absolutePath(fileName),
+    });
+    return reply.updated === true;
+  }
+
+  /** Terminate the resident host and reject any in-flight requests. */
+  public dispose(): void {
+    this.resident.dispose();
+  }
+
+  private absolutePath(fileName: string): string {
+    return path.isAbsolute(fileName)
+      ? fileName
+      : path.resolve(this.projectRoot, fileName);
+  }
+}

package/src/compiler/internal/residentTransformProcess.ts

@@ -0,0 +1,216 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type Interface, createInterface } from "node:readline";
+
+/** Cap on retained stderr so a long-lived host cannot grow it without bound. */
+const STDERR_TAIL_LIMIT = 64 * 1024;
+
+/** Options for spawning the resident transform host. */
+export interface ResidentTransformProcessOptions {
+  args: readonly string[];
+  binary: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+interface PendingRequest {
+  reject: (reason: Error) => void;
+  resolve: (reply: Record<string, unknown>) => void;
+}
+
+/**
+ * Async client for the long-lived `utility-host serve` process.
+ *
+ * The host transforms the whole project once at startup, caches every file's
+ * transformed TypeScript, then answers newline-delimited requests. This class
+ * speaks that protocol: each {@link request} writes one JSON line and the host
+ * replies with one line, matched FIFO. A transform request (`{"file":...}`) is
+ * answered with `{"typescript":...,"found":...}`, and an update request
+ * (`{"update":...,"content":...}`) with `{"updated":...}`.
+ *
+ * One resident process answers every request from one service instead of
+ * spawning a fresh `transform` subprocess per call, so a single process pays
+ * the project compile once (samchon/ttsc#255).
+ */
+export class ResidentTransformProcess {
+  private readonly child: ChildProcess;
+  private readonly reader: Interface;
+  private readonly pending: PendingRequest[] = [];
+  private stderr = "";
+  private failure: Error | undefined;
+
+  public constructor(options: ResidentTransformProcessOptions) {
+    // Default stdio is "pipe" for stdin/stdout/stderr, which is exactly what the
+    // line protocol needs; spelling it out as a string[] would not narrow to
+    // StdioOptions, so it is left implicit.
+    this.child = spawn(options.binary, [...options.args], {
+      cwd: options.cwd,
+      env: options.env,
+      windowsHide: true,
+    });
+    const stdout = this.child.stdout;
+    const stdin = this.child.stdin;
+    if (stdout === null || stdin === null) {
+      this.child.kill();
+      throw new Error("ttsc: resident transform host has no stdio pipes");
+    }
+    this.reader = createInterface({ input: stdout });
+    this.reader.on("line", (line) => this.onLine(line));
+    // Drive completion off stdout's end, not the process "exit" event: every
+    // buffered "line" is delivered before "close", so a reply that arrived just
+    // before the host exited still resolves its request instead of racing the
+    // exit-time rejection.
+    this.reader.on("close", () => this.onReaderClose());
+    this.child.stderr?.on("data", (chunk: Buffer | string) => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      // Keep only the tail: stderr is consulted for the crash message, and a
+      // long resident session can write diagnostics on every failed update.
+      this.stderr = (this.stderr + text).slice(-STDERR_TAIL_LIMIT);
+    });
+    this.child.on("error", (error) => this.fail(error));
+    // A dead host's pipes emit "error" (EPIPE on POSIX, often ECONNRESET on
+    // Windows). Without these listeners Node turns a pipe error into an uncaught
+    // exception that crashes the whole consumer process; route them through
+    // fail() (stderr is non-critical) so a pipe death fails in-flight requests
+    // instead, and also closes the window where stdin.destroyed has not flipped.
+    stdin.on("error", (error) => this.fail(error));
+    stdout.on("error", (error) => this.fail(error));
+    this.child.stderr?.on("error", () => {});
+  }
+
+  /**
+   * Send one request to the host and resolve with its parsed JSON reply. The
+   * host answers in FIFO order, so the caller interprets the reply shape by the
+   * payload it sent (a transform reply vs an update reply). Rejects when the
+   * host has already failed or exited, or if writing the request fails.
+   */
+  public request(
+    payload: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
+    if (this.failure !== undefined) {
+      return Promise.reject(this.failure);
+    }
+    const stdin = this.child.stdin;
+    if (stdin === null || stdin.destroyed) {
+      return Promise.reject(
+        new Error("ttsc: resident transform host stdin is closed"),
+      );
+    }
+    return new Promise<Record<string, unknown>>((resolve, reject) => {
+      const pending: PendingRequest = { reject, resolve };
+      this.pending.push(pending);
+      stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+        if (error) {
+          this.removePending(pending);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  /**
+   * Terminate the resident process and reject any in-flight requests. Safe to
+   * call more than once.
+   */
+  public dispose(): void {
+    if (this.failure === undefined) {
+      // If the host already died, reject with its real exit error (stderr +
+      // exit code) rather than a bland "disposed" message.
+      this.failure =
+        this.child.exitCode !== null || this.child.signalCode !== null
+          ? this.exitError()
+          : new Error("ttsc: resident transform host disposed");
+    }
+    const stdin = this.child.stdin;
+    if (stdin !== null && !stdin.destroyed) {
+      stdin.end();
+    }
+    this.reader.close();
+    this.rejectAll(this.failure);
+    if (this.child.exitCode === null && this.child.signalCode === null) {
+      this.child.kill();
+    }
+  }
+
+  private onLine(line: string): void {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+    const request = this.pending.shift();
+    if (request === undefined) {
+      // The host must emit exactly one reply per request, so an unmatched line
+      // is a protocol violation that would desync every later reply into the
+      // wrong request. Fail fast rather than silently returning wrong output.
+      // A line arriving after teardown (failure already set) is benign.
+      if (this.failure === undefined) {
+        this.fail(
+          new Error("ttsc: resident transform host sent an unsolicited reply"),
+        );
+      }
+      return;
+    }
+    request.resolve(parseReply(trimmed));
+  }
+
+  private onReaderClose(): void {
+    if (this.pending.length === 0) {
+      return;
+    }
+    this.rejectAll(this.failure ?? this.exitError());
+  }
+
+  private fail(error: Error): void {
+    this.failure ??= error;
+    this.rejectAll(this.failure);
+  }
+
+  private rejectAll(error: Error): void {
+    while (this.pending.length !== 0) {
+      this.pending.shift()!.reject(error);
+    }
+  }
+
+  private removePending(target: PendingRequest): void {
+    const index = this.pending.indexOf(target);
+    if (index !== -1) {
+      this.pending.splice(index, 1);
+    }
+  }
+
+  private exitError(): Error {
+    const detail = this.stderr.trim();
+    if (detail.length !== 0) {
+      return new Error(detail);
+    }
+    // Read the child's own exit fields (set synchronously by Node) so the
+    // message is accurate even before this instance's "exit" handler would run.
+    const code = this.child.exitCode;
+    const signalCode = this.child.signalCode;
+    const signal = signalCode === null ? "" : `, signal ${signalCode}`;
+    return new Error(
+      `ttsc: resident transform host exited (code ${code ?? "null"}${signal})`,
+    );
+  }
+}
+
+/**
+ * Parse one reply line into a plain object. A malformed line degrades to an
+ * empty object rather than throwing, so one bad line never rejects a request
+ * the FIFO has already advanced past; the caller reads missing fields as
+ * absent.
+ */
+function parseReply(line: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // A non-object or unparseable line is treated as an empty reply.
+  }
+  return {};
+}

package/src/compiler/internal/startResidentTransform.ts

@@ -0,0 +1,126 @@
+import path from "node:path";
+
+import { loadProjectPlugins } from "../../plugin/internal/loadProjectPlugins";
+import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+import { readProjectConfig } from "./project/readProjectConfig";
+import { ResidentTransformProcess } from "./residentTransformProcess";
+import { resolveBinary } from "./resolveBinary";
+import { resolveTsgo } from "./resolveTsgo";
+import {
+  assertSharedHostCompatibility,
+  linkedTransformPlugins,
+  selectSharedHostPlugin,
+} from "./sharedHostHelpers";
+
+/**
+ * A started resident transform host plus the project root its keys are relative
+ * to.
+ */
+export interface StartedResidentTransform {
+  process: ResidentTransformProcess;
+  projectRoot: string;
+}
+
+/**
+ * Start a resident `serve` host for the configured project.
+ *
+ * Mirrors the plugin spawn of `transformProjectInMemory`, but launches the
+ * shared host's `serve` subcommand as one long-lived process instead of a
+ * per-call `transform` subprocess. The host compiles the whole project once at
+ * startup and then answers per-file requests, so one caller pays the project
+ * compile once and reuses it across its own per-file requests.
+ *
+ * Resident mode runs through the linked-plugin shared host
+ * (`cmd/utility-host`), which is the only binary that exposes `serve`. It
+ * therefore requires at least one transform-stage plugin; executable transform
+ * hosts that own their own process are not served and must use the per-call
+ * transform path. Check-stage plugins are not run by the resident host.
+ */
+export function startResidentTransform(
+  context: ITtscCompilerContext,
+): StartedResidentTransform {
+  const cwd = path.resolve(context.cwd ?? process.cwd());
+  const project = readProjectConfig({
+    cwd,
+    projectRoot: context.projectRoot,
+    tsconfig: context.tsconfig,
+  });
+  const loaded = loadProjectPlugins({
+    binary: resolveBinary(context) ?? "",
+    cacheDir: context.cacheDir ?? context.env?.TTSC_CACHE_DIR,
+    cwd,
+    entries: context.plugins,
+    projectRoot: context.projectRoot,
+    tsconfig: project.path,
+  });
+  const transformers = loaded.nativePlugins.filter(
+    (plugin) => plugin.stage === "transform",
+  );
+  if (transformers.length === 0) {
+    throw new Error(
+      "ttsc: TtscService resident mode requires at least one transform-stage plugin; " +
+        "use TtscCompiler.transform for projects with only check-stage plugins or none",
+    );
+  }
+  assertSharedHostCompatibility(transformers, "source-to-source");
+
+  const host = selectSharedHostPlugin(transformers);
+  const tsgoBinary = resolveTsgo({ ...context, cwd: project.root }).binary;
+  const resident = new ResidentTransformProcess({
+    args: [
+      "serve",
+      `--tsconfig=${project.path}`,
+      `--plugins-json=${serializeNativePlugins(transformers)}`,
+      `--cwd=${project.root}`,
+    ],
+    binary: host.binary,
+    cwd: project.root,
+    env: residentEnv(context, tsgoBinary, loaded.nativePlugins),
+  });
+  return { process: resident, projectRoot: project.root };
+}
+
+/**
+ * Build the environment for the resident host spawn. Matches the per-call
+ * transform spawn: injects the Node, tsgo, and ttsx binaries so the host never
+ * searches PATH, and forwards linked transform plugins via
+ * `TTSC_LINKED_PLUGINS_JSON`.
+ */
+function residentEnv(
+  context: ITtscCompilerContext,
+  tsgoBinary: string,
+  nativePlugins: readonly ITtscLoadedNativePlugin[],
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    TTSC_NODE_BINARY: process.env.TTSC_NODE_BINARY ?? process.execPath,
+    TTSC_TSGO_BINARY: process.env.TTSC_TSGO_BINARY ?? tsgoBinary,
+    TTSC_TTSX_BINARY:
+      process.env.TTSC_TTSX_BINARY ??
+      path.join(__dirname, "..", "..", "launcher", "ttsx.js"),
+    ...context.env,
+  };
+  const linked = linkedTransformPlugins(nativePlugins);
+  if (linked.length !== 0) {
+    env.TTSC_LINKED_PLUGINS_JSON = serializeNativePlugins(linked);
+  }
+  return env;
+}
+
+/**
+ * Serialize the plugin list to the `--plugins-json` /
+ * `TTSC_LINKED_PLUGINS_JSON` shape the native host reads: only the fields it
+ * needs, to keep the arg short.
+ */
+function serializeNativePlugins(
+  plugins: readonly ITtscLoadedNativePlugin[],
+): string {
+  return JSON.stringify(
+    plugins.map((plugin) => ({
+      config: plugin.config,
+      name: plugin.name,
+      stage: plugin.stage,
+    })),
+  );
+}

package/src/index.ts

@@ -8,4 +8,5 @@
  */
 
 export * from "./TtscCompiler";
+export * from "./TtscService";
 export * from "./structures/index";

package/src/plugin/internal/loadProjectPlugins.ts

@@ -570,7 +570,7 @@ function orderNativePlugins(
 
 function loadPluginEntry(
   entry: ITtscProjectPluginConfig,
-  context: ITtscPluginFactoryContext,
+  base: Omit<ITtscPluginFactoryContext, "dirname" | "filename">,
   baseDir: string,
 ): ITtscPlugin {
   return withPluginLoaderEnv(() => {
@@ -582,6 +582,16 @@ function loadPluginEntry(
     }
 
     const request = resolvePluginRequest(specifier, baseDir);
+    // `dirname`/`filename` are per-entry: each plugin entry resolves to its own
+    // descriptor module, so they are derived here from the resolved `request`
+    // rather than carried on the shared base context. They give factories a
+    // load-mode-independent stand-in for `__dirname`/`__filename`, which are
+    // undefined when a descriptor loads through ttsx or as ESM.
+    const context: ITtscPluginFactoryContext = {
+      ...base,
+      dirname: path.dirname(request),
+      filename: request,
+    };
     const mod = requirePluginEntry(request, context) as {
       createTtscPlugin?: TtscPluginFactory;
       default?: ITtscPlugin | TtscPluginFactory;
@@ -702,6 +712,8 @@ function loadDescriptorViaTtsx(
         TTSC_PLUGIN_CONTEXT: JSON.stringify({
           binary: context.binary,
           cwd: context.cwd,
+          dirname: context.dirname,
+          filename: context.filename,
           plugin: context.plugin,
           projectRoot: context.projectRoot,
           tsconfig: context.tsconfig,
@@ -853,8 +865,10 @@ function resolveGoPackageDir(source: string, label: string): string {
       `ttsc: plugin "${label}" source does not exist: ${source}\n` +
         `  Plugin descriptors run without CommonJS globals: __dirname, __filename, ` +
         `and require are undefined when ttsc loads a descriptor through ttsx or as ESM. ` +
-        `If this path was derived from one of them, resolve it from context.projectRoot ` +
-        `instead, e.g. createRequire(path.join(context.projectRoot, "package.json"))` +
+        `If this path was derived from one of them, use context.dirname / ` +
+        `context.filename (the descriptor's own directory and file, populated in ` +
+        `every load mode), or resolve it from context.projectRoot, e.g. ` +
+        `createRequire(path.join(context.projectRoot, "package.json"))` +
         `.resolve("<your-package>/package.json").`,
     );
   }

package/src/structures/ITtscPlugin.ts

@@ -37,14 +37,16 @@ export interface ITtscPlugin {
    *
    * Relative paths are resolved from the consumer project root. Package
    * descriptors published in npm packages should normally return absolute paths
-   * based on their own descriptor directory.
+   * based on their own descriptor directory — derive them from a factory's
+   * `context.dirname` (the load-mode-independent replacement for `__dirname`,
+   * which is undefined when ttsc loads the descriptor through ttsx or as ESM).
    *
    * Common layouts:
    *
-   * - `source: path.resolve(__dirname, "src")` when a package descriptor keeps
-   *   its Go command in `src`.
-   * - `source: path.resolve(__dirname, "plugin")` when a published package has a
-   *   dedicated Go plugin folder.
+   * - `source: path.resolve(context.dirname, "src")` when a package descriptor
+   *   keeps its Go command in `src`.
+   * - `source: path.resolve(context.dirname, "plugin")` when a published package
+   *   has a dedicated Go plugin folder.
    * - `source: "plugin"` only for project-local descriptors where the consumer
    *   project root owns the `plugin` directory.
    * - `source: "go.mod"` when the consumer project root itself is the command

package/src/structures/ITtscPluginFactoryContext.ts

@@ -6,7 +6,7 @@ import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
  * Plugin packages may export a static {@link ITtscPlugin} descriptor when the
  * descriptor never depends on the consuming project. Export a factory when the
  * descriptor needs to inspect the original plugin config, the resolved tsconfig
- * path, or the project root.
+ * path, the project root, or the descriptor's own location on disk.
  *
  * The factory runs in Node.js while ttsc is loading `compilerOptions.plugins`.
  * It should only create the descriptor. Heavy validation and TypeScript-Go work
@@ -32,6 +32,31 @@ export interface ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
    */
   cwd: string;
 
+  /**
+   * Absolute path to the directory holding the resolved plugin descriptor entry
+   * — the directory of {@link ITtscPluginFactoryContext.filename}.
+   *
+   * This is the load-mode-independent replacement for the CommonJS `__dirname`.
+   * A descriptor compiled to CommonJS and loaded through `require` keeps
+   * `__dirname`, but a `.ts`-source or ESM descriptor (loaded through ttsx or
+   * as a native module) runs without it, so a `source` derived from `__dirname`
+   * silently mis-resolves. Resolve package-relative paths from `dirname`
+   * instead: it is always the descriptor file's own directory, regardless of
+   * how ttsc loaded it.
+   */
+  dirname: string;
+
+  /**
+   * Absolute path to the resolved plugin descriptor entry module itself — the
+   * file ttsc loaded for this entry's `transform` specifier.
+   *
+   * This is the load-mode-independent replacement for the CommonJS
+   * `__filename`, available even when the descriptor runs as ESM or `.ts`
+   * source where the `__filename` global is undefined.
+   * {@link ITtscPluginFactoryContext.dirname} is its containing directory.
+   */
+  filename: string;
+
   /**
    * Original `compilerOptions.plugins[]` entry that loaded this plugin.
    *