refactor: wip

Author: Michael Hladky

packages/models/project.json

@@ -8,6 +8,7 @@
       "dependsOn": [
         "^build",
         "generate-docs",
+        "ts-patch",
         { "projects": "zod2md-jsdocs", "target": "build" }
       ]
     },

tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md

@@ -80,9 +80,10 @@ Default values:
 
 ## Options
 
-| Name           | type                               | description                                            |
-| -------------- | ---------------------------------- | ------------------------------------------------------ |
-| **targetName** | `string` (DEFAULT 'generate-docs') | The id used to identify a target in your project.json. |
+| Name                        | type                               | description                                                         |
+| --------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
+| **docsTargetName**          | `string` (DEFAULT 'generate-docs') | The name of the docs generation target.                             |
+| **jsDocsTypesAugmentation** | `boolean` (DEFAULT `true`)         | Whether to enable TypeScript transformer integration with ts-patch. |
 
 All options are optional and provided in the `nx.json` file.
 
@@ -94,7 +95,8 @@ All options are optional and provided in the `nx.json` file.
     {
       "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js",
       "options": {
-        "targetName": "docs",
+        "docsTargetName": "docs",
+        "jsDocsTypesAugmentation": true,
       },
     },
   ],

tools/zod2md-jsdocs/project.json

@@ -5,13 +5,7 @@
   "projectType": "library",
   "targets": {
     "lint": {},
-    "build": {
-      "dependsOn": ["pre-build"]
-    },
-    "pre-build": {
-      "command": "ts-patch install",
-      "cache": true,
-      "inputs": ["sharedGlobals", { "runtime": "ts-patch check" }]
-    }
+    "build": {},
+    "unit-test": {}
   }
 }

tools/zod2md-jsdocs/src/lib/transformers.ts

@@ -3,7 +3,15 @@ import type * as ts from 'typescript';
 
 const tsInstance: typeof ts = require('typescript');
 
-function generateJSDocComment(typeName: string, baseUrl: string): string {
+/**
+ * Generates a JSDoc comment for a given type name and base URL.
+ * @param typeName
+ * @param baseUrl
+ */
+export function generateJSDocComment(
+  typeName: string,
+  baseUrl: string,
+): string {
   const markdownLink = `${baseUrl}#${typeName.toLowerCase()}`;
   return `*
  * Type Definition: \`${typeName}\`

tools/zod2md-jsdocs/src/lib/transformers.unit.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { generateJSDocComment } from './transformers';
+
+describe('generateJSDocComment', () => {
+  it('should generate JSDoc comment with type name and base URL', () => {
+    const result = generateJSDocComment(
+      'UserSchema',
+      'https://example.com/docs',
+    );
+    expect(result).toMatchInlineSnapshot(`
+      "*
+       * Type Definition: \`UserSchema\`
+       *
+       * This type is derived from a Zod schema and represents
+       * the validated structure of \`UserSchema\` used within the application.
+       *
+       * @see {@link https://example.com/docs#userschema}
+       "
+    `);
+  });
+
+  it('should generate JSDoc comment for different type name', () => {
+    const result = generateJSDocComment(
+      'ConfigOptions',
+      'https://docs.site.com',
+    );
+    expect(result).toBe(
+      `*
+ * Type Definition: \`ConfigOptions\`
+ *
+ * This type is derived from a Zod schema and represents
+ * the validated structure of \`ConfigOptions\` used within the application.
+ *
+ * @see {@link https://docs.site.com#configoptions}
+ `,
+    );
+  });
+
+  it('should convert type name to lowercase in the link anchor', () => {
+    const result = generateJSDocComment('MyComplexType', 'https://example.com');
+    expect(result).toContain('https://example.com#');
+  });
+
+  it('should handle type names with numbers', () => {
+    const result = generateJSDocComment('Schema123', 'https://example.com/api');
+    expect(result).toContain('Type Definition: `Schema123`');
+    expect(result).toContain('#schema123');
+  });
+});

tools/zod2md-jsdocs/src/nx-plugin.cjs

@@ -1,36 +1,68 @@
 const path = require('node:path');
 
 const ZOD2MD_CONFIG_FILE = 'zod2md.config.ts';
+const TS_PATCH_TARGET_NAME = 'ts-patch';
+const GENERATE_DOCS_TARGET_NAME = 'generate-docs';
+
+/**
+ * Creates the ts-patch target configuration
+ * @returns {object} ts-patch target configuration
+ */
+const createTsPatchTargetConfig = {
+  command: 'ts-patch install',
+  cache: true,
+  inputs: ['sharedGlobals', { runtime: 'ts-patch check' }],
+};
+
+/**
+ * Creates the docs generation target configuration
+ * @param {object} params - Configuration parameters
+ * @param {string} params.config - Path to the zod2md config file
+ * @param {string} params.output - Path to the output markdown file
+ * @returns {object} Docs target configuration
+ */
+function createDocsTargetConfig({ config, output }) {
+  return {
+    executor: 'nx:run-commands',
+    options: {
+      commands: [
+        `zod2md --config ${config} --output ${output}`,
+        `prettier --write ${output}`,
+      ],
+      parallel: false,
+    },
+    cache: true,
+    inputs: ['production', '^production', config],
+    outputs: [output],
+  };
+}
 
 const createNodesV2 = [
   `**/${ZOD2MD_CONFIG_FILE}`,
   async (zod2MdConfigurationFiles, createNodesOptions) => {
-    const options = createNodesOptions ?? {};
-    const targetName = options.targetName ?? 'generate-docs';
+    const {
+      docsTargetName = GENERATE_DOCS_TARGET_NAME,
+      jsDocsTypesAugmentation = true,
+    } = createNodesOptions ?? {};
 
     return Promise.all(
       zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
         const projectRoot = path.dirname(zod2MdConfigurationFile);
         const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot;
         const output = '{projectRoot}/docs/{projectName}-reference.md';
         const config = `{projectRoot}/${ZOD2MD_CONFIG_FILE}`;
+
         const result = {
           projects: {
             [normalizedProjectRoot]: {
               targets: {
-                [targetName]: {
-                  executor: 'nx:run-commands',
-                  options: {
-                    commands: [
-                      `zod2md --config ${config} --output ${output}`,
-                      `prettier --write ${output}`,
-                    ],
-                    parallel: false,
-                  },
-                  cache: true,
-                  inputs: ['production', '^production', config],
-                  outputs: [output],
-                },
+                ...(jsDocsTypesAugmentation
+                  ? { [TS_PATCH_TARGET_NAME]: createTsPatchTargetConfig }
+                  : {}),
+                [docsTargetName]: createDocsTargetConfig({
+                  config,
+                  output,
+                }),
               },
             },
           },