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

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-doc-coverage-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-doc-coverage-e2e/mocks/fixtures/angular/code-pushup.config.ts

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

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

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

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

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

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

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

e2e/plugin-doc-coverage-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-doc-coverage-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-doc-coverage-e2e/mocks/fixtures/react/code-pushup.config.ts

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

e2e/plugin-doc-coverage-e2e/mocks/fixtures/react/component.js

@@ -0,0 +1,10 @@
+function MyComponent() {
+  return (
+    <div>
+      <h1>Hello World</h1>
+      <p>This is a basic React component</p>
+    </div>
+  );
+}
+
+export default MyComponent;

e2e/plugin-doc-coverage-e2e/project.json

@@ -0,0 +1,23 @@
+{
+  "name": "plugin-doc-coverage-e2e",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "e2e/plugin-doc-coverage-e2e/src",
+  "projectType": "application",
+  "tags": ["scope:plugin", "type:e2e"],
+  "implicitDependencies": ["cli", "plugin-jsdocs"],
+  "targets": {
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["e2e/plugin-doc-coverage-e2e/**/*.ts"]
+      }
+    },
+    "e2e": {
+      "executor": "@nx/vite:test",
+      "options": {
+        "configFile": "e2e/plugin-doc-coverage-e2e/vite.config.e2e.ts"
+      }
+    }
+  }
+}

e2e/plugin-doc-coverage-e2e/tests/collect.e2e.test.ts

@@ -0,0 +1,72 @@
+import { cp } from 'node:fs/promises';
+import path from 'node:path';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { type Report, reportSchema } from '@code-pushup/models';
+import { nxTargetProject } from '@code-pushup/test-nx-utils';
+import { teardownTestFolder } from '@code-pushup/test-setup';
+import {
+  E2E_ENVIRONMENTS_DIR,
+  TEST_OUTPUT_DIR,
+  omitVariableReportData,
+  removeColorCodes,
+} from '@code-pushup/test-utils';
+import { executeProcess, readJsonFile } from '@code-pushup/utils';
+
+describe('PLUGIN collect report with doc-coverage-plugin NPM package', () => {
+  const fixturesDir = path.join(
+    'e2e',
+    'plugin-doc-coverage-e2e',
+    'mocks',
+    'fixtures',
+  );
+  const fixturesAngularDir = path.join(fixturesDir, 'angular');
+  const fixturesReactDir = path.join(fixturesDir, 'react');
+
+  const envRoot = path.join(
+    E2E_ENVIRONMENTS_DIR,
+    nxTargetProject(),
+    TEST_OUTPUT_DIR,
+  );
+  const angularDir = path.join(envRoot, 'angular');
+  const reactDir = path.join(envRoot, 'react');
+  const angularOutputDir = path.join(angularDir, '.code-pushup');
+  const reactOutputDir = path.join(reactDir, '.code-pushup');
+
+  beforeAll(async () => {
+    await cp(fixturesAngularDir, angularDir, { recursive: true });
+    await cp(fixturesReactDir, reactDir, { recursive: true });
+  });
+
+  afterAll(async () => {
+    await teardownTestFolder(angularDir);
+    await teardownTestFolder(reactDir);
+  });
+
+  afterEach(async () => {
+    await teardownTestFolder(angularOutputDir);
+    await teardownTestFolder(reactOutputDir);
+  });
+
+  it('should run Doc Coverage plugin for Angular example dir and create report.json', async () => {
+    const { code, stdout } = await executeProcess({
+      command: 'npx',
+      args: ['@code-pushup/cli', 'collect', '--no-progress'],
+      cwd: angularDir,
+    });
+
+    expect(code).toBe(0);
+
+    expect(removeColorCodes(stdout)).toMatchFileSnapshot(
+      '__snapshots__/report.txt',
+    );
+
+    const report = await readJsonFile(
+      path.join(angularOutputDir, 'report.json'),
+    );
+
+    expect(() => reportSchema.parse(report)).not.toThrow();
+    expect(
+      JSON.stringify(omitVariableReportData(report as Report), null, 2),
+    ).toMatchFileSnapshot('__snapshots__/report.json');
+  });
+});

e2e/plugin-doc-coverage-e2e/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["vitest"]
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.test.json"
+    }
+  ]
+}

e2e/plugin-doc-coverage-e2e/tsconfig.test.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "types": ["vitest/globals", "vitest/importMeta", "vite/client", "node"],
+    "target": "ES2020"
+  },
+  "exclude": ["__test-env__/**"],
+  "include": [
+    "vite.config.e2e.ts",
+    "tests/**/*.e2e.test.ts",
+    "tests/**/*.d.ts",
+    "mocks/**/*.ts"
+  ]
+}

e2e/plugin-doc-coverage-e2e/vite.config.e2e.ts

@@ -0,0 +1,21 @@
+/// <reference types="vitest" />
+import { defineConfig } from 'vite';
+import { tsconfigPathAliases } from '../../tools/vitest-tsconfig-path-aliases.js';
+
+export default defineConfig({
+  cacheDir: '../../node_modules/.vite/plugin-doc-coverage-e2e',
+  test: {
+    reporters: ['basic'],
+    testTimeout: 120_000,
+    globals: true,
+    alias: tsconfigPathAliases(),
+    pool: 'threads',
+    poolOptions: { threads: { singleThread: true } },
+    cache: {
+      dir: '../../node_modules/.vitest',
+    },
+    environment: 'node',
+    include: ['tests/**/*.e2e.test.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    setupFiles: ['../../testing/test-setup/src/lib/reset.mocks.ts'],
+  },
+});