refactor(ui-codemods): update codemod dacumentation and usage, delete old codemods

Author: matyasf

docs/contributor-docs/codemods.md

@@ -0,0 +1,69 @@
+---
+title: Writing codemods
+category: Contributor Guides
+order: 11
+---
+
+## Codemods
+
+Codemods are small scripts that can automate tedious code refactorings. It's like Search & replace, just on steroids, InstUI uses them so breaking changes during major version upgrades are easier for users. Common use cases are renaming imports or props of components.
+
+To accomplish this our codemods use [jsCodeshift](https://github.com/facebook/jscodeshift). This tool parses source files to an Abstract Syntax Tree (AST) and gives us an API that can modify it.
+
+### Codemod development
+
+Our codemods live in the `ui-codemods` package. Each codemod is an ES module with a default export and is executed by jscodeshift. it should have the following code:
+
+```ts
+---
+type: code
+---
+import type { Transform } from 'jscodeshift'
+/**
+ * @param file the file to transform
+ * @param api jscodeshift instance
+ * @param options
+ * @param options.filename if `filename` is specified then emitted warnings are
+ * written to this file.
+ * @param options.usePrettier if `true` the transformed code will be run through
+ * [Prettier](https://prettier.io/). You can customize this through a [Prettier
+ * config file](https://prettier.io/docs/configuration.html)
+ * @returns the modified file as `string` or `null`
+ */
+const myCodemod: Transform = (file, api,
+                              options?: { fileName?: string; usePrettier?: boolean }) => {
+    return instUICodemodExecutor([my, cool, scripts], file, api, options)
+}
+export default myCodemod
+```
+
+> You can find lots of useful helper functions in `utils/codemodhelpers.ts` and `utils/codemodTypeCheckers.ts`
+
+#### Testing codemods
+
+You should write unit tests for your codemods. They are tested via test fixtures (sample before transform, sample after transform). To create a unit test for say `sampleCodemod` the following steps are needed:
+
+1, create a new test in `__node_tests__/codemod.tests.ts`:
+
+```ts
+---
+type: code
+---
+it('tests the cool sampleCodemod', () => {
+  runTest(sampleCodemod)
+})
+```
+
+2, create a folder named `sampleCodemod` in `__node_tests__/__testfixtures__`  
+3, Here create sample input-output file pairs whose filename follows the following naming convention: `[fixtureName].input.[js/ts/tsx]`, `[fixtureName].output.[js/ts/tsx]`. These should be your test cases that ensure that the codemod does the transformation correctly.
+
+Done! Run `npm run test:vitest ui-codemods` to run your test.
+
+Finally, you should try to run your codemod as users will do:
+
+```sh
+---
+type: code
+---
+npx [email protected] -t /path/to/sampleCodemod.ts /path/to/code/to/rewrite --usePrettier=false
+```

packages/ui-codemods/README.md

@@ -4,7 +4,7 @@ category: packages
 
 ## ui-codemods
 
-The ui-codemods package should make it easier to deal with API changes when upgrading Instructure UI libraries.
+The `ui-codemods` package should make it easier to deal with API changes when upgrading Instructure UI libraries.
 
 [![npm][npm]][npm-url]
 [![MIT License][license-badge]][license]
@@ -18,102 +18,20 @@ The codemod scripts can be installed via the following command:
 ---
 type: code
 ---
-npm install @instructure/ui-codemods
+# use here the InstUI version number you are upgrading to
+npm install @instructure/ui-codemods@10
 ```
 
-The configuration files are located in the [instui-config](#instui-config) package.
-This can be installed via the following command:
-
-```sh
----
-type: code
----
-npm install @instructure/instui-config
-```
-
-### Updating Deprecated Props
-
-This codemod helps you update your project by renaming `props` that have had names changed (e.g., `onReady` => `onOpen`).
-
-```sh
----
-type: code
----
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updatePropNames.ts <path> --config=node_modules/@instructure/instui-config/codemod-configs/v<version number ex. 5 or 6>/propNames.config.json
-```
-
-### Updating Package Imports
-
-This codemod helps you update your project by renaming `imports` that have changed (e.g., `instructure-ui` => `@instructure/<package name>`).
-
-```sh
----
-type: code
----
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updateImports.ts <path> --config=node_modules/@instructure/instui-config/codemod-configs/v<version number ex. 5 or 6>/imports.config.js
-```
-
-### Updating more complex props to the InstUI v8 syntax
-
-This codemod upgrades more complex changes like Button, also outputs any manual changes needed to the console. Run this in a InstUI v7 codebase only. This command has an optional fileName parameter, supplying this will append to the given file the warnings.
-
-```sh
----
-type: code
----
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updateV7Props.ts <path> -fileName updateV7PropsWarnings.txt
-```
-
-### Codemod for breaking changes after updating the dependencies to V8
-
-```sh
----
-type: code
----
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updateV8Breaking.ts <path>
-```
-
-This codemod updates breaking changes after a v8 upgrade. Run this in a project after you have upgraded your dependencies to InstUI v8.
-
-### Codemod for breaking changes after updating the dependencies to V9
-
-```sh
----
-type: code
----
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updateV9Breaking.ts <path> --parser=tsx --usePrettier=false
-```
-
-This codemod addresses breaking changes following a v9 upgrade. Notably, it updates `EmotionThemeProvider` to `InstUISettingsProvider`. Execute this in your project post-upgrade to InstUI v9. Prettier is turned on by default for output formatting, and you can also use the `usePrettier` flag. Additionally, the parser flag can specify the parser for jsx and tsx files.
-
 ### Codemod for changing the color palette to the v10 color palette
 
 ```sh
 ---
 type: code
 ---
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updateV10Breaking.ts <path> --parser=tsx --usePrettier=false
-```
-
-This codemod updates the `canvas` and `canvas-high-contrast` color palettes. Execute this in your project post-upgrade to InstUI v10. Prettier is turned on by default for output formatting, and you can also use the `usePrettier` flag. Additionally, the parser flag can specify the parser for jsx and tsx files.
-
-### Codemod for adding a wrapper to ReactDOM.render()
-
-```sh
----
-type: code
----
-jscodeshift -t node_modules/@instructure/ui-codemods/lib/updateV8ReactDOM.ts <path> -fileName updateV8ReactDOM.txt
+npx [email protected] -t node_modules/@instructure/ui-codemods/lib/updateV10Breaking.ts <path> --usePrettier=false
 ```
 
-This codemod updates ReactDOM.render calls with a given wrapper, for example:
-ReactDOM.render(<div />) -> ReactDOM.render(<Root><div /></Root>).
-Parameters (all optional):
-
-- `fileName`: supplying this will append to the given file the warnings.
-- `wrapperPath`: The import path for the wrapper, default value is '@canvas/react-root'.
-- `wrapperTag`: The tag to wrap render calls in, default is 'Root'.
-- `isDefaultImport`: Is the given tag a default import? Default value is `true`.
+This codemod updates the `canvas` and `canvas-high-contrast` color palettes. Execute this in your project post-upgrade to InstUI v10. Prettier is turned on by default for output formatting, and you can also use the `usePrettier` flag.
 
 [npm]: https://img.shields.io/npm/v/@instructure/ui-codemods.svg
 [npm-url]: https://npmjs.com/package/@instructure/ui-codemods

packages/ui-codemods/lib/__node_tests__/__testfixtures__/updateV10Breaking/colorsJS.input.js

@@ -0,0 +1,43 @@
+// this is the same as the other colors test, it just makes sure that
+// codemods work on plain `.js` files too
+/* eslint-disable */
+// @ts-nocheck
+import { canvas, canvasHighContrast } from '@instructure/ui'
+
+export const generateStyle = () => {
+  return {
+    logoSubtitle: {
+      label: 'logoSubtitle',
+      marginTop: '-3px'
+    },
+    optionWrapper: {
+      label: 'optionWrapper',
+      margin: '-0.5rem -0.75rem',
+      padding: '0.5rem 0.75rem',
+      border: '0 solid ' + canvas.colors.tiara,
+      borderBottomWidth: '1px',
+      display: 'flex',
+      maxWidth: '100%',
+      overflow: 'hidden',
+      alignItems: 'center'
+    },
+    optionIcon: {
+      label: 'optionIcon',
+      width: '36px',
+      height: '36px',
+      backgroundColor: canvasHighContrast.colors.oxford,
+      borderRadius: 100,
+      flexShrink: 0,
+      display: 'flex',
+      justifyContent: 'center',
+      alignItems: 'center'
+    },
+    truncateSingleLine: {
+      overflow: 'hidden',
+      whiteSpace: 'nowrap',
+      textOverflow: 'ellipsis'
+    }
+  }
+}
+
+export const generateComponentTheme = () => ({})

packages/ui-codemods/lib/__node_tests__/__testfixtures__/updateV10Breaking/colorsJS.output.js

@@ -0,0 +1,43 @@
+// this is the same as the other colors test, it just makes sure that
+// codemods work on plain `.js` files too
+/* eslint-disable */
+// @ts-nocheck
+import { canvas, canvasHighContrast } from '@instructure/ui'
+
+export const generateStyle = () => {
+  return {
+    logoSubtitle: {
+      label: 'logoSubtitle',
+      marginTop: '-3px'
+    },
+    optionWrapper: {
+      label: 'optionWrapper',
+      margin: '-0.5rem -0.75rem',
+      padding: '0.5rem 0.75rem',
+      border: '0 solid ' + canvas.colors?.contrasts?.grey1214,
+      borderBottomWidth: '1px',
+      display: 'flex',
+      maxWidth: '100%',
+      overflow: 'hidden',
+      alignItems: 'center'
+    },
+    optionIcon: {
+      label: 'optionIcon',
+      width: '36px',
+      height: '36px',
+      backgroundColor: canvasHighContrast.colors?.contrasts?.grey100100,
+      borderRadius: 100,
+      flexShrink: 0,
+      display: 'flex',
+      justifyContent: 'center',
+      alignItems: 'center'
+    },
+    truncateSingleLine: {
+      overflow: 'hidden',
+      whiteSpace: 'nowrap',
+      textOverflow: 'ellipsis'
+    }
+  }
+}
+
+export const generateComponentTheme = () => ({})

…__node_tests__/updateV10Breaking.test.ts …mods/lib/__node_tests__/codemods.test.tspackages/ui-codemods/lib/__node_tests__/updateV10Breaking.test.ts renamed to packages/ui-codemods/lib/__node_tests__/codemods.test.ts packages/ui-codemods/lib/__node_tests__/updateV10Breaking.test.ts renamed to packages/ui-codemods/lib/__node_tests__/codemods.test.ts

@@ -22,11 +22,11 @@
  * SOFTWARE.
  */
 
-import { runTest } from './testHelpers'
+import { runTest } from './runTest'
 import updateV10Breaking from '../updateV10Breaking'
 
-describe('updateV10Breaking', () => {
-  it('test color codemods', () => {
+describe('test codemods', () => {
+  it('test InstUI v10 color codemods', () => {
     runTest(updateV10Breaking)
   })
 })

…demods/lib/__node_tests__/testHelpers.ts …i-codemods/lib/__node_tests__/runTest.tspackages/ui-codemods/lib/__node_tests__/testHelpers.ts renamed to packages/ui-codemods/lib/__node_tests__/runTest.ts packages/ui-codemods/lib/__node_tests__/testHelpers.ts renamed to packages/ui-codemods/lib/__node_tests__/runTest.ts

@@ -63,9 +63,7 @@ export function runTest(codemod: Transform) {
       // based on the file's extension.
       // Also, this is closer to how its used, there is always a correct
       // filename
-      runInlineTest(codemod, {}, { path: inputPath, source: input }, expected, {
-        parser: 'tsx'
-      })
+      runInlineTest(codemod, {}, { path: inputPath, source: input }, expected)
       fixturesRun++
     }
   })