From 61257d88d5326d4a92e7c05fa53979cbbca4ed69 Mon Sep 17 00:00:00 2001 From: Aviv Eyal Date: Tue, 6 May 2014 19:08:30 -0700 Subject: [PATCH] Update doc for available lints Summary: - Mention many new linters now included. - Basic description of .arclint + example - Move Philosophy sections above Configuration sections. Test Plan: compile with bin/diviner. Reviewers: #blessed_reviewers, epriestley Reviewed By: #blessed_reviewers, epriestley Subscribers: joshuaspence, hach-que, epriestley, Korvin Differential Revision: https://secure.phabricator.com/D9000 --- src/docs/user/userguide/arcanist_lint.diviner | 166 ++++++++++++------ 1 file changed, 114 insertions(+), 52 deletions(-) diff --git a/src/docs/user/userguide/arcanist_lint.diviner b/src/docs/user/userguide/arcanist_lint.diviner index 4be3c402df..c43b0d5acc 100644 --- a/src/docs/user/userguide/arcanist_lint.diviner +++ b/src/docs/user/userguide/arcanist_lint.diviner @@ -39,16 +39,40 @@ write new bindings fairly easily if you have custom tools. Arcanist ships with bindings for these linters: - - [[http://www.jshint.com/ | JSHint]], a Javascript linter based on JSHint. + - [[http://www.jshint.com/ | JSHint]], a Javascript linter. See @{class@arcanist:ArcanistJSHintLinter}. - - [[http://pypi.python.org/pypi/pep8 | PEP8]], a Python linter. - See @{class@arcanist:ArcanistPEP8Linter}. - - [[http://pypi.python.org/pypi/pyflakes | Pyflakes]], another Python linter. - See @{class@arcanist:ArcanistPyFlakesLinter}. - - [[http://pypi.python.org/pypi/pylint | Pylint]], yet another Python linter. - See @{class@arcanist:ArcanistPyLintLinter}. + - [[http://pypi.python.org/pypi/pep8 | PEP8]], + [[http://pypi.python.org/pypi/pyflakes | Pyflakes]], + [[https://flake8.readthedocs.org/ | Flake8]], and + [[http://pypi.python.org/pypi/pylint | Pylint]] - various Python linters. + See @{class@arcanist:ArcanistPEP8Linter}, + @{class@arcanist:ArcanistPyFlakesLinter}, + @{class@arcanist:ArcanistFlake8Linter}, + and @{class@arcanist:ArcanistPyLintLinter}. - [[http://pear.php.net/package/PHP_CodeSniffer | PHP CodeSniffer]], a PHP linter. See @{class@arcanist:ArcanistPhpcsLinter}. + - [[http://cppcheck.sourceforge.net/ | Cppcheck]] and + [[http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py | + cpplint.py]], two checkers for C++. See + @{class@arcanist:ArcanistCppcheckLinter} and + @{class@arcanist:ArcanistCpplintLinter} respectively. + - [[https://github.com/hach-que/cstools | cslint]], a C# linting tool based on + [[http://stylecop.codeplex.com/ | StyleCop]]. See + @{class@arcanist:ArcanistCSharpLinter}. + - [[http://puppet-lint.com/ | puppet-lint]], a linter for + [[http://puppetlabs.com/ | Puppet]] manifests. See + @{class@arcanist:ArcanistPuppetLintLinter}. + - [[http://www.ruby-lang.org | Ruby]]'s built-in checker. See + @{class@arcanist:ArcanistRubyLinter}. + - [[http://www.scala-sbt.org/ | sbt]], a built tool for Scala. See + @{class@arcanist:ArcanistScalaSBTLinter}. + - [[http://csslint.net/ | CSSLint]], for CSS: + @{class@arcanist:ArcanistCSSLintLinter}. + - [[https://github.com/less/less.js | lessc]], error detection in + [[http://lesscss.org/ | LESS]] code. @{class@arcanist:ArcanistLesscLinter}. + - [[http://php.net/simplexml | SimpleXML]] for XML files. + @{class@arcanist:ArcanistXMLLinter}. + Arcanist also ships with generic bindings which can be configured to parse the output of a broad range of lint programs: @@ -73,6 +97,8 @@ Additionally, Arcanist ships with some general purpose linters: marked unlintable. - @{class@arcanist:ArcanistGeneratedLinter}, which can disable lint for generated files. + - @{class@arcanist:ArcanistMergeConflictLinter}, which detects unresolved + merge conflicts. Finally, Arcanist has special-purpose linters: @@ -89,51 +115,6 @@ You can add support for new linters in three ways: - use a generic binding like @{class@arcanist:ArcanistScriptAndRegexLinter} and drive the integration through configuration. -= Configuring Lint = - -Arcanist's lint integration involves two major components: linters and lint -engines. - -Linters themselves are programs which detect problems in a source file. Usually -a linter is an external script, which Arcanist runs and passes a path to, like -`jshint` or `pep8.py`. The script emits some messages, and Arcanist parses -the output into structured errors. A piece of glue code (like -@{class@arcanist:ArcanistJSHintLinter} or -@{class@arcanist:ArcanistPEP8Linter}) handles calling the external script and -interpreting its output. - -Lint engines coordinate linters, and decide which linters should run on which -files. For instance, you might want to run `jshint` on all your `.js` files, -and `pep8.py` on all your `.py` files. And you might not want to lint anything -in `externals/` or `third-party/`, and maybe there are other files which you -want to exclude or apply special rules for. - -To configure arc for lint, you specify the name of a lint engine, and possibly -provide some additional configuration. To name a lint engine, set `lint.engine` -in your `.arcconfig` to the name of a class which extends -@{class@arcanist:ArcanistLintEngine}. For more information on `.arcconfig`, see -@{article:Arcanist User Guide: Configuring a New Project}. - -You can also set a default lint engine by setting `lint.engine` in your global -user config with `arc set-config lint.engine`, or specify one explicitly with -`arc lint --engine `. - -The available engines are: - - - @{class@arcanist:ComprehensiveLintEngine}, which runs a wide array of - linters on many types of files. This is probably of limited use in any real - project because it is overbroad, but is a good starting point for getting - lint doing things. - - @{class@arcanist:ArcanistSingleLintEngine}, which runs a single linter on - every file unconditionally. This can be used with a glue linter like - @{class@arcanist:ArcanistScriptAndRegexLinter} to put engine logic in an - external script. - - A custom engine you write. For most projects, lint rules are sufficiently - specialized that this is the best option. For instructions on writing a - custom lint engine, see - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows} - and @{class@arcanist:ExampleLintEngine}. - = Using Lint to Improve Code Review = Code review is most valuable when it's about the big ideas in a change. It is @@ -187,6 +168,87 @@ lint tools at Facebook: valuable to have the linter not only say "the convention is to put a space after comma in a function call" but to fix it for you. + += Configuring Lint = + +Most built in linters can be setup by creating a file named `.arclint` in the +workspace root, which is read by +@{class@arcanist:ArcanistConfigurationDrivenLintEngine}. + +It's a JSON file, which should look something like: + { + "linters" : { + "sample" : { + "type" : "pep8", + "include" : "(\\.py$)", + "exclude" : "(^exclude.py)", + "severity" : { + "E401" : "warning" + } + } + } +Where: + - The key (`sample`) is only used for reporting, + - `type` (`pep8`) is used to find the right linter, + - `include` and `exclude` specify paths to run linter on, and + - `severity` is specified by the linter implementation; Other linters may + define other configurable values. + +You may specify many linters in a single `.arclint` file; For an example, see +[[https://github.com/epriestley/arclint-examples/ | the arclint-examples +repository]]. + +Currently available linter types are: `csharp`, `filename`, `csslint`, +`flake8`, `jshint`, `jsonlint`, `lessc`, `pep8`, `phpcs`, `puppet-lint`, +`pyflakes`, `ruby`, `generated`, `nolint`, `script-and-regex`, +`spelling`, `text`, `xml`. + += Legacy Setups: Using arcconfig = + +Integration with linters that do not (yet) fully support `.arclint` involves two +major components: linters and lint engines. + +Linters themselves are programs which detect problems in a source file. Usually +a linter is an external script, which Arcanist runs and passes a path to, like +`jshint` or `pep8.py`. The script emits some messages, and Arcanist parses +the output into structured errors. A piece of glue code (like +@{class@arcanist:ArcanistJSHintLinter} or +@{class@arcanist:ArcanistPEP8Linter}) handles calling the external script and +interpreting its output. + +Lint engines coordinate linters, and decide which linters should run on which +files. For instance, you might want to run `jshint` on all your `.js` files, +and `pep8.py` on all your `.py` files. And you might not want to lint anything +in `externals/` or `third-party/`, and maybe there are other files which you +want to exclude or apply special rules for. + +To configure arc for lint, you specify the name of a lint engine, and possibly +provide some additional configuration. To name a lint engine, set `lint.engine` +in your `.arcconfig` to the name of a class which extends +@{class@arcanist:ArcanistLintEngine}. For more information on `.arcconfig`, see +@{article:Arcanist User Guide: Configuring a New Project}. + +You can also set a default lint engine by setting `lint.engine` in your global +user config with `arc set-config lint.engine`, or specify one explicitly with +`arc lint --engine `. + +The available engines are: + + - @{class@arcanist:ComprehensiveLintEngine}, which runs a wide array of + linters on many types of files. This is probably of limited use in any real + project because it is overbroad, but is a good starting point for getting + lint doing things. + - @{class@arcanist:ArcanistSingleLintEngine}, which runs a single linter on + every file unconditionally. This can be used with a glue linter like + @{class@arcanist:ArcanistScriptAndRegexLinter} to put engine logic in an + external script. + - A custom engine you write. For most projects, lint rules are sufficiently + specialized that this is the best option. For instructions on writing a + custom lint engine, see + @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows} + and @{class@arcanist:ExampleLintEngine}. + + = Next Steps = Continue by: