### ATTW Configuration File Example

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Provides an example of a `.attw.json` configuration file, showcasing various options for format, profile, ignored rules, entrypoints, and display settings.

```json
{
  "format": "table",
  "profile": "node16",
  "ignoreRules": ["cjs-only-exports-default", "false-esm"],
  "entrypoints": [".", "./utils", "./types"],
  "excludeEntrypoints": ["./internal"],
  "emoji": true,
  "color": true,
  "summary": true
}
```

--------------------------------

### Install and Run ATTW CLI

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Instructions for installing the ATTW CLI globally and running basic checks on npm packages, including version-specific checks and using npx.

```bash
npm i -g @arethetypeswrong/cli
attw --from-npm axios
attw --from-npm axios@1.4.0
attw --from-npm lodash@^4.0.0
npx --yes @arethetypeswrong/cli --from-npm react
```

--------------------------------

### CLI Help and Version

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Commands to display help information or the current version of the installed CLI.

```shell
attw --help
attw --version
```

--------------------------------

### Install arethetypeswrong CLI

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Install the CLI globally using npm to access the attw command.

```shell
npm i -g @arethetypeswrong/cli
```

--------------------------------

### Configure Output Formatting

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Examples for toggling summary, emoji, color, and quiet mode outputs in the CLI.

```shell
attw --summary/--no-summary <file-name>
attw --emoji/--no-emoji <file-name>
attw --color/--no-color <file-name>
attw --quiet <file-name>
```

--------------------------------

### Analyze npm packages with attw

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Examples of how to analyze packages using local tarballs, in-place packing, or directly from the npm registry.

```shell
attw cool-package-1.0.0.tgz
attw --pack .
attw --from-npm @arethetypeswrong/cli
npx --yes @arethetypeswrong/cli --pack .
npx --yes @arethetypeswrong/cli --from-npm @arethetypeswrong/cli
```

--------------------------------

### GET /versions

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/history/README.md

Retrieves a mapping of dates to the list of packages and versions analyzed on those dates.

```APIDOC
## GET /versions

### Description
Retrieves the historical mapping of dates to the packages and versions analyzed.

### Method
GET

### Endpoint
getVersionsByDate()

### Response
#### Success Response (200)
- **data** (Object) - A dictionary where keys are dates (YYYY-MM-DD) and values are arrays of objects containing { packageName, packageVersion }.

#### Response Example
{
  "2023-01-01": [{ "packageName": "lodash", "packageVersion": "4.17.21" }]
}
```

--------------------------------

### Configure DefinitelyTyped and Output Format

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Examples of specifying DefinitelyTyped versions and controlling the output format of the analysis results.

```shell
attw -p <package-name> --definitely-typed <version>
attw -p <package-name> --no-definitely-typed
attw --format <format> <file-name>
```

--------------------------------

### Check Package from npm Registry

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Instructions on how to install the ATTW CLI globally and check packages directly from the npm registry using different version specifiers.

```APIDOC
## Install CLI
```bash
npm i -g @arethetypeswrong/cli
```

### Check Package from npm Registry

This command fetches and analyzes packages directly from the npm registry.

#### Usage

- **Check a package:** `attw --from-npm [package-name]`
- **Check specific version:** `attw --from-npm [package-name]@[version]`
- **Check with version range:** `attw --from-npm [package-name]@[version-range]`

#### Examples

```bash
# Check axios
attw --from-npm axios

# Check specific version of axios
attw --from-npm axios@1.4.0

# Check lodash with version range
attw --from-npm lodash@^4.0.0

# Using npx without installing
npx --yes @arethetypeswrong/cli --from-npm react
```
```

--------------------------------

### Example of Type Declaration File

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md

A standard TypeScript declaration file defining named exports.

```typescript
export declare const a: string;
export declare function b(): number;
```

--------------------------------

### GET /analysis

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/history/README.md

Retrieves the full dataset of type analysis results for all tracked packages.

```APIDOC
## GET /analysis

### Description
Retrieves the complete analysis object containing type compatibility data for all packages indexed by 'packageName@packageVersion'.

### Method
GET

### Endpoint
getAllDataAsObject()

### Response
#### Success Response (200)
- **data** (Object) - A map of package identifiers to their respective analysis results, including detected problems.

#### Response Example
{
  "lodash@4.17.21": {
    "problems": [{ "kind": "FalseESM", "message": "..." }]
  }
}
```

--------------------------------

### Example of problematic package.json exports

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FallbackCondition.md

A configuration demonstrating how nested conditions in package.json 'exports' can trigger the TypeScript resolution bug when a specific type file is missing.

```json
{
  "exports": {
    ".": {
      "types": {
        "foo": "./didnt-match.d.ts"
      },
      "import": {
        "types": "./doesnt-exist.d.ts",
        "default": "./exists.mjs"
      }
    }
  }
}
```

--------------------------------

### CommonJS Compatibility Pattern in JavaScript

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/MissingExportEquals.md

Example of a JavaScript module using a compatibility pattern where the class is assigned to both module.exports and a default property.

```javascript
class Whatever {
  /* ... */
}
Whatever.default = Whatever;
module.exports = Whatever;
```

--------------------------------

### Untyped ESM Package.json Example

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/UntypedResolution.md

Illustrates a common cause of the 'No types' error: a package.json using 'exports' before TypeScript fully supported it, leading to resolution mismatches between Node.js and TypeScript.

```json
{
  "name": "pkg",
  "main": "./index.js",
  "types": "./index.d.ts",
  "exports": {
    "import": "./index.mjs",
    "require": "./index.js"
  }
}
```

--------------------------------

### Common package.json misconfiguration example

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FallbackCondition.md

A common scenario where missing type-specific files (like .d.mts) causes TypeScript to fall back to incorrect type definitions, often leading to masquerading issues.

```json
{
  "name": "pkg",
  "main": "./index.js",
  "types": "./index.d.ts",
  "exports": {
    "import": "./index.mjs",
    "default": "./index.js"
  }
}
```

--------------------------------

### Filter Analysis Problems

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Provides examples of filtering analysis results by specific criteria such as problem kind, entrypoint, or resolution mode using the filterProblems utility.

```typescript
import { createPackageFromNpm, checkPackage } from "@arethetypeswrong/core";
import { filterProblems } from "@arethetypeswrong/core/problems";
import type { Analysis } from "@arethetypeswrong/core";

const pkg = await createPackageFromNpm("axios");
const result = await checkPackage(pkg);

if (!result.types) {
  process.exit(1);
}

const analysis = result as Analysis;

// Filter by problem kind
const falseCjsProblems = filterProblems(analysis, {
  kind: ["FalseCJS"],
});
console.log(`FalseCJS problems: ${falseCjsProblems.length}`);

// Filter by entrypoint
const mainEntryProblems = filterProblems(analysis, {
  entrypoint: ".",
});
console.log(`Main entry problems: ${mainEntryProblems.length}`);

// Filter by resolution kind
const node16CjsProblems = filterProblems(analysis, {
  resolutionKind: "node16-cjs",
});
console.log(`Node16 CJS problems: ${node16CjsProblems.length}`);

// Filter by resolution option (covers both CJS and ESM for node16)
const node16AllProblems = filterProblems(analysis, {
  resolutionOption: "node16",
});
console.log(`All Node16 problems: ${node16AllProblems.length}`);

// Combine filters
const specificProblems = filterProblems(analysis, {
  kind: ["FalseESM", "FalseCJS"],
  entrypoint: ".",
  resolutionKind: "node16-esm",
});
console.log(`Specific problems: ${specificProblems.length}`);

// Alternative: pass problems array directly
const customFiltered = filterProblems(analysis.problems, analysis, {
  kind: ["NoResolution"],
});
```

--------------------------------

### Configure Entrypoint Discovery and Filtering with checkPackage

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Demonstrates how to use the checkPackage function to analyze specific entrypoints. It shows how to include, exclude, or enable legacy discovery modes to fine-tune the analysis process.

```typescript
import { createPackageFromNpm, checkPackage } from "@arethetypeswrong/core";

const pkg = await createPackageFromNpm("vue");

// Check only specific entrypoints
const result1 = await checkPackage(pkg, {
  entrypoints: [".", "./jsx-runtime"],
});

// Add entrypoints to auto-discovered ones
const result2 = await checkPackage(pkg, {
  includeEntrypoints: ["./custom-entry"],
});

// Exclude certain entrypoints
const result3 = await checkPackage(pkg, {
  excludeEntrypoints: ["./macros", /internal/],
});

// Enable legacy entrypoint discovery (all files as entrypoints)
const result4 = await checkPackage(pkg, {
  entrypointsLegacy: true,
});

// Combine options
const result5 = await checkPackage(pkg, {
  includeEntrypoints: ["./extra"],
  excludeEntrypoints: ["./deprecated"],
  entrypointsLegacy: false,
});

if (result5.types) {
  console.log(`Checked ${Object.keys(result5.entrypoints).length} entrypoints`);
}
```

--------------------------------

### Configure Package Entrypoints

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Demonstrates how to define or modify package entrypoints using the --entrypoints, --include-entrypoints, --exclude-entrypoints, and --entrypoints-legacy flags.

```shell
attw --pack . --entrypoints . one two three
attw --pack . --include-entrypoints added
attw --pack . --exclude-entrypoints styles.css
attw --pack . --entrypoints-legacy
```

--------------------------------

### Use ATTW Configuration File

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Shows how to use the default `.attw.json` configuration file or specify a custom path using the `--config-path` flag when running the ATTW CLI.

```bash
attw --pack .
attw --pack . --config-path ./custom-attw-config.json
```

--------------------------------

### Define Configuration File Path

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Shows how to specify a custom path for the configuration file instead of the default .attw.json.

```shell
attw --config-path <path> <file-name>
```

--------------------------------

### Access Problem Metadata with problemKindInfo

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Demonstrates how to retrieve metadata, descriptions, and documentation URLs for specific problem kinds identified during package analysis.

```typescript
import { problemKindInfo, allProblemKinds } from "@arethetypeswrong/core/problems";
import type { ProblemKind } from "@arethetypeswrong/core";

// List all problem kinds
console.log("All problem kinds:", allProblemKinds);

// Get info for a specific problem
const falseCjsInfo = problemKindInfo["FalseCJS"];
console.log(`${falseCjsInfo.emoji} ${falseCjsInfo.title}`);
console.log(falseCjsInfo.description);
console.log(falseCjsInfo.docsUrl);

// Iterate all problem types
for (const kind of allProblemKinds) {
  const info = problemKindInfo[kind];
  console.log(`${info.emoji} ${kind}: ${info.shortDescription}`);
}
```

--------------------------------

### Configure ATTW Entrypoints

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Explains how to specify which entrypoints of a package should be analyzed by ATTW using flags like `--entrypoints`, `--include-entrypoints`, and `--exclude-entrypoints`, including a legacy mode.

```bash
attw --pack . --entrypoints . one two three
attw --pack . --include-entrypoints custom-entry
attw --pack . --exclude-entrypoints styles.css internal
attw --pack . --entrypoints-legacy
```

--------------------------------

### Configuration File

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Use a configuration file (`.attw.json`) to set default options for the ATTW CLI.

```APIDOC
## Configuration File

Create a `.attw.json` file for persistent configuration.

### Example `.attw.json`

```json
{
  "format": "table",
  "profile": "node16",
  "ignoreRules": ["cjs-only-exports-default", "false-esm"],
  "entrypoints": [ ".", "./utils", "./types" ],
  "excludeEntrypoints": [ "./internal" ],
  "emoji": true,
  "color": true,
  "summary": true
}
```

### Usage

- **Use default config file:** `attw --pack .`
- **Use custom config path:** `attw --pack . --config-path ./custom-attw-config.json`
```

--------------------------------

### Check Local Packages with ATTW

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Demonstrates how to use the ATTW CLI to analyze local npm packages, either from a packed tarball or directly from a directory, including an option to automatically pack the directory.

```bash
npm pack
attw my-package-1.0.0.tgz
attw $(npm pack)
attw --pack .
npx --yes @arethetypeswrong/cli --pack .
```

--------------------------------

### visitResolutions

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Iterates over all entrypoint resolutions using a visitor pattern for custom processing.

```APIDOC
## visitResolutions

### Description
Traverse all entrypoint resolutions and execute a callback function for each.

### Parameters
#### Request Body
- **entrypoints** (Object) - Required - The entrypoints object from a package analysis.
- **visitor** (Function) - Required - Callback function receiving (resolution, entrypoint).

### Response
- Executes the provided visitor function for every resolution found in the analysis.
```

--------------------------------

### Entrypoint Configuration

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Configure which package entrypoints are analyzed using `--entrypoints`, `--include-entrypoints`, and `--exclude-entrypoints`.

```APIDOC
## Entrypoint Configuration

Control which package entrypoints are analyzed.

### Options

- `--entrypoints [entrypoint1] [entrypoint2] ...`: Analyze only the specified entrypoints.
- `--include-entrypoints [entrypoint]`: Add specified entrypoints to the auto-discovered ones.
- `--exclude-entrypoints [entrypoint]`: Exclude specified entrypoints from analysis.
- `--entrypoints-legacy`: Enable legacy mode where all files are treated as entrypoints for packages without explicit `exports`.

### Examples

```bash
# Check only specific entrypoints
attw --pack . --entrypoints . one two three

# Add custom entrypoints to auto-discovered ones
attw --pack . --include-entrypoints custom-entry

# Exclude specific entrypoints
attw --pack . --exclude-entrypoints styles.css internal

# Enable legacy mode
attw --pack . --entrypoints-legacy
```
```

--------------------------------

### CLI: Show Version Information

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Displays the version information for the Are The Types Wrong CLI, core, and TypeScript.

```bash
attw --version
```

--------------------------------

### Visit entrypoint resolutions

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Uses a visitor pattern to iterate over all entrypoint resolutions. Useful for inspecting resolution status, file paths, and associated problems.

```typescript
import { createPackageFromNpm, checkPackage } from "@arethetypeswrong/core";
import { visitResolutions } from "@arethetypeswrong/core/utils";
import type { Analysis } from "@arethetypeswrong/core";

const pkg = await createPackageFromNpm("vue");
const result = await checkPackage(pkg);

if (!result.types) {
  process.exit(1);
}

const analysis = result as Analysis;

visitResolutions(analysis.entrypoints, (resolution, entrypoint) => {
  console.log(`${entrypoint.subpath} [${resolution.resolutionKind}]`);
  if (resolution.resolution) {
    console.log(`  -> ${resolution.resolution.fileName}`);
  }
});
```

--------------------------------

### createPackageFromNpm

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Fetches a package from the npm registry and returns a Package object for analysis.

```APIDOC
## POST /createPackageFromNpm

### Description
Fetches a package from the npm registry and returns a Package object for analysis.

### Method
POST

### Parameters
#### Request Body
- **packageName** (string) - Required - The name of the package to fetch (e.g., 'axios' or 'lodash@4.17.21')
- **options** (object) - Optional - Configuration for fetching types:
  - **definitelyTyped** (boolean|string) - Optional - Include @types package (default: true)
  - **before** (Date) - Optional - Fetch package state before a certain date
  - **allowDeprecated** (boolean) - Optional - Allow fetching deprecated versions

### Request Example
{
  "packageName": "lodash",
  "options": {
    "definitelyTyped": true
  }
}

### Response
#### Success Response (200)
- **pkg** (object) - A Package object containing package metadata and file access methods.

#### Response Example
{
  "packageName": "lodash",
  "packageVersion": "4.17.21"
}
```

--------------------------------

### Entrypoints Configuration

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Control how package entrypoints are discovered and processed by the attw CLI. Options include automatic discovery, legacy mode, explicit definition, inclusion, and exclusion of specific entrypoints.

```APIDOC
## Entrypoints Configuration

`attw` automatically discovers package entrypoints by looking at package.json `exports` and subdirectories with additional package.json files. In a package lacking `exports`, providing the `--entrypoints-legacy` option will include all published code files. This automatic discovery process can be overridden with the `--entrypoints` option, or altered with the `--include-entrypoints` and `--exclude-entrypoints` options:

### CLI Examples

```shell
attw --pack . --entrypoints . one two three    # Just ".", "./one", "./two", "./three"
attw --pack . --include-entrypoints added      # Auto-discovered entrypoints plus "./added"
attw --pack . --exclude-entrypoints styles.css # Auto-discovered entrypoints except "./styles.css"
attw --pack . --entrypoints-legacy             # All published code files
```

### Configuration File

In the config file, `entrypoints`, `includeEntrypoints`, `excludeEntrypoints`, and `entrypointsLegacy` can be set.
```

--------------------------------

### Configure ATTW Output Formats

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Shows how to control the output format of the ATTW analysis results using the `--format` flag, with options for table, ASCII, JSON, and auto-detection.

```bash
attw --from-npm axios --format table
attw --from-npm axios --format table-flipped
attw --from-npm vue --format ascii
attw --from-npm lodash --format auto
attw --from-npm axios --format json
```

--------------------------------

### Core API: Create Package from NPM

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Fetches a package from the npm registry and returns a Package object for analysis. Supports fetching specific versions, version ranges, and controlling @types package inclusion and versions. It can also filter packages published before a certain date and allow deprecated versions.

```typescript
import { createPackageFromNpm, checkPackage } from "@arethetypeswrong/core";

// Fetch latest version
const pkg = await createPackageFromNpm("axios");

// Fetch specific version
const pkgVersioned = await createPackageFromNpm("lodash@4.17.21");

// Fetch with version range
const pkgRange = await createPackageFromNpm("react@^18.0.0");

// Include @types package automatically (default behavior)
const pkgWithTypes = await createPackageFromNpm("lodash", {
  definitelyTyped: true,
});

// Specify @types version explicitly
const pkgWithSpecificTypes = await createPackageFromNpm("lodash", {
  definitelyTyped: "4.14.195",
});

// Disable @types package inclusion
const pkgNoTypes = await createPackageFromNpm("lodash", {
  definitelyTyped: false,
});

// Fetch package from before a certain date
const pkgBefore = await createPackageFromNpm("axios", {
  before: new Date("2023-01-01"),
});

// Allow deprecated versions
const pkgDeprecated = await createPackageFromNpm("axios@0.21.0", {
  allowDeprecated: true,
});

console.log(`Loaded ${pkg.packageName}@${pkg.packageVersion}`);
// Output: Loaded axios@1.4.0
```

--------------------------------

### Check Local Package

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

How to analyze local npm packages from tarballs or directories using the ATTW CLI.

```APIDOC
## Check Local Package

Analyze a local tarball or directory containing a package.

### Usage

- **Check a packed tarball:** `attw [tarball-path]`
- **Pack and check a directory:** `attw --pack .`

### Examples

```bash
# Pack the current directory and check the tarball
npm pack
attw my-package-1.0.0.tgz

# Or in one command
attw $(npm pack)

# Pack and check a directory (will run npm pack automatically)
attw --pack .

# Check current directory with npx
npx --yes @arethetypeswrong/cli --pack .
```
```

--------------------------------

### Set Resolution Profiles

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Shows how to apply specific resolution profiles to the analysis process using the --profile flag.

```shell
attw <file-name> --profile <profile>
```

--------------------------------

### Configure DefinitelyTyped Integration in ATTW

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Explains how ATTW integrates with DefinitelyTyped for untyped packages, including options to auto-infer versions, specify a version, disable integration, or use a local tarball.

```bash
attw --from-npm lodash
attw --from-npm lodash --definitely-typed 4.14.0
attw --from-npm lodash --no-definitely-typed
attw --from-npm big.js --definitely-typed ./types-big.js-6.2.0.tgz
```

--------------------------------

### Configure package.json exports for subpath resolution

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/NoResolution.md

This JSON configuration demonstrates how to define package entry points using the 'exports' field. It highlights potential compatibility issues with older Node.js versions that do not support this field.

```json
{
  "name": "pkg",
  "main": "./dist/index.js",
  "exports": {
    ".": "./dist/index.js",
    "./subpath": "./dist/subpath.js"
  }
}
```

--------------------------------

### Run AreTheTypesWrong on moment@2.29.1.tgz

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/test/snapshots/moment@2.29.1.tgz.md

This command analyzes the moment@2.29.1.tgz package using the AreTheTypesWrong tool. It checks for type compatibility across different Node.js versions (node10, node16 CJS/ESM) and a bundler environment. The output is formatted as a table, and in this case, no problems were found, indicated by green circles and an exit code of 0.

```bash
$ attw moment@2.29.1.tgz -f table-flipped

moment v2.29.1

Build tools:
- typescript@^1.8.10
- rollup@2.17.1

 No problems found 🌟


┌──────────┬────────┬───────────────────┬───────────────────┬─────────┐
│          │ node10 │ node16 (from CJS) │ node16 (from ESM) │ bundler │
├──────────┼────────┼───────────────────┼───────────────────┼─────────┤
│ "moment" │ 🟢     │ 🟢 (CJS)          │ 🟢 (CJS)          │ 🟢      │
└──────────┴────────┴───────────────────┴───────────────────┴─────────┘


Exit code: 0
```

--------------------------------

### CLI: Control Output Formatting

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Demonstrates CLI flags to control the output of Are The Types Wrong, such as disabling emoji, colors, problem summaries, or enabling quiet mode.

```bash
attw --from-npm axios --no-emoji
attw --from-npm axios --no-color
attw --from-npm axios --no-summary
attw --from-npm axios --quiet
```

--------------------------------

### Config Path Configuration

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Specify the path to the configuration file for the attw CLI.

```APIDOC
## Config Path Configuration

The path to the config file. Defaults to `./.attw.json`.

### CLI Usage

```shell
attw --config-path <path> <file-name>
```

### Notes

Cannot be set from within the config file itself.
```

--------------------------------

### Configure ATTW Analysis Profiles

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Details how to use analysis profiles with ATTW to control which resolution modes are required for a successful analysis, such as 'strict', 'node16', and 'esm-only'.

```bash
attw --from-npm axios --profile strict
attw --from-npm axios --profile node16
attw --from-npm axios --profile esm-only
```

--------------------------------

### Package.json Configuration for Dual CJS/ESM Support

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseESM.md

Demonstrates a common package.json structure that leads to the 'Masquerading as ESM' issue, where a single .d.ts file is used for both CJS and ESM exports, causing conflicts. It also shows corrected configurations using separate declaration files for CJS.

```json
{
  "name": "pkg",
  "type": "module",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.js",
      "require": "./index.cjs"
    }
  }
}
```

```json
{
  "name": "pkg",
  "type": "module",
  "exports": {
    ".": {
      "import": {
        "types": "./index.d.ts",
        "default": "./index.js"
      },
      "require": {
        "types": "./index.d.cts",
        "default": "./index.cjs"
      }
    }
  }
}
```

```json
{
  "name": "pkg",
  "type": "module",
  "exports": {
    ".": {
      "import": "./index.js",
      "require": "./index.cjs"
    }
  }
}
```

--------------------------------

### Run ATTW analysis on a package

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/test/snapshots/@fluid-experimental__presence@2.3.0.tgz --profile strict -f table.md

Executes the ATTW CLI tool against a specific package tarball to generate a compatibility report. The command uses strict profiling and outputs a table format to visualize resolution success across environments.

```bash
attw @fluid-experimental__presence@2.3.0.tgz --profile strict -f table
```

--------------------------------

### Output Formatting Options

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Control the output format of the attw CLI, including summary display, emoji usage, colorization, and quiet mode.

```APIDOC
## Output Formatting Options

### Summary/No Summary

Whether to display a summary of what the different errors/problems mean. Defaults to showing the summary (`--summary`).

#### CLI Usage

```shell
attw --summary/--no-summary <file-name>
```

#### Configuration File

In the config file, `summary` can be a boolean value.

### Emoji/No Emoji

Whether to print the information with emojis. Defaults to printing with emojis (`--emoji`).

#### CLI Usage

```shell
attw --emoji/--no-emoji <file-name>
```

#### Configuration File

In the config file, `emoji` can be a boolean value.

### Color/No Color

Whether to print with colors. Defaults to printing with colors (`--color`).

The `FORCE_COLOR` env variable is also available for use (set is to `0` or `1`).

#### CLI Usage

```shell
attw --color/--no-color <file-name>
```

#### Configuration File

In the config file, `color` can be a boolean value.

### Quiet Mode

When set, nothing will be printed to STDOUT.

#### CLI Usage

```shell
attw --quiet <file-name>
```

#### Configuration File

In the config file, `quiet` can be a boolean value.
```

--------------------------------

### Verify package types with attw CLI

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/test/snapshots/@cerbos__core@0.18.1.tgz.md

Executes the 'attw' command against a specific package tarball to check for type definition issues. The output is formatted as a table to display compatibility across Node.js versions and bundlers.

```bash
attw @cerbos__core@0.18.1.tgz -f table-flipped
```

--------------------------------

### Manage resolution modes and options

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Provides utilities to inspect TypeScript module resolution settings and map between resolution options and specific resolution kinds.

```typescript
import { allResolutionOptions, allResolutionKinds, getResolutionOption, getResolutionKinds } from "@arethetypeswrong/core/utils";

console.log(allResolutionOptions);
console.log(allResolutionKinds);

console.log(getResolutionOption("node16-cjs"));
console.log(getResolutionKinds("node16"));
```

--------------------------------

### Merge Implementation Packages with Types

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Shows how to combine an implementation package fetched from npm with a separate set of types loaded from a local tarball using the mergedWithTypes method.

```typescript
import {
  createPackageFromNpm,
  createPackageFromTarballData,
  checkPackage,
} from "@arethetypeswrong/core";
import { readFileSync } from "fs";

// Fetch implementation package without @types
const implPkg = await createPackageFromNpm("lodash", {
  definitelyTyped: false,
});

// Load custom types from local tarball
const typesData = readFileSync("./my-lodash-types-1.0.0.tgz");
const typesPkg = createPackageFromTarballData(new Uint8Array(typesData));

// Merge packages
const mergedPkg = implPkg.mergedWithTypes(typesPkg);

console.log(`Implementation: ${mergedPkg.packageName}@${mergedPkg.packageVersion}`);
console.log(`Types: ${mergedPkg.typesPackage?.packageName}@${mergedPkg.typesPackage?.packageVersion}`);

// Run analysis on merged package
const result = await checkPackage(mergedPkg);
if (result.types?.kind === "@types") {
  console.log(`Using @types from: ${result.types.definitelyTypedUrl}`);
}
```

--------------------------------

### CLI Command Analysis

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Documentation for the primary command-line interface used to analyze packages for type resolution issues.

```APIDOC
## CLI Analysis Commands

### Description
Analyze npm packages for TypeScript resolution issues using local files or registry lookups.

### Usage
`attw [options] [file-name]`

### Options
- **--pack** (string) - Optional - Specify a directory to run `npm pack` in, analyze the resulting tarball, and delete it afterwards.
- **--from-npm** (string) - Optional - Specify the name (and optionally version) of a package from the NPM registry.
- **--definitely-typed** (string) - Optional - Specify the version or SemVer range of the DefinitelyTyped `@types` package to use.
- **--format** (string) - Optional - Output format: `table`, `table-flipped`, `ascii`, `auto`, or `json`. Defaults to `auto`.

### Request Example
`attw --from-npm @arethetypeswrong/cli --format json`

### Response
#### Success Response (0)
- **JSON Output** (object) - Returns the raw analysis data including resolution status, detected problems, and entrypoint information.
```

--------------------------------

### Run arethetypeswrong analysis on node-html-parser

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/test/snapshots/node-html-parser@6.1.5.tgz.md

This command runs the arethetypeswrong tool to analyze the node-html-parser package. It outputs the results in a table-flipped format, indicating compatibility across different Node.js versions and bundlers. The analysis reveals issues with CommonJS default exports.

```bash
$ attw node-html-parser@6.1.5.tgz -f table-flipped
```

--------------------------------

### Ignore Specific ATTW Rules

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Demonstrates how to ignore specific problem types or rules during ATTW analysis to prevent them from causing failures, using the `--ignore-rules` flag with single or multiple rule names.

```bash
attw --from-npm lodash --ignore-rules cjs-only-exports-default
attw --from-npm axios --ignore-rules no-resolution untyped-resolution false-esm
```

--------------------------------

### Demonstrating Named Import Runtime Errors

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/NamedExports.md

Shows how a named import from a CommonJS module results in a SyntaxError at runtime, while a default import remains functional.

```typescript
import { a } from "./api.cjs";
// SyntaxError: Named export 'a' not found.

import api from "./api.cjs";
api.a; // Ok
```

--------------------------------

### Specify Ignore Rules

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli/README.md

Demonstrates how to suppress specific error types or resolution problems from the analysis output using the --ignore-rules flag.

```shell
attw <file-name> --ignore-rules <rules...>
```

--------------------------------

### Querying Historical Type Analysis Data

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/history/README.md

This snippet demonstrates how to import the core functions from @arethetypeswrong/history to retrieve package versions by date and the full analysis dataset. It then shows a helper function to filter these packages for specific type-related problems, such as FalseESM, for a given date.

```typescript
import { getAllDataAsObject, getVersionsByDate } from "@arethetypeswrong/history";

const dates = await getVersionsByDate();
const data = await getAllDataAsObject();

function getPackagesWithFalseCJSProblems(date) {
  const packages = dates[date];
  const result = [];
  for (const { packageName, packageVersion } of packages) {
    const analysis = data[`${packageName}@${packageVersion}`];
    if (analysis?.problems.some((p) => p.kind === "FalseESM")) {
      result.push(analysis);
    }
  }
  return result;
}

const mayFalseESMProblems = getPackagesWithFalseCJSProblems("2023-05-01").length;
const juneFalseESMProblems = getPackagesWithFalseCJSProblems("2023-06-01").length;
console.log({ mayFalseESMProblems, juneFalseESMProblems });
```

--------------------------------

### DefinitelyTyped Integration

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Configure how `@types` packages are included for untyped packages.

```APIDOC
## DefinitelyTyped Integration

Configure how `@types` packages are included for untyped packages.

### Options

- `--definitely-typed [version]`: Specify the version of the `@types` package to use.
- `--no-definitely-typed`: Disable the inclusion of `@types` packages.

### Examples

```bash
# Auto-infer @types version from implementation package (default)
attw --from-npm lodash

# Specify @types version
attw --from-npm lodash --definitely-typed 4.14.0

# Disable @types inclusion
attw --from-npm lodash --no-definitely-typed

# Use local @types tarball
attw --from-npm big.js --definitely-typed ./types-big.js-6.2.0.tgz
```
```

--------------------------------

### Resolution Utilities

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Utilities for managing and querying TypeScript resolution options and kinds.

```APIDOC
## Resolution Utilities

### Description
Provides access to all supported resolution options and mapping between resolution kinds and their base options.

### Methods
- **allResolutionOptions**: Returns list of valid moduleResolution settings.
- **allResolutionKinds**: Returns list of all CJS/ESM resolution variants.
- **getResolutionOption(kind)**: Maps a specific kind to its base option.
- **getResolutionKinds(option)**: Maps an option to its supported kinds.

### Response Example
["node10", "node16", "bundler"]
```

--------------------------------

### Configure package.json for Dual-Module Exports

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md

This snippet demonstrates the incorrect configuration that leads to type resolution errors and the corrected version using separate .d.mts and .d.ts files to ensure TypeScript correctly maps declarations to the appropriate module format.

```json
{
  "name": "pkg",
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}
```

```json
{
  "name": "pkg",
  "exports": {
    ".": {
      "import": {
        "types": "./index.d.mts",
        "default": "./index.mjs"
      },
      "require": {
        "types": "./index.d.ts",
        "default": "./index.js"
      }
    }
  }
}
```

--------------------------------

### groupProblemsByKind

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Groups an array of package analysis problems by their specific kind for easier categorization and reporting.

```APIDOC
## groupProblemsByKind

### Description
Groups problems array by their kind for easier processing.

### Parameters
#### Request Body
- **problems** (Array) - Required - The list of problems returned from the package analysis.

### Response
#### Success Response (200)
- **grouped** (Object) - An object where keys are problem kinds and values are arrays of corresponding problem objects.

### Request Example
{
  "problems": [...] 
}

### Response Example
{
  "kindName": [ { "problemData": "..." } ]
}
```

--------------------------------

### Core API: Create Package from Tarball URL

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Creates a Package object from a remote tarball URL, commonly used for fetching packages directly from the npm registry. After creating the Package object, it can be passed to the `checkPackage` function for analysis.

```typescript
import { createPackageFromTarballUrl, checkPackage } from "@arethetypeswrong/core";

// Fetch from npm registry tarball URL
const pkg = await createPackageFromTarballUrl(
  "https://registry.npmjs.org/axios/-/axios-1.4.0.tgz"
);

console.log(`Loaded ${pkg.packageName}@${pkg.packageVersion}`);
// Output: Loaded axios@1.4.0

// Run analysis
const result = await checkPackage(pkg);
```

--------------------------------

### Correcting Type Definitions for Functions

Source: https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/MissingExportEquals.md

Demonstrates how to use a namespace to export a function and its associated types using export =.

```typescript
declare function Whatever(props: Whatever.WhateverProps): void;
declare namespace Whatever {
  import _default = Whatever;
  export { _default as default };
  export interface WhateverProps {
    /* ... */
  }
}
export = Whatever;
```

--------------------------------

### Analysis Profiles

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Configure analysis profiles to specify which resolution modes must pass for the package to be considered valid.

```APIDOC
## Analysis Profiles

Profiles configure which resolution modes are required to pass.

### Available Profiles

- `strict`: Requires all resolution modes to pass (default).
- `node16`: Ignores `node10` resolution failures.
- `esm-only`: Ignores CommonJS (`cjs`) resolution failures.

### Examples

```bash
# Strict profile (default)
attw --from-npm axios --profile strict

# Node16 profile
attw --from-npm axios --profile node16

# ESM-only profile
attw --from-npm axios --profile esm-only
```
```

--------------------------------

### Core API: Create Package from Tarball Data

Source: https://context7.com/arethetypeswrong/arethetypeswrong.github.io/llms.txt

Creates a Package object from a tarball buffer, typically obtained from `npm pack`. This function allows for local package analysis without publishing. It provides methods to check for type declarations, list files, read specific files, and verify file existence within the package.

```typescript
import { createPackageFromTarballData, checkPackage } from "@arethetypeswrong/core";
import { readFileSync } from "fs";

// Read local tarball
const tarballData = readFileSync("./my-package-1.0.0.tgz");
const pkg = createPackageFromTarballData(new Uint8Array(tarballData));

console.log(`Package: ${pkg.packageName}@${pkg.packageVersion}`);

// Check if package contains TypeScript types
if (pkg.containsTypes()) {
  console.log("Package includes type declarations");
}

// List all files in the package
const files = pkg.listFiles();
console.log("Files:", files);
// Output: ["/node_modules/my-package/index.js", "/node_modules/my-package/index.d.ts", ...]

// Read a specific file
const packageJson = JSON.parse(pkg.readFile(`/node_modules/${pkg.packageName}/package.json`));
console.log("Main entry:", packageJson.main);

// Check if file exists
if (pkg.fileExists(`/node_modules/${pkg.packageName}/dist/index.d.ts`)) {
  console.log("Types file found");
}
```