Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Orion/ESLint"

(Rules)
(Best Practices)
Line 269: Line 269:
 
| Warning
 
| Warning
 
| 7.0
 
| 7.0
|  
+
| ''Throw an Error instead.''
 
| Flags code that throws a non-Error, eg. <code>throw "a problem occurred";</code>
 
| Flags code that throws a non-Error, eg. <code>throw "a problem occurred";</code>
 
|-
 
|-

Revision as of 12:31, 10 March 2015

Orion 5.0 moved to ESLint as the validator that ships with Orion. This page captures ongoing issues.

Rules

The following sections describe all of the rules currently available in Orion and ones that we plan to add in the future.

Potential Programming Problems

These rules report about problems with your code that might have undesired or incorrect results. Warnings from these rules should be addressed.

Rule Default Severity Available Since Problem Message Details
no-comma-dangle Ignore 8.0 Trailing commas in object expressions are discouraged. Flags trailing commas in object expressions.
no-cond-assign Error 8.0 Expected a conditional expression and instead saw an assignment. Flags assignment in an if/while/do..while/for condition.
no-console Error 8.0 Discouraged use of console in browser-based code. Flags the use of console in browser-based code
no-constant-condition Error 8.0 Discouraged use of constant as a conditional expression. Flags the use of a constant as a conditional expression
no-debugger Warning 6.0 debugger' statement use is discouraged.  
no-dupe-keys Error 6.0 Duplicate object key '{key}'. Flags object literals that contain the same key more than once.
no-empty-block Warning 7.0   Flags an empty block like if (something) { }.
no-extra-semi Warning 5.0 Unnecessary semicolon.  
no-regex-spaces Error 8.0 Avoid using multiple spaces in regular expressions. Use ' {${0}}' instead. Flags regular expressions that have two or more subsequent spaces.
no-reserved-keys Error 8.0 Reserved words should not be used as property keys. Checks to see if a JavaScript reserved word is being used as a property key
no-sparse-arrays Warning 8.0 Sparse array declarations should de avoided. Flags sparse arrays with null elements
no-unreachable Error 6.0 Unreachable code. Flags statements that occur after a return, throw, etc.
use-isnan Error 6.0 Use the isNaN function to compare with NaN.  

Best Practices

These rules are not necessarily problem with your code, but are warnings that you might be doing something you probably should not be.

Rule Default Severity Available Since Problem Message Details
block-scoped-var Error - '{variable}' is already defined.
  • Occurs when a function-scoped variable is treated as if it was block scoped.
  • ESLint calls this error '{variable} used outside of binding context.'
curly Ignore 6.0 Statements should be enclosed in braces.  
eqeqeq Warning 5.0
  • Expected '===' and saw '=='.
  • Expected '!==' and saw '!='.
 
missing-doc Ignore 5.0 "Missing documentation for function '{name}.'" Flags missing documentation nodes on function declarations and function expressions when they appear as object properties
missing-doc-items Ignore -   Flags missing documentation for parameters, returns, throws, etc on function declarations and function expressions when they appear as object properties
no-caller Error 9.0 arguments.{callee, caller} is deprecated. Flags references to arguments.callee and arguments.caller.
no-eval Ignore 6.0 'eval' function calls are discouraged.  
no-fallthrough Error 6.0 Switch case may be entered by falling through previous case. If intended, add a new comment //$FALL-THROUGH$ on the line above Flags a fallthrough case within a switch statement, unless it is explicitly commented.
no-implied-eval Ignore 6.0 Implicit 'eval' function calls are discouraged. Flags calls to the string-argument form of setTimeout and setInterval, which implicitly perform eval. This rule logic was merged to be part of the no-eval rule.
no-iterator Error 8.0 Discouraged __iterator__ property use. Flags use of __iterator__ as an identifier name or property key.
no-new-array Warning 6.0 Use the array literal notation []. Flags new Array().
no-new-func Warning 6.0 The Function constructor is eval. Flags new Function().
no-new-object Warning 6.0 Use the object literal notation {}. Flags new Object().
no-new-wrappers Warning 6.0 Do not use {String, Number, Boolean, Math, JSON} as a constructor. Flags new applied to any of those.
no-proto Error -
  • Reserved name '__proto__' should not be assigned."
  • 'Reserved name '__proto__' should not be used as a key."
 
no-redeclare Warning 5.0 '{a}' is already defined. Usually results from having two for loops in the same function that share a loop variable declaration like var i=....
no-self-compare Error -   Flags comparisons where the left- and right-hand sides are the same.
no-shadow Warning 8.0 '{a}' is already declared in the upper scope. Flags variables that have the same name as a variable declared in an upper scope.
no-shadow-global Warning 9.0 '{a}' shadows a global member. Flags variables that have the same name as a variable declared in the global scope or specified environments.
no-undef Error 5.0 '{variable}' is not defined.
  • Flags references to a global variable that is not listed in a /*global*/ or /*globals*/ block.
  • Predefined environments (eg. node, browser) can be set in the /*jslint */ block.
no-unused-params Warning 6.0 "Parameter '{param}' is not used." Flags parameters in function declarations / expressions if they are not being used
no-unused-vars Warning 5.0 Function declares unused variable '{a}'.  
no-use-before-define Warning 5.0 '{a}' was used before it was defined.  
no-with Warning - Expected an identifier and instead saw 'with'. Treated as fatal parse error in JSLint.
radix Warning 8.0 Missing radix parameter. Warns when parseInt() called without the 2nd parameter (radix).
throw-error Warning 7.0 Throw an Error instead. Flags code that throws a non-Error, eg. throw "a problem occurred";

Code Style

These rules are not problems in any way but will warn based on certain accepted styles for coding.

Rule Default Severity Available Since Problem Message Details
missing-nls Ignore -   Flags String literals that are not properly NLS'd
new-parens Error 6.0 Missing parentheses invoking constructor. Flags new Whatever
no-mixed-returns Error -   Flags functions that return more than one kind of item, for example returning String and Object
no-undef-init Warning - It is not necessary to initialize '{variable}' to 'undefined'.  
semi Warning 5.0 Missing semicolon.  

Implementing a new rule

This section explains how to implement a new linting rule. For brevity, all paths are given relative to bundles/org.eclipse.orion.client.javascript/web/ in the client repo.

First, create the tests and rule:

  1. Create a new test file for the rule at: /eslint/tests/lib/rules/{rule-name}.js.
  2. Link your test to the suite in /eslint/tests/load-tests.js.
  3. Implement the actual logic for your rule in /eslint/lib/load-rules-async.js.

At this point you should run the JS bundle tests and ensure your rule works as intended. To get your rule running in the Orion product's validator, there are additional steps:

  1. Create strings for the validation message(s) generated by your rule in /javascript/nls/root/problems.js.
  2. Create a short string describing what your rule does in /javascript/nls/root/messages.js.
  3. Add an entry to the orion.core.setting declaration in /javascript/plugins/javascriptPlugin.js. This allows your rule to be configured from the JS validator settings page. Make sure it references the same nameKey used in messages.js.
  4. Add a config entry for your rule to the default ESLint config object in /javascript/validator.js.
  5. Add your rule to the #updated() handler in /javascript/validator.js.

Reload the JS plugin, and your rule should now be configurable from the Settings page, and properly set up for translation too.

Tests

  • Every rule needs extensive unit tests.
  • Unit tests should use Mocha.

Running the tests

  • To run the ESLint tests as part of the main JavaScript tests suite load {orion-server-url}/javascript/js-tests/JsMochaSuite.html in your web browser.
  • To run just the ESLint rule tests, load {orion-server-url}/js-tests/javascript/JsMochaSuite.html?grep=ESLint%20Rule%20Tests in your browser.
  • To run just the ESLint core tests, load {orion-server-url}/js-tests/javascript/JsMochaSuite.html?grep=ESLint%20Core%20Tests in your browser.
  • To run only a subset of the tests, add ?grep=ESLint%20Rule%20Tests onto the test page URL.

See Mocha usage options for more options.

User interface

  • Should we have a UI for configuring what rules are active? bug 424268.
  • Should we try to support .eslintrc? This would be an ideal project-scope setting.
  • Should we try to honor equivalent JSLint/JSHint flags when possible? For example /*jslint eqeqeq:false */ could disable the eqeqeq rule on a per-file basis.
    • ESLint now has its own syntax for this: /*eslint ..*/, which we are using instead.

i18n

We need to support i18n. Pre-req is bug 422278 (orion.edit.validator support for i18n).

Back to the top