ttsc 0.30.4 → 0.31.1

package/lib/plugin/internal/source/SourceBuildCacheLayout.js

@@ -0,0 +1,291 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceBuildCacheLayout = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const SidecarEnvironment_1 = require("../../../compiler/internal/sharedHost/SidecarEnvironment");
+const pruneCacheFileRoot_1 = require("./pruneCacheFileRoot");
+const pruneGoBuildCacheRoot_1 = require("./pruneGoBuildCacheRoot");
+const prunePluginCacheRoot_1 = require("./prunePluginCacheRoot");
+/**
+ * The layout of ttsc's source-plugin cache and the file operations its
+ * maintenance shares.
+ *
+ * The default cache lives inside the workspace, at
+ * `<workspaceRoot>/node_modules/.cache/ttsc`, so removing `node_modules` (or
+ * the repository) reclaims the binaries and default Go objects stored there.
+ * Dedicated or caller-owned Go cache overrides can live elsewhere. This is the
+ * `find-cache-dir` convention (Babel, webpack, ESLint, Nuxt): a disposable
+ * build cache under `node_modules/.cache/<tool>`. ttsc keeps no automatic
+ * global (`~/.cache`) cache, because a machine-wide one would grow across tsgo
+ * and plugin version bumps without an owner to reclaim it. See
+ * `resolveSourceBuildCachePaths` for the override-then-workspace priority.
+ *
+ * @evidence contracts/common.md#principled-implementation Named cache parts separate compiled binaries, Go objects and serialized answers whose owners and retention policies differ.
+ * @evidence contracts/common.md#clear-and-simple-design Shared path names and metadata primitives live together; each collector retains its own selection policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Directory and marker names define the persisted layout, and filesystem mutations use owned entries rather than patching foreign APIs.
+ * @evidence contracts/common.md#meaningful-documentation Native prose locates the workspace cache and explains its disposable lifetime; public constant comments describe their payloads with separated members under the documentation guidance.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path construction, directory-entry inspection and atomic rename are delegated to Node APIs; layout names are protocol components rather than platform separators.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The namespace groups separately owned operations; grouping itself does not run a traversal.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Layout names do not establish computation identity or validity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace has no acquired state; its maintenance operations own reclamation decisions.
+ */
+var SourceBuildCacheLayout;
+(function (SourceBuildCacheLayout) {
+    const DEFAULT_WORKSPACE_CACHE_MARKER = ".workspace-root";
+    /** Directory name the workspace-local cache is placed under. */
+    SourceBuildCacheLayout.NODE_MODULES_DIRNAME = "node_modules";
+    /** Directory name of ttsc's cache root below `node_modules/.cache`. */
+    SourceBuildCacheLayout.TTSC_CACHE_DIRNAME = "ttsc";
+    /** Directory name of ttsc's own Go object cache inside the cache root. */
+    SourceBuildCacheLayout.GO_BUILD_CACHE_DIRNAME = "go-build";
+    /** File inside a plugin cache entry recording when it was last used. */
+    SourceBuildCacheLayout.CACHE_LAST_USED_FILE = ".last-used";
+    /** Directory of the descriptor evaluation answers inside the cache root. */
+    SourceBuildCacheLayout.DESCRIPTOR_CACHE_DIRNAME = "descriptors";
+    /** Directory of the capability-resolution answers inside the cache root. */
+    SourceBuildCacheLayout.CAPABILITY_CACHE_DIRNAME = "capabilities";
+    /** Directory of the ttsx runtime inside the cache root. */
+    SourceBuildCacheLayout.RUNTIME_CACHE_DIRNAME = "ttsx";
+    /**
+     * Directory inside a runtime cache directory that holds one directory per
+     * prepared run, owned by the processes of that run.
+     */
+    SourceBuildCacheLayout.RUNTIME_PROJECT_DIRNAME = "project";
+    /** Directory of the lowered orphan sources inside the cache root. */
+    SourceBuildCacheLayout.ORPHAN_CACHE_DIRNAME = "ttsx-orphan";
+    /**
+     * The parts of the cache root whose entries are single files, each collected
+     * by `pruneCacheFileRoot` and removed by `ttsc clean`.
+     */
+    SourceBuildCacheLayout.CACHE_FILE_DIRNAMES = [
+        SourceBuildCacheLayout.DESCRIPTOR_CACHE_DIRNAME,
+        SourceBuildCacheLayout.CAPABILITY_CACHE_DIRNAME,
+        SourceBuildCacheLayout.ORPHAN_CACHE_DIRNAME,
+    ];
+    /**
+     * Run the opportunistic pruning of the plugin cache, of ttsc's Go object
+     * cache, and of the single-file caches (`CACHE_FILE_DIRNAMES`), but only for
+     * the default workspace-local location. A root the caller named through
+     * `cacheDir` or `TTSC_CACHE_DIR` is theirs, and this opportunistic
+     * maintenance skips it. Explicit clean requests follow the separate cleanup
+     * contract.
+     *
+     * @evidence contracts/common.md#principled-implementation Pruning is admitted only for an unoverridden workspace root, and Go objects are admitted only when their provenance is ttsc-cache.
+     * @evidence contracts/common.md#clear-and-simple-design This ownership gate dispatches to dedicated binary, object and file collectors without duplicating their eviction policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Effective environment injection is a supported host boundary; explicit user-owned roots are deliberately protected.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain default-root ownership and why overrides suppress maintenance; prose and tags are visibly separated.
+     * @evidence contracts/portability.md#os-neutral-implementation The gate reads injected environment values with Windows case-insensitive names and uses path-aware collector APIs without separator assumptions.
+     * @evidence contracts/performance.md#efficient-algorithms A fixed ownership branch reads the injected environment; Windows name matching scans its keys and text. Admitted collectors additionally perform native metadata/ownership scans, optional entry sorts and recursive deletion, with path/text and retained-entry costs. Delegated ownership retries can lack a deadline; fixed dispatch count does not bound collector work.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This dispatch does not produce or validate a reusable computation result.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Default binary and answer collectors attempt opportunistic reclamation; explicit roots remain caller-owned. Live or unknown owners, protected entries, failures and future-invocation pacing can retain payloads or ownership records without a finite bound; this dispatch acquires no independent handle.
+     */
+    function maybePruneSourceBuildCaches(paths, cacheDir, env = process.env) {
+        // GC only the default (workspace-local) location. When the user pins an
+        // explicit `cacheDir`/`TTSC_CACHE_DIR`, they own its lifetime, so ttsc must
+        // not delete entries out from under them. `env` is the effective instance
+        // environment so a programmatic caller that pins `TTSC_CACHE_DIR` only in
+        // `context.env` is honored without leaning on the shared `process.env`.
+        if (!cacheDir && !SidecarEnvironment_1.SidecarEnvironment.read(env, "TTSC_CACHE_DIR")) {
+            (0, prunePluginCacheRoot_1.prunePluginCacheRoot)(paths.pluginRoot);
+            if (paths.goBuildRootSource === "ttsc-cache") {
+                (0, pruneGoBuildCacheRoot_1.pruneGoBuildCacheRoot)(paths.goBuildRoot);
+            }
+            pruneCacheFiles(paths.root);
+        }
+    }
+    SourceBuildCacheLayout.maybePruneSourceBuildCaches = maybePruneSourceBuildCaches;
+    /**
+     * Apply the opportunistic collector to each single-file part
+     * (`CACHE_FILE_DIRNAMES`) of `root`.
+     *
+     * @evidence contracts/common.md#principled-implementation Each declared answer-cache part receives the same single-file collector independently of binary and runtime directories; that owner decides interval admission, protection and tolerated deletion failure rather than this adapter guaranteeing reclamation.
+     * @evidence contracts/common.md#clear-and-simple-design One loop over the layout's fixed part list centralizes maintenance dispatch.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The part list is the persisted layout contract, not a list of recognized projects or expected answers.
+     * @evidence contracts/common.md#meaningful-documentation The native comment identifies the collected population and references the owning layout constant; tags follow a blank comment line.
+     * @evidence contracts/portability.md#os-neutral-implementation path.join constructs native children; directory checks and deletion policy stay in the collector.
+     * @evidence contracts/performance.md#efficient-algorithms Dispatch visits the fixed part list and constructs native child paths with work proportional to their text. Admitted collectors additionally pay their metadata/filename scans and optional entry sorts; payload population is not bounded by the part count.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work A maintenance pass has filesystem effects and cannot be reused merely because it returns void.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Each serialized-answer population receives age/size reclamation, with recent-use protection and failed deletes explicitly allowed to defer reclamation.
+     */
+    function pruneCacheFiles(root) {
+        for (const name of SourceBuildCacheLayout.CACHE_FILE_DIRNAMES)
+            (0, pruneCacheFileRoot_1.pruneCacheFileRoot)(node_path_1.default.join(root, name));
+    }
+    SourceBuildCacheLayout.pruneCacheFiles = pruneCacheFiles;
+    /**
+     * Record that `root` was selected as a default workspace-local cache root.
+     *
+     * The marker keeps an intentionally empty `node_modules` authoritative after
+     * its first cache write changes its sole payload to `.cache/ttsc`. Creation
+     * is exclusive so concurrent first writers never follow or replace an
+     * existing filesystem entry. The selected root is pinned to its ordinary
+     * physical spelling before publication; default writers use that returned
+     * spelling for their payload too. Metadata checks do not hold a directory
+     * handle that prevents concurrent replacement of the selected path.
+     *
+     * @evidence contracts/common.md#principled-implementation Current ordinary-root metadata and physical spelling precede exclusive marker creation, recording the selected installation boundary. The producer uses the returned spelling; continued root identity requires that the path not be concurrently replaced, rather than a retained directory-handle proof.
+     * @evidence contracts/common.md#clear-and-simple-design Marker publication and existing-entry validation return one physical root for the caller's payload.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker represents an actual prior selection and is not fabricated workspace detection for particular consumers.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain first-write placement stability, current root validation and the path-replacement limit before exclusive marker publication.
+     * @evidence contracts/portability.md#os-neutral-implementation Native lstat/realpath observe ordinary-root identity and Node's wx creation refuses an existing marker without OS-based case assumptions; these calls do not freeze parent-directory identity.
+     * @evidence contracts/performance.md#efficient-algorithms Publication uses a fixed number of filesystem operations plus ordinary-root validation; recursive parent creation scales with missing path depth.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This operation persists installation provenance, not a computed answer whose inputs can be shared.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources At most one marker is retained per root and is reclaimed with that root; synchronous filesystem calls retain no open handle.
+     */
+    function markDefaultWorkspaceCacheRoot(root) {
+        const physicalRoot = canonicalPluginCacheRoot(root);
+        const marker = node_path_1.default.join(physicalRoot, DEFAULT_WORKSPACE_CACHE_MARKER);
+        try {
+            node_fs_1.default.writeFileSync(marker, "1\n", { encoding: "utf8", flag: "wx" });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const stats = node_fs_1.default.lstatSync(marker);
+            if (!stats.isFile() || stats.isSymbolicLink()) {
+                throw new Error(`ttsc: unsafe workspace cache marker: ${marker}`);
+            }
+        }
+        return physicalRoot;
+    }
+    SourceBuildCacheLayout.markDefaultWorkspaceCacheRoot = markDefaultWorkspaceCacheRoot;
+    /**
+     * Report whether one collected directory listing is empty or has a marker.
+     *
+     * An empty root is the state after root creation and before marker
+     * publication. One listing avoids combining separate marker and emptiness
+     * probes; it does not freeze directory contents or prove later ownership.
+     *
+     * @evidence contracts/common.md#principled-implementation Emptiness and ordinary-marker admission use the same collected Dirent list, avoiding separate observations. The result is placement evidence at that read, not an atomic filesystem snapshot or continuing ownership guarantee.
+     * @evidence contracts/common.md#clear-and-simple-design Emptiness and marker recognition are derived from the same local array.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The marker is protocol provenance; no project name or fixture-specific filesystem shape is privileged.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains the concurrent publication interval that makes a single snapshot necessary.
+     * @evidence contracts/portability.md#os-neutral-implementation Dirent type checks reject a symbolic marker using native filesystem facts instead of platform labels.
+     * @evidence contracts/performance.md#efficient-algorithms One directory listing and linear marker search retain O(entries) references plus returned filename text; listing and equality costs include the visited names and native filesystem work, with no recursive payload traversal.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The current directory state is queried afresh because marker publication can change its answer.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This query retains no resource beyond its local directory snapshot.
+     */
+    function isEmptyOrMarkedDefaultWorkspaceCacheRoot(root) {
+        const entries = node_fs_1.default.readdirSync(root, { withFileTypes: true });
+        if (entries.length === 0)
+            return true;
+        const marker = entries.find((entry) => entry.name === DEFAULT_WORKSPACE_CACHE_MARKER);
+        return marker !== undefined && marker.isFile() && !marker.isSymbolicLink();
+    }
+    SourceBuildCacheLayout.isEmptyOrMarkedDefaultWorkspaceCacheRoot = isEmptyOrMarkedDefaultWorkspaceCacheRoot;
+    /**
+     * Resolve the current default plugin cache to an ordinary physical spelling.
+     * Missing root directories are created. Returned spelling avoids following
+     * the caller's original ancestor alias again, but no retained directory
+     * handle prevents later replacement of the physical path.
+     *
+     * @evidence contracts/common.md#principled-implementation lstat rejects an aliased leaf and realpath checks the current root against its observed physical parent. The returned spelling removes the original ancestor alias from later lookups, subject to path identity remaining stable after these non-atomic metadata observations.
+     * @evidence contracts/common.md#clear-and-simple-design This boundary returns a physical spelling or throws; downstream collectors receive no partially validated path state.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Filesystem identity comes from actual entry types and realpath rather than special-cased path strings.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states creation, current physical spelling and the absence of a directory-handle identity pin; the inline comment explains avoidance of the original ancestor alias.
+     * @evidence contracts/portability.md#os-neutral-implementation Native realpath and lstat handle physical paths and links; textual equality here compares resolved parent spellings and does not infer volume case policy from an OS name.
+     * @evidence contracts/performance.md#efficient-algorithms A fixed number of metadata operations performs validation, with path resolution and recursive creation dependent on ancestor depth.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Mutable aliases are validated per invocation rather than memoized without an invalidation witness.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This operation returns a path and retains no handles or root history. Created directories belong to the selected cache owner; their lifetime and eviction remain with that caller's cache policy.
+     */
+    function canonicalPluginCacheRoot(root) {
+        node_fs_1.default.mkdirSync(root, { recursive: true });
+        const physicalParent = node_fs_1.default.realpathSync.native(node_path_1.default.dirname(root));
+        const stats = node_fs_1.default.lstatSync(root);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error(`ttsc: unsafe plugin cache root: ${root}`);
+        }
+        // Later lookups use this resolved spelling instead of the caller's original
+        // ancestor alias; this is not a handle pin against physical-path replacement.
+        const physicalRoot = node_fs_1.default.realpathSync.native(root);
+        if (node_path_1.default.dirname(physicalRoot) !== physicalParent) {
+            throw new Error(`ttsc: plugin cache root escaped its parent: ${root}`);
+        }
+        return physicalRoot;
+    }
+    SourceBuildCacheLayout.canonicalPluginCacheRoot = canonicalPluginCacheRoot;
+    /**
+     * The millisecond timestamp a metadata file records, falling back to its
+     * mtime when content reading fails or trimmed content is empty or nonfinite.
+     * Returns `null` only when content supplies no timestamp and stat also fails.
+     * Numeric text uses JavaScript Number conversion, without an integer, range
+     * or decimal-only admission rule.
+     *
+     * @evidence contracts/common.md#principled-implementation Nonempty finite Number-convertible text supplies the timestamp; failed content reads, blank text and nonfinite values fall back to native mtime, and only failed stat after that absence yields null. This reader does not validate chronology or impose a numeric range.
+     * @evidence contracts/common.md#clear-and-simple-design Content parsing and metadata fallback are two explicit stages with one nullable result.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Number parsing observes actual stored metadata; no known timestamps or cache keys receive special treatment.
+     * @evidence contracts/common.md#meaningful-documentation Native documentation states timestamp units, the fallback and the unavailable outcome, separated from tags.
+     * @evidence contracts/portability.md#os-neutral-implementation Node reads UTF-8 metadata and exposes mtimeMs consistently; no native date string or filesystem case convention is assumed.
+     * @evidence contracts/performance.md#efficient-algorithms The synchronous read decodes the complete metadata, then trimming and Number conversion inspect its text, with temporary storage proportional to read bytes/text and at most one fallback stat. Supplied path work and native reads are additional costs; the reader enforces no metadata-size cap.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current timestamps change on hits and maintenance, so this reader does not cache its answer.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous reads leave no retained handle or history.
+     */
+    function readTimestamp(file) {
+        try {
+            const text = node_fs_1.default.readFileSync(file, "utf8").trim();
+            const value = Number(text);
+            if (text.length !== 0 && Number.isFinite(value)) {
+                return value;
+            }
+        }
+        catch { }
+        try {
+            return node_fs_1.default.statSync(file).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    }
+    SourceBuildCacheLayout.readTimestamp = readTimestamp;
+    /**
+     * Replace cache metadata without following a pre-existing link or hard link.
+     *
+     * The caller supplies an owned, already selected parent directory. Replacing
+     * its terminal entry does not authorize writes through an arbitrary parent.
+     *
+     * @evidence contracts/common.md#principled-implementation An exclusive sibling staging file is renamed over the target entry, preserving complete publication and avoiding writes through the old inode's aliases.
+     * @evidence contracts/common.md#clear-and-simple-design Creation, publication and unconditional staging cleanup are contained in one try/finally.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Process identity and random bytes give independent sibling-name candidates, with exclusive creation refusing an occupied candidate; this is not a proof that names can never collide. Publication errors propagate rather than fabricate successful metadata.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish terminal-entry replacement from parent ownership, and inline prose explains why rename avoids alias mutation.
+     * @evidence contracts/portability.md#os-neutral-implementation Same-directory rename and exclusive creation use Node's native semantics; failure on locked Windows entries propagates to the owner's policy.
+     * @evidence contracts/performance.md#efficient-algorithms One contents write, one rename and one cleanup include supplied path/name and contents text work, plus fixed-size random sibling-name generation and native filesystem operations. The existing entry's contents are not copied.
+     *
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Each publication changes filesystem state and cannot be shared by equal return values.
+     *
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Finally attempts removal of the staging candidate after success or failure, without retaining a handle or history. This assumes that independently chosen candidate belongs to this publication; cleanup errors can leave it for the owning cache collector, and no numeric bound on failed leftovers is established here.
+     */
+    function replaceCacheMetadataFile(file, contents) {
+        const temporary = node_path_1.default.join(node_path_1.default.dirname(file), `.${node_path_1.default.basename(file)}.${process.pid}-${node_crypto_1.default
+            .randomBytes(16)
+            .toString("hex")}.tmp`);
+        try {
+            node_fs_1.default.writeFileSync(temporary, contents, { encoding: "utf8", flag: "wx" });
+            // rename replaces the directory entry itself. Unlike writeFile(file), it
+            // cannot follow a symlink or mutate another hard link to the old inode.
+            node_fs_1.default.renameSync(temporary, file);
+        }
+        finally {
+            try {
+                node_fs_1.default.rmSync(temporary, { force: true });
+            }
+            catch { }
+        }
+    }
+    SourceBuildCacheLayout.replaceCacheMetadataFile = replaceCacheMetadataFile;
+})(SourceBuildCacheLayout || (exports.SourceBuildCacheLayout = SourceBuildCacheLayout = {}));
+//# sourceMappingURL=SourceBuildCacheLayout.js.map

package/lib/plugin/internal/source/SourceBuildCacheLayout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceBuildCacheLayout.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/SourceBuildCacheLayout.ts"],"names":[],"mappings":"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"}

package/lib/plugin/internal/source/SourceBuildFilesystemOperations.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Synchronous filesystem reads used to fingerprint external Go toolchains.
+ *
+ * The key accepts a byte reader so external toolchain fingerprinting has one
+ * explicit filesystem dependency. Production supplies `fs.readFileSync`.
+ *
+ * @evidence contracts/common.md#principled-implementation The synchronous Buffer-returning method preserves the exact file bytes used for the Go root content identity, including ordinary read failures.
+ * @evidence contracts/common.md#clear-and-simple-design The boundary contains only the byte-read operation that hashing consumes; metadata and enumeration remain with native identity validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Injection replaces an owned dependency explicitly rather than patching fs globals or adding a production path for an expected test result.
+ * @evidence contracts/common.md#meaningful-documentation The owning prose identifies the fingerprinting dependency and its production reader; the member states byte-read semantics.
+ * @evidence contracts/portability.md#os-neutral-implementation The reader receives native file locations and returns unmodified bytes through Node's filesystem API; path and case interpretation are not reimplemented by this interface.
+ *
+ * @evidenceExclude contracts/performance.md#efficient-algorithms The boundary type does not choose the hasher's traversal or processing strategy.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The interface supplies reads and owns no shared computation or cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Implementations and enclosing calls own read resources; the declaration retains no handle.
+ */
+export interface SourceBuildFilesystemOperations {
+    /**
+     * Read a file's bytes, as `fs.readFileSync` does.
+     *
+     * @evidence contracts/common.md#principled-implementation Synchronous byte reads provide the file content that the enclosing fingerprint computation hashes and propagate unreadable-file errors.
+     * @evidence contracts/common.md#clear-and-simple-design One argument and one Buffer result express the required read capability without an asynchronous adapter.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Callers supply this capability explicitly instead of replacing foreign filesystem methods.
+     * @evidence contracts/common.md#meaningful-documentation The method names its byte-read and fs.readFileSync semantics in native JSDoc.
+     * @evidence contracts/portability.md#os-neutral-implementation The native location is passed to the filesystem reader unchanged rather than interpreted as a URL or slash-only protocol path.
+     *
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This signature supplies byte access; the owning hash traversal chooses the processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The reader does not coordinate requests or cache completed values.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The signature owns no file handle or retained value; synchronous implementations complete each read before returning.
+     */
+    readFile(location: string): Buffer;
+}

package/lib/plugin/internal/source/SourceBuildFilesystemOperations.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=SourceBuildFilesystemOperations.js.map

package/lib/plugin/internal/source/SourceBuildFilesystemOperations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceBuildFilesystemOperations.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/SourceBuildFilesystemOperations.ts"],"names":[],"mappings":""}

package/lib/plugin/internal/source/SourcePluginAdmission.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Reject source-build input conflicts at their existing admission points.
+ * Existing readers/builders still acquire module information and materialize
+ * sources; these operations establish admission of the inputs they receive.
+ *
+ * @evidence contracts/common.md#principled-implementation The real builder uses package, cache-containment and managed-replacement checks at their existing acquisition boundaries.
+ * @evidence contracts/common.md#clear-and-simple-design One source admission concern groups rejection policy without a toolchain or build executor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Admission does not replace native acquisition, certify a supplied proof or fabricate compiled output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates supplied/read inputs from source materialization and compilation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace groups members; members own native path/file decisions.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own their processing decisions rather than this grouping.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This grouping owns no shared build/evaluation cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry, open handle or retained task.
+ */
+export declare namespace SourcePluginAdmission {
+    /**
+     * Refuse a contributor whose source root has its own go.mod. The observation
+     * is existence only, as in the original merge loop; copying and compilation
+     * remain later builder operations.
+     *
+     * @evidence contracts/common.md#principled-implementation Native existence at the exact contributor-root go.mod rejects module ownership before that contributor is copied into the host module.
+     * @evidence contracts/common.md#clear-and-simple-design One observed package-admission guard retains the original named diagnostic.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No compiler, toolchain probe or supplied success marker replaces the actual existence observation.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states existence-only observation and separates later copying/building.
+     * @evidence contracts/portability.md#os-neutral-implementation node:path joins the native root and basename; node:fs observes native existence without separator or case assumptions.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This single native metadata admission owns no population-processing algorithm; native lookup work is delegated to fs.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current native existence is required and is not cached by this guard.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The existence query opens no caller-owned handle and retains no source population.
+     */
+    function requireContributorPackage(pluginName: string, contributor: {
+        readonly name: string;
+        readonly source: string;
+    }): void;
+    /**
+     * Refuse caches among source directories included by the key's path policy.
+     * Excluded directories such as node_modules retain that policy's meaning;
+     * this lexical containment is not proof of physical alias identity.
+     *
+     * @evidence contracts/common.md#principled-implementation Each cache/source pair uses the same directory-kind pluginSourceCovers policy as source inclusion, rejecting a cache that would mutate its keyed source.
+     * @evidence contracts/common.md#clear-and-simple-design One guard owns pair ordering and the diagnostic naming the conflicting cache/source.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No key or compiler output is assumed valid merely because a path passes lexical containment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states source inclusion, excluded-directory behavior and the physical-identity limitation.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve and pluginSourceCovers preserve the current native path grammar without universal case folding.
+     * @evidence contracts/performance.md#efficient-algorithms Up to C times S pair checks delegate path-relative/component scans; an admitted population performs all pairs and the first conflict throws, without filesystem enumeration.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current supplied roots are checked directly; this guard does not cache source keys or compiled results.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Pair traversal retains no root history or native handle; diagnostic/result lifetime belongs to the caller.
+     */
+    function requireCachesOutsideSources(caches: readonly string[], sources: readonly string[]): void;
+    /**
+     * Identify compiler/shim module names whose replacement ttsc owns. This is
+     * module-name policy, not a lookup of a physical Go module.
+     *
+     * @evidence contracts/common.md#principled-implementation Exact ttsc/compiler roots and the compiler shim namespace retain the existing managed-module discriminants.
+     * @evidence contracts/common.md#clear-and-simple-design Both replacement rejection and workspace filtering use this same predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Module-name policy does not fabricate filesystem module identity or compiled provenance.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes module-name classification from physical lookup.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Go module identifiers are supplied strings, not native filesystem paths.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Exact/prefix string comparisons own no population-processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current module text is classified without retained lookup results.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No native handle, module registry or task is acquired or retained.
+     */
+    function isManagedModule(modulePath: string): boolean;
+    /**
+     * Reject managed or overlay module replacements observed in source go.mod.
+     * The caller retains its ttsc-root exemption and acquires overlay names only
+     * after finding source replacements, preserving reader effect ordering.
+     *
+     * @evidence contracts/common.md#principled-implementation The first source replacement matching managed-name policy or the acquired overlay set produces the original rejection diagnostic.
+     * @evidence contracts/common.md#clear-and-simple-design This operation consumes observed module names while the real reader remains with the builder.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied replacement records do not certify their native acquisition or replace a Go compiler.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the caller's root exemption and acquisition-order responsibility.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Supplied Go module identifiers are compared without filesystem paths or native process calls.
+     * @evidence contracts/performance.md#efficient-algorithms One ordered pass over R replacement records delegates string classification and Set membership, throwing at the first forbidden record without copying the population.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This decision consumes current supplied observations and retains no cross-build cache.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This guard retains no replacement history, native handle or task.
+     */
+    function requireSourceReplacements(replacements: readonly {
+        readonly modulePath: string;
+    }[], overlayModules: ReadonlySet<string>, pluginName: string): void;
+}

package/lib/plugin/internal/source/SourcePluginAdmission.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourcePluginAdmission = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const pluginSourceCovers_1 = require("./pluginSourceCovers");
+/**
+ * Reject source-build input conflicts at their existing admission points.
+ * Existing readers/builders still acquire module information and materialize
+ * sources; these operations establish admission of the inputs they receive.
+ *
+ * @evidence contracts/common.md#principled-implementation The real builder uses package, cache-containment and managed-replacement checks at their existing acquisition boundaries.
+ * @evidence contracts/common.md#clear-and-simple-design One source admission concern groups rejection policy without a toolchain or build executor.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Admission does not replace native acquisition, certify a supplied proof or fabricate compiled output.
+ * @evidence contracts/common.md#meaningful-documentation Native prose separates supplied/read inputs from source materialization and compilation.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation The namespace groups members; members own native path/file decisions.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms Members own their processing decisions rather than this grouping.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This grouping owns no shared build/evaluation cache.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The namespace owns no registry, open handle or retained task.
+ */
+var SourcePluginAdmission;
+(function (SourcePluginAdmission) {
+    /**
+     * Refuse a contributor whose source root has its own go.mod. The observation
+     * is existence only, as in the original merge loop; copying and compilation
+     * remain later builder operations.
+     *
+     * @evidence contracts/common.md#principled-implementation Native existence at the exact contributor-root go.mod rejects module ownership before that contributor is copied into the host module.
+     * @evidence contracts/common.md#clear-and-simple-design One observed package-admission guard retains the original named diagnostic.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No compiler, toolchain probe or supplied success marker replaces the actual existence observation.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states existence-only observation and separates later copying/building.
+     * @evidence contracts/portability.md#os-neutral-implementation node:path joins the native root and basename; node:fs observes native existence without separator or case assumptions.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms This single native metadata admission owns no population-processing algorithm; native lookup work is delegated to fs.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current native existence is required and is not cached by this guard.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The existence query opens no caller-owned handle and retains no source population.
+     */
+    function requireContributorPackage(pluginName, contributor) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(contributor.source, "go.mod")))
+            throw new Error(`ttsc: plugin "${pluginName}" contributor "${contributor.name}" must ship Go ` +
+                `source as a package, not a module (go.mod found at ${contributor.source}/go.mod). ` +
+                `Remove go.mod so the contributor compiles inside the host module's dependency graph.`);
+    }
+    SourcePluginAdmission.requireContributorPackage = requireContributorPackage;
+    /**
+     * Refuse caches among source directories included by the key's path policy.
+     * Excluded directories such as node_modules retain that policy's meaning;
+     * this lexical containment is not proof of physical alias identity.
+     *
+     * @evidence contracts/common.md#principled-implementation Each cache/source pair uses the same directory-kind pluginSourceCovers policy as source inclusion, rejecting a cache that would mutate its keyed source.
+     * @evidence contracts/common.md#clear-and-simple-design One guard owns pair ordering and the diagnostic naming the conflicting cache/source.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No key or compiler output is assumed valid merely because a path passes lexical containment.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states source inclusion, excluded-directory behavior and the physical-identity limitation.
+     * @evidence contracts/portability.md#os-neutral-implementation Native path.resolve and pluginSourceCovers preserve the current native path grammar without universal case folding.
+     * @evidence contracts/performance.md#efficient-algorithms Up to C times S pair checks delegate path-relative/component scans; an admitted population performs all pairs and the first conflict throws, without filesystem enumeration.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current supplied roots are checked directly; this guard does not cache source keys or compiled results.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Pair traversal retains no root history or native handle; diagnostic/result lifetime belongs to the caller.
+     */
+    function requireCachesOutsideSources(caches, sources) {
+        for (const cache of caches)
+            for (const source of sources)
+                if ((0, pluginSourceCovers_1.pluginSourceCovers)(source, node_path_1.default.resolve(cache), "directory"))
+                    throw new Error(`ttsc: the cache ${cache} lies inside the plugin source ${source}, ` +
+                        `which the plugin's binary is keyed on, so every build would change ` +
+                        `the source it was keyed on. Place the cache outside the plugin's ` +
+                        `sources; the default one, in node_modules, already is.`);
+    }
+    SourcePluginAdmission.requireCachesOutsideSources = requireCachesOutsideSources;
+    /**
+     * Identify compiler/shim module names whose replacement ttsc owns. This is
+     * module-name policy, not a lookup of a physical Go module.
+     *
+     * @evidence contracts/common.md#principled-implementation Exact ttsc/compiler roots and the compiler shim namespace retain the existing managed-module discriminants.
+     * @evidence contracts/common.md#clear-and-simple-design Both replacement rejection and workspace filtering use this same predicate.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Module-name policy does not fabricate filesystem module identity or compiled provenance.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes module-name classification from physical lookup.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Go module identifiers are supplied strings, not native filesystem paths.
+     * @evidenceExclude contracts/performance.md#efficient-algorithms Exact/prefix string comparisons own no population-processing strategy.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Current module text is classified without retained lookup results.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No native handle, module registry or task is acquired or retained.
+     */
+    function isManagedModule(modulePath) {
+        return (modulePath === "github.com/samchon/ttsc/packages/ttsc" ||
+            modulePath === "github.com/microsoft/typescript-go" ||
+            modulePath.startsWith("github.com/microsoft/typescript-go/shim/"));
+    }
+    SourcePluginAdmission.isManagedModule = isManagedModule;
+    /**
+     * Reject managed or overlay module replacements observed in source go.mod.
+     * The caller retains its ttsc-root exemption and acquires overlay names only
+     * after finding source replacements, preserving reader effect ordering.
+     *
+     * @evidence contracts/common.md#principled-implementation The first source replacement matching managed-name policy or the acquired overlay set produces the original rejection diagnostic.
+     * @evidence contracts/common.md#clear-and-simple-design This operation consumes observed module names while the real reader remains with the builder.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Supplied replacement records do not certify their native acquisition or replace a Go compiler.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the caller's root exemption and acquisition-order responsibility.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Supplied Go module identifiers are compared without filesystem paths or native process calls.
+     * @evidence contracts/performance.md#efficient-algorithms One ordered pass over R replacement records delegates string classification and Set membership, throwing at the first forbidden record without copying the population.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This decision consumes current supplied observations and retains no cross-build cache.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This guard retains no replacement history, native handle or task.
+     */
+    function requireSourceReplacements(replacements, overlayModules, pluginName) {
+        for (const replacement of replacements)
+            if (isManagedModule(replacement.modulePath) ||
+                overlayModules.has(replacement.modulePath))
+                throw new Error(`ttsc: plugin "${pluginName}" go.mod replaces ttsc-managed module ` +
+                    `${JSON.stringify(replacement.modulePath)}. Remove this replace directive; ` +
+                    `ttsc supplies its own compiler and shim modules while building source plugins.`);
+    }
+    SourcePluginAdmission.requireSourceReplacements = requireSourceReplacements;
+})(SourcePluginAdmission || (exports.SourcePluginAdmission = SourcePluginAdmission = {}));
+//# sourceMappingURL=SourcePluginAdmission.js.map

package/lib/plugin/internal/source/SourcePluginAdmission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourcePluginAdmission.js","sourceRoot":"","sources":["../../../../src/plugin/internal/source/SourcePluginAdmission.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,0DAA6B;AAE7B,6DAA0D;AAE1D;;;;;;;;;;;;;GAaG;AACH,IAAiB,qBAAqB,CA2GrC;AA3GD,WAAiB,qBAAqB;IACpC;;;;;;;;;;;;;OAaG;IACH,SAAgB,yBAAyB,CACvC,UAAkB,EAClB,WAA+D;QAE/D,IAAI,iBAAE,CAAC,UAAU,CAAC,mBAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACxD,MAAM,IAAI,KAAK,CACb,iBAAiB,UAAU,kBAAkB,WAAW,CAAC,IAAI,iBAAiB;gBAC5E,sDAAsD,WAAW,CAAC,MAAM,YAAY;gBACpF,sFAAsF,CACzF,CAAC;IACN,CAAC;IAVe,sBAAA,yBAAyB,4BAUxC,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,2BAA2B,CACzC,MAAyB,EACzB,OAA0B;QAE1B,KAAK,MAAM,KAAK,IAAI,MAAM;YACxB,KAAK,MAAM,MAAM,IAAI,OAAO;gBAC1B,IAAI,IAAA,uCAAkB,EAAC,MAAM,EAAE,mBAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;oBAC9D,MAAM,IAAI,KAAK,CACb,mBAAmB,KAAK,kCAAkC,MAAM,IAAI;wBAClE,qEAAqE;wBACrE,mEAAmE;wBACnE,wDAAwD,CAC3D,CAAC;IACV,CAAC;IAbe,sBAAA,2BAA2B,8BAa1C,CAAA;IAED;;;;;;;;;;;;OAYG;IACH,SAAgB,eAAe,CAAC,UAAkB;QAChD,OAAO,CACL,UAAU,KAAK,uCAAuC;YACtD,UAAU,KAAK,oCAAoC;YACnD,UAAU,CAAC,UAAU,CAAC,0CAA0C,CAAC,CAClE,CAAC;IACJ,CAAC;IANe,sBAAA,eAAe,kBAM9B,CAAA;IAED;;;;;;;;;;;;;OAaG;IACH,SAAgB,yBAAyB,CACvC,YAAwD,EACxD,cAAmC,EACnC,UAAkB;QAElB,KAAK,MAAM,WAAW,IAAI,YAAY;YACpC,IACE,eAAe,CAAC,WAAW,CAAC,UAAU,CAAC;gBACvC,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC;gBAE1C,MAAM,IAAI,KAAK,CACb,iBAAiB,UAAU,wCAAwC;oBACjE,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,mCAAmC;oBAC5E,gFAAgF,CACnF,CAAC;IACR,CAAC;IAfe,sBAAA,yBAAyB,4BAexC,CAAA;AACH,CAAC,EA3GgB,qBAAqB,aAArB,qBAAqB,GAArB,qBAAqB,QA2GrC"}