doc(cli): document viz.js warning on node 12

README.md

@@ -95,6 +95,13 @@ Options:
 bin/smcat docs/sample.smcat
 ```
 
+> <details>
+>   <summary>note for use on Node.js 12</summary>
+>   On Node.js 12 you might see a warning message on stderr:
+>   <code>Invalid asm.js: Function definition doesn't match use</code>.
+>   It's harmless. See <a href="docs/faq.md#node12">the FAQ</a> for details.
+> </details>
+
 Or, if you'd rather have the native GraphViz dot do that for you:
 
 ```sh

bin/smcat

@@ -1,86 +1,91 @@
 #!/usr/bin/env node
-const program  = require("commander");
-const semver   = require("semver");
+const program = require("commander");
+const semver = require("semver");
 const $package = require("../package.json");
+const makeDescription = require("../src/cli/makeDescription");
 
 /* istanbul ignore if  */
 if (!semver.satisfies(process.versions.node, $package.engines.node)) {
-    process.stderr.write(`\nERROR: your node version (${process.versions.node}) is not recent enough.\n`);
-    process.stderr.write(`       state-machine-cat is supported on node ${$package.engines.node}\n\n`);
+  process.stderr.write(
+    `\nERROR: your node version (${process.versions.node}) is not recent enough.\n`
+  );
+  process.stderr.write(
+    `       state-machine-cat is supported on node ${$package.engines.node}\n\n`
+  );
 
-    /* eslint no-process-exit: 0 */
-    process.exit(-1);
+  /* eslint no-process-exit: 0 */
+  process.exit(-1);
 }
 
-const normalize   = require("../src/cli/normalize");
+const normalize = require("../src/cli/normalize");
 const validations = require("../src/cli/validations");
-const actions     = require("../src/cli/actions");
+const actions = require("../src/cli/actions");
 
 function presentError(e) {
-    process.stderr.write(actions.formatError(e));
+  process.stderr.write(actions.formatError(e));
 
-    /* eslint no-process-exit:0 */
-    process.exit(1);
+  /* eslint no-process-exit:0 */
+  process.exit(1);
 }
 
 try {
-    program
-        .version($package.version)
-        .option(
-            "-T --output-type <type>",
-            validations.validOutputTypeRE,
-            validations.validOutputType,
-            validations.defaultOutputType
-        ).option(
-            "-I --input-type <type>",
-            validations.validInputTypeRE,
-            validations.validInputType,
-            validations.defaultInputType
-        ).option(
-            "-E --engine <type>",
-            validations.validEngineRE,
-            validations.validEngine,
-            validations.defaultEngine
-        ).option(
-            "-d --direction <dir>",
-            validations.validDirectionRE,
-            validations.validDirection,
-            validations.defaultDirection
-        ).option(
-            "-o --output-to <file>",
-            "File to write to. use - for stdout."
-        ).option(
-            "--dot-graph-attrs <string>",
-            "graph attributes to pass to the dot render engine",
-            validations.validDotAttrs
-        ).option(
-            "--dot-node-attrs <string>",
-            "node attributes to pass to the dot render engine",
-            validations.validDotAttrs
-        ).option(
-            "--dot-edge-attrs <string>",
-            "edge attributes to pass to the dot render engine",
-            validations.validDotAttrs
-        ).option(
-            "--desugar",
-            "transform pseudo states into transitions (!experimental!)"
-        ).option(
-            "-l --license",
-            "Display license and exit",
-            () => {
-                process.stdout.write(actions.LICENSE);
-                process.exit(0);
-            }
-        ).arguments(
-            "[infile]"
-        ).parse(
-            process.argv
-        );
-    validations.validateArguments(
-        normalize(program.args[0], program)
+  program
+    .version($package.version)
+    .description(makeDescription(process.versions.node))
+    .option(
+      "-T --output-type <type>",
+      validations.validOutputTypeRE,
+      validations.validOutputType,
+      validations.defaultOutputType
     )
-        .then(actions.transform)
-        .catch(presentError);
+    .option(
+      "-I --input-type <type>",
+      validations.validInputTypeRE,
+      validations.validInputType,
+      validations.defaultInputType
+    )
+    .option(
+      "-E --engine <type>",
+      validations.validEngineRE,
+      validations.validEngine,
+      validations.defaultEngine
+    )
+    .option(
+      "-d --direction <dir>",
+      validations.validDirectionRE,
+      validations.validDirection,
+      validations.defaultDirection
+    )
+    .option("-o --output-to <file>", "File to write to. use - for stdout.")
+    .option(
+      "--dot-graph-attrs <string>",
+      "graph attributes to pass to the dot render engine",
+      validations.validDotAttrs
+    )
+    .option(
+      "--dot-node-attrs <string>",
+      "node attributes to pass to the dot render engine",
+      validations.validDotAttrs
+    )
+    .option(
+      "--dot-edge-attrs <string>",
+      "edge attributes to pass to the dot render engine",
+      validations.validDotAttrs
+    )
+    .option(
+      "--desugar",
+      "transform pseudo states into transitions (!experimental!)"
+    )
+    .option("-l --license", "Display license and exit", () => {
+      process.stdout.write(actions.LICENSE);
+      process.exit(0);
+    })
+    .arguments("[infile]")
+    .parse(process.argv);
+  validations
+    .validateArguments(normalize(program.args[0], program))
+    .then(actions.transform)
+    .catch(presentError);
 } catch (e) {
-    presentError(e);
+  presentError(e);
 }

docs/faq.md

@@ -0,0 +1,8 @@
+### <a id="node12"></a>Q: I'm on node 12 and get a warning when I convert to svg with the cli. What's up?
+
+**A**: On Node.js 12 you might see a warning message on stderr:
+_Invalid asm.js: Function definition doesn't match use_.
+It's a [known issue](https://github.com/mdaines/viz.js/issues/96) in viz.js,
+the graph render library state-machine-cat uses.
+The message is harmless and the rendered svg will come out just
+fine, but know we're looking into alternatives.

package.json

@@ -74,17 +74,20 @@
   },
   "dependencies": {
     "ajv": "6.10.2",
+    "chalk": "2.4.2",
     "commander": "3.0.2",
     "fast-xml-parser": "3.13.0",
     "get-stream": "5.1.0",
     "handlebars": "4.4.2",
     "he": "1.2.0",
+    "indent-string": "4.0.0",
     "lodash.castarray": "4.4.0",
     "lodash.clonedeep": "4.5.0",
     "lodash.get": "4.4.2",
     "lodash.reject": "4.6.0",
     "semver": "6.3.0",
-    "viz.js": "1.8.2"
+    "viz.js": "1.8.2",
+    "wrap-ansi": "6.0.0"
   },
   "devDependencies": {
     "chai": "4.2.0",

src/cli/makeDescription.js

@@ -0,0 +1,31 @@
+const chalk = require("chalk");
+const indentString = require("indent-string");
+const wrapAnsi = require("wrap-ansi");
+const semver = require("semver");
+
+function wrapAndIndent(pString) {
+  const DOGMATIC_MAX_CONSOLE_WIDTH = 78;
+  const DEFAULT_INDENT = 2;
+
+  const MAX_WIDTH = DOGMATIC_MAX_CONSOLE_WIDTH - DEFAULT_INDENT;
+
+  return indentString(wrapAnsi(pString, MAX_WIDTH), DEFAULT_INDENT);
+}
+
+module.exports = function(pNodeVersion) {
+  const lDescription =
+    "Write beautiful state charts - https://github.com/sverweij/state-machine-cat";
+  const lNode12Warning =
+    "When you output svg on node >=12, you might see " +
+    `${chalk.italic(
+      "'Invalid asm.js: Function definition doesn't match use'"
+    )}. ` +
+    "It's harmless. See " +
+    `https://github.com/sverweij/state-machine-cat/docs/FAQ.md#node12`;
+
+  return indentString(
+    semver.satisfies(pNodeVersion, ">=12")
+      ? `${lDescription}\n\n${wrapAndIndent(chalk.dim(lNode12Warning))}`
+      : lDescription
+  );
+};

test/cli/makeDescription.spec.js

@@ -0,0 +1,13 @@
+const expect = require("chai").expect;
+const makeDescription = require("../../src/cli/makeDescription");
+
+describe("#cli - makeDescription", () => {
+  it("tells about the asm.js warning on node >=12", () => {
+    expect(makeDescription("v12.11.1")).to.contain(">=12");
+  });
+
+  it("doesn't tell about the asm.js warning on node <12", () => {
+    expect(makeDescription("v10.16.3")).to.not.contain(">=12");
+  });
+});
+/* eslint no-undefined: 0 */