feat(plugin-jsdocs): add setup wizard binding

Author: hanna-skryl

packages/create-cli/README.md

@@ -72,6 +72,13 @@ Each plugin exposes its own configuration keys that can be passed as CLI argumen
 |**`--lighthouse.urls`**|`string \| string[]`|`http://localhost:4200`| Target URL(s) (comma-separated) |
 |**`--lighthouse.categories`**|`('performance'`\|`'a11y'`\|`'best-practices'`\|`'seo')[]`| all | Lighthouse categories |
 
+#### JSDocs
+
+| Option | Type | Default | Description |
+| ------------------------- | -------------------- | -------------------------------------------- | -------------------------------------- |
+|**`--jsdocs.patterns`**|`string \| string[]`|`src/**/*.ts, src/**/*.js, !**/node_modules`| Source file patterns (comma-separated) |
+|**`--jsdocs.categories`**|`boolean`|`true`| Add JSDocs categories |
+
 #### Axe
 
 | Option | Type | Default | Description |

packages/create-cli/src/index.ts

@@ -5,6 +5,7 @@ import { axeSetupBinding } from '@code-pushup/axe-plugin';
 import{coverageSetupBinding}from'@code-pushup/coverage-plugin';
 import{eslintSetupBinding}from'@code-pushup/eslint-plugin';
 import{jsPackagesSetupBinding}from'@code-pushup/js-packages-plugin';
+import{jsDocsSetupBinding}from'@code-pushup/jsdocs-plugin';
 import{lighthouseSetupBinding}from'@code-pushup/lighthouse-plugin';
 import{typescriptSetupBinding}from'@code-pushup/typescript-plugin';
 import{parsePluginSlugs,validatePluginSlugs}from'./lib/setup/plugins.js';
@@ -16,14 +17,14 @@ import {
 }from'./lib/setup/types.js';
 import{runSetupWizard}from'./lib/setup/wizard.js';
 
-// TODO: create, import and pass remaining plugin bindings (jsdocs)
 constbindings: PluginSetupBinding[]=[
 eslintSetupBinding,
 coverageSetupBinding,
 jsPackagesSetupBinding,
 typescriptSetupBinding,
 lighthouseSetupBinding,
 axeSetupBinding,
+jsDocsSetupBinding,
 ];
 
 constargv=awaityargs(hideBin(process.argv))

packages/plugin-jsdocs/src/index.ts

@@ -1,4 +1,5 @@
 import{jsDocsPlugin}from'./lib/jsdocs-plugin.js';
 
 exportdefaultjsDocsPlugin;
+export{jsDocsSetupBinding}from'./lib/binding.js';
 exporttype{JsDocsPluginConfig}from'./lib/config.js';

packages/plugin-jsdocs/src/lib/binding.ts

@@ -0,0 +1,93 @@
+import{createRequire}from'node:module';
+importtype{
+CategoryConfig,
+PluginAnswer,
+PluginSetupBinding,
+}from'@code-pushup/models';
+import{
+answerBoolean,
+answerNonEmptyArray,
+singleQuote,
+}from'@code-pushup/utils';
+import{PLUGIN_SLUG,PLUGIN_TITLE}from'./constants.js';
+
+const{name: PACKAGE_NAME}=createRequire(import.meta.url)(
+'../../package.json',
+)astypeofimport('../../package.json');
+
+constDEFAULT_PATTERNS: [string, ...string[]]=[
+'src/**/*.ts',
+'src/**/*.js',
+'!**/node_modules',
+];
+
+constCATEGORY: CategoryConfig={
+slug: 'docs',
+title: 'Documentation',
+description: 'Measures how much of your code is **documented**.',
+refs: [
+{
+type: 'group',
+plugin: PLUGIN_SLUG,
+slug: 'documentation-coverage',
+weight: 1,
+},
+],
+};
+
+typeJsDocsOptions={
+patterns: [string, ...string[]];
+categories: boolean;
+};
+
+exportconstjsDocsSetupBinding={
+slug: PLUGIN_SLUG,
+title: PLUGIN_TITLE,
+packageName: PACKAGE_NAME,
+prompts: async()=>[
+{
+key: 'jsdocs.patterns',
+message: 'Source file patterns (comma-separated)',
+type: 'input',
+default: DEFAULT_PATTERNS.join(', '),
+},
+{
+key: 'jsdocs.categories',
+message: 'Add JSDocs categories?',
+type: 'confirm',
+default: true,
+},
+],
+generateConfig: (answers: Record<string,PluginAnswer>)=>{
+constoptions=parseAnswers(answers);
+return{
+imports: [
+{moduleSpecifier: PACKAGE_NAME,defaultImport: 'jsDocsPlugin'},
+],
+pluginInit: formatPluginInit(options.patterns),
+ ...(options.categories ? {categories: [CATEGORY]} : {}),
+};
+},
+}satisfiesPluginSetupBinding;
+
+functionparseAnswers(answers: Record<string,PluginAnswer>): JsDocsOptions{
+return{
+patterns: answerNonEmptyArray(
+answers,
+'jsdocs.patterns',
+DEFAULT_PATTERNS[0],
+),
+categories: answerBoolean(answers,'jsdocs.categories'),
+};
+}
+
+functionformatPluginInit([first, ...rest]: [string, ...string[]]): string[]{
+if(rest.length===0){
+return[`jsDocsPlugin(${singleQuote(first)}),`];
+}
+return[
+'jsDocsPlugin([',
+ ...[first, ...rest].map(p=>` ${singleQuote(p)},`),
+']),',
+];
+}

packages/plugin-jsdocs/src/lib/binding.unit.test.ts

@@ -0,0 +1,83 @@
+importtype{PluginAnswer}from'@code-pushup/models';
+import{jsDocsSetupBindingasbinding}from'./binding.js';
+
+constdefaultAnswers: Record<string,PluginAnswer>={
+'jsdocs.patterns': 'src/**/*.ts, src/**/*.js, !**/node_modules',
+'jsdocs.categories': true,
+};
+
+constnoCategoryAnswers: Record<string,PluginAnswer>={
+ ...defaultAnswers,
+'jsdocs.categories': false,
+};
+
+describe('jsDocsSetupBinding',()=>{
+describe('prompts',()=>{
+it('should default to common TypeScript and JavaScript source patterns',async()=>{
+awaitexpect(binding.prompts!()).resolves.toIncludeAllPartialMembers([
+{
+key: 'jsdocs.patterns',
+type: 'input',
+default: 'src/**/*.ts, src/**/*.js, !**/node_modules',
+},
+]);
+});
+
+it('should offer to add categories by default',async()=>{
+awaitexpect(binding.prompts!()).resolves.toIncludeAllPartialMembers([
+{key: 'jsdocs.categories',type: 'confirm',default: true},
+]);
+});
+});
+
+describe('generateConfig',()=>{
+it('should import from @code-pushup/jsdocs-plugin',()=>{
+const{ imports }=binding.generateConfig(defaultAnswers);
+expect(imports).toStrictEqual([
+expect.objectContaining({
+defaultImport: 'jsDocsPlugin',
+}),
+]);
+});
+
+it('should pass multiple patterns as array to plugin call',()=>{
+const{ pluginInit }=binding.generateConfig(defaultAnswers);
+expect(pluginInit).toStrictEqual([
+'jsDocsPlugin([',
+" 'src/**/*.ts',",
+" 'src/**/*.js',",
+" '!**/node_modules',",
+']),',
+]);
+});
+
+it('should pass single pattern as string to plugin call',()=>{
+const{ pluginInit }=binding.generateConfig({
+ ...defaultAnswers,
+'jsdocs.patterns': 'src/**/*.ts',
+});
+expect(pluginInit).toStrictEqual(["jsDocsPlugin('src/**/*.ts'),"]);
+});
+
+it('should generate Documentation category from documentation-coverage group',()=>{
+const{ categories }=binding.generateConfig(defaultAnswers);
+expect(categories).toStrictEqual([
+expect.objectContaining({
+slug: 'docs',
+title: 'Documentation',
+refs: [
+expect.objectContaining({
+plugin: 'jsdocs',
+slug: 'documentation-coverage',
+}),
+],
+}),
+]);
+});
+
+it('should omit categories when declined',()=>{
+const{ categories }=binding.generateConfig(noCategoryAnswers);
+expect(categories).toBeUndefined();
+});
+});
+});