Introduce typed path invariants throughout tsc (TYPED PATHS)

Replace ambiguous string path contracts with a typed lattice for rooted
files, rooted directories, normalized relative paths, and canonical path
keys. Keep canonical identity as a one-way sink while retaining
presentation spelling wherever diagnostics, watches, symlinks, or
protocol responses need it.

Carry those invariants through compiler inputs and outputs, module
resolution, project snapshots, language-service hosts, VFS operations,
source maps, LSP conversion, and the JavaScript API. Separate raw
compiler option wire values from finalized rooted options, and
centralize explicit normalization, rooting, and case-sensitivity
boundaries.

This commit consolidates the exploratory migration into one reviewable
rewrite after the independently portable fixes. It also adapts those
fixes to the typed representation and retains the two newer main
changes, including auto-import completion retries and tuple completion
filtering.

Category: Typed-path migration

Author: jakebailey

Herebyfile.mjs

@@ -623,6 +623,7 @@ const enumDefs = [
     { name: "NewLineKind", goPrefix: "NewLineKind", goFile: "tsc/internal/core/compileroptions.go", outDir: "packages/typescript/src/enums" },
     { name: "JsxEmit", goPrefix: "JsxEmit", goFile: "tsc/internal/core/compileroptions.go", outDir: "packages/typescript/src/enums" },
     { name: "ScriptKind", goPrefix: "ScriptKind", goFile: "tsc/internal/core/scriptkind.go", outDir: "packages/typescript/src/enums" },
+    { name: "CaseSensitivity", goPrefix: "Case", goFile: "tsc/internal/tspath/path.go", outDir: "packages/typescript/src/enums" },
     { name: "TokenFlags", goPrefix: "TokenFlags", goFile: "tsc/internal/ast/tokenflags.go", outDir: "packages/typescript/src/enums" },
     { name: "DiagnosticDirectivePolicy", goPrefix: "MappedDiagnosticDirectivePolicy", goFile: "tsc/internal/ast/ast.go", outDir: "packages/typescript/src/enums" },
     { name: "SpanMapKind", goPrefix: "Kind", goFile: "tsc/internal/spanmap/spanmap.go", outDir: "packages/typescript/src/enums" },

packages/typescript/package.json

@@ -50,6 +50,10 @@
             "@typescript/source": "./src/api/fs.ts",
             "default": "./dist/api/fs.js"
         },
+        "./unstable/path": {
+            "@typescript/source": "./src/api/typedPaths.ts",
+            "default": "./dist/api/typedPaths.js"
+        },
         "./unstable/proto": {
             "@typescript/source": "./src/api/proto.ts",
             "default": "./dist/api/proto.js"

packages/typescript/src/api/async/api.ts

@@ -9,6 +9,11 @@ import {
 } from "#vscode-jsonrpc/node";
 import type { ChildProcess } from "node:child_process";
 import type { Socket } from "node:net";
+import type {
+    RootedDirectoryPath,
+    RootedFilePath,
+    RootedPath,
+} from "../../ast/index.ts";
 import {
     type FileSystem,
     fsCallbackNames,
@@ -141,32 +146,45 @@ export class Client {
     private registerFSCallbacks(connection: MessageConnection, fs: FileSystem | undefined): void {
         if (!fs) return;
         for (const name of fsCallbackNames) {
-            if (name === "writeFile") {
-                if (!fs.writeFile) continue;
-                const callback = fs.writeFile;
-
-                const requestType = new RequestType<{ path: string; data: string; }, unknown, void>(name);
-                connection.onRequest(requestType, (arg: { path: string; data: string; }) => {
-                    callback(arg.path, arg.data);
-                    return null;
-                });
-
-                continue;
-            }
-
-            const callback = fs[name];
-            if (callback) {
-                const requestType = new RequestType<unknown, unknown, void>(name);
-                connection.onRequest(requestType, (arg: unknown) => {
-                    const result = callback(arg as any);
-                    if (name === "readFile") {
-                        // readFile has 3 returns: string (content), null (not found), undefined (fall back).
-                        // JSON-RPC can't distinguish null from undefined, so wrap in object.
-                        if (result === undefined) return null;
-                        return { content: result };
+            switch (name) {
+                case "readFile":
+                    if (fs.readFile) {
+                        connection.onRequest(new RequestType<RootedFilePath, unknown, void>(name), fileName => {
+                            const result = fs.readFile!(fileName);
+                            // readFile has 3 returns: string (content), null (not found), undefined (fall back).
+                            // JSON-RPC can't distinguish null from undefined, so wrap in object.
+                            return result === undefined ? null : { content: result };
+                        });
+                    }
+                    break;
+                case "fileExists":
+                    if (fs.fileExists) {
+                        connection.onRequest(new RequestType<RootedFilePath, unknown, void>(name), fileName => fs.fileExists!(fileName) ?? null);
+                    }
+                    break;
+                case "directoryExists":
+                    if (fs.directoryExists) {
+                        connection.onRequest(new RequestType<RootedDirectoryPath, unknown, void>(name), directoryName => fs.directoryExists!(directoryName) ?? null);
+                    }
+                    break;
+                case "getAccessibleEntries":
+                    if (fs.getAccessibleEntries) {
+                        connection.onRequest(new RequestType<RootedDirectoryPath, unknown, void>(name), directoryName => fs.getAccessibleEntries!(directoryName) ?? null);
+                    }
+                    break;
+                case "realpath":
+                    if (fs.realpath) {
+                        connection.onRequest(new RequestType<RootedPath, unknown, void>(name), path => fs.realpath!(path) ?? null);
+                    }
+                    break;
+                case "writeFile":
+                    if (fs.writeFile) {
+                        connection.onRequest(new RequestType<{ path: RootedFilePath; data: string; }, unknown, void>(name), arg => {
+                            fs.writeFile!(arg.path, arg.data);
+                            return null;
+                        });
                     }
-                    return result ?? null;
-                });
+                    break;
             }
         }
     }

packages/typescript/src/api/async/client.ts

@@ -8,6 +8,10 @@ import type {
     NamedTupleMember,
     ParameterDeclaration,
 } from "../../ast/ast.ts";
+import type {
+    RootedDirectoryPath,
+    RootedFilePath,
+} from "../../ast/index.ts";
 import type {
     Diagnostic,
     RequestFileSystem,
@@ -396,28 +400,28 @@ export interface CompletionInfo {
 }
 
 export interface FormatDiagnosticsHost {
-    getCurrentDirectory(): string;
+    getCurrentDirectory(): RootedDirectoryPath;
     getCanonicalFileName(fileName: string): string;
     getNewLine(): string;
 }
 
 export interface EmitOutputFile {
     readonly text: string;
-    readonly sourceFileName?: string | undefined;
+    readonly sourceFileName?: RootedFilePath | undefined;
 }
 
 export interface EmitResult {
     readonly emitSkipped: boolean;
     readonly diagnostics: readonly Diagnostic[];
-    readonly emittedFiles: readonly string[];
+    readonly emittedFiles: readonly RootedFilePath[];
     /** Emitted files captured as a filesystem layer suitable for {@link Snapshot.update}. */
     readonly fileSystem?: RequestFileSystem | undefined;
 }
 
 export interface EmitOutput {
     readonly emitSkipped: boolean;
     readonly diagnostics: readonly Diagnostic[];
-    readonly outputFiles: ReadonlyMap<string, EmitOutputFile>;
+    readonly outputFiles: ReadonlyMap<RootedFilePath, EmitOutputFile>;
 }
 
 export interface ImportSymbolAction {

packages/typescript/src/api/async/types.ts

@@ -1,8 +1,12 @@
+import type {
+    RootedDirectoryPath,
+    RootedFilePath,
+} from "../ast/index.ts";
 import { convertToRelativePath } from "./path.ts";
 import type { DiagnosticResponse as Diagnostic } from "./proto.generated.ts";
 
 export interface FormatDiagnosticsHost {
-    getCurrentDirectory(): string;
+    getCurrentDirectory(): RootedDirectoryPath;
     getCanonicalFileName(fileName: string): string;
     getNewLine(): string;
 }
@@ -70,7 +74,7 @@ function flattenDiagnosticMessage(diagnostic: Diagnostic, newLine: string, inden
     return result;
 }
 
-function relativeFileName(fileName: string, host: FormatDiagnosticsHost): string {
+function relativeFileName(fileName: RootedFilePath, host: FormatDiagnosticsHost): string {
     return convertToRelativePath(
         fileName,
         host.getCurrentDirectory(),

packages/typescript/src/api/diagnosticFormatter.ts

@@ -1,9 +1,16 @@
 import getExePath from "#getExePath";
 import { dirname } from "node:path";
+import type {
+    RootedDirectoryPath,
+    RootedFilePath,
+    RootedPath,
+} from "../ast/index.ts";
 import {
-    createGetCanonicalFileName,
+    canonicalize,
+    CaseSensitivity,
     getPathComponents,
     normalizePath,
+    toRootedFilePath,
 } from "./path.ts";
 import type {
     RequestDirectoryEntries,
@@ -21,19 +28,29 @@ export interface FileSystemEntries {
 }
 
 export interface FileSystem {
-    directoryExists?: ((directoryName: string) => boolean | undefined) | undefined;
-    fileExists?: ((fileName: string) => boolean | undefined) | undefined;
-    getAccessibleEntries?: ((directoryName: string) => FileSystemEntries | undefined) | undefined;
+    directoryExists?: (directoryName: RootedDirectoryPath) => boolean | undefined;
+    fileExists?: (fileName: RootedFilePath) => boolean | undefined;
+    getAccessibleEntries?: (directoryName: RootedDirectoryPath) => FileSystemEntries | undefined;
     /**
      * Read a file's content.
      * - Return the file content as a `string` (including `""` for empty files).
      * - Return `null` to indicate the file does not exist (without falling back to the real FS).
      * - Return `undefined` to fall back to the real filesystem.
      */
-    readFile?: ((fileName: string) => string | null | undefined) | undefined;
-    realpath?: ((path: string) => string | undefined) | undefined;
-    writeFile?: ((path: string, content: string) => void) | undefined;
-    removeFile?: ((path: string) => void) | undefined;
+    readFile?: (fileName: RootedFilePath) => string | null | undefined;
+    realpath?: (path: RootedPath) => RootedPath | undefined;
+    writeFile?: (path: RootedFilePath, content: string) => void;
+    removeFile?: (path: RootedFilePath) => void;
+}
+
+export interface VirtualFileSystem extends FileSystem {
+    directoryExists(directoryName: RootedDirectoryPath): boolean;
+    fileExists(fileName: RootedFilePath): boolean;
+    getAccessibleEntries(directoryName: RootedDirectoryPath): FileSystemEntries | undefined;
+    readFile(fileName: RootedFilePath): string | undefined;
+    realpath(path: RootedPath): RootedPath;
+    writeFile(path: RootedFilePath, content: string): void;
+    removeFile(path: RootedFilePath): void;
 }
 
 /** The callback names supported by the Go server for virtual FS delegation. */
@@ -53,7 +70,7 @@ export interface CreateFileSystemWithLibOptions extends CreateFileSystemOptions
 }
 
 export interface CreateVirtualFileSystemOptions {
-    useCaseSensitiveFileNames?: boolean;
+    caseSensitivity?: CaseSensitivity;
 }
 
 /**
@@ -201,13 +218,14 @@ function createVDirectory(name: string): VDirectory {
 export function createVirtualFileSystem(
     files: Record<string, string>,
     options: CreateVirtualFileSystemOptions = {},
-): FileSystem {
-    const getCanonicalFileName = createGetCanonicalFileName(options.useCaseSensitiveFileNames !== false);
+): VirtualFileSystem {
+    const caseSensitivity = options.caseSensitivity ?? CaseSensitivity.Sensitive;
     const root = createVDirectory("");
     const content = new Map<string, string>();
 
-    for (const [filePath, data] of Object.entries(files)) {
-        const key = getCanonicalFileName(filePath);
+    for (const [rawFilePath, data] of Object.entries(files)) {
+        const filePath = toRootedFilePath(rawFilePath, undefined);
+        const key = getKey(filePath);
         if (content.has(key)) {
             throw new Error(`Duplicate virtual filesystem path: ${filePath}`);
         }
@@ -225,15 +243,22 @@ export function createVirtualFileSystem(
         removeFile,
     };
 
+    function getKey(path: RootedPath): string {
+        return canonicalize(path, caseSensitivity);
+    }
+
     function getSegmentKey(segment: string): string {
-        return getCanonicalFileName(segment);
+        return canonicalize(segment, caseSensitivity);
     }
 
-    function getNodeFromPath(path: string): VNode | undefined {
+    function getNodeFromPath(path: RootedPath): VNode | undefined {
         if (!path || path === "/") {
             return root;
         }
-        const segments = getPathComponents(path).slice(1);
+        return getNodeFromSegments(getPathComponents(path).slice(1));
+    }
+
+    function getNodeFromSegments(segments: readonly string[]): VNode | undefined {
         let current: VNode = root;
         for (const segment of segments) {
             if (current.type !== "directory") {
@@ -263,7 +288,7 @@ export function createVirtualFileSystem(
         return current;
     }
 
-    function addToTree(path: string): void {
+    function addToTree(path: RootedFilePath): void {
         const segments = getPathComponents(path).slice(1);
         if (segments.length === 0) {
             throw new Error(`Invalid file path: "${path}"`);
@@ -275,32 +300,32 @@ export function createVirtualFileSystem(
         dirNode.children[key] = { type: "file", name: existing?.name ?? filename };
     }
 
-    function writeFile(path: string, data: string): void {
-        content.set(getCanonicalFileName(path), data);
+    function writeFile(path: RootedFilePath, data: string): void {
+        content.set(getKey(path), data);
         addToTree(path);
     }
 
-    function removeFile(path: string): void {
-        content.delete(getCanonicalFileName(path));
+    function removeFile(path: RootedFilePath): void {
+        content.delete(getKey(path));
         const segments = getPathComponents(path).slice(1);
         if (segments.length === 0) return;
         const filename = segments.pop()!;
-        const dirNode = getNodeFromPath("/" + segments.join("/"));
+        const dirNode = getNodeFromSegments(segments);
         if (dirNode && dirNode.type === "directory") {
             delete dirNode.children[getSegmentKey(filename)];
         }
     }
 
-    function directoryExists(directoryName: string): boolean {
+    function directoryExists(directoryName: RootedDirectoryPath): boolean {
         const node = getNodeFromPath(directoryName);
         return !!node && node.type === "directory";
     }
 
-    function fileExists(fileName: string): boolean {
-        return content.has(getCanonicalFileName(fileName));
+    function fileExists(fileName: RootedFilePath): boolean {
+        return content.has(getKey(fileName));
     }
 
-    function getAccessibleEntries(directoryName: string): FileSystemEntries | undefined {
+    function getAccessibleEntries(directoryName: RootedDirectoryPath): FileSystemEntries | undefined {
         const node = getNodeFromPath(directoryName);
         if (!node || node.type !== "directory") {
             return undefined;
@@ -318,7 +343,7 @@ export function createVirtualFileSystem(
         return { files: fileEntries, directories };
     }
 
-    function readFile(fileName: string): string | undefined {
-        return content.get(getCanonicalFileName(fileName));
+    function readFile(fileName: RootedFilePath): string | undefined {
+        return content.get(getKey(fileName));
     }
 }

packages/typescript/src/api/fs.ts

@@ -2,6 +2,7 @@ import {
     type FileReference,
     ModifierFlags,
     type Node,
+    type PathKey,
     SyntaxKind,
 } from "../../ast/index.ts";
 import type { TimingCollector } from "../timing.ts";