@mui/internal-docs-infra 0.2.0-alpha.1 → 0.2.0

package/esm/pipeline/loadServerSource/loadServerSource.js

@@ -5,7 +5,7 @@ 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';
-import { parseImports } from "../loaderUtils/index.js";
+import { parseImportsAndComments } from "../loaderUtils/index.js";
 import { resolveImportResultWithFs } from "../loaderUtils/resolveModulePathWithFs.js";
 import { processRelativeImports } from "../loaderUtils/processRelativeImports.js";
 import { isJavaScriptModule } from "../loaderUtils/resolveModulePath.js";
@@ -33,7 +33,7 @@ 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, _yield$parseImports, importResult, externals, transformedExternals, _i, _Object$entries, _Object$entries$_i, modulePath, externalImport, relativeImportsCompatible, _i2, _Object$entries2, _Object$entries2$_i, importPath, _Object$entries2$_i$, path, names, includeTypeDefs, resolvedPathsMap, _processRelativeImpor, processedSource, extraFiles, extraDependencies;
+      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;
       return _regenerator().w(function (_context) {
         while (1) switch (_context.n) {
           case 0:
@@ -53,7 +53,8 @@ export function createLoadServerSource() {
           case 2:
             // Check if this is a static asset file (non-JS/TS modules)
             isJavascriptModuleFile = isJavaScriptModule(filePath);
-            if (isJavascriptModuleFile) {
+            isCssFile = filePath.toLowerCase().endsWith('.css');
+            if (!(!isJavascriptModuleFile && !isCssFile)) {
               _context.n = 3;
               break;
             }
@@ -62,12 +63,12 @@ export function createLoadServerSource() {
             });
           case 3:
             _context.n = 4;
-            return parseImports(source, filePath);
+            return parseImportsAndComments(source, filePath);
           case 4:
-            _yield$parseImports = _context.v;
-            importResult = _yield$parseImports.relative;
-            externals = _yield$parseImports.externals;
-            // Transform externals from parseImports format to simplified format
+            _yield$parseImportsAn = _context.v;
+            importResult = _yield$parseImportsAn.relative;
+            externals = _yield$parseImportsAn.externals;
+            // Transform externals from parseImportsAndComments format to simplified format
             transformedExternals = {};
             for (_i = 0, _Object$entries = Object.entries(externals); _i < _Object$entries.length; _i++) {
               _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2), modulePath = _Object$entries$_i[0], externalImport = _Object$entries$_i[1];
@@ -88,35 +89,74 @@ export function createLoadServerSource() {
               externals: Object.keys(transformedExternals).length > 0 ? transformedExternals : undefined
             });
           case 5:
-            // Convert to format expected by resolveImportResultWithFs and processImports
-            relativeImportsCompatible = {};
+            // 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, includeTypeDefs = _Object$entries2$_i$.includeTypeDefs;
-              relativeImportsCompatible[importPath] = _extends({
+              _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;
+              importsCompatible[importPath] = {
                 path: path,
                 names: names.map(function (_ref) {
                   var name = _ref.name,
                     alias = _ref.alias;
                   return alias || name;
-                })
+                }),
+                positions: positions
+              };
+            }
+            if (!isCssFile) {
+              _context.n = 6;
+              break;
+            }
+            // For CSS files, we don't need complex path resolution
+            // The parseImportsAndComments function already resolved paths for CSS
+            result = processRelativeImports(source, importsCompatible, storeAt);
+            processedSource = result.processedSource;
+            extraFiles = result.extraFiles;
+
+            // Build dependencies list for recursive loading (CSS files use direct paths)
+            extraDependencies = Object.values(importResult).map(function (_ref2) {
+              var path = _ref2.path;
+              return path;
+            });
+            _context.n = 8;
+            break;
+          case 6:
+            // 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;
+              relativeImportsCompatible[_importPath] = _extends({
+                path: _path,
+                names: _names.map(function (_ref3) {
+                  var name = _ref3.name,
+                    alias = _ref3.alias;
+                  return alias || name;
+                }),
+                // Use alias if available
+                positions: _positions
               }, includeTypeDefs && {
                 includeTypeDefs: includeTypeDefs
               });
             }
 
             // Resolve import paths, handling JS/TS modules and static assets appropriately
-            _context.n = 6;
+            _context.n = 7;
             return resolveImportResultWithFs(relativeImportsCompatible);
-          case 6:
+          case 7:
             resolvedPathsMap = _context.v;
-            // Process imports using the consolidated helper function
-            _processRelativeImpor = processRelativeImports(source, relativeImportsCompatible, resolvedPathsMap, storeAt), processedSource = _processRelativeImpor.processedSource, extraFiles = _processRelativeImpor.extraFiles; // Build dependencies list for recursive loading
-            extraDependencies = Object.values(importResult).map(function (_ref2) {
-              var path = _ref2.path;
+            // Process imports using the unified helper function
+            _result = processRelativeImports(source, importsCompatible, storeAt, true, resolvedPathsMap);
+            processedSource = _result.processedSource;
+            extraFiles = _result.extraFiles;
+
+            // 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;
             });
+          case 8:
             return _context.a(2, {
               source: processedSource,
               extraFiles: Object.keys(extraFiles).length > 0 ? extraFiles : undefined,

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

@@ -1,4 +1,4 @@
-export * from "./parseImports.js";
+export * from "./parseImportsAndComments.js";
 export * from "./resolveModulePath.js";
 export * from "./rewriteImports.js";
 export * from "./processRelativeImports.js";

package/esm/pipeline/loaderUtils/index.js

@@ -1,4 +1,4 @@
-export * from "./parseImports.js";
+export * from "./parseImportsAndComments.js";
 export * from "./resolveModulePath.js";
 export * from "./rewriteImports.js";
 export * from "./processRelativeImports.js";

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

@@ -0,0 +1,91 @@
+/**
+ * Represents a single import name with its properties.
+ */
+export interface ImportName {
+  /** The imported name or identifier */
+  name: string;
+  /** The alias used when importing (e.g., 'as newName') */
+  alias?: string;
+  /** The type of import: default, named, or namespace (*) */
+  type: 'default' | 'named' | 'namespace';
+  /** Whether this is a TypeScript type-only import */
+  isType?: boolean;
+}
+/**
+ * Represents the position of an import path in the source code.
+ */
+export interface ImportPathPosition {
+  /** The start index of the import path (including quotes) */
+  start: number;
+  /** The end index of the import path (including quotes) */
+  end: number;
+}
+/**
+ * Represents an import from a relative path (starts with ./ or ../).
+ */
+export interface RelativeImport {
+  /** The resolved absolute path to the imported file */
+  path: string;
+  /** Array of imported names from this module */
+  names: ImportName[];
+  /** Whether TypeScript type definitions should be included for this import */
+  includeTypeDefs?: true;
+  /** Array of positions where this import path appears in the source code */
+  positions: ImportPathPosition[];
+}
+/**
+ * Represents an import from an external package (node_modules).
+ */
+export interface ExternalImport {
+  /** Array of imported names from this external package */
+  names: ImportName[];
+  /** Array of positions where this import path appears in the source code */
+  positions: ImportPathPosition[];
+}
+/**
+ * The result of parsing import statements from source code.
+ */
+export interface ImportsAndComments {
+  /** Map of relative import paths to their import details */
+  relative: Record<string, RelativeImport>;
+  /** Map of external package names to their import details */
+  externals: Record<string, ExternalImport>;
+  /** The processed code with comments removed (if comment processing was requested) */
+  code?: string;
+  /** Map of line numbers to arrays of comment content (if comment processing was requested) */
+  comments?: Record<number, string[]>;
+}
+/**
+ * Parse import statements from JavaScript/TypeScript/CSS code.
+ *
+ * This function analyzes source code to extract all import statements, categorizing them
+ * as either relative imports (local files) or external imports (packages). It supports
+ * JavaScript, TypeScript, CSS, and MDX files.
+ *
+ * Comment processing (stripping/collecting) is performed during import parsing
+ * for efficiency. Since we must already parse the entire file character-by-character
+ * to correctly identify imports while avoiding false positives in strings, comments,
+ * and template literals, it's most efficient to handle comment processing in this
+ * same pass rather than requiring separate parsing steps.
+ *
+ * @param code - The source code to parse
+ * @param filePath - The file 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
+ * @returns Promise resolving to parsed import data, optionally including processed code and collected comments
+ *
+ * @example
+ * ```typescript
+ * const result = await parseImportsAndComments(
+ *   'import React from "react";\nimport { Button } from "./Button";',
+ *   '/src/App.tsx'
+ * );
+ * // result.externals['react'] contains the React import
+ * // result.relative['./Button'] contains the Button import
+ * ```
+ */
+export declare function parseImportsAndComments(code: string, filePath: string, options?: {
+  removeCommentsWithPrefix?: string[];
+  notableCommentsPrefix?: string[];
+}): Promise<ImportsAndComments>;