Breadcrumb migrator (#8071)

### WHY are these changes introduced?

In v11 we are moving away from arrays in breadcrumbs props in Page
components and using single objects instead in order to make the
interface easier to understand. This migrator takes the inside object of
the array and keeps it in the same prop. This will make the v11
migration easier for consumers.

I might change it to using the last item in the array in case some
people are still using multiple items in the array. Web is not but that
doesn't mean others aren't.

Also I think I'm going to write a codepath to remove the prop altogether
if there is an empty array? I could leave the comment though and let
people resolve themselves.


### How to 🎩
```
npx @shopify/polaris-migrator@0.0.0-snapshot-release-20230223014528 v11-react-update-page-breadcrumbs './**/*.{ts,tsx}'
```
then run eslint and prettier:
```
npx eslint --fix .
npx prettier --write .
```

After applying a migration, it might be helpful to commit the changes
that do not need a manual check from those that do. You can do this a
few different ways, but we suggest staging all your changes, then
unstaging those that include the manual check comment:
```sh
# Stash files with "polaris-migrator:" comments
git stash push $(grep -r -l "polaris-migrator:" $(git ls-files -m))

# Stage all files without "polaris-migrator:" comments
git add .

# Bring back the change with "polaris-migrator:" comments
git stash pop

# (optional) if there a files that have both "polaris-migrator:" comments
# _and_ complete fixes, add the complete fixes now
git add -p

# Commit all the complete fixes:
git commit

# Now you're left with changes that have "polaris-migrator:" comments only
```

### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

---------

Co-authored-by: Sam Rose <sam.rose@shopify.com>

Author: itwasmattgregg

.changeset/silent-elephants-compare.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris-migrator': minor
+---
+
+Added a migration for updating the Page component `breadcrumbs` prop to use an object instead of an array

polaris-migrator/src/migrations/v11-react-update-page-breadcrumbs/tests/v11-react-update-page-breadcrumbs.input.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import {Page} from '@shopify/polaris';
+
+export function App({
+  breadcrumbProps = [{url: '/testing', content: 'Breadcrumb'}],
+}) {
+  const breadcrumbs = [{url: '/testing', content: 'Breadcrumb'}];
+  const getBreadcrumbs = () => [{url: '/testing', content: 'Breadcrumb'}];
+  return (
+    <>
+      <Page breadcrumbs={[{url: '/testing', content: 'Breadcrumb'}]}>
+        hello
+      </Page>
+      <Page
+        breadcrumbs={[
+          {url: '/testing', content: 'Breadcrumb'},
+          {url: '/testing2', content: 'Breadcrumb2'},
+        ]}
+      >
+        hello
+      </Page>
+      <Page breadcrumbs={[]}>testing</Page>
+      <Page breadcrumbs={breadcrumbs}>testing</Page>
+      <Page breadcrumbs={breadcrumbProps}>testing</Page>
+      <Page breadcrumbs={getBreadcrumbs()}>testing</Page>
+    </>
+  );
+}

polaris-migrator/src/migrations/v11-react-update-page-breadcrumbs/tests/v11-react-update-page-breadcrumbs.output.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import {Page} from '@shopify/polaris';
+
+export function App({
+  breadcrumbProps = [{url: '/testing', content: 'Breadcrumb'}],
+}) {
+  const breadcrumbs = [{url: '/testing', content: 'Breadcrumb'}];
+  const getBreadcrumbs = () => [{url: '/testing', content: 'Breadcrumb'}];
+  return (
+    <>
+      <Page backAction={{url: '/testing', content: 'Breadcrumb'}}>hello</Page>
+      <Page backAction={{url: '/testing2', content: 'Breadcrumb2'}}>hello</Page>
+      <Page>testing</Page>
+      <Page
+        backAction={
+          /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. In this case, you will need to update the breadcrumbs variable to be a single object instead of an array as arrays have been deprecated. */
+          breadcrumbs
+        }
+      >
+        testing
+      </Page>
+      <Page
+        backAction={
+          /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. In this case, you will need to update the breadcrumbs variable to be a single object instead of an array as arrays have been deprecated. */
+          breadcrumbProps
+        }
+      >
+        testing
+      </Page>
+      <Page
+        backAction={
+          /* polaris-migrator: Unable to migrate the following expression. Please upgrade manually. In this case, you will need to update the breadcrumbs variable to be a single object instead of an array as arrays have been deprecated. */
+          getBreadcrumbs()
+        }
+      >
+        testing
+      </Page>
+    </>
+  );
+}

polaris-migrator/src/migrations/v11-react-update-page-breadcrumbs/tests/v11-react-update-page-breadcrumbs.test.ts

@@ -0,0 +1,11 @@
+import {check} from '../../../utilities/testUtils';
+
+const migration = 'v11-react-update-page-breadcrumbs';
+const fixtures = ['v11-react-update-page-breadcrumbs'];
+
+for (const fixture of fixtures) {
+  check(__dirname, {
+    fixture,
+    migration,
+  });
+}

polaris-migrator/src/migrations/v11-react-update-page-breadcrumbs/v11-react-update-page-breadcrumbs.ts

@@ -0,0 +1,101 @@
+import type {API, FileInfo} from 'jscodeshift';
+
+import {POLARIS_MIGRATOR_COMMENT} from '../../constants';
+import {
+  insertCommentBefore,
+  removeJSXAttributes,
+  replaceJSXAttributes,
+} from '../../utilities/jsx';
+
+export default function v11reactUpdatePageBreadcrumbs(
+  fileInfo: FileInfo,
+  {jscodeshift: j}: API,
+) {
+  const source = j(fileInfo.source);
+
+  source
+    .findJSXElements('Page')
+    .find(j.JSXAttribute, {
+      name: {
+        type: 'JSXIdentifier',
+        name: 'breadcrumbs',
+      },
+      value: {
+        type: 'JSXExpressionContainer',
+      },
+    })
+    .find(j.JSXExpressionContainer)
+    .filter((nodePath) => {
+      if (nodePath.node.expression.type === 'Identifier') {
+        replaceJSXAttributes(
+          j,
+          j(nodePath).closest(j.JSXElement).paths()[0],
+          'breadcrumbs',
+          'backAction',
+        );
+
+        insertCommentBefore(
+          j,
+          j(nodePath).find(j.Identifier).paths()[0],
+          `${POLARIS_MIGRATOR_COMMENT} In this case, you will need to update the breadcrumbs variable to be a single object instead of an array as arrays have been deprecated.`,
+        );
+      }
+
+      if (nodePath.node.expression.type === 'CallExpression') {
+        replaceJSXAttributes(
+          j,
+          j(nodePath).closest(j.JSXElement).paths()[0],
+          'breadcrumbs',
+          'backAction',
+        );
+        insertCommentBefore(
+          j,
+          j(nodePath).find(j.Identifier).paths()[0],
+          `${POLARIS_MIGRATOR_COMMENT} In this case, you will need to update the breadcrumbs variable to be a single object instead of an array as arrays have been deprecated.`,
+        );
+        return false;
+      }
+
+      if (nodePath.node.expression.type === 'ObjectExpression') {
+        replaceJSXAttributes(
+          j,
+          j(nodePath).closest(j.JSXElement).paths()[0],
+          'breadcrumbs',
+          'backAction',
+        );
+      }
+
+      return true;
+    })
+    .find(j.ArrayExpression)
+    .replaceWith((nodePath) => {
+      const arrayOfBreadcrumbs = nodePath.node.elements;
+
+      if (arrayOfBreadcrumbs.length === 0) {
+        removeJSXAttributes(
+          j,
+          nodePath.parentPath.parentPath.parentPath.parentPath,
+          'breadcrumbs',
+        );
+        return;
+      }
+
+      if (
+        arrayOfBreadcrumbs[arrayOfBreadcrumbs.length - 1]?.type !==
+        'ObjectExpression'
+      )
+        return;
+
+      replaceJSXAttributes(
+        j,
+        j(nodePath).closest(j.JSXElement).paths()[0],
+        'breadcrumbs',
+        'backAction',
+      );
+      return j.template.expression`${
+        arrayOfBreadcrumbs[arrayOfBreadcrumbs.length - 1]
+      }`;
+    });
+
+  return source.toSource();
+}