feat: include MagentoResolver and docs

Author: zetlen

Diff for: README.md

@@ -22,3 +22,5 @@ a Peregrine app to a Magento backend and a
 * [`PWADevServer`](docs/PWADevServer.md) -- Configures your system settings and
 * [`ServiceWorkerPlugin`](docs/ServiceWorkerPlugin.md) -- Creates
   a ServiceWorker with different settings based on dev scenarios
+* [`MagentoResolver`](docs/MagentoResolver.md) -- Configures Webpack to resolve
+  modules and assets in Magento PWA themes.

Diff for: docs/MagentoResolver.md

@@ -0,0 +1,56 @@
+## MagentoResolver
+
+Adapter for configuring Webpack to resolve assets according to Magento PWA conventions.
+
+### Usage
+
+In `webpack.config.js`:
+
+```js
+const buildpack = require('@magento/pwa-buildpack');
+const MagentoResolver = buildpack.Webpack.MagentoResolver;
+
+module.exports = async env => {
+    const config {
+        /* webpack entry, output, rules, etc */
+
+
+        resolve: await MagentoResolver.configure({
+            paths: {
+                root: __dirname
+            }
+        })
+
+    };
+
+    return config;
+}
+```
+
+
+ - ⚠️ `MagentoResolver.configure()` is async and returns a Promise, so a Webpack
+   config that uses it must use the [Exporting a Promise configuration type](https://webpack.js.org/configuration/configuration-types/#exporting-a-promise).
+   The newer `async/await` syntax looks cleaner than using Promises directly.
+
+### Purpose
+
+Generates a configuration for use in the [`resolve` property of Webpack config](https://webpack.js.org/configuration/resolve/).
+Describes how to traverse the filesystem structure for assets required in source
+files.
+
+Currently, `MagentoResolver` does very little, but it's likely that the Magento
+development environment will require custom resolution rules in the future; this
+utility sets the precedent of the API for delivering those rules.
+
+### API
+
+`MagentoResolver` has only one method: `.configure(options)`. It returns a Promise
+for an object that can be assigned to the `resolve` property in Webpack config
+objects.
+
+#### `MagentoResolver.configure(options: ResolverOptions): Promise<resolve>`
+
+#### `options`
+
+ - `paths: object`: **Required.** Local absolute paths to theme folders.
+     - `root`: Absolute path to the root directory of the theme.

Diff for: src/webpack/MagentoResolver.js

@@ -0,0 +1,15 @@
+const optionsValidator = require('../util/options-validator');
+class MagentoResolver {
+    static validateConfig = optionsValidator('MagentoResolver', {
+        'paths.root': 'string'
+    });
+    static async configure(options) {
+        this.validateConfig('.configure()', options);
+        return {
+            modules: [options.paths.root, 'node_modules'],
+            mainFiles: ['index'],
+            extensions: ['.js']
+        };
+    }
+}
+module.exports = MagentoResolver;

Diff for: src/webpack/Resolver.js

@@ -0,0 +1,15 @@
+const MagentoResolver = require('../MagentoResolver');
+test('static configure() produces a webpack resolver config', async () => {
+    await expect(
+        MagentoResolver.configure({ paths: { root: 'fakeRoot' } })
+    ).resolves.toEqual({
+        modules: ['fakeRoot', 'node_modules'],
+        mainFiles: ['index'],
+        extensions: ['.js']
+    });
+});
+test('static configure() throws if required paths are missing', async () => {
+    await expect(
+        MagentoResolver.configure({ paths: { root: false } })
+    ).rejects.toThrow('paths.root must be of type string');
+});

Diff for: src/webpack/__tests__/MagentoResolver.spec.js

@@ -1,6 +1,6 @@
 module.exports = {
     MagentoRootComponentsPlugin: require('./plugins/MagentoRootComponentsPlugin'),
     ServiceWorkerPlugin: require('./plugins/ServiceWorkerPlugin'),
-    Resolver: require('./Resolver'),
+    MagentoResolver: require('./MagentoResolver'),
     PWADevServer: require('./PWADevServer')
 };