@elliemae/ds-codemods 3.31.4 → 3.32.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-codemods",
-  "version": "3.31.4",
+  "version": "3.32.0-rc.2",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Code Mods",
   "files": [

package/readme.md

@@ -0,0 +1,374 @@
+# `ds-codemods` API Documentation (up to version 3.31.X)
+
+## Migrating from `<1.37.X` to `>1.37.X`
+
+This scripts will recursively check the files matching the `globPattern` and using an opinionated substitution map will "search and replace" some legacy imports
+
+This was created for adressing dimsum 1.37.X legacy way of improting components and is only addressing the specific substitution map for moving from `< 1.37.X` to `> 1.37.X`
+
+### Command
+
+`npx @elliemae/ds-codemods fix-legacy-imports`
+
+### Arguments
+
+- `globPattern`
+
+A comma separated list of globPatterns catching the file in which to fix the imports
+
+default: `'./**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx'`
+
+- `globPatternIgnore`
+
+A comma separated list of ignored files that are matched by the globPattern and should not be "fixed"
+
+default: `'**/node_modules/**/*'`
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods fix-legacy-imports --globPattern='./**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx' --globPatternIgnore='**/node_modules/**/*'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods fix-legacy-imports
+```
+
+## Reverting `>1.37.X` Migration
+
+This scripts will recursively check the files matching the `globPattern` and using an opinionated substitution map will undo the changes from the `fix-legacy-imports`.
+
+This was created "for good measure" and "just in case", but in a `git` based project it would be much better to just undo pending changes if possible.
+
+### Command
+
+`npx @elliemae/ds-codemods fix-legacy-imports:revert`
+
+### Arguments
+
+- Same as migrating from `<1.37.X` to `>1.37.X`.
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods fix-legacy-imports:revert --globPattern='./**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx' --globPatternIgnore='**/node_modules/**/*'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods fix-legacy-imports:revert
+```
+
+## Deprecated Components Check (Dismissed)
+
+Based on the execution of `npm ls` command, analyse the output vs "deprecated dimsum packages",
+
+Executing this script will result in a `markdown` compliant log in the terminal of the currently found deprecated components
+
+This script is somewhate not mantained and is instead substituted by the much more powerful `deprecated-components-usage-report` script, information from this scripts WILL be partial
+
+### Command
+
+`npx @elliemae/ds-codemods check-deprecated-packages`
+
+### Arguments
+
+- `cwd`
+
+The project root directory (where node_modules folder lives)
+
+default: `'./'`
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods check-deprecated-packages --cwd='./'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods check-deprecated-packages
+```
+
+## Ensuring `package.json` Compliance
+
+A script meant to be used to ensure the dependencies listed in a given `package.json` file matches the `dimsum`'s versioning assumption to be considered "healthy"
+
+The assumption are
+
+- all the `@elliemae/ds-*` packages MUST point to the same version
+- the "pointed" version should be within 6 `minor` version from highest release
+
+uses third-party `pacote` to detect latest publish version.
+
+### Command
+
+`npx @elliemae/ds-codemods check-packages-inconsistencies`
+
+### Arguments
+
+- `globPattern`
+
+A comma separated list of globPatterns catching the file in which to fix the imports
+
+default: `'./package.json'`
+
+- `globPatternIgnore`
+
+A comma separated list of ignored files that are matched by the globPattern and should not be "fixed"
+
+default: `'**/node_modules/**/*'`
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods check-packages-inconsistencies --globPattern='./package.json' --globPatternIgnore='**/node_modules/**/*'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods check-packages-inconsistencies
+```
+
+## Missing Dependencies Detection
+
+A script that using the third-party package `pacote` checks if the project `package.json` is not correctly depending on the "expected" packages.
+
+This is a simple overloaded way to invoke pacote, so it's affected 1-1 with any limitation/problem the `pacote` package may have.
+
+### Command
+
+`npx @elliemae/ds-codemods check-missing-packages`
+
+### Arguments
+
+- `projectFolderPath`
+
+path to the project folder containing the package.json file
+
+default: `'./'`
+
+- `ignorePackagesGlobPattern`
+
+A comma separated list of "false positive" packages to be passed to pacote, if any.
+
+default: `''`
+
+- `ignoreFilesGlobPattern`
+
+A comma separated list of globPatterns for ignored files, if any.
+
+default: `'**/*.eslintrc.js'`
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods check-missing-packages --projectFolderPath='./' --ignorePackagesGlobPattern='' --ignoreFilesGlobPattern='**/*.eslintrc.js'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods check-missing-packages
+```
+
+## Migrating from `<3.X.X` to `>3.X.X`
+
+similar to `fix-legacy-imports` this script was created to facilitate projects transition from `dimsum < 3.x.x` to `> 3.x.x`.
+
+This mainly search for imports from `@elliema/ds-basic/{something}` and switch the ESM module import syntax to the one that dimsum `3.x.x` requires ( which is usually pointing to the specific dedicated package, instead of the aggregated ds-basic package which in dimsum 3.x.x dropped all the components exports )
+
+### Command
+
+`npx @elliemae/ds-codemods help-migrate-to-v3`
+
+### Arguments
+
+- `globPattern`
+
+A comma separated list of globPatterns catching the file in which to fix the imports
+
+default: `'./**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx'`
+
+- `globPatternIgnore`
+
+A comma separated list of ignored files that are matched by the globPattern and should not be "fixed"
+
+default: `'**/node_modules/**/*'`
+
+### Usage
+
+- **CLI**
+
+```
+  npx @elliemae/ds-codemods help-migrate-to-v3 --globPattern='./**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx' --globPatternIgnore='**/node_modules/**/*'
+```
+
+- **Guided CLI**
+
+```
+  npx @elliemae/ds-codemods help-migrate-to-v3
+```
+
+## Generating Reports on Deprecated Component Usage
+
+The latest script attempting to tackle "housekeeping" with the dimsum deprecated packages,
+
+Will create a file in the `outputPath` that will contain a report in a `csv` format,
+The file that will be checked for will depend on sensible defaults and the opinionated sensible default is making use of `gitIgnore` if present, scan all js/ts jsx/tsx files.
+
+This is manually mantained some minor miss-aligment MAY happen, but dimsum teams tries it's best to keep this up to date.
+
+### Command
+
+`npx @elliemae/ds-codemods deprecated-components-usage-report`
+
+### Arguments
+
+- `outputPath`
+
+path to the .csv file to write the report to
+
+default: `'./dimsum-deprecated-components-usage-report.csv'`
+
+- `startingDirPath`
+
+Please provide the project root directory (where node_modules folder lives)
+
+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'`
+
+- `debug` (CLI Only)
+
+A flag to display some debugging information in case an execution bug arises
+
+default: `false`
+
+- `append` (CLI Only)
+
+A flag to specify that if the `outputPath` csv already exists, the script should try to append the `csv` rows to that file instead of overwriting the content
+
+default: `false`
+
+- `org` (CLI Only)
+
+A `string` that when provided will add a dedicated column to the csv report. Mainly used to be able to analyze multiple code-base and being able to recognize them in the report
+
+default: `undefined`
+
+- `repo` (CLI Only)
+
+A `string` that when provided will add a dedicated column to the csv report. Mainly used to be able to analyze multiple code-base and being able to recognize them in the report
+
+default: `undefined`
+
+### Usage
+
+- **CLI:**
+
+```
+  npx @elliemae/ds-codemods deprecated-components-usage-report --outputPath='./dimsum-deprecated-components-usage-report.csv' --startingDirPath='./' --gitIgnorePath='./.gitignore' --debug --append --org='ICE' --repo='Dimsum'
+```
+
+- **Guided CLI:**
+
+```
+npx @elliemae/ds-codemods deprecated-components-usage-report
+```
+
+```
+npx @elliemae/ds-codemods deprecated-components-usage-report --append --org='ICE' --repo='Dimsum'
+```
+
+## Generating `.CSV` Reports on Component Usage
+
+A script that will create a `csv` report as per defined in the output path and will fill it with a detailed report of every istance of ESM `import` statement that involves a `@elliemae/ds-*` package
+
+This report also reports wheter "default" imports, "named import with alias" or "global import" pattern has been used.
+`Dimsum` strongly suggest and kind-of would like t
+
+### Command
+
+`npx @elliemae/ds-codemods components-usage-report`
+
+### Arguments
+
+- `outputPath`
+
+path to the .csv file to write the report to
+
+default: `'./dimsum-components-usage-report.csv'`
+
+- `startingDirPath`
+
+Please provide the project root directory (where node_modules folder lives)
+
+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'`
+
+- `debug` (CLI Only)
+
+A flag to display some debugging information in case an execution bug arises
+
+default: `false`
+
+- `append` (CLI Only)
+
+A flag to specify that if the `outputPath` csv already exists, the script should try to append the `csv` rows to that file instead of overwriting the content
+
+default: `false`
+
+- `org` (CLI Only)
+
+A `string` that when provided will add a dedicated column to the csv report. Mainly used to be able to analyze multiple code-base and being able to recognize them in the report
+
+default: `undefined`
+
+- `repo` (CLI Only)
+
+A `string` that when provided will add a dedicated column to the csv report. Mainly used to be able to analyze multiple code-base and being able to recognize them in the report
+
+default: `undefined`
+
+### Usage
+
+- **CLI:**
+
+```
+  npx @elliemae/ds-codemods components-usage-report --outputPath='./dimsum-components-usage-report.csv' --startingDirPath='./' --gitIgnorePath='./.gitignore' --debug --append --org='ICE' --repo='Dimsum'
+```
+
+- **Guided CLI:**
+
+```
+npx @elliemae/ds-codemods components-usage-report
+```
+
+```
+npx @elliemae/ds-codemods components-usage-report --append --org='ICE' --repo='Dimsum'
+```