@studiometa/stylelint-formatter-gitlab 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 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]
+
+## v0.0.0 - 2024-05-31
+
+First release 🎉

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Studio Meta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# StyleLint formatter for GitLab Code Quality
+
+[![NPM Version](https://img.shields.io/npm/v/@studiometa/stylelint-formatter-gitlab.svg?style=flat-square)](https://www.npmjs.com/package/@studiometa/stylelint-formatter-gitlab/)
+
+> Format StyleLint errors for Gitlab Code Quality reports.
+
+## Installation
+
+Install the package with NPM:
+
+```bash
+npm install -D stylelint@16 @studiometa/stylelint-formatter-gitlab
+```
+
+## Usage
+
+Define a GitLab job to run `stylelint`.
+
+_.gitlab-ci.yml_:
+
+```yaml
+stylelint:
+  image: node
+  script:
+    - npm ci
+    - npx stylelint --custom-formatter=@studiometa/stylelint-formatter-gitlab .
+  artifacts:
+    reports:
+      codequality: gl-codequality.json
+```
+
+The formatter will automatically detect a GitLab CI environment. It will detect where to output the
+code quality report based on the GitLab configuration file.
+
+## Configuration Options
+
+StyleLint 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                                                                                                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STYLELINT_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. |
+| `STYLELINT_FORMATTER`           | The Stylelint formatter to use for the console output. This defaults to string, the default Stylelint formatter.                                               |
+
+## Notes
+
+This project is based on the [`stylelint-formatter-gitlab`](https://gitlab.com/leon0399/stylelint-formatter-gitlab) package which seems unmaintained and does not support StyleLint v16.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@studiometa/stylelint-formatter-gitlab",
+  "version": "0.0.0",
+  "description": "A StyleLint formatter for the GitLab Code Quality report",
+  "main": "src/index.js",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "bun test test/",
+    "lint": "eslint . --cache",
+    "fix": "eslint . --cache --fix"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/studiometa/stylelint-formatter-gitlab.git"
+  },
+  "keywords": [
+    "gitlab",
+    "stylelint",
+    "formatter",
+    "code",
+    "quality"
+  ],
+  "author": "Studio Meta <agence@studiometa.fr> (https://www.studiometa.fr/)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/studiometa/stylelint-formatter-gitlab/issues"
+  },
+  "homepage": "https://github.com/studiometa/stylelint-formatter-gitlab#readme",
+  "devDependencies": {
+    "@studiometa/eslint-config": "^4.0.1",
+    "@studiometa/prettier-config": "^4.0.0",
+    "@studiometa/stylelint-config": "4.0.0",
+    "bun": "^1.1.3",
+    "eslint": "^9.0.0",
+    "prettier": "^3.2.5",
+    "stylelint": "16.6.1"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "jest-diff": "^29.7.0",
+    "js-yaml": "^4.1.0"
+  },
+  "peerDependencies": {
+    "stylelint": "^16.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,24 @@
+import { writeFileSync } from 'node:fs';
+import stylelint from 'stylelint';
+import { getOutputPath, convert, getEnv } from './utils.js';
+
+/**
+ * GitLab formatter.
+ * @param {import('stylelint').LintResult[]} results
+ * @param {import('stylelint').LinterResult} returnValue
+ * @returns {void}
+ */
+export default function gitlabFormatter(results, returnValue) {
+  const { CI_JOB_NAME, STYLELINT_CODE_QUALITY_REPORT, STYLELINT_FORMATTER } = getEnv();
+
+  if (CI_JOB_NAME || STYLELINT_CODE_QUALITY_REPORT) {
+    writeFileSync(
+      STYLELINT_CODE_QUALITY_REPORT || getOutputPath(),
+      JSON.stringify(convert(results), null, 2),
+    );
+  }
+
+  stylelint.formatters[STYLELINT_FORMATTER].then((fallbackFormatter) => {
+    console.log(fallbackFormatter(results, returnValue));
+  });
+}

package/src/types.d.ts

@@ -0,0 +1,31 @@
+import type { Formatters } from 'stylelint';
+
+export interface FileInfo {
+  filename: string;
+  input: string;
+  output: string;
+  isFormatted: boolean;
+}
+
+export interface CodeQualityReport {
+  type: 'issue';
+  check_name: string;
+  description: string;
+  severity: string;
+  fingerprint: string;
+  location: {
+    path: string;
+    lines: {
+      begin: number;
+      end: number;
+    };
+  };
+}
+
+export interface Env {
+  CI_CONFIG_PATH: string;
+  CI_JOB_NAME: string;
+  CI_PROJECT_DIR: string;
+  STYLELINT_CODE_QUALITY_REPORT: string;
+  STYLELINT_FORMATTER: keyof Formatters;
+}

package/src/utils.js

@@ -0,0 +1,120 @@
+import { createHash } from 'node:crypto';
+import { join, resolve, relative } from 'node:path';
+import { readFileSync } from 'node:fs';
+import isGlob from 'is-glob';
+import yaml from 'js-yaml';
+
+/**
+ * Get environment variables with sane defaults.
+ * @returns {import('./types.d.ts').Env}
+ */
+export function getEnv() {
+  const {
+    // Used as a fallback for local testing.
+    CI_CONFIG_PATH = '.gitlab-ci.yml',
+    CI_JOB_NAME,
+    CI_PROJECT_DIR = process.cwd(),
+    STYLELINT_CODE_QUALITY_REPORT,
+    STYLELINT_FORMATTER = 'string',
+  } = process.env;
+
+  return {
+    CI_CONFIG_PATH,
+    CI_JOB_NAME,
+    CI_PROJECT_DIR,
+    STYLELINT_CODE_QUALITY_REPORT,
+    STYLELINT_FORMATTER,
+  };
+}
+
+/**
+ * Get the output path.
+ * @returns {string}
+ */
+export function getOutputPath() {
+  const { CI_PROJECT_DIR, CI_CONFIG_PATH, CI_JOB_NAME } = getEnv();
+  const jobs = yaml.load(readFileSync(join(CI_PROJECT_DIR, CI_CONFIG_PATH), 'utf-8'));
+  const { artifacts } = jobs[CI_JOB_NAME];
+  const location = artifacts && artifacts.reports && artifacts.reports.codequality;
+  const msg = `Expected ${CI_JOB_NAME}.artifacts.reports.codequality to be one exact path`;
+  if (location === null || location === undefined) {
+    throw new Error(`${msg}, but no value was found.`);
+  }
+  if (Array.isArray(location)) {
+    throw new Error(`${msg}, but found an array instead.`);
+  }
+  if (typeof location !== 'string') {
+    throw new Error(`${msg}, but found ${JSON.stringify(location)} instead.`);
+  }
+  if (isGlob(location)) {
+    throw new Error(`${msg}, but found a glob instead.`);
+  }
+  return resolve(CI_PROJECT_DIR, location);
+}
+
+/**
+ * Create fingerprint.
+ * @param   {string} filePath
+ * @param   {string} message
+ * @returns {string}
+ */
+export function createFingerprint(filePath, message) {
+  const md5 = createHash('md5');
+  md5.update(filePath);
+  if (message.rule) {
+    md5.update(message.rule);
+  }
+  md5.update(message.text);
+  return md5.digest('hex');
+}
+
+/**
+ * Map severity.
+ * @param   {string} severity
+ * @returns {string}
+ */
+export function mapSeverity(severity) {
+  switch (severity) {
+    case 'error':
+      return 'major';
+    case 'warning':
+      return 'minor';
+    default:
+      return 'minor';
+  }
+}
+
+/**
+ * @param {import('stylelint').Warning[]} results
+ * @param {string} source
+ * @returns {import('./types.d.ts').CodeQualityReport[]}
+ */
+function formatter(results, source) {
+  const { CI_PROJECT_DIR } = getEnv();
+  const relativePath = relative(CI_PROJECT_DIR, source);
+  return results.map((result) => ({
+    type: 'issue',
+    check_name: result.rule,
+    severity: mapSeverity(result.severity),
+    description: result.text,
+    fingerprint: createFingerprint(relativePath, result),
+    location: {
+      path: relativePath,
+      lines: {
+        begin: result.line,
+        end: result.line,
+      },
+    },
+  }));
+}
+
+/**
+ * @param {import('stylelint').LintResult[]} results
+ * @returns {object[]}
+ */
+export function convert(results) {
+  return results.reduce(
+    (acc, result) => [...acc, ...formatter(result.warnings, result.source)],
+    [],
+  );
+}