refactor: add sync generator for zod2md tooling setup

.env.example

@@ -1,2 +1,8 @@
-# for uploading to portal
+# Example environment variables
+# These are for reference only - use .env.local for local development
+
+# For uploading to Code PushUp portal
 CP_API_KEY=
+
+# Note: For local development with tsx/TypeScript execution,
+# copy .env.local.example to .env.local and configure NODE_OPTIONS there

.env.local

@@ -0,0 +1,9 @@
+# Local development environment variables
+# Copy this to .env.local and customize for your setup
+
+# Enable tsx for TypeScript execution in Nx
+# This allows running local generator/executor directly as .ts files without pre-compilation
+# This allowes the local plugins to import files with .js extensions (same as the packages in the repository)
+NODE_OPTIONS=--import tsx
+# This is used to resolve the paths in the local generator/executor so local packages can be imported as path aliases
+TSX_TSCONFIG_PATH=tsconfig.base.json

.env.local.example

@@ -0,0 +1,12 @@
+# Local development environment variables
+# Copy this to .env.local (gitignored) and customize for your setup
+
+# Enable tsx for TypeScript execution in Nx
+# This allows running local generator/executor directly as .ts files without pre-compilation
+# This allowes the local plugins to import files with .js extensions (same as the packages in the repository)
+NODE_OPTIONS=--import tsx
+# This is used to resolve the paths in the local generator/executor so local packages can be imported as path aliases
+TSX_TSCONFIG_PATH=tsconfig.base.json
+
+# Local API keys (optional - only if testing upload features)
+# CP_API_KEY=your_api_key_here

e2e/nx-plugin-e2e/tests/plugin-plugins-config.e2e.test.ts

@@ -74,7 +74,8 @@ describe('nx-plugin pluginsConfig', () => {
 
     await materializeTree(tree, cwd);
 
-    const { code, projectJson } = await nxShowProjectJson(cwd, project);
+    const { code, stderr, projectJson } = await nxShowProjectJson(cwd, project);
+    expect(stderr).toBe('');
     expect(code).toBe(0);
 
     expect(projectJson).toStrictEqual(

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": {},

packages/plugin-typescript/mocks/fixtures/nx-monorepo/_nx.json

@@ -1 +1,8 @@
-{}
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "targetDefaults": {},
+  "workspaceLayout": {
+    "appsDir": "apps",
+    "libsDir": "packages"
+  }
+}

packages/plugin-typescript/mocks/fixtures/nx-monorepo/_package.json

@@ -1 +1,5 @@
-{}
+{
+  "name": "nx-monorepo-fixture",
+  "version": "0.0.0",
+  "private": true
+}

packages/plugin-typescript/mocks/fixtures/nx-monorepo/tsconfig.base.json

@@ -0,0 +1,25 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "rootDir": ".",
+    "sourceMap": true,
+    "declaration": false,
+    "moduleResolution": "node",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": false,
+    "target": "es2022",
+    "module": "esnext",
+    "lib": ["es2023"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@code-pushup/cli": ["packages/cli/src/index.ts"],
+      "@code-pushup/core": ["packages/core/src/index.ts"],
+      "@code-pushup/nx-plugin": ["packages/nx-plugin/src/index.ts"],
+      "@code-pushup/utils": ["packages/utils/src/index.ts"]
+    }
+  },
+  "exclude": ["node_modules", "tmp"]
+}

packages/plugin-typescript/src/lib/nx/tsconfig-paths.ts

@@ -36,12 +36,21 @@ function isProjectIncluded(
  */
 async function findTsconfigsInProject(projectRoot: string): Promise<string[]> {
   const absoluteRoot = path.resolve(process.cwd(), projectRoot);
-  const files = await readdir(absoluteRoot);
 
-  return files
-    .filter(file => TSCONFIG_PATTERN.test(file))
-    .filter(file => hasFilesToCompile(path.join(absoluteRoot, file)))
-    .map(file => path.join(projectRoot, file));
+  try {
+    const files = await readdir(absoluteRoot);
+
+    return files
+      .filter(file => TSCONFIG_PATTERN.test(file))
+      .filter(file => hasFilesToCompile(path.join(absoluteRoot, file)))
+      .map(file => path.join(projectRoot, file));
+  } catch (error) {
+    // If directory doesn't exist or can't be read, return empty array
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
 }
 
 /**

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,29 @@ 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', project, '--json'],
+      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 | string | null;
+      stderr?: string;
+      stdout?: string;
+      message?: string;
+    };
+    return {
+      code: typeof execError.code === 'number' ? execError.code : 1,
+      stderr: execError.stderr ?? execError.message ?? String(error),
+      projectJson: JSON.parse('{}'),
+    };
+  }
 }

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

@@ -7,7 +7,11 @@ export async function materializeTree(tree: Tree, targetFolder: string) {
   const changes = tree.listChanges();
   await Promise.all(
     changes.map(async change => {
-      const filePath = path.join(targetFolder, change.path);
+      // Handle absolute paths that start with '/' by making them relative
+      const relativePath = change.path.startsWith('/')
+        ? change.path.slice(1)
+        : change.path;
+      const filePath = path.join(targetFolder, relativePath);
 
       if (change.type === 'CREATE' || change.type === 'UPDATE') {
         try {

testing/test-utils/src/index.ts

@@ -12,3 +12,4 @@ export * from './lib/utils/project-graph.js';
 export * from './lib/utils/test-folder-setup.js';
 export * from './lib/utils/omit-trace-json.js';
 export * from './lib/utils/profiler.mock.js';
+export * from './lib/utils/execute-process.js';

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

@@ -0,0 +1,13 @@
+/** THIS IS A COPY OF THE UTILS PACKAGE AND TESTED THERE **/
+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