@sap/eslint-plugin-cds 2.4.1 → 2.6.0

package/lib/utils/genDocs.js

@@ -0,0 +1,345 @@
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const semver = require('semver')
+const cp = require('child_process')
+
+const cds = require('@sap/cds')
+const { mkdirp } = cds.utils
+
+const Cache = require('./Cache')
+const IS_WIN = os.platform() === 'win32'
+
+const { exit } = require('process')
+
+const constants = require('../constants')
+
+/**
+ * Generates custom rules documentation (markdown files)
+ * for user according to contents of:
+ * - Rule files
+ * - Test files (with valid/invalid/fixed examples)
+ */
+module.exports = async (projectPath, customRulesDir, registry, prepareRelease = false) => {
+  let docsPath, rulePath, testPath, release
+
+  Cache.set('testerCases', true)
+
+  if (!projectPath) {
+    docsPath = path.join(__dirname, '../../docs')
+    rulePath = path.join(__dirname, '../rules')
+    testPath = path.join(__dirname, '../../tests/lib/rules')
+    release = JSON.parse(fs.readFileSync(path.join(__dirname, '../../package.json')).toString()).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')).toString()).version
+      : getPackageVersion(registry)
+    if (versionInternal) {
+      console.log(`Updating internal rules from v>=${versionInternal}:\n${registry}\n`)
+      const rulesInternal = getRules(docsPath, rulePath, testPath, versionInternal)
+      genDocFiles(rulesInternal, 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')).toString()).version
+      : getPackageVersion(npmRegistry)
+    if (versionExternal) {
+      console.log(`Updating external rules from v>=${versionExternal}:\n${npmRegistry}\n`)
+      const rulesExternal = getRules(docsPath, rulePath, testPath, versionExternal, release)
+      genDocFiles(rulesExternal, docsPath, release)
+    }
+  } else {
+    // Get "custom" rules
+    const rules = getRules(docsPath, rulePath, testPath)
+    genDocFiles(rules, docsPath)
+  }
+  console.log('Done!')
+}
+
+/**
+ * Generates markdown table of all rules with their respective properties based on input rules
+ * @param rules array of rules with mandatory name, details properties
+ * @param release
+ * @returns markdown table of all rules
+ */
+function genMdRules (rules, release = false) {
+  let mdRulesTable = ''
+  if (rules.length > 0) {
+    const emojiRecommended = '✔️'
+    const emojiFixable = '🔧'
+    const emojiSuggestions = '💡'
+    const emojiConstruction = '🚧'
+    let mdRulesHeader = 'Rules in ESLint are grouped by type to help you understand their purpose. Each rule has emojis denoting:\n\n'
+    mdRulesHeader += `${emojiRecommended} if the plugin's "recommended" configuration enables the rule\n\n`
+    mdRulesHeader += `${emojiFixable} if problems reported by the rule are automatically fixable (\`--fix\`)\n\n`
+    mdRulesHeader += `${emojiSuggestions}  if problems reported by the rule are manually fixable (editor)\n\n`
+    if (!release) {
+      mdRulesHeader += `${emojiConstruction} if rule exists in plugin (main branch) but is not yet released (artifactory)\n\n`
+      mdRulesHeader += '|   |   |   |   |  |  |  |\n'
+      mdRulesHeader += '|:-:|:-:|:-:|:-:|-:|:-|:-|\n'
+    } else {
+      mdRulesHeader += '|   |   |   |   |  |  |  |\n'
+      mdRulesHeader += '|:-:|:-:|:-:|:-:|-:|:-|:-|\n'
+    }
+    let mdRules = ''
+    rules.forEach((rule) => {
+      if (rule.name && rule.details) {
+        const isRecommended = rule.recommended ? emojiRecommended : ''
+        const isFixable = rule.fixable ? emojiFixable : ''
+        const hasSuggestions = rule.hasSuggestions ? emojiSuggestions : ''
+        const underConstruction = rule.construction ? emojiConstruction : ''
+        mdRules += release
+          ? `| ${isRecommended} | ${isFixable} | ${hasSuggestions} | |   | [${rule.name}](Rules-released.md#${rule.name}) | ${rule.details}|\n`
+          : `| ${isRecommended} | ${isFixable} | ${hasSuggestions} | ${underConstruction} |   | [${rule.name}](Rules.md#${rule.name}) | ${rule.details}|\n`
+      }
+    })
+    mdRulesTable = mdRules ? `${mdRulesHeader}${mdRules}\n` : ''
+  }
+  return mdRulesTable
+}
+
+/**
+    * 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 rules
+    * @param docsPath
+    * @param release
+    */
+function genDocFiles (rules, 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 header = '# @sap/eslint-plugin-cds [latest]\n\n'
+  const mdRuleList = genMdRules(rules, release)
+
+  // Get rule details
+  let mdRules = ''
+  /* eslint-disable-next-line no-unused-vars */
+  rules.forEach(rule => {
+    mdRules += `${rule.contents}\n\n${rule.sources}\n\n---\n\n`
+  })
+
+  if (mdRuleListCur !== mdRuleList || mdRulesCur !== mdRules) {
+    fs.writeFileSync(ruleDocsPath, header + mdRules, 'utf8')
+    fs.writeFileSync(ruleListDocsPath, header + mdRuleList, 'utf8')
+  }
+}
+
+function getPackageVersion (registry) {
+  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.log(`Failed to connect to ${registry} - check your connection and try again.`)
+    exit(0)
+  }
+  const version = JSON.parse(result).version
+  if (!version) {
+    console.log(`Failed to get latest plugin version from ${registry} - check your connection and try again.`)
+    exit(0)
+  }
+  return version
+}
+
+function getRules (docsPath, rulePath, testPath, versionRequired = '0.0.0', release = false) {
+  let mdRule, mdRuleSources, mdRuleContents
+  const rules = []
+  const ruleVersionsPath = path.join(docsPath, '_data', 'rule_versions.json')
+  const ruleVersions = require(ruleVersionsPath)
+  let fileNumber = 0
+  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')
+      fileNumber++
+
+      // Get rule meta information
+      const ruleMeta = require(path.join(rulePath, file)).meta
+      let version = ruleVersions.added[rule]
+      if (!version) {
+        version = JSON.parse(fs.readFileSync(path.join(__dirname, '../../package.json')).toString()).version
+        ruleVersions.added[rule] = version
+        fs.writeFileSync(ruleVersionsPath, JSON.stringify(ruleVersions, null, 4), 'utf8')
+      }
+      if ((release && semver.satisfies(version, `<=${versionRequired}`)) || !release) {
+        console.log(`${fileNumber}> preparing docs for ${ruleTestPath}`)
+
+        const details = ruleMeta.docs.description
+        const flavor = ruleMeta.model ? ruleMeta.model : constants.DEFAULT_RULE_FLAVOR
+        const category = (flavor === 'none') ? 'Environment' : 'Model Validation'
+        const fixable = ruleMeta.fixable
+        const messages = ruleMeta.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 rulesEntry = {
+          name: rule,
+          details,
+          recommended: isRecommended,
+          fixable: isFixable,
+          hasSuggestions,
+          construction: underConstruction,
+          messages,
+          version
+        }
+        try {
+          mdRule = getRuleExamples(rule, ruleTestPath, testPath, rulesEntry)
+        } catch (err) {
+          // Just continue
+        }
+        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`
+
+        rulesEntry.contents = mdRuleContents
+        rulesEntry.sources = mdRuleSources
+        rules.push(rulesEntry)
+      }
+    }
+    return undefined
+  })
+  return rules
+}
+
+function getRuleExamples (rule, ruleTestPath, testPath, ruleDictEntry) {
+  // Get rule valid/invalid tests
+  let mdRule = ''
+  if (fs.existsSync(ruleTestPath)) {
+    require(`${ruleTestPath}`)
+    const testerCases = Cache.get(`testerCases:${rule}`)
+    const isEnvRule = testerCases.valid[0].filename === '<text>'
+    const valid = !isEnvRule ? fs.readFileSync(testerCases.valid[0].filename, 'utf8') : JSON.stringify(testerCases.valid[0].options[0].environment, null, 4)
+    const invalid = !isEnvRule ? fs.readFileSync(testerCases.invalid[0].filename, 'utf8') : JSON.stringify(testerCases.invalid[0].options[0].environment, null, 4)
+    let validString = ''
+    let invalidString = ''
+    if (!isEnvRule) {
+      const errors = testerCases.invalid[0].errors
+      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 {
+              if (err.messageId) {
+                errorsSorted[errorsSorted.length - 1].messageId += '\n' + err.messageId
+              }
+              if (err.message) {
+                errorsSorted[errorsSorted.length - 1].message += '\n' + err.message
+              }
+            }
+          }
+        }
+      })
+      const code = invalid.split('\n')
+      errorsSorted.forEach((err, i) => {
+        if (err.messageId && ruleDictEntry.messages) {
+          let msg = ruleDictEntry.messages[err.messageId]
+          let data
+          if (errorsSorted[i].suggestions && errorsSorted[i].suggestions[0]) {
+            data = errorsSorted[i].suggestions[0].data
+          }
+          if (data && msg) {
+            Object.keys(data).forEach((d) => {
+              msg = msg.replace(`{{${d}}}`, data[d])
+            })
+          }
+          err.message = msg
+        }
+        const msg = err.message && err.message.includes && err.message.includes('"') ? err.message.replace(/"/gm, '`') : err.message
+        if (err.line) {
+          const stringStart = errorsSorted[i - 1] ? errorsSorted[i - 1].line : 0
+          invalidString += code.slice(stringStart, err.line - 1).join('\n')
+          const errorString = err.line === err.endLine ? code[err.line - 1] : code.slice(err.line - 1, err.endLine - 1).join('\n')
+          const replacedErrorLine = errorString.substring(0, err.column - 1) +
+            `<span style="display:inline-block; position:relative; color:red; border-bottom:2pt dotted red" title="${msg}"><b><i>` +
+            errorString.substring(err.column - 1, err.endColumn - 1) +
+            '</i></b></span>' + errorString.substring(err.endColumn - 1)
+          invalidString += '\n' + replacedErrorLine
+          const stringEnd = errorsSorted[i + 1] ? code.slice(err.line, errorsSorted[i + 1].line - 1).join('\n') : code.slice(err.line).join('\n')
+          invalidString += errorsSorted[i + 1] ? stringEnd : '\n' + stringEnd
+        }
+      })
+    } else {
+      invalidString = invalid
+    }
+    validString = valid
+
+    mdRule +=
+      '<span>✔️&nbsp;&nbsp; Example of ' +
+      '<span style="color:green">correct</span> ' +
+      `code for this rule:</span>\n\n<pre><code>${validString.trim()}</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>${invalidString.trim()}</code></pre>`
+  }
+  return mdRule
+}

package/lib/utils/getConfigPath.js

@@ -0,0 +1,33 @@
+/**
+ * Searches for ESLint config file types (in order or precedence)
+ * and returns corresponding directory (usually project's root dir)
+ * https://eslint.org/docs/user-guide/configuring#configuration-file-formats
+ * @param {string} currentDir start here and search until root dir
+ * @returns {string} dir containing ESLint config file (empty if not exists)
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+module.exports = (currentDir = '.') => {
+  const configFiles = [
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.yaml',
+    '.eslintrc.yml',
+    '.eslintrc.json',
+    '.eslintrc',
+    'package.json'
+  ]
+  let configDir = path.resolve(currentDir)
+  while (configDir !== path.resolve(configDir, '..')) {
+    for (const configFile of configFiles) {
+      const configPath = path.join(configDir, configFile)
+      if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
+        return configPath
+      }
+    }
+    configDir = path.join(configDir, '..')
+  }
+  return ''
+}

package/lib/utils/getConfiguredFileTypes.js

@@ -0,0 +1,10 @@
+const { FILES } = require('../constants')
+
+/**
+ * Returns an array of allowed file extensions
+ * the plugin can parse of the form "*.ext"
+ * @returns { ConfigOverrideFiles } Array of file extensions
+ */
+module.exports = () => {
+  return FILES
+}

package/lib/utils/getFileExtensions.js

@@ -0,0 +1,8 @@
+const constants = require('../constants')
+
+/**
+ * Returns an array of allowed file extensions
+ * the plugin can parse of the form "*.ext"
+ * @returns { ConfigOverrideFiles } Array of file extensions
+ */
+module.exports = () => constants.FILES

package/lib/utils/getProjectRootPath.js

@@ -0,0 +1,25 @@
+/**
+ * Searches for directory containing cds roots
+ * @param {string} currentDir start here and search until root dir
+ * @returns {string} dir containing cds roots (empty if not exists)
+ */
+
+const path = require('path')
+const cds = require('@sap/cds')
+const Cache = require('./Cache')
+
+module.exports = (currentDir = '.') => {
+  let dir = path.resolve(currentDir)
+  while (dir !== path.resolve(dir, '..')) {
+    // @ts-ignore
+    cds.resolve.cache = {}
+    // @ts-ignore
+    const roots = cds.resolve('*', { root: dir })
+    if (roots && roots.length > 0) {
+      Cache.set(`roots:${dir}`, roots)
+      return dir
+    }
+    dir = path.join(dir, '..')
+  }
+  return ''
+}

package/lib/utils/isConfiguredFileType.js

@@ -0,0 +1,20 @@
+const { FILES, MODEL_FILES } = require('../constants')
+
+/**
+ * Checks whether the given filePath matches a regex `files`
+ * @param {string} filePath
+ * @returns boolean
+ */
+module.exports = (filePath, fileType) => {
+  const genRegex = (key) => new RegExp(`${key.map((file) => file.replace('*', '')).join('$|')}$`)
+  let isValid = false
+  switch (fileType) {
+    case 'MODEL_FILES':
+      isValid = genRegex(MODEL_FILES).test(filePath)
+      break
+    case 'FILES':
+      isValid = genRegex(FILES).test(filePath)
+      break
+  }
+  return isValid
+}