@georgewrmarshall/design-system-metrics 1.0.0

package/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,json,yml}]
+charset = utf-8
+indent_style = space
+indent_size = 2

package/.gitattributes

@@ -0,0 +1,4 @@
+/.yarn/**            linguist-vendored
+/.yarn/releases/*    binary
+/.yarn/plugins/**/*  binary
+/.pnp.*              binary linguist-generated

package/README.md

@@ -0,0 +1,117 @@
+# **@georgewrmarshall/design-system-metrics**
+
+A CLI tool to audit design system component usage across multiple MetaMask codebases
+
+## **Getting Started**
+
+- [Extension](#extension)
+- [Mobile](#mobile)
+- [CLI Options](#cli-options)
+- [Requirements](#requirements)
+
+---
+
+### **Extension**
+
+1. **Clone the [MetaMask Extension](https://github.com/MetaMask/metamask-extension)** repository if you haven’t already:
+
+```bash
+git clone https://github.com/MetaMask/metamask-extension.git
+```
+
+2. **Run the CLI tool from the `@georgewrmarshall/design-system-metrics` package:**
+
+Navigate to the `@georgewrmarshall/design-system-metrics` package directory:
+
+```bash
+cd /path/to/@georgewrmarshall/design-system-metrics
+```
+
+3. **Run the CLI tool for the MetaMask Extension:**
+
+```bash
+yarn node index.js --project extension
+```
+
+4. A file called `extension-component-adoption-metrics.csv` will be generated in the current working directory if there are no errors.
+
+---
+
+### **Mobile**
+
+1. **Clone the [MetaMask Mobile](https://github.com/MetaMask/metamask-mobile)** repository if you haven’t already:
+
+```bash
+git clone https://github.com/MetaMask/metamask-mobile.git
+```
+
+2. **Run the CLI tool from the `@georgewrmarshall/design-system-metrics` package:**
+
+Navigate to the `@georgewrmarshall/design-system-metrics` package directory:
+
+```bash
+cd /path/to/@georgewrmarshall/design-system-metrics
+```
+
+3. **Run the CLI tool for the MetaMask Mobile project:**
+
+```bash
+yarn node index.js --project mobile
+```
+
+4. A file called `mobile-component-adoption-metrics.csv` will be generated in the current working directory if there are no errors.
+
+---
+
+### **CLI Options**
+
+- **`--project` (Required)**: Specify the project to audit. Options are:
+
+- `extension`: For MetaMask Extension
+- `mobile`: For MetaMask Mobile
+
+Example:
+
+```bash
+yarn node index.js --project extension
+```
+
+- **`--format` (Optional)**: Specify the output format. Options are `csv` (default) or `json`.
+
+Example:
+
+```bash
+yarn node index.js --project extension --format json
+```
+
+- **Custom Configuration**: By default, the tool uses a `config.json` file to define the component list and ignore patterns. You can also pass a custom configuration file by adding the `--config` option:
+
+```bash
+yarn node index.js --project extension --config /path/to/custom-config.json
+```
+
+---
+
+### **Requirements**
+
+- The tool **ignores deprecated components** (e.g., `component-library/deprecated`).
+- The tool **does not count duplicate components** when imported from different locations (e.g., `<Button` from `../../ui/button` versus `<Button` from `../../component-library`).
+- Components **inside JSDoc comments** are not counted (e.g., `@deprecated <Box /> is deprecated in favour of <Box />`).
+
+---
+
+### **Example Output**
+
+Upon running the CLI tool, a CSV file will be generated in the root of the repository (e.g., `extension-component-adoption-metrics.csv` or `mobile-component-adoption-metrics.csv`), listing the components and the number of instances where they are used.
+
+---
+
+### **Contributing**
+
+If you wish to contribute to the tool, ensure you are running the latest version of **Yarn (v4.x)** and **Node.js**. You can make adjustments to the `config.json` file or update the CLI logic for tracking additional components or repositories.
+
+---
+
+### **License**
+
+This project is licensed under the [MIT License](LICENSE).

package/config.json

@@ -0,0 +1,123 @@
+{
+  "projects": {
+    "extension": {
+      "rootFolder": "ui",
+      "ignoreFolders": ["ui/components/component-library"],
+      "filePattern": "ui/**/*.{js,tsx}",
+      "outputFile": "extension-component-adoption-metrics.csv",
+      "components": [
+        "AvatarAccount",
+        "AvatarBase",
+        "AvatarFavicon",
+        "AvatarIcon",
+        "AvatarNetwork",
+        "AvatarToken",
+        "BadgeWrapper",
+        "BannerAlert",
+        "BannerBase",
+        "BannerTip",
+        "Box",
+        "Button",
+        "ButtonBase",
+        "ButtonIcon",
+        "ButtonLink",
+        "ButtonPrimary",
+        "ButtonSecondary",
+        "Checkbox",
+        "Container",
+        "FormTextField",
+        "HeaderBase",
+        "HelpText",
+        "Icon",
+        "Input",
+        "Label",
+        "Modal",
+        "ModalBody",
+        "ModalContent",
+        "ModalFocus",
+        "ModalFooter",
+        "ModalHeader",
+        "ModalOverlay",
+        "PickerNetwork",
+        "Popover",
+        "PopoverHeader",
+        "SelectButton",
+        "SelectOption",
+        "SelectWrapper",
+        "Tag",
+        "TagUrl",
+        "Text",
+        "TextField",
+        "TextFieldSearch"
+      ]
+    },
+    "mobile": {
+      "rootFolder": "app",
+      "ignoreFolders": ["app/component-library"],
+      "filePattern": "app/components/**/*.{js,tsx}",
+      "outputFile": "mobile-component-adoption-metrics.csv",
+      "components": [
+        "Accordion",
+        "Avatar",
+        "AvatarAccount",
+        "AvatarBase",
+        "AvatarFavicon",
+        "AvatarGroup",
+        "AvatarIcon",
+        "AvatarNetwork",
+        "AvatarToken",
+        "Badge",
+        "BadgeBase",
+        "BadgeNetwork",
+        "BadgeStatus",
+        "BadgeWrapper",
+        "Banner",
+        "BannerAlert",
+        "BannerBase",
+        "BannerTip",
+        "BottomSheet",
+        "BottomSheetFooter",
+        "BottomSheetHeader",
+        "Button",
+        "ButtonBase",
+        "ButtonIcon",
+        "ButtonLink",
+        "ButtonPrimary",
+        "ButtonSecondary",
+        "Card",
+        "Cell",
+        "CellBase",
+        "CellDisplay",
+        "CellMultiSelect",
+        "CellSelect",
+        "Checkbox",
+        "Header",
+        "HelpText",
+        "Icon",
+        "Input",
+        "Label",
+        "ListItem",
+        "ListItemColumn",
+        "ModalConfirmation",
+        "ModalMadatory",
+        "MultiSelectItem",
+        "Overlay",
+        "PickerAccount",
+        "PickerBase",
+        "PickerNetwork",
+        "SelectItem",
+        "SheetBottom",
+        "SheetHeader",
+        "TabBar",
+        "TabBarItem",
+        "Tag",
+        "TagUrl",
+        "Text",
+        "TextField",
+        "TextFieldSearch",
+        "TextWithPrefixIcon",
+        "Toast"
+      ]
+    }
+  }
+}

package/index.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+const fs = require("fs").promises;
+const { glob } = require("glob");
+const path = require("path");
+const babelParser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+const { program } = require("commander");
+const chalk = require("chalk");
+
+// Load configuration
+const CONFIG_PATH = path.join(__dirname, "config.json");
+let config;
+
+// Function to load and parse the configuration file
+const loadConfig = async () => {
+  try {
+    const configContent = await fs.readFile(CONFIG_PATH, "utf8");
+    config = JSON.parse(configContent);
+  } catch (err) {
+    console.error(
+      chalk.red(`Failed to load configuration file: ${err.message}`)
+    );
+    process.exit(1);
+  }
+};
+
+// Define CLI options using Commander
+program
+  .version("1.0.0")
+  .description("Design System Metrics CLI Tool")
+  .requiredOption(
+    "-p, --project <name>",
+    "Specify the project to audit (e.g., extension, mobile)"
+  )
+  .option("-f, --format <type>", "Output format (csv, json)", "csv")
+  .parse(process.argv);
+
+const options = program.opts();
+
+// Initialize component instances and file mappings
+let componentInstances = new Map();
+let componentFiles = new Map();
+
+// Function to process a single file
+const processFile = async (filePath, componentsSet, importedComponentsSet) => {
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+
+    // Parse the file content into an AST
+    const ast = babelParser.parse(content, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+    });
+
+    // Traverse the AST to find import declarations from the component library
+    traverse(ast, {
+      ImportDeclaration({ node }) {
+        const importPath = node.source.value;
+        if (importPath.includes("/component-library")) {
+          node.specifiers.forEach((specifier) => {
+            if (specifier.type === "ImportSpecifier") {
+              importedComponentsSet.add(specifier.imported.name);
+            }
+          });
+        }
+      },
+    });
+
+    // Traverse the AST to find JSX elements
+    traverse(ast, {
+      JSXElement({ node }) {
+        const openingElement = node.openingElement;
+        if (
+          openingElement &&
+          openingElement.name &&
+          (openingElement.name.type === "JSXIdentifier" ||
+            openingElement.name.type === "JSXMemberExpression")
+        ) {
+          let componentName = "";
+
+          if (openingElement.name.type === "JSXIdentifier") {
+            componentName = openingElement.name.name;
+          } else if (openingElement.name.type === "JSXMemberExpression") {
+            // Handle namespaced components like <UI.Button>
+            let current = openingElement.name;
+            while (current.object) {
+              current = current.object;
+            }
+            componentName = current.name;
+          }
+
+          if (
+            componentsSet.has(componentName) &&
+            importedComponentsSet.has(componentName)
+          ) {
+            const count = componentInstances.get(componentName) || 0;
+            componentInstances.set(componentName, count + 1);
+
+            const files = componentFiles.get(componentName) || [];
+            files.push(filePath);
+            componentFiles.set(componentName, files);
+          }
+        }
+      },
+    });
+  } catch (err) {
+    console.error(
+      chalk.yellow(`Error processing file ${filePath}: ${err.message}`)
+    );
+  }
+};
+
+// Main function to coordinate the audit
+const main = async () => {
+  await loadConfig();
+
+  const projectName = options.project;
+  const projectConfig = config.projects[projectName];
+
+  if (!projectConfig) {
+    console.error(
+      chalk.red(
+        `Project "${projectName}" is not defined in the configuration file.`
+      )
+    );
+    process.exit(1);
+  }
+
+  const { rootFolder, ignoreFolders, filePattern, outputFile, components } =
+    projectConfig;
+
+  const componentsSet = new Set(components);
+
+  console.log(chalk.blue(`\nStarting audit for project: ${projectName}\n`));
+
+  try {
+    const files = await glob(filePattern, {
+      ignore: [
+        ...ignoreFolders.map((folder) => path.join(folder, "**")),
+        `${rootFolder}/**/*.test.{js,tsx}`,
+      ],
+    });
+
+    if (files.length === 0) {
+      console.log(chalk.yellow("No files matched the provided pattern."));
+      return;
+    }
+
+    // Process files concurrently
+    await Promise.all(
+      files.map((file) => processFile(file, componentsSet, new Set()))
+    );
+
+    console.log(chalk.green("\nComponent Adoption Metrics:"));
+
+    let csvContent = "Component,Instances,File Paths\n";
+    let jsonOutput = {};
+
+    componentsSet.forEach((componentName) => {
+      const instanceCount = componentInstances.get(componentName) || 0;
+      const filePaths = componentFiles.get(componentName) || [];
+      console.log(`${chalk.cyan(componentName)}: ${instanceCount}`);
+
+      if (options.format.toLowerCase() === "json") {
+        jsonOutput[componentName] = {
+          instances: instanceCount,
+          files: filePaths,
+        };
+      } else {
+        csvContent += `"${componentName}",${instanceCount},"${filePaths.join(
+          ", "
+        )}"\n`;
+      }
+    });
+
+    // Write the metrics to the specified output file
+    try {
+      if (options.format.toLowerCase() === "json") {
+        await fs.writeFile(outputFile, JSON.stringify(jsonOutput, null, 2));
+      } else {
+        await fs.writeFile(outputFile, csvContent);
+      }
+      console.log(
+        chalk.green(`\nComponent metrics written to ${outputFile}\n`)
+      );
+    } catch (err) {
+      console.error(chalk.red(`Error writing to file: ${err.message}`));
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error reading files: ${err.message}`));
+  }
+};
+
+main();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@georgewrmarshall/design-system-metrics",
+  "version": "1.0.0",
+  "description": "A CLI tool to audit design system component usage across multiple MetaMask codebases",
+  "main": "index.js",
+  "packageManager": "yarn@4.3.1",
+  "bin": "./index.js",
+  "scripts": {
+    "start": "node index.js --project extension"
+  },
+  "keywords": [
+    "cli",
+    "audit",
+    "components",
+    "ast",
+    "babel"
+  ],
+  "author": "George Marshall",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.25.7",
+    "@babel/traverse": "^7.25.7",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}