@elliemae/ds-codemods 3.80.0-next.22 → 3.80.0-next.30

package/bin/cli/code-mods/command-logics/legacy-deprecation/AGENTS.md

@@ -27,7 +27,7 @@ registered, separately invocable CLI commands (see `commands.mjs`,
 referenced by name in Confluence pages and recorded walkthroughs, so the command names and their
 CLI-visible behavior must keep working exactly as they did before, indefinitely.
 
-What moved is only *where their implementation lives on disk*: their import maps,
+What moved is only _where their implementation lives on disk_: their import maps,
 `packageJsonReplaceLogic.mjs`, and core logic now live in `26-3/` and `27-1/` in this folder, each
 exposing a `run26dot3MigrationLogic()` / `run27dot1MigrationLogic()` function.
 `execute-commands-map.mjs`'s cases for those two commands call those functions directly - they are
@@ -42,12 +42,20 @@ dedicated command**. Instead:
 1. Add a new subfolder here, named after the dot-release (E.G. `27-3/`).
 2. Give it its own `legacyXXdotYImportMap.mjs` (exact-match capture-group regex, same technique as
    every other one here) and `packageJsonReplaceLogic.mjs`, mirroring `27-2/`'s exact shape - `27-2/`
-   is the reference pattern for a *fully self-contained* subfolder (not a thin wrapper around an
+   is the reference pattern for a _fully self-contained_ subfolder (not a thin wrapper around an
    external, independently-registered command, unlike `26-3/`/`27-1/`).
 3. Expose a `runXXdotYMigrationLogic()` function from an `index.mjs`-equivalent file in that
    subfolder (name it `runXXdotYMigrationLogic.mjs`, matching the existing convention).
 4. Wire it into this folder's `index.mjs`: import it, add its dot-release key to
    `AVAILABLE_MIGRATIONS`, and add its conditional call in `legacyDeprecation()`.
+5. Update the consumer-facing surfaces: the `readme.md` of this package (the `legacy-deprecation`
+   section lists which migrations `all` runs), a migration guide under
+   `stories/docs/confluence-content/migrations/dimsum-3-x/` (plus its entry in `AIndex.md` and export
+   in `index.stories.jsx`), and the release's Go-to-market delta brief under
+   `stories/docs/confluence-content/release-notes/`. Wording rules: see the "Terminology for
+   consumer-facing docs" section below.
+6. Add the moved package to `bin/cli/constants/deprecatedPackages.mjs` so the usage report and the
+   Storybook legacy-usage checker surface it.
 
 No new `commands.mjs` entry, no new `execute-commands-map.mjs` case, no new
 `inquirer-questions-prompter.mjs` case, no new CLI flag - the existing `legacy-deprecation` command
@@ -65,3 +73,39 @@ extra prompt. Pass it as a comma separated string, E.G. `--migrations 26.3,27.1`
 alongside it (E.G. `--migrations 26.3,all`) - this is intentional, not a bug: "all" existing in the
 list at all means "run everything," full stop, so a consumer/CI script that defaults to `all` can't
 be accidentally narrowed by a stray extra pick.
+
+## Terminology for consumer-facing docs (curated by the CTO)
+
+When a package moves to its `-legacy-` counterpart, the docs that consumers read (the release notes'
+Go-to-market delta brief, the migration guide under `stories/docs/confluence-content/migrations/`,
+and this package's `readme.md`) use the CTO-curated wording, chosen to transmit the actual immediate impact in the release:
+
+- **"import only"** - the change consumers make. Running this command is an import-only,
+  development-time change (source imports and `package.json`) with no runtime impact on end users.
+- **"the package moved"** (or "relocated") - what happened to the package. Not "deleted", not
+  "rewritten".
+- **"migration" is reserved for adapting code.** That is why a release's kickoff charter can say
+  "No forced migration" while the brief labels the same item "Breaking": the item is breaking only
+  because the import stops resolving. Do not describe this command's work as "a migration" in consumer
+  docs. The consumer would still get the same behaviour they got up until now. Migration is reserved for having to change,
+  adapt, and modify consumer facing behaviours and developer facing API interfaces.
+- **"Codemod provided"** is the existing way to say the tooling exists (see the 26.3 "Deprecated
+  Components Package Rename" row in `stories/docs/confluence-content/release-notes/v26-3/ReleaseKickoffCharter.md`).
+- Keep it short and factual, in the shape of the neighboring guides in
+  `migrations/dimsum-3-x/` (Rationale, then Migration Steps). The ds-mobile move is the reference:
+  `DsMobileToDsLegacyMobile.md` and the `ds-mobile` section of
+  `release-notes/v27-2/GoToMarketDeltaBrief.md`. Point to those instead of copying their text here.
+
+Evidence rule for "Known differences": list only what a side-by-side run of the live package against the
+legacy build that will actually ship shows (DOM, ARIA, `data-testid`, screenshots). The ds-mobile move used
+the standalone Playwright harness that lives in the dimsum-legacy repo at
+`environments/compare-live-vs-legacy` (its `AGENTS.md` explains the toolchain and how to point the legacy side
+at a `pnpm pack` tarball of the ported package). Do not
+carry a differences list forward from an earlier state of the legacy code.
+
+Placement constraint: a guide that shows `from '<old package>'` samples must live under `migrations/`,
+`release-notes/` or `a11y-rationale/`, because `checkLegacyCodeUsage.mjs` (run in `build-storybook`)
+fails on any other scanned file that imports the moved package.
+
+This file's own history section still says "mechanical rename". That is internal wording and can stay;
+the terms above apply to what consumers read.

package/bin/cli/constants/deprecatedPackages.mjs

@@ -710,10 +710,11 @@ export const DISMISSED_BEFORE_DEPRECATION_FLOWS_EXISTED = [
 /**
  * for packages we are not actively investing in and have no committed replacement (unlike
  * LEGACY_WITH_NEW_*_MIGRATION_EFFORT) and that are not being "removed in favor of examples" either
- * (unlike DISMISSED_WITH_EXAMPLE) - we still have no known active consumers, so there is nothing to
- * migrate anyone to yet. If/when a real consumer shows up asking "what do I use instead", that becomes
- * an ad-hoc, case-by-case discussion (potentially a dedicated effort for the specific components they
- * need) rather than a pre-baked migration path here.
+ * (unlike DISMISSED_WITH_EXAMPLE). A mechanical rename to the `-legacy-` package may exist (E.G.
+ * `legacy-deprecation --migrations 27.2` for @elliemae/ds-mobile), but there is no live replacement to
+ * migrate to, so the effort of leaving the legacy package stays case-by-case: if/when a real consumer
+ * shows up asking "what do I use instead", that becomes an ad-hoc discussion (potentially a dedicated
+ * effort for the specific components they need) rather than a pre-baked migration path here.
  * @type {DeprecatedPackageMatch[]}
  */
 /* prettier-ignore */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-codemods",
-  "version": "3.80.0-next.22",
+  "version": "3.80.0-next.30",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Code Mods",
   "files": [

package/readme.md

@@ -372,3 +372,63 @@ npx @elliemae/ds-codemods components-usage-report
 ```
 npx @elliemae/ds-codemods components-usage-report --append --org='ICE' --repo='Dimsum'
 ```
+
+## Moving Packages to their `-legacy-` Counterpart (`legacy-deprecation`)
+
+Some packages were pulled out of live's normal publish set and only remain available through their `-legacy-` prefixed package. This script does the import-only change for them: it rewrites the `from '<package>'` imports/exports in the scanned files and swaps the entries in the `dependencies`, `devDependencies` and `peerDependencies` of every `package.json` (version set to `"*"`).
+
+It bundles three dot-release migrations:
+
+- `26.3`: `@elliemae/ds-button` -> `@elliemae/ds-legacy-button`, `@elliemae/ds-date-range-picker` -> `@elliemae/ds-legacy-date-range-picker`, `@elliemae/ds-header` -> `@elliemae/ds-legacy-header`, `@elliemae/ds-number-range-field` -> `@elliemae/ds-legacy-number-range-field`, `@elliemae/ds-slider` -> `@elliemae/ds-legacy-slider`, `@elliemae/ds-zipcode-search` -> `@elliemae/ds-legacy-zipcode-search`, `@elliemae/ds-button-group` -> `@elliemae/ds-legacy-button-group`, `@elliemae/ds-date-range-selector` -> `@elliemae/ds-legacy-date-range-selector`, `@elliemae/ds-hidden` -> `@elliemae/ds-legacy-hidden`, `@elliemae/ds-page-number` -> `@elliemae/ds-legacy-page-number`, `@elliemae/ds-spinner` -> `@elliemae/ds-legacy-spinner`, `@elliemae/ds-zoom` -> `@elliemae/ds-legacy-zoom`, `@elliemae/ds-button-v1` -> `@elliemae/ds-legacy-button-v1`, `@elliemae/ds-date-time-recurrence-picker` -> `@elliemae/ds-legacy-date-time-recurrence-picker`, `@elliemae/ds-label-value` -> `@elliemae/ds-legacy-label-value`, `@elliemae/ds-pills` -> `@elliemae/ds-legacy-pills`, `@elliemae/ds-text-wrapper` -> `@elliemae/ds-legacy-text-wrapper`, `@elliemae/ds-card-array` -> `@elliemae/ds-legacy-card-array`, `@elliemae/ds-dropdownmenu` -> `@elliemae/ds-legacy-dropdownmenu`, `@elliemae/ds-list-section-header` -> `@elliemae/ds-legacy-list-section-header`, `@elliemae/ds-popover` -> `@elliemae/ds-legacy-popover`, `@elliemae/ds-time-picker` -> `@elliemae/ds-legacy-time-picker`, `@elliemae/ds-common` -> `@elliemae/ds-legacy-common`, `@elliemae/ds-filterbar` -> `@elliemae/ds-legacy-filterbar`, `@elliemae/ds-menu` -> `@elliemae/ds-legacy-menu`, `@elliemae/ds-popper` -> `@elliemae/ds-legacy-popper`, `@elliemae/ds-toolbar` -> `@elliemae/ds-legacy-toolbar`, `@elliemae/ds-datagrids` -> `@elliemae/ds-legacy-datagrids`, `@elliemae/ds-form` -> `@elliemae/ds-legacy-form`, `@elliemae/ds-mini-toolbar` -> `@elliemae/ds-legacy-mini-toolbar`, `@elliemae/ds-search-field` -> `@elliemae/ds-legacy-search-field`, `@elliemae/ds-uploader` -> `@elliemae/ds-legacy-uploader`, `@elliemae/ds-date-picker` -> `@elliemae/ds-legacy-date-picker`, `@elliemae/ds-group-box` -> `@elliemae/ds-legacy-group-box`, `@elliemae/ds-modal` -> `@elliemae/ds-legacy-modal`, `@elliemae/ds-shuttle` -> `@elliemae/ds-legacy-shuttle`, `@elliemae/ds-wysiwygeditor` -> `@elliemae/ds-legacy-wysiwygeditor`.
+- `27.1`: `@elliemae/ds-truncated-tooltip-text` -> `@elliemae/ds-legacy-truncated-tooltip-text`.
+- `27.2`: `@elliemae/ds-mobile` -> `@elliemae/ds-legacy-mobile`.
+
+`all` (the default) runs all of them; pass `--migrations 27.2` to run only one.
+
+This is an import-only, development-time change (source imports and `package.json`) with no runtime impact on end users. The legacy package is the live source on `@elliemae/ds-legacy-*` dependencies: all 85 exports are present and DOM, ARIA and `data-testid` values match except where a legacy dependency renders differently (accordion header element, tabs swipe-card layer, `aria-disabled="false"` on legacy buttons, multi-select checkbox and infinite-loader test ids); the slot system (`data-dimsum-slot`) is not present in the legacy package. Read the [`@elliemae/ds-mobile` -> `@elliemae/ds-legacy-mobile` migration guide](/?path=/story/resources-migrations-dimsum3-x--ds-mobile-to-ds-legacy-mobile) for the details.
+
+What it does NOT rewrite: `require(...)`, dynamic `import(...)`, side-effect `import '<package>'`, `jest.mock(...)`/`jest.requireActual(...)`, TS `import('<package>')` types, bundler alias/externals config, `.md`/`.mdx`/`.cjs`/`.mts`/`.cts` files, `package.json` `optionalDependencies`/`resolutions`/`overrides`/`pnpm.overrides`, `tsconfig` `paths` and lockfiles (run `pnpm i --fix-lockfile` afterwards). Do not run it inside a workspace where the package is a `workspace:*` dependency.
+
+### Command
+
+`npx @elliemae/ds-codemods legacy-deprecation`
+
+### Arguments
+
+- `startingDirPath`
+
+Please provide the project root directory (where node_modules folder lives), relative to the current working directory
+
+default: `'./'`
+
+- `gitIgnorePath`
+
+Please provide the path to the .gitignore file (if a non-matching path is provided, node_modules, dist and build will be ignored)
+
+default: `'./.gitignore'`
+
+- `migrations` (CLI Only)
+
+A comma separated list of the migrations to run, E.G. `27.2`. Never prompted for. `all` (the default) always wins, even if specific migrations are passed alongside it.
+
+default: `'all'`
+
+- `debug` (CLI Only)
+
+Log the changes that would be made without writing any file
+
+default: `false`
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods legacy-deprecation --migrations 27.2 --startingDirPath='./' --gitIgnorePath='./.gitignore'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods legacy-deprecation
+```