[codemod] Document and Clean the codemod utils (mui#21014)

Author: alexfauquette

packages/x-codemod/src/util/propsToObject.ts

@@ -5,6 +5,10 @@ const getAttributeName = (attribute: JSXAttribute): string =>
 
 interface RemoveObjectPropertyArgs {
   root: Collection<any>;
+  /**
+   * Names of the components to target
+   * @example ["DataGrid", "DataGridPro"]
+   */
   componentsNames: string[];
   /**
    * Prop which contains the object whose property will be removed
@@ -21,6 +25,10 @@ interface RemoveObjectPropertyArgs {
   j: JSCodeshift;
 }
 
+/**
+ * Removes a property from an object prop in specified components.
+ * If the object only contains that property, the whole prop is removed.
+ */
 export default function removeObjectProperty({
   root,
   propName,

packages/x-codemod/src/util/removeObjectProperty.ts

@@ -2,11 +2,22 @@ import type { Collection, JSCodeshift } from 'jscodeshift';
 
 interface RemovePropsArgs {
   root: Collection<any>;
+  /**
+   * Names of the components to target
+   * @example ["DataGrid", "DataGridPro"]
+   */
   componentNames: string[];
+  /**
+   * The list of props to remove
+   * @example ["disableSelectionOnClick", "hideFooterSelectedRowCount"]
+   */
   props: string[];
   j: JSCodeshift;
 }
 
+/**
+ * Removes specified props from given components.
+ */
 export default function removeProps({ root, componentNames, props, j }: RemovePropsArgs) {
   return root
     .find(j.JSXElement)

packages/x-codemod/src/util/removeProps.ts

@@ -2,7 +2,15 @@ import type { Collection, JSCodeshift } from 'jscodeshift';
 
 interface RenamePropsArgs {
   root: Collection<any>;
+  /**
+   * Names of the components to target
+   * @example ["DataGrid", "DataGridPro"]
+   */
   componentNames: string[];
+  /**
+   * Translation mapping from component names to slot names
+   * @example { Root: "root", Input: "input" }
+   */
   translation: Record<string, string>;
   j: JSCodeshift;
 }
@@ -18,6 +26,10 @@ const getSlotsTranslation = (translations: Record<string, string>) => {
   return lowercasedTranslation;
 };
 
+/**
+ * Replace the components / componentsProps by their equivalent slots / slotProps.
+ * Only used for v6 -> v7 migration.
+ */
 export default function renameComponentsSlots({
   root,
   componentNames,

packages/x-codemod/src/util/renameCSSClasses.ts

@@ -7,16 +7,34 @@ import type {
 } from 'jscodeshift';
 
 interface ImportConfig {
+  /**
+   * The old endpoint relative to the package name.
+   * @example 'TreeView' in '@mui/x-tree-view/TreeView'
+   */
   oldEndpoint?: string;
+  /**
+   * The new endpoint relative to the package name.
+   * @example 'SimpleTreeView' in '@mui/x-tree-view/SimpleTreeView'
+   */
   newEndpoint?: string;
-  skipRoot?: boolean;
+  /**
+   * The mapping of old identifier names to new identifier names.
+   * @example { TreeView: 'SimpleTreeView', TreeItem: 'SimpleTreeItem' }
+   */
   importsMapping: Record<string, string>;
 }
 
 interface RenameImportsParameters {
   j: JSCodeshift;
   root: Collection<any>;
+  /**
+   * The list of packages impacted by the renaming.
+   * @example ['@mui/x-date-pickers', '@mui/x-date-pickers-pro']
+   */
   packageNames: string[];
+  /**
+   * The list of renaming configurations to apply.
+   */
   imports: ImportConfig[];
 }
 
@@ -49,12 +67,13 @@ const getMatchingRootImport = (
   parameters: RenameImportsParameters,
 ) => {
   return parameters.imports.find((importConfig) => {
-    return (
-      !importConfig.skipRoot && importConfig.importsMapping.hasOwnProperty(path.node.imported.name)
-    );
+    return importConfig.importsMapping.hasOwnProperty(path.node.imported.name);
   });
 };
 
+/**
+ * Rename import paths, identifiers and usages based on a renaming configuration.
+ */
 export function renameImports(parameters: RenameImportsParameters) {
   const { j, root } = parameters;
 

packages/x-codemod/src/util/renameComponentsSlots.ts

@@ -2,11 +2,24 @@ import type { Collection, JSCodeshift } from 'jscodeshift';
 
 interface RenamePropsArgs {
   root: Collection<any>;
+  /**
+   * Names of the components to target
+   * @example ["DataGrid", "DataGridPro"]
+   */
   componentNames: string[];
+  /**
+   * Object that maps prop names to their nested properties renaming mappings.
+   *
+   * In the following example we rename properties inside `componentsProps` prop:
+   * @example { componentsProps: { root: "slotRoot", input: "slotInput" } }
+   */
   nestedProps: Record<string, Record<string, any>>;
   j: JSCodeshift;
 }
 
+/**
+ * Allow to rename object properties inside props of specified components.
+ */
 export default function renameNestedProps({
   root,
   componentNames,

packages/x-codemod/src/util/renameImports.ts

@@ -2,7 +2,15 @@ import type { Collection, JSCodeshift } from 'jscodeshift';
 
 interface RenamePropsArgs {
   root: Collection<any>;
+  /**
+   * Names of the components to target
+   * @example ["DataGrid", "DataGridPro"]
+   */
   componentNames: string[];
+  /**
+   * Props renaming mapping
+   * @example { disableSelectionOnClick: "disableRowSelectionOnClick" }
+   */
   props: Record<string, any>;
   j: JSCodeshift;
 }

packages/x-codemod/src/util/renameNestedProps.ts

@@ -1,4 +1,4 @@
-import renameCSSClasses from '../../../util/renameCSSClasses';
+import type { Collection, JSCodeshift } from 'jscodeshift';
 import { JsCodeShiftAPI, JsCodeShiftFileInfo } from '../../../types';
 import renameIdentifiers, { PreRequisiteUsage, matchImport } from '../../../util/renameIdentifiers';
 
@@ -50,10 +50,41 @@ const renamedLiterals = {
   filterPanelLinkOperator: 'filterPanelLogicOperator',
 };
 
-const renamedClasses = {
-  'MuiDataGrid-filterFormLinkOperatorInput': 'MuiDataGrid-filterFormLogicOperatorInput',
-  'MuiDataGrid-withBorder': 'MuiDataGrid-withBorderColor',
-};
+interface RenameCSSClassesArgs {
+  root: Collection<any>;
+  j: JSCodeshift;
+}
+
+/**
+ * Renames CSS classes when they are literals based on the provided mapping.
+ */
+function renameCSSClasses({ root, j }: RenameCSSClassesArgs) {
+  const renamedClasses = {
+    'MuiDataGrid-filterFormLinkOperatorInput': 'MuiDataGrid-filterFormLogicOperatorInput',
+    'MuiDataGrid-withBorder': 'MuiDataGrid-withBorderColor',
+  };
+
+  root
+    .find(j.Literal)
+    .filter(
+      (path) =>
+        !!Object.keys(renamedClasses).find((className) => {
+          const literal = path.node.value as any;
+          return (
+            typeof literal === 'string' &&
+            literal.includes(className) &&
+            !literal.includes(renamedClasses[className])
+          );
+        }),
+    )
+    .replaceWith((path) => {
+      const literal = path.node.value as any;
+      const targetClassKey = Object.keys(renamedClasses).find((className) =>
+        literal.includes(className),
+      )!;
+      return j.literal(literal.replace(targetClassKey, renamedClasses[targetClassKey]));
+    });
+}
 
 export default function transform(file: JsCodeShiftFileInfo, api: JsCodeShiftAPI, options: any) {
   const j = api.jscodeshift;
@@ -98,7 +129,7 @@ export default function transform(file: JsCodeShiftFileInfo, api: JsCodeShiftAPI
     // Rename the classes
     // - 'MuiDataGrid-filterFormLinkOperatorInput'
     // + 'MuiDataGrid-filterFormLogicOperatorInput'
-    renameCSSClasses({ j, root, renamedClasses });
+    renameCSSClasses({ j, root });
   }
 
   return root.toSource(printOptions);