feat: 🎸 add JSDoc parsing for classes and methods

nivekcode · nivekcode · commit fd9615ee5872 · 2025-09-23T16:06:27.000+02:00
diff --git a/src/parser/component/component.model.ts b/src/parser/component/component.model.ts
@@ -14,4 +14,5 @@ export interface NgParselComponent extends NgParselOutput {
   template: string;
   styles: string | string[];
   methodsPublicExplicit: NgParselMethod[];
+  classJsDoc?: string | undefined;
 }
diff --git a/src/parser/component/component.parser.ts b/src/parser/component/component.parser.ts
@@ -6,7 +6,7 @@ import { tsquery } from '@phenomnomnominal/tsquery';
 import { parseInputsAndOutputs } from '../shared/parser/field-decorator.parser.js';
 import { parseExplicitPublicMethods } from '../shared/parser/method.parser.js';
 import { NgParselOutputType } from '../shared/model/types.model.js';
-import { parseClassName } from '../shared/parser/class.parser.js';
+import { parseClassName, parseClassJsDoc } from '../shared/parser/class.parser.js';
 
 import { NgParselComponent } from './component.model.js';
 import { getDecoratorProperties } from '../shared/parser/decorator.parser.js';
@@ -39,6 +39,7 @@ export function parseComponent(ast: ts.SourceFile, componentFilePath: string): N
     inputs: inputsAndOutputs.inputs,
     outputs: inputsAndOutputs.outputs,
     methodsPublicExplicit: parseExplicitPublicMethods(ast),
+    classJsDoc: parseClassJsDoc(ast),
   };
 }
 
diff --git a/src/parser/directive/directive.model.ts b/src/parser/directive/directive.model.ts
@@ -10,4 +10,5 @@ export interface NgParselDirective extends NgParselOutput {
   inputs: NgParselFieldDecorator[];
   outputs: NgParselFieldDecorator[];
   methodsPublicExplicit: NgParselMethod[];
+  classJsDoc?: string | undefined;
 }
diff --git a/src/parser/directive/directive.parser.ts b/src/parser/directive/directive.parser.ts
@@ -1,7 +1,7 @@
 import { readFileSync } from 'fs';
 import * as ts from 'typescript';
 
-import { parseClassName } from '../shared/parser/class.parser.js';
+import { parseClassName, parseClassJsDoc } from '../shared/parser/class.parser.js';
 import { NgParselOutputType } from '../shared/model/types.model.js';
 import { getDecoratorProperties } from '../shared/parser/decorator.parser.js';
 import { parseInputsAndOutputs } from '../shared/parser/field-decorator.parser.js';
@@ -26,5 +26,6 @@ export function parseDirective(ast: ts.SourceFile, directiveFilePath: string): N
     inputs: inputsAndOutputs.inputs,
     outputs: inputsAndOutputs.outputs,
     methodsPublicExplicit: parseExplicitPublicMethods(ast),
+    classJsDoc: parseClassJsDoc(ast),
   };
 }
diff --git a/src/parser/pipe/pipe.model.ts b/src/parser/pipe/pipe.model.ts
@@ -6,4 +6,5 @@ export interface NgParselPipe extends NgParselOutput {
   pure: boolean;
   standalone: boolean;
   implementation: string;
+  classJsDoc?: string | undefined;
 }
diff --git a/src/parser/pipe/pipe.parser.ts b/src/parser/pipe/pipe.parser.ts
@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 import { readFileSync } from 'fs';
 
-import { parseClassName } from '../shared/parser/class.parser.js';
+import { parseClassName, parseClassJsDoc } from '../shared/parser/class.parser.js';
 import { NgParselOutputType } from '../shared/model/types.model.js';
 import { getDecoratorProperties } from '../shared/parser/decorator.parser.js';
 
@@ -19,5 +19,6 @@ export function parsePipe(ast: ts.SourceFile, pipeFilePath: string): NgParselPip
     pure: pipeDecorators.pure || true,
     standalone: pipeDecorators.standalone || false,
     implementation: pipeImplementation,
+    classJsDoc: parseClassJsDoc(ast),
   };
 }
diff --git a/src/parser/services/service.model.ts b/src/parser/services/service.model.ts
@@ -5,4 +5,5 @@ import { NgParselField } from '../shared/model/field.model.js';
 export interface NgParselService extends NgParselOutput {
   fieldsPublicExplicit: NgParselField[];
   methodsPublicExplicit: NgParselMethod[];
+  classJsDoc?: string | undefined;
 }
diff --git a/src/parser/services/service.parser.ts b/src/parser/services/service.parser.ts
@@ -1,7 +1,7 @@
 import * as ts from 'typescript';
 
 import { NgParselOutputType } from '../shared/model/types.model.js';
-import { parseClassName } from '../shared/parser/class.parser.js';
+import { parseClassName, parseClassJsDoc } from '../shared/parser/class.parser.js';
 import { parseExplicitPublicMethods } from '../shared/parser/method.parser.js';
 
 import { NgParselService } from './service.model.js';
@@ -14,5 +14,6 @@ export function parseService(ast: ts.SourceFile, filePath: string): NgParselServ
     filePath,
     fieldsPublicExplicit: parseExplicitPublicFields(ast),
     methodsPublicExplicit: parseExplicitPublicMethods(ast),
+    classJsDoc: parseClassJsDoc(ast),
   };
 }
diff --git a/src/parser/shared/model/method.model.ts b/src/parser/shared/model/method.model.ts
@@ -4,4 +4,5 @@ export interface NgParselMethod {
   name: string;
   args: NgParselArgs[];
   returnType: string;
+  jsDoc?: string | undefined;
 }
diff --git a/src/parser/shared/parser/class.parser.spec.ts b/src/parser/shared/parser/class.parser.spec.ts
@@ -1,6 +1,6 @@
 import { tsquery } from '@phenomnomnominal/tsquery';
 
-import { parseClassName } from './class.parser.js';
+import { parseClassName, parseClassJsDoc } from './class.parser.js';
 
 describe('ClassParser', () => {
   it('should extract the class name', () => {
@@ -9,4 +9,51 @@ describe('ClassParser', () => {
         `);
     expect(parseClassName(ast)).toEqual('MyTestClass');
   });
+
+  it('should return undefined for class JSDoc when no JSDoc exists', () => {
+    const ast = tsquery.ast(`
+        export class MyTestClass {
+            public myExplicitMethod(foo: string, bar: boolean): string {
+            }
+        }
+    `);
+
+    expect(parseClassJsDoc(ast)).toBeUndefined();
+  });
+
+  it('should parse JSDoc comments for class declarations', () => {
+    const ast = tsquery.ast(`
+        /**
+         * This is a JSDoc comment for MyTestClass
+         * @description A test class
+         * @example
+         * const myClass = new MyTestClass();
+         */
+        export class MyTestClass {
+            public myExplicitMethod(foo: string, bar: boolean): string {
+              return 'test';
+            }
+        }
+    `);
+
+    expect(parseClassJsDoc(ast)).toEqual('This is a JSDoc comment for MyTestClass\n@description A test class\n@example const myClass = new MyTestClass();');
+  });
+
+  it('should parse JSDoc comments with multiple tags', () => {
+    const ast = tsquery.ast(`
+        /**
+         * This is a JSDoc comment for MyTestClass
+         * @description A test class
+         * @deprecated Use NewTestClass instead
+         * @since 1.0.0
+         */
+        export class MyTestClass {
+            public myExplicitMethod(foo: string, bar: boolean): string {
+              return 'test';
+            }
+        }
+    `);
+
+    expect(parseClassJsDoc(ast)).toEqual('This is a JSDoc comment for MyTestClass\n@description A test class\n@deprecated Use NewTestClass instead\n@since 1.0.0');
+  });
 });
diff --git a/src/parser/shared/parser/class.parser.ts b/src/parser/shared/parser/class.parser.ts
@@ -1,7 +1,37 @@
 import * as ts from 'typescript';
 import { tsquery } from '@phenomnomnominal/tsquery';
 
+/**
+ * Extracts JSDoc comments from a TypeScript node
+ * @param node The TypeScript node to extract JSDoc comments from
+ * @returns The extracted JSDoc comment as a string, or undefined if no JSDoc comment exists
+ */
+function extractJSDocComment(node: ts.Node | undefined): string | undefined {
+  if (!node) return undefined;
+
+  const jsDocs = (node as any).jsDoc as ts.JSDoc[] | undefined;
+  if (!jsDocs || jsDocs.length === 0) return undefined;
+
+  const jsDoc = jsDocs[0];
+  let result = (jsDoc?.comment as string) ?? '';
+
+  if (jsDoc?.tags) {
+    for (const tag of jsDoc.tags) {
+      result += `\n@${tag.tagName.getText()} ${tag.comment ?? ''}`;
+    }
+  }
+
+  return result.trim();
+}
+
 export function parseClassName(ast: ts.SourceFile): string {
   const classDeclarations = [...tsquery(ast, 'ClassDeclaration > Identifier')] as ts.Identifier[];
   return classDeclarations[0]?.getText() as string;
 }
+
+export function parseClassJsDoc(ast: ts.SourceFile): string | undefined {
+  const classDeclarations = [...tsquery(ast, 'ClassDeclaration')] as ts.ClassDeclaration[];
+  if (classDeclarations.length === 0) return undefined;
+
+  return extractJSDocComment(classDeclarations[0]);
+}
diff --git a/src/parser/shared/parser/method.parser.spec.ts b/src/parser/shared/parser/method.parser.spec.ts
@@ -21,6 +21,7 @@ describe('MethodParser', () => {
           { name: 'bar', type: 'boolean' },
         ],
         returnType: 'string',
+        jsDoc: undefined,
       },
     ];
 
@@ -45,6 +46,40 @@ describe('MethodParser', () => {
           { name: 'bar', type: 'boolean' },
         ],
         returnType: 'string',
+        jsDoc: undefined,
+      },
+    ];
+
+    expect(parseExplicitPublicMethods(ast)).toEqual(expectedOutput);
+  });
+
+  it('should parse JSDoc comments for explicit public methods', () => {
+    const ast = tsquery.ast(`
+        export class MyTestClass {
+            /**
+             * This is a JSDoc comment for myExplicitMethod
+             * @param foo The foo parameter
+             * @param bar The bar parameter
+             * @returns A string value
+             */
+            public myExplicitMethod(foo: string, bar: boolean): string {
+              return 'test';
+            }
+        
+            myMethod(foo: string, bar: boolean): string {
+              return 'test';
+            }
+        `);
+
+    const expectedOutput = [
+      {
+        name: 'myExplicitMethod',
+        args: [
+          { name: 'foo', type: 'string' },
+          { name: 'bar', type: 'boolean' },
+        ],
+        returnType: 'string',
+        jsDoc: 'This is a JSDoc comment for myExplicitMethod\n@param foo The foo parameter\n@param bar The bar parameter\n@returns A string value',
       },
     ];
 
diff --git a/src/parser/shared/parser/method.parser.ts b/src/parser/shared/parser/method.parser.ts
@@ -4,14 +4,40 @@ import { tsquery } from '@phenomnomnominal/tsquery';
 import { NgParselArgs } from '../model/args.model.js';
 import { NgParselMethod } from '../model/method.model.js';
 
+/**
+ * Extracts JSDoc comments from a TypeScript node
+ * @param node The TypeScript node to extract JSDoc comments from
+ * @returns The extracted JSDoc comment as a string, or undefined if no JSDoc comment exists
+ */
+function extractJSDocComment(node: ts.Node | undefined): string | undefined {
+  if (!node) return undefined;
+
+  const jsDocs = (node as any).jsDoc as ts.JSDoc[] | undefined;
+  if (!jsDocs || jsDocs.length === 0) return undefined;
+
+  const jsDoc = jsDocs[0];
+  let result = (jsDoc?.comment as string) ?? '';
+
+  if (jsDoc?.tags) {
+    for (const tag of jsDoc.tags) {
+      result += `\n@${tag.tagName.getText()} ${tag.comment ?? ''}`;
+    }
+  }
+
+  return result.trim();
+}
+
 export function parseExplicitPublicMethods(ast: ts.SourceFile): NgParselMethod[] {
-  const explicitMethods = tsquery(ast, 'MethodDeclaration:has(PublicKeyword)');
 
-  return explicitMethods.map((method: any) => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const explicitMethods = tsquery(ast, 'MethodDeclaration:has(PublicKeyword)') as any[];
+
+  return explicitMethods.map((method) => {
     return {
       name: method.name.getText(),
       args: method.parameters.map((parameters: ts.ParameterDeclaration) => parseMethodParameters(parameters)),
       returnType: method.type?.getText(),
+      jsDoc: extractJSDocComment(method),
     };
   });
 }

Original file line number	Diff line number	Diff line change
`@@ -14,4 +14,5 @@ export interface NgParselComponent extends NgParselOutput {`
`14`	`14`	`template: string;`
`15`	`15`	`styles: string \| string[];`
`16`	`16`	`methodsPublicExplicit: NgParselMethod[];`
	`17`	`+ classJsDoc?: string \| undefined;`
`17`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -10,4 +10,5 @@ export interface NgParselDirective extends NgParselOutput {`
`10`	`10`	`inputs: NgParselFieldDecorator[];`
`11`	`11`	`outputs: NgParselFieldDecorator[];`
`12`	`12`	`methodsPublicExplicit: NgParselMethod[];`
	`13`	`+ classJsDoc?: string \| undefined;`
`13`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,4 +6,5 @@ export interface NgParselPipe extends NgParselOutput {`
`6`	`6`	`pure: boolean;`
`7`	`7`	`standalone: boolean;`
`8`	`8`	`implementation: string;`
	`9`	`+ classJsDoc?: string \| undefined;`
`9`	`10`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,4 +5,5 @@ import { NgParselField } from '../shared/model/field.model.js';`
`5`	`5`	`export interface NgParselService extends NgParselOutput {`
`6`	`6`	`fieldsPublicExplicit: NgParselField[];`
`7`	`7`	`methodsPublicExplicit: NgParselMethod[];`
	`8`	`+ classJsDoc?: string \| undefined;`
`8`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,5 @@ export interface NgParselMethod {`
`4`	`4`	`name: string;`
`5`	`5`	`args: NgParselArgs[];`
`6`	`6`	`returnType: string;`
	`7`	`+ jsDoc?: string \| undefined;`
`7`	`8`	`}`