@ttsc/unplugin 0.31.5 → 0.32.1

package/src/core/transform/TtscPrecompilation.ts

@@ -0,0 +1,103 @@
+import path from "node:path";
+
+import { isTransformTarget } from "../isTransformTarget";
+import type { ResolvedTtscUnpluginOptions } from "../options/ResolvedTtscUnpluginOptions";
+import type { TtscTransformCache } from "./cache/TtscTransformCache";
+import { transformCacheEpoch } from "./cache/transformCacheEpoch";
+import { transformFilesystem } from "./cache/transformFilesystem";
+import { pluginsAreDisabled } from "./utils/pluginsAreDisabled";
+
+/**
+ * Schedule explicitly selected source entries before the host reaches their
+ * imports. Compilation and proof stay with the ordinary transform core.
+ *
+ * A host often discovers its next workspace project only after the preceding
+ * project's transform finishes (#1764). Starting known entries together avoids
+ * that dependency on host traversal order. Walking unrelated projects would
+ * execute plugins the user never selected, so this owner uses only the supplied
+ * entries. Preparation leaves module delivery and host registration to the
+ * actual request.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit entries authorize scheduling; the supplied core capture retains project selection, configuration identity and all generation proofs. The context contains the current working directory, options, aliases and delivery epoch, not new cache authority.
+ * @evidence contracts/common.md#clear-and-simple-design One scheduler owns per-cache startup deduplication and reset; the transform core owns compiled generations and their disposal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No directory-wide discovery, plugin substitution or skipped proof is introduced; preparation never impersonates a host module delivery.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains host traversal order, explicit effectful selection and separation from delivery; members state context lifetime and failure ownership.
+ * @evidence contracts/portability.md#os-neutral-implementation Entries resolve through native path semantics from the current cwd and read through the cache's filesystem boundary; source eligibility uses the adapter's existing shared predicate.
+ * @evidence contracts/performance.md#efficient-algorithms Each new context serializes cwd, options and aliases, then resolves and deduplicates E entries and reads their source bytes once. Capture starts without waiting for other entries; native capture and proof retain their own costs. Repeated requests serialize the context but do not reread the entries.
+ * @evidence contracts/performance.md#reuse-equivalent-work One latest context per cache and epoch starts each entry once; ordinary project keys deduplicate entries in the same project. Context equality controls scheduling only, and retained results still need normal admission.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources A WeakMap retains one context string per live cache. Startup rejection handlers consume each detached promise; running captures and native resources remain cache-owned and withdrawal disposes their fulfilled generations. No cancellation deadline or entry-count cap is added.
+ */
+export namespace TtscPrecompilation {
+  const contexts = new WeakMap<TtscTransformCache, string>();
+
+  /**
+   * Start every eligible explicit entry without waiting for its siblings.
+   * Failed speculative preparation is reported when its module is requested, so
+   * an unrelated delivered project's load can proceed.
+   *
+   * @evidence contracts/common.md#principled-implementation The context is installed before captures start, so recursive and concurrent deliveries cannot restart the same batch; only supported source entries reach normal core capture.
+   * @evidence contracts/common.md#clear-and-simple-design One synchronous loop separates startup ownership from asynchronous capture settlement.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed entry reads are not fabricated as empty source, and rejected captures do not become successful output. Actual delivery remains the error boundary.
+   * @evidence contracts/common.md#meaningful-documentation Prose states parallel startup and deferred error reporting; callback and context ownership remain explicit.
+   * @evidence contracts/portability.md#os-neutral-implementation Native absolute entry paths are passed as exact paths to capture and source reads use the same cache-owned filesystem as generation validation.
+   * @evidence contracts/performance.md#efficient-algorithms Context serialization precedes one E-entry deduplicating loop and actual source-byte reads; captures overlap their asynchronous work rather than being awaited sequentially.
+   * @evidence contracts/performance.md#reuse-equivalent-work Identical latest cwd, options, aliases and epoch skip scheduling; project Promise identity and normal input proof decide compile reuse, independently of this scheduling record.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Context state follows its weak cache key. Every started capture receives a rejection handler immediately; its own core/cache owners release native resources, including withdrawal during capture.
+   */
+  export function start(
+    cache: TtscTransformCache,
+    options: ResolvedTtscUnpluginOptions,
+    aliasPaths: Record<string, string[]> | undefined,
+    capture: (file: string, source: string) => Promise<unknown>,
+  ): void {
+    if (
+      options.precompile?.length === 0 ||
+      options.precompile === undefined ||
+      pluginsAreDisabled(options.plugins)
+    )
+      return;
+    // Entry, project and projectRoot paths all use cwd. The same relative
+    // options under another directory select different work, even if the
+    // host retains its cache; capture coordinates must belong to this call.
+    const cwd = process.cwd();
+    const context = JSON.stringify([
+      cwd,
+      options,
+      aliasPaths,
+      transformCacheEpoch(cache),
+    ]);
+    if (contexts.get(cache) === context) return;
+    contexts.set(cache, context);
+    const entries = new Set<string>();
+    const filesystem = transformFilesystem(cache);
+    for (const entry of options.precompile) {
+      if (!isTransformTarget(entry)) continue;
+      const file = path.resolve(cwd, entry);
+      if (entries.has(file)) continue;
+      entries.add(file);
+      try {
+        const source = filesystem.readFile(file).toString("utf8");
+        void capture(file, source).catch(() => undefined);
+      } catch {
+        // A missing entry must not poison another project's load. Its actual
+        // host delivery still owns the native read error and recovery.
+      }
+    }
+  }
+
+  /**
+   * End startup ownership when the cache withdraws its generations.
+   *
+   * @evidence contracts/common.md#principled-implementation Withdrawal removes scheduling state with generation ownership so a later lifecycle can prepare the same entries again.
+   * @evidence contracts/common.md#clear-and-simple-design One weak-key deletion shares the cache's existing reset boundary.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Clearing scheduling permission does not admit or cancel any compiled result.
+   * @evidence contracts/common.md#meaningful-documentation The headline identifies the same generation withdrawal boundary used by callers.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation WeakMap deletion performs no native operation.
+   * @evidenceExclude contracts/performance.md#efficient-algorithms One identity deletion chooses no traversal or processing strategy.
+   * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation withdraws the previous scheduling record rather than reusing work.
+   * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Deletion releases the single scheduling record; native resources remain owned by generation withdrawal.
+   */
+  export function clear(cache: TtscTransformCache): void {
+    contexts.delete(cache);
+  }
+}

package/src/core/transform/cache/selectCachedGenerationAction.ts

@@ -43,6 +43,8 @@ export function selectCachedGenerationAction(props: {
   generation: Promise<TtscCachedProjectTransform>;
   key: string;
   source: string;
+  /** False only for speculative source reads before an actual module delivery. */
+  reportDivergence?: boolean;
   proof?: TtscGenerationProof.Transaction;
 }): "serve" | "retry" | "capture" {
   if (
@@ -57,6 +59,7 @@ export function selectCachedGenerationAction(props: {
       props.source,
       props.epoch,
       props.proof,
+      props.reportDivergence,
     )
   ) {
     return "serve";

package/src/core/transform/cache/withdrawTtscTransformGenerations.ts

@@ -1,3 +1,4 @@
+import { TtscPrecompilation } from "../TtscPrecompilation";
 import type { TtscTransformCache } from "./TtscTransformCache";
 import { disposeCachedTransform } from "./disposeCachedTransform";
 
@@ -35,6 +36,7 @@ export function withdrawTtscTransformGenerations(
   cache: TtscTransformCache,
 ): void {
   const generations = [...cache.values()];
+  TtscPrecompilation.clear(cache);
   cache.clear();
   for (const generation of generations) {
     void generation.then(disposeCachedTransform, () => undefined);

package/src/core/transform/envelope/generationCaseSensitivity.ts

@@ -0,0 +1,46 @@
+import type { ITtscCompilerTransformation } from "ttsc";
+
+import { resultFilesystem } from "../cache/resultFilesystem";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+import { envelopeDerivation } from "./envelopeDerivation";
+
+/**
+ * The directory case answers of one generation's identity context
+ * (`envelopeDerivation`), for another identity context built while that
+ * generation is captured over the same filesystem view.
+ *
+ * Capturing a generation builds several identity contexts: the input selections
+ * and the trackers' baselines. Each asked every directory's case policy again,
+ * which on Windows costs an `fsutil` process for a directory whose names cannot
+ * settle it (samchon/ttsc#1742). They now ask the generation's own context,
+ * which memoizes each directory once for the generation. A view other than the
+ * one registered for the result observes for itself, and a tracker's re-check
+ * after an event still builds a context of its own.
+ *
+ * @evidence contracts/common.md#principled-implementation Sharing is admitted only for the filesystem view registered for the result, the view the generation context observes; any other view keeps its own observations.
+ * @evidence contracts/common.md#clear-and-simple-design One selector returns the generation's case operation, or the view's own for another view, and callers pass it to the existing context factory.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No answer is cached beyond the generation context that observed it, and a tracker's event re-check is not routed through it.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the repeated probes, the view condition and the re-check exception.
+ * @evidence contracts/portability.md#os-neutral-implementation The generation context observes case policy through the registered view's own probes; no platform assumption is introduced.
+ * @evidence contracts/performance.md#efficient-algorithms One registry lookup and one derivation lookup; the returned operation delegates to the generation context's memo.
+ * @evidence contracts/performance.md#reuse-equivalent-work Every context capturing one generation shares the generation's answer for each directory.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The answers belong to the generation context, which the generation already owns; this selector retains nothing.
+ */
+export function generationCaseSensitivity(props: {
+  /** The view the caller's context observes through. */
+  filesystem: TtscTransformFilesystemOperations;
+
+  /** Native project directory of the generation. */
+  projectRoot: string;
+
+  /** The generation's compiler result. */
+  result: ITtscCompilerTransformation;
+}): TtscTransformFilesystemOperations["caseSensitive"] {
+  if (resultFilesystem(props.result) !== props.filesystem)
+    return props.filesystem.caseSensitive;
+  const context = envelopeDerivation({
+    projectRoot: props.projectRoot,
+    result: props.result,
+  }).identityContext;
+  return (directory) => context.caseSensitive(directory);
+}

package/src/core/transform/envelope/selectExternalInputPaths.ts

@@ -10,6 +10,7 @@ import { isProjectWalkPath } from "../project/isProjectWalkPath";
 import { isTransformScratchInput } from "../tsconfig/isTransformScratchInput";
 import { envelopeDerivation } from "./envelopeDerivation";
 import { envelopeGraphIndexes } from "./envelopeGraphIndexes";
+import { generationCaseSensitivity } from "./generationCaseSensitivity";
 
 /**
  * Derive the absolute out-of-walk input set of a whole project transform: the
@@ -63,7 +64,10 @@ export function selectExternalInputPaths(props: {
   }
   const members: string[] = [];
   const filesystem = props.filesystem ?? DEFAULT_FILESYSTEM_OPERATIONS;
-  const identities = createHostPathIdentityContext(filesystem);
+  const identities = createHostPathIdentityContext(
+    filesystem,
+    generationCaseSensitivity({ ...props, filesystem }),
+  );
   const resolutionCandidates = new Set<string>();
   const graph = props.result.graph;
   const graphState = envelopeDerivation({

package/src/core/transform/envelope/selectNotifiableAbsentInputs.ts

@@ -8,6 +8,7 @@ import { relativeToProject } from "../filesystem/relativeToProject";
 import { isTransformScratchInput } from "../tsconfig/isTransformScratchInput";
 import { envelopeDerivation } from "./envelopeDerivation";
 import { envelopeGraphIndexes } from "./envelopeGraphIndexes";
+import { generationCaseSensitivity } from "./generationCaseSensitivity";
 
 /**
  * The generation's resolution candidates recorded as not files, so its
@@ -72,7 +73,10 @@ export function selectNotifiableAbsentInputs(props: {
   if (graph === undefined) {
     return empty;
   }
-  const identities = createHostPathIdentityContext(props.filesystem);
+  const identities = createHostPathIdentityContext(
+    props.filesystem,
+    generationCaseSensitivity(props),
+  );
   const graphState = envelopeDerivation({
     projectRoot: props.projectRoot,
     result: props.result,

package/src/core/transform/filesystem/createHostPathIdentityContext.ts

@@ -29,6 +29,8 @@ import type { TtscTransformFilesystemOperations } from "./TtscTransformFilesyste
  *   The returned context memoizes path, realpath and case observations for
  *   repeated questions within one filesystem transaction. Callers must create
  *   a new context when later filesystem changes can invalidate those observations.
+ *   A caller capturing one generation can hand in that generation's case answers,
+ *   so its contexts do not each ask the filesystem again (samchon/ttsc#1742).
  * @evidence contracts/performance.md#bound-retention-and-release-resources
  *   Ownership of the context and its maps transfers to the caller. Retained
  *   entries grow with queried paths and ancestors and have no internal eviction;
@@ -36,9 +38,15 @@ import type { TtscTransformFilesystemOperations } from "./TtscTransformFilesyste
  */
 export function createHostPathIdentityContext(
   filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+  /**
+   * Case answers this context shares with the others of its unit of work,
+   * observed through the same `filesystem`; omitted, the context asks for
+   * itself.
+   */
+  caseSensitive: TtscTransformFilesystemOperations["caseSensitive"] = filesystem.caseSensitive,
 ): FilesystemPathIdentityContext {
   return createFilesystemPathIdentityContext({
-    caseSensitive: filesystem.caseSensitive,
+    caseSensitive,
     lstat: filesystem.lstat,
     platform: filesystem.platform,
     readdir: (directory) =>

package/src/core/transform/generation/captureTransformGeneration.ts

@@ -12,6 +12,7 @@ import { TRANSFORM_RESULT_MEMBERSHIP } from "../cache/TRANSFORM_RESULT_MEMBERSHI
 import type { TtscCachedProjectTransform } from "../cache/TtscCachedProjectTransform";
 import { refreshFilesystemClockReference } from "../clock/refreshFilesystemClockReference";
 import { reportDivergentDelivery } from "../diagnostics/reportDivergentDelivery";
+import { generationCaseSensitivity } from "../envelope/generationCaseSensitivity";
 import { selectDeclaredProjectInputKeys } from "../envelope/selectDeclaredProjectInputKeys";
 import { selectExternalInputPaths } from "../envelope/selectExternalInputPaths";
 import { selectNotifiableAbsentInputs } from "../envelope/selectNotifiableAbsentInputs";
@@ -126,6 +127,9 @@ export async function captureTransformGeneration(props: {
   /** Host-delivered text compared with the compiler's on-disk source baseline. */
   currentSource: string;
 
+  /** False for preparation, whose source read is not a host module delivery. */
+  reportDivergence?: boolean;
+
   /** Optional delivery epoch to which this captured observation belongs. */
   deliveryEpoch?: number;
 
@@ -457,6 +461,13 @@ export async function captureTransformGeneration(props: {
       clockReferenceDirectory ?? scratchDirectory,
       props.filesystem,
     );
+    // Every context capturing this generation below shares the generation's
+    // directory case answers, rather than each asking again (samchon/ttsc#1742).
+    const generationCase = generationCaseSensitivity({
+      filesystem: props.filesystem,
+      projectRoot,
+      result,
+    });
     const persistentHostInputs = selectPersistentHostInputs({
       filesystem: props.filesystem,
       projectRoot,
@@ -518,6 +529,7 @@ export async function captureTransformGeneration(props: {
               projectRoot,
               result,
             }),
+            generationCase,
           )
         : undefined;
     compileTrace?.("bridge-tracker-lifecycle", {
@@ -566,6 +578,7 @@ export async function captureTransformGeneration(props: {
                 .filter((input) => !absentCandidates.has(input))
                 .map((input) => [path.resolve(input), "presence" as const]),
             ),
+            generationCase,
           )
         : undefined;
     compileTrace?.("bridge-tracker-lifecycle", {
@@ -628,7 +641,7 @@ export async function captureTransformGeneration(props: {
     // this generation. A delivered text that differs, because a plugin ordered
     // before ttsc rewrote the module or the file changed after the host read
     // it, must not replace them: every sibling delivery compares the disk and
-    // would recompile the project (samchon/ttsc#1394). It is reported once
+    // would recompile the project (samchon/ttsc#1394). An actual delivery is reported once
     // instead, and the file's own compile is served.
     const currentFileKey = toProjectKey(
       projectRoot,
@@ -681,7 +694,14 @@ export async function captureTransformGeneration(props: {
       props.currentFile,
       diskHash ?? deliveredHash,
     );
-    if (diskHash !== undefined && diskHash !== deliveredHash) {
+    // Preparation reads native source only to seed the ordinary capture. A
+    // later edit is handled by generation proof, not a warning about a host
+    // rewrite: no host delivered that speculative module (#1764).
+    if (
+      props.reportDivergence !== false &&
+      diskHash !== undefined &&
+      diskHash !== deliveredHash
+    ) {
       reportDivergentDelivery(cached, props.currentFile);
     }
     // An adopted compile was certified by its publisher, and is matched below

package/src/core/transform/generation/selectPersistentHostInputs.ts

@@ -1,5 +1,6 @@
 import type { ITtscCompilerTransformation } from "ttsc";
 
+import { generationCaseSensitivity } from "../envelope/generationCaseSensitivity";
 import { selectListedFiles } from "../envelope/selectListedFiles";
 import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
 import { createHostPathIdentityContext } from "../filesystem/createHostPathIdentityContext";
@@ -43,7 +44,10 @@ export function selectPersistentHostInputs(props: {
     props.temporaryTsconfig === undefined
   )
     return inputs;
-  const identities = createHostPathIdentityContext(props.filesystem);
+  const identities = createHostPathIdentityContext(
+    props.filesystem,
+    generationCaseSensitivity(props),
+  );
   const temporary =
     props.temporaryTsconfig === undefined
       ? undefined

package/src/core/transform/generation/transformProject.ts

@@ -97,6 +97,9 @@ export async function transformProject(props: {
   /** Delivered module text compared against the compiler's disk observation. */
   currentSource: string;
 
+  /** False for preparation, whose source read is not a host module delivery. */
+  reportDivergence?: boolean;
+
   /**
    * Delivery pass this compile was started for; see
    * {@link TtscCachedProjectTransform.deliveryEpoch}.

package/src/core/transform/inputs/nativeInputPredicateState.ts

@@ -69,9 +69,7 @@ export function nativeInputPredicateState(
     } else if (kind === "optional-file") {
       try {
         digest = filesystem.stat(file).isFile()
-          ? hash(
-              Buffer.concat([Buffer.from("file\0"), readBytes()]),
-            )
+          ? hash(Buffer.concat([Buffer.from("file\0"), readBytes()]))
           : hash("missing\0");
       } catch (error) {
         if (!missing(error)) return undefined;

package/src/core/transform/tracker/createHostInputMutationTracker.ts

@@ -114,12 +114,21 @@ export async function createHostInputMutationTracker(
    * filesystem.
    */
   scopes?: ReadonlyMap<string, TtscTrackedInputScope>,
+  /**
+   * The case answers of the generation this tracker watches, for its baseline
+   * (`generationCaseSensitivity`); omitted, the baseline observes for itself.
+   * An event's re-check always observes afresh.
+   */
+  caseSensitive?: TtscTransformFilesystemOperations["caseSensitive"],
 ): Promise<TtscProjectMutationTracker> {
   const paths =
     (filesystem.platform ?? process.platform) === "win32"
       ? path.win32
       : path.posix;
-  const identities = createHostPathIdentityContext(filesystem);
+  const identities = createHostPathIdentityContext(
+    filesystem,
+    caseSensitive ?? filesystem.caseSensitive,
+  );
   // The project root in both of its spellings: an input the compiler reported
   // physically is the project's as much as one spelled as the project was
   // named, and the root's observer is opened once, under the name.

package/src/core/transform/tracker/createProjectMutationTracker.ts

@@ -38,10 +38,12 @@ import { watchLocationIdentity } from "./watchLocationIdentity";
  * directory excluded in both lexical and native spellings. Unknown, missing and
  * linked ancestry remains conservative. Membership rejection withdraws
  * notification authority except below such a proven excluded directory, so a
- * recursive backend's writes to a cache or output tree cost no proof. Named
- * events also compare current native identity and case policy with the retained
- * identity transaction. Retargeting withdraws notification authority without
- * changing the meaning of earlier recorded event spellings.
+ * recursive backend's writes to a cache or output tree cost no proof, nor does
+ * an edit to an existing unlinked file whose every name the program cannot
+ * admit (samchon/ttsc#1737). Named events also compare current native identity
+ * and case policy with the retained identity transaction. Retargeting withdraws
+ * notification authority without changing the meaning of earlier recorded event
+ * spellings.
  *
  * @evidence contracts/common.md#principled-implementation
  *   The project walk and membership policy own structural relevance; content
@@ -193,6 +195,26 @@ export async function createProjectMutationTracker(
     }
     return excluded;
   };
+  // Whether an event names an existing file no spelling can make a program
+  // member: a regular file with no second hard link, whose own and physical
+  // names are both names the program cannot admit. A directory alias can move
+  // a file into the program but cannot rename it, and a removed name, a link
+  // or a directory stays conservative.
+  const existingNonProgramFile = (changed: string): boolean => {
+    try {
+      const stats = filesystem.lstat(changed);
+      if (!stats.isFile() || stats.nlink > 1n) return false;
+      return (
+        !isPossibleProgramFileName(paths.basename(changed), policy) &&
+        !isPossibleProgramFileName(
+          paths.basename(filesystem.realpath(changed)),
+          policy,
+        )
+      );
+    } catch {
+      return false;
+    }
+  };
   const reportsMembership = (location: string, filename: string): boolean => {
     const changed = paths.join(location, filename);
     const current = createHostPathIdentityContext(filesystem);
@@ -221,8 +243,14 @@ export async function createProjectMutationTracker(
     // except below a directory the walk provably excludes. A recursive backend
     // (macOS, Windows) hears every write under the root, a cache or an output
     // directory among them, and withdrawing authority for each sent every later
-    // delivery to the whole-snapshot proof.
-    if (!membership && !excludedFromWalk(changed, true))
+    // delivery to the whole-snapshot proof. An existing file whose every name
+    // the program cannot admit is no member either, a stylesheet or an asset
+    // edited in a source directory among them, on every backend.
+    if (
+      !membership &&
+      !excludedFromWalk(changed, true) &&
+      !existingNonProgramFile(changed)
+    )
       tracker.unverified = true;
     return membership;
   };