[PWA-355]: Add richer extension points and documentation

.gitignore

@@ -14,4 +14,7 @@ test-results.json
 yarn-error.log
 # Packages that build partially transpiled ES modules put them here
 docker/certs
-.history
+.history
+
+## exception: commit node_modules folders in test fixtures
+!**/__fixtures__/*/node_modules

jest.config.js

@@ -42,7 +42,6 @@ const testGlob = '/**/{src,lib,_buildpack}/**/__tests__/*.(test|spec).js';
 // Reusable test configuration for Venia UI and storefront packages.
 const testReactComponents = inPackage => ({
     // Expose jsdom to tests.
-    browser: true,
     moduleNameMapper: {
         // Mock binary files to avoid excess RAM usage.
         '\\.(jpg|jpeg|png)$':
@@ -52,7 +51,9 @@ const testReactComponents = inPackage => ({
         // This mapping forces CSS Modules to return literal identies,
         // so e.g. `classes.root` is always `"root"`.
         '\\.css$': 'identity-obj-proxy',
-        '\\.svg$': 'identity-obj-proxy'
+        '\\.svg$': 'identity-obj-proxy',
+        '@magento/venia-drivers':
+            '<rootDir>/packages/venia-ui/lib/drivers/index.js'
     },
     moduleFileExtensions: ['ee.js', 'ce.js', 'js', 'json', 'jsx', 'node'],
     // Reproduce the Webpack resolution config that lets Venia import
@@ -73,7 +74,7 @@ const testReactComponents = inPackage => ({
         // import `.graphql` files into JS.
         '\\.(gql|graphql)$': 'jest-transform-graphql',
         // Use the default babel-jest for everything else.
-        '\\.(js|css)$': 'babel-jest'
+        '\\.(jsx?|css)$': 'babel-jest'
     },
     // Normally babel-jest ignores node_modules and only transpiles the current
     // package's source. The below setting forces babel-jest to transpile
@@ -256,7 +257,6 @@ const jestConfig = {
         configureProject('pagebuilder', 'Pagebuilder', testReactComponents),
         configureProject('peregrine', 'Peregrine', inPackage => ({
             // Expose jsdom to tests.
-            browser: true,
             setupFiles: [
                 // Shim DOM properties not supported by jsdom
                 inPackage('scripts/shim.js'),
@@ -318,6 +318,7 @@ const jestConfig = {
         // Not node_modules
         '!**/node_modules/**',
         // Not __tests__, __helpers__, or __any_double_underscore_folders__
+        '!**/TestHelpers/**',
         '!**/__[[:alpha:]]*__/**',
         '!**/.*/__[[:alpha:]]*__/**',
         // Not this file itself

package.json

@@ -39,7 +39,7 @@
     "storybook:venia": "yarn workspace @magento/venia-ui run storybook",
     "test": "jest",
     "test:ci": "jest --no-cache --max-workers=3 --json --outputFile=test-results.json",
-    "test:debug": "node --inspect-brk node_modules/.bin/jest --no-cache --no-coverage --runInBand",
+    "test:debug": "node --inspect-brk node_modules/.bin/jest --no-cache --no-coverage --runInBand --testTimeout 86400",
     "test:dev": "jest --watch",
     "validate-queries": "yarn venia run validate-queries",
     "venia": "yarn workspace @magento/venia-concept",
@@ -48,7 +48,7 @@
   },
   "devDependencies": {
     "@magento/eslint-config": "~1.5.0",
-    "@types/jest": "~24.0.18",
+    "@types/jest": "~25.2.1",
     "caller-id": "~0.1.0",
     "chalk": "~2.4.2",
     "chokidar": "~2.1.2",
@@ -68,9 +68,9 @@
     "first-run": "~2.0.0",
     "graphql-tag": "~2.10.1",
     "identity-obj-proxy": "~3.0.0",
-    "jest": "~24.3.1",
+    "jest": "~26.0.1",
     "jest-fetch-mock": "~2.1.1",
-    "jest-junit": "~6.3.0",
+    "jest-junit": "~10.0.0",
     "jest-transform-graphql": "~2.1.0",
     "lodash.debounce": "~4.0.8",
     "prettier": "~1.16.4",

packages/pagebuilder/lib/ContentTypes/Block/__tests__/block.spec.js

@@ -58,9 +58,7 @@ test('renders a Block component with all props configured and Page Builder rich
     };
     const component = createTestInstance(<Block {...blockProps} />);
 
-    expect(
-        component.root.find(child => child.type.name === 'Row')
-    ).toBeTruthy();
+    expect(component.root.find(child => child.type === MockRow)).toBeTruthy();
 });
 
 test('renders a Block component with HTML content', () => {

packages/pagebuilder/lib/ContentTypes/ButtonItem/__tests__/buttonItem.spec.js

@@ -14,6 +14,21 @@ jest.mock('@magento/venia-drivers', () => ({
 }));
 useHistory.mockImplementation(() => history);
 
+const mockWindowLocation = {
+    assign: jest.fn()
+};
+
+let oldWindowLocation;
+beforeEach(() => {
+    oldWindowLocation = window.location;
+    delete window.location;
+    window.location = mockWindowLocation;
+    mockWindowLocation.assign.mockClear();
+});
+afterEach(() => {
+    window.location = oldWindowLocation;
+});
+
 test('renders a ButtonItem component', () => {
     const component = createTestInstance(<ButtonItem />);
 
@@ -73,7 +88,6 @@ test('clicking button with external link goes to correct destination', () => {
     };
     const component = createTestInstance(<ButtonItem {...buttonItemProps} />);
     const button = component.root.findByType(Button);
-    window.location.assign = jest.fn();
     button.props.onClick();
     expect(window.location.assign).toBeCalledWith('https://www.adobe.com');
 });

packages/pagebuilder/intercept.js → packages/pagebuilder/lib/intercept.js

@@ -27,7 +27,7 @@ module.exports = targets => {
         .richContentRenderers.tap(richContentRenderers => {
             richContentRenderers.add({
                 componentName: 'PageBuilder',
-                packageName: myName
+                importPath: myName
             });
         });
 };

packages/pagebuilder/package.json

@@ -61,7 +61,7 @@
   },
   "pwa-studio": {
     "targets": {
-      "intercept": "./intercept"
+      "intercept": "./lib/intercept"
     }
   },
   "sideEffects": false

packages/peregrine/lib/targets/__tests__/peregrine-targets.spec.js

@@ -0,0 +1,83 @@
+const {
+    buildModuleWith,
+    mockTargetProvider
+} = require('@magento/pwa-buildpack');
+const declare = require('../peregrine-declare');
+const intercept = require('../peregrine-intercept');
+
+test('declares a sync target talons and intercepts transformModules', () => {
+    const targets = mockTargetProvider(
+        '@magento/peregrine',
+        (_, dep) =>
+            ({
+                '@magento/pwa-buildpack': {
+                    specialFeatures: {
+                        tap: jest.fn()
+                    },
+                    transformModules: {
+                        tap: jest.fn()
+                    }
+                }
+            }[dep])
+    );
+    declare(targets);
+    expect(targets.own.talons.tap).toBeDefined();
+    const hook = jest.fn();
+    // no implementation testing in declare phase
+    targets.own.talons.tap('test', hook);
+    targets.own.talons.call('woah');
+    expect(hook).toHaveBeenCalledWith('woah');
+
+    intercept(targets);
+    const buildpackTargets = targets.of('@magento/pwa-buildpack');
+    expect(buildpackTargets.transformModules.tap).toHaveBeenCalled();
+});
+
+test('enables third parties to wrap talons', async () => {
+    // sorry, buildModuleWith is slow. TODO: make it take less than a minute?
+    jest.setTimeout(60000);
+    const talonIntegratingDep = {
+        name: 'goose-app',
+        declare() {},
+        intercept(targets) {
+            targets.of('@magento/peregrine').talons.tap(talons => {
+                talons.ProductFullDetail.useProductFullDetail.wrapWith(
+                    'src/usePFDIntercept'
+                );
+                talons.App.useApp.wrapWith('src/useAppIntercept');
+                talons.App.useApp.wrapWith('src/swedish');
+            });
+        }
+    };
+    const built = await buildModuleWith('src/index.js', {
+        context: __dirname,
+        dependencies: [
+            {
+                name: '@magento/peregrine',
+                declare,
+                intercept
+            },
+            talonIntegratingDep
+        ],
+        mockFiles: {
+            'src/index.js': `
+ import { useApp } from '@magento/peregrine/lib/talons/App/useApp';
+ import { useProductFullDetail } from '@magento/peregrine/lib/talons/ProductFullDetail/useProductFullDetail';
+ export default useApp() + useProductFullDetail()`,
+            'src/usePFDIntercept': `export default function usePFDIntercept(original) { return function usePFD() { return 'BEEP >o'; } };`,
+            'src/useAppIntercept': `export default function useAppIntercept(original) {
+     return function useApp() {
+         return 'o< HONK';
+     };
+ }
+ `,
+            'src/swedish': `export default function swedish(impl) {
+    return function() {
+        return impl().replace("O", "Ö")
+    }
+}`
+        }
+    });
+
+    expect(built.run()).toBe('o< HÖNKBEEP >o');
+});

packages/peregrine/lib/targets/peregrine-declare.js

@@ -0,0 +1,48 @@
+/**
+ * These targets are available for interception to modules which depend on `@magento/peregrine`.
+ *
+ * Their implementations are found in `./peregrine-intercept.js`.
+ *
+ * @module Peregrine/Targets
+ */
+module.exports = targets => {
+    targets.declare({
+        /**
+         * @callback talonIntercept
+         * @param {Peregrine/Targets.TalonWrapperConfig} talons - Registry of talon namespaces, talons, and Sets of interceptors
+         * @returns {undefined} - Interceptors of `talons` should add to the
+         * sets on passed TalonWrapperConfig instance. Any returned value will
+         * be ignored.
+         */
+
+        /**
+         * Collects requests to intercept and "wrap" individual Peregrine
+         * talons in decorator functions. Use it to add your own code to run
+         * when Peregrine talons are invoked, and/or to modify the behavior and
+         * output of those talons.
+         *
+         * This target is a convenience wrapper around the
+         * `@magento/pwa-buildpack` target `transformModules`. That target uses
+         * filenames, which are not guaranteed to be semantically versioned or
+         * to be readable APIs.
+         * This target publishes talons as functions to wrap, rather than as
+         * files to decorate.
+         *
+         * @type {tapable.SyncHook}
+         * @param {talonIntercept}
+         *
+         * @example <caption>Log whenever the `useApp()` hook runs.</caption>
+         * targets.of('@magento/peregrine').talons.tap(talons => {
+         *   talons.App.useApp.wrapWith('./log-wrapper');
+         * })
+         * // log-wrapper.js:
+         * export default function wrapUseApp(original) {
+         *   return function useApp(...args) {
+         *     console.log('calling useApp with', ...args);
+         *     return original(...args);
+         *   }
+         * }
+         */
+        talons: new targets.types.Sync(['talons'])
+    });
+};

packages/peregrine/lib/targets/peregrine-intercept.js

@@ -0,0 +1,68 @@
+/**
+ * @module Peregrine/Targets
+ */
+const path = require('path');
+
+/**
+ *
+ * @class TalonWrapperConfig
+ * @hideconstructor
+ */
+function TalonWrapperConfig(addTransforms) {
+    const wrappable = (talonFile, exportName) => ({
+        wrapWith: wrapperModule =>
+            addTransforms({
+                type: 'source',
+                fileToTransform: path.join('./lib/talons/', talonFile),
+                transformModule:
+                    '@magento/pwa-buildpack/lib/WebpackTools/loaders/wrap-esm-loader',
+                options: {
+                    wrapperModule,
+                    exportName
+                }
+            })
+    });
+    return {
+        /**
+         * @memberof TalonWrapperConfig
+         *
+         */
+
+        ProductFullDetail: {
+            useProductFullDetail: wrappable(
+                'ProductFullDetail/useProductFullDetail',
+                'useProductFullDetail'
+            )
+        },
+        App: {
+            useApp: wrappable('App/useApp', 'useApp')
+        }
+    };
+}
+
+module.exports = targets => {
+    const builtins = targets.of('@magento/pwa-buildpack');
+
+    builtins.specialFeatures.tap(featuresByModule => {
+        featuresByModule['@magento/peregrine'] = {
+            cssModules: true,
+            esModules: true,
+            graphQlQueries: true
+        };
+    });
+
+    /**
+     * Tap the low-level Buildpack target for wrapping _any_ frontend module.
+     * Wrap the config object in a TalonWrapperConfig, which presents
+     * higher-level targets for named and namespaced talons, instead of the
+     * file paths directly.
+     * Pass that higher-level config through `talons` interceptors, so they can
+     * add wrappers for the talon modules without tapping the `transformModules`
+     * config themselves.
+     */
+    builtins.transformModules.tap(addTransform => {
+        const talonWrapperConfig = new TalonWrapperConfig(addTransform);
+
+        targets.own.talons.call(talonWrapperConfig);
+    });
+};

packages/peregrine/package.json

@@ -44,6 +44,12 @@
     "node": ">=10.x",
     "yarn": ">=1.12.0"
   },
+  "pwa-studio": {
+    "targets": {
+      "declare": "./lib/targets/peregrine-declare",
+      "intercept": "./lib/targets/peregrine-intercept"
+    }
+  },
   "module": "lib/index.js",
   "jsnext:main": "lib/index.js",
   "es2015": "lib/index.js",

packages/pwa-buildpack/__mocks__/devcert.js

@@ -0,0 +1,7 @@
+module.exports = {
+    configuredDomains: jest.fn().mockReturnValue([]),
+    certificateFor: jest.fn().mockReturnValue({
+        key: 'fakekey',
+        cert: 'fakecert'
+    })
+};

packages/pwa-buildpack/__mocks__/word-wrap.js

@@ -0,0 +1,8 @@
+// don't actually word wrap, it messes with tests since the autodetect is
+// system-dependent
+const wordWrap = jest.requireActual('word-wrap');
+module.exports = (str, opts) =>
+    wordWrap(str, {
+        ...opts,
+        width: 1000
+    });

packages/pwa-buildpack/envVarDefinitions.json

@@ -171,6 +171,17 @@
                     "example": "sandbox_8yrzsvtm_s2bg8fs563crhqzk"
                 }
             ]
+        },
+        {
+            "name": "BuildBus and targets",
+            "variables": [
+                {
+                    "name": "BUILDBUS_DEPS_ADDITIONAL",
+                    "type": "str",
+                    "desc": "A list of resolvable NPM modules that BuildBus will scan for targets, in addition to those declared in project `dependencies` and `devDependencies`.",
+                    "default": ""
+                }
+            ]
         }
     ],
     "changes": [