feat(responsibilities): add class descriptions

#44,#187

lib/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("fs");
+const meow = require("meow");
+const path = require("path");
+// eslint-disable-next-line node/no-unsupported-features
+const { CLIEngine } = require("eslint");
+
+const msg = {
+  error: "❌  There was a problem generating your CRC Model report.\n   ",
+
+  success: "✅  CRC Model report generated at ",
+
+  usage: `
+  Usage
+    $ eslint-plugin-crc input [options] [info]
+
+  Input
+    The path (or glob) of the JavaScript resources you want
+    analyzed. [Default: '.']
+
+  Options
+    --output, -o  The "CRC Models report" destination directory.
+                  [Default: './reports']
+
+  Info
+    --help        Show this dialog.
+    --version     Display the installed semantic version.
+
+  Examples
+    $ eslint-plugin-crc
+    ✅  Generated a CRC Model report to
+     /Users/you/work/repo/reports/crc-model-report.md.
+
+    $ eslint-plugin-crc 'lib/**/*.js' -o='./tests/analysis'
+    ✅  Generated a CRC Model report to
+     /Users/you/work/repo/tests/analysis/crc-model-report.md.
+
+    $ eslint-plugin-crc -o='😱 '
+    ❌  There was a problem generating your CRC Model report.
+        Error: ENOENT: no such file or directory, open '😱 '
+  `,
+
+  toString: function (message = "", type = msg.success) {
+    return type + message;
+  }
+};
+
+const options = {
+  flags: {
+    output: {
+      alias: "o",
+      default: path.resolve(__dirname, "../reports/crc-model-report.md"),
+      type: "string"
+    }
+  }
+};
+
+function writeReportFile (out, report) {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  fs.writeFile(out, report, {flag: "w"}, (err) => {
+    if (err) {
+      console.error(msg.toString(err, msg.error));
+    }
+    console.log(msg.toString(out));
+  });
+}
+
+function generateReport () {
+  const eslintCli = new CLIEngine("./lib/.eslintrc.yml");
+  const cli = meow(msg.usage, options);
+  const files = eslintCli.resolveFileGlobPatterns(cli.input);
+  const report = eslintCli.executeOnFiles(files);
+  const formatter = eslintCli.getFormatter("./lib/formatters/crc/index.js");
+  const crcModelReport = formatter(report.results);
+  const out = cli.flags.output || options.flags.output.default;
+  writeReportFile(out, crcModelReport);
+}
+
+function main () {
+  generateReport();
+}
+
+main();

lib/crc/complexity.js

@@ -0,0 +1,11 @@
+// const astConfig = require("./ast-config");
+const escomplex = require("escomplex");
+// const espree = require("espree");
+
+class Complexity {
+  static analyze (context) {
+    return escomplex.analyse(context);
+  }
+}
+
+module.exports = Complexity;

lib/crc/crc-class.js

@@ -2,7 +2,9 @@
  * @fileoverview Create a `class` summary object for CrcModels.
  * @author Greg Swindle (https://github.com/gregswindle)
  */
-const { defaults } = require("lodash");
+const doctrine = require("doctrine");
+// eslint-disable-next-line node/no-unsupported-features
+const { first, get, isEmpty, defaults } = require("lodash");
 /**
  * Default NullObject constructor parameters.
  *
@@ -12,10 +14,23 @@ const { defaults } = require("lodash");
 const defaultConstructorParams = {
   code: null,
   description: null,
+  meta: {},
   name: null,
   superClass: null
 };
 
+function setDescription (crcClass) {
+  const comments = get(crcClass, "code.ast.comments");
+  if (!isEmpty(comments)) {
+    const ast = doctrine.parse(first(comments).value, {
+      recoverable: true,
+      sloppy: true,
+      unwrap: true
+    });
+    crcClass.description = ast.description.replace(/\s+/g, " ");
+  }
+}
+
 /**
  * Represents `class` "summary" `Object` used for reporting.
  *
@@ -36,6 +51,7 @@ class CrcClass {
    * the CrcClass's properties.
    * @param {SourceCode} [params.code] - The ESLint
    * {@link http://bit.ly/2kfR79f `SourceCode`} object.
+   * @param {object} []
    * @param {string} [params.name] - The source code identifier of the class or
    * object to be modeled.
    * @param {string} [params.description] - A summary of the
@@ -53,9 +69,11 @@ class CrcClass {
   // eslint-disable-next-line node/no-unsupported-features
   constructor (params = defaultConstructorParams) {
     this.description = params.description;
+    this.meta = params.meta;
     this.name = params.name;
     this.code = params.code;
     this.superClass = params.superClass;
+    setDescription(this);
   }
 
   /**
@@ -71,7 +89,10 @@ class CrcClass {
   static factory (context) {
     const ctxt = context || { code: null };
     const params = defaults({
-      code: ctxt.code
+      code: ctxt.code,
+      meta: {
+        filePath: ctxt.filePath
+      }
     }, defaultConstructorParams);
 
     return new CrcClass(params);

lib/crc/crc-context.js

@@ -2,31 +2,40 @@ const astConfig = require("./ast-config");
 const espree = require("espree");
 const fs = require("fs");
 const path = require("path");
+// eslint-disable-next-line node/no-unsupported-features
 const { SourceCode } = require("eslint");
 
 /**
  * Provides contextual information about source code.
  *
  */
 class CrcContext {
+  constructor (code, filePath, descriptor) {
+    this.code = code;
+    this.filePath = filePath;
+    this.descriptor = descriptor;
+  }
   /**
    * Factory method for generating a CrcContext object.
    *
    * @static
    * @param {Result} result - An ESLint Rule Result.
-   * @param  {object} descriptorFactory - An object that identifies ASTNodes
+   * @param {Object} descriptorFactory - An object that identifies ASTNodes
    * with ESQuery selectors.
+   * @example
+   * const context = CrcContext.create(result, descriptorFactory);
    * @returns {CrcContext} A CrcContext object.
    */
   static create (result, descriptorFactory) {
     // eslint-disable-next-line security/detect-non-literal-fs-filename
     const src = fs.readFileSync(path.resolve(result.filePath)).toString();
     const ast = espree.parse(src, astConfig);
-    return {
-      code: new SourceCode(src, ast),
-      filePath: result.filePath,
-      descriptor: descriptorFactory.descriptor
-    };
+
+    return new CrcContext(
+      new SourceCode(src, ast),
+      result.filePath,
+      descriptorFactory.descriptor
+    );
   }
 }
 

lib/crc/crc-model.js

@@ -38,9 +38,14 @@ class CrcModel {
   // eslint-disable-next-line node/no-unsupported-features
   constructor (params = defaultParams) {
     this.class = params.class;
-    this.responsibilities = params.responsibilities;
     this.collaborators = params.collaborators;
+    this.responsibilities = params.responsibilities;
   }
+
+  // eslint-disable-next-line node/no-unsupported-features
+  // static parse (rawSource) {
+  //
+  // }
 }
 
 module.exports = CrcModel;

lib/crc/crc-report.js

@@ -0,0 +1,15 @@
+/**
+ * A collection of "classes"--i.e., prototypable JS objects--in a single CrcReport.
+ */
+// class CrcReport {
+//   constructor () {
+//     this.meta = {
+//       date: new Date(),
+//       description: null,
+//       title: null
+//     };
+//     this.classes = [];
+//   }
+// }
+
+// module.exports = CrcReport;

lib/crc/crc-reporter.js

@@ -32,7 +32,8 @@ class CrcReporter {
     const crcClasses = [];
     getAllContexts(results, this.descriptors).forEach((context) => {
       const descriptor = this.descriptors.get(context.descriptor);
-      crcClasses.push(descriptor.factory(context));
+      const crcClass = descriptor.factory(context);
+      crcClasses.push(crcClass);
     });
 
     return crcClasses.map((crcClass) => {

lib/crc/descriptors/class-matcher-crc-class.js

@@ -15,7 +15,7 @@ class ClassMatcherCrcClass extends CrcClass {
    * @static
    * @override
    * @param {Context} context  - An ESLint
-   * {@link https://goo.gl/tuUSG5 Context} object with relevant information.
+   * {@link https://goo.Gl/tuUSG5 Context} object with relevant information.
    * @example
    * const crcClass = ClassMatcherCrcClass.factory(result, params);
    * @returns {CrcClass} A `CrcClass` `NullObject`.

lib/crc/descriptors/new-expression-crc-class.js

@@ -10,7 +10,7 @@ class NewExpressionCrcClass extends CrcClass {
    * @override
    * @param {ASTNode} node - An abstract syntax tree node.
    * @param {Context} context  - An ESLint
-   * {@link https://goo.gl/tuUSG5 Context} object with relevant information.
+   * {@link https://goo.Gl/tuUSG5 Context} object with relevant information.
    * @example
    * const crcClass = NewExpressionCrcClass.factory(node, context);
    * @returns {CrcClass} A NullObject for CrcClass.

lib/crc/descriptors/object-expression-crc-class.js

@@ -9,7 +9,7 @@ class ObjectExpressionCrcClass extends CrcClass {
    * @static
    * @override
    * @param {Context} context  - An ESLint
-   * {@link https://goo.gl/tuUSG5 Context} object with relevant information.
+   * {@link https://goo.Gl/tuUSG5 Context} object with relevant information.
    * @example
    * const crcClass = ObjectExpressionCrcClass.factory(context);
    * @returns {CrcClass} A NullObject for CrcClass.

lib/crc/index.js

@@ -26,9 +26,10 @@ module.exports = {
   CrcClass,
 
   /**
-   * Represents a Class-Responsibility-Collaboration model, which expresses the
-   * scope of an object's behaviors (**responsibilities**) and the objects it
-   * depends on to fulfill its responsibilities (**collaborators**).
+   * Represents a Class-Responsibility-Collaboration model, which
+   * expresses the scope of an object's behaviors (**responsibilities**)
+   * and the objects it depends on to fulfill its responsibilities
+   * (**collaborators**).
    * @see CrcModel
    */
   CrcModel

lib/formatters/crc/crc-formatter.js

@@ -0,0 +1,7 @@
+// const { CLIEngine } = require("eslint");
+//
+// const cli = new CLIEngine({
+//   configFile: '../.eslintrc.yml'
+// });
+//
+// module.exports = cli.getFormatter('.');

lib/formatters/crc/crc-model-template.md → lib/formatters/crc/crc-model-template.html

@@ -9,9 +9,7 @@ <h3>
             <tt>extends
             <%= _.get(crcModel, 'class.superClass.name') || '<a rel="noopener" href="https://is.gd/ZZBLcn" target="mdn">Object</a>' %></tt>
        </h3>
-       <blockquote>
-         <%- crcModel.class.description %>
-       </blockquote>
+       <blockquote><%- crcModel.class.description %></blockquote>
        </th>
     </tr>
     <tr valign="top" align="left">
@@ -25,15 +23,6 @@ <h3>
         <details>
           <summary><img src="docs/img/icons8/icon-javascript-filled-25.png" alt="Select to toggle" align="top"> Details...</summary>
             <dl>
-            <dt><strong>Example</dt>
-            <dd><blockquote>
-
-```js
-
-```
-
-</blockquote>
-</dd>
             <dt><strong>Source code</strong></dt>
             <dd><blockquote>
 
@@ -50,6 +39,12 @@ <h3>
               <li>TODO: reference two.</li>
               <li>TODO: reference one.</li>
            </ol></blockquote></dd>
+           <dt><strong>Path</strong></dt>
+           <dd>
+            <blockquote>
+              <%- crcModel.class.meta.filePath %>
+            </blockquote>
+           </dd>
             </dl>
         </details>
       </td>
@@ -73,6 +68,3 @@ <h3>
 </table>
 
 <!--/crc-model-template:html,markdown -->
-
-
-[classes-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes

lib/formatters/crc/crc-page-template.md → lib/formatters/crc/crc-page-template.html

@@ -1,6 +1,9 @@
 # CRC Model results
+
 > <%= reportSummary %>. Generated on <%= date.toISOString() %>.
 
  <%= results %>
 
 ---
+
+[classes-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes