Feature/particle 11 add typescript, jest, tweak lerna, and update rea…

…dme (#849)

* add learn:bootstrap command and update readme with tutorial on how to get started

* set nvm to node 12

* * add typescript compilation
* add jest and configure for supporting both ts and js files
* swap create from js to ts and use es6 default export

* fix update:check and update:start scripts to use concurrency 1 allowing clearer update messages and for the cli to work on the update:start script

* update packages to latest dependency versions

* add tutorial for dev install and remove clean script. Add clean script directly into readme for how to quickly remove all package-lock.json files if you npm install anything

* WIP fix bin npm link inside of dist

* remove bin file from root particle library, add json and .md file copying using a src/scripts/build.ts file to copy files

* convert js files to ts

* clean up logs and change require to import

* update readme regarding installing a dependency via npm link

.gitignore

@@ -16,9 +16,12 @@ packages/*/package-lock.json
 # Dependencies
 node_modules
 
-#IDE Plugins
+# IDE Plugins
 .idea
 
 # Errors
 npm-debug.log
 php_errors.log
+
+# Typescript
+dist

.nvmrc

@@ -1 +1 @@
-10
+12

README.md

@@ -11,3 +11,49 @@ TBD
 ## Usage
 
 TBD
+
+## DEV Installation
+
+### Steps
+
+1. Clone the repo
+1. Run `npm install`, This will install all dev dependencies and run the postinstall script `lerna:install` which runs `lerna bootstrap --nohoist` and installs all package dependencies.
+1. If you update subdependencies, simply run `npm install` or `npm run lerna:install` to re-install lerna package dependencies. This is especially helpful when you are pulling in new code (with sub dependency additionas) from another branch.
+1. `npm run build:watch` build the project in the dist folder
+1. `npm run test:watch` to start jest in watch mode (recommended)
+
+### Installing A Dependency
+
+1. Run `npm run build`, build will fire off the `tsc` build script and also copy the package.json and README.md files from the `packages/*` directories directly into the dist folder. Alternatively have the compiler in watch mode `npm run build:watch` and run `npm run postbuild` to copy the files in.
+1. Cd into `dist/<REPO_NAME>` and run `npm link`, this will link the **bin** alias as an alias in your terminal. Example the bin is named `@phase2/particle-cli` therefore running `npx @phase2/particle-cli -v` will invoke the binary file `particle-cli`.
+
+#### Example
+
+```bash
+npm install
+cd dist; cd particle-cli;
+npm unlink particle-cli; npm unlink @phase2/particle-cli; // npm unlink should also work
+npm link;
+npx @phase2/particle-cli -V; // works
+particle-cli -V; // works
+@phase2/particle-cli; // fails as npm does not directly register the alias, only the binary file
+```
+
+### Clean the repo
+
+To remove package-lock.json from all levels of the repo simply run this command. PS is used to prevent grep from exiting as this throws an error with `lerna exec` even with the `--no-bail` flag.
+
+```bash
+ps -ef | (grep -q -s -R ^$1 package-lock.json && rm -rf package-lock.json) | { grep -v grep || true; }; lerna exec -- ps -ef | (grep -q -s -R ^$1 package-lock.json && rm -rf package-lock.json) | { grep -v grep || true; }
+```
+
+### Upgrading dependencies
+
+- `npm run update:check`: similar to `npm outdated`, it will check for outdated dependencies inside the root and lerna packages.
+- `npm run update:start`: initialized `npm-upgrade` for the root package and lerna packages. Allows for opting in to each upgrade with prompts.
+
+### How to run a package script
+
+```bash
+npx lerna run --scope @phase2/particle-cli test
+```

babel.config.js

@@ -0,0 +1,20 @@
+module.exports = {
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        useBuiltIns: 'entry',
+        target: { node: 12 },
+      },
+    ],
+    '@babel/preset-typescript',
+  ],
+  env: {
+    test: {
+      presets: [['@babel/preset-env']],
+    },
+    production: {
+      plugins: ['transform-remove-console'],
+    },
+  },
+}

jest.config.js

@@ -0,0 +1,20 @@
+module.exports = {
+  displayName: 'Particle CJS',
+  verbose: true,
+  preset: 'ts-jest',
+  moduleFileExtensions: ['js', 'ts', 'json'],
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.(ts)$': 'ts-jest',
+  },
+  globals: {
+    'ts-jest': {
+      diagnostics: true, // allows for type checking. Set to false only if you need to debug something quickly
+      tsConfig: 'tsconfig.json',
+    },
+  },
+  watchPlugins: [
+    'jest-watch-typeahead/filename',
+    'jest-watch-typeahead/testname',
+  ],
+}

lerna.json

@@ -1,5 +1,4 @@
 {
-  "version": "11.0.0",
   "npmClient": "npm",
   "command": {
     "publish": {
@@ -10,8 +9,6 @@
       "npmClientArgs": ["--no-package-lock"]
     }
   },
-  "packages": [
-    "packages/*"
-  ],
+  "packages": ["packages/*"],
   "version": "independent"
 }

package.json

@@ -13,7 +13,6 @@
     "Drupal"
   ],
   "homepage": "https://github.com/phase2/particle#readme",
-  "homepage": "https://github.com/phase2/particle#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/phase2/particle.git"
@@ -23,12 +22,34 @@
   },
   "license": "GPL-2.0",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "pretty-check": "prettier --check packages/**/*.js"
+    "lerna:install": "npx lerna bootstrap --hoist",
+    "postinstall": "npm run lerna:install",
+    "pretty-check": "prettier --check packages/**/*.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "build": "tsc -p tsconfig.json && npm run postbuild",
+    "postbuild": "ts-node ./src/scripts/build.ts",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "update:check": "npx ncu && npx lerna exec --concurrency 1 --no-bail -- npx ncu",
+    "update:start": "npm-upgrade && lerna exec --concurrency 1 -- npm-upgrade; npm run lerna:install"
   },
   "devDependencies": {
-    "eslint": "^6.8.0",
-    "lerna": "^3.20.2",
-    "prettier": "1.19.1"
-  }
+    "@babel/core": "^7.10.2",
+    "@babel/preset-env": "^7.10.2",
+    "@types/jest": "^26.0.0",
+    "babel-plugin-transform-remove-console": "^6.9.4",
+    "eslint": "^7.2.0",
+    "jest": "^26.0.1",
+    "jest-watch-typeahead": "^0.6.0",
+    "lerna": "^3.22.1",
+    "npm-check-updates": "^7.0.1",
+    "npm-upgrade": "^2.0.3",
+    "prettier": "2.0.5",
+    "ts-jest": "^26.1.0",
+    "ts-node": "^8.10.2",
+    "typescript": "^3.9.5"
+  },
+  "files": [
+    "dist/**/*"
+  ]
 }

packages/eslint-config/package.json

@@ -26,9 +26,9 @@
   },
   "license": "GPL-2.0",
   "devDependencies": {
-    "eslint": "^6.6.0"
+    "eslint": "^7.2.0"
   },
   "peerDependencies": {
-    "eslint": "^6.6.0"
+    "eslint": "^7.2.0"
   }
 }

packages/generator-particle-drupal/package.json

@@ -29,6 +29,6 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "yeoman-generator": "^4.4.0"
+    "yeoman-generator": "^4.10.1"
   }
 }

packages/particle-cli/__tests__/create.test.ts

@@ -0,0 +1,10 @@
+import create from '../lib/create'
+import repoPackage from '../package.json'
+
+const { name } = repoPackage
+
+describe(`${name}/create`, () => {
+  it('show log', () => {
+    expect(create()).toBeTruthy()
+  })
+})

packages/particle-cli/bin/particle-cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+const program = require('commander')
+// const pkg = require('../package'); // can't do since this is not copied over into dist unless its an import
+import pkg from '../package.json'
+const create = require('../lib/create')
+
+/**
+ * Initialize Commander program with version.
+ */
+program.version(pkg.version, '-V, --version')
+
+program
+  .command('create')
+  .alias('init')
+  .description('Scaffold your project from a set of prompts.')
+  .action(function () {
+    // @TODO Implement Create Function.
+    create()
+  })
+
+// allow commander to parse `process.argv`
+program.parse(process.argv)

packages/particle-cli/lib/create.js → packages/particle-cli/lib/create.ts

@@ -24,8 +24,9 @@
  *
  */
 
-const create = function() {
-  console.log('Create Particle Project');
-};
+const create = () => {
+  console.log('Create Particle Project')
+  return true
+}
 
-module.exports = create;
+export default create

packages/particle-cli/package.json

@@ -30,7 +30,7 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "commander": "^4.1.0",
+    "commander": "^5.1.0",
     "esm": "^3.2.25"
   }
 }

packages/stylelint-config/package.json

@@ -24,17 +24,17 @@
   },
   "license": "GPL-2.0",
   "dependencies": {
-    "stylelint-config-prettier": "^6.0.0",
-    "stylelint-order": "2.2.1",
+    "stylelint-config-prettier": "^8.0.1",
+    "stylelint-order": "4.1.0",
     "stylelint-prettier": "1.1.2",
-    "stylelint-scss": "3.13.0",
-    "stylelint": "^12.0.0"
+    "stylelint-scss": "3.17.2",
+    "stylelint": ">=13.6.0"
   },
   "devDependencies": {
-    "eslint": "^5.4.0",
-    "stylelint": "9.5.0"
+    "eslint": "^7.2.0",
+    "stylelint": ">=13.6.0"
   },
   "peerDependencies": {
-    "stylelint": ">=9.4.0"
+    "stylelint": ">=13.6.0"
   }
 }

src/scripts/build.ts

@@ -0,0 +1,34 @@
+import fs from 'fs'
+import { exec } from 'child_process'
+
+const distFolder = './dist' // add your scripts to folder named scripts
+const packagesFolder = './packages'
+const files = fs.readdirSync(distFolder) // reading files from folders
+
+enum CopyFiles {
+  README = 'README.md',
+  PACKAGE = 'package.json',
+}
+
+/**
+ * iterates through all dist packages and references the dist folder to the packages folder and grabs files unrelated to JS or TS that are required for publishing the package
+ *  */
+
+files.forEach((packageName: string) => {
+  const path = `${packagesFolder}/${packageName}`
+  const b = fs.readdirSync(path).forEach((item: string) => {
+    if (item === CopyFiles.README || item === CopyFiles.PACKAGE) {
+      exec(
+        `cp ${path}/${item} ${distFolder}/${packageName}/${item}`,
+        { shell: '/bin/bash' },
+        (err: any, stdout: any, stderr: any) => {
+          console.log(
+            `successfully wrote ${path}/${item} to dist`,
+            stdout,
+            stderr
+          )
+        }
+      )
+    }
+  })
+})

tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "target": "ES2020",
+    "moduleResolution": "node",
+    "sourceMap": true,
+    "outDir": "dist",
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "noImplicitAny": true
+  },
+  "include": ["packages/**/*"],
+  "exclude": ["node_modules", "**/__tests__/*"]
+}