feat(plugin-doc-coverage): add support for variable statement to be documented, improve test

Author: aramirezj

code-pushup.config.bundled_oq2x2csd2at.mjs

@@ -9,41 +9,3 @@ export function DUMMY_FUNCTION() {
 export function DUMMY_FUNCTION_2() {
   return 'Hello World 2';
 }
-
-// class DummyClass {
-//   /**
-//    * Dummy property that returns 'Hello World 3'.
-//    * @returns {string} - The string 'Hello World 3'.
-//    */
-//   dummyProperty = 'Hello World 3';
-
-//   /**
-//    * Dummy method that returns 'Hello World 4'.
-//    * @returns {string} - The string 'Hello World 4'.
-//    */
-//   dummyMethod() {
-//     return 'Hello World 4';
-//   }
-
-//   constructor() {
-//     this.dummyProperty = 'Hello World 3';
-//   }
-// }
-
-// export default DummyClass;
-
-// export const variableDummy = 'Hello World 5';
-
-// export const variableDummy2 = 'Hello World 6';
-
-// /** Dummy variable that returns 'Hello World 7'. */
-// export const variableDummy3 = 'Hello World 7';
-
-// /** Dummy interface that returns 'Hello World 8'. */
-// export interface DummyInterface {
-//   dummyProperty: string;
-//   dummyMethod(): string;
-// }
-
-// /** Dummy type that returns 'Hello World 9'. */
-// export type DummyType = string;

packages/plugin-doc-coverage/mocks/component-mock.ts

@@ -1,3 +1,5 @@
+export const someVariable = 'Hello World 1';
+
 export function mapEventToCustomEvent(event: string) {
   return event;
 }

packages/plugin-doc-coverage/mocks/fixtures/angular/map-event.function.ts

@@ -6,70 +6,37 @@ import {
   SourceFile,
   SyntaxKind,
   TypeAliasDeclaration,
+  VariableStatement,
 } from 'ts-morph';
-import type { CoverageType } from '../src/lib/models';
+import type { CoverageType } from '../src/lib/runner/models';
 
 export function sourceFileMock(
   file: string,
   nodes: Partial<Record<CoverageType, Record<number, boolean>>>,
 ): SourceFile {
+  const createNodeGetter = <T>(
+    coverageType: CoverageType,
+    nodeData?: Record<number, boolean>,
+  ) => {
+    if (!nodeData) return [];
+    return Object.entries(nodeData).map(([line, isCommented]) =>
+      nodeMock({ coverageType, line: Number(line), file, isCommented }),
+    ) as unknown as T[];
+  };
+
   return {
     getFilePath: () => file as any,
     getClasses: () =>
-      nodes.classes
-        ? (Object.entries(nodes.classes).map(([line, isCommented]) =>
-            nodeMock({
-              coverageType: 'classes',
-              line: Number(line),
-              file,
-              isCommented,
-            }),
-          ) as unknown as ClassDeclaration[])
-        : [],
+      createNodeGetter<ClassDeclaration>('classes', nodes.classes),
     getFunctions: () =>
-      nodes.functions
-        ? (Object.entries(nodes.functions).map(([line, isCommented]) =>
-            nodeMock({
-              coverageType: 'functions',
-              line: Number(line),
-              file,
-              isCommented,
-            }),
-          ) as unknown as FunctionDeclaration[])
-        : [],
-    getEnums: () =>
-      nodes.enums
-        ? (Object.entries(nodes.enums).map(([line, isCommented]) =>
-            nodeMock({
-              coverageType: 'enums',
-              line: Number(line),
-              file,
-              isCommented,
-            }),
-          ) as unknown as EnumDeclaration[])
-        : [],
+      createNodeGetter<FunctionDeclaration>('functions', nodes.functions),
+    getEnums: () => createNodeGetter<EnumDeclaration>('enums', nodes.enums),
     getTypeAliases: () =>
-      nodes.types
-        ? (Object.entries(nodes.types).map(([line, isCommented]) =>
-            nodeMock({
-              coverageType: 'types',
-              line: Number(line),
-              file,
-              isCommented,
-            }),
-          ) as unknown as TypeAliasDeclaration[])
-        : [],
+      createNodeGetter<TypeAliasDeclaration>('types', nodes.types),
     getInterfaces: () =>
-      nodes.interfaces
-        ? (Object.entries(nodes.interfaces).map(([line, isCommented]) =>
-            nodeMock({
-              coverageType: 'interfaces',
-              line: Number(line),
-              file,
-              isCommented,
-            }),
-          ) as unknown as InterfaceDeclaration[])
-        : [],
+      createNodeGetter<InterfaceDeclaration>('interfaces', nodes.interfaces),
+    getVariableStatements: () =>
+      createNodeGetter<VariableStatement>('variables', nodes.variables),
   } as SourceFile;
 }
 
@@ -84,6 +51,7 @@ export function nodeMock(options: {
     getJsDocs: () => (options.isCommented ? ['Comment'] : []),
     getName: () => 'test',
     getStartLineNumber: () => options.line,
+    getDeclarations: () => [],
     // Only for classes
     getMethods: () => [],
     getProperties: () => [],

packages/plugin-doc-coverage/mocks/source-files.mock.ts

@@ -23,7 +23,7 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
       },
       {
         "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/map-event.function.ts",
-        "line": 1,
+        "line": 3,
         "name": "mapEventToCustomEvent",
         "type": "functions",
       },
@@ -40,7 +40,7 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "issues": [
       {
         "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/app.component.ts",
-        "line": 15,
+        "line": 17,
         "name": "sendEvent",
         "type": "methods",
       },
@@ -52,7 +52,7 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "issues": [
       {
         "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/app.component.ts",
-        "line": 5,
+        "line": 7,
         "name": "title",
         "type": "properties",
       },
@@ -65,9 +65,16 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "nodesCount": 0,
   },
   "variables": {
-    "coverage": 100,
-    "issues": [],
-    "nodesCount": 0,
+    "coverage": 0,
+    "issues": [
+      {
+        "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/map-event.function.ts",
+        "line": 1,
+        "name": "someVariable",
+        "type": "variables",
+      },
+    ],
+    "nodesCount": 1,
   },
 }
 `;
@@ -89,7 +96,7 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "issues": [
       {
         "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/map-event.function.ts",
-        "line": 1,
+        "line": 3,
         "name": "mapEventToCustomEvent",
         "type": "functions",
       },
@@ -106,7 +113,7 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "issues": [
       {
         "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/app.component.ts",
-        "line": 15,
+        "line": 17,
         "name": "sendEvent",
         "type": "methods",
       },
@@ -118,7 +125,7 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "issues": [
       {
         "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/app.component.ts",
-        "line": 5,
+        "line": 7,
         "name": "title",
         "type": "properties",
       },
@@ -131,9 +138,16 @@ exports[`processDocCoverage > should succesfully get the right number of ts file
     "nodesCount": 0,
   },
   "variables": {
-    "coverage": 100,
-    "issues": [],
-    "nodesCount": 0,
+    "coverage": 0,
+    "issues": [
+      {
+        "file": "/home/alejandro/dev/code-pushup-cli/packages/plugin-doc-coverage/mocks/fixtures/angular/map-event.function.ts",
+        "line": 1,
+        "name": "someVariable",
+        "type": "variables",
+      },
+    ],
+    "nodesCount": 1,
   },
 }
 `;

packages/plugin-doc-coverage/src/lib/runner/__snapshots__/doc-processer.integration.test.ts.snap

@@ -1,4 +1,9 @@
-import { ClassDeclaration, Project, SourceFile } from 'ts-morph';
+import {
+  ClassDeclaration,
+  Project,
+  SourceFile,
+  VariableStatement,
+} from 'ts-morph';
 import type { DocCoveragePluginConfig } from '../config.js';
 import type {
   CoverageResult,
@@ -11,6 +16,30 @@ import {
   getCoverageTypeFromKind,
 } from './utils.js';
 
+/**
+ * Gets the variables information from the variable statements
+ * @param variableStatements - The variable statements to process
+ * @returns {Node[]} The variables information with the right methods to get the information
+ */
+export function getVariablesInformation(
+  variableStatements: VariableStatement[],
+) {
+  return variableStatements.flatMap(variable => {
+    // Get parent-level information
+    const parentInfo = {
+      getKind: () => variable.getKind(),
+      getJsDocs: () => variable.getJsDocs(),
+      getStartLineNumber: () => variable.getStartLineNumber(),
+    };
+
+    // Map each declaration to combine parent info with declaration-specific info
+    return variable.getDeclarations().map(declaration => ({
+      ...parentInfo,
+      getName: () => declaration.getName(),
+    }));
+  });
+}
+
 /**
  * Processes documentation coverage for TypeScript files in the specified path
  * @param toInclude - The file path pattern to include for documentation analysis
@@ -44,6 +73,7 @@ export function getUnprocessedCoverageReport(
         ...sourceFile.getTypeAliases(),
         ...sourceFile.getEnums(),
         ...sourceFile.getInterfaces(),
+        ...getVariablesInformation(sourceFile.getVariableStatements()),
       ];
 
       const coverageReportOfCurrentFile = allNodesFromFile.reduce(

packages/plugin-doc-coverage/src/lib/runner/doc-processer.ts

@@ -1,8 +1,9 @@
-import type { ClassDeclaration } from 'ts-morph';
+import type { ClassDeclaration, VariableStatement } from 'ts-morph';
 import { nodeMock, sourceFileMock } from '../../../mocks/source-files.mock';
 import {
   getClassNodes,
   getUnprocessedCoverageReport,
+  getVariablesInformation,
   mergeCoverageResults,
 } from './doc-processer.js';
 import type { UnprocessedCoverageResult } from './models.js';
@@ -196,3 +197,79 @@ describe('getClassNodes', () => {
     expect(propertyNodeSpy).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('getVariablesInformation', () => {
+  it('should process variable statements correctly', () => {
+    const mockDeclaration = {
+      getName: () => 'testVariable',
+    };
+
+    const mockVariableStatement = {
+      getKind: () => 'const',
+      getJsDocs: () => ['some docs'],
+      getStartLineNumber: () => 42,
+      getDeclarations: () => [mockDeclaration],
+    };
+
+    const result = getVariablesInformation([
+      mockVariableStatement as unknown as VariableStatement,
+    ]);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      getKind: expect.any(Function),
+      getJsDocs: expect.any(Function),
+      getStartLineNumber: expect.any(Function),
+      getName: expect.any(Function),
+    });
+    // It must be defined
+    expect(result[0]!.getName()).toBe('testVariable');
+    expect(result[0]!.getKind()).toBe('const');
+    expect(result[0]!.getJsDocs()).toEqual(['some docs']);
+    expect(result[0]!.getStartLineNumber()).toBe(42);
+  });
+
+  it('should handle multiple declarations in a single variable statement', () => {
+    const mockDeclarations = [
+      { getName: () => 'var1' },
+      { getName: () => 'var2' },
+    ];
+
+    const mockVariableStatement = {
+      getKind: () => 'let',
+      getJsDocs: () => [],
+      getStartLineNumber: () => 10,
+      getDeclarations: () => mockDeclarations,
+    };
+
+    const result = getVariablesInformation([
+      mockVariableStatement as unknown as VariableStatement,
+    ]);
+
+    expect(result).toHaveLength(2);
+    // They must be defined
+    expect(result[0]!.getName()).toBe('var1');
+    expect(result[1]!.getName()).toBe('var2');
+    expect(result[0]!.getKind()).toBe('let');
+    expect(result[1]!.getKind()).toBe('let');
+  });
+
+  it('should handle empty variable statements array', () => {
+    const result = getVariablesInformation([]);
+    expect(result).toHaveLength(0);
+  });
+
+  it('should handle variable statements without declarations', () => {
+    const mockVariableStatement = {
+      getKind: () => 'const',
+      getJsDocs: () => [],
+      getStartLineNumber: () => 1,
+      getDeclarations: () => [],
+    };
+
+    const result = getVariablesInformation([
+      mockVariableStatement as unknown as VariableStatement,
+    ]);
+    expect(result).toHaveLength(0);
+  });
+});

packages/plugin-doc-coverage/src/lib/runner/doc-processer.unit.test.ts

@@ -67,6 +67,7 @@ export function getCoverageTypeFromKind(kind: SyntaxKind): CoverageType {
       return 'interfaces';
     case SyntaxKind.EnumDeclaration:
       return 'enums';
+    case SyntaxKind.VariableStatement:
     case SyntaxKind.VariableDeclaration:
       return 'variables';
     case SyntaxKind.PropertyDeclaration: