Introduce typed path invariants throughout tsc

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.

Author: jakebailey

Herebyfile.mjs

@@ -419,6 +419,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 } from "../proto.ts";
 import type {
     NodeHandle,
@@ -387,26 +391,26 @@ 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[];
 }
 
 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,24 +1,42 @@
-import { getPathComponents } from "./path.ts";
+import type {
+    RootedDirectoryPath,
+    RootedFilePath,
+    RootedPath,
+} from "../ast/index.ts";
+import {
+    getPathComponents,
+    toRootedFilePath,
+} from "./path.ts";
 
 export interface FileSystemEntries {
     files: string[];
     directories: string[];
 }
 
 export interface FileSystem {
-    directoryExists?: (directoryName: string) => boolean | undefined;
-    fileExists?: (fileName: string) => boolean | undefined;
-    getAccessibleEntries?: (directoryName: string) => FileSystemEntries | 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;
-    realpath?: (path: string) => string | undefined;
-    writeFile?: (path: string, content: string) => void;
-    removeFile?: (path: string) => void;
+    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. */
@@ -35,15 +53,16 @@ interface VFile {
 
 type VNode = VDirectory | VFile;
 
-export function createVirtualFileSystem(files: Record<string, string>): FileSystem {
+export function createVirtualFileSystem(files: Record<string, string>): VirtualFileSystem {
     const root: VDirectory = {
         type: "directory",
         children: {},
     };
-    const content: Record<string, string> = {};
+    const content = new Map<RootedFilePath, string>();
 
-    for (const filePath of Object.keys(files)) {
-        content[filePath] = files[filePath];
+    for (const [rawFilePath, data] of Object.entries(files)) {
+        const filePath = toRootedFilePath(rawFilePath, undefined);
+        content.set(filePath, data);
         addToTree(filePath);
     }
 
@@ -57,11 +76,14 @@ export function createVirtualFileSystem(files: Record<string, string>): FileSyst
         removeFile,
     };
 
-    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") {
@@ -90,7 +112,7 @@ export function createVirtualFileSystem(files: Record<string, string>): FileSyst
         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}"`);
@@ -100,32 +122,32 @@ export function createVirtualFileSystem(files: Record<string, string>): FileSyst
         dirNode.children[filename] = { type: "file" };
     }
 
-    function writeFile(path: string, data: string): void {
-        content[path] = data;
+    function writeFile(path: RootedFilePath, data: string): void {
+        content.set(path, data);
         addToTree(path);
     }
 
-    function removeFile(path: string): void {
-        delete content[path];
+    function removeFile(path: RootedFilePath): void {
+        content.delete(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[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 fileName in content;
+    function fileExists(fileName: RootedFilePath): boolean {
+        return content.has(fileName);
     }
 
-    function getAccessibleEntries(directoryName: string): FileSystemEntries | undefined {
+    function getAccessibleEntries(directoryName: RootedDirectoryPath): FileSystemEntries | undefined {
         const node = getNodeFromPath(directoryName);
         if (!node || node.type !== "directory") {
             return undefined;
@@ -143,10 +165,7 @@ export function createVirtualFileSystem(files: Record<string, string>): FileSyst
         return { files: fileEntries, directories };
     }
 
-    function readFile(fileName: string): string | undefined {
-        if (fileName in content) {
-            return content[fileName];
-        }
-        return undefined;
+    function readFile(fileName: RootedFilePath): string | undefined {
+        return content.get(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";
@@ -52,7 +53,7 @@ export interface SourceFileInfo {
     readonly _offsetStructuredData: number;
     readonly _decoder: TextDecoder;
     nodes: any[];
-    readonly path?: string;
+    readonly path?: PathKey;
     /**
      * The timing collector that per-node materialization is reported into, and
      * that this source file registered itself with when fetched. Present only