@code-pushup/jsdocs-plugin 0.58.0

package/README.md

@@ -0,0 +1,241 @@
+# @code-pushup/jsdocs-plugin
+
+[![npm](https://img.shields.io/npm/v/%40code-pushup%2Fjsdocs-plugin.svg)](https://www.npmjs.com/package/@code-pushup/jsdocs-plugin)
+[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Fjsdocs-plugin)](https://npmtrends.com/@code-pushup/jsdocs-plugin)
+[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup%2Fjsdocs-plugin)](https://www.npmjs.com/package/@code-pushup/jsdocs-plugin?activeTab=dependencies)
+
+📚 **Code PushUp plugin for tracking documentation coverage.** 📝
+
+This plugin allows you to measure and track documentation coverage in your TypeScript/JavaScript project.
+It analyzes your codebase and checks for documentation on different code elements like classes, functions, interfaces, types, and variables.
+
+Measured documentation types are mapped to Code PushUp audits in the following way:
+
+- `value`: The value is the number of undocumented nodes -> 4
+- `displayValue`: `${value} undocumented ${type}` -> 4 undocumented functions
+- `score`: 0.5 -> total nodes 8, undocumented 4 -> 4/8
+- The score is value converted to 0-1 range
+- Missing documentation is mapped to issues in the audit details (undocumented classes, functions, interfaces, etc.)
+
+## Getting started
+
+1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
+
+2. Install as a dev dependency with your package manager:
+
+   ```sh
+   npm install --save-dev @code-pushup/jsdocs-plugin
+   ```
+
+   ```sh
+   yarn add --dev @code-pushup/jsdocs-plugin
+   ```
+
+   ```sh
+   pnpm add --save-dev @code-pushup/jsdocs-plugin
+   ```
+
+3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.ts`).
+
+   ```js
+   import jsDocsPlugin from '@code-pushup/jsdocs-plugin';
+
+   export default {
+     // ...
+     plugins: [
+       // ...
+       jsDocsPlugin(['**/*.ts']),
+     ],
+   };
+   ```
+
+4. (Optional) Reference individual audits or the provided plugin group which you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
+
+   💡 Assign weights based on what influence each documentation type should have on the overall category score (assign weight 0 to only include as extra info, without influencing category score).
+
+   ```js
+   export default {
+     // ...
+     categories: [
+       {
+         slug: 'documentation',
+         title: 'Documentation',
+         refs: [
+           {
+             type: 'group',
+             plugin: 'jsdocs',
+             slug: 'jsdocs',
+             weight: 1,
+           },
+           // ...
+         ],
+       },
+       // ...
+     ],
+   };
+   ```
+
+5. Run the CLI with `npx code-pushup collect` and view or upload report (refer to [CLI docs](../cli/README.md)).
+
+## About documentation coverage
+
+Documentation coverage is a metric that indicates what percentage of your code elements have proper documentation. It helps ensure your codebase is well-documented and maintainable.
+
+The plugin provides multiple audits, one for each documentation type (classes, functions, interfaces, etc.), and groups them together for an overall documentation coverage measurement. Each audit:
+
+- Measures the documentation coverage for its specific type (e.g., classes, functions)
+- Provides a score based on the percentage of documented elements
+- Includes details about which elements are missing documentation
+
+These audits are grouped together to provide a comprehensive view of your codebase's documentation status. You can use either:
+
+- The complete group of audits for overall documentation coverage
+- Individual audits to focus on specific documentation types
+
+## Plugin architecture
+
+### Plugin configuration specification
+
+The plugin accepts the following parameters:
+
+#### patterns
+
+Required parameter. The `patterns` option accepts an array of strings that define patterns to include or exclude files. You can use glob patterns to match files and the `!` symbol to exclude specific patterns. Example:
+
+```js
+jsDocsPlugin({
+  patterns: [
+    'src/**/*.ts',              // include all TypeScript files in src
+    '!src/**/*.{spec,test}.ts', // exclude test files
+    '!src/**/testing/**/*.ts'   // exclude testing utilities
+  ],
+}),
+```
+
+#### OnlyAudits
+
+Optional parameter. The `onlyAudits` option allows you to specify which documentation types you want to measure. Only the specified audits will be included in the results. Example:
+
+```js
+jsDocsPlugin({
+  patterns: ['src/**/*.ts'],
+  onlyAudits: [
+    'classes-coverage',
+    'functions-coverage'
+  ] // Only measure documentation for classes and functions
+}),
+```
+
+#### SkipAudits
+
+Optional parameter. The `skipAudits` option allows you to exclude specific documentation types from measurement. All other types will be included in the results.
+
+```js
+jsDocsPlugin({
+  patterns: ['src/**/*.ts'],
+  skipAudits: [
+    'variables-coverage',
+    'interfaces-coverage'
+  ] // Measure all documentation types except variables and interfaces
+}),
+```
+
+> ⚠️ **Warning:** You cannot use both `onlyAudits` and `skipAudits` in the same configuration. Choose the one that better suits your needs.
+
+### Audits and group
+
+This plugin provides a group for convenient declaration in your config. When defined this way, all measured documentation type audits have the same weight.
+
+```ts
+     // ...
+     categories: [
+       {
+         slug: 'documentation',
+         title: 'Documentation',
+         refs: [
+           {
+             type: 'group',
+             plugin: 'jsdocs',
+             slug: 'jsdocs',
+             weight: 1,
+           },
+           // ...
+         ],
+       },
+       // ...
+     ],
+```
+
+Each documentation type still has its own audit. So when you want to include a subset of documentation types or assign different weights to them, you can do so in the following way:
+
+```ts
+     // ...
+     categories: [
+       {
+         slug: 'documentation',
+         title: 'Documentation',
+         refs: [
+           {
+             type: 'audit',
+             plugin: 'jsdocs',
+             slug: 'class-jsdocs',
+             weight: 2,
+           },
+           {
+             type: 'audit',
+             plugin: 'jsdocs',
+             slug: 'function-jsdocs',
+             weight: 1,
+           },
+           // ...
+         ],
+       },
+       // ...
+     ],
+```
+
+### Audit output
+
+The plugin outputs a single audit that measures the overall documentation coverage percentage of your codebase.
+
+For instance, this is an example of the plugin output:
+
+```json
+{
+  "packageName": "@code-pushup/jsdocs-plugin",
+  "version": "0.57.0",
+  "title": "Documentation coverage",
+  "slug": "jsdocs",
+  "icon": "folder-src",
+  "duration": 920,
+  "date": "2024-12-17T16:45:28.581Z",
+  "audits": [
+    {
+      "slug": "percentage-coverage",
+      "displayValue": "16 %",
+      "value": 16,
+      "score": 0.16,
+      "details": {
+        "issues": []
+      },
+      "title": "Percentage of codebase with documentation",
+      "description": "Measures how many % of the codebase have documentation."
+    }
+  ],
+  "description": "Official Code PushUp documentation coverage plugin.",
+  "docsUrl": "https://www.npmjs.com/package/@code-pushup/jsdocs-plugin/",
+  "groups": [
+    {
+      "slug": "jsdocs",
+      "refs": [
+        {
+          "slug": "percentage-coverage",
+          "weight": 1
+        }
+      ],
+      "title": "Documentation coverage metrics",
+      "description": "Group containing all defined documentation coverage types as audits."
+    }
+  ]
+}
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@code-pushup/jsdocs-plugin",
+  "version": "0.58.0",
+  "description": "Code PushUp plugin for tracking documentation coverage 📚",
+  "license": "MIT",
+  "homepage": "https://github.com/code-pushup/cli/tree/main/packages/plugin-jsdocs#readme",
+  "bugs": {
+    "url": "https://github.com/code-pushup/cli/issues?q=is%3Aissue%20state%3Aopen%20type%3ABug%20label%3A\"🧩%20jsdocs-plugin\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/code-pushup/cli.git",
+    "directory": "packages/plugin-jsdocs"
+  },
+  "keywords": [
+    "documentation coverage",
+    "documentation quality",
+    "docs completeness",
+    "automated documentation checks",
+    "coverage audit",
+    "documentation conformance",
+    "docs KPI tracking",
+    "documentation feedback",
+    "actionable documentation insights",
+    "documentation regression guard",
+    "documentation score monitoring",
+    "developer documentation tools",
+    "plugin for documentation coverage",
+    "CLI documentation coverage",
+    "Code PushUp documentation",
+    "documentation audit"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "dependencies": {
+    "@code-pushup/models": "0.58.0",
+    "@code-pushup/utils": "0.58.0",
+    "zod": "^3.22.4",
+    "ts-morph": "^24.0.0"
+  },
+  "module": "./src/index.js",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+import { jsDocsPlugin } from './lib/jsdocs-plugin.js';
+export default jsDocsPlugin;
+export type { JsDocsPluginConfig } from './lib/config.js';

package/src/index.js

@@ -0,0 +1,3 @@
+import { jsDocsPlugin } from './lib/jsdocs-plugin.js';
+export default jsDocsPlugin;
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/plugin-jsdocs/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,eAAe,YAAY,CAAC"}

package/src/lib/config.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export declare const jsDocsPluginConfigSchema: z.ZodEffects<z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>, z.ZodEffects<z.ZodObject<{
+    skipAudits: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    onlyAudits: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    patterns: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+}, "strip", z.ZodTypeAny, {
+    patterns: string | string[];
+    skipAudits?: string[] | undefined;
+    onlyAudits?: string[] | undefined;
+}, {
+    patterns: string | string[];
+    skipAudits?: string[] | undefined;
+    onlyAudits?: string[] | undefined;
+}>, {
+    patterns: string | string[];
+    skipAudits?: string[] | undefined;
+    onlyAudits?: string[] | undefined;
+}, {
+    patterns: string | string[];
+    skipAudits?: string[] | undefined;
+    onlyAudits?: string[] | undefined;
+}>]>, {
+    patterns: string | string[];
+    skipAudits?: string[] | undefined;
+    onlyAudits?: string[] | undefined;
+}, string | string[] | {
+    patterns: string | string[];
+    skipAudits?: string[] | undefined;
+    onlyAudits?: string[] | undefined;
+}>;
+/** Type of the config that is passed to the plugin */
+export type JsDocsPluginConfig = z.input<typeof jsDocsPluginConfigSchema>;
+/** Same as JsDocsPluginConfig but processed so the config is already an object even if it was passed the array of patterns */
+export type JsDocsPluginTransformedConfig = z.infer<typeof jsDocsPluginConfigSchema>;

package/src/lib/config.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+const patternsSchema = z.union([z.string(), z.array(z.string()).min(1)], {
+    description: 'Glob pattern to match source files to evaluate.',
+});
+const jsDocsTargetObjectSchema = z
+    .object({
+    skipAudits: z
+        .array(z.string())
+        .optional()
+        .describe('List of audit slugs to exclude from evaluation. When specified, all audits except these will be evaluated.'),
+    onlyAudits: z
+        .array(z.string())
+        .optional()
+        .describe('List of audit slugs to evaluate. When specified, only these audits will be evaluated.'),
+    patterns: patternsSchema,
+})
+    .refine(data => !(data.skipAudits && data.onlyAudits), {
+    message: "You can't define 'skipAudits' and 'onlyAudits' simultaneously",
+    path: ['skipAudits', 'onlyAudits'],
+});
+export const jsDocsPluginConfigSchema = z
+    .union([patternsSchema, jsDocsTargetObjectSchema])
+    .transform(target => typeof target === 'string' || Array.isArray(target)
+    ? { patterns: target }
+    : target);
+//# sourceMappingURL=config.js.map

package/src/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../packages/plugin-jsdocs/src/lib/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE;IACvE,WAAW,EAAE,iDAAiD;CAC/D,CAAC,CAAC;AAEH,MAAM,wBAAwB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACN,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CACP,4GAA4G,CAC7G;IACH,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CACP,uFAAuF,CACxF;IACH,QAAQ,EAAE,cAAc;CACzB,CAAC;KACD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE;IACrD,OAAO,EAAE,+DAA+D;IACxE,IAAI,EAAE,CAAC,YAAY,EAAE,YAAY,CAAC;CACnC,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC;KACtC,KAAK,CAAC,CAAC,cAAc,EAAE,wBAAwB,CAAC,CAAC;KACjD,SAAS,CAAC,MAAM,CAAC,EAAE,CAClB,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;IACjD,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE;IACtB,CAAC,CAAC,MAAM,CACX,CAAC"}

package/src/lib/constants.d.ts

@@ -0,0 +1,5 @@
+import type { Audit, Group } from '@code-pushup/models';
+import type { AuditSlug } from './models.js';
+export declare const PLUGIN_SLUG = "jsdocs";
+export declare const AUDITS_MAP: Record<AuditSlug, Audit>;
+export declare const groups: Group[];

package/src/lib/constants.js

@@ -0,0 +1,61 @@
+export const PLUGIN_SLUG = 'jsdocs';
+export const AUDITS_MAP = {
+    'classes-coverage': {
+        slug: 'classes-coverage',
+        title: 'Classes coverage',
+        description: 'Documentation coverage of classes',
+    },
+    'methods-coverage': {
+        slug: 'methods-coverage',
+        title: 'Methods coverage',
+        description: 'Documentation coverage of methods',
+    },
+    'functions-coverage': {
+        slug: 'functions-coverage',
+        title: 'Functions coverage',
+        description: 'Documentation coverage of functions',
+    },
+    'interfaces-coverage': {
+        slug: 'interfaces-coverage',
+        title: 'Interfaces coverage',
+        description: 'Documentation coverage of interfaces',
+    },
+    'variables-coverage': {
+        slug: 'variables-coverage',
+        title: 'Variables coverage',
+        description: 'Documentation coverage of variables',
+    },
+    'properties-coverage': {
+        slug: 'properties-coverage',
+        title: 'Properties coverage',
+        description: 'Documentation coverage of properties',
+    },
+    'types-coverage': {
+        slug: 'types-coverage',
+        title: 'Types coverage',
+        description: 'Documentation coverage of types',
+    },
+    'enums-coverage': {
+        slug: 'enums-coverage',
+        title: 'Enums coverage',
+        description: 'Documentation coverage of enums',
+    },
+};
+export const groups = [
+    {
+        slug: 'documentation-coverage',
+        title: 'Documentation coverage',
+        description: 'Documentation coverage',
+        refs: Object.keys(AUDITS_MAP).map(slug => ({
+            slug,
+            weight: [
+                'classes-coverage',
+                'functions-coverage',
+                'methods-coverage',
+            ].includes(slug)
+                ? 2
+                : 1,
+        })),
+    },
+];
+//# sourceMappingURL=constants.js.map

package/src/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../packages/plugin-jsdocs/src/lib/constants.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC,MAAM,CAAC,MAAM,UAAU,GAA6B;IAClD,kBAAkB,EAAE;QAClB,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,kBAAkB;QACzB,WAAW,EAAE,mCAAmC;KACjD;IACD,kBAAkB,EAAE;QAClB,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,kBAAkB;QACzB,WAAW,EAAE,mCAAmC;KACjD;IACD,oBAAoB,EAAE;QACpB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EAAE,qCAAqC;KACnD;IACD,qBAAqB,EAAE;QACrB,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,sCAAsC;KACpD;IACD,oBAAoB,EAAE;QACpB,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EAAE,qCAAqC;KACnD;IACD,qBAAqB,EAAE;QACrB,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EAAE,sCAAsC;KACpD;IACD,gBAAgB,EAAE;QAChB,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,iCAAiC;KAC/C;IACD,gBAAgB,EAAE;QAChB,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,iCAAiC;KAC/C;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,MAAM,GAAY;IAC7B;QACE,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EAAE,wBAAwB;QACrC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzC,IAAI;YACJ,MAAM,EAAE;gBACN,kBAAkB;gBAClB,oBAAoB;gBACpB,kBAAkB;aACnB,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACd,CAAC,CAAC,CAAC;gBACH,CAAC,CAAC,CAAC;SACN,CAAC,CAAC;KACJ;CACF,CAAC"}

package/src/lib/jsdocs-plugin.d.ts

@@ -0,0 +1,22 @@
+import type { PluginConfig } from '@code-pushup/models';
+import { type JsDocsPluginConfig } from './config.js';
+export declare const PLUGIN_TITLE = "JSDoc coverage";
+export declare const PLUGIN_DESCRIPTION = "Official Code PushUp JSDoc coverage plugin.";
+export declare const PLUGIN_DOCS_URL = "https://www.npmjs.com/package/@code-pushup/jsdocs-plugin/";
+/**
+ * Instantiates Code PushUp documentation coverage plugin for core config.
+ *
+ * @example
+ * import jsDocsPlugin from '@code-pushup/jsdocs-plugin'
+ *
+ * export default {
+ *   // ... core config ...
+ *   plugins: [
+ *     // ... other plugins ...
+ *     jsDocsPlugin(['**/*.ts'])
+ *   ]
+ * }
+ *
+ * @returns Plugin configuration.
+ */
+export declare function jsDocsPlugin(config: JsDocsPluginConfig): PluginConfig;

package/src/lib/jsdocs-plugin.js

@@ -0,0 +1,37 @@
+import { jsDocsPluginConfigSchema } from './config.js';
+import { PLUGIN_SLUG, groups } from './constants.js';
+import { createRunnerFunction } from './runner/runner.js';
+import { filterAuditsByPluginConfig, filterGroupsByOnlyAudits, } from './utils.js';
+export const PLUGIN_TITLE = 'JSDoc coverage';
+export const PLUGIN_DESCRIPTION = 'Official Code PushUp JSDoc coverage plugin.';
+export const PLUGIN_DOCS_URL = 'https://www.npmjs.com/package/@code-pushup/jsdocs-plugin/';
+/**
+ * Instantiates Code PushUp documentation coverage plugin for core config.
+ *
+ * @example
+ * import jsDocsPlugin from '@code-pushup/jsdocs-plugin'
+ *
+ * export default {
+ *   // ... core config ...
+ *   plugins: [
+ *     // ... other plugins ...
+ *     jsDocsPlugin(['**/*.ts'])
+ *   ]
+ * }
+ *
+ * @returns Plugin configuration.
+ */
+export function jsDocsPlugin(config) {
+    const jsDocsConfig = jsDocsPluginConfigSchema.parse(config);
+    return {
+        slug: PLUGIN_SLUG,
+        title: PLUGIN_TITLE,
+        icon: 'folder-docs',
+        description: PLUGIN_DESCRIPTION,
+        docsUrl: PLUGIN_DOCS_URL,
+        groups: filterGroupsByOnlyAudits(groups, jsDocsConfig),
+        audits: filterAuditsByPluginConfig(jsDocsConfig),
+        runner: createRunnerFunction(jsDocsConfig),
+    };
+}
+//# sourceMappingURL=jsdocs-plugin.js.map

package/src/lib/jsdocs-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsdocs-plugin.js","sourceRoot":"","sources":["../../../../../packages/plugin-jsdocs/src/lib/jsdocs-plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE7C,MAAM,CAAC,MAAM,kBAAkB,GAAG,6CAA6C,CAAC;AAEhF,MAAM,CAAC,MAAM,eAAe,GAC1B,2DAA2D,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,MAAM,YAAY,GAAG,wBAAwB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5D,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,kBAAkB;QAC/B,OAAO,EAAE,eAAe;QACxB,MAAM,EAAE,wBAAwB,CAAC,MAAM,EAAE,YAAY,CAAC;QACtD,MAAM,EAAE,0BAA0B,CAAC,YAAY,CAAC;QAChD,MAAM,EAAE,oBAAoB,CAAC,YAAY,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/src/lib/models.d.ts

@@ -0,0 +1,2 @@
+import type { CoverageType } from './runner/models.js';
+export type AuditSlug = `${CoverageType}-coverage`;

package/src/lib/models.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=models.js.map

package/src/lib/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../../packages/plugin-jsdocs/src/lib/models.ts"],"names":[],"mappings":""}

package/src/lib/runner/constants.d.ts

@@ -0,0 +1,4 @@
+import { SyntaxKind } from 'ts-morph';
+import type { CoverageType } from './models.js';
+/** Maps the SyntaxKind from the library ts-morph to the coverage type. */
+export declare const SYNTAX_COVERAGE_MAP: Map<SyntaxKind, CoverageType>;

package/src/lib/runner/constants.js

@@ -0,0 +1,14 @@
+import { SyntaxKind } from 'ts-morph';
+/** Maps the SyntaxKind from the library ts-morph to the coverage type. */
+export const SYNTAX_COVERAGE_MAP = new Map([
+    [SyntaxKind.ClassDeclaration, 'classes'],
+    [SyntaxKind.MethodDeclaration, 'methods'],
+    [SyntaxKind.FunctionDeclaration, 'functions'],
+    [SyntaxKind.InterfaceDeclaration, 'interfaces'],
+    [SyntaxKind.EnumDeclaration, 'enums'],
+    [SyntaxKind.VariableDeclaration, 'variables'],
+    [SyntaxKind.VariableStatement, 'variables'],
+    [SyntaxKind.PropertyDeclaration, 'properties'],
+    [SyntaxKind.TypeAliasDeclaration, 'types'],
+]);
+//# sourceMappingURL=constants.js.map

package/src/lib/runner/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../../packages/plugin-jsdocs/src/lib/runner/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAA2B;IACnE,CAAC,UAAU,CAAC,gBAAgB,EAAE,SAAS,CAAC;IACxC,CAAC,UAAU,CAAC,iBAAiB,EAAE,SAAS,CAAC;IACzC,CAAC,UAAU,CAAC,mBAAmB,EAAE,WAAW,CAAC;IAC7C,CAAC,UAAU,CAAC,oBAAoB,EAAE,YAAY,CAAC;IAC/C,CAAC,UAAU,CAAC,eAAe,EAAE,OAAO,CAAC;IACrC,CAAC,UAAU,CAAC,mBAAmB,EAAE,WAAW,CAAC;IAC7C,CAAC,UAAU,CAAC,iBAAiB,EAAE,WAAW,CAAC;IAC3C,CAAC,UAAU,CAAC,mBAAmB,EAAE,YAAY,CAAC;IAC9C,CAAC,UAAU,CAAC,oBAAoB,EAAE,OAAO,CAAC;CAC3C,CAAC,CAAC"}

package/src/lib/runner/doc-processor.d.ts

@@ -0,0 +1,45 @@
+import { ClassDeclaration, JSDoc, SourceFile, SyntaxKind, VariableStatement } from 'ts-morph';
+import type { JsDocsPluginTransformedConfig } from '../config.js';
+import type { DocumentationCoverageReport, DocumentationReport } from './models.js';
+/**
+ * Gets the variables information from the variable statements
+ * @param variableStatements - The variable statements to process
+ * @returns The variables information with the right methods to get the information
+ */
+export declare function getVariablesInformation(variableStatements: VariableStatement[]): {
+    getName: () => string;
+    getKind: () => SyntaxKind;
+    getJsDocs: () => JSDoc[];
+    getStartLineNumber: () => number;
+}[];
+/**
+ * Processes documentation coverage for TypeScript files in the specified path
+ * @param config - The configuration object containing patterns to include for documentation analysis
+ * @returns Object containing coverage statistics and undocumented items
+ */
+export declare function processJsDocs(config: JsDocsPluginTransformedConfig): DocumentationCoverageReport;
+export declare function getAllNodesFromASourceFile(sourceFile: SourceFile): ({
+    getName: () => string;
+    getKind: () => SyntaxKind;
+    getJsDocs: () => JSDoc[];
+    getStartLineNumber: () => number;
+} | ClassDeclaration | import("ts-morph").FunctionDeclaration | import("ts-morph").MethodDeclaration | import("ts-morph").PropertyDeclaration | import("ts-morph").TypeAliasDeclaration | import("ts-morph").EnumDeclaration | import("ts-morph").InterfaceDeclaration)[];
+/**
+ * Gets the documentation coverage report from the source files
+ * @param sourceFiles - The source files to process
+ * @returns The documentation coverage report
+ */
+export declare function getDocumentationReport(sourceFiles: SourceFile[]): DocumentationCoverageReport;
+/**
+ * Merges two documentation results
+ * @param accumulatedReport - The first empty documentation result
+ * @param currentFileReport - The second documentation result
+ * @returns The merged documentation result
+ */
+export declare function mergeDocumentationReports(accumulatedReport: DocumentationReport, currentFileReport: Partial<DocumentationReport>): DocumentationReport;
+/**
+ * Gets the nodes from a class
+ * @param classNodes - The class nodes to process
+ * @returns The nodes from the class
+ */
+export declare function getClassNodes(classNodes: ClassDeclaration[]): (import("ts-morph").MethodDeclaration | import("ts-morph").PropertyDeclaration)[];

package/src/lib/runner/doc-processor.js

@@ -0,0 +1,120 @@
+import { ClassDeclaration, JSDoc, Project, SourceFile, SyntaxKind, VariableStatement, } from 'ts-morph';
+import { objectFromEntries, objectToEntries } from '@code-pushup/utils';
+import { calculateCoverage, createEmptyCoverageData, getCoverageTypeFromKind, } from './utils.js';
+/**
+ * Gets the variables information from the variable statements
+ * @param variableStatements - The variable statements to process
+ * @returns The variables information with the right methods to get the information
+ */
+export function getVariablesInformation(variableStatements) {
+    return variableStatements.flatMap(variable => {
+        // Get parent-level information
+        const parentInfo = {
+            getKind: () => variable.getKind(),
+            getJsDocs: () => variable.getJsDocs(),
+            getStartLineNumber: () => variable.getStartLineNumber(),
+        };
+        // Map each declaration to combine parent info with declaration-specific info
+        return variable.getDeclarations().map(declaration => ({
+            ...parentInfo,
+            getName: () => declaration.getName(),
+        }));
+    });
+}
+/**
+ * Processes documentation coverage for TypeScript files in the specified path
+ * @param config - The configuration object containing patterns to include for documentation analysis
+ * @returns Object containing coverage statistics and undocumented items
+ */
+export function processJsDocs(config) {
+    const project = new Project();
+    project.addSourceFilesAtPaths(config.patterns);
+    return getDocumentationReport(project.getSourceFiles());
+}
+export function getAllNodesFromASourceFile(sourceFile) {
+    const classes = sourceFile.getClasses();
+    return [
+        ...sourceFile.getFunctions(),
+        ...classes,
+        ...getClassNodes(classes),
+        ...sourceFile.getTypeAliases(),
+        ...sourceFile.getEnums(),
+        ...sourceFile.getInterfaces(),
+        ...getVariablesInformation(sourceFile.getVariableStatements()),
+    ];
+}
+/**
+ * Gets the documentation coverage report from the source files
+ * @param sourceFiles - The source files to process
+ * @returns The documentation coverage report
+ */
+export function getDocumentationReport(sourceFiles) {
+    const unprocessedCoverageReport = sourceFiles.reduce((coverageReportOfAllFiles, sourceFile) => {
+        const filePath = sourceFile.getFilePath();
+        const allNodesFromFile = getAllNodesFromASourceFile(sourceFile);
+        const coverageReportOfCurrentFile = getCoverageFromAllNodesOfFile(allNodesFromFile, filePath);
+        return mergeDocumentationReports(coverageReportOfAllFiles, coverageReportOfCurrentFile);
+    }, createEmptyCoverageData());
+    return calculateCoverage(unprocessedCoverageReport);
+}
+/**
+ * Gets the coverage from all nodes of a file
+ * @param nodes - The nodes to process
+ * @param filePath - The file path where the nodes are located
+ * @returns The coverage report for the nodes
+ */
+function getCoverageFromAllNodesOfFile(nodes, filePath) {
+    return nodes.reduce((acc, node) => {
+        const nodeType = getCoverageTypeFromKind(node.getKind());
+        const currentTypeReport = acc[nodeType];
+        const updatedIssues = node.getJsDocs().length === 0
+            ? [
+                ...currentTypeReport.issues,
+                {
+                    file: filePath,
+                    type: nodeType,
+                    name: node.getName() || '',
+                    line: node.getStartLineNumber(),
+                },
+            ]
+            : currentTypeReport.issues;
+        return {
+            ...acc,
+            [nodeType]: {
+                nodesCount: currentTypeReport.nodesCount + 1,
+                issues: updatedIssues,
+            },
+        };
+    }, createEmptyCoverageData());
+}
+/**
+ * Merges two documentation results
+ * @param accumulatedReport - The first empty documentation result
+ * @param currentFileReport - The second documentation result
+ * @returns The merged documentation result
+ */
+export function mergeDocumentationReports(accumulatedReport, currentFileReport) {
+    return objectFromEntries(objectToEntries(accumulatedReport).map(([key, value]) => {
+        const node = value;
+        const type = key;
+        return [
+            type,
+            {
+                nodesCount: node.nodesCount + (currentFileReport[type]?.nodesCount ?? 0),
+                issues: [...node.issues, ...(currentFileReport[type]?.issues ?? [])],
+            },
+        ];
+    }));
+}
+/**
+ * Gets the nodes from a class
+ * @param classNodes - The class nodes to process
+ * @returns The nodes from the class
+ */
+export function getClassNodes(classNodes) {
+    return classNodes.flatMap(classNode => [
+        ...classNode.getMethods(),
+        ...classNode.getProperties(),
+    ]);
+}
+//# sourceMappingURL=doc-processor.js.map

package/src/lib/runner/doc-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-processor.js","sourceRoot":"","sources":["../../../../../../packages/plugin-jsdocs/src/lib/runner/doc-processor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,EACL,OAAO,EACP,UAAU,EACV,UAAU,EACV,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAMxE,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AASpB;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,kBAAuC;IAEvC,OAAO,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;QAC3C,+BAA+B;QAC/B,MAAM,UAAU,GAAG;YACjB,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE;YACjC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE;YACrC,kBAAkB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,kBAAkB,EAAE;SACxD,CAAC;QAEF,6EAA6E;QAC7E,OAAO,QAAQ,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YACpD,GAAG,UAAU;YACb,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE;SACrC,CAAC,CAAC,CAAC;IACN,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAqC;IAErC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO,sBAAsB,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,UAAsB;IAC/D,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,EAAE,CAAC;IACxC,OAAO;QACL,GAAG,UAAU,CAAC,YAAY,EAAE;QAC5B,GAAG,OAAO;QACV,GAAG,aAAa,CAAC,OAAO,CAAC;QACzB,GAAG,UAAU,CAAC,cAAc,EAAE;QAC9B,GAAG,UAAU,CAAC,QAAQ,EAAE;QACxB,GAAG,UAAU,CAAC,aAAa,EAAE;QAC7B,GAAG,uBAAuB,CAAC,UAAU,CAAC,qBAAqB,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAyB;IAEzB,MAAM,yBAAyB,GAAG,WAAW,CAAC,MAAM,CAClD,CAAC,wBAAwB,EAAE,UAAU,EAAE,EAAE;QACvC,MAAM,QAAQ,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QAC1C,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,UAAU,CAAC,CAAC;QAEhE,MAAM,2BAA2B,GAAG,6BAA6B,CAC/D,gBAAgB,EAChB,QAAQ,CACT,CAAC;QAEF,OAAO,yBAAyB,CAC9B,wBAAwB,EACxB,2BAA2B,CAC5B,CAAC;IACJ,CAAC,EACD,uBAAuB,EAAE,CAC1B,CAAC;IAEF,OAAO,iBAAiB,CAAC,yBAAyB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,SAAS,6BAA6B,CAAC,KAAa,EAAE,QAAgB;IACpE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAwB,EAAE,IAAU,EAAE,EAAE;QAC3D,MAAM,QAAQ,GAAG,uBAAuB,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACzD,MAAM,iBAAiB,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,aAAa,GACjB,IAAI,CAAC,SAAS,EAAE,CAAC,MAAM,KAAK,CAAC;YAC3B,CAAC,CAAC;gBACE,GAAG,iBAAiB,CAAC,MAAM;gBAC3B;oBACE,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;oBAC1B,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE;iBAChC;aACF;YACH,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC;QAE/B,OAAO;YACL,GAAG,GAAG;YACN,CAAC,QAAQ,CAAC,EAAE;gBACV,UAAU,EAAE,iBAAiB,CAAC,UAAU,GAAG,CAAC;gBAC5C,MAAM,EAAE,aAAa;aACtB;SACF,CAAC;IACJ,CAAC,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,iBAAsC,EACtC,iBAA+C;IAE/C,OAAO,iBAAiB,CACtB,eAAe,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QACtD,MAAM,IAAI,GAAG,KAAK,CAAC;QACnB,MAAM,IAAI,GAAG,GAAG,CAAC;QACjB,OAAO;YACL,IAAI;YACJ;gBACE,UAAU,EACR,IAAI,CAAC,UAAU,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;gBAC9D,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;aACrE;SACF,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,UAA8B;IAC1D,OAAO,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,GAAG,SAAS,CAAC,UAAU,EAAE;QACzB,GAAG,SAAS,CAAC,aAAa,EAAE;KAC7B,CAAC,CAAC;AACL,CAAC"}

package/src/lib/runner/models.d.ts

@@ -0,0 +1,21 @@
+/** The possible coverage types for documentation analysis */
+export type CoverageType = 'classes' | 'methods' | 'functions' | 'interfaces' | 'enums' | 'variables' | 'properties' | 'types';
+/** The undocumented node is the node that is not documented and has the information for the report. */
+export type UndocumentedNode = {
+    file: string;
+    type: CoverageType;
+    name: string;
+    line: number;
+    class?: string;
+};
+/** The documentation data has the issues and the total nodes count from a specific CoverageType. */
+export type DocumentationData = {
+    issues: UndocumentedNode[];
+    nodesCount: number;
+};
+/** The documentation report has all the documentation data for each coverage type. */
+export type DocumentationReport = Record<CoverageType, DocumentationData>;
+/** The processed documentation result has the documentation data for each coverage type and with coverage stats. */
+export type DocumentationCoverageReport = Record<CoverageType, DocumentationData & {
+    coverage: number;
+}>;

package/src/lib/runner/models.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=models.js.map

package/src/lib/runner/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../../../packages/plugin-jsdocs/src/lib/runner/models.ts"],"names":[],"mappings":""}

package/src/lib/runner/runner.d.ts

@@ -0,0 +1,11 @@
+import type { AuditOutputs, RunnerFunction } from '@code-pushup/models';
+import type { JsDocsPluginTransformedConfig } from '../config.js';
+import type { DocumentationCoverageReport } from './models.js';
+export declare function createRunnerFunction(config: JsDocsPluginTransformedConfig): RunnerFunction;
+/**
+ * Transforms the coverage report into audit outputs.
+ * @param coverageResult - The coverage result containing undocumented items and coverage statistics
+ * @param options - Configuration options specifying which audits to include and exclude
+ * @returns Audit outputs with coverage scores and details about undocumented items
+ */
+export declare function trasformCoverageReportToAuditOutputs(coverageResult: DocumentationCoverageReport, options: Pick<JsDocsPluginTransformedConfig, 'onlyAudits' | 'skipAudits'>): AuditOutputs;

package/src/lib/runner/runner.js

@@ -0,0 +1,44 @@
+import { processJsDocs } from './doc-processor.js';
+import { coverageTypeToAuditSlug } from './utils.js';
+export function createRunnerFunction(config) {
+    return () => {
+        const coverageResult = processJsDocs(config);
+        return trasformCoverageReportToAuditOutputs(coverageResult, config);
+    };
+}
+/**
+ * Transforms the coverage report into audit outputs.
+ * @param coverageResult - The coverage result containing undocumented items and coverage statistics
+ * @param options - Configuration options specifying which audits to include and exclude
+ * @returns Audit outputs with coverage scores and details about undocumented items
+ */
+export function trasformCoverageReportToAuditOutputs(coverageResult, options) {
+    return Object.entries(coverageResult)
+        .filter(([type]) => {
+        const auditSlug = coverageTypeToAuditSlug(type);
+        if (options.onlyAudits?.length) {
+            return options.onlyAudits.includes(auditSlug);
+        }
+        if (options.skipAudits?.length) {
+            return !options.skipAudits.includes(auditSlug);
+        }
+        return true;
+    })
+        .map(([type, item]) => {
+        const { coverage, issues } = item;
+        return {
+            slug: `${type}-coverage`,
+            value: issues.length,
+            score: coverage / 100,
+            displayValue: `${issues.length} undocumented ${type}`,
+            details: {
+                issues: item.issues.map(({ file, line, name }) => ({
+                    message: `Missing ${type} documentation for ${name}`,
+                    source: { file, position: { startLine: line } },
+                    severity: 'warning',
+                })),
+            },
+        };
+    });
+}
+//# sourceMappingURL=runner.js.map

package/src/lib/runner/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../../../../packages/plugin-jsdocs/src/lib/runner/runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,UAAU,oBAAoB,CAClC,MAAqC;IAErC,OAAO,GAAiB,EAAE;QACxB,MAAM,cAAc,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,oCAAoC,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oCAAoC,CAClD,cAA2C,EAC3C,OAAyE;IAEzE,OAAO,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE;QACjB,MAAM,SAAS,GAAG,uBAAuB,CAAC,IAAoB,CAAC,CAAC;QAChE,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;YAC/B,OAAO,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;YAC/B,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QACpB,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAElC,OAAO;YACL,IAAI,EAAE,GAAG,IAAI,WAAW;YACxB,KAAK,EAAE,MAAM,CAAC,MAAM;YACpB,KAAK,EAAE,QAAQ,GAAG,GAAG;YACrB,YAAY,EAAE,GAAG,MAAM,CAAC,MAAM,iBAAiB,IAAI,EAAE;YACrD,OAAO,EAAE;gBACP,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;oBACjD,OAAO,EAAE,WAAW,IAAI,sBAAsB,IAAI,EAAE;oBACpD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE;oBAC/C,QAAQ,EAAE,SAAS;iBACpB,CAAC,CAAC;aACJ;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/src/lib/runner/utils.d.ts

@@ -0,0 +1,25 @@
+import { SyntaxKind } from 'ts-morph';
+import type { CoverageType, DocumentationCoverageReport, DocumentationReport } from './models.js';
+/**
+ * Creates an empty unprocessed coverage report.
+ * @returns The empty unprocessed coverage report.
+ */
+export declare function createEmptyCoverageData(): DocumentationReport;
+/**
+ * Converts the coverage type to the audit slug.
+ * @param type - The coverage type.
+ * @returns The audit slug.
+ */
+export declare function coverageTypeToAuditSlug(type: CoverageType): string;
+/**
+ * Calculates the coverage percentage for each coverage type.
+ * @param result - The unprocessed coverage result.
+ * @returns The processed coverage result.
+ */
+export declare function calculateCoverage(result: DocumentationReport): DocumentationCoverageReport;
+/**
+ * Maps the SyntaxKind from the library ts-morph to the coverage type.
+ * @param kind - The SyntaxKind from the library ts-morph.
+ * @returns The coverage type.
+ */
+export declare function getCoverageTypeFromKind(kind: SyntaxKind): CoverageType;

package/src/lib/runner/utils.js

@@ -0,0 +1,59 @@
+import { SyntaxKind } from 'ts-morph';
+import { SYNTAX_COVERAGE_MAP } from './constants.js';
+/**
+ * Creates an empty unprocessed coverage report.
+ * @returns The empty unprocessed coverage report.
+ */
+export function createEmptyCoverageData() {
+    return {
+        enums: { nodesCount: 0, issues: [] },
+        interfaces: { nodesCount: 0, issues: [] },
+        types: { nodesCount: 0, issues: [] },
+        functions: { nodesCount: 0, issues: [] },
+        variables: { nodesCount: 0, issues: [] },
+        classes: { nodesCount: 0, issues: [] },
+        methods: { nodesCount: 0, issues: [] },
+        properties: { nodesCount: 0, issues: [] },
+    };
+}
+/**
+ * Converts the coverage type to the audit slug.
+ * @param type - The coverage type.
+ * @returns The audit slug.
+ */
+export function coverageTypeToAuditSlug(type) {
+    return `${type}-coverage`;
+}
+/**
+ * Calculates the coverage percentage for each coverage type.
+ * @param result - The unprocessed coverage result.
+ * @returns The processed coverage result.
+ */
+export function calculateCoverage(result) {
+    return Object.fromEntries(Object.entries(result).map(([key, value]) => {
+        const type = key;
+        return [
+            type,
+            {
+                coverage: value.nodesCount === 0
+                    ? 100
+                    : Number(((1 - value.issues.length / value.nodesCount) * 100).toFixed(2)),
+                issues: value.issues,
+                nodesCount: value.nodesCount,
+            },
+        ];
+    }));
+}
+/**
+ * Maps the SyntaxKind from the library ts-morph to the coverage type.
+ * @param kind - The SyntaxKind from the library ts-morph.
+ * @returns The coverage type.
+ */
+export function getCoverageTypeFromKind(kind) {
+    const type = SYNTAX_COVERAGE_MAP.get(kind);
+    if (!type) {
+        throw new Error(`Unsupported syntax kind: ${kind}`);
+    }
+    return type;
+}
+//# sourceMappingURL=utils.js.map

package/src/lib/runner/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../../../packages/plugin-jsdocs/src/lib/runner/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAOrD;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACpC,UAAU,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACzC,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACpC,SAAS,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACxC,SAAS,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACxC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACtC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;QACtC,UAAU,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;KAC1C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAkB;IACxD,OAAO,GAAG,IAAI,WAAW,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA2B;IAC3D,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,GAAmB,CAAC;QACjC,OAAO;YACL,IAAI;YACJ;gBACE,QAAQ,EACN,KAAK,CAAC,UAAU,KAAK,CAAC;oBACpB,CAAC,CAAC,GAAG;oBACL,CAAC,CAAC,MAAM,CACJ,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAC1D,CAAC,CACF,CACF;gBACP,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,UAAU,EAAE,KAAK,CAAC,UAAU;aAC7B;SACF,CAAC;IACJ,CAAC,CAAC,CAC4B,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAgB;IACtD,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/src/lib/utils.d.ts

@@ -0,0 +1,18 @@
+import type { Audit, Group } from '@code-pushup/models';
+import type { JsDocsPluginTransformedConfig } from './config.js';
+/**
+ * Get audits based on the configuration.
+ * If no audits are specified, return all audits.
+ * If audits are specified, return only the specified audits.
+ * @param config - The configuration object.
+ * @returns The audits.
+ */
+export declare function filterAuditsByPluginConfig(config: Pick<JsDocsPluginTransformedConfig, 'onlyAudits' | 'skipAudits'>): Audit[];
+/**
+ * Filter groups by the audits that are specified in the configuration.
+ * The groups refs are filtered to only include the audits that are specified in the configuration.
+ * @param groups - The groups to filter.
+ * @param options - The configuration object containing either onlyAudits or skipAudits.
+ * @returns The filtered groups.
+ */
+export declare function filterGroupsByOnlyAudits(groups: Group[], options: Pick<JsDocsPluginTransformedConfig, 'onlyAudits' | 'skipAudits'>): Group[];

package/src/lib/utils.js

@@ -0,0 +1,35 @@
+import { AUDITS_MAP } from './constants.js';
+/**
+ * Get audits based on the configuration.
+ * If no audits are specified, return all audits.
+ * If audits are specified, return only the specified audits.
+ * @param config - The configuration object.
+ * @returns The audits.
+ */
+export function filterAuditsByPluginConfig(config) {
+    const { onlyAudits, skipAudits } = config;
+    if (onlyAudits && onlyAudits.length > 0) {
+        return Object.values(AUDITS_MAP).filter(audit => onlyAudits.includes(audit.slug));
+    }
+    if (skipAudits && skipAudits.length > 0) {
+        return Object.values(AUDITS_MAP).filter(audit => !skipAudits.includes(audit.slug));
+    }
+    return Object.values(AUDITS_MAP);
+}
+/**
+ * Filter groups by the audits that are specified in the configuration.
+ * The groups refs are filtered to only include the audits that are specified in the configuration.
+ * @param groups - The groups to filter.
+ * @param options - The configuration object containing either onlyAudits or skipAudits.
+ * @returns The filtered groups.
+ */
+export function filterGroupsByOnlyAudits(groups, options) {
+    const audits = filterAuditsByPluginConfig(options);
+    return groups
+        .map(group => ({
+        ...group,
+        refs: group.refs.filter(ref => audits.some(audit => audit.slug === ref.slug)),
+    }))
+        .filter(group => group.refs.length > 0);
+}
+//# sourceMappingURL=utils.js.map

package/src/lib/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../../packages/plugin-jsdocs/src/lib/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAwE;IAExE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;IAE1C,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC9C,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAChC,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CACrC,KAAK,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAC1C,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAe,EACf,OAAyE;IAEzE,MAAM,MAAM,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACnD,OAAO,MAAM;SACV,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACb,GAAG,KAAK;QACR,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAC5B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,CAC9C;KACF,CAAC,CAAC;SACF,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC5C,CAAC"}