refactor: add sync generator for zod2md tooling setup

nx.json

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

packages/models/project.json

@@ -3,14 +3,10 @@
   "$schema": "../../node_modules/nx/schemas/project-schema.json",
   "sourceRoot": "packages/models/src",
   "projectType": "library",
+  "implicitDependencies": ["zod2md-jsdocs"],
   "targets": {
     "build": {
-      "dependsOn": [
-        "^build",
-        "generate-docs",
-        { "projects": "zod2md-jsdocs", "target": "build" },
-        { "projects": "zod2md-jsdocs", "target": "ts-patch" }
-      ]
+      "dependsOn": ["^build", "generate-docs", "ts-patch"]
     },
     "lint": {},
     "unit-test": {},

testing/test-nx-utils/src/lib/utils/nx.ts

@@ -11,7 +11,7 @@ import { libraryGenerator } from '@nx/js';
 import type { LibraryGeneratorSchema } from '@nx/js/src/generators/library/schema';
 import path from 'node:path';
 import { createTreeWithEmptyWorkspace } from 'nx/src/generators/testing-utils/create-tree-with-empty-workspace';
-import { executeProcess } from '@code-pushup/utils';
+import { executeProcess } from '@code-pushup/test-utils';
 
 export function executorContext<
   T extends { projectName: string; cwd?: string },
@@ -95,11 +95,28 @@ export async function nxShowProjectJson<T extends ProjectConfiguration>(
   cwd: string,
   project: string,
 ) {
-  const { code, stderr, stdout } = await executeProcess({
-    command: 'npx',
-    args: ['nx', 'show', `project --json  ${project}`],
-    cwd,
-  });
+  try {
+    const { stderr, stdout } = await executeProcess({
+      command: 'npx',
+      args: ['nx', 'show', 'project', '--json', project],
+      cwd,
+    });
 
-  return { code, stderr, projectJson: JSON.parse(stdout) as T };
+    return {
+      code: 0,
+      stderr,
+      projectJson: JSON.parse(stdout) as T,
+    };
+  } catch (error: unknown) {
+    const execError = error as {
+      code?: number;
+      stderr?: string;
+      stdout?: string;
+    };
+    return {
+      code: execError.code ?? 1,
+      stderr: execError.stderr ?? String(error),
+      projectJson: JSON.parse(execError.stdout ?? '{}') as T,
+    };
+  }
 }

testing/test-utils/src/index.ts

@@ -10,3 +10,4 @@ export * from './lib/utils/file-system.js';
 export * from './lib/utils/create-npm-workshpace.js';
 export * from './lib/utils/project-graph.js';
 export * from './lib/utils/test-folder-setup.js';
+export * from './lib/utils/execute-process.js';

testing/test-utils/src/lib/utils/execute-process.ts

@@ -0,0 +1,12 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export async function executeProcess(cfg: {
+  command: string;
+  args: string[];
+  cwd: string;
+}) {
+  const execFileAsync = promisify(execFile);
+  const { command, args, cwd } = cfg;
+  return await execFileAsync(command, args, { cwd });
+}

tools/zod2md-jsdocs/README.md

@@ -4,44 +4,9 @@ A comprehensive toolset for generating and enhancing TypeScript documentation fr
 
 ## What's Included
 
-This package provides two main components:
+This package provides the following components:
 
-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
-
-## Quick Start
-
-### Using the Nx Plugin
-
-Add the plugin to your `nx.json`:
-
-```jsonc
-{
-  "plugins": ["./tools/zod2md-jsdocs/src/nx-plugin.ts"],
-}
-```
-
-Create a `zod2md.config.ts` in your project, and you'll automatically get a `generate-docs` target.
-
-[Learn more about the Nx Plugin →](./docs/zod2md-jsdocs-nx-plugin.md)
-
-### Using the TypeScript Transformer
-
-1. Install ts-patch: `ts-patch install`
-2. Add to your `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "plugins": [
-      {
-        "transform": "./tools/zod2md-jsdocs/dist/src",
-        "afterDeclarations": true,
-        "baseUrl": "https://github.com/code-pushup/cli/blob/main/packages/<PROJECT-NAME>/docs/models-reference.md"
-      }
-    ]
-  }
-}
-```
-
-[Learn more about the TypeScript Transformer →](./docs/zod2md-jsdocs-ts-transformer.md)
+1. **[Nx Plugin](./src/lib/plugin/README.md)** - Automatically generates documentation targets for projects with Zod schemas
+2. **[Nx Configuration Generator](./src/lib/generators/configuration/README.md)** - Automatically generates documentation targets for projects with Zod schemas
+3. **[Nx Sync Zod2Md Setup Generator](./src/lib/generators/sync-zod2md-setup/README.md)** - Automatically generates documentation targets for projects with Zod schemas
+4. **[TypeScript Transformer](./src/lib/transformers/README.md)** - Enhances generated type definitions with JSDoc comments and schema metadata

tools/zod2md-jsdocs/eslint.config.js

@@ -1,11 +1,53 @@
+const tseslint = require('typescript-eslint');
 const baseConfig = require('../../eslint.config.js').default;
 
-module.exports = [
+module.exports = tseslint.config(
   ...baseConfig,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: __dirname,
+      },
+    },
+  },
+  {
+    files: ['**/*.ts'],
+    rules: {
+      // Nx plugins don't yet support ESM: https://github.com/nrwl/nx/issues/15682
+      'unicorn/prefer-module': 'off',
+      // used instead of verbatimModuleSyntax tsconfig flag (requires ESM)
+      '@typescript-eslint/consistent-type-imports': [
+        'warn',
+        {
+          fixStyle: 'inline-type-imports',
+          disallowTypeAnnotations: false,
+        },
+      ],
+      '@typescript-eslint/consistent-type-exports': [
+        'warn',
+        { fixMixedExportsWithInlineTypeSpecifier: true },
+      ],
+      // `import path from 'node:path'` incompatible with CJS runtime, prefer `import * as path from 'node:path'`
+      'unicorn/import-style': [
+        'warn',
+        { styles: { 'node:path': { namespace: true } } },
+      ],
+      // `import { logger } from '@nx/devkit' is OK here
+      'no-restricted-imports': 'off',
+    },
+  },
   {
     files: ['**/*.json'],
     rules: {
       '@nx/dependency-checks': 'error',
     },
   },
-];
+  {
+    files: ['**/package.json', '**/generators.json'],
+    rules: {
+      '@nx/nx-plugin-checks': 'error',
+    },
+  },
+);

tools/zod2md-jsdocs/generators.json

@@ -0,0 +1,19 @@
+{
+  "generators": {
+    "sync-zod2md-setup": {
+      "factory": "./src/lib/generators/sync-zod2md-setup/sync-zod2md-setup",
+      "schema": "./src/lib/generators/sync-zod2md-setup/schema.json",
+      "description": "sync-zod2md-setup generator"
+    },
+    "configuration": {
+      "factory": "./src/lib/generators/configuration/configuration",
+      "schema": "./src/lib/generators/configuration/schema.json",
+      "description": "configuration generator"
+    },
+    "sync-zod2md-docs": {
+      "factory": "./src/lib/generators/sync-zod2md-docs/sync-zod2md-docs",
+      "schema": "./src/lib/generators/sync-zod2md-docs/schema.json",
+      "description": "sync-zod2md-docs generator"
+    }
+  }
+}

tools/zod2md-jsdocs/package.json

@@ -1,15 +1,17 @@
 {
-  "name": "@code-pushup/zod2md-jsdocs",
+  "name": "@tooling/zod2md-jsdocs",
   "version": "0.0.0",
   "description": "TypeScript transformers enhancing models with JSDoc and schema metadata",
   "type": "commonjs",
   "main": "./src/index.js",
   "dependencies": {
+    "@nx/devkit": "22.3.3",
     "ts-patch": "^3.3.0",
     "typescript": "5.7.3",
-    "@nx/devkit": "22.3.3"
+    "zod2md": "^0.2.4"
   },
   "files": [
     "src"
-  ]
+  ],
+  "generators": "./generators.json"
 }

tools/zod2md-jsdocs/project.json

@@ -4,9 +4,53 @@
   "sourceRoot": "tools/zod2md-jsdocs/src",
   "projectType": "library",
   "targets": {
-    "lint": {},
-    "build": {},
+    "build": {
+      "options": {
+        "assets": [
+          "{projectRoot}/*.md",
+          {
+            "input": "./tools/zod2md-jsdocs/src",
+            "glob": "**/!(*.ts)",
+            "output": "./src"
+          },
+          {
+            "input": "./tools/zod2md-jsdocs/src",
+            "glob": "**/*.d.ts",
+            "output": "./src"
+          },
+          {
+            "input": "./tools/zod2md-jsdocs",
+            "glob": "generators.json",
+            "output": "."
+          },
+          {
+            "input": "./tools/zod2md-jsdocs",
+            "glob": "executors.json",
+            "output": "."
+          }
+        ]
+      }
+    },
+    "lint": {
+      "options": {
+        "lintFilePatterns": [
+          "tools/zod2md-jsdocs/**/*.ts",
+          "tools/zod2md-jsdocs/package.json",
+          "tools/zod2md-jsdocs/generators.json"
+        ]
+      }
+    },
+    "lint-report": {
+      "options": {
+        "lintFilePatterns": [
+          "tools/zod2md-jsdocs/**/*.ts",
+          "tools/zod2md-jsdocs/package.json",
+          "tools/zod2md-jsdocs/generators.json"
+        ]
+      }
+    },
     "unit-test": {},
+    "int-test": {},
     "ts-patch": {
       "command": "ts-patch install",
       "cache": true,
@@ -17,5 +61,6 @@
         }
       ]
     }
-  }
+  },
+  "tags": ["scope:tooling", "type:feature", "publishable"]
 }

tools/zod2md-jsdocs/src/index.ts

@@ -1,8 +1,7 @@
-import { annotateTypeDefinitions } from './lib/transformers.js';
+import { annotateTypeDefinitions } from './lib/transformers/transformers.js';
 
 export {
   annotateTypeDefinitions,
   generateJSDocComment,
-} from './lib/transformers.js';
-
+} from './lib/transformers/transformers.js';
 export default annotateTypeDefinitions;