@georgewrmarshall/design-system-metrics 2.4.0 → 2.6.0

package/.claude/settings.local.json

@@ -21,7 +21,8 @@
       "Bash(yarn upgrade:*)",
       "Bash(yarn up:*)",
       "Bash(yarn npm info:*)",
-      "Bash(yarn remove:*)"
+      "Bash(yarn remove:*)",
+      "Bash(cat:*)"
     ],
     "deny": [],
     "ask": []

package/CHANGELOG.md

@@ -5,8 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-02-23
+
+### Added
+
+- **Complete MMDS Component List**: MMDS Usage sheet now shows all available MMDS components, including those with 0 instances
+  - Previously only showed components that were actively used
+  - Now displays the full component list with usage counts, making it easier to identify available but unused components
+  - Helps track MMDS component adoption opportunities
+
+- **Totals Rows**: All sheets now include totals at the bottom for easy summary analysis
+  - Migration Progress: Shows total deprecated instances, total MMDS instances, and overall migration percentage (with accurate deduplication)
+  - Intermediate Migrations: Shows total instances awaiting intermediate migration
+  - MMDS Usage: Shows total MMDS component instances across all components
+  - No Replacement: Shows total instances of components without direct replacements
+  - Console output now displays these totals for quick visibility
+
+- **Grouped Display with Summary Rows**: Migration Progress sheet now groups deprecated components by their MMDS replacement
+  - Components mapping to the same MMDS component are displayed together (e.g., all Icon variants grouped together)
+  - Individual rows show deprecated component details with "-" for MMDS instances and percentage to avoid misleading duplicates
+  - Summary rows (format: "→ Component Total") show aggregated deprecated count, MMDS instances, and accurate migration percentage for each group
+  - Single-mapping components continue to display normally with all columns filled
+  - Provides much more accurate and meaningful migration percentages
+
+### Fixed
+
+- **Migration Progress Totals**: Fixed duplicate counting when multiple deprecated components map to the same MMDS component
+  - Each MMDS component is counted only once in the total, providing accurate migration percentage
+  - Individual rows still show correct per-component breakdown
+
+- **Test Suite**: Updated tests to work with date-stamped output files
+  - Added helper function to dynamically find generated XLSX files
+  - All 14 tests passing
+
+## [2.5.0] - 2026-02-21
+
+### Fixed
+
+- **Version Number**: Corrected CLI version number in index.js to match package.json version (was incorrectly set to "3.0.0")
+
 ## [2.4.0] - 2026-02-21
 
+### Added
+
+- **Output File Date Stamps**: Generated XLSX files now automatically include today's date in the filename
+  - Format: `{project}-component-metrics-YYYY-MM-DD.xlsx`
+  - Example: `extension-component-metrics-2026-02-21.xlsx`
+  - Makes it easier to track metrics over time and compare historical data
+
 ### Changed
 
 - **Extension Component Mappings**: Corrected replacement targets to reflect actual migration state

package/__tests__/metrics.test.js

@@ -5,7 +5,13 @@ const ExcelJS = require('exceljs');
 
 const TEST_CONFIG = path.join(__dirname, 'fixtures/test-config.json');
 const OUTPUT_DIR = path.join(__dirname, 'output');
-const XLSX_OUTPUT = path.join(OUTPUT_DIR, 'test-metrics.xlsx');
+// Helper to get the generated XLSX file (with date stamp)
+const getXLSXOutput = async () => {
+  const files = await fs.readdir(OUTPUT_DIR);
+  const xlsxFile = files.find(f => f.startsWith('test-metrics-') && f.endsWith('.xlsx'));
+  return xlsxFile ? path.join(OUTPUT_DIR, xlsxFile) : null;
+};
+const XLSX_OUTPUT_BASE = 'test-metrics';
 
 describe('Design System Metrics', () => {
   beforeAll(() => {
@@ -50,12 +56,8 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
-      const exists = await fs
-        .access(XLSX_OUTPUT)
-        .then(() => true)
-        .catch(() => false);
-
-      expect(exists).toBe(true);
+      const XLSX_OUTPUT = await getXLSXOutput();
+      expect(XLSX_OUTPUT).not.toBeNull();
 
       const workbook = await readXLSX(XLSX_OUTPUT);
       const sheetNames = workbook.worksheets.map(ws => ws.name);
@@ -74,6 +76,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Migration Progress');
       const headers = data[0];
@@ -92,6 +95,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Migration Progress');
 
@@ -111,6 +115,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Migration Progress');
 
@@ -128,6 +133,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Path-Level Detail');
       const headers = data[0];
@@ -144,6 +150,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Path-Level Detail');
 
@@ -159,6 +166,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Path-Level Detail');
 
@@ -174,6 +182,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'Path-Level Detail');
 
@@ -190,6 +199,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'MMDS Usage');
       const headers = data[0];
@@ -205,6 +215,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'MMDS Usage');
 
@@ -222,6 +233,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'MMDS Usage');
 
@@ -237,6 +249,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'MMDS Usage');
 
@@ -253,6 +266,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'No Replacement');
       const headers = data[0];
@@ -269,6 +283,7 @@ describe('Design System Metrics', () => {
         { stdio: 'pipe' }
       );
 
+      const XLSX_OUTPUT = await getXLSXOutput();
       const workbook = await readXLSX(XLSX_OUTPUT);
       const data = getSheetData(workbook, 'No Replacement');
 

package/index.js

@@ -46,7 +46,7 @@ const validateConfig = (cfg) => {
 
 // Define CLI options using Commander
 program
-  .version("3.0.0")
+  .version("2.6.0")
   .description("Design System Metrics CLI Tool - Track component usage and migration progress")
   .requiredOption(
     "-p, --project <name>",
@@ -259,12 +259,19 @@ const main = async () => {
     rootFolder,
     ignoreFolders,
     filePattern,
-    outputFile,
+    outputFile: baseOutputFile,
     deprecatedComponents = {},
     currentComponents = [],
     currentPackages = [],
   } = projectConfig;
 
+  // Add today's date to the output filename
+  const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD format
+  const ext = path.extname(baseOutputFile);
+  const basename = path.basename(baseOutputFile, ext);
+  const dirname = path.dirname(baseOutputFile);
+  const outputFile = path.join(dirname, `${basename}-${today}${ext}`);
+
   const currentComponentsSet = new Set(currentComponents);
 
   console.log(chalk.blue(`\nStarting audit for project: ${projectName}\n`));
@@ -362,27 +369,99 @@ const main = async () => {
         (metrics.replacement.package.includes("@metamask/design-system"))
       );
 
+    // Group deprecated components by their MMDS replacement component
+    const groupedByMMDS = new Map();
     componentsWithMMDSReplacement.forEach(([componentName, metrics]) => {
       const mmdsComp = metrics.replacement.component;
-      const deprecatedCount = metrics.totalCount;
+      if (!groupedByMMDS.has(mmdsComp)) {
+        groupedByMMDS.set(mmdsComp, []);
+      }
+      groupedByMMDS.get(mmdsComp).push([componentName, metrics]);
+    });
+
+    let totalDeprecated = 0;
+    let totalMMDS = 0;
+
+    // Process each MMDS component group
+    for (const [mmdsComp, deprecatedComponents] of groupedByMMDS.entries()) {
       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)}%`,
-      ]);
-    });
+      if (deprecatedComponents.length === 1) {
+        // Single component mapping - show normally
+        const [componentName, metrics] = deprecatedComponents[0];
+        const deprecatedCount = metrics.totalCount;
+        const total = deprecatedCount + mmdsCount;
+        const percentage = total > 0 ? (mmdsCount / total) * 100 : 0;
+        const sourcePaths = config.projects[projectName].deprecatedComponents[componentName].paths.join(", ");
+
+        totalDeprecated += deprecatedCount;
+        totalMMDS += mmdsCount;
+
+        migrationSheet.addRow([
+          componentName,
+          sourcePaths,
+          mmdsComp,
+          deprecatedCount,
+          mmdsCount,
+          `${percentage.toFixed(2)}%`,
+        ]);
+      } else {
+        // Multiple components mapping to same MMDS component
+        let groupDeprecatedTotal = 0;
+
+        // Add individual rows (without MMDS count and percentage)
+        deprecatedComponents.forEach(([componentName, metrics]) => {
+          const deprecatedCount = metrics.totalCount;
+          const sourcePaths = config.projects[projectName].deprecatedComponents[componentName].paths.join(", ");
+
+          groupDeprecatedTotal += deprecatedCount;
+
+          migrationSheet.addRow([
+            componentName,
+            sourcePaths,
+            mmdsComp,
+            deprecatedCount,
+            "-",
+            "-",
+          ]);
+        });
+
+        // Add summary row for the group
+        const total = groupDeprecatedTotal + mmdsCount;
+        const percentage = total > 0 ? (mmdsCount / total) * 100 : 0;
+
+        migrationSheet.addRow([
+          `→ ${mmdsComp} Total`,
+          "",
+          mmdsComp,
+          groupDeprecatedTotal,
+          mmdsCount,
+          `${percentage.toFixed(2)}%`,
+        ]);
+
+        totalDeprecated += groupDeprecatedTotal;
+        totalMMDS += mmdsCount;
+      }
+    }
+
+    // Add totals row
+    const totalAll = totalDeprecated + totalMMDS;
+    const totalPercentage = totalAll > 0 ? (totalMMDS / totalAll) * 100 : 0;
+    migrationSheet.addRow([
+      "TOTAL",
+      "",
+      "",
+      totalDeprecated,
+      totalMMDS,
+      `${totalPercentage.toFixed(2)}%`,
+    ]);
 
     console.log(
       chalk.blue(`Migration Progress: ${componentsWithMMDSReplacement.length} components tracked`)
     );
+    console.log(
+      chalk.blue(`Total Migration: ${totalMMDS}/${totalAll} (${totalPercentage.toFixed(2)}%)`)
+    );
 
     // Sheet 2: Intermediate Migrations (components migrating to component-library)
     const intermediateSheet = workbook.addWorksheet("Intermediate Migrations");
@@ -400,11 +479,15 @@ const main = async () => {
         metrics.replacement.package === "component-library"
       );
 
+    let totalIntermediate = 0;
+
     componentsWithIntermediateReplacement.forEach(([componentName, metrics]) => {
       const oldPaths = deprecatedComponents[componentName].paths.join(", ");
       const newComponent = metrics.replacement.component;
       const newPath = metrics.replacement.path || metrics.replacement.package;
 
+      totalIntermediate += metrics.totalCount;
+
       intermediateSheet.addRow([
         componentName,
         oldPaths,
@@ -414,9 +497,21 @@ const main = async () => {
       ]);
     });
 
+    // Add totals row
+    intermediateSheet.addRow([
+      "TOTAL",
+      "",
+      "",
+      "",
+      totalIntermediate,
+    ]);
+
     console.log(
       chalk.blue(`Intermediate Migrations: ${componentsWithIntermediateReplacement.length} components tracked`)
     );
+    console.log(
+      chalk.blue(`Total Intermediate Instances: ${totalIntermediate}`)
+    );
 
     // Sheet 3: Path-Level Detail
     const pathDetailSheet = workbook.addWorksheet("Path-Level Detail");
@@ -446,15 +541,35 @@ const main = async () => {
     const mmdsSheet = workbook.addWorksheet("MMDS Usage");
     mmdsSheet.addRow(["Component", "Instances", "File Paths"]);
 
-    currentMetrics.forEach((metrics, componentName) => {
-      console.log(`${chalk.cyan(componentName)}: ${metrics.count} (MMDS)`);
+    // Include all MMDS components, even those with 0 instances
+    let totalMMDSUsage = 0;
+
+    currentComponentsSet.forEach((componentName) => {
+      const metrics = currentMetrics.get(componentName);
+      const count = metrics ? metrics.count : 0;
+      const files = metrics ? metrics.files.join(", ") : "";
+
+      totalMMDSUsage += count;
+
+      console.log(`${chalk.cyan(componentName)}: ${count} (MMDS)`);
       mmdsSheet.addRow([
         componentName,
-        metrics.count,
-        metrics.files.join(", "),
+        count,
+        files,
       ]);
     });
 
+    // Add totals row
+    mmdsSheet.addRow([
+      "TOTAL",
+      totalMMDSUsage,
+      "",
+    ]);
+
+    console.log(
+      chalk.blue(`Total MMDS Usage: ${totalMMDSUsage} instances`)
+    );
+
     // Sheet 5: No Replacement Components
     const noReplacementSheet = workbook.addWorksheet("No Replacement");
     noReplacementSheet.addRow(["Component", "Path", "Instances", "File Paths"]);
@@ -462,8 +577,12 @@ const main = async () => {
     const componentsWithNoReplacement = Array.from(deprecatedMetrics.entries())
       .filter(([, metrics]) => !metrics.replacement);
 
+    let totalNoReplacement = 0;
+
     componentsWithNoReplacement.forEach(([componentName, metrics]) => {
       const paths = deprecatedComponents[componentName].paths.join(", ");
+      totalNoReplacement += metrics.totalCount;
+
       noReplacementSheet.addRow([
         componentName,
         paths,
@@ -472,9 +591,20 @@ const main = async () => {
       ]);
     });
 
+    // Add totals row
+    noReplacementSheet.addRow([
+      "TOTAL",
+      "",
+      totalNoReplacement,
+      "",
+    ]);
+
     console.log(
       chalk.blue(`No Replacement: ${componentsWithNoReplacement.length} components`)
     );
+    console.log(
+      chalk.blue(`Total No Replacement Instances: ${totalNoReplacement}`)
+    );
 
     // Create output directory if it doesn't exist
     const outputDir = path.dirname(outputFile);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@georgewrmarshall/design-system-metrics",
-  "version": "2.4.0",
+  "version": "2.6.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",