core: restructure types for direct import and publishing (#14441)

.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'],

.github/workflows/ci.yml

@@ -31,6 +31,7 @@ jobs:
         node-version: 16.x
 
     - run: yarn install --frozen-lockfile --network-timeout 1000000
+    - run: yarn type-check
     - run: yarn build-all
 
     # Run pptr tests using ToT Chrome instead of stable default.
@@ -53,7 +54,6 @@ jobs:
 
     - run: yarn diff:sample-json
     - run: yarn diff:flow-sample-json
-    - run: yarn type-check
     - run: yarn lint
     - run: yarn test-lantern
     - run: yarn test-legacy-javascript

.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/audits/audit.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../types/lh.js';
 import {isUnderTest} from '../lib/lh-env.js';
 import * as statistics from '../lib/statistics.js';
 import {Util} from '../util.cjs';

core/computed/network-records.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../types/lh.js';
 import {makeComputedArtifact} from './computed-artifact.js';
 import {NetworkRecorder} from '../lib/network-recorder.js';
 

core/config/default-config.js

@@ -6,6 +6,7 @@
 
 /* eslint-disable max-len */
 
+import * as LH from '../../types/lh.js';
 import * as constants from './constants.js';
 import * as i18n from '../lib/i18n/i18n.js';
 import {metricsToAudits} from './metrics-to-audits.js';

core/config/desktop-config.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../types/lh.js';
 import * as constants from './constants.js';
 
 /** @type {LH.Config} */

core/gather/base-gatherer.js

@@ -4,6 +4,8 @@
  * 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 * as LH from '../../types/lh.js';
+
 /* eslint-disable no-unused-vars */
 
 /**

core/gather/driver/execution-context.js

@@ -6,6 +6,7 @@
 
 /* global window */
 
+import * as LH from '../../../types/lh.js';
 import {pageFunctions} from '../../lib/page-functions.js';
 
 class ExecutionContext {

core/gather/fetcher.js

@@ -4,6 +4,8 @@
  * 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 * as LH from '../../types/lh.js';
+
 /**
  * @fileoverview Fetcher is a utility for making requests to any arbitrary resource,
  * ignoring normal browser constraints such as CORS.

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/legacy/gather/connections/connection.js

@@ -8,6 +8,7 @@ import {EventEmitter} from 'events';
 
 import log from 'lighthouse-logger';
 
+import * as LH from '../../../../types/lh.js';
 import {LighthouseError} from '../../../lib/lh-error.js';
 
 // TODO(bckenny): CommandCallback properties should be tied by command type after

core/legacy/gather/driver.js

@@ -8,6 +8,7 @@ import {EventEmitter} from 'events';
 
 import log from 'lighthouse-logger';
 
+import * as LH from '../../../types/lh.js';
 import {Fetcher} from '../../gather/fetcher.js';
 import {ExecutionContext} from '../../gather/driver/execution-context.js';
 import {LighthouseError} from '../../lib/lh-error.js';

core/lib/dependency-graph/cpu-node.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../../types/lh.js';
 import {BaseNode} from './base-node.js';
 
 class CPUNode extends BaseNode {

core/lib/dependency-graph/network-node.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../../types/lh.js';
 import {BaseNode} from './base-node.js';
 import {NetworkRequest} from '../network-request.js';
 

core/lib/dependency-graph/simulator/connection-pool.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../../../types/lh.js';
 import {NetworkAnalyzer} from './network-analyzer.js';
 import {TcpConnection} from './tcp-connection.js';
 

core/lib/dependency-graph/simulator/dns-cache.js

@@ -4,6 +4,8 @@
  * 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 * as LH from '../../../../types/lh.js';
+
 // A DNS lookup will usually take ~1-2 roundtrips of connection latency plus the extra DNS routing time.
 // Example: https://www.webpagetest.org/result/180703_3A_e33ec79747c002ed4d7bcbfc81462203/1/details/#waterfall_view_step1
 // Example: https://www.webpagetest.org/result/180707_1M_89673eb633b5d98386de95dfcf9b33d5/1/details/#waterfall_view_step1

core/lib/dependency-graph/simulator/simulator-timing-map.js

@@ -16,8 +16,8 @@ import {BaseNode} from '../base-node.js';
 
 
 /** @typedef {import('../base-node.js').Node} Node */
-/** @typedef {import('../network-node').NetworkNode} NetworkNode */
-/** @typedef {import('../cpu-node').CPUNode} CpuNode */
+/** @typedef {import('../network-node.js').NetworkNode} NetworkNode */
+/** @typedef {import('../cpu-node.js').CPUNode} CpuNode */
 
 /**
  * @typedef NodeTimingComplete

core/lib/dependency-graph/simulator/simulator.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../../../types/lh.js';
 import {BaseNode} from '../base-node.js';
 import {TcpConnection} from './tcp-connection.js';
 import {ConnectionPool} from './connection-pool.js';
@@ -14,8 +15,8 @@ import * as constants from '../../../config/constants.js';
 const mobileSlow4G = constants.throttling.mobileSlow4G;
 
 /** @typedef {import('../base-node.js').Node} Node */
-/** @typedef {import('../network-node').NetworkNode} NetworkNode */
-/** @typedef {import('../cpu-node').CPUNode} CpuNode */
+/** @typedef {import('../network-node.js').NetworkNode} NetworkNode */
+/** @typedef {import('../cpu-node.js').CPUNode} CpuNode */
 /** @typedef {import('./simulator-timing-map.js').CpuNodeTimingComplete | import('./simulator-timing-map.js').NetworkNodeTimingComplete} CompleteNodeTiming */
 /** @typedef {import('./simulator-timing-map.js').ConnectionTiming} ConnectionTiming */
 

core/lib/network-request.js

@@ -52,6 +52,7 @@
       Trace: ResourceFinish.ts
  */
 
+import * as LH from '../../types/lh.js';
 import UrlUtils from './url-utils.js';
 
 // Lightrider X-Header names for timing information.

core/lib/tracehouse/main-thread-tasks.js

@@ -4,6 +4,7 @@
  * 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 * as LH from '../../../types/lh.js';
 import {taskGroups, taskNameToGroup} from './task-groups.js';
 
 /**

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 */
 

docs/recipes/package.json

@@ -1,9 +1,10 @@
 {
   "private": true,
   "scripts": {
-    "install-all": "rm -rf /tmp/.junk && rm -f {auth,custom-gatherer-puppeteer,integration-test}/yarn.lock && yarn --cwd auth/ --cache-folder /tmp/.junk && yarn --cwd integration-test/ --cache-folder /tmp/.junk && yarn --cwd custom-gatherer-puppeteer/ --cache-folder /tmp/.junk",
+    "install-all": "rm -rf /tmp/.junk && rm -f {auth,custom-gatherer-puppeteer,integration-test,type-checking}/yarn.lock && yarn --cwd auth/ --cache-folder /tmp/.junk && yarn --cwd integration-test/ --cache-folder /tmp/.junk && yarn --cwd custom-gatherer-puppeteer/ --cache-folder /tmp/.junk && yarn --cwd type-checking/ --cache-folder /tmp/.junk",
     "integration-test": "yarn --cwd integration-test/ test",
     "custom-gatherer-puppeteer-test": "yarn --cwd custom-gatherer-puppeteer/ test",
+    "type-checking-test": "yarn --cwd type-checking/ test",
     "test": "sh test-recipes.sh"
   }
 }

docs/recipes/test-recipes.sh

@@ -19,3 +19,4 @@ fi
 yarn install-all
 yarn integration-test
 yarn custom-gatherer-puppeteer-test
+yarn type-checking-test

docs/recipes/type-checking/package.json

@@ -0,0 +1,14 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "tsc"
+  },
+  "devDependencies": {
+    "lighthouse": "file:../../../dist/lighthouse.tgz",
+    "typescript": "^4.9.4"
+  },
+  "dependencies": {
+    "puppeteer": "^19.5.2"
+  }
+}

docs/recipes/type-checking/readme.md

@@ -0,0 +1,5 @@
+# Lighthouse type checking recipe
+
+This example project demonstrates how Lighthouse types can be imported into a node project.
+
+`use-types.ts` is a basic user flow script that takes advantage of Lighthouse types and integrates with the version of Puppeteer installed.

docs/recipes/type-checking/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "target": "esnext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+  },
+  "include": [
+    "./use-types.ts"
+  ]
+}

docs/recipes/type-checking/use-types.ts

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright 2023 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * 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 {writeFileSync} from 'fs';
+
+import * as lhApi from 'lighthouse';
+import puppeteer from 'puppeteer';
+
+const browser = await puppeteer.launch();
+const page = await browser.newPage();
+
+const config: lhApi.Config = {
+  extends: 'lighthouse:default',
+  settings: {
+    skipAudits: ['uses-http2'],
+  },
+};
+
+// Lighthouse will accept a page from whatever Puppeteer version is installed.
+const flow: lhApi.UserFlow = await lhApi.startFlow(page, {config});
+
+await flow.navigate('https://example.com');
+
+await flow.startTimespan({name: 'Click button'});
+await page.click('button');
+await flow.endTimespan();
+
+await flow.snapshot({name: 'New page state'});
+
+const report = await flow.generateReport();
+writeFileSync('flow.report.html', report);

flow-report/tsconfig.json

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

package.json

@@ -13,7 +13,8 @@
     "node": ">=16.16"
   },
   "scripts": {
-    "prepack": "yarn build-report --standalone --flow --esm",
+    "prepack": "yarn build-report --standalone --flow --esm && yarn build-types",
+    "postpack": "yarn clean-types",
     "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: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",
@@ -29,9 +30,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": "yarn type-check && 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 -xfq '*.d.ts' '*.d.cts' -e 'node_modules/' -e 'dist/' -e '.tmp/' -e '**/types/'",
     "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/internal/query-selector';
 
 declare global {
   var CompressionStream: {