refactor: add baseUrl options

Author: Michael Hladky

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"
       }
     ]
   },

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`)                                                                                |

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,17 +17,25 @@ function generateJSDocComment(typeName: string): string {
 
 function annotateTypeDefinitions(
   _program: ts.Program,
-  _pluginConfig: PluginConfig,
+  pluginConfig: PluginConfig,
   extras?: TransformerExtras,
 ): ts.TransformerFactory<ts.SourceFile> {
+  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 => {
       if (
         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,