feat: add codemod (#3836)

.changeset/good-houses-end.md

@@ -0,0 +1,5 @@
+---
+'@toptal/picasso-codemod': minor
+---
+
+- add `spacing-values` codemod. Please run the codemod (`npx @toptal/picasso-codemod@latest v38.1.0`) to replace spacing property values of `Container` and `Dropdown` components with BASE-aligned property values according to the https://github.com/toptal/picasso/blob/master/docs/decisions/18-spacings.md. Property values that do not have BASE counterpart or are complex expressions have to be updated manually (non-BASE values have to be replaced with BASE ones after consulting with Design Team), codemod outputs the list of such cases for convenience. Run linter or prettier to align updated code with project code style.

packages/picasso-codemod/README.md

@@ -41,6 +41,15 @@ Codemods do not guarantee the code format preservation. Therefore be sure to run
 
 ## Included Scripts
 
+
+### v38.1.0
+
+Replaces spacing property values of `Container` and `Dropdown` components with BASE-aligned property values according to the https://github.com/toptal/picasso/blob/master/docs/decisions/18-spacings.md. Property values that do not have BASE counterpart or are complex expressions have to be updated manually (non-BASE values have to be replaced with BASE ones after consulting with Design Team), codemod outputs the list of such cases for convenience. Run linter or prettier to align updated code with project code style
+
+```sh
+npx @toptal/picasso-codemod v38.1.0@latest
+```
+
 ### v36.0.0
 
 Replaces all imports of RichTextEditor related components to `@toptal/picasso-rich-text-editor` and updates package.json with a new version of `@toptal/picasso`, `@toptal/picasso-rich-text-editor` and `@toptal/picasso-forms`

packages/picasso-codemod/package.json

@@ -27,7 +27,7 @@
     "react": ">=16.12.0 < 19.0.0"
   },
   "devDependencies": {
-    "@types/jscodeshift": "^0.11.5"
+    "@types/jscodeshift": "^0.11.6"
   },
   "bin": {
     "picasso-codemod": "./bin/picasso-codemod.mjs"

packages/picasso-codemod/src/v38.1.0/__testfixtures__/default.input.tsx

@@ -0,0 +1,35 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+import React from 'react'
+import { Container } from '@toptal/picasso'
+
+const test = 'large'
+const booleanVariable = true
+const extraProps = { align: 'left '}
+
+export default () => (
+  <>
+    <Container top='small' someProp='small'>Content</Container>
+    <Container right={test} someProp={1.5}>Content</Container>
+    <Container bottom={1.5}>Content</Container>
+    <Container left={1.6}>Content</Container>
+    <Container top={booleanVariable ? 'small' : 1.5}>Content</Container>
+    <Container {...extraProps}>Content</Container>
+    <Dropdown
+      someProp='small'
+      offset={{
+        top: 'small',
+        right: test,
+        bottom: 3,
+        left: 1.6
+      }}
+      content={
+        <Menu>
+          <Menu.Item>Menu item 1</Menu.Item>
+        </Menu>
+      }
+    >
+      Dropdown
+    </Dropdown>
+  </>
+)

packages/picasso-codemod/src/v38.1.0/__testfixtures__/default.output.tsx

@@ -0,0 +1,37 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+import React from 'react'
+import { Container } from '@toptal/picasso'
+
+import { SPACING_4, SPACING_6, SPACING_12 } from '@toptal/picasso/utils';
+
+const test = 'large'
+const booleanVariable = true
+const extraProps = { align: 'left '}
+
+export default () => (
+  <>
+    <Container top={SPACING_4} someProp='small'>Content</Container>
+    <Container right={test} someProp={1.5}>Content</Container>
+    <Container bottom={SPACING_6}>Content</Container>
+    <Container left={1.6}>Content</Container>
+    <Container top={booleanVariable ? SPACING_4 : SPACING_6}>Content</Container>
+    <Container {...extraProps}>Content</Container>
+    <Dropdown
+      someProp='small'
+      offset={{
+        top: SPACING_4,
+        right: test,
+        bottom: SPACING_12,
+        left: 1.6
+      }}
+      content={
+        <Menu>
+          <Menu.Item>Menu item 1</Menu.Item>
+        </Menu>
+      }
+    >
+      Dropdown
+    </Dropdown>
+  </>
+)

packages/picasso-codemod/src/v38.1.0/__tests__/test.ts

@@ -0,0 +1,3 @@
+import { defineTest } from 'jscodeshift/src/testUtils'
+
+defineTest(__dirname, 'spacing-values', {}, 'default', { parser: 'tsx' })

packages/picasso-codemod/src/v38.1.0/config.ts

@@ -0,0 +1,10 @@
+export const AFFECTED_COMPONENTS = ['Container', 'Dropdown']
+export const AFFECTED_ATTRIBUTES = [
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'padded',
+  'gap',
+  'offset',
+]

packages/picasso-codemod/src/v38.1.0/index.ts

@@ -0,0 +1 @@
+export { default } from './spacing-values'

packages/picasso-codemod/src/v38.1.0/spacing-values.ts

@@ -0,0 +1,118 @@
+import type {
+  JSXAttribute,
+  JSXIdentifier,
+  JSXMemberExpression,
+  JSXNamespacedName,
+  JSXSpreadAttribute,
+  Transform,
+} from 'jscodeshift'
+
+import { AFFECTED_ATTRIBUTES, AFFECTED_COMPONENTS } from './config'
+import type { ManuallyFixableCase, TransformationOptions } from './types'
+import {
+  reportManuallyFixableCases,
+  insertSpacingImport,
+  getUpdatedNode,
+} from './utils'
+
+const isJSXAttribute = (
+  attribute: JSXSpreadAttribute | JSXAttribute
+): attribute is JSXAttribute => !!(attribute as any).name?.name
+const isJSXMemberExpression = (
+  element: JSXIdentifier | JSXNamespacedName | JSXMemberExpression
+): element is JSXMemberExpression => !(element as any).name
+
+const transform: Transform = (file, api) => {
+  const spacingsToImport: string[] = []
+  const manuallyFixableCases: ManuallyFixableCase[] = []
+
+  const j = api.jscodeshift
+  const ast = j(file.source)
+
+  ast
+    .find(j.JSXElement)
+    .filter(path => {
+      if (isJSXMemberExpression(path.node.openingElement.name)) {
+        return false
+      }
+
+      if (typeof path.node.openingElement.name.name !== 'string') {
+        return false
+      }
+
+      return AFFECTED_COMPONENTS.includes(path.node.openingElement.name.name)
+    })
+    .forEach(element => {
+      const updatedElementAttributes =
+        element.node.openingElement.attributes?.map(attribute => {
+          if (!isJSXAttribute(attribute)) {
+            return attribute
+          }
+
+          const attributeName = attribute.name.name
+          const ignoreAttribute =
+            !(typeof attributeName === 'string') ||
+            !AFFECTED_ATTRIBUTES.includes(attributeName)
+
+          if (ignoreAttribute) {
+            return attribute
+          }
+
+          // Populate "manuallyFixableCases" and "spacingsToImport" as transformations are happening
+          // deeper and deeper in attribute value node
+          const transformationOptions: TransformationOptions = {
+            api,
+            reportManuallyFixableCase: () => {
+              if (isJSXMemberExpression(element.value.openingElement.name)) {
+                return
+              }
+
+              if (typeof element.value.openingElement.name.name !== 'string') {
+                return
+              }
+
+              manuallyFixableCases.push({
+                componentName: element.value.openingElement.name.name,
+                attributeName,
+                location: `${file.path}:${element.value.loc?.start.line}`,
+              })
+            },
+            addSpacingImport: spacingIdentifier =>
+              spacingsToImport.push(spacingIdentifier),
+          }
+
+          if (attribute.value?.type === 'JSXExpressionContainer') {
+            const updatedNode = getUpdatedNode(
+              attribute.value.expression,
+              transformationOptions
+            )
+
+            attribute.value.expression = updatedNode
+          } else if (attribute.value) {
+            const updatedNode = getUpdatedNode(
+              attribute.value,
+              transformationOptions
+            )
+
+            attribute.value =
+              api.jscodeshift.jsxExpressionContainer(updatedNode)
+          }
+
+          return attribute
+        })
+
+      element.node.openingElement.attributes = updatedElementAttributes
+    })
+
+  if (spacingsToImport.length > 0) {
+    insertSpacingImport(api, ast, spacingsToImport)
+  }
+
+  if (manuallyFixableCases.length > 0) {
+    reportManuallyFixableCases(manuallyFixableCases)
+  }
+
+  return ast.toSource({ quote: 'single' })
+}
+
+export default transform

packages/picasso-codemod/src/v38.1.0/types.ts

@@ -0,0 +1,13 @@
+import type { API } from 'jscodeshift'
+
+export type TransformationOptions = {
+  api: API
+  reportManuallyFixableCase: () => void
+  addSpacingImport: (spacingIdentifier: string) => void
+}
+
+export type ManuallyFixableCase = {
+  componentName: string
+  attributeName: string
+  location: string
+}

packages/picasso-codemod/src/v38.1.0/utils/get-node-for-number.ts

@@ -0,0 +1,32 @@
+import type { TransformationOptions } from '../types'
+
+export const NUMERIC_VALUE_TO_SPACING_CONSTANTS = [
+  { value: 0, name: 'SPACING_0' },
+  { value: 0.25, name: 'SPACING_1' },
+  { value: 0.5, name: 'SPACING_2' },
+  { value: 0.75, name: 'SPACING_3' },
+  { value: 1, name: 'SPACING_4' },
+  { value: 1.5, name: 'SPACING_6' },
+  { value: 2, name: 'SPACING_8' },
+  { value: 2.5, name: 'SPACING_10' },
+  { value: 3, name: 'SPACING_12' },
+]
+
+export const getNodeForNumber = (
+  node: any,
+  { api, reportManuallyFixableCase, addSpacingImport }: TransformationOptions
+) => {
+  const numericValue = node.value
+  const spacing = NUMERIC_VALUE_TO_SPACING_CONSTANTS.find(
+    ({ value }) => value === numericValue
+  )
+
+  if (spacing) {
+    addSpacingImport(spacing.name)
+
+    return api.jscodeshift.identifier(spacing.name)
+  }
+  reportManuallyFixableCase()
+
+  return node
+}

packages/picasso-codemod/src/v38.1.0/utils/get-node-for-size-string-constant.ts

@@ -0,0 +1,27 @@
+import type { TransformationOptions } from '../types'
+
+export const SIZE_TO_SPACING_CONSTANT: Record<string, string> = {
+  xsmall: 'SPACING_2',
+  small: 'SPACING_4',
+  medium: 'SPACING_6',
+  large: 'SPACING_8',
+  xlarge: 'SPACING_10',
+}
+
+export const getNodeForSizeStringConstant = (
+  node: any,
+  { api, addSpacingImport }: TransformationOptions
+) => {
+  const spacingConstant = node.value
+  const spacingName = SIZE_TO_SPACING_CONSTANT[spacingConstant]
+
+  if (!spacingName) {
+    throw new Error(
+      `Unable to match "${spacingConstant}" size string constant to BASE spacing`
+    )
+  }
+
+  addSpacingImport(spacingName)
+
+  return api.jscodeshift.identifier(spacingName)
+}

packages/picasso-codemod/src/v38.1.0/utils/get-updated-node.ts

@@ -0,0 +1,47 @@
+import type {
+  ConditionalExpression,
+  JSXAttribute,
+  JSXExpressionContainer,
+} from 'jscodeshift'
+
+import type { TransformationOptions } from '../types'
+import { getNodeForNumber } from './get-node-for-number'
+import { getNodeForSizeStringConstant } from './get-node-for-size-string-constant'
+
+type NodeType =
+  | JSXExpressionContainer['expression']
+  | NonNullable<JSXAttribute['value']>
+
+export const getUpdatedNode = (
+  node: NodeType,
+  options: TransformationOptions
+) => {
+  const { reportManuallyFixableCase } = options
+
+  if (node.type === 'StringLiteral') {
+    node = getNodeForSizeStringConstant(node, options)
+  } else if (node.type === 'NumericLiteral') {
+    node = getNodeForNumber(node, options)
+  } else if (node.type === 'ObjectExpression') {
+    const updatedProperties = node.properties.map((property: any) => {
+      property.value = getUpdatedNode(property.value, options)
+
+      return property
+    })
+
+    node.properties = updatedProperties
+  } else if (node.type === 'ConditionalExpression') {
+    node.consequent = getUpdatedNode(
+      node.consequent,
+      options
+    ) as ConditionalExpression['consequent']
+    node.alternate = getUpdatedNode(
+      node.alternate,
+      options
+    ) as ConditionalExpression['alternate']
+  } else {
+    reportManuallyFixableCase()
+  }
+
+  return node
+}

packages/picasso-codemod/src/v38.1.0/utils/index.ts

@@ -0,0 +1,5 @@
+export { getUpdatedNode } from './get-updated-node'
+export { getNodeForNumber } from './get-node-for-number'
+export { getNodeForSizeStringConstant } from './get-node-for-size-string-constant'
+export { reportManuallyFixableCases } from './report-manually-fixable-cases'
+export { insertSpacingImport } from './insert-spacing-import'