@mui/internal-docs-infra
Version:
MUI Infra - internal documentation creation tools.
109 lines • 4.83 kB
text/typescript
/**
* Comment prefixes for tool-specific ignore directives that should be stripped
* from documentation code blocks by default. These comments are noise in docs
* and don't provide value to the reader.
*/
export declare const IGNORE_COMMENT_PREFIXES: string[];
/**
* 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 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 */
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 1-indexed output line numbers (in `code`, after comment removal) to arrays of
* comment content (if comment processing was requested). 1-indexed is the canonical
* `Code` convention, matching the HAST `dataLn` gutter the enhancers read.
*/
comments?: Record<number, string[]>;
}
/**
* Parse import and export-from statements from JavaScript/TypeScript/CSS code.
*
* This function analyzes source code to extract all import and export-from 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.
*
* The function accepts file:// URLs, http(s):// URLs, or file paths. File URLs
* and OS paths are normalized to a portable POSIX-style path internally and
* resolved via `path.resolve`. http(s):// URLs are preserved verbatim and
* relative imports are resolved via WHATWG `URL`, which means demos can be
* parsed straight out of remote sources without first being mapped onto a
* placeholder `file://` URL.
*
* @param code - The source code to parse
* @param fileUrl - The file URL (`file://`, `http://`, `https://`) 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
* @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";\nexport { Icon } from "./Icon";',
* '/src/App.tsx'
* );
* // result.externals['react'] contains the React import
* // result.relative['./Button'] contains the Button import
* // result.relative['./Icon'] contains the Icon re-export
* ```
*/
export declare function parseImportsAndComments(code: string, fileUrl: string, options?: {
removeCommentsWithPrefix?: string[];
notableCommentsPrefix?: string[];
}): Promise<ImportsAndComments>;