@code-pushup/coverage-plugin 0.13.0

package/README.md

@@ -0,0 +1,159 @@
+# @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
+
+- The value is in range 0-100 and represents the code coverage for all passed results (_covered / total_)
+- the score is value converted to 0-1 range
+- 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. Set lcov as the reporter to the configuration (example for Jest [here](https://jestjs.io/docs/configuration#coveragereporters-arraystring--string-options)).
+
+3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.js`).
+
+   Pass paths to the code coverage results in LCOV format and optionally define your code coverage tool to be run first.
+   All coverage types are measured by default. If you wish to focus on a subset of offered types of coverage, define them in `coverageTypes`.
+
+   📌 Please note that when you define the tool command, you still need to define the paths to all relevant coverage results.
+
+   The configuration will look similarly to the following:
+
+   ```js
+   import coveragePlugin from '@code-pushup/coverage-plugin';
+
+   export default {
+     // ...
+     plugins: [
+       // ...
+       await coveragePlugin({
+         reports: [{ resultsPath: 'coverage/lcov.info' }],
+         coverageToolCommand: {
+           command: 'npx',
+           args: ['jest', '--coverage', '--coverageReporters=lcov'],
+         },
+       }),
+     ],
+   };
+   ```
+
+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).
+
+   ```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.
+
+> [!IMPORTANT]
+> 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.
+
+If you want to know more code coverage and how each type of coverage is measured, go to [Software Testing Help](https://www.softwaretestinghelp.com/code-coverage-tutorial/).
+
+### 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.
+
+> [!NOTE]
+> Branch name is usually a number indexed from 0, indicating either truthy/falsy condition or loop conditions.
+
+## Plugin architecture
+
+### Plugin configuration specification
+
+The plugin accepts the following parameters:
+
+- `coverageTypes`: An array of types of coverage that you wish to track. Supported values: `function`, `branch`, `line`. Defaults to all available types.
+- `reports`: Array of information about files with code coverage results - paths to results, path to project root the results belong to. LCOV format is supported for now.
+- (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": 95,
+  "details": {
+    "issues": [
+      {
+        "message": "Lines 7-9 are not covered in any test case.",
+        "severity": "warning",
+        "source": {
+          "file": "packages/cli/src/lib/utils.ts",
+          "position": {
+            "startLine": 7,
+            "endLine": 9
+          }
+        }
+      }
+    ]
+  }
+}
+```

package/index.js

@@ -0,0 +1,848 @@
+// packages/plugin-coverage/src/lib/coverage-plugin.ts
+import { join as join3 } from "node:path";
+
+// packages/models/src/lib/audit.ts
+import { z as z2 } from "zod";
+
+// packages/models/src/lib/implementation/schemas.ts
+import { z } from "zod";
+import { MATERIAL_ICONS } from "@code-pushup/portal-client";
+
+// packages/models/src/lib/implementation/limits.ts
+var MAX_SLUG_LENGTH = 128;
+var MAX_TITLE_LENGTH = 256;
+var MAX_DESCRIPTION_LENGTH = 65536;
+var MAX_ISSUE_MESSAGE_LENGTH = 1024;
+
+// packages/models/src/lib/implementation/utils.ts
+var slugRegex = /^[a-z\d]+(?:-[a-z\d]+)*$/;
+var filenameRegex = /^(?!.*[ \\/:*?"<>|]).+$/;
+function hasDuplicateStrings(strings) {
+  const sortedStrings = [...strings].sort();
+  const duplStrings = sortedStrings.filter(
+    (item, index) => index !== 0 && item === sortedStrings[index - 1]
+  );
+  return duplStrings.length === 0 ? false : [...new Set(duplStrings)];
+}
+function hasMissingStrings(toCheck, existing) {
+  const nonExisting = toCheck.filter((s) => !existing.includes(s));
+  return nonExisting.length === 0 ? false : nonExisting;
+}
+function errorItems(items, transform = (itemArr) => itemArr.join(", ")) {
+  return transform(items || []);
+}
+function exists(value) {
+  return value != null;
+}
+function getMissingRefsForCategories(categories, plugins) {
+  if (categories.length === 0) {
+    return false;
+  }
+  const auditRefsFromCategory = categories.flatMap(
+    ({ refs }) => refs.filter(({ type }) => type === "audit").map(({ plugin, slug }) => `${plugin}/${slug}`)
+  );
+  const auditRefsFromPlugins = plugins.flatMap(
+    ({ audits, slug: pluginSlug }) => audits.map(({ slug }) => `${pluginSlug}/${slug}`)
+  );
+  const missingAuditRefs = hasMissingStrings(
+    auditRefsFromCategory,
+    auditRefsFromPlugins
+  );
+  const groupRefsFromCategory = categories.flatMap(
+    ({ refs }) => refs.filter(({ type }) => type === "group").map(({ plugin, slug }) => `${plugin}#${slug} (group)`)
+  );
+  const groupRefsFromPlugins = plugins.flatMap(
+    ({ groups, slug: pluginSlug }) => Array.isArray(groups) ? groups.map(({ slug }) => `${pluginSlug}#${slug} (group)`) : []
+  );
+  const missingGroupRefs = hasMissingStrings(
+    groupRefsFromCategory,
+    groupRefsFromPlugins
+  );
+  const missingRefs = [missingAuditRefs, missingGroupRefs].filter((refs) => Array.isArray(refs) && refs.length > 0).flat();
+  return missingRefs.length > 0 ? missingRefs : false;
+}
+function missingRefsForCategoriesErrorMsg(categories, plugins) {
+  const missingRefs = getMissingRefsForCategories(categories, plugins);
+  return `The following category references need to point to an audit or group: ${errorItems(
+    missingRefs
+  )}`;
+}
+
+// packages/models/src/lib/implementation/schemas.ts
+function executionMetaSchema(options = {
+  descriptionDate: "Execution start date and time",
+  descriptionDuration: "Execution duration in ms"
+}) {
+  return z.object({
+    date: z.string({ description: options.descriptionDate }),
+    duration: z.number({ description: options.descriptionDuration })
+  });
+}
+function slugSchema(description = "Unique ID (human-readable, URL-safe)") {
+  return z.string({ description }).regex(slugRegex, {
+    message: "The slug has to follow the pattern [0-9a-z] followed by multiple optional groups of -[0-9a-z]. e.g. my-slug"
+  }).max(MAX_SLUG_LENGTH, {
+    message: `slug can be max ${MAX_SLUG_LENGTH} characters long`
+  });
+}
+function descriptionSchema(description = "Description (markdown)") {
+  return z.string({ description }).max(MAX_DESCRIPTION_LENGTH).optional();
+}
+function docsUrlSchema(description = "Documentation site") {
+  return urlSchema(description).optional().or(z.string().max(0));
+}
+function urlSchema(description) {
+  return z.string({ description }).url();
+}
+function titleSchema(description = "Descriptive name") {
+  return z.string({ description }).max(MAX_TITLE_LENGTH);
+}
+function metaSchema(options) {
+  const {
+    descriptionDescription,
+    titleDescription,
+    docsUrlDescription,
+    description
+  } = options ?? {};
+  return z.object(
+    {
+      title: titleSchema(titleDescription),
+      description: descriptionSchema(descriptionDescription),
+      docsUrl: docsUrlSchema(docsUrlDescription)
+    },
+    { description }
+  );
+}
+function filePathSchema(description) {
+  return z.string({ description }).trim().min(1, { message: "path is invalid" });
+}
+function fileNameSchema(description) {
+  return z.string({ description }).trim().regex(filenameRegex, {
+    message: `The filename has to be valid`
+  }).min(1, { message: "file name is invalid" });
+}
+function positiveIntSchema(description) {
+  return z.number({ description }).int().nonnegative();
+}
+function packageVersionSchema(options) {
+  const { versionDescription = "NPM version of the package", required } = options ?? {};
+  const packageSchema = z.string({ description: "NPM package name" });
+  const versionSchema = z.string({ description: versionDescription });
+  return z.object(
+    {
+      packageName: required ? packageSchema : packageSchema.optional(),
+      version: required ? versionSchema : versionSchema.optional()
+    },
+    { description: "NPM package name and version of a published package" }
+  );
+}
+function weightSchema(description = "Coefficient for the given score (use weight 0 if only for display)") {
+  return positiveIntSchema(description);
+}
+function weightedRefSchema(description, slugDescription) {
+  return z.object(
+    {
+      slug: slugSchema(slugDescription),
+      weight: weightSchema("Weight used to calculate score")
+    },
+    { description }
+  );
+}
+function scorableSchema(description, refSchema, duplicateCheckFn, duplicateMessageFn) {
+  return z.object(
+    {
+      slug: slugSchema('Human-readable unique ID, e.g. "performance"'),
+      refs: z.array(refSchema).min(1).refine(
+        (refs) => !duplicateCheckFn(refs),
+        (refs) => ({
+          message: duplicateMessageFn(refs)
+        })
+      ).refine(hasWeightedRefsInCategories, () => ({
+        message: `In a category there has to be at least one ref with weight > 0`
+      }))
+    },
+    { description }
+  );
+}
+var materialIconSchema = z.enum(
+  MATERIAL_ICONS,
+  { description: "Icon from VSCode Material Icons extension" }
+);
+function hasWeightedRefsInCategories(categoryRefs) {
+  return categoryRefs.reduce((acc, { weight }) => weight + acc, 0) !== 0;
+}
+
+// packages/models/src/lib/audit.ts
+var auditSchema = z2.object({
+  slug: slugSchema("ID (unique within plugin)")
+}).merge(
+  metaSchema({
+    titleDescription: "Descriptive name",
+    descriptionDescription: "Description (markdown)",
+    docsUrlDescription: "Link to documentation (rationale)",
+    description: "List of scorable metrics for the given plugin"
+  })
+);
+var pluginAuditsSchema = z2.array(auditSchema, {
+  description: "List of audits maintained in a plugin"
+}).refine(
+  (auditMetadata) => !getDuplicateSlugsInAudits(auditMetadata),
+  (auditMetadata) => ({
+    message: duplicateSlugsInAuditsErrorMsg(auditMetadata)
+  })
+);
+function duplicateSlugsInAuditsErrorMsg(audits) {
+  const duplicateRefs = getDuplicateSlugsInAudits(audits);
+  return `In plugin audits the following slugs are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateSlugsInAudits(audits) {
+  return hasDuplicateStrings(audits.map(({ slug }) => slug));
+}
+
+// packages/models/src/lib/audit-issue.ts
+import { z as z3 } from "zod";
+var sourceFileLocationSchema = z3.object(
+  {
+    file: filePathSchema("Relative path to source file in Git repo"),
+    position: z3.object(
+      {
+        startLine: positiveIntSchema("Start line"),
+        startColumn: positiveIntSchema("Start column").optional(),
+        endLine: positiveIntSchema("End line").optional(),
+        endColumn: positiveIntSchema("End column").optional()
+      },
+      { description: "Location in file" }
+    ).optional()
+  },
+  { description: "Source file location" }
+);
+var issueSeveritySchema = z3.enum(["info", "warning", "error"], {
+  description: "Severity level"
+});
+var issueSchema = z3.object(
+  {
+    message: z3.string({ description: "Descriptive error message" }).max(MAX_ISSUE_MESSAGE_LENGTH),
+    severity: issueSeveritySchema,
+    source: sourceFileLocationSchema.optional()
+  },
+  { description: "Issue information" }
+);
+
+// packages/models/src/lib/audit-output.ts
+import { z as z4 } from "zod";
+var auditOutputSchema = z4.object(
+  {
+    slug: slugSchema("Reference to audit"),
+    displayValue: z4.string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" }).optional(),
+    value: positiveIntSchema("Raw numeric value"),
+    score: z4.number({
+      description: "Value between 0 and 1"
+    }).min(0).max(1),
+    details: z4.object(
+      {
+        issues: z4.array(issueSchema, { description: "List of findings" })
+      },
+      { description: "Detailed information" }
+    ).optional()
+  },
+  { description: "Audit information" }
+);
+var auditOutputsSchema = z4.array(auditOutputSchema, {
+  description: "List of JSON formatted audit output emitted by the runner process of a plugin"
+}).refine(
+  (audits) => !getDuplicateSlugsInAudits2(audits),
+  (audits) => ({ message: duplicateSlugsInAuditsErrorMsg2(audits) })
+);
+function duplicateSlugsInAuditsErrorMsg2(audits) {
+  const duplicateRefs = getDuplicateSlugsInAudits2(audits);
+  return `In plugin audits the slugs are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateSlugsInAudits2(audits) {
+  return hasDuplicateStrings(audits.map(({ slug }) => slug));
+}
+
+// packages/models/src/lib/category-config.ts
+import { z as z5 } from "zod";
+var categoryRefSchema = weightedRefSchema(
+  "Weighted references to audits and/or groups for the category",
+  "Slug of an audit or group (depending on `type`)"
+).merge(
+  z5.object({
+    type: z5.enum(["audit", "group"], {
+      description: "Discriminant for reference kind, affects where `slug` is looked up"
+    }),
+    plugin: slugSchema(
+      "Plugin slug (plugin should contain referenced audit or group)"
+    )
+  })
+);
+var categoryConfigSchema = scorableSchema(
+  "Category with a score calculated from audits and groups from various plugins",
+  categoryRefSchema,
+  getDuplicateRefsInCategoryMetrics,
+  duplicateRefsInCategoryMetricsErrorMsg
+).merge(
+  metaSchema({
+    titleDescription: "Category Title",
+    docsUrlDescription: "Category docs URL",
+    descriptionDescription: "Category description",
+    description: "Meta info for category"
+  })
+).merge(
+  z5.object({
+    isBinary: z5.boolean({
+      description: 'Is this a binary category (i.e. only a perfect score considered a "pass")?'
+    }).optional()
+  })
+);
+function duplicateRefsInCategoryMetricsErrorMsg(metrics) {
+  const duplicateRefs = getDuplicateRefsInCategoryMetrics(metrics);
+  return `In the categories, the following audit or group refs are duplicates: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateRefsInCategoryMetrics(metrics) {
+  return hasDuplicateStrings(
+    metrics.map(({ slug, type, plugin }) => `${type} :: ${plugin} / ${slug}`)
+  );
+}
+var categoriesSchema = z5.array(categoryConfigSchema, {
+  description: "Categorization of individual audits"
+}).refine(
+  (categoryCfg) => !getDuplicateSlugCategories(categoryCfg),
+  (categoryCfg) => ({
+    message: duplicateSlugCategoriesErrorMsg(categoryCfg)
+  })
+);
+function duplicateSlugCategoriesErrorMsg(categories) {
+  const duplicateStringSlugs = getDuplicateSlugCategories(categories);
+  return `In the categories, the following slugs are duplicated: ${errorItems(
+    duplicateStringSlugs
+  )}`;
+}
+function getDuplicateSlugCategories(categories) {
+  return hasDuplicateStrings(categories.map(({ slug }) => slug));
+}
+
+// packages/models/src/lib/core-config.ts
+import { z as z11 } from "zod";
+
+// packages/models/src/lib/persist-config.ts
+import { z as z6 } from "zod";
+var formatSchema = z6.enum(["json", "md"]);
+var persistConfigSchema = z6.object({
+  outputDir: filePathSchema("Artifacts folder").optional(),
+  filename: fileNameSchema(
+    "Artifacts file name (without extension)"
+  ).optional(),
+  format: z6.array(formatSchema).optional()
+});
+
+// packages/models/src/lib/plugin-config.ts
+import { z as z9 } from "zod";
+
+// packages/models/src/lib/group.ts
+import { z as z7 } from "zod";
+var groupRefSchema = weightedRefSchema(
+  "Weighted reference to a group",
+  "Reference slug to a group within this plugin (e.g. 'max-lines')"
+);
+var groupMetaSchema = metaSchema({
+  titleDescription: "Descriptive name for the group",
+  descriptionDescription: "Description of the group (markdown)",
+  docsUrlDescription: "Group documentation site",
+  description: "Group metadata"
+});
+var groupSchema = scorableSchema(
+  'A group aggregates a set of audits into a single score which can be referenced from a category. E.g. the group slug "performance" groups audits and can be referenced in a category',
+  groupRefSchema,
+  getDuplicateRefsInGroups,
+  duplicateRefsInGroupsErrorMsg
+).merge(groupMetaSchema);
+var groupsSchema = z7.array(groupSchema, {
+  description: "List of groups"
+}).optional().refine(
+  (groups) => !getDuplicateSlugsInGroups(groups),
+  (groups) => ({
+    message: duplicateSlugsInGroupsErrorMsg(groups)
+  })
+);
+function duplicateRefsInGroupsErrorMsg(groups) {
+  const duplicateRefs = getDuplicateRefsInGroups(groups);
+  return `In plugin groups the following references are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateRefsInGroups(groups) {
+  return hasDuplicateStrings(groups.map(({ slug: ref }) => ref).filter(exists));
+}
+function duplicateSlugsInGroupsErrorMsg(groups) {
+  const duplicateRefs = getDuplicateSlugsInGroups(groups);
+  return `In groups the following slugs are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateSlugsInGroups(groups) {
+  return Array.isArray(groups) ? hasDuplicateStrings(groups.map(({ slug }) => slug)) : false;
+}
+
+// packages/models/src/lib/runner-config.ts
+import { z as z8 } from "zod";
+var outputTransformSchema = z8.function().args(z8.unknown()).returns(z8.union([auditOutputsSchema, z8.promise(auditOutputsSchema)]));
+var runnerConfigSchema = z8.object(
+  {
+    command: z8.string({
+      description: "Shell command to execute"
+    }),
+    args: z8.array(z8.string({ description: "Command arguments" })).optional(),
+    outputFile: filePathSchema("Output path"),
+    outputTransform: outputTransformSchema.optional()
+  },
+  {
+    description: "How to execute runner"
+  }
+);
+var onProgressSchema = z8.function().args(z8.unknown()).returns(z8.void());
+var runnerFunctionSchema = z8.function().args(onProgressSchema.optional()).returns(z8.union([auditOutputsSchema, z8.promise(auditOutputsSchema)]));
+
+// packages/models/src/lib/plugin-config.ts
+var pluginMetaSchema = packageVersionSchema().merge(
+  metaSchema({
+    titleDescription: "Descriptive name",
+    descriptionDescription: "Description (markdown)",
+    docsUrlDescription: "Plugin documentation site",
+    description: "Plugin metadata"
+  })
+).merge(
+  z9.object({
+    slug: slugSchema("Unique plugin slug within core config"),
+    icon: materialIconSchema
+  })
+);
+var pluginDataSchema = z9.object({
+  runner: z9.union([runnerConfigSchema, runnerFunctionSchema]),
+  audits: pluginAuditsSchema,
+  groups: groupsSchema
+});
+var pluginConfigSchema = pluginMetaSchema.merge(pluginDataSchema).refine(
+  (pluginCfg) => !getMissingRefsFromGroups(pluginCfg),
+  (pluginCfg) => ({
+    message: missingRefsFromGroupsErrorMsg(pluginCfg)
+  })
+);
+function missingRefsFromGroupsErrorMsg(pluginCfg) {
+  const missingRefs = getMissingRefsFromGroups(pluginCfg);
+  return `The following group references need to point to an existing audit in this plugin config: ${errorItems(
+    missingRefs
+  )}`;
+}
+function getMissingRefsFromGroups(pluginCfg) {
+  return hasMissingStrings(
+    pluginCfg.groups?.flatMap(
+      ({ refs: audits }) => audits.map(({ slug: ref }) => ref)
+    ) ?? [],
+    pluginCfg.audits.map(({ slug }) => slug)
+  );
+}
+
+// packages/models/src/lib/upload-config.ts
+import { z as z10 } from "zod";
+var uploadConfigSchema = z10.object({
+  server: urlSchema("URL of deployed portal API"),
+  apiKey: z10.string({
+    description: "API key with write access to portal (use `process.env` for security)"
+  }),
+  organization: slugSchema("Organization slug from Code PushUp portal"),
+  project: slugSchema("Project slug from Code PushUp portal"),
+  timeout: z10.number({ description: "Request timeout in minutes (default is 5)" }).positive().int().optional()
+});
+
+// packages/models/src/lib/core-config.ts
+var unrefinedCoreConfigSchema = z11.object({
+  plugins: z11.array(pluginConfigSchema, {
+    description: "List of plugins to be used (official, community-provided, or custom)"
+  }).min(1),
+  /** portal configuration for persisting results */
+  persist: persistConfigSchema.optional(),
+  /** portal configuration for uploading results */
+  upload: uploadConfigSchema.optional(),
+  categories: categoriesSchema.optional()
+});
+var coreConfigSchema = refineCoreConfig(unrefinedCoreConfigSchema);
+function refineCoreConfig(schema) {
+  return schema.refine(
+    (coreCfg) => !getMissingRefsForCategories(coreCfg.categories ?? [], coreCfg.plugins),
+    (coreCfg) => ({
+      message: missingRefsForCategoriesErrorMsg(
+        coreCfg.categories ?? [],
+        coreCfg.plugins
+      )
+    })
+  );
+}
+
+// packages/models/src/lib/report.ts
+import { z as z12 } from "zod";
+var auditReportSchema = auditSchema.merge(auditOutputSchema);
+var pluginReportSchema = pluginMetaSchema.merge(
+  executionMetaSchema({
+    descriptionDate: "Start date and time of plugin run",
+    descriptionDuration: "Duration of the plugin run in ms"
+  })
+).merge(
+  z12.object({
+    audits: z12.array(auditReportSchema),
+    groups: z12.array(groupSchema).optional()
+  })
+).refine(
+  (pluginReport) => !getMissingRefsFromGroups2(pluginReport.audits, pluginReport.groups ?? []),
+  (pluginReport) => ({
+    message: missingRefsFromGroupsErrorMsg2(
+      pluginReport.audits,
+      pluginReport.groups ?? []
+    )
+  })
+);
+function missingRefsFromGroupsErrorMsg2(audits, groups) {
+  const missingRefs = getMissingRefsFromGroups2(audits, groups);
+  return `group references need to point to an existing audit in this plugin report: ${errorItems(
+    missingRefs
+  )}`;
+}
+function getMissingRefsFromGroups2(audits, groups) {
+  return hasMissingStrings(
+    groups.flatMap(
+      ({ refs: auditRefs }) => auditRefs.map(({ slug: ref }) => ref)
+    ),
+    audits.map(({ slug }) => slug)
+  );
+}
+var reportSchema = packageVersionSchema({
+  versionDescription: "NPM version of the CLI",
+  required: true
+}).merge(
+  executionMetaSchema({
+    descriptionDate: "Start date and time of the collect run",
+    descriptionDuration: "Duration of the collect run in ms"
+  })
+).merge(
+  z12.object(
+    {
+      categories: z12.array(categoryConfigSchema),
+      plugins: z12.array(pluginReportSchema).min(1)
+    },
+    { description: "Collect output data" }
+  )
+).refine(
+  (report) => !getMissingRefsForCategories(report.categories, report.plugins),
+  (report) => ({
+    message: missingRefsForCategoriesErrorMsg(
+      report.categories,
+      report.plugins
+    )
+  })
+);
+
+// packages/utils/src/lib/file-system.ts
+import { bundleRequire } from "bundle-require";
+import chalk from "chalk";
+import { mkdir, readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+async function readTextFile(path) {
+  const buffer = await readFile(path);
+  return buffer.toString();
+}
+function pluginWorkDir(slug) {
+  return join("node_modules", ".code-pushup", slug);
+}
+
+// packages/utils/src/lib/git.ts
+import { simpleGit } from "simple-git";
+var git = simpleGit();
+
+// packages/utils/src/lib/progress.ts
+import chalk2 from "chalk";
+import { MultiProgressBars } from "multi-progress-bars";
+
+// packages/utils/src/lib/reports/generate-stdout-summary.ts
+import cliui from "@isaacs/cliui";
+import chalk3 from "chalk";
+import CliTable3 from "cli-table3";
+
+// packages/utils/src/lib/transform.ts
+import { platform } from "node:os";
+function toUnixPath(path, options) {
+  const unixPath = path.replace(/\\/g, "/");
+  if (options?.toRelative) {
+    return unixPath.replace(`${process.cwd().replace(/\\/g, "/")}/`, "");
+  }
+  return unixPath;
+}
+function toUnixNewlines(text) {
+  return platform() === "win32" ? text.replace(/\r\n/g, "\n") : text;
+}
+function capitalize(text) {
+  return `${text.charAt(0).toLocaleUpperCase()}${text.slice(
+    1
+  )}`;
+}
+function toNumberPrecision(value, decimalPlaces) {
+  return Number(
+    `${Math.round(
+      Number.parseFloat(`${value}e${decimalPlaces}`)
+    )}e-${decimalPlaces}`
+  );
+}
+function toOrdinal(value) {
+  if (value % 10 === 1 && value % 100 !== 11) {
+    return `${value}st`;
+  }
+  if (value % 10 === 2 && value % 100 !== 12) {
+    return `${value}nd`;
+  }
+  if (value % 10 === 3 && value % 100 !== 13) {
+    return `${value}rd`;
+  }
+  return `${value}th`;
+}
+
+// packages/plugin-coverage/package.json
+var name = "@code-pushup/coverage-plugin";
+var version = "0.13.0";
+
+// packages/plugin-coverage/src/lib/config.ts
+import { z as z13 } from "zod";
+var coverageTypeSchema = z13.enum(["function", "branch", "line"]);
+var coverageReportSchema = z13.object({
+  resultsPath: z13.string().includes("lcov"),
+  pathToProject: z13.string({
+    description: "Path from workspace root to project root. Necessary for LCOV reports."
+  }).optional()
+});
+var coveragePluginConfigSchema = z13.object({
+  coverageToolCommand: z13.object({
+    command: z13.string({ description: "Command to run coverage tool." }).min(1),
+    args: z13.array(z13.string(), {
+      description: "Arguments to be passed to the coverage tool."
+    }).optional()
+  }).optional(),
+  coverageTypes: z13.array(coverageTypeSchema, {
+    description: "Coverage types measured. Defaults to all available types."
+  }).min(1).default(["function", "branch", "line"]),
+  reports: z13.array(coverageReportSchema, {
+    description: "Path to all code coverage report files. Only LCOV format is supported for now."
+  }).min(1),
+  perfectScoreThreshold: z13.number({
+    description: "Score will be 1 (perfect) for this coverage and above. Score range is 0 - 1."
+  }).gt(0).max(1).optional()
+});
+
+// packages/plugin-coverage/src/lib/runner/lcov/runner.ts
+import { join as join2 } from "node:path";
+
+// packages/plugin-coverage/src/lib/runner/lcov/parse-lcov.ts
+import parseLcovExport from "parse-lcov";
+var godKnows = parseLcovExport;
+var parseLcov = "default" in godKnows ? godKnows.default : godKnows;
+
+// packages/plugin-coverage/src/lib/runner/lcov/utils.ts
+function calculateCoverage(hit, found) {
+  return found > 0 ? hit / found : 1;
+}
+function mergeConsecutiveNumbers(numberArr) {
+  return [...numberArr].sort().reduce((acc, currValue) => {
+    const prevValue = acc.at(-1);
+    if (prevValue != null && (prevValue.start === currValue - 1 || prevValue.end === currValue - 1)) {
+      return [...acc.slice(0, -1), { start: prevValue.start, end: currValue }];
+    }
+    return [...acc, { start: currValue }];
+  }, []);
+}
+
+// packages/plugin-coverage/src/lib/runner/lcov/transform.ts
+function lcovReportToFunctionStat(record) {
+  return {
+    totalFound: record.functions.found,
+    totalHit: record.functions.hit,
+    issues: record.functions.hit < record.functions.found ? record.functions.details.filter((detail) => !detail.hit).map(
+      (detail) => ({
+        message: `Function ${detail.name} is not called in any test case.`,
+        severity: "error",
+        source: {
+          file: toUnixPath(record.file),
+          position: { startLine: detail.line }
+        }
+      })
+    ) : []
+  };
+}
+function lcovReportToLineStat(record) {
+  const missingCoverage = record.lines.hit < record.lines.found;
+  const lines = missingCoverage ? record.lines.details.filter((detail) => !detail.hit).map((detail) => detail.line) : [];
+  const linePositions = mergeConsecutiveNumbers(lines);
+  return {
+    totalFound: record.lines.found,
+    totalHit: record.lines.hit,
+    issues: missingCoverage ? linePositions.map((linePosition) => {
+      const lineReference = linePosition.end == null ? `Line ${linePosition.start} is` : `Lines ${linePosition.start}-${linePosition.end} are`;
+      return {
+        message: `${lineReference} not covered in any test case.`,
+        severity: "warning",
+        source: {
+          file: toUnixPath(record.file),
+          position: {
+            startLine: linePosition.start,
+            endLine: linePosition.end
+          }
+        }
+      };
+    }) : []
+  };
+}
+function lcovReportToBranchStat(record) {
+  return {
+    totalFound: record.branches.found,
+    totalHit: record.branches.hit,
+    issues: record.branches.hit < record.branches.found ? record.branches.details.filter((detail) => !detail.taken).map(
+      (detail) => ({
+        message: `${toOrdinal(
+          detail.branch + 1
+        )} branch is not taken in any test case.`,
+        severity: "error",
+        source: {
+          file: toUnixPath(record.file),
+          position: { startLine: detail.line }
+        }
+      })
+    ) : []
+  };
+}
+var recordToStatFunctionMapper = {
+  branch: lcovReportToBranchStat,
+  line: lcovReportToLineStat,
+  function: lcovReportToFunctionStat
+};
+function lcovCoverageToAuditOutput(stat2, coverageType) {
+  const coverage = calculateCoverage(stat2.totalHit, stat2.totalFound);
+  const MAX_DECIMAL_PLACES = 4;
+  const roundedIntValue = toNumberPrecision(coverage * 100, 0);
+  return {
+    slug: `${coverageType}-coverage`,
+    score: toNumberPrecision(coverage, MAX_DECIMAL_PLACES),
+    value: roundedIntValue,
+    displayValue: `${roundedIntValue} %`,
+    ...stat2.issues.length > 0 && { details: { issues: stat2.issues } }
+  };
+}
+
+// packages/plugin-coverage/src/lib/runner/lcov/runner.ts
+async function lcovResultsToAuditOutputs(reports, coverageTypes) {
+  const parsedReports = await Promise.all(
+    reports.map(async (report) => {
+      const reportContent = await readTextFile(report.resultsPath);
+      const parsedRecords = parseLcov(toUnixNewlines(reportContent));
+      return parsedRecords.map((record) => ({
+        ...record,
+        file: report.pathToProject == null ? record.file : join2(report.pathToProject, record.file)
+      }));
+    })
+  );
+  if (parsedReports.length !== reports.length) {
+    throw new Error("Some provided LCOV reports were not valid.");
+  }
+  const flatReports = parsedReports.flat();
+  if (flatReports.length === 0) {
+    throw new Error("All provided reports are empty.");
+  }
+  const totalCoverageStats = getTotalCoverageFromLcovReports(
+    flatReports,
+    coverageTypes
+  );
+  return coverageTypes.map((coverageType) => {
+    const stats = totalCoverageStats[coverageType];
+    if (!stats) {
+      return null;
+    }
+    return lcovCoverageToAuditOutput(stats, coverageType);
+  }).filter(exists);
+}
+function getTotalCoverageFromLcovReports(records, coverageTypes) {
+  return records.reduce(
+    (acc, report) => Object.fromEntries([
+      ...Object.entries(acc),
+      ...Object.entries(
+        getCoverageStatsFromLcovRecord(report, coverageTypes)
+      ).map(([type, stats]) => [
+        type,
+        {
+          totalFound: (acc[type]?.totalFound ?? 0) + stats.totalFound,
+          totalHit: (acc[type]?.totalHit ?? 0) + stats.totalHit,
+          issues: [...acc[type]?.issues ?? [], ...stats.issues]
+        }
+      ])
+    ]),
+    {}
+  );
+}
+function getCoverageStatsFromLcovRecord(record, coverageTypes) {
+  return Object.fromEntries(
+    coverageTypes.map((coverageType) => [
+      coverageType,
+      recordToStatFunctionMapper[coverageType](record)
+    ])
+  );
+}
+
+// packages/plugin-coverage/src/lib/utils.ts
+function applyMaxScoreAboveThreshold(outputs, threshold) {
+  return outputs.map(
+    (output) => output.score >= threshold ? { ...output, score: 1 } : output
+  );
+}
+
+// packages/plugin-coverage/src/lib/coverage-plugin.ts
+var RUNNER_OUTPUT_PATH = join3(
+  pluginWorkDir("coverage"),
+  "runner-output.json"
+);
+function coveragePlugin(config) {
+  const { reports, perfectScoreThreshold, coverageTypes, coverageToolCommand } = coveragePluginConfigSchema.parse(config);
+  const audits = coverageTypes.map(
+    (type) => ({
+      slug: `${type}-coverage`,
+      title: `${capitalize(type)} coverage`,
+      description: `${capitalize(type)} coverage percentage on the project.`
+    })
+  );
+  const getAuditOutputs = async () => perfectScoreThreshold ? applyMaxScoreAboveThreshold(
+    await lcovResultsToAuditOutputs(reports, coverageTypes),
+    perfectScoreThreshold
+  ) : await lcovResultsToAuditOutputs(reports, coverageTypes);
+  const runner = coverageToolCommand == null ? getAuditOutputs : {
+    command: coverageToolCommand.command,
+    args: coverageToolCommand.args,
+    outputFile: RUNNER_OUTPUT_PATH,
+    outputTransform: getAuditOutputs
+  };
+  return {
+    slug: "coverage",
+    title: "Code coverage",
+    icon: "folder-coverage-open",
+    description: "Official Code PushUp code coverage plugin.",
+    docsUrl: "https://www.npmjs.com/package/@code-pushup/coverage-plugin/",
+    packageName: name,
+    version,
+    audits,
+    runner
+  };
+}
+
+// packages/plugin-coverage/src/index.ts
+var src_default = coveragePlugin;
+export {
+  src_default as default
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@code-pushup/coverage-plugin",
+  "version": "0.13.0",
+  "dependencies": {
+    "@code-pushup/models": "*",
+    "@code-pushup/utils": "*",
+    "parse-lcov": "^1.0.4",
+    "zod": "^3.22.4"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/code-pushup/cli#readme",
+  "bugs": {
+    "url": "https://github.com/code-pushup/cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/code-pushup/cli.git",
+    "directory": "packages/plugin-coverage"
+  },
+  "contributors": [
+    {
+      "name": "Igor Katsuba",
+      "email": "igor@katsuba.dev",
+      "url": "https://katsuba.dev"
+    },
+    {
+      "name": "Kateřina Pilátová",
+      "email": "katerina.pilatova@flowup.cz",
+      "url": "https://github.com/Tlacenka"
+    },
+    {
+      "name": "Matěj Chalk",
+      "email": "matej.chalk@flowup.cz",
+      "url": "https://github.com/matejchalk"
+    },
+    {
+      "name": "Michael Hladky",
+      "email": "michael.hladky@push-based.io",
+      "url": "https://push-based.io"
+    },
+    {
+      "name": "Michael Seredenko",
+      "email": "misha.seredenko@push-based.io",
+      "url": "https://github.com/MishaSeredenkoPushBased"
+    }
+  ],
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+import { coveragePlugin } from './lib/coverage-plugin';
+export default coveragePlugin;
+export type { CoveragePluginConfig } from './lib/config';

package/src/lib/config.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+export declare const coverageTypeSchema: z.ZodEnum<["function", "branch", "line"]>;
+export type CoverageType = z.infer<typeof coverageTypeSchema>;
+export declare const coverageReportSchema: z.ZodObject<{
+    resultsPath: z.ZodString;
+    pathToProject: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    resultsPath: string;
+    pathToProject?: string | undefined;
+}, {
+    resultsPath: string;
+    pathToProject?: string | undefined;
+}>;
+export type CoverageReport = z.infer<typeof coverageReportSchema>;
+export declare const coveragePluginConfigSchema: z.ZodObject<{
+    coverageToolCommand: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        args?: string[] | undefined;
+    }, {
+        command: string;
+        args?: string[] | undefined;
+    }>>;
+    coverageTypes: z.ZodDefault<z.ZodArray<z.ZodEnum<["function", "branch", "line"]>, "many">>;
+    reports: z.ZodArray<z.ZodObject<{
+        resultsPath: z.ZodString;
+        pathToProject: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        resultsPath: string;
+        pathToProject?: string | undefined;
+    }, {
+        resultsPath: string;
+        pathToProject?: string | undefined;
+    }>, "many">;
+    perfectScoreThreshold: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    coverageTypes: ("function" | "branch" | "line")[];
+    reports: {
+        resultsPath: string;
+        pathToProject?: string | undefined;
+    }[];
+    coverageToolCommand?: {
+        command: string;
+        args?: string[] | undefined;
+    } | undefined;
+    perfectScoreThreshold?: number | undefined;
+}, {
+    reports: {
+        resultsPath: string;
+        pathToProject?: string | undefined;
+    }[];
+    coverageToolCommand?: {
+        command: string;
+        args?: string[] | undefined;
+    } | undefined;
+    coverageTypes?: ("function" | "branch" | "line")[] | undefined;
+    perfectScoreThreshold?: number | undefined;
+}>;
+export type CoveragePluginConfig = z.input<typeof coveragePluginConfigSchema>;

package/src/lib/coverage-plugin.d.ts

@@ -0,0 +1,22 @@
+import type { PluginConfig } from '@code-pushup/models';
+import { CoveragePluginConfig } from './config';
+export declare const RUNNER_OUTPUT_PATH: string;
+/**
+ * Instantiates Code PushUp code coverage plugin for core config.
+ *
+ * @example
+ * import coveragePlugin from '@code-pushup/coverage-plugin'
+ *
+ * export default {
+ *   // ... core config ...
+ *   plugins: [
+ *     // ... other plugins ...
+ *     await coveragePlugin({
+ *       reports: [{ resultsPath: 'coverage/cli/lcov.info', pathToProject: 'packages/cli' }]
+ *     })
+ *   ]
+ * }
+ *
+ * @returns Plugin configuration.
+ */
+export declare function coveragePlugin(config: CoveragePluginConfig): PluginConfig;

package/src/lib/runner/lcov/parse-lcov.d.ts

@@ -0,0 +1,4 @@
+import parseLcovExport from 'parse-lcov';
+type ParseLcovFn = typeof parseLcovExport;
+export declare const parseLcov: ParseLcovFn;
+export {};

package/src/lib/runner/lcov/runner.d.ts

@@ -0,0 +1,9 @@
+import { AuditOutputs } from '@code-pushup/models';
+import { CoverageReport, CoverageType } from '../../config';
+/**
+ *
+ * @param reports report files
+ * @param coverageTypes types of coverage to be considered
+ * @returns Audit outputs with complete coverage data.
+ */
+export declare function lcovResultsToAuditOutputs(reports: CoverageReport[], coverageTypes: CoverageType[]): Promise<AuditOutputs>;

package/src/lib/runner/lcov/transform.d.ts

@@ -0,0 +1,19 @@
+import { LCOVRecord } from 'parse-lcov';
+import { AuditOutput } from '@code-pushup/models';
+import { CoverageType } from '../../config';
+import { LCOVStat } from './types';
+export declare function lcovReportToFunctionStat(record: LCOVRecord): LCOVStat;
+export declare function lcovReportToLineStat(record: LCOVRecord): LCOVStat;
+export declare function lcovReportToBranchStat(record: LCOVRecord): LCOVStat;
+export declare const recordToStatFunctionMapper: {
+    branch: typeof lcovReportToBranchStat;
+    line: typeof lcovReportToLineStat;
+    function: typeof lcovReportToFunctionStat;
+};
+/**
+ *
+ * @param stat code coverage result for a given type
+ * @param coverageType code coverage type
+ * @returns Result of complete code ccoverage data coverted to AuditOutput
+ */
+export declare function lcovCoverageToAuditOutput(stat: LCOVStat, coverageType: CoverageType): AuditOutput;

package/src/lib/runner/lcov/types.d.ts

@@ -0,0 +1,12 @@
+import type { Issue } from '@code-pushup/models';
+import { CoverageType } from '../../config';
+export type LCOVStat = {
+    totalFound: number;
+    totalHit: number;
+    issues: Issue[];
+};
+export type LCOVStats = Partial<Record<CoverageType, LCOVStat>>;
+export type NumberRange = {
+    start: number;
+    end?: number;
+};

package/src/lib/runner/lcov/utils.d.ts

@@ -0,0 +1,9 @@
+import { NumberRange } from './types';
+/**
+ * This function calculates coverage as ratio of tested entities vs total
+ * @param hit how many entities were executed in at least one test
+ * @param found  how many entities were found overall
+ * @returns coverage between 0 and 1
+ */
+export declare function calculateCoverage(hit: number, found: number): number;
+export declare function mergeConsecutiveNumbers(numberArr: number[]): NumberRange[];

package/src/lib/utils.d.ts

@@ -0,0 +1,8 @@
+import type { AuditOutputs } from '@code-pushup/models';
+/**
+ * Since more code coverage does not necessarily mean better score, this optional override allows for defining custom coverage goals.
+ * @param outputs original results
+ * @param threshold threshold above which the score is to be 1
+ * @returns Outputs with overriden score (not value) to 1 if it reached a defined threshold.
+ */
+export declare function applyMaxScoreAboveThreshold(outputs: AuditOutputs, threshold: number): AuditOutputs;