eslint-formatter-gitlab 5.1.0 → 6.0.1

package/README.md

@@ -1,22 +1,26 @@
 # ESLint Formatter for GitLab
 
+[![gitlab pipeline](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/badges/main/pipeline.svg)](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/pipelines)
+[![code coverage](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/badges/main/coverage.svg)](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/pipelines)
+[![sponsors](https://img.shields.io/github/sponsors/remcohaszing)](https://github.com/sponsors/remcohaszing)
+[![npm version](https://img.shields.io/npm/v/eslint-formatter-gitlab)](https://www.npmjs.com/package/eslint-formatter-gitlab)
+[![npm downloads](https://img.shields.io/npm/dm/eslint-formatter-gitlab)](https://www.npmjs.com/package/eslint-formatter-gitlab)
+
+<img alt="" height="256" src="https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/avatar">
+
 Show ESLint results directly in the
-[GitLab code quality](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html)
-results.
+[GitLab code quality](https://docs.gitlab.com/ee/ci/testing/code_quality.html) results.
 
 ## Table of Contents
 
-- [Requirements](#requirements)
 - [Installation](#installation)
 - [Usage](#usage)
+  - [Programmatic usage](#programmatic-usage)
 - [Example](#example)
 - [Configuration](#configuration)
+- [Compatibility](#compatibility)
 - [License](#license)
 
-## Requirements
-
-This package requires at least Node.js 18 and ESLint 5.
-
 ## Installation
 
 Install `eslint` and `eslint-formatter-gitlab` using your package manager.
@@ -29,21 +33,35 @@ npm install --save-dev eslint eslint-formatter-gitlab
 
 Define a GitLab job to run `eslint`.
 
-_.gitlab-ci.yml_:
+`.gitlab-ci.yml`:
 
 ```yaml
 eslint:
-  image: node:20-alpine
+  image: node:22-alpine
   script:
     - npm ci
-    - npx eslint --format gitlab .
+    - npx eslint --format gitlab
   artifacts:
     reports:
       codequality: gl-codequality.json
 ```
 
 The formatter automatically detects a GitLab CI environment. It detects where to output the code
-quality report based on the GitLab configuration file.
+quality report based on the GitLab configuration file. It also prints ESLint issues to the GitLab
+job console with links.
+
+### Programmatic usage
+
+The formatter can be used programmatically using ESLint.
+
+```js
+import { ESLint } from 'eslint'
+
+const eslint = new ESLint()
+const formatter = await eslint.loadFormatter('gitlab')
+const results = await eslint.lintFiles([])
+const formatted = await formatter.format(results)
+```
 
 ## Example
 
@@ -55,8 +73,20 @@ An example of the results can be seen in
 
 ESLint formatters don’t take any configuration options. `eslint-formatter-gitlab` uses GitLab’s
 [predefined environment variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
-to configure the output. In addition, the environment variable `ESLINT_CODE_QUALITY_REPORT` is used
-to override the location to store the code quality report.
+to configure the output. The following predefined environment variables are used:
+
+- `CI_COMMIT_SHORT_SHA` to generate a link in the console output.
+- `CI_CONFIG_PATH` to determine the GitLab CI configuration file to use. (Default: `.gitlab-ci.yml`)
+- `CI_JOB_NAME` to determine which job configuration to read the code quality report path from.
+- `CI_PROJECT_DIR` To determine relative paths. (Default: current working directory)
+- `CI_PROJECT_URL` to generate a link in the console output.
+
+In addition, the environment variable `ESLINT_CODE_QUALITY_REPORT` is used to override the location
+to store the code quality report.
+
+## Compatibility
+
+This package is compatible with Node.js 20 or greater and ESLint 9 or greater.
 
 ## License
 

package/lib/eslint-formatter-gitlab.js

@@ -0,0 +1,173 @@
+/**
+ * @import { ESLint } from 'eslint'
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, relative, resolve } from 'node:path'
+import { styleText } from 'node:util'
+
+import { toCodeClimate } from 'eslint-formatter-codeclimate'
+import yaml from 'yaml'
+
+/** @type {yaml.CollectionTag} */
+const reference = {
+  tag: '!reference',
+  collection: 'seq',
+  default: false,
+  resolve() {
+    // We only allow the syntax. We don’t actually resolve the reference.
+  }
+}
+
+/**
+ * @param {string} projectDir
+ *   The GitLab project directory.
+ * @param {string | undefined} jobName
+ *   The GitLab CI job name.
+ * @returns {Promise<string>}
+ *   The output path of the code quality artifact.
+ */
+async function getOutputPath(projectDir, jobName) {
+  const configPath = join(projectDir, process.env.CI_CONFIG_PATH ?? '.gitlab-ci.yml')
+  // GitlabCI allows a custom configuration path which can be a URL or a path relative to another
+  // project. In these cases CI_CONFIG_PATH is empty and we'll have to require the user provide
+  // ESLINT_CODE_QUALITY_REPORT.
+  let configContents
+  try {
+    configContents = await readFile(configPath, 'utf8')
+  } catch {
+    throw new Error(
+      'Could not resolve .gitlab-ci.yml to automatically detect report artifact path.' +
+        ' Please manually provide a path via the ESLINT_CODE_QUALITY_REPORT variable.'
+    )
+  }
+  const doc = yaml.parseDocument(configContents, {
+    version: '1.1',
+    customTags: [reference]
+  })
+  const path = [jobName, 'artifacts', 'reports', 'codequality']
+  const location = doc.getIn(path)
+  if (typeof location !== 'string' || !location) {
+    throw new TypeError(
+      `Expected ${path.join('.')} to be one exact path, got: ${JSON.stringify(location)}`
+    )
+  }
+  return resolve(projectDir, location)
+}
+
+/**
+ * Make a text singular or plural based on the count.
+ *
+ * @param {number} count
+ *   The count of the data.
+ * @param {string} text
+ *   The text to make singular or plural.
+ * @returns {string}
+ *   The formatted text.
+ */
+function plural(count, text) {
+  return `${count} ${text}${count === 1 ? '' : 's'}`
+}
+
+/**
+ * @param {ESLint.LintResult[]} results
+ *   The ESLint report results.
+ * @param {string} projectDir
+ *   The GitLab project directory.
+ * @returns {string}
+ *   The ESLint messages converted to a format suitable as output in GitLab CI job logs.
+ */
+function gitlabConsoleFormatter(results, projectDir) {
+  // Severity labels manually padded to have equal lengths and end with spaces
+  const labelFatal = `${styleText('magenta', 'fatal')}  `
+  const labelError = `${styleText('red', 'error')}  `
+  const labelWarn = `${styleText('yellow', 'warn')}   `
+
+  const lines = ['']
+
+  /** @type {string | undefined} */
+  let gitLabBaseURL
+  const projectUrl = process.env.CI_PROJECT_URL
+  const commitSha = process.env.CI_COMMIT_SHORT_SHA
+  if (projectUrl && commitSha) {
+    gitLabBaseURL = `${projectUrl}/-/blob/${commitSha}/`
+  }
+
+  let fatal = 0
+  let errors = 0
+  let warnings = 0
+  let maxRuleIdLength = 0
+  let maxMsgLength = 0
+
+  for (const result of results) {
+    fatal += result.fatalErrorCount
+    errors += result.errorCount - result.fatalErrorCount
+    warnings += result.warningCount
+    for (const message of result.messages) {
+      if (message.ruleId) {
+        maxRuleIdLength = Math.max(maxRuleIdLength, message.ruleId.length)
+      }
+      maxMsgLength = Math.max(maxMsgLength, message.message.length)
+    }
+  }
+
+  for (const result of results) {
+    const { filePath, messages } = result
+    const repoFilePath = relative(projectDir, filePath)
+
+    for (const message of messages) {
+      let line = message.fatal ? labelFatal : message.severity === 1 ? labelWarn : labelError
+      line += String(message.ruleId || '').padEnd(maxRuleIdLength + 2)
+      line += message.message.padEnd(maxMsgLength + 2)
+
+      if (gitLabBaseURL) {
+        // Create link to referenced file in GitLab
+        let anchor = `#L${message.line}`
+        if (message.endLine != null && message.endLine !== message.line) {
+          anchor += `-${message.endLine}`
+        }
+        line += styleText('blue', `${gitLabBaseURL}${repoFilePath}${anchor}`)
+      } else {
+        line += `${filePath}:${message.line}:${message.column}`
+      }
+
+      lines.push(line)
+    }
+  }
+
+  const total = warnings + errors + fatal
+  if (total > 0) {
+    const details = `(${fatal} fatal, ${plural(errors, 'error')}, ${plural(warnings, 'warning')})`
+    lines.push('', `${styleText('red', '✖')} ${plural(total, 'problem')} ${details}`)
+  } else {
+    lines.push(`${styleText('green', '✔')} No problems found`)
+  }
+
+  lines.push('')
+  return lines.join('\n')
+}
+
+/**
+ * @param {ESLint.LintResult[]} results
+ *   The ESLint report results.
+ * @param {ESLint.LintResultData} data
+ *   The ESLint report result data.
+ * @returns {Promise<string>}
+ *   The ESLint output to print to the console.
+ */
+async function eslintFormatterGitLab(results, data) {
+  let outputPath = process.env.ESLINT_CODE_QUALITY_REPORT
+  const projectDir = process.env.CI_PROJECT_DIR ?? data.cwd
+  const jobName = process.env.CI_JOB_NAME
+  if (jobName || outputPath) {
+    const issues = toCodeClimate(results, data.rulesMeta, projectDir)
+    outputPath ||= await getOutputPath(projectDir, jobName)
+    const dir = dirname(outputPath)
+    await mkdir(dir, { recursive: true })
+    await writeFile(outputPath, `${JSON.stringify(issues, null, 2)}\n`)
+  }
+
+  return gitlabConsoleFormatter(results, projectDir)
+}
+
+export default eslintFormatterGitLab

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "eslint-formatter-gitlab",
-  "version": "5.1.0",
+  "version": "6.0.1",
   "description": "Show ESLint results directly in the GitLab code quality results",
+  "type": "module",
   "author": "Remco Haszing <remcohaszing@gmail.com>",
   "license": "MIT",
   "homepage": "https://gitlab.com/remcohaszing/eslint-formatter-gitlab#readme",
   "repository": "gitlab:remcohaszing/eslint-formatter-gitlab",
   "funding": "https://github.com/sponsors/remcohaszing",
   "bugs": "https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/issues",
-  "exports": "./index.js",
+  "main": "./lib/eslint-formatter-gitlab.js",
+  "types": "./types/eslint-formatter-gitlab.d.ts",
+  "exports": {
+    "types": "./types/eslint-formatter-gitlab.d.ts",
+    "default": "./lib/eslint-formatter-gitlab.js"
+  },
   "files": [
-    "index.*"
+    "lib",
+    "types"
   ],
   "scripts": {
     "prepack": "tsc --build",
-    "test": "c8 node --test --test-reporter @reporters/junit --test-reporter-destination=junit.xml --test-reporter spec --test-reporter-destination stdout"
+    "test": "c8 node --test --test-reporter junit --test-reporter-destination=junit.xml --test-reporter spec --test-reporter-destination stdout"
   },
   "keywords": [
     "eslint",
@@ -24,23 +31,20 @@
     "gitlab-ci"
   ],
   "dependencies": {
-    "chalk": "^4.0.0",
+    "eslint-formatter-codeclimate": "^1.0.0",
     "yaml": "^2.0.0"
   },
   "peerDependencies": {
-    "eslint": ">=5"
+    "eslint": ">=9"
   },
   "devDependencies": {
-    "@reporters/junit": "^1.0.0",
-    "@types/eslint": "^8.0.0",
-    "@types/node": "^20.0.0",
-    "c8": "^8.0.0",
+    "@remcohaszing/eslint": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "c8": "^10.0.0",
     "codeclimate-types": "^0.3.0",
-    "eslint": "^8.0.0",
-    "eslint-config-remcohaszing": "^10.0.0",
     "prettier": "^3.0.0",
-    "remark-cli": "^11.0.0",
-    "remark-preset-remcohaszing": "^2.0.0",
+    "remark-cli": "^12.0.0",
+    "remark-preset-remcohaszing": "^3.0.0",
     "typescript": "^5.0.0"
   }
 }

package/types/eslint-formatter-gitlab.d.ts

@@ -0,0 +1,12 @@
+export default eslintFormatterGitLab;
+/**
+ * @param {ESLint.LintResult[]} results
+ *   The ESLint report results.
+ * @param {ESLint.LintResultData} data
+ *   The ESLint report result data.
+ * @returns {Promise<string>}
+ *   The ESLint output to print to the console.
+ */
+declare function eslintFormatterGitLab(results: ESLint.LintResult[], data: ESLint.LintResultData): Promise<string>;
+import type { ESLint } from 'eslint';
+//# sourceMappingURL=eslint-formatter-gitlab.d.ts.map

package/types/eslint-formatter-gitlab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eslint-formatter-gitlab.d.ts","sourceRoot":"","sources":["../lib/eslint-formatter-gitlab.js"],"names":[],"mappings":";AAqJA;;;;;;;GAOG;AACH,gDAPW,iBAAiB,EAAE,QAEnB,qBAAqB,GAEnB,OAAO,CAAC,MAAM,CAAC,CAgB3B;4BAzK0B,QAAQ"}

package/index.d.ts

@@ -1,11 +0,0 @@
-export = eslintFormatterGitLab;
-/**
- * @param {import('eslint').ESLint.LintResult[]} results
- *   The ESLint report results.
- * @param {import('eslint').ESLint.LintResultData} data
- *   The ESLint report result data.
- * @returns {string}
- *   The ESLint output to print to the console.
- */
-declare function eslintFormatterGitLab(results: import('eslint').ESLint.LintResult[], data: import('eslint').ESLint.LintResultData): string;
-//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";AA0PA;;;;;;;GAOG;AACH,gDAPW,OAAO,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,QAEpC,OAAO,QAAQ,EAAE,MAAM,CAAC,cAAc,GAEpC,MAAM,CAmBlB"}

package/index.js

@@ -1,277 +0,0 @@
-const { createHash } = require('node:crypto')
-const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } = require('node:fs')
-const { EOL } = require('node:os')
-const { dirname, join, relative, resolve } = require('node:path')
-
-const chalk = require('chalk')
-const yaml = require('yaml')
-
-const {
-  CI_COMMIT_SHORT_SHA,
-  CI_CONFIG_PATH = '.gitlab-ci.yml',
-  CI_JOB_NAME,
-  CI_PROJECT_DIR = process.cwd(),
-  CI_PROJECT_URL,
-  ESLINT_CODE_QUALITY_REPORT,
-  GITLAB_CI
-} = process.env
-
-/** @type {yaml.CollectionTag} */
-const reference = {
-  tag: '!reference',
-  collection: 'seq',
-  default: false,
-  resolve() {
-    // We only allow the syntax. We don’t actually resolve the reference.
-  }
-}
-
-/**
- * @returns {string}
- *   The output path of the code quality artifact.
- */
-function getOutputPath() {
-  const configPath = join(CI_PROJECT_DIR, CI_CONFIG_PATH)
-  // GitlabCI allows a custom configuration path which can be a URL or a path relative to another
-  // project. In these cases CI_CONFIG_PATH is empty and we'll have to require the user provide
-  // ESLINT_CODE_QUALITY_REPORT.
-  if (!existsSync(configPath) || !lstatSync(configPath).isFile()) {
-    throw new Error(
-      'Could not resolve .gitlab-ci.yml to automatically detect report artifact path.' +
-        ' Please manually provide a path via the ESLINT_CODE_QUALITY_REPORT variable.'
-    )
-  }
-  const doc = yaml.parseDocument(readFileSync(configPath, 'utf8'), {
-    version: '1.1',
-    customTags: [reference]
-  })
-  const path = [CI_JOB_NAME, 'artifacts', 'reports', 'codequality']
-  const location = doc.getIn(path)
-  if (typeof location !== 'string' || !location) {
-    throw new TypeError(
-      `Expected ${path.join('.')} to be one exact path, got: ${JSON.stringify(location)}`
-    )
-  }
-  return resolve(CI_PROJECT_DIR, location)
-}
-
-/**
- * @param {string} filePath
- *   The path to the linted file.
- * @param {import('eslint').Linter.LintMessage} message
- *   The ESLint report message.
- * @param {Set<string>} hashes
- *   Hashes already encountered. Used to avoid duplicate hashes
- * @returns {string}
- *   The fingerprint for the ESLint report message.
- */
-function createFingerprint(filePath, message, hashes) {
-  const md5 = createHash('md5')
-  md5.update(filePath)
-  if (message.ruleId) {
-    md5.update(message.ruleId)
-  }
-  md5.update(message.message)
-
-  // Create copy of hash since md5.digest() will finalize it, not allowing us to .update() again
-  let md5Tmp = md5.copy()
-  let hash = md5Tmp.digest('hex')
-
-  while (hashes.has(hash)) {
-    // Hash collision. This happens if we encounter the same ESLint message in one file
-    // multiple times. Keep generating new hashes until we get a unique one.
-    md5.update(hash)
-
-    md5Tmp = md5.copy()
-    hash = md5Tmp.digest('hex')
-  }
-
-  hashes.add(hash)
-  return hash
-}
-
-/**
- * @param {import('eslint').ESLint.LintResult[]} results
- *   The ESLint report results.
- * @param {import('eslint').ESLint.LintResultData} data
- *   The ESLint report result data.
- * @returns {import('codeclimate-types').Issue[]}
- *   The ESLint messages in the form of a GitLab code quality report.
- */
-function convert(results, data) {
-  /** @type {import('codeclimate-types').Issue[]} */
-  const messages = []
-
-  /** @type {Set<string>} */
-  const hashes = new Set()
-
-  for (const result of results) {
-    const relativePath = relative(CI_PROJECT_DIR, result.filePath)
-
-    for (const message of result.messages) {
-      /** @type {import('codeclimate-types').Issue} */
-      const issue = {
-        type: 'issue',
-        categories: ['Style'],
-        check_name: message.ruleId ?? '',
-        description: message.message,
-        severity: message.fatal ? 'critical' : message.severity === 2 ? 'major' : 'minor',
-        fingerprint: createFingerprint(relativePath, message, hashes),
-        location: {
-          path: relativePath,
-          lines: {
-            begin: message.line,
-            end: message.endLine ?? message.line
-          }
-        }
-      }
-      messages.push(issue)
-
-      if (!message.ruleId) {
-        continue
-      }
-
-      if (!data.rulesMeta[message.ruleId]) {
-        continue
-      }
-
-      const { docs, type } = data.rulesMeta[message.ruleId]
-      if (type === 'problem') {
-        issue.categories.unshift('Bug Risk')
-      }
-
-      if (!docs) {
-        continue
-      }
-
-      let body = docs.description || ''
-      if (docs.url) {
-        if (body) {
-          body += '\n\n'
-        }
-        body += `[${message.ruleId}](${docs.url})`
-      }
-
-      if (body) {
-        issue.content = { body }
-      }
-    }
-  }
-  return messages
-}
-
-/**
- * Make a text singular or plural based on the count.
- *
- * @param {number} count
- *   The count of the data.
- * @param {string} text
- *   The text to make singular or plural.
- * @returns {string}
- *   The formatted text.
- */
-function plural(count, text) {
-  return `${count} ${text}${count === 1 ? '' : 's'}`
-}
-
-/**
- * @param {import('eslint').ESLint.LintResult[]} results
- *   The ESLint report results.
- * @returns {string}
- *   The ESLint messages converted to a format suitable as output in GitLab CI job logs.
- */
-function gitlabConsoleFormatter(results) {
-  // Severity labels manually padded to have equal lengths and end with spaces
-  const labelFatal = `${chalk.magenta('fatal')}  `
-  const labelError = `${chalk.red('error')}  `
-  const labelWarn = `${chalk.yellow('warn')}   `
-
-  const lines = ['']
-
-  /** @type {string | undefined} */
-  let gitLabBaseURL
-  if (CI_PROJECT_URL && CI_COMMIT_SHORT_SHA) {
-    gitLabBaseURL = `${CI_PROJECT_URL}/-/blob/${CI_COMMIT_SHORT_SHA}/`
-  }
-
-  let fatal = 0
-  let errors = 0
-  let warnings = 0
-  let maxRuleIdLength = 0
-  let maxMsgLength = 0
-
-  for (const result of results) {
-    fatal += result.fatalErrorCount
-    errors += result.errorCount - result.fatalErrorCount
-    warnings += result.warningCount
-    for (const message of result.messages) {
-      if (message.ruleId) {
-        maxRuleIdLength = Math.max(maxRuleIdLength, message.ruleId.length)
-      }
-      maxMsgLength = Math.max(maxMsgLength, message.message.length)
-    }
-  }
-
-  for (const result of results) {
-    const { filePath, messages } = result
-    const repoFilePath = relative(CI_PROJECT_DIR, filePath)
-
-    for (const message of messages) {
-      let line = message.fatal ? labelFatal : message.severity === 1 ? labelWarn : labelError
-      line += String(message.ruleId || '').padEnd(maxRuleIdLength + 2)
-      line += message.message.padEnd(maxMsgLength + 2)
-
-      if (gitLabBaseURL) {
-        // Create link to referenced file in GitLab
-        let anchor = `#L${message.line}`
-        if (message.endLine != null && message.endLine !== message.line) {
-          anchor += `-${message.endLine}`
-        }
-        line += chalk.blue(`${gitLabBaseURL}${repoFilePath}${anchor}`)
-      } else {
-        line += `${filePath}:${message.line}:${message.column}`
-      }
-
-      lines.push(line)
-    }
-  }
-
-  const total = warnings + errors + fatal
-  if (total > 0) {
-    const details = `(${fatal} fatal, ${plural(errors, 'error')}, ${plural(warnings, 'warning')})`
-    lines.push('', `${chalk.red('✖')} ${plural(total, 'problem')} ${details}`)
-  } else {
-    lines.push(`${chalk.green('✔')} No problems found`)
-  }
-
-  lines.push('')
-  return lines.join(EOL)
-}
-
-/**
- * @param {import('eslint').ESLint.LintResult[]} results
- *   The ESLint report results.
- * @param {import('eslint').ESLint.LintResultData} data
- *   The ESLint report result data.
- * @returns {string}
- *   The ESLint output to print to the console.
- */
-function eslintFormatterGitLab(results, data) {
-  /* c8 ignore start */
-  if (GITLAB_CI === 'true') {
-    chalk.level = 1
-  }
-
-  /* c8 ignore stop */
-  if (CI_JOB_NAME || ESLINT_CODE_QUALITY_REPORT) {
-    const issues = convert(results, data)
-    const outputPath = ESLINT_CODE_QUALITY_REPORT || getOutputPath()
-    const dir = dirname(outputPath)
-    mkdirSync(dir, { recursive: true })
-    writeFileSync(outputPath, JSON.stringify(issues, null, 2))
-  }
-
-  return gitlabConsoleFormatter(results)
-}
-
-module.exports = eslintFormatterGitLab