feat(plugin-jsdocs): add plugin-jsdocs to analyze documentation in ts/js projects (#896)

Author: aramirezj

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/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;
+}

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

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