Merge branch 'main' into extend-utils

# Conflicts:
#	packages/utils/src/index.ts

Author: BioPhoton

code-pushup.config.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import {
   coverageCoreConfigNx,
   eslintCoreConfigNx,
+  jsDocsCoreConfig,
   jsPackagesCoreConfig,
   lighthouseCoreConfig,
 } from './code-pushup.preset.js';
@@ -39,4 +40,12 @@ export default mergeConfigs(
     'https://github.com/code-pushup/cli?tab=readme-ov-file#code-pushup-cli/',
   ),
   await eslintCoreConfigNx(),
+  jsDocsCoreConfig([
+    'packages/**/src/**/*.ts',
+    '!packages/**/node_modules',
+    '!packages/**/{mocks,mock}',
+    '!**/*.{spec,test}.ts',
+    '!**/implementation/**',
+    '!**/internal/**',
+  ]),
 );

code-pushup.preset.ts

@@ -10,6 +10,14 @@ import eslintPlugin, {
   eslintConfigFromNxProject,
 } from './packages/plugin-eslint/src/index.js';
 import jsPackagesPlugin from './packages/plugin-js-packages/src/index.js';
+import jsDocsPlugin, {
+  JsDocsPluginConfig,
+} from './packages/plugin-jsdocs/src/index.js';
+import {
+  PLUGIN_SLUG,
+  groups,
+} from './packages/plugin-jsdocs/src/lib/constants.js';
+import { filterGroupsByOnlyAudits } from './packages/plugin-jsdocs/src/lib/utils.js';
 import lighthousePlugin, {
   lighthouseGroupRef,
 } from './packages/plugin-lighthouse/src/index.js';
@@ -82,6 +90,24 @@ export const eslintCategories: CategoryConfig[] = [
   },
 ];
 
+export function getJsDocsCategories(
+  config: JsDocsPluginConfig,
+): CategoryConfig[] {
+  return [
+    {
+      slug: 'docs',
+      title: 'Documentation',
+      description: 'Measures how much of your code is **documented**.',
+      refs: filterGroupsByOnlyAudits(groups, config).map(group => ({
+        weight: 1,
+        type: 'group',
+        plugin: PLUGIN_SLUG,
+        slug: group.slug,
+      })),
+    },
+  ];
+}
+
 export const coverageCategories: CategoryConfig[] = [
   {
     slug: 'code-coverage',
@@ -114,6 +140,19 @@ export const lighthouseCoreConfig = async (
   };
 };
 
+export const jsDocsCoreConfig = (
+  config: JsDocsPluginConfig | string[],
+): CoreConfig => {
+  return {
+    plugins: [
+      jsDocsPlugin(Array.isArray(config) ? { patterns: config } : config),
+    ],
+    categories: getJsDocsCategories(
+      Array.isArray(config) ? { patterns: config } : config,
+    ),
+  };
+};
+
 export const eslintCoreConfigNx = async (
   projectName?: string,
 ): Promise<CoreConfig> => {

e2e/nx-plugin-e2e/tests/executor-cli.e2e.test.ts

@@ -2,7 +2,10 @@ import { type Tree, updateProjectConfiguration } from '@nx/devkit';
 import path from 'node:path';
 import { readProjectConfiguration } from 'nx/src/generators/utils/project-configuration';
 import { afterEach, expect } from 'vitest';
-import { generateCodePushupConfig } from '@code-pushup/nx-plugin';
+import {
+  type AutorunCommandExecutorOptions,
+  generateCodePushupConfig,
+} from '@code-pushup/nx-plugin';
 import {
   generateWorkspaceAndProject,
   materializeTree,
@@ -20,6 +23,7 @@ import { INLINE_PLUGIN } from './inline-plugin.js';
 async function addTargetToWorkspace(
   tree: Tree,
   options: { cwd: string; project: string },
+  executorOptions?: AutorunCommandExecutorOptions,
 ) {
   const { cwd, project } = options;
   const projectCfg = readProjectConfiguration(tree, project);
@@ -29,6 +33,7 @@ async function addTargetToWorkspace(
       ...projectCfg.targets,
       'code-pushup': {
         executor: '@code-pushup/nx-plugin:cli',
+        ...(executorOptions && { options: executorOptions }),
       },
     },
   });
@@ -95,6 +100,42 @@ describe('executor command', () => {
     ).rejects.toThrow('');
   });
 
+  it('should execute collect executor and merge target and command-line options', async () => {
+    const cwd = path.join(testFileDir, 'execute-collect-with-merged-options');
+    await addTargetToWorkspace(
+      tree,
+      { cwd, project },
+      {
+        persist: {
+          outputDir: '.reports',
+          filename: 'report',
+        },
+      },
+    );
+
+    const { stdout, code } = await executeProcess({
+      command: 'npx',
+      args: [
+        'nx',
+        'run',
+        `${project}:code-pushup`,
+        'collect',
+        '--persist.filename=terminal-report',
+      ],
+      cwd,
+    });
+
+    expect(code).toBe(0);
+    const cleanStdout = removeColorCodes(stdout);
+    expect(cleanStdout).toContain(
+      'nx run my-lib:code-pushup collect --persist.filename=terminal-report',
+    );
+
+    await expect(
+      readJsonFile(path.join(cwd, '.reports', 'terminal-report.json')),
+    ).resolves.not.toThrow();
+  });
+
   it('should execute collect executor and add report to sub folder named by project', async () => {
     const cwd = path.join(testFileDir, 'execute-collect-command');
     await addTargetToWorkspace(tree, { cwd, project });

e2e/plugin-jsdocs-e2e/eslint.config.js

@@ -0,0 +1,12 @@
+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,
+    },
+  },
+});

e2e/plugin-jsdocs-e2e/mocks/fixtures/angular/code-pushup.config.ts

@@ -0,0 +1,5 @@
+import jsDocsPlugin from '@code-pushup/jsdocs-plugin';
+
+export default {
+  plugins: [jsDocsPlugin(['**/*.ts'])],
+};

e2e/plugin-jsdocs-e2e/mocks/fixtures/angular/src/app.component.css

@@ -0,0 +1,4 @@
+h1 {
+  color: #336699;
+  text-align: center;
+}

e2e/plugin-jsdocs-e2e/mocks/fixtures/angular/src/app.component.html

@@ -0,0 +1 @@
+<h1>{{ title }}</h1>

e2e/plugin-jsdocs-e2e/mocks/fixtures/angular/src/app.component.spec.ts

@@ -0,0 +1,3 @@
+function notRealisticFunction() {
+  return 'notRealisticFunction';
+}

e2e/plugin-jsdocs-e2e/mocks/fixtures/angular/src/app.component.ts

@@ -0,0 +1,18 @@
+/**
+ * Basic Angular component that displays a welcome message
+ */
+export class AppComponent {
+  protected readonly title = 'My Angular App';
+
+  /**
+   * Dummy method that returns a welcome message
+   * @returns {string} - The welcome message
+   */
+  getWelcomeMessage() {
+    return 'Welcome to My Angular App!';
+  }
+
+  sendEvent() {
+    return 'Event sent';
+  }
+}

e2e/plugin-jsdocs-e2e/mocks/fixtures/angular/src/map-event.function.ts

@@ -0,0 +1,10 @@
+export const someVariable = 'Hello World 1';
+
+export function mapEventToCustomEvent(event: string) {
+  return event;
+}
+
+/** Commented */
+export function mapCustomEventToEvent(event: string) {
+  return event;
+}