From 5f8de423f190bbb79a62f804151bc24824fa32d8 Mon Sep 17 00:00:00 2001 From: "Matt A. Tobin" Date: Fri, 2 Feb 2018 04:16:08 -0500 Subject: Add m-esr52 at 52.6.0 --- tools/lint/docs/create.rst | 153 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 tools/lint/docs/create.rst (limited to 'tools/lint/docs/create.rst') diff --git a/tools/lint/docs/create.rst b/tools/lint/docs/create.rst new file mode 100644 index 000000000..a132417a8 --- /dev/null +++ b/tools/lint/docs/create.rst @@ -0,0 +1,153 @@ +Adding a New Linter to the Tree +=============================== + +A linter is a python file with a ``.lint`` extension and a global dict called LINTER. Depending on how +complex it is, there may or may not be any actual python code alongside the LINTER definition. + +Here's a trivial example: + +no-eval.lint + +.. code-block:: python + + LINTER = { + 'name': 'EvalLinter', + 'description': "Ensures the string 'eval' doesn't show up." + 'include': "**/*.js", + 'type': 'string', + 'payload': 'eval', + } + +Now ``no-eval.lint`` gets passed into :func:`LintRoller.read`. + + +Linter Types +------------ + +There are three types of linters, though more may be added in the future. + +1. string - fails if substring is found +2. regex - fails if regex matches +3. external - fails if a python function returns a non-empty result list +4. structured_log - fails if a mozlog logger emits any lint_error or lint_warning log messages + +As seen from the example above, string and regex linters are very easy to create, but they +should be avoided if possible. It is much better to use a context aware linter for the language you +are trying to lint. For example, use eslint to lint JavaScript files, use flake8 to lint python +files, etc. + +Which brings us to the third and most interesting type of linter, +external. External linters call an arbitrary python function which is +responsible for not only running the linter, but ensuring the results +are structured properly. For example, an external type could shell out +to a 3rd party linter, collect the output and format it into a list of +:class:`ResultContainer` objects. The signature for this python +function is ``lint(files, **kwargs)``, where ``files`` is a list of +files to lint. + +Structured log linters are much like external linters, but suitable +for cases where the linter code is using mozlog and emits +``lint_error`` or ``lint_warning`` logging messages when the lint +fails. This is recommended for writing novel gecko-specific lints. In +this case the signature for lint functions is ``lint(files, logger, +**kwargs)``. + +LINTER Definition +----------------- + +Each ``.lint`` file must have a variable called LINTER which is a dict containing metadata about the +linter. Here are the supported keys: + +* name - The name of the linter (required) +* description - A brief description of the linter's purpose (required) +* type - One of 'string', 'regex' or 'external' (required) +* payload - The actual linting logic, depends on the type (required) +* include - A list of glob patterns that must be matched (optional) +* exclude - A list of glob patterns that must not be matched (optional) +* extensions - A list of file extensions to be considered (optional) +* setup - A function that sets up external dependencies (optional) + +In addition to the above, some ``.lint`` files correspond to a single lint rule. For these, the +following additional keys may be specified: + +* message - A string to print on infraction (optional) +* hint - A string with a clue on how to fix the infraction (optional) +* rule - An id string for the lint rule (optional) +* level - The severity of the infraction, either 'error' or 'warning' (optional) + +For structured_log lints the following additional keys apply: + +* logger - A StructuredLog object to use for logging. If not supplied + one will be created (optional) + +Example +------- + +Here is an example of an external linter that shells out to the python flake8 linter: + +.. code-block:: python + + import json + import os + import subprocess + from collections import defaultdict + + from mozlint import result + + + FLAKE8_NOT_FOUND = """ + Could not find flake8! Install flake8 and try again. + """.strip() + + + def lint(files, **lintargs): + import which + + binary = os.environ.get('FLAKE8') + if not binary: + try: + binary = which.which('flake8') + except which.WhichError: + print(FLAKE8_NOT_FOUND) + return 1 + + # Flake8 allows passing in a custom format string. We use + # this to help mold the default flake8 format into what + # mozlint's ResultContainer object expects. + cmdargs = [ + binary, + '--format', + '{"path":"%(path)s","lineno":%(row)s,"column":%(col)s,"rule":"%(code)s","message":"%(text)s"}', + ] + files + + proc = subprocess.Popen(cmdargs, stdout=subprocess.PIPE, env=os.environ) + output = proc.communicate()[0] + + # all passed + if not output: + return [] + + results = [] + for line in output.splitlines(): + # res is a dict of the form specified by --format above + res = json.loads(line) + + # parse level out of the id string + if 'code' in res and res['code'].startswith('W'): + res['level'] = 'warning' + + # result.from_linter is a convenience method that + # creates a ResultContainer using a LINTER definition + # to populate some defaults. + results.append(result.from_linter(LINTER, **res)) + + return results + + + LINTER = { + 'name': "flake8", + 'description': "Python linter", + 'include': ['**/*.py'], + 'type': 'external', + 'payload': lint, + } -- cgit v1.2.3