core: restructure types for direct import and publishing

.eslintignore

@@ -15,4 +15,5 @@ core/scripts/legacy-javascript/variants
 third-party/**
 
 # ignore d.ts files until we can properly lint them
-*.d.ts
+**/*.d.ts
+**/*.d.cts

.eslintrc.cjs

@@ -76,7 +76,7 @@ module.exports = {
       vars: 'all',
       args: 'after-used',
       argsIgnorePattern: '(^reject$|^_+$)',
-      varsIgnorePattern: '(^_$)',
+      varsIgnorePattern: '(^_$|^LH$)',
     }],
     'space-infix-ops': 2,
     'strict': [2, 'global'],

.gitignore

@@ -62,3 +62,8 @@ proto/scripts/*_processed.json
 # require any lock file to be checked in explicitly
 yarn.lock
 
+# ignore generated d.ts files
+**/*.d.ts
+**/*.d.cts
+!**/types/**/*.d.ts
+

core/index.js

@@ -16,6 +16,7 @@ import {ReportGenerator} from '../report/generator/report-generator.js';
 import {startTimespanGather} from './gather/timespan-runner.js';
 import {snapshotGather} from './gather/snapshot-runner.js';
 import {navigationGather} from './gather/navigation-runner.js';
+import * as LH from '../types/lh.js';
 
 /** @typedef {import('./legacy/gather/connections/connection.js').Connection} Connection */
 
@@ -157,6 +158,7 @@ export {default as Gatherer} from './gather/base-gatherer.js';
 export {NetworkRecords} from './computed/network-records.js';
 export {default as defaultConfig} from './config/default-config.js';
 export {default as desktopConfig} from './config/desktop-config.js';
+export * from '../types/lh.js';
 export {
   legacyNavigation,
   startFlow,

core/user-flow.js

@@ -13,6 +13,7 @@ import {initializeConfig} from './config/config.js';
 import {getFormatted} from '../shared/localization/format.js';
 import {mergeConfigFragment, deepClone} from './config/config-helpers.js';
 import * as i18n from './lib/i18n/i18n.js';
+import * as LH from '../types/lh.js';
 
 /** @typedef {WeakMap<LH.UserFlow.GatherStep, LH.Gatherer.FRGatherResult['runnerOptions']>} GatherStepRunnerOptions */
 

flow-report/tsconfig.json

@@ -19,7 +19,7 @@
     "**/*.ts",
     "**/*.tsx",
     "./types",
-    "../types/test.d.ts",
+    "../types/env/test.d.ts",
     "../root.js",
     "../esm-utils.js",
     "../core/test/test-env/fake-timers.js",

package.json

@@ -15,7 +15,7 @@
   "scripts": {
     "prepack": "yarn build-report --standalone --flow --esm",
     "build-all": "npm-run-posix-or-windows build-all:task",
-    "build-all:task": "yarn build-report && yarn build-cdt-lib && yarn build-devtools && concurrently 'yarn build-extension' 'yarn build-lr' 'yarn build-viewer' 'yarn build-treemap' 'yarn build-smokehouse-bundle' && yarn build-pack",
+    "build-all:task": "yarn build-report && yarn build-cdt-lib && yarn build-devtools && yarn build-types && concurrently 'yarn build-extension' 'yarn build-lr' 'yarn build-viewer' 'yarn build-treemap' 'yarn build-smokehouse-bundle' && yarn build-pack",
     "build-all:task:windows": "yarn build-report && yarn build-cdt-lib && yarn build-extension && yarn build-devtools && yarn build-lr && yarn build-viewer && yarn build-treemap && yarn build-smokehouse-bundle",
     "build-cdt-lib": "node ./build/build-cdt-lib.js",
     "build-extension": "yarn build-extension-chrome && yarn build-extension-firefox",
@@ -29,9 +29,11 @@
     "build-sample-reports": "yarn build-report && node build/build-sample-reports.js",
     "build-treemap": "node ./build/build-treemap.js",
     "build-viewer": "node ./build/build-viewer.js",
+    "build-types": "tsc --build tsconfig-all.json && rsync -a .tmp/tsbuildinfo/ ./ --include='*.d.ts' --include='*.d.cts' --exclude='*.map' --exclude='*.tsbuildinfo'",
     "reset-link": "(yarn unlink || true) && yarn link && yarn link lighthouse",
     "c8": "bash core/scripts/c8.sh",
     "clean": "rm -r dist proto/scripts/*.json proto/scripts/*_pb2.* proto/scripts/*_pb.* proto/scripts/__pycache__ proto/scripts/*.pyc *.report.html *.report.dom.html *.report.json *.devtoolslog.json *.trace.json shared/localization/locales/*.ctc.json || true",
+    "clean-types": "git clean -xf '*.d.ts' '*.d.cts' -e 'node_modules/' -e 'dist/' -e '.tmp/'",
     "lint": "[ \"$CI\" = true ] && eslint --quiet -f codeframe . || eslint .",
     "smoke": "node cli/test/smokehouse/frontends/smokehouse-bin.js",
     "debug": "node --inspect-brk ./cli/index.js",

report/types/augment-dom.d.ts

@@ -10,7 +10,7 @@
  */
 
 // Import to augment querySelector/querySelectorAll with stricter type checking.
-import '../../types/query-selector';
+import '../../types/env/query-selector';
 
 declare global {
   var CompressionStream: {

types/audit.d.ts

@@ -5,12 +5,12 @@
  */
 
 import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map.js';
-import {Artifacts} from './artifacts';
-import AuditDetails from './lhr/audit-details';
-import Config from './config';
-import Gatherer from './gatherer';
-import {IcuMessage} from './lhr/i18n';
-import * as AuditResult from './lhr/audit-result';
+import Artifacts from './artifacts.js';
+import AuditDetails from './lhr/audit-details.js';
+import Config from './config.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
+import * as AuditResult from './lhr/audit-result.js';
 import Util from './utility-types.js';
 
 declare module Audit {

types/config.d.ts

@@ -6,9 +6,9 @@
  */
 
 import {Audit} from '../core/audits/audit.js';
-import {SharedFlagsSettings, ConfigSettings} from './lhr/settings';
-import Gatherer from './gatherer';
-import {IcuMessage} from './lhr/i18n';
+import {SharedFlagsSettings, ConfigSettings} from './lhr/settings.js';
+import Gatherer from './gatherer.js';
+import {IcuMessage} from './lhr/i18n.js';
 
 interface ClassOf<T> {
   new (): T;

types/env/global.d.ts

@@ -0,0 +1,3 @@
+export * from '../lh.js';
+
+export as namespace LH;

types/lookup-closest-locale/index.d.ts → types/env/lookup-closest-locale.d.ts

@@ -4,8 +4,10 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
+type Locale = import('../lhr/settings.js').Locale;
+
 declare module 'lookup-closest-locale' {
-  function lookupClosestLocale(locale: string[]|string|undefined, available: Record<LH.Locale, any>): LH.Locale|undefined;
+  function lookupClosestLocale(locale: string[]|string|undefined, available: Record<Locale, any>): Locale|undefined;
 
   export = lookupClosestLocale;
 }

types/smokehouse.d.ts → types/env/smokehouse.d.ts

@@ -4,9 +4,9 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {Artifacts} from './artifacts';
-import Config from './config';
-import LHResult from './lhr/lhr';
+import Artifacts from '../artifacts.js';
+import Config from '../config.js';
+import LHResult from '../lhr/lhr.js';
 
 declare global {
   module Smokehouse {

types/externs.d.ts

@@ -4,9 +4,9 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
-import {Artifacts} from './artifacts';
-import LHResult from './lhr/lhr';
-import {SharedFlagsSettings, OutputMode} from './lhr/settings';
+import Artifacts from './artifacts.js';
+import LHResult from './lhr/lhr.js';
+import {SharedFlagsSettings, OutputMode} from './lhr/settings.js';
 
 /**
  * Extends the flags in SharedFlagsSettings with flags used to configure the

types/gatherer.d.ts

@@ -4,6 +4,9 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
+import Crdp from 'devtools-protocol/types/protocol';
+import CrdpMappings from 'devtools-protocol/types/protocol-mapping';
+
 import {NetworkNode as _NetworkNode} from '../core/lib/dependency-graph/network-node';
 import {CPUNode as _CPUNode} from '../core/lib/dependency-graph/cpu-node';
 import {Simulator as _Simulator} from '../core/lib/dependency-graph/simulator/simulator';
@@ -12,24 +15,27 @@ import {ExecutionContext} from '../core/gather/driver/execution-context';
 import {Fetcher} from '../core/gather/fetcher';
 import {ArbitraryEqualityMap} from '../core/lib/arbitrary-equality-map';
 
-import {Artifacts, BaseArtifacts, FRBaseArtifacts, GathererArtifacts} from './artifacts';
+import Artifacts from './artifacts';
 import Config from './config';
 import {IcuMessage} from './lhr/i18n';
 import Result from './lhr/lhr';
 import Protocol from './protocol';
-import {Trace, DevtoolsLog} from './artifacts';
+import Puppeteer from './puppeteer';
+
+type CrdpEvents = CrdpMappings.Events;
+type CrdpCommands = CrdpMappings.Commands;
 
 declare module Gatherer {
   /** The Lighthouse wrapper around a raw CDP session. */
   interface FRProtocolSession {
-    setTargetInfo(targetInfo: LH.Crdp.Target.TargetInfo): void;
+    setTargetInfo(targetInfo: Crdp.Target.TargetInfo): void;
     hasNextProtocolTimeout(): boolean;
     getNextProtocolTimeout(): number;
     setNextProtocolTimeout(ms: number): void;
-    on<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    once<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    off<TEvent extends keyof LH.CrdpEvents>(event: TEvent, callback: (...args: LH.CrdpEvents[TEvent]) => void): void;
-    sendCommand<TMethod extends keyof LH.CrdpCommands>(method: TMethod, ...params: LH.CrdpCommands[TMethod]['paramsType']): Promise<LH.CrdpCommands[TMethod]['returnType']>;
+    on<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    once<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    off<TEvent extends keyof CrdpEvents>(event: TEvent, callback: (...args: CrdpEvents[TEvent]) => void): void;
+    sendCommand<TMethod extends keyof CrdpCommands>(method: TMethod, ...params: CrdpCommands[TMethod]['paramsType']): Promise<CrdpCommands[TMethod]['returnType']>;
     dispose(): Promise<void>;
   }
 
@@ -53,13 +59,13 @@ declare module Gatherer {
     /** The connection to the page being analyzed. */
     driver: FRTransitionalDriver;
     /** The Puppeteer page handle. Will be undefined in legacy navigation mode. */
-    page?: LH.Puppeteer.Page;
+    page?: Puppeteer.Page;
     /** The set of base artifacts that are always collected. */
-    baseArtifacts: FRBaseArtifacts;
+    baseArtifacts: Artifacts.FRBaseArtifacts;
     /** The cached results of computed artifacts. */
     computedCache: Map<string, ArbitraryEqualityMap>;
     /** The set of available dependencies requested by the current gatherer. */
-    dependencies: Pick<GathererArtifacts, Exclude<TDependencies, DefaultDependenciesKey>>;
+    dependencies: Pick<Artifacts.GathererArtifacts, Exclude<TDependencies, DefaultDependenciesKey>>;
     /** The settings used for gathering. */
     settings: Config.Settings;
   }
@@ -82,22 +88,22 @@ declare module Gatherer {
     computedCache: Map<string, ArbitraryEqualityMap>
     /** Gatherers can push to this array to add top-level warnings to the LHR. */
     LighthouseRunWarnings: Array<string | IcuMessage>;
-    baseArtifacts: BaseArtifacts;
+    baseArtifacts: Artifacts.BaseArtifacts;
   }
 
   interface LoadData {
     networkRecords: Array<Artifacts.NetworkRequest>;
-    devtoolsLog: DevtoolsLog;
-    trace?: Trace;
+    devtoolsLog: Artifacts.DevtoolsLog;
+    trace?: Artifacts.Trace;
   }
 
-  type PhaseResultNonPromise = void | GathererArtifacts[keyof GathererArtifacts];
+  type PhaseResultNonPromise = void | Artifacts.GathererArtifacts[keyof Artifacts.GathererArtifacts];
   type PhaseResult = PhaseResultNonPromise | Promise<PhaseResultNonPromise>
 
   type GatherMode = Result.GatherMode;
 
   type DefaultDependenciesKey = '__none__'
-  type DependencyKey = keyof GathererArtifacts | DefaultDependenciesKey
+  type DependencyKey = keyof Artifacts.GathererArtifacts | DefaultDependenciesKey
 
   interface GathererMetaNoDependencies {
     /**
@@ -123,7 +129,7 @@ declare module Gatherer {
       GathererMetaWithDependencies<Exclude<TDependencies, DefaultDependenciesKey>>;
 
   interface GathererInstance {
-    name: keyof GathererArtifacts;
+    name: keyof Artifacts.GathererArtifacts;
     beforePass(context: Gatherer.PassContext): PhaseResult;
     pass(context: Gatherer.PassContext): PhaseResult;
     afterPass(context: Gatherer.PassContext, loadData: Gatherer.LoadData): PhaseResult;
@@ -132,7 +138,7 @@ declare module Gatherer {
   type FRGatherPhase = keyof Omit<Gatherer.FRGathererInstance, 'name'|'meta'>
 
   interface FRGathererInstance<TDependencies extends DependencyKey = DefaultDependenciesKey> {
-    name: keyof GathererArtifacts; // temporary COMPAT measure until artifact config support is available
+    name: keyof Artifacts.GathererArtifacts; // temporary COMPAT measure until artifact config support is available
     meta: GathererMeta<TDependencies>;
     startInstrumentation(context: FRTransitionalContext<DefaultDependenciesKey>): Promise<void>|void;
     startSensitiveInstrumentation(context: FRTransitionalContext<DefaultDependenciesKey>): Promise<void>|void;