Skip to content

Latest commit

 

History

History
262 lines (171 loc) · 7.77 KB

README.md

File metadata and controls

262 lines (171 loc) · 7.77 KB
Raw

arethetypeswrong/cli

A CLI for arethetypeswrong.github.io.

This project attempts to analyze npm package contents for issues with their TypeScript types, particularly ESM-related module resolution issues. The following kinds of problems can be detected in the node10, node16, and bundler module resolution modes:

Installation

npm i -g @arethetypeswrong/cli

Usage

The attw command acts very similarly to arethetypeswrong.github.io, with some additional features that are useful for command line usage.

The CLI can check an npm packed tarball:

npm pack
attw cool-package-1.0.0.tgz
# or
attw $(npm pack)

or pack one in-place by specifying --pack and a directory:

attw --pack .

or check a package from npm:

attw --from-npm @arethetypeswrong/cli

You can also use attw without installing globally by using npx. Pack one in-place by specifying --pack and a directory:

npx --yes @arethetypeswrong/cli --pack .

or check a package from npm:

npx --yes @arethetypeswrong/cli --from-npm @arethetypeswrong/cli

Configuration

attw supports a JSON config file (by default named .attw.json) which allows you to pre-set the command line arguments. The options are a one-to-one mapping of the command line flags, changed to camelCase, and are all documented in their relevant Options section below.

Options

Help

Show help information and exit.

In the CLI: --help, -h

attw --help

Version

Print the current version of attw and exit.

In the CLI: --version, -v

attw --version

Pack

Specify a directory to run npm pack in (instead of specifying a tarball filename), analyze the resulting tarball, and delete it afterwards.

attw --pack .

From NPM

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

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

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.

The available values are:

  • table, where columns are entrypoints and rows are resolution kinds
  • table-flipped, where columns are resolution kinds and rows are entrypoints
  • ascii, for large tables where the output is clunky
  • auto, which picks whichever of the above best fits the terminal width
  • json outputs the raw JSON data (overriding all other rendering options)

In the CLI: --format, -f

attw --format <format> <file-name>

In the config file, format can be a string value.

Entrypoints

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:

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

Profiles

Profiles select a set of resolution modes to require/ignore. All are evaluated but failures outside of those required are ignored.

The available profiles are:

  • strict - requires all resolutions
  • node16 - ignores node10 resolution failures
  • esm-only - ignores CJS resolution failures

In the CLI: --profile

attw <file-name> --profile <profile>

In the config file, profile can be a string value.

Ignore Rules

Specifies rules/problems to ignore (i.e. not raise an error for).

The available values are:

  • no-resolution
  • untyped-resolution
  • false-cjs
  • false-esm
  • cjs-resolves-to-esm
  • fallback-condition
  • cjs-only-exports-default
  • false-export-default
  • unexpected-module-syntax
  • missing-export-equals
  • internal-resolution-error
  • named-exports

In the CLI: --ignore-rules

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

In the config file, ignoreRules can be an array of strings.

Summary/No Summary

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

In the CLI: --summary/--no-summary

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

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).

In the CLI: --emoji/--no-emoji

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

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).

In the CLI: --color/--no-color

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

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

Quiet

When set, nothing will be printed to STDOUT.

In the CLI: --quiet, -q

attw --quiet <file-name>

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

Config Path

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

In the CLI: --config-path <path>

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

Cannot be set from within the config file itself.