@sap/eslint-plugin-cds 2.0.4 → 2.2.1

package/lib/impl/utils/rules.js

@@ -0,0 +1,541 @@
+/**
+ * @typedef { import('eslint').Linter.ConfigOverride.files } ConfigOverrideFiles
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { mkdirp } = require("@sap/cds/lib/utils");
+const { getLastLine } = require("./model");
+
+const JSONC = require("./jsonc");
+const { categories, files, recommended } = require("../constants");
+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 {ConfigOverrideFiles} Array of file extensions
+   */
+  getFileExtensions: function () {
+    return files;
+  },
+
+  /**
+   * 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'
+   */
+  getDisabled: function (
+    rules,
+    listEnvRules,
+    listModelRules,
+    code,
+    sourcecode,
+    line
+  ) {
+    const listDisabled = [];
+    const rulesDisabled = rules.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];
+              if (disableRules) {
+                disableRules = disableRules
+                  .split(",")
+                  .map((rule) => rule.trim());
+              } else {
+                disableRules = listEnvRules
+                  .concat(listModelRules)
+                  .map((rule) => `@sap/cds/${rule}`);
+              }
+              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);
+            }
+            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";
+                }
+              });
+            }
+          }
+        }
+      }
+    }
+    return rulesDisabled;
+  },
+
+  /**
+   * Checks whether a given lint error/warning has been disabled
+   * by comments (as it should then be suppressed)
+   * @param entry lint report
+   * @param cdscontext cds context object
+   * @param rules all availabe rules
+   * @returns boolean
+   */
+
+  checkDisabled: function (
+    entry,
+    cdscontext,
+    rules,
+    listEnvRules,
+    listModelRules
+  ) {
+    let isDisabled = false;
+    if (entry.loc && entry.loc.start) {
+      const line = entry.loc.start.line;
+      if (cdscontext) {
+        const rulesDisabled = module.exports.getDisabled(
+          rules,
+          listEnvRules,
+          listModelRules,
+          cdscontext.code,
+          cdscontext.sourcecode,
+          line
+        );
+        let ruleID = cdscontext.ruleID;
+        if (!ruleID) {
+          ruleID = cdscontext.id;
+        }
+        if (
+          line &&
+          ruleID in rulesDisabled &&
+          rulesDisabled[ruleID] === "off"
+        ) {
+          isDisabled = true;
+        }
+      }
+    }
+    return isDisabled;
+  },
+
+  /**
+   * 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) {
+    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 "";
+    }
+  },
+
+  /**
+   * 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 {
+      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 version = "latest";
+    if (release) {
+      version = release;
+    }
+    let mdRules = `# @sap/eslint-plugin-cds [${version}]\n\n`;
+    if (table) {
+      mdRules += "|  |   |   |   |  |\n";
+      mdRules += "|:-:|:-:|:-:|:-:|:-|\n";
+      /* eslint-disable-next-line no-unused-vars */
+      Object.entries(ruleDict).forEach(([, rules]) => {
+        rules.forEach(function (rule) {
+          if (release) {
+            mdRules += `| ${rule.recommended} | ${rule.fixable} | ${rule.hasSuggestions} | [${rule.name}](Rules-released.md#rule-${rule.name}) | ${rule.details}|\n`;
+          } else {
+            mdRules += `| ${rule.recommended} | ${rule.fixable} | ${rule.hasSuggestions} | [${rule.name}](Rules.md#rule-${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) {
+    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");
+
+    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) {
+        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) {
+    let mdRule, mdRuleSources, mdRuleContents;
+    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`);
+    }
+
+    if (!fs.existsSync(docsPath)) {
+      await mkdirp(docsPath);
+    }
+    if (!fs.existsSync(rulePath)) {
+      await mkdirp(rulePath);
+    }
+    if (!fs.existsSync(testPath)) {
+      await mkdirp(testPath);
+    }
+
+    const 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), "");
+        if (rule !== "cds-compile-error") {
+          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 suggestions = module.exports.getKeyFromMeta(
+            ruleMeta,
+            "hasSuggestions"
+          );
+
+          let isFixable = "";
+          if (["code", "whitespace"].includes(fixable)) {
+            isFixable = "🔧";
+          }
+
+          let isRecommended = "";
+          if (Object.keys(recommended).includes(`@sap/cds/${rule}`)) {
+            isRecommended = "✔️";
+          }
+
+          let hasSuggestions = "";
+          if (suggestions === true) {
+            hasSuggestions = "💡";
+          }
+
+          const version = module.exports.getKeyFromMeta(ruleMeta, "version");
+
+          // 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) => {
+              if (err.messageId) {
+                err.message = err.messageId;
+              }
+              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");
+              }
+            });
+
+            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>`;
+          }
+
+          mdRuleContents = `## ${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`;
+
+          if (Object.keys(ruleDict).includes(category)) {
+            ruleDict[category].push({
+              name: rule,
+              details,
+              recommended: isRecommended,
+              fixable: isFixable,
+              hasSuggestions,
+              version: version,
+              contents: mdRuleContents,
+              sources: mdRuleSources,
+            });
+          } else {
+            ruleDict[category] = [
+              {
+                name: rule,
+                details,
+                recommended: isRecommended,
+                fixable: isFixable,
+                hasSuggestions,
+                version: version,
+                contents: mdRuleContents,
+                sources: mdRuleSources,
+              },
+            ];
+          }
+        }
+      }
+    });
+
+    module.exports.genDocFiles(ruleDict, docsPath);
+    if (release) {
+      module.exports.genDocFiles(ruleDict, docsPath, release);
+    }
+  },
+
+  /**
+   * 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") {
+        const rulename = file.replace(".js", "");
+        const ruleID = `${rulename}`;
+        rules[ruleID] = require(path.join(dirname, file));
+        const category =
+          rules[ruleID].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);
+        }
+      }
+    });
+    const listRules = listEnvRules.concat(listModelRules);
+    return { rules, listRules, listEnvRules, listModelRules };
+  },
+};

package/lib/impl/utils/validate.js

@@ -0,0 +1,56 @@
+/**
+ * @typedef { import("eslint").Rule.RuleContext.options } ContextOptions
+ */
+
+module.exports = {
+  /**
+   * Checks whether the rule name is valid, as it must be
+   * contained in either the plugins rule set or the user's
+   * custom rules provided at runtime
+   * @param context
+   * @param pluginRules
+   * @param customRules
+   * @returns
+   */
+  isValidRule: function (context, rules) {
+    if (rules.includes(context.ruleID.replace("@sap/cds/", ""))) {
+      return true;
+    }
+    return false;
+  },
+
+  /**
+   * Checks whether the compiled cds model is eligible
+   * for performing the plugin's rule checks
+   * @param cds cds object
+   * @param ruleID rule name
+   * @returns
+   */
+  isValidModel: function (context) {
+    const { cds, ruleID } = context;
+    if (
+      cds &&
+      cds.model &&
+      !cds.model.err &&
+      !(
+        ruleID === "@sap/cds/cds-compile-error" ||
+        ruleID === "cds-compile-error"
+      )
+    ) {
+      return true;
+    }
+    return false;
+  },
+
+  /**
+   * Checks whether the cds environment is passed
+   * @param {ContextOptions} options
+   * @returns
+   */
+  isValidEnv: function (options) {
+    if (options[0] && options[0].environment) {
+      return true;
+    }
+    return false;
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sap/eslint-plugin-cds",
-  "version": "2.0.4",
+  "version": "2.2.1",
   "description": "ESLint plugin including recommended SAP Cloud Application Programming model and environment rules",
   "homepage": "https://cap.cloud.sap/",
   "keywords": [
@@ -14,7 +14,7 @@
   "license": "See LICENSE file",
   "main": "lib/impl/index.js",
   "files": [
-    "lib/**/*.js",
+    "lib/",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -24,6 +24,6 @@
     "semver": "^7.3.4"
   },
   "peerDependencies": {
-    "eslint": ">=6"
+    "eslint": ">=7"
   }
 }