Add support for DefinitelyTyped

.changeset/good-glasses-wait.md

@@ -0,0 +1,11 @@
+---
+"@arethetypeswrong/core": minor
+---
+
+Add support for DefinitelyTyped analysis.
+
+- `createPackageFromNpm` now takes an options parameter that can control DefinitelyTyped inclusion.
+- The `Package` type is now a class, with new properties and methods:
+  - `typesPackage` contains the package name and version for the included DefinitelyTyped package, if any.
+  - `mergedWithTypes(typesPackage: Package)` returns a new `Package` instance with all files from both packages and the `typesPackage` instance property metadata filled in.
+- `createPackageFromTarballData` is no longer asynchronous.

.changeset/loud-hairs-relate.md

@@ -0,0 +1,9 @@
+---
+"@arethetypeswrong/cli": minor
+---
+
+Add support for DefinitelyTyped analysis.
+
+- `@types` packages will be fetched by default for implementation packages that do not contain any TypeScript files.
+- `--definitely-typed` can be used to set the version of the `@types` package fetched. By default, the version is inferred from the implementation package version.
+- `--no-definitely-typed` can be used to prevent `@types` package inclusion.

packages/cli/README.md

@@ -75,7 +75,7 @@ attw --pack .
 
 #### From NPM
 
-Specify the name (and, optionally, version range) of a package from the NPM registry instead of a local tarball filename.
+Specify the name (and, optionally, version or SemVer range) of a package from the NPM registry instead of a local tarball filename.
 
 In the CLI: `--from-npm`, `-p`
 
@@ -85,6 +85,17 @@ attw --from-npm <package-name>
 
 In the config file, `fromNpm` can be a boolean value.
 
+#### DefinitelyTyped
+
+When a package does not contain types, specifies the version or SemVer range of the DefinitelyTyped `@types` package to use. Defaults to inferring the best version match from the implementation package version.
+
+In the CLI: `--definitely-typed`, `--no-definitely-typed`
+
+```shell
+attw -p <package-name> --definitely-typed <version>
+attw -p <package-name> --no-definitely-typed
+```
+
 #### Format
 
 The format to print the output in. Defaults to `auto`.

packages/cli/src/index.ts

@@ -25,6 +25,7 @@ type Format = (typeof formats)[number];
 export interface Opts {
   pack?: boolean;
   fromNpm?: boolean;
+  definitelyTyped?: boolean | string;
   summary?: boolean;
   emoji?: boolean;
   color?: boolean;
@@ -55,6 +56,8 @@ particularly ESM-related module resolution issues.`
   )
   .option("-P, --pack", "Run `npm pack` in the specified directory and delete the resulting .tgz file afterwards")
   .option("-p, --from-npm", "Read from the npm registry instead of a local file")
+  .addOption(new Option("--definitely-typed [version]", "Specify the version range of @types to use").default(true))
+  .option("--no-definitely-typed", "Don't include @types")
   .addOption(new Option("-f, --format <format>", "Specify the print format").choices(formats).default("auto"))
   .option("-q, --quiet", "Don't print anything to STDOUT (overrides all other options)")
   .option(
@@ -92,6 +95,13 @@ particularly ESM-related module resolution issues.`
 
     let analysis: core.CheckResult;
     let deleteTgz;
+    const dtIsPath =
+      typeof opts.definitelyTyped === "string" &&
+      (opts.definitelyTyped.includes("/") ||
+        opts.definitelyTyped.includes("\\") ||
+        opts.definitelyTyped.endsWith(".tgz") ||
+        opts.definitelyTyped.endsWith(".tar.gz"));
+
     if (opts.fromNpm) {
       if (opts.pack) {
         program.error("--pack and --from-npm cannot be used together");
@@ -101,14 +111,18 @@ particularly ESM-related module resolution issues.`
         if (result.status === "error") {
           program.error(result.error);
         } else {
-          analysis = await core.checkPackage(
-            await core.createPackageFromNpm(`${result.data.name}@${result.data.version}`),
-            {
-              entrypoints: opts.entrypoints,
-              includeEntrypoints: opts.includeEntrypoints,
-              excludeEntrypoints: opts.excludeEntrypoints,
-            }
-          );
+          const pkg = dtIsPath
+            ? (await core.createPackageFromNpm(`${result.data.name}@${result.data.version}`)).mergedWithTypes(
+                core.createPackageFromTarballData(new Uint8Array(await readFile(opts.definitelyTyped as string)))
+              )
+            : await core.createPackageFromNpm(`${result.data.name}@${result.data.version}`, {
+                definitelyTyped: opts.definitelyTyped,
+              });
+          analysis = await core.checkPackage(pkg, {
+            entrypoints: opts.entrypoints,
+            includeEntrypoints: opts.includeEntrypoints,
+            excludeEntrypoints: opts.excludeEntrypoints,
+          });
         }
       } catch (error) {
         if (error instanceof FetchError) {
@@ -156,7 +170,14 @@ particularly ESM-related module resolution issues.`
         }
         const file = await readFile(fileName);
         const data = new Uint8Array(file);
-        analysis = await core.checkPackage(await core.createPackageFromTarballData(data), {
+        const pkg = dtIsPath
+          ? core
+              .createPackageFromTarballData(data)
+              .mergedWithTypes(
+                core.createPackageFromTarballData(new Uint8Array(await readFile(opts.definitelyTyped as string)))
+              )
+          : core.createPackageFromTarballData(data);
+        analysis = await core.checkPackage(pkg, {
           entrypoints: opts.entrypoints,
           includeEntrypoints: opts.includeEntrypoints,
           excludeEntrypoints: opts.excludeEntrypoints,

packages/cli/src/render/typed.ts

@@ -31,6 +31,12 @@ export async function typed(analysis: core.Analysis, opts: Opts) {
     );
   }
 
+  console.log(`${analysis.packageName} v${analysis.packageVersion}`);
+  if (analysis.types.kind === "@types") {
+    console.log(`${analysis.types.packageName} v${analysis.types.packageVersion}`);
+  }
+  console.log();
+
   if (opts.summary) {
     const defaultSummary = marked(!opts.emoji ? " No problems found" : " No problems found 🌟");
     const summaryTexts = Object.keys(grouped).map((kind) => {

packages/cli/test/snapshots.test.ts

@@ -28,6 +28,15 @@ const tests = [
   ["[email protected]", "--entrypoints . jsx-runtime"],
   ["[email protected]", "--exclude-entrypoints macros -f ascii"],
   ["[email protected]", "--include-entrypoints ./foo -f ascii"],
+
+  [
+    "[email protected]",
+    `--definitely-typed ${new URL("../../../core/test/fixtures/@[email protected]", import.meta.url).pathname}`,
+  ],
+  [
+    "[email protected]",
+    `--definitely-typed ${new URL("../../../core/test/fixtures/@[email protected]", import.meta.url).pathname}`,
+  ],
 ];
 
 const defaultOpts = "-f table-flipped";

packages/cli/test/snapshots/@apollo__client-3.7.16.tgz.md

@@ -4,6 +4,8 @@
 $ attw @apollo__client-3.7.16.tgz -f table-flipped
 
 
+@apollo/client v3.7.16
+
 👺 Import resolved to an ESM type declaration file, but a CommonJS JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseESM.md
 
 ⚠️ A require call resolved to an ESM JavaScript file, which is an error in Node and some bundlers. CommonJS consumers will need to use a dynamic import. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSResolvesToESM.md

packages/cli/test/snapshots/@ice__app@3.2.6.tgz.md

@@ -4,6 +4,8 @@
 $ attw @[email protected] -f table-flipped
 
 
+@ice/app v3.2.6
+
 ⚠️ A require call resolved to an ESM JavaScript file, which is an error in Node and some bundlers. CommonJS consumers will need to use a dynamic import. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSResolvesToESM.md
 
 💀 Import failed to resolve to type declarations or JavaScript files. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/NoResolution.md

packages/cli/test/snapshots/@reduxjs__toolkit@2.0.0-beta.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw @[email protected] -f table-flipped
 
 
+@reduxjs/toolkit v2.0.0-beta.0
+
 🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
 
 🥴 Import found in a type declaration file failed to resolve. Either this indicates that runtime resolution errors will occur, or (more likely) the types misrepresent the contents of the JavaScript files. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/InternalResolutionError.md

packages/cli/test/snapshots/@vitejs__plugin-react@3.1.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw @[email protected] -f table-flipped
 
 
+@vitejs/plugin-react v3.1.0
+
 🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
 
 

packages/cli/test/snapshots/ajv@8.12.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+ajv v8.12.0
+
  No problems found 🌟
 
 

packages/cli/test/snapshots/astring@1.8.6.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+astring v1.8.6
+
 🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
 
 

packages/cli/test/snapshots/axios@1.4.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+axios v1.4.0
+
 ❓ Wildcard subpaths cannot yet be analyzed by this tool. https://github.com/arethetypeswrong/arethetypeswrong.github.io/issues/40
 
 💀 Import failed to resolve to type declarations or JavaScript files. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/NoResolution.md

packages/cli/test/snapshots/big.js@6.2.1.tgz --definitely-typed UsersandrewDeveloperarethetypeswrong.github.iopackagescoretestfixtures@types__big.js@6.2.0.tgz.md

@@ -0,0 +1,33 @@
+# [email protected] --definitely-typed /Users/andrew/Developer/arethetypeswrong.github.io/packages/core/test/fixtures/@[email protected]
+
+```
+$ attw [email protected] --definitely-typed /Users/andrew/Developer/arethetypeswrong.github.io/packages/core/test/fixtures/@[email protected]
+
+
+big.js v6.2.1
+@types/big.js v6.2.0
+
+🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
+
+❌ Import resolved to JavaScript files, but no type declarations were found. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/UntypedResolution.md
+
+⚠️ A require call resolved to an ESM JavaScript file, which is an error in Node and some bundlers. CommonJS consumers will need to use a dynamic import. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSResolvesToESM.md
+
+
+┌───────────────────┬────────────────────────┬──────────────────────────────┬─────────────────┬───────────────────────┐
+│                   │ "big.js"               │ "big.js/big.mjs"             │ "big.js/big.js" │ "big.js/package.json" │
+├───────────────────┼────────────────────────┼──────────────────────────────┼─────────────────┼───────────────────────┤
+│ node10            │ 🟢                     │ ❌ No types                  │ ❌ No types     │ 🟢 (JSON)             │
+├───────────────────┼────────────────────────┼──────────────────────────────┼─────────────────┼───────────────────────┤
+│ node16 (from CJS) │ 🟢 (CJS)               │ ❌ No types                  │ ❌ No types     │ 🟢 (JSON)             │
+│                   │                        │ ⚠️ ESM (dynamic import only) │                 │                       │
+├───────────────────┼────────────────────────┼──────────────────────────────┼─────────────────┼───────────────────────┤
+│ node16 (from ESM) │ 🎭 Masquerading as CJS │ ❌ No types                  │ ❌ No types     │ 🟢 (JSON)             │
+├───────────────────┼────────────────────────┼──────────────────────────────┼─────────────────┼───────────────────────┤
+│ bundler           │ 🟢                     │ ❌ No types                  │ ❌ No types     │ 🟢 (JSON)             │
+└───────────────────┴────────────────────────┴──────────────────────────────┴─────────────────┴───────────────────────┘
+
+
+```
+
+Exit code: 1

packages/cli/test/snapshots/commander@10.0.1.tgz -f table.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table
 
 
+commander v10.0.1
+
 🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
 
 ❌ Import resolved to JavaScript files, but no type declarations were found. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/UntypedResolution.md

packages/cli/test/snapshots/hexoid@1.0.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+hexoid v1.0.0
+
 ❗️ The resolved types use export default where the JavaScript file appears to use module.exports =. This will cause TypeScript under the node16 module mode to think an extra .default property access is required, but that will likely fail at runtime. These types should use export = instead of export default. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseExportDefault.md
 
 

packages/cli/test/snapshots/klona@2.0.6.tgz -f ascii.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f ascii
 
 
+klona v2.0.6
+
 🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
 
 

packages/cli/test/snapshots/node-html-parser@6.1.5.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+node-html-parser v6.1.5
+
 🤨 CommonJS module simulates a default export with exports.default and exports.__esModule, but does not also set module.exports for compatibility with Node. Node, and some bundlers under certain conditions (https://andrewbranch.github.io/interop-test/#synthesizing-default-exports-for-cjs-modules), do not respect the __esModule marker, so accessing the intended default export will require a .default property access on the default import. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSOnlyExportsDefault.md
 
 

packages/cli/test/snapshots/postcss@8.4.21.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+postcss v8.4.21
+
 🎭 Import resolved to a CommonJS type declaration file, but an ESM JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md
 
 🐛 Import resolved to types through a conditional package.json export, but only after failing to resolve through an earlier condition. This behavior is a TypeScript bug (https://github.com/microsoft/TypeScript/issues/50762). It may misrepresent the runtime behavior of this import and should not be relied upon. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FallbackCondition.md

packages/cli/test/snapshots/react-chartjs-2@5.2.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+react-chartjs-2 v5.2.0
+
 👺 Import resolved to an ESM type declaration file, but a CommonJS JavaScript file. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseESM.md
 
 ⚠️ A require call resolved to an ESM JavaScript file, which is an error in Node and some bundlers. CommonJS consumers will need to use a dynamic import. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSResolvesToESM.md

packages/cli/test/snapshots/react@18.2.0.tgz --definitely-typed UsersandrewDeveloperarethetypeswrong.github.iopackagescoretestfixtures@types__react@18.2.21.tgz.md

@@ -0,0 +1,32 @@
+# [email protected] --definitely-typed /Users/andrew/Developer/arethetypeswrong.github.io/packages/core/test/fixtures/@[email protected]
+
+```
+$ attw [email protected] --definitely-typed /Users/andrew/Developer/arethetypeswrong.github.io/packages/core/test/fixtures/@[email protected]
+
+
+react v18.2.0
+@types/react v18.2.21
+
+ No problems found 🌟
+
+
+┌─────────────────────────┬───────────┬───────────────────┬───────────────────┬───────────┐
+│                         │ node10    │ node16 (from CJS) │ node16 (from ESM) │ bundler   │
+├─────────────────────────┼───────────┼───────────────────┼───────────────────┼───────────┤
+│ "react"                 │ 🟢        │ 🟢 (CJS)          │ 🟢 (CJS)          │ 🟢        │
+├─────────────────────────┼───────────┼───────────────────┼───────────────────┼───────────┤
+│ "react/package.json"    │ 🟢 (JSON) │ 🟢 (JSON)         │ 🟢 (JSON)         │ 🟢 (JSON) │
+├─────────────────────────┼───────────┼───────────────────┼───────────────────┼───────────┤
+│ "react/jsx-runtime"     │ 🟢        │ 🟢 (CJS)          │ 🟢 (CJS)          │ 🟢        │
+├─────────────────────────┼───────────┼───────────────────┼───────────────────┼───────────┤
+│ "react/jsx-dev-runtime" │ 🟢        │ 🟢 (CJS)          │ 🟢 (CJS)          │ 🟢        │
+├─────────────────────────┼───────────┼───────────────────┼───────────────────┼───────────┤
+│ "react/canary"          │ 🟢        │ 🟢 (CJS)          │ 🟢 (CJS)          │ 🟢        │
+├─────────────────────────┼───────────┼───────────────────┼───────────────────┼───────────┤
+│ "react/experimental"    │ 🟢        │ 🟢 (CJS)          │ 🟢 (CJS)          │ 🟢        │
+└─────────────────────────┴───────────┴───────────────────┴───────────────────┴───────────┘
+
+
+```
+
+Exit code: 0

packages/cli/test/snapshots/rfdc@1.3.0.tgz.md

@@ -4,6 +4,8 @@
 $ attw [email protected] -f table-flipped
 
 
+rfdc v1.3.0
+
 ❌ Import resolved to JavaScript files, but no type declarations were found. https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/UntypedResolution.md