@sap/eslint-plugin-cds 2.1.0 → 2.3.0

package/lib/impl/utils/rules.js

@@ -1,25 +1,25 @@
+/**
+ * @typedef { import('eslint').Linter.ConfigOverride.files } ConfigOverrideFiles
+ */
+
 const fs = require("fs");
+const os = require("os");
+const cp = require("child_process");
+const semver = require("semver");
 const path = require("path");
 const { mkdirp } = require("@sap/cds/lib/utils");
-const { getLastLine } = require("./model");
+const { Cache, getLastLine } = require("./model");
 
 const JSONC = require("./jsonc");
-const CONSTANTS = require("../constants");
-const REGEX_COMMENT_START = "(/\\*|(.+)?//)\\s+eslint-";
+const { categories } = require("../constants");
+const IS_WIN = os.platform() === "win32";
+const REGEX_COMMENT_START = "(/\\*|(.+)?//)(\\s?)+eslint-";
 const REGEX_COMMENTS = `${REGEX_COMMENT_START}(enable|disable)(-next)?(-line)?(.+)?`;
 
 module.exports = {
   /**
-   * Returns an array of allowed file extensions
-   * the plugin can parse of the form "*.ext"
-   * @returns Array of file extensions
-   */
-  getFileExtensions: function () {
-    return CONSTANTS.overrides[0].files;
-  },
-
-  /**
-   * Turns rules on/off for given line according to eslint-disable comments:
+   * Turns rules "on" or "off" for given line according to eslint-disable
+   * comments:
    * 1. Reads code string and extracts a list of comments (in order)
    * 2. Initiates rulesDisabled array with all rules "on" by default
    * 3. Switches rules "off" (or "on" again) based on disable comment
@@ -28,92 +28,140 @@ module.exports = {
    * @param line current code line to analyze
    * @returns rules dictionary with rules being either 'on' and 'off'
    */
-  getDisabledFromComments: function (rules, code, sourcecode, line) {
+  getDisabled: function (code, sourcecode, line) {
     const listDisabled = [];
-    const rulesDisabled = rules.reduce((o, key) => ({ ...o, [key]: "on" }), {});
-    const matches = [...code.matchAll(REGEX_COMMENTS)];
-    if (matches.length > 0) {
-      matches.forEach((match) => {
-        if (match) {
-          const index = match.index;
-          match = match[0];
-          if (match.includes("*/")) {
-            match = match.split("*/")[0].replace("/*", "");
-          } else if (match.includes("//")) {
-            match = match.split("//")[1];
-          }
-          if (match) match = match.trim();
-          ["disable", "enable"].forEach((keyword) => {
-            const loc = sourcecode.getLocFromIndex(index);
-            const disableType = match.split(" ")[0];
-            let disableRules = match.split(`${disableType} `)[1];
-            if (disableRules) {
-              disableRules = disableRules.split(",").map((rule) => rule.trim());
-            } else {
-              const envRules = module.exports.getEnvRules(path.join(__dirname, "../rules"));
-              const modelRules = module.exports.getModelRules(path.join(__dirname, "../rules"));
-              disableRules = envRules.concat(modelRules).map((rule) => `@sap/cds/${rule}`);
+    let { listEnvRules, listModelRules, listRules } = Cache.get("rulesInfo");
+    const rulesDisabled = listRules.reduce(
+      (o, key) => ({ ...o, [key]: "on" }),
+      {}
+    );
+    let matches = [];
+    if (code) {
+      matches = [...code.matchAll(REGEX_COMMENTS)];
+      if (matches.length > 0) {
+        matches.forEach((match) => {
+          if (match) {
+            const index = match.index;
+            match = match[0];
+            if (match.includes("*/")) {
+              match = match.split("*/")[0].replace("/*", "");
+            } else if (match.includes("//")) {
+              match = match.split("//")[1];
+            }
+            if (match) {
+              match = match.trim();
             }
-            let comment = {};
-            if (
-              [
-                `eslint-${keyword}`,
-                `eslint-${keyword}-line`,
-                `eslint-${keyword}-next-line`,
-              ].includes(disableType)
-            ) {
-              if (disableType.includes("-next-line")) {
-                comment = {
-                  lineComment: loc.line,
-                  lineDisabled: loc.line + 1,
-                  rules: disableRules,
-                  type: keyword,
-                };
+            ["disable", "enable"].forEach((keyword) => {
+              const loc = sourcecode.getLocFromIndex(index);
+              const disableType = match.split(" ")[0];
+              let disableRules = match.split(`${disableType} `)[1];
+              if (disableRules) {
+                disableRules = disableRules
+                  .split(",")
+                  .map((rule) => rule.trim());
               } else {
-                comment = {
-                  lineComment: loc.line,
-                  lineDisabled: loc.line,
-                  rules: disableRules,
-                  type: keyword,
-                };
+                disableRules = listEnvRules
+                  .concat(listModelRules)
+                  .map((rule) => `@sap/cds/${rule}`);
               }
-              if (!disableType.includes("-line")) {
-                comment.lineDisabled = "EOF";
+              let comment = {};
+              if (
+                [
+                  `eslint-${keyword}`,
+                  `eslint-${keyword}-line`,
+                  `eslint-${keyword}-next-line`,
+                ].includes(disableType)
+              ) {
+                if (disableType.includes("-next-line")) {
+                  comment = {
+                    lineComment: loc.line,
+                    lineDisabled: loc.line + 1,
+                    rules: disableRules,
+                    type: keyword,
+                  };
+                } else {
+                  comment = {
+                    lineComment: loc.line,
+                    lineDisabled: loc.line,
+                    rules: disableRules,
+                    type: keyword,
+                  };
+                }
+                if (!disableType.includes("-line")) {
+                  comment.lineDisabled = "EOF";
+                }
               }
+              listDisabled.push(comment);
+            });
+          }
+        });
+        for (let i = 0; i <= listDisabled.length - 1; i++) {
+          if (listDisabled[i].lineComment > line) {
+            break;
+          }
+          if (
+            listDisabled[i].lineDisabled === "EOF" ||
+            listDisabled[i].lineDisabled === line
+          ) {
+            if (listDisabled[i].lineDisabled === "EOF") {
+              listDisabled[i].lineDisabled = getLastLine(code);
             }
-            listDisabled.push(comment);
-          });
+            if (listDisabled[i].rules) {
+              listDisabled[i].rules.forEach((rule) => {
+                if (listDisabled[i].type === "disable") {
+                  rulesDisabled[rule] = "off";
+                } else if (listDisabled[i].type === "enable") {
+                  rulesDisabled[rule] = "on";
+                }
+              });
+            }
+          }
         }
-      });
-      for (let i = 0; i <= listDisabled.length - 1; i++) {
-        if (listDisabled[i].lineComment > line) {
-          break;
+      }
+    }
+    return rulesDisabled;
+  },
+
+  /**
+   * Checks whether a lint rule has been disabled by eslint-disable
+   * comments at a given location
+   * @param entry lint report
+   * @param cdscontext cds context object
+   * @param rules all availabe rules
+   * @returns boolean
+   */
+
+  isRuleDisabled: function (entry, cdscontext) {
+    let isDisabled = false;
+    if (entry.loc && entry.loc.start) {
+      const line = entry.loc.start.line;
+      if (cdscontext) {
+        const rulesDisabled = module.exports.getDisabled(
+          cdscontext.code,
+          cdscontext.sourcecode,
+          line
+        );
+        let ruleID = cdscontext.ruleID;
+        if (!ruleID) {
+          ruleID = cdscontext.id;
         }
         if (
-          listDisabled[i].lineDisabled === "EOF" ||
-          listDisabled[i].lineDisabled === line
+          line &&
+          ruleID in rulesDisabled &&
+          rulesDisabled[ruleID] === "off"
         ) {
-          if (listDisabled[i].lineDisabled === "EOF") {
-            listDisabled[i].lineDisabled = getLastLine(code);
-          }
-          if (listDisabled[i].rules) {
-            listDisabled[i].rules.forEach((rule) => {
-              if (listDisabled[i].type === "disable") {
-                rulesDisabled[rule] = "off";
-              } else if (listDisabled[i].type === "enable") {
-                rulesDisabled[rule] = "on";
-              }
-            });
-          }
+          isDisabled = true;
         }
       }
     }
-    return rulesDisabled;
+    return isDisabled;
   },
+
   /**
-   * Gets value for a given key in allowed keys of ESLint's meta data in createRule api
-   * @param {*} text
-   * @param {*} key
+   * Gets value for a given key in allowed keys of ESLint's meta data in
+   * defineRule api
+   * @param {string} text meta object from rule
+   * @param {string} key key to get value for
    * @returns Value for given key
    */
   getKeyFromMeta: function (text, key) {
@@ -138,14 +186,44 @@ module.exports = {
         return "";
       }
     } else {
+      const regexBoolean = new RegExp(`${key}:[\\s]+true[\\s]?,`, "gm");
+      const matchBoolean = regexBoolean.exec(text);
+      if (matchBoolean) {
+        if (matchBoolean[0].includes("true,")) {
+          return true;
+        } else {
+          return false;
+        }
+      }
       return "";
     }
   },
 
+  getPackageVersion: function (registry) {
+    let version;
+    try {
+      const result = cp.execSync(
+        `npm show @sap/eslint-plugin-cds --@sap:registry=${registry} --json`,
+        {
+          cwd: process.cwd(),
+          shell: IS_WIN,
+          stdio: "pipe",
+        })
+        .toString();
+      version = JSON.parse(result)["version"];
+    } catch (err) {
+      // Do not throw
+    }
+    if (!version) {
+      console.err(`Failed to get latest plugin version from ${registry} - check your connection and try again.`);
+    }
+    return version;
+  },
+
   /**
    * Gets value for a given key in allowed keys for input of runRuleTester api
-   * @param {*} text
-   * @param {*} key
+   * @param {string} text test input for ruleTester
+   * @param {string} key key to get value for
    * @returns Value for given key
    */
   getKeyFromTest: function (text, key) {
@@ -172,6 +250,12 @@ module.exports = {
       if (matchTestKey) {
         result = matchTestKey[0];
       }
+    } else if (key === "data") {
+      const regexTestKey = new RegExp(`${key}:.*}`, "gm");
+      const matchTestKey = regexTestKey.exec(text);
+      if (matchTestKey) {
+        result = matchTestKey[0];
+      }
     } else {
       result = `No parameter \\'${key}\\' found in ruleTest`;
     }
@@ -180,26 +264,37 @@ module.exports = {
 
   /**
    * Generates overview table of all rules based on rule dictionary.
-   * @param {*} ruleDict
-   * @param {*} release
-   * @param {*} table
+   * @param ruleDict
+   * @param release
+   * @param table
    * @returns Markdown table
    */
   genMdRules: function (ruleDict, release, table = true) {
-    let version = "latest";
-    if (release) {
-      version = release;
-    }
-    let mdRules = `# @sap/eslint-plugin-cds [${version}]\n\n`;
+    let mdRules = `# @sap/eslint-plugin-cds [latest]\n\n`;
     if (table) {
-      mdRules += "<table>";
-      mdRules += "<tr><th>Rule</th><th>Category</th><th>Recommended</th><th>Fixable</th><th>Version</th></tr>";
-      Object.entries(ruleDict).forEach(([category, rules]) => {
+      mdRules += `Rules in ESLint are grouped by type to help you understand their purpose. Each rule has emojis denoting:\n\n`;
+      mdRules += `✔️ if the plugin's "recommended" configuration enables the rule\n\n`;
+      mdRules += `🔧 if problems reported by the rule are automatically fixable (\`--fix\`)\n\n`;
+      mdRules += `💡  if problems reported by the rule are manually fixable (editor)\n\n`;
+      if (!release) {
+        mdRules += `🚧 if rule exists in plugin (main branch) but is not yet released (artifactory)\n\n`;
+        mdRules += "|   |   |   |   |  |  |  |\n";
+        mdRules += "|:-:|:-:|:-:|:-:|-:|:-|:-|\n";
+      } else {
+        mdRules += "|   |   |   |   |  |  |  |\n";
+        mdRules += "|:-:|:-:|:-:|:-:|-:|:-|:-|\n";
+      }
+      /* eslint-disable-next-line no-unused-vars */
+      Object.entries(ruleDict).forEach(([, rules]) => {
         rules.forEach(function (rule) {
-          mdRules += `<tr><td><a title="${rule.details}" href="./Rules.md#rule-${rule.name}">${rule.name}</a></td><td>${category}</td><td>${rule.recommended}</td><td>${rule.fix}</td><td>${rule.version}</td></tr>`;
+          if (release) {
+            mdRules += `| ${rule.recommended} | ${rule.fixable} | ${rule.hasSuggestions} | | &nbsp; | [${rule.name}](Rules-released.md#${rule.name}) | ${rule.details}|\n`;
+          } else {
+            mdRules += `| ${rule.recommended} | ${rule.fixable} | ${rule.hasSuggestions} | ${rule.construction} | &nbsp; | [${rule.name}](Rules.md#${rule.name}) | ${rule.details}|\n`;
+          }
         });
       });
-      mdRules += "</table>\n\n<br>\n\n";
+      mdRules += "\n";
     }
     return mdRules;
   },
@@ -211,11 +306,11 @@ module.exports = {
    * If used internally within the @sap/eslint-plugin-cds, this
    * also generates 'released' files, which only contain information
    * on rules published until the currently released version.
-   * @param {*} ruleDict
-   * @param {*} docsPath
-   * @param {*} release
+   * @param ruleDict
+   * @param docsPath
+   * @param release
    */
-  genDocFiles: function (ruleDict, docsPath, release) {
+  genDocFiles: function (ruleDict, docsPath, release=false) {
     let suffix = "";
     if (release) {
       suffix = "-released";
@@ -232,8 +327,11 @@ module.exports = {
     const mdRulesCur = fs.readFileSync(ruleDocsPath, "utf8");
     const mdRuleListCur = fs.readFileSync(ruleListDocsPath, "utf8");
 
+    // Get rules table
+    let mdRuleList = module.exports.genMdRules(ruleDict, release, true);
+
+    // Get rule details
     let mdRules = module.exports.genMdRules(ruleDict, release, false);
-    let mdRuleList = module.exports.genMdRules(ruleDict);
     /* eslint-disable-next-line no-unused-vars */
     Object.entries(ruleDict).forEach(([category, rules]) => {
       rules.forEach(function (rule) {
@@ -252,10 +350,10 @@ module.exports = {
    * for user according to contents of:
    * - Rule files
    * - Test files (with valid/invalid/fixed examples)
-   * @param {*} projectPath
+   * @param {string} projectPath
+   * @param {string} customRulesDir
    */
-  async genDocs(projectPath, customRulesDir) {
-    let mdRule, mdRuleSources, mdRuleContents;
+  async genDocs(projectPath, customRulesDir, registry) {
     let docsPath, rulePath, testPath, release;
 
     if (!projectPath) {
@@ -269,19 +367,40 @@ module.exports = {
       docsPath = path.join(projectPath, `${customRulesDir}/docs`);
       rulePath = path.join(projectPath, `${customRulesDir}/rules`);
       testPath = path.join(projectPath, `${customRulesDir}/tests`);
+      if (!fs.existsSync(docsPath)) {
+        await mkdirp(docsPath);
+      }
+      if (!fs.existsSync(rulePath)) {
+        await mkdirp(rulePath);
+      }
+      if (!fs.existsSync(testPath)) {
+        await mkdirp(testPath);
+      }
     }
 
-    if (!fs.existsSync(docsPath)) {
-      await mkdirp(docsPath);
-    }
-    if (!fs.existsSync(rulePath)) {
-      await mkdirp(rulePath);
-    }
-    if (!fs.existsSync(testPath)) {
-      await mkdirp(testPath);
+    if (registry) {
+      // Get rules (internal on artifactory)
+      const versionInternal = module.exports.getPackageVersion(registry);
+      if (versionInternal) {
+        const ruleDictInternal = module.exports.getRuleDict(docsPath, rulePath, testPath, versionInternal);
+        module.exports.genDocFiles(ruleDictInternal, docsPath);
+      }
+      // Get rules released (external on npm)
+      const versionExternal = module.exports.getPackageVersion("https://registry.npmjs.org");
+      if (versionExternal) {
+        const ruleDictExternal = module.exports.getRuleDict(docsPath, rulePath, testPath, versionExternal, release);
+        module.exports.genDocFiles(ruleDictExternal, docsPath, release);
+      }
+    } else {
+      // Get "custom" rules
+      const ruleDict = module.exports.getRuleDict(docsPath, rulePath, testPath);
+      module.exports.genDocFiles(ruleDict, docsPath);
     }
+  },
 
-    const ruleDict = {};
+  getRuleDict: function (docsPath, rulePath, testPath, versionRequired='0.0.0', release=false) {
+    let mdRule, mdRuleSources, mdRuleContents;
+    let ruleDict = {};
     fs.readdirSync(rulePath).filter(function (file) {
       if (path.extname(file).toLowerCase() === ".js" && file !== "index.js") {
         const rule = path.basename(file).replace(path.extname(file), "");
@@ -289,169 +408,271 @@ module.exports = {
           const ruleTestPath = path.join(testPath, rule, "rule.test.js");
 
           // Get rule meta information
-          const ruleMeta = fs.readFileSync(path.join(rulePath, file), "utf8");
-          const details = module.exports.getKeyFromMeta(
-            ruleMeta,
-            "description"
-          );
-          const category = module.exports.getKeyFromMeta(ruleMeta, "category");
-          const fixable = module.exports.getKeyFromMeta(ruleMeta, "fixable");
+          const ruleMeta = require(path.join(rulePath, file)).meta;
+          const version = ruleMeta.docs.version;
 
-          let isFixable = "";
-          if (["code", "whitespace"].includes(fixable)) {
-            isFixable = "🔧";
-          }
-
-          let isRecommended = "";
-          if (Object.keys(CONSTANTS.recommended).includes(`@sap/cds/${rule}`)) {
-            isRecommended = "✔️";
-          }
+          if ((release && semver.satisfies(version, `<=${versionRequired}`))
+          || (!release)) {
+            const details = ruleMeta.docs.description;
+            const category = ruleMeta.docs.category;
+            const fixable = ruleMeta.fixable;
+            const messages = ruleMeta.messages;
+            const recommended = ruleMeta.docs.recommended;
+            const suggestions = ruleMeta.hasSuggestions;
 
-          const version = module.exports.getKeyFromMeta(ruleMeta, "version");
+            let underConstruction = "";
+            if (!release && semver.satisfies(version, `>${versionRequired}`)) {
+              underConstruction = "🚧";
+            }
 
-          // Get rule valid/invalid tests
-          mdRule = "";
-          if (fs.existsSync(ruleTestPath)) {
-            const ruleTest = fs.readFileSync(ruleTestPath, "utf8");
-            const filename = module.exports.getKeyFromTest(
-              ruleTest,
-              "filename"
-            );
-            let errorsString = module.exports.getKeyFromTest(
-              ruleTest,
-              "errors"
-            );
-            const re = /(\S+):/gm;
-            errorsString = errorsString
-              .replace(re, `"$&`)
-              .replace(/:/gm, '":')
-              .replace(/`/gm, '"');
-            const errors = JSONC.parse(`{${errorsString}}`).errors;
-            const valid = fs.readFileSync(
-              path.join(testPath, rule, "valid", filename),
-              "utf8"
-            );
-            let invalid = fs.readFileSync(
-              path.join(testPath, rule, "invalid", filename),
-              "utf8"
-            );
-            const insertAt = (str, sub, pos) =>
-              `${str.slice(0, pos)}${sub}${str.slice(pos)}`;
-            errors.forEach((err) => {
-              const msg = err.message.replace(/"/gm, "`");
-              if (err.line) {
-                const code = invalid.split("\n");
-                code[err.line - 1] = insertAt(
-                  code[err.line - 1],
-                  "</span>",
-                  err.endColumn - 1
-                );
-                code[err.line - 1] = insertAt(
-                  code[err.line - 1],
-                  `<span style="text-decoration-line:underline; text-decoration-style:wavy; text-decoration-color:red;" title="${msg}">`,
-                  err.column - 1
-                );
-                invalid = code.join("\n");
-              }
-            });
+            let isFixable = "";
+            if (["code", "whitespace"].includes(fixable)) {
+              isFixable = "🔧";
+            }
 
-            mdRule +=
-              `<span>✔️&nbsp;&nbsp; Example of ` +
-              `<span style="color:green">correct</span> ` +
-              `code for this rule:</span>\n\n<pre><code>\n${valid}\n</code></pre>\n\n`;
-            mdRule +=
-              `<span>❌&nbsp;&nbsp; Example of ` +
-              `<span style="color:red">incorrect</span> ` +
-              `code for this rule:</span>\n\n<pre><code>\n${invalid}\n</code></pre>`;
-          }
+            let isRecommended = "";
+            if (recommended === true) {
+              isRecommended = "✔️";
+            }
 
-          mdRuleContents = `## Rule: ${rule}\n`;
-          mdRuleContents += `<span class='label shifted'>${category}</span>\n\n`;
-          mdRuleContents += `### Rule Details\n${details}\n\n`;
-          if (mdRule) {
-            mdRuleContents += `### Examples\n${mdRule}\n\n`;
-          }
-          mdRuleContents += `### Version\nThis rule was introduced in \`@sap/eslint-plugin-cds ${version}\`.\n\n`;
-          mdRuleSources = `### Resources\n[Rule & Documentation source](${path.relative(
-            docsPath,
-            path.join(rulePath, `${rule}.js`)
-          ).replace(/\\/g,'/')})\n\n`;
+            let hasSuggestions = "";
+            if (suggestions === true) {
+              hasSuggestions = "💡";
+            }
 
-          if (Object.keys(ruleDict).includes(category)) {
-            ruleDict[category].push({
+            const ruleDictEntry = {
               name: rule,
               details,
               recommended: isRecommended,
-              fix: isFixable,
+              fixable: isFixable,
+              hasSuggestions,
+              construction: underConstruction,
+              messages,
               version: version,
-              contents: mdRuleContents,
-              sources: mdRuleSources,
-            });
-          } else {
-            ruleDict[category] = [
-              {
-                name: rule,
-                details,
-                recommended: isRecommended,
-                fix: isFixable,
-                version: version,
-                contents: mdRuleContents,
-                sources: mdRuleSources,
-              },
-            ];
+            };
+            mdRule = module.exports.getRuleExamples(ruleTestPath, testPath, ruleDictEntry);
+            mdRuleContents = "";
+            if (!release && underConstruction) {
+              mdRuleContents += `## ${rule}\n<span class='shifted'>${underConstruction}&nbsp;&nbsp;<span class='label'>${category}</span></span>\n\n`;
+            } else {
+              mdRuleContents += `## ${rule}\n<span class='shifted label'>${category}</span>\n\n`;
+            }
+            mdRuleContents += `### Rule Details\n${details}\n\n`;
+            if (mdRule) {
+              mdRuleContents += `### Examples\n${mdRule}\n\n`;
+            }
+            mdRuleContents += `### Version\nThis rule was introduced in \`@sap/eslint-plugin-cds ${version}\`.\n\n`;
+            mdRuleSources = `### Resources\n[Rule & Documentation source](${path
+              .relative(docsPath, path.join(rulePath, `${rule}.js`))
+              .replace(/\\/g, "/")})\n\n`;
+
+            ruleDictEntry.contents = mdRuleContents;
+            ruleDictEntry.sources = mdRuleSources;
+            if (Object.keys(ruleDict).includes(category)) {
+              ruleDict[category].push(ruleDictEntry);
+            } else {
+              ruleDict[category] = [
+                {
+                  name: rule,
+                  details,
+                  recommended: isRecommended,
+                  fixable: isFixable,
+                  hasSuggestions,
+                  version: version,
+                  contents: mdRuleContents,
+                  sources: mdRuleSources,
+                  construction: underConstruction
+                },
+              ];
+            }
           }
         }
       }
     });
+    return ruleDict;
+  },
 
-    module.exports.genDocFiles(ruleDict, docsPath);
-    if (release) {
-      module.exports.genDocFiles(ruleDict, docsPath, release);
+  getRuleExamples: function (ruleTestPath, testPath, ruleDictEntry) {
+    // Get rule valid/invalid tests
+    let mdRule = "";
+    if (fs.existsSync(ruleTestPath)) {
+      const ruleTest = fs.readFileSync(ruleTestPath, "utf8");
+      const filename = module.exports.getKeyFromTest(
+        ruleTest,
+        "filename"
+      );
+      let errorsString = module.exports.getKeyFromTest(
+        ruleTest,
+        "errors"
+      );
+      const re = /(\S+):/gm;
+      errorsString = errorsString
+        .replace(re, `"$&`)
+        .replace(/:/gm, '":')
+        .replace(/`/gm, '"');
+      const errors = JSONC.parse(`{${errorsString}}`).errors;
+      const valid = fs.readFileSync(
+        path.join(testPath, ruleDictEntry.name, "valid", filename),
+        "utf8"
+      );
+      let invalid = fs.readFileSync(
+        path.join(testPath, ruleDictEntry.name, "invalid", filename),
+        "utf8"
+      );
+      const insertAt = (str, sub, pos) =>
+        `${str.slice(0, pos)}${sub}${str.slice(pos)}`;
+      let errorsSorted = []
+      errors.forEach((err) => {
+        if (errorsSorted.length === 0) {
+          errorsSorted = [err];
+        } else {
+          const errLast = errorsSorted[errorsSorted.length - 1];
+          if (err.line > errLast.line) {
+            errorsSorted.push(err)
+          } else if (err.line < errLast.line) {
+            errorsSorted.unshift(err);
+          } else {
+            if (err.column > errLast.column) {
+              errorsSorted.push(err)
+            } else if (err.line < errLast.line) {
+              errorsSorted.unshift(err)
+            } else {
+              errorsSorted.push(err)
+            }
+          }
+        }
+      })
+      errorsSorted.reverse().forEach((err, i) => {
+        if (err.messageId) {
+          let msg = ruleDictEntry.messages[err.messageId];
+          let data;
+          if (errorsSorted[i].suggestions && errorsSorted[i].suggestions[0]) {
+            data = errorsSorted[i].suggestions[0].data;
+          }
+          if (data) {
+            Object.keys(data).forEach((d) => {
+              msg = msg.replace(`{{${d}}}`, data[d]);
+            })
+          }
+          err.message = msg;
+        }
+        const msg = err.message.replace(/"/gm, "`");
+        if (err.line) {
+          const code = invalid.split("\n");
+          code[err.line - 1] = insertAt(
+            code[err.line - 1],
+            "</span>",
+            err.endColumn - 1
+          );
+          code[err.line - 1] = insertAt(
+            code[err.line - 1],
+            `<span style="display:inline-block; position:relative; border-bottom:2pt dotted red" title="${msg}">`,
+            err.column - 1
+          );
+          invalid = code.join("\n");
+        }
+      });
+
+      mdRule +=
+        `<span>✔️&nbsp;&nbsp; Example of ` +
+        `<span style="color:green">correct</span> ` +
+        `code for this rule:</span>\n\n<pre><code>\n${valid}\n</code></pre>\n\n`;
+      mdRule +=
+        `<span>❌&nbsp;&nbsp; Example of ` +
+        `<span style="color:red">incorrect</span> ` +
+        `code for this rule:</span>\n\n<pre><code>\n${invalid}\n</code></pre>`;
     }
+    return mdRule;
   },
 
-  getRules: function (dirname) {
+  /**
+   * Gets all relevant rules information (dictionary of rules contents, lists
+   * of 'env' and 'model' rules) for the rules directory provided
+   * - Default categories is 'model'
+   * @param {string} dirname
+   * @returns rules information
+   */
+  getRules(dirname) {
     const rules = {};
+    const listEnvRules = [];
+    const listModelRules = [];
     fs.readdirSync(dirname).forEach((file) => {
       if (path.extname(file) === ".js" && file !== "index.js") {
-        rules[file.replace(".js", "")] = require(path.join(dirname, file));
+        const rulename = file.replace(".js", "");
+        let rule = require(path.join(dirname, file));
+        if (!rule.meta) {
+          return;
+        }
+        rule = module.exports.applyRuleDefaults(rule);
+        rules[rulename] = rule;
+        const category =
+          rules[rulename].meta.docs.category || categories["model"];
+        if (
+          !listEnvRules.includes(rulename) &&
+          category === categories["env"]
+        ) {
+          listEnvRules.push(rulename);
+        }
+        if (
+          !listModelRules.includes(rulename) &&
+          category === categories["model"]
+        ) {
+          listModelRules.push(rulename);
+        }
       }
     });
-    return rules;
+    const listRules = listEnvRules.concat(listModelRules);
+    return { rules, listRules, listEnvRules, listModelRules };
   },
 
-  // REVISIT: The two methods below...
-  // 1. Read all rule implementations .js sources and scan them for meta data -> why not using these files' module exports?
-  // 2. They do so twice per file -> once for getEnvRules, once for getModelRules
-  // 3. Both are even invoked twice by `cds lint` -> once before `eslint` is spawned, once after
-
-  getEnvRules: function (dirname) {
-    const envRules = [];
-    fs.readdirSync(dirname).forEach((file) => {
-      if (path.extname(file) === ".js" && file !== "index.js") {
-        const rulePath = path.join(dirname, file);
-        const ruleMeta = fs.readFileSync(rulePath, "utf8");
-        const category = module.exports.getKeyFromMeta(ruleMeta, "category");
-        if (category === "Environment") {
-          envRules.push(file.replace(".js", ""));
-        }
+  /**
+   * Sets defaults for rule meta data for missing required
+   * propeties:
+   * - Rule is of type "problem"
+   * - Rule is in model category
+   * - Rule severity is "error"
+   * @param {*} rule
+   * @returns
+   */
+  applyRuleDefaults(rule) {
+    let ruleSanitized;
+    if (rule.meta) {
+      ruleSanitized = { ...rule };
+      if (!rule.meta.type) {
+        ruleSanitized.meta.type = "problem";
       }
-    });
-    return envRules;
+      if (rule.meta.docs && !rule.meta.docs.category) {
+        ruleSanitized.meta.docs.category = categories["model"];
+      }
+      if (rule.meta.docs.recommended && !rule.meta.severity) {
+        ruleSanitized.meta.severity = "error";
+      }
+    }
+    return ruleSanitized;
   },
 
-  getModelRules: function (dirname) {
-    const modelRules = [];
-    fs.readdirSync(dirname).forEach((file) => {
-      if (path.extname(file) === ".js" && file !== "index.js") {
-        const rulePath = path.join(dirname, file);
-        const ruleMeta = fs.readFileSync(rulePath, "utf8");
-        const category = module.exports.getKeyFromMeta(ruleMeta, "category");
-        if (category === CONSTANTS.categories.model) {
-          modelRules.push(file.replace(".js", ""));
-        }
+  populateRules: function (context, customRulesDir) {
+    const configPath = Cache.get("configpath") || "";
+    // Allow for custom rules
+    if (configPath) {
+      let customRulesPath = path.join(
+        Cache.get("configpath"),
+        customRulesDir,
+        "rules"
+      );
+      let customRulesInfo;
+      if (fs.existsSync(customRulesPath)) {
+        customRulesInfo = module.exports.getRules(customRulesPath);
+        Cache.set("rulesInfo", {
+          listEnvRules: context.listEnvRules.concat(
+            customRulesInfo.listEnvRules
+          ),
+          listModelRules: context.listModelRules.concat(
+            customRulesInfo.listModelRules
+          ),
+          listRules: context.listRules.concat(customRulesInfo.listRules),
+        });
       }
-    });
-    return modelRules;
+    }
   },
 };