ttsc 0.30.4 → 0.31.0

package/src/internal/pathIdentity/createFilesystemPathIdentityContext.ts

@@ -0,0 +1,437 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { E2ETrace } from "../E2ETrace";
+import { OwnedSynchronousProcess } from "../OwnedSynchronousProcess";
+import { parseWindowsDirectoryCaseSensitivity } from "../parseWindowsDirectoryCaseSensitivity";
+import type { FilesystemPathIdentity } from "./FilesystemPathIdentity";
+import type { FilesystemPathIdentityContext } from "./FilesystemPathIdentityContext";
+import type { FilesystemPathIdentityOperations } from "./FilesystemPathIdentityOperations";
+import { isFilesystemPathIdentityWithin } from "./isFilesystemPathIdentityWithin";
+import { resolveFilesystemPath } from "./resolveFilesystemPath";
+
+/**
+ * Create one filesystem-identity resolver for a filesystem transaction.
+ *
+ * Successfully observed prefixes use their physical spelling. An unresolved
+ * suffix preserves spelling under sensitive or unknown policy; observed
+ * insensitivity permits ASCII case folding. In best-effort mode that suffix can
+ * include unreadable existing entries, so it is not proof of absence.
+ *
+ * Cached observations agree for the same queried key, not an atomic view of the
+ * whole filesystem. An unavailable read-only case probe reports unknown and
+ * preserves unresolved suffix spelling; only observed insensitivity permits
+ * folding.
+ *
+ * @evidence contracts/common.md#principled-implementation Successful realpath observations establish physical prefixes; unresolved segments fold only under observed insensitivity, while sensitive or unknown ancestors preserve spelling. Best-effort unavailability does not establish absence or complete alias resolution, and unknown policy is not replaced with an OS-default equivalence assumption.
+ * @evidence contracts/common.md#clear-and-simple-design A transaction owns resolution and three memoized observation maps; native case probing, lexical normalization and key construction are separate helpers with one identity policy shared by all callers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Supported injected operations replace no foreign methods; strict unexpected realpath failures propagate. Best-effort realpath is explicit, while unavailable case evidence remains unknown rather than a fabricated OS-default capability.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain missing-suffix semantics, per-key rather than atomic consistency and unknown case evidence; helpers document native probing premises, with separate tag paragraphs.
+ * @evidence contracts/portability.md#os-neutral-implementation Native realpath, alternate-name observations and read-only Windows fsutil obtain actual case evidence; native path APIs separate Windows and POSIX syntax. OS names select syntax or probe mechanisms, never an unmeasured directory policy.
+ * @evidence contracts/performance.md#efficient-algorithms Construction allocates maps and closures without querying paths. Physical resolution visits missing ancestors and reverses the collected suffix once; lexical relations walk components. Default case probes enumerate uncapped immediate entries and inspect folded-name text, then stop at the first conclusive alternate-name observation. A rejected alternate is conclusive only when its original still exists; disappeared entries cannot establish sensitivity. Darwin can walk same-device ancestors, while Windows can synchronously launch directory and volume fsutil queries and parse returned bytes. Work includes visited path/name/output lengths and native metadata/process costs, not just depth or entry count.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each transaction memoizes resolved paths, realpath success or permitted-unavailable observations and case answers by their native keys; repeated questions reuse observations only within that unit of work, not across later filesystem generations. Best-effort cached unavailability is not an absence certificate.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Context-owned maps grow with queried paths and visited ancestors without internal eviction; reclamation requires the caller to release references to the context and its returned methods. Entry snapshots, decoded query text and synchronous fsutil results are transient rather than retained observers; no descriptor or child handle is held between completed observations. A Windows query supplies no explicit timeout, so active synchronous work has no deadline here. This boundary imposes no query-population quota or explicit dispose operation.
+ */
+export function createFilesystemPathIdentityContext(
+  operations: Partial<FilesystemPathIdentityOperations> = {},
+): FilesystemPathIdentityContext {
+  const identities = new Map<string, CachedIdentity>();
+  const realpaths = new Map<string, CachedRealpath>();
+  const sensitivities = new Map<string, boolean | undefined>();
+  const platform = operations.platform ?? process.platform;
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const throwOnRealpathError = operations.throwOnRealpathError ?? true;
+  const realpath = operations.realpath ?? physicalRealpath;
+  const lstat = operations.lstat ?? fs.lstatSync;
+  const readdir = operations.readdir ?? fs.readdirSync;
+  const caseSensitive =
+    operations.caseSensitive ??
+    ((directory: string) => {
+      try {
+        return filesystemDirectoryIsCaseSensitive(directory, platform, {
+          lstat,
+          readdir,
+          realpath,
+        });
+      } catch {
+        // A failed capability observation is unknown. This does not suppress
+        // strict physical identity errors in the separate realpath resolver.
+        return undefined;
+      }
+    });
+
+  const resolve = (location: string): FilesystemPathIdentity => {
+    const normalized = resolveFilesystemPath(location, platform);
+    const cached = identities.get(normalized);
+    if (cached !== undefined) return cached.identity;
+    let existing = normalized;
+    const missing: string[] = [];
+    while (true) {
+      const physical = cachedRealpath(
+        realpaths,
+        realpath,
+        existing,
+        platform,
+        throwOnRealpathError,
+      );
+      if (physical !== undefined) {
+        missing.reverse();
+        const sensitive =
+          missing.length === 0
+            ? true
+            : cachedCaseSensitivity(sensitivities, caseSensitive, physical);
+        const suffix =
+          sensitive === false ? missing.map(foldAsciiCase) : missing;
+        const canonical = pathApi.resolve(physical, ...suffix);
+        const identity = {
+          key: filesystemPathIdentityKey(canonical, platform),
+          path: canonical,
+        };
+        identities.set(normalized, {
+          ancestor: physical,
+          identity,
+        });
+        return identity;
+      }
+      const parent = pathApi.dirname(existing);
+      if (parent === existing) {
+        const sensitive = cachedCaseSensitivity(
+          sensitivities,
+          caseSensitive,
+          existing,
+        );
+        const identity = {
+          key: filesystemPathIdentityKey(
+            sensitive === false ? foldAsciiCase(normalized) : normalized,
+            platform,
+          ),
+          path: normalized,
+        };
+        identities.set(normalized, {
+          ancestor: normalized,
+          identity,
+        });
+        return identity;
+      }
+      missing.push(pathApi.basename(existing));
+      existing = parent;
+    }
+  };
+
+  const directoryCaseSensitive = (directory: string): boolean | undefined => {
+    const normalized = resolveFilesystemPath(directory, platform);
+    resolve(normalized);
+    return cachedCaseSensitivity(
+      sensitivities,
+      caseSensitive,
+      identities.get(normalized)!.ancestor,
+    );
+  };
+
+  const lexicalParts = (
+    location: string,
+  ): { root: string; segments: string[] } => {
+    const normalized = resolveFilesystemPath(location, platform);
+    const root = pathApi.parse(normalized).root;
+    return {
+      root,
+      segments: normalized
+        .slice(root.length)
+        .split(pathApi.sep)
+        .filter(Boolean),
+    };
+  };
+
+  // These candidates guide observation routing, not equality or cache proof.
+  const lexicalRelation = (
+    root: string,
+    candidate: string,
+    within: boolean,
+  ): boolean => {
+    const parent = lexicalParts(root);
+    const child = lexicalParts(candidate);
+    if (
+      filesystemPathIdentityKey(parent.root, platform) !==
+        filesystemPathIdentityKey(child.root, platform) ||
+      (within
+        ? parent.segments.length > child.segments.length
+        : parent.segments.length !== child.segments.length)
+    )
+      return false;
+    let directory = parent.root;
+    for (let index = 0; index < parent.segments.length; index++) {
+      const expected = parent.segments[index]!;
+      const actual = child.segments[index]!;
+      if (expected !== actual) {
+        // Native Unicode case and normalization tables are not represented by
+        // the ASCII probe. Keep such spellings eligible rather than inventing
+        // a Unicode equivalence relation that could lose a watcher event.
+        if (/^[\x00-\x7f]*$/.test(expected) && /^[\x00-\x7f]*$/.test(actual)) {
+          if (
+            directoryCaseSensitive(directory) === true ||
+            foldAsciiCase(expected) !== foldAsciiCase(actual)
+          )
+            return false;
+        }
+      }
+      directory = pathApi.join(directory, expected);
+    }
+    return true;
+  };
+
+  return {
+    caseSensitive: directoryCaseSensitive,
+    isWithin: (root, candidate) =>
+      isFilesystemPathIdentityWithin(
+        resolve(root).key,
+        resolve(candidate).key,
+        platform,
+      ),
+    lexicalKey: (location) => {
+      const lexical = lexicalParts(location);
+      let parent = lexical.root;
+      const segments = lexical.segments.map((segment) => {
+        const key =
+          directoryCaseSensitive(parent) === false
+            ? foldAsciiCase(segment)
+            : segment;
+        parent = pathApi.join(parent, segment);
+        return key;
+      });
+      return pathApi.join(
+        filesystemPathIdentityKey(lexical.root, platform),
+        ...segments,
+      );
+    },
+    lexicalMatches: (left, right) => lexicalRelation(left, right, false),
+    lexicalIsWithin: (root, candidate) =>
+      lexicalRelation(root, candidate, true),
+    resolve,
+  };
+}
+
+type CachedIdentity = {
+  ancestor: string;
+  identity: FilesystemPathIdentity;
+};
+
+type CachedRealpath =
+  | {
+      found: false;
+    }
+  | {
+      found: true;
+      path: string;
+    };
+
+function cachedRealpath(
+  cache: Map<string, CachedRealpath>,
+  realpath: (location: string) => string,
+  location: string,
+  platform: NodeJS.Platform,
+  throwOnRealpathError: boolean,
+): string | undefined {
+  const cached = cache.get(location);
+  if (cached !== undefined) return cached.found ? cached.path : undefined;
+  try {
+    const physical = resolveFilesystemPath(realpath(location), platform);
+    cache.set(location, { found: true, path: physical });
+    return physical;
+  } catch (error) {
+    if (throwOnRealpathError && isMissingFilesystemEntry(error) === false) {
+      throw error;
+    }
+    cache.set(location, { found: false });
+    return undefined;
+  }
+}
+
+function cachedCaseSensitivity(
+  cache: Map<string, boolean | undefined>,
+  caseSensitive: (directory: string) => boolean | undefined,
+  directory: string,
+): boolean | undefined {
+  if (cache.has(directory)) return cache.get(directory);
+  const sensitive = caseSensitive(directory);
+  cache.set(directory, sensitive);
+  return sensitive;
+}
+
+function physicalRealpath(location: string): string {
+  return fs.realpathSync.native?.(location) ?? fs.realpathSync(location);
+}
+
+function filesystemDirectoryIsCaseSensitive(
+  directory: string,
+  platform: NodeJS.Platform,
+  operations: {
+    lstat(location: string): fs.Stats | fs.BigIntStats;
+    readdir(directory: string): string[];
+    realpath(location: string): string;
+  },
+): boolean | undefined {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  let entries: string[];
+  try {
+    entries = operations.readdir(directory);
+  } catch {
+    return undefined;
+  }
+  const foldedNames = new Map<string, string>();
+  for (const name of entries) {
+    const folded = foldAsciiCase(name);
+    const previous = foldedNames.get(folded);
+    if (previous !== undefined && previous !== name) return true;
+    foldedNames.set(folded, name);
+  }
+  for (const name of entries) {
+    const alternate = alternateCase(name);
+    if (alternate === name) continue;
+    try {
+      operations.lstat(pathApi.join(directory, alternate));
+    } catch (error) {
+      if (isMissingFilesystemEntry(error)) {
+        // Enumeration is not an atomic snapshot. An absent alternate proves
+        // sensitivity only if the original spelling still names an entry.
+        try {
+          operations.lstat(pathApi.join(directory, name));
+          return true;
+        } catch (originalError) {
+          if (isMissingFilesystemEntry(originalError) === false)
+            throw originalError;
+        }
+        continue;
+      }
+      throw error;
+    }
+    try {
+      const actual = resolveFilesystemPath(
+        operations.realpath(pathApi.join(directory, name)),
+        platform,
+      );
+      const alias = resolveFilesystemPath(
+        operations.realpath(pathApi.join(directory, alternate)),
+        platform,
+      );
+      return actual !== alias;
+    } catch (error) {
+      if (isMissingFilesystemEntry(error) === false) throw error;
+    }
+  }
+  if (platform === "darwin") {
+    // APFS/HFS case semantics are volume-wide. An empty directory has no child
+    // name to probe, so ask the same read-only question of its existing name in
+    // the parent and walk upward until a name with ASCII case is available.
+    // This avoids a write probe while still distinguishing default APFS from a
+    // case-sensitive volume.
+    let current = resolveFilesystemPath(directory, platform);
+    while (true) {
+      const parent = pathApi.dirname(current);
+      if (parent === current) break;
+      // Names are interpreted by their parent; another mount is not evidence
+      // of the directory's own volume case policy.
+      if (operations.lstat(current).dev !== operations.lstat(parent).dev)
+        return undefined;
+      const name = pathApi.basename(current);
+      const alternate = alternateCase(name);
+      if (alternate !== name) {
+        try {
+          const actual = resolveFilesystemPath(
+            operations.realpath(current),
+            platform,
+          );
+          const alias = resolveFilesystemPath(
+            operations.realpath(pathApi.join(parent, alternate)),
+            platform,
+          );
+          return actual !== alias;
+        } catch (error) {
+          if (isMissingFilesystemEntry(error) === false) throw error;
+        }
+      }
+      current = parent;
+    }
+    return undefined;
+  }
+  if (platform !== "win32") return undefined;
+  // Node does not expose the Windows per-directory flag. Prefer fsutil's
+  // read-only answer; unavailable capability remains unknown.
+  const queried = queryWindowsDirectoryCaseSensitivity(directory);
+  if (queried !== undefined) return queried;
+  return undefined;
+}
+
+/**
+ * Read the per-directory flag without depending on fsutil's display language.
+ *
+ * English output is cheap to recognize directly. Other Windows locales write
+ * console-code-page bytes that Node cannot reliably decode, so their raw
+ * message is interpreted against the volume-root query.
+ */
+function queryWindowsDirectoryCaseSensitivity(
+  directory: string,
+): boolean | undefined {
+  const result = queryWindowsDirectoryCaseSensitivityBytes(directory);
+  if (result === undefined) return undefined;
+  const volumeRoot = path.win32.parse(directory).root;
+  const direct = parseWindowsDirectoryCaseSensitivity(
+    result,
+    undefined,
+    volumeRoot,
+  );
+  if (direct !== undefined) return direct;
+  const volume = queryWindowsDirectoryCaseSensitivityBytes(volumeRoot);
+  return parseWindowsDirectoryCaseSensitivity(result, volume, volumeRoot);
+}
+
+function queryWindowsDirectoryCaseSensitivityBytes(
+  directory: string,
+): Buffer | undefined {
+  const args = ["file", "queryCaseSensitiveInfo", directory];
+  const result = E2ETrace.synchronous(
+    "fsutil.exe",
+    args,
+    {},
+    "path-case-probe",
+    () =>
+      OwnedSynchronousProcess.launch("fsutil.exe", args, {
+        windowsHide: true,
+      }) ?? childProcess.spawnSync("fsutil.exe", args, { windowsHide: true }),
+  );
+  return result.error === undefined &&
+    result.status === 0 &&
+    Buffer.isBuffer(result.stdout)
+    ? result.stdout
+    : undefined;
+}
+
+function filesystemPathIdentityKey(
+  location: string,
+  platform: NodeJS.Platform,
+): string {
+  if (platform !== "win32") return location;
+  const root = path.win32.parse(location).root;
+  return `${root.toLowerCase()}${location.slice(root.length)}`;
+}
+
+function alternateCase(value: string): string {
+  return value.replace(/[A-Za-z]/g, (character) =>
+    character === character.toLowerCase()
+      ? character.toUpperCase()
+      : character.toLowerCase(),
+  );
+}
+
+/** ASCII folding is the case equivalence observed by the read-only probes. */
+function foldAsciiCase(value: string): string {
+  return value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+}
+
+function isMissingFilesystemEntry(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}

package/src/internal/pathIdentity/createProjectInputPathIdentityContext.ts

@@ -0,0 +1,34 @@
+import type { ProjectInputPathIdentityContext } from "./ProjectInputPathIdentityContext";
+import type { ProjectInputPathIdentityOperations } from "./ProjectInputPathIdentityOperations";
+import { createFilesystemPathIdentityContext } from "./createFilesystemPathIdentityContext";
+
+/**
+ * Create the identity resolver used for project inputs.
+ *
+ * It is {@link createFilesystemPathIdentityContext} under the project-input
+ * name, kept as its own entry point so the watch, build, and LSP hosts that
+ * reason about project inputs read as such while sharing one implementation.
+ * Each call creates a new context; it does not reuse another transaction's
+ * observations. Creation allocates maps and closures without querying native
+ * paths. Later method calls perform the underlying resolver's native or
+ * injected observations, including a read-only Windows case query when
+ * selected. The caller chooses the observation lifetime by retaining or
+ * discarding the returned context; no explicit dispose operation or map
+ * eviction is supplied.
+ *
+ * @param operations Replaceable filesystem primitives; omitted members use the
+ *   host's own.
+ * @evidence contracts/common.md#principled-implementation Returning the filesystem context gives project consumers identical realpath, missing-suffix and case-policy decisions instead of a second identity relation.
+ * @evidence contracts/common.md#clear-and-simple-design This domain entry point delegates its entire policy and retains only a project-oriented name for watch, build and LSP callers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Operations use the supported injection boundary; neither native methods nor foreign globals are patched to change identity.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the domain name, shared implementation and omitted-operation defaults, with tags visibly separate.
+ * @evidence contracts/portability.md#os-neutral-implementation The owning resolver uses actual native case evidence and path syntax; unavailable policy remains unknown and preserves identity spellings instead of assuming an OS-default filesystem capability.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The returned context owns maps whose queried path/ancestor populations have no internal eviction bound; its lifetime and injected-operation references pass to the caller. Creation opens no native handle, and the alias adds no disposal or observation-freshness guarantee.
+ * @evidence contracts/performance.md#efficient-algorithms Construction delegates fixed map/closure allocation without path traversal. Actual context method calls incur the shared resolver's path/ancestor/entry/native-probe work; delegating does not make those later costs constant or impose a population cap.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each new context independently memoizes per-key observations within its caller-chosen transaction, including missing paths and unknown case answers. No context is shared across calls, and cached observations are not a fresh filesystem snapshot.
+ */
+export function createProjectInputPathIdentityContext(
+  operations: Partial<ProjectInputPathIdentityOperations> = {},
+): ProjectInputPathIdentityContext {
+  return createFilesystemPathIdentityContext(operations);
+}

package/src/internal/pathIdentity/isFilesystemPathIdentityWithin.ts

@@ -0,0 +1,32 @@
+import path from "node:path";
+
+/**
+ * Whether `candidate` equals `root` or lies beneath it, compared lexically.
+ *
+ * Both arguments must already be identity keys (see
+ * {@link FilesystemPathIdentity.key}). The function performs no filesystem
+ * access and no case folding. A root that already ends in a separator (a volume
+ * root such as `C:\` or `/`) is used as is, so every path on that volume is
+ * inside it.
+ *
+ * @param platform Separator semantics; defaults to the host platform.
+ * @evidence contracts/common.md#principled-implementation Equality includes the root itself and a separator-delimited prefix includes only descendants; inputs must already carry canonical identity keys so sibling names and case policy are not guessed here.
+ * @evidence contracts/common.md#clear-and-simple-design One equality check and one boundary prefix check keep this lexical predicate separate from the resolver that proves keys.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The volume-root separator rule is path syntax required by containment, not an expected-result exception or a casing workaround.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents the canonical-key premise, no filesystem access and volume-root behavior, which callers need to avoid treating raw paths as identities.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit platform separators preserve drive, UNC and POSIX root boundaries; existing keys supply native case policy rather than whole-path lowercasing here.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The lexical boolean query owns no native handle, persistent observation map or output artifact; a temporary separator-suffixed root is invocation-local.
+ * @evidence contracts/performance.md#efficient-algorithms Equality and one separator-delimited prefix comparison inspect string contents; a non-root suffix construction can copy the root spelling. Work and temporary text depend on key lengths, without filesystem observation, component walking or descendant enumeration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This predicate compares already-produced identity keys and owns no expensive producer, shared native observations or mutable authority whose equivalent work needs coordination. Key construction and its reuse belong to the supplying context.
+ */
+export function isFilesystemPathIdentityWithin(
+  root: string,
+  candidate: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (candidate === root) return true;
+  const separator = platform === "win32" ? path.win32.sep : path.posix.sep;
+  return candidate.startsWith(
+    root.endsWith(separator) ? root : `${root}${separator}`,
+  );
+}

package/src/internal/pathIdentity/isProjectInputPathIdentityWithin.ts

@@ -0,0 +1,22 @@
+import { isFilesystemPathIdentityWithin } from "./isFilesystemPathIdentityWithin";
+
+/**
+ * Whether one project-input identity key contains another, using the host
+ * platform's separator; the project-input name of
+ * {@link isFilesystemPathIdentityWithin}.
+ *
+ * @evidence contracts/common.md#principled-implementation Delegation preserves canonical-key equality and separator-boundary containment for project inputs with the same premises as filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design The project-facing name introduces no independent containment policy; the filesystem predicate remains the owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No project-specific path exception or foreign mutation bypasses the canonical-key predicate.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the identity-key inputs and shared owner, without suggesting raw lexical paths have been physically resolved.
+ * @evidence contracts/portability.md#os-neutral-implementation The host separator is obtained by the shared predicate while case and alias equivalence must already be encoded in its input keys.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The delegated lexical query owns no native handle, persistent cache or created artifact; this domain adapter adds no retained state.
+ * @evidence contracts/performance.md#efficient-algorithms Delegation performs the shared equality and separator-prefix comparisons, with string work and temporary suffix text dependent on input key lengths. This adapter adds no native lookup or descendant enumeration.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The adapter receives precomputed identity keys and introduces no producer or mutable observations to share. Identity construction and transaction reuse remain with the caller's context, rather than a second cache here.
+ */
+export function isProjectInputPathIdentityWithin(
+  root: string,
+  candidate: string,
+): boolean {
+  return isFilesystemPathIdentityWithin(root, candidate);
+}

package/src/internal/pathIdentity/resolveFilesystemPath.ts

@@ -0,0 +1,43 @@
+import path from "node:path";
+
+/**
+ * Normalize a path lexically, without touching the filesystem.
+ *
+ * On Windows, forward slashes become backslashes and the extended-length
+ * prefixes a native API can return (`\\?\C:\...` and `\\?\UNC\server\share`)
+ * are removed, so one location spelled by Node, by `fs.realpathSync.native`,
+ * and by a user compares equal before any identity is taken. POSIX paths are
+ * only resolved. Relative spellings also depend on the selected path API's
+ * current-directory resolution; `platform` chooses path syntax, not an
+ * independent filesystem.
+ *
+ * @param platform Path semantics; defaults to the host platform.
+ * @evidence contracts/common.md#principled-implementation Native path resolution removes only recognized drive and UNC extended-length aliases; it normalizes lexical spelling without pretending to establish filesystem identity.
+ * @evidence contracts/common.md#clear-and-simple-design One Windows normalization branch precedes the selected path API, keeping lexical syntax separate from physical realpath and case-policy decisions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Recognized Windows path prefixes are native syntax, not consumer exceptions; no filesystem method or global state is replaced.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains lexical scope, supported extended prefixes and the platform argument, separately from the acknowledgments.
+ * @evidence contracts/portability.md#os-neutral-implementation Explicit win32 or posix path semantics handle native separators and Windows extended drive/UNC representations without assuming casing establishes physical identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Local and returned strings scale with supplied and resolved path text, but this lexical operation owns no independent historical population, handle or running task.
+ * @evidence contracts/performance.md#efficient-algorithms Windows separator replacement and lowercase-prefix inspection traverse path text and allocate local strings; selected path.resolve performs lexical segment/current-directory resolution. A fixed expression count is not constant work, and no native filesystem identity query or directory enumeration occurs here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This lexical normalizer coordinates no work across requests and retains no cache; relative results depend on current-directory resolution as well as the explicit arguments.
+ */
+export function resolveFilesystemPath(
+  location: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  if (platform !== "win32") {
+    return pathApi.resolve(location);
+  }
+  const normalized = location.replaceAll("/", "\\");
+  if (normalized.toLowerCase().startsWith("\\\\?\\unc\\")) {
+    return pathApi.resolve(`\\\\${normalized.slice(8)}`);
+  }
+  if (
+    normalized.startsWith("\\\\?\\") &&
+    /^[A-Za-z]:\\/.test(normalized.slice(4))
+  ) {
+    return pathApi.resolve(normalized.slice(4));
+  }
+  return pathApi.resolve(normalized);
+}

package/src/internal/pathIdentity/resolvePhysicalPath.ts

@@ -0,0 +1,31 @@
+import { createFilesystemPathIdentityContext } from "./createFilesystemPathIdentityContext";
+
+/**
+ * Best-effort physical spelling of `location`: resolved links and junctions use
+ * the filesystem's returned spelling, followed by any unresolved suffix
+ * (`createFilesystemPathIdentityContext`).
+ *
+ * Total on purpose. Native failures may leave an unresolved suffix after an
+ * observed prefix; if the overall resolution throws, the original spelling is
+ * returned. This is not proof that every existing segment was readable.
+ *
+ * @param location An absolute path.
+ * @returns Its best-effort spelling, or `location` itself on caught failure.
+ * @evidence contracts/common.md#principled-implementation The shared resolver follows existing ancestors and canonicalizes missing suffixes; an unavailable answer falls back to the caller's path because this best-effort utility is not a deletion authorization.
+ * @evidence contracts/common.md#clear-and-simple-design The physical-path view delegates to the owning identity resolver and has one total fallback; it does not duplicate alias or case policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failure preserves the original usable spelling rather than fabricating a proved identity, and no foreign filesystem behavior is patched.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the absolute-path premise and total fallback, keeping use meaning separate from tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Realpath and case semantics come from the shared native boundary; unavailable case policy preserves missing spelling, and the total error fallback remains best-effort rather than a proved alias guarantee.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources One fresh identity context owns call-local path/ancestor/case maps during resolution; native observations and any Windows case-query child belong to that delegated boundary. The context becomes reclaimable after success or caught failure, and only the returned path string escapes; this wrapper retains no historical registry or held directory handle.
+ * @evidence contracts/performance.md#efficient-algorithms Delegated resolution traverses path ancestors and text and can scan native case-probe directory entries or invoke a Windows query; fixed wrapper steps do not bound that native work. Temporary context maps and returned spelling grow with observed paths and ancestors.
+ * @evidence contracts/performance.md#reuse-equivalent-work The fresh context memoizes equivalent realpath/case observations within this call only. Later calls resolve current filesystem state again rather than reuse historical physical answers; the best-effort fallback is not an identity certificate.
+ */
+export function resolvePhysicalPath(location: string): string {
+  try {
+    return createFilesystemPathIdentityContext({
+      throwOnRealpathError: false,
+    }).resolve(location).path;
+  } catch {
+    return location;
+  }
+}

package/src/internal/pathIdentity/resolveProjectInputPath.ts

@@ -0,0 +1,18 @@
+import { resolveFilesystemPath } from "./resolveFilesystemPath";
+
+/**
+ * Lexically normalize a project-input path on the host platform; the
+ * project-input name of {@link resolveFilesystemPath}.
+ *
+ * @evidence contracts/common.md#principled-implementation Direct delegation gives project paths the same lexical semantics as other native paths; it performs no physical identity comparison.
+ * @evidence contracts/common.md#clear-and-simple-design The domain-named entry point retains one shared normalization owner without a second project-specific algorithm.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No project spelling or fixture is special-cased; the supported lexical boundary handles the input.
+ * @evidence contracts/common.md#meaningful-documentation The concise native description identifies lexical scope and links its shared owner, with a blank line before tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Host path normalization delegates Windows extended aliases and POSIX separators to resolveFilesystemPath; it does not infer a volume's case behavior.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Delegated local/returned path strings have no independent historical population or native resource lifetime owned by this domain adapter.
+ * @evidence contracts/performance.md#efficient-algorithms The shared lexical owner traverses path text and segments and may use current-directory resolution for relative inputs; one forwarding call does not remove that delegated cost.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This domain adapter coordinates no cross-request work; it delegates a current lexical normalization without holding a result cache.
+ */
+export function resolveProjectInputPath(location: string): string {
+  return resolveFilesystemPath(location);
+}

package/src/internal/pluginSource.ts

@@ -0,0 +1,26 @@
+/**
+ * Public entry of `ttsc/plugin-source`.
+ *
+ * A plugin's binary is keyed on its Go source and the environment it is built
+ * in, and a transform envelope reports the state of every source directory its
+ * binaries were built from
+ * (`ITtscCompilerTransformation.ISuccess.pluginSources`). A consumer that
+ * caches the output, as `@ttsc/unplugin` does, proves that state with the rule
+ * the build itself applied rather than a copy of it: the state of a source
+ * directory, the files and digest of its sources within that state, which of
+ * its subdirectories the state passes over and which paths below it an observer
+ * must hear, and the ttsc and TypeScript-Go versions every build is keyed on,
+ * which name output kept beyond the process that produced it. This barrel is
+ * the one module path such a consumer imports, so the implementation keeps one
+ * declaration per file.
+ */
+export * from "../plugin/internal/source/collectPluginSourceFiles";
+export * from "../plugin/internal/source/pluginBuildVersions";
+export * from "../plugin/internal/source/pluginSourceCovers";
+export * from "../plugin/internal/source/pluginSourceFilesSignature";
+export * from "../plugin/internal/source/pluginSourceDigest";
+export * from "../plugin/internal/source/pluginSourceState";
+export * from "../plugin/internal/source/pluginSourceStateHolds";
+export * from "../plugin/internal/source/processPluginBuildEnvironment";
+export * from "../plugin/internal/source/PluginBuildEnvironmentReadings";
+export * from "../plugin/internal/source/prunesPluginSourceDirectory";