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