@sap/eslint-plugin-cds 2.3.2 → 2.3.5

package/lib/utils/rules.js

@@ -0,0 +1,979 @@
+/**
+ * @typedef { import('eslint').Linter.ConfigOverride.files } ConfigOverrideFiles
+ */
+
+const fs = require("fs");
+const os = require("os");
+const cp = require("child_process");
+const cds = require("@sap/cds");
+
+const semver = require("semver");
+const path = require("path");
+const { mkdirp } = require("@sap/cds/lib/utils");
+const { SourceCode } = require("eslint");
+
+const { hasDebugFlag, isValidFile, isVSCodeEditor } = require("./helpers");
+const { DEFAULT_RULE_CATEGORY, DEFAULT_RULE_SEVERITY, DEFAULT_RULE_TYPE } = require("../constants");
+
+const {
+  Cache,
+  getAST,
+  getLastLine,
+  initRootModel,
+  updateModel,
+  compileModelFromFile,
+  isNewConfigPath,
+  isFileInModel,
+  hasFileChanged,
+  getLocation,
+  getRange,
+  loadConfigPath,
+} = require("./model");
+
+const { isValidModel } = require("./validate");
+const { exit } = require("process");
+
+const JSONC = require("./jsonc");
+const IS_WIN = os.platform() === "win32";
+const REGEX_COMMENT_START = "(/\\*|(.+)?//)(\\s?)+eslint-";
+const REGEX_COMMENTS = `${REGEX_COMMENT_START}(enable|disable)(-next)?(-line)?(.+)?`;
+
+function doReport(cdscontext, reportDescriptor, d) {
+  const retouchLocations = (descriptor) => {
+    if (d) {
+      descriptor.loc = descriptor.loc || cdscontext.cds.getLocation(d.name, d);
+      descriptor.file = descriptor.file || (d.$location ? d.$location.file : "unknown.cds");
+    }
+  };
+
+  switch (typeof reportDescriptor) {
+    case "string":
+      reportDescriptor = { message: reportDescriptor };
+      retouchLocations(reportDescriptor);
+      cdscontext.report(reportDescriptor);
+      break;
+    case "object":
+      if (!Array.isArray(reportDescriptor)) {
+        retouchLocations(reportDescriptor);
+        cdscontext.report(reportDescriptor);
+      } else {
+        reportDescriptor.forEach((x) => {
+          if (typeof x === "string") {
+            x = { message: x };
+          }
+          retouchLocations(x);
+          cdscontext.report(x);
+        });
+      }
+      break;
+  }
+}
+
+function reportCompilationErr(meta, node, cdscontext, err) {
+  const lint = { err: true };
+  const name = err.constructor.name;
+  if (err.messages) {
+    lint.message = `${name}: ${err.message}`;
+    // const text = err.message.split(/CDS Compilation failed\s+/, "");
+    err.messages.forEach((msg) => {
+      if (msg.severity === "Error") {
+        meta.severity = 2;
+        lint.file = msg.location.file;
+        lint.message = `${name}: ${msg}`;
+        lint.filePath = cdscontext.filePath;
+        return {
+          meta,
+          create: cdscontext.report(lint),
+        };
+      }
+    });
+  }
+}
+
+function reportErr(meta, node, cdscontext, err) {
+  const lint = { err: true };
+  lint.err = true;
+  if (hasDebugFlag() && !isVSCodeEditor()) {
+    lint.message = err.stack;
+    meta.severity = 2;
+    return {
+      meta,
+      create: cdscontext.report(lint),
+    };
+  }
+}
+
+/**
+ * Expands CDS context object with some CDS properties
+ * We also retrieve the file contents cached by the preprocessor
+ * @param {RuleContext} context
+ * @param {RuleNode} node
+ * @returns cdscontext
+ */
+function addCDSContext(context, node) {
+  const filePath = (context.filePath = context.getPhysicalFilename());
+  const configPath = !Cache.has("test") ? loadConfigPath(filePath) : path.dirname(filePath);
+  let sourcecode = context.getSourceCode();
+  const code = sourcecode.getText(node) || Cache.get(`file:${filePath}`);
+  if (code) {
+    sourcecode = new SourceCode(code, getAST(code));
+  }
+  const options = context.options;
+  const id = context.id;
+  return {
+    _context: context,
+    report: module.exports.reportProxy(context.report),
+    cds: module.exports.cdsProxy(cds, { code, filePath, configPath, id, options }),
+    id,
+    code,
+    sourcecode,
+    options,
+    filePath,
+    configPath,
+  };
+}
+
+/**
+ * Wrapper for ESLint's Rule creator:
+ * https://eslint.org/docs/developer-guide/working-with-rules
+ * - Must follow the ESLint prescribed convention for all rule exports
+ * - ESLint uses 'create' function to traverse its AST nodes
+ * - Since we do not work with an AST for cds models, a dummy 'Programm'
+ *   node is used as an entry point
+ * - For all ESLint rules, we have two entry points for additional checks:
+ *     1. Before ESLint's report via context.report()
+ *        (see getProxyReport())
+ * - More eslint-like API
+ * - More convenience re error reports
+ * @param {CDSRuleSpec} spec
+ * @returns {RuleModule}
+ */
+function createRule(spec) {
+  const { meta, create } = spec;
+
+  if (!meta.type) meta.type = DEFAULT_RULE_TYPE;
+  if (!meta.severity) meta.severity = DEFAULT_RULE_SEVERITY;
+  if (meta.docs && !meta.docs.category) meta.docs.category = DEFAULT_RULE_CATEGORY;
+
+  return {
+    meta,
+    create: (context) => ({
+      Program: function (node) {
+        const cdscontext = addCDSContext(context, node, meta);
+        const lintWithCDSLinter = isValidFile(cdscontext.filePath, 'FILES');
+
+        if (lintWithCDSLinter || Cache.has("test") ) {
+          try {
+            const { report, ...ruleDescriptors } = cdscontext;
+            const handlers = create({ ...ruleDescriptors, report: (r) => report(r) });
+
+            // Report descriptors with fake visitor 'all'
+            // Used for environment rules and rules which require another compiled model
+            // (i.e. sql or odata)
+            if (handlers.all) {
+              let reportDescriptor = handlers.all();
+              doReport(cdscontext, reportDescriptor);
+            } else {
+              // TODO: Use external address
+              // Report descriptors with visitors using using `any.is()`
+              // https://pages.github.tools.sap/cap/docs/node.js/cds-reflect
+              if (cdscontext.cds.model) {
+                cdscontext.cds.model.forall((d) =>
+                  Object.entries(handlers)
+                    .filter(([type, lazy]) => d.is(type))
+                    .forEach(([lazy, handler]) => doReport(cdscontext, handler(d), d))
+                );
+              }
+            }
+            if (Cache.has(`errRootModel`)) {
+              reportCompilationErr(meta, node, cdscontext, Cache.get('errRootModel'));
+            }
+          } catch (err) {
+            // Report errors in ESLint style
+            if (err.messages) {
+              // Always show model compile errors
+              reportCompilationErr(meta, node, cdscontext, err);
+            } else {
+              // Thrown errors are only shown on console with --debug
+              reportErr(meta, node, cdscontext, err);
+            }
+          }
+        }
+      },
+    }),
+  };
+}
+
+/**
+ * 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
+ */
+
+function isRuleDisabled(entry, cdscontext) {
+  let isDisabled = false;
+  if (entry.loc && entry.loc.start) {
+    const line = entry.loc.start.line;
+    if (cdscontext) {
+      const rulesDisabled = _getDisabled(cdscontext.code, cdscontext.sourcecode, line);
+      const id = cdscontext.id;
+      isDisabled = line && id in rulesDisabled && rulesDisabled[id] === "off";
+    }
+  }
+  return isDisabled;
+}
+
+/**
+ * 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
+ * @param code current code
+ * @param sourcecode source code object to get index from
+ * @param line current code line to analyze
+ * @returns rules dictionary with rules being either 'on' and 'off'
+ */
+function _getDisabled(code, sourcecode, line) {
+  const listDisabled = [];
+  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();
+          }
+          ["disable", "enable"].forEach((keyword) => {
+            const loc = sourcecode.getLocFromIndex(index);
+            const disableType = match.split(" ")[0];
+            let disableRules = match.split(`${disableType} `)[1];
+            disableRules = disableRules
+              ? disableRules.split(",").map((rule) => rule.trim())
+              : listEnvRules.concat(listModelRules).map((rule) => `@sap/cds/${rule}`);
+            let comment = {};
+            if ([`eslint-${keyword}`, `eslint-${keyword}-line`, `eslint-${keyword}-next-line`].includes(disableType)) {
+              comment = disableType.includes("-next-line")
+                ? {
+                    lineComment: loc.line,
+                    lineDisabled: loc.line + 1,
+                    rules: disableRules,
+                    type: keyword,
+                  }
+                : {
+                    lineComment: loc.line,
+                    lineDisabled: loc.line,
+                    rules: disableRules,
+                    type: keyword,
+                  };
+              if (!disableType.includes("-line")) {
+                comment.lineDisabled = "EOF";
+              }
+            }
+            listDisabled.push(comment);
+          });
+        }
+      });
+      for (const el of listDisabled.filter(
+        (d) => d.lineComment > line && (d.lineDisabled === "EOF" || d.lineDisabled === line)
+      )) {
+        if (el.lineDisabled === "EOF") {
+          el.lineDisabled = getLastLine(code);
+        }
+        if (el.rules) {
+          el.rules.forEach((rule) => {
+            if (el.type === "disable") {
+              rulesDisabled[rule] = "off";
+            } else if (el.type === "enable") {
+              rulesDisabled[rule] = "on";
+            }
+          });
+        }
+      }
+    }
+  }
+  return rulesDisabled;
+}
+
+module.exports = {
+  /**
+   * Gets value for a given key in allowed keys of ESLint's meta data
+   * @param {string} text meta object from rule
+   * @param {string} key key to get value for
+   * @returns Value for given key
+   */
+  getKeyFromMeta: function (text, key) {
+    const regexQuote = new RegExp(`${key}:[\\s]+[\\', \\\`, \\"]`, "gm");
+    const matchQuote = regexQuote.exec(text);
+    if (matchQuote) {
+      const quote = matchQuote[0].slice(-1);
+      const exprStart = `${key}:[\\s]+\\${quote}`;
+      const exprEnd = `(\\${quote},,?)`;
+      const regexKey = new RegExp(`${exprStart}[\\s\\S]*?${exprEnd}`, "gm");
+      const matchKey = regexKey.exec(text);
+      if (matchKey) {
+        const regexStart = new RegExp(`${exprStart}`, "gm");
+        const regexEnd = new RegExp(`${exprEnd}`, "gm");
+        return matchKey[0]
+          .replace(regexStart, "")
+          .replace(regexEnd, "")
+          .replace("fixable:", "")
+          .replace(/\\/gm, "")
+          .trim();
+      } else {
+        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;
+    let result;
+    try {
+      result = cp
+        .execSync(`npm show @sap/eslint-plugin-cds --@sap:registry=${registry} --json`, {
+          cwd: process.cwd(),
+          shell: IS_WIN,
+          stdio: "pipe",
+        })
+        .toString();
+    } catch (err) {
+      console.err(`Failed to connect to ${registry} - check your connection and try again.`);
+      exit(0);
+    }
+    version = JSON.parse(result)["version"];
+    if (!version) {
+      console.err(`Failed to get latest plugin version from ${registry} - check your connection and try again.`);
+      exit(0);
+    }
+    return version;
+  },
+
+  /**
+   * Gets value for a given key in allowed keys for input of runRuleTester api
+   * @param {string} text test input for ruleTester
+   * @param {string} key key to get value for
+   * @returns Value for given key
+   */
+  getKeyFromTest: function (text, key) {
+    let result = "";
+    if (["root", "rule", "filename", "parser"].includes(key)) {
+      const regexTestKey = new RegExp(`${key}:.*$`, "gm");
+      const matchTestKey = regexTestKey.exec(text);
+      if (matchTestKey) {
+        const quote = matchTestKey[0].replace(",", "").slice(-1);
+        const regexTestValue = new RegExp(`${quote}[\\s\\S]*?(\\${quote},?)`, "gm");
+        const matchValue = regexTestValue.exec(matchTestKey[0]);
+        if (matchValue) {
+          const regex = new RegExp(`${quote},`, "gm");
+          const regex2 = new RegExp(`${quote}`, "gm");
+          result = matchValue[0].replace(regex, "").replace(regex2, "");
+        }
+      }
+    } else if (key === "errors") {
+      const regexTestKey = new RegExp(`${key}:.*$(([\\s]+.+)+])?`, "gm");
+      const matchTestKey = regexTestKey.exec(text);
+      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`;
+    }
+    return result;
+  },
+
+  /**
+   * Generates overview table of all rules based on rule dictionary.
+   * @param ruleDict
+   * @param release
+   * @param table
+   * @returns Markdown table
+   */
+  genMdRules: function (ruleDict, release, table = true) {
+    let mdRules = `# @sap/eslint-plugin-cds [latest]\n\n`;
+    if (table) {
+      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 += release
+            ? `| ${rule.recommended} | ${rule.fixable} | ${rule.hasSuggestions} | |   | [${rule.name}](Rules-released.md#${rule.name}) | ${rule.details}|\n`
+            : `| ${rule.recommended} | ${rule.fixable} | ${rule.hasSuggestions} | ${rule.construction} |   | [${rule.name}](Rules.md#${rule.name}) | ${rule.details}|\n`;
+        });
+      });
+      mdRules += "\n";
+    }
+    return mdRules;
+  },
+
+  /**
+   * Generates markdown documentation files for:
+   * - Overview of all rules in form of markdown table (RuleList)
+   * - List of all rules details in form of markdown page (Rules)
+   * 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
+   */
+  genDocFiles: function (ruleDict, docsPath, release = false) {
+    let suffix = "";
+    if (release) {
+      suffix = "-released";
+    }
+    const ruleDocsPath = path.join(docsPath, `Rules${suffix}.md`);
+    const ruleListDocsPath = path.join(docsPath, `RuleList${suffix}.md`);
+
+    if (!fs.existsSync(ruleDocsPath)) {
+      fs.writeFileSync(ruleDocsPath, "", "utf8");
+    }
+    if (!fs.existsSync(ruleListDocsPath)) {
+      fs.writeFileSync(ruleListDocsPath, "", "utf8");
+    }
+    const mdRulesCur = fs.readFileSync(ruleDocsPath, "utf8");
+    const mdRuleListCur = fs.readFileSync(ruleListDocsPath, "utf8");
+
+    // Get rules table
+    const mdRuleList = module.exports.genMdRules(ruleDict, release, true);
+
+    // Get rule details
+    let mdRules = module.exports.genMdRules(ruleDict, release, false);
+    /* eslint-disable-next-line no-unused-vars */
+    Object.entries(ruleDict).forEach(([category, rules]) => {
+      rules.forEach(function (rule) {
+        mdRules += `${rule.contents}\n\n${rule.sources}\n\n---\n\n`;
+      });
+    });
+
+    if (mdRuleListCur !== mdRuleList || mdRulesCur !== mdRules) {
+      fs.writeFileSync(ruleDocsPath, mdRules, "utf8");
+      fs.writeFileSync(ruleListDocsPath, mdRuleList, "utf8");
+    }
+  },
+
+  /**
+   * Generates custom rules documentation (markdown files)
+   * for user according to contents of:
+   * - Rule files
+   * - Test files (with valid/invalid/fixed examples)
+   * @param {string} projectPath
+   * @param {string} customRulesDir
+   */
+  async genDocs(projectPath, customRulesDir, registry, prepareRelease = false) {
+    let docsPath, rulePath, testPath, release;
+
+    if (!projectPath) {
+      docsPath = path.join(__dirname, "../../docs");
+      rulePath = path.join(__dirname, "../rules");
+      testPath = path.join(__dirname, "../../test/rules");
+      release = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"))).version;
+    } else {
+      docsPath = path.join(projectPath, `${customRulesDir}/docs`);
+      rulePath = path.join(projectPath, `${customRulesDir}/rules`);
+      testPath = path.join(projectPath, `${customRulesDir}/tests`);
+      await Promise.all(
+        [docsPath, rulePath, testPath].filter((path) => !fs.existsSync(path)).map((path) => mkdirp(path))
+      );
+    }
+
+    if (registry) {
+      // Get rules (internal on artifactory)
+      const versionInternal = prepareRelease
+        ? JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"))).version
+        : module.exports.getPackageVersion(registry);
+      if (versionInternal) {
+        console.log(`Updating internal rules from v>=${versionInternal}:\n${registry}\n`);
+        const ruleDictInternal = module.exports.getRuleDict(docsPath, rulePath, testPath, versionInternal);
+        module.exports.genDocFiles(ruleDictInternal, docsPath);
+      }
+      // Get rules released (external on npm)
+      const npmRegistry = "https://registry.npmjs.org";
+      const versionExternal = prepareRelease
+        ? JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"))).version
+        : module.exports.getPackageVersion(npmRegistry);
+      if (versionExternal) {
+        console.log(`Updating external rules from v>=${versionExternal}:\n${npmRegistry}\n`);
+        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);
+    }
+    console.log("Done!");
+  },
+
+  getRuleDict: function (docsPath, rulePath, testPath, versionRequired = "0.0.0", release = false) {
+    let mdRule, mdRuleSources, mdRuleContents;
+    const ruleDict = {};
+    fs.readdirSync(rulePath).filter((file) => {
+      if (path.extname(file).toLowerCase() === ".js" && file !== "index.js") {
+        const rule = path.basename(file).replace(path.extname(file), "");
+        const ruleTestPath = path.join(testPath, rule, "rule.test.js");
+
+        // Get rule meta information
+        const ruleMeta = require(path.join(rulePath, file)).meta;
+        const version = ruleMeta.docs.version;
+
+        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;
+
+          let underConstruction = "";
+          if (!release && (version === "TBD" || semver.satisfies(version, `>${versionRequired}`))) {
+            underConstruction = "🚧";
+            console.log(`  > 🚧 Rule '${rule}' still under construction.\n`);
+          }
+
+          const isFixable = ["code", "whitespace"].includes(fixable) ? "🔧" : "";
+          const isRecommended = recommended === true ? "✔️" : "";
+          const hasSuggestions = suggestions === true ? "💡" : "";
+
+          const ruleDictEntry = {
+            name: rule,
+            details,
+            recommended: isRecommended,
+            fixable: isFixable,
+            hasSuggestions,
+            construction: underConstruction,
+            messages,
+            version: version,
+          };
+          mdRule = module.exports.getRuleExamples(ruleTestPath, testPath, ruleDictEntry);
+          mdRuleContents = "";
+
+          mdRuleContents +=
+            !release && underConstruction
+              ? `## ${rule}\n<span class='shifted'>${underConstruction}&nbsp;&nbsp;<span class='label'>${category}</span></span>\n\n`
+              : `## ${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;
+  },
+
+  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], "</i></b></span>", err.endColumn - 1);
+          code[err.line - 1] = insertAt(
+            code[err.line - 1],
+            `<span style="display:inline-block; position:relative; color:red; border-bottom:2pt dotted red" title="${msg}"><b><i>`,
+            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;
+  },
+
+  /**
+   * Gets all plugin rules and stores contents for later use in isRuleDisabled()
+   * @param {*} dirname rules dirname
+   * @param {*} rulename optional rule name (for single rule unit tests with RuleTester)
+   * @returns rule object with sources and rule lists
+   */
+  getRules: function (dirname, rulename) {
+    let rulesInfo;
+    if (Cache.has("rulesInfo")) {
+      rulesInfo = Cache.get("rulesInfo");
+    } else {
+      const rules = {};
+      const listEnvRules = [];
+      const listModelRules = [];
+
+      if (rulename) {
+        const file = `${rulename}.js`;
+
+        let rule = createRule(require(path.join(dirname, file)));
+        rules[rulename] = rule;
+
+        if (!listEnvRules.includes(rulename) && !isValidModel(file, "model")) {
+          listEnvRules.push(rulename);
+        }
+        if (!listModelRules.includes(rulename) && isValidModel(file, "model")) {
+          listModelRules.push(rulename);
+        }
+      } else {
+        fs.readdirSync(dirname).forEach((file) => {
+          if (path.extname(file) === ".js") {
+            const rulename = file.replace(".js", "");
+
+            let rule = createRule(require(path.join(dirname, file)));
+            rules[rulename] = rule;
+
+            if (!listEnvRules.includes(rulename) && !isValidModel(file, "model")) {
+              listEnvRules.push(rulename);
+            }
+            if (!listModelRules.includes(rulename) && isValidModel(file, "model")) {
+              listModelRules.push(rulename);
+            }
+          }
+        });
+      }
+      const listRules = listEnvRules.concat(listModelRules);
+
+      const recommended = Object.assign(
+        {},
+        ...Object.entries(rules)
+          .filter(([, v]) => v.meta.docs.recommended)
+          .map(([k, v]) => ({ [`@sap/cds/${k}`]: v.meta.severity }))
+      );
+
+      const all = Object.assign({}, ...Object.entries(rules).map(([k, v]) => ({ [`@sap/cds/${k}`]: v.meta.severity })));
+      rulesInfo = { sources: rules, all, recommended, listRules, listEnvRules, listModelRules };
+      Cache.set("rulesInfo", rulesInfo);
+    }
+    return rulesInfo;
+  },
+
+  // 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),
+  //       });
+  //     }
+  //   }
+  // },
+
+  /**
+   * Generates proxy for `@sap/cds` object which adds:
+   * - Extra properties (model, environment, etc.)
+   * - Option to cache function calls (apply)
+   * @param {cds} object
+   * @returns Proxy for cds
+   */
+  cdsProxy: function (cds, { code, filePath, configPath, id, options }) {
+    const handler = {
+      get(target, prop, receiver) {
+        let value;
+        switch (prop) {
+          case "model":
+            value = module.exports.getModel(code, filePath, configPath, id, cds);
+            break;
+          case "environment":
+            value = module.exports.getEnvironment(options);
+            break;
+          case "getLocation":
+            value = getLocation;
+            break;
+          case "getRange":
+            value = getRange;
+            break;
+          default:
+            break;
+        }
+        if (value) {
+          return value;
+        } else {
+          value = Reflect.get(target, prop, receiver);
+          if (value && typeof value == "object") {
+            value = new Proxy(value, handler);
+          }
+          return value;
+        }
+      },
+      apply(target, thisArg, argumentsList) {
+        // NOTE: Possible to add caching for expensive function calls
+        // here as the rule set grows further
+        const result = Reflect.apply(target, this, argumentsList);
+        return result;
+      },
+    };
+    return new Proxy(cds, handler);
+  },
+  /**
+   * Generates proxy for ESLint's context object which adds caching
+   * @param {CDSRuleReport} ESLint's context object
+   * @returns {Rule.ReportDescriptor}
+   */
+  reportProxy: function (ruleReport) {
+    const handler = {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value !== "object") {
+          return value;
+        }
+        if (value) {
+          return new Proxy(value, handler);
+        }
+        return {
+          err: `Property ${prop} prop does not exist on object ${ruleReport}!`,
+        };
+      },
+      apply(target, thisArg, argumentsList) {
+        let report = false;
+        if (argumentsList.length > 0) {
+          argumentsList.forEach((lint) => {
+            if (lint) {
+              // Do not consider disabled content
+              if (!isRuleDisabled(lint, thisArg)) {
+                const isModelLint = lint.file && isValidFile(lint.file, "MODEL_FILES") && !lint.err;
+                if (isModelLint && module.exports.isDedicatedFile(lint, thisArg)) {
+                  if (isVSCodeEditor()) {
+                    report = true;
+                  } else {
+                    if (module.exports.isReportUnique(lint, "modelReports")) {
+                      report = true;
+                    }
+                  }
+                }
+                if (!lint.loc) {
+                  lint.loc = module.exports.addDefaultLoc();
+                }
+                if (
+                  !isModelLint &&
+                  !lint.err &&
+                  module.exports.isReportUnique(lint, "envReports", thisArg.configPath)
+                ) {
+                  report = true;
+                }
+                if (lint.err && (lint.file || module.exports.isReportUnique(lint, "errReports", thisArg.configPath))) {
+                  report = true;
+                }
+                if (report) {
+                  return thisArg._context.report(lint);
+                }
+              }
+            }
+          });
+        }
+      },
+    };
+    return new Proxy(ruleReport, handler);
+  },
+
+  resolveFilePath: (file) => (path.isAbsolute(file) ? file : path.join(Cache.get("configpath"), file)),
+
+  isDedicatedFile: (lint, thisArg) =>
+    module.exports.resolveFilePath(lint.file) === thisArg.filePath || lint.file === "<stdin>.cds",
+
+  isReportUnique: function (lint, name, uniqueness) {
+    let report = false;
+    if (!uniqueness) {
+      uniqueness = JSON.stringify(lint);
+    }
+    if (!Cache.has(name) && uniqueness) {
+      const lintString = `${uniqueness}:${JSON.stringify(lint)}`;
+      Cache.set(name, [lintString]);
+      report = true;
+    } else {
+      if (uniqueness) {
+        const lintMessages = Cache.has(name) ? Cache.get(name) : [];
+        const lintString = `${uniqueness}:${JSON.stringify(lint)}`;
+        if (!lintMessages.includes(lintString)) {
+          lintMessages.push(lintString);
+          Cache.set(name, lintMessages);
+          report = true;
+        }
+      }
+    }
+    return report;
+  },
+
+  addDefaultLoc: () => ({
+    start: { line: 0, column: -1 },
+    end: { line: 0, column: -1 },
+  }),
+
+  getModel: function (code, filePath, configPath) {
+    let model;
+
+    if (Cache.has("test")) {
+      return Cache.get(`model:${configPath}`);
+    }
+
+    if (!Cache.has(`model:${configPath}`)) {
+      const isValidPluginFile = isValidFile(filePath, "FILES");
+
+      if (isValidPluginFile) {
+        model = initRootModel(configPath);
+        if (module.exports.isParkedModelFile(filePath, configPath)) {
+          return compileModelFromFile(code, filePath);
+        } else if (model) {
+          return model;
+        }
+      }
+    } else {
+      const isValidModelFile = isValidFile(filePath, "MODEL_FILES");
+
+      if (module.exports.isParkedModelFile(filePath, configPath)) {
+        return compileModelFromFile(code, filePath);
+      } else if (isValidModelFile) {
+        const hasRootChanged = isNewConfigPath(configPath);
+        const fileChanged = hasFileChanged(code, filePath, configPath);
+
+        if (hasRootChanged || fileChanged) {
+          if (hasRootChanged) {
+            Cache.remove("envReports");
+          }
+          Cache.remove("modelReports");
+          Cache.remove("errReports");
+          model = updateModel(code, filePath, configPath);
+        } else {
+          model = Cache.get(`model:${configPath}`);
+        }
+      } else {
+        model = Cache.get(`model:${configPath}`);
+      }
+      return model;
+    }
+  },
+
+  isParkedModelFile: (filePath, configPath) =>
+    isValidFile(filePath, "MODEL_FILES") && !isFileInModel(filePath, configPath),
+
+  getEnvironment: function (options) {
+    let environment;
+    if (options) {
+      const hasEnvTestCases = options && options[0] && options[0].environment;
+      if (hasEnvTestCases) {
+        environment = options[0].environment;
+      }
+    }
+    return environment;
+  },
+  createRule,
+};