From 52409e232e46f928f71fa5de817191050b48388b Mon Sep 17 00:00:00 2001 From: hugoer Date: Fri, 4 Sep 2026 11:31:36 +0200 Subject: [PATCH 1/2] fix(types): resolve the four Lab*Options types from the package root MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit lib/index.js is a value-only façade of lazy getters, so a type is importable from the root only if it is re-declared there. LabAuditOptions, LabWriteOptions, LabPlanControls and LabPlanOptions were added to the README's "Key exported types" table without the matching @typedef, so the documented `import type { LabPlanOptions } from '@hugoer/web-perf-cli'` failed with TS2305 while the same import from the /lab subpath worked. type-tests/root.ts asserts that every row of that table resolves from the root, but enumerates the rows by hand and never listed these four, so the guard passed on an invariant it only partially checked. Adding them to the import and the Rows tuple reproduces the four TS2305 errors against the old index.js and passes against the new one. Same defect #17 fixed for LabReport, CruxReport and the rest. --- lib/index.js | 4 ++++ type-tests/root.ts | 7 ++++++- types/lib/index.d.ts | 26 +++++++++++++++++++++++++- 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/lib/index.js b/lib/index.js index 965c4a9..6ebc65c 100644 --- a/lib/index.js +++ b/lib/index.js @@ -5,6 +5,10 @@ * * @typedef {import('./lab').LabReport} LabReport * @typedef {import('./lab').LabPlanResult} LabPlanResult + * @typedef {import('./lab').LabAuditOptions} LabAuditOptions + * @typedef {import('./lab').LabWriteOptions} LabWriteOptions + * @typedef {import('./lab').LabPlanControls} LabPlanControls + * @typedef {import('./lab').LabPlanOptions} LabPlanOptions * @typedef {import('./psi').PsiReport} PsiReport * @typedef {import('./psi').PsiBatchResult} PsiBatchResult * @typedef {import('./crux').CruxReport} CruxReport diff --git a/type-tests/root.ts b/type-tests/root.ts index 4ff50b7..ce16821 100644 --- a/type-tests/root.ts +++ b/type-tests/root.ts @@ -8,15 +8,20 @@ import type { CruxReport, CruxMetric, CruxBatchResult, CruxFormFactor, CruxHistoryReport, CruxHistoryBatchResult, RunSummary, LabProfile, NetworkPreset, DevicePreset, + LabAuditOptions, LabWriteOptions, LabPlanControls, LabPlanOptions, } from '@hugoer/web-perf-cli'; export const fns = [runCruxAudit, runPsiAudit, runLabAudit, normalizeOrigin]; export const flags: readonly string[] = CHROME_FLAGS; -// Every row of the README's "Key exported types" table must resolve from the root. +// Every row of the README's "Key exported types" table must resolve from the root. The list is +// maintained by hand, so a new row added to that table is only covered once it is added here too +// — four Lab*Options rows sat undetected that way (#22). The README table carries a comment +// pointing back at this file so the two are edited together. export type Rows = [ LabReport, LabPlanResult, PsiReport, PsiBatchResult, CruxReport, CruxMetric, CruxBatchResult, CruxFormFactor, CruxHistoryReport, CruxHistoryBatchResult, RunSummary, LabProfile, NetworkPreset, DevicePreset, + LabAuditOptions, LabWriteOptions, LabPlanControls, LabPlanOptions, ]; diff --git a/types/lib/index.d.ts b/types/lib/index.d.ts index eab7e0b..85a5f38 100644 --- a/types/lib/index.d.ts +++ b/types/lib/index.d.ts @@ -1,5 +1,5 @@ declare namespace _exports { - export { LabReport, LabPlanResult, PsiReport, PsiBatchResult, CruxReport, CruxMetric, CruxBatchResult, CruxFormFactor, CruxHistoryReport, CruxHistoryBatchResult, LabProfile, NetworkPreset, DevicePreset, RunSummary }; + export { LabReport, LabPlanResult, LabAuditOptions, LabWriteOptions, LabPlanControls, LabPlanOptions, PsiReport, PsiBatchResult, CruxReport, CruxMetric, CruxBatchResult, CruxFormFactor, CruxHistoryReport, CruxHistoryBatchResult, LabProfile, NetworkPreset, DevicePreset, RunSummary }; } declare namespace _exports { const runLabAudit: typeof import("./lab").runLabAudit; @@ -39,6 +39,30 @@ type LabReport = import("./lab").LabReport; * documented `import type { CruxReport } from '@hugoer/web-perf-cli'` fails with TS2305. */ type LabPlanResult = import("./lab").LabPlanResult; +/** + * The types the README's "Key exported types" table promises from the package root. Re-declared + * here because lib/index.js is a value-only façade of lazy getters: without these, the + * documented `import type { CruxReport } from '@hugoer/web-perf-cli'` fails with TS2305. + */ +type LabAuditOptions = import("./lab").LabAuditOptions; +/** + * The types the README's "Key exported types" table promises from the package root. Re-declared + * here because lib/index.js is a value-only façade of lazy getters: without these, the + * documented `import type { CruxReport } from '@hugoer/web-perf-cli'` fails with TS2305. + */ +type LabWriteOptions = import("./lab").LabWriteOptions; +/** + * The types the README's "Key exported types" table promises from the package root. Re-declared + * here because lib/index.js is a value-only façade of lazy getters: without these, the + * documented `import type { CruxReport } from '@hugoer/web-perf-cli'` fails with TS2305. + */ +type LabPlanControls = import("./lab").LabPlanControls; +/** + * The types the README's "Key exported types" table promises from the package root. Re-declared + * here because lib/index.js is a value-only façade of lazy getters: without these, the + * documented `import type { CruxReport } from '@hugoer/web-perf-cli'` fails with TS2305. + */ +type LabPlanOptions = import("./lab").LabPlanOptions; /** * The types the README's "Key exported types" table promises from the package root. Re-declared * here because lib/index.js is a value-only façade of lazy getters: without these, the From d328c79f95734fde666630d0cdf2ea11e2205267 Mon Sep 17 00:00:00 2001 From: hugoer Date: Fri, 4 Sep 2026 11:31:42 +0200 Subject: [PATCH 2/2] docs: point the exported-types table at the guard that covers it The hand-maintained Rows tuple in type-tests/root.ts is why the four Lab*Options rows drifted undetected: a README row added without a matching tuple entry is invisible to CI. An HTML comment above the table names the two files to edit alongside it and why the root re-declaration is needed at all. A comment rather than a generated check: the failure mode is a documented type that does not resolve, not a broken build, and parsing the table at test time costs more than the drift it would prevent. Revisit if it drifts again. --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 041607e..c7be215 100644 --- a/README.md +++ b/README.md @@ -594,6 +594,11 @@ import type { CruxHistoryReport } from '@hugoer/web-perf-cli/crux-history'; Key exported types: + + | Type | Description | |------|-------------| | `LabReport` | Lighthouse JSON with `i18n` and `timing` stripped (categories, audits, environment, configSettings). Pass `--no-strip-json-props` / `stripJsonProps: false` to keep them |