ttsc 0.31.6 → 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/load/resolveNativeSource.ts

@@ -30,13 +30,19 @@ export function resolveNativeSource(
   plugin: ITtscPlugin,
   config: ITtscProjectPluginConfig,
   index: number,
-  options?: { env?: NodeJS.ProcessEnv; observation?: NativeSourcePackages.Package },
+  options?: {
+    env?: NodeJS.ProcessEnv;
+    observation?: NativeSourcePackages.Package;
+  },
 ): { kind: "executable" | "linked"; moduleRoot: string } {
   const label = pluginLabel(plugin, config, index);
   requirePluginSource(source, label);
   const { moduleRoot } = resolvePluginGoModule(source, label);
-  const observation = options?.observation ?? NativeSourcePackages.propose([
-    { source, label, ownModule: plugin.stage === "check" },
-  ], SidecarEnvironment.merge(options?.env ?? process.env))[0]!.observation;
+  const observation =
+    options?.observation ??
+    NativeSourcePackages.propose(
+      [{ source, label, ownModule: plugin.stage === "check" }],
+      SidecarEnvironment.merge(options?.env ?? process.env),
+    )[0]!.observation;
   return { kind: NativeSourcePackages.kind(observation, label), moduleRoot };
 }

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/plugin/internal/source/pluginModuleReplaceDirectories.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { resolvePhysicalPath } from "../../../internal/pathIdentity/resolvePhysicalPath";
 import { GoToolResolution } from "./GoToolResolution";
 import type { IPluginModuleReplaceDirectory } from "./IPluginModuleReplaceDirectory";
+import type { PluginContentIdentities } from "./PluginContentIdentities";
 import { SourcePluginWorkspace } from "./SourcePluginWorkspace";
 import { resolveGoCompiler } from "./resolveGoCompiler";
 import { selectPluginModuleReplaceDirectories } from "./selectPluginModuleReplaceDirectories";
@@ -30,6 +31,8 @@ import { selectPluginModuleReplaceDirectories } from "./selectPluginModuleReplac
  * @param env The build's effective environment.
  * @param goBinary The Go tool the build runs, or `undefined` to resolve it as
  *   the build does.
+ * @param identities The load's record store, carried by a reader this call
+ *   registers so the load's later reads reuse recorded syntax.
  * @returns Each replacement outside the module, sorted by module path: the
  *   replaced module path and version, the target as `go.mod` spells it, and the
  *   target's absolute path.
@@ -52,6 +55,7 @@ export function pluginModuleReplaceDirectories(
   goBinary?: string,
   reader?: SourcePluginWorkspace.GoModReader,
   readers?: Map<string, SourcePluginWorkspace.GoModReader>,
+  identities?: PluginContentIdentities.Store,
 ): IPluginModuleReplaceDirectory[] {
   const root = path.resolve(moduleRoot);
   let text: string;
@@ -72,7 +76,12 @@ export function pluginModuleReplaceDirectories(
       root,
     );
   const parsed = (
-    reader ?? SourcePluginWorkspace.createGoModReader(go, root, env, readers)
+    reader ??
+    // WARNING (#1739): the first reader registered for a Go binary serves the
+    // whole load, so it must carry the load's record store, or every later
+    // reader request of the load gets a store-less one and the go.mod syntax
+    // records are never read or written.
+    SourcePluginWorkspace.createGoModReader(go, root, env, readers, identities)
   ).read(root);
   // Parsed syntax may be shared; physical containment is current native state
   // and must be recomputed even when these manifest bytes are unchanged.

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/TtscCommonOptions.ts

@@ -86,8 +86,8 @@ export interface TtscCommonOptions {
   }[];
 
   /**
-   * Retained native compiler argument base when project selection redirects
-   * the Program to a different root. Absent retains the selected project root.
+   * Retained native compiler argument base when project selection redirects the
+   * Program to a different root. Absent retains the selected project root.
    * Response frames and relative native options use this base; plugin/rule
    * context and config-relative paths retain their separate project authority.
    */

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>);

package/internal/graphsymbols/position_helpers_follow_ecma_line_terminators_test.go

@@ -1,78 +0,0 @@
-package graphsymbols
-
-import (
-  "testing"
-  "unicode/utf8"
-
-  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
-  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
-)
-
-// TestPositionHelpersFollowECMALineTerminators verifies graph-backed LSP
-// positions use the compiler's LF, CRLF, CR, LS, and PS line boundaries.
-//
-// An offset-to-position helper that counted only LF while its inverse counted
-// CR too would map an editor cursor to a graph offset that returns on a
-// different line. Literal starts and ends establish three authored logical
-// lines; the test walks their UTF-8 boundaries, including an emoji, and requires
-// a round trip. Columns are not compared to literal UTF-16 counts, so symmetric
-// column mistakes can pass. No editor/server request is exercised.
-//
-// 1. Build three lines with each ECMAScript terminator.
-// 2. Enumerate every valid cursor boundary before each terminator.
-// 3. Convert each offset to UTF-16 LSP position and back to the same offset.
-//
-// @evidence contracts/testing.md#behavioral-verification Verifies graph-backed LSP positions use the compiler's LF, CRLF, CR, LS, and PS line boundaries.
-// @evidence contracts/testing.md#independent-expectations Each case embeds one ECMAScript terminator (LF, CRLF, CR, LS or PS) in a three-line literal, so the expected line count (three) and the line of every offset follow from the language's line-terminator definition. Columns are checked only by an offset -> position -> offset round trip over every UTF-8 rune boundary (including the two-unit emoji), not against literal UTF-16 column numbers, so a column error made symmetrically by both helpers would not be detected.
-// @evidence contracts/testing.md#distinguishing-cases Build three lines with each ECMAScript terminator; Enumerate every valid cursor boundary before each terminator; Convert each offset to UTF-16 LSP position and back to the same offset; the five terminator subtests differ only in the terminator, and a position on the line index just past the last line must not resolve (negative case). No empty-text or out-of-range-column input is exercised here.
-// @evidence contracts/testing.md#execution-ownership Directly calls the maintained line and position helpers on authored UTF-8 strings in this process. Literal byte boundaries establish enumeration; round-trip column expectations share the two converters and are not a separate UTF-16 oracle. It creates no native fixture, loads no Program, installs no consumer, and starts no product process or editor/server connection.
-func TestPositionHelpersFollowECMALineTerminators(t *testing.T) {
-  cases := []struct {
-    name       string
-    terminator string
-  }{
-    {name: "LF", terminator: "\n"},
-    {name: "CRLF", terminator: "\r\n"},
-    {name: "CR", terminator: "\r"},
-    {name: "LS", terminator: "\u2028"},
-    {name: "PS", terminator: "\u2029"},
-  }
-  for _, tc := range cases {
-    t.Run(tc.name, func(t *testing.T) {
-      text := "alpha😀" + tc.terminator + "beta" + tc.terminator + "gamma"
-      starts := graph.ECMALineStarts(text)
-      if len(starts) != 3 {
-        t.Fatalf("line starts = %v, want three lines", starts)
-      }
-      expectedStarts := []int{0, 9 + len(tc.terminator), 13 + 2*len(tc.terminator)}
-      expectedEnds := []int{9, 13 + len(tc.terminator), len(text)}
-      for line, start := range starts {
-        end := graph.LineEnd(text, starts, line)
-        if start != expectedStarts[line] || end != expectedEnds[line] {
-          t.Fatalf("line %d boundaries = (%d, %d), want (%d, %d)", line, start, end, expectedStarts[line], expectedEnds[line])
-        }
-        for offset := start; ; {
-          position := offsetToPosition(text, offset)
-          if position.Line != line {
-            t.Fatalf("offset %d position line = %d, want %d", offset, position.Line, line)
-          }
-          restored, ok := lspPositionToOffset(text, position)
-          if !ok || restored != offset {
-            t.Fatalf("offset %d -> %+v -> (%d, %t), want itself", offset, position, restored, ok)
-          }
-          if offset == end {
-            break
-          }
-          _, size := utf8.DecodeRuneInString(text[offset:])
-          if size == 0 {
-            t.Fatal("unexpected zero-width UTF-8 rune")
-          }
-          offset += size
-        }
-      }
-      if _, ok := lspPositionToOffset(text, lspserver.LSPPosition{Line: len(starts), Character: 0}); ok {
-        t.Fatal("position on a nonexistent source line must not resolve")
-      }
-    })
-  }
-}