@ttsc/unplugin 0.30.4 → 0.31.0

package/src/core/farm/farmPersistentCacheWithoutRecords.ts

@@ -0,0 +1,82 @@
+import path from "node:path";
+
+import { hostToolDirectory } from "../bridge/hostToolDirectory";
+import { projectRecordDirectoryWritable } from "../bridge/projectRecordDirectoryWritable";
+import { farmRecordFallback } from "./farmRecordFallback";
+
+/**
+ * Farm's configuration with its persistent cache turned off when no project
+ * record could be written anywhere Farm accepts one, or the configuration
+ * unchanged (samchon/ttsc#1480).
+ *
+ * A module handed to a host without its project's record depends on its own
+ * bytes alone, and the adapter marks it uncacheable where the host allows that.
+ * Farm offers a JavaScript plugin no per-module opt-out of its persistent
+ * cache, so after a type-only edit made while Farm was stopped, it restored
+ * such a module and served its old output. Its `config` hook can turn the cache
+ * off for the whole compile, measured on Farm 1.7.11: a module Farm restores on
+ * the second compile of a browser target ran its transform again, and no store
+ * was written. So Farm is asked here, before any delivery, whether its records
+ * will exist: below its root (`hostToolDirectory`), or in the fallback it
+ * accepts (`farmRecordFallback`), each tested by a current write. This does not
+ * promise later write capability. Where neither can be written persistent cache
+ * use is disabled in the returned configuration, and the user is told once why,
+ * as a Node process warning, code `TTSC_PROJECT_RECORD_UNWRITABLE`.
+ *
+ * @param config Farm's user configuration, as its `config` hook receives it.
+ * @param cwd The directory Farm runs in, the root when the configuration names
+ *   none.
+ * @evidence contracts/common.md#principled-implementation Current record-directory probes select whether Farm is asked to retain persistent modules; when both fail the returned config disables that cache. Later writes still need delivery-time failure handling, so a successful probe is not lifetime invalidation authority.
+ * @evidence contracts/common.md#clear-and-simple-design The configuration hook probes the two existing record locations and returns a shallow config/compilation copy changing persistentCache when needed. Other own enumerable fields and shared nested values are preserved.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts This is a host capability boundary with a stated invalidation reason, rather than a test-only bypass, patched cache implementation, or assumed writable directory.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains why per-module opt-out is unavailable and why the warning and configuration-level fallback are necessary.
+ * @evidence contracts/portability.md#os-neutral-implementation Writability is proven by an actual write below the tool directory and the fallback, and the root is resolved with path.resolve against cwd, so no operating-system name, permission bit or drive layout is assumed.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   At most two write probes retain native path/mkdir/write/removal work and
+ *   delegated fallback naming/trust setup. Warning text follows path length;
+ *   disabling cache copies the config/compilation own fields. A fixed probe
+ *   count does not make native operations or field populations constant cost.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   The WARNED set emits the unwritable-records warning once per tool
+ *   directory spelling, not once per config pass. It marks before emission,
+ *   so it suppresses later attempts rather than certifying user receipt. Write
+ *   capability is still freshly probed instead of reused from that warning key.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   WARNED retains each distinct tool-directory spelling for the process life,
+ *   without eviction or a fixed string-byte bound. Probe cleanup and persistent
+ *   directories belong to the write-probe helper; failed removal can leave its
+ *   probe. Returned config ownership transfers to Farm.
+ */
+export function farmPersistentCacheWithoutRecords<
+  Config extends {
+    compilation?: { persistentCache?: unknown };
+    root?: string;
+  },
+>(config: Config, cwd: string): Config {
+  if (config.compilation?.persistentCache === false) return config;
+  const root = path.resolve(cwd, config.root ?? ".");
+  const toolDirectory = hostToolDirectory(root);
+  if (projectRecordDirectoryWritable(toolDirectory)) return config;
+  const fallback = farmRecordFallback(root);
+  if (fallback !== undefined && projectRecordDirectoryWritable(fallback)) {
+    return config;
+  }
+  if (!WARNED.has(toolDirectory)) {
+    WARNED.add(toolDirectory);
+    process.emitWarning(
+      `@ttsc/unplugin: project records cannot be written below ` +
+        `${toolDirectory}, nor anywhere else Farm accepts them, so Farm's ` +
+        "persistent cache is turned off: it would restore a module whatever " +
+        "the types its output consulted did while Farm was stopped. Let the " +
+        `adapter write below ${toolDirectory}.`,
+      { code: "TTSC_PROJECT_RECORD_UNWRITABLE" },
+    );
+  }
+  return {
+    ...config,
+    compilation: { ...config.compilation, persistentCache: false },
+  };
+}
+
+/** The tool directories this process already warned about. */
+const WARNED = new Set<string>();

package/src/core/farm/farmRecordFallback.ts

@@ -0,0 +1,41 @@
+import path from "node:path";
+
+import { fallbackToolDirectory } from "../bridge/fallbackToolDirectory";
+
+/**
+ * The fallback tool directory Farm accepts for a root, or `undefined` when it
+ * accepts none (samchon/ttsc#1480).
+ *
+ * Farm computes every watch file's path relative to its root and fails on one
+ * it cannot relate, such as a file on another Windows drive, and its watcher
+ * refuses an extra file below any `node_modules` (`hostToolDirectory`). The
+ * fallback below this user's validated state directory
+ * (`fallbackToolDirectory`) qualifies where it shares the root's drive and lies
+ * below no `node_modules`, and Farm's records live below the root alone
+ * otherwise.
+ *
+ * @param root Farm's configured root.
+ * @evidence contracts/common.md#principled-implementation A fallback is usable only when native relative-path semantics relate it to the Farm root and none of its path components is node_modules, matching the host's watch-file restrictions.
+ * @evidence contracts/common.md#clear-and-simple-design The adapter filters the shared user-state fallback provider with two host restrictions instead of creating another record location policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No drive letter or user directory is hardcoded; rejection follows the host's actual path and watcher capabilities.
+ * @evidence contracts/common.md#meaningful-documentation The native comment names both host restrictions and explains why the root's own directory remains the alternative.
+ * @evidence contracts/portability.md#os-neutral-implementation Containment is decided with path.relative and path.isAbsolute, so a fallback on another Windows drive is refused without comparing drive letters, and node_modules is found as a path segment split on the platform's separator.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Native relative/isAbsolute processing follows root/fallback text, then
+ *   split/includes scans its path components and allocates their array. Cold
+ *   fallback naming additionally retains native user-state trust setup and
+ *   root hashing; a cached name does not certify current writability.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Filters one current root/fallback pair. Naming reuse belongs to the shared
+ *   fallback provider; host acceptance and writer capability are separate checks.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function farmRecordFallback(root: string): string | undefined {
+  const fallback = fallbackToolDirectory(root);
+  if (fallback === undefined) return undefined;
+  if (path.isAbsolute(path.relative(root, fallback))) return undefined;
+  return fallback.split(path.sep).includes("node_modules")
+    ? undefined
+    : fallback;
+}

package/src/core/index.ts

@@ -1,400 +1,52 @@
-import type { UnpluginFactory, UnpluginInstance } from "unplugin";
-import { createUnplugin } from "unplugin";
-
-import { createEsbuildOptions } from "./esbuild";
-import type { TtscUnpluginOptions } from "./options";
-import { resolveOptions } from "./options";
-import { typescriptTransformSourcePattern } from "./sourceExtensions";
-import {
-  beginTtscTransformBuild,
-  captureWatchInputBaseline,
-  captureWatchInputFileBaseline,
-  collectExternalInputHashes,
-  collectProjectInputHashSnapshot,
-  collectProjectInputHashes,
-  createTtscTransformCache,
-  isDeclarationFile,
-  isProjectWalkPath,
-  isWatchInputKeyBaseline,
-  resetTtscTransformCache,
-  stripQuery,
-  transformTtsc,
-  watchInputEvidenceMatchesBaseline,
-} from "./transform";
-import { createViteServeInputWatch } from "./viteServe";
-
-const name = "ttsc-unplugin";
-/**
- * Matches the exact TypeScript source extensions the ttsc transform handles:
- * `.ts`, `.tsx`, `.mts`, and `.cts`. JavaScript and invented extension forms
- * such as `.mtsx` are deliberately excluded.
- *
- * Shared with the Bun adapter (`bun.ts`) and the standalone Turbopack loader
- * (`turbopack.ts`) through {@link isTransformTarget}, so the filter is defined
- * once and every adapter answers the same way.
- */
-export const sourceFilePattern = typescriptTransformSourcePattern;
-/** Matches any path segment that is a `node_modules` directory (cross-platform). */
-const nodeModulesPattern = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
-/**
- * Matches virtual module ids: Rollup/Vite use a leading NUL byte (`\0`) as
- * convention.
- */
-const virtualModulePattern = /\0/;
-
-/**
- * Unplugin factory that wires the ttsc transform pipeline into any supported
- * bundler (Vite, Rollup, Rolldown, webpack, Rspack, esbuild, Farm).
- *
- * The factory resolves raw options once, creates one transform cache for the
- * whole plugin instance, and captures Vite alias configuration via the
- * `vite.configResolved` hook so that path aliases are forwarded to the
- * generated tsconfig overlay. A host with a real `buildStart` opens a delivery
- * pass there and keeps its generation across passes; a watching Vite
- * development server keeps persistent validation instead, because its one
- * `buildStart` spans later HMR edits and so cannot mark a pass, while a dev
- * server configured without a watcher takes the pass lifecycle with them,
- * having declared it will observe no edit at all.
- */
-const unpluginFactory: UnpluginFactory<
-  TtscUnpluginOptions | undefined,
-  false
-> = (rawOptions = {}, meta) => {
-  const options = resolveOptions(rawOptions);
-  if (meta.framework === "esbuild") {
-    return createEsbuildOptions(options, isTransformTarget);
-  }
-  const transformCache = createTtscTransformCache();
-  const serveInputs = createViteServeInputWatch();
-  let aliases: unknown;
-  let viteCommand: string | undefined;
-  let viteWatching = true;
-  // Whether a build-mode session is driven by Rollup's watcher. `build.watch`
-  // is `null` for an ordinary build and an object under `--watch`, which is the
-  // axis the disposal boundary actually turns on: only a watching build repeats
-  // its build phase, and only a watching build ends at `closeWatcher`.
-  let viteBuildWatching = false;
-  // A restart can start the replacement plugin container before closing the
-  // old one, and Vite calls buildEnd even for a container that never started.
-  // Track the stable per-container PluginContext identity so that unstarted
-  // old containers cannot dispose a replacement's freshly initialized cache.
-  let viteBuildOwners = new WeakSet<object>();
-  let viteBuildLifecycles = 0;
-
-  return {
-    name,
-    enforce: "pre",
-
-    vite: {
-      configResolved(config) {
-        aliases = config.resolve.alias;
-        // Re-read per config resolution: a plugin instance reused across a
-        // serve and a later build must stop routing missing inputs to the
-        // serve-time poll, even though the closed server stays attached
-        // (see the dispose note in viteServe.ts).
-        viteCommand = config.command;
-        // `server.watch: null` disables Vite's watcher outright, which is how
-        // a one-shot consumer (a `vitest --run` suite above all) configures the
-        // dev server. Nothing can then deliver a change event, so every watch
-        // registration is dead weight, and not cheap dead weight: Vite's
-        // import analysis resolves each registered path like a real import of
-        // the transformed module, once per module, which is the dominant cost
-        // of a delivered module in a project with a real dependency graph
-        // (samchon/ttsc#1246).
-        viteWatching =
-          (config as { server?: { watch?: unknown } }).server?.watch !== null;
-        // Read on the same principle as the line above, from the half of the
-        // config that governs a build rather than a server. The comparison is
-        // loose where the server's is strict because the two defaults differ:
-        // `server.watch` is an object unless explicitly `null`, while
-        // `build.watch` is absent or `null` unless `--watch` supplies one.
-        viteBuildWatching =
-          (config as { build?: { watch?: unknown } }).build?.watch != null;
-      },
-      // Compiler dependencies belong to the filesystem watch graph. Vite's
-      // transform-context addWatchFile also inserts runtime imports, so none
-      // of those dependencies may use that channel during serve (#1368).
-      configureServer(server) {
-        serveInputs.attach(server);
-      },
-      watchChange(id, change) {
-        if (change.event === "delete") serveInputs.forget(stripQuery(id));
-      },
-      // Vite calls buildEnd when the dev server closes, and Rollup calls it at
-      // the end of every build phase; drop every poller and, once the last
-      // overlapping container has closed, every generation-owned filesystem
-      // tracker as well.
-      //
-      // Disposing here is right wherever the end of a build phase is also the
-      // end of the session: a dev server, and an ordinary one-shot build. It is
-      // wrong for a watching build, whose watcher repeats build phases, so it
-      // means "this pass ended" there — measured as
-      // `buildStart -> buildEnd -> ... -> buildStart -> buildEnd` across
-      // `vite build --watch` rebuilds. Disposing on that repeat discarded the
-      // generation once per rebuild independently of the `buildStart` clear, so
-      // fixing one of the two sites alone left this host recompiling the whole
-      // project per edit (samchon/ttsc#1301). The watching build hands its
-      // teardown to `closeWatcher` below instead.
-      async buildEnd() {
-        if (viteBuildOwners.delete(this)) {
-          viteBuildLifecycles -= 1;
-        }
-        if (viteBuildLifecycles === 0) {
-          if (viteCommand === "serve" || !viteBuildWatching) {
-            resetTtscTransformCache(transformCache);
-          }
-          await serveInputs.dispose();
-        }
-      },
-      // The watching build's real teardown, and the only hook in a
-      // `vite build --watch` trace that fires exactly once: buildEnd,
-      // writeBundle and closeBundle all repeat per rebuild there. A generation
-      // retained across passes owns directory watchers, so this is where they
-      // are released. Vite's dev server drives no Rollup watcher and an
-      // ordinary build closes its bundle instead, so neither reaches here;
-      // a host that fired both would simply reset twice, which is idempotent.
-      //
-      // The container bookkeeping is cleared with the cache, and the owner set
-      // is replaced rather than merely zeroed alongside it. A watcher closed
-      // mid-rebuild leaves a container still registered, and its later
-      // `buildEnd` would then decrement a counter that is already zero and
-      // strand it below zero, after which the disposal above could never fire
-      // again for this plugin instance.
-      async closeWatcher() {
-        viteBuildOwners = new WeakSet<object>();
-        viteBuildLifecycles = 0;
-        resetTtscTransformCache(transformCache);
-        await serveInputs.dispose();
-      },
-    },
-
-    // Rollup and Rolldown carry none of the Vite block's hooks, so before this
-    // they had no disposal site at all. They get both halves of the same
-    // boundary: a watching session ends at `closeWatcher`, and a one-shot build
-    // ends when its build phase does. `this.meta.watchMode` separates the two
-    // there, the way `build.watch` does for Vite, so a one-shot build is not
-    // left without a site the way `vite build` was (samchon/ttsc#1301).
-    // unplugin merges each of these blocks only into its own adapter, so the
-    // Vite adapter never receives them.
-    //
-    // A `buildEnd` at the top level instead of inside a block would be a
-    // regression rather than a shorthand: unplugin forwards a top-level one to
-    // esbuild's `onEnd` and to webpack's and Rspack's `hooks.emit`, each of
-    // which repeats per rebuild, so those hosts would start discarding a valid
-    // generation on every edit, which is samchon/ttsc#1300 again.
-    rollup: {
-      buildEnd(this: { meta?: { watchMode?: boolean } }) {
-        if (this.meta?.watchMode !== true) {
-          resetTtscTransformCache(transformCache);
-        }
-      },
-      closeWatcher() {
-        resetTtscTransformCache(transformCache);
-      },
-    },
-    rolldown: {
-      buildEnd(this: { meta?: { watchMode?: boolean } }) {
-        if (this.meta?.watchMode !== true) {
-          resetTtscTransformCache(transformCache);
-        }
-      },
-      closeWatcher() {
-        resetTtscTransformCache(transformCache);
-      },
-    },
-
-    // These hosts map a top-level buildEnd to a per-compilation hook, so use
-    // their true compiler or context teardown instead. The custom callbacks
-    // are installed by unplugin alongside its ordinary transform wiring.
-    webpack(compiler) {
-      compiler.hooks.shutdown.tap(name, () => {
-        resetTtscTransformCache(transformCache);
-      });
-    },
-    rspack(compiler) {
-      compiler.hooks.shutdown.tap(name, () => {
-        resetTtscTransformCache(transformCache);
-      });
-    },
-    farm: {
-      // Farm calls buildStart only for the initial compilation. Every update
-      // opens a new pass so a failed verdict can recover, while an unchanged
-      // successful generation remains reusable across its module deliveries.
-      updateModules: {
-        executor() {
-          beginTtscTransformBuild(transformCache);
-        },
-      },
-    },
-    buildStart() {
-      if (viteCommand !== undefined && !viteBuildOwners.has(this as object)) {
-        viteBuildOwners.add(this as object);
-        viteBuildLifecycles += 1;
-      }
-      // Persistent validation exists for a session that spans edits it can
-      // observe, and a dev server told to open no watcher is not one:
-      // `server.watch: null` leaves Vite with no change channel at all, so no
-      // edit can reach the session, nothing invalidates what one touched, and
-      // no client is hot-updated. Validating each delivery there does not buy
-      // freshness, it buys incoherence — modules delivered before an edit and
-      // after it would come from two different compilations of one program —
-      // while costing a full derived-input proof per delivered module. The pass
-      // lifecycle settles each module's first delivery against the generation
-      // the session started from, exactly as a build does, and still
-      // revalidates a module this session already delivered. A one-shot suite
-      // configures precisely this server (`vitest --run` sets `server.watch =
-      // null`) and is the workload behind samchon/ttsc#970
-      // (samchon/ttsc#1260). The neighbouring watch-registration decision reads
-      // the same two properties for the same reason.
-      //
-      // Opening a pass no longer discards the generation, so the `else` branch
-      // is what every host with a repeating `buildStart` takes without paying a
-      // whole-project transform per rebuild (samchon/ttsc#1300).
-      if (viteCommand === "serve" && viteWatching) {
-        resetTtscTransformCache(transformCache);
-      } else {
-        beginTtscTransformBuild(transformCache);
-      }
-    },
-
-    transformInclude(id) {
-      const file = stripQuery(id);
-      return isTransformTarget(file);
-    },
-
-    async transform(source, id) {
-      const file = stripQuery(id);
-      if (!isTransformTarget(file)) {
-        return undefined;
-      }
-      // The project-root observer is already live when a Vite serve transform
-      // begins. Its sequence token lets registration prove only inputs that
-      // could have changed during compilation, instead of synchronously
-      // re-reading every input in a large compiler graph.
-      const serveStartedAt =
-        viteCommand === "serve" && viteWatching
-          ? serveInputs.begin()
-          : undefined;
-      return transformTtsc(file, source, options, aliases, transformCache, {
-        // A watcherless server has no invalidation channel and needs no
-        // watch-input derivation. Every other host keeps its native contract.
-        addWatchFiles:
-          viteCommand === "serve" && !viteWatching
-            ? undefined
-            : (inputs, failed) => {
-                if (viteCommand === "serve") {
-                  serveInputs.replace(file, inputs, failed, serveStartedAt);
-                } else {
-                  const native = this.getNativeBuildContext?.();
-                  for (const input of inputs) {
-                    if (
-                      native?.framework === "rspack" &&
-                      native.loaderContext !== undefined
-                    ) {
-                      // Compilation-level dependencies schedule a pass but do
-                      // not invalidate Rspack's cached transformed modules.
-                      if (input.evidence?.missing === true)
-                        native.loaderContext.addMissingDependency(input.file);
-                      else native.loaderContext.addDependency(input.file);
-                    } else if (native?.framework === "farm") {
-                      native.context.addWatchFile(file, input.file);
-                    } else {
-                      this.addWatchFile(input.file);
-                    }
-                  }
-                }
-              },
-        // A module the plugin declared volatile depends on non-file inputs,
-        // which no file-dependency snapshot can represent; mark it
-        // uncacheable where the bundler exposes that control.
-        markVolatile: () => {
-          const native = this.getNativeBuildContext?.();
-          if (
-            native?.framework === "webpack" ||
-            native?.framework === "rspack"
-          ) {
-            native.loaderContext?.cacheable?.(false);
-          }
-        },
-      });
-    },
-  };
-};
-
-const unplugin: UnpluginInstance<TtscUnpluginOptions | undefined, false> =
-  createUnplugin(unpluginFactory);
-
-export type {
-  TtscUnpluginCompilerOptionsJson,
-  TtscUnpluginOptions,
-} from "./options";
-export type {
-  TtscProjectDiscoveryFilesystem,
-  TtscProjectTreeDiscoveryFilesystem,
-  TtscProjectTsconfigCandidate,
-  TtscProjectTsconfigDiscovery,
-} from "./projectDiscovery";
-export type {
-  TtscProjectInputHashSnapshot,
-  TtscTransformFilesystemOperations,
-  TtscTransformHooks,
-  TtscWatchInput,
-  TtscWatchInputBaseline,
-  TtscWatchInputEvidence,
-  TtscWatchInputFileBaseline,
-  TtscWatchInputKeyBaseline,
-  TtscWatchInputState,
-} from "./transform";
-export type {
-  ITsconfigSourceSnapshotEntry,
-  ITtscProjectMembershipPolicy,
-} from "./tsconfigPaths";
-export {
-  mergeMembershipPolicyOverlay,
-  readProjectMembershipPolicy,
-  readTsconfigSourceSnapshot,
-} from "./tsconfigPaths";
-export {
-  beginTtscTransformBuild,
-  captureWatchInputBaseline,
-  captureWatchInputFileBaseline,
-  collectExternalInputHashes,
-  collectProjectInputHashSnapshot,
-  collectProjectInputHashes,
-  createTtscTransformCache,
-  isProjectWalkPath,
-  isWatchInputKeyBaseline,
-  resetTtscTransformCache,
-  resolveOptions,
-  transformTtsc,
-  unplugin,
-  watchInputEvidenceMatchesBaseline,
-};
-export {
-  discoverNearestProjectTsconfig,
-  findNearestProjectTsconfig,
-  findProjectTsconfigs,
-} from "./projectDiscovery";
-
-export default unplugin;
-
-/**
- * Returns `true` when the module id refers to a real TypeScript source file
- * that should be processed by the ttsc transform.
- *
- * TypeScript only. {@link sourceFilePattern} deliberately excludes JavaScript,
- * so a `.js` module reaches no adapter's transform, and this docstring used to
- * say otherwise while the pattern it is built from said the truth
- * (samchon/ttsc#1309).
- *
- * Also excluded: virtual modules (NUL prefix), `.d.ts` declaration files, and
- * anything inside `node_modules`.
- */
-export function isTransformTarget(id: string): boolean {
-  return (
-    sourceFilePattern.test(id) &&
-    !virtualModulePattern.test(id) &&
-    !isDeclarationFile(id) &&
-    !nodeModulesPattern.test(id)
-  );
-}
+export { fallbackToolDirectory } from "./bridge/fallbackToolDirectory";
+export { hostToolDirectory } from "./bridge/hostToolDirectory";
+export { PROJECT_RECORD_DIRECTORY } from "./bridge/PROJECT_RECORD_DIRECTORY";
+export { projectRecordFile } from "./bridge/projectRecordFile";
+export { projectRecordMoved } from "./bridge/projectRecordMoved";
+export { readProjectRecordFile } from "./bridge/readProjectRecordFile";
+export type { TtscProjectRecord } from "./bridge/TtscProjectRecord";
+export { discoverNearestProjectTsconfig } from "./discovery/discoverNearestProjectTsconfig";
+export { findNearestProjectTsconfig } from "./discovery/findNearestProjectTsconfig";
+export { findProjectTsconfigs } from "./discovery/findProjectTsconfigs";
+export type { TtscProjectDiscoveryFilesystem } from "./discovery/TtscProjectDiscoveryFilesystem";
+export type { TtscProjectTreeDiscoveryFilesystem } from "./discovery/TtscProjectTreeDiscoveryFilesystem";
+export type { TtscProjectTsconfigCandidate } from "./discovery/TtscProjectTsconfigCandidate";
+export type { TtscProjectTsconfigDiscovery } from "./discovery/TtscProjectTsconfigDiscovery";
+export { isTransformTarget } from "./isTransformTarget";
+export { resolveOptions } from "./options/resolveOptions";
+export type { TtscUnpluginCompilerOptionsJson } from "./options/TtscUnpluginCompilerOptionsJson";
+export type { TtscUnpluginOptions } from "./options/TtscUnpluginOptions";
+export { sourceFilePattern } from "./sourceFilePattern";
+export { beginTtscTransformBuild } from "./transform/cache/beginTtscTransformBuild";
+export { createTtscTransformCache } from "./transform/cache/createTtscTransformCache";
+export { resetTtscTransformCache } from "./transform/cache/resetTtscTransformCache";
+export type { TtscTransformFilesystemOperations } from "./transform/filesystem/TtscTransformFilesystemOperations";
+export { collectExternalInputHashes } from "./transform/project/collectExternalInputHashes";
+export { collectProjectInputHashes } from "./transform/project/collectProjectInputHashes";
+export { collectProjectInputHashSnapshot } from "./transform/project/collectProjectInputHashSnapshot";
+export { isProjectWalkPath } from "./transform/project/isProjectWalkPath";
+export type { TtscProjectInputHashSnapshot } from "./transform/project/TtscProjectInputHashSnapshot";
+export { transformTtsc } from "./transform/transformTtsc";
+export { captureWatchInputBaseline } from "./transform/watch/captureWatchInputBaseline";
+export { captureWatchInputFileBaseline } from "./transform/watch/captureWatchInputFileBaseline";
+export { isWatchInputKeyBaseline } from "./transform/watch/isWatchInputKeyBaseline";
+export type { TtscProjectRegistration } from "./transform/watch/TtscProjectRegistration";
+export type { TtscTransformHooks } from "./transform/watch/TtscTransformHooks";
+export type { TtscWatchInput } from "./transform/watch/TtscWatchInput";
+export type { TtscWatchInputBaseline } from "./transform/watch/TtscWatchInputBaseline";
+export type { TtscWatchInputEvidence } from "./transform/watch/TtscWatchInputEvidence";
+export type { TtscWatchInputFileBaseline } from "./transform/watch/TtscWatchInputFileBaseline";
+export type { TtscWatchInputKeyBaseline } from "./transform/watch/TtscWatchInputKeyBaseline";
+export type { TtscWatchInputState } from "./transform/watch/TtscWatchInputState";
+export { openTtscTransformSession } from "./transform/session/openTtscTransformSession";
+export { readTtscTransformSession } from "./transform/session/readTtscTransformSession";
+export { shareTtscTransformCache } from "./transform/session/shareTtscTransformCache";
+export { watchInputEvidenceMatchesBaseline } from "./transform/watch/watchInputEvidenceMatchesBaseline";
+export type { ITsconfigSourceSnapshotEntry } from "./tsconfig/ITsconfigSourceSnapshotEntry";
+export type { ITtscProjectMembershipPolicy } from "./tsconfig/ITtscProjectMembershipPolicy";
+export { mergeMembershipPolicyOverlay } from "./tsconfig/mergeMembershipPolicyOverlay";
+export { readProjectMembershipPolicy } from "./tsconfig/readProjectMembershipPolicy";
+export { readTsconfigSourceSnapshot } from "./tsconfig/readTsconfigSourceSnapshot";
+export { searchedReferencedProjects } from "./tsconfig/searchedReferencedProjects";
+export { selectReferencedProject } from "./tsconfig/selectReferencedProject";
+export { unplugin, unplugin as default } from "./unplugin";

package/src/core/isTransformTarget.ts

@@ -0,0 +1,58 @@
+import { sourceFilePattern } from "./sourceFilePattern";
+import { isDeclarationFile } from "./transform/utils/isDeclarationFile";
+
+/** Matches any path segment that is a `node_modules` directory (cross-platform). */
+const nodeModulesPattern = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
+
+/**
+ * Matches virtual module ids: Rollup/Vite use a leading NUL byte (`\0`) as
+ * convention.
+ */
+const virtualModulePattern = /\0/;
+
+/**
+ * Classify whether the supplied module identifier belongs to the transform's
+ * TypeScript source syntax. This does not probe native existence or
+ * readability.
+ *
+ * {@link sourceFilePattern} deliberately excludes JavaScript, so a `.js` module
+ * reaches no adapter's transform.
+ *
+ * Also excluded: identifiers containing NUL, declaration basenames, and exact
+ * `node_modules` components under either module-id separator spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   The shared extension predicate admits TypeScript source, then NUL ids,
+ *   declaration basenames and complete node_modules segments are rejected.
+ *   Both slash spellings belong to module-id syntax, independent of host OS.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One predicate owns adapter inclusion; declaration classification delegates
+ *   to its dedicated helper instead of duplicating suffix policy per host.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   node_modules and virtual identifiers are contractual ownership boundaries,
+ *   not fixture paths or consumer names.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain TypeScript-only ownership and exclusions, with
+ *   descriptive prose separated from tags per documentation guidance.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Classifies bundler identifier syntax, including both slash spellings,
+ *   without deciding native filesystem identity or case policy.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Fixed regular expressions and declaration-basename checks each scan at
+ *   most the identifier length. Short-circuit rejection avoids subsequent
+ *   scans. Declaration classification additionally allocates normalized text
+ *   and extracts its basename; temporary text follows identifier length. No
+ *   filesystem lookup or per-call pattern construction occurs.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function isTransformTarget(id: string): boolean {
+  return (
+    sourceFilePattern.test(id) &&
+    !virtualModulePattern.test(id) &&
+    !isDeclarationFile(id) &&
+    !nodeModulesPattern.test(id)
+  );
+}