fix(cli): clarify usage of --format (#2575)

docs/guides/2-cli.md

@@ -31,9 +31,9 @@ Other options include:
       --help                     Show help                                                                     [boolean]
   -e, --encoding                 text encoding to use
           [string] [choices: "utf8", "ascii", "utf-8", "utf16le", "ucs2", "ucs-2", "base64", "latin1"] [default: "utf8"]
-  -f, --format                   formatters to use for outputting results, more than one can be given joining them with
-                                 a comma
-        [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif"]
+  -f, --format                   formatters to use for outputting results, more than one can be provided by using
+                                 multiple flags
+         [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif"]
                                                                                                     [default: "stylish"]
   -o, --output                   where to output results, can be a single file name, multiple "output.<format>" or
                                  missing to print to stdout                                                     [string]
@@ -176,6 +176,27 @@ title: Example
 
 <!-- type: tab-end -->
 
+### Multiple formatters
+
+If you wish to output results in multiple formats, you can do so by passing multiple `-f` flags.
+In order to output results in multiple formats, you must also pass the `-o` flag with a filename for each format.
+
+```bash
+spectral lint "specs/**/*.yaml" -f json -f junit -o.json results.json -o.junit junit.xml
+```
+
+You can also pipe an output to stdout.
+
+```bash
+spectral lint "specs/**/*.yaml" -f stylish -f junit -o.junit junit.xml -o.stylish "<stdout>"
+```
+
+It's possible to output each format to stdout.
+
+```bash
+spectral lint "specs/**/*.yaml" -f text -f stylish -o.text "<stdout>" -o.stylish "<stdout>"
+```
+
 ## Proxying
 
 To have requests made from Spectral be proxied through a server, you'd need to specify the `PROXY` environment variable:

packages/cli/package.json

@@ -52,7 +52,7 @@
     "pony-cause": "^1.0.0",
     "stacktracey": "^2.1.7",
     "tslib": "^2.3.0",
-    "yargs": "17.3.1"
+    "yargs": "~17.7.2"
   },
   "devDependencies": {
     "@types/es-aggregate-error": "^1.0.2",
@@ -65,8 +65,7 @@
   },
   "pkg": {
     "scripts": [
-      "./dist/**/*.js",
-      "../../node_modules/vm2/lib/*.js"
+      "./dist/**/*.js"
     ],
     "assets": [
       "./dist/**/*.json",

packages/cli/src/commands/lint.ts

@@ -42,7 +42,7 @@ const lintCommand: CommandModule = {
         },
       })
       .middleware((argv: Dictionary<unknown>) => {
-        const formats = argv.format as string[] & { 0: string };
+        const formats = argv.format as [string, ...string[]];
         if (argv.output === void 0) {
           argv.output = { [formats[0]]: '<stdout>' };
         } else if (typeof argv.output === 'string') {
@@ -101,7 +101,8 @@ const lintCommand: CommandModule = {
         },
         format: {
           alias: 'f',
-          description: 'formatters to use for outputting results, more than one can be given joining them with a comma',
+          description:
+            'formatters to use for outputting results, more than one can be provided by using multiple flags',
           choices: formatOptions,
           default: OutputFormat.STYLISH,
           type: 'string',

test-harness/scenarios/fail-on-unmatched-glob-patterns.scenario

@@ -5,7 +5,7 @@ module.exports = {
   rules: {}
 }
 ====command-nix====
-{bin} lint ./*oops.{yml,yaml,json} --fail-on-unmatched-globs --ruleset "{asset:ruleset}"
+{bin} lint "./*oops.{yml,yaml,json}" --fail-on-unmatched-globs --ruleset "{asset:ruleset}"
 ====status====
 2
 ====stderr====

test-harness/scenarios/help-no-document.scenario

@@ -20,7 +20,7 @@ Options:
       --version                  Show version number  [boolean]
       --help                     Show help  [boolean]
   -e, --encoding                 text encoding to use  [string] [choices: "utf8", "ascii", "utf-8", "utf16le", "ucs2", "ucs-2", "base64", "latin1"] [default: "utf8"]
-  -f, --format                   formatters to use for outputting results, more than one can be given joining them with a comma  [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif"] [default: "stylish"]
+  -f, --format                   formatters to use for outputting results, more than one can be provided by using multiple flags  [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif"] [default: "stylish"]
   -o, --output                   where to output results, can be a single file name, multiple "output.<format>" or missing to print to stdout  [string]
       --stdin-filepath           path to a file to pretend that stdin comes from  [string]
       --resolver                 path to custom json-ref-resolver instance  [string]

test-harness/scenarios/proxy-agent.scenario

@@ -4,7 +4,7 @@ Requests for $refs are proxied when PROXY env variable is set
 foo:
   $ref: http://localhost:3002/foo.json#/ref
 ====env====
-PROXY=http://localhost:3001
+PROXY=http://127.0.0.1:3001
 ====asset:ruleset====
 module.exports = {
   rules: {}

test-harness/scenarios/strict-options.scenario

@@ -20,7 +20,7 @@ Options:
       --version                  Show version number  [boolean]
       --help                     Show help  [boolean]
   -e, --encoding                 text encoding to use  [string] [choices: "utf8", "ascii", "utf-8", "utf16le", "ucs2", "ucs-2", "base64", "latin1"] [default: "utf8"]
-  -f, --format                   formatters to use for outputting results, more than one can be given joining them with a comma  [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif"] [default: "stylish"]
+  -f, --format                   formatters to use for outputting results, more than one can be provided by using multiple flags  [string] [choices: "json", "stylish", "junit", "html", "text", "teamcity", "pretty", "github-actions", "sarif"] [default: "stylish"]
   -o, --output                   where to output results, can be a single file name, multiple "output.<format>" or missing to print to stdout  [string]
       --stdin-filepath           path to a file to pretend that stdin comes from  [string]
       --resolver                 path to custom json-ref-resolver instance  [string]