Fixes and documentation for topcoder-lib-setup script

Fix for #15 and #12

Author: birdofpreyru

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Topcoder React Utils Changelog
 
+### v0.4.3
+- Removes `adopt-dev-deps` script (use
+  [`topcoder-lib-setup`](docs/topcoder-lib-setup-script.md) instead).
+
 ### v0.4.2
 Adds `topcoder-lib-setup` script, which should help to update our ReactJS
 libraries in the host packages. Not mentioned in the docs as it still pending

README.md

@@ -8,37 +8,34 @@ The [Topcoder](https://www.topcoder.com) collection of generic ReactJS
 configurations, components and utilities to be shared between all internal and
 external ReactJS projects developed by the Topcoder community.
 
-### Content
+## Content
 - [Installation](#installation)
-- [Configurations](#configurations)
-- [Components](#components)
-- [Utilities](#utilities)
+- [Reference](#reference)
+  - [Configurations](#configurations)
+  - [Components](#components)
+  - [NodeJS Scripts](#nodejs-scripts)
+  - [Utilities](#utilities)
 - [Development](#development)
 - [License](#license)
 
-### <a name="installation">Installation</a>
-Install this package as
+## Installation
+Install the package as
 ```bash
 $ npm install --save topcoder-react-utils
+$ ./node_modules/.bin/topcoder-lib-setup
 ```
-Import the global stylesheet into the root ReactJS component of your app:
+Then import the global stylesheet into the root ReactJS component of your app:
 ```js
 import 'topcoder-react-utils/dist/style.css';
 ```
 
-You are done if you only use components and utilities provided by this
-package. If you are to use configurations to build or test your code, you
-also need to install all development dependencies into your own package:
-```
-$ ./node_modules/.bin/adopt-dev-deps topcoder-react-utils
+To upgrade this library to the latest version just execute again
+```bash
+$ ./node_modules/.bin/topcoder-lib-setup
 ```
 
-Installed dev dependencies will be stored into your `package.json`, thus
-further invokations of `npm install` will automatically install them. You
-only need to call `adopt-dev-deps` again if you update
-`topcoder-react-utils` to a newer version.
-
-### <a name="configurations">Configurations</a>
+## Reference
+### Configurations
 - [**Babel Configurations**](docs/babel-config.md) &mdash; Standard
   configurations for [Babel](https://babeljs.io/);
 - [**ESLint Configurations**](docs/eslint-config.md) &mdash; Standard
@@ -50,7 +47,7 @@ only need to call `adopt-dev-deps` again if you update
 - [**Webpack Configurations**](docs/webpack-config.md) &mdash; Standard
   configurations for [Webpack](https://webpack.js.org/).
 
-### <a name="components">Components</a>
+### Components
 - [**`Avatar`**](docs/avatar.md) &mdash; The standard component for user avatars;
 - [**`Button`**](docs/button.md) &mdash; Handles buttons and button-like links
   (components that look like regular buttons, but behave as links) in the same
@@ -62,7 +59,11 @@ only need to call `adopt-dev-deps` again if you update
 - [**`ScalableRect`**](docs/scalable-rect.md) &mdash; Container that keeps
   the specified aspect ratio regardless the width you set.
 
-### <a name="utilities">Utilities</a>
+### NodeJS Scripts
+- [**topcoder-lib-setup**](docs/topcoder-lib-setup-script.md) &mdash; Helps to
+  install and upgrade **topcoder-react-utils** and other similar libraries.
+
+### Utilities
 - [**Client**](docs/client.md) &mdash; Client-side initialization code.
 - [**Config**](docs/config.md) &mdash; Isomorphic app config;
 - [**Global Styles**](docs/global-styles.md) &mdash; Global styles necessary for
@@ -81,7 +82,7 @@ only need to call `adopt-dev-deps` again if you update
 - [**Webpack**](docs/webpack-utils.md) &mdash; Various utils related to the
   Webpack bundling process.
 
-### <a name="development">Development</a>
+## Development
 For convenient development you can link this package into your host package:
 1.  Clone [`topcoder-react-utils`](https://github.com/topcoder-platform/topcoder-react-utils)
     to your machine, and checkout the branch you are going to work with;
@@ -118,5 +119,5 @@ any breaking changes into the codebase! Breaking changes should be done via
 `minor` or `major` update, and they should be documented in
 the [CHANGELOG](CHANGELOG.md).
 
-### <a name="license">License</a>
+## License
 Topcoder React Utils is [MIT Licensed](LICENSE.md)

bin/adopt-dev-deps

@@ -46,7 +46,8 @@ const HELP = [{
  *  into NPM's install command.
  */
 function generateTargetPackage(entry) {
-  if (entry[1].match(/^[^]/)) return `${entry[0]}@${entry[1].slice(1)}`;
+  if (entry[1].match(/^https?:\/\//)) return entry[1];
+  if (entry[1].match(/^[^~]/)) return `${entry[0]}@${entry[1].slice(1)}`;
   return `${entry[0]}@${entry[1]}`;
 }
 

bin/topcoder-lib-setup

@@ -0,0 +1,57 @@
+# `topcoder-lib-setup` script
+
+NodeJS script that helps to install and upgrade `topcoder-react-utils` and other
+similar NPM libraries maintained by Topcoder.
+
+**Why?** — When library version is upgraded manually, it is difficult
+to ensure the same versions of common dependencies are used by the upgraded
+library and by its host codebase. In some situations the mismatch of exact
+versions leads to odd issues, difficult to track. This script solves this
+problem.
+
+### Usage
+
+From the host package's root directory call it as:
+```sh
+$ ./node_modules/.bin/topcoder-lib-setup [OPTION]... [LIBRARY]...
+```
+Where `[OPTIONS]...` is an optional, whitespace-separated list of options (see
+below); and `[LIBRARY]...` is an optional, whitespace-separated list of libraries
+to update. If no library names are given, `topcoder-react-utils` is assumed by
+default.
+
+For each `library` specified in the `[LIBRARY]...` list, this script does the
+following:
+
+- Installs the specified (if `library` contains `@x.y.z` semver suffix), or
+  the latest (automatically appending `@latest` suffix to `library`) version
+  of `library` as a regular dependency of the host code. Specifically, it does:
+  ```bash
+  $ npm install --save library
+  ```
+
+- Installs all dev dependencies of `library` into the host code as dev
+  dependencies with exactly the same versions. Specifically, it generates
+  a whitespace-separated list `devDeps` of dev dependencies, then executes
+  ```bash
+  $ npm install --save-dev devDeps
+  ```
+
+- Updates regular dependencies or the host package, that are also used by
+  `library` to the same versions used by the library. Specifically, it generates
+  a whitespace-separated list of dependencies, `deps`, which is an intersection
+  of regular dependencies of `library` witht the set of regular dependencies of
+  the host code; and the version of each dependency in the list is taken from
+  the `library`'s `package.json`. Then it executes:
+  ```bash
+  $ npm install --save deps
+  ```
+
+Once the steps described above are completed for each library, the script
+executes `$ npm install` to ensure that any packages removed temporarily
+during those steps are installed back.
+
+### Options
+| Option | Alias | Description |
+| --- | --- | --- |
+| `--help` | `-h` | Prints to standard output the basic usage instructions.

docs/topcoder-lib-setup-script.md

@@ -1,6 +1,5 @@
 {
   "bin": {
-    "adopt-dev-deps": "./bin/adopt-dev-deps",
     "topcoder-lib-setup": "./bin/topcoder-lib-setup"
   },
   "bugs": {
@@ -9,6 +8,8 @@
   "dependencies": {
     "babel-runtime": "^6.26.0",
     "body-parser": "^1.18.3",
+    "command-line-args": "^5.0.2",
+    "command-line-usage": "^5.0.5",
     "compression": "^1.7.2",
     "config": "^1.30.0",
     "cookie-parser": "^1.4.3",
@@ -56,8 +57,6 @@
     "babel-preset-env": "^1.7.0",
     "babel-preset-react": "^6.24.1",
     "babel-preset-stage-2": "^6.24.1",
-    "command-line-args": "^5.0.2",
-    "command-line-usage": "^5.0.5",
     "css-loader": "^0.28.11",
     "eslint": "^4.19.1",
     "eslint-config-airbnb": "^16.1.0",