@mui/internal-docs-infra 0.2.3-canary.9 → 0.3.1-canary.1

package/esm/pipeline/loadServerSitemap/loadServerSitemap.js

@@ -0,0 +1,170 @@
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLoadServerPageIndex } from "../loadServerPageIndex/loadServerPageIndex.js";
+import { parseCreateFactoryCall } from "../loadPrecomputedCodeHighlighter/parseCreateFactoryCall.js";
+
+/**
+ * Options for creating a loadServerSitemap function
+ */
+
+/**
+ * Function type for loading sitemap data from a sitemap index file URL
+ */
+
+/**
+ * Creates the default Orama schema for search indexing.
+ * See: https://docs.orama.com/docs/orama-js/usage/create#schema-properties-and-types
+ */
+export function createSitemapSchema() {
+  return {
+    slug: 'string',
+    path: 'string',
+    title: 'string',
+    description: 'string',
+    sections: 'string[]',
+    subsections: 'string[]',
+    keywords: 'string[]'
+  };
+}
+
+/**
+ * Default loadServerSitemap function that loads sitemap data from a sitemap index file.
+ * This function parses the sitemap index file to find createSitemap calls and resolves
+ * the page index paths from the imports.
+ */
+export var loadServerSitemap = createLoadServerSitemap();
+
+/**
+ * Creates a loadServerSitemap function with custom options.
+ *
+ * This factory function creates a LoadServerSitemap implementation that:
+ * 1. Parses the sitemap index file to find createSitemap calls with page imports
+ * 2. Resolves all page index paths from the imports
+ * 3. Loads each page index using loadServerPageIndex
+ * 4. Returns a Sitemap object with schema and page data
+ *
+ * @param options - Configuration options for the loader
+ * @returns LoadServerSitemap function that takes a file URL and returns Promise<Sitemap>
+ */
+export function createLoadServerSitemap() {
+  var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return /*#__PURE__*/function () {
+    var _loadSitemap = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(url) {
+      var _options$rootContext;
+      var filePath, rootContext, loadPageIndex, source, sitemapCall, entries, results, sitemapData, errors, _iterator, _step, result, errorMessages;
+      return _regenerator().w(function (_context2) {
+        while (1) switch (_context2.n) {
+          case 0:
+            // Convert file:// URL to proper file system path for reading the file
+            // Using fileURLToPath handles Windows drive letters correctly (e.g., file:///C:/... → C:\...)
+            filePath = url.startsWith('file://') ? fileURLToPath(url) : url; // Determine root context from file path if not provided
+            rootContext = (_options$rootContext = options.rootContext) != null ? _options$rootContext : path.dirname(filePath); // Create page index loader with root context
+            loadPageIndex = createLoadServerPageIndex({
+              rootContext: rootContext
+            }); // Read the source file to find createSitemap calls
+            _context2.n = 1;
+            return readFile(filePath, 'utf-8');
+          case 1:
+            source = _context2.v;
+            _context2.n = 2;
+            return parseCreateFactoryCall(source, filePath);
+          case 2:
+            sitemapCall = _context2.v;
+            if (!(!sitemapCall || !sitemapCall.variants)) {
+              _context2.n = 3;
+              break;
+            }
+            return _context2.a(2, {
+              schema: createSitemapSchema(),
+              data: {}
+            });
+          case 3:
+            // Process all page index files in parallel
+            entries = Object.entries(sitemapCall.variants);
+            _context2.n = 4;
+            return Promise.all(entries.map(/*#__PURE__*/function () {
+              var _ref2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(_ref) {
+                var _ref3, key, importPath, metadata, _t;
+                return _regenerator().w(function (_context) {
+                  while (1) switch (_context.p = _context.n) {
+                    case 0:
+                      _ref3 = _slicedToArray(_ref, 2), key = _ref3[0], importPath = _ref3[1];
+                      _context.p = 1;
+                      _context.n = 2;
+                      return loadPageIndex(importPath);
+                    case 2:
+                      metadata = _context.v;
+                      return _context.a(2, {
+                        key: key,
+                        metadata: metadata,
+                        error: null
+                      });
+                    case 3:
+                      _context.p = 3;
+                      _t = _context.v;
+                      return _context.a(2, {
+                        key: key,
+                        metadata: null,
+                        error: _t instanceof Error ? _t : new Error(String(_t))
+                      });
+                  }
+                }, _callee, null, [[1, 3]]);
+              }));
+              return function (_x2) {
+                return _ref2.apply(this, arguments);
+              };
+            }()));
+          case 4:
+            results = _context2.v;
+            // Collect results and errors
+            sitemapData = {};
+            errors = [];
+            _iterator = _createForOfIteratorHelper(results);
+            try {
+              for (_iterator.s(); !(_step = _iterator.n()).done;) {
+                result = _step.value;
+                if (result.error) {
+                  errors.push({
+                    key: result.key,
+                    error: result.error
+                  });
+                } else if (result.metadata) {
+                  sitemapData[result.key] = result.metadata;
+                }
+              }
+
+              // Throw if any pages failed to load
+            } catch (err) {
+              _iterator.e(err);
+            } finally {
+              _iterator.f();
+            }
+            if (!(errors.length > 0)) {
+              _context2.n = 5;
+              break;
+            }
+            errorMessages = errors.map(function (_ref4) {
+              var key = _ref4.key,
+                error = _ref4.error;
+              return "  ".concat(key, ": ").concat(error.message);
+            }).join('\n');
+            throw new Error("Failed to load ".concat(errors.length, " page index(es):\n").concat(errorMessages));
+          case 5:
+            return _context2.a(2, {
+              schema: createSitemapSchema(),
+              data: sitemapData
+            });
+        }
+      }, _callee2);
+    }));
+    function loadSitemap(_x) {
+      return _loadSitemap.apply(this, arguments);
+    }
+    return loadSitemap;
+  }();
+}

package/esm/pipeline/loadServerSource/loadServerSource.js

@@ -5,8 +5,10 @@ import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 // webpack does not like node: imports
 // eslint-disable-next-line n/prefer-node-protocol
 import { readFile } from 'fs/promises';
+// eslint-disable-next-line n/prefer-node-protocol
+import { fileURLToPath } from 'url';
 import { parseImportsAndComments } from "../loaderUtils/index.js";
-import { resolveImportResultWithFs } from "../loaderUtils/resolveModulePathWithFs.js";
+import { resolveImportResultWithFs } from "../loadServerCodeMeta/resolveModulePathWithFs.js";
 import { processRelativeImports } from "../loaderUtils/processRelativeImports.js";
 import { isJavaScriptModule } from "../loaderUtils/resolveModulePath.js";
 /**
@@ -33,12 +35,13 @@ export function createLoadServerSource() {
     storeAt = _options$storeAt === void 0 ? 'flat' : _options$storeAt;
   return /*#__PURE__*/function () {
     var _loadSource = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(url) {
-      var filePath, source, isJavascriptModuleFile, isCssFile, _yield$parseImportsAn, importResult, externals, transformedExternals, _i, _Object$entries, _Object$entries$_i, modulePath, externalImport, processedSource, extraFiles, extraDependencies, importsCompatible, _i2, _Object$entries2, _Object$entries2$_i, importPath, _Object$entries2$_i$, path, names, positions, result, relativeImportsCompatible, _i3, _Object$entries3, _Object$entries3$_i, _importPath, _Object$entries3$_i$, _path, _names, includeTypeDefs, _positions, resolvedPathsMap, _result;
+      var filePath, source, isJavascriptModuleFile, isCssFile, _yield$parseImportsAn, importResult, externals, transformedExternals, _i, _Object$entries, _Object$entries$_i, modulePath, externalImport, processedSource, extraFiles, extraDependencies, importsCompatible, _i2, _Object$entries2, _Object$entries2$_i, importPath, _Object$entries2$_i$, importUrl, names, positions, result, relativeImportsCompatible, _i3, _Object$entries3, _Object$entries3$_i, _importPath, _Object$entries3$_i$, _importUrl, _names, includeTypeDefs, _positions, resolvedPathsMap, _result;
       return _regenerator().w(function (_context) {
         while (1) switch (_context.n) {
           case 0:
-            // Remove file:// prefix if present
-            filePath = url.replace('file://', ''); // Read the file
+            // Convert file:// URL to proper file system path for reading the file
+            // Using fileURLToPath handles Windows drive letters correctly (e.g., file:///C:/... → C:\...)
+            filePath = url.startsWith('file://') ? fileURLToPath(url) : url; // Read the file
             _context.n = 1;
             return readFile(filePath, 'utf8');
           case 1:
@@ -63,7 +66,7 @@ export function createLoadServerSource() {
             });
           case 3:
             _context.n = 4;
-            return parseImportsAndComments(source, filePath);
+            return parseImportsAndComments(source, url);
           case 4:
             _yield$parseImportsAn = _context.v;
             importResult = _yield$parseImportsAn.relative;
@@ -92,9 +95,9 @@ export function createLoadServerSource() {
             // Convert import result to the format expected by processImports, preserving position data
             importsCompatible = {};
             for (_i2 = 0, _Object$entries2 = Object.entries(importResult); _i2 < _Object$entries2.length; _i2++) {
-              _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2), importPath = _Object$entries2$_i[0], _Object$entries2$_i$ = _Object$entries2$_i[1], path = _Object$entries2$_i$.path, names = _Object$entries2$_i$.names, positions = _Object$entries2$_i$.positions;
+              _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2), importPath = _Object$entries2$_i[0], _Object$entries2$_i$ = _Object$entries2$_i[1], importUrl = _Object$entries2$_i$.url, names = _Object$entries2$_i$.names, positions = _Object$entries2$_i$.positions;
               importsCompatible[importPath] = {
-                path: path,
+                url: importUrl,
                 names: names.map(function (_ref) {
                   var name = _ref.name,
                     alias = _ref.alias;
@@ -115,8 +118,8 @@ export function createLoadServerSource() {
 
             // Build dependencies list for recursive loading (CSS files use direct paths)
             extraDependencies = Object.values(importResult).map(function (_ref2) {
-              var path = _ref2.path;
-              return path;
+              var importUrl = _ref2.url;
+              return importUrl;
             });
             _context.n = 8;
             break;
@@ -124,9 +127,9 @@ export function createLoadServerSource() {
             // For JavaScript/TypeScript files, resolve paths first
             relativeImportsCompatible = {};
             for (_i3 = 0, _Object$entries3 = Object.entries(importResult); _i3 < _Object$entries3.length; _i3++) {
-              _Object$entries3$_i = _slicedToArray(_Object$entries3[_i3], 2), _importPath = _Object$entries3$_i[0], _Object$entries3$_i$ = _Object$entries3$_i[1], _path = _Object$entries3$_i$.path, _names = _Object$entries3$_i$.names, includeTypeDefs = _Object$entries3$_i$.includeTypeDefs, _positions = _Object$entries3$_i$.positions;
+              _Object$entries3$_i = _slicedToArray(_Object$entries3[_i3], 2), _importPath = _Object$entries3$_i[0], _Object$entries3$_i$ = _Object$entries3$_i[1], _importUrl = _Object$entries3$_i$.url, _names = _Object$entries3$_i$.names, includeTypeDefs = _Object$entries3$_i$.includeTypeDefs, _positions = _Object$entries3$_i$.positions;
               relativeImportsCompatible[_importPath] = _extends({
-                path: _path,
+                url: _importUrl,
                 names: _names.map(function (_ref3) {
                   var name = _ref3.name,
                     alias = _ref3.alias;
@@ -151,10 +154,10 @@ export function createLoadServerSource() {
 
             // Build dependencies list for recursive loading
             extraDependencies = Object.values(importResult).map(function (_ref4) {
-              var path = _ref4.path;
-              return resolvedPathsMap.get(path);
-            }).filter(function (path) {
-              return path !== undefined;
+              var importUrl = _ref4.url;
+              return resolvedPathsMap.get(importUrl);
+            }).filter(function (resolved) {
+              return resolved !== undefined;
             });
           case 8:
             return _context.a(2, {

package/esm/pipeline/loaderUtils/externalsToPackages.js

@@ -21,7 +21,7 @@ export function externalsToPackages(externals) {
  * - 'react' -> 'react'
  * - 'react-dom' -> 'react-dom'
  * - '@mui/internal-docs-infra/CodeHighlighter' -> '@mui/internal-docs-infra'
- * - '@mui/internal-docs-infra/parseSource' -> '@mui/internal-docs-infra'
+ * - '@mui/internal-docs-infra/pipeline/parseSource' -> '@mui/internal-docs-infra'
  * - 'lodash/get' -> 'lodash'
  * - 'some-package/submodule/deep' -> 'some-package'
  */

package/esm/pipeline/loaderUtils/extractNameAndSlugFromUrl.d.ts

@@ -1,12 +1,3 @@
-/**
- * Extracts and formats a name and slug from a URL path.
- * This utility takes the last meaningful segment of a URL path and formats it
- * into both a human-readable title and a URL-friendly slug.
- *
- * - Strips common file extensions (index.js, index.ts, index.tsx, etc.)
- * - Converts kebab-case to Title Case for names
- * - Ensures slugs are in kebab-case format
- */
 /**
  * Extracts and formats a name and slug from a URL path
  * @param url - The URL to extract from (can be file:// URL or regular path)

package/esm/pipeline/loaderUtils/extractNameAndSlugFromUrl.js

@@ -1,3 +1,5 @@
+import { fileUrlToPortablePath } from "./fileUrlToPortablePath.js";
+
 /**
  * Extracts and formats a name and slug from a URL path.
  * This utility takes the last meaningful segment of a URL path and formats it
@@ -82,17 +84,15 @@ function toKebabCase(str) {
  * @returns The last meaningful path segment
  */
 function extractLastSegment(url) {
-  // Handle file: URLs by removing the protocol
-  var path = url;
-  if (url.startsWith('file:')) {
-    path = url.replace(/^file:\/\//, '');
-  }
+  // Convert to portable path format for consistent handling across platforms
+  // This handles file:// URLs, Windows paths with backslashes, and regular paths
+  var path = fileUrlToPortablePath(url);
 
   // Strip query parameters and hash fragments before processing
-  path = path.split('?')[0].split('#')[0];
+  var cleanPath = path.split('?')[0].split('#')[0];
 
   // Split the path into segments and filter out empty ones
-  var segments = path.split('/').filter(Boolean);
+  var segments = cleanPath.split('/').filter(Boolean);
   if (segments.length === 0) {
     throw new Error('Could not extract meaningful segment from URL');
   }

package/esm/pipeline/loaderUtils/fileUrlToPortablePath.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts a file:// URL to a portable path format that can be used with path-module (POSIX-only).
+ *
+ * This function is designed to work with isomorphic code that uses path-module,
+ * which only supports POSIX paths. The key insight is that by stripping the `file://`
+ * prefix and normalizing backslashes to forward slashes, we get a path that:
+ * - On Unix: `/home/user/file.ts` - works directly with path-module
+ * - On Windows: `/C:/Users/file.ts` - also works with path-module because it starts with `/`
+ *
+ * The resulting path is NOT a valid filesystem path on Windows, but it's a valid
+ * POSIX-style path for path manipulation. Use `fileURLToPath` from the `url` module
+ * when you need to access the actual filesystem.
+ *
+ * @param fileUrl - A file:// URL or absolute path (with forward slashes)
+ * @returns A portable path starting with `/` that works with path-module
+ *
+ * @example
+ * // Unix file URL
+ * fileUrlToPortablePath('file:///home/user/file.ts') // => '/home/user/file.ts'
+ *
+ * // Windows file URL
+ * fileUrlToPortablePath('file:///C:/Users/file.ts') // => '/C:/Users/file.ts'
+ *
+ * // Already a portable path (passthrough)
+ * fileUrlToPortablePath('/home/user/file.ts') // => '/home/user/file.ts'
+ */
+export declare function fileUrlToPortablePath(fileUrl: string): string;
+/**
+ * Converts a portable path back to a file:// URL.
+ *
+ * This is the inverse of `fileUrlToPortablePath`. It takes a portable path
+ * (which always starts with `/`) and converts it back to a proper file:// URL.
+ *
+ * @param portablePath - A portable path starting with `/`
+ * @returns A file:// URL
+ *
+ * @example
+ * // Unix path
+ * portablePathToFileUrl('/home/user/file.ts') // => 'file:///home/user/file.ts'
+ *
+ * // Windows path (portable format)
+ * portablePathToFileUrl('/C:/Users/file.ts') // => 'file:///C:/Users/file.ts'
+ */
+export declare function portablePathToFileUrl(portablePath: string): string;

package/esm/pipeline/loaderUtils/fileUrlToPortablePath.js

@@ -0,0 +1,80 @@
+/**
+ * Converts a file:// URL to a portable path format that can be used with path-module (POSIX-only).
+ *
+ * This function is designed to work with isomorphic code that uses path-module,
+ * which only supports POSIX paths. The key insight is that by stripping the `file://`
+ * prefix and normalizing backslashes to forward slashes, we get a path that:
+ * - On Unix: `/home/user/file.ts` - works directly with path-module
+ * - On Windows: `/C:/Users/file.ts` - also works with path-module because it starts with `/`
+ *
+ * The resulting path is NOT a valid filesystem path on Windows, but it's a valid
+ * POSIX-style path for path manipulation. Use `fileURLToPath` from the `url` module
+ * when you need to access the actual filesystem.
+ *
+ * @param fileUrl - A file:// URL or absolute path (with forward slashes)
+ * @returns A portable path starting with `/` that works with path-module
+ *
+ * @example
+ * // Unix file URL
+ * fileUrlToPortablePath('file:///home/user/file.ts') // => '/home/user/file.ts'
+ *
+ * // Windows file URL
+ * fileUrlToPortablePath('file:///C:/Users/file.ts') // => '/C:/Users/file.ts'
+ *
+ * // Already a portable path (passthrough)
+ * fileUrlToPortablePath('/home/user/file.ts') // => '/home/user/file.ts'
+ */
+export function fileUrlToPortablePath(fileUrl) {
+  // If it's not a file:// URL, check if it's already a portable path
+  if (!fileUrl.startsWith('file://')) {
+    // Normalize backslashes to forward slashes
+    var normalized = fileUrl.replace(/\\/g, '/');
+    // If it doesn't start with /, it's likely a Windows path - add leading slash
+    if (!normalized.startsWith('/') && /^[a-zA-Z]:\//.test(normalized)) {
+      return "/".concat(normalized);
+    }
+    return normalized;
+  }
+
+  // Strip the file:// prefix
+  // file:///home/user/file.ts => /home/user/file.ts (Unix)
+  // file:///C:/Users/file.ts => /C:/Users/file.ts (Windows - keep the leading slash)
+  var path = fileUrl.slice(7); // Remove 'file://'
+
+  // Normalize any backslashes that might have snuck in
+  path = path.replace(/\\/g, '/');
+
+  // If it doesn't start with /, add one (should already have one for valid file:// URLs)
+  if (!path.startsWith('/')) {
+    path = "/".concat(path);
+  }
+  return path;
+}
+
+/**
+ * Converts a portable path back to a file:// URL.
+ *
+ * This is the inverse of `fileUrlToPortablePath`. It takes a portable path
+ * (which always starts with `/`) and converts it back to a proper file:// URL.
+ *
+ * @param portablePath - A portable path starting with `/`
+ * @returns A file:// URL
+ *
+ * @example
+ * // Unix path
+ * portablePathToFileUrl('/home/user/file.ts') // => 'file:///home/user/file.ts'
+ *
+ * // Windows path (portable format)
+ * portablePathToFileUrl('/C:/Users/file.ts') // => 'file:///C:/Users/file.ts'
+ */
+export function portablePathToFileUrl(portablePath) {
+  // If it's already a URL (file://, http://, https://), return as-is
+  if (portablePath.startsWith('file://') || portablePath.startsWith('http://') || portablePath.startsWith('https://')) {
+    return portablePath;
+  }
+
+  // For Windows portable paths like /C:/Users/..., we need file:// + path
+  // For Unix paths like /home/user/..., we need file:// + path
+  // Both cases: file:// + /path = file:///path
+  return "file://".concat(portablePath);
+}

package/esm/pipeline/loaderUtils/index.d.ts

@@ -4,4 +4,5 @@ export * from "./rewriteImports.js";
 export * from "./processRelativeImports.js";
 export * from "./getFileNameFromUrl.js";
 export * from "./extractNameAndSlugFromUrl.js";
-export * from "./externalsToPackages.js";
+export * from "./externalsToPackages.js";
+export * from "./fileUrlToPortablePath.js";

package/esm/pipeline/loaderUtils/index.js

@@ -4,4 +4,5 @@ export * from "./rewriteImports.js";
 export * from "./processRelativeImports.js";
 export * from "./getFileNameFromUrl.js";
 export * from "./extractNameAndSlugFromUrl.js";
-export * from "./externalsToPackages.js";
+export * from "./externalsToPackages.js";
+export * from "./fileUrlToPortablePath.js";

package/esm/pipeline/loaderUtils/parseImportsAndComments.d.ts

@@ -24,8 +24,8 @@ export interface ImportPathPosition {
  * Represents an import from a relative path (starts with ./ or ../).
  */
 export interface RelativeImport {
-  /** The resolved absolute path to the imported file */
-  path: string;
+  /** The resolved absolute URL to the imported file (file:// URL) */
+  url: string;
   /** Array of imported names from this module */
   names: ImportName[];
   /** Whether TypeScript type definitions should be included for this import */
@@ -68,8 +68,12 @@ export interface ImportsAndComments {
  * and template literals, it's most efficient to handle comment processing in this
  * same pass rather than requiring separate parsing steps.
  *
+ * The function accepts file:// URLs or file paths and converts them internally to a
+ * portable path format that works cross-platform. Resolved import paths are returned
+ * in the same portable format (forward slashes, starting with /).
+ *
  * @param code - The source code to parse
- * @param filePath - The file path, used to determine file type and resolve relative imports
+ * @param fileUrl - The file URL (file:// protocol) or path, used to determine file type and resolve relative imports
  * @param options - Optional configuration for comment processing
  * @param options.removeCommentsWithPrefix - Array of prefixes; comments starting with these will be stripped from output
  * @param options.notableCommentsPrefix - Array of prefixes; comments starting with these will be collected regardless of stripping
@@ -79,13 +83,13 @@ export interface ImportsAndComments {
  * ```typescript
  * const result = await parseImportsAndComments(
  *   'import React from "react";\nimport { Button } from "./Button";',
- *   '/src/App.tsx'
+ *   'file:///src/App.tsx'
  * );
  * // result.externals['react'] contains the React import
- * // result.relative['./Button'] contains the Button import
+ * // result.relative['./Button'] contains the Button import with url: 'file:///src/Button'
  * ```
  */
-export declare function parseImportsAndComments(code: string, filePath: string, options?: {
+export declare function parseImportsAndComments(code: string, fileUrl: string, options?: {
   removeCommentsWithPrefix?: string[];
   notableCommentsPrefix?: string[];
 }): Promise<ImportsAndComments>;

package/esm/pipeline/loaderUtils/parseImportsAndComments.js

@@ -3,9 +3,8 @@ import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
 import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import _extends from "@babel/runtime/helpers/esm/extends";
 import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
-// webpack does not like node: imports
-// eslint-disable-next-line n/prefer-node-protocol
-import path from 'path';
+import * as path from 'path-module';
+import { fileUrlToPortablePath, portablePathToFileUrl } from "./fileUrlToPortablePath.js";
 
 /**
  * Represents a single import name with its properties.
@@ -845,7 +844,7 @@ function detectCssImport(sourceText, pos, cssResult, cssExternals, cssFilePath,
         var resolvedPath = path.resolve(path.dirname(cssFilePath), normalizedPath);
         if (!cssResult[importResult.modulePath]) {
           cssResult[importResult.modulePath] = {
-            path: resolvedPath,
+            url: portablePathToFileUrl(resolvedPath),
             names: [],
             positions: []
           };
@@ -954,7 +953,7 @@ function parseJSImports(code, filePath, result, externals, isMdxFile, removeComm
               var resolvedPath = path.resolve(path.dirname(filePath), _modulePath);
               if (!result[_modulePath]) {
                 result[_modulePath] = {
-                  path: resolvedPath,
+                  url: portablePathToFileUrl(resolvedPath),
                   names: [],
                   positions: []
                 };
@@ -1083,7 +1082,7 @@ function parseJSImports(code, filePath, result, externals, isMdxFile, removeComm
           var _resolvedPath = path.resolve(path.dirname(filePath), modulePath);
           if (!result[modulePath]) {
             result[modulePath] = _extends({
-              path: _resolvedPath,
+              url: portablePathToFileUrl(_resolvedPath),
               names: [],
               positions: []
             }, isTypeImport && {
@@ -1285,8 +1284,12 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
  * and template literals, it's most efficient to handle comment processing in this
  * same pass rather than requiring separate parsing steps.
  *
+ * The function accepts file:// URLs or file paths and converts them internally to a
+ * portable path format that works cross-platform. Resolved import paths are returned
+ * in the same portable format (forward slashes, starting with /).
+ *
  * @param code - The source code to parse
- * @param filePath - The file path, used to determine file type and resolve relative imports
+ * @param fileUrl - The file URL (file:// protocol) or path, used to determine file type and resolve relative imports
  * @param options - Optional configuration for comment processing
  * @param options.removeCommentsWithPrefix - Array of prefixes; comments starting with these will be stripped from output
  * @param options.notableCommentsPrefix - Array of prefixes; comments starting with these will be collected regardless of stripping
@@ -1296,23 +1299,25 @@ function detectJavaScriptImport(sourceText, pos, _positionMapper) {
  * ```typescript
  * const result = await parseImportsAndComments(
  *   'import React from "react";\nimport { Button } from "./Button";',
- *   '/src/App.tsx'
+ *   'file:///src/App.tsx'
  * );
  * // result.externals['react'] contains the React import
- * // result.relative['./Button'] contains the Button import
+ * // result.relative['./Button'] contains the Button import with url: 'file:///src/Button'
  * ```
  */
 export function parseImportsAndComments(_x, _x2, _x3) {
   return _parseImportsAndComments.apply(this, arguments);
 }
 function _parseImportsAndComments() {
-  _parseImportsAndComments = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(code, filePath, options) {
-    var result, externals, isCssFile, isMdxFile;
+  _parseImportsAndComments = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(code, fileUrl, options) {
+    var result, externals, filePath, isCssFile, isMdxFile;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.n) {
         case 0:
           result = {};
-          externals = {}; // Check if this is a CSS file
+          externals = {}; // Convert file:// URL or OS path to portable path format for cross-platform compatibility
+          // Portable paths always use forward slashes and start with / (even on Windows: /C:/...)
+          filePath = fileUrlToPortablePath(fileUrl); // Check if this is a CSS file
           isCssFile = filePath.toLowerCase().endsWith('.css'); // Check if this is an MDX file (which can contain code blocks with triple backticks)
           isMdxFile = filePath.toLowerCase().endsWith('.mdx'); // If this is a CSS file, parse CSS @import statements instead
           if (!isCssFile) {

package/esm/pipeline/loaderUtils/processRelativeImports.d.ts

@@ -15,7 +15,7 @@ export interface ProcessImportsResult {
  * @returns Object with processed source and extraFiles mapping
  */
 export declare function processRelativeImports(source: string, importResult: Record<string, {
-  path: string;
+  url: string;
   names: string[];
   positions?: Array<{
     start: number;