@georgewrmarshall/design-system-metrics 2.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/.claude/settings.local.json +6 -1
  2. package/CHANGELOG.md +19 -0
  3. package/README.md +160 -106
  4. package/__tests__/fixtures/test-config.json +35 -8
  5. package/__tests__/metrics.test.js +186 -95
  6. package/config.json +1190 -163
  7. package/index.js +291 -128
  8. package/package.json +2 -1
package/.claude/settings.local.json CHANGED
@@ -16,7 +16,12 @@
16
16
  "Bash(git commit -m \"$(cat <<''EOF''\nchore: bump version to 2.1.0 and add CHANGELOG\n\n- Bumped version from 2.0.0 to 2.1.0\n- Added comprehensive CHANGELOG.md with full version history\n- Documented all changes from 1.0.0 through 2.1.0\n- Added migration guide for v1.x to v2.0.0 upgrade\n- Listed all 5 missing components that were added\n- Included Jest test suite additions\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n)\")",
17
17
  "Bash(git commit:*)",
18
18
  "Bash(yarn npm audit)",
19
- "Bash(git log:*)"
19
+ "Bash(git log:*)",
20
+ "Bash(yarn add:*)",
21
+ "Bash(yarn upgrade:*)",
22
+ "Bash(yarn up:*)",
23
+ "Bash(yarn npm info:*)",
24
+ "Bash(yarn remove:*)"
20
25
  ],
21
26
  "deny": [],
22
27
  "ask": []
package/CHANGELOG.md CHANGED
@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.4.0] - 2026-02-21
9
+
10
+ ### Changed
11
+
12
+ - **Extension Component Mappings**: Corrected replacement targets to reflect actual migration state
13
+ - Set 30+ component-library versions as most up to date with no MMDS replacement: BannerAlert, BannerBase, BannerTip, FileUploader, FormTextField, HeaderBase, HelpText, Input, Label, LottieAnimation, Modal components (7), PickerNetwork, SelectButton, SelectOption, SelectWrapper, SensitiveText, Skeleton, Tag, TagUrl, Textarea, TextFieldSearch
14
+ - Added intermediate migrations to component-library: Chip→Tag, FormField→FormTextField, Menu→Popover
15
+ - Fixed replacement targets: SiteOrigin→AvatarFavicon (was Text), ButtonLink→TextButton (was ButtonBase), ActionableMessage/Callout→BannerAlert (was BannerBase)
16
+
17
+ - **Mobile Component Mappings**: Updated 60+ components to reflect actual migration state
18
+ - Set component-library versions as most up to date with no MMDS replacement: Accordion, AccountBalance, AccountBase, AccountCell, ActionListItem, AggregatedPercentage, Avatar, Badge, BadgeBase, Banner components (3), BottomSheet components (3), ButtonFilter, ButtonHero, ButtonPill, ButtonSemantic, ButtonToggle, Card, Cell components (5), ConditionalScrollView, ContractBox components (2), CustomInput, CustomSpendCap, Header components (5), HelpText, Input, KeyValueRow, Label, ListItem components (6), Loader, MainActionButton, Modal components (2), Multichain components (4), MultiSelectItem, PercentageChange, Picker components (3), QuickAction components (2), RadioButton, SegmentedControl, Select components (4), SensitiveText, Skeleton, Tab components (6), Tag components (3), TextField, TextFieldSearch, TextWithPrefixIcon, TitleLeft, Toast
19
+ - Added intermediate migrations to component-library: SheetBottom→BottomSheet, SheetHeader→BottomSheetHeader
20
+ - Fixed replacement targets: ButtonLink→TextButton (was ButtonBase), BadgeNotifications→BadgeCount
21
+
22
+ ### Fixed
23
+
24
+ - Component replacement mappings now accurately reflect which components are the most current implementations
25
+ - Intermediate migration paths correctly identify multi-step migrations through component-library before eventual MMDS migration
26
+
8
27
  ## [2.2.0] - 2026-01-22
9
28
 
10
29
  ### Added
package/README.md CHANGED
@@ -1,15 +1,15 @@
1
1
  # **@georgewrmarshall/design-system-metrics**
2
2
 
3
- A CLI tool to audit design system component usage and track migration progress across MetaMask codebases. Identifies deprecated local component usage and measures adoption of the new MetaMask Design System (MMDS) NPM packages.
3
+ A CLI tool to audit design system component usage and track migration progress across MetaMask codebases. Identifies deprecated local component usage, tracks intermediate migrations, and measures adoption of the new MetaMask Design System (MMDS) NPM packages.
4
4
 
5
5
  ## **Getting Started**
6
6
 
7
7
  - [Extension](#extension)
8
8
  - [Mobile](#mobile)
9
- - [Design System Packages](#design-system-packages)
10
9
  - [CLI Options](#cli-options)
11
10
  - [Features](#features)
12
11
  - [Output Files](#output-files)
12
+ - [Configuration](#configuration)
13
13
  - [Requirements](#requirements)
14
14
 
15
15
  ---
@@ -20,6 +20,7 @@ A CLI tool to audit design system component usage and track migration progress a
20
20
 
21
21
  ```bash
22
22
  git clone https://github.com/MetaMask/metamask-extension.git
23
+ cd metamask-extension
23
24
  ```
24
25
 
25
26
  2. **Run the CLI tool using npx:**
@@ -28,9 +29,8 @@ git clone https://github.com/MetaMask/metamask-extension.git
28
29
  npx @georgewrmarshall/design-system-metrics --project extension
29
30
  ```
30
31
 
31
- 3. Two files will be generated in the current working directory:
32
- - `extension-component-metrics-deprecated.csv` - Old local component-library usage (needs migration)
33
- - `extension-component-metrics-current.csv` - New MMDS NPM package usage (@metamask/design-system-react)
32
+ 3. An XLSX file will be generated in the current directory:
33
+ - `extension-component-metrics.xlsx` - Multi-sheet workbook with migration progress, path-level details, and MMDS usage
34
34
 
35
35
  ---
36
36
 
@@ -40,6 +40,7 @@ npx @georgewrmarshall/design-system-metrics --project extension
40
40
 
41
41
  ```bash
42
42
  git clone https://github.com/MetaMask/metamask-mobile.git
43
+ cd metamask-mobile
43
44
  ```
44
45
 
45
46
  2. **Run the CLI tool using npx:**
@@ -48,166 +49,219 @@ git clone https://github.com/MetaMask/metamask-mobile.git
48
49
  npx @georgewrmarshall/design-system-metrics --project mobile
49
50
  ```
50
51
 
51
- 3. Two files will be generated in the current working directory:
52
- - `mobile-component-metrics-deprecated.csv` - Old local component-library usage (needs migration)
53
- - `mobile-component-metrics-current.csv` - New MMDS NPM package usage (@metamask/design-system-react-native)
52
+ 3. An XLSX file will be generated in the current directory:
53
+ - `mobile-component-metrics.xlsx` - Multi-sheet workbook with migration progress, path-level details, and MMDS usage
54
54
 
55
55
  ---
56
56
 
57
- ### **Design System Packages**
57
+ ### **CLI Options**
58
58
 
59
- You can also audit the design system NPM packages themselves to track component usage within the design system repos.
59
+ - **`--project` (Required)**: Specify the project to audit. Options are:
60
+ - `extension`: For MetaMask Extension
61
+ - `mobile`: For MetaMask Mobile
60
62
 
61
- #### **design-system-react**
63
+ Example:
64
+ ```bash
65
+ npx @georgewrmarshall/design-system-metrics --project extension
66
+ ```
62
67
 
63
- 1. **Clone the [design-system-react](https://github.com/MetaMask/design-system-react)** repository:
68
+ - **`--config` (Optional)**: Path to custom configuration file
64
69
 
65
- ```bash
66
- git clone https://github.com/MetaMask/design-system-react.git
67
- ```
70
+ Example:
71
+ ```bash
72
+ npx @georgewrmarshall/design-system-metrics --project extension --config ./custom-config.json
73
+ ```
68
74
 
69
- 2. **Run the CLI tool:**
75
+ ---
70
76
 
71
- ```bash
72
- npx @georgewrmarshall/design-system-metrics --project design-system-react
73
- ```
77
+ ### **Features**
74
78
 
75
- 3. One file will be generated:
76
- - `design-system-react-metrics.csv` - Component usage within the design system package
79
+ #### **Multi-Path Component Tracking**
80
+ Track component usage across multiple old implementations migrating to MMDS:
77
81
 
78
- #### **design-system-react-native**
82
+ - **Multiple deprecated paths**: Track usage from really old UI components AND old component-library versions
83
+ - **Path-level breakdowns**: See which specific implementation path has the most usage
84
+ - **Accurate migration metrics**: Calculate migration progress across all deprecated versions
79
85
 
80
- 1. **Clone the [design-system-react-native](https://github.com/MetaMask/design-system-react-native)** repository:
86
+ **Example:**
87
+ ```
88
+ Button from ui/components/ui/button: 15 uses (really old)
89
+ Button from component-library/Button: 42 uses (old)
90
+ Button from @metamask/design-system-react: 23 uses (new MMDS)
81
91
 
82
- ```bash
83
- git clone https://github.com/MetaMask/design-system-react-native.git
92
+ Migration Progress: 23 / (15 + 42 + 23) = 28.75%
84
93
  ```
85
94
 
86
- 2. **Run the CLI tool:**
95
+ #### **Intermediate Migration Tracking**
96
+ Some components migrate to component-library first before going to MMDS:
87
97
 
88
- ```bash
89
- npx @georgewrmarshall/design-system-metrics --project design-system-react-native
98
+ ```
99
+ Popover (ui/components/ui/popover) → Modal (component-library) → (future MMDS migration)
90
100
  ```
91
101
 
92
- 3. One file will be generated:
93
- - `design-system-react-native-metrics.csv` - Component usage within the design system package
102
+ The tool identifies these intermediate migrations and reports them separately so you can track the full migration journey.
94
103
 
95
- ---
104
+ #### **No Replacement Tracking**
105
+ Some deprecated components don't have direct MMDS replacements yet. The tool identifies and reports these separately:
96
106
 
97
- ### **CLI Options**
98
-
99
- - **`--project` (Required)**: Specify the project to audit. Options are:
100
- - `extension`: For MetaMask Extension
101
- - `mobile`: For MetaMask Mobile
102
- - `design-system-react`: For design-system-react package
103
- - `design-system-react-native`: For design-system-react-native package
107
+ ```
108
+ TextField - No direct MMDS replacement (custom implementation needed)
109
+ ```
104
110
 
105
- Example:
106
- ```bash
107
- npx @georgewrmarshall/design-system-metrics --project extension
108
- ```
111
+ #### **Detailed XLSX Reports**
112
+ Generate comprehensive Excel workbooks with 5 sheets:
109
113
 
110
- - **`--format` (Optional)**: Specify the output format. Options are `csv` (default) or `json`.
114
+ 1. **Migration Progress**: Components migrating to MMDS with % complete
115
+ 2. **Intermediate Migrations**: Components with intermediate component-library steps
116
+ 3. **Path-Level Detail**: Usage broken down by specific import paths
117
+ 4. **MMDS Usage**: Current MMDS component adoption
118
+ 5. **No Replacement**: Components needing custom migration approaches
111
119
 
112
- Example:
113
- ```bash
114
- npx @georgewrmarshall/design-system-metrics --project extension --format json
115
- ```
120
+ ---
116
121
 
117
- - **`--sources` (Optional)**: Specify which sources to track. Options are:
118
- - `all` (default): Track both deprecated and current sources
119
- - `deprecated`: Only track old local component-library usage
120
- - `current`: Only track new MMDS NPM package usage
121
- - Comma-separated: `deprecated,current` (same as `all`)
122
+ ### **Output Files**
122
123
 
123
- Example:
124
- ```bash
125
- npx @georgewrmarshall/design-system-metrics --project extension --sources deprecated
126
- ```
124
+ The tool generates an XLSX workbook with multiple sheets providing different views of your migration progress.
127
125
 
128
- - **`--config` (Optional)**: Path to custom configuration file
126
+ #### **Sheet 1: Migration Progress**
127
+ Tracks components migrating directly to MMDS packages.
129
128
 
130
- Example:
131
- ```bash
132
- npx @georgewrmarshall/design-system-metrics --project extension --config ./custom-config.json
133
- ```
129
+ | Deprecated Component | Source Paths | MMDS Component | Deprecated Instances | MMDS Instances | Migrated % |
130
+ |---------------------|--------------|----------------|---------------------|----------------|------------|
131
+ | Button | ui/components/ui/button, component-library/button | Button | 57 | 23 | 28.75% |
132
+ | Icon | component-library/icon | Icon | 142 | 89 | 38.52% |
134
133
 
135
- ---
134
+ #### **Sheet 2: Intermediate Migrations**
135
+ Shows components migrating to component-library before eventual MMDS migration.
136
136
 
137
- ### **Features**
137
+ | Old Component | Old Path | New Component | New Package/Path | Instances |
138
+ |--------------|----------|---------------|------------------|-----------|
139
+ | Popover | ui/components/ui/popover | Modal | component-library/modal | 15 |
138
140
 
139
- #### **Multi-Source Tracking (Extension & Mobile)**
140
- For Extension and Mobile projects, the tool tracks component usage from two distinct sources:
141
+ #### **Sheet 3: Path-Level Detail**
142
+ Breaks down usage by specific import paths to see which old implementations are most used.
141
143
 
142
- 1. **Deprecated**: Components imported from old local `/component-library` paths (needs migration)
143
- 2. **Current**: Components imported from new MMDS NPM packages:
144
- - Extension: `@metamask/design-system-react`
145
- - Mobile: `@metamask/design-system-react-native`
144
+ | Component | Specific Path | Instances | File Paths |
145
+ |-----------|--------------|-----------|------------|
146
+ | Button | ui/components/ui/button | 15 | pages/send.js, pages/home.js |
147
+ | Button | component-library/button | 42 | pages/settings.js, pages/confirm.js |
146
148
 
147
- This helps you track **migration progress** from deprecated local components to the new design system packages.
149
+ #### **Sheet 4: MMDS Usage**
150
+ Current adoption of MMDS components.
148
151
 
149
- #### **Design System Package Auditing**
150
- For design system packages themselves (`design-system-react` and `design-system-react-native`), the tool generates a single report showing all component usage within the package. This helps you understand which components are being used internally.
152
+ | Component | Instances | File Paths |
153
+ |-----------|-----------|------------|
154
+ | Button | 23 | pages/new-feature.js |
155
+ | Icon | 89 | pages/dashboard.js, pages/wallet.js |
151
156
 
152
- #### **Flexible Configuration**
153
- Four project configurations are available in `config.json`:
154
- - `extension` - Tracks Extension repo (deprecated = local, current = @metamask/design-system-react)
155
- - `mobile` - Tracks Mobile repo (deprecated = local, current = @metamask/design-system-react-native)
156
- - `design-system-react` - Tracks the design-system-react package itself
157
- - `design-system-react-native` - Tracks the design-system-react-native package itself
157
+ #### **Sheet 5: No Replacement**
158
+ Components without direct MMDS replacements.
158
159
 
159
- Each project can be configured with:
160
- - Custom file patterns and ignore rules
161
- - Component lists to audit
162
- - NPM packages to track (for extension/mobile)
160
+ | Component | Path | Instances | File Paths |
161
+ |-----------|------|-----------|------------|
162
+ | TextField | component-library/text-field | 34 | pages/forms.js |
163
163
 
164
164
  ---
165
165
 
166
- ### **Output Files**
167
-
168
- #### **Extension & Mobile Projects**
169
- Two separate CSV or JSON files are generated to track migration progress:
166
+ ### **Configuration**
170
167
 
171
- **CSV Format:**
172
- ```csv
173
- Component,Instances,File Paths
174
- "Button",42,"ui/pages/send/send.js, ui/pages/home/home.js"
175
- ```
168
+ The tool uses a `config.json` file to define projects and their component mappings.
176
169
 
177
- **Files Generated:**
178
- - `{project}-component-metrics-deprecated.csv` - Old local component usage
179
- - `{project}-component-metrics-current.csv` - New NPM package usage
170
+ #### **Config Structure**
180
171
 
181
- **JSON Format:**
182
172
  ```json
183
173
  {
184
- "Button": {
185
- "instances": 42,
186
- "files": ["ui/pages/send/send.js", "ui/pages/home/home.js"]
174
+ "projects": {
175
+ "extension": {
176
+ "rootFolder": "ui",
177
+ "ignoreFolders": ["ui/components/component-library"],
178
+ "filePattern": "ui/**/*.{js,tsx}",
179
+ "outputFile": "extension-component-metrics.xlsx",
180
+ "currentPackages": ["@metamask/design-system-react"],
181
+ "deprecatedComponents": {
182
+ "Button": {
183
+ "paths": [
184
+ "ui/components/ui/button",
185
+ "ui/components/component-library/button"
186
+ ],
187
+ "replacement": {
188
+ "component": "Button",
189
+ "package": "@metamask/design-system-react"
190
+ }
191
+ },
192
+ "Popover": {
193
+ "paths": ["ui/components/ui/popover"],
194
+ "replacement": {
195
+ "component": "Modal",
196
+ "package": "component-library",
197
+ "path": "ui/components/component-library/modal"
198
+ }
199
+ },
200
+ "TextField": {
201
+ "paths": ["ui/components/component-library/text-field"],
202
+ "replacement": null
203
+ }
204
+ },
205
+ "currentComponents": [
206
+ "Button",
207
+ "Icon",
208
+ "Text",
209
+ "Box"
210
+ ]
211
+ }
187
212
  }
188
213
  }
189
214
  ```
190
215
 
191
- #### **Design System Package Projects**
192
- One aggregated report showing all component usage:
216
+ #### **Config Fields**
217
+
218
+ **Project Level:**
219
+ - `rootFolder`: Root directory to scan
220
+ - `ignoreFolders`: Directories to exclude (e.g., the component-library source itself)
221
+ - `filePattern`: Glob pattern for files to scan
222
+ - `outputFile`: Name of the generated XLSX file
223
+ - `currentPackages`: NPM packages to track as "current" (MMDS packages)
224
+ - `currentComponents`: List of components available in MMDS packages
225
+
226
+ **Deprecated Components:**
227
+ - `paths`: Array of import paths to match (can be multiple old implementations)
228
+ - `replacement`: Object describing the migration target
229
+ - For MMDS migrations: `{ component: "Button", package: "@metamask/design-system-react" }`
230
+ - For intermediate migrations: `{ component: "Modal", package: "component-library", path: "..." }`
231
+ - For no replacement: `null`
193
232
 
194
- **Files Generated:**
195
- - `design-system-react-metrics.csv` - All component usage in design-system-react
196
- - `design-system-react-native-metrics.csv` - All component usage in design-system-react-native
233
+ #### **Path Matching**
234
+
235
+ The tool matches import paths flexibly:
236
+ - Exact matches: `ui/components/component-library/button`
237
+ - Relative imports: `../../components/component-library/button`
238
+ - Partial matches: Any path containing `/component-library`
239
+ - Package imports: `react-native-vector-icons/Ionicons`
197
240
 
198
241
  ---
199
242
 
200
243
  ### **Requirements**
201
244
 
202
- - The tool **only counts components that are imported** from tracked sources:
203
- - For Extension/Mobile: Local `/component-library` (deprecated) or configured NPM packages (current)
204
- - For Design System packages: Any imports within the package
245
+ - The tool **only counts components that are imported** from tracked sources
205
246
  - Components **inside JSDoc comments** are not counted as usage
206
247
  - **Test files** are automatically excluded (`*.test.{js,tsx}`)
207
248
  - **Node.js** v14 or higher is required
208
249
 
209
250
  ---
210
251
 
252
+ ### **Migration Strategy**
253
+
254
+ The tool helps you plan your migration strategy by identifying:
255
+
256
+ 1. **High-impact components**: Components with the most usage that should be migrated first
257
+ 2. **Multiple old versions**: Components with usage spread across really old and old implementations
258
+ 3. **Intermediate steps**: Components that need to go through component-library first
259
+ 4. **Custom work needed**: Components without direct MMDS replacements
260
+
261
+ Use the Path-Level Detail sheet to prioritize which old implementation to migrate first (usually the most-used one).
262
+
263
+ ---
264
+
211
265
  ### **Future Feature Ideas**
212
266
 
213
267
  We're exploring additional features to enhance design system adoption tracking:
package/__tests__/fixtures/test-config.json CHANGED
@@ -4,15 +4,42 @@
4
4
  "rootFolder": "__tests__/fixtures/test-project/ui",
5
5
  "ignoreFolders": ["__tests__/fixtures/test-project/ui/components/component-library"],
6
6
  "filePattern": "__tests__/fixtures/test-project/ui/**/*.{js,tsx}",
7
- "outputFile": "__tests__/output/test-metrics.csv",
7
+ "outputFile": "__tests__/output/test-metrics.xlsx",
8
8
  "currentPackages": ["@metamask/design-system-react"],
9
- "deprecatedComponents": [
10
- "Button",
11
- "Icon",
12
- "Modal",
13
- "TextField",
14
- "BannerAlert"
15
- ],
9
+ "deprecatedComponents": {
10
+ "Button": {
11
+ "paths": ["__tests__/fixtures/test-project/ui/components/component-library/button"],
12
+ "replacement": {
13
+ "component": "Button",
14
+ "package": "@metamask/design-system-react"
15
+ }
16
+ },
17
+ "Icon": {
18
+ "paths": ["__tests__/fixtures/test-project/ui/components/component-library/icon"],
19
+ "replacement": {
20
+ "component": "Icon",
21
+ "package": "@metamask/design-system-react"
22
+ }
23
+ },
24
+ "Modal": {
25
+ "paths": ["__tests__/fixtures/test-project/ui/components/component-library/modal"],
26
+ "replacement": {
27
+ "component": "Modal",
28
+ "package": "@metamask/design-system-react"
29
+ }
30
+ },
31
+ "TextField": {
32
+ "paths": ["__tests__/fixtures/test-project/ui/components/component-library/text-field"],
33
+ "replacement": null
34
+ },
35
+ "BannerAlert": {
36
+ "paths": ["__tests__/fixtures/test-project/ui/components/component-library/banner-alert"],
37
+ "replacement": {
38
+ "component": "BannerAlert",
39
+ "package": "@metamask/design-system-react"
40
+ }
41
+ }
42
+ },
16
43
  "currentComponents": [
17
44
  "Button",
18
45
  "Icon",