feat(models): auto-generate JSDoc annotations

Author: hanna-skryl

package-lock.json

@@ -108,6 +108,7 @@
     "prettier": "^3.4.1",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "ts-patch": "^3.3.0",
     "tsconfig-paths": "^4.2.0",
     "tsx": "^4.19.0",
     "type-fest": "^4.26.1",

package.json

@@ -4,7 +4,7 @@ import baseConfig from '../../eslint.config.js';
 export default tseslint.config(
   ...baseConfig,
   {
-    files: ['**/*.ts'],
+    files: ['/**/*.ts'],
     languageOptions: {
       parserOptions: {
         projectService: true,
@@ -18,4 +18,7 @@ export default tseslint.config(
       '@nx/dependency-checks': 'error',
     },
   },
+  {
+    ignores: ['packages/models/transformers/**/*.ts'],
+  },
 );

packages/models/eslint.config.js

@@ -3,6 +3,7 @@
   "$schema": "../../node_modules/nx/schemas/project-schema.json",
   "sourceRoot": "packages/models/src",
   "projectType": "library",
+  "implicitDependencies": ["models-transformers"],
   "targets": {
     "build": {
       "executor": "@nx/js:tsc",

packages/models/project.json

@@ -0,0 +1,11 @@
+const baseConfig = require('../../../eslint.config.js').default;
+
+module.exports = [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': 'error',
+    },
+  },
+];

packages/models/transformers/eslint.config.cjs

@@ -0,0 +1,11 @@
+{
+  "name": "@code-pushup/models-transformers",
+  "version": "0.0.0",
+  "description": "TypeScript transformers enhancing models with JSDoc and schema metadata",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "dependencies": {
+    "typescript": "^5.5.4",
+    "ts-patch": "^3.3.0"
+  }
+}

packages/models/transformers/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "models-transformers",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/models/transformers/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "dependsOn": [{ "target": "pre-build" }],
+      "options": {
+        "outputPath": "dist/packages/models-transformers",
+        "main": "packages/models/transformers/src/index.ts",
+        "tsConfig": "packages/models/transformers/tsconfig.lib.json"
+      }
+    },
+    "pre-build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "npx ts-patch install"
+      }
+    }
+  }
+}

packages/models/transformers/project.json

@@ -0,0 +1,4 @@
+const transformers = require('./lib/transformers.js');
+
+module.exports = transformers;
+module.exports.default = transformers;

packages/models/transformers/src/index.ts

@@ -0,0 +1,50 @@
+import type { PluginConfig, TransformerExtras } from 'ts-patch';
+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()}`;
+  return `*
+ * Type Definition: \`${typeName}\`
+ * 
+ * This type is derived from a Zod schema and represents 
+ * the validated structure of \`${typeName}\` used within the application.
+ * 
+ * @see {@link ${markdownLink}}
+ `;
+}
+
+function annotateTypeDefinitions(
+  _program: ts.Program,
+  _pluginConfig: PluginConfig,
+  extras?: TransformerExtras,
+): ts.TransformerFactory<ts.SourceFile> {
+  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);
+        tsLib.addSyntheticLeadingComment(
+          node,
+          tsLib.SyntaxKind.MultiLineCommentTrivia,
+          jsDocComment,
+          true,
+        );
+        return node;
+      }
+      return tsLib.visitEachChild(node, visitor, context);
+    };
+    return (sourceFile: ts.SourceFile) => {
+      return tsLib.visitNode(sourceFile, visitor, tsLib.isSourceFile);
+    };
+  };
+}
+
+module.exports = annotateTypeDefinitions;

packages/models/transformers/src/lib/transformers.ts

@@ -0,0 +1,14 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "verbatimModuleSyntax": false
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}