feat: implement scoreTarget for audits

Author: hanna-skryl

packages/core/src/lib/implementation/execute-plugin.ts

@@ -14,6 +14,7 @@ import {
   groupByStatus,
   logMultipleResults,
   pluralizeToken,
+  scoreAuditsWithTarget,
 } from '@code-pushup/utils';
 import {
   executePluginRunner,
@@ -57,6 +58,7 @@ export async function executePlugin(
     description,
     docsUrl,
     groups,
+    scoreTarget,
     ...pluginMeta
   } = pluginConfig;
   const { write: cacheWrite = false, read: cacheRead = false } = cache;
@@ -76,8 +78,13 @@ export async function executePlugin(
     });
   }
 
+  // transform audit scores to 1 when they meet/exceed scoreTarget
+  const transformedAudits = scoreTarget
+    ? scoreAuditsWithTarget(audits, scoreTarget)
+    : audits;
+
   // enrich `AuditOutputs` to `AuditReport`
-  const auditReports: AuditReport[] = audits.map(
+  const auditReports: AuditReport[] = transformedAudits.map(
     (auditOutput: AuditOutput) => ({
       ...auditOutput,
       ...(pluginConfigAudits.find(

packages/core/src/lib/implementation/execute-plugin.unit.test.ts

@@ -124,6 +124,67 @@ describe('executePlugin', () => {
       MINIMAL_PLUGIN_CONFIG_MOCK,
     );
   });
+
+  it('should apply a single score target to all audits', async () => {
+    const pluginConfig: PluginConfig = {
+      ...MINIMAL_PLUGIN_CONFIG_MOCK,
+      scoreTarget: 0.8,
+      audits: [
+        {
+          slug: 'speed-index',
+          title: 'Speed Index',
+        },
+        {
+          slug: 'total-blocking-time',
+          title: 'Total Blocking Time',
+        },
+      ],
+      runner: () => [
+        { slug: 'speed-index', score: 0.9, value: 1300 },
+        { slug: 'total-blocking-time', score: 0.3, value: 600 },
+      ],
+    };
+
+    const result = await executePlugin(pluginConfig, {
+      persist: { outputDir: '' },
+      cache: { read: false, write: false },
+    });
+
+    expect(result.audits).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          slug: 'speed-index',
+          score: 1,
+          scoreTarget: 0.8,
+        }),
+        expect.objectContaining({
+          slug: 'total-blocking-time',
+          score: 0.3,
+          scoreTarget: 0.8,
+        }),
+      ]),
+    );
+  });
+
+  it('should apply per-audit score targets', async () => {
+    const pluginConfig: PluginConfig = {
+      ...MINIMAL_PLUGIN_CONFIG_MOCK, // returns node-version audit with score 0.3
+      scoreTarget: {
+        'node-version': 0.2,
+      },
+    };
+
+    const result = await executePlugin(pluginConfig, {
+      persist: { outputDir: '' },
+      cache: { read: false, write: false },
+    });
+
+    expect(result.audits[0]).toMatchObject({
+      slug: 'node-version',
+      score: 1,
+      scoreTarget: 0.2,
+    });
+  });
 });
 
 describe('executePlugins', () => {

packages/utils/src/index.ts

@@ -102,7 +102,7 @@ export {
 } from './lib/reports/generate-md-reports-diff.js';
 export { loadReport } from './lib/reports/load-report.js';
 export { logStdoutSummary } from './lib/reports/log-stdout-summary.js';
-export { scoreReport } from './lib/reports/scoring.js';
+export { scoreReport, scoreAuditsWithTarget } from './lib/reports/scoring.js';
 export { sortReport } from './lib/reports/sorting.js';
 export type {
   ScoredCategoryConfig,

packages/utils/src/lib/reports/scoring.ts

@@ -1,7 +1,9 @@
 import type {
+  AuditOutput,
   AuditReport,
   CategoryRef,
   GroupRef,
+  PluginScoreTarget,
   Report,
 } from '@code-pushup/models';
 import { deepClone } from '../transform.js';
@@ -117,3 +119,37 @@ function parseScoringParameters<T extends { weight: number }>(
 
   return scoredRefs;
 }
+
+/**
+ * Sets audit score to 1 if it meets target.
+ * @param audit audit output to evaluate
+ * @param scoreTarget threshold for perfect score (0-1)
+ * @returns Audit with scoreTarget field
+ */
+export function scoreAuditWithTarget(
+  audit: AuditOutput,
+  scoreTarget: number,
+): AuditOutput {
+  return audit.score >= scoreTarget
+    ? { ...audit, score: 1, scoreTarget }
+    : { ...audit, scoreTarget };
+}
+
+/**
+ * Sets audit scores to 1 when targets are met.
+ * @param audits audit outputs from plugin execution
+ * @param scoreTarget number or { slug: target } mapping
+ * @returns Transformed audits with scoreTarget field
+ */
+export function scoreAuditsWithTarget(
+  audits: AuditOutput[],
+  scoreTarget: PluginScoreTarget,
+): AuditOutput[] {
+  if (typeof scoreTarget === 'number') {
+    return audits.map(audit => scoreAuditWithTarget(audit, scoreTarget));
+  }
+  return audits.map(audit => {
+    const target = scoreTarget?.[audit.slug];
+    return target == null ? audit : scoreAuditWithTarget(audit, target);
+  });
+}

packages/utils/src/lib/reports/scoring.unit.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect } from 'vitest';
 import { REPORT_MOCK } from '@code-pushup/test-utils';
-import { calculateScore, scoreReport } from './scoring.js';
+import {
+  calculateScore,
+  scoreAuditWithTarget,
+  scoreAuditsWithTarget,
+  scoreReport,
+} from './scoring.js';
 
 describe('calculateScore', () => {
   it('should calculate the same score for one reference', () => {
@@ -136,3 +141,108 @@ describe('scoreReport', () => {
     );
   });
 });
+
+describe('scoreAuditWithTarget', () => {
+  it('should add scoreTarget and increase an audit score to 1 when the target is reached', () => {
+    expect(
+      scoreAuditWithTarget(
+        { slug: 'speed-index', score: 0.9, value: 1300 },
+        0.8,
+      ),
+    ).toEqual({
+      slug: 'speed-index',
+      score: 1,
+      value: 1300,
+      scoreTarget: 0.8,
+    });
+  });
+
+  it('should only add scoreTarget when the target is not reached', () => {
+    expect(
+      scoreAuditWithTarget(
+        { slug: 'largest-contentful-paint', score: 0.6, value: 3000 },
+        0.8,
+      ),
+    ).toEqual({
+      slug: 'largest-contentful-paint',
+      score: 0.6,
+      value: 3000,
+      scoreTarget: 0.8,
+    });
+  });
+});
+
+describe('scoreAuditsWithTarget', () => {
+  it('should apply a single score target to all audits', () => {
+    const audits = [
+      { slug: 'first-contentful-paint', score: 0.8, value: 1200 },
+      { slug: 'largest-contentful-paint', score: 0.6, value: 3000 },
+      { slug: 'speed-index', score: 0.9, value: 1300 },
+    ];
+
+    expect(scoreAuditsWithTarget(audits, 0.75)).toEqual([
+      {
+        slug: 'first-contentful-paint',
+        score: 1,
+        value: 1200,
+        scoreTarget: 0.75,
+      },
+      {
+        slug: 'largest-contentful-paint',
+        score: 0.6,
+        value: 3000,
+        scoreTarget: 0.75,
+      },
+      { slug: 'speed-index', score: 1, value: 1300, scoreTarget: 0.75 },
+    ]);
+  });
+
+  it('should apply per-audit score targets', () => {
+    const audits = [
+      { slug: 'first-contentful-paint', score: 0.8, value: 1200 },
+      { slug: 'largest-contentful-paint', score: 0.6, value: 3000 },
+      { slug: 'speed-index', score: 0.9, value: 1300 },
+    ];
+
+    expect(
+      scoreAuditsWithTarget(audits, {
+        'first-contentful-paint': 0.85,
+        'largest-contentful-paint': 0.5,
+      }),
+    ).toEqual([
+      {
+        slug: 'first-contentful-paint',
+        score: 0.8,
+        value: 1200,
+        scoreTarget: 0.85,
+      },
+      {
+        slug: 'largest-contentful-paint',
+        score: 1,
+        value: 3000,
+        scoreTarget: 0.5,
+      },
+      { slug: 'speed-index', score: 0.9, value: 1300 },
+    ]);
+  });
+
+  it('should set an audit score to 1 when the original score equals the target', () => {
+    const audits = [{ slug: 'speed-index', score: 0.9, value: 1300 }];
+
+    expect(scoreAuditsWithTarget(audits, 0.9)).toEqual([
+      { slug: 'speed-index', score: 1, value: 1300, scoreTarget: 0.9 },
+    ]);
+  });
+
+  it('should handle an empty audits array', () => {
+    expect(scoreAuditsWithTarget([], 0.8)).toEqual([]);
+  });
+
+  it('should handle an empty score target record', () => {
+    const audits = [{ slug: 'speed-index', score: 0.9, value: 1300 }];
+
+    expect(scoreAuditsWithTarget(audits, {})).toEqual([
+      { slug: 'speed-index', score: 0.9, value: 1300 },
+    ]);
+  });
+});