1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
ESLint
======
`ESLint`__ is a popular linter for JavaScript. The ESLint integration also uses
`Prettier`_ to enforce code formatting.
Run Locally
-----------
The mozlint integration of ESLint can be run using mach:
.. parsed-literal::
$ mach lint --linter eslint <file paths>
Alternatively, omit the ``--linter eslint`` and run all configured linters, which will include
ESLint.
ESLint also supports the ``--fix`` option to autofix most errors raised from most of the rules.
See the `Usage guide`_ for more options.
Understanding Rules and Errors
------------------------------
* Only some files are linted, see the :searchfox:`configuration <tools/lint/eslint.yml>` for details.
* By design we do not lint/format reftests not crashtests as these are specially crafted tests.
* If you don't understand a rule, you can look it in `eslint.org's rule list`_ for more
information about it.
* For Mozilla specific rules (with the mozilla/ prefix), see these for more details:
* `eslint-plugin-mozilla`_
* `eslint-plugin-spidermonkey-js`_
Common Issues and How To Solve Them
-----------------------------------
My editor says that ``mozilla/whatever`` is unknown
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Run ``./mach eslint --setup``, and restart your editor.
My editor doesn't understand a new global I've just added (e.g. to a content file or head.js file)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* This is a limitation which is a mixture of our ESLint setup and how we share globals across files.
* Restarting your editor should pick up the new globals.
* You can always double check via ``./mach lint --linter eslint <file path>`` on the command line.
I am getting a linter error "Unknown Services member property"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Make sure to add any new Services to ``tools/lint/eslint/eslint-plugin-mozilla/lib/services.json``. For example by copying from
``<objdir>/xpcom/components/services.json`` after a build.
.. _adding-tests:
I'm adding tests, how do I set up the right configuration?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please note we prefer the tests to be in named directories as this makes it
easier to identify the types of tests developers are working with. Additionally,
it is not possible to scope ESLint rules to individual files based on .ini
files without a build step that would break editors, or an expensive loading
cycle.
* If the directory path of the tests is one of the `known ones`_, then ESLint will
do the right thing for that test type. This is the preferred option.
* For example placing xpcshell-tests in ``browser/components/foo/test/unit/``
will set up ESLint correctly.
* If you really can't match the directory name, e.g. like the
``browser/base/content/tests/*``, then you'll need to add a new entry in
:searchfox:`.eslintrc-test-paths.js <.eslintrc-test-paths.js>`.
Please do not add new cases of multiple types of tests within a single directory,
this is `difficult for ESLint to handle`_. Currently this may cause:
* Rules to be incorrectly applied to the wrong types of test file.
* Extra definitions for globals in tests which means that the no undefined variables
rule does not get triggered in some cases.
I'm using an ES module
^^^^^^^^^^^^^^^^^^^^^^
* Use a ``.mjs`` extension for the file. ESLint will pick this up and automatically
treat it as a module.
* If it is a system module (e.g. component definition or other non-frontend code),
use a ``.sys.mjs`` extension.
This code should neither be linted nor formatted
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* If it is a third-party piece of code, please add it to :searchfox:`ThirdPartyPaths.txt <tools/rewriting/ThirdPartyPaths.txt>`.
* If it is a generated file, please add it to :searchfox:`Generated.txt <tools/rewriting/Generated.txt>`.
* If intentionally invalid, please add it to :searchfox:`.eslintignore <.eslintignore>`.
This code shouldn't be formatted
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The vast majority of code should be formatted, however we allow some limited
cases where it makes sense, for example:
* A table in an array where laying it out in a table fashion makes it more readable.
* Other structures or function calls where layout is more readable in a particular format.
To disable prettier for code like this, ``// prettier-ignore`` may be used on
the line previous to where you want it disabled.
See the `prettier ignore docs`_ for more information.
I have valid code that is failing the ``no-undef`` rule or can't be parsed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Please do not add this to :searchfox:`.eslintignore <.eslintignore>`. Generally
this can be fixed, if the following tips don't help, please `seek help`_.
* If you are adding a new test directory, see the :ref:`section above <adding-tests>`
* If you are writing a script loaded into special environment (e.g. frame script) you may need to tell ESLint to use the `environment definitions`_ for each case:
* ``/* eslint-env mozilla/frame-script */``
* If you are writing a worker, then you may need to use the worker or chrome-worker environment:
* ``/* eslint-env worker */``
* ``/* eslint-env mozilla/chrome-worker */``
* I use ``Services.scriptloader.loadSubScript``:
* ``/* import-globals-from relative/path/to/file.js``
Configuration
-------------
The global configuration file lives in ``topsrcdir/.eslintrc``. This global configuration can be
overridden by including an ``.eslintrc`` in the appropriate subdirectory. For an overview of the
supported configuration, see `ESLint's documentation`_.
Please keep differences in rules across the tree to a minimum. We want to be consistent to
make it easier for developers.
Sources
-------
* :searchfox:`Configuration (YAML) <tools/lint/eslint.yml>`
* :searchfox:`Source <tools/lint/eslint/__init__.py>`
Builders
--------
`Mark Banner (standard8) <https://people.mozilla.org/s?query=standard8>`__ owns
the builders. Questions can also be asked on #lint:mozilla.org on Matrix.
ESLint (ES)
^^^^^^^^^^^
This is a tier-1 task. For test failures the patch causing the
issue should be backed out or the issue fixed.
Some failures can be fixed with ``./mach eslint --fix path/to/file``.
For test harness issues, file bugs in Developer Infrastructure :: Lint and Formatting.
ESLint-build (ES-B)
^^^^^^^^^^^^^^^^^^^
This is a tier-2 task that is run once a day at midnight UTC via a cron job.
It currently runs the ESLint rules plus two additional rules:
* `valid-ci-uses <eslint-plugin-mozilla/valid-ci-uses.html>`__
* `valid-services-property <eslint-plugin-mozilla/valid-services-property.html>`__
These are two rules that both require build artifacts.
To run them manually, you can run:
``MOZ_OBJDIR=objdir-ff-opt ./mach eslint --rule "mozilla/valid-ci-uses: error" --rule "mozilla/valid-services-property: error" *``
For test failures, the regression causing bug may be able to be found by:
* Determining if the file where the error is reported has been changed recently.
* Seeing if an associated ``.idl`` file has been changed.
If no regressing bug can easily be found, file a bug in the relevant
product/component for the file where the failure is and cc :standard8.
For test harness issues, file bugs in Developer Infrastructure :: Lint and Formatting.
.. toctree::
:hidden:
eslint-plugin-mozilla
eslint-plugin-spidermonkey-js
.. __: https://eslint.org/
.. _Prettier: https://prettier.io/
.. _Usage guide: ../usage.html
.. _ESLint's documentation: https://eslint.org/docs/user-guide/configuring
.. _eslint.org's rule list: https://eslint.org/docs/rules/
.. _eslint-plugin-mozilla: eslint-plugin-mozilla.html
.. _eslint-plugin-spidermonkey-js: eslint-plugin-spidermonkey-js.html
.. _informed that it is a module: https://searchfox.org/mozilla-central/rev/9399e5832979755cd340383f4ca4069dd5fc7774/browser/base/content/.eslintrc.js
.. _seek help: ../index.html#getting-help
.. _patterns in .eslintrc.js: https://searchfox.org/mozilla-central/rev/9399e5832979755cd340383f4ca4069dd5fc7774/.eslintrc.js#24-38
.. _environment definitions: ./eslint-plugin-mozilla/environment.html
.. _known ones: https://searchfox.org/mozilla-central/rev/287583a4a605eee8cd2d41381ffaea7a93d7b987/.eslintrc.js#24-40
.. _difficult for ESLint to handle: https://bugzilla.mozilla.org/show_bug.cgi?id=1379669
.. _prettier ignore docs: https://prettier.io/docs/en/ignore.html
|
