feat(plugin-coverage): implement lcov parsing

package.json

@@ -53,6 +53,7 @@
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.3",
     "multi-progress-bars": "^5.0.3",
+    "parse-lcov": "^1.0.4",
     "simple-git": "^3.20.0",
     "yargs": "^17.7.2",
     "zod": "^3.22.4"

packages/plugin-coverage/README.md

@@ -0,0 +1,154 @@
+# @code-pushup/coverage-plugin
+
+**Code PushUp plugin for tracking code coverage.**
+
+This plugin allows you to measure and track code coverage on your project.
+
+Measured coverage types are mapped to Code PushUp audits in the following way
+
+- both the score and value is in range 0-1 and represents the code coverage for all passed results (_covered / total_)
+- missing coverage is mapped to issues in the audit details (uncalled functions, uncovered branches or lines)
+
+## Getting started
+
+1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
+
+2. Prepare either existing code coverage result files or a command for a coverage tool of your choice that will generate the results, such as [Istanbul](https://github.com/istanbuljs).
+
+3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.js`).
+
+   Pass coverage types you wish to track (line, branch or function), paths to the code coverage results in LCOV format and optionally define your code coverage tool to be run first.
+
+   Please note that when you define the tool command, you still need to define the paths to the coverage results.
+
+   The configuration will look similarly to the following:
+
+   ```js
+   import coveragePlugin from '@code-pushup/coverage-plugin';
+
+   export default {
+     // ...
+     plugins: [
+       // ...
+       await coveragePlugin({
+         coverageType: ['branch', 'function', 'line'],
+         reports: ['coverage/cli/lcov.info'],
+         coverageToolCommand: {
+           command: 'npx nx run-many',
+           args: ['-t', 'test', '--coverage'],
+         },
+       }),
+     ],
+   };
+   ```
+
+4. (Optional) Reference audits which you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
+
+   Assign weights based on what influence each coverage type should have on the overall category score (assign weight 0 to only include as extra info, without influencing category score).
+
+   Note that categories can combine multiple plugins.
+
+   ```js
+   export default {
+     // ...
+     categories: [
+       {
+         slug: 'code-coverage',
+         title: 'Code coverage',
+         refs: [
+           {
+             type: 'audit',
+             plugin: 'coverage',
+             slug: 'function-coverage',
+             weight: 2,
+           },
+           {
+             type: 'audit',
+             plugin: 'coverage',
+             slug: 'branch-coverage',
+             weight: 1,
+           },
+           {
+             type: 'audit',
+             plugin: 'coverage',
+             slug: 'line-coverage',
+             weight: 1,
+           },
+           // ...
+         ],
+       },
+       // ...
+     ],
+   };
+   ```
+
+5. Run the CLI with `npx code-pushup collect` and view or upload report (refer to [CLI docs](../cli/README.md)).
+
+## About code coverage
+
+Code coverage is a metric that indicates what percentage of source code is executed by unit tests. It can give insights into test effectiveness and uncover parts of source code that would otherwise go untested.
+
+However, please note that code coverage is not the same as test coverage. Test coverage measures the amount of acceptance criteria covered by tests and is hard to formally verify. This means that code coverage cannot guarantee that the designed software caters to the business requirements.
+
+### LCOV format
+
+The LCOV format was originally used by [GCOV](https://gcc.gnu.org/onlinedocs/gcc/gcov/introduction-to-gcov.html) tool for coverage results in C/C++ projects.
+It recognises the following entities:
+
+- TN [test name]
+- SF [source file]
+- FN [line number] [function name]
+- FNF [number of functions found]
+- FNH [number of functions hit]
+- FNDA [number of hits] [function name]
+- BRDA [line number] [block number] [branch name] [number of hits]
+- BRF [number of branches found]
+- BRH [number of branches taken]
+- DA [line number] [number of hits]
+- LF [lines found]
+- LH [lines hit]
+
+[Here](https://github.com/linux-test-project/lcov/issues/113#issuecomment-762335134) is the source of the information above.
+
+## Plugin architecture
+
+### Plugin configuration specification
+
+The plugin accepts the following parameters:
+
+- `coverageType`: An array of types of coverage that you wish to track. Supported values: function, branch, line.
+- `reports`: Array of paths to files with code coverage results. Supported formats: LCOV.
+- (optional) `coverageToolCommand`: If you wish to run your coverage tool to generate the results first, you may define it here.
+- (optional) `perfectScoreThreshold`: If your coverage goal is not 100%, you may define it here in range 0-1. Any score above the defined threshold will be given the perfect score. The value will stay unaffected.
+
+### Audit output
+
+An audit is an aggregation of all results for one coverage type passed to the plugin.
+
+For functions and branches, an issue points to a single instance of a branch or function not covered in any test and counts as an error. In line coverage, one issue groups any amount of consecutive lines together to reduce the total amount of issues and counts as a warning.
+
+For instance, the following can be an audit output for line coverage.
+
+```json
+{
+  "slug": "line-coverage",
+  "displayValue": "95 %",
+  "score": 0.95,
+  "value": 0.95,
+  "details": {
+    "issues": [
+      {
+        "message": "Lines 7-9 are not covered in any test case.",
+        "severity": "warning",
+        "source": {
+          "file": "src/lib/utils.ts",
+          "position": {
+            "startLine": 7,
+            "endLine": 9
+          }
+        }
+      }
+    ]
+  }
+}
+```

packages/plugin-coverage/mocks/single-record-lcov.info

@@ -0,0 +1,33 @@
+TN:
+SF:src\lib\utils.ts
+FN:2,formatReportScore
+FN:6,calcDuration
+FNF:2
+FNH:2
+FNDA:1,formatReportScore
+FNDA:6,calcDuration
+DA:1,1
+DA:2,1
+DA:3,1
+DA:4,1
+DA:5,1
+DA:6,1
+DA:7,0
+DA:8,0
+DA:9,0
+DA:10,1
+LF:10
+LH:7
+BRDA:1,0,0,6
+BRDA:1,1,0,5
+BRDA:2,4,0,1
+BRDA:4,5,0,17
+BRDA:5,6,0,4
+BRDA:6,7,0,13
+BRDA:6,10,0,0
+BRDA:7,11,0,3
+BRDA:10,12,0,12
+BRDA:10,13,0,0
+BRF:10
+BRH:8
+end_of_record

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

@@ -0,0 +1,64 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`lcovResultsToAuditOutputs > should correctly convert lcov results to AuditOutputs 1`] = `
+[
+  {
+    "details": {
+      "issues": [
+        {
+          "message": "Branch 0 is not taken in any test case.",
+          "severity": "error",
+          "source": {
+            "file": "src/lib/utils.ts",
+            "position": {
+              "startLine": 6,
+            },
+          },
+        },
+        {
+          "message": "Branch 0 is not taken in any test case.",
+          "severity": "error",
+          "source": {
+            "file": "src/lib/utils.ts",
+            "position": {
+              "startLine": 10,
+            },
+          },
+        },
+      ],
+    },
+    "displayValue": "80 %",
+    "score": 0.8,
+    "slug": "branch-coverage",
+    "value": 80,
+  },
+  {
+    "details": undefined,
+    "displayValue": "100 %",
+    "score": 1,
+    "slug": "function-coverage",
+    "value": 100,
+  },
+  {
+    "details": {
+      "issues": [
+        {
+          "message": "Lines 7-9 are not covered in any test case.",
+          "severity": "warning",
+          "source": {
+            "file": "src/lib/utils.ts",
+            "position": {
+              "endLine": 9,
+              "startLine": 7,
+            },
+          },
+        },
+      ],
+    },
+    "displayValue": "70 %",
+    "score": 0.7,
+    "slug": "line-coverage",
+    "value": 70,
+  },
+]
+`;

packages/plugin-coverage/src/lib/runner/lcov/parse-lcov.ts

@@ -0,0 +1,11 @@
+import parseLcovExport from 'parse-lcov';
+
+type ParseLcovFn = typeof parseLcovExport;
+
+// the parse-lcov export is inconsistent (sometimes it's .default, sometimes it's .default.default)
+const godKnows = parseLcovExport as unknown as
+  | ParseLcovFn
+  | { default: ParseLcovFn };
+
+export const parseLcov: ParseLcovFn =
+  'default' in godKnows ? godKnows.default : godKnows;

packages/plugin-coverage/src/lib/runner/lcov/runner.integration.test.ts

@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+import { describe, it } from 'vitest';
+import { lcovResultsToAuditOutputs } from './runner';
+
+describe('lcovResultsToAuditOutputs', () => {
+  it('should correctly convert lcov results to AuditOutputs', async () => {
+    /**
+     * The stats passed in the fixture are as follows
+     * Functions: 2 found, 2 covered (100% coverage)
+     * Branches: 10 found, 8 covered (80% coverage) - last value of BRDA
+     * Lines: 10 found, 7 covered (70% coverage) - merged into one issue with line range
+     */
+    const results = await lcovResultsToAuditOutputs(
+      [join('packages', 'plugin-coverage', 'mocks', 'single-record-lcov.info')],
+      ['branch', 'function', 'line'],
+    );
+    expect(results).toMatchSnapshot();
+  });
+});