Issue/afp 355 website pipeline (#166)

* AFP-355: Create scaffold for website build pipeline

* AFP-355: Fix babel configs to produce working bin scripts. Remove styled-components from react-changelogs. Add config options to pipeline interface.

* AFP-355: Add changesets

* AFP-355: Reset babel dependencies back to their previous versions

Author: Noviny

.changeset/rotten-bottles-cover/changes.json

@@ -0,0 +1,9 @@
+{
+  "releases": [
+    { "name": "changeset-bot", "type": "patch" },
+    { "name": "@brisk-docs/file-viewer", "type": "patch" },
+    { "name": "@brisk-docs/react-changelogs", "type": "patch" },
+    { "name": "@brisk-docs/website", "type": "patch" }
+  ],
+  "dependents": []
+}

.changeset/rotten-bottles-cover/changes.md

@@ -0,0 +1 @@
+Fix babel configs for building packages to produce working dists for node scripts.

.changeset/slow-kings-float/changes.json

@@ -0,0 +1,4 @@
+{
+  "releases": [{ "name": "@brisk-docs/react-changelogs", "type": "patch" }],
+  "dependents": []
+}

.changeset/slow-kings-float/changes.md

@@ -0,0 +1 @@
+Use emotion instead of styled components.

.changeset/twenty-badgers-destroy/changes.json

@@ -0,0 +1,4 @@
+{
+  "releases": [{ "name": "@brisk-docs/website", "type": "minor" }],
+  "dependents": []
+}

.changeset/twenty-badgers-destroy/changes.md

@@ -0,0 +1 @@
+Add scaffolding for new website build pipeline. This is available as a brisk-next command.

babel.config.js

@@ -1,5 +1,5 @@
 module.exports = {
-  presets: ['next/babel', '@zeit/next-typescript/babel'],
+  presets: ['@babel/preset-env', '@babel/react', '@babel/preset-typescript'],
   plugins: [
     'emotion',
     [

package.json

@@ -20,6 +20,7 @@
     "delete:dist": "bolt ws exec --parallel -- rm -rf dist",
     "delete:modules": "bolt ws exec --parallel -- rm -rf node_modules && rm -rf node_modules",
     "docs": "node packages/website/src/bin/index.js dev",
+    "docs-next": "node packages/website/bin.js",
     "prettier": "prettier --write \"**/*.{js,ts,tsx}\"",
     "lint": "yarn lint:eslint && yarn lint:prettier && yarn check:types",
     "lint:prettier": "prettier --list-different \"**/*.{js,ts,tsx}\"",
@@ -40,7 +41,8 @@
   "preconstruct": {
     "packages": [
       "packages/react-changelogs",
-      "packages/file-viewer"
+      "packages/file-viewer",
+      "packages/website"
     ]
   },
   "dependencies": {

packages/changeset-bot/index.test.js

@@ -17,7 +17,7 @@ describe('changeset-bot', () => {
     const app = probot.load(changesetBot);
 
     // just return a test token
-    app.app = () => 'test';
+    app.app = () => 'test.ts';
   });
 
   it('should add a comment when there is no comment', async () => {

packages/file-viewer/package.json

@@ -36,6 +36,7 @@
     "@atlaskit/icon": "^16.0.1",
     "@atlaskit/theme": "^6.0.0",
     "@atlaskit/toggle": "^7.0.0",
+    "@babel/runtime": "^7.4.3",
     "@babel/runtime-corejs2": "^7.4.3",
     "@emotion/core": "^10.0.9",
     "@emotion/styled": "^10.0.9",
@@ -45,4 +46,4 @@
     "react-addons-text-content": "^0.0.4",
     "react-markdown": "^2.5.0"
   }
-}
+}

packages/react-changelogs/examples/filter-changelogs.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import styled from 'styled-components';
+import styled from '@emotion/styled';
 import { gridSize, math } from '@atlaskit/theme';
 import Changelog from '../src/components/changelog';
 

packages/react-changelogs/examples/set-changelog-entries-per-page.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import styled from 'styled-components';
+import styled from '@emotion/styled';
 import { gridSize, math } from '@atlaskit/theme';
 import Changelog from '../src/components/changelog';
 

packages/react-changelogs/package.json

@@ -34,11 +34,13 @@
     "@atlaskit/css-reset": "^3.0.5",
     "@atlaskit/pagination": "^10.0.1",
     "@atlaskit/theme": "^6.0.0",
+    "@babel/runtime": "^7.4.3",
     "@babel/runtime-corejs2": "^7.4.3",
+    "@emotion/core": "^10.0.9",
+    "@emotion/styled": "^10.0.9",
     "prismjs": "^1.15.0",
     "react-addons-text-content": "^0.0.4",
     "react-markdown": "^2.5.0",
-    "semver": "^5.4.1",
-    "styled-components": "^3.2.6"
+    "semver": "^5.4.1"
   }
-}
+}

packages/react-changelogs/src/components/changelog.tsx

@@ -1,13 +1,13 @@
 import * as React from 'react';
 // @ts-ignore - The types for ReactMarkdown are wrong and do not think it has a default export
 import ReactMarkdown from 'react-markdown';
-import styled, { css } from 'styled-components';
-import { math, gridSize, colors, borderRadius } from '@atlaskit/theme';
+import styled from '@emotion/styled';
+import { gridSize, colors, borderRadius } from '@atlaskit/theme';
 import Pagination from '@atlaskit/pagination';
 import filterChangelog from '../utils/filter-changelog';
 import divideChangelog from '../utils/divide-changelog';
 
-const gutter = math.multiply(gridSize, 3);
+const gutter = gridSize() * 3;
 
 const H3 = styled.h3`
   color: ${colors.N200};
@@ -56,8 +56,8 @@ const LogItem = styled.div`
 
   ${(p: { major: boolean }) =>
     p.major
-      ? css`
-          &:not(:first-child) {
+      ? `
+          &:not(:first-of-type) {
             border-top: 2px solid ${colors.N30};
             margin-top: ${gutter}px;
             padding-top: ${gutter}px;

packages/website/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/* eslint-disable strict */
+
+'use strict';
+
+const runPipeline = require('./').default;
+
+runPipeline().catch(e => console.error(e));

packages/website/docs/build-pipeline/1-scan-metadata-stage.md

@@ -0,0 +1,8 @@
+# Scan metadata build stage
+
+This is the start of the Brisk pipeline. During this stage, the target project is scanned in order to find all the
+packages, examples and docs that will be used in the final website. The output of this stage is a data structure
+containing all of this info.
+
+This stage should be the only one in the pipeline to be reading the user's filesystem to find the location of important
+files or for other metadata. This is to avoid harmful couplings of the filesystem to the finished website.

packages/website/docs/build-pipeline/2-generate-website-info-stage.md

@@ -0,0 +1,2 @@
+# Generate website info build stage
+

packages/website/docs/build-pipeline/3-generate-pages-stage.md

@@ -0,0 +1 @@
+# Generate pages build stage

packages/website/docs/build-pipeline/4-build-website-stage.md

@@ -0,0 +1 @@
+# Build website build stage

packages/website/docs/build-pipeline/5-start-website-stage.md

@@ -0,0 +1 @@
+# Start website build stage

packages/website/docs/build-pipeline/README.md

@@ -0,0 +1,11 @@
+# The brisk website build pipeline
+
+Brisk docs uses a pipeline of build stages to take the docs in a codebase and turn it into a website.
+
+## Build stages reference
+
+- [Scan metadata stage](./1-scan-metadata-stage.md)
+- [Generate website info stage](./2-generate-website-info-stage.md)
+- [Generate pages stage](./3-generate-pages-stage.md)
+- [Build website stage](./4-build-website-stage.md)
+- [Start website stage](./5-start-website-stage.md)

packages/website/docs/nesting/work.md

@@ -2,7 +2,8 @@
   "name": "@brisk-docs/website",
   "version": "0.7.4",
   "description": "The Brisk website documenter",
-  "main": "src/bin/index.js",
+  "main": "dist/website.cjs.js",
+  "module": "dist/website.esm.js",
   "maintainers": [
     "Dean Pisani",
     "Aparna Raj",
@@ -21,7 +22,11 @@
     "start": "node src/bin/index.js start"
   },
   "bin": {
-    "brisk": "src/bin/index.js"
+    "brisk": "src/bin/index.js",
+    "brisk-next": "bin.js"
+  },
+  "engines": {
+    "node": ">=10.0.0"
   },
   "files": [
     "src",
@@ -33,7 +38,9 @@
     "next.config.js",
     "next-externals.js",
     "types.ts",
-    "tsconfig.json"
+    "tsconfig.json",
+    "bin.js",
+    "dist"
   ],
   "dependencies": {
     "@atlaskit/avatar": "^14.1.8",
@@ -120,4 +127,4 @@
     "mock-fs": "^4.10.1",
     "ts-loader": "^5.3.3"
   }
-}
+}

packages/website/package.json

@@ -0,0 +1,3 @@
+import runPipeline from './pipeline';
+
+export default runPipeline;

packages/website/src/index.ts

@@ -0,0 +1,17 @@
+import scanMetadata from './stages/scan-metadata';
+import generateWebsiteInfo from './stages/generate-website-info';
+import generatePages from './stages/generate-pages';
+import buildWebsite from './stages/build-website';
+import runWebsite from './stages/run-website';
+
+export default () => {
+  const initialConfiguration = {};
+  return scanMetadata(initialConfiguration, {})
+    .then(result => generateWebsiteInfo(result, {}))
+    .then(result => generatePages(result, {}))
+    .then(result => buildWebsite(result, {}))
+    .then(result => runWebsite(result, {}))
+    .then(() => {
+      console.log('Thanks for documenting with brisk-docs! 🎿');
+    });
+};

packages/website/src/pipeline/index.ts

@@ -0,0 +1,15 @@
+import createStage from '../make-pipline-stage';
+
+interface StageInput {}
+
+// Boilerplate, uncomment when used
+// interface StageConfig {}
+
+interface StageOutput {}
+
+export default createStage(
+  'build-website',
+  async (input: StageInput): Promise<StageOutput> => {
+    return input;
+  },
+);

packages/website/src/pipeline/stages/build-website/index.ts

@@ -0,0 +1,3 @@
+describe('Build website stage', () => {
+  it.skip('needs tests', () => {});
+});

packages/website/src/pipeline/stages/build-website/test.ts

@@ -0,0 +1,15 @@
+import createStage from '../make-pipline-stage';
+
+interface StageInput {}
+
+// Boilerplate, uncomment when used
+// interface StageConfig {}
+
+export interface StageOutput {}
+
+export default createStage(
+  'generate-pages',
+  async (input: StageInput): Promise<StageOutput> => {
+    return input;
+  },
+);

packages/website/src/pipeline/stages/generate-pages/index.ts

@@ -0,0 +1,3 @@
+describe('Generate pages build stage', () => {
+  it.skip('needs tests', () => {});
+});

packages/website/src/pipeline/stages/generate-pages/test.ts

@@ -0,0 +1,15 @@
+import createStage from '../make-pipline-stage';
+
+interface StageInput {}
+
+// Boilerplate, uncomment when used
+// interface StageConfig {}
+
+interface StageOutput {}
+
+export default createStage(
+  'generate-website-info',
+  async (input: StageInput): Promise<StageOutput> => {
+    return input;
+  },
+);

packages/website/src/pipeline/stages/generate-website-info/index.ts

@@ -0,0 +1,3 @@
+describe('Generate website info build stage', () => {
+  it.skip('needs tests', () => {});
+});

packages/website/src/pipeline/stages/generate-website-info/test.ts

@@ -0,0 +1,42 @@
+import { PerformanceObserver } from 'perf_hooks';
+import createStage from './make-pipline-stage';
+
+describe('Pipeline stage generator', () => {
+  it('creates a run property from the given function', async () => {
+    const step = jest.fn();
+    step.mockReturnValue(Promise.resolve('result'));
+
+    const runStage = createStage('test-stage', step);
+    const stageInput = {};
+    const stageConfig = {};
+    const result = await runStage(stageInput, stageConfig);
+
+    expect(step).toHaveBeenCalledWith(stageInput, stageConfig);
+    expect(result).toBe('result');
+  });
+
+  it('sends a performance measure event to the performance timing API', () => {
+    const getPerformanceMetric = new Promise((resolve, reject) => {
+      const obs = new PerformanceObserver(items => {
+        const entry = items
+          .getEntries()
+          .find(e => e.name === 'brisk-pipeline-stage-duration:test-stage');
+        if (!entry) {
+          reject(
+            new Error('brisk-pipeline-stage-duration:test-stage entry missing'),
+          );
+        } else {
+          resolve(entry.duration);
+        }
+
+        obs.disconnect();
+      });
+      obs.observe({ entryTypes: ['measure'] });
+    });
+
+    const runStage = createStage('test-stage', () => Promise.resolve());
+    runStage({}, {});
+
+    return expect(getPerformanceMetric).resolves.toEqual(expect.any(Number));
+  });
+});

packages/website/src/pipeline/stages/make-pipeline-stage.test.ts

@@ -0,0 +1,39 @@
+import { performance } from 'perf_hooks';
+
+export type PipelineStage<StageInput, StageConfig, StageOutput> = (
+  input: StageInput,
+  configOptions: StageConfig,
+) => Promise<StageOutput>;
+
+/**
+ * Creates a stage for the website build pipeline with performance profiling
+ * built in.
+ */
+export default <StageInput, StageConfig, StageOutput>(
+  id: string,
+  buildStep: (
+    input: StageInput,
+    configOptions: StageConfig,
+  ) => Promise<StageOutput>,
+): PipelineStage<StageInput, StageConfig, StageOutput> => {
+  return async (
+    input: StageInput,
+    configOptions: StageConfig,
+  ): Promise<StageOutput> => {
+    const perfBeginId = `brisk-pipeline-stage-begin:${id}`;
+    const perfEndId = `brisk-pipeline-stage-end:${id}`;
+
+    performance.mark(perfBeginId);
+
+    const result = await buildStep(input, configOptions);
+
+    performance.mark(perfEndId);
+    performance.measure(
+      `brisk-pipeline-stage-duration:${id}`,
+      perfBeginId,
+      perfEndId,
+    );
+
+    return result;
+  };
+};