chore: add zod2md-nx-plugin

nx.json

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

packages/models/project.json

@@ -4,19 +4,6 @@
   "sourceRoot": "packages/models/src",
   "projectType": "library",
   "targets": {
-    "generate-docs": {
-      "executor": "nx:run-commands",
-      "options": {
-        "commands": [
-          "zod2md --config {projectRoot}/zod2md.config.ts",
-          "prettier --write {projectRoot}/docs/models-reference.md"
-        ],
-        "parallel": false
-      },
-      "cache": true,
-      "inputs": ["production", "^production", "{projectRoot}/zod2md.config.ts"],
-      "outputs": ["{projectRoot}/docs/models-reference.md"]
-    },
     "build": {
       "dependsOn": [
         "^build",

tools/zod2md-nx-plugin/README.md

@@ -0,0 +1,120 @@
+# @code-pushup/zod2md-nx-plugin
+
+The Nx Plugin for [zod2md](https://github.com/code-pushup/zod2md), a tool for generating documentation from Zod schemas.
+
+Why should you use this plugin?
+
+- Zero setup cost. Just add a `zod2md.config.ts` file and you're good to go.
+- Automatic target generation
+- Minimal configuration
+- Automated caching and dependency tracking
+
+## Usage
+
+```jsonc
+// nx.json
+{
+  //...
+  "plugins": ["./tools/zod2md-nx-plugin/src/lib/plugin.js"],
+}
+```
+
+or with options:
+
+```jsonc
+// nx.json
+{
+  //...
+  "plugins": [
+    {
+      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "options": {
+        "targetName": "zod-docs",
+      },
+    },
+  ],
+}
+```
+
+Now every project with a `zod2md.config.ts` file will have a `generate-docs` target automatically created.
+
+- `nx run <project-name>:generate-docs`
+
+Run it and the project will automatically generate documentation from your Zod schemas.
+
+```text
+Root/
+├── project-name/
+│   ├── zod2md.config.ts
+│   ├── docs/
+│   │   └── project-name-reference.md 👈 generated
+│   └── ...
+└── ...
+```
+
+The generated target:
+
+1. Runs `zod2md` with the project's configuration
+2. Formats the generated markdown with Prettier
+3. Caches the result for better performance
+
+### Passing zod2md options
+
+You can override the config and output paths when running the target:
+
+```bash
+# Use custom output file
+nx generate-docs my-project --output=docs/custom-api.md
+
+# Use custom config file
+nx generate-docs my-project --config=custom-zod2md.config.ts
+
+# Use both
+nx generate-docs my-project --config=custom.config.ts --output=docs/api.md
+```
+
+Default values:
+
+- `config`: `{projectRoot}/zod2md.config.ts`
+- `output`: `{projectRoot}/docs/{projectName}-reference.md`
+
+## Options
+
+| Name           | type                               | description                                            |
+| -------------- | ---------------------------------- | ------------------------------------------------------ |
+| **targetName** | `string` (DEFAULT 'generate-docs') | The id used to identify a target in your project.json. |
+
+All options are optional and provided in the `nx.json` file.
+
+```jsonc
+// nx.json
+{
+  //...
+  "plugins": [
+    {
+      "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js",
+      "options": {
+        "targetName": "docs",
+      },
+    },
+  ],
+}
+```
+
+## Configuration
+
+Create a `zod2md.config.ts` file in your project:
+
+```ts
+import type { Config } from 'zod2md';
+
+export default {
+  entry: 'packages/models/src/index.ts',
+  tsconfig: 'packages/models/tsconfig.lib.json',
+  format: 'esm',
+  title: 'Models reference',
+  output: 'packages/models/docs/models-reference.md',
+} satisfies Config;
+```
+
+For a full list of configuration options visit the [zod2md documentation](https://github.com/matejchalk/zod2md?tab=readme-ov-file#configuration).

tools/zod2md-nx-plugin/eslint.config.js

@@ -0,0 +1,21 @@
+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,
+      },
+    },
+  },
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': ['error', { ignoredDependencies: [] }],
+    },
+  },
+);

tools/zod2md-nx-plugin/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@code-pushup/zod2md-nx-plugin",
+  "version": "0.0.0",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=17.0.0"
+  },
+  "dependencies": {},
+  "files": [
+    "src",
+    "!**/*.tsbuildinfo"
+  ]
+}

tools/zod2md-nx-plugin/project.json

@@ -0,0 +1,10 @@
+{
+  "name": "zod2md-nx-plugin",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "tools/zod2md-nx-plugin/src",
+  "projectType": "library",
+  "targets": {
+    "lint": {}
+  },
+  "tags": ["scope:shared", "type:util"]
+}

tools/zod2md-nx-plugin/src/lib/plugin.js

@@ -0,0 +1,53 @@
+import { dirname } from 'node:path';
+
+export const createNodesV2 = [
+  `**/zod2md.config.ts`,
+  async (zod2MdConfigurationFiles, createNodesOptions, context) => {
+    const options = createNodesOptions ?? {};
+    const targetName = options.targetName ?? 'generate-docs';
+
+    return Promise.all(
+      zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => {
+        const projectRoot = dirname(zod2MdConfigurationFile);
+        const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot;
+        const result = {
+          projects: {
+            [normalizedProjectRoot]: {
+              targets: {
+                [targetName]: {
+                  executor: 'nx:run-commands',
+                  options: {
+                    commands: [
+                      'zod2md --config {args.config} --output {args.output}',
+                      'prettier --write {args.output}',
+                    ],
+                    parallel: false,
+                    config: '{projectRoot}/zod2md.config.ts',
+                    output: '{projectRoot}/docs/{projectName}-reference.md',
+                  },
+                  cache: true,
+                  inputs: [
+                    'production',
+                    '^production',
+                    '{projectRoot}/zod2md.config.ts',
+                  ],
+                  outputs: ['{projectRoot}/docs/{outputFile}'],
+                },
+              },
+            },
+          },
+        };
+
+        return [zod2MdConfigurationFile, result];
+      }),
+    );
+  },
+];
+
+// default export for nx.json#plugins
+const plugin = {
+  name: 'zod2md-nx-plugin',
+  createNodesV2,
+};
+
+export default plugin;