feat(gamut)!: promote deep imports to the root, renaming Menu and SelectDropdown elements

.changeset/gamut-codemods-deep-imports.md

@@ -0,0 +1,5 @@
+---
+'@skillsoft/gamut-codemods': minor
+---
+
+`scope-swap` now rewrites `/dist/` deep imports that have a public replacement to the package root, and merges them into an existing import from the same package. Renamed exports keep their local name, so `import { List } from '@codecademy/gamut/dist/Menu/elements'` becomes `import { MenuList as List } from '@skillsoft/gamut'`. Imports of names that stayed internal, deep imports with no public replacement (`ButtonBase`), unknown deep imports, and deep paths in mocks or `require()` get a warning.

.changeset/gamut-codemods-scope-swap.md

@@ -0,0 +1,5 @@
+---
+'@skillsoft/gamut-codemods': minor
+---
+
+Add `@skillsoft/gamut-codemods`, a CLI for moving a repo from `@codecademy/gamut*` to `@skillsoft/gamut*`. Run `npx @skillsoft/gamut-codemods scope-swap .` from a clean working tree. This release adds the runner and the `scope-swap` preset with no migrations yet: a run lists every line that still names an old package and prints next steps. Pass `--dry` to preview, `--only=a,b` to pick migrations, and `--no-report` to skip the leftovers list.

.changeset/gamut-root-exports.md

@@ -0,0 +1,22 @@
+---
+'@skillsoft/gamut': minor
+---
+
+**Breaking:** export Menu's list elements and SelectDropdown's option component from the package root, under new names that don't collide with the public `List` component and `IconOption` type.
+
+| Old (`dist/Menu/elements`, `dist/Form/SelectDropdown/elements`) | New (`@skillsoft/gamut`)            |
+| --------------------------------------------------------------- | ----------------------------------- |
+| `List`, `ListProps`                                             | `MenuList`, `MenuListProps`         |
+| `ListItem`, `ListItemProps`                                     | `MenuListItem`, `MenuListItemProps` |
+| `ListLink`, `ListLinkProps`                                     | `MenuListLink`, `MenuListLinkProps` |
+| `ListButton`                                                    | `MenuListButton`                    |
+| `IconOption` (the component)                                    | `IconOptionComponent`               |
+
+`MenuToolTipWrapper` is now exported from the root too. The `IconOption` type is unchanged.
+
+Also new at the root:
+
+- `formFieldStyles`, `formFieldPaddingStyles`, and `conditionalStyles`, for custom inputs that should look like `Input`, such as third-party hosted payment fields. The rest of `Form/styles` stays internal.
+- The `HTMLToReactNode` and `ButtonBaseProps` types.
+
+Coming from `@codecademy/gamut`, `npx @skillsoft/gamut-codemods scope-swap .` rewrites imports of all of these, including from their old `/dist/` paths.

packages/gamut-codemods/README.md

@@ -56,6 +56,7 @@ Every skillsoft-gamut pull request publishes installable previews through pkg.pr
 
 | Migration                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `deep-imports`             | `@codecademy/gamut/dist/PopoverContainer/types` → `@codecademy/gamut`, and the rest of the promoted deep imports. Menu's `List*` and SelectDropdown's `IconOption` component were renamed on the way to the root.                                                                                                                                                                                                                                                                                                                          |
 | `moved-exports`            | Moves `Video` and `VideoProps` off the root import onto `/Video`. Warns on namespace imports, `export *`, and mocks that stub `Video`.                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `markdown-video-overrides` | Markdown no longer renders `<iframe>` and `<video>` through `Video` by default. Adds `iframeOverride` / `videoOverride` to each `<Markdown>` that didn't skip them, importing `Iframe` and `MarkdownVideo` from `/Video`. Drops the removed `skipDefaultOverrides.iframe` / `.video` keys, writing `iframeOverride={undefined}` where they were `true`. Warns on a `skipDefaultOverrides` it can't read. Skipped when every `@codecademy/gamut` range in the repo is already 74.0.0 or newer, since that release made the change upstream. |
 | `mf-shared`                | Replaces `@codecademy/gamut-kit` in Module Federation `shared` config with the packages it bundled. Gamut becomes a real singleton, so test the host and remotes together.                                                                                                                                                                                                                                                                                                                                                                 |

packages/gamut-codemods/src/__tests__/__testfixtures__/end-to-end-deep-imports.input.tsx

@@ -0,0 +1,5 @@
+import { Box } from '@codecademy/gamut';
+import { PopoverContainerProps } from '@codecademy/gamut/dist/PopoverContainer/types';
+import { List } from '@codecademy/gamut/dist/Menu/elements';
+
+export const Thing = (p: PopoverContainerProps) => <Box><List /></Box>;

packages/gamut-codemods/src/__tests__/__testfixtures__/end-to-end-deep-imports.output.tsx

@@ -0,0 +1,3 @@
+import { Box, PopoverContainerProps, MenuList as List } from '@skillsoft/gamut';
+
+export const Thing = (p: PopoverContainerProps) => <Box><List /></Box>;

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/export-namespace.input.tsx

@@ -0,0 +1 @@
+export * as Menu from '@codecademy/gamut/dist/Menu/elements';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/export-namespace.output.tsx

@@ -0,0 +1 @@
+export * as Menu from '@codecademy/gamut';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/export-unrenamed.input.tsx

@@ -0,0 +1 @@
+export { MenuIcon, ListItem } from '@codecademy/gamut/dist/Menu/elements';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/export-unrenamed.output.tsx

@@ -0,0 +1 @@
+export { MenuIcon, MenuListItem as ListItem } from '@codecademy/gamut';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/form-styles.input.tsx

@@ -0,0 +1,4 @@
+import { conditionalStyles, formFieldStyles } from '@codecademy/gamut/dist/Form/styles';
+import { formFieldPaddingStyles as padding } from '@codecademy/gamut/dist/Form/styles';
+import { formFieldStyles as f, checkboxLabel } from '@codecademy/gamut/dist/Form/styles';
+import * as formStyles from '@codecademy/gamut/dist/Form/styles';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/form-styles.output.tsx

@@ -0,0 +1,3 @@
+import { conditionalStyles, formFieldStyles, formFieldPaddingStyles as padding } from '@codecademy/gamut';
+import { formFieldStyles as f, checkboxLabel } from '@codecademy/gamut/dist/Form/styles';
+import * as formStyles from '@codecademy/gamut/dist/Form/styles';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/form-styles.warnings.json

@@ -0,0 +1 @@
+["checkboxLabel isn't exported from '@codecademy/gamut'", "* isn't exported from '@codecademy/gamut'"]

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/merge.input.tsx

@@ -0,0 +1,8 @@
+import { Box, FlexBox, List, Text } from '@codecademy/gamut';
+import { ListItem } from '@codecademy/gamut/dist/Menu/elements';
+import type { BoxProps } from '@codecademy/gamut';
+import type { PopoverContainerProps } from '@codecademy/gamut/dist/PopoverContainer/types';
+import { Box as Again } from '@codecademy/gamut/dist/Box/props';
+import * as Gamut from '@codecademy/gamut';
+import { variance } from '@codecademy/variance';
+import { Prop } from '@codecademy/variance/dist/types/config';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/merge.output.tsx

@@ -0,0 +1,5 @@
+import { Box, FlexBox, List, Text, MenuListItem as ListItem } from '@codecademy/gamut';
+import type { BoxProps, PopoverContainerProps } from '@codecademy/gamut';
+import { Box as Again } from '@codecademy/gamut/dist/Box/props';
+import * as Gamut from '@codecademy/gamut';
+import { variance, Prop } from '@codecademy/variance';

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/merge.warnings.json

@@ -0,0 +1 @@
+["is only partly public", "Box is already imported from '@skillsoft/gamut'"]

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/mocks-unmapped.input.tsx

@@ -0,0 +1,5 @@
+import { Box } from '@codecademy/gamut/dist/Box';
+
+jest.mock('@codecademy/gamut/dist/Nope/thing', () => ({}));
+const button = require('@codecademy/gamut/dist/ButtonBase/ButtonBase');
+export const B = [Box, button];

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/mocks-unmapped.output.tsx

@@ -0,0 +1,5 @@
+import { Box } from '@codecademy/gamut/dist/Box';
+
+jest.mock('@codecademy/gamut/dist/Nope/thing', () => ({}));
+const button = require('@codecademy/gamut/dist/ButtonBase/ButtonBase');
+export const B = [Box, button];

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/mocks-unmapped.warnings.json

@@ -0,0 +1,4 @@
+[
+  "'@codecademy/gamut/dist/Nope/thing' in a mock or require() needs a manual rewrite",
+  "'@codecademy/gamut/dist/ButtonBase/ButtonBase' in a mock or require() needs a manual rewrite"
+]

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/renames.input.tsx

@@ -0,0 +1,6 @@
+import { List, ListItem as Item, type ListProps } from '@codecademy/gamut/dist/Menu/elements';
+import { IconOption } from '@codecademy/gamut/dist/Form/SelectDropdown/elements';
+
+export { ListButton } from '@codecademy/gamut/dist/Menu/elements';
+
+jest.mock('@codecademy/gamut/dist/Menu/elements', () => ({ List: () => null }));

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/renames.output.tsx

@@ -0,0 +1,10 @@
+import {
+  MenuList as List,
+  MenuListItem as Item,
+  type MenuListProps as ListProps,
+  IconOptionComponent as IconOption,
+} from '@codecademy/gamut';
+
+export { MenuListButton as ListButton } from '@codecademy/gamut';
+
+jest.mock('@codecademy/gamut', () => ({ List: () => null }));

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/renames.warnings.json

@@ -0,0 +1 @@
+["That now covers the whole package, and some exports were renamed. Check it by hand."]

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/rewrites.input.tsx

@@ -0,0 +1,7 @@
+import { PopoverContainerProps } from '@codecademy/gamut/dist/PopoverContainer/types';
+import type { Prop } from '@codecademy/variance/dist/types/config';
+import { formStyles } from '@codecademy/gamut/dist/Form/styles';
+import { ButtonBase } from '@codecademy/gamut/dist/ButtonBase/ButtonBase';
+import { Mystery } from '@codecademy/gamut/dist/Nope';
+
+jest.mock('@codecademy/gamut/dist/Box/props');

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/rewrites.output.tsx

@@ -0,0 +1,7 @@
+import { PopoverContainerProps } from '@codecademy/gamut';
+import type { Prop } from '@codecademy/variance';
+import { formStyles } from '@codecademy/gamut/dist/Form/styles';
+import { ButtonBase } from '@codecademy/gamut/dist/ButtonBase/ButtonBase';
+import { Mystery } from '@codecademy/gamut/dist/Nope';
+
+jest.mock('@codecademy/gamut');

packages/gamut-codemods/src/migrations/deep-imports/__testfixtures__/rewrites.warnings.json

@@ -0,0 +1 @@
+["'@codecademy/gamut/dist/Form/styles' is only partly public. formStyles isn't exported from '@codecademy/gamut'", "'@codecademy/gamut/dist/ButtonBase/ButtonBase' has no public replacement", "unmapped deep import '@codecademy/gamut/dist/Nope'", "rewrote '@codecademy/gamut/dist/Box/props' to '@codecademy/gamut' in a mock or require(). That now covers the whole package."]

packages/gamut-codemods/src/migrations/deep-imports/index.ts

@@ -0,0 +1,253 @@
+import type {
+  Collection,
+  ExportSpecifier,
+  ImportDeclaration,
+  ImportSpecifier,
+  JSCodeshift,
+} from 'jscodeshift';
+
+import { renameSpecifier } from '../../lib/manifest';
+import { findModuleStrings, nameOf } from '../../lib/module-strings';
+import type { AstMigration } from '../../lib/types';
+
+/*
+  `@codecademy/gamut/dist/...` -> the public entry point from
+  manifest.deepImports. Renamed exports keep their local name so call sites
+  don't change: `import { List }` becomes `import { MenuList as List }`.
+*/
+
+const DIST = /^(@codecademy\/[\w-]+|eslint-plugin-gamut)\/dist(\/|$)/;
+
+type Specifier = ImportSpecifier | ExportSpecifier | { type: string };
+
+/*
+  Specifiers are rebuilt rather than mutated. `import { List }` has imported
+  and local sharing one source range, so recast's patcher drops the alias if
+  you only swap `imported`.
+*/
+const renameSpecifiers = (
+  j: JSCodeshift,
+  specifiers: Specifier[],
+  renames: Record<string, string>
+) =>
+  specifiers.map((spec) => {
+    if (spec.type === 'ImportSpecifier') {
+      const { imported, local, importKind } = spec as ImportSpecifier & {
+        importKind?: string;
+      };
+      const next = renames[nameOf(imported)];
+      if (!next) return spec;
+      const renamed = j.importSpecifier(
+        j.identifier(next),
+        j.identifier(nameOf(local ?? imported))
+      );
+      Object.assign(renamed, { importKind });
+      return renamed;
+    }
+    if (spec.type === 'ExportSpecifier') {
+      const { local, exported } = spec as ExportSpecifier;
+      const next = renames[nameOf(local)];
+      if (!next) return spec;
+      return j.exportSpecifier.from({
+        local: j.identifier(next),
+        exported: j.identifier(nameOf(exported ?? local)),
+      });
+    }
+    return spec;
+  });
+
+/* Only plain `{ a, b as c }` imports can be merged; defaults and `* as` can't. */
+const namedOnly = (node: ImportDeclaration) =>
+  (node.specifiers ?? []).every((spec) => spec.type === 'ImportSpecifier');
+
+/* Names the file already imports by name from `source`. */
+const importedNamesFrom = (root: Collection, j: JSCodeshift, source: string) =>
+  new Set(
+    root
+      .find(j.ImportDeclaration)
+      .nodes()
+      .filter((node) => node.source.value === source)
+      .flatMap((node) =>
+        (node.specifiers ?? [])
+          .filter(
+            (spec): spec is ImportSpecifier => spec.type === 'ImportSpecifier'
+          )
+          .map((spec) => nameOf(spec.imported))
+      )
+  );
+
+const mergeKey = (node: ImportDeclaration) =>
+  `${String(node.source.value)}\0${node.importKind ?? 'value'}`;
+
+type NamedSpecifier = ImportSpecifier & { importKind?: string };
+
+const specifierKey = (spec: NamedSpecifier) =>
+  `${spec.importKind ?? 'value'} ${nameOf(spec.imported)} ${nameOf(
+    spec.local ?? spec.imported
+  )}`;
+
+/*
+  A rewritten deep import often lands on a package the file already
+  imports from, and two declarations from one source trip
+  import/no-duplicates. Fold each rewritten declaration into the first
+  plain named import of the same source and kind. Declarations the file
+  already had are never merged with each other.
+*/
+const mergeRewritten = (
+  j: JSCodeshift,
+  root: Collection,
+  rewritten: Set<unknown>
+) => {
+  const targets = new Map<string, ImportDeclaration>();
+  root.find(j.ImportDeclaration).forEach((p) => {
+    const { node } = p;
+    if (!namedOnly(node)) return;
+    const key = mergeKey(node);
+    const target = targets.get(key);
+    if (!target) {
+      targets.set(key, node);
+      return;
+    }
+    if (!rewritten.has(node)) return;
+
+    const existing = new Set(
+      (target.specifiers as NamedSpecifier[]).map(specifierKey)
+    );
+    /* Clone into the target; recast's patcher can crash on moved nodes. */
+    const moved = (node.specifiers as NamedSpecifier[])
+      .filter((spec) => !existing.has(specifierKey(spec)))
+      .map((spec) =>
+        Object.assign(
+          j.importSpecifier(
+            j.identifier(nameOf(spec.imported)),
+            j.identifier(nameOf(spec.local ?? spec.imported))
+          ),
+          { importKind: spec.importKind }
+        )
+      );
+    target.specifiers = [...(target.specifiers ?? []), ...moved];
+    j(p).remove();
+  });
+};
+
+export const deepImports: AstMigration = {
+  name: 'deep-imports',
+  kind: 'ast',
+  description: 'Rewrite /dist/ deep imports to public entry points.',
+  run({ j, root, manifest, warn }) {
+    const byPath = new Map(manifest.deepImports.map((row) => [row.from, row]));
+    let changed = false;
+
+    /* Declarations first, so renames can be applied to their specifiers. */
+    const declarations = [
+      ...root.find(j.ImportDeclaration).nodes(),
+      ...root.find(j.ExportNamedDeclaration).nodes(),
+      ...root.find(j.ExportAllDeclaration).nodes(),
+    ];
+    const handled = new Set<unknown>();
+    const rewritten = new Set<unknown>();
+
+    for (const node of declarations) {
+      const source = node.source as { value?: unknown } | null | undefined;
+      if (typeof source?.value !== 'string' || !DIST.test(source.value)) {
+        continue;
+      }
+      handled.add(source);
+      const row = byPath.get(source.value);
+      if (!row) {
+        warn(
+          node,
+          `unmapped deep import '${source.value}'. Add it to the preset manifest's deepImports.`
+        );
+        continue;
+      }
+      if (!row.to) {
+        warn(
+          node,
+          `'${row.from}' has no public replacement. ${row.note ?? ''}`
+        );
+        continue;
+      }
+      if (row.onlyNames) {
+        const allowed = new Set(row.onlyNames);
+        const specifiers =
+          'specifiers' in node ? ((node.specifiers ?? []) as Specifier[]) : [];
+        const blocked = specifiers
+          .map((spec) =>
+            spec.type === 'ImportSpecifier'
+              ? nameOf((spec as ImportSpecifier).imported)
+              : spec.type === 'ExportSpecifier'
+              ? nameOf((spec as ExportSpecifier).local)
+              : '*'
+          )
+          .filter((name) => !allowed.has(name));
+        if (node.type === 'ExportAllDeclaration') blocked.push('*');
+        if (blocked.length > 0) {
+          warn(
+            node,
+            `'${row.from}' is only partly public. ${blocked.join(
+              ', '
+            )} isn't exported from '${row.to}'. ${row.note ?? ''}`
+          );
+          /* Usually a name the file already imports from the public entry. */
+          const alreadyImported = importedNamesFrom(root, j, row.to);
+          const duplicates = blocked.filter((name) =>
+            alreadyImported.has(name)
+          );
+          /* Warn with the names the run leaves behind, not the old scope. */
+          const after = (value: string) =>
+            renameSpecifier(manifest, value) ?? value;
+          if (duplicates.length > 0) {
+            warn(
+              node,
+              `${duplicates.join(', ')} is already imported from '${after(
+                row.to
+              )}' in this file, so this import duplicates it. Drop the '${after(
+                row.from
+              )}' import and use the '${after(row.to)}' one.`
+            );
+          }
+          continue;
+        }
+      }
+      if (row.renames && 'specifiers' in node && node.specifiers) {
+        node.specifiers = renameSpecifiers(
+          j,
+          node.specifiers,
+          row.renames
+        ) as typeof node.specifiers;
+      }
+      node.source = j.stringLiteral(row.to);
+      if (node.type === 'ImportDeclaration') rewritten.add(node);
+      changed = true;
+    }
+
+    if (rewritten.size > 0) mergeRewritten(j, root, rewritten);
+
+    /* Then mocks, require(), import(): only the string can change here. */
+    for (const literal of findModuleStrings(j, root)) {
+      if (handled.has(literal) || !DIST.test(literal.value)) continue;
+      const row = byPath.get(literal.value);
+      if (!row?.to) {
+        warn(
+          literal,
+          `deep import '${literal.value}' in a mock or require() needs a manual rewrite.`
+        );
+        continue;
+      }
+      /* jest.mock of a deep path now mocks the whole package. */
+      warn(
+        literal,
+        `rewrote '${literal.value}' to '${
+          row.to
+        }' in a mock or require(). That now covers the whole package${
+          row.renames ? ', and some exports were renamed' : ''
+        }. Check it by hand.`
+      );
+      literal.value = row.to;
+      changed = true;
+    }
+
+    return changed;
+  },
+};