refactor: typescript projects & docs generation

.eslintrc.json

@@ -39,7 +39,9 @@
       "files": ["packages/*/*/test/**/*_spec*.ts"],
       "rules": {
         "global-require": "off",
-        "import/no-dynamic-require": "off"
+        "import/no-dynamic-require": "off",
+        "node/no-unpublished-import": "off",
+        "node/no-unpublished-require": "off"
       }
     },
     {

.github/workflows/ci.yml

@@ -115,6 +115,8 @@ jobs:
           npm install -g bolt@$BOLT_VERSION
       - name: Install
         run: bolt
+      - name: Build
+        run: bolt build
       - name: Test
         run: bolt coverage:slow
         env:
@@ -160,21 +162,14 @@ jobs:
   #   needs: [fast-tests, slow-tests]
   #   runs-on: [ubuntu-latest]
   #   steps:
-  #     - uses: actions/checkout@v1
-  #     - name: Use Node.js 12.x
-  #       uses: actions/setup-node@v2.5.1
+  #     - name: Checkout
+  #       uses: actions/checkout@v1
+  #     - name: Use Node.js 16
+  #       uses: actions/setup-node@v3.1.1
   #       with:
-  #         node-version: 12.x
+  #         node-version: '16'
   #         cache: yarn
   #     - name: Install bolt
-  #       shell: bash
-  #       run: |
-  #         case "$(uname -s)" in
-  #           Windows*|CYGWIN*|MINGW*|MSYS*) BOLT_VERSION=0.21.2 ;;
-  #           *) BOLT_VERSION=latest ;;
-  #         esac
-  #         npm install -g bolt@$BOLT_VERSION
-  #     - name: Deploy docs
-  #       run: ci/docs.sh
-  #       env:
-  #         NOW_TOKEN: ${{ secrets.NOW_TOKEN }}
+  #       run: npm install -g bolt
+  #     - name: Generate docs
+  #       run: bolt docs:deploy:build

.github/workflows/gh-pages.yml

@@ -0,0 +1,45 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+          fetch-depth: 0
+
+      - name: Use Node.js LTS
+        uses: actions/setup-node@v2.5.1
+        with:
+          node-version: 16.x
+          cache: yarn
+
+      - name: Install Bolt CLI
+        shell: bash
+        run: |
+          case "$(uname -s)" in
+            Windows*|CYGWIN*|MINGW*|MSYS*) BOLT_VERSION=0.21.2 ;;
+            *) BOLT_VERSION=latest ;;
+          esac
+          npm install -g bolt@$BOLT_VERSION
+
+      - name: Build
+        shell: bash
+        run: |
+          bolt
+          bolt docs
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs

.gitignore

@@ -7,15 +7,11 @@ docs
 doc
 node_modules
 yarn-error.log
-**/.npmignore
-!/.npmignore
-**/tsconfig.json
-!/tsconfig.json
+packages/**/.npmignore
+packages/**/tsconfig.json
 !packages/template/*/tmpl/tsconfig.json
-**/tslint.json
-!/tslint.json
-**/yarn.lock
-!/yarn.lock
+packages/**/tslint.json
+packages/**/yarn.lock
 packages/*/*/index.ts
 packages/.old
 packages/utils/types/index.d.ts
@@ -25,4 +21,6 @@ packages/plugin/**/README.md
 packages/api/cli/README.md
 !packages/**/base/README.md
 !/README.md
+packages/**/tsconfig.tsbuildinfo
+packages/**/.swc
 .webpack

.mocharc.js

@@ -2,8 +2,7 @@ const path = require('path');
 
 module.exports = {
   extension: ['ts'],
-  loader: 'ts-node/esm',
-  require: [path.join(__dirname, 'tools', 'test-setup.ts')],
+  require: ['ts-node/register', path.join(__dirname, 'tools', 'test-setup.ts')],
   timeout: 800000,
   recursive: true,
 };

package.json

@@ -18,22 +18,19 @@
     ]
   },
   "scripts": {
-    "clean": "rimraf dist && bolt ws exec -- rimraf dist",
-    "prebuild": "bolt clean && ts-node tools/link-ts.ts && ts-node tools/copy-shared-types.ts && tsc --project ./tsconfig.packages.json --emitDeclarationOnly && ts-node tools/copy-types.ts",
-    "build": "yarn build:quick",
-    "build:quick": "bolt ws exec -- swc src --out-dir dist --quiet --extensions \".ts\" --config-file ../../../.swcrc",
+    "clean": "rimraf dist && bolt ws exec -- rimraf dist tsconfig.tsbuildinfo",
+    "build": "bolt ws exec -- tsc --emitDeclarationOnly && bolt ws exec -- swc src --out-dir dist --quiet --extensions \".ts\" --config-file ../../../.swcrc",
+    "build:full": "bolt ws exec -- tsc -b",
     "postbuild": "ts-node tools/test-dist",
-    "coverage:fast": "xvfb-maybe cross-env INTEGRATION_TESTS=0 TS_NODE_FILES=true nyc mocha './tools/test-globber.ts' && nyc report --reporter=text-lcov > coverage.lcov",
-    "coverage:slow": "xvfb-maybe cross-env TS_NODE_FILES=true nyc mocha './tools/test-globber.ts' --integration && nyc report --reporter=text-lcov > coverage.lcov",
-    "docs": "bolt docs:generate && bolt docs:position",
-    "docs:generate": "bolt ws exec -- node_modules/.bin/typedoc --out doc --excludeExternals --ignoreCompilerErrors --mode file --excludePrivate --excludeProtected --hideGenerator",
-    "docs:position": "ts-node tools/position-docs.ts",
-    "docs:deploy": "ts-node tools/sync-readmes.ts && bolt docs && ts-node tools/copy-now.ts && cd docs && now && now alias",
-    "docs:deploy:ci": "ts-node tools/sync-readmes.ts && bolt docs && ts-node tools/copy-now.ts && cd docs && now --token $NOW_TOKEN && now alias --token $NOW_TOKEN",
+    "coverage:fast": "xvfb-maybe cross-env INTEGRATION_TESTS=0 TS_NODE_PROJECT='./tsconfig.test.json' TS_NODE_FILES=1 nyc mocha './tools/test-globber.ts' && nyc report --reporter=text-lcov > coverage.lcov",
+    "coverage:slow": "xvfb-maybe cross-env TS_NODE_PROJECT='./tsconfig.test.json' TS_NODE_FILES=1 nyc mocha './tools/test-globber.ts' --integration && nyc report --reporter=text-lcov > coverage.lcov",
+    "docs": "bolt build:full && bolt docs:generate",
+    "docs:generate": "node --max-old-space-size=8192 -r ts-node/register ./tools/gen-docs.ts",
+    "docs:deploy:build": "ts-node tools/sync-readmes.ts && bolt docs",
     "lint": "prettier --check . && eslint .",
-    "test": "xvfb-maybe cross-env TS_NODE_FILES=true mocha './tools/test-globber.ts'",
-    "test:fast": "xvfb-maybe cross-env TEST_FAST_ONLY=1 TS_NODE_FILES=true mocha './tools/test-globber.ts'",
-    "postinstall": "rimraf node_modules/.bin/*.ps1 && ts-node tools/link-ts.ts"
+    "test": "xvfb-maybe cross-env TS_NODE_PROJECT='./tsconfig.test.json' TS_NODE_FILES=1 mocha './tools/test-globber.ts'",
+    "test:fast": "xvfb-maybe cross-env TS_NODE_PROJECT='./tsconfig.test.json' TEST_FAST_ONLY=1 TS_NODE_FILES=1 mocha './tools/test-globber.ts'",
+    "postinstall": "rimraf node_modules/.bin/*.ps1 && ts-node ./tools/gen-tsconfigs.ts && ts-node ./tools/gen-ts-glue.ts"
   },
   "dependencies": {
     "@aws-sdk/abort-controller": "^3.29.0",
@@ -141,8 +138,8 @@
     "sinon": "^13.0.1",
     "sinon-chai": "^3.6.0",
     "ts-node": "^10.0.0",
-    "typedoc": "^0.22.0",
-    "typescript": "^4.5.4",
+    "typedoc": "^0.22.15",
+    "typescript": "^4.6.3",
     "xvfb-maybe": "^0.2.1"
   },
   "optionalDependencies": {

packages/installer/darwin/src/InstallerDarwin.ts

@@ -27,7 +27,7 @@ export default abstract class InstallerDarwin extends InstallerBase {
     if (writeAccess) {
       await promisify(exec)(moveCommand);
     } else {
-      await promisify(sudo.exec)(moveCommand, {
+      await (promisify(sudo.exec) as (cmd: string, opts: unknown) => Promise<unknown>)(moveCommand, {
         name: 'Electron Forge',
       });
     }

packages/utils/types/package.json

@@ -6,7 +6,7 @@
   "author": "Samuel Attard",
   "license": "MIT",
   "main": "dist/index.js",
-  "typings": "index.d.ts",
+  "typings": "dist/index.d.ts",
   "dependencies": {
     "@electron-forge/async-ora": "6.0.0-beta.63",
     "electron-packager": "^15.4.0",

tools/gen-docs.ts

@@ -0,0 +1,24 @@
+import * as path from 'path';
+import { getPackageInfo } from './utils';
+import * as typedoc from 'typedoc';
+
+(async () => {
+  const packages = await getPackageInfo();
+
+  const typedocApp = new typedoc.Application();
+  typedocApp.bootstrap({
+    entryPointStrategy: 'packages',
+    entryPoints: packages.map((pkg) => pkg.path),
+    excludeExternals: true,
+    excludePrivate: true,
+    excludeProtected: true,
+    hideGenerator: true,
+  });
+
+  const projReflection = typedocApp.convert();
+  if (projReflection === undefined) {
+    throw new Error('Failed to find package sources');
+  }
+
+  await typedocApp.generateDocs(projReflection, path.resolve(__dirname, '..', 'docs'));
+})().catch(console.error);

tools/gen-ts-glue.ts

@@ -0,0 +1,68 @@
+/**
+ * Mixing glue with lint is probably something you never want to do in real
+ * life, but in this project it helps the linter do its job. And sometimes the
+ * test suite too.
+ *
+ * This script creates `index.ts` files in each package directory that simply
+ * re-export the exports of the real main file. This is necessary for when all
+ * the packages are run under a common context (instead of each individually).
+ * This is because the symlinks bolt makes for each package are descendants of
+ * the context node is running in and therefore aren't treated as modules, only
+ * as directories. Therefore package.json isn't considered and we need an index
+ * file (like index.ts) to redirect to the right file.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getPackageInfo } from './utils';
+
+// NOTE: this interface only defines the fields in the package.json that are
+// used in this script
+interface PartialPackageManifest {
+  main?: string;
+}
+
+/**
+ * A heuristic to convert the `main` value from the package.json from its output
+ * location to the source location (e.g. dist/ to src/ & .js to .ts).
+ */
+function convertMainToSrc(main: string): string {
+  return main.replace(/^dist\//, 'src/').replace(/\.js$/, '.ts');
+}
+
+(async () => {
+  const pkgs = await getPackageInfo();
+
+  // Run each package in parallel
+  await Promise.all(
+    pkgs.map(async (pkg) => {
+      // Extract the `main` field from the package.json
+      const { main } = pkg.manifest as PartialPackageManifest;
+
+      // Skip packages that have no main (e.g. the cli as of writing)
+      if (main === undefined) {
+        return;
+      }
+
+      // Read the main file
+      const srcMain = convertMainToSrc(main);
+      const srcMainFull = path.resolve(pkg.path, srcMain);
+      const srcMainContents = await fs.readFile(srcMainFull, { encoding: 'utf8' });
+
+      // Detect if the package has a default export
+      const hasDefault = /export\s+default/i.test(srcMainContents);
+
+      // Write the facade entry-point file
+      const importTarget = './' + srcMain.replace(/\.ts$/, '');
+      const facadeFilePath = path.resolve(pkg.path, 'index.ts');
+      let facadeFileContents =
+        '// ⚠️ AUTOGENERATED ⚠️ AUTOGENERATED ⚠️ AUTOGENERATED ⚠️\n' +
+        '// This file was automatically generated by `tools/gen-ts-glue.ts`. Do not modify directly if you want to keep your changes.\n' +
+        `export * from "${importTarget}";\n`;
+      if (hasDefault) {
+        facadeFileContents += `import defaultExport from "${importTarget}";\n` + `export default defaultExport;\n`;
+      }
+      await fs.writeFile(facadeFilePath, facadeFileContents);
+    })
+  );
+})().catch(console.error);