@ttsc/unplugin 0.28.5 → 0.29.0

package/lib/core/transform.d.mts

@@ -82,6 +82,8 @@ interface TtscProjectMutationTracker {
  * graph-free envelopes retain complete-snapshot validation.
  */
 export interface TtscCachedProjectTransform {
+    /** Predicate-preserving compiler proofs for external candidate spellings. */
+    externalInputObservations?: Record<string, ITtscCompilerTransformation.IInputObservation>;
     /**
      * SHA-256 hash of every input the compiler reported outside the project walk
      * (keyed by filesystem identity), captured at the time of the transform.
@@ -201,6 +203,8 @@ export interface TtscCachedProjectTransform {
     hostInputValidation?: TtscHostInputValidation;
     /** Live notification state for file/directory creation, deletion, and rename. */
     projectMutationTracker?: TtscProjectMutationTracker;
+    /** Whether a generated wrapper and its source config graph stayed coherent. */
+    configStateComplete?: boolean;
     /**
      * Whether the generation-time project walk observed every directory and file
      * it attempted to snapshot. An incomplete walk may never authorize narrow
@@ -339,39 +343,92 @@ export declare function resetTtscTransformCache(cache: TtscTransformCache): void
  * What the generation already knows about one derived watch input, handed to
  * the adapter so it does not rederive it per input per delivery.
  *
- * Both facts are generation state: the identity is the memoized
- * {@link pathIdentityKey} of the input, and `missing` is the existence the
- * generation recorded and every cache hit revalidates. An adapter that computes
- * them itself pays a `realpath`, a case-sensitivity directory listing, and an
- * `existsSync` for every input of every delivered module, which is O(modules x
- * inputs) for one build (samchon/ttsc#1246).
+ * All facts are generation state: the identity is the memoized
+ * {@link pathIdentityKey} of the input, `missing` preserves the original public
+ * existence contract, and `unavailable` distinguishes a failed file predicate
+ * from ordinary absence. An adapter that computes them itself pays a
+ * `realpath`, a case-sensitivity directory listing, and an `existsSync` for
+ * every input of every delivered module, which is O(modules x inputs) for one
+ * build (samchon/ttsc#1246).
  */
 export interface TtscWatchInputEvidence {
     /** Memoized filesystem identity of the input. */
     identity: string;
-    /** Whether the generation recorded this input as absent. */
+    /** Whether the generation recorded this input as unavailable as a file. */
     missing: boolean;
+    /** The generation state Metro can compare with its main-process baseline. */
+    state?: TtscWatchInputState;
+    /** Which unavailable predicate must become true before invalidation. */
+    unavailable?: "missing" | "not-file";
+}
+/** Exact generation state behind one derived watch input. */
+export type TtscWatchInputState = {
+    /** A project-walk or dependency-only input read as ordinary host bytes. */
+    codec: "host";
+    hash: string;
+} | {
+    /** A realized compiler-graph input, including its physical target. */
+    codec: "graph";
+    hash: string;
+    realpath: string | null;
+} | {
+    /** The exact compiler predicates observed for a resolver input. */
+    codec: "predicates";
+    observation: ITtscCompilerTransformation.IInputObservation;
+};
+/** Main-process file predicate used only by project discovery. */
+export interface TtscWatchInputFileBaseline {
+    fileExists: boolean;
+    identity: string;
+}
+/** Main-process state broad enough to compare every watch-input codec. */
+export interface TtscWatchInputBaseline extends TtscWatchInputFileBaseline {
+    directoryExists: boolean;
+    graphHash: string;
+    graphReadHash: string | null;
+    hostHash: string;
+    realpath: {
+        ok: false;
+        path?: never;
+    } | {
+        ok: true;
+        path: string;
+    };
+    stat: "directory" | "file" | "missing";
+}
+/** Baseline shape stored for either a discovery predicate or a full input. */
+export type TtscWatchInputKeyBaseline = TtscWatchInputFileBaseline | TtscWatchInputBaseline;
+/** One derived input and its optional generation proof. */
+export interface TtscWatchInput {
+    evidence?: TtscWatchInputEvidence;
+    file: string;
 }
 /**
  * Hooks the bundler adapter passes into {@link transformTtsc} so transform
- * side-channels (plugin-reported dependencies and host resolution candidates)
- * reach the bundler without leaking extra fields on the returned
- * `TransformResult`.
+ * side-channels (plugin-reported dependencies and host resolver inputs) reach
+ * the bundler without leaking extra fields on the returned `TransformResult`.
  */
 export interface TtscTransformHooks {
     /**
      * Invoked once per absolute watch-input path derived for the transformed file
      * `F`: the plugin-reported `dependencies[F]` list unioned with the host-owned
      * reference graph's contribution — the reachability closure of `graph.edges`
-     * from `F`, the `graph.globals` files, the `graph.configs` chain, and missing
-     * higher-priority `graph.candidates` — or, for a file the envelope declared
-     * `dependenciesComplete`, only `dependencies[F]`, `graph.candidates`, and the
-     * universal `graph.configs` chain. Adapters forward this to the bundler's
+     * from `F`, the `graph.globals` files, the `graph.configs` chain, importer
+     * `graph.candidates`, and universal `graph.resolutionInputs`. For a file the
+     * envelope declared `dependenciesComplete`, only `dependencies[F]`,
+     * `graph.candidates`, `graph.resolutionInputs`, and the universal
+     * `graph.configs` chain remain. Adapters forward this to the bundler's
      * `addWatchFile` so type-only inputs participate in watch-mode and
      * persistent-cache invalidation. See {@link selectWatchInputs} for the exact
      * derivation.
      */
     addWatchFile?: (file: string, evidence?: TtscWatchInputEvidence) => void;
+    /**
+     * Batched form of {@link addWatchFile}. When supplied, the transform calls it
+     * once per delivered module and does not call `addWatchFile` for that
+     * module.
+     */
+    addWatchFiles?: (inputs: readonly TtscWatchInput[]) => void;
     /**
      * Invoked when the plugin declared the transformed file volatile (the
      * envelope's `volatile` list): its output depends on non-file inputs that no
@@ -396,8 +453,7 @@ export interface TtscTransformHooks {
  * @param id - Bundler module id (may carry a query string or virtual prefix).
  * @param source - Current file content supplied by the bundler.
  * @param options - Resolved plugin options.
- * @param aliases - Raw bundler alias configuration (Vite array or webpack
- *   object).
+ * @param aliases - Raw Vite alias configuration (object or array).
  * @param cache - Optional project cache. Callers with a real `buildStart`
  *   boundary declare it through {@link beginTtscTransformBuild}; other hosts
  *   retain persistent validation.
@@ -464,6 +520,8 @@ export declare function isDeclarationFile(id: string): boolean;
  * unnecessary module update and preserves the original source map.
  */
 export declare function createTransformResult(source: string, code: string): TtscTransformResult | undefined;
+/** Validate one predicate-preserving graph proof against a filesystem view. */
+export declare function validateGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem?: TtscTransformFilesystemOperations): string[];
 /**
  * Hash every input file under `projectRoot` (the same walk universe
  * {@link matchesCachedSource} validates against), keyed by project-relative
@@ -471,6 +529,16 @@ export declare function createTransformResult(source: string, code: string): Tts
  * can fold the identical input universe into their own cache fingerprints.
  */
 export declare function collectProjectInputHashes(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): Record<string, string>;
+/** One project-walk hash set together with its completeness proof. */
+export interface TtscProjectInputHashSnapshot {
+    complete: boolean;
+    hashes: Record<string, string>;
+}
+/**
+ * Hash the project walk and retain whether every attempted directory and file
+ * was observed coherently. Cache-key hosts must reject an incomplete set.
+ */
+export declare function collectProjectInputHashSnapshot(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): TtscProjectInputHashSnapshot;
 /**
  * Report whether an absolute `file` belongs to the project walk universe of
  * `root`: it lies under `root`, every component exists without traversing a
@@ -492,6 +560,18 @@ export declare function isProjectWalkPath(root: string, file: string, _identitie
  * with identical semantics at cache-key time.
  */
 export declare function collectExternalInputHashes(paths: readonly string[], filesystem?: TtscTransformFilesystemOperations): Record<string, string>;
+/** Capture the stable file predicate used by implicit project discovery. */
+export declare function captureWatchInputFileBaseline(file: string, filesystem?: TtscTransformFilesystemOperations): TtscWatchInputFileBaseline | undefined;
+/**
+ * Capture one stable main-process baseline that can be compared with any
+ * generation-owned watch-input evidence. Two equal broad observations are
+ * required so a cache key never publishes a torn path state.
+ */
+export declare function captureWatchInputBaseline(file: string, filesystem?: TtscTransformFilesystemOperations): TtscWatchInputBaseline | undefined;
+/** Compare generation evidence with the main process's exact key baseline. */
+export declare function watchInputEvidenceMatchesBaseline(evidence: TtscWatchInputEvidence, baseline: TtscWatchInputKeyBaseline): boolean;
+/** Validate the complete narrow or broad shape stored in a key baseline. */
+export declare function isWatchInputKeyBaseline(baseline: unknown): baseline is TtscWatchInputKeyBaseline;
 /**
  * Build a comparison key for a path without changing the spelling handed to a
  * filesystem or bundler. Windows is case-insensitive; macOS is probed per

package/lib/core/transform.d.ts

@@ -82,6 +82,8 @@ interface TtscProjectMutationTracker {
  * graph-free envelopes retain complete-snapshot validation.
  */
 export interface TtscCachedProjectTransform {
+    /** Predicate-preserving compiler proofs for external candidate spellings. */
+    externalInputObservations?: Record<string, ITtscCompilerTransformation.IInputObservation>;
     /**
      * SHA-256 hash of every input the compiler reported outside the project walk
      * (keyed by filesystem identity), captured at the time of the transform.
@@ -201,6 +203,8 @@ export interface TtscCachedProjectTransform {
     hostInputValidation?: TtscHostInputValidation;
     /** Live notification state for file/directory creation, deletion, and rename. */
     projectMutationTracker?: TtscProjectMutationTracker;
+    /** Whether a generated wrapper and its source config graph stayed coherent. */
+    configStateComplete?: boolean;
     /**
      * Whether the generation-time project walk observed every directory and file
      * it attempted to snapshot. An incomplete walk may never authorize narrow
@@ -339,39 +343,92 @@ export declare function resetTtscTransformCache(cache: TtscTransformCache): void
  * What the generation already knows about one derived watch input, handed to
  * the adapter so it does not rederive it per input per delivery.
  *
- * Both facts are generation state: the identity is the memoized
- * {@link pathIdentityKey} of the input, and `missing` is the existence the
- * generation recorded and every cache hit revalidates. An adapter that computes
- * them itself pays a `realpath`, a case-sensitivity directory listing, and an
- * `existsSync` for every input of every delivered module, which is O(modules x
- * inputs) for one build (samchon/ttsc#1246).
+ * All facts are generation state: the identity is the memoized
+ * {@link pathIdentityKey} of the input, `missing` preserves the original public
+ * existence contract, and `unavailable` distinguishes a failed file predicate
+ * from ordinary absence. An adapter that computes them itself pays a
+ * `realpath`, a case-sensitivity directory listing, and an `existsSync` for
+ * every input of every delivered module, which is O(modules x inputs) for one
+ * build (samchon/ttsc#1246).
  */
 export interface TtscWatchInputEvidence {
     /** Memoized filesystem identity of the input. */
     identity: string;
-    /** Whether the generation recorded this input as absent. */
+    /** Whether the generation recorded this input as unavailable as a file. */
     missing: boolean;
+    /** The generation state Metro can compare with its main-process baseline. */
+    state?: TtscWatchInputState;
+    /** Which unavailable predicate must become true before invalidation. */
+    unavailable?: "missing" | "not-file";
+}
+/** Exact generation state behind one derived watch input. */
+export type TtscWatchInputState = {
+    /** A project-walk or dependency-only input read as ordinary host bytes. */
+    codec: "host";
+    hash: string;
+} | {
+    /** A realized compiler-graph input, including its physical target. */
+    codec: "graph";
+    hash: string;
+    realpath: string | null;
+} | {
+    /** The exact compiler predicates observed for a resolver input. */
+    codec: "predicates";
+    observation: ITtscCompilerTransformation.IInputObservation;
+};
+/** Main-process file predicate used only by project discovery. */
+export interface TtscWatchInputFileBaseline {
+    fileExists: boolean;
+    identity: string;
+}
+/** Main-process state broad enough to compare every watch-input codec. */
+export interface TtscWatchInputBaseline extends TtscWatchInputFileBaseline {
+    directoryExists: boolean;
+    graphHash: string;
+    graphReadHash: string | null;
+    hostHash: string;
+    realpath: {
+        ok: false;
+        path?: never;
+    } | {
+        ok: true;
+        path: string;
+    };
+    stat: "directory" | "file" | "missing";
+}
+/** Baseline shape stored for either a discovery predicate or a full input. */
+export type TtscWatchInputKeyBaseline = TtscWatchInputFileBaseline | TtscWatchInputBaseline;
+/** One derived input and its optional generation proof. */
+export interface TtscWatchInput {
+    evidence?: TtscWatchInputEvidence;
+    file: string;
 }
 /**
  * Hooks the bundler adapter passes into {@link transformTtsc} so transform
- * side-channels (plugin-reported dependencies and host resolution candidates)
- * reach the bundler without leaking extra fields on the returned
- * `TransformResult`.
+ * side-channels (plugin-reported dependencies and host resolver inputs) reach
+ * the bundler without leaking extra fields on the returned `TransformResult`.
  */
 export interface TtscTransformHooks {
     /**
      * Invoked once per absolute watch-input path derived for the transformed file
      * `F`: the plugin-reported `dependencies[F]` list unioned with the host-owned
      * reference graph's contribution — the reachability closure of `graph.edges`
-     * from `F`, the `graph.globals` files, the `graph.configs` chain, and missing
-     * higher-priority `graph.candidates` — or, for a file the envelope declared
-     * `dependenciesComplete`, only `dependencies[F]`, `graph.candidates`, and the
-     * universal `graph.configs` chain. Adapters forward this to the bundler's
+     * from `F`, the `graph.globals` files, the `graph.configs` chain, importer
+     * `graph.candidates`, and universal `graph.resolutionInputs`. For a file the
+     * envelope declared `dependenciesComplete`, only `dependencies[F]`,
+     * `graph.candidates`, `graph.resolutionInputs`, and the universal
+     * `graph.configs` chain remain. Adapters forward this to the bundler's
      * `addWatchFile` so type-only inputs participate in watch-mode and
      * persistent-cache invalidation. See {@link selectWatchInputs} for the exact
      * derivation.
      */
     addWatchFile?: (file: string, evidence?: TtscWatchInputEvidence) => void;
+    /**
+     * Batched form of {@link addWatchFile}. When supplied, the transform calls it
+     * once per delivered module and does not call `addWatchFile` for that
+     * module.
+     */
+    addWatchFiles?: (inputs: readonly TtscWatchInput[]) => void;
     /**
      * Invoked when the plugin declared the transformed file volatile (the
      * envelope's `volatile` list): its output depends on non-file inputs that no
@@ -396,8 +453,7 @@ export interface TtscTransformHooks {
  * @param id - Bundler module id (may carry a query string or virtual prefix).
  * @param source - Current file content supplied by the bundler.
  * @param options - Resolved plugin options.
- * @param aliases - Raw bundler alias configuration (Vite array or webpack
- *   object).
+ * @param aliases - Raw Vite alias configuration (object or array).
  * @param cache - Optional project cache. Callers with a real `buildStart`
  *   boundary declare it through {@link beginTtscTransformBuild}; other hosts
  *   retain persistent validation.
@@ -464,6 +520,8 @@ export declare function isDeclarationFile(id: string): boolean;
  * unnecessary module update and preserves the original source map.
  */
 export declare function createTransformResult(source: string, code: string): TtscTransformResult | undefined;
+/** Validate one predicate-preserving graph proof against a filesystem view. */
+export declare function validateGraphInputObservation(file: string, observation: ITtscCompilerTransformation.IInputObservation, filesystem?: TtscTransformFilesystemOperations): string[];
 /**
  * Hash every input file under `projectRoot` (the same walk universe
  * {@link matchesCachedSource} validates against), keyed by project-relative
@@ -471,6 +529,16 @@ export declare function createTransformResult(source: string, code: string): Tts
  * can fold the identical input universe into their own cache fingerprints.
  */
 export declare function collectProjectInputHashes(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): Record<string, string>;
+/** One project-walk hash set together with its completeness proof. */
+export interface TtscProjectInputHashSnapshot {
+    complete: boolean;
+    hashes: Record<string, string>;
+}
+/**
+ * Hash the project walk and retain whether every attempted directory and file
+ * was observed coherently. Cache-key hosts must reject an incomplete set.
+ */
+export declare function collectProjectInputHashSnapshot(projectRoot: string, identities?: FilesystemPathIdentityContext, filesystem?: TtscTransformFilesystemOperations, policy?: ITtscProjectMembershipPolicy): TtscProjectInputHashSnapshot;
 /**
  * Report whether an absolute `file` belongs to the project walk universe of
  * `root`: it lies under `root`, every component exists without traversing a
@@ -492,6 +560,18 @@ export declare function isProjectWalkPath(root: string, file: string, _identitie
  * with identical semantics at cache-key time.
  */
 export declare function collectExternalInputHashes(paths: readonly string[], filesystem?: TtscTransformFilesystemOperations): Record<string, string>;
+/** Capture the stable file predicate used by implicit project discovery. */
+export declare function captureWatchInputFileBaseline(file: string, filesystem?: TtscTransformFilesystemOperations): TtscWatchInputFileBaseline | undefined;
+/**
+ * Capture one stable main-process baseline that can be compared with any
+ * generation-owned watch-input evidence. Two equal broad observations are
+ * required so a cache key never publishes a torn path state.
+ */
+export declare function captureWatchInputBaseline(file: string, filesystem?: TtscTransformFilesystemOperations): TtscWatchInputBaseline | undefined;
+/** Compare generation evidence with the main process's exact key baseline. */
+export declare function watchInputEvidenceMatchesBaseline(evidence: TtscWatchInputEvidence, baseline: TtscWatchInputKeyBaseline): boolean;
+/** Validate the complete narrow or broad shape stored in a key baseline. */
+export declare function isWatchInputKeyBaseline(baseline: unknown): baseline is TtscWatchInputKeyBaseline;
 /**
  * Build a comparison key for a path without changing the spelling handed to a
  * filesystem or bundler. Windows is case-insensitive; macOS is probed per