eslint-formatter-gitlab 5.0.0 → 6.0.0

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,7 +33,7 @@ npm install --save-dev eslint eslint-formatter-gitlab
 
 Define a GitLab job to run `eslint`.
 
-_.gitlab-ci.yml_:
+`.gitlab-ci.yml`:
 
 ```yaml
 eslint:
@@ -43,7 +47,21 @@ eslint:
 ```
 
 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/{index.js → lib/eslint-formatter-gitlab.js}

@@ -1,31 +1,16 @@
 /**
- * @typedef {import('eslint').ESLint.LintResult} LintResult
- * @typedef {import('eslint').ESLint.LintResultData} LintResultData
- * @typedef {import('eslint').Linter.LintMessage} LintMessage
- * @typedef {import('codeclimate-types').Issue} Issue
+ * @import { Issue } from 'codeclimate-types'
+ * @import { ESLint, Linter } from 'eslint'
  */
 
-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')
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join, relative, resolve } from 'node:path'
+import { styleText } from 'node:util'
 
-const chalk = require('chalk')
-const yaml = require('yaml')
+import yaml from '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}
- */
+/** @type {yaml.CollectionTag} */
 const reference = {
   tag: '!reference',
   collection: 'seq',
@@ -36,38 +21,50 @@ const reference = {
 }
 
 /**
- * @returns {string} The output path of the code quality artifact.
+ * @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.
  */
-function getOutputPath() {
-  const configPath = join(CI_PROJECT_DIR, CI_CONFIG_PATH)
+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.
-  if (!existsSync(configPath) || !lstatSync(configPath).isFile()) {
+  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(readFileSync(configPath, 'utf8'), {
+  const doc = yaml.parseDocument(configContents, {
     version: '1.1',
     customTags: [reference]
   })
-  const path = [CI_JOB_NAME, 'artifacts', 'reports', 'codequality']
+  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(CI_PROJECT_DIR, location)
+  return resolve(projectDir, location)
 }
 
 /**
- * @param {string} filePath The path to the linted file.
- * @param {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.
+ * @param {string} filePath
+ *   The path to the linted file.
+ * @param {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')
@@ -95,11 +92,16 @@ function createFingerprint(filePath, message, hashes) {
 }
 
 /**
- * @param {LintResult[]} results The ESLint report results.
- * @param {LintResultData} data The ESLint report result data.
- * @returns {Issue[]} The ESLint messages in the form of a GitLab code quality report.
+ * @param {ESLint.LintResult[]} results
+ *   The ESLint report results.
+ * @param {ESLint.LintResultData} data
+ *   The ESLint report result data.
+ * @param {string} projectDir
+ *   The GitLab project directory.
+ * @returns {Issue[]}
+ *   The ESLint messages in the form of a GitLab code quality report.
  */
-function convert(results, data) {
+function convert(results, data, projectDir) {
   /** @type {Issue[]} */
   const messages = []
 
@@ -107,7 +109,7 @@ function convert(results, data) {
   const hashes = new Set()
 
   for (const result of results) {
-    const relativePath = relative(CI_PROJECT_DIR, result.filePath)
+    const relativePath = relative(projectDir, result.filePath)
 
     for (const message of result.messages) {
       /** @type {Issue} */
@@ -126,26 +128,36 @@ function convert(results, data) {
           }
         }
       }
-      if (message.ruleId && message.ruleId in data.rulesMeta) {
-        const { docs, type } = data.rulesMeta[message.ruleId]
-        if (type === 'problem') {
-          issue.categories.unshift('Bug Risk')
-        }
+      messages.push(issue)
 
-        if (docs) {
-          let body = docs.description || ''
-          if (docs.url) {
-            if (body) {
-              body += '\n\n'
-            }
-            body += `[${message.ruleId}](${docs.url})`
-          }
-          if (body) {
-            issue.content = { body }
-          }
+      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 }
       }
-      messages.push(issue)
     }
   }
   return messages
@@ -154,31 +166,39 @@ function convert(results, data) {
 /**
  * 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.
+ * @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 {LintResult[]} results The ESLint report results.
- * @returns {string} The ESLint messages converted to a format
- *   suitable as output in GitLab CI job logs.
+ * @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) {
+function gitlabConsoleFormatter(results, projectDir) {
   // 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 labelFatal = `${styleText('magenta', 'fatal')}  `
+  const labelError = `${styleText('red', 'error')}  `
+  const labelWarn = `${styleText('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}/`
+  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
@@ -201,7 +221,7 @@ function gitlabConsoleFormatter(results) {
 
   for (const result of results) {
     const { filePath, messages } = result
-    const repoFilePath = relative(CI_PROJECT_DIR, filePath)
+    const repoFilePath = relative(projectDir, filePath)
 
     for (const message of messages) {
       let line = message.fatal ? labelFatal : message.severity === 1 ? labelWarn : labelError
@@ -214,7 +234,7 @@ function gitlabConsoleFormatter(results) {
         if (message.endLine != null && message.endLine !== message.line) {
           anchor += `-${message.endLine}`
         }
-        line += chalk.blue(`${gitLabBaseURL}${repoFilePath}${anchor}`)
+        line += styleText('blue', `${gitLabBaseURL}${repoFilePath}${anchor}`)
       } else {
         line += `${filePath}:${message.line}:${message.column}`
       }
@@ -226,33 +246,36 @@ function gitlabConsoleFormatter(results) {
   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}`)
+    lines.push('', `${styleText('red', '✖')} ${plural(total, 'problem')} ${details}`)
   } else {
-    lines.push(`${chalk.green('✔')} No problems found`)
+    lines.push(`${styleText('green', '✔')} No problems found`)
   }
 
   lines.push('')
-  return lines.join(EOL)
+  return lines.join('\n')
 }
 
 /**
- * @param {LintResult[]} results The ESLint report results.
- * @param {LintResultData} data The ESLint report result data.
+ * @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.
  */
-module.exports = (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()
+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 = convert(results, data, projectDir)
+    outputPath ||= await getOutputPath(projectDir, jobName)
     const dir = dirname(outputPath)
-    mkdirSync(dir, { recursive: true })
-    writeFileSync(outputPath, JSON.stringify(issues, null, 2))
+    await mkdir(dir, { recursive: true })
+    await writeFile(outputPath, `${JSON.stringify(issues, null, 2)}\n`)
   }
 
-  return gitlabConsoleFormatter(results)
+  return gitlabConsoleFormatter(results, projectDir)
 }
+
+export default eslintFormatterGitLab

package/package.json

@@ -1,19 +1,27 @@
 {
   "name": "eslint-formatter-gitlab",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "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.js"
+    "lib",
+    "types"
   ],
   "scripts": {
-    "test": "c8 node --test --test-reporter @reporters/junit --test-reporter-destination=junit.xml --test-reporter spec --test-reporter-destination stdout"
+    "prepack": "tsc --build",
+    "test": "c8 node --test --test-reporter junit --test-reporter-destination=junit.xml --test-reporter spec --test-reporter-destination stdout"
   },
   "keywords": [
     "eslint",
@@ -23,23 +31,19 @@
     "gitlab-ci"
   ],
   "dependencies": {
-    "chalk": "^4.0.0",
     "yaml": "^2.0.0"
   },
   "peerDependencies": {
-    "eslint": "^5 || ^6 || ^7 || ^8"
+    "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": "^9.0.0",
-    "prettier": "^2.0.0",
-    "remark-cli": "^11.0.0",
-    "remark-preset-remcohaszing": "^1.0.0",
+    "prettier": "^3.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":";AAiQA;;;;;;;GAOG;AACH,gDAPW,iBAAiB,EAAE,QAEnB,qBAAqB,GAEnB,OAAO,CAAC,MAAM,CAAC,CAgB3B;4BApRkC,QAAQ"}