eslint-formatter-gitlab 2.2.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,17 +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.
+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.
 
-| 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. |
-| `ESLINT_FORMATTER`           | The ESLint formatter to use for the console output. This defaults to stylish, the default ESLint 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,18 +1,89 @@
-const { createHash } = require('crypto');
-const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
-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
+ */
 
-const { CLIEngine } = require('eslint');
-const yaml = require('js-yaml');
+/**
+ * @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');
+
+const chalk = require('chalk');
+const yaml = require('yaml');
 
 const {
   CI_CONFIG_PATH = '.gitlab-ci.yml',
   CI_JOB_NAME,
   CI_PROJECT_DIR = process.cwd(),
+  CI_PROJECT_URL,
+  CI_COMMIT_SHORT_SHA,
   ESLINT_CODE_QUALITY_REPORT,
-  ESLINT_FORMATTER,
+  GITLAB_CI,
+  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.
  */
@@ -27,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.`);
@@ -41,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) {
@@ -56,44 +129,155 @@ 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.
- */
-function convert(results) {
-  return results.reduce(
-    (acc, result) => [
-      ...acc,
-      ...result.messages.map((message) => {
-        const relativePath = relative(CI_PROJECT_DIR, result.filePath);
-        // https://github.com/codeclimate/spec/blob/master/SPEC.md#data-types
-        return {
-          description: message.message,
-          severity: message.severity === 2 ? 'major' : 'minor',
-          fingerprint: createFingerprint(relativePath, message),
-          location: {
-            path: relativePath,
-            lines: {
-              begin: message.line,
-            },
+ * @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, data) {
+  /** @type {CodeClimateIssue[]} */
+  const messages = [];
+  for (const result of results) {
+    for (const message of result.messages) {
+      const relativePath = relative(CI_PROJECT_DIR, result.filePath);
+
+      /** @type {CodeClimateIssue} */
+      const issue = {
+        type: 'issue',
+        check_name: message.ruleId ?? '',
+        description: message.message,
+        severity: message.severity === 2 ? 'major' : 'minor',
+        fingerprint: createFingerprint(relativePath, message),
+        location: {
+          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;
 }
 
-module.exports = (results) => {
+/**
+ * @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) {
+  return message.fatal || message.severity === 2;
+}
+
+/**
+ * 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 {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 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 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;
+    const repoFilePath = relative(CI_PROJECT_DIR, filePath);
+
+    for (const message of messages) {
+      let line;
+      line = messageIsLevelError(message) ? labelError : labelWarn;
+      line += String(message.ruleId || '').padEnd(maxRuleIdLength + 2);
+      line += message.message.padEnd(maxMsgLength + 2);
+
+      if (gitLabBaseURL) {
+        // Create link to referenced file in GitLab
+        const anchor = message.line === undefined ? '' : `#L${message.line}`;
+        line += chalk.blue(`${gitLabBaseURL}${repoFilePath}${anchor}`);
+      } else {
+        line += `${filePath}:${message.line || 0}:${message.column || 0}`;
+      }
+
+      lines.push(line);
+    }
+  }
+
+  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`);
+  }
+
+  lines.push('');
+  return lines.join(EOL);
+}
+
+/**
+ * @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));
   }
-  let formatter = CLIEngine.getFormatter(ESLINT_FORMATTER);
-  if (formatter === module.exports) {
-    formatter = CLIEngine.getFormatter();
-  }
-  return formatter(results);
+
+  return gitlabConsoleFormatter(results);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-formatter-gitlab",
-  "version": "2.2.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,29 +27,28 @@
     "gitlab",
     "gitlab-ci"
   ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
   "dependencies": {
-    "js-yaml": "^4.0.0"
+    "chalk": "^4.0.0",
+    "yaml": "^2.0.0"
   },
   "peerDependencies": {
-    "eslint": "^5 || ^6 || ^7"
+    "eslint": "^5 || ^6 || ^7 || ^8"
   },
   "devDependencies": {
-    "codecov": "^3.8.1",
-    "eslint": "^7.18.0",
-    "eslint-config-remcohaszing": "^3.1.0",
-    "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-import": "^2.22.1",
-    "eslint-plugin-jest": "^24.1.3",
-    "eslint-plugin-jest-formatting": "^2.0.1",
-    "eslint-plugin-jsdoc": "^31.4.0",
-    "eslint-plugin-markdown": "^2.0.0-rc.1",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-prettier": "^3.3.1",
-    "eslint-plugin-sort-destructure-keys": "^1.3.5",
-    "eslint-plugin-unicorn": "^27.0.0",
-    "jest": "^26.6.3",
-    "jest-junit": "^12.0.0",
-    "memfs": "^3.2.0",
-    "prettier": "^2.2.1"
+    "@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",
+    "jest": "^29.0.0",
+    "jest-junit": "^14.0.0",
+    "memfs": "^3.0.0",
+    "prettier": "^2.0.0",
+    "typescript": "^4.0.0"
   }
 }

package/CHANGELOG.md

@@ -1,56 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
-adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [2.2.0] - 2021-01-27
-
-### Changed
-
-- Updated `ja-yaml`.
-
-## [2.2.0] - 2020-12-12
-
-### Added
-
-- Added severity to output.
-
-## [2.0.0] - 2020-04-14
-
-### Changed
-
-- Support ESLint 7.
-
-### Fixed
-
-- Fix infinite recursion when `ESLINT_CODE_QUALITY_REPORT` refers to `eslint-formatter-gitlab`
-  itself.
-
-## [1.1.0] - 2019-08-08
-
-### Changed
-
-- Support ESLint 6.
-
-## [1.0.2] - 2018-12-13
-
-### Fixes
-
-- Fix automated release process.
-
-## [1.0.1] - 2018-12-13
-
-### Added
-
-- Tests.
-- Link to example merge request.
-
-## [1.0.0] - 2018-11-29
-
-### Added
-
-- Initial release.