Merge pull request #334 from primer/shawnbot/module-generator

Add new module generator

Author: shawnbot

.travis.yml

@@ -9,9 +9,6 @@ env:
     # github
     - secure: "J+1oWjvvXjyrwkY/4IFWKdN/weFmQcPwlRuFG4R0Gb3rYe4nqtC9l68sJvmS8asc8dQMhOhcUZCH6sjvo7l2WD4NuK4umPSbs+rJNUsfbvH4pZjStQIj/3ll1OfQelGDWAYQWhIfciYY4F3Bp0ZWTfKOppLQ2AVIYu1fPVXDdlo="
 
-before_script:
-  - lerna bootstrap
-
 script:
   - npm test
 

modules/generator-primer-module/README.md

@@ -0,0 +1,107 @@
+# Primer CSS Module Generator
+
+[![npm version](http://img.shields.io/npm/v/generator-primer-module.svg)](https://www.npmjs.org/package/generator-primer-module)
+[![Build Status](https://travis-ci.org/primer/primer-css.svg?branch=master)](https://travis-ci.org/primer/primer-css)
+
+Primer is the CSS framework that powers GitHub's front-end design. This is a
+[Yeoman] generator that we use to scaffold new Primer modules.
+
+## Usage
+
+### In the Monorepo
+
+1. `cd` to the top level directory of the `primer-css` repository
+1. Run:
+
+    ```sh
+    npm run new-module
+    ```
+
+    You can also pass the module name as a positional argument like this:
+
+    ```sh
+    npm run new-module -- primer-module-name
+    ```
+
+1. Answer the interactive prompts.
+
+    > If you don't know some of the answers (aside from the module name, which
+    > is required), it's okay to press <kbd>enter</kbd> or <kbd>return</kbd>.
+
+1. If all goes well, the new module will be bootstrapped and ready to use. You
+   should see a directory with this structure:
+
+    ```
+    modules/primer-module-name/
+    ├── LICENSE
+    ├── README.md
+    ├── index.scss
+    ├── lib
+    │   └── module-name.scss
+    └── package.json
+    ```
+
+1. If you have any TODOs left from unanswered prompts, fill them out! You can
+   list them again with:
+
+   ```sh
+   ack TODO modules/primer-module-name
+   ```
+
+   (Note: you can use `grep` if you don't have `ack` installed.)
+
+
+### Standalone installation
+
+This repository is distributed with [npm][npm]. After [installing
+npm][install-npm], you can install `generator-primer-module` with this command.
+
+```sh
+npm install --save generator-primer-module
+```
+
+You'll also need to install the [`yo` CLI](https://github.com/yeoman/yo):
+
+```sh
+npm install -g yo
+```
+
+### Standalone usage
+
+It's possible to use this generator to create "standalone" Primer modules that
+live outside of the Primer CSS monorepo, with the following caveats:
+
+* When prompted to add the new module to existing meta-packages, you will need
+  to un-select them all.
+* You will also need to manually install all of the monorepo's top-level dev
+  dependencies to get tools like `primer-module-build` and `ava`.
+* The `npm test` command will not work, because it references a test spec in
+  the monorepo.
+
+To run the generator, just pass `primer-module` to the `yo` CLI:
+
+```sh
+yo primer-module
+```
+
+Then answer the interactiv prompts. **Note that, unlike most other generators,
+this one creates a new directory with the provided module name in the current
+working directory.**
+
+You can also pass the module name as a positional argument, as in:
+
+```sh
+yo primer-module primer-foo-bar
+```
+
+
+## License
+
+[MIT](./LICENSE) &copy; [GitHub](https://github.com/)
+
+[primer]: https://github.com/primer/primer
+[docs]: http://primercss.io/
+[npm]: https://www.npmjs.com/
+[install-npm]: https://docs.npmjs.com/getting-started/installing-node
+[sass]: http://sass-lang.com/
+[yeoman]: http://yeoman.io

modules/generator-primer-module/app/index.js

@@ -0,0 +1,175 @@
+const chalk = require("chalk")
+const fse = require("fs-extra")
+const path = require("path")
+const Generator = require("yeoman-generator")
+
+const stripPrimerPrefix = require("./lib/strip-prefix")
+
+const OPTIONS = require("./options")
+
+module.exports = class PrimerModule extends Generator {
+
+  constructor(args, opts) {
+    super(args, opts)
+
+    // initialize positional arguments and option flags
+    Object.entries(OPTIONS).forEach(([name, val]) => {
+      if (val.argument) {
+        this.argument(name, Object.assign(val.argument, {name}))
+      } else if (val.option) {
+        const option = Object.assign(val.option, {name})
+        if (name.includes("_")) {
+          const alias = name.replace(/_/g, "-")
+          option.alias = option.alias
+            ? [alias].concat(option.alias)
+            : alias
+        }
+        this.option(name, option)
+      }
+    })
+  }
+
+  initializing() {
+    // this.log("It looks like you are adding a new Primer module!")
+  }
+
+  prompting() {
+    if (this.options.module) {
+      this.log(
+        "Okay, let's get you started with %s...",
+        chalk.green(this.options.module)
+      )
+    }
+
+    // filter out options without prompts, and which already
+    // have options set, then add back the "name" key to each
+    const prompts = Object.entries(OPTIONS)
+      .filter(([name, {prompt}]) => {
+        return prompt && (
+          prompt.when === true || typeof this.options[name] === "undefined"
+        )
+      })
+      .map(([name, {prompt}]) => {
+        // bind functions to the generator as `this`
+        Object.keys(prompt).forEach(key => {
+          if (typeof prompt[key] === "function") {
+            prompt[key] = prompt[key].bind(this)
+          }
+        })
+        return Object.assign(prompt, {name})
+      })
+
+    // remove prompts for which arguments were already provided
+    return this.prompt(prompts)
+      .then(answers => {
+        Object.assign(this.options, answers)
+      })
+  }
+
+  configuring() {
+    this.dependencies = this._getDependencies()
+    if (this.options.docs) {
+      return fse.readFile(this.options.docs, "utf8")
+        .then(docs => this.options.docs = docs)
+    }
+  }
+
+  paths() {
+    this.basePath = this.destinationPath(this.options.module)
+  }
+
+  writing() {
+    this.log("creating: %s", chalk.green(this.basePath))
+
+    const data = {
+      "dependencies": this.dependencies,
+    }
+
+    Object.assign(
+      data,
+      Object.entries(OPTIONS)
+        .map(([name, value]) => [name, this.options[name]])
+        .reduce((acc, [name, value]) => {
+          acc[name] = value
+          return acc
+        }, {})
+    )
+
+    if (this.options.verbose) {
+      const debugData = Object.assign({}, data, {
+        "dependencies": Object.keys(data.dependencies),
+      })
+      console.warn(chalk.green("data:"), JSON.stringify(debugData, null, "  "))
+    }
+
+    // for the index.scss import
+    data.lib = stripPrimerPrefix(data.module)
+
+    // copy the whole directory with each file treated as
+    // an EJS template
+    this.fs.copyTpl(
+      this.templatePath(),
+      this.basePath,
+      data
+    )
+
+    const src = path.join(this.basePath, "lib/module.scss")
+    const dest = src.replace("module.scss", `${data.lib}.scss`)
+    this.fs.move(src, dest)
+  }
+
+  install() {
+    const pkg = this.fs.readJSON(
+      path.join(this.basePath, "package.json")
+    )
+    // this.log("package:", pkg.name, "@", pkg.version)
+
+    const dependents = this.options.dependents
+    if (Array.isArray(dependents)) {
+      dependents.forEach(dependent => {
+        this._addAsDependencyTo(pkg, dependent)
+      })
+    } else {
+      this.log(chalk.red("No dependents!"), dependents)
+    }
+  }
+
+  end() {
+    if (this.options.todo === true) {
+      this.log(
+        "\n📝 ",
+        chalk.bold("Remember to fill in any remaining TODOs below:"),
+        "\n"
+      )
+      this.spawnCommandSync("ack", ["TODO", this.basePath], {
+        stdio: "inherit",
+      })
+    }
+  }
+
+  _getDependencies() {
+    return [
+      "primer-support",
+    ].reduce((deps, module) => {
+      deps[module] = require(`${module}/package.json`)
+      return deps
+    }, {})
+  }
+
+  _addAsDependencyTo(pkg, dest) {
+    this.log(
+      "adding %s@%s as a dependency to %s...",
+      pkg.name, pkg.version, dest
+    )
+
+    const destPath = require.resolve(
+      path.join("../../", dest, "package.json")
+    )
+
+    this.fs.extendJSON(destPath, {
+      dependencies: {
+        [pkg.name]: pkg.version,
+      },
+    })
+  }
+}

modules/generator-primer-module/app/lib/capitalize.js

@@ -0,0 +1,5 @@
+module.exports = str => {
+  return str.split("-")
+    .map(word => word.charAt(0).toUpperCase() + word.substr(1).toLowerCase())
+    .join(" ")
+}

modules/generator-primer-module/app/lib/strip-prefix.js

@@ -0,0 +1 @@
+module.exports = str => str.replace(/^primer-/, "")