ttsc 0.32.0 → 0.32.1

package/src/plugin/internal/load/pluginResolutionFailure.ts

@@ -0,0 +1,37 @@
+/**
+ * Attribute a package-resolution failure to its plugin and consumer directory.
+ *
+ * Runtime resolvers can throw objects with an empty message. The request and
+ * directory remain actionable independently of that message; the original cause
+ * and any string error code remain available to callers.
+ *
+ * @evidence contracts/common.md#principled-implementation Resolution supplies the actual specifier and consumer directory, so diagnostic context survives an empty runtime message without inferring a cause or changing resolver policy.
+ * @evidence contracts/common.md#clear-and-simple-design One error boundary enriches diagnostics while preserving the original cause and a string code.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Error attribution uses every failed request without package-name, runtime-name or message-pattern exceptions.
+ * @evidence contracts/common.md#meaningful-documentation The comment states why independent resolution context is necessary and which original failure fields survive.
+ *
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The function displays caller-supplied strings and performs no filesystem, path-identity or process operation.
+ * @evidence contracts/performance.md#efficient-algorithms One diagnostic allocation copies specifier, directory and optional message text; work and storage scale with those strings.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Errors describe the current failed request and own no reusable observation.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned error transfers its cause to the caller and owns no native resource or cross-call population.
+ */
+export function pluginResolutionFailure(
+  specifier: string,
+  consumerDir: string,
+  cause: unknown,
+): Error {
+  const record =
+    typeof cause === "object" && cause !== null
+      ? (cause as { code?: unknown; message?: unknown })
+      : undefined;
+  const message = typeof cause === "string" ? cause : record?.message;
+  const detail =
+    typeof message === "string" && message.trim() !== "" ? `: ${message}` : "";
+  const error = new Error(
+    `ttsc: could not resolve plugin ${JSON.stringify(specifier)} from ${JSON.stringify(consumerDir)}${detail}`,
+    { cause },
+  );
+  return typeof record?.code === "string"
+    ? Object.assign(error, { code: record.code })
+    : error;
+}

package/src/plugin/internal/source/PluginBuildEnvironmentReadings.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { SHARE_ENV, Worker } from "node:worker_threads";
 
 import { SidecarEnvironment } from "../../../compiler/internal/sharedHost/SidecarEnvironment";
+import { workerModuleUrl } from "../../../internal/workerModuleUrl";
 import { PluginBuildEnvironmentWitness } from "./PluginBuildEnvironmentWitness";
 import { PluginContentIdentities } from "./PluginContentIdentities";
 import { pluginBuildEnvironment } from "./pluginBuildEnvironment";
@@ -24,7 +25,7 @@ import { pluginBuildEnvironment } from "./pluginBuildEnvironment";
  * @evidence contracts/common.md#clear-and-simple-design One owner shares observation records across synchronous reads, cache-only proof and asynchronous preparation.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Cold preparation performs the same actual native Go/toolchain reading off-thread; failed or stale observations are never replaced by producer-expected state.
  * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes preparation, publication and cache-only authority; members document their separate execution responsibilities.
- * @evidence contracts/portability.md#os-neutral-implementation Complete environment snapshots use the shared native-name merger; metadata witnesses preserve actual native filesystem and link identity.
+ * @evidence contracts/portability.md#os-neutral-implementation Complete environment snapshots use the shared native-name merger; metadata witnesses preserve actual native filesystem and link identity. A supported module URL requires the CommonJS source or emitted worker entry while Node retains inherited execution options and preload hooks.
  * @evidenceExclude contracts/performance.md#efficient-algorithms Individual members own variable indexing, witness validation and native preparation.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work The members specify the invalidation and sharing boundaries.
  * @evidence contracts/performance.md#bound-retention-and-release-resources Readings replace existing keys but retain historical directory/environment keys without eviction. One idle worker and its retirement listeners remain process-owned/unreferenced; active work is ref'ed and per-request listeners are removed at settlement. Distinct requests can queue without a population bound/timeout; a stalled request can delay successors. Failed-worker termination is initiated without joining its promise, and this owner does not mutate the shared environment.
@@ -293,7 +294,12 @@ export namespace PluginBuildEnvironmentReadings {
   function acquireWorker(): Worker {
     if (worker !== undefined) return worker;
     const created = new Worker(
-      path.join(__dirname, "pluginBuildEnvironmentWorker.js"),
+      workerModuleUrl(
+        path.join(
+          __dirname,
+          `pluginBuildEnvironmentWorker${path.extname(__filename)}`,
+        ),
+      ),
       { env: SHARE_ENV },
     );
     worker = created;

package/src/structures/ITtscCompilerContext.ts

@@ -29,8 +29,7 @@ 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.
+   * resolve project source files, and resolve relative cache paths.
    *
    * An omitted value uses `process.cwd()` when the operation resolves its
    * context; construction does not capture that default.
@@ -49,19 +48,20 @@ export interface ITtscCompilerContext {
   tsconfig?: string;
 
   /**
-   * Project root override for generated config wrappers.
+   * Source root used for source membership, native plugin cwd and cache paths.
    *
-   * Most callers should leave this unset so the project root is the directory
-   * containing {@link ITtscCompilerContext.tsconfig}. Embedders that synthesize
-   * a temporary config extending a real project config can set this to keep
-   * plugin resolution, cache paths, and native plugin `--cwd` anchored to the
-   * real project.
+   * Omission uses the resolved config directory. Set a common ancestor when the
+   * config includes sibling packages; relative paths resolve from cwd. Returned
+   * relative Go-source paths and descriptor process cwd also use this root.
+   * Plugin package resolution and factory contexts keep the selected config
+   * directory independently. Generated config wrappers supply the real consumer
+   * directory through pluginConfigDir and may retain a wider source root here.
    */
   projectRoot?: string;
 
   /**
-   * Directory that anchors plugin config-file discovery and relative
-   * `configFile` resolution.
+   * Consumer directory for plugin packages, factory contexts, plugin
+   * config-file discovery and relative `configFile` resolution.
    *
    * Leave this unset so plugins anchor at the directory of the resolved
    * {@link ITtscCompilerContext.tsconfig} as usual. Embedders that compile
@@ -89,8 +89,8 @@ export interface ITtscCompilerContext {
   binary?: string;
 
   /**
-   * Additional environment variables for child compiler and plugin-descriptor
-   * processes, and for the worker thread of
+   * Additional environment variables for executable selection, compiler and
+   * plugin-descriptor child processes, and for the worker thread of
    * {@link TtscCompiler.transformAsync}.
    *
    * The supplied overrides are copied at construction. Values are merged over

package/src/structures/ITtscPlugin.ts

@@ -87,11 +87,13 @@ export interface ITtscPlugin {
    * linked into the selected native host and must register through
    * `driver.RegisterPlugin`.
    *
-   * 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. 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).
+   * Relative paths are resolved from the compiler's source root, including an
+   * explicit projectRoot override. This can differ from the factory's consumer
+   * directory for plugin package resolution. Package descriptors published in
+   * npm packages should normally return absolute paths 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:
    *

package/src/structures/ITtscPluginFactoryContext.ts

@@ -76,8 +76,8 @@ export interface ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
   plugin: T;
 
   /**
-   * Caller-declared anchor for plugin config-file discovery and relative
-   * `configFile` resolution.
+   * Caller-declared consumer directory for plugin package discovery, factory
+   * contexts and relative `configFile` resolution.
    *
    * Absent for ordinary invocations, where a factory anchors config discovery
    * at the {@link ITtscPluginFactoryContext.tsconfig} directory. Present when
@@ -91,13 +91,14 @@ export interface ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
   pluginConfigDir?: string;
 
   /**
-   * Project root used as the native plugin working directory and package
-   * discovery base.
+   * Consumer directory used for plugin package discovery.
    *
-   * By default this is the directory containing the resolved tsconfig/jsconfig.
-   * Callers may override it when a wrapper config lives outside the project.
-   * Relative `source` paths returned by a plugin descriptor resolve from this
-   * directory.
+   * This is pluginConfigDir when supplied, otherwise the directory containing
+   * the resolved tsconfig/jsconfig. A compiler projectRoot override can widen
+   * source membership without changing this package-resolution anchor.
+   * Descriptor process cwd, native plugin cwd and returned relative source
+   * paths retain the compiler's source root; return absolute source paths when
+   * those directories differ.
    */
   projectRoot: string;
 

package/src/structures/internal/TtscSingleFileEmitOptions.ts

@@ -42,10 +42,14 @@ export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
  * this notification is not the complete compiler or project-rule input graph.
  * The reporting load also hands over its record store, if it opened one, so the
  * owner proves each root's state from the plugin cache's records instead of
- * reading the sources the load is about to prove (#1728).
+ * reading the sources the load is about to prove (#1728). Asynchronous build
+ * entries await a returned promise before reading or building those sources;
+ * synchronous entries require a synchronous handler. Separate function
+ * alternatives preserve TypeScript's void-handler assignability, including
+ * ignored non-promise return values.
  *
- * @evidence contracts/common.md#principled-implementation Readonly roots describe the actual native-plugin sources whose later edits need observation.
- * @evidence contracts/common.md#clear-and-simple-design A void notification leaves watcher construction and lifetime with the invocation owner.
+ * @evidence contracts/common.md#principled-implementation Readonly roots describe the actual native-plugin sources whose later edits need observation; separate void and Promise function alternatives preserve existing ignored-return callback assignability while exposing asynchronous completion.
+ * @evidence contracts/common.md#clear-and-simple-design The handoff leaves watcher construction and lifetime with the invocation owner, while its completion determines when the producer may continue.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts The supported callback neither replaces foreign watchers nor fabricates fixture-specific roots.
  * @evidence contracts/common.md#meaningful-documentation Native prose states the source population and owner before acknowledgment tags.
  * @evidence contracts/portability.md#os-neutral-implementation Native source paths pass through without separator rewriting, alias collapse or an encoded OS-specific watcher.
@@ -53,16 +57,23 @@ export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
  * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
  */
-export type TtscPluginSourceInputsHandler = (
-  inputs: readonly string[],
-  identities?: PluginContentIdentities.Store,
-) => void;
+export type TtscPluginSourceInputsHandler =
+  | ((
+      inputs: readonly string[],
+      identities?: PluginContentIdentities.Store,
+    ) => void)
+  | ((
+      inputs: readonly string[],
+      identities?: PluginContentIdentities.Store,
+    ) => Promise<void>);
 
 /**
  * Receive the discovered project-rule filesystem topology for the watch owner.
+ * Asynchronous build entries await a returned promise before compilation;
+ * synchronous entries require a synchronous handler.
  *
  * @evidence contracts/common.md#principled-implementation The snapshot retains exact, glob and reload dependencies rather than reducing them to plugin-source roots.
- * @evidence contracts/common.md#clear-and-simple-design A separate void notification transfers topology without assigning watcher lifetime to the emit options.
+ * @evidence contracts/common.md#clear-and-simple-design A separate completion-bearing notification transfers topology without assigning watcher lifetime to the emit options.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts A discovered rule snapshot crosses a supported boundary without replacing watcher internals or inventing passing inputs.
  * @evidence contracts/common.md#meaningful-documentation Native prose identifies the project-rule payload and watch owner before the separated tags.
  * @evidence contracts/portability.md#os-neutral-implementation The snapshot retains native paths, explicit glob grammar and declared versus physical identities without blanket case folding.
@@ -70,6 +81,6 @@ export type TtscPluginSourceInputsHandler = (
  * @evidenceExclude contracts/performance.md#efficient-algorithms A type declaration chooses no processing strategy.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work A type declaration computes nothing, so there is no work to share.
  */
-export type TtscProjectInputsHandler = (
-  inputs: ITtscProjectInputSnapshot,
-) => void;
+export type TtscProjectInputsHandler =
+  | ((inputs: ITtscProjectInputSnapshot) => void)
+  | ((inputs: ITtscProjectInputSnapshot) => Promise<void>);