Merge branch 'DefinitelyTyped:master' into master

.dprint.jsonc

@@ -28,7 +28,6 @@
         "./types/react-native",
         "./types/recurly__recurly-js",
         "./types/sawtooth-sdk",
-        "./types/three",
         "./types/webextension-polyfill",
         "./types/winrt-uwp",
         "./types/vscode",

.github/workflows/CI.yml

@@ -1,13 +1,65 @@
 name: CI
-on: pull_request
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  schedule:
+    # 12PM UTC -> 4AM Pacific
+    - cron: '0 12 * * *'
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  # If in a PR, use the ref (refs/pull/<num>) so outdated PR runs are cancelled.
+  # Otherwise, run_id is unique so all other events will never be cancelled.
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
+  setup-matrix:
+    runs-on: ubuntu-latest
+    if: github.repository == 'DefinitelyTyped/DefinitelyTyped'
+
+    outputs:
+      matrix: ${{ steps.matrix.outputs.matrix }}
+
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          # Need this to be able to inquire about origin/master
+          filter: blob:none # https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/
+          fetch-depth: 0 # Default is 1; need to set to 0 to get the benefits of blob:none.
+      - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+        with:
+          node-version: '20'
+
+      - uses: pnpm/action-setup@d882d12c64e032187b2edb46d3a0d003b7a43598 # v2.4.0
+
+      - id: matrix
+        run: |
+          if [ "${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}" == "true" ]; then
+            TESTS=all
+          else
+            TESTS=$(pnpm ls --depth -1 --parseable --filter '...@types/**[HEAD^1]' | wc -)
+          fi
+          MATRIX=$(node ./scripts/get-ci-matrix $TESTS)
+          echo $MATRIX
+          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+
   test:
     runs-on: ubuntu-latest
     if: github.repository == 'DefinitelyTyped/DefinitelyTyped'
+    needs: setup-matrix
+
+    strategy:
+      matrix: ${{ fromJson(needs.setup-matrix.outputs.matrix) }}
+      fail-fast: false
 
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
@@ -35,19 +87,68 @@ jobs:
           echo "store=$(pnpm store path)" >> $GITHUB_OUTPUT
 
       - name: Restore pnpm cache
-        uses: actions/cache/restore@704facf57e6136b1bc63b828d79edcd491f0ee84 # v3.3.2
+        uses: actions/cache/restore@13aacd865c20de90d75de3b17ebe84f7a17d57d2 # v4.0.0
         with:
           path: ${{ steps.pnpm-cache.outputs.store }}
           key: ${{ runner.os }}-pnpm-store-cache-
           restore-keys: ${{ runner.os }}-pnpm-store-cache-
 
       - run: ./scripts/pnpm-install.sh
+        name: pnpm install (filtered)
+        if: ${{ !(github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') }}
+
+      - run: pnpm install
         name: pnpm install
+        if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
 
       - run: pnpm ls
 
-      # Run tests
-      - run: pnpm run test-all
+      - run: pnpm run test-all --diffBase HEAD^1 --shardCount ${{ matrix.shardCount }} --shardId ${{ matrix.shardId }}
+        if: ${{ !(github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') }}
+
+      - run: pnpm dtslint-runner --path . --selection all --onlyTestTsNext --shardCount ${{ matrix.shardCount }} --shardId ${{ matrix.shardId }}
+        if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
+
+      - name: Get suggestions dir
+        id: suggestions-dir
+        run: echo "path=$(node ./scripts/get-suggestions-dir.js)" >> "$GITHUB_OUTPUT"
+        if: ${{ github.event_name == 'pull_request' }}
+
+      - name: Upload suggestions
+        uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 # v4.3.0
+        with:
+          name: suggestions_${{ matrix.shardId }}_${{ matrix.shardCount }}
+          if-no-files-found: ignore
+          path: ${{ steps.suggestions-dir.outputs.path }}
+          retention-days: 1
+        if: ${{ github.event_name == 'pull_request' }}
+
+  dangerbot:
+    runs-on: ubuntu-latest
+    if: github.repository == 'DefinitelyTyped/DefinitelyTyped' && github.event_name == 'pull_request'
+
+    needs:
+      - test
+
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+        with:
+          node-version: '20'
+
+      - uses: pnpm/action-setup@d882d12c64e032187b2edb46d3a0d003b7a43598 # v2.4.0
+        with:
+          run_install: |
+            - args: [--filter, ., --filter, '{./scripts}...']
+
+      - name: Get suggestions dir
+        id: suggestions-dir
+        run: echo "path=$(node ./scripts/get-suggestions-dir.js)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/download-artifact@6b208ae046db98c579e8a3aa621ab581ff575935 # v4.1.1
+        with:
+          path: ${{ steps.suggestions-dir.outputs.path }}
+          merge-multiple: true
 
       - name: 'Run Danger'
         env:

.github/workflows/format-and-commit.yml

@@ -31,7 +31,7 @@ jobs:
         id: date
         run: echo "date=$(/bin/date -u "+%Y-%m-%d")" >> $GITHUB_OUTPUT
 
-      - uses: actions/cache@704facf57e6136b1bc63b828d79edcd491f0ee84 # v3.3.2
+      - uses: actions/cache@13aacd865c20de90d75de3b17ebe84f7a17d57d2 # v4.0.0
         with:
           # dprint caches info about the files in the repo to skip formatting them.
           # However, since package.json and .dprint.jsonc don't change very often,

.github/workflows/ghostbuster.yml

@@ -34,7 +34,7 @@ jobs:
           run_install: |
             - args: [--filter, ., --filter, '{./scripts}...']
 
-      - run: node ./scripts/ghostbuster.js
+      - run: node ./scripts/ghostbuster.js > ${{ runner.temp }}/comment.md
         env:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN_API_READ }}
 
@@ -51,7 +51,7 @@ jobs:
           fi
 
       - if: ${{ inputs.skipPR != 'true' }}
-        uses: peter-evans/create-pull-request@153407881ec5c347639a548ade7d8ad1d6740e38 # v5.0.2
+        uses: peter-evans/create-pull-request@b1ddad2c994a25fbc81a28b3ec0e368bb2021c50 # v6.0.0
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: 'Remove contributors with deleted accounts #no-publishing-comment'
@@ -61,7 +61,4 @@ jobs:
           branch-suffix: short-commit-hash
           delete-branch: true
           title: Remove contributors with deleted accounts
-          body: |
-            Generated from [.github/workflows/ghostbuster.yml](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/.github/workflows/ghostbuster.yml)
-
-            Some of these users may have simply changed their usernames; you may want do a bit of searching and ping them to see if they still want to be owners.
+          body-path: ${{ runner.temp }}/comment.md

.github/workflows/pnpm-cache.yml

@@ -26,7 +26,7 @@ jobs:
         run: pnpm install
 
       - name: Save pnpm cache
-        uses: actions/cache/save@704facf57e6136b1bc63b828d79edcd491f0ee84 # v3.3.2
+        uses: actions/cache/save@13aacd865c20de90d75de3b17ebe84f7a17d57d2 # v4.0.0
         with:
           path: ${{ steps.pnpm-cache.outputs.store }}
           key: ${{ runner.os }}-pnpm-store-cache-${{ steps.pnpm-cache.outputs.date }}

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm lint-staged --config .lintstagedrc.json --allow-empty

.lintstagedrc.json

@@ -0,0 +1 @@
+{ "*": "pnpm dprint fmt --allow-no-files" }

README.md

@@ -17,8 +17,10 @@ At the very least, you may want to `git clean -fdx` the repo (or `node ./scripts
 This section tracks the health of the repository and publishing process.
 It may be helpful for contributors experiencing any issues with their PRs and packages.
 
-* Most recent build [type-checked/linted](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) cleanly: [![Build Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.DefinitelyTyped?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=1&branchName=master)
-* All packages are type-checking/linting cleanly on typescript@next: [![Build status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/Nightly%20dtslint)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=8)
+* Most recent build [type-checked/linted](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) cleanly: [![Build status](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml/badge.svg?branch=master&event=push)
+](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml?query=branch%3Amaster+event%3Apush)
+* All packages are type-checking/linting cleanly on typescript@next: [![Build status](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml/badge.svg?branch=master&event=schedule)
+](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml?query=branch%3Amaster+event%3Aschedule)
 * All packages are being [published to npm](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) in under an hour and a half: [![Publish Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.types-publisher-watchdog?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=5&branchName=master)
 * [typescript-bot](https://github.com/typescript-bot) has been active on Definitely Typed [![Activity Status](https://dev.azure.com/definitelytyped/DefinitelyTyped/_apis/build/status/DefinitelyTyped.typescript-bot-watchdog?branchName=master)](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=6&branchName=master)
 * Current [infrastructure status updates](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/44317)
@@ -149,14 +151,13 @@ We use a bot to let a large number of pull requests to DefinitelyTyped be handle
 
 You can clone the entire repository [as per usual](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository), but it's large and includes a massive directory of type packages. This will take some time to clone and may be unnecessarily unwieldy.
 
-For a more manageable clone that includes _only_ the type packages relevant to you, you can use git's [`sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout), [`--filter`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt) and [`--depth`](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) features. This will reduce clone time and improve git performance.
+For a more manageable clone that includes _only_ the type packages relevant to you, you can use git's [`sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout) and [`--filter`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt) features. This will reduce clone time and improve git performance.
 
 >:warning: This requires minimum [git version 2.27.0](https://git-scm.com/downloads), which is likely newer than the default on most machines. More complicated procedures are available in older versions, but not covered by this guide.
 
-1. `git clone --sparse --filter=blob:none --depth=1 <forkedUrl>`
+1. `git clone --sparse --filter=blob:none <forkedUrl>`
     - `--sparse` initializes the sparse-checkout file so the working directory starts with only the files in the root of the repository.
-    - `--filter=blob:none` will exclude files, fetching them only as needed.
-    - `--depth=1` will further improve clone speed by truncating commit history, but it may cause issues as summarized [here](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).
+    - `--filter=blob:none` will including all commit history but exclude files, fetching them only as needed.
 2. `git sparse-checkout add types/<type> types/<dependency-type> ...`
 
 </details>
@@ -219,14 +220,99 @@ This script uses [dtslint](https://github.com/microsoft/DefinitelyTyped-tools/tr
 
 Once you have all your changes ready, use `pnpm run test-all` to see how your changes affect other modules.
 
+##### @arethetypeswrong/cli (`attw`) checks
+
+dtslint includes module format and `package.json` configuration checks from [@arethetypeswrong/cli](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli). The checks run only if a SemVer-major-compatible implementation package can be found on npm to compare against the DefinitelyTyped package. (DefinitelyTyped packages marked as `"nonNpm": true` in their `package.json` are skipped.)
+
+Many packages currently fail the `attw` checks and need to be fixed. To allow us to make incremental progress, failed `attw` checks do not fail the `dtslint` run when the package is listed in `failingPackages` in [`attw.json`](./attw.json), but they will still be reported in the `pnpm test my-package` output. If you fix the package, remove it from `failingPackages` so that `attw` checks can start failing `dtslint` runs.
+
+All problems reported by `attw` have documentation linked in the output. Some rules of thumb to help avoid problems:
+
+- The `package.json` in the DefinitelyTyped package must have matching `type` and `exports` fields if the implementation package uses them in its `package.json`. For example, if an implementation `package.json` looks like:
+
+  ```json
+  {
+      "name": "my-package",
+      "version": "1.0.1",
+      "type": "module",
+      "main": "dist/cjs/index.cjs",
+      "exports": {
+          ".": {
+              "import": "./dist/esm/index.js",
+              "require": "./dist/cjs/index.cjs"
+          },
+          "./subpath": {
+              "import": "./dist/esm/subpath.js",
+              "require": "./dist/cjs/subpath.cjs"
+          }
+      }
+  }
+  ```
+
+  then the DefinitelyTyped `package.json` should look something like:
+
+  ```json5
+  {
+      "name": "@types/my-package",
+      "version": "1.0.9999",
+      "type": "module",
+      "types": "index.d.ts",
+      "exports": {
+          ".": {
+              "import": "./index.d.ts",
+              "require": "./index.d.cts"
+          },
+          "./subpath": {
+              "import": "./subpath.d.ts",
+               "require": "./subpath.d.cts"
+          }
+      }
+  }
+  ```
+
+  Notice that each `exports` subpath is reflected, and each JavaScript file has a corresponding declaration file with a matching file extension—a `.d.ts` file types a `.js` file, not a `.mjs` or `.cjs` file!
+
+- When the implementation package uses `module.exports = ...`, the DefinitelyTyped package should use `export =`, not `export default`. (Alternatively, if the `module.exports` is just an object of named properties, the DefinitelyTyped package can use a series of named exports.) The most common obstacle to correcting this problem is confusion about how to export types in addition to the primary export. For example, assume these types are incorrectly using `export default`:
+
+  ```ts
+  export interface Options {
+    // ...
+  }
+  export default function doSomething(options: Options): void;
+  ```
+
+  Changing the `export default` to an `export =` creates an error:
+
+  ```ts
+  export interface Options {
+    // ...
+  }
+  declare function doSomething(options: Options): void;
+  export = doSomething;
+  // ^^^^^^^^^^^^^^^^^
+  // Error: An export assignment cannot be used in a module with other exported elements.
+  ```
+
+  To fix this, move the types inside a namespace with the same name as the function:
+
+  ```ts
+  declare namespace doSomething {
+    export interface Options {
+      // ...
+    }
+  }
+  declare function doSomething(options: doSomething.Options): void;
+  export = doSomething;
+  ```
+
+If you need help fixing a problem, please ask in the DefinitelyTyped channel on the [TypeScript Community Discord server](https://discord.gg/typescript).
+
 #### Naming
 
 If you are adding typings for an npm package, create a directory with the same name.
-If the package you are adding typings for is not on npm, make sure the name you choose for it does not conflict with the name of a package on npm.
+If the package you are adding typings for is not on npm, set `"nonNpm": true` in the `package.json`, and make sure the name you choose for it does not conflict with the name of a package on npm.
 (You can use `npm info <my-package>` to check for the existence of the `<my-package>` package.)
 
-If a non-npm package conflicts with an existing npm package try adding -browser to the end of the name to get `<my-package>-browser`.
-
 #### `<my-package>-tests.ts`
 
 There should be a `<my-package>-tests.ts` file, which is considered your test file, along with any `*.ts` files it imports.
@@ -488,6 +574,8 @@ Then they are wrong and we've not noticed yet. You can help by submitting a pull
 Yes, using [dprint](https://dprint.dev).
 We recommend using a [dprint extension for your editor](https://dprint.dev/install/#editor-extensions).
 
+Alternatively, you can enable a git hook which will format your code automatically. Run `pnpm run setup-hooks`. Then, when you commit, `dprint fmt` command will be executed on changed files.  If you take advantage of [partial clone](#partial-clone), make sure to call `git sparse-checkout add .husky` to check out the git hooks before running the `setup-hooks` script.
+
 Pull requests do not require correct formatting to be merged.
 Any unformatted code will be automatically reformatted after being merged.
 
@@ -648,6 +736,13 @@ Another package may select this version by specifying:
 
 Also, `/// <reference types=".." />` will not work with path mapping, so dependencies must use `import`.
 
+#### How do breaking type changes work if type declaration packages closely track the library package's version?
+
+`@types` packages always type packages of the same version, so `@types/foo@5.4.x` are for `foo@5.4.x`.
+As a consequence, all changes, breaking or not, are published as patch revisions, unless paired with a major/minor bump to change the package version being targeted (coincidentally or not).
+
+When it comes to breaking changes, DT maintainers consider the popularity of the package, the upsides of the proposed breaking change, the effort that will be required for users to fix their code, and whether the change could reasonably be delayed until it can be synced with a major bump of the upstream library.
+
 #### How do I write definitions for packages that can be used globally and as a module?
 
 The TypeScript handbook contains excellent [general information about writing definitions](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) and also [this example definition file](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html) which shows how to create a definition using ES6-style module syntax, while also specifying objects made available to the global scope.  This technique is demonstrated practically in the [definition for `big.js`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/big.js/index.d.ts), which is a library that can be loaded globally via script tag on a web page or imported via require or ES6-style imports.