feat: add ~/ui and ~/shared import alias infrastructure

Configure all build systems to resolve ~/ui and ~/shared aliases:
- tsconfig.json: paths for ~/ui/* and ~/shared/*
- webpack: resolve.alias entries
- browserify: pathmodify plugin in build pipeline
- jest: moduleNameMapper in unit and integration configs
- storybook: resolve.alias in webpack config
- depcheck: ignore aliases in dependency check

No existing imports are changed. Both relative and aliased imports
work simultaneously, enabling gradual opt-in adoption.

Co-authored-by: Francis Nepomuceno <n3ps@users.noreply.github.com>

Author: cursoragent

.depcheckrc.yml

@@ -105,6 +105,8 @@ ignores:
   - '@metamask/permissions-kernel-snap'
   # perps poc
   - '@metamask/perps-controller'
+  # import aliases (not real packages)
+  - '~'
 
 # files depcheck should not parse
 ignorePatterns:

.storybook/main.js

@@ -32,6 +32,8 @@ module.exports = {
     config.node = {
       __filename: true,
     };
+    config.resolve.alias['~/ui'] = path.resolve(__dirname, '../ui');
+    config.resolve.alias['~/shared'] = path.resolve(__dirname, '../shared');
     config.resolve.alias['webextension-polyfill'] = require.resolve(
       '../ui/__mocks__/webextension-polyfill.js',
     );

development/build/scripts.js

@@ -27,6 +27,7 @@ const lavamoatBrowserify = require('lavamoat-browserify');
 const terser = require('terser');
 
 const bifyModuleGroups = require('bify-module-groups');
+const pathmodify = require('pathmodify');
 
 const { streamFlatMap } = require('../stream-flat-map');
 const { isManifestV3 } = require('../../shared/modules/mv3.utils');
@@ -1109,6 +1110,13 @@ async function createBundle(buildConfiguration, { reloadOnChange }) {
   const { label, bundlerOpts, events } = buildConfiguration;
   const bundler = browserify(bundlerOpts);
 
+  bundler.plugin(pathmodify, {
+    mods: [
+      pathmodify.mod.dir('~/ui', path.join(__dirname, '../../ui')),
+      pathmodify.mod.dir('~/shared', path.join(__dirname, '../../shared')),
+    ],
+  });
+
   // manually apply non-standard options
   bundler.external(bundlerOpts.manualExternal);
   bundler.ignore(bundlerOpts.manualIgnore);

development/webpack/webpack.config.ts

@@ -313,6 +313,8 @@ const config = {
         context,
         '../ui/__mocks__/perps/perps-controller',
       ),
+      '~/ui': join(context, '../ui'),
+      '~/shared': join(context, '../shared'),
     },
     // use `fallback` to redirect module requests when normal resolving fails,
     // good for polyfill-ing built-in node modules that aren't available in

jest.config.js

@@ -19,6 +19,8 @@ module.exports = {
     // Map @metamask/perps-controller to local mock
     '^@metamask/perps-controller$':
       '<rootDir>/ui/__mocks__/perps/perps-controller/index.ts',
+    '^~/ui/(.*)$': '<rootDir>/ui/$1',
+    '^~/shared/(.*)$': '<rootDir>/shared/$1',
   },
   // The path to the Prettier executable used to format snapshots
   // Jest doesn't support Prettier 3 yet, so we use Prettier 2

jest.integration.config.js

@@ -13,6 +13,8 @@ module.exports = {
     // Map @metamask/perps-controller to local mock
     '^@metamask/perps-controller$':
       '<rootDir>/ui/__mocks__/perps/perps-controller/index.ts',
+    '^~/ui/(.*)$': '<rootDir>/ui/$1',
+    '^~/shared/(.*)$': '<rootDir>/shared/$1',
   },
   // The path to the Prettier executable used to format snapshots
   // Jest doesn't support Prettier 3 yet, so we use Prettier 2

lavamoat/build-system/policy.json

@@ -5017,6 +5017,14 @@
         "util.promisify": true
       }
     },
+    "pathmodify": {
+      "builtin": {
+        "util.deprecate": true
+      },
+      "packages": {
+        "pathmodify>readable-stream": true
+      }
+    },
     "gulp-livereload>event-stream>pause-stream": {
       "packages": {
         "browserify>JSONStream>through": true
@@ -5631,6 +5639,27 @@
         "@storybook/react>util-deprecate": true
       }
     },
+    "pathmodify>readable-stream": {
+      "builtin": {
+        "buffer.Buffer": true,
+        "events.EventEmitter.listenerCount": true,
+        "stream": true,
+        "util": true
+      },
+      "globals": {
+        "process.browser": true,
+        "process.env.READABLE_STREAM": true,
+        "process.nextTick": true,
+        "process.stderr": true,
+        "process.stdout": true
+      },
+      "packages": {
+        "readable-stream-2>core-util-is": true,
+        "pumpify>inherits": true,
+        "pathmodify>readable-stream>isarray": true,
+        "pathmodify>readable-stream>string_decoder": true
+      }
+    },
     "browserify>read-only-stream>readable-stream": {
       "builtin": {
         "events.EventEmitter": true,
@@ -7022,6 +7051,11 @@
         "gulp>vinyl-fs>glob-stream>ordered-read-streams>readable-stream>safe-buffer": true
       }
     },
+    "pathmodify>readable-stream>string_decoder": {
+      "builtin": {
+        "buffer.Buffer": true
+      }
+    },
     "browserify>read-only-stream>readable-stream>string_decoder": {
       "packages": {
         "browserify>read-only-stream>readable-stream>safe-buffer": true

package.json

@@ -693,6 +693,7 @@
     "nyc": "^15.1.0",
     "octokit": "^4.1.3",
     "path-browserify": "^1.0.1",
+    "pathmodify": "^0.5.0",
     "postcss": "^8.4.32",
     "postcss-discard-font-face": "^3.0.0",
     "postcss-loader": "^8.1.1",

tsconfig.json

@@ -27,7 +27,9 @@
     "baseUrl": ".",
     // Path mappings for module resolution
     "paths": {
-      "@metamask/perps-controller": ["ui/__mocks__/perps/perps-controller"]
+      "@metamask/perps-controller": ["ui/__mocks__/perps/perps-controller"],
+      "~/ui/*": ["ui/*"],
+      "~/shared/*": ["shared/*"]
     }
   },
   "exclude": [

yarn.lock

@@ -33258,6 +33258,7 @@ __metadata:
     nyc: "npm:^15.1.0"
     octokit: "npm:^4.1.3"
     path-browserify: "npm:^1.0.1"
+    pathmodify: "npm:^0.5.0"
     pify: "npm:^5.0.0"
     postcss: "npm:^8.4.32"
     postcss-discard-font-face: "npm:^3.0.0"
@@ -35789,6 +35790,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"pathmodify@npm:^0.5.0":
+  version: 0.5.0
+  resolution: "pathmodify@npm:0.5.0"
+  dependencies:
+    readable-stream: "npm:1.x"
+  peerDependencies:
+    browserify: ">=5.1.0"
+  checksum: 10/48cc6345fc534c2d37cf8ad191c7f28663262c71877e62609570d32d3caf2655d1837b10ff90994bc731f581737d486eafeba1ef605627d67b00d1d967ab87ac
+  languageName: node
+  linkType: hard
+
 "pause-stream@npm:0.0.11":
   version: 0.0.11
   resolution: "pause-stream@npm:0.0.11"
@@ -38041,6 +38053,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"readable-stream@npm:1.x":
+  version: 1.1.14
+  resolution: "readable-stream@npm:1.1.14"
+  dependencies:
+    core-util-is: "npm:~1.0.0"
+    inherits: "npm:~2.0.1"
+    isarray: "npm:0.0.1"
+    string_decoder: "npm:~0.10.x"
+  checksum: 10/1aa2cf4bd02f9ab3e1d57842a43a413b52be5300aa089ad1f2e3cea00684532d73edc6a2ba52b0c3210d8b57eb20a695a6d2b96d1c6085ee979c6021ad48ad20
+  languageName: node
+  linkType: hard
+
 "readable-stream@npm:4.7.0, readable-stream@npm:^3.6.2 || ^4.4.2, readable-stream@npm:^4.5.2, readable-stream@npm:^4.7.0":
   version: 4.7.0
   resolution: "readable-stream@npm:4.7.0"
@@ -41114,7 +41138,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"string_decoder@npm:0.10":
+"string_decoder@npm:0.10, string_decoder@npm:~0.10.x":
   version: 0.10.31
   resolution: "string_decoder@npm:0.10.31"
   checksum: 10/cc43e6b1340d4c7843da0e37d4c87a4084c2342fc99dcf6563c3ec273bb082f0cbd4ebf25d5da19b04fb16400d393885fda830be5128e1c416c73b5a6165f175