Add ForwardSlashPath branded type and toForwardSlashPath utility function

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/1369f6f6-b129-4be5-b4c7-7337eefb6eaa

Author: Copilot

.changeset/add-forward-slash-path-utility.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Add `toForwardSlashPath` utility function and `ForwardSlashPath` branded type. All path normalization that previously used inline `.replaceAll("\\", "/")` now goes through this single, centralized function, making Windows path handling easier to find and reason about.

bin/counterfact.js

@@ -162,6 +162,14 @@ const { loadConfigFile } = await import(
   )
 );
 
+const { toForwardSlashPath } = await import(
+  resolve(
+    nativeTs
+      ? "../src/util/forward-slash-path.js"
+      : "../dist/util/forward-slash-path.js",
+  )
+);
+
 const DEFAULT_PORT = 3100;
 
 const debug = createDebug("counterfact:bin:counterfact");
@@ -314,9 +322,9 @@ async function main(source, destination) {
     source = options.spec;
   }
 
-  const destinationPath = nodePath.resolve(destination).replaceAll("\\", "/");
+  const destinationPath = toForwardSlashPath(nodePath.resolve(destination));
 
-  const basePath = nodePath.resolve(destinationPath).replaceAll("\\", "/");
+  const basePath = toForwardSlashPath(nodePath.resolve(destinationPath));
 
   // If no action-related option is provided, default to all options
 

src/app.ts

@@ -19,6 +19,7 @@ import { Transpiler } from "./server/transpiler.js";
 import { CodeGenerator } from "./typescript-generator/code-generator.js";
 import { writeScenarioContextType } from "./typescript-generator/generate.js";
 import { runtimeCanExecuteErasableTs } from "./util/runtime-can-execute-erasable-ts.js";
+import { toForwardSlashPath } from "./util/forward-slash-path.js";
 
 export { loadOpenApiDocument } from "./server/load-openapi-document.js";
 
@@ -113,9 +114,9 @@ export async function createMswHandlers(
   await fs.readFile(config.openApiPath);
   const openApiDocument = await loadOpenApiDocument(config.openApiPath);
   const modulesPath = config.basePath;
-  const compiledPathsDirectory = nodePath
-    .join(modulesPath, ".cache")
-    .replaceAll("\\", "/");
+  const compiledPathsDirectory = toForwardSlashPath(
+    nodePath.join(modulesPath, ".cache"),
+  );
 
   const registry = new Registry();
   const contextRegistry = new ContextRegistry();
@@ -175,9 +176,9 @@ export async function counterfact(config: Config) {
 
   const nativeTs = await runtimeCanExecuteErasableTs();
 
-  const compiledPathsDirectory = nodePath
-    .join(modulesPath, nativeTs ? "routes" : ".cache")
-    .replaceAll("\\", "/");
+  const compiledPathsDirectory = toForwardSlashPath(
+    nodePath.join(modulesPath, nativeTs ? "routes" : ".cache"),
+  );
 
   if (!nativeTs) {
     await rm(compiledPathsDirectory, { force: true, recursive: true });
@@ -208,7 +209,7 @@ export async function counterfact(config: Config) {
   );
 
   const transpiler = new Transpiler(
-    nodePath.join(modulesPath, "routes").replaceAll("\\", "/"),
+    toForwardSlashPath(nodePath.join(modulesPath, "routes")),
     compiledPathsDirectory,
     "commonjs",
   );
@@ -217,7 +218,7 @@ export async function counterfact(config: Config) {
     compiledPathsDirectory,
     registry,
     contextRegistry,
-    nodePath.join(modulesPath, "scenarios").replaceAll("\\", "/"),
+    toForwardSlashPath(nodePath.join(modulesPath, "scenarios")),
     scenarioRegistry,
   );
 

src/migrate/update-route-types.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 
 import createDebug from "debug";
 
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import {
   OperationTypeCoder,
   type SecurityScheme,
@@ -271,9 +272,7 @@ async function processRouteDirectory(
         );
       } else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
         // Process TypeScript route files (skip context files)
-        const routePath = relativePath
-          .replace(/\.ts$/, "")
-          .replaceAll("\\", "/");
+        const routePath = toForwardSlashPath(relativePath.replace(/\.ts$/, ""));
         const methodMap = mapping.get(routePath);
 
         if (methodMap) {

src/server/file-discovery.ts

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
 
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { escapePathForWindows } from "../util/windows-escape.js";
 
 const JS_EXTENSIONS = new Set(["cjs", "cts", "js", "mjs", "mts", "ts"]);
@@ -17,7 +18,7 @@ export class FileDiscovery {
   private readonly basePath: string;
 
   public constructor(basePath: string) {
-    this.basePath = basePath.replaceAll("\\", "/");
+    this.basePath = toForwardSlashPath(basePath);
   }
 
   /**
@@ -29,9 +30,7 @@ export class FileDiscovery {
    * @throws When `basePath/directory` does not exist.
    */
   public async findFiles(directory = ""): Promise<string[]> {
-    const fullDir = nodePath
-      .join(this.basePath, directory)
-      .replaceAll("\\", "/");
+    const fullDir = toForwardSlashPath(nodePath.join(this.basePath, directory));
 
     if (!existsSync(fullDir)) {
       throw new Error(`Directory does not exist ${fullDir}`);
@@ -43,7 +42,7 @@ export class FileDiscovery {
       entries.map(async (entry) => {
         if (entry.isDirectory()) {
           return this.findFiles(
-            nodePath.join(directory, entry.name).replaceAll("\\", "/"),
+            toForwardSlashPath(nodePath.join(directory, entry.name)),
           );
         }
 
@@ -53,9 +52,9 @@ export class FileDiscovery {
           return [];
         }
 
-        const fullPath = nodePath
-          .join(this.basePath, directory, entry.name)
-          .replaceAll("\\", "/");
+        const fullPath = toForwardSlashPath(
+          nodePath.join(this.basePath, directory, entry.name),
+        );
 
         return [escapePathForWindows(fullPath)];
       }),

src/server/module-loader.ts

@@ -18,6 +18,7 @@ import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import type { Module, Registry } from "./registry.js";
 import { ScenarioRegistry } from "./scenario-registry.js";
 import { uncachedImport } from "./uncached-import.js";
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { unescapePathForWindows } from "../util/windows-escape.js";
 
 const { uncachedRequire } = await import("./uncached-require.cjs");
@@ -69,10 +70,13 @@ export class ModuleLoader extends EventTarget {
     scenarioRegistry?: ScenarioRegistry,
   ) {
     super();
-    this.basePath = basePath.replaceAll("\\", "/");
+    this.basePath = toForwardSlashPath(basePath);
     this.registry = registry;
     this.contextRegistry = contextRegistry;
-    this.scenariosPath = scenariosPath?.replaceAll("\\", "/");
+    this.scenariosPath =
+      scenariosPath === undefined
+        ? undefined
+        : toForwardSlashPath(scenariosPath);
     this.scenarioRegistry = scenarioRegistry;
     this.fileDiscovery = new FileDiscovery(this.basePath);
   }
@@ -98,7 +102,7 @@ export class ModuleLoader extends EventTarget {
         )
           return;
 
-        const pathName = pathNameOriginal.replaceAll("\\", "/");
+        const pathName = toForwardSlashPath(pathNameOriginal);
 
         if (pathName.includes("$.context") && eventName === "add") {
           process.stdout.write(
@@ -114,17 +118,18 @@ export class ModuleLoader extends EventTarget {
 
         const parts = nodePath.parse(pathName.replace(this.basePath, ""));
         const url = unescapePathForWindows(
-          `/${parts.dir}/${parts.name}`
-            .replaceAll("\\", "/")
-            .replaceAll(/\/+/gu, "/"),
+          toForwardSlashPath(`/${parts.dir}/${parts.name}`).replaceAll(
+            /\/+/gu,
+            "/",
+          ),
         );
 
         if (eventName === "unlink") {
           this.registry.remove(url);
           this.dispatchEvent(new Event("remove"));
           if (this.isContextFile(pathName)) {
             this.contextRegistry.remove(
-              unescapePathForWindows(parts.dir).replaceAll("\\", "/") || "/",
+              unescapePathForWindows(toForwardSlashPath(parts.dir)) || "/",
             );
           }
           return;
@@ -155,7 +160,7 @@ export class ModuleLoader extends EventTarget {
 
           if (!["add", "change", "unlink"].includes(eventName)) return;
 
-          const pathName = pathNameOriginal.replaceAll("\\", "/");
+          const pathName = toForwardSlashPath(pathNameOriginal);
 
           if (eventName === "unlink") {
             const fileKey = this.scenarioFileKey(pathName);
@@ -215,18 +220,18 @@ export class ModuleLoader extends EventTarget {
   }
 
   private scenarioFileKey(pathName: string): string {
-    const normalizedScenariosPath = (this.scenariosPath ?? "").replaceAll(
-      "\\",
-      "/",
+    const normalizedScenariosPath = toForwardSlashPath(
+      this.scenariosPath ?? "",
+    );
+    const directory = toForwardSlashPath(
+      dirname(pathName.slice(normalizedScenariosPath.length)),
     );
-    const directory = dirname(
-      pathName.slice(normalizedScenariosPath.length),
-    ).replaceAll("\\", "/");
     const name = nodePath.parse(basename(pathName)).name;
     const url = unescapePathForWindows(
-      `/${nodePath.join(directory, name)}`
-        .replaceAll("\\", "/")
-        .replaceAll(/\/+/gu, "/"),
+      toForwardSlashPath(`/${nodePath.join(directory, name)}`).replaceAll(
+        /\/+/gu,
+        "/",
+      ),
     );
 
     return url.slice(1); // strip leading "/"
@@ -258,15 +263,14 @@ export class ModuleLoader extends EventTarget {
   private async loadEndpoint(pathName: string) {
     debug("importing module: %s", pathName);
 
-    const directory = dirname(pathName.slice(this.basePath.length)).replaceAll(
-      "\\",
-      "/",
+    const directory = toForwardSlashPath(
+      dirname(pathName.slice(this.basePath.length)),
     );
 
     const url = unescapePathForWindows(
-      `/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`
-        .replaceAll("\\", "/")
-        .replaceAll(/\/+/gu, "/"),
+      toForwardSlashPath(
+        `/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`,
+      ).replaceAll(/\/+/gu, "/"),
     );
 
     debug(`loading pathName from dependencyGraph: ${pathName}`);
@@ -290,9 +294,9 @@ export class ModuleLoader extends EventTarget {
           importError instanceof SyntaxError ||
           String(importError).startsWith("SyntaxError:");
 
-        const displayPath = nodePath
-          .relative(process.cwd(), unescapePathForWindows(pathName))
-          .replaceAll("\\", "/");
+        const displayPath = toForwardSlashPath(
+          nodePath.relative(process.cwd(), unescapePathForWindows(pathName)),
+        );
 
         const message = isSyntaxError
           ? `There is a syntax error in the route file: ${displayPath}`

src/server/transpiler.ts

@@ -9,6 +9,7 @@ import createDebug from "debug";
 import ts from "typescript";
 
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
 import { convertFileExtensionsToCjs } from "./convert-js-extensions-to-cjs.js";
 
@@ -79,12 +80,13 @@ export class Transpiler extends EventTarget {
         )
           return;
 
-        const sourcePath = sourcePathOriginal.replaceAll("\\", "/");
+        const sourcePath = toForwardSlashPath(sourcePathOriginal);
 
-        const destinationPath = sourcePath
-          .replace(this.sourcePath, this.destinationPath)
-          .replaceAll("\\", "/")
-          .replace(".ts", this.extension);
+        const destinationPath = toForwardSlashPath(
+          sourcePath
+            .replace(this.sourcePath, this.destinationPath)
+            .replace(".ts", this.extension),
+        );
 
         if (["add", "change"].includes(eventName)) {
           transpiles.push(
@@ -152,13 +154,13 @@ export class Transpiler extends EventTarget {
 
     const result: string = transpileOutput.outputText;
 
-    const fullDestination = nodePath
-      .join(
+    const fullDestination = toForwardSlashPath(
+      nodePath.join(
         sourcePath
           .replace(this.sourcePath, this.destinationPath)
           .replace(".ts", this.extension),
-      )
-      .replaceAll("\\", "/");
+      ),
+    );
 
     const resultWithTransformedFileExtensions =
       convertFileExtensionsToCjs(result);

src/typescript-generator/generate.ts

@@ -5,6 +5,7 @@ import nodePath from "node:path";
 import createDebug from "debug";
 
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { OperationCoder } from "./operation-coder.js";
 import { type SecurityScheme } from "./operation-type-coder.js";
 import { pruneRoutes } from "./prune.js";
@@ -210,9 +211,9 @@ async function walkForContextFiles(
         results,
       );
     } else if (entry.name === "_.context.ts") {
-      const relDir = nodePath
-        .relative(routesDir, currentDir)
-        .replaceAll("\\", "/");
+      const relDir = toForwardSlashPath(
+        nodePath.relative(routesDir, currentDir),
+      );
       const routePath = relDir === "" ? "/" : `/${relDir}`;
       const depth = relDir === "" ? 0 : relDir.split("/").length;
       const importPath =

src/typescript-generator/operation-coder.ts

@@ -1,5 +1,6 @@
 import nodePath from "node:path";
 
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
 import {
   OperationTypeCoder,
@@ -88,8 +89,6 @@ export class OperationCoder extends Coder {
       .at(-2)!
       .replaceAll("~1", "/");
 
-    return `${nodePath
-      .join("routes", pathString)
-      .replaceAll("\\", "/")}.types.ts`;
+    return `${toForwardSlashPath(nodePath.join("routes", pathString))}.types.ts`;
   }
 }

src/typescript-generator/operation-type-coder.ts

@@ -1,5 +1,6 @@
 import nodePath from "node:path";
 
+import { toForwardSlashPath } from "../util/forward-slash-path.js";
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
 import { buildJsDoc } from "./jsdoc.js";
 import { ParameterExportTypeCoder } from "./parameter-export-type-coder.js";
@@ -187,9 +188,9 @@ export class OperationTypeCoder extends TypeCoder {
       .at(-2)!
       .replaceAll("~1", "/");
 
-    return `${nodePath
-      .join("types/paths", pathString === "/" ? "/index" : pathString)
-      .replaceAll("\\", "/")}.types.ts`;
+    return `${toForwardSlashPath(
+      nodePath.join("types/paths", pathString === "/" ? "/index" : pathString),
+    )}.types.ts`;
   }
 
   /**