@ttsc/unplugin 0.28.2 → 0.28.4

package/lib/core/transform.d.mts

@@ -3,6 +3,7 @@ import type { ITtscCompilerTransformation } from "ttsc";
 import { type FilesystemPathIdentityContext, type FilesystemPathIdentityOperations } from "ttsc/path-identity";
 import type { TransformResult } from "unplugin";
 import type { ResolvedTtscUnpluginOptions } from "./options.mjs";
+import { type ITtscProjectMembershipPolicy } from "./tsconfigPaths.mjs";
 /**
  * The normalised transform result type that this module produces.
  *
@@ -11,26 +12,39 @@ import type { ResolvedTtscUnpluginOptions } from "./options.mjs";
  * `undefined`.
  */
 export type TtscTransformResult = Exclude<TransformResult, string | null | undefined>;
-/**
- * Normalised alias entry used when building the `paths` overlay for the
- * generated tsconfig. Derived from either a Vite array alias or a webpack/
- * Rspack object alias.
- */
-export interface TtscTransformAlias {
-    /** The alias key (module specifier prefix). */
-    find: string;
-    /** Absolute or cwd-relative path that the alias points to. */
-    replacement: string;
-}
-/** One directory's cheap project-membership identity at generation time. */
+/** One directory's project-membership identity at generation time. */
 interface TtscProjectDirectorySnapshot {
     /** Absolute directory spelling used by the project walk. */
     path: string;
-    /** Metadata signature that changes when its immediate membership changes. */
+    /**
+     * Whether this directory's subtree can hold a program input.
+     *
+     * A directory that cannot is still walked and still watched, so a source
+     * appearing in it later is noticed, but it takes no part in the membership
+     * comparison. That is what lets a bundler create its output directory and
+     * fill it without voiding a generation no compiler input touched, for any
+     * output directory rather than for fifteen names (samchon/ttsc#1307).
+     */
+    relevant: boolean;
+    /**
+     * Digest of the entries the walk itself considers: every immediate child the
+     * ignore list does not drop, with its kind.
+     *
+     * Deliberately not the directory's own metadata. A directory's stamp moves
+     * whenever _any_ entry is added or removed, including the ones the walk
+     * exists to ignore, so a bundler emitting into `dist/` — or merely creating
+     * that directory for the first time — moved the project root's stamp and
+     * voided a generation that no compiler input had touched. The ignore list
+     * only protects the generation if the membership proof honours it too.
+     */
     signature: string;
 }
 /** Generation-scoped directory watchers used to detect membership changes. */
 interface TtscProjectMutationTracker {
+    /** Absolute paths named by generation-time mutation events. */
+    changes: Set<string>;
+    /** Whether additional event paths were discarded after the witness bound. */
+    changesOmitted: boolean;
     close: () => void;
     /**
      * Absolute spellings whose creation, change or removal this tracker would
@@ -113,6 +127,28 @@ export interface TtscCachedProjectTransform {
      * transform.
      */
     inputHashes: Record<string, string>;
+    /**
+     * What the resolved configuration admitted into this generation's program.
+     *
+     * Recorded per generation rather than read per validation because it is a
+     * property of the configuration the compile ran under, so a later delivery
+     * must judge membership by the same rule the compile did. A tsconfig edit
+     * that changes the rule also changes a declared input, which replaces the
+     * generation and its policy together.
+     */
+    membershipPolicy: ITtscProjectMembershipPolicy;
+    /**
+     * Files already reported as absent from the program, and the pass that
+     * reporting belongs to, so the notice is one per file per pass rather than
+     * one per delivery.
+     */
+    missingOutputReported?: Set<string>;
+    missingOutputEpoch?: number;
+    /**
+     * The project config this generation compiled, so a module the program does
+     * not contain can be told which program that was.
+     */
+    tsconfig: string;
     /**
      * Metadata signature of each {@link inputHashes} entry whose hash was proven
      * against an unracing read of the file on disk, in a tick the observed
@@ -124,6 +160,13 @@ export interface TtscCachedProjectTransform {
      * disk bytes against the recorded hash, and may record a signature then.
      */
     inputSignatures?: Record<string, string>;
+    /**
+     * Raw source hash of every readable key in the transform output, keyed by
+     * filesystem identity. Unlike {@link inputHashes}, this includes source
+     * outputs outside the project walk without adding arbitrary output keys to
+     * the complete project snapshot.
+     */
+    sourceHashes?: Record<string, string>;
     /** Metadata snapshot of every directory in the stable generation walk. */
     projectDirectories?: TtscProjectDirectorySnapshot[];
     /** Live notification state for universal host-input changes. */
@@ -168,19 +211,50 @@ export interface TtscCachedProjectTransform {
     projectRoot: string;
     /** Raw compiler output returned by {@link TtscCompiler.transform}. */
     result: ITtscCompilerTransformation;
+    /**
+     * The delivery epoch this generation is currently settled against, or
+     * `undefined` for a generation no epoch has proven.
+     *
+     * Set when the generation is compiled, and again whenever a later epoch's
+     * first delivery proves the whole generation still matches the filesystem.
+     * While it equals the cache's current epoch, each module's first delivery is
+     * settled by the supplied source alone, exactly as it was when every pass
+     * compiled its own generation (samchon/ttsc#1300).
+     */
+    deliveryEpoch?: number;
+    /**
+     * Whether this generation's non-error diagnostics have been surfaced at all,
+     * and the epoch they were last surfaced in.
+     *
+     * The diagnostics describe one compile of one program, so they belong to the
+     * generation rather than to a delivery; a pass that reuses a retained
+     * generation still surfaces them once, because a build's warnings are part of
+     * what that build reports (samchon/ttsc#1304). The two fields are separate so
+     * a persistent host, whose epoch is `undefined`, still reports the first
+     * time.
+     */
+    diagnosticsReported?: boolean;
+    diagnosticsEpoch?: number;
     /**
      * Files already delivered from this generation, keyed by filesystem identity.
-     * Build-scoped caches use this to skip persistent validation only for a
-     * module's first delivery inside the current build.
+     * A cache with a delivery epoch uses this to skip persistent validation only
+     * for a module's first delivery inside the current pass; the set is cleared
+     * whenever a new epoch's gate re-proves the generation.
      */
     servedFiles?: Set<string>;
+    /**
+     * Absolute path of the adapter-owned scratch directory used for this
+     * generation. It is disposed after compilation, so none of its compiler,
+     * resolver, or plugin artifacts can be a persistent cache or watch input.
+     */
+    scratchDirectory?: string;
     /**
      * Absolute path of the generated temp-dir tsconfig this compile ran against,
      * when an alias/compiler-options overlay required one. The compiler reports
      * it in the envelope's `graph.configs` chain, but it is disposed right after
      * the compile, so registering it as a watch input would invalidate every
-     * bundler cache snapshot on the next build; watch derivation must skip
-     * exactly this path.
+     * bundler cache snapshot on the next build; watch derivation must skip this
+     * path. {@link scratchDirectory} owns the wider disposable-input bound.
      */
     temporaryTsconfig?: string;
 }
@@ -234,20 +308,31 @@ export declare function normalizeHostInputName(name: string, caseSensitive: bool
 /** Create an empty persistent transform cache with isolated filesystem reads. */
 export declare function createTtscTransformCache(operations?: Partial<TtscTransformFilesystemOperations>): TtscTransformCache;
 /**
- * Start a host build, clearing its prior generation and enabling constant-time
- * first delivery for modules compiled during this build.
+ * Open a new delivery pass, enabling constant-time first delivery for every
+ * module this pass asks for.
+ *
+ * This deliberately retains the cached generation. The pass boundary is a
+ * statement about _deliveries_ — each module is requested at most once inside
+ * it — not about whether the compiled program is still correct, which the
+ * generation's own recorded snapshot answers and which
+ * {@link matchesCachedSource} proves once at the pass's first delivery. Clearing
+ * here instead made a host whose `buildStart` repeats recompile the whole
+ * project on every rebuild even when no compiler input had changed
+ * (samchon/ttsc#1300). Use {@link resetTtscTransformCache} to actually discard a
+ * generation and its watchers.
  *
- * Hosts without a guaranteed build-start callback use persistent validation
- * unless they have another immutable lifecycle. Bun runtime setup, for example,
+ * Hosts without a guaranteed pass boundary use persistent validation unless
+ * they have another immutable lifecycle. Bun runtime setup, for example,
  * defines one process-scoped module-loading session.
  */
 export declare function beginTtscTransformBuild(cache: TtscTransformCache): void;
 /**
- * Clear a cache and return it to persistent validation mode.
+ * Discard every generation, dispose its watchers, and return the cache to
+ * persistent validation mode.
  *
- * This is distinct from {@link beginTtscTransformBuild}: hosts such as Vite's
- * development server may invoke `buildStart` only once for a process that spans
- * many edits, so that callback cannot authorize build-scoped shortcuts.
+ * This is the unconditional lifecycle boundary, and it is distinct from
+ * {@link beginTtscTransformBuild}: a pass ending is not a reason to throw a
+ * proven compile away, while a session ending is.
  */
 export declare function resetTtscTransformCache(cache: TtscTransformCache): void;
 /**
@@ -365,8 +450,10 @@ interface TtscHostInputValidation {
  */
 export declare function stripQuery(id: string): string;
 /**
- * Returns `true` for TypeScript declaration files (`.d.ts`, `.d.mts`,
- * `.d.cts`).
+ * Returns `true` for every declaration-file spelling TypeScript-Go accepts.
+ * Besides the standard `.d.ts`, `.d.mts`, and `.d.cts` forms, TypeScript-Go
+ * treats an arbitrary-extension source such as `styles.d.css.ts` as a
+ * declaration file too.
  */
 export declare function isDeclarationFile(id: string): boolean;
 /**
@@ -383,7 +470,7 @@ export declare function createTransformResult(source: string, code: string): Tts
  * slash path. Exported so hosts without a per-build boundary (`@ttsc/metro`)
  * can fold the identical input universe into their own cache fingerprints.
  */
-export declare function collectProjectInputHashes(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations): Record<string, string>;
+export declare function collectProjectInputHashes(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): Record<string, string>;
 /**
  * Report whether an absolute `file` belongs to the project walk universe of
  * `root`: it lies under `root`, every component exists without traversing a
@@ -393,7 +480,7 @@ export declare function collectProjectInputHashes(projectRoot: string, identitie
  * Missing paths and files reached through symlinks or Windows junctions are
  * out-of-walk inputs that only the reference graph can prove relevant.
  */
-export declare function isProjectWalkPath(root: string, file: string, _identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations): boolean;
+export declare function isProjectWalkPath(root: string, file: string, _identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): boolean;
 /**
  * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
  * readable file, a stable directory-kind digest for a directory candidate, and

package/lib/core/transform.d.ts

@@ -3,6 +3,7 @@ import type { ITtscCompilerTransformation } from "ttsc";
 import { type FilesystemPathIdentityContext, type FilesystemPathIdentityOperations } from "ttsc/path-identity";
 import type { TransformResult } from "unplugin";
 import type { ResolvedTtscUnpluginOptions } from "./options";
+import { type ITtscProjectMembershipPolicy } from "./tsconfigPaths";
 /**
  * The normalised transform result type that this module produces.
  *
@@ -11,26 +12,39 @@ import type { ResolvedTtscUnpluginOptions } from "./options";
  * `undefined`.
  */
 export type TtscTransformResult = Exclude<TransformResult, string | null | undefined>;
-/**
- * Normalised alias entry used when building the `paths` overlay for the
- * generated tsconfig. Derived from either a Vite array alias or a webpack/
- * Rspack object alias.
- */
-export interface TtscTransformAlias {
-    /** The alias key (module specifier prefix). */
-    find: string;
-    /** Absolute or cwd-relative path that the alias points to. */
-    replacement: string;
-}
-/** One directory's cheap project-membership identity at generation time. */
+/** One directory's project-membership identity at generation time. */
 interface TtscProjectDirectorySnapshot {
     /** Absolute directory spelling used by the project walk. */
     path: string;
-    /** Metadata signature that changes when its immediate membership changes. */
+    /**
+     * Whether this directory's subtree can hold a program input.
+     *
+     * A directory that cannot is still walked and still watched, so a source
+     * appearing in it later is noticed, but it takes no part in the membership
+     * comparison. That is what lets a bundler create its output directory and
+     * fill it without voiding a generation no compiler input touched, for any
+     * output directory rather than for fifteen names (samchon/ttsc#1307).
+     */
+    relevant: boolean;
+    /**
+     * Digest of the entries the walk itself considers: every immediate child the
+     * ignore list does not drop, with its kind.
+     *
+     * Deliberately not the directory's own metadata. A directory's stamp moves
+     * whenever _any_ entry is added or removed, including the ones the walk
+     * exists to ignore, so a bundler emitting into `dist/` — or merely creating
+     * that directory for the first time — moved the project root's stamp and
+     * voided a generation that no compiler input had touched. The ignore list
+     * only protects the generation if the membership proof honours it too.
+     */
     signature: string;
 }
 /** Generation-scoped directory watchers used to detect membership changes. */
 interface TtscProjectMutationTracker {
+    /** Absolute paths named by generation-time mutation events. */
+    changes: Set<string>;
+    /** Whether additional event paths were discarded after the witness bound. */
+    changesOmitted: boolean;
     close: () => void;
     /**
      * Absolute spellings whose creation, change or removal this tracker would
@@ -113,6 +127,28 @@ export interface TtscCachedProjectTransform {
      * transform.
      */
     inputHashes: Record<string, string>;
+    /**
+     * What the resolved configuration admitted into this generation's program.
+     *
+     * Recorded per generation rather than read per validation because it is a
+     * property of the configuration the compile ran under, so a later delivery
+     * must judge membership by the same rule the compile did. A tsconfig edit
+     * that changes the rule also changes a declared input, which replaces the
+     * generation and its policy together.
+     */
+    membershipPolicy: ITtscProjectMembershipPolicy;
+    /**
+     * Files already reported as absent from the program, and the pass that
+     * reporting belongs to, so the notice is one per file per pass rather than
+     * one per delivery.
+     */
+    missingOutputReported?: Set<string>;
+    missingOutputEpoch?: number;
+    /**
+     * The project config this generation compiled, so a module the program does
+     * not contain can be told which program that was.
+     */
+    tsconfig: string;
     /**
      * Metadata signature of each {@link inputHashes} entry whose hash was proven
      * against an unracing read of the file on disk, in a tick the observed
@@ -124,6 +160,13 @@ export interface TtscCachedProjectTransform {
      * disk bytes against the recorded hash, and may record a signature then.
      */
     inputSignatures?: Record<string, string>;
+    /**
+     * Raw source hash of every readable key in the transform output, keyed by
+     * filesystem identity. Unlike {@link inputHashes}, this includes source
+     * outputs outside the project walk without adding arbitrary output keys to
+     * the complete project snapshot.
+     */
+    sourceHashes?: Record<string, string>;
     /** Metadata snapshot of every directory in the stable generation walk. */
     projectDirectories?: TtscProjectDirectorySnapshot[];
     /** Live notification state for universal host-input changes. */
@@ -168,19 +211,50 @@ export interface TtscCachedProjectTransform {
     projectRoot: string;
     /** Raw compiler output returned by {@link TtscCompiler.transform}. */
     result: ITtscCompilerTransformation;
+    /**
+     * The delivery epoch this generation is currently settled against, or
+     * `undefined` for a generation no epoch has proven.
+     *
+     * Set when the generation is compiled, and again whenever a later epoch's
+     * first delivery proves the whole generation still matches the filesystem.
+     * While it equals the cache's current epoch, each module's first delivery is
+     * settled by the supplied source alone, exactly as it was when every pass
+     * compiled its own generation (samchon/ttsc#1300).
+     */
+    deliveryEpoch?: number;
+    /**
+     * Whether this generation's non-error diagnostics have been surfaced at all,
+     * and the epoch they were last surfaced in.
+     *
+     * The diagnostics describe one compile of one program, so they belong to the
+     * generation rather than to a delivery; a pass that reuses a retained
+     * generation still surfaces them once, because a build's warnings are part of
+     * what that build reports (samchon/ttsc#1304). The two fields are separate so
+     * a persistent host, whose epoch is `undefined`, still reports the first
+     * time.
+     */
+    diagnosticsReported?: boolean;
+    diagnosticsEpoch?: number;
     /**
      * Files already delivered from this generation, keyed by filesystem identity.
-     * Build-scoped caches use this to skip persistent validation only for a
-     * module's first delivery inside the current build.
+     * A cache with a delivery epoch uses this to skip persistent validation only
+     * for a module's first delivery inside the current pass; the set is cleared
+     * whenever a new epoch's gate re-proves the generation.
      */
     servedFiles?: Set<string>;
+    /**
+     * Absolute path of the adapter-owned scratch directory used for this
+     * generation. It is disposed after compilation, so none of its compiler,
+     * resolver, or plugin artifacts can be a persistent cache or watch input.
+     */
+    scratchDirectory?: string;
     /**
      * Absolute path of the generated temp-dir tsconfig this compile ran against,
      * when an alias/compiler-options overlay required one. The compiler reports
      * it in the envelope's `graph.configs` chain, but it is disposed right after
      * the compile, so registering it as a watch input would invalidate every
-     * bundler cache snapshot on the next build; watch derivation must skip
-     * exactly this path.
+     * bundler cache snapshot on the next build; watch derivation must skip this
+     * path. {@link scratchDirectory} owns the wider disposable-input bound.
      */
     temporaryTsconfig?: string;
 }
@@ -234,20 +308,31 @@ export declare function normalizeHostInputName(name: string, caseSensitive: bool
 /** Create an empty persistent transform cache with isolated filesystem reads. */
 export declare function createTtscTransformCache(operations?: Partial<TtscTransformFilesystemOperations>): TtscTransformCache;
 /**
- * Start a host build, clearing its prior generation and enabling constant-time
- * first delivery for modules compiled during this build.
+ * Open a new delivery pass, enabling constant-time first delivery for every
+ * module this pass asks for.
+ *
+ * This deliberately retains the cached generation. The pass boundary is a
+ * statement about _deliveries_ — each module is requested at most once inside
+ * it — not about whether the compiled program is still correct, which the
+ * generation's own recorded snapshot answers and which
+ * {@link matchesCachedSource} proves once at the pass's first delivery. Clearing
+ * here instead made a host whose `buildStart` repeats recompile the whole
+ * project on every rebuild even when no compiler input had changed
+ * (samchon/ttsc#1300). Use {@link resetTtscTransformCache} to actually discard a
+ * generation and its watchers.
  *
- * Hosts without a guaranteed build-start callback use persistent validation
- * unless they have another immutable lifecycle. Bun runtime setup, for example,
+ * Hosts without a guaranteed pass boundary use persistent validation unless
+ * they have another immutable lifecycle. Bun runtime setup, for example,
  * defines one process-scoped module-loading session.
  */
 export declare function beginTtscTransformBuild(cache: TtscTransformCache): void;
 /**
- * Clear a cache and return it to persistent validation mode.
+ * Discard every generation, dispose its watchers, and return the cache to
+ * persistent validation mode.
  *
- * This is distinct from {@link beginTtscTransformBuild}: hosts such as Vite's
- * development server may invoke `buildStart` only once for a process that spans
- * many edits, so that callback cannot authorize build-scoped shortcuts.
+ * This is the unconditional lifecycle boundary, and it is distinct from
+ * {@link beginTtscTransformBuild}: a pass ending is not a reason to throw a
+ * proven compile away, while a session ending is.
  */
 export declare function resetTtscTransformCache(cache: TtscTransformCache): void;
 /**
@@ -365,8 +450,10 @@ interface TtscHostInputValidation {
  */
 export declare function stripQuery(id: string): string;
 /**
- * Returns `true` for TypeScript declaration files (`.d.ts`, `.d.mts`,
- * `.d.cts`).
+ * Returns `true` for every declaration-file spelling TypeScript-Go accepts.
+ * Besides the standard `.d.ts`, `.d.mts`, and `.d.cts` forms, TypeScript-Go
+ * treats an arbitrary-extension source such as `styles.d.css.ts` as a
+ * declaration file too.
  */
 export declare function isDeclarationFile(id: string): boolean;
 /**
@@ -383,7 +470,7 @@ export declare function createTransformResult(source: string, code: string): Tts
  * slash path. Exported so hosts without a per-build boundary (`@ttsc/metro`)
  * can fold the identical input universe into their own cache fingerprints.
  */
-export declare function collectProjectInputHashes(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations): Record<string, string>;
+export declare function collectProjectInputHashes(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): Record<string, string>;
 /**
  * Report whether an absolute `file` belongs to the project walk universe of
  * `root`: it lies under `root`, every component exists without traversing a
@@ -393,7 +480,7 @@ export declare function collectProjectInputHashes(projectRoot: string, identitie
  * Missing paths and files reached through symlinks or Windows junctions are
  * out-of-walk inputs that only the reference graph can prove relevant.
  */
-export declare function isProjectWalkPath(root: string, file: string, _identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations): boolean;
+export declare function isProjectWalkPath(root: string, file: string, _identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): boolean;
 /**
  * Hash a list of absolute out-of-walk input paths: content SHA-256 for a
  * readable file, a stable directory-kind digest for a directory candidate, and