@georgewrmarshall/design-system-metrics 2.2.0 → 2.4.0

package/index.js

@@ -7,6 +7,7 @@ const babelParser = require("@babel/parser");
 const traverse = require("@babel/traverse").default;
 const { program } = require("commander");
 const chalk = require("chalk");
+const ExcelJS = require("exceljs");
 
 let config;
 
@@ -15,6 +16,7 @@ const loadConfig = async (configPath) => {
   try {
     const configContent = await fs.readFile(configPath, "utf8");
     config = JSON.parse(configContent);
+    validateConfig(config);
   } catch (err) {
     console.error(
       chalk.red(`Failed to load configuration file: ${err.message}`)
@@ -23,20 +25,33 @@ const loadConfig = async (configPath) => {
   }
 };
 
+// Validate config structure
+const validateConfig = (cfg) => {
+  if (!cfg.projects || typeof cfg.projects !== 'object') {
+    throw new Error('Config must have a "projects" object');
+  }
+
+  for (const [projectName, projectCfg] of Object.entries(cfg.projects)) {
+    if (projectCfg.deprecatedComponents && typeof projectCfg.deprecatedComponents !== 'object') {
+      throw new Error(`Project "${projectName}" deprecatedComponents must be an object`);
+    }
+
+    // Check if using old array format
+    if (Array.isArray(projectCfg.deprecatedComponents)) {
+      console.warn(chalk.yellow(`\nWarning: Project "${projectName}" is using the old array format for deprecatedComponents.`));
+      console.warn(chalk.yellow('Please migrate to the new object format with paths and replacement info.\n'));
+    }
+  }
+};
+
 // Define CLI options using Commander
 program
-  .version("2.1.0")
-  .description("Design System Metrics CLI Tool - Track component usage from multiple sources")
+  .version("3.0.0")
+  .description("Design System Metrics CLI Tool - Track component usage and migration progress")
   .requiredOption(
     "-p, --project <name>",
     "Specify the project to audit (e.g., extension, mobile)"
   )
-  .option("-f, --format <type>", "Output format (csv, json)", "csv")
-  .option(
-    "-s, --sources <types>",
-    "Comma-separated list of sources to track (deprecated, current, all)",
-    "all"
-  )
   .option(
     "-c, --config <path>",
     "Path to custom config file",
@@ -47,34 +62,80 @@ program
 const options = program.opts();
 
 // Initialize component instances and file mappings
-// Structure: Map<componentName, Map<source, { count, files }>>
+// Structure: Map<componentName, Map<source, Map<specificPath, { count, files }>>>
 let componentMetrics = new Map();
 
-// Helper function to track component usage by source
-const trackComponent = (componentName, source, filePath) => {
+// Helper function to track component usage by source and specific path
+const trackComponent = (componentName, source, specificPath, filePath) => {
   if (!componentMetrics.has(componentName)) {
     componentMetrics.set(componentName, new Map());
   }
 
   const sourceMetrics = componentMetrics.get(componentName);
   if (!sourceMetrics.has(source)) {
-    sourceMetrics.set(source, { count: 0, files: [] });
+    sourceMetrics.set(source, new Map());
   }
 
-  const metrics = sourceMetrics.get(source);
+  const pathMetrics = sourceMetrics.get(source);
+  if (!pathMetrics.has(specificPath)) {
+    pathMetrics.set(specificPath, { count: 0, files: [] });
+  }
+
+  const metrics = pathMetrics.get(specificPath);
   metrics.count++;
   metrics.files.push(filePath);
 };
 
+// Helper function to check if import path matches any component paths
+const matchComponentPath = (importPath, deprecatedComponents) => {
+  // Normalize the import path
+  const normalizedImportPath = importPath.replace(/\\/g, '/');
+
+  for (const [componentName, config] of Object.entries(deprecatedComponents)) {
+    for (const componentPath of config.paths) {
+      // Normalize the component path
+      const normalizedComponentPath = componentPath.replace(/\\/g, '/');
+
+      // Check for exact match
+      if (normalizedImportPath === normalizedComponentPath) {
+        return { componentName, matchedPath: componentPath };
+      }
+
+      // Check if import path ends with the component path (relative imports)
+      if (normalizedImportPath.endsWith(normalizedComponentPath)) {
+        return { componentName, matchedPath: componentPath };
+      }
+
+      // Check if import path includes key parts of component path
+      // e.g., "../../components/component-library" matches "*/component-library/*"
+      const pathParts = normalizedComponentPath.split('/');
+      const importParts = normalizedImportPath.split('/');
+
+      // If import includes "/component-library" and path includes "/component-library"
+      if (normalizedImportPath.includes('/component-library') &&
+          normalizedComponentPath.includes('/component-library')) {
+        return { componentName, matchedPath: componentPath };
+      }
+
+      // Check for package imports (e.g., react-native-vector-icons/*)
+      if (normalizedComponentPath.includes(normalizedImportPath)) {
+        return { componentName, matchedPath: componentPath };
+      }
+    }
+  }
+  return null;
+};
+
 // Function to process a single file
 const processFile = async (
   filePath,
-  deprecatedComponentsSet,
+  deprecatedComponents,
   currentComponentsSet,
   currentPackages
 ) => {
-  // Track imports by source: Map<componentName, source>
+  // Track imports by source: Map<componentName, { source, specificPath }>
   const componentImports = new Map();
+
   try {
     const content = await fs.readFile(filePath, "utf8");
 
@@ -82,64 +143,61 @@ const processFile = async (
     const ast = babelParser.parse(content, {
       sourceType: "module",
       plugins: ["jsx", "typescript"],
-      attachComment: true, // Enable comment attachment for JSDoc parsing
+      attachComment: true,
     });
 
     // Traverse the AST to find import declarations from multiple sources
     traverse(ast, {
       ImportDeclaration({ node }) {
         const importPath = node.source.value;
-        console.log(`Import path detected: ${importPath}`);
 
         let source = null;
+        let specificPath = null;
 
-        // Check if it's from local component library (DEPRECATED)
-        if (importPath.includes("/component-library")) {
+        // Check if it's a deprecated component from local paths
+        const deprecatedMatch = matchComponentPath(importPath, deprecatedComponents);
+        if (deprecatedMatch) {
           source = "deprecated";
-        }
-        // Check if it's from current NPM packages
-        else if (currentPackages && currentPackages.length > 0) {
-          for (const pkg of currentPackages) {
-            if (importPath === pkg || importPath.startsWith(`${pkg}/`)) {
-              source = "current";
-              break;
-            }
-          }
-        }
+          specificPath = deprecatedMatch.matchedPath;
 
-        // If we found a relevant import source, track the components
-        if (source) {
           node.specifiers.forEach((specifier) => {
             let componentName = null;
 
             if (specifier.type === "ImportDefaultSpecifier") {
               componentName = specifier.local.name;
-              console.log(
-                `Default imported component: ${componentName} (${source})`
-              );
             } else if (specifier.type === "ImportSpecifier") {
               componentName = specifier.local.name;
-              console.log(`Named imported component: ${componentName} (${source})`);
             }
 
-            if (componentName) {
-              // Check if component is in deprecated list (for local imports)
-              if (
-                source === "deprecated" &&
-                deprecatedComponentsSet.has(componentName)
-              ) {
-                componentImports.set(componentName, source);
-              }
-              // Check if component is in current list (for NPM imports)
-              else if (
-                source === "current" &&
-                currentComponentsSet.has(componentName)
-              ) {
-                componentImports.set(componentName, source);
-              }
+            if (componentName && deprecatedComponents[componentName]) {
+              componentImports.set(componentName, { source, specificPath });
             }
           });
         }
+        // Check if it's from current NPM packages
+        else if (currentPackages && currentPackages.length > 0) {
+          for (const pkg of currentPackages) {
+            if (importPath === pkg || importPath.startsWith(`${pkg}/`)) {
+              source = "current";
+              specificPath = pkg;
+
+              node.specifiers.forEach((specifier) => {
+                let componentName = null;
+
+                if (specifier.type === "ImportDefaultSpecifier") {
+                  componentName = specifier.local.name;
+                } else if (specifier.type === "ImportSpecifier") {
+                  componentName = specifier.local.name;
+                }
+
+                if (componentName && currentComponentsSet.has(componentName)) {
+                  componentImports.set(componentName, { source, specificPath });
+                }
+              });
+              break;
+            }
+          }
+        }
       },
     });
 
@@ -166,16 +224,10 @@ const processFile = async (
             componentName = current.name;
           }
 
-          console.log(`JSX component detected: ${componentName}`);
-
           // Check if this component was imported and track its usage
           if (componentImports.has(componentName)) {
-            const source = componentImports.get(componentName);
-            trackComponent(componentName, source, filePath);
-
-            console.log(
-              `Matched JSX component: ${componentName}, Source: ${source}`
-            );
+            const { source, specificPath } = componentImports.get(componentName);
+            trackComponent(componentName, source, specificPath, filePath);
           }
         }
       },
@@ -208,12 +260,11 @@ const main = async () => {
     ignoreFolders,
     filePattern,
     outputFile,
-    deprecatedComponents = [],
+    deprecatedComponents = {},
     currentComponents = [],
     currentPackages = [],
   } = projectConfig;
 
-  const deprecatedComponentsSet = new Set(deprecatedComponents);
   const currentComponentsSet = new Set(currentComponents);
 
   console.log(chalk.blue(`\nStarting audit for project: ${projectName}\n`));
@@ -236,95 +287,207 @@ const main = async () => {
       files.map((file) =>
         processFile(
           file,
-          deprecatedComponentsSet,
+          deprecatedComponents,
           currentComponentsSet,
           currentPackages
         )
       )
     );
 
-    console.log(chalk.green("\nComponent Migration Metrics:"));
+    console.log(chalk.green("\nGenerating Component Migration Metrics...\n"));
+
+    // Collect metrics by component and calculate totals
+    const deprecatedMetrics = new Map(); // Map<componentName, { totalCount, pathBreakdown, files }>
+    const currentMetrics = new Map(); // Map<componentName, { count, files }>
+
+    // Aggregate deprecated metrics across all paths
+    for (const [componentName, componentConfig] of Object.entries(deprecatedComponents)) {
+      const componentSources = componentMetrics.get(componentName);
+      if (componentSources && componentSources.has("deprecated")) {
+        const pathMetrics = componentSources.get("deprecated");
+        let totalCount = 0;
+        const pathBreakdown = new Map();
+        const allFiles = [];
+
+        for (const [specificPath, metrics] of pathMetrics.entries()) {
+          totalCount += metrics.count;
+          pathBreakdown.set(specificPath, metrics);
+          allFiles.push(...metrics.files);
+        }
 
-    // Parse sources filter from CLI
-    let requestedSources = ["deprecated", "current"];
-    if (options.sources && options.sources !== "all") {
-      requestedSources = options.sources.split(",").map((s) => s.trim());
+        deprecatedMetrics.set(componentName, {
+          totalCount,
+          pathBreakdown,
+          files: allFiles,
+          replacement: componentConfig.replacement,
+        });
+      }
     }
 
-    const sourceTypes = requestedSources;
-
-    for (const sourceType of sourceTypes) {
-      // Filter component metrics for this source type
-      const sourceMetrics = new Map();
-
-      // Determine which component set to use based on source type
-      const componentSet =
-        sourceType === "deprecated"
-          ? deprecatedComponentsSet
-          : currentComponentsSet;
-
-      componentSet.forEach((componentName) => {
-        const componentSources = componentMetrics.get(componentName);
-        if (componentSources) {
-          const metrics = componentSources.get(sourceType);
-          if (metrics) {
-            sourceMetrics.set(componentName, metrics);
-          }
+    // Collect current (MMDS) metrics
+    currentComponentsSet.forEach((componentName) => {
+      const componentSources = componentMetrics.get(componentName);
+      if (componentSources && componentSources.has("current")) {
+        const pathMetrics = componentSources.get("current");
+        let totalCount = 0;
+        const allFiles = [];
+
+        for (const [, metrics] of pathMetrics.entries()) {
+          totalCount += metrics.count;
+          allFiles.push(...metrics.files);
         }
-      });
 
-      // Skip if no metrics for this source
-      if (sourceMetrics.size === 0) {
-        console.log(
-          chalk.yellow(
-            `No ${sourceType} components found, skipping report.`
-          )
-        );
-        continue;
+        currentMetrics.set(componentName, { count: totalCount, files: allFiles });
       }
+    });
 
-      // Generate output file name
-      const baseFileName = outputFile.replace(/\.(csv|json)$/, "");
-      const sourceOutputFile = `${baseFileName}-${sourceType}.${options.format.toLowerCase()}`;
+    // Generate XLSX file with multiple sheets using ExcelJS
+    const workbook = new ExcelJS.Workbook();
+
+    // Sheet 1: Migration Progress (components migrating to MMDS)
+    const migrationSheet = workbook.addWorksheet("Migration Progress");
+    migrationSheet.addRow([
+      "Deprecated Component",
+      "Source Paths",
+      "MMDS Component",
+      "Deprecated Instances",
+      "MMDS Instances",
+      "Migrated %",
+    ]);
+
+    const componentsWithMMDSReplacement = Array.from(deprecatedMetrics.entries())
+      .filter(([, metrics]) =>
+        metrics.replacement &&
+        metrics.replacement.package &&
+        (metrics.replacement.package.includes("@metamask/design-system"))
+      );
 
-      console.log(
-        chalk.blue(
-          `\n${sourceType.toUpperCase()} Components (${sourceType === "deprecated" ? "Local component-library" : currentPackages.join(", ")}):`
-        )
+    componentsWithMMDSReplacement.forEach(([componentName, metrics]) => {
+      const mmdsComp = metrics.replacement.component;
+      const deprecatedCount = metrics.totalCount;
+      const mmdsCount = currentMetrics.get(mmdsComp)?.count || 0;
+      const total = deprecatedCount + mmdsCount;
+      const percentage = total > 0 ? (mmdsCount / total) * 100 : 0;
+      const sourcePaths = deprecatedComponents[componentName].paths.join(", ");
+
+      migrationSheet.addRow([
+        componentName,
+        sourcePaths,
+        mmdsComp,
+        deprecatedCount,
+        mmdsCount,
+        `${percentage.toFixed(2)}%`,
+      ]);
+    });
+
+    console.log(
+      chalk.blue(`Migration Progress: ${componentsWithMMDSReplacement.length} components tracked`)
+    );
+
+    // Sheet 2: Intermediate Migrations (components migrating to component-library)
+    const intermediateSheet = workbook.addWorksheet("Intermediate Migrations");
+    intermediateSheet.addRow([
+      "Old Component",
+      "Old Path",
+      "New Component",
+      "New Package/Path",
+      "Instances",
+    ]);
+
+    const componentsWithIntermediateReplacement = Array.from(deprecatedMetrics.entries())
+      .filter(([, metrics]) =>
+        metrics.replacement &&
+        metrics.replacement.package === "component-library"
       );
 
-      if (options.format.toLowerCase() === "json") {
-        const jsonOutput = {};
-        sourceMetrics.forEach((metrics, componentName) => {
-          console.log(`${chalk.cyan(componentName)}: ${metrics.count}`);
-          jsonOutput[componentName] = {
-            instances: metrics.count,
-            files: metrics.files,
-          };
-        });
+    componentsWithIntermediateReplacement.forEach(([componentName, metrics]) => {
+      const oldPaths = deprecatedComponents[componentName].paths.join(", ");
+      const newComponent = metrics.replacement.component;
+      const newPath = metrics.replacement.path || metrics.replacement.package;
+
+      intermediateSheet.addRow([
+        componentName,
+        oldPaths,
+        newComponent,
+        newPath,
+        metrics.totalCount,
+      ]);
+    });
 
-        await fs.writeFile(
-          sourceOutputFile,
-          JSON.stringify(jsonOutput, null, 2)
-        );
-      } else {
-        // CSV format
-        let csvContent = "Component,Instances,File Paths\n";
-
-        sourceMetrics.forEach((metrics, componentName) => {
-          console.log(`${chalk.cyan(componentName)}: ${metrics.count}`);
-          csvContent += `"${componentName}",${metrics.count},"${metrics.files.join(", ")}"\n`;
-        });
+    console.log(
+      chalk.blue(`Intermediate Migrations: ${componentsWithIntermediateReplacement.length} components tracked`)
+    );
 
-        await fs.writeFile(sourceOutputFile, csvContent);
-      }
+    // Sheet 3: Path-Level Detail
+    const pathDetailSheet = workbook.addWorksheet("Path-Level Detail");
+    pathDetailSheet.addRow([
+      "Component",
+      "Specific Path",
+      "Instances",
+      "File Paths",
+    ]);
+
+    deprecatedMetrics.forEach((metrics, componentName) => {
+      metrics.pathBreakdown.forEach((pathMetrics, specificPath) => {
+        pathDetailSheet.addRow([
+          componentName,
+          specificPath,
+          pathMetrics.count,
+          pathMetrics.files.join(", "),
+        ]);
+      });
+    });
 
-      console.log(chalk.green(`Metrics written to ${sourceOutputFile}`));
-    }
+    console.log(
+      chalk.blue(`Path-Level Detail: ${deprecatedMetrics.size} components with path breakdowns`)
+    );
+
+    // Sheet 4: MMDS Usage
+    const mmdsSheet = workbook.addWorksheet("MMDS Usage");
+    mmdsSheet.addRow(["Component", "Instances", "File Paths"]);
+
+    currentMetrics.forEach((metrics, componentName) => {
+      console.log(`${chalk.cyan(componentName)}: ${metrics.count} (MMDS)`);
+      mmdsSheet.addRow([
+        componentName,
+        metrics.count,
+        metrics.files.join(", "),
+      ]);
+    });
+
+    // Sheet 5: No Replacement Components
+    const noReplacementSheet = workbook.addWorksheet("No Replacement");
+    noReplacementSheet.addRow(["Component", "Path", "Instances", "File Paths"]);
+
+    const componentsWithNoReplacement = Array.from(deprecatedMetrics.entries())
+      .filter(([, metrics]) => !metrics.replacement);
+
+    componentsWithNoReplacement.forEach(([componentName, metrics]) => {
+      const paths = deprecatedComponents[componentName].paths.join(", ");
+      noReplacementSheet.addRow([
+        componentName,
+        paths,
+        metrics.totalCount,
+        metrics.files.join(", "),
+      ]);
+    });
+
+    console.log(
+      chalk.blue(`No Replacement: ${componentsWithNoReplacement.length} components`)
+    );
+
+    // Create output directory if it doesn't exist
+    const outputDir = path.dirname(outputFile);
+    await fs.mkdir(outputDir, { recursive: true });
+
+    // Write the XLSX file
+    await workbook.xlsx.writeFile(outputFile);
 
-    console.log(chalk.green("\n✓ All reports generated successfully!\n"));
+    console.log(chalk.green(`\n✓ Metrics written to ${outputFile}`));
+    console.log(chalk.green("✓ All reports generated successfully!\n"));
   } catch (err) {
-    console.error(chalk.red(`Error reading files: ${err.message}`));
+    console.error(chalk.red(`Error: ${err.message}`));
+    console.error(chalk.red(err.stack));
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@georgewrmarshall/design-system-metrics",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "A CLI tool to audit design system component usage from local libraries, NPM packages, and track deprecated components across MetaMask codebases",
   "main": "index.js",
   "packageManager": "yarn@4.3.1",
@@ -25,6 +25,7 @@
     "brace-expansion": "^4.0.0",
     "chalk": "^4.1.2",
     "commander": "^12.1.0",
+    "exceljs": "^4.4.0",
     "glob": "^11.0.0"
   },
   "devDependencies": {