ttsc 0.30.4 → 0.31.0

package/lib/TtscCompiler.d.ts

@@ -5,10 +5,12 @@ import type { ITtscCompilerTransformation } from "./structures/ITtscCompilerTran
  * Programmatic compiler host for the `ttsc` TypeScript-Go pipeline.
  *
  * `TtscCompiler` is the root JavaScript API exported by the `ttsc` package. It
- * represents one resolved project context: a working directory, an optional
- * project config path, an optional native toolchain override, an environment, a
- * cache root, and a plugin list. Those values are captured by the constructor
- * and are intentionally not replaceable per method call.
+ * owns one selection policy: working-directory and project-config options,
+ * native toolchain and environment overrides, a cache option and a plugin list.
+ * Supplied options and plugin JSON conversion are captured by the constructor
+ * and cannot be replaced per method call. Omitted defaults and relative path
+ * resolution still depend on the invocation's process state, and discovery
+ * observes the current filesystem.
  *
  * The class exposes only the operations that make sense for an embedded
  * compiler host:
@@ -20,6 +22,22 @@ import type { ITtscCompilerTransformation } from "./structures/ITtscCompilerTran
  *   structured result instead of terminal text.
  * - {@link TtscCompiler.transform}: transform the configured project and return an
  *   embed-style transformation result.
+ * - {@link TtscCompiler.transformAsync}: the same transform on a worker thread,
+ *   for hosts that keep serving other work meanwhile.
+ *
+ * Compile/transform failures use their structured envelopes; preparation and
+ * cleanup instead return their path lists or throw. Worker execution moves
+ * blocking transform work off-thread, while caller-side context setup, transfer
+ * and result adaptation still consume calling-thread work.
+ *
+ * @evidence contracts/common.md#principled-implementation A constructor-owned project context fixes selectors and JSON plugin payloads while methods preserve compiler success/failure/exception distinctions; real source/native owners supply compilation rather than the class inferring validity from partial output.
+ * @evidence contracts/common.md#clear-and-simple-design The public methods represent preparation, cleanup and compilation lifecycles; private helpers own context views, path bases and result adaptation, keeping selection policy stable across calls.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No caller or fixture is special-cased and no foreign compiler behavior is patched; compile/transform adapt native/plugin failures into results while prepare/clean propagate throws, preserving each operation's actual error contract.
+ * @evidence contracts/common.md#meaningful-documentation Native class and method paragraphs describe project binding, captured JSON conversion, cache ownership and structured outcomes; documented members use visible separation following the documentation skill.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path APIs resolve explicit cwd/config/cache anchors, shared physical identity validates cleanup, and native environment-name lookup protects caller GOCACHE; unknown native case policy does not authorize merging missing case variants.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated compiler/loading/cleanup owners pay their native path, source, metadata and output work; context copying/transfer follows configured payload bytes. Result envelopes retain existing output maps rather than rescanning their files, while severity checks and fallback diagnostic formatting process diagnostic/stream data. Offloading does not remove caller setup, transfer or adaptation costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work The instance reuses its immutable constructor plugin serialization and downstream input-validated binary/descriptor caches; each compile still runs under current project inputs rather than reusing an unproved prior compilation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The instance retains constructor context bytes for its lifetime; captures/temporary outputs and workers keep their respective owners' release policies and limitations. Clean validates the complete candidate plan before deletion attempts, which can fail and leave partial reclamation rather than a guaranteed storage bound.
  */
 export declare class TtscCompiler {
     private readonly context;
@@ -28,40 +46,75 @@ export declare class TtscCompiler {
      *
      * The context is defensively copied: mutations to the original object after
      * construction do not affect this instance. Omit `context` (or pass `{}`) to
-     * inherit all defaults from the running process.
+     * inherit defaults from the running process when operations resolve them.
+     *
+     * Plugin JSON conversion, including custom `toJSON`, is captured once here.
+     * Later operations preserve the original host selectors and use that captured
+     * payload. Non-JSON-serializable plugin input fails during construction.
      */
     constructor(context?: ITtscCompilerContext);
     /**
      * Build every configured source plugin into the instance cache.
      *
      * This method loads the project plugin descriptors, resolves their
-     * {@link ITtscPlugin.source} paths, and compiles those Go command packages
-     * into the ttsc cache. It is useful when a host application wants to pay the
-     * lazy build cost before the first compile call.
+     * {@link ITtscPlugin.source} paths, and builds executable plugins or linked
+     * hosts for those Go source packages in the ttsc cache. It is useful when a
+     * host application wants to pay the lazy build cost before the first compile
+     * call.
      *
      * `prepare()` is not a project check. It does not create a TypeScript-Go
      * Program, does not run diagnostics, and does not emit output files.
      *
      * @returns Compiled native plugin binary paths.
+     * @evidence contracts/common.md#principled-implementation Loading descriptors under resolved project anchors and building declared source plugins returns the actual resulting native binaries; preparation does not claim project diagnostic validity.
+     * @evidence contracts/common.md#clear-and-simple-design One operation creates a fresh context view and delegates descriptor loading/building to their owners, returning only the binary paths relevant to preparation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Plugin declarations are resolved through the actual loader and failures propagate; no expected binary path or fabricated successful build substitutes for compilation.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish lazy source preparation from a project check and describe its returned paths, with prose and tags separated.
+     * @evidence contracts/portability.md#os-neutral-implementation Native cwd/config/cache bases are forwarded explicitly to the loader, which owns executable and path differences; this method adds no shell spelling or OS-specific installation path.
+     * @evidence contracts/performance.md#efficient-algorithms Loading/building includes the loader's package resolution, descriptor evaluation, source/toolchain observations and admitted native builds; these costs follow their bytes/populations rather than one logical call. The returned N native paths are projected once, without a separate project check merely to form that list.
+     * @evidence contracts/performance.md#reuse-equivalent-work Constructor JSON conversion and input-validated plugin build/descriptor caches are shared across operations; a changed source/toolchain input requires the owner's new build rather than assuming an existing path is valid.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources A fresh operation context transfers to loading/building and its result paths transfer to the caller; cache artifacts remain with the cache owner until clean, with no new persistent preparation registry.
      */
     prepare(): string[];
     /**
      * Remove compiled cache artifacts for this compiler instance.
      *
-     * Removes an explicit `cacheDir` wholesale. Otherwise removes the plugin
-     * binary subdirectory, a safely identified ttsc-owned Go build cache
-     * (including an external `TTSC_GO_CACHE_DIR`), and the two legacy
-     * project-local caches. A user-provided `GOCACHE` is never removed. Every
-     * resolved deletion target is validated before the first removal. The cache
-     * location comes from this instance's `cacheDir` and environment
-     * (`TTSC_CACHE_DIR` / `TTSC_GO_CACHE_DIR`), defaulting to
+     * Selects an explicit `cacheDir` as a whole. Otherwise removes the plugin
+     * binary subdirectory, the descriptor, capability, and orphan-lowering
+     * caches, the runtime directories of `ttsx` and `ttsc/register` runs whose
+     * owners are provably gone (a run that may still be in progress keeps its
+     * own), a safely identified ttsc-owned Go build cache (including an external
+     * `TTSC_GO_CACHE_DIR`), and the two legacy project-local caches. A
+     * user-provided `GOCACHE` is protected in both modes: overlapping or
+     * uncertain deletion candidates are preserved. Every resolved deletion target
+     * is validated before the first removal. The cache location comes from this
+     * instance's `cacheDir` and environment (`TTSC_CACHE_DIR` /
+     * `TTSC_GO_CACHE_DIR`), defaulting to
      * `<workspaceRoot>/node_modules/.cache/ttsc`. Any resolved cache target that
      * equals or contains the project, or names a filesystem root, is rejected
      * before any directory is removed.
      *
+     * Default runtime selection uses the runtime-root lock and conservative owner
+     * records. An explicit whole-cache selector is not filtered by runtime owner
+     * liveness. Root discovery and metadata checks are sequential observations,
+     * not a namespace snapshot: selected roots/physical parents must remain
+     * stable while the operation uses its lock and deletion plan.
+     *
      * @returns Cache directories that were removed.
+     * @evidence contracts/common.md#principled-implementation Explicit and default ownership select different cache sets, and every candidate is validated before deletion; physical overlap preserves caller GOCACHE while roots and project-containing candidates fail closed.
+     * @evidence contracts/common.md#clear-and-simple-design This public operation selects the project and optional runtime lock; cleanResolved owns the complete candidate plan and the shared cleanup helper owns deletion safety across API and CLI paths.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Cache ownership follows declared selectors and observed physical identities, not fixture-specific directories. Default runtime selection preserves live/unknown ownership; an explicit whole-cache selector has its documented separate deletion meaning.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs specify explicit/default ownership, external caller cache preservation, runtime liveness and validation-before-deletion so callers can assess destructive effects.
+     * @evidence contracts/portability.md#os-neutral-implementation Native resolution and shared identity handle aliases and volume roots; canonical environment-name lookup reads caller GOCACHE on Windows, and unavailable case measurement does not assert case-variant identity.
+     * @evidence contracts/performance.md#efficient-algorithms Default runtime existence, candidate discovery and optional runtime planning can repeat delegated workspace/root observations; their ancestor/manifest/layout work is not constant projection. Complete-set identity/protection validation then precedes removal. Runtime owner scans, lock attempts and recursive deletion add their path/record/entry costs, without rebuilding plugin outputs to decide cleanup.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Cleanup and runtime liveness are mutable deletion effects; cached deletion plans cannot authorize a later filesystem generation.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The default runtime-plan branch holds its selected root's lock through resolution/deletion and delegates finally release, including the lock owner's unbounded peer-handle retirement limitation. Stable root discovery and namespace identity are required across sequential observations; the explicit whole-cache branch is not runtime-liveness filtered. Partial native rm failures are observable, not rolled back, and no storage ceiling is established.
      */
     clean(): string[];
+    /** Resolve the deletion set after the runtime directory lock is held. */
+    private cleanResolved;
     /**
      * Compile the configured project.
      *
@@ -74,18 +127,27 @@ export declare class TtscCompiler {
      *
      * The result uses an `embed-typescript`-style discriminated union: `success`
      * for clean compiles, `failure` for compiler diagnostics or plugin failures
-     * that reached the build pipeline, and `exception` for host failures that
-     * prevent any project check from running.
+     * that reached the build pipeline, and `exception` for host failures during
+     * preparation, execution, response decoding, output capture or cleanup.
      *
      * @returns Structured compilation result containing diagnostics or output.
+     * @evidence contracts/common.md#principled-implementation Native status and error diagnostics jointly determine success versus failure; unexpected host exceptions remain a separate envelope, and emitted files come from the actual compiler pipeline.
+     * @evidence contracts/common.md#clear-and-simple-design The public method supplies an owned context to the compiler and delegates outcome adaptation to runProject, avoiding a second compile-specific selection policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Captured output never substitutes for a successful status or absence of error diagnostics; real host exceptions are exposed rather than patched into expected results.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain in-memory output ownership, plugin temporary output and the three result states, with a separate acknowledgment block.
+     * @evidence contracts/portability.md#os-neutral-implementation Native compiler and plugin owners receive explicit context path/environment inputs; their supported spawning and temporary-output boundaries isolate platform representation rather than shell concatenation here.
+     * @evidence contracts/performance.md#efficient-algorithms One compile pipeline pays delegated source/native/output-capture costs. This adapter retains the existing output map, checks diagnostic severity and may format a process fallback diagnostic; context copies and diagnostic/stream text add their own costs, without a second project traversal just to form the envelope.
+     * @evidence contracts/performance.md#reuse-equivalent-work Immutable plugin serialization and downstream validated source/descriptor caches are reused, while project compilation is repeated because source and filesystem inputs can change between calls.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The synchronous pipeline owns child captures and temporary output cleanup; returned output bytes and diagnostics transfer to the caller, and this method retains no historical results.
      */
     compile(): ITtscCompilerResult;
     /**
      * Transform the configured project and return TypeScript text by file path.
      *
      * This is the source-to-source API for plugin authors. It must not return
-     * JavaScript emit, declaration files, or source maps; those artifacts belong
-     * to {@link TtscCompiler.compile}. A transform native source is expected to
+     * JavaScript emit or declaration files; those artifacts belong to
+     * {@link TtscCompiler.compile}. Optional source maps describe transformed
+     * TypeScript back to its input. A transform native source is expected to
      * write JSON shaped as `{ "typescript": { "src/file.ts": "..." } }` to
      * stdout. When no transform native source is configured, ttsc returns the
      * TypeScript files loaded by the TypeScript-Go Program together with normal
@@ -96,8 +158,42 @@ export declare class TtscCompiler {
      * errors return `exception`.
      *
      * @returns Transformation result containing TypeScript text or diagnostics.
+     * @evidence contracts/common.md#principled-implementation The transform owner returns source-language text and diagnostics, and outcome adaptation uses real status/error severity; host failures remain exceptions rather than absent transformed files.
+     * @evidence contracts/common.md#clear-and-simple-design The method supplies the same context policy as compile and delegates source transformation plus its distinct envelope to their owning helpers.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No emitted JavaScript is mislabeled as TypeScript and no consumer-specific output substitutes for native transformation; supported plugin/no-plugin lanes preserve actual diagnostics.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish source transformation from emit and describe plugin JSON, no-plugin behavior and the result states, visibly separate from tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path and environment inputs remain context data passed to the transform owner; this adapter adds no platform shell or filename convention.
+     * @evidence contracts/performance.md#efficient-algorithms One transform pays delegated source/native/capture costs. The envelope retains existing text/advisory maps and examines diagnostic severity or process fallback text; context/payload work remains with its actual owners, without a second compiler pass to shape the result.
+     * @evidence contracts/performance.md#reuse-equivalent-work Constructor plugin payload and validated downstream compilation artifacts are reusable; transformed source results are not retained across mutable project inputs without proof.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Synchronous native captures and temporary project outputs belong to the transform owner; returned source text belongs to the caller and the compiler instance stores no result history.
      */
     transform(): ITtscCompilerTransformation;
+    /**
+     * {@link TtscCompiler.transform} with blocking transform execution offloaded.
+     *
+     * Returns the same envelope with the same failure semantics, and the same
+     * descriptor-resilient launches. The whole transform, plugin loading
+     * included, runs on a worker thread. Calling-thread context copying, request
+     * transfer and result adaptation still perform work; this is not a guarantee
+     * that the event loop stays free throughout. The worker adopts `process.env`
+     * as it is at the call: a host that scopes process-global state such as
+     * `TEMP` around the call covers the whole transform, and nothing that changes
+     * the environment afterward reaches it. Idle workers are pooled so plugin
+     * loading's in-process caches stay warm, and never keep the process alive.
+     * The pool bounds idle workers by reported host parallelism; active requests
+     * have no implicit concurrency cap or deadline.
+     *
+     * @returns Transformation result containing TypeScript text or diagnostics.
+     * @evidence contracts/common.md#principled-implementation The worker executes the same synchronous transform under the invocation environment; separate selector/payload transfer preserves constructor JSON conversion, and success/failure/exception adaptation matches the synchronous API.
+     * @evidence contracts/common.md#clear-and-simple-design The method owns only asynchronous outcome adaptation; the worker owner handles exclusive checkout, environment adoption and terminal settlement while the snapshot owner handles transport-safe plugin meaning.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported workers offload transform execution instead of patching caller globals; caller-side setup/transfer/adaptation remains, and failures become the actual exception envelope.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain whole-transform offloading, invocation environment isolation, warm reuse and active/idle limits following the documentation skill.
+     * @evidence contracts/portability.md#os-neutral-implementation Worker-owned native paths and canonical environment-name merging preserve platform authority; JSON plugin payload travels separately from structured-cloned host selectors, avoiding unsupported function cloning.
+     * @evidence contracts/performance.md#efficient-algorithms One transform runs on one checked-out worker, with delegated source/native costs. Context copying, environment merge, encoding/structured transfer and response cloning follow payload bytes on their owning threads; result envelopes retain returned maps and inspect diagnostics rather than recompiling or rescanning all returned text.
+     * @evidence contracts/performance.md#reuse-equivalent-work Warm workers retain validated loader caches and the constructor's captured JSON is reused; every invocation still adopts its own environment and performs its own transform.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The worker owner releases exclusive listeners on terminal settlement, retires failed/excess workers and bounds idle retention by CPU budget; active requests and their data scale with concurrency and have no implicit deadline.
+     */
+    transformAsync(): Promise<ITtscCompilerTransformation>;
     private compilerContext;
     private resolveProjectExecution;
     private resolveCleanProjectRoot;
@@ -110,8 +206,9 @@ export declare class TtscCompiler {
      * documented {@link ITtscCompilerContext.env} contract that child compiler,
      * native-plugin, native-host, and isolated descriptor processes already
      * receive. Returned as a fresh object so callers never mutate the shared
-     * `process.env`; when no `context.env` was supplied this is a plain copy of
-     * `process.env`, so CLI / default behavior is unchanged.
+     * `process.env`. Native environment-name identity is applied while inherited
+     * and constructor layers remain distinct, so Windows aliases cannot defeat
+     * constructor authority and POSIX spellings stay independent.
      */
     private resolveEffectiveEnv;
 }