Add @metamask/build-utils package

README.md

@@ -50,6 +50,7 @@ linkStyle default opacity:0.5
   approval_controller(["@metamask/approval-controller"]);
   assets_controllers(["@metamask/assets-controllers"]);
   base_controller(["@metamask/base-controller"]);
+  build_utils(["@metamask/build-utils"]);
   composable_controller(["@metamask/composable-controller"]);
   controller_utils(["@metamask/controller-utils"]);
   ens_controller(["@metamask/ens-controller"]);
@@ -134,9 +135,9 @@ linkStyle default opacity:0.5
   signature_controller --> approval_controller;
   signature_controller --> base_controller;
   signature_controller --> controller_utils;
+  signature_controller --> keyring_controller;
   signature_controller --> logging_controller;
   signature_controller --> message_manager;
-  signature_controller --> keyring_controller;
   transaction_controller --> approval_controller;
   transaction_controller --> base_controller;
   transaction_controller --> controller_utils;

packages/build-utils/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+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).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/core/

packages/build-utils/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2023 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

packages/build-utils/README.md

@@ -0,0 +1,21 @@
+# `@metamask/build-utils`
+
+Utilities for building MetaMask applications.
+
+## Installation
+
+`yarn add @metamask/build-utils`
+
+or
+
+`npm install @metamask/build-utils`
+
+## Usage
+
+### `/transforms`
+
+See [the transforms readme](https://github.com/MetaMask/core/packages/build-utils/src/transforms/README.md).
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

packages/build-utils/jest.config.js

@@ -0,0 +1,26 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+const merge = require('deepmerge');
+const path = require('path');
+
+const baseConfig = require('../../jest.config.packages');
+
+const displayName = path.basename(__dirname);
+
+module.exports = merge(baseConfig, {
+  // The display name when running multiple projects
+  displayName,
+
+  // An object that configures minimum threshold enforcement for coverage results
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+});

packages/build-utils/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@metamask/build-utils",
+  "version": "0.0.0",
+  "description": "Utilities for building MetaMask applications",
+  "keywords": [
+    "MetaMask",
+    "Ethereum"
+  ],
+  "homepage": "https://github.com/MetaMask/core/tree/main/packages/build-utils#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/core/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/core.git"
+  },
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build:docs": "typedoc",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/build-utils",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "jest --reporters=jest-silent-reporter",
+    "test:clean": "jest --clearCache",
+    "test:verbose": "jest --verbose",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@metamask/utils": "^8.2.0"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^3.4.3",
+    "@types/eslint": "^8.44.7",
+    "@types/jest": "^27.4.1",
+    "deepmerge": "^4.2.2",
+    "eslint": "^8.44.0",
+    "jest": "^27.5.1",
+    "ts-jest": "^27.1.4",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "~4.8.4"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

packages/build-utils/src/index.ts

@@ -0,0 +1,3 @@
+export type { FeatureLabels } from './transforms/remove-fenced-code';
+export { removeFencedCode } from './transforms/remove-fenced-code';
+export { lintTransformedFile } from './transforms/utils';

packages/build-utils/src/transforms/README.md

@@ -0,0 +1,198 @@
+# Source file transforms
+
+This directory contains home-grown transforms for the build systems of the MetaMask applications.
+
+## Remove Fenced Code
+
+> `./remove-fenced-code.ts`
+
+### Usage
+
+Let's imagine you've added some fences to your source code.
+
+```typescript
+this.store.updateStructure({
+  /** ..., */
+  GasFeeController: this.gasFeeController,
+  TokenListController: this.tokenListController,
+  ///: BEGIN:ONLY_INCLUDE_IF(snaps)
+  SnapController: this.snapController,
+  ///: END:ONLY_INCLUDE_IF
+});
+```
+
+The transform should be applied on your raw source files as they are committed to
+your repository, before anything else (e.g. Babel, `tsc`, etc.) parses or modifies them.
+
+```typescript
+import {
+  FeatureLabels,
+  removeFencedCode,
+  lintTransformedFile,
+} from '@metamask/build-utils';
+
+// Let's imagine this function exists in your build system and is called immediately
+// after your source files are read from disk.
+async function applyTransforms(
+  filePath: string,
+  fileContent: string,
+  features: FeatureLabels,
+  shouldLintTransformedFiles: boolean = true,
+): string {
+  const [newFileContent, wasModified] = removeFencedCode(
+    filePath,
+    fileContent,
+    features,
+  );
+
+  // You may choose to disable linting during e.g. dev builds since lint failures cause
+  // an error to be thrown.
+  if (wasModified && shouldLintTransformedFiles) {
+    // You probably only need a singleton ESLint instance for your linting purposes.
+    // See the lintTransformedFile documentation for important notes about usage.
+    const eslintInstance = getESLintInstance();
+    await lintTransformedFile(eslintInstance, filePath, newFileContent);
+  }
+  return newFileContent;
+}
+
+// Then, in the relevant part of your build process...
+
+const features: FeatureLabels = {
+  active: new Set(['foo']), // Fences with these features will be included.
+  all: new Set(['snaps', 'foo' /** etc. */]), // All extant features must be listed here.
+};
+
+const transformedFile = await applyTransforms(
+  filePath,
+  fileContent,
+  features,
+  shouldLintTransformedFiles,
+);
+
+// Do something with the results.
+// continueBuildProcess(transformedFile);
+```
+
+After the transform has been applied as above, the example source code will look like this:
+
+```typescript
+this.store.updateStructure({
+  /** ..., */
+  GasFeeController: this.gasFeeController,
+  TokenListController: this.tokenListController,
+});
+```
+
+### Overview
+
+When creating builds that support different features, it is desirable to exclude
+unsupported features, files, and dependencies at build time. Undesired files and
+dependencies can be excluded wholesale, but the _use_ of undesired modules in
+files that should otherwise be included – i.e. import statements and references
+to those imports – cannot.
+
+To support the exclusion of the use of undesired modules at build time, we
+introduce the concept of code fencing to our build system. Our code fencing
+syntax amounts to a tiny DSL, which is specified below.
+
+The transform expects to receive the contents of individual files as a single string,
+which it will parse in order to identify any code fences. If any fences that should not
+be included in the current build are found, the fences and the lines that they wrap
+are deleted. An error is thrown if a malformed fence is identified.
+
+For example, the following fenced code:
+
+```javascript
+this.store.updateStructure({
+  ...,
+  GasFeeController: this.gasFeeController,
+  TokenListController: this.tokenListController,
+  ///: BEGIN:ONLY_INCLUDE_IF(snaps)
+  SnapController: this.snapController,
+  ///: END:ONLY_INCLUDE_IF
+});
+```
+
+Is transformed as follows if the current build should not include the `snaps` feature:
+
+```javascript
+this.store.updateStructure({
+  ...,
+  GasFeeController: this.gasFeeController,
+  TokenListController: this.tokenListController,
+});
+```
+
+Note that multiple features can be specified by separating them with
+commands inside the parameter parentheses:
+
+```javascript
+///: BEGIN:ONLY_INCLUDE_IF(build-beta,build-flask)
+```
+
+### Code Fencing Syntax
+
+> In the specification, angle brackets, `< >`, indicate required tokens, while
+> straight brackets, `[ ]`, indicate optional tokens.
+>
+> Alphabetical characters identify the name and purpose of a token. All other
+> characters, including parentheses, `( )`, are literals.
+
+A fence line is a single-line JavaScript comment, optionally surrounded by
+whitespace, in the following format:
+
+```text
+///: <terminus>:<command>[(parameters)]
+
+|__| |________________________________|
+  |                  |
+  |                  |
+sentinel         directive
+```
+
+The first part of a fence line is the **sentinel** which is always the string
+"`///:`". If the first four non-whitespace characters of a line are not exactly the
+**sentinel** the line will be ignored by the parser. The **sentinel** must be
+succeeded by a single space character, or parsing will fail.
+
+The remainder of the fence line is called the **directive**
+The directive consists of a **terminus** **command** and **parameters**
+
+- The **terminus** is one of the strings `BEGIN` and `END`. It must be followed by
+  a single colon, `:`.
+- The **command** is a string of uppercase alphabetical characters, optionally
+  including underscores, `_`. The possible commands are listed later in this
+  specification.
+- The **parameters** are a string of comma-separated RegEx `\w` strings. The parameters
+  string must be parenthesized, only specified for `BEGIN` directives, and valid for its
+  command.
+
+A valid code fence consists of two fence lines surrounding one or more lines of
+non-fence lines. The first fence line must consist of a `BEGIN` directive, and
+the second an `END` directive. The command of both directives must be the same,
+and the parameters (if any) must be valid for the command. Nesting is not intended
+to be supported, and may produce undefined behavior.
+
+If an invalid fence is detected, parsing will fail, and the transform will throw
+an error.
+
+### Commands
+
+#### `ONLY_INCLUDE_IF`
+
+This, the only command defined so far, is used to exclude lines of code depending
+on flags provided to the current build process. If a particular set of lines should
+only be included in e.g. the beta build type, they should be wrapped as follows:
+
+```javascript
+///: BEGIN:ONLY_INCLUDE_IF(build-beta)
+console.log('I am only included in beta builds.');
+///: END:ONLY_INCLUDE_IF
+```
+
+At build time, the fences and the fenced lines will be removed if the `build-beta`
+flag is not provided to the transform.
+
+The parameters must be provided as a comma-separated list of features that are
+valid per the consumer's build system.