chore: add zod2md-nx-plugin #1162
+355
−87
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,7 +18,4 @@ export default tseslint.config( | |
| '@nx/dependency-checks': 'error', | ||
| }, | ||
| }, | ||
| ); | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # @code-pushup/zod2md-jsdocs-nx-plugin | ||
|
|
||
| The Nx Plugin for [zod2md](https://github.com/matejchalk/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-jsdocs-nx-plugin/src/lib/plugin.js"], | ||
|
Collaborator
There was a problem hiding this comment. The path |
||
| } | ||
| ``` | ||
|
|
||
| or with options: | ||
|
|
||
| ```jsonc | ||
| // nx.json | ||
| { | ||
| //... | ||
| "plugins": [ | ||
| { | ||
| "plugin": "./tools/zod2md-jsdocs-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 | | ||
| | --------------------------- | ---------------------------------- | ------------------------------------------------------------------- | | ||
| | **docsTargetName** | `string` (DEFAULT 'generate-docs') | The name of the docs generation target. | | ||
| | **jsDocsTypesAugmentation** | `boolean` (DEFAULT `true`) | Whether to enable TypeScript transformer integration with ts-patch. | | ||
|
|
||
| All options are optional and provided in the `nx.json` file. | ||
|
|
||
| ```jsonc | ||
| // nx.json | ||
| { | ||
| //... | ||
| "plugins": [ | ||
| { | ||
| "plugin": "./tools/zod2md-jsdocs-nx-plugin/src/lib/plugin.js", | ||
| "options": { | ||
| "docsTargetName": "docs", | ||
| "jsDocsTypesAugmentation": true, | ||
| }, | ||
| }, | ||
| ], | ||
| } | ||
| ``` | ||
|
|
||
| ## 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). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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": "./tools/zod2md-jsdocs/dist", | ||
| "afterDeclarations": true, | ||
| "baseUrl": "https://github.com/code-pushup/cli/blob/main/packages/<PROJECT-NAME>/docs/models-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`) | |
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,20 +4,8 @@ | |
| "sourceRoot": "tools/zod2md-jsdocs/src", | ||
| "projectType": "library", | ||
| "targets": { | ||
|
Comment on lines
-17
to
-21
Collaborator
There was a problem hiding this comment. I would restore this target - see previous comment. I'm fine with renaming |
||
| "lint": {}, | ||
| "build": {}, | ||
| "unit-test": {} | ||
| } | ||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please restore this line - see previous comment.