Development

After forking the repo from GitHub and installing pnpm:

git clone https://github.com/<your-name-here>/TypeStat
cd TypeStat
pnpm

This repository includes a list of suggested VS Code extensions. It's a good idea to use VS Code and accept its suggestion to install them, as they'll help with development.

Building

Run tsup locally to build source files from src/ into output files in lib/:

pnpm build

Add --watch to run the builder in a watch mode that continuously cleans and recreates lib/ as you save files:

pnpm build --watch

Once built, you can run TypeStat locally with node bin/typestat.mjs.

Formatting

Prettier is used to format code. It should be applied automatically when you save files in VS Code or make a Git commit.

To manually reformat all files, you can run:

pnpm format --write

Linting

ESLint is used with with typescript-eslint) to lint JavaScript and TypeScript source files. You can run it locally on the command-line:

pnpm run lint

ESLint can be run with --fix to auto-fix some lint rule complaints:

pnpm run lint --fix

Note that you'll likely need to run pnpm build before pnpm lint so that lint rules which check the file system can pick up on any built files.

Testing

There are two kinds of tests:

• Unit tests
• Mutation tests

Unit Tests

Vitest is used for tests. You can run it locally on the command-line:

pnpm run test

Add the --coverage flag to compute test coverage and place reports in the coverage/ directory:

pnpm run test --coverage

Note that console-fail-test is enabled for all test runs. Calls to console.log, console.warn, and other console methods will cause a test to fail.

Debugging Unit Tests

This repository includes a VS Code launch configuration for debugging unit tests. To launch it, open a test file, then run Debug Current Test File from the VS Code Debug panel (or press F5).

Mutation Tests

Most TypeStat tests run TypeStat on checked-in files and are use snapshot testing for output. These tests are located under test/cases.

Vitest is also used for these tests. To accept new snapshots, you can use Vitest's snapshot updates:

pnpm run test:mutation --update

Debugging Mutation Tests

VS Code tasks to debug test files is shipped that allows directly placing breakpoints in source TypeScript code.

• Accept Current Mutation Test runs with -u/--update on the test folder of a currently opened test file, such as an original.ts or typestat.json to update its snapshot.
• Debug Current Test File does not run with -u/--update, and thus treats any differences as test failures.

Performance Debugging Tips

You can use the debugger in Chrome to debug TypeStat on the CLI. Run it with node --inspect then visit chrome://inspect to use the browser debugger.

For example:

node --inspect typestat --config typestat.json

Type Checking

You should be able to see suggestions from TypeScript in your editor for all open files.

However, it can be useful to run the TypeScript command-line (tsc) to type check all files in src/:

pnpm tsc

Add --watch to keep the type checker running in a watch mode that updates the display as you save files:

pnpm tsc --watch