@elliemae/ds-codemods 3.31.0-next.3 → 3.31.0-next.4

package/bin/cli/code-mods/command-logics/components-usage-report/dimsumImportStatementsRegExp.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/components-usage-report/index.mjs

@@ -0,0 +1,46 @@
+import fs from 'fs';
+import { createCSVReport } from './utils.mjs';
+
+const writeReport = (options, csvRows) => {
+  const { outputPath, append } = options;
+  if (!append) {
+    fs.writeFileSync(outputPath, csvRows.join('\n'));
+  } else {
+    // when we append we do not want to repeat the header, instead we want to add a new line
+    // we check if the file exists and if it does we check if the first line is the header
+    const fileExists = fs.existsSync(outputPath);
+    let shouldAddHeader = true;
+    if (fileExists) {
+      const fileContent = fs.readFileSync(outputPath, 'utf8');
+      const firstLine = fileContent.split('\n')[0];
+      if (firstLine === csvRows[0]) {
+        shouldAddHeader = false;
+      }
+    }
+    if (!shouldAddHeader) {
+      // since we are appending, the first line is left empty, this way the csvRows.join('\n') will add a new line
+      csvRows[0] = '';
+    }
+    fs.appendFileSync(outputPath, csvRows.join('\n'));
+  }
+};
+
+/**
+ * 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 {string} options.org - optional org, if present an extra column will be added to the report
+ * @param {string} options.repo - optional repo, if present an extra column will be added to the report
+ * @param {boolean} options.debug - debug flag
+ * @param {boolean} options.append - whether to append to the file or override it
+ *
+ * @returns {void}
+ */
+export const componentsUsageReport = (options) => {
+  const csvRows = createCSVReport(options);
+  writeReport(options, csvRows);
+};
+
+export default componentsUsageReport;

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

@@ -0,0 +1,320 @@
+/* eslint-disable max-params, max-lines, max-statements, max-len */
+import fs from 'fs';
+import { filePathsWithGitIgnore } from '../../../utils/filepathsMatchers.mjs';
+import { dimsumImportStatementsRegExp } from './dimsumImportStatementsRegExp.mjs';
+
+/**
+ * @typedef {Object} ImportAllAsResults
+ * @property {string} fullMatch
+ * @property {string} renamedAs
+ *
+ * @typedef {Object} DefaultImportResults
+ * @property {string} fullMatch
+ * @property {string} renamedAs
+ *
+ * @typedef {Object} PartialNamedImport
+ * @property {string} namedImportWithRename[number].partialFullMatch
+ * @property {string} namedImportWithRename[number].component
+ * @property {string|undefined} namedImportWithRename[number].renamedTo
+ *
+ * @typedef {PartialNamedImport[]} NamedImportResults
+ *
+ * @typedef { object } ImportsFlags
+ * @property {boolean} hasRelationWithDimsum
+ *
+ *
+ * @typedef {Object} fileImportsInfos
+ * @property {ImportAllAsResults[]} globalRenameImports
+ * @property {DefaultImportResults[]} importedDefaults
+ * @property {namedImportWithoutRename[]} importedNamedComponentsWithoutRename
+ * @property {namedImportWithRename[]} importedNamedComponentsWithRename
+ *
+ * @typedef {ImportsFlags & fileImportsInfos & Object} FileReport
+ * @property {string} filePath
+ */
+
+// specific regexp to distinguish 'import * as X from "Y"'
+/**
+ * given an ESM import statement as a string, it returns the renamed all as alias if present
+ * @param {string} importStatement - the import statement to parse
+ * @returns {ImportAllAsResults | undefined}
+ *  if renamed all as alias is present returns an object with the full match and the renamed all as alias
+ *
+ *  if no renamed all as alias is present returns undefined
+ * @example
+ * renameAllAs('import * as X from "Y"') // { fullMatch: 'import * as X from "Y"', renamedAs: 'X' }
+ * renameAllAs('import X from "Y"') // undefined
+ */
+const renameAllAs = (importStatement) => {
+  const renameAllAsRegex = /\*\s+as\s+(\w+)/gms;
+  // using matchAll because match doesn't preserve the capturing groups...
+  const matches = importStatement.matchAll(renameAllAsRegex);
+  const match = [...matches][0];
+  if (!match) return undefined;
+  return {
+    fullMatch: importStatement,
+    renamedAs: match[1],
+  };
+};
+
+/**
+ * given an ESM import statement as a string, it returns the default import alias if present
+ * @param {string} importStatement - the import statement to parse
+ * @returns {DefaultImportResults | undefined}
+ * if default import alias is present returns an object with the full match and the default import alias
+ *
+ * if no default import alias is present returns undefined
+ * @example
+ * defaultImport('import X from "Y"') // { fullMatch: 'import X from "Y"', renamedAs: 'X' }
+ * defaultImport('import X, { A, B } from "Y"') // { fullMatch: 'import X, { A, B } from "Y"', renamedAs: 'X' }
+ * defaultImport('import { A, B } from "Y"') // undefined
+ */
+const defaultImport = (importStatement) => {
+  const defaultImportRegex = /^import\s*(\w+)(?:,\s(?:\{(?:[\s\S](?!{))*?\}))*/gms;
+  // using matchAll because match doesn't preserve the capturing groups...
+  const matches = importStatement.matchAll(defaultImportRegex);
+  const match = [...matches][0];
+  if (!match) return undefined;
+  /** @type {DefaultImportResults} */
+  return {
+    fullMatch: importStatement,
+    renamedAs: match[1],
+  };
+};
+
+/**
+ * given the curly braces part of an ESM import statement, it returns the named imports with and without rename
+ * @param {string} curlyBracesImportString - the curly braces part of an ESM import statement
+ * @returns {NamedImportResults}
+ * an array with the named imports info
+ *
+ * if not named imports are present in the curly braces block the array will be empty (length 0)
+ * @example
+ * namedImports('{ A, B, C }')
+ * // [
+ * //   { partialFullMatch: 'A', component: 'A', renamedTo: undefined},
+ * //   { partialFullMatch: 'B', component: 'B', renamedTo: undefined},
+ * //   { partialFullMatch: 'C', component: 'C', renamedTo: undefined}
+ * // ]
+ * namedImports('{ A as X, B as Y, C as Z }')
+ * // [
+ * //   { partialFullMatch: 'A as X', component: 'A', renamedTo: 'X' },
+ * //   { partialFullMatch: 'B as Y', component: 'B', renamedTo: 'Y' },
+ * //   { partialFullMatch: 'C as Z', component: 'C', renamedTo: 'Z' }
+ * // ]
+ * namedImports('{ A, B as Y, C }')
+ * // [
+ * //   { partialFullMatch: 'B as Y', component: 'B', renamedTo: 'Y' }
+ * //   { partialFullMatch: 'A', component: 'A', renamedTo: undefined},
+ * //   { partialFullMatch: 'C', component: 'C', renamedTo: undefined}
+ * // ]
+ */
+const namedImports = (curlyBracesImportString) => {
+  // the following two regexps must be used in a previously "between braces" match to work as expected
+  const namedWithRenameRegex = /(\w+)\sas\s+(\w+)/gms;
+  const namedImportsWithoutRenameRegex =
+    /(?<=^[{\s]+)\w+\b(?!\b\s+as\s+\w+)|(?<=,\s+)\b\w+\b(?=\s*,)|(?<!(?:as)|(?:type)\s+)\b\w+(?=\s+})/gms;
+  // ----------
+  // using matchAll because match doesn't preserve the capturing groups...
+  const namedImportWithRenameMatches = [...curlyBracesImportString.matchAll(namedWithRenameRegex)];
+  const namedImportWithRename = namedImportWithRenameMatches.map((match) => ({
+    partialFullMatch: match[0],
+    component: match[1],
+    renamedTo: match[2],
+  }));
+  const namedImportWithoutRenameMatches = [...curlyBracesImportString.matchAll(namedImportsWithoutRenameRegex)];
+  const namedImportWithoutRename = namedImportWithoutRenameMatches.map((match) => ({
+    partialFullMatch: match[0],
+    component: match[0],
+    renamedTo: undefined,
+  }));
+  return [...namedImportWithRename, ...namedImportWithoutRename];
+};
+
+// const fileReset = (filePath) => {
+//   if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+// };
+
+// const fileUpsert = (filePath, content) => {
+//   const fileExists = fs.existsSync(filePath);
+//   if (!fileExists) fs.writeFileSync(filePath, content);
+//   else fs.appendFileSync(filePath, content);
+// };
+
+/**
+ * given a file path, it checks if the file contains any dimsum components
+ * @param {string} filePath - path to the file to check
+ * @returns {FileReport} - a report of the file
+ */
+export const getFileReport = (filePath) => {
+  const fileAsString = fs.readFileSync(filePath, 'utf8');
+  const matches = fileAsString.matchAll(dimsumImportStatementsRegExp);
+  const importStatements = [...matches]; // convert iterator to array - matchAll returns an iterator...
+
+  /** @type {FileReport} */
+  const fileReport = {
+    filePath,
+    hasRelationWithDimsum: importStatements.length > 0,
+    globalRenameImports: [],
+    importedDefaults: [],
+    importedNamedComponentsWithoutRename: [],
+    importedNamedComponentsWithRename: [],
+  };
+
+  importStatements.forEach((match) => {
+    const fullMatch = match[0];
+    const importedComponent = match[1];
+    const packageName = match[2];
+    const importAllAsInfo = renameAllAs(fullMatch);
+    const defaultImportInfo = defaultImport(fullMatch);
+    const partialNamedInfoData = namedImports(importedComponent);
+    if (importAllAsInfo) fileReport.globalRenameImports.push({ ...importAllAsInfo, packageName, fullMatch });
+    if (defaultImportInfo) fileReport.importedDefaults.push({ ...defaultImportInfo, packageName, fullMatch });
+    if (partialNamedInfoData.length !== 0)
+      partialNamedInfoData.forEach((partialNamedInfo) => {
+        const namedImportItem = {
+          component: partialNamedInfo.component,
+          packageName,
+          fullMatch,
+        };
+        if (partialNamedInfo.renamedTo)
+          fileReport.importedNamedComponentsWithRename.push({
+            ...namedImportItem,
+            renamedTo: partialNamedInfo.renamedTo,
+          });
+        else fileReport.importedNamedComponentsWithoutRename.push(namedImportItem);
+      });
+  });
+
+  return fileReport;
+};
+/**
+ * given a datum and a file path and options, generates a csv row
+ */
+const generateCSVRow = (datum, filePath, options) => {
+  // "Org(?),Imported Component,Repository(?),Package Name,Renamed Alias,File Path
+  const { importedComponent, packageName, renamedAs } = datum;
+  return `${options.org ? `${options.org},` : ''}${importedComponent},${
+    options.repo ? `${options.repo},` : ''
+  }${packageName},${renamedAs},${filePath}`;
+};
+
+/**
+ * given a file report, generates related csv rows (one or more)
+ * @param {FileReport} fileReport - the file report to generate the csv rows from
+ * @returns {string[]} - the csv rows flattened per relevant columns distinguishers
+ *
+ */
+const generateCSVRows = (fileReport, options) => {
+  const {
+    filePath,
+    hasRelationWithDimsum,
+    globalRenameImports,
+    importedDefaults,
+    importedNamedComponentsWithoutRename,
+    importedNamedComponentsWithRename,
+  } = fileReport;
+  const csvRows = [];
+  if (hasRelationWithDimsum) {
+    // opinionated way to describe a global rename import in the csv
+    // the opinion is: Imported Component: *, Renamed Alias: <the renamed alias>
+    if (globalRenameImports.length > 0) {
+      globalRenameImports.forEach((globalRenameImport) => {
+        csvRows.push(
+          generateCSVRow(
+            {
+              importedComponent: '*',
+              packageName: globalRenameImport.packageName,
+              renamedAs: globalRenameImport.renamedAs,
+            },
+            filePath,
+            options,
+          ),
+        );
+      });
+    }
+    // opinionated way to describe a default import in the csv
+    // the opinion is: Imported Component: 'default', Renamed Alias: <the renamed alias>
+    if (importedDefaults.length > 0) {
+      importedDefaults.forEach((importedDefault) => {
+        csvRows.push(
+          generateCSVRow(
+            {
+              importedComponent: 'default',
+              packageName: importedDefault.packageName,
+              renamedAs: importedDefault.renamedAs,
+            },
+            filePath,
+            options,
+          ),
+        );
+      });
+    }
+    // opinionated way to describe a named import that wasn't renamed in the csv
+    // the opinion is: Imported Component: <the named import>, Renamed Alias: ''
+    if (importedNamedComponentsWithoutRename.length > 0) {
+      importedNamedComponentsWithoutRename.forEach((importedNamedComponent) => {
+        csvRows.push(
+          generateCSVRow(
+            {
+              importedComponent: importedNamedComponent.component,
+              packageName: importedNamedComponent.packageName,
+              renamedAs: '',
+            },
+            filePath,
+            options,
+          ),
+        );
+      });
+    }
+
+    if (importedNamedComponentsWithRename.length > 0) {
+      importedNamedComponentsWithRename.forEach((importedNamedComponent) => {
+        csvRows.push(
+          generateCSVRow(
+            {
+              importedComponent: importedNamedComponent.component,
+              packageName: importedNamedComponent.packageName,
+              renamedAs: importedNamedComponent.renamedTo,
+            },
+            filePath,
+            options,
+          ),
+        );
+      });
+    }
+  }
+  return csvRows;
+};
+/**
+ * generates a report of 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 {string} options.org - optional org, if present an extra column will be added to the report
+ * @param {string} options.repo - optional repo, if present an extra column will be added to the report
+ * @param {boolean} options.debug - debug flag
+ * @param {boolean} options.append - whether to append to the file or override it
+ *
+ * @returns {string[]} - the csv rows, always starting with the header
+ */
+export const createCSVReport = (options) => {
+  const filesToParse = filePathsWithGitIgnore(options);
+
+  let csvRows = [
+    generateCSVRow(
+      { importedComponent: 'Imported Component', packageName: 'Package Name', renamedAs: 'Renamed Alias' },
+      'File Path',
+      { ...options, org: options.org ? 'Org' : undefined, repo: options.repo ? 'Repository' : undefined },
+    ),
+  ];
+
+  filesToParse.forEach((filePath) => {
+    const fileReport = getFileReport(filePath);
+    const fileCSVRows = generateCSVRows(fileReport, options);
+    csvRows.push(...fileCSVRows);
+  });
+
+  return csvRows;
+};

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

@@ -4,6 +4,7 @@ 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 { componentsUsageReport } from './components-usage-report/index.mjs';
 import { COMMANDS } from '../commands.mjs';
 
 export async function executeCommandsMap(args, options) {
@@ -29,6 +30,9 @@ export async function executeCommandsMap(args, options) {
     case COMMANDS.DEPRECATED_PACKAGES_USAGE_REPORT:
       deprecatedComponentsUsageReport(options);
       break;
+    case COMMANDS.COMPONENT_USAGE_REPORT:
+      componentsUsageReport(options);
+      break;
     default:
       break;
   }

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

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

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

@@ -27,6 +27,7 @@ async function promptForMissingScriptSpecificOptions({ originalOptions, promptOp
     case COMMANDS.HELP_MIGRATE_TO_V3:
       scriptQuestions.push(...getHelpMigrateToV3Questions(originalOptions));
       break;
+    case COMMANDS.COMPONENT_USAGE_REPORT:
     case COMMANDS.DEPRECATED_PACKAGES_USAGE_REPORT:
       scriptQuestions.push(...getDeprecatedUsageReportQuestions(originalOptions));
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-codemods",
-  "version": "3.31.0-next.3",
+  "version": "3.31.0-next.4",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Code Mods",
   "files": [
@@ -47,12 +47,15 @@
     "typeSafety": false
   },
   "scripts": {
-    "try-codemods": "npx ./",
     "dev:install": "pnpm --filter {.}... i --no-lockfile",
     "eslint:fix": "eslint --ext='.js,.jsx,.test.js,.ts,.tsx' --fix --config='../../.eslintrc.js' bin/",
-    "try-check-deprecated-packages": "npx ./ check-deprecated-packages --cwd=\"test-ables/check-deprecated-packages/with-deprecated\"",
-    "try-check-deprecated-packages-no-dimsum": "npx ./ check-deprecated-packages --cwd=\"test-ables/check-deprecated-packages/without-dimsum-packages\"",
-    "try-help-migrate-to-v3": "npx ./ help-migrate-to-v3 --globPattern=\"test-ables/help-migrate-to-v3/**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx\" --globPatternIgnore=\"**/node_modules/**/*\"",
+    "test-codemods": "npx ./",
+    "test-check-deprecated-packages": "npx ./ check-deprecated-packages --cwd=\"test-ables/check-deprecated-packages/with-deprecated\"",
+    "test-check-deprecated-packages-no-dimsum": "npx ./ check-deprecated-packages --cwd=\"test-ables/check-deprecated-packages/without-dimsum-packages\"",
+    "test-components-usage-report": "npx ./ components-usage-report --outputPath=\"./test.csv\" --startingDirPath=\"../../../environments\" --gitIgnorePath=\"../../../.gitignore\"",
+    "test-components-usage-report-complete": "npx ./ components-usage-report --outputPath=\"./test.csv\" --startingDirPath=\"../../../environments\" --gitIgnorePath=\"../../../.gitignore\" --repo=\"Dimsum\" --org=\"ICE\"",
+    "test-components-usage-report-complete-append": "npx ./ components-usage-report --outputPath=\"./test.csv\" --startingDirPath=\"../../../environments\" --gitIgnorePath=\"../../../.gitignore\" --repo=\"Dimsum2\" --org=\"ICE2\"",
+    "test-help-migrate-to-v3": "npx ./ help-migrate-to-v3 --globPattern=\"test-ables/help-migrate-to-v3/**/*.js,./**/*.jsx,./**/*.ts,./**/*.tsx\" --globPatternIgnore=\"**/node_modules/**/*\"",
     "create-package": "hygen package new",
     "create-part": "hygen part new",
     "checkDeps": "exit 0 | echo"