From 867c80d02a5d225bb865446a937ccfa97557122a Mon Sep 17 00:00:00 2001 From: John Doe Date: Tue, 2 Dec 2025 21:54:16 +0100 Subject: [PATCH 01/14] refactor: move models-transformers into tools --- packages/models/project.json | 2 +- packages/models/tsconfig.lib.json | 8 +-- tools/jsdoc-annotation-transformer/README.md | 69 +++++++++++++++++++ .../eslint.config.cjs | 2 +- .../package.json | 2 +- .../project.json | 10 +-- .../src/index.ts | 0 .../src/lib/transformers.ts | 0 .../tsconfig.json | 2 +- .../tsconfig.lib.json | 3 +- .../tsconfig.spec.json | 29 ++++++++ .../vitest.unit.config.ts | 3 + 12 files changed, 113 insertions(+), 17 deletions(-) create mode 100644 tools/jsdoc-annotation-transformer/README.md rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/eslint.config.cjs (67%) rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/package.json (82%) rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/project.json (58%) rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/src/index.ts (100%) rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/src/lib/transformers.ts (100%) rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/tsconfig.json (81%) rename {packages/models/transformers => tools/jsdoc-annotation-transformer}/tsconfig.lib.json (76%) create mode 100644 tools/jsdoc-annotation-transformer/tsconfig.spec.json create mode 100644 tools/jsdoc-annotation-transformer/vitest.unit.config.ts diff --git a/packages/models/project.json b/packages/models/project.json index 0045b607e..d76e0034f 100644 --- a/packages/models/project.json +++ b/packages/models/project.json @@ -21,7 +21,7 @@ "dependsOn": [ "^build", "generate-docs", - { "projects": "models-transformers", "target": "build" } + { "projects": "jsdocs-annotation-transformer", "target": "build" } ] }, "lint": {}, diff --git a/packages/models/tsconfig.lib.json b/packages/models/tsconfig.lib.json index 2c92983e0..23ebd7dba 100644 --- a/packages/models/tsconfig.lib.json +++ b/packages/models/tsconfig.lib.json @@ -3,13 +3,7 @@ "compilerOptions": { "outDir": "../../dist/out-tsc", "declaration": true, - "types": ["node"], - "plugins": [ - { - "transform": "./packages/models/transformers/dist", - "afterDeclarations": true - } - ] + "types": ["node"] }, "include": ["src/**/*.ts"], "exclude": [ diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md new file mode 100644 index 000000000..033289349 --- /dev/null +++ b/tools/jsdoc-annotation-transformer/README.md @@ -0,0 +1,69 @@ +# @code-pushup/jsdocs-annotation-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 transformer 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 models 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": "./packages/models/transformers/dist", + "afterDeclarations": true + } + ] + } +} +``` + +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. | diff --git a/packages/models/transformers/eslint.config.cjs b/tools/jsdoc-annotation-transformer/eslint.config.cjs similarity index 67% rename from packages/models/transformers/eslint.config.cjs rename to tools/jsdoc-annotation-transformer/eslint.config.cjs index 4eaecdb17..467b6c94b 100644 --- a/packages/models/transformers/eslint.config.cjs +++ b/tools/jsdoc-annotation-transformer/eslint.config.cjs @@ -1,4 +1,4 @@ -const baseConfig = require('../../../eslint.config.js').default; +const baseConfig = require('../../eslint.config.js').default; module.exports = [ ...baseConfig, diff --git a/packages/models/transformers/package.json b/tools/jsdoc-annotation-transformer/package.json similarity index 82% rename from packages/models/transformers/package.json rename to tools/jsdoc-annotation-transformer/package.json index e5d33d01b..273fd5821 100644 --- a/packages/models/transformers/package.json +++ b/tools/jsdoc-annotation-transformer/package.json @@ -1,5 +1,5 @@ { - "name": "@code-pushup/models-transformers", + "name": "@code-pushup/jsdocs-annotation-transformer", "version": "0.0.0", "description": "TypeScript transformers enhancing models with JSDoc and schema metadata", "type": "commonjs", diff --git a/packages/models/transformers/project.json b/tools/jsdoc-annotation-transformer/project.json similarity index 58% rename from packages/models/transformers/project.json rename to tools/jsdoc-annotation-transformer/project.json index 9b3ed9b10..bcdbbeb48 100644 --- a/packages/models/transformers/project.json +++ b/tools/jsdoc-annotation-transformer/project.json @@ -1,7 +1,7 @@ { - "name": "models-transformers", + "name": "jsdoc-annotation-transformer", "$schema": "../../../node_modules/nx/schemas/project-schema.json", - "sourceRoot": "packages/models/transformers/src", + "sourceRoot": "tools/jsdoc-annotation-transformer/src", "projectType": "library", "targets": { "build": { @@ -9,9 +9,9 @@ "outputs": ["{options.outputPath}"], "dependsOn": ["pre-build"], "options": { - "outputPath": "packages/models/transformers/dist", - "main": "packages/models/transformers/src/index.ts", - "tsConfig": "packages/models/transformers/tsconfig.lib.json" + "outputPath": "tools/jsdoc-annotation-transformer/dist", + "main": "tools/jsdoc-annotation-transformer/src/index.ts", + "tsConfig": "tools/jsdoc-annotation-transformer/tsconfig.lib.json" } }, "pre-build": { diff --git a/packages/models/transformers/src/index.ts b/tools/jsdoc-annotation-transformer/src/index.ts similarity index 100% rename from packages/models/transformers/src/index.ts rename to tools/jsdoc-annotation-transformer/src/index.ts diff --git a/packages/models/transformers/src/lib/transformers.ts b/tools/jsdoc-annotation-transformer/src/lib/transformers.ts similarity index 100% rename from packages/models/transformers/src/lib/transformers.ts rename to tools/jsdoc-annotation-transformer/src/lib/transformers.ts diff --git a/packages/models/transformers/tsconfig.json b/tools/jsdoc-annotation-transformer/tsconfig.json similarity index 81% rename from packages/models/transformers/tsconfig.json rename to tools/jsdoc-annotation-transformer/tsconfig.json index fe17bec70..0c1036efe 100644 --- a/packages/models/transformers/tsconfig.json +++ b/tools/jsdoc-annotation-transformer/tsconfig.json @@ -1,5 +1,5 @@ { - "extends": "../../../tsconfig.base.json", + "extends": "../../tsconfig.base.json", "compilerOptions": { "module": "commonjs", "verbatimModuleSyntax": false diff --git a/packages/models/transformers/tsconfig.lib.json b/tools/jsdoc-annotation-transformer/tsconfig.lib.json similarity index 76% rename from packages/models/transformers/tsconfig.lib.json rename to tools/jsdoc-annotation-transformer/tsconfig.lib.json index 48174f134..bebaef047 100644 --- a/packages/models/transformers/tsconfig.lib.json +++ b/tools/jsdoc-annotation-transformer/tsconfig.lib.json @@ -4,7 +4,8 @@ "outDir": "./dist", "rootDir": "./", "module": "commonjs", - "types": ["node"] + "types": ["node"], + "esModuleInterop": true }, "include": ["src/**/*.ts"] } diff --git a/tools/jsdoc-annotation-transformer/tsconfig.spec.json b/tools/jsdoc-annotation-transformer/tsconfig.spec.json new file mode 100644 index 000000000..827403667 --- /dev/null +++ b/tools/jsdoc-annotation-transformer/tsconfig.spec.json @@ -0,0 +1,29 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "../../dist/out-tsc", + "types": [ + "vitest/globals", + "vitest/importMeta", + "vite/client", + "node", + "vitest" + ] + }, + "include": [ + "vite.config.ts", + "vite.config.mts", + "vitest.config.ts", + "vitest.config.mts", + "vitest.unit.config.ts", + "src/**/*.test.ts", + "src/**/*.spec.ts", + "src/**/*.test.tsx", + "src/**/*.spec.tsx", + "src/**/*.test.js", + "src/**/*.spec.js", + "src/**/*.test.jsx", + "src/**/*.spec.jsx", + "src/**/*.d.ts" + ] +} diff --git a/tools/jsdoc-annotation-transformer/vitest.unit.config.ts b/tools/jsdoc-annotation-transformer/vitest.unit.config.ts new file mode 100644 index 000000000..0c1d15939 --- /dev/null +++ b/tools/jsdoc-annotation-transformer/vitest.unit.config.ts @@ -0,0 +1,3 @@ +import { createUnitTestConfig } from '../../testing/test-setup-config/src/index.js'; + +export default createUnitTestConfig('jsdoc-annotation-transformer'); From 594f45129ac178611ea0de1a14ac7f1676ea4d44 Mon Sep 17 00:00:00 2001 From: John Doe Date: Tue, 2 Dec 2025 22:59:33 +0100 Subject: [PATCH 02/14] refactor: add zod2md-nx-plugin --- nx.json | 1 + packages/models/project.json | 13 ------- tools/zod2md-nx-plugin/README.md | 40 ++++++++++++++++++++ tools/zod2md-nx-plugin/eslint.config.js | 21 +++++++++++ tools/zod2md-nx-plugin/package.json | 30 +++++++++++++++ tools/zod2md-nx-plugin/project.json | 10 +++++ tools/zod2md-nx-plugin/src/lib/plugin.js | 48 ++++++++++++++++++++++++ tsconfig.base.json | 3 +- 8 files changed, 152 insertions(+), 14 deletions(-) create mode 100644 tools/zod2md-nx-plugin/README.md create mode 100644 tools/zod2md-nx-plugin/eslint.config.js create mode 100644 tools/zod2md-nx-plugin/package.json create mode 100644 tools/zod2md-nx-plugin/project.json create mode 100644 tools/zod2md-nx-plugin/src/lib/plugin.js diff --git a/nx.json b/nx.json index 648165e0f..1a562452b 100644 --- a/nx.json +++ b/nx.json @@ -337,6 +337,7 @@ "releaseTagPattern": "v{version}" }, "plugins": [ + "./tools/zod2md-nx-plugin/src/lib/plugin.js", { "plugin": "@push-based/nx-verdaccio", "options": { diff --git a/packages/models/project.json b/packages/models/project.json index d76e0034f..ae716fb18 100644 --- a/packages/models/project.json +++ b/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", diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md new file mode 100644 index 000000000..dc8a8145b --- /dev/null +++ b/tools/zod2md-nx-plugin/README.md @@ -0,0 +1,40 @@ +# @code-pushup/zod2md-nx-plugin + +[![npm](https://img.shields.io/npm/v/%40code-pushup%2Futils.svg)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin) +[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Futils)](https://npmtrends.com/@code-pushup/zod2md-nx-plugin) +[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/utils)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin?activeTab=dependencies) + +Low-level **utilities** (helper functions, etc.) used by [Code PushUp CLI](../cli/README.md). + +## Setup + +If you've already installed another `@code-pushup/*` package, then you may have already installed `@code-pushup/zod2md-nx-plugin` indirectly. + +If not, you can always install it separately: + +```sh +npm install --save-dev @code-pushup/zod2md-nx-plugin +``` + +```sh +yarn add --dev @code-pushup/zod2md-nx-plugin +``` + +```sh +pnpm add --save-dev @code-pushup/zod2md-nx-plugin +``` + +## Usage + +```ts +import { executeProcess, readJsonFile, slugify } from '@code-pushup/zod2md-nx-plugin'; + +await executeProcess({ + command: 'npx', + args: ['eslint', '--format=json', '--output-file=output.json', '**/*.js'], +}); + +const data = await readJsonFile('output.json'); + +const slug = slugify('Hello, world!'); // "hello-world" +``` diff --git a/tools/zod2md-nx-plugin/eslint.config.js b/tools/zod2md-nx-plugin/eslint.config.js new file mode 100644 index 000000000..fb044aa16 --- /dev/null +++ b/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: [] }], + }, + }, +); diff --git a/tools/zod2md-nx-plugin/package.json b/tools/zod2md-nx-plugin/package.json new file mode 100644 index 000000000..81e3c16ba --- /dev/null +++ b/tools/zod2md-nx-plugin/package.json @@ -0,0 +1,30 @@ +{ + "name": "@code-pushup/zod2md-nx-plugin", + "version": "0.0.0", + "license": "MIT", + "homepage": "https://github.com/code-pushup/cli/tree/main/tools/zod2md-nx-plugin#readme", + "publishConfig": { + "access": "public" + }, + "type": "module", + "engines": { + "node": ">=17.0.0" + }, + "dependencies": { + "@code-pushup/models": "0.92.0", + "ansis": "^3.3.0", + "build-md": "^0.4.2", + "bundle-require": "^5.1.0", + "esbuild": "^0.25.2", + "ora": "^9.0.0", + "semver": "^7.6.0", + "simple-git": "^3.20.0", + "string-width": "^8.1.0", + "wrap-ansi": "^9.0.2", + "zod": "^4.0.5" + }, + "files": [ + "src", + "!**/*.tsbuildinfo" + ] +} diff --git a/tools/zod2md-nx-plugin/project.json b/tools/zod2md-nx-plugin/project.json new file mode 100644 index 000000000..7841ae50c --- /dev/null +++ b/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", "publishable"] +} diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js new file mode 100644 index 000000000..4ad425fe4 --- /dev/null +++ b/tools/zod2md-nx-plugin/src/lib/plugin.js @@ -0,0 +1,48 @@ +import { dirname } from 'node:path'; + +export const createNodesV2 = [ + `**/zod2md.config.ts`, + async (zod2MdConfigurationFiles, createNodesOptions, context) => { + return Promise.all( + zod2MdConfigurationFiles.map(async zod2MdConfigurationFile => { + const projectRoot = dirname(zod2MdConfigurationFile); + const normalizedProjectRoot = projectRoot === '.' ? '' : projectRoot; + const result = { + projects: { + [normalizedProjectRoot]: { + targets: { + 'generate-docs': { + executor: 'nx:run-commands', + options: { + commands: [ + 'zod2md --config {projectRoot}/zod2md.config.ts', + 'prettier --write {projectRoot}/docs/{projectName}-reference.md', + ], + parallel: false, + }, + cache: true, + inputs: [ + 'production', + '^production', + '{projectRoot}/zod2md.config.ts', + ], + outputs: ['{projectRoot}/docs/{projectName}-reference.md'], + }, + }, + }, + }, + }; + + return [zod2MdConfigurationFile, result]; + }), + ); + }, +]; + +// default export for nx.json#plugins +const plugin = { + name: 'zod2md-nx-plugin', + createNodesV2, +}; + +export default plugin; diff --git a/tsconfig.base.json b/tsconfig.base.json index ac98b47ed..d5991b570 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -47,7 +47,8 @@ "@code-pushup/typescript-plugin": [ "packages/plugin-typescript/src/index.ts" ], - "@code-pushup/utils": ["packages/utils/src/index.ts"] + "@code-pushup/utils": ["packages/utils/src/index.ts"], + "@code-pushup/zod2md-nx-plugin": ["tools/zod2md-nx-plugin/src/index.ts"] } }, "exclude": ["node_modules", "tmp"] From 00256ee630b88f63b0e4c62af5eceaf8868cf20a Mon Sep 17 00:00:00 2001 From: John Doe Date: Tue, 2 Dec 2025 23:13:20 +0100 Subject: [PATCH 03/14] refactor: wip --- tools/jsdoc-annotation-transformer/README.md | 4 ++-- tools/jsdoc-annotation-transformer/project.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md index 033289349..b857dbae6 100644 --- a/tools/jsdoc-annotation-transformer/README.md +++ b/tools/jsdoc-annotation-transformer/README.md @@ -12,7 +12,7 @@ The transformer hooks into the TypeScript compilation process using `ts-patch` a - The type name - A description explaining the type is derived from a Zod schema -- A link to the models reference documentation +- A link to the type reference documentation ## Example @@ -51,7 +51,7 @@ export type Report = { "compilerOptions": { "plugins": [ { - "transform": "./packages/models/transformers/dist", + "transform": "./path/to/transformer/dist", "afterDeclarations": true } ] diff --git a/tools/jsdoc-annotation-transformer/project.json b/tools/jsdoc-annotation-transformer/project.json index bcdbbeb48..08705b324 100644 --- a/tools/jsdoc-annotation-transformer/project.json +++ b/tools/jsdoc-annotation-transformer/project.json @@ -1,6 +1,6 @@ { "name": "jsdoc-annotation-transformer", - "$schema": "../../../node_modules/nx/schemas/project-schema.json", + "$schema": "../../node_modules/nx/schemas/project-schema.json", "sourceRoot": "tools/jsdoc-annotation-transformer/src", "projectType": "library", "targets": { From 9112bf0157615e7fa61202e1d913454fe835597d Mon Sep 17 00:00:00 2001 From: John Doe Date: Wed, 3 Dec 2025 00:04:23 +0100 Subject: [PATCH 04/14] refactor: adjust plugin code --- tools/zod2md-nx-plugin/README.md | 106 ++++++++++++++++++----- tools/zod2md-nx-plugin/package.json | 15 +--- tools/zod2md-nx-plugin/src/lib/plugin.js | 13 ++- 3 files changed, 93 insertions(+), 41 deletions(-) diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md index dc8a8145b..998512994 100644 --- a/tools/zod2md-nx-plugin/README.md +++ b/tools/zod2md-nx-plugin/README.md @@ -1,40 +1,100 @@ # @code-pushup/zod2md-nx-plugin -[![npm](https://img.shields.io/npm/v/%40code-pushup%2Futils.svg)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin) -[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Futils)](https://npmtrends.com/@code-pushup/zod2md-nx-plugin) -[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/utils)](https://www.npmjs.com/package/@code-pushup/zod2md-nx-plugin?activeTab=dependencies) +The Nx Plugin for [zod2md](https://github.com/code-pushup/zod2md), a tool for generating documentation from Zod schemas. -Low-level **utilities** (helper functions, etc.) used by [Code PushUp CLI](../cli/README.md). +Why should you use this plugin? -## Setup +- 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 -If you've already installed another `@code-pushup/*` package, then you may have already installed `@code-pushup/zod2md-nx-plugin` indirectly. - -If not, you can always install it separately: +## Usage -```sh -npm install --save-dev @code-pushup/zod2md-nx-plugin +```jsonc +// nx.json +{ + //... + "plugins": ["./tools/zod2md-nx-plugin/src/lib/plugin.js"], +} ``` -```sh -yarn add --dev @code-pushup/zod2md-nx-plugin +or with options: + +```jsonc +// nx.json +{ + //... + "plugins": [ + { + "plugin": "./tools/zod2md-nx-plugin/src/lib/plugin.js", + "options": { + "targetName": "docs", + }, + }, + ], +} ``` -```sh -pnpm add --save-dev @code-pushup/zod2md-nx-plugin +Now every project with a `zod2md.config.ts` file will have a `generate-docs` target automatically created. + +- `nx run :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 +│ └── ... +└── ... ``` -## Usage +The generated target: -```ts -import { executeProcess, readJsonFile, slugify } from '@code-pushup/zod2md-nx-plugin'; +1. Runs `zod2md` with the project's configuration +2. Formats the generated markdown with Prettier +3. Caches the result for better performance -await executeProcess({ - command: 'npx', - args: ['eslint', '--format=json', '--output-file=output.json', '**/*.js'], -}); +## Options -const data = await readJsonFile('output.json'); +| Name | type | description | +| -------------- | ---------------------------------- | ------------------------------------------------------ | +| **targetName** | `string` (DEFAULT 'generate-docs') | The id used to identify a target in your project.json. | -const slug = slugify('Hello, world!'); // "hello-world" +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/code-pushup/zod2md#readme). diff --git a/tools/zod2md-nx-plugin/package.json b/tools/zod2md-nx-plugin/package.json index 81e3c16ba..ebcfdaf59 100644 --- a/tools/zod2md-nx-plugin/package.json +++ b/tools/zod2md-nx-plugin/package.json @@ -2,7 +2,6 @@ "name": "@code-pushup/zod2md-nx-plugin", "version": "0.0.0", "license": "MIT", - "homepage": "https://github.com/code-pushup/cli/tree/main/tools/zod2md-nx-plugin#readme", "publishConfig": { "access": "public" }, @@ -10,19 +9,7 @@ "engines": { "node": ">=17.0.0" }, - "dependencies": { - "@code-pushup/models": "0.92.0", - "ansis": "^3.3.0", - "build-md": "^0.4.2", - "bundle-require": "^5.1.0", - "esbuild": "^0.25.2", - "ora": "^9.0.0", - "semver": "^7.6.0", - "simple-git": "^3.20.0", - "string-width": "^8.1.0", - "wrap-ansi": "^9.0.2", - "zod": "^4.0.5" - }, + "dependencies": {}, "files": [ "src", "!**/*.tsbuildinfo" diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js index 4ad425fe4..01db44686 100644 --- a/tools/zod2md-nx-plugin/src/lib/plugin.js +++ b/tools/zod2md-nx-plugin/src/lib/plugin.js @@ -3,6 +3,9 @@ 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); @@ -11,14 +14,16 @@ export const createNodesV2 = [ projects: { [normalizedProjectRoot]: { targets: { - 'generate-docs': { + [targetName]: { executor: 'nx:run-commands', options: { commands: [ - 'zod2md --config {projectRoot}/zod2md.config.ts', - 'prettier --write {projectRoot}/docs/{projectName}-reference.md', + '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: [ @@ -26,7 +31,7 @@ export const createNodesV2 = [ '^production', '{projectRoot}/zod2md.config.ts', ], - outputs: ['{projectRoot}/docs/{projectName}-reference.md'], + outputs: ['{projectRoot}/docs/{outputFile}'], }, }, }, From 9f83837b1f27e8ac8723743149c50d511a0f58d2 Mon Sep 17 00:00:00 2001 From: John Doe Date: Wed, 3 Dec 2025 00:47:16 +0100 Subject: [PATCH 05/14] refactor: wip --- nx.json | 1 - tools/zod2md-nx-plugin/README.md | 100 ----------------------- tools/zod2md-nx-plugin/eslint.config.js | 21 ----- tools/zod2md-nx-plugin/package.json | 17 ---- tools/zod2md-nx-plugin/project.json | 10 --- tools/zod2md-nx-plugin/src/lib/plugin.js | 53 ------------ tsconfig.base.json | 3 +- 7 files changed, 1 insertion(+), 204 deletions(-) delete mode 100644 tools/zod2md-nx-plugin/README.md delete mode 100644 tools/zod2md-nx-plugin/eslint.config.js delete mode 100644 tools/zod2md-nx-plugin/package.json delete mode 100644 tools/zod2md-nx-plugin/project.json delete mode 100644 tools/zod2md-nx-plugin/src/lib/plugin.js diff --git a/nx.json b/nx.json index 1a562452b..648165e0f 100644 --- a/nx.json +++ b/nx.json @@ -337,7 +337,6 @@ "releaseTagPattern": "v{version}" }, "plugins": [ - "./tools/zod2md-nx-plugin/src/lib/plugin.js", { "plugin": "@push-based/nx-verdaccio", "options": { diff --git a/tools/zod2md-nx-plugin/README.md b/tools/zod2md-nx-plugin/README.md deleted file mode 100644 index 998512994..000000000 --- a/tools/zod2md-nx-plugin/README.md +++ /dev/null @@ -1,100 +0,0 @@ -# @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": "docs", - }, - }, - ], -} -``` - -Now every project with a `zod2md.config.ts` file will have a `generate-docs` target automatically created. - -- `nx run :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 - -## 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/code-pushup/zod2md#readme). diff --git a/tools/zod2md-nx-plugin/eslint.config.js b/tools/zod2md-nx-plugin/eslint.config.js deleted file mode 100644 index fb044aa16..000000000 --- a/tools/zod2md-nx-plugin/eslint.config.js +++ /dev/null @@ -1,21 +0,0 @@ -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: [] }], - }, - }, -); diff --git a/tools/zod2md-nx-plugin/package.json b/tools/zod2md-nx-plugin/package.json deleted file mode 100644 index ebcfdaf59..000000000 --- a/tools/zod2md-nx-plugin/package.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "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" - ] -} diff --git a/tools/zod2md-nx-plugin/project.json b/tools/zod2md-nx-plugin/project.json deleted file mode 100644 index 7841ae50c..000000000 --- a/tools/zod2md-nx-plugin/project.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "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", "publishable"] -} diff --git a/tools/zod2md-nx-plugin/src/lib/plugin.js b/tools/zod2md-nx-plugin/src/lib/plugin.js deleted file mode 100644 index 01db44686..000000000 --- a/tools/zod2md-nx-plugin/src/lib/plugin.js +++ /dev/null @@ -1,53 +0,0 @@ -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; diff --git a/tsconfig.base.json b/tsconfig.base.json index d5991b570..ac98b47ed 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -47,8 +47,7 @@ "@code-pushup/typescript-plugin": [ "packages/plugin-typescript/src/index.ts" ], - "@code-pushup/utils": ["packages/utils/src/index.ts"], - "@code-pushup/zod2md-nx-plugin": ["tools/zod2md-nx-plugin/src/index.ts"] + "@code-pushup/utils": ["packages/utils/src/index.ts"] } }, "exclude": ["node_modules", "tmp"] From 83dd2d8a9043233f5830701c21ae12bf12c6b9ae Mon Sep 17 00:00:00 2001 From: John Doe Date: Wed, 3 Dec 2025 00:49:18 +0100 Subject: [PATCH 06/14] refactor: wip --- packages/models/project.json | 13 +++++++++++++ packages/models/tsconfig.lib.json | 8 +++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/packages/models/project.json b/packages/models/project.json index ae716fb18..d76e0034f 100644 --- a/packages/models/project.json +++ b/packages/models/project.json @@ -4,6 +4,19 @@ "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", diff --git a/packages/models/tsconfig.lib.json b/packages/models/tsconfig.lib.json index 23ebd7dba..d50d80769 100644 --- a/packages/models/tsconfig.lib.json +++ b/packages/models/tsconfig.lib.json @@ -3,7 +3,13 @@ "compilerOptions": { "outDir": "../../dist/out-tsc", "declaration": true, - "types": ["node"] + "types": ["node"], + "plugins": [ + { + "transform": "./tools/jsdoc-annotation-transformer/dist", + "afterDeclarations": true + } + ] }, "include": ["src/**/*.ts"], "exclude": [ From ee323410c4d8e8db23e9b35af973ccb9b08c6ef9 Mon Sep 17 00:00:00 2001 From: John Doe Date: Wed, 3 Dec 2025 00:55:46 +0100 Subject: [PATCH 07/14] refactor: wip --- packages/models/project.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/models/project.json b/packages/models/project.json index d76e0034f..0e2edf4d4 100644 --- a/packages/models/project.json +++ b/packages/models/project.json @@ -21,7 +21,7 @@ "dependsOn": [ "^build", "generate-docs", - { "projects": "jsdocs-annotation-transformer", "target": "build" } + { "projects": "jsdoc-annotation-transformer", "target": "build" } ] }, "lint": {}, From f8a89f81b409c430aa57d77381e4c665f660c765 Mon Sep 17 00:00:00 2001 From: Michael Hladky <10064416+BioPhoton@users.noreply.github.com> Date: Wed, 3 Dec 2025 17:28:11 +0100 Subject: [PATCH 08/14] Update tools/jsdoc-annotation-transformer/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matěj Chalk <34691111+matejchalk@users.noreply.github.com> --- tools/jsdoc-annotation-transformer/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md index b857dbae6..c274633db 100644 --- a/tools/jsdoc-annotation-transformer/README.md +++ b/tools/jsdoc-annotation-transformer/README.md @@ -42,7 +42,7 @@ export type Report = { ## Usage -1. ts-patch install +1. `ts-patch install` 2. Add the transformer to your `tsconfig.json`: From 7221e4295772efdb6de55704f73f88db1b092588 Mon Sep 17 00:00:00 2001 From: Michael Hladky Date: Wed, 3 Dec 2025 17:36:05 +0100 Subject: [PATCH 09/14] refactor: wip --- tools/jsdoc-annotation-transformer/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md index c274633db..e129d558f 100644 --- a/tools/jsdoc-annotation-transformer/README.md +++ b/tools/jsdoc-annotation-transformer/README.md @@ -8,7 +8,7 @@ This package provides a TypeScript compiler transformer that automatically adds ## How It Works -The transformer hooks into the TypeScript compilation process using `ts-patch` and automatically adds JSDoc comments above type definitions. Each comment includes: +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 From d2fd7366b4264121e70ea1f37213b9b26151b270 Mon Sep 17 00:00:00 2001 From: Michael Hladky Date: Thu, 4 Dec 2025 18:24:41 +0100 Subject: [PATCH 10/14] refactor: add baseUrl options --- packages/models/tsconfig.lib.json | 3 ++- tools/jsdoc-annotation-transformer/README.md | 4 +++- .../src/lib/transformers.ts | 19 ++++++++++++------- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/packages/models/tsconfig.lib.json b/packages/models/tsconfig.lib.json index d50d80769..f9efb1eac 100644 --- a/packages/models/tsconfig.lib.json +++ b/packages/models/tsconfig.lib.json @@ -7,7 +7,8 @@ "plugins": [ { "transform": "./tools/jsdoc-annotation-transformer/dist", - "afterDeclarations": true + "afterDeclarations": true, + "baseUrl": "https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md" } ] }, diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/jsdoc-annotation-transformer/README.md index e129d558f..2d0302fd2 100644 --- a/tools/jsdoc-annotation-transformer/README.md +++ b/tools/jsdoc-annotation-transformer/README.md @@ -52,7 +52,8 @@ export type Report = { "plugins": [ { "transform": "./path/to/transformer/dist", - "afterDeclarations": true + "afterDeclarations": true, + "baseUrl": "https://example.com/docs/api-reference.md" } ] } @@ -67,3 +68,4 @@ export type Report = { | ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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`) | diff --git a/tools/jsdoc-annotation-transformer/src/lib/transformers.ts b/tools/jsdoc-annotation-transformer/src/lib/transformers.ts index b61f19455..85b60a6ce 100644 --- a/tools/jsdoc-annotation-transformer/src/lib/transformers.ts +++ b/tools/jsdoc-annotation-transformer/src/lib/transformers.ts @@ -3,11 +3,8 @@ import type * as ts from 'typescript'; const tsInstance: typeof ts = require('typescript'); -const BASE_URL = - 'https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md'; - -function generateJSDocComment(typeName: string): string { - const markdownLink = `${BASE_URL}#${typeName.toLowerCase()}`; +function generateJSDocComment(typeName: string, baseUrl: string): string { + const markdownLink = `${baseUrl}#${typeName.toLowerCase()}`; return `* * Type Definition: \`${typeName}\` * @@ -20,9 +17,17 @@ function generateJSDocComment(typeName: string): string { function annotateTypeDefinitions( _program: ts.Program, - _pluginConfig: PluginConfig, + pluginConfig: PluginConfig, extras?: TransformerExtras, ): ts.TransformerFactory { + const baseUrl = pluginConfig.baseUrl as string | undefined; + + if (!baseUrl) { + throw new Error( + 'jsdoc-annotation-transformer: "baseUrl" option is required. ' + + 'Please configure it in your tsconfig.json plugins section.', + ); + } const tsLib = extras?.ts ?? tsInstance; return (context: ts.TransformationContext) => { const visitor = (node: ts.Node): ts.Node => { @@ -30,7 +35,7 @@ function annotateTypeDefinitions( tsLib.isTypeAliasDeclaration(node) || tsLib.isInterfaceDeclaration(node) ) { - const jsDocComment = generateJSDocComment(node.name.text); + const jsDocComment = generateJSDocComment(node.name.text, baseUrl); tsLib.addSyntheticLeadingComment( node, tsLib.SyntaxKind.MultiLineCommentTrivia, From 96a763d92ff69ee2f64eb60c86338a48cc9cc80a Mon Sep 17 00:00:00 2001 From: Michael Hladky Date: Thu, 4 Dec 2025 19:26:32 +0100 Subject: [PATCH 11/14] refactor: rename --- .../README.md | 0 .../eslint.config.cjs | 0 .../package.json | 0 .../project.json | 10 +++++----- .../src/index.ts | 0 .../src/lib/transformers.ts | 8 ++++---- .../tsconfig.json | 0 .../tsconfig.lib.json | 0 .../tsconfig.spec.json | 0 .../vitest.unit.config.ts | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/README.md (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/eslint.config.cjs (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/package.json (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/project.json (58%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/src/index.ts (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/src/lib/transformers.ts (91%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/tsconfig.json (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/tsconfig.lib.json (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/tsconfig.spec.json (100%) rename tools/{jsdoc-annotation-transformer => zod2md-jsdocs}/vitest.unit.config.ts (55%) diff --git a/tools/jsdoc-annotation-transformer/README.md b/tools/zod2md-jsdocs/README.md similarity index 100% rename from tools/jsdoc-annotation-transformer/README.md rename to tools/zod2md-jsdocs/README.md diff --git a/tools/jsdoc-annotation-transformer/eslint.config.cjs b/tools/zod2md-jsdocs/eslint.config.cjs similarity index 100% rename from tools/jsdoc-annotation-transformer/eslint.config.cjs rename to tools/zod2md-jsdocs/eslint.config.cjs diff --git a/tools/jsdoc-annotation-transformer/package.json b/tools/zod2md-jsdocs/package.json similarity index 100% rename from tools/jsdoc-annotation-transformer/package.json rename to tools/zod2md-jsdocs/package.json diff --git a/tools/jsdoc-annotation-transformer/project.json b/tools/zod2md-jsdocs/project.json similarity index 58% rename from tools/jsdoc-annotation-transformer/project.json rename to tools/zod2md-jsdocs/project.json index 08705b324..18501546f 100644 --- a/tools/jsdoc-annotation-transformer/project.json +++ b/tools/zod2md-jsdocs/project.json @@ -1,7 +1,7 @@ { - "name": "jsdoc-annotation-transformer", + "name": "zod2md-jsdocs", "$schema": "../../node_modules/nx/schemas/project-schema.json", - "sourceRoot": "tools/jsdoc-annotation-transformer/src", + "sourceRoot": "tools/zod2md-jsdocs/src", "projectType": "library", "targets": { "build": { @@ -9,9 +9,9 @@ "outputs": ["{options.outputPath}"], "dependsOn": ["pre-build"], "options": { - "outputPath": "tools/jsdoc-annotation-transformer/dist", - "main": "tools/jsdoc-annotation-transformer/src/index.ts", - "tsConfig": "tools/jsdoc-annotation-transformer/tsconfig.lib.json" + "outputPath": "tools/zod2md-jsdocs/dist", + "main": "tools/zod2md-jsdocs/src/index.ts", + "tsConfig": "tools/zod2md-jsdocs/tsconfig.lib.json" } }, "pre-build": { diff --git a/tools/jsdoc-annotation-transformer/src/index.ts b/tools/zod2md-jsdocs/src/index.ts similarity index 100% rename from tools/jsdoc-annotation-transformer/src/index.ts rename to tools/zod2md-jsdocs/src/index.ts diff --git a/tools/jsdoc-annotation-transformer/src/lib/transformers.ts b/tools/zod2md-jsdocs/src/lib/transformers.ts similarity index 91% rename from tools/jsdoc-annotation-transformer/src/lib/transformers.ts rename to tools/zod2md-jsdocs/src/lib/transformers.ts index 85b60a6ce..33fb2e6ba 100644 --- a/tools/jsdoc-annotation-transformer/src/lib/transformers.ts +++ b/tools/zod2md-jsdocs/src/lib/transformers.ts @@ -7,10 +7,10 @@ function generateJSDocComment(typeName: string, baseUrl: string): string { const markdownLink = `${baseUrl}#${typeName.toLowerCase()}`; return `* * Type Definition: \`${typeName}\` - * - * This type is derived from a Zod schema and represents + * + * This type is derived from a Zod schema and represents * the validated structure of \`${typeName}\` used within the application. - * + * * @see {@link ${markdownLink}} `; } @@ -24,7 +24,7 @@ function annotateTypeDefinitions( if (!baseUrl) { throw new Error( - 'jsdoc-annotation-transformer: "baseUrl" option is required. ' + + 'zod2md-jsdocs: "baseUrl" option is required. ' + 'Please configure it in your tsconfig.json plugins section.', ); } diff --git a/tools/jsdoc-annotation-transformer/tsconfig.json b/tools/zod2md-jsdocs/tsconfig.json similarity index 100% rename from tools/jsdoc-annotation-transformer/tsconfig.json rename to tools/zod2md-jsdocs/tsconfig.json diff --git a/tools/jsdoc-annotation-transformer/tsconfig.lib.json b/tools/zod2md-jsdocs/tsconfig.lib.json similarity index 100% rename from tools/jsdoc-annotation-transformer/tsconfig.lib.json rename to tools/zod2md-jsdocs/tsconfig.lib.json diff --git a/tools/jsdoc-annotation-transformer/tsconfig.spec.json b/tools/zod2md-jsdocs/tsconfig.spec.json similarity index 100% rename from tools/jsdoc-annotation-transformer/tsconfig.spec.json rename to tools/zod2md-jsdocs/tsconfig.spec.json diff --git a/tools/jsdoc-annotation-transformer/vitest.unit.config.ts b/tools/zod2md-jsdocs/vitest.unit.config.ts similarity index 55% rename from tools/jsdoc-annotation-transformer/vitest.unit.config.ts rename to tools/zod2md-jsdocs/vitest.unit.config.ts index 0c1d15939..f32d2557d 100644 --- a/tools/jsdoc-annotation-transformer/vitest.unit.config.ts +++ b/tools/zod2md-jsdocs/vitest.unit.config.ts @@ -1,3 +1,3 @@ import { createUnitTestConfig } from '../../testing/test-setup-config/src/index.js'; -export default createUnitTestConfig('jsdoc-annotation-transformer'); +export default createUnitTestConfig('zod2md-jsdocs'); From e751c3f465386d7e1f7405d938c35828b20593e1 Mon Sep 17 00:00:00 2001 From: Michael Hladky Date: Thu, 4 Dec 2025 19:30:10 +0100 Subject: [PATCH 12/14] refactor: rename --- packages/models/project.json | 2 +- packages/models/tsconfig.lib.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/models/project.json b/packages/models/project.json index 0e2edf4d4..04f0cc1d2 100644 --- a/packages/models/project.json +++ b/packages/models/project.json @@ -21,7 +21,7 @@ "dependsOn": [ "^build", "generate-docs", - { "projects": "jsdoc-annotation-transformer", "target": "build" } + { "projects": "zod2md-jsdoc", "target": "build" } ] }, "lint": {}, diff --git a/packages/models/tsconfig.lib.json b/packages/models/tsconfig.lib.json index f9efb1eac..366c01702 100644 --- a/packages/models/tsconfig.lib.json +++ b/packages/models/tsconfig.lib.json @@ -6,7 +6,7 @@ "types": ["node"], "plugins": [ { - "transform": "./tools/jsdoc-annotation-transformer/dist", + "transform": "./tools/zod2md-jsdocs/dist", "afterDeclarations": true, "baseUrl": "https://github.com/code-pushup/cli/blob/main/packages/models/docs/models-reference.md" } From 2a94cd8477f6e2785dbb2826eac0ca95a32a8515 Mon Sep 17 00:00:00 2001 From: Michael Hladky Date: Thu, 4 Dec 2025 19:31:52 +0100 Subject: [PATCH 13/14] refactor: wip --- tools/zod2md-jsdocs/README.md | 2 +- tools/zod2md-jsdocs/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/zod2md-jsdocs/README.md b/tools/zod2md-jsdocs/README.md index 2d0302fd2..c56a57a0b 100644 --- a/tools/zod2md-jsdocs/README.md +++ b/tools/zod2md-jsdocs/README.md @@ -1,4 +1,4 @@ -# @code-pushup/jsdocs-annotation-transformer +# @code-pushup/zod2md-jsdocs TypeScript transformer plugin that automatically enhances type definitions with JSDoc comments and schema metadata. diff --git a/tools/zod2md-jsdocs/package.json b/tools/zod2md-jsdocs/package.json index 273fd5821..e29c5d9db 100644 --- a/tools/zod2md-jsdocs/package.json +++ b/tools/zod2md-jsdocs/package.json @@ -1,5 +1,5 @@ { - "name": "@code-pushup/jsdocs-annotation-transformer", + "name": "@code-pushup/zod2md-jsdocs", "version": "0.0.0", "description": "TypeScript transformers enhancing models with JSDoc and schema metadata", "type": "commonjs", From c40f9b182f321f87d172f0585e6789f9c7b6ce63 Mon Sep 17 00:00:00 2001 From: Michael Hladky Date: Thu, 4 Dec 2025 19:37:45 +0100 Subject: [PATCH 14/14] refactor: wip --- packages/models/project.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/models/project.json b/packages/models/project.json index 04f0cc1d2..b09523d29 100644 --- a/packages/models/project.json +++ b/packages/models/project.json @@ -21,7 +21,7 @@ "dependsOn": [ "^build", "generate-docs", - { "projects": "zod2md-jsdoc", "target": "build" } + { "projects": "zod2md-jsdocs", "target": "build" } ] }, "lint": {},