chore: add eslint formatter for multiple formats (#1090)

This PR includes:
- added MVP custom lint formatter under tools
- add `lint-report` to `nx.json#defaultTargets`

Task Graph:
<img width="1324" height="327" alt="Screenshot 2025-09-02 at 13 51 18"
src="https://github.com/user-attachments/assets/bf535954-a556-412b-a815-928d1c6aedca"
/>

> [!note]
> This enables us to reuse the lint work. We always create json +
terminal output and in the conformance target we just depend on the
targets and consume the output. In the past we where running the lint
work 2 times as it is not possible to get terminal for DX and json for
conformance

Related:
- #1068

---------

Co-authored-by: Matěj Chalk <34691111+matejchalk@users.noreply.github.com>

Author: BioPhoton

code-pushup.preset.ts

@@ -177,7 +177,13 @@ export const eslintCoreConfigNx = async (
           eslintrc: `packages/${projectName}/eslint.config.js`,
           patterns: ['.'],
         })
-      : await eslintPlugin(await eslintConfigFromAllNxProjects()),
+      : await eslintPlugin(await eslintConfigFromAllNxProjects(), {
+          artifacts: {
+            // We leverage Nx dependsOn to only run all lint targets before we run code-pushup
+            // generateArtifactsCommand: 'npx nx run-many -t lint',
+            artifactsPaths: ['packages/**/.eslint/eslint-report.json'],
+          },
+        }),
   ],
   categories: eslintCategories,
 });

nx.json

@@ -49,12 +49,40 @@
       }
     ],
     "sharedGlobals": [
-      { "runtime": "node -e \"console.log(require('os').platform())\"" },
-      { "runtime": "node -v" },
-      { "runtime": "npm -v" }
+      {
+        "runtime": "node -e \"console.log(require('os').platform())\""
+      },
+      {
+        "runtime": "node -v"
+      },
+      {
+        "runtime": "npm -v"
+      }
     ]
   },
   "targetDefaults": {
+    "lint": {
+      "dependsOn": ["eslint-formatter-multi:build"],
+      "inputs": ["lint-eslint-inputs"],
+      "outputs": ["{projectRoot}/.eslint/**/*"],
+      "cache": true,
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "eslint",
+        "args": [
+          "{projectRoot}/**/*.ts",
+          "{projectRoot}/package.json",
+          "--config={projectRoot}/eslint.config.js",
+          "--max-warnings=0",
+          "--no-warn-ignored",
+          "--error-on-unmatched-pattern=false",
+          "--format=./tools/eslint-formatter-multi/dist/src/index.js"
+        ],
+        "env": {
+          "ESLINT_FORMATTER_CONFIG": "{\"outputDir\":\"{projectRoot}/.eslint\"}"
+        }
+      }
+    },
     "build": {
       "dependsOn": ["^build"],
       "inputs": ["production", "^production"],
@@ -97,36 +125,6 @@
       "inputs": ["default"],
       "cache": true
     },
-    "lint": {
-      "inputs": ["lint-eslint-inputs"],
-      "executor": "@nx/eslint:lint",
-      "outputs": ["{options.outputFile}"],
-      "cache": true,
-      "options": {
-        "errorOnUnmatchedPattern": false,
-        "maxWarnings": 0,
-        "lintFilePatterns": [
-          "{projectRoot}/**/*.ts",
-          "{projectRoot}/package.json"
-        ]
-      }
-    },
-    "lint-report": {
-      "inputs": ["default", "{workspaceRoot}/eslint.config.?(c)js"],
-      "outputs": ["{projectRoot}/.eslint/eslint-report*.json"],
-      "cache": true,
-      "executor": "@nx/linter:eslint",
-      "options": {
-        "errorOnUnmatchedPattern": false,
-        "maxWarnings": 0,
-        "format": "json",
-        "outputFile": "{projectRoot}/.eslint/eslint-report.json",
-        "lintFilePatterns": [
-          "{projectRoot}/**/*.ts",
-          "{projectRoot}/package.json"
-        ]
-      }
-    },
     "nxv-pkg-install": {
       "parallelism": false
     },

packages/plugin-eslint/src/lib/runner/lint.ts

@@ -25,7 +25,7 @@ async function executeLint({
   patterns,
 }: ESLintTarget): Promise<ESLint.LintResult[]> {
   // running as CLI because ESLint#lintFiles() runs out of memory
-  const { stdout } = await executeProcess({
+  const { stdout, stderr, code } = await executeProcess({
     command: 'npx',
     args: [
       'eslint',
@@ -42,6 +42,12 @@ async function executeLint({
     cwd: process.cwd(),
   });
 
+  if (!stdout.trim()) {
+    throw new Error(
+      `ESLint produced empty output. Exit code: ${code}, STDERR: ${stderr}`,
+    );
+  }
+
   return JSON.parse(stdout) as ESLint.LintResult[];
 }
 

project.json

@@ -16,7 +16,14 @@
         }
       ]
     },
-    "code-pushup-eslint": {},
+    "code-pushup-eslint": {
+      "dependsOn": [
+        {
+          "target": "lint",
+          "projects": "*"
+        }
+      ]
+    },
     "code-pushup-jsdocs": {},
     "code-pushup-typescript": {},
     "code-pushup": {

tools/eslint-formatter-multi/README.md

@@ -0,0 +1,77 @@
+# ESLint Multi Formatter
+
+The ESLint plugin uses a custom formatter that supports multiple output formats and destinations simultaneously.
+
+## Configuration
+
+Use the `ESLINT_FORMATTER_CONFIG` environment variable to configure the formatter with JSON.
+
+### Configuration Schema
+
+```jsonc
+{
+  "outputDir": "./reports", // Optional: Output directory (default: cwd/.eslint)
+  "filename": "eslint-report", // Optional: Base filename without extension (default: 'eslint-report')
+  "formats": ["json"], // Optional: Array of format names for file output (default: ['json'])
+  "terminal": "stylish", // Optional: Format for terminal output (default: 'stylish')
+  "verbose": true, // Optional: Enable verbose logging (default: false)
+}
+```
+
+### Supported Formats
+
+The following ESLint formatters are supported:
+
+- `stylish` (default terminal output)
+- `json` (default file output)
+- Custom formatters (fallback to stylish formatting)
+
+## Usage Examples
+
+### Basic Usage
+
+```bash
+# Default behavior - JSON file output + stylish console output
+npx eslint .
+
+# Custom output directory and filename
+ESLINT_FORMATTER_CONFIG='{"outputDir":"./ci-reports","filename":"lint-results"}' npx eslint .
+# Creates: ci-reports/lint-results.json + terminal output
+```
+
+### Multiple Output Formats
+
+```bash
+# Generate JSON file
+ESLINT_FORMATTER_CONFIG='{"formats":["json"],"terminal":"stylish"}' npx eslint .
+# Creates: .eslint/eslint-report.json + terminal output
+
+# Custom directory with JSON format
+ESLINT_FORMATTER_CONFIG='{"outputDir":"./reports","filename":"eslint-results","formats":["json"]}' npx eslint .
+# Creates: reports/eslint-results.json
+```
+
+### Terminal Output Only
+
+```bash
+# Only show terminal output, no files
+ESLINT_FORMATTER_CONFIG='{"formats":[],"terminal":"stylish"}' npx eslint .
+
+# Different terminal format
+ESLINT_FORMATTER_CONFIG='{"formats":[],"terminal":"stylish"}' npx eslint .
+```
+
+## Default Behavior
+
+When no `ESLINT_FORMATTER_CONFIG` is provided, the formatter uses these defaults:
+
+- **outputDir**: `./.eslint` (relative to current working directory)
+- **filename**: `eslint-report`
+- **formats**: `["json"]`
+- **terminal**: `stylish`
+- **verbose**: `false`
+
+This means by default you get:
+
+- A JSON file at `./.eslint/eslint-report.json`
+- Stylish terminal output

tools/eslint-formatter-multi/eslint.config.js

@@ -0,0 +1,21 @@
+import tseslint from 'typescript-eslint';
+import baseConfig from '../../eslint.config.js';
+
+export default tseslint.config(
+  ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': ['error'],
+    },
+  },
+);

tools/eslint-formatter-multi/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@code-pushup/eslint-formatter-multi",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "engines": {
+    "node": ">=17.0.0"
+  },
+  "description": "ESLint formatter that supports multiple output formats and destinations simultaneously",
+  "author": "Michael Hladky",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/code-pushup/cli.git",
+    "directory": "tools/eslint-formatter-multi"
+  },
+  "keywords": [
+    "eslint",
+    "eslint-formatter",
+    "eslintformatter",
+    "multi-format",
+    "code-quality",
+    "linting"
+  ],
+  "files": [
+    "src/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ansis": "^3.3.0",
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "eslint": "^8.0.0 || ^9.0.0"
+  }
+}

tools/eslint-formatter-multi/project.json

@@ -0,0 +1,12 @@
+{
+  "name": "eslint-formatter-multi",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "tools/eslint-formatter-multi/src",
+  "projectType": "library",
+  "tags": ["scope:tooling", "type:util"],
+  "targets": {
+    "lint": {},
+    "unit-test": {},
+    "build": {}
+  }
+}

tools/eslint-formatter-multi/src/index.ts

@@ -0,0 +1,3 @@
+export { default } from './lib/multiple-formats.js';
+export * from './lib/multiple-formats.js';
+export * from './lib/utils.js';

tools/eslint-formatter-multi/src/lib/multiple-formats.ts

@@ -0,0 +1,83 @@
+import type { ESLint } from 'eslint';
+import * as process from 'node:process';
+import type { FormatterConfig } from './types.js';
+import {
+  type EslintFormat,
+  formatTerminalOutput,
+  findConfigFromEnv as getConfigFromEnv,
+  persistEslintReports,
+} from './utils.js';
+
+export const DEFAULT_OUTPUT_DIR = '.eslint';
+export const DEFAULT_FILENAME = 'eslint-report';
+export const DEFAULT_FORMATS = ['json'] as EslintFormat[];
+export const DEFAULT_TERMINAL = 'stylish' as EslintFormat;
+
+export const DEFAULT_CONFIG: Required<
+  Pick<
+    FormatterConfig,
+    'outputDir' | 'filename' | 'formats' | 'terminal' | 'verbose'
+  >
+> = {
+  outputDir: DEFAULT_OUTPUT_DIR,
+  filename: DEFAULT_FILENAME,
+  formats: DEFAULT_FORMATS,
+  terminal: DEFAULT_TERMINAL,
+  verbose: false,
+};
+
+/**
+ * Format ESLint results using multiple configurable formatters
+ *
+ * @param results - The ESLint results
+ * @param args - The arguments passed to the formatter
+ * @returns The formatted results for terminal display
+ *
+ * @example
+ * // Basic usage:
+ * ESLINT_FORMATTER_CONFIG='{"filename":"lint-results","formats":["json"],"terminal":"stylish"}' npx eslint .
+ * // Creates: .eslint/eslint-results.json + terminal output
+ *
+ * // With custom output directory:
+ * ESLINT_FORMATTER_CONFIG='{"outputDir":"./ci-reports","filename":"eslint-report","formats":["json","html"],"terminal":"stylish"}' nx lint utils
+ * // Creates: ci-reports/eslint-report.json, ci-reports/eslint-report.html + terminal output
+ *
+ * Configuration schema:
+ * {
+ *   "outputDir": "./reports",           // Optional: Output directory (default: cwd/.eslint)
+ *   "filename": "eslint-report",        // Optional: Base filename without extension (default: 'eslint-report')
+ *   "formats": ["json"],        // Optional: Array of format names for file output (default: ['json'])
+ *   "terminal": "stylish"               // Optional: Format for terminal output (default: 'stylish')
+ * }
+ */
+export default async function multipleFormats(
+  results: ESLint.LintResult[],
+  _args?: unknown,
+): Promise<string> {
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...getConfigFromEnv(process.env),
+  } satisfies FormatterConfig;
+
+  const {
+    outputDir = DEFAULT_OUTPUT_DIR,
+    filename,
+    formats,
+    terminal,
+    verbose = false,
+  } = config;
+
+  try {
+    await persistEslintReports(formats, results, {
+      outputDir,
+      filename,
+      verbose,
+    });
+  } catch (error) {
+    if (verbose) {
+      console.error('Error writing ESLint reports:', error);
+    }
+  }
+
+  return formatTerminalOutput(terminal, results);
+}