Strongly type file paths

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/client.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 { FileSystemCallbacks } from "../fs.ts";
 import {
     configureFileSystemCallbacks,
@@ -142,24 +147,72 @@ export class Client {
     ): void {
         if (!fs) return;
         for (const name of configuration.callbackNames) {
-            if (name === "writeFile") {
-                const callback = fs.writeFile;
-                if (typeof callback !== "function") throw new Error("Invalid writeFile callback configuration");
-
-                const requestType = new RequestType<{ path: string; data: string; }, unknown, void>(name);
-                connection.onRequest(requestType, (arg: { path: string; data: string; }) => {
-                    return encodeFileSystemCallbackResult(name, callback(arg.path, arg.data));
-                });
-
-                continue;
+            switch (name) {
+                case "readFile": {
+                    const callback = fs.readFile;
+                    if (typeof callback !== "function") throw new Error("Invalid readFile callback configuration");
+                    connection.onRequest(new RequestType<RootedFilePath, unknown, void>(name), fileName => {
+                        return encodeFileSystemCallbackResult(name, callback(fileName));
+                    });
+                    break;
+                }
+                case "fileExists": {
+                    const callback = fs.fileExists;
+                    if (typeof callback !== "function") throw new Error("Invalid fileExists callback configuration");
+                    connection.onRequest(new RequestType<RootedFilePath, unknown, void>(name), fileName => {
+                        return encodeFileSystemCallbackResult(name, callback(fileName));
+                    });
+                    break;
+                }
+                case "directoryExists": {
+                    const callback = fs.directoryExists;
+                    if (typeof callback !== "function") throw new Error("Invalid directoryExists callback configuration");
+                    connection.onRequest(new RequestType<RootedDirectoryPath, unknown, void>(name), directoryName => {
+                        return encodeFileSystemCallbackResult(name, callback(directoryName));
+                    });
+                    break;
+                }
+                case "getAccessibleEntries": {
+                    const callback = fs.getAccessibleEntries;
+                    if (typeof callback !== "function") throw new Error("Invalid getAccessibleEntries callback configuration");
+                    connection.onRequest(new RequestType<RootedDirectoryPath, unknown, void>(name), directoryName => {
+                        return encodeFileSystemCallbackResult(name, callback(directoryName));
+                    });
+                    break;
+                }
+                case "realpath": {
+                    const callback = fs.realpath;
+                    if (typeof callback !== "function") throw new Error("Invalid realpath callback configuration");
+                    connection.onRequest(new RequestType<RootedPath, unknown, void>(name), path => {
+                        return encodeFileSystemCallbackResult(name, callback(path));
+                    });
+                    break;
+                }
+                case "stat": {
+                    const callback = fs.stat;
+                    if (typeof callback !== "function") throw new Error("Invalid stat callback configuration");
+                    connection.onRequest(new RequestType<RootedPath, unknown, void>(name), path => {
+                        return encodeFileSystemCallbackResult(name, callback(path));
+                    });
+                    break;
+                }
+                case "writeFile": {
+                    const callback = fs.writeFile;
+                    if (typeof callback !== "function") throw new Error("Invalid writeFile callback configuration");
+                    connection.onRequest(new RequestType<{ path: RootedFilePath; data: string; }, unknown, void>(name), arg => {
+                        return encodeFileSystemCallbackResult(name, callback(arg.path, arg.data));
+                    });
+                    break;
+                }
+                case "removeFile": {
+                    const callback = fs.removeFile;
+                    if (typeof callback !== "function") throw new Error("Invalid removeFile callback configuration");
+                    connection.onRequest(new RequestType<RootedPath, unknown, void>(name), path => {
+                        return encodeFileSystemCallbackResult(name, callback(path));
+                    });
+                    break;
+                }
             }
-
-            const callback = fs[name];
-            if (typeof callback !== "function") throw new Error(`Invalid ${name} callback configuration`);
-            const requestType = new RequestType<unknown, unknown, void>(name);
-            connection.onRequest(requestType, (arg: unknown) => {
-                return encodeFileSystemCallbackResult(name, callback(arg as string));
-            });
         }
     }
 

packages/typescript/src/api/async/types.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,
@@ -410,28 +414,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/diagnosticFormatter.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/fs.ts

@@ -1,5 +1,10 @@
 import getExePath from "#getExePath";
 import { dirname } from "node:path";
+import type {
+    RootedDirectoryPath,
+    RootedFilePath,
+    RootedPath,
+} from "../ast/index.ts";
 import { normalizePath } from "./path.ts";
 import type {
     RequestDirectoryEntries,
@@ -54,15 +59,15 @@ export const serverFS: {
 
 export interface FileSystemCallbacks {
     directoryExists:
-        | ((directoryName: string) => boolean | typeof serverFS.useOS | typeof serverFS.error)
+        | ((directoryName: RootedDirectoryPath) => boolean | typeof serverFS.useOS | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.error;
     fileExists:
-        | ((fileName: string) => boolean | typeof serverFS.useOS | typeof serverFS.error)
+        | ((fileName: RootedFilePath) => boolean | typeof serverFS.useOS | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.error;
     getAccessibleEntries:
-        | ((directoryName: string) => FileSystemEntries | typeof serverFS.useOS | typeof serverFS.error)
+        | ((directoryName: RootedDirectoryPath) => FileSystemEntries | typeof serverFS.useOS | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.error;
     /**
@@ -72,26 +77,26 @@ export interface FileSystemCallbacks {
      * - Return {@link serverFS.useOS} to fall back to the server's operating-system filesystem.
      */
     readFile:
-        | ((fileName: string) => string | undefined | typeof serverFS.useOS | typeof serverFS.error)
+        | ((fileName: RootedFilePath) => string | undefined | typeof serverFS.useOS | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.error;
     realpath:
-        | ((path: string) => string | typeof serverFS.useOS | typeof serverFS.identity | typeof serverFS.error)
+        | ((path: RootedPath) => RootedPath | typeof serverFS.useOS | typeof serverFS.identity | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.identity
         | typeof serverFS.error;
     stat:
-        | ((path: string) => FileSystemStat | undefined | typeof serverFS.useOS | typeof serverFS.fakeStat | typeof serverFS.error)
+        | ((path: RootedPath) => FileSystemStat | undefined | typeof serverFS.useOS | typeof serverFS.fakeStat | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.fakeStat
         | typeof serverFS.error;
     writeFile:
-        | ((path: string, content: string) => void | typeof serverFS.useOS | typeof serverFS.noop | typeof serverFS.error)
+        | ((path: RootedFilePath, content: string) => void | typeof serverFS.useOS | typeof serverFS.noop | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.noop
         | typeof serverFS.error;
     removeFile:
-        | ((path: string) => void | typeof serverFS.useOS | typeof serverFS.noop | typeof serverFS.error)
+        | ((path: RootedPath) => void | typeof serverFS.useOS | typeof serverFS.noop | typeof serverFS.error)
         | typeof serverFS.useOS
         | typeof serverFS.noop
         | typeof serverFS.error;

packages/typescript/src/api/node/node.infrastructure.ts

@@ -1,6 +1,7 @@
 import {
     type FileReference,
     type Node,
+    type PathKey,
     SyntaxKind,
 } from "../../ast/index.ts";
 export { modifierToFlag } from "../../ast/modifiers.ts";

packages/typescript/src/api/node/node.ts

@@ -5,13 +5,15 @@ import {
     type MappedDiagnosticDirective,
     type Node,
     NodeFlags,
-    type Path,
+    type PathKey,
+    type RootedFilePath,
     SpanMap,
     SpanMapFeature,
     SpanMapKind,
     SyntaxKind,
     TokenFlags,
 } from "../../ast/index.ts";
+import { tryPathKeyFromCanonical } from "../path.ts";
 import type { TimingCollector } from "../timing.ts";
 import { MsgpackReader } from "./msgpack.ts";
 import {
@@ -96,7 +98,7 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
     private _cachedAmbientModuleNames: readonly string[] | undefined;
     private _cachedSpanMap: SpanMap | undefined;
     private _spanMapRead = false;
-    private _cachedSupplementalSourceFileNames: readonly string[] | undefined;
+    private _cachedSupplementalSourceFileNames: readonly RootedFilePath[] | undefined;
     private _cachedDiagnosticDirectives: readonly MappedDiagnosticDirective[] | undefined;
     private _diagnosticDirectivesRead = false;
 
@@ -214,14 +216,26 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
         return this._offsetExtendedData + (this.data & NODE_EXTENDED_DATA_MASK);
     }
 
-    get fileName(): string {
+    private getFileName(stringIndex: number): RootedFilePath {
+        return this.getString(stringIndex) as RootedFilePath;
+    }
+
+    private getPathKey(stringIndex: number): PathKey {
+        return this.getString(stringIndex) as PathKey;
+    }
+
+    private readFileNameArray(structuredDataOffset: number): readonly RootedFilePath[] {
+        return this.readStringArray(structuredDataOffset) as readonly RootedFilePath[];
+    }
+
+    get fileName(): RootedFilePath {
         const stringIndex = this.view.getUint32(this.extendedDataOffset + sourceFileExtendedDataOffsets.FileName, true);
-        return this.getString(stringIndex);
+        return this.getFileName(stringIndex);
     }
 
-    get path(): Path {
+    get path(): PathKey {
         const stringIndex = this.view.getUint32(this.extendedDataOffset + sourceFileExtendedDataOffsets.Path, true);
-        return this.getString(stringIndex) as Path;
+        return this.getPathKey(stringIndex);
     }
 
     get languageVariant(): number {
@@ -323,26 +337,26 @@ export class RemoteSourceFile extends RemoteNode implements SourceFileInfo {
         return this._cachedSpanMap = new SpanMap(segments);
     }
 
-    get supplementalSourceFileNames(): readonly string[] | undefined {
+    get supplementalSourceFileNames(): readonly RootedFilePath[] | undefined {
         if (this._cachedSupplementalSourceFileNames !== undefined) return this._cachedSupplementalSourceFileNames;
         const offset = this.view.getUint32(this.extendedDataOffset + sourceFileExtendedDataOffsets.SupplementalSourceFileNames, true);
         if (offset === NO_STRUCTURED_DATA) return undefined;
-        return this._cachedSupplementalSourceFileNames = this.readStringArray(offset);
+        return this._cachedSupplementalSourceFileNames = this.readFileNameArray(offset);
     }
 
-    get canonicalSourceFileName(): string | undefined {
+    get canonicalSourceFileName(): RootedFilePath | undefined {
         const stringIndex = this.view.getUint32(this.extendedDataOffset + sourceFileExtendedDataOffsets.CanonicalSourceFileName, true);
-        return stringIndex === NO_STRUCTURED_DATA ? undefined : this.getString(stringIndex);
+        return stringIndex === NO_STRUCTURED_DATA ? undefined : this.getFileName(stringIndex);
     }
 
     get contentMapper(): string | undefined {
         const stringIndex = this.view.getUint32(this.extendedDataOffset + sourceFileExtendedDataOffsets.ContentMapper, true);
         return stringIndex === NO_STRUCTURED_DATA ? undefined : this.getString(stringIndex);
     }
 
-    get virtualFileName(): string | undefined {
+    get virtualFileName(): RootedFilePath | undefined {
         const stringIndex = this.view.getUint32(this.extendedDataOffset + sourceFileExtendedDataOffsets.VirtualFileName, true);
-        return stringIndex === NO_STRUCTURED_DATA ? undefined : this.getString(stringIndex);
+        return stringIndex === NO_STRUCTURED_DATA ? undefined : this.getFileName(stringIndex);
     }
 
     get diagnosticDirectives(): readonly MappedDiagnosticDirective[] | undefined {
@@ -453,14 +467,14 @@ export function findDescendant(root: Node, pos: number, end: number, kind: Synta
 export interface ParsedNodeHandle {
     index: number;
     kind: SyntaxKind;
-    path: Path;
+    path: PathKey;
 }
 
 /**
- * Parse a node handle string into its components.
+ * Parse a compiler-produced node handle into its components.
  * Handle format: "index.kind.path" where path may contain dots.
  */
-export function parseNodeHandle(handle: string): ParsedNodeHandle {
+export function parseNodeHandleFromCompiler(handle: string): ParsedNodeHandle {
     const firstDot = handle.indexOf(".");
     if (firstDot === -1) {
         throw new Error(`Invalid node handle: ${handle}`);
@@ -470,10 +484,27 @@ export function parseNodeHandle(handle: string): ParsedNodeHandle {
         throw new Error(`Invalid node handle: ${handle}`);
     }
 
+    const indexText = handle.slice(0, firstDot);
+    const kindText = handle.slice(firstDot + 1, secondDot);
+    const path = handle.slice(secondDot + 1);
+    const index = Number(indexText);
+    const kind = Number(kindText);
+    const key = tryPathKeyFromCanonical(path);
+    if (
+        !Number.isSafeInteger(index) ||
+        index < 0 ||
+        String(index) !== indexText ||
+        !Number.isSafeInteger(kind) ||
+        kind < 0 ||
+        String(kind) !== kindText ||
+        key === undefined
+    ) {
+        throw new Error(`Invalid node handle: ${handle}`);
+    }
     return {
-        index: parseInt(handle.slice(0, firstDot), 10),
-        kind: parseInt(handle.slice(firstDot + 1, secondDot), 10) as SyntaxKind,
-        path: handle.slice(secondDot + 1) as Path,
+        index,
+        kind: kind as SyntaxKind,
+        path: key,
     };
 }