yeoman-generator 5.4.2 → 5.6.0

package/lib/actions/install.js

@@ -6,8 +6,14 @@ const dargs = require('dargs');
 const chalk = require('chalk');
 
 /**
+ * @deprecated since version 5.0.0.
+ * Not included by default.
  * @mixin
  * @alias actions/install
+ *
+ * @example
+ * const Generator = require('yeoman-generator');
+ * _.extend(Generator.prototype, require('yeoman-generator/lib/actions/install'));
  */
 const install = module.exports;
 

package/lib/actions/package-json.js

@@ -1,10 +1,10 @@
 'use strict';
 
-/**
- * @mixin
- * @alias actions/packege-json
- */
 module.exports = (cls) =>
+  /**
+   * @mixin
+   * @alias actions/package-json
+   */
   class extends cls {
     /**
      * @private
@@ -42,6 +42,9 @@ module.exports = (cls) =>
     /**
      * Add dependencies to the destination the package.json.
      *
+     * Environment watches for package.json changes at `this.env.cwd`, and triggers an package manager install if it has been committed to disk.
+     * If package.json is at a different folder, like a changed generator root, propagate it to the Environment like `this.env.cwd = this.destinationPath()`.
+     *
      * @param {Object|string|string[]} dependencies
      * @return {Promise} a 'packageName: packageVersion' object
      */
@@ -54,6 +57,9 @@ module.exports = (cls) =>
     /**
      * Add dependencies to the destination the package.json.
      *
+     * Environment watches for package.json changes at `this.env.cwd`, and triggers an package manager install if it has been committed to disk.
+     * If package.json is at a different folder, like a changed generator root, propagate it to the Environment like `this.env.cwd = this.destinationPath()`.
+     *
      * @param {Object|string|string[]} dependencies
      * @return {Promise} a 'packageName: packageVersion' object
      */

package/lib/index.js

@@ -101,8 +101,8 @@ class Generator extends Base {
    * Every generator should extend this base class.
    *
    * @constructor
+   * @augments actions/package-json
    * @mixes actions/help
-   * @mixes actions/install
    * @mixes actions/spawn-command
    * @mixes actions/user
    * @mixes actions/fs
@@ -335,10 +335,27 @@ class Generator extends Base {
    *
    * @param  {Object[]} priorities - Priorities
    * @param  {String} priorities.priorityName - Priority name
-   * @param  {String} priorities.before - The new priority will be queued before the `before` priority.
+   * @param  {String} [priorities.before] - The new priority will be queued before the `before` priority. Required for new priorities.
    * @param  {String} [priorities.queueName] - Name to be used at grouped-queue
+   * @param  {boolean} [priorities.edit] - Edit a priority
+   * @param  {boolean} [priorities.skip] - Queued manually only
+   * @param  {Object[]|function} [priorities.args] - Arguments to pass to tasks
    */
   registerPriorities(priorities) {
+    priorities = priorities.filter((priority) => {
+      if (priority.edit) {
+        const queue = this._queues[priority.priorityName];
+        if (!queue) {
+          throw new Error(
+            `Error editing priority ${priority.priorityName}, not found`
+          );
+        }
+
+        Object.assign(queue, {...priority, edit: undefined});
+      }
+
+      return !priority.edit;
+    });
     const customPriorities = priorities.map((customPriority) => {
       // Keep backward compatibility with name
       const newPriority = {
@@ -849,40 +866,25 @@ class Generator extends Base {
   }
 
   /**
-   * Schedule methods on a run queue.
+   * Schedule tasks from a group on a run queue.
    *
    * @param {Object}          taskGroup: Object containing tasks.
    * @param {TaskOptions} [taskOptions]: options.
    */
   queueTaskGroup(taskGroup, taskOptions) {
-    // Run each queue items
-    _.each(taskGroup, (newMethod, newMethodName) => {
-      if (!_.isFunction(newMethod) || !methodIsValid(newMethodName)) return;
-
-      this.queueTask({
-        ...taskOptions,
-        method: newMethod,
-        taskName: newMethodName
-      });
+    this.extractTasksFromGroup(taskGroup, taskOptions).forEach((task) => {
+      this.queueTask(task);
     });
   }
 
   /**
    * @private
-   * Schedule a generator's method on a run queue.
+   * Extract tasks from a priority.
    *
    * @param {String}  name: The method name to schedule.
    * @param {TaskOptions} [taskOptions]: options.
    */
-  queueOwnTask(name, taskOptions = {}) {
-    const {taskPrefix} = this.features;
-    const propertyName = taskPrefix ? `${taskPrefix}${name}` : name;
-    const property = Object.getOwnPropertyDescriptor(
-      Object.getPrototypeOf(this),
-      propertyName
-    );
-    const item = property.value ? property.value : property.get.call(this);
-
+  extractTasksFromPriority(name, taskOptions = {}) {
     const priority = this._queues[name];
     taskOptions = {
       ...priority,
@@ -891,20 +893,63 @@ class Generator extends Base {
       ...taskOptions
     };
 
-    // Name points to a function; run it!
+    if (taskOptions.auto && priority && priority.skip) {
+      return [];
+    }
+
+    const {taskPrefix} = this.features;
+    const propertyName = taskPrefix ? `${taskPrefix}${name}` : name;
+    const property = Object.getOwnPropertyDescriptor(
+      taskOptions.taskOrigin || Object.getPrototypeOf(this),
+      propertyName
+    );
+    if (!property) return [];
+
+    const item = property.value ? property.value : property.get.call(this);
+
+    // Name points to a function; single task
     if (typeof item === 'function') {
-      taskOptions.taskName = name;
-      taskOptions.method = item;
-      this.queueTask(taskOptions);
-      return;
+      return [{...taskOptions, taskName: name, method: item}];
     }
 
-    // Not a queue hash; stop
-    if (!priority) {
-      return;
+    if (!item || !priority) {
+      return [];
     }
 
-    this.queueTaskGroup(item, taskOptions);
+    return this.extractTasksFromGroup(item, taskOptions);
+  }
+
+  /**
+   * @private
+   * Extract tasks from group.
+   *
+   * @param {Object}  group: Task group.
+   * @param {TaskOptions} [taskOptions]: options.
+   */
+  extractTasksFromGroup(group, taskOptions) {
+    return Object.entries(group)
+      .map(([taskName, method]) => {
+        if (typeof method !== 'function' || !methodIsValid(taskName)) return;
+        return {
+          ...taskOptions,
+          method,
+          taskName
+        };
+      })
+      .filter(Boolean);
+  }
+
+  /**
+   * @private
+   * Schedule a generator's method on a run queue.
+   *
+   * @param {String}  name: The method name to schedule.
+   * @param {TaskOptions} [taskOptions]: options.
+   */
+  queueOwnTask(name, taskOptions) {
+    this.extractTasksFromPriority(name, taskOptions).forEach((task) =>
+      this.queueTask(task)
+    );
   }
 
   /**
@@ -975,6 +1020,8 @@ class Generator extends Base {
 
     for (const methodName of validMethods)
       this.queueOwnTask(methodName, taskOptions);
+
+    this.emit('queueOwnTasks');
   }
 
   /**
@@ -983,24 +1030,11 @@ class Generator extends Base {
    * @param {Task} task: Task to be queued.
    */
   queueTask(task) {
-    const {reject, queueName = 'default', taskName: methodName, method} = task;
-    const once = task.once ? methodName : undefined;
-
-    const priority = Object.entries(this._queues).find(
-      ([_, options]) => options.queueName === queueName
-    );
-    const priorityName = priority ? priority[0] : undefined;
+    const {queueName = 'default', taskName: methodName, run, once} = task;
 
-    const self = this;
     const {runLoop} = this.env;
-    let namespace = '';
-    if (self.options && self.options.namespace) {
-      namespace = self.options.namespace;
-    }
-
-    // Task status allows to ignore (cancel) current queued tasks.
-    // Each queueOwnTasks (complete run) create a new taskStatus.
-    const taskStatus = this._taskStatus || {};
+    const {_taskStatus: taskStatus, options = {}} = this;
+    const {namespace = ''} = options;
 
     debug(
       `Queueing ${namespace}#${methodName} with options %o`,
@@ -1010,59 +1044,94 @@ class Generator extends Base {
       queueName,
       // Run-queue's done(continue), pause
       (continueQueue) => {
-        debug(`Running ${namespace}#${methodName}`);
-        self.emit(`method:${methodName}`);
-        const taskCancelled = task.cancellable && taskStatus.cancelled;
-        if (taskCancelled) {
-          continueQueue();
-          return;
-        }
-
-        runAsync(function () {
-          self.async = () => this.async();
-          self.runningState = {namespace, queueName, methodName};
-          return method.apply(self, self.args);
-        })()
-          .then(() => {
-            delete self.runningState;
-            const eventName = `done$${
-              namespace || 'unknownnamespace'
-            }#${methodName}`;
-            debug(`Done event ${eventName}`);
-            self.env.emit(eventName, {
-              namespace,
-              generator: self,
-              queueName,
-              priorityName
-            });
-            continueQueue();
-          })
-          .catch((error) => {
-            debug(
-              `An error occured while running ${namespace}#${methodName}`,
-              error
-            );
-            if (reject) {
-              debug('Rejecting task promise, queue will continue normally');
-              reject(error);
-              continueQueue();
-              return;
-            }
-
-            delete self.runningState;
-            try {
-              self.env.emit('error', error);
-            } catch (error) {
-              setImmediate(() => {
-                throw error;
-              });
-            }
-          });
+        this.executeTask(task, undefined, taskStatus).then(continueQueue);
       },
-      {once, run: task.run}
+      {once: once ? methodName : undefined, run}
     );
   }
 
+  /**
+   * @private
+   * Execute a task.
+   *
+   * @param {Task} task: Task to be executed.
+   * @param {string[]} args: Task arguments.
+   * @param {Object} taskStatus.
+   * @return Promise
+   */
+  executeTask(
+    task,
+    args = task.args || this.args,
+    taskStatus = this._taskStatus || {}
+  ) {
+    return new Promise((resolve) => {
+      const {
+        reject,
+        queueName = 'default',
+        taskName: methodName,
+        method
+      } = task;
+      const {namespace = ''} = this.options || {};
+      args = typeof args === 'function' ? args(this) : args;
+
+      const priority = Object.entries(this._queues).find(
+        ([_, options]) => options.queueName === queueName
+      );
+      const priorityName = priority ? priority[0] : undefined;
+
+      debug(`Running ${namespace}#${methodName}`);
+      this.emit(`method:${methodName}`);
+      const taskCancelled = task.cancellable && taskStatus.cancelled;
+      if (taskCancelled) {
+        resolve();
+        return;
+      }
+
+      const generator = this;
+
+      runAsync(function () {
+        generator.async = () => this.async();
+        generator.runningState = {namespace, queueName, methodName};
+        return method.apply(generator, args);
+      })()
+        .then(() => {
+          delete this.runningState;
+          const eventName = `done$${
+            namespace || 'unknownnamespace'
+          }#${methodName}`;
+          debug(`Done event ${eventName}`);
+          this.env.emit(eventName, {
+            namespace,
+            generator: this,
+            queueName,
+            priorityName
+          });
+          resolve();
+        })
+        .catch((error) => {
+          debug(
+            `An error occured while running ${namespace}#${methodName}`,
+            error
+          );
+          if (reject) {
+            debug('Rejecting task promise, queue will continue normally');
+            reject(error);
+            resolve();
+            return;
+          }
+
+          delete this.runningState;
+          try {
+            this.env.emit('error', error);
+          } catch (error) {
+            setImmediate(() => {
+              throw error;
+            });
+          }
+        });
+    });
+  }
+
   /**
    * Generator config Storage.
    */
@@ -1075,7 +1144,23 @@ class Generator extends Base {
   }
 
   /**
-   * Package.json Storage.
+   * Package.json Storage resolved to `this.destinationPath('package.json')`.
+   *
+   * Environment watches for package.json changes at `this.env.cwd`, and triggers an package manager install if it has been committed to disk.
+   * If package.json is at a different folder, like a changed generator root, propagate it to the Environment like `this.env.cwd = this.destinationPath()`.
+   *
+   * @example
+   * this.packageJson.merge({
+   *   scripts: {
+   *     start: 'webpack --serve',
+   *   },
+   *   dependencies: {
+   *     ...
+   *   },
+   *   peerDependencies: {
+   *     ...
+   *   },
+   * });
    */
   get packageJson() {
     if (!this._packageJson) {
@@ -1104,7 +1189,7 @@ class Generator extends Base {
   startOver(options = {}) {
     this.cancelCancellableTasks();
     Object.assign(this.options, options);
-    this.queueOwnTasks();
+    this.queueOwnTasks({auto: true});
   }
 
   /**
@@ -1143,7 +1228,7 @@ class Generator extends Base {
     debug(
       `Queueing generator ${this.options.namespace} with generator version ${this.yoGeneratorVersion}`
     );
-    this.queueOwnTasks();
+    this.queueOwnTasks({auto: true});
 
     if (this._composedWith.some((generator) => generator.then)) {
       return Promise.all(this._composedWith).then(async (generators) => {
@@ -1315,23 +1400,36 @@ this.composeWith({
    * Return a storage instance.
    * @param  {String} storePath  The path of the json file
    * @param  {String} [path] The name in which is stored inside the json
-   * @param  {String} [lodashPath] Treat path as an lodash path
+   * @param  {boolean|Object} [options] Treat path as an lodash path
    * @return {Storage} json storage
    */
-  createStorage(storePath, path, lodashPath = false) {
+  createStorage(storePath, path, options) {
+    if (typeof path === 'object') {
+      options = path;
+      path = undefined;
+    } else if (typeof options === 'boolean') {
+      options = {lodashPath: options};
+    }
+
     storePath = this.destinationPath(storePath);
-    return new Storage(path, this.fs, storePath, lodashPath);
+    return new Storage(path, this.fs, storePath, options);
   }
 
   /**
    * Return a storage instance.
    * @param  {String} [rootName] The rootName in which is stored inside .yo-rc.json
+   * @param  {object} [options] Storage options
    * @return {Storage} Generator storage
    * @private
    */
-  _getStorage(rootName = this.rootGeneratorName()) {
+  _getStorage(rootName = this.rootGeneratorName(), options) {
+    if (typeof rootName === 'object') {
+      options = rootName;
+      rootName = this.rootGeneratorName();
+    }
+
     const storePath = path.join(this.destinationRoot(), '.yo-rc.json');
-    return new Storage(rootName, this.fs, storePath);
+    return new Storage(rootName, this.fs, storePath, options);
   }
 
   /**

package/lib/util/storage.js

@@ -1,6 +1,7 @@
 'use strict';
 const assert = require('assert');
 const _ = require('lodash');
+const sortKeys = require('sort-keys');
 
 /**
  * Proxy handler for Storage
@@ -41,6 +42,7 @@ const proxyHandler = {
  * @param {Boolean} [options.lodashPath=false] Set true to treat name as a lodash path.
  * @param {Boolean} [options.disableCache=false] Set true to disable json object cache.
  * @param {Boolean} [options.disableCacheByFile=false] Set true to cleanup cache for every fs change.
+ * @param {Boolean} [options.sorted=false] Set true to write sorted json.
  *
  * @example
  * class extend Generator {
@@ -62,9 +64,10 @@ class Storage {
     }
 
     _.defaults(options, {
-      lodash: false,
+      lodashPath: false,
       disableCache: false,
-      disableCacheByFile: false
+      disableCacheByFile: false,
+      sorted: false
     });
 
     assert(configPath, 'A config filepath is required to create a storage');
@@ -76,6 +79,7 @@ class Storage {
     this.lodashPath = options.lodashPath;
     this.disableCache = options.disableCache;
     this.disableCacheByFile = options.disableCacheByFile;
+    this.sorted = options.sorted;
 
     this.existed = Object.keys(this._store).length > 0;
 
@@ -113,6 +117,10 @@ class Storage {
    * @private
    */
   _persist(value) {
+    if (this.sorted) {
+      value = sortKeys(value, {deep: true});
+    }
+
     let fullStore;
     if (this.name) {
       fullStore = this.fs.readJSON(this.path, {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeoman-generator",
-  "version": "5.4.2",
+  "version": "5.6.0",
   "description": "Rails-inspired generator system that provides scaffolding for your apps",
   "homepage": "http://yeoman.io",
   "author": "Yeoman",
@@ -22,12 +22,12 @@
     "app"
   ],
   "config": {
-    "doc_path": "./yeoman-generator-doc"
+    "doc_path": "../yeoman-generator-doc/"
   },
   "devDependencies": {
     "coveralls": "^3.0.3",
     "inquirer": "^7.3.2",
-    "jsdoc": "^3.6.3",
+    "jsdoc": "^3.6.7",
     "mem-fs": "^2.1.0",
     "mem-fs-editor": "^9.0.0",
     "mocha": "^8.0.1",
@@ -55,9 +55,9 @@
     "pretest": "xo",
     "test": "nyc mocha --forbid-only",
     "doc": "npm run doc:generate && npm run doc:fix && npm run doc:prettier",
-    "doc:generate": "jsdoc -c jsdoc.json -d $npm_package_config_doc_path",
-    "doc:prettier": "prettier $npm_package_config_doc_path --write --ignore-path .prettierignore-doc",
-    "doc:fix": "sed -i -e 's:^[[:space:]]*<!--[[:space:]]*$::g' -e 's:^[[:space:]]*-->[[:space:]]*$::g' $npm_package_config_doc_path/global.html || true",
+    "doc:generate": "jsdoc -c jsdoc.json -d $npm_package_config_doc_path$DOC_FOLDER",
+    "doc:prettier": "prettier $npm_package_config_doc_path$DOC_FOLDER --write --ignore-path .prettierignore-doc",
+    "doc:fix": "sed -i -e 's:^[[:space:]]*<!--[[:space:]]*$::g' -e 's:^[[:space:]]*-->[[:space:]]*$::g' $npm_package_config_doc_path$DOC_FOLDER/global.html || true",
     "coverage": "nyc report --reporter=text-lcov | coveralls"
   },
   "dependencies": {
@@ -71,7 +71,8 @@
     "read-pkg-up": "^7.0.1",
     "run-async": "^2.0.0",
     "semver": "^7.2.1",
-    "shelljs": "^0.8.4",
+    "shelljs": "^0.8.5",
+    "sort-keys": "^4.2.0",
     "text-table": "^0.2.0"
   },
   "peerDependencies": {