eslint-formatter-gitlab 3.0.0 → 4.0.0

package/README.md

@@ -1,10 +1,12 @@
 # ESLint Formatter for GitLab
 
-> Show ESLint results directly in the [GitLab code quality] results
+Show ESLint results directly in the
+[GitLab code quality](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html)
+results
 
 ## Requirements
 
-This requires at least GitLab Bronze or Starter 11.5 and at least ESLint 5.
+This package requires at least Node.js 14 and ESLint 5.
 
 ## Installation
 
@@ -14,13 +16,15 @@ Install `eslint` and `eslint-formatter-gitlab` using your package manager.
 npm install --save-dev eslint eslint-formatter-gitlab
 ```
 
+## Usage
+
 Define a GitLab job to run `eslint`.
 
 _.gitlab-ci.yml_:
 
 ```yaml
 eslint:
-  image: node:14-alpine
+  image: node:18-alpine
   script:
     - npm ci
     - npx eslint --format gitlab .
@@ -34,23 +38,16 @@ code quality report based on the GitLab configuration file.
 
 ## Example
 
-An example of the results can be seen in [Merge Request !1] of `eslint-formatter-gitlab` itself.
+An example of the results can be seen in
+[Merge Request !1](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/merge_requests/1) of
+`eslint-formatter-gitlab` itself.
 
 ## Configuration Options
 
-ESLint formatters don’t take any configuration options. In order to still allow some way of
-configuration, options are passed using environment variables.
-
-| Environment Variable         | Description                                                                                                                                                    |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ESLINT_CODE_QUALITY_REPORT` | The location to store the code quality report. By default it will detect the location of the codequality artifact defined in the GitLab CI configuration file. |
-
-## Upgrading
-
-### to v3
+ESLint formatters don’t take any configuration options. `eslint-formatter-gitlab` uses GitLab
+environment variables 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.
 
-- Support for the environment variable `ESLINT_FORMATTER` has been removed, console output now
-  always uses a builtin formatter.
+# License
 
-[gitlab code quality]: https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html
-[merge request !1]: https://gitlab.com/remcohaszing/eslint-formatter-gitlab/merge_requests/1
+[MIT](LICENSE.md) @ [Remco Haszing](https://gitlab.com/remcohaszing)

package/index.js

@@ -1,11 +1,65 @@
-const { createHash } = require('crypto');
-const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
-const { EOL } = require('os');
-const { dirname, join, relative, resolve } = require('path');
+/**
+ * @typedef {import('eslint').ESLint.LintResult} LintResult
+ * @typedef {import('eslint').ESLint.LintResultData} LintResultData
+ * @typedef {import('eslint').Linter.LintMessage} LintMessage
+ */
+
+/**
+ * @typedef {object} GitLabReports
+ * @property {string} [codequality]
+ */
+
+/**
+ * @typedef {object} GitLabArtifacts
+ * @property {GitLabReports} [reports]
+ */
+
+/**
+ * @typedef {object} GitLabJob
+ * @property {GitLabArtifacts} [artifacts]
+ */
+
+/**
+ * @typedef {Record<string, GitLabJob>} GitLabCI
+ */
+
+/**
+ * @typedef {object} CodeClimateLines
+ * @property {number} begin
+ * @property {number} end
+ */
+
+/**
+ * @typedef {object} CodeClimateContents
+ * @property {string} body
+ */
+
+/**
+ * @typedef {object} CodeClimateLocation
+ * https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#locations
+ * @property {string} path
+ * @property {CodeClimateLines} lines
+ */
+
+/**
+ * @typedef {object} CodeClimateIssue
+ * https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#issues
+ * @property {'issue'} type
+ * @property {string} check_name
+ * @property {string} description
+ * @property {CodeClimateContents} [contents]
+ * @property {'info' | 'minor' | 'major' | 'critical' | 'blocker'} severity
+ * @property {string} [fingerprint]
+ * @property {CodeClimateLocation} location
+ */
+
+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');
 
-// eslint-disable-next-line unicorn/import-style
 const chalk = require('chalk');
-const yaml = require('js-yaml');
+const yaml = require('yaml');
 
 const {
   CI_CONFIG_PATH = '.gitlab-ci.yml',
@@ -18,6 +72,18 @@ const {
   NODE_ENV,
 } = 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.
  */
@@ -32,9 +98,11 @@ function getOutputPath() {
         ' Please manually provide a path via the ESLINT_CODE_QUALITY_REPORT variable.',
     );
   }
-  const jobs = yaml.load(readFileSync(configPath, 'utf-8'));
-  const { artifacts } = jobs[CI_JOB_NAME];
-  const location = artifacts && artifacts.reports && artifacts.reports.codequality;
+  const jobs = /** @type {GitLabCI} */ (
+    yaml.parse(readFileSync(configPath, 'utf8'), { version: '1.1', customTags: [reference] })
+  );
+  const { artifacts } = jobs[/** @type {string} */ (CI_JOB_NAME)];
+  const location = artifacts?.reports?.codequality;
   const msg = `Expected ${CI_JOB_NAME}.artifacts.reports.codequality to be one exact path`;
   if (!location) {
     throw new Error(`${msg}, but no value was found.`);
@@ -46,8 +114,8 @@ function getOutputPath() {
 }
 
 /**
- * @param {string} filePath - The path to the linted file.
- * @param {object} message - The ESLint report message.
+ * @param {string} filePath The path to the linted file.
+ * @param {LintMessage} message The ESLint report message.
  * @returns {string} The fingerprint for the ESLint report message.
  */
 function createFingerprint(filePath, message) {
@@ -61,16 +129,21 @@ function createFingerprint(filePath, message) {
 }
 
 /**
- * @param {object[]} results - The ESLint report results.
- * @returns {object[]} The ESLint messages in the form of a GitLab code quality report.
+ * @param {LintResult[]} results The ESLint report results.
+ * @param {LintResultData} data The ESLint report result data.
+ * @returns {CodeClimateIssue[]} The ESLint messages in the form of a GitLab code quality report.
  */
-function convert(results) {
+function convert(results, data) {
+  /** @type {CodeClimateIssue[]} */
   const messages = [];
   for (const result of results) {
     for (const message of result.messages) {
       const relativePath = relative(CI_PROJECT_DIR, result.filePath);
-      // https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types
-      messages.push({
+
+      /** @type {CodeClimateIssue} */
+      const issue = {
+        type: 'issue',
+        check_name: message.ruleId ?? '',
         description: message.message,
         severity: message.severity === 2 ? 'major' : 'minor',
         fingerprint: createFingerprint(relativePath, message),
@@ -78,16 +151,31 @@ function convert(results) {
           path: relativePath,
           lines: {
             begin: message.line,
+            end: message.endLine ?? message.line,
           },
         },
-      });
+      };
+      const docs = message.ruleId ? data.rulesMeta[message.ruleId]?.docs : undefined;
+      if (docs) {
+        let body = docs.description || '';
+        if (docs.url) {
+          if (body) {
+            body += '\n\n';
+          }
+          body += `[${message.ruleId}](${docs.url})`;
+        }
+        if (body) {
+          issue.contents = { body };
+        }
+      }
+      messages.push(issue);
     }
   }
   return messages;
 }
 
 /**
- * @param {object} message - The ESLint report message.
+ * @param {LintMessage} message The ESLint report message.
  * @returns {boolean} `true` if the message is at error level, `false` if it represents a warning
  */
 function messageIsLevelError(message) {
@@ -95,34 +183,18 @@ function messageIsLevelError(message) {
 }
 
 /**
- * @param {object[]} results - The ESLint report results.
- * @returns {object} Statistics about the number of problems at various levels
- * and length of contained description strings.
+ * 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 calculateResultsStats(results) {
-  const stats = { total: 0, errors: 0, warnings: 0, maxRuleIdLength: 0, maxMsgLength: 0 };
-
-  for (const result of results) {
-    for (const message of result.messages) {
-      const isError = messageIsLevelError(message);
-      stats.errors += isError ? 1 : 0;
-      stats.warnings += isError ? 0 : 1;
-      stats.maxRuleIdLength = message.ruleId
-        ? Math.max(stats.maxRuleIdLength, message.ruleId.length)
-        : stats.maxRuleIdLength;
-      stats.maxMsgLength = Math.max(stats.maxMsgLength, message.message.length);
-    }
-  }
-
-  stats.total = stats.warnings + stats.errors;
-
-  return stats;
+function plural(count, text) {
+  return `${count} ${text}${count === 1 ? '' : 's'}`;
 }
 
-const plural = (count, text) => `${count} ${text}${count === 1 ? '' : 's'}`;
-
 /**
- * @param {object[]} results - The ESLint report results.
+ * @param {LintResult[]} results The ESLint report results.
  * @returns {string} The ESLint messages converted to a format
  * suitable as output in GitLab CI job logs.
  */
@@ -133,12 +205,28 @@ function gitlabConsoleFormatter(results) {
 
   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 stats = calculateResultsStats(results);
+  let errors = 0;
+  let warnings = 0;
+  let maxRuleIdLength = 0;
+  let maxMsgLength = 0;
+
+  for (const result of results) {
+    for (const message of result.messages) {
+      const isError = messageIsLevelError(message);
+      errors += isError ? 1 : 0;
+      warnings += isError ? 0 : 1;
+      maxRuleIdLength = message.ruleId
+        ? Math.max(maxRuleIdLength, message.ruleId.length)
+        : maxRuleIdLength;
+      maxMsgLength = Math.max(maxMsgLength, message.message.length);
+    }
+  }
 
   for (const result of results) {
     const { filePath, messages } = result;
@@ -147,8 +235,8 @@ function gitlabConsoleFormatter(results) {
     for (const message of messages) {
       let line;
       line = messageIsLevelError(message) ? labelError : labelWarn;
-      line += String(message.ruleId ? message.ruleId : '').padEnd(stats.maxRuleIdLength + 2);
-      line += message.message.padEnd(stats.maxMsgLength + 2);
+      line += String(message.ruleId || '').padEnd(maxRuleIdLength + 2);
+      line += message.message.padEnd(maxMsgLength + 2);
 
       if (gitLabBaseURL) {
         // Create link to referenced file in GitLab
@@ -162,9 +250,10 @@ function gitlabConsoleFormatter(results) {
     }
   }
 
-  if (stats.total > 0) {
-    const details = `(${plural(stats.errors, 'error')}, ${plural(stats.warnings, 'warning')})`;
-    lines.push('', `${chalk.red('✖')} ${plural(stats.total, 'problem')} ${details}`);
+  const total = warnings + errors;
+  if (total > 0) {
+    const details = `(${plural(errors, 'error')}, ${plural(warnings, 'warning')})`;
+    lines.push('', `${chalk.red('✖')} ${plural(total, 'problem')} ${details}`);
   } else {
     lines.push(`${chalk.green('✔')} No problems found`);
   }
@@ -173,16 +262,21 @@ function gitlabConsoleFormatter(results) {
   return lines.join(EOL);
 }
 
-module.exports = (results) => {
+/**
+ * @param {LintResult[]} results The ESLint report results.
+ * @param {LintResultData} data The ESLint report result data.
+ */
+module.exports = (results, data) => {
+  /* istanbul ignore next */
   if (GITLAB_CI === 'true' && NODE_ENV !== 'test') {
     chalk.level = 1;
   }
   if (CI_JOB_NAME || ESLINT_CODE_QUALITY_REPORT) {
-    const data = convert(results);
+    const issues = convert(results, data);
     const outputPath = ESLINT_CODE_QUALITY_REPORT || getOutputPath();
     const dir = dirname(outputPath);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(outputPath, JSON.stringify(data, null, 2));
+    writeFileSync(outputPath, JSON.stringify(issues, null, 2));
   }
 
   return gitlabConsoleFormatter(results);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-formatter-gitlab",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Show ESLint results directly in the GitLab code quality results",
   "author": "Remco Haszing <remcohaszing@gmail.com>",
   "license": "MIT",
@@ -9,14 +9,16 @@
     "type": "git",
     "url": "https://gitlab.com/remcohaszing/eslint-formatter-gitlab.git"
   },
+  "funding": "https://github.com/sponsors/remcohaszing",
   "bugs": {
     "url": "https://gitlab.com/remcohaszing/eslint-formatter-gitlab.git/issues"
   },
+  "exports": "./index.js",
   "files": [
     "index.js"
   ],
   "scripts": {
-    "test": "jest"
+    "test": "jest --coverage"
   },
   "keywords": [
     "eslint",
@@ -25,30 +27,28 @@
     "gitlab",
     "gitlab-ci"
   ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
   "dependencies": {
     "chalk": "^4.0.0",
-    "js-yaml": "^4.0.0"
+    "yaml": "^2.0.0"
   },
   "peerDependencies": {
     "eslint": "^5 || ^6 || ^7 || ^8"
   },
   "devDependencies": {
-    "codecov": "^3.0.0",
-    "eslint": "^7.0.0",
-    "eslint-config-remcohaszing": "^3.0.0",
-    "eslint-plugin-eslint-comments": "^3.0.0",
-    "eslint-plugin-import": "^2.0.0",
-    "eslint-plugin-jest": "^24.0.0",
+    "@types/eslint": "^8.0.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^18.0.0",
+    "eslint": "^8.0.0",
+    "eslint-config-remcohaszing": "^7.0.0",
+    "eslint-plugin-jest": "^27.0.0",
     "eslint-plugin-jest-formatting": "^3.0.0",
-    "eslint-plugin-jsdoc": "^36.0.0",
-    "eslint-plugin-markdown": "^2.0.0",
-    "eslint-plugin-node": "^11.0.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "eslint-plugin-sort-destructure-keys": "^1.0.0",
-    "eslint-plugin-unicorn": "^36.0.0",
-    "jest": "^27.0.0",
-    "jest-junit": "^13.0.0",
+    "jest": "^29.0.0",
+    "jest-junit": "^14.0.0",
     "memfs": "^3.0.0",
-    "prettier": "^2.0.0"
+    "prettier": "^2.0.0",
+    "typescript": "^4.0.0"
   }
 }