Update rule metadata (#4302)

css-sonarpedia/sonarpedia.json

@@ -3,7 +3,7 @@
   "languages": [
     "CSS"
   ],
-  "latest-update": "2023-09-22T12:30:24.906477Z",
+  "latest-update": "2023-10-20T14:08:17.442676Z",
   "options": {
     "no-language-in-filenames": true
   }

sonar-plugin/css/src/main/resources/org/sonar/l10n/css/rules/css/S1128.json

@@ -10,7 +10,7 @@
   "status": "ready",
   "remediation": {
     "func": "Constant\/Issue",
-    "constantCost": "2min"
+    "constantCost": "1min"
   },
   "tags": [
     "unused"

sonar-plugin/css/src/main/resources/org/sonar/l10n/css/rules/css/S4649.html

@@ -1,23 +1,45 @@
 <h2>Why is this an issue?</h2>
+<p>The <code>font-family</code> (and the shorthand <code>font</code>) CSS property specifies a prioritized list of one or more font family names
+and/or generic family names for the selected element.</p>
 <p>If none of the font names defined in a <code>font</code> or <code>font-family</code> declaration are available on the browser of the user, the
 browser will display the text using its default font. It’s recommended to always define a generic font family for each declaration of
-<code>font</code> or <code>font-family</code> to get a less degraded situation than relying on the default browser font. All browsers should implement
-a list of generic font matching these families: <code>Serif</code>, <code>Sans-serif</code>, <code>cursive</code>, <code>fantasy</code>,
-<code>Monospace</code>.</p>
-<h3>Noncompliant code example</h3>
-<pre>
+<code>font</code> or <code>font-family</code> to get a less degraded situation than relying on the default browser font. This lets the browser select
+an acceptable fallback font when necessary.</p>
+<p>The list of generic font families is as follows:</p>
+<ul>
+  <li> <code>serif</code>: Glyphs have finishing strokes, flared or tapering ends, or actual serifed endings. </li>
+  <li> <code>sans-serif</code>: Glyphs have plain stroke endings. </li>
+  <li> <code>cursive</code>: Glyphs in cursive fonts generally have either joining strokes or other cursive characteristics beyond those of italic
+  typefaces. </li>
+  <li> <code>fantasy</code>: Fantasy fonts are primarily decorative fonts that contain playful representations of characters. </li>
+  <li> <code>monospace</code>: All glyphs have the same fixed width. </li>
+  <li> <code>system-ui</code>: Glyphs are taken from the default user interface font on a given platform. </li>
+  <li> <code>ui-serif</code>: The default user interface serif font. </li>
+  <li> <code>ui-sans-serif</code>: The default user interface sans-serif font. </li>
+  <li> <code>ui-monospace</code>: The default user interface monospace font. </li>
+  <li> <code>ui-rounded</code>: The default user interface font that has rounded features. </li>
+</ul>
+<h2>How to fix it</h2>
+<p>You should always include at least one generic family name in a <code>font-family</code> list, since there’s no guarantee that any given font is
+available.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
 a {
   font-family: Helvetica, Arial, Verdana, Tahoma; /* Noncompliant; there is no generic font family in the list */
 }
 </pre>
-<h3>Compliant solution</h3>
-<pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
 a {
   font-family: Helvetica, Arial, Verdana, Tahoma, sans-serif;
 }
 </pre>
 <h2>Resources</h2>
+<h3>Documentation</h3>
 <ul>
-  <li> <a href="https://www.w3.org/TR/CSS2/fonts.html#generic-font-families">CSS Specification</a> - Generic font families </li>
+  <li> CSS Specification - <a href="https://www.w3.org/TR/CSS2/fonts.html#generic-font-families">Generic font families</a> </li>
+  <li> MDN - <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/font-family"><code>font-family</code></a> </li>
+  <li> MDN - <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/font"><code>font</code></a> </li>
 </ul>
 

sonar-plugin/css/src/main/resources/org/sonar/l10n/css/rules/css/S4666.html

@@ -1,21 +1,39 @@
 <h2>Why is this an issue?</h2>
-<p>Duplication of selectors might indicate a copy-paste mistake. The rule detects the following kinds of duplications:</p>
+<p>In CSS, when selectors are duplicated, the browser applies them in cascade. This means that if two selectors are identical, the second one takes
+precedence. However, if the declarations within the selectors are not conflicting, they will be combined.</p>
+<p>This behavior can lead to unexpected results and make debugging more difficult, especially in larger stylesheets. Therefore, it’s generally
+recommended to avoid duplicating selectors.</p>
+<p>The rule detects the following kinds of duplications:</p>
 <ul>
-  <li> within a list of selectors in a single rule set </li>
+  <li> within a list of selectors in a single rule set, </li>
   <li> for duplicated selectors in different rule sets within a single stylesheet. </li>
 </ul>
-<h3>Noncompliant code example</h3>
-<pre>
-.foo, .bar, .foo { ... }  /* Noncompliant */
+<h2>How to fix it</h2>
+<p>To fix your code, either remove the duplicated selector or merge all declarations.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+p {
+  color: blue;
+  font-size: 16px;
+}
 
-.class1 { ... }
-.class1 { ... }  /* Noncompliant */
+p { /* Noncompliant: duplicated selector 'p', overwrites property 'color' */
+  color: red;
+}
 </pre>
-<h3>Compliant solution</h3>
-<pre>
-.foo, .bar { ... }
-
-.class1 { ... }
-.class2 { ... }
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+p {
+  color: red;
+  font-size: 16px;
+}
 </pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li> MDN - <a href="https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors">CSS selectors</a> </li>
+  <li> MDN - <a href="https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance">Cascade, specificity, and
+  inheritance</a> </li>
+</ul>
 

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S106.html

@@ -1,9 +1,39 @@
 <h2>Why is this an issue?</h2>
-<p>Debug statements are always useful during development. But include them in production code - particularly in code that runs client-side - and you
-run the risk of inadvertently exposing sensitive information, slowing down the browser, or even erroring-out the site for some users.</p>
-<h3>Noncompliant code example</h3>
-<pre>
-console.log(password_entered); // Noncompliant
+<p>In software development, logs serve as a record of events within an application, providing crucial insights for debugging. When logging, it is
+essential to ensure that the logs are:</p>
+<ul>
+  <li> easily accessible </li>
+  <li> uniformly formatted for readability </li>
+  <li> properly recorded </li>
+  <li> securely logged when dealing with sensitive data </li>
+</ul>
+<p>Those requirements are not met if a program directly writes to the standard outputs (e.g., console). That is why defining and using a dedicated
+logger is highly recommended.</p>
+<h3>Code examples</h3>
+<p>The following noncompliant code:</p>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+function doSomething() {
+  // ...
+  console.log("My Message");
+  // ...
+}
+</pre>
+<p>In <code>Node.js</code> could be replaced by the <code>winston</code> logging library:</p>
+<pre data-diff-id="1" data-diff-type="compliant">
+const winston = require("winston");
+
+const logger = winston.createLogger({
+  level: "debug",
+  format: winston.format.json(),
+  transports: [new winston.transports.Console()],
+});
+
+
+function doSomething() {
+  // ...
+  logger.info("My Message");
+  // ...
+}
 </pre>
 <h2>Resources</h2>
 <ul>

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1066.html

@@ -1,17 +1,43 @@
 <h2>Why is this an issue?</h2>
-<p>Merging collapsible <code>if</code> statements increases the code’s readability.</p>
-<h3>Noncompliant code example</h3>
+<p>Nested code - blocks of code inside blocks of code - is eventually necessary, but increases complexity. This is why keeping the code as flat as
+possible, by avoiding unnecessary nesting, is considered a good practice.</p>
+<p>Merging <code>if</code> statements when possible will decrease the nesting of the code and improve its readability.</p>
+<p>Code like</p>
 <pre>
 if (x != undefined) {
   if (y === 2) {
     // ...
   }
 }
 </pre>
-<h3>Compliant solution</h3>
+<p>Will be more readable as</p>
 <pre>
 if (x != undefined &amp;&amp; y === 2) {
   // ...
 }
 </pre>
+<h2>How to fix it</h2>
+<p>If merging the conditions seems to result in a more complex code, extracting the condition or part of it in a named function or variable is a
+better approach to fix readability.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre>
+if (file != undefined) {
+  if (file.isFile() || file.isDirectory()) {        // Noncompliant
+    /* ... */
+  }
+}
+</pre>
+<h4>Compliant solution</h4>
+<pre>
+function isFileOrDirectory(File file) {
+  return file.isFile() || file.isDirectory();
+}
+
+/* ... */
+
+if (file. != undefined &amp;&amp; isFileOrDirectory(file)) { // Compliant
+  /* ... */
+}
+</pre>
 

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1066.json

@@ -1,5 +1,5 @@
 {
-  "title": "Collapsible \"if\" statements should be merged",
+  "title": "Mergeable \"if\" statements should be combined",
   "type": "CODE_SMELL",
   "code": {
     "impacts": {

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1068.html

@@ -37,7 +37,8 @@ <h2>Why is this an issue?</h2>
 <h2>Resources</h2>
 <h3>Documentation</h3>
 <ul>
-  <li> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields">MDN - Private class features</a> </li>
-  <li> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">MDN - Classes</a> </li>
+  <li> MDN web docs - <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields">Private class
+  features</a> </li>
+  <li> MDN web docs - <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">Classes</a> </li>
 </ul>
 

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S109.html

@@ -1,23 +1,26 @@
+<p>A magic number is a hard-coded numerical value that may lack context or meaning. They should not be used because they can make the code less
+readable and maintainable.</p>
 <h2>Why is this an issue?</h2>
-<p>A magic number is a number that comes out of nowhere, and is directly used in a statement. Magic numbers are often used, for instance to limit the
-number of iterations of a loop, to test the value of a property, etc.</p>
-<p>Using magic numbers may seem obvious and straightforward when you’re writing a piece of code, but they are much less obvious and straightforward at
-debugging time.</p>
-<p>That is why magic numbers must be demystified by first being assigned to clearly named variables before being used.</p>
-<p>-1, 0 and 1 are not considered magic numbers.</p>
-<h3>Noncompliant code example</h3>
-<pre>
+<p>Magic numbers make the code more complex to understand as it requires the reader to have knowledge about the global context to understand the
+number itself. Their usage may seem obvious when writing the code, but it may not be the case for another developer or later once the context faded
+away. -1, 0, and 1 are not considered magic numbers.</p>
+<h2>How to fix it</h2>
+<p>Replacing them with a constant allows us to provide a meaningful name associated with the value. Instead of adding complexity to the code, it
+brings clarity and helps to understand the context and the global meaning.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
 function doSomething() {
-  for (let i = 0; i &lt; 4; i++) {    // Noncompliant, 4 is a magic number
+  for (let i = 0; i &lt; 4; i++) { // Noncompliant, 4 is a magic number
     // ...
   }
 }
 </pre>
-<h3>Compliant solution</h3>
-<pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
 function doSomething() {
   const numberOfCycles = 4;
-  for (let i = 0; i &lt; numberOfCycles; i++) {
+  for (let i = 0; i &lt; numberOfCycles; i++) { // Compliant
     // ...
   }
 }

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1110.html

@@ -1,25 +1,25 @@
 <p>This rule is deprecated, and will eventually be removed.</p>
 <h2>Why is this an issue?</h2>
-<p>The use of parentheses, even those not required to enforce a desired order of operations, can clarify the intent behind a piece of code. But
-redundant pairs of parentheses could be misleading, and should be removed.</p>
-<h3>Noncompliant code example</h3>
+<p>Parentheses can disambiguate the order of operations in complex expressions and make the code easier to understand.</p>
 <pre>
-let x = (y / 2 + 1);   //Compliant even if those parenthesis are useless for the compiler
+a = (b * c) + (d * e); // Compliant: the intent is clear.
+</pre>
+<p>Redundant parentheses are parenthesis that do not change the behavior of the code, and do not clarify the intent. They can mislead and complexify
+the code. They should be removed.</p>
+<h3>Noncompliant code example</h3>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+let x = ((y / 2 + 1));  // Noncompliant
 
-if (a &amp;&amp; ((x+y &gt; 0))) {  // Noncompliant
-  //...
+if (a &amp;&amp; ((x + y &gt; 0))) {  // Noncompliant
+  return ((x + 1));  // Noncompliant
 }
-
-return ((x + 1));  // Noncompliant
 </pre>
 <h3>Compliant solution</h3>
-<pre>
+<pre data-diff-id="1" data-diff-type="compliant">
 let x = (y / 2 + 1);
 
-if (a &amp;&amp; (x+y &gt; 0)) {
-  //...
+if (a &amp;&amp; (x + y &gt; 0)) {
+  return (x + 1);
 }
-
-return (x + 1);
 </pre>
 

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1117.html

@@ -1,4 +1,42 @@
 <h2>Why is this an issue?</h2>
-<p>Overriding or shadowing a variable declared in an outer scope can strongly impact the readability, and therefore the maintainability, of a piece of
-code. Further, it could lead maintainers to introduce bugs because they think they’re using one variable but are really using another.</p>
+<p>Variable shadowing happens when a variable declared in a specific scope has the same name as a variable in an outer scope.</p>
+<p>This can lead to three main problems:</p>
+<ul>
+  <li> Confusion: The same name can refer to different variables in different parts of the scope, making the code hard to read and understand. </li>
+  <li> Unintended Behavior: You might accidentally use the wrong variable, leading to hard-to-detect bugs. </li>
+  <li> Maintenance Issues: If the inner variable is removed or renamed, the code’s behavior might change unexpectedly because the outer variable is
+  now being used. </li>
+</ul>
+<p>To avoid these problems, rename the shadowing, shadowed, or both variables to accurately represent their purpose with unique and meaningful
+names.</p>
+<p>Note that functions in JavaScript are first-class citizens. This means that they possess the same attributes as variables, including the ability to
+shadow other variables and, conversely, be shadowed by them.</p>
+<h3>Noncompliant code example</h3>
+<p>The example below shows the typical situations in which shadowing can occur.</p>
+<pre>
+function outer(items) {
+  var counter = 0;
+
+  function inner(items) { // Noncompliant: the parameter "items" is shadowed.
+    var counter = counter + 1; // Noncompliant: the outer "counter" is shadowed.
+  }
+
+  inner(items);
+
+  return counter; // returns 0
+}
+
+function search(items, match) { // Noncompliant: the function "match" (below) is shadowed.
+  // ...
+}
+
+function match(value, key) {
+  // ...
+}
+</pre>
+<h2>Resources</h2>
+<h3>Related rules</h3>
+<ul>
+  <li> {rule:javascript:S2814} - Variables and functions should not be redeclared </li>
+</ul>
 

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1117.json

@@ -1,5 +1,4 @@
 {
-  "title": "Variables should not be shadowed",
   "type": "CODE_SMELL",
   "code": {
     "impacts": {
@@ -21,6 +20,7 @@
   "sqKey": "S1117",
   "scope": "Main",
   "quickfix": "unknown",
+  "title": "Variables should not be shadowed",
   "compatibleLanguages": [
     "JAVASCRIPT",
     "TYPESCRIPT"

sonar-plugin/javascript-checks/src/main/resources/org/sonar/l10n/javascript/rules/javascript/S1119.html

@@ -23,8 +23,8 @@ <h2>Why is this an issue?</h2>
 <h2>Resources</h2>
 <h3>Documentation</h3>
 <ul>
-  <li> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label">MDN - label</a> </li>
-  <li> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break">MDN - <code>break</code></a> </li>
-  <li> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/continue">MDN - <code>continue</code></a> </li>
+  <li> MDN web docs - <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/label">label</a> </li>
+  <li> MDN web docs - <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/break"><code>break</code></a> </li>
+  <li> MDN web docs - <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/continue"><code>continue</code></a> </li>
 </ul>