refactor: wip

Author: Michael Hladky

nx.json

@@ -337,7 +337,7 @@
     "releaseTagPattern": "v{version}"
   },
   "plugins": [
-    "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+    "./tools/zod2md-jsdocs/src/nx-plugin.js",
     {
       "plugin": "@push-based/nx-verdaccio",
       "options": {

tools/zod2md-jsdocs/README.md

@@ -1,57 +1,41 @@
-# @code-pushup/zod2md-jsdocs
+# zod2md-jsdocs
 
-TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata.
+A comprehensive toolset for generating and enhancing TypeScript documentation from Zod schemas. This package combines an Nx plugin for automated documentation generation with a TypeScript transformer that enriches type definitions with JSDoc comments.
 
-## Purpose
+## What's Included
 
-This package provides a TypeScript compiler transformer that automatically adds JSDoc documentation to type aliases and interfaces during compilation. It's designed to improve developer experience by injecting helpful metadata and documentation links directly into generated type definitions.
+This package provides two main components:
 
-## How It Works
+1. **[Nx Plugin](./docs/zod2md-jsdocs-nx-plugin.md)** - Automatically generates documentation targets for projects with Zod schemas
+2. **[TypeScript Transformer](./docs/zod2md-jsdocs-ts-transformer.md)** - Enhances generated type definitions with JSDoc comments and schema metadata
 
-The [TS transformer](https://github.com/itsdouges/typescript-transformer-handbook) hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes:
+## Quick Start
 
-- The type name
-- A description explaining the type is derived from a Zod schema
-- A link to the type reference documentation
+### Using the Nx Plugin
 
-## Example
+Add the plugin to your `nx.json`:
 
-Given a type definition like:
-
-```typescript
-export type Report = {
-  // ... type properties
-};
+```jsonc
+{
+  "plugins": ["./tools/zod2md-jsdocs/src/lib/plugin.js"],
+}
 ```
 
-The transformer automatically generates:
+Create a `zod2md.config.ts` in your project, and you'll automatically get a `generate-docs` target.
 
-```typescript
-/**
- * Type Definition: `Report`
- *
- * This type is derived from a Zod schema and represents
- * the validated structure of `Report` used within the application.
- *
- * @see {@link https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md#report}
- */
-export type Report = {
-  // ... type properties
-};
-```
+[Learn more about the Nx Plugin →](./docs/zod2md-jsdocs-nx-plugin.md)
 
-## Usage
+### Using the TypeScript Transformer
 
-1. `ts-patch install`
-
-2. Add the transformer to your `tsconfig.json`:
+1. Install ts-patch: `ts-patch install`
+2. Add to your `tsconfig.json`:
 
 ```json
 {
   "compilerOptions": {
     "plugins": [
       {
-        "transform": "./path/to/transformer/dist",
+        "transform": "./tools/zod2md-jsdocs/dist/src",
         "afterDeclarations": true,
         "baseUrl": "https://example.com/docs/api-reference.md"
       }
@@ -60,12 +44,4 @@ export type Report = {
 }
 ```
 
-3. Build your TypeScript project. The transformer will run automatically and add JSDoc comments to your type definitions.
-
-### Options
-
-| Option              | Type      | Required | Description                                                                                                                                                         |
-| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `transform`         | `string`  | Yes      | Path to the transformer module                                                                                                                                      |
-| `afterDeclarations` | `boolean` | No       | Set to `true` to run the transformer after TypeScript generates declaration files (`.d.ts`). This ensures JSDoc comments are added to the emitted type definitions. |
-| `baseUrl`           | `string`  | Yes      | Base URL for documentation links (e.g., `https://example.com/docs/api-reference.md`)                                                                                |
+[Learn more about the TypeScript Transformer →](./docs/zod2md-jsdocs-ts-transformer.md)

tools/zod2md-nx-plugin/README.md …d-jsdocs/docs/zod2md-jsdocs-nx-plugin.mdtools/zod2md-nx-plugin/README.md renamed to tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md tools/zod2md-nx-plugin/README.md renamed to tools/zod2md-jsdocs/docs/zod2md-jsdocs-nx-plugin.md

@@ -1,4 +1,4 @@
-# @code-pushup/zod2md-nx-plugin
+# @code-pushup/zod2md-jsdocs-nx-plugin
 
 The Nx Plugin for [zod2md](https://github.com/matejchalk/zod2md), a tool for generating documentation from Zod schemas.
 
@@ -15,7 +15,7 @@ Why should you use this plugin?
 // nx.json
 {
   //...
-  "plugins": ["./tools/zod2md-nx-plugin/src/lib/plugin.js"],
+  "plugins": ["./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js"],
 }
 ```
 
@@ -27,7 +27,7 @@ or with options:
   //...
   "plugins": [
     {
-      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js",
       "options": {
         "targetName": "zod-docs",
       },
@@ -92,7 +92,7 @@ All options are optional and provided in the `nx.json` file.
   //...
   "plugins": [
     {
-      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js",
       "options": {
         "targetName": "docs",
       },

tools/zod2md-jsdocs/docs/zod2md-jsdocs-ts-transformer.md

@@ -0,0 +1,71 @@
+# zod2md-jsdocs-ts-transformer
+
+TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata.
+
+## Purpose
+
+This package provides a TypeScript compiler transformer that automatically adds JSDoc documentation to type aliases and interfaces during compilation. It's designed to improve developer experience by injecting helpful metadata and documentation links directly into generated type definitions.
+
+## How It Works
+
+The [TS transformer](https://github.com/itsdouges/typescript-transformer-handbook) hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes:
+
+- The type name
+- A description explaining the type is derived from a Zod schema
+- A link to the type reference documentation
+
+## Example
+
+Given a type definition like:
+
+```typescript
+export type Report = {
+  // ... type properties
+};
+```
+
+The transformer automatically generates:
+
+```typescript
+/**
+ * Type Definition: `Report`
+ *
+ * This type is derived from a Zod schema and represents
+ * the validated structure of `Report` used within the application.
+ *
+ * @see {@link https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md#report}
+ */
+export type Report = {
+  // ... type properties
+};
+```
+
+## Usage
+
+1. `ts-patch install`
+
+2. Add the transformer to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "./path/to/transformer/dist",
+        "afterDeclarations": true,
+        "baseUrl": "https://example.com/docs/api-reference.md"
+      }
+    ]
+  }
+}
+```
+
+3. Build your TypeScript project. The transformer will run automatically and add JSDoc comments to your type definitions.
+
+### Options
+
+| Option              | Type      | Required | Description                                                                                                                                                         |
+| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transform`         | `string`  | Yes      | Path to the transformer module                                                                                                                                      |
+| `afterDeclarations` | `boolean` | No       | Set to `true` to run the transformer after TypeScript generates declaration files (`.d.ts`). This ensures JSDoc comments are added to the emitted type definitions. |
+| `baseUrl`           | `string`  | Yes      | Base URL for documentation links (e.g., `https://example.com/docs/api-reference.md`)                                                                                |

tools/zod2md-nx-plugin/src/lib/plugin.js tools/zod2md-jsdocs/src/nx-plugin.jstools/zod2md-nx-plugin/src/lib/plugin.js renamed to tools/zod2md-jsdocs/src/nx-plugin.js

@@ -45,9 +45,9 @@ export const createNodesV2 = [
 ];
 
 // default export for nx.json#plugins
-const plugin = {
-  name: 'zod2md-nx-plugin',
+const nxPlugin = {
+  name: 'zod2md-jsdocs-nx-plugin',
   createNodesV2,
 };
 
-export default plugin;
+export default nxPlugin;