@sap/eslint-plugin-cds 3.0.5 → 3.1.1

package/lib/utils/genDocs.js

@@ -1,346 +0,0 @@
-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')
-const LOG = process.env.SILENT ? undefined : constants.log
-
-/**
- * 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) {
-      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) {
-      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)
-  }
-  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 = ''
-
-  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) {
-    LOG?.(`Failed to connect to ${registry} - check your connection and try again.`)
-    exit(0)
-  }
-  const version = JSON.parse(result).version
-  if (!version) {
-    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) {
-        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 = '🚧'
-          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
-}