Add CLI Package

packages/cli/README.md

@@ -0,0 +1,175 @@
+# arethetypeswrong/cli
+
+A CLI wrapper for [arethetypeswrong](https://arethetypeswrong.github.io/).
+
+## Installation
+
+**NOTE:** The package has not yet been published to NPM.
+
+```shell
+npm i -g @arethetypeswrong/cli
+```
+
+<!-- Or, using `npx`: -->
+<!---->
+<!-- ```shell -->
+<!-- npx attw -->
+<!-- ``` -->
+
+## Usage
+
+The `attw` command acts very similarly to [the arethetypeswrong website](https://arethetypeswrong.github.io/), with some additional features that are useful for command line usage.
+
+The usage is:
+
+```shell
+attw [options] <file-name>
+```
+
+Where `<file-name>` is a required positional argument - either the path to a local `.tar.gz` file, or the name of an NPM package.
+
+## 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.
+
+Note that the `--config-path` option cannot be set from the config file :upside_down_face:
+
+### Options
+
+#### Help
+
+Show help information and exit.
+
+In the CLI: `--help`, `-h`
+
+```shell
+attw --help
+```
+
+#### Version
+
+Print the current version of `attw` and exit.
+
+In the CLI: `--version`, `-v`
+
+```shell
+attw --version
+```
+
+#### Format
+
+The format to print the output in. Defaults to `table`.
+
+The available values are:
+- `table`
+- `table-flipped`, where the resolution kinds are the table's head, and the entry points label the table's rows
+- `ascii`, for large tables where the output is clunky
+- `raw`, outputs the raw JSON data (overriding all other rendering options)
+
+In the CLI: `--format`, `-F`
+
+```shell
+attw --format <format> <file-name>
+```
+
+In the config file, `format` can be a string value.
+
+#### From NPM
+
+Treat `<file-name>` as the name (and, optionally, version) of a package from the NPM registry.
+
+In the CLI: `--from-npm`, `-f`
+
+```shell
+attw --from-npm <package-name>
+```
+
+In the config file, `fromNpm` can be a boolean value.
+
+#### Ignore Rules
+
+Specifies rules/problems to ignore (i.e. not raise an error for).
+
+The available values are:
+- `wildcard`
+- `no-resolution`
+- `untyped-resolution`
+- `false-cjs`
+- `false-esm`
+- `cjs-resolves-to-esm`
+- `fallback-condition`
+- `cjs-only-exports-default`
+- `false-export-default`
+- `unexpected-esm-syntax`
+- `unexpected-cjs-syntax`
+
+In the CLI: `--ignore-rules`
+
+```shell
+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`
+
+```shell
+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`
+
+```shell
+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`
+
+```shell
+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`
+
+```shell
+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>`
+
+```shell
+attw --config-path <path> <file-name>
+```
+
+Cannot be set from within the config file itself.
+

packages/cli/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@arethetypeswrong/cli",
+  "version": "0.0.1",
+  "description": "A CLI tool for arethetypeswrong.github.io",
+  "author": "Andrew Branch & ej-shafran",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arethetypeswrong/arethetypeswrong.github.io.git",
+    "directory": "packages/cli"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "attw": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "tsc": "tsc",
+    "local:install": "npm install -g .",
+    "local:uninstall": "npm uninstall -g @arethetypeswrong/cli",
+    "build": "npm run local:uninstall && npm run tsc && npm run local:install"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^20.2.5",
+    "@types/node-fetch": "^2.6.4",
+    "typescript": "^5.0.0-dev.20230207"
+  },
+  "dependencies": {
+    "@arethetypeswrong/core": "^0.0.6",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "commander": "^10.0.1"
+  }
+}

packages/cli/src/index.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import * as core from "@arethetypeswrong/core";
+import { Option, program } from "commander";
+import chalk from "chalk";
+import { readFile } from "fs/promises";
+import { FetchError } from "node-fetch";
+import { createRequire } from "module";
+
+import * as render from "./render/index.js";
+import { readConfig } from "./readConfig.js";
+import { problemFlags } from "./problemUtils.js";
+
+const packageJson = createRequire(import.meta.url)("../package.json");
+const version = packageJson.version;
+const coreVersion = packageJson.dependencies["@arethetypeswrong/core"].substring(1);
+const tsVersion = packageJson.devDependencies.typescript.substring(1);
+
+const formats = ["table", "table-flipped", "ascii", "json"] as const;
+
+type Format = (typeof formats)[number];
+
+export interface Opts {
+  fromNpm?: boolean;
+  summary?: boolean;
+  emoji?: boolean;
+  color?: boolean;
+  quiet?: boolean;
+  configPath?: string;
+  ignoreRules?: string[];
+  format: Format;
+}
+
+program
+  .addHelpText("before", `ATTW CLI (v${version})\n`)
+  .addHelpText("after", `\ncore: v${coreVersion}, typescript: v${tsVersion}`)
+  .version(`v${version}`)
+  .name("attw")
+  .description(
+    `${chalk.bold.blue(
+      "Are the Types Wrong?"
+    )} attempts to analyze npm package contents for issues with their TypeScript types,
+particularly ESM-related module resolution issues.`
+  )
+  .argument("<file-name>", "the file to check; by default a path to a .tar.gz file, unless --from-npm is set")
+  .option("-f, --from-npm", "read from the npm registry instead of a local file")
+  .addOption(new Option("-F, --format <format>", "specify the print format").choices(formats).default("table"))
+  .option("-q, --quiet", "don't print anything to STDOUT (overrides all other options)")
+  .addOption(
+    new Option("--ignore-rules <rules...>", "specify rules to ignore").choices(Object.values(problemFlags)).default([])
+  )
+  .option("--summary, --no-summary", "whether to print summary information about the different errors")
+  .option("--emoji, --no-emoji", "whether to use any emojis")
+  .option("--color, --no-color", "whether to use any colors (the FORCE_COLOR env variable is also available)")
+  .option("--config-path <path>", "path to config file (default: ./.attw.json)")
+  .action(async (fileName: string) => {
+    const opts = program.opts<Opts>();
+    await readConfig(program, opts.configPath);
+    opts.ignoreRules = opts.ignoreRules?.map(
+      (value) => Object.keys(problemFlags).find((key) => problemFlags[key as core.ProblemKind] === value) as string
+    );
+
+    if (opts.quiet) {
+      console.log = () => { };
+    }
+
+    if (!opts.color) {
+      process.env.FORCE_COLOR = "0";
+    }
+
+    let analysis: core.Analysis;
+    if (opts.fromNpm) {
+      try {
+        const result = core.parsePackageSpec(fileName);
+        if (result.status === "error") {
+          program.error(result.error);
+        } else {
+          analysis = await core.checkPackage(result.data.packageName, result.data.version);
+        }
+      } catch (error) {
+        if (error instanceof FetchError) {
+          program.error(`error while fetching package:\n${error.message}`, { code: error.code });
+        }
+
+        handleError(error, "checking package");
+      }
+    } else {
+      try {
+        const file = await readFile(fileName);
+        const data = new Uint8Array(file);
+        analysis = await core.checkTgz(data);
+      } catch (error) {
+        handleError(error, "checking file");
+      }
+    }
+
+    if (opts.format === "json") {
+      const result = { analysis } as {
+        analysis: core.Analysis;
+        problems?: Partial<Record<core.ProblemKind, core.Problem[]>>;
+      };
+
+      if (analysis.containsTypes) {
+        result.problems = core.groupByKind(core.getProblems(analysis));
+      }
+
+      console.log(JSON.stringify(result));
+
+      if (
+        analysis.containsTypes &&
+        core.getProblems(analysis).some((problem) => !opts.ignoreRules.includes(problem.kind))
+      )
+        process.exit(1);
+
+      return;
+    }
+
+    console.log();
+    if (analysis.containsTypes) {
+      await render.typed(analysis, opts);
+
+      if (
+        analysis.containsTypes &&
+        core.getProblems(analysis).some((problem) => !opts.ignoreRules.includes(problem.kind))
+      )
+        process.exit(1);
+    } else {
+      render.untyped(analysis as core.UntypedAnalysis);
+    }
+  });
+
+program.parse(process.argv);
+
+function handleError(error: unknown, title: string): never {
+  if (error && typeof error === "object" && "message" in error) {
+    program.error(`error while ${title}:\n${error.message}`, {
+      code: "code" in error && typeof error.code === "string" ? error.code : "UNKNOWN",
+    });
+  }
+
+  program.error(`unknown error while ${title}`, { code: "UNKNOWN" });
+}