Add code comments for certain castings

Author: nojaf

client/src/utils.ts

@@ -26,6 +26,7 @@ export type NormalizedPath = string & { __brand: "NormalizedPath" };
  * @returns The normalized path, or null if input was null
  */
 export function normalizePath(filePath: string | null): NormalizedPath | null {
+  // `path.normalize` ensures we can assume string is now NormalizedPath
   return filePath != null ? (path.normalize(filePath) as NormalizedPath) : null;
 }
 

server/src/find-runtime.ts

@@ -1,7 +1,7 @@
 import { readdir, stat as statAsync, readFile } from "fs/promises";
 import { join, resolve } from "path";
 import { compilerInfoPartialPath } from "./constants";
-import { NormalizedPath } from "./utils";
+import { NormalizedPath, normalizePath } from "./utils";
 
 // Efficient parallel folder traversal to find node_modules directories
 async function findNodeModulesDirs(
@@ -102,7 +102,9 @@ async function findRuntimePath(
     const contents = await readFile(compilerInfo, "utf8");
     const compileInfo: { runtime_path?: string } = JSON.parse(contents);
     if (compileInfo && compileInfo.runtime_path) {
-      return [compileInfo.runtime_path as NormalizedPath];
+      // We somewhat assume the user to pass down a normalized path, but we cannot be sure of this.
+      const normalizedRuntimePath = normalizePath(compileInfo.runtime_path);
+      return normalizedRuntimePath ? [normalizedRuntimePath] : [];
     }
   } catch {
     // Ignore errors, fallback to node_modules search
@@ -150,6 +152,7 @@ async function findRuntimePath(
   ).then((results) => results.flatMap((x) => x));
 
   return rescriptRuntimeDirs.map(
+    // `resolve` ensures we can assume string is now NormalizedPath
     (runtime) => resolve(runtime) as NormalizedPath,
   );
 }

server/src/incrementalCompilation.ts

@@ -302,11 +302,13 @@ function triggerIncrementalCompilationOfFile(
         ? `${moduleName}-${project.namespaceName}`
         : moduleName;
 
+    // projectRootPath is already NormalizedPath, appending a constant string still makes it a NormalizedPath
     const incrementalFolderPath: NormalizedPath = path.join(
       projectRootPath,
       INCREMENTAL_FILE_FOLDER_LOCATION,
     ) as NormalizedPath;
 
+    // projectRootPath is already NormalizedPath, appending a constant string still makes it a NormalizedPath
     let originalTypeFileLocation = path.resolve(
       projectRootPath,
       c.compilerDirPartialPath,
@@ -316,6 +318,7 @@ function triggerIncrementalCompilationOfFile(
     const parsed = path.parse(originalTypeFileLocation);
     parsed.ext = ext === ".res" ? ".cmt" : ".cmti";
     parsed.base = "";
+    // As originalTypeFileLocation was a NormalizedPath, path.format ensures we can assume string is now NormalizedPath
     originalTypeFileLocation = path.format(parsed) as NormalizedPath;
 
     incrementalFileCacheEntry = {
@@ -326,6 +329,7 @@ function triggerIncrementalCompilationOfFile(
         moduleNameNamespaced,
         sourceFileName: moduleName + ext,
         sourceFilePath: filePath,
+        // As incrementalFolderPath was a NormalizedPath, path.join ensures we can assume string is now NormalizedPath
         incrementalFilePath: path.join(
           incrementalFolderPath,
           moduleName + ext,

server/src/utils.ts

@@ -51,6 +51,7 @@ export type FileURI = string & { __brand: "FileURI" };
  * @returns The normalized path, or null if input was null
  */
 export function normalizePath(filePath: string | null): NormalizedPath | null {
+  // `path.normalize` ensures we can assume string is now NormalizedPath
   return filePath != null ? (path.normalize(filePath) as NormalizedPath) : null;
 }
 
@@ -77,6 +78,7 @@ let tempFileId = 0;
 export let createFileInTempDir = (extension = ""): NormalizedPath => {
   let tempFileName = tempFilePrefix + tempFileId + extension;
   tempFileId = tempFileId + 1;
+  // `os.tmpdir` returns an absolute path, so `path.join` ensures we can assume string is now NormalizedPath
   return path.join(os.tmpdir(), tempFileName) as NormalizedPath;
 };
 
@@ -715,6 +717,7 @@ export let runBuildWatcherUsingValidBuildPath = (
 
 // parser helpers
 export let pathToURI = (file: NormalizedPath): FileURI => {
+  // `pathToFileURL` ensures we can assume string is now FileURI
   return pathToFileURL(file).toString() as FileURI;
 };
 let parseFileAndRange = (fileAndRange: string) => {
@@ -953,10 +956,9 @@ export let parseCompilerLogOutput = async (
   for (const parsedDiagnostic of parsedDiagnostics) {
     let [fileAndRangeLine, ...diagnosticMessage] = parsedDiagnostic.content;
     let { file, range } = parseFileAndRange(fileAndRangeLine);
-    const fileUri = file as FileURI;
 
-    if (result[fileUri] == null) {
-      result[fileUri] = [];
+    if (result[file] == null) {
+      result[file] = [];
     }
 
     // remove start and end whitespaces/newlines
@@ -982,7 +984,7 @@ export let parseCompilerLogOutput = async (
         range,
       });
 
-      result[fileUri].push(diagnostic);
+      result[file].push(diagnostic);
     }
   }