lighthouse-audit-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blake Vandercar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# lighthouse-audit-utils
+
+Everything you'd do with a finished Lighthouse run, in one call: write the
+reports to disk, print the fix list to the terminal, and fail the run if a
+category scored below its threshold. Each step can be configured or disabled.
+
+```bash
+npm install --save-dev lighthouse-audit-utils
+```
+
+`lighthouse` is a peer dependency.
+
+## Usage
+
+`runAudit` audits a URL and handles the result:
+
+```ts
+import { runAudit } from 'lighthouse-audit-utils'
+
+await runAudit({
+  lighthouseArgs: {
+    url: 'https://example.com',
+    flags: { port, output: ['html', 'json'] },
+  },
+  reports: { directory: 'lighthouse', name: 'desktop' },
+  thresholds: { performance: 90 },
+})
+```
+
+`lighthouseArgs` is handed to `lighthouse()`, in the order it takes them:
+
+| Option   | Default    | Description                                           |
+| -------- | ---------- | ----------------------------------------------------- |
+| `url`    | _required_ | The URL to audit                                      |
+| `flags`  | _none_     | Settings for the run, e.g. the `port` Lighthouse uses |
+| `config` | _none_     | Overrides the default config, e.g. `desktopConfig`    |
+
+Everything else it takes is passed straight to `handleAuditResult` below, which returns `{ result, failures }`.
+
+## `handleAuditResult`
+
+Handles a run you've already made yourself — this is what `runAudit` calls with the result from the actual `lighthouse()` audit:
+
+```ts
+import lighthouse from 'lighthouse'
+import { handleAuditResult } from 'lighthouse-audit-utils'
+
+const result = await lighthouse(url, { port, output: ['html', 'json'] })
+if (!result) throw new Error('Lighthouse returned no result')
+
+await handleAuditResult({
+  result,
+  reports: { directory: 'lighthouse', name: 'desktop' },
+  thresholds: { performance: 90 },
+})
+```
+
+The three steps run in that order — reports, recommendations, thresholds — so a
+failing run still prints its fix list before throwing.
+
+| Option            | Default    | Description                                                  |
+| ----------------- | ---------- | ------------------------------------------------------------ |
+| `result`          | _required_ | The full `RunnerResult` from a Lighthouse run                |
+| `reports`         | _none_     | Where to write the reports; omit to skip writing them        |
+| `recommendations` | _none_     | Recommendation logging options, or `false` to skip                  |
+| `thresholds`      | `100`      | Minimum scores (0-100) — one number for all, or per category |
+| `ignoreError`     | `false`    | Return the threshold failures rather than throwing on them              |
+
+
+```ts
+// just the log
+await handleAuditResult({ result, ignoreError: true })
+
+// just the thresholds
+await handleAuditResult({ result, recommendations: false })
+```
+
+### `reports`
+
+| Option      | Default    | Description                                                    |
+| ----------- | ---------- | -------------------------------------------------------------- |
+| `directory` | _required_ | Directory to write into; created if it doesn't exist           |
+| `name`      | _required_ | Base filename, e.g. `desktop` → `desktop.html`, `desktop.json` |
+
+Each report is written to `<directory>/<name>.<format>`, using the formats the
+run's `output` flag asked for.
+
+### `thresholds`
+
+One number applies to every category; an object sets them individually. Any
+category you leave out has to score 100, so the strict case is the default:
+
+```ts
+await handleAuditResult({ result }) // every category must score 100
+await handleAuditResult({ result, thresholds: 90 })
+await handleAuditResult({ result, thresholds: { performance: 90 } })
+```
+
+Only the categories present that are scored in the lighthouse report are checked.
+
+### `ignoreError`
+
+Returns the threshold failures instead of throwing an error, so you can decide what to do with
+them. `undefined` when everything passed.
+
+### `recommendations`
+
+| Option           | Default        | Description                                                    |
+| ---------------- | -------------- | -------------------------------------------------------------- |
+| `label`          | `reports.name` | Distinguishes runs of the same URL, e.g. `desktop`/`mobile`    |
+| `maxItems`       | `5`            | Rows shown per audit before collapsing to "…and N more"        |
+| `maxValueLength` | `120`          | Max length of a single value before it's truncated with an "…" |
+
+Pass `recommendations: false` to skip the log entirely.
+
+#### Output
+
+The log is the same fix list the report UI shows — failing audits, their
+estimated savings, and the individual offending URLs/nodes — so a failing CI run
+is actionable without downloading and opening the HTML report. Audits are
+grouped by category and sorted by estimated savings, so the biggest wins come
+first:
+
+```
+───── Lighthouse recommendations: desktop — https://example.com/ ─────
+
+Performance: 87
+  • Reduce unused JavaScript (Est savings of 1,010 KiB)
+      unused-javascript · score 50
+        - https://example.com/assets/vendor.css  ·  Transfer Size: 24.1 KiB
+        - https://example.com/assets/fonts.css  ·  Transfer Size: 7.3 KiB
+        - https://example.com/assets/dep-vendor-1.js  ·  Transfer Size: 372 KiB  ·  Est Savings: 343 KiB
+        - https://example.com/assets/dep-vendor-2.js  ·  Transfer Size: 176 KiB  ·  Est Savings: 149 KiB
+        - …and 2 more
+  • Properly size images (Potential savings of 96 KiB)
+      uses-responsive-images · score 62
+        - https://example.com/hero.png  ·  Size: 142 KiB
+        - …and 3 more
+  • Render-blocking requests — est. savings: FCP 310 ms, LCP 310 ms
+      render-blocking-insight · score 50
+        - https://example.com/assets/index.css  ·  Transfer Size: 12.4 KiB  ·  Duration: 52 ms
+
+Accessibility: 100 — nothing to fix
+```
+
+## Example: Playwright
+
+Lighthouse navigates over the CDP port itself, so launch a persistent context on
+that port and point `lighthouse` at it.
+
+```ts
+import { desktopConfig } from 'lighthouse'
+import { runAudit } from 'lighthouse-audit-utils'
+
+await runAudit({
+  lighthouseArgs: {
+    url: page.url(),
+    flags: { port, output: ['html', 'json'] },
+    config: desktopConfig,
+  },
+  reports: { directory: testInfo.outputPath('lighthouse'), name: 'desktop' },
+  thresholds: { performance: 90 },
+})
+```
+
+## Individual utilities
+
+The three steps are also exported on their own, each taking the report first and
+its options second:
+
+```ts
+writeReports(result, { directory, name })
+logRecommendations(lhr, { label, maxItems, maxValueLength })
+checkAgainstThresholds(lhr, { thresholds, ignoreError })
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build       # tsup → dist/ (types via tsc)
+pnpm start       # tsup watch
+pnpm check       # biome + tsc
+pnpm format      # biome check --fix
+```
+
+CI type-checks and builds against both supported peer majors, Lighthouse 12 and
+13, on Node 22/24/26.
+
+## License
+
+MIT

package/dist/handle-audit-result.d.ts

@@ -0,0 +1,24 @@
+import type { RunnerResult } from 'lighthouse';
+import { type FormattingArgs } from './log-recommendations';
+import { type ThresholdsArgs } from './thresholds';
+import { type WriteReportsArgs } from './write-reports';
+export type HandleAuditResultArgs = {
+    /** The full `RunnerResult` from a Lighthouse run */
+    result: RunnerResult;
+    /** Where to write the reports. Omit to skip writing them. */
+    reports?: WriteReportsArgs;
+    /** Options for recommendations logging. Set to `false` to disable. */
+    recommendations?: (FormattingArgs & {
+        /** Distinguishes runs of the same URL in one log. Defaults to `reports.name`. */
+        label?: string;
+    }) | false;
+} & ThresholdsArgs;
+/**
+ * Everything you'd do with a finished Lighthouse run:
+ *  1. write the reports
+ *  2. log the recommendations
+ *  3. check the scores against the thresholds (goes last so reporting occurs before throwing).
+ *
+ * @returns the threshold failures, if `ignoreError` kept them from throwing
+ */
+export declare const handleAuditResult: ({ result, reports, thresholds, ignoreError, recommendations, }: HandleAuditResultArgs) => Promise<import("./thresholds").ThresholdFailure[] | undefined>;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type HandleAuditResultArgs, handleAuditResult, } from './handle-audit-result';
+export { type FormattingArgs, logRecommendations, } from './log-recommendations';
+export { type LighthouseArgs, runAudit } from './run-audit';
+export { type Category, checkAgainstThresholds, type LighthouseThresholds, type ThresholdFailure, } from './thresholds';
+export { writeReports } from './write-reports';

package/dist/index.js

@@ -0,0 +1,196 @@
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+import lighthouse from 'lighthouse';
+
+// lighthouse-audit-utils 1.0.0
+
+// src/log-recommendations.ts
+var resolveMetricSavings = (audit) => Object.entries(audit.metricSavings ?? {}).filter(([, ms]) => !!ms);
+var maxMetricSavings = (audit) => Math.max(0, ...resolveMetricSavings(audit).map(([, ms]) => ms));
+var metricValueType = (metric) => metric === "CLS" ? "numeric" : "ms";
+var MEASURE_TYPES = [
+  "bytes",
+  "ms",
+  "timespanMs",
+  "numeric"
+];
+var formatValue = (value, valueType, maxValueLength) => {
+  if (value === void 0 || typeof value === "boolean") {
+    return "";
+  }
+  if (typeof value === "number") {
+    if (valueType === "bytes") {
+      const kib = value / 1024;
+      const rounded = kib >= 100 ? Math.round(kib) : Math.round(kib * 10) / 10;
+      return `${rounded} KiB`;
+    }
+    if (valueType === "ms" || valueType === "timespanMs") {
+      return `${Math.round(value)} ms`;
+    }
+    return String(Math.round(value * 100) / 100);
+  }
+  const text = (() => {
+    if (typeof value === "string") {
+      return value;
+    }
+    if (!("type" in value)) {
+      return "";
+    }
+    switch (value.type) {
+      case "url":
+        return value.value;
+      case "link":
+        return value.url || value.text;
+      case "code":
+        return String(value.value);
+      case "node":
+        return value.nodeLabel ?? value.selector ?? value.snippet ?? "";
+      case "source-location":
+        return `${value.url}:${value.line}:${value.column}`;
+      default:
+        return "";
+    }
+  })();
+  const singleLine = text.replace(/\s+/g, " ").trim();
+  return singleLine.length > maxValueLength ? `${singleLine.slice(0, maxValueLength)}\u2026` : singleLine;
+};
+var formatItems = (details, { maxItems, maxValueLength }) => {
+  if (details?.type !== "opportunity" && details?.type !== "table") {
+    return [];
+  }
+  const [identity, ...measures] = details.headings.filter(({ key }) => !!key);
+  if (!identity) {
+    return [];
+  }
+  const lines = details.items.slice(0, maxItems).map((item) => {
+    const columns = [
+      formatValue(item[identity.key ?? ""], identity.valueType, maxValueLength),
+      ...measures.filter(({ valueType }) => MEASURE_TYPES.includes(valueType)).map(
+        (heading) => `${heading.label}: ${formatValue(item[heading.key ?? ""], heading.valueType, maxValueLength)}`
+      )
+    ];
+    return `        - ${columns.filter(Boolean).join("  \xB7  ")}`;
+  });
+  const remaining = details.items.length - maxItems;
+  if (remaining > 0) {
+    lines.push(`        - \u2026and ${remaining} more`);
+  }
+  return lines;
+};
+var logRecommendations = (lhr, {
+  label,
+  maxItems = 5,
+  maxValueLength = 120
+}) => {
+  const lines = [
+    "",
+    `\u2500\u2500\u2500\u2500\u2500 Lighthouse recommendations${label ? `: ${label}` : ""} \u2014 ${lhr.finalDisplayedUrl} \u2500\u2500\u2500\u2500\u2500`
+  ];
+  for (const category of Object.values(lhr.categories)) {
+    const categoryScoreValue = category.score === null ? "N/A" : Math.round(category.score * 100);
+    const categoryLine = `${category.title}: ${categoryScoreValue}`;
+    const failing = category.auditRefs.map(({ id }) => lhr.audits[id]).filter((audit) => !!audit && audit.score !== null && audit.score < 1).sort(
+      (a, b) => maxMetricSavings(b) - maxMetricSavings(a) || (a.score ?? 0) - (b.score ?? 0)
+    );
+    if (!failing.length) {
+      lines.push("", `${categoryLine} \u2014 nothing to fix`);
+      continue;
+    }
+    lines.push("", categoryLine);
+    for (const audit of failing) {
+      const displayValue = audit.displayValue ? ` (${audit.displayValue})` : "";
+      const savingsValue = (() => {
+        if (audit.displayValue?.toLowerCase().includes("savings")) {
+          return "";
+        }
+        const overallSavingsBytes = audit.details?.type === "opportunity" ? audit.details.overallSavingsBytes : void 0;
+        const estSavings = [
+          ...resolveMetricSavings(audit).map(
+            ([metric, value]) => `${metric} ${formatValue(value, metricValueType(metric), maxValueLength)}`
+          ),
+          formatValue(overallSavingsBytes, "bytes", maxValueLength)
+        ].filter(Boolean);
+        return estSavings.length ? ` \u2014 est. savings: ${estSavings.join(", ")}` : "";
+      })();
+      const scoreValue = audit.score === null ? "N/A" : Math.round(audit.score * 100);
+      lines.push(`  \u2022 ${audit.title}${displayValue}${savingsValue}`);
+      lines.push(`      ${audit.id} \xB7 score ${scoreValue}`);
+      lines.push(...formatItems(audit.details, { maxItems, maxValueLength }));
+    }
+  }
+  lines.push("");
+  console.log(lines.join("\n"));
+};
+
+// src/thresholds.ts
+var thresholdFailureMessage = (failures) => [
+  "Lighthouse thresholds not met:",
+  ...failures.map(
+    ({ category, minimum, score }) => `${category} scored ${score}, below the ${minimum} threshold`
+  )
+].join("\n");
+var checkAgainstThresholds = (lhr, { thresholds = 100, ignoreError }) => {
+  const isFlat = typeof thresholds === "number";
+  const defaultMinimum = isFlat ? thresholds : 100;
+  const minimums = isFlat ? {} : thresholds ?? {};
+  const failures = Object.values(lhr.categories).filter((c) => c.score !== null).map(({ id, score }) => ({
+    category: id,
+    minimum: minimums[id] ?? defaultMinimum,
+    score: score * 100
+  })).filter(({ score, minimum }) => score < minimum);
+  if (!failures.length) {
+    return void 0;
+  }
+  if (!ignoreError) {
+    throw new Error(thresholdFailureMessage(failures));
+  }
+  return failures;
+};
+var writeReports = async (result, { directory, name }) => {
+  const formats = [result.lhr.configSettings.output].flat();
+  await mkdir(directory, { recursive: true });
+  await Promise.all(
+    [result.report].flat().map(
+      (report, i) => writeFile(path.join(directory, `${name}.${formats[i]}`), report)
+    )
+  );
+};
+
+// src/handle-audit-result.ts
+var handleAuditResult = async ({
+  result,
+  reports,
+  thresholds,
+  ignoreError,
+  recommendations
+}) => {
+  if (reports) {
+    await writeReports(result, reports);
+  }
+  if (recommendations !== false) {
+    logRecommendations(result.lhr, {
+      label: reports?.name,
+      ...recommendations
+    });
+  }
+  const failures = checkAgainstThresholds(result.lhr, {
+    thresholds,
+    ignoreError
+  });
+  return failures;
+};
+var runAudit = async ({
+  lighthouseArgs: { url, flags, config },
+  ...handleArgs
+}) => {
+  const result = await lighthouse(url, flags, config);
+  if (!result) {
+    throw new Error(`Lighthouse returned no result for ${url}`);
+  }
+  const failures = await handleAuditResult({ result, ...handleArgs });
+  return { result, failures };
+};
+
+export { checkAgainstThresholds, handleAuditResult, logRecommendations, runAudit, writeReports };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/log-recommendations.ts","../src/thresholds.ts","../src/write-reports.ts","../src/handle-audit-result.ts","../src/run-audit.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { RunnerResult } from 'lighthouse'\nimport type Details from 'lighthouse/types/lhr/audit-details'\n\ntype Lhr = RunnerResult['lhr']\ntype Audit = Lhr['audits'][string]\ntype AuditDetails = NonNullable<Audit['details']>\n\n/** resolves to values that are only non-zero numbers */\nconst resolveMetricSavings = (audit: Audit) =>\n  Object.entries(audit.metricSavings ?? {}).filter(([, ms]) => !!ms) as [\n    string,\n    number,\n  ][]\n\nconst maxMetricSavings = (audit: Audit) =>\n  Math.max(0, ...resolveMetricSavings(audit).map(([, ms]) => ms))\n\n/** CLS savings are a unitless shift score; every other metric is milliseconds. */\nconst metricValueType = (metric: string): Details.ItemValueType =>\n  metric === 'CLS' ? 'numeric' : 'ms'\n\n/** Columns worth repeating alongside an item's identity (URL, node, ...). */\nconst MEASURE_TYPES: Details.ItemValueType[] = [\n  'bytes',\n  'ms',\n  'timespanMs',\n  'numeric',\n]\n\nexport type FormattingArgs = {\n  /**\n   * Rows shown per audit before collapsing to \"…and N more\"\n   * @default 5\n   */\n  maxItems?: number\n  /**\n   * Max length of a single value before it's truncated with an \"…\"\n   * @default 120\n   */\n  maxValueLength?: number\n}\n\nconst formatValue = (\n  value: Details.ItemValue | undefined,\n  valueType: Details.ItemValueType,\n  maxValueLength: number\n): string => {\n  if (value === undefined || typeof value === 'boolean') {\n    return ''\n  }\n\n  if (typeof value === 'number') {\n    if (valueType === 'bytes') {\n      // Keep a decimal on small values so sub-KiB assets don't read as \"0 KiB\".\n      const kib = value / 1024\n      const rounded = kib >= 100 ? Math.round(kib) : Math.round(kib * 10) / 10\n      return `${rounded} KiB`\n    }\n    if (valueType === 'ms' || valueType === 'timespanMs') {\n      return `${Math.round(value)} ms`\n    }\n    return String(Math.round(value * 100) / 100)\n  }\n\n  // `IcuMessage` is the only object value without a `type` tag.\n  const text = (() => {\n    if (typeof value === 'string') {\n      return value\n    }\n    if (!('type' in value)) {\n      return ''\n    }\n    switch (value.type) {\n      case 'url':\n        return value.value\n      case 'link':\n        return value.url || value.text\n      case 'code':\n        return String(value.value)\n      case 'node':\n        return value.nodeLabel ?? value.selector ?? value.snippet ?? ''\n      case 'source-location':\n        return `${value.url}:${value.line}:${value.column}`\n      default:\n        return ''\n    }\n  })()\n\n  // Node labels and snippets carry the element's own line breaks — flatten them\n  // so one item stays on one line.\n  const singleLine = text.replace(/\\s+/g, ' ').trim()\n\n  return singleLine.length > maxValueLength\n    ? `${singleLine.slice(0, maxValueLength)}…`\n    : singleLine\n}\n\n/**\n * The individual offenders the report UI lists under an audit — the specific\n * render-blocking scripts, oversized images, failing DOM nodes, and so on.\n */\nconst formatItems = (\n  details: AuditDetails | undefined,\n  { maxItems, maxValueLength }: Required<FormattingArgs>\n): string[] => {\n  if (details?.type !== 'opportunity' && details?.type !== 'table') {\n    return []\n  }\n\n  const [identity, ...measures] = details.headings.filter(({ key }) => !!key)\n  if (!identity) {\n    return []\n  }\n\n  const lines = details.items.slice(0, maxItems).map((item) => {\n    const columns = [\n      formatValue(item[identity.key ?? ''], identity.valueType, maxValueLength),\n      ...measures\n        .filter(({ valueType }) => MEASURE_TYPES.includes(valueType))\n        .map(\n          (heading) =>\n            `${heading.label}: ${formatValue(item[heading.key ?? ''], heading.valueType, maxValueLength)}`\n        ),\n    ]\n    return `        - ${columns.filter(Boolean).join('  ·  ')}`\n  })\n\n  const remaining = details.items.length - maxItems\n  if (remaining > 0) {\n    lines.push(`        - …and ${remaining} more`)\n  }\n  return lines\n}\n\n/**\n * Print the same fix list the Lighthouse report UI shows, so a failing run is\n * actionable from the terminal/CI log without opening the HTML report.\n */\nexport const logRecommendations = (\n  /** The Lighthouse result object   */\n  lhr: Lhr,\n  {\n    label,\n    maxItems = 5,\n    maxValueLength = 120,\n  }: {\n    /** Distinguishes runs of the same URL in one log (e.g. `desktop`/`mobile`). */\n    label?: string\n  } & FormattingArgs\n) => {\n  const lines = [\n    '',\n    `───── Lighthouse recommendations${label ? `: ${label}` : ''} — ${lhr.finalDisplayedUrl} ─────`,\n  ]\n\n  for (const category of Object.values(lhr.categories)) {\n    const categoryScoreValue =\n      category.score === null ? 'N/A' : Math.round(category.score * 100)\n    const categoryLine = `${category.title}: ${categoryScoreValue}`\n\n    const failing = category.auditRefs\n      .map(({ id }) => lhr.audits[id])\n      .filter((audit) => !!audit && audit.score !== null && audit.score < 1)\n      .sort(\n        (a, b) =>\n          maxMetricSavings(b) - maxMetricSavings(a) ||\n          (a.score ?? 0) - (b.score ?? 0)\n      )\n\n    if (!failing.length) {\n      lines.push('', `${categoryLine} — nothing to fix`)\n      continue\n    }\n\n    lines.push('', categoryLine)\n\n    for (const audit of failing) {\n      const displayValue = audit.displayValue ? ` (${audit.displayValue})` : ''\n\n      const savingsValue: string = (() => {\n        // Most opportunities already spell out their savings in `displayValue`.\n        if (audit.displayValue?.toLowerCase().includes('savings')) {\n          return ''\n        }\n\n        const overallSavingsBytes =\n          audit.details?.type === 'opportunity'\n            ? audit.details.overallSavingsBytes\n            : undefined\n        const estSavings = [\n          ...resolveMetricSavings(audit).map(\n            ([metric, value]) =>\n              `${metric} ${formatValue(value, metricValueType(metric), maxValueLength)}`\n          ),\n          formatValue(overallSavingsBytes, 'bytes', maxValueLength),\n        ].filter(Boolean)\n\n        return estSavings.length\n          ? ` — est. savings: ${estSavings.join(', ')}`\n          : ''\n      })()\n\n      const scoreValue =\n        audit.score === null ? 'N/A' : Math.round(audit.score * 100)\n\n      lines.push(`  • ${audit.title}${displayValue}${savingsValue}`)\n      lines.push(`      ${audit.id} · score ${scoreValue}`)\n      lines.push(...formatItems(audit.details, { maxItems, maxValueLength }))\n    }\n  }\n\n  lines.push('')\n  console.log(lines.join('\\n'))\n}\n","import type { RunnerResult } from 'lighthouse'\n\ntype Lhr = RunnerResult['lhr']\ntype CategoryResult = Lhr['categories'][string]\n\nexport type Category =\n  | 'performance'\n  | 'accessibility'\n  | 'best-practices'\n  | 'seo'\n\n/** Per-category minimums, or one number applied to every category. */\nexport type LighthouseThresholds = number | Partial<Record<Category, number>>\n\n/** A category that scored below the minimum it was given. */\nexport type ThresholdFailure = {\n  /** The category's id as the run reported it — usually a `Category`. */\n  category: string\n  /** The minimum this category was checked against (0-100). */\n  minimum: number\n  /** What it actually scored (0-100). */\n  score: number\n}\n\nconst thresholdFailureMessage = (failures: ThresholdFailure[]) =>\n  [\n    'Lighthouse thresholds not met:',\n    ...failures.map(\n      ({ category, minimum, score }) =>\n        `${category} scored ${score}, below the ${minimum} threshold`\n    ),\n  ].join('\\n')\n\nexport type ThresholdsArgs = {\n  /**\n   * Minimum category scores (0-100), either per category or one number for all\n   * of them. If per category, any category omitted must score 100.\n   */\n  thresholds?: LighthouseThresholds\n  /** Return the failures rather than throwing them. */\n  ignoreError?: boolean\n}\n\n/**\n * Checks every category the run scored, throwing an error describing the ones\n * that fell short. Pass `ignoreError` to get those shortfalls back instead, so\n * the caller can log the recommendations before failing.\n */\nexport const checkAgainstThresholds = (\n  /** The Lighthouse result object */\n  lhr: Lhr,\n  { thresholds = 100, ignoreError }: ThresholdsArgs\n): ThresholdFailure[] | undefined => {\n  const isFlat = typeof thresholds === 'number'\n  const defaultMinimum = isFlat ? thresholds : 100\n  const minimums: Record<string, number | undefined> = isFlat\n    ? {}\n    : (thresholds ?? {})\n\n  const failures = Object.values(lhr.categories)\n    .filter((c): c is CategoryResult & { score: number } => c.score !== null)\n    .map(({ id, score }) => ({\n      category: id,\n      minimum: minimums[id] ?? defaultMinimum,\n      score: score * 100,\n    }))\n    .filter(({ score, minimum }) => score < minimum)\n\n  if (!failures.length) {\n    return undefined\n  }\n\n  if (!ignoreError) {\n    throw new Error(thresholdFailureMessage(failures))\n  }\n\n  return failures\n}\n","import { mkdir, writeFile } from 'node:fs/promises'\nimport path from 'node:path'\nimport type { RunnerResult } from 'lighthouse'\n\nexport type WriteReportsArgs = { directory: string; name: string }\n\n/**\n * Writes each report to `<directory>/<name>.<format>`, using the formats the\n * run's `output` flag asked for.\n */\nexport const writeReports = async (\n  result: RunnerResult,\n  { directory, name }: WriteReportsArgs\n) => {\n  const formats = [result.lhr.configSettings.output].flat()\n\n  await mkdir(directory, { recursive: true })\n  await Promise.all(\n    [result.report]\n      .flat()\n      .map((report, i) =>\n        writeFile(path.join(directory, `${name}.${formats[i]}`), report)\n      )\n  )\n}\n","import type { RunnerResult } from 'lighthouse'\n\nimport { type FormattingArgs, logRecommendations } from './log-recommendations'\nimport { checkAgainstThresholds, type ThresholdsArgs } from './thresholds'\nimport { type WriteReportsArgs, writeReports } from './write-reports'\n\nexport type HandleAuditResultArgs = {\n  /** The full `RunnerResult` from a Lighthouse run */\n  result: RunnerResult\n  /** Where to write the reports. Omit to skip writing them. */\n  reports?: WriteReportsArgs\n  /** Options for recommendations logging. Set to `false` to disable. */\n  recommendations?:\n    | (FormattingArgs & {\n        /** Distinguishes runs of the same URL in one log. Defaults to `reports.name`. */\n        label?: string\n      })\n    | false\n} & ThresholdsArgs\n\n/**\n * Everything you'd do with a finished Lighthouse run:\n *  1. write the reports\n *  2. log the recommendations\n *  3. check the scores against the thresholds (goes last so reporting occurs before throwing).\n *\n * @returns the threshold failures, if `ignoreError` kept them from throwing\n */\nexport const handleAuditResult = async ({\n  result,\n  reports,\n  thresholds,\n  ignoreError,\n  recommendations,\n}: HandleAuditResultArgs) => {\n  if (reports) {\n    await writeReports(result, reports)\n  }\n\n  if (recommendations !== false) {\n    logRecommendations(result.lhr, {\n      label: reports?.name,\n      ...recommendations,\n    })\n  }\n\n  const failures = checkAgainstThresholds(result.lhr, {\n    thresholds,\n    ignoreError,\n  })\n\n  return failures\n}\n","import lighthouse, { type Config, type Flags } from 'lighthouse'\n\nimport {\n  type HandleAuditResultArgs,\n  handleAuditResult,\n} from './handle-audit-result'\n\n/** What `lighthouse()` itself takes, in the order it takes it. */\nexport type LighthouseArgs = {\n  /** The URL to audit */\n  url: string\n  /** Settings for the run, e.g. the `port` Lighthouse connects to */\n  flags?: Flags\n  /** Overrides the default config, e.g. `desktopConfig` */\n  config?: Config\n}\n\n/**\n * Audits a URL and hands the result straight to {@link handleAuditResult}.\n *\n * @returns the run's result, plus the threshold failures if `ignoreError` kept\n * them from throwing\n */\nexport const runAudit = async ({\n  lighthouseArgs: { url, flags, config },\n  ...handleArgs\n}: {\n  /** Passed through to `lighthouse()` */\n  lighthouseArgs: LighthouseArgs\n} & Omit<HandleAuditResultArgs, 'result'>) => {\n  const result = await lighthouse(url, flags, config)\n  if (!result) {\n    throw new Error(`Lighthouse returned no result for ${url}`)\n  }\n\n  const failures = await handleAuditResult({ result, ...handleArgs })\n\n  return { result, failures }\n}\n"]}

package/dist/log-recommendations.d.ts

@@ -0,0 +1,25 @@
+import type { RunnerResult } from 'lighthouse';
+type Lhr = RunnerResult['lhr'];
+export type FormattingArgs = {
+    /**
+     * Rows shown per audit before collapsing to "…and N more"
+     * @default 5
+     */
+    maxItems?: number;
+    /**
+     * Max length of a single value before it's truncated with an "…"
+     * @default 120
+     */
+    maxValueLength?: number;
+};
+/**
+ * Print the same fix list the Lighthouse report UI shows, so a failing run is
+ * actionable from the terminal/CI log without opening the HTML report.
+ */
+export declare const logRecommendations: (
+/** The Lighthouse result object   */
+lhr: Lhr, { label, maxItems, maxValueLength, }: {
+    /** Distinguishes runs of the same URL in one log (e.g. `desktop`/`mobile`). */
+    label?: string;
+} & FormattingArgs) => void;
+export {};

package/dist/run-audit.d.ts

@@ -0,0 +1,24 @@
+import { type Config, type Flags } from 'lighthouse';
+import { type HandleAuditResultArgs } from './handle-audit-result';
+/** What `lighthouse()` itself takes, in the order it takes it. */
+export type LighthouseArgs = {
+    /** The URL to audit */
+    url: string;
+    /** Settings for the run, e.g. the `port` Lighthouse connects to */
+    flags?: Flags;
+    /** Overrides the default config, e.g. `desktopConfig` */
+    config?: Config;
+};
+/**
+ * Audits a URL and hands the result straight to {@link handleAuditResult}.
+ *
+ * @returns the run's result, plus the threshold failures if `ignoreError` kept
+ * them from throwing
+ */
+export declare const runAudit: ({ lighthouseArgs: { url, flags, config }, ...handleArgs }: {
+    /** Passed through to `lighthouse()` */
+    lighthouseArgs: LighthouseArgs;
+} & Omit<HandleAuditResultArgs, 'result'>) => Promise<{
+    result: import("lighthouse").RunnerResult;
+    failures: import("./thresholds").ThresholdFailure[] | undefined;
+}>;

package/dist/thresholds.d.ts

@@ -0,0 +1,32 @@
+import type { RunnerResult } from 'lighthouse';
+type Lhr = RunnerResult['lhr'];
+export type Category = 'performance' | 'accessibility' | 'best-practices' | 'seo';
+/** Per-category minimums, or one number applied to every category. */
+export type LighthouseThresholds = number | Partial<Record<Category, number>>;
+/** A category that scored below the minimum it was given. */
+export type ThresholdFailure = {
+    /** The category's id as the run reported it — usually a `Category`. */
+    category: string;
+    /** The minimum this category was checked against (0-100). */
+    minimum: number;
+    /** What it actually scored (0-100). */
+    score: number;
+};
+export type ThresholdsArgs = {
+    /**
+     * Minimum category scores (0-100), either per category or one number for all
+     * of them. If per category, any category omitted must score 100.
+     */
+    thresholds?: LighthouseThresholds;
+    /** Return the failures rather than throwing them. */
+    ignoreError?: boolean;
+};
+/**
+ * Checks every category the run scored, throwing an error describing the ones
+ * that fell short. Pass `ignoreError` to get those shortfalls back instead, so
+ * the caller can log the recommendations before failing.
+ */
+export declare const checkAgainstThresholds: (
+/** The Lighthouse result object */
+lhr: Lhr, { thresholds, ignoreError }: ThresholdsArgs) => ThresholdFailure[] | undefined;
+export {};

package/dist/write-reports.d.ts

@@ -0,0 +1,10 @@
+import type { RunnerResult } from 'lighthouse';
+export type WriteReportsArgs = {
+    directory: string;
+    name: string;
+};
+/**
+ * Writes each report to `<directory>/<name>.<format>`, using the formats the
+ * run's `output` flag asked for.
+ */
+export declare const writeReports: (result: RunnerResult, { directory, name }: WriteReportsArgs) => Promise<void>;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "lighthouse-audit-utils",
+  "version": "1.0.0",
+  "description": "Small utilities for driving Lighthouse audits yourself: check scores against thresholds, write reports to disk, and log the fix list to the terminal.",
+  "keywords": [
+    "lighthouse",
+    "playwright",
+    "performance",
+    "ci",
+    "terminal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bvandrc/lighthouse-audit-utils"
+  },
+  "author": {
+    "name": "Blake Vandercar",
+    "email": "bvandercar@outlook.com"
+  },
+  "license": "MIT",
+  "type": "module",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.9.0",
+  "scripts": {
+    "__c0": "====================[ Build & Development ]======================",
+    "prepack": "pnpm build",
+    "build": "tsup-node && pnpm build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "start": "tsup-node --watch",
+    "__c1": "====================[ Linting & Type Checking ]==================",
+    "check": "npx biome check . && pnpm ts:check",
+    "format": "npx biome check . --fix",
+    "ts:check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "lighthouse": "^12 || ^13"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2",
+    "@types/node": "^24",
+    "lighthouse": "^13",
+    "tsup": "^8",
+    "typescript": "^7"
+  }
+}