ttsc 0.30.4 → 0.31.1

package/src/internal/projectInputPathIdentity.ts

@@ -1,391 +1,30 @@
-import childProcess from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-
-import { parseWindowsDirectoryCaseSensitivity } from "./windowsDirectoryCaseSensitivity";
-
-export type FilesystemPathIdentity = {
-  key: string;
-  path: string;
-};
-
-export type FilesystemPathIdentityOperations = {
-  caseSensitive(directory: string): boolean;
-  lstat?(location: string): fs.Stats | fs.BigIntStats;
-  platform: NodeJS.Platform;
-  readdir?(directory: string): string[];
-  realpath(location: string): string;
-  throwOnRealpathError: boolean;
-};
-
-export type FilesystemPathIdentityContext = {
-  caseSensitive(directory: string): boolean;
-  isWithin(root: string, candidate: string): boolean;
-  resolve(location: string): FilesystemPathIdentity;
-};
-
-type CachedIdentity = {
-  ancestor: string;
-  identity: FilesystemPathIdentity;
-};
-
-type CachedRealpath =
-  | {
-      found: false;
-    }
-  | {
-      found: true;
-      path: string;
-    };
-
 /**
- * Create one filesystem-identity resolver for a filesystem transaction.
+ * Public entry of `ttsc/path-identity`.
  *
- * Existing segments use their physical spelling. A missing suffix keeps exact
- * spelling only under a case-sensitive directory; otherwise its canonical
- * spelling is folded so aliases remain one declaration before they exist.
- */
-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>();
-  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) =>
-      filesystemDirectoryIsCaseSensitive(directory, platform, {
-        lstat,
-        readdir,
-        realpath,
-      }));
-
-  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) {
-        const sensitive =
-          missing.length === 0
-            ? true
-            : cachedCaseSensitivity(sensitivities, caseSensitive, physical);
-        const suffix = sensitive
-          ? missing
-          : missing.map((segment) => segment.toLowerCase());
-        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 ? normalized : normalized.toLowerCase(),
-            platform,
-          ),
-          path: normalized,
-        };
-        identities.set(normalized, {
-          ancestor: normalized,
-          identity,
-        });
-        return identity;
-      }
-      missing.unshift(pathApi.basename(existing));
-      existing = parent;
-    }
-  };
-
-  return {
-    caseSensitive: (directory) => {
-      const normalized = resolveFilesystemPath(directory, platform);
-      resolve(normalized);
-      return cachedCaseSensitivity(
-        sensitivities,
-        caseSensitive,
-        identities.get(normalized)!.ancestor,
-      );
-    },
-    isWithin: (root, candidate) =>
-      isFilesystemPathIdentityWithin(
-        resolve(root).key,
-        resolve(candidate).key,
-        platform,
-      ),
-    resolve,
-  };
-}
-
-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}`,
-  );
-}
-
-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);
-}
-
-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>,
-  caseSensitive: (directory: string) => boolean,
-  directory: string,
-): boolean {
-  const cached = cache.get(directory);
-  if (cached !== undefined) return cached;
-  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 {
-  const pathApi = platform === "win32" ? path.win32 : path.posix;
-  let entries: string[];
-  try {
-    entries = operations.readdir(directory);
-  } catch {
-    return unprovenCaseSensitivity(platform);
-  }
-  const foldedNames = new Map<string, string>();
-  for (const name of entries) {
-    const folded = name.toLowerCase();
-    const previous = foldedNames.get(folded);
-    if (previous !== undefined && previous !== name) return true;
-    foldedNames.set(folded, name);
-  }
-  let rejectedAlternate = false;
-  for (const name of entries) {
-    const alternate = alternateCase(name);
-    if (alternate === name) continue;
-    try {
-      operations.lstat(pathApi.join(directory, alternate));
-      return false;
-    } catch (error) {
-      if (isMissingFilesystemEntry(error)) {
-        rejectedAlternate = true;
-        continue;
-      }
-      throw error;
-    }
-  }
-  if (rejectedAlternate) return true;
-  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;
-      const name = pathApi.basename(current);
-      const alternate = alternateCase(name);
-      if (alternate !== name) {
-        try {
-          operations.realpath(pathApi.join(parent, alternate));
-          return false;
-        } catch (error) {
-          if (isMissingFilesystemEntry(error) === false) throw error;
-        }
-      }
-      current = parent;
-    }
-    return unprovenCaseSensitivity(platform);
-  }
-  if (platform !== "win32") return true;
-  // Node does not expose the Windows per-directory flag. Prefer fsutil's
-  // read-only answer, then conservatively preserve distinct declarations.
-  const queried = queryWindowsDirectoryCaseSensitivity(directory);
-  if (queried !== undefined) return queried;
-  return unprovenCaseSensitivity(platform);
-}
-
-/**
- * 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 result = childProcess.spawnSync(
-    "fsutil.exe",
-    ["file", "queryCaseSensitiveInfo", directory],
-    { windowsHide: true },
-  );
-  return result.error === undefined &&
-    result.status === 0 &&
-    Buffer.isBuffer(result.stdout)
-    ? result.stdout
-    : undefined;
-}
-
-/**
- * What to assume when the volume refused to answer.
- *
- * Every probe above returns a proof: two names that fold together prove the
- * volume keeps them apart, and a name that opens under the other case proves it
- * does not. This is the remaining case — an empty or unreadable directory, a
- * name with no letter to alter, a Windows build whose `fsutil` lacks the
- * subcommand — and the only honest answer is the platform's own default.
+ * The filesystem-identity rules that decide when two spellings name one file
+ * (Windows 8.3 names, symlinks and junctions, per-directory case sensitivity,
+ * extended-length prefixes) are shared by the compiler host, the watch
+ * launcher, the LSP host, `@ttsc/unplugin`, and the VS Code extension. This
+ * barrel is the one module path those consumers import, so the implementation
+ * can keep one declaration per file below `pathIdentity/`.
  *
- * NTFS and APFS are case-insensitive unless a volume or a directory was opted
- * out, so guessing sensitive there splits one file into two identities under
- * two spellings, which is the failure this module exists to remove. The rarer
- * mistake, on a volume that really was opted out, merges two files differing
- * only in case into one watched identity.
+ * It also carries the compiler's own answer to which spelling of a selected
+ * project is the one its Program and its plugins see, `resolveProjectIdentity`,
+ * so an adapter that writes a config or a path for the compiler anchors it
+ * exactly where the compiler would.
  */
-function unprovenCaseSensitivity(platform: NodeJS.Platform): boolean {
-  return platform !== "win32" && platform !== "darwin";
-}
-
-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(),
-  );
-}
-
-function isMissingFilesystemEntry(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    "code" in error &&
-    (error.code === "ENOENT" || error.code === "ENOTDIR")
-  );
-}
-
-export type ProjectInputPathIdentity = FilesystemPathIdentity;
-export type ProjectInputPathIdentityOperations =
-  FilesystemPathIdentityOperations;
-export type ProjectInputPathIdentityContext = FilesystemPathIdentityContext;
-
-export function createProjectInputPathIdentityContext(
-  operations: Partial<ProjectInputPathIdentityOperations> = {},
-): ProjectInputPathIdentityContext {
-  return createFilesystemPathIdentityContext(operations);
-}
-
-export function isProjectInputPathIdentityWithin(
-  root: string,
-  candidate: string,
-): boolean {
-  return isFilesystemPathIdentityWithin(root, candidate);
-}
-
-export function resolveProjectInputPath(location: string): string {
-  return resolveFilesystemPath(location);
-}
+export * from "./pathIdentity/FilesystemPathIdentity";
+export * from "./pathIdentity/FilesystemPathIdentityOperations";
+export * from "./pathIdentity/FilesystemPathIdentityContext";
+export * from "./pathIdentity/createFilesystemPathIdentityContext";
+export * from "./pathIdentity/isFilesystemPathIdentityWithin";
+export * from "./pathIdentity/resolveFilesystemPath";
+export * from "./pathIdentity/ProjectInputPathIdentity";
+export * from "./pathIdentity/ProjectInputPathIdentityOperations";
+export * from "./pathIdentity/ProjectInputPathIdentityContext";
+export * from "./pathIdentity/createProjectInputPathIdentityContext";
+export * from "./pathIdentity/isProjectInputPathIdentityWithin";
+export * from "./pathIdentity/resolveProjectInputPath";
+export * from "../compiler/internal/project/resolveProjectIdentity";
+export type { ITtscProjectIdentity } from "../structures/internal/ITtscProjectIdentity";
+export type { ITtscProjectLocatorOptions } from "../structures/internal/ITtscProjectLocatorOptions";

package/src/internal/resolveNodeBinary.ts

@@ -1,180 +1,28 @@
-import childProcess from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-
-import { captureProcessOutput } from "../compiler/internal/captureProcessOutput";
-import {
-  isSpawnSyncFdExhaustion,
-  spawnSyncWithLowDescriptors,
-} from "./spawnSyncResilient";
-
-export type JavaScriptRuntimeCapabilities = {
-  bun: boolean;
-  executable?: string;
-  registerHooks: boolean;
-};
-
-type RuntimeCapabilityCacheEntry = {
-  capabilities: JavaScriptRuntimeCapabilities;
-  identity: string;
-};
-
-const runtimeCapabilityCache = new Map<string, RuntimeCapabilityCacheEntry>();
-
-/** Probe an interpreter instead of inferring its identity from the host. */
-export function javascriptRuntimeCapabilities(
-  runtime: string,
-  env: NodeJS.ProcessEnv,
-  cwd: string,
-): JavaScriptRuntimeCapabilities {
-  const effectiveEnv = { ...process.env, ...env };
-  const cacheKey = runtimeCapabilityCacheKey(runtime, effectiveEnv);
-  const beforeIdentity = runtimeExecutableIdentity(runtime);
-  if (cacheKey !== undefined && beforeIdentity !== undefined) {
-    const cached = runtimeCapabilityCache.get(cacheKey);
-    if (cached?.identity === beforeIdentity) return { ...cached.capabilities };
-    runtimeCapabilityCache.delete(cacheKey);
-  }
-  const args = [
-    "-e",
-    `const Module = require("node:module"); process.stdout.write(JSON.stringify({ bun: typeof globalThis.Bun === "object", executable: process.execPath, registerHooks: typeof Module.registerHooks === "function" }));`,
-  ];
-  const options = {
-    cwd,
-    encoding: "utf8" as const,
-    env: effectiveEnv,
-    timeout: 30_000,
-    windowsHide: true,
-  };
-  let result = childProcess.spawnSync(runtime, args, options);
-  if (process.platform !== "win32" && isSpawnSyncFdExhaustion(result.error)) {
-    const capture = captureProcessOutput();
-    try {
-      const retried = spawnSyncWithLowDescriptors(runtime, args, options, {
-        stderr: capture.stderrPath,
-        stdout: capture.stdoutPath,
-      });
-      const stdout = capture.read("stdout", "utf8") as string;
-      const stderr = capture.read("stderr", "utf8") as string;
-      result = {
-        ...retried,
-        output: [null, stdout, stderr],
-        stderr,
-        stdout,
-      };
-    } finally {
-      capture.dispose();
-    }
-  }
-  let capabilities: JavaScriptRuntimeCapabilities = {
-    bun: false,
-    registerHooks: false,
-  };
-  if (result.status === 0) {
-    try {
-      const parsed = JSON.parse(
-        result.stdout,
-      ) as Partial<JavaScriptRuntimeCapabilities>;
-      capabilities = {
-        bun: parsed.bun === true,
-        ...(typeof parsed.executable === "string" &&
-        path.isAbsolute(parsed.executable)
-          ? { executable: path.resolve(parsed.executable) }
-          : {}),
-        registerHooks: parsed.registerHooks === true,
-      };
-    } catch {
-      // An incompatible executable is not a Node runtime candidate.
-    }
-  }
-  // Cache successful absolute candidates only when the child reports that same
-  // executable and both its lexical link and physical target retain the same
-  // filesystem identity. Relative/bare commands and wrappers can resolve
-  // differently by cwd/PATH/environment, negative probes can become valid later,
-  // and NODE_OPTIONS can load mutable user code, so none of those states are
-  // memoized. This removes a process spawn from the common path without
-  // authorizing a replaced or redirected runtime in a long-lived host.
-  const afterIdentity = runtimeExecutableIdentity(runtime);
-  if (
-    cacheKey !== undefined &&
-    capabilities.executable !== undefined &&
-    beforeIdentity !== undefined &&
-    beforeIdentity === afterIdentity &&
-    sameRuntimeExecutable(runtime, capabilities.executable)
-  ) {
-    runtimeCapabilityCache.set(cacheKey, {
-      capabilities: { ...capabilities },
-      identity: afterIdentity,
-    });
-  }
-  return capabilities;
-}
-
-/** True when a probe ran the candidate itself rather than a mutable wrapper. */
-function sameRuntimeExecutable(candidate: string, executable: string): boolean {
-  try {
-    const candidateStats = fs.statSync(candidate, { bigint: true });
-    const executableStats = fs.statSync(executable, { bigint: true });
-    return (
-      (candidateStats.ino !== 0n &&
-        candidateStats.dev === executableStats.dev &&
-        candidateStats.ino === executableStats.ino) ||
-      fs.realpathSync.native(candidate) === fs.realpathSync.native(executable)
-    );
-  } catch {
-    return false;
-  }
-}
-
-/** Stable cache key only for an absolute runtime with no preload authority. */
-function runtimeCapabilityCacheKey(
-  runtime: string,
-  env: NodeJS.ProcessEnv,
-): string | undefined {
-  if (!path.isAbsolute(runtime) || env.NODE_OPTIONS?.trim()) return undefined;
-  return path.resolve(runtime);
-}
-
-/** Identity of an executable spelling and the physical file it selects. */
-function runtimeExecutableIdentity(runtime: string): string | undefined {
-  if (!path.isAbsolute(runtime)) return undefined;
-  try {
-    const lexical = fs.lstatSync(runtime, { bigint: true });
-    const physicalPath = fs.realpathSync.native(runtime);
-    const physical = fs.statSync(physicalPath, { bigint: true });
-    return [
-      physicalPath,
-      lexical.dev,
-      lexical.ino,
-      lexical.mode,
-      lexical.size,
-      lexical.mtimeNs,
-      lexical.ctimeNs,
-      physical.dev,
-      physical.ino,
-      physical.mode,
-      physical.size,
-      physical.mtimeNs,
-      physical.ctimeNs,
-    ].join("\0");
-  } catch {
-    return undefined;
-  }
-}
+import { SidecarEnvironment } from "../compiler/internal/sharedHost/SidecarEnvironment";
+import { javascriptRuntimeCapabilities } from "./javascriptRuntimeCapabilities";
 
 /**
  * Locate a real Node runtime for ttsx and native JavaScript config loaders.
  *
  * Bun can directly evaluate a descriptor, but it does not implement the
  * synchronous `module.registerHooks` contract used by those loaders.
+ *
+ * @evidence contracts/common.md#principled-implementation Ordered candidates are accepted only after an actual runtime probe reports non-Bun registerHooks support and its absolute executable; names alone do not establish the loader capability.
+ * @evidence contracts/common.md#clear-and-simple-design Candidate precedence and duplicate suppression remain here, while the shared probe owns launch, capability parsing and freshness policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The node spelling is a supported final discovery candidate, not an assumed successful runtime; incompatible candidates are skipped without patching modules or globals.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the consumer and the required synchronous hook capability, while the selection loop makes precedence apparent without redundant prose.
+ * @evidence contracts/portability.md#os-neutral-implementation Executable discovery reads injected Windows environment names case-insensitively, measures candidates through native spawning and returns the child's absolute executable.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate references and seen spellings are invocation-local and become reclaimable after return. The delegated synchronous probe owns child/capture cleanup and its persistent capability map; the four-candidate list does not bound that historical map, which has no eviction policy.
+ * @evidence contracts/performance.md#efficient-algorithms At most four candidate slots are inspected with first-usable short-circuiting and exact-spelling deduplication. Environment-key/spelling work and delegated executable-byte identity, environment merge, native probing/parsing or descriptor-exhaustion retry costs dominate; four slots do not bound executable bytes, output text or native work.
+ * @evidence contracts/performance.md#reuse-equivalent-work Exact duplicate spellings share one candidate probe within this call. The probe owner additionally reuses stable absolute same-executable capabilities only while byte/link/target identity and no-preload authority hold; relative, wrapper, changed and unproven failed candidates need fresh observation.
  */
 export function resolveNodeBinary(
   env: NodeJS.ProcessEnv = process.env,
   cwd: string = process.cwd(),
 ): string | undefined {
   const candidates = [
-    env.TTSC_NODE_BINARY,
-    process.env.TTSC_NODE_BINARY,
+    SidecarEnvironment.read(env, "TTSC_NODE_BINARY"),
+    SidecarEnvironment.read(process.env, "TTSC_NODE_BINARY"),
     process.execPath,
     "node",
   ];