@elliemae/ds-codemods 3.26.0-next.5 → 3.26.0-next.7

package/bin/cli/code-mods/cli.mjs

@@ -11,6 +11,14 @@ function parseArgumentsIntoOptions(rawArgs) {
       '--projectFolderPath': String,
       '--ignorePackagesGlobPattern': String,
       '--ignoreFilesGlobPattern': String,
+      '--outputPath': String,
+      '--startingDirPath': String,
+      '--gitIgnorePath': String,
+      // CLI flag, not available as a question -> Boolean are not supported by the combo of arg and (dynamic) inquirer.
+      // it's impossible to determine if the user has passed the flag or not because
+      //  for arg Boolean are either true or undefined.
+      '--debug': Boolean,
+      '--fileExtensions': String,
     },
     {
       argv: rawArgs.slice(2),
@@ -23,6 +31,11 @@ function parseArgumentsIntoOptions(rawArgs) {
     projectFolderPath: args['--projectFolderPath'],
     ignorePackagesGlobPattern: args['--ignorePackagesGlobPattern'],
     ignoreFilesGlobPattern: args['--ignoreFilesGlobPattern'],
+    outputPath: args['--outputPath'],
+    startingDirPath: args['--startingDirPath'],
+    debug: args['--debug'], // CLI flag, not available as a question.
+    fileExtensions: args['--fileExtensions'], // CLI flag, not available as a question.
+    gitIgnorePath: args['--gitIgnorePath'],
     script: args._[0],
   };
 }

package/bin/cli/code-mods/command-arguments/getDeprecatedUsageReportQuestions.mjs

@@ -0,0 +1,31 @@
+export const getDeprecatedUsageReportQuestions = (originalOptions) => {
+  const extraOptions = [];
+  const { outputPath, startingDirPath, gitIgnorePath } = originalOptions;
+  if (!outputPath && outputPath !== '') {
+    extraOptions.push({
+      type: 'input',
+      name: 'outputPath',
+      message: 'path to the .csv file to write the report to',
+      default: './dimsum-deprecated-components-usage-report.csv',
+    });
+  }
+  if (!startingDirPath && startingDirPath !== '') {
+    extraOptions.push({
+      type: 'input',
+      name: 'startingDirPath',
+      message: 'Please provide the project root directory (where node_modules folder lives)',
+      default: './',
+    });
+  }
+  if (!gitIgnorePath && gitIgnorePath !== '') {
+    extraOptions.push({
+      type: 'input',
+      name: 'gitIgnorePath',
+      message: 'Please provide the path to the .gitignore file',
+      default: './.gitignore',
+    });
+  }
+  // --debug is a CLI flag, not available as a question.
+
+  return extraOptions;
+};

package/bin/cli/code-mods/command-arguments/promptDeprecatedPackages.mjs

@@ -4,7 +4,7 @@ export const getDeprecatedPackagesQuestions = (originalOptions) => {
   if (!cwd && cwd !== '') {
     extraOptions.push({
       type: 'input',
-      name: 'globPatternIgnore',
+      name: 'cwd',
       message: 'Please provide the project root directory (where node_modules folder lives)',
       default: './',
     });

package/bin/cli/code-mods/command-logics/check-deprecated-packages/logResults.mjs

@@ -6,7 +6,7 @@ import {
   brightCyanStr,
   whiteStr,
 } from '../../../utils/CLI_COLORS.mjs';
-import { DEPRECATED_PACKAGES } from './constants.mjs';
+import { DEPRECATED_PACKAGES } from '../../../constants/deprecatedPackages.mjs';
 
 const logDeprecatedComponent = ({ name, solution, severity, confluence }) => {
   const [sevDesc, sevLevel] = severity;

package/bin/cli/code-mods/command-logics/deprecated-components-usage-report/index.mjs

@@ -0,0 +1,36 @@
+import fs from 'fs';
+import { filePathsWithGitIgnore } from '../../../utils/filepathsMatchers.mjs';
+import { generateCsvRows, checkFileForDeprecatedComponents } from './utils.mjs';
+
+/**
+ * generates a report of deprecated components usage
+ * @param {object} options - options *
+ * @param {string} options.outputPath - path to the .csv file to write the report to
+ * @param {string} options.startingDirPath - path to the project root directory (where node_modules folder lives)
+ * @param {string} options.gitIgnorePath - path to the .gitignore file
+ * @param {boolean} options.debug - debug flag
+ *
+ * @returns {void}
+ */
+export const deprecatedComponentsUsageReport = (options) => {
+  const { outputPath } = options;
+
+  const filesToParse = filePathsWithGitIgnore(options);
+  // we have a lot more info than the one we use in the csv,
+  //  in case we want to expand it in the future we can store it in the map...
+  // const problematicFiles = new Map();
+
+  const csvRows = ['Legacy Component,Legacy Package,Filename,File Path'];
+  filesToParse.forEach((filePath) => {
+    const fileReport = checkFileForDeprecatedComponents(filePath);
+    if (fileReport.isFileProblematic) {
+      // we have a lot more info than the one we use in the csv,
+      //  in case we want to expand it in the future we can store it in the map...
+      // problematicFiles.set(filePath, fileReport);
+      csvRows.push(...generateCsvRows(fileReport, filePath));
+    }
+  });
+  fs.writeFileSync(outputPath, csvRows.join('\n'));
+};
+
+export default deprecatedComponentsUsageReport;

package/bin/cli/code-mods/command-logics/deprecated-components-usage-report/regexp.mjs

@@ -0,0 +1,55 @@
+// eslint-disable-next-line max-len, max-len
+// /^import\s*((?:[\S]*(?:\s*as\s*[\S]*)?(?:\s*,\s*(?:(?:[\S]*\s*as\s*[\S]*)|(?:\{(?:[\s\S](?!{))*?\})))?)|(?:\{(?:[\s\S](?!{))*?\}))\s*from\s*['"](@elliemae\/ds-\S+)['"]/gms
+/*
+reg-exp divided into units for readability:
+^import\s*                  - matches "import" followed by any number of spaces,
+                              constraints the match to the beginning of the line
+(                           - start of the first capturing group
+   // this one captures:
+   - the default import (e.g. import Button from 'wherever')
+   - the named import (e.g. import Button as Btn from 'wherever')
+   - the default import followed by a comma (e.g. import Button, { Input } from 'wherever')
+   (?:
+      [\S]*                - matches any non-whitespace character any number of times
+                              this is meant to catch the default import (e.g. import Button from 'wherever')
+      (?:\s*as\s*[\S]*)?   - optionally matches the named import (e.g. import Button as Btn from 'wherever')
+
+      (?:                  - optionally matches imports with comma after them
+                                (e.g. import Button, { Input } from 'wherever')
+        \s*,\s*            - matches a comma, with any number of spaces before and after it
+                           - in ESM after a comma you have a named default import or a destructured import...
+        (?:
+          (?:[\S]*\s*as\s*[\S]*)  - the catching of "default" imports as above,
+                                      no optional named import because after comma you can't repeat the default import
+          |
+          (?:\{           - between curly braces START
+            (?:[\s\S]     - anything (including new lines)
+              (?!{)       - as long as it's not followed by another curly brace 
+                              (avoid matching import from other packages followed by import from @elliemae/ds-* )
+            )*?
+          \})             - between curly braces END
+        )
+      )?                    
+   )
+   |                        - OR
+   // this one captures:
+   - the destructured import (e.g. import { Button } from 'wherever')
+   (?:\{           - between curly braces START
+      (?:[\s\S]     - anything (including new lines)
+        (?!{)       - as long as it's not followed by another curly brace 
+                      (avoid matching import from other packages followed by import from @elliemae/ds-* )
+      )*?
+    \})             - between curly braces END
+   
+)
+\s*from\s*                  - matches "from" with any number of spaces before and after it
+- matches a string between single or double quotes that starts with "@elliemae/ds-*"
+ ['"]
+    (@elliemae\/ds-\S+)
+ ['"]
+
+https://regex101.com/r/7BsJPF/1
+*/
+export const dimsumImportStatementsRegExp =
+  // eslint-disable-next-line max-len
+  /^import\s*((?:[\S]*(?:\s*as\s*[\S]*)?(?:\s*,\s*(?:(?:[\S]*\s*as\s*[\S]*)|(?:\{(?:[\s\S](?!{))*?\})))?)|(?:\{(?:[\s\S](?!{))*?\}))\s*from\s*['"](@elliemae\/ds-\S+)['"]/gms;

package/bin/cli/code-mods/command-logics/deprecated-components-usage-report/utils.mjs

@@ -0,0 +1,256 @@
+/* eslint-disable max-lines */
+/* eslint-disable max-statements */
+/* eslint-disable max-len */
+import fs from 'fs';
+import { dimsumImportStatementsRegExp } from './regexp.mjs';
+import {
+  LEGACY_WITH_NEW_SMALL_MIGRATION_EFFORT,
+  LEGACY_WITH_NEW_MEDIUM_MIGRATION_EFFORT,
+  LEGACY_WITH_NEW_LARGE_MIGRATION_EFFORT,
+  DISMISSED_WITH_EXAMPLE,
+} from '../../../constants/index.mjs';
+
+/**
+ * @typedef {typeof LEGACY_WITH_NEW_SMALL_MIGRATION_EFFORT
+ *    | typeof LEGACY_WITH_NEW_MEDIUM_MIGRATION_EFFORT
+ *    | typeof LEGACY_WITH_NEW_LARGE_MIGRATION_EFFORT} deprecatedEffortMap
+ * @typedef {deprecatedEffortMap[number]} deprecatedEffortMapEntry
+ * @typedef {typeof DISMISSED_WITH_EXAMPLE[number]} dismissedWithExampleEntry
+ *
+ * @typedef { object } regexpInfo
+ * @property { string } regexpInfo.fullMatch
+ * @property { string } regexpInfo.importedComponent
+ * @property { string } regexpInfo.packageName
+ *
+ * @typedef {object} matchSharedPropieties
+ * @property {regexpInfo} matchSharedPropieties.regexpInfo
+ *
+ * @typedef { object } matchWithEffortEntryPropeties
+ * @property { deprecatedEffortMapEntry } matchWithEffortEntryPropeties.matchingEffortMetainfo
+ *
+ * @typedef { object } matchDeprecatedEntryPropeties
+ * @property { dismissedWithExampleEntry } matchDeprecatedEntryPropeties.matchingEffortMetainfo
+ *
+ * @typedef {matchSharedPropieties & matchWithEffortEntryPropeties} matchWithEffortMetaInfo
+ * @typedef {matchSharedPropieties & matchDeprecatedEntryPropeties} matchDeprecatedWithExample
+ *
+ * @typedef {matchWithEffortMetaInfo | matchDeprecatedWithExample} matchedEffortMapValue
+ *
+ * @typedef {Map<string, matchedEffortMapValue>} matchedEffortMap
+ *
+ * @typedef {object} fileReport
+ * @property {boolean} fileReport.isFileProblematic
+ * @property {matchWithEffortMetaInfo} fileReport.deprecatedSmallEffort
+ * @property {matchWithEffortMetaInfo} fileReport.deprecatedMediumEffort
+ * @property {matchWithEffortMetaInfo} fileReport.deprecatedLargeEffort
+ * @property {matchDeprecatedWithExample} fileReport.deprecatedDismissed
+ *
+ */
+
+// we generate some supporting data structures to make the matching more efficient from the existing constants...
+// we do this runtime because we want to avoid having to maintain this manually and this is a one time cost runtime wise with the cache...
+const runtimeDeprecatedDSReportCache = new Map();
+const getSupportingDataStructures = (deprecatedEffortMap, effortCacheUID) => {
+  if (runtimeDeprecatedDSReportCache.has(effortCacheUID)) {
+    return runtimeDeprecatedDSReportCache.get(effortCacheUID);
+  }
+  // we generate some supporting data structures to make the matching more efficient from the existing constants...
+  const effortsSamePackageList = [];
+  const effortsSamePackageOldComponentsList = [];
+  const effortsDifferentPackageList = [];
+
+  deprecatedEffortMap.forEach((DeprecatedPackageMeta) => {
+    const { oldPackage, component, newPackage } = DeprecatedPackageMeta;
+    if (oldPackage === newPackage) {
+      if (!effortsSamePackageList.includes(oldPackage)) effortsSamePackageList.push(oldPackage);
+      if (!effortsSamePackageOldComponentsList.includes(component)) effortsSamePackageOldComponentsList.push(component);
+    } else {
+      if (!effortsDifferentPackageList.includes(oldPackage)) effortsDifferentPackageList.push(oldPackage);
+    }
+  });
+
+  runtimeDeprecatedDSReportCache.set(effortCacheUID, {
+    effortsSamePackageList,
+    effortsSamePackageOldComponentsList,
+    effortsDifferentPackageList,
+  });
+
+  return runtimeDeprecatedDSReportCache.get(effortCacheUID);
+};
+
+/**
+ * given a list of import statements, it checks if any of them is deprecated based on the constants provided
+ * @param {string[][]} importStatements - list of import statements to check generated by the regex
+ * @param {LEGACY_WITH_NEW_SMALL_MIGRATION_EFFORT} deprecatedEffortMap - list of constants to check against
+ * @param {string} effortCacheUID - a string to identify the effort level (small, medium, large) in the cache if existing
+ * @returns {Map<string, matchWithEffortMetaInfo>} - a map of matched statements
+ */
+const checkDeprecatedEffort = (importStatements, deprecatedEffortMap, effortCacheUID = '') => {
+  const { effortsSamePackageList, effortsSamePackageOldComponentsList, effortsDifferentPackageList } =
+    getSupportingDataStructures(deprecatedEffortMap, effortCacheUID);
+
+  const matchedEfforts = new Map();
+
+  importStatements.forEach((importStatement) => {
+    const [fullMatch, importedComponent, packageName] = importStatement;
+    // first we check if we need to care about this package at all
+    //  we do not care if the package is not in the list of packages that have small migration effort
+    // when the deprecation is in another package we know for sure that the statement is deprecated
+    const statementIsDeprecatedForSure =
+      effortsDifferentPackageList.findIndex((pck) => pck.includes(packageName)) !== -1;
+    // when the deprecation is in the same package we need to check if the component itself is deprecated
+    const statementIsPotentiallyDeprecated =
+      effortsSamePackageList.findIndex((pck) => pck.includes(packageName)) !== -1;
+    let isStatementActuallyDeprecated = false;
+    if (!statementIsDeprecatedForSure && statementIsPotentiallyDeprecated) {
+      effortsSamePackageOldComponentsList.forEach((deprecatedComponent) => {
+        if (importedComponent.includes(deprecatedComponent)) {
+          isStatementActuallyDeprecated = true;
+        }
+      });
+    }
+    const statementIsDeprecated = statementIsDeprecatedForSure || isStatementActuallyDeprecated;
+    if (statementIsDeprecated) {
+      // we iterate the deprecatedEffortMap again now that we know the statement is deprecated,
+      // we do this so we can reach the constant meta-informations (like the new package name, severityTags, etc...)
+      // technically this is O(n * m) where n is ~<10 and m is ~<50 so even the worst case is not that bad...
+      const matchingEffortMetainfoIndx = deprecatedEffortMap.findIndex((effortMetainfo) => {
+        if (statementIsDeprecatedForSure) {
+          return effortMetainfo.oldPackage === packageName;
+        }
+        return importedComponent.includes(effortMetainfo.component);
+      });
+      matchedEfforts.set(fullMatch, {
+        regexpInfo: { fullMatch, importedComponent, packageName },
+        matchingEffortMetainfo: deprecatedEffortMap[matchingEffortMetainfoIndx],
+      });
+    }
+  });
+  return matchedEfforts;
+};
+/**
+ * given a list of import statements, it checks if any of them is a low effort deprecation
+ * @param {string[][]} importStatements - list of import statements to check generated by the regex
+ * @returns {Map<string, matchWithEffortMetaInfo>} - a map of matched statements
+ */
+export const checkDeprecatedSmallEffort = (importStatements) =>
+  checkDeprecatedEffort(importStatements, LEGACY_WITH_NEW_SMALL_MIGRATION_EFFORT, 'small');
+
+/**
+ * given a list of import statements, it checks if any of them is a medium effort deprecation
+ * @param {string[][]} importStatements - list of import statements to check generated by the regex
+ * @returns {Map<string, matchWithEffortMetaInfo>} - a map of matched statements
+ */
+export const checkDeprecatedMediumEffort = (importStatements) =>
+  checkDeprecatedEffort(importStatements, LEGACY_WITH_NEW_MEDIUM_MIGRATION_EFFORT, 'medium');
+
+/**
+ * given a list of import statements, it checks if any of them is a large effort deprecation
+ * @param {string[][]} importStatements - list of import statements to check generated by the regex
+ * @returns {Map<string, matchWithEffortMetaInfo>} - a map of matched statements
+ */
+export const checkDeprecatedLargeEffort = (importStatements) =>
+  checkDeprecatedEffort(importStatements, LEGACY_WITH_NEW_LARGE_MIGRATION_EFFORT, 'large');
+
+/**
+ * given a list of import statements, it checks if any of them is a large effort deprecation
+ * @param {string[][]} importStatements - list of import statements to check generated by the regex
+ * @returns {Map<string, matchDeprecatedWithExample>} - a map of matched statements
+ */
+export const checkDeprecatedDismissed = (importStatements) => {
+  const matchedEfforts = new Map();
+  importStatements.forEach((importStatement) => {
+    const [fullMatch, importedComponent, packageName] = importStatement;
+    const matchingEffortMetainfoIndx = DISMISSED_WITH_EXAMPLE.findIndex((effortMetainfo) =>
+      importedComponent.includes(effortMetainfo.component),
+    );
+    if (matchingEffortMetainfoIndx === -1) return;
+    matchedEfforts.set(fullMatch, {
+      regexpInfo: { fullMatch, importedComponent, packageName },
+      matchingEffortMetainfo: DISMISSED_WITH_EXAMPLE[matchingEffortMetainfoIndx],
+    });
+  });
+  return matchedEfforts;
+};
+
+/**
+ * given a file path, it checks if the file contains any deprecated components
+ * @param {string} filePath - path to the file to check
+ * @returns {fileReport} - a report of the file
+ */
+export const checkFileForDeprecatedComponents = (filePath) => {
+  const fileAsString = fs.readFileSync(filePath, 'utf8');
+  const matches = fileAsString.matchAll(dimsumImportStatementsRegExp);
+  const importStatements = [...matches]; // convert iterator to array - matchAll returns an iterator...
+  const deprecatedSmallEffort = checkDeprecatedSmallEffort(importStatements);
+  const deprecatedMediumEffort = checkDeprecatedMediumEffort(importStatements);
+  const deprecatedLargeEffort = checkDeprecatedLargeEffort(importStatements);
+  const deprecatedDismissed = checkDeprecatedDismissed(importStatements);
+
+  const isFileProblematic =
+    deprecatedSmallEffort.size > 0 ||
+    deprecatedMediumEffort.size > 0 ||
+    deprecatedLargeEffort.size > 0 ||
+    deprecatedDismissed.size > 0;
+
+  return {
+    isFileProblematic,
+    deprecatedSmallEffort,
+    deprecatedMediumEffort,
+    deprecatedLargeEffort,
+    deprecatedDismissed,
+  };
+};
+
+/**
+ * Helper function to generate a csv row from a "matched effort" object
+ * @param {matchedEffortMapValue} matchedEffort
+ * @param {string} filePath
+ * @returns {string} - csv row
+ */
+const generateCsvRowFromMatchedEffort = (matchedEffort, filePath) => {
+  const { matchingEffortMetainfo } = matchedEffort;
+  // matchingEffortMetainfo type is deprecatedEffortMapEntry | dismissedWithExampleEntry
+  // they share 'component' and 'oldPackage' properties and for the current use case we only care about those
+  // if we want to expand the csv in the future we have to take care of this difference in the types
+  const { component, oldPackage } = matchingEffortMetainfo;
+  const filename = filePath.split('/').pop();
+  const cwdFolders = process.cwd().split('/');
+  const pathFolders = filePath.split('/');
+  const latestMatchingFolderIndx = pathFolders.findIndex((folder, indx) => folder !== cwdFolders[indx]);
+  const filePathFolders = pathFolders.slice(latestMatchingFolderIndx);
+  const reducedFilePath = filePathFolders.join('/');
+  return `${component},${oldPackage},${filename},${reducedFilePath}`;
+};
+/**
+ * Helper function to generate a list of csv rows from a given file report
+ * @param {fileReport} fileReport
+ * @param {string} filePath
+ * @returns {string[]} - list of csv rows
+ */
+export const generateCsvRows = (fileReport, filePath) => {
+  const { deprecatedSmallEffort, deprecatedMediumEffort, deprecatedLargeEffort, deprecatedDismissed } = fileReport;
+  // csv structure = 'Legacy Component,Legacy Package,Filename,File Path'
+  // Legacy Component -> matchingEffortMetainfo.component
+  // Legacy Package -> matchingEffortMetainfo.oldPackage
+  // Filename -> filePath last part
+  // File Path -> filePath starting from latest matching folder from cwd
+  //  (if cwd is /a/b/c/d/ and file path /a/b/1/2/3/file.tsx -> b/1/2/3/file.tsx)
+  //  this is not a perfect "detect the root" solution, but should work in our CI/CD pipeline
+  const csvRows = [];
+  deprecatedSmallEffort.forEach((effort) => {
+    csvRows.push(generateCsvRowFromMatchedEffort(effort, filePath));
+  });
+  deprecatedMediumEffort.forEach((effort) => {
+    csvRows.push(generateCsvRowFromMatchedEffort(effort, filePath));
+  });
+  deprecatedLargeEffort.forEach((effort) => {
+    csvRows.push(generateCsvRowFromMatchedEffort(effort, filePath));
+  });
+
+  deprecatedDismissed.forEach((effort) => {
+    csvRows.push(generateCsvRowFromMatchedEffort(effort, filePath));
+  });
+
+  return csvRows;
+};

package/bin/cli/code-mods/command-logics/execute-commands-map.mjs

@@ -3,6 +3,7 @@ import { checkPackagesInconsistencies } from './check-packages-inconsistencies/i
 import { checkMissingPackages } from './check-missing-packages/index.mjs';
 import { checkDeprecatedPackages } from './check-deprecated-packages/index.mjs';
 import { helpMigrateToV3 } from './help-migrate-to-v3/index.mjs';
+import { deprecatedComponentsUsageReport } from './deprecated-components-usage-report/index.mjs';
 import { COMMANDS } from '../commands.mjs';
 
 export async function executeCommandsMap(args, options) {
@@ -25,6 +26,9 @@ export async function executeCommandsMap(args, options) {
     case COMMANDS.HELP_MIGRATE_TO_V3:
       helpMigrateToV3(options);
       break;
+    case COMMANDS.DEPRECATED_PACKAGES_USAGE_REPORT:
+      deprecatedComponentsUsageReport(options);
+      break;
     default:
       break;
   }

package/bin/cli/code-mods/commands.mjs

@@ -5,6 +5,7 @@ export const COMMANDS = {
   CHECK_PACKAGES_INCONSISTENCIES: 'check-packages-inconsistencies',
   CHECK_MISSING_PACKAGES: 'check-missing-packages',
   HELP_MIGRATE_TO_V3: 'help-migrate-to-v3',
+  DEPRECATED_PACKAGES_USAGE_REPORT: 'deprecated-components-usage-report',
   EXIT: 'exit',
 };
 

package/bin/cli/code-mods/inquirer-questions-prompter.mjs

@@ -5,6 +5,7 @@ import { getPackagesInconsistenciesQuestions } from './command-arguments/promptC
 import { getDeprecatedPackagesQuestions } from './command-arguments/promptDeprecatedPackages.mjs';
 import { getHelpMigrateToV3Questions } from './command-arguments/promptHelpMigrateToV3.mjs';
 import { getMissingPackagesQuestions } from './command-arguments/promptMissingPackages.mjs';
+import { getDeprecatedUsageReportQuestions } from './command-arguments/getDeprecatedUsageReportQuestions.mjs';
 
 async function promptForMissingScriptSpecificOptions({ originalOptions, promptOptions }) {
   const script = originalOptions.script || promptOptions.script;
@@ -26,6 +27,9 @@ async function promptForMissingScriptSpecificOptions({ originalOptions, promptOp
     case COMMANDS.HELP_MIGRATE_TO_V3:
       scriptQuestions.push(...getHelpMigrateToV3Questions(originalOptions));
       break;
+    case COMMANDS.DEPRECATED_PACKAGES_USAGE_REPORT:
+      scriptQuestions.push(...getDeprecatedUsageReportQuestions(originalOptions));
+      break;
     default:
       break;
   }

package/bin/cli/constants/deprecatedPackages.mjs

@@ -0,0 +1,332 @@
+/* eslint-disable max-lines */
+/**
+ * @typedef {object} SeverityTag
+ * @property {string} SeverityTag.name - the name of the tag
+ * @property {string} SeverityTag.severity - the severity of the tag
+ * @property {number} SeverityTag.severityInteger - the severity of the tag as an integer
+ * @property {string} SeverityTag.description - the description of the tag
+ *
+ * @typedef {object} DeprecatedPackageMatch
+ * @property {string} DeprecatedPackageMatch.component - the name of the LEGACY component
+ * @property {string} DeprecatedPackageMatch.oldPackage - the name of the LEGACY package
+ *
+ * @typedef {object} DeprecatedPackageWithEffortProperties
+ * @property {string} DeprecatedPackageWithEffortProperties.newComponent - the name of the NEW component
+ * @property {string} DeprecatedPackageWithEffortProperties.newPackage - the name of the NEW package
+ * @property {SeverityTag[]} DeprecatedPackageWithEffortProperties.tags - the tags associated with the component
+ *
+ * @typedef {DeprecatedPackageMatch & DeprecatedPackageWithEffortProperties} DeprecatedPackage
+ */
+
+const SEVERITY = {
+  NON_STARTER: ['Failing to upgrade will make the project impossible to start/use', 1],
+  KNOWN_ISSUES: [
+    'The component has unfixable known issues. Failing to upgrade means APP will have to live with those',
+    2,
+  ],
+  FRAGILE_AND_UNMANTAINED: [
+    'Failing to upgrade will make the project fragile and any error will have to be addressed by the APP team',
+    3,
+  ],
+  UNMANTAINED: ['Failing to upgrade will mean that any error will have to be addressed by the APP team', 4],
+};
+
+const SOLUTIONS = {
+  REMOVED: 'the component has been regarded as supreflous and has hencheforth been removed in favor of examples',
+  NEW_VERSION_BREAKING: 'the component impedes further enhancments/bugfixes, a new version ex-novo has been created.',
+};
+
+export const DEPRECATED_PACKAGES = {
+  '@elliemae/ds-datagrids': {
+    name: 'data-grid',
+    solution: SOLUTIONS.NEW_VERSION_BREAKING,
+    severity: SEVERITY.KNOWN_ISSUES,
+    // TODO create relative confluence
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
+  },
+  '@elliemae/ds-date-picker': {
+    name: 'date-picker',
+    solution: SOLUTIONS.NEW_VERSION_BREAKING,
+    severity: SEVERITY.KNOWN_ISSUES,
+    // TODO create relative confluence
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
+  },
+  '@elliemae/ds-date-range-picker': {
+    name: 'date-range-picker',
+    solution: SOLUTIONS.NEW_VERSION_BREAKING,
+    severity: SEVERITY.KNOWN_ISSUES,
+    // TODO create relative confluence
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
+  },
+  '@elliemae/ds-date-time-picker': {
+    name: 'date-time-picker',
+    solution: SOLUTIONS.NEW_VERSION_BREAKING,
+    severity: SEVERITY.KNOWN_ISSUES,
+    // TODO create relative confluence
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
+  },
+  '@elliemae/ds-time-picker': {
+    name: 'time-picker',
+    solution: SOLUTIONS.NEW_VERSION_BREAKING,
+    severity: SEVERITY.KNOWN_ISSUES,
+    // TODO create relative confluence
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
+  },
+  '@elliemae/ds-button-group': {
+    name: 'button-group',
+    solution: SOLUTIONS.REMOVED,
+    severity: SEVERITY.NON_STARTER,
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Button+Group+-+Dimsum+2.x',
+  },
+  '@elliemae/ds-card-array': {
+    name: 'card-array',
+    solution: SOLUTIONS.REMOVED,
+    severity: SEVERITY.NON_STARTER,
+    confluence: 'https://confluence.elliemae.io/display/FEAE/Card+Array+-+Dimsum+2.x',
+  },
+  '@elliemae/ds-form': {
+    subComponents: [
+      {
+        name: 'combobox',
+        solution: SOLUTIONS.NEW_VERSION_BREAKING,
+        severity: SEVERITY.FRAGILE_AND_UNMANTAINED,
+        confluence: 'https://confluence.elliemae.io/display/FEAE/Combo-box+-+Dimsum+2.x',
+      },
+    ],
+  },
+  '@elliemae/ds-combobox-v1': {
+    subComponents: [
+      {
+        name: 'combobox',
+        solution: SOLUTIONS.NEW_VERSION_BREAKING,
+        severity: SEVERITY.FRAGILE_AND_UNMANTAINED,
+        confluence: 'https://confluence.elliemae.io/display/FEAE/Combo-box+-+Dimsum+2.x',
+      },
+    ],
+  },
+};
+
+/*********************************************************************************************
+  Those constant would be extremely hard to read if we "prettify" them with project rules...
+  I'm making a conscious decision to disable prettier and auto-formatting for this section of the code.
+**********************************************************************************************/
+/* eslint-disable max-len, prettier/prettier  */
+
+/**
+ * @type {object<string, SeverityTag>}
+ * @property {SeverityTag} SEVERITY_TAGS.A11Y_LIMITATIONS
+ * @property {SeverityTag} SEVERITY_TAGS.TOOLING_BLOCKER
+ * @property {SeverityTag} SEVERITY_TAGS.UNMANTAINED
+ * @property {SeverityTag} SEVERITY_TAGS.FRAGILE
+ * @property {SeverityTag} SEVERITY_TAGS.KNOWN_ISSUES
+ */
+/* prettier-ignore */
+const SEVERITY_TAGS = {
+  // we don't expect to have any NON_STARTER, if we eventually do, we have to evaluate them manually
+  // { name: 'NON_STARTER', severity: "P1" },
+  A11Y_LIMITATIONS:{
+    name: 'A11Y_LIMITATIONS',    severity: 'P2', severityInteger: 2,
+    description: 'The accessibility requirements are only available to the alternative solution' },
+
+  TOOLING_BLOCKER:{
+    name: 'TOOLING_BLOCKER',     severity: 'P2', severityInteger: 2,
+    description: 
+     'The component is based in third-party-packages that makes changing tools like jest, styled-compoents, etc... impossible' },
+
+  UNMANTAINED:{ name: 'UNMANTAINED',         severity: 'P3', severityInteger: 3,
+    description:
+      'The component company-wise is low priority and has not received any meaningful attention in more than 8 months' },
+
+  FRAGILE:{ name: 'FRAGILE',             severity: 'P3', severityInteger: 3,
+    description: 'The component is extremely fragile and not extensible' },
+  
+  KNOWN_ISSUES:{ name: 'KNOWN_ISSUES',        severity: 'P3', severityInteger: 3,
+    description: 'The component has known issues that cannot be fixed' },
+};
+
+/* prettier-ignore */
+/**
+ * @type {DeprecatedPackage[]}
+ */
+export const LEGACY_WITH_NEW_SMALL_MIGRATION_EFFORT = [
+  { component:    'DSModal',                          oldPackage: '@elliemae/ds-modal',
+    newComponent: 'DSDialog',                         newPackage: '@elliemae/ds-dialog',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSButton',                         oldPackage: '@elliemae/ds-button',
+    newComponent: 'DSButtonV3',                       newPackage: '@elliemae/ds-button',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSCircularProgressIndicator',      oldPackage: '@elliemae/ds-circular-progress-indicator',
+    newComponent: 'DSCircularIndeterminateIndicator', newPackage: '@elliemae/ds-circular-progress-indicator',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSButtonV2',                       oldPackage: '@elliemae/ds-button',
+    newComponent: 'DSButtonV3',                       newPackage: '@elliemae/ds-button',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSTooltipV2',                      oldPackage: '@elliemae/ds-tooltip',
+    newComponent: 'DSTooltipV3',                      newPackage: '@elliemae/ds-tooltip',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSSeparator',                      oldPackage: '@elliemae/ds-separator',
+    newComponent: 'DSSeparatorV2',                    newPackage: '@elliemae/ds-separator',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSFormItemLayout',                 oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSFormLayoutBlockItem',            newPackage: '@elliemae/ds-form-layout-blocks',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSTooltip',                        oldPackage: '@elliemae/ds-tooltip',
+    newComponent: 'DSTooltipV3',                      newPackage: '@elliemae/ds-tooltip',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSToggle',                         oldPackage: '@elliemae/ds-toggle',
+    newComponent: 'DSControlledToggle',               newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSDateInput',                      oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSControlledDateTimePicker',       newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSDateInputV2',                    oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSControlledDateTimePicker',       newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSComboBox2',                      oldPackage: '@elliemae/ds-form', 
+    newComponent: 'DSComboBoxV3',                     newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSComboBoxV1',                     oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSComboBoxV3',                     newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSComboBox',                       oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSComboBoxV3',                     newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSPill',                           oldPackage: '@elliemae/ds-pills',
+    newComponent: 'DSPillV2',                         newPackage: '@elliemae/ds-pills-v2',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSCheckbox',                       oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSControlledCheckbox',             newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+  
+  { component:    'DSInputGroup',                     oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSInputGroup',                     newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+  
+  { component:    'DSRadio',                          oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSControlledRadio',                newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+  
+  { component:    'DSTextBox',                        oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSInputText',                      newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSLargeInputText',                 oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSControlledLargeTextInput',       newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+];
+/**
+ * @type {DeprecatedPackage[]}
+ */
+/* prettier-ignore */
+export const LEGACY_WITH_NEW_MEDIUM_MIGRATION_EFFORT = [
+  { component:    'DSDropdownMenu',                   oldPackage: '@elliemae/ds-dropdownmenu',
+    newComponent: 'DSDropdownMenuV2',                 newPackage: '@elliemae/ds-dropdown-menu-v2',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'Minitoolbar',                      oldPackage: '@elliemae/ds-mini-toolbar',
+    newComponent: 'DSToolbarV2',                      newPackage: '@elliemae/ds-toolbar-v2',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSToolbar',                        oldPackage: '@elliemae/ds-toolbar',
+    newComponent: 'DSToolbarV2',                      newPackage: '@elliemae/ds-toolbar',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSDatePicker',                     oldPackage: '@elliemae/ds-date-picker',
+    newComponent: 'DSControlledDateTimePicker',       newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSDateRangePicker',                oldPackage: '@elliemae/ds-date-range-picker',
+    newComponent: 'DSControlledDateRangePicker',      newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSTimeInput',                      oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSControlledDateTimePicker',       newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DSTimePicker',                     oldPackage: '@elliemae/ds-time-picker',
+    newComponent: 'DSControlledDateTimePicker',       newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+  
+  { component:    'DSInputMask',                      oldPackage: '@elliemae/ds-form',
+    newComponent: 'DSInputText',                      newPackage: '@elliemae/ds-controlled-form',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+]
+
+/* prettier-ignore */
+export const LEGACY_WITH_NEW_LARGE_MIGRATION_EFFORT = [
+  { component:    'DSShuttle',                        oldPackage: '@elliemae/ds-shuttle',
+    newComponent: 'DSShuttleV2',                      newPackage: '@elliemae/ds-shuttle-v2',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+
+  { component:    'DataGrid',                         oldPackage: '@elliemae/ds-data-grid',
+    newComponent: 'DataTable',                        newPackage: '@elliemae/ds-data-table',
+    tags:[ SEVERITY_TAGS.A11Y_LIMITATIONS ],
+  },
+];
+
+// all of those are considered LOW effort
+/**
+ * @type {DeprecatedPackageMatch[]}
+ */
+/* prettier-ignore */
+export const DISMISSED_WITH_EXAMPLE = [
+  { component: 'DSButtonGroup',                       oldPackage:    'ds-button-group'                 },
+  { component: 'DSCardArray',                         oldPackage:    'ds-card-array'                   },
+  { component: 'DSLabelValue',                        oldPackage:    'ds-label-value'                  },
+  { component: 'DSDateRangeSelector',                 oldPackage:    'ds-date-range-selector'          },
+  { component: 'DSInputProtected',                    oldPackage:    'ds-form'                         },
+  { component: 'DSGroupBox',                          oldPackage:    'ds-group-box'                    },
+  { component: 'DSFilterBar',                         oldPackage:    'ds-filterbar'                    },
+  { component: 'DSDateTimeRecurrenceSelector',        oldPackage:    'ds-date-time-recurrence-picker'  },
+  { component: 'DSNumberRangeField',                  oldPackage:    'ds-number-range-field'           },
+  { component: 'DSPageNumber',                        oldPackage:    'ds-page-number'                  },
+  { component: 'DSSearchField',                       oldPackage:    'ds-search-field'                 },
+];
+/* eslint-enable max-len, prettier/prettier  */
+/*********************************************************************************************
+                              Formatting is back on :)
+**********************************************************************************************/

package/bin/cli/constants/index.mjs

@@ -0,0 +1,7 @@
+export {
+  DEPRECATED_PACKAGES,
+  LEGACY_WITH_NEW_SMALL_MIGRATION_EFFORT,
+  LEGACY_WITH_NEW_MEDIUM_MIGRATION_EFFORT,
+  LEGACY_WITH_NEW_LARGE_MIGRATION_EFFORT,
+  DISMISSED_WITH_EXAMPLE,
+} from './deprecatedPackages.mjs';

package/bin/cli/utils/File Matching.md

@@ -0,0 +1,83 @@
+# Regarding file matching
+
+## Support for Gitignore
+
+### pre-analysis
+
+based on CLI `man(ual)` git ignore : `man 5 gitignore`
+
+```
+GITIGNORE(5)                                                                                                           Git Manual                                                                                                             GITIGNORE(5)
+
+NAME
+       gitignore - Specifies intentionally untracked files to ignore
+```
+
+specifically:
+
+```
+
+DESCRIPTION
+       [...]
+       Each line in a gitignore file specifies a pattern.
+       [...]
+
+PATTERN FORMAT
+       [...]
+       See fnmatch(3) and the FNM_PATHNAME flag for a more detailed description.
+```
+
+the algorithm to support `.gitignore` syntaxes for filtering we need requires the following charateristics:
+
+- multiple patterns match
+- `fnmatch` patterns support
+
+### Gathering the list of files
+
+Ideally speaking we want to find a solution that would support the generation of the filepaths list based on the "gitignore" in one go.
+
+The standard filesystem API from nodejs 20 is not able to support glob patterns as of today, it's merely able to generate a list of every single file-path recursively.
+
+#### How does other do it?
+
+##### Glob - how does it generate the file list?
+
+based on my understanding, the creator of `Glob` has also developed a dedicated file-system optimization library he uses in the Glob package, which is [path-scurry](https://www.npmjs.com/package/path-scurry#:~:text=For%20resolving,resolution).
+
+> For resolving string paths, PathScurry ranges from 5-50 times faster than path.resolve on repeated resolutions, but around 100 to 1000 times slower on the first resolution.
+> [...]
+> With default settings on a folder tree of 100,000 items, consisting of around a 10-to-1 ratio of normal files to directories, PathScurry performs comparably to @nodelib/fs.walk, which is the fastest and most reliable file system walker I could find.
+> As far as I can tell, it's almost impossible to go much faster in a Node.js program, just based on how fast you can push syscalls out to the fs thread pool.
+
+I understand that under the hood `Glob` is NOT applying the matching pattern at the "matching" step itself, it's instead generating a list of all the files and later on filtering it down with `regexp` string matching.
+
+I also understand that the optimization path-scurry are providing to the file-list generation are not necessarly beneficial to our scenario and are making a trade-off of memory in favory of execution time, which in CI & CD environments may not be desiderable due to the reduced RAM of the environments, we usually prefeer to have the pipeline run 2x longer but requiring 1/2 the RAM resources rather then taking 1/2 the time but reserving 2x the RAM.
+
+[from scurry docs](https://www.npmjs.com/package/path-scurry#:~:text=PathScurry%20makes,can)
+
+> PathScurry makes heavy use of LRUCache to efficiently cache whatever it can, and Path objects remain in the graph for the lifetime of the walker
+
+##### [Glob](https://www.npmjs.com/package/glob#:~:text=testing,characters) - gitignore support
+
+based on my current understanding, the node package `glob` is not specifically about supporting all the possible syntaxes that are meant to be supported by the gitignore patterns:
+
+> testing, fast-glob is around 10-20% faster than this module when walking over 200k files nested 4 directories deep 1.
+> However, there are some inconsistencies with Bash matching behavior that this module does not suffer from
+
+and it's instead trying to create a bash compliant list of files paths based on bash patterns.
+
+for this reason to ensure 1-1 `Glob` matching would require still a further pattern matching on the generated list and I understand we would not necessarly benefit from the trades-off glob is making under the hood.
+
+#### What I will do
+
+##### step 1 - generate the file-list via native fs readDir
+
+I will use the native node implementation to ensure maximum compatibility and to not encur the risk that the glob abstraction may incurr due to the heavy use of the LRUCache, relying on node's own performance optimization. I think that if any enhancement on the performance/memory is required it would be easier to manage if we don't deal with Glob out-of-the-box optimization and start from the bottom-line
+
+##### step 2 - further filtering - gitignore compliant
+
+I have found out https://github.com/micromatch/micromatch
+
+which seems to be used by `square`, `webpack`, `babel core`, `yarn`, `jest`, `taro`, `bulma`, `browser-sync`, `documentation.js`, `stylelint`, `nyc`, `ava`
+
+and seems to be matching our requirements.

package/bin/cli/utils/debugHelpers.mjs

@@ -0,0 +1,58 @@
+// -----------------------------------------------------------------------------
+// Debug helpers for ram issues
+// -----------------------------------------------------------------------------
+/**
+ * a helper function to format memory usage data into a human readable format
+ * @param {number} data - memory usage data
+ * @returns {string} - formatted memory usage data in MB
+ */
+const formatMemoryUsage = (data) => `${Math.round((data / 1024 / 1024) * 100) / 100} MB`;
+
+/**
+ * logs the current memory usage
+ * @param {object} memoryData - memory usage data - process.memoryUsage()
+ * @param {string} [prefix=''] - prefix for the log
+ * @returns {void}
+ */
+export const logCurrMemoryUsage = (memoryData, prefix = '') => {
+  const memoryUsage = {
+    // 'process total allocated memory': `${formatMemoryUsage(memoryData.rss)}`, // not relevant?
+    'heap total size': `${formatMemoryUsage(memoryData.heapTotal)}`,
+    'current heap memory used': `${formatMemoryUsage(memoryData.heapUsed)}`,
+    // 'v8 external memory': `${formatMemoryUsage(memoryData.external)}`, // not relevant?
+  };
+  console.log('************************************************************************');
+  console.log(prefix, memoryUsage);
+  console.log('************************************************************************');
+};
+
+/**
+ * logs the difference between two memory usage data objects
+ * @param {object} memoryDataBefore - memory usage data - process.memoryUsage()
+ * @param {object} memoryDataAfter - memory usage data - process.memoryUsage()
+ * @param {string} [prefix=''] - prefix for the log
+ * @returns {void}
+ */
+export const logMemoryUsageDiff = (memoryDataBefore, memoryDataAfter, prefix = '') => {
+  // const diffRSS = memoryDataAfter.rss - memoryDataBefore.rss;
+  const diffHeapTotal = memoryDataAfter.heapTotal - memoryDataBefore.heapTotal;
+  const diffHeapUsed = memoryDataAfter.heapUsed - memoryDataBefore.heapUsed;
+  // const diffExternal = memoryDataAfter.external - memoryDataBefore.external;
+  const diffData = {
+    // 'process total allocated memory': `${formatMemoryUsage(memoryDataBefore.rss)} ${
+    //   diffRSS > 0 ? '+' : ''
+    // }${formatMemoryUsage(diffRSS)}`, // not relevant?
+    'heap total size': `${formatMemoryUsage(memoryDataBefore.heapTotal)} ${
+      diffHeapTotal > 0 ? '+' : ''
+    }${formatMemoryUsage(diffHeapTotal)}`,
+    'current heap memory used': `${formatMemoryUsage(memoryDataBefore.heapUsed)} ${
+      diffHeapUsed > 0 ? '+' : ''
+    }${formatMemoryUsage(diffHeapUsed)}`,
+    // 'v8 external memory': `${formatMemoryUsage(memoryDataBefore.external)} ${
+    //   diffExternal > 0 ? '+' : ''
+    // }${formatMemoryUsage(diffExternal)}`, // not relevant?
+  };
+  console.log('************************************************************************');
+  console.log(prefix, diffData);
+  console.log('************************************************************************');
+};

package/bin/cli/utils/filepathsMatchers.mjs

@@ -0,0 +1,198 @@
+/* eslint-disable max-lines */
+/* eslint-disable indent */
+import path from 'path';
+import { readdirSync, readFileSync } from 'fs';
+import { logCurrMemoryUsage, logMemoryUsageDiff } from './debugHelpers.mjs';
+import micromatch from 'micromatch'; // used to filter out files that match the git ignore patterns
+
+/********************************************************************
+ * ******* GENERIC STRING HELPERS COMMON TO PATHS & FILENAMES *******
+ ********************************************************************/
+
+/**
+ * convert windows paths to POSIX (glob compatible) slashes ( \ -- to --> /).
+ *
+ * @param {string} pathString the path to convert
+ * @returns {string} path with glob compatible POSIX slashes ( \ -- to --> /).
+ */
+const generatePosixPath = (pathString) => pathString.replace(/\\/g, '/');
+
+/**
+ * prepend process.cwd() to a string and convert to POSIX (glob compatible) slashes ( \ -- to --> /).
+ *
+ * @param {string} stringToPrependTo the string to prepend the CWD and make glob compatible
+ * @returns {string} paths with prepent CWD and glob compatible POSIX slashes ( \ -- to --> /).
+ */
+export const generatePathFromCurrentFolder = (...stringToPrependTo) =>
+  generatePosixPath(path.join(process.cwd(), ...stringToPrependTo));
+
+/********************************************************************
+ *** DIRECTORY RECURSIONS HELPERS - NO IGNORING DURING ITERATION ****
+ ********************************************************************/
+/**
+ * generates a list of files paths from a starting path iterating dirs recursively -
+ *  in node 20 this is potentially really slow per se,
+ *  we are implementing a micro-optimization by implementing it internally.
+ *
+ * This should not be required if
+ *  - node 20 fixes the performance issue with `readdirSync` -> recursive: true.
+ *  - we only need to support node 20+.
+ *
+ * withFileTypes: true - to avoid the extra `stat` system call.
+ *
+ * This function is also converting the paths to POSIX (glob compatible) internally, no need for windows specific code.
+ * @param {string} startingPath - path to start generating the list of files from
+ * @returns {string[]} - list of files paths
+ * @see https://nodejs.org/api/fs.html#fsreaddirsyncpath-options
+ * @see https://stackoverflow.com/a/76632197/1689370
+ */
+const getFilesMicroOptimized = (dir) => {
+  let dirsToProcess = [dir];
+  const outputFiles = [];
+  while (dirsToProcess.length > 0) {
+    const dir = dirsToProcess.pop();
+
+    const fileList = readdirSync(dir, { withFileTypes: true });
+    fileList.forEach((file) => {
+      const filePath = generatePosixPath(`${dir}/${file.name}`);
+      if (file.isDirectory()) {
+        dirsToProcess.push(filePath);
+      } else {
+        outputFiles.push(filePath);
+      }
+    });
+  }
+  return outputFiles;
+};
+
+/**
+ * generates a list of files paths from a starting path recursively -
+ *  in node 20 this is potentially really slow per se, we are implementing a micro-optimization:
+ *  we invoke the function recursively only on directories as a replacement for the `recursive` option of `readdirSync`
+ *     and additionally we use `withFileTypes` option to avoid the extra `stat` system call.
+ *
+ *  the way this is implemented we can use it on node < 20 as well.
+ *
+ * This function is also converting the paths to POSIX (glob compatible) internally, no need for windows specific code.
+ * @param {string} startingPath - path to start generating the list of files from
+ * @returns {string[]} - list of files paths
+ * @see https://nodejs.org/api/fs.html#fsreaddirsyncpath-options
+ * @see https://stackoverflow.com/a/76632197/1689370
+ */
+export const fullFilesPaths = (startingPath, debug = false) => {
+  let startMemoryUsage;
+  let endMemoryUsage;
+  let startTime;
+  if (debug) {
+    startTime = performance.now();
+    startMemoryUsage = process.memoryUsage();
+    logCurrMemoryUsage(startMemoryUsage, 'before recursion start');
+  }
+
+  // this is split into an helper function to make it explicit that
+  //   we know about the `recursive` option of `readdirSync` and we are not using it on purpose.
+  // required if running on node < 20
+  //  because of the lack of the `recursive` option of `readdirSync` in those versions.
+  const files = getFilesMicroOptimized(generatePathFromCurrentFolder(startingPath));
+
+  if (debug) {
+    endMemoryUsage = process.memoryUsage();
+    logMemoryUsageDiff(startMemoryUsage, endMemoryUsage, 'diff after recursion end');
+    // eslint-disable-next-line no-console
+    console.log('Estimated execution time: ', performance.now() - startTime);
+    // eslint-disable-next-line no-console
+    console.log('List of file entries generated:', files.length);
+  }
+  return files;
+};
+
+/********************************************************************
+ * DIRECTORY RECURSIONS HELPERS - IGNORING PATTERNS WHILE ITERATING *
+ this is not used, but keeping it around for reference,
+    as of 04/december/2023 this is slower than filtering at the end.
+ ********************************************************************/
+
+// Required if running on node < 20 becuase of the lack of the `recursive` option of `readdirSync` in those versions.
+// const getFilesMicroOptimizedWithIgnore = (startingPath, gitPatterns) => {
+//   let dirsToProcess = [generatePathFromCurrentFolder(startingPath)];
+//   const outputFiles = [];
+//   // the iterative approach avoids stack overflow errors
+//   //  allowing us to invoke the filtering function while iterating the directories
+//   while (dirsToProcess.length > 0) {
+//     const dir = dirsToProcess.pop();
+//     // we filter out the ignored files and directories here
+//     const fileList = readdirSync(dir, { withFileTypes: true }).filter(
+//       (file) => !micromatch.isMatch(generatePosixPath(`${dir}/${file.name}`), gitPatterns, { contains: true }),
+//     );
+//     fileList.forEach((file) => {
+//       const filePath = generatePosixPath(`${dir}/${file.name}`);
+//       if (file.isDirectory()) {
+//         dirsToProcess.push(filePath);
+//       } else {
+//         outputFiles.push(filePath);
+//       }
+//     });
+//   }
+//   return outputFiles;
+// };
+// const fullFilesPathsWithIgnore = (startingPath, gitPatterns, debug = false) => {
+//   let startMemoryUsage;
+//   let endMemoryUsage;
+//   let startTime;
+//   if (debug) {
+//     startTime = performance.now();
+//     startMemoryUsage = process.memoryUsage();
+//     logCurrMemoryUsage(startMemoryUsage, 'before recursion start');
+//   }
+//   // this is split into an helper function to make it explicit that
+//   //   we know about the `recursive` option of `readdirSync` and we are not using it on purpose.
+//   const files = getFilesMicroOptimizedWithIgnore(startingPath, gitPatterns, {
+//     debug,
+//     startMemoryUsage,
+//   });
+
+//   if (debug) {
+//     endMemoryUsage = process.memoryUsage();
+//     logMemoryUsageDiff(startMemoryUsage, endMemoryUsage, 'diff after recursion end');
+//     console.log('Estimated execution time: ', performance.now() - startTime);
+//     console.log('List of file entries generated:', files.length);
+//   }
+//   return files;
+// };
+
+/**
+ * generates a list of files paths from a starting path recursively,
+ *  filtering out files that match the git ignore patterns
+ * @param {object} options - options
+ * @param {string} options.startingDirPath - path to start generating the list of files from
+ * @param {string} options.gitIgnorePath - path to the .gitignore file
+ * @param {boolean} options.debug - debug flag
+ * @param {string} options.fileExtensions - comma separated list of file extensions to filter by
+ * @returns {string[]} - list of files paths
+ *
+ **/
+export const filePathsWithGitIgnore = (options) => {
+  const { startingDirPath, gitIgnorePath, debug = false, fileExtensions = '.js,.jsx,.ts,.tsx,.mjs' } = options;
+  // we generate a list of patterns to ignore from the .gitignore file.
+  const gitIgnoreFileContent = readFileSync(generatePathFromCurrentFolder(gitIgnorePath), 'utf8');
+  const gitIgnoreFileContentLines = gitIgnoreFileContent.split(/\r?\n/);
+  // remove empty and commented lines
+  const gitPatterns = gitIgnoreFileContentLines.filter((line) => line !== '' && !line.startsWith('#'));
+
+  // console.log('--------------- ----------------- filtering as we go:');
+  // const files = fullFilesPathsWithIgnore(startingDirPath, gitPatterns, debug);
+  // console.log(files.length);
+
+  // Based on my testing, filtering at the end results in way better performance than filtering as we go...
+  // console.log('--------------- ----------------- filtering at the end:');
+  const nonGitIgnoredFiles = fullFilesPaths(startingDirPath, debug).filter(
+    (file) => !micromatch.isMatch(file, gitPatterns, { contains: true }),
+  );
+  // we only want files matching the file extensions
+  const files = nonGitIgnoredFiles.filter((filePath) => {
+    const dotlessExtension = filePath.split('.').pop();
+    return fileExtensions.split(',').some((fileExtension) => fileExtension === `.${dotlessExtension}`);
+  });
+
+  return files;
+};

package/bin/cli/utils/index.mjs

@@ -1,5 +1,5 @@
-export * from './generatePathFromCurrentFolder.mjs';
-export * from './globArray.mjs';
-export * from './replaceFromMap.mjs';
-export * from './matchHelpers.mjs';
-export * from './getLatestDimsumVersion.mjs';
+export { generatePathFromCurrentFolder, fullFilesPaths } from './filepathsMatchers.mjs';
+export { globArray } from './globArray.mjs';
+export { replaceFromMap } from './replaceFromMap.mjs';
+export { getVersions, getMatchVersions, getHighestMatchVersion } from './matchHelpers.mjs';
+export { getLatestDimsumVersion } from './getLatestDimsumVersion.mjs';

package/package.json

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

package/bin/cli/code-mods/command-logics/check-deprecated-packages/constants.mjs

@@ -1,87 +0,0 @@
-export const SEVERITY = {
-  NON_STARTER: ['Failing to upgrade will make the project impossible to start/use', 1],
-  KNOWN_ISSUES: [
-    'The component has unfixable known issues. Failing to upgrade means APP will have to live with those',
-    2,
-  ],
-  FRAGILE_AND_UNMANTAINED: [
-    'Failing to upgrade will make the project fragile and any error will have to be addressed by the APP team',
-    3,
-  ],
-  UNMANTAINED: ['Failing to upgrade will mean that any error will have to be addressed by the APP team', 4],
-};
-
-export const SOLUTIONS = {
-  REMOVED: 'the component has been regarded as supreflous and has hencheforth been removed in favor of examples',
-  NEW_VERSION_BREAKING: 'the component impedes further enhancments/bugfixes, a new version ex-novo has been created.',
-};
-
-export const DEPRECATED_PACKAGES = {
-  '@elliemae/ds-datagrids': {
-    name: 'data-grid',
-    solution: SOLUTIONS.NEW_VERSION_BREAKING,
-    severity: SEVERITY.KNOWN_ISSUES,
-    // TODO create relative confluence
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
-  },
-  '@elliemae/ds-date-picker': {
-    name: 'date-picker',
-    solution: SOLUTIONS.NEW_VERSION_BREAKING,
-    severity: SEVERITY.KNOWN_ISSUES,
-    // TODO create relative confluence
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
-  },
-  '@elliemae/ds-date-range-picker': {
-    name: 'date-range-picker',
-    solution: SOLUTIONS.NEW_VERSION_BREAKING,
-    severity: SEVERITY.KNOWN_ISSUES,
-    // TODO create relative confluence
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
-  },
-  '@elliemae/ds-date-time-picker': {
-    name: 'date-time-picker',
-    solution: SOLUTIONS.NEW_VERSION_BREAKING,
-    severity: SEVERITY.KNOWN_ISSUES,
-    // TODO create relative confluence
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
-  },
-  '@elliemae/ds-time-picker': {
-    name: 'time-picker',
-    solution: SOLUTIONS.NEW_VERSION_BREAKING,
-    severity: SEVERITY.KNOWN_ISSUES,
-    // TODO create relative confluence
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Breaking+changes+-+Migration+steps+and+rationale',
-  },
-  '@elliemae/ds-button-group': {
-    name: 'button-group',
-    solution: SOLUTIONS.REMOVED,
-    severity: SEVERITY.NON_STARTER,
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Button+Group+-+Dimsum+2.x',
-  },
-  '@elliemae/ds-card-array': {
-    name: 'card-array',
-    solution: SOLUTIONS.REMOVED,
-    severity: SEVERITY.NON_STARTER,
-    confluence: 'https://confluence.elliemae.io/display/FEAE/Card+Array+-+Dimsum+2.x',
-  },
-  '@elliemae/ds-form': {
-    subComponents: [
-      {
-        name: 'combobox',
-        solution: SOLUTIONS.NEW_VERSION_BREAKING,
-        severity: SEVERITY.FRAGILE_AND_UNMANTAINED,
-        confluence: 'https://confluence.elliemae.io/display/FEAE/Combo-box+-+Dimsum+2.x',
-      },
-    ],
-  },
-  '@elliemae/ds-combobox-v1': {
-    subComponents: [
-      {
-        name: 'combobox',
-        solution: SOLUTIONS.NEW_VERSION_BREAKING,
-        severity: SEVERITY.FRAGILE_AND_UNMANTAINED,
-        confluence: 'https://confluence.elliemae.io/display/FEAE/Combo-box+-+Dimsum+2.x',
-      },
-    ],
-  },
-};

package/bin/cli/utils/generatePathFromCurrentFolder.mjs

@@ -1,11 +0,0 @@
-import path from 'path';
-/**
- * prepend process.cwd() to a string and convert to POSIX (glob compatible) slashes ( \ -- to --> /).
- *
- * @param {string} stringToPrependTo the string to prepend the CWD and make glob compatible
- * @returns {string} paths with prepent CWD and glob compatible POSIX slashes ( \ -- to --> /).
- */
-export const generatePathFromCurrentFolder = (...stringToPrependTo) =>
-  path.join(process.cwd(), ...stringToPrependTo).replace(/\\/g, '/');
-
-export default generatePathFromCurrentFolder;