Provide arc linters --verbose to list all available options

Summary:
Ref T2039. I'll update the corresponding documentation.

It feels a little awkward that this is disconnected from `getLinterConfigurationOptions()`, but I dislike returning weird ad-hoc structures more than I dislike having two methods. Most linters don't implement either of these anyway.

Test Plan: Ran `arc linters` and `arc linters --verbose`.

Reviewers: btrahan, joshuaspence

Reviewed By: joshuaspence

Subscribers: epriestley

Maniphest Tasks: T2039

Differential Revision: https://secure.phabricator.com/D9062

src/lint/engine/ArcanistConfigurationDrivenLintEngine.php

@@ -47,6 +47,16 @@ final class ArcanistConfigurationDrivenLintEngine extends ArcanistLintEngine {
         $linter = clone $linters[$type];
         $linter->setEngine($this);
         $more = $linter->getLinterConfigurationOptions();
+
+        foreach ($more as $key => $option_spec) {
+          PhutilTypeSpec::checkMap(
+            $option_spec,
+            array(
+              'type' => 'string',
+              'help' => 'string',
+            ));
+          $more[$key] = $option_spec['type'];
+        }
       } else {
         // We'll raise an error below about the invalid "type" key.
         $linter = null;

src/lint/linter/ArcanistCSharpLinter.php

@@ -2,8 +2,6 @@
 
 /**
  * C# linter for Arcanist.
- *
- * @group linter
  */
 final class ArcanistCSharpLinter extends ArcanistLinter {
 
@@ -27,8 +25,19 @@ final class ArcanistCSharpLinter extends ArcanistLinter {
   public function getLinterConfigurationOptions() {
     $options = parent::getLinterConfigurationOptions();
 
-    $options["discovery"] = 'map<string, list<string>>';
-    $options["binary"] = 'string';
+    $options['discovery'] = array(
+      'type' => 'map<string, list<string>>',
+      'help' => pht('Provide a discovery map.'),
+    );
+
+
+    // TODO: This should probably be replaced with "bin" when this moves
+    // to extend ExternalLinter.
+
+    $options['binary'] = array(
+      'type' => 'string',
+      'help' => pht('Override default binary.'),
+    );
 
     return $options;
   }

src/lint/linter/ArcanistExternalLinter.php

@@ -442,15 +442,33 @@ abstract class ArcanistExternalLinter extends ArcanistFutureLinter {
     }
   }
 
-
   public function getLinterConfigurationOptions() {
     $options = array(
-      'bin' => 'optional string | list<string>',
-      'flags' => 'optional list<string>',
+      'bin' => array(
+        'type' => 'optional string | list<string>',
+        'help' => pht(
+          'Specify a string (or list of strings) identifying the binary '.
+          'which should be invoked to execute this linter. This overrides '.
+          'the default binary. If you provide a list of possible binaries, '.
+          'the first one which exists will be used.')
+      ),
+      'flags' => array(
+        'type' => 'optional list<string>',
+        'help' => pht(
+          'Provide a list of additional flags to pass to the linter on the '.
+          'command line.'),
+      ),
     );
 
     if ($this->shouldUseInterpreter()) {
-      $options['interpreter'] = 'optional string | list<string>';
+      $options['interpreter'] = array(
+        'type' => 'optional string | list<string>',
+        'help' => pht(
+          'Specify a string (or list of strings) identifying the interpreter '.
+          'which should be used to invoke the linter binary. If you provide '.
+          'a list of possible interpreters, the first one that exists '.
+          'will be used.'),
+      );
     }
 
     return $options + parent::getLinterConfigurationOptions();

src/lint/linter/ArcanistLesscLinter.php

@@ -40,8 +40,17 @@ final class ArcanistLesscLinter extends ArcanistExternalLinter {
 
   public function getLinterConfigurationOptions() {
     return parent::getLinterConfigurationOptions() + array(
-      'lessc.strict-math' => 'optional bool',
-      'lessc.strict-units' => 'optional bool',
+      'lessc.strict-math' => array(
+        'type' => 'optional bool',
+        'help' => pht(
+          'Enable strict math, which only processes mathematical expressions '.
+          'inside extraneous parentheses.'),
+      ),
+      'lessc.strict-units' => array(
+        'type' => 'optional bool',
+        'help' => pht(
+          'Enable strict handling of units in expressions.'),
+      ),
     );
   }
 

src/lint/linter/ArcanistLinter.php

@@ -74,6 +74,7 @@ abstract class ArcanistLinter {
       get_class($this));
   }
 
+
   public function getLinterPriority() {
     return 1.0;
   }
@@ -360,8 +361,18 @@ abstract class ArcanistLinter {
     }
 
     return array(
-      'severity' => 'optional map<string|int, string>',
-      'severity.rules' => 'optional map<string, string>',
+      'severity' => array(
+        'type' => 'optional map<string|int, string>',
+        'help' => pht(
+          'Provide a map from lint codes to adjusted severity levels: error, '.
+          'warning, advice, autofix or disabled.')
+      ),
+      'severity.rules' => array(
+        'type' => 'optional map<string, string>',
+        'help' => pht(
+          'Provide a map of regular expressions to severity levels. All '.
+          'matching codes have their severity adjusted.'),
+      ),
     );
   }
 

src/lint/linter/ArcanistTextLinter.php

@@ -33,7 +33,12 @@ final class ArcanistTextLinter extends ArcanistLinter {
 
   public function getLinterConfigurationOptions() {
     $options = array(
-      'text.max-line-length' => 'optional int',
+      'text.max-line-length' => array(
+        'type' => 'optional int',
+        'help' => pht(
+          'Adjust the maximum line length before a warning is raised. By '.
+          'default, a warning is raised on lines exceeding 80 characters.'),
+      ),
     );
 
     return $options + parent::getLinterConfigurationOptions();

src/workflow/ArcanistLintersWorkflow.php

@@ -26,7 +26,11 @@ EOTEXT
   }
 
   public function getArguments() {
-    return array();
+    return array(
+      'verbose' => array(
+        'help' => pht('Show detailed information, including options.'),
+      ),
+    );
   }
 
   public function run() {
@@ -77,6 +81,7 @@ EOTEXT
         'uri' => $linter->getInfoURI(),
         'description' => $linter->getInfoDescription(),
         'exception' => $exception,
+        'options' => $linter->getLinterConfigurationOptions(),
       );
     }
 
@@ -137,10 +142,44 @@ EOTEXT
         $print_tail = true;
       }
 
+      $options = $linter['options'];
+      if ($options && $this->getArgument('verbose')) {
+        $console->writeOut(
+          "\n%s**%s**\n\n",
+          $pad,
+          pht('Configuration Options'));
+
+        $last_option = last_key($options);
+        foreach ($options as $option => $option_spec) {
+          $console->writeOut(
+            "%s__%s__ (%s)\n",
+            $pad,
+            $option,
+            $option_spec['type']);
+
+          $console->writeOut(
+            "%s\n",
+            phutil_console_wrap(
+              $option_spec['help'],
+              strlen($pad) + 2));
+
+          if ($option != $last_option) {
+            $console->writeOut("\n");
+          }
+        }
+        $print_tail = true;
+      }
+
       if ($print_tail) {
         $console->writeOut("\n");
       }
     }
+
+    if (!$this->getArgument('verbose')) {
+      $console->writeOut(
+        "%s\n",
+        pht('(Run `arc linters --verbose` for more details.)'));
+    }
   }