mirror of
https://github.com/ezolenko/rollup-plugin-typescript2.git
synced 2026-02-01 15:54:21 +00:00
61d78bd2f3
* test: add initial integration test harness
- some additional ts-jest config is needed to parse `index.ts`
- since Rollup isn't used when importing files during testing, we need to enable `esModuleInterop`
- the import of `findCacheDir` was immediately erroring without this (and maybe more, but `esModuleInterop` made the import work)
- add `tsconfig.test.json` for this purpose
- use `ts-jest` JSDoc types to get types for the ts-jest config as well
- add an integration/ dir in the __tests__/ dir for all integration tests
- add a fixtures/ dir in there as well for integration test fixtures
- add a `tsconfig.json` for all fixtures to use
- basically so that rpt2 source code is not `include`d, though also bc this may be good to customize for fixtures
- add a simple fixture with "no-errors" that does an import and a type-only import
- add a simple integration test that just ensures that all files are part of the bundle
- the bundled `index` file and each file's declaration and declaration map
- and no _other_ files!
- for Rollup, need to use paths relative to the root of the whole project
- probably because that is `cwd` when running `jest` from root
- will probably abstract out helpers here in the future as the test suite grows
- 70% coverage of `index.ts` with just this one test!
- update CONTRIBUTING.md now that an integration test exists
* refactor: use `local` func for path resolution
- similar to the unit test suite
- also remove the `.only` that I was using during development
* add comparison test for cache / no cache
- should probably do this for each integration test suite
- refactor: split out a `genBundle` func to DRY things up
- this was bound to happen eventually
- don't think testing other output formats is necessary since we don't have any specific logic for that, so that is just Rollup behavior
- take `input` path and rpt2 options as params
- and add the `tsconfig` as a default
- add a hacky workaround so that Rollup doesn't output a bunch of warnings in the logs
- format: use double quotes for strings consistently (my bad, I normally use single quotes in my own repos)
* refactor: use a temp cacheRoot
- so we can clean it up after testing to ensure consistency
- and so we're not filling up the cache in `node_modules` with testing caches
- also add a comment to one the of the tests
* test: check w/ and w/o declarations + declaration maps
- make sure they don't get output when not asked for
* fix(test): actually test the cache
- `clean: true` also means that no cache is created
- which is a bit confusing naming, but was requested by a few users and implemented in f15cb84dcc99a0bd20f3afce101c0991683010b6
- so have to create the bundle one _more_ time to create the cache
- note that `tscache`'s `getCached` and `isDirty` functions are now actually covered in the coverage report
* fix(ci): increase integration test timeout
- double it bc it was occassionally failing on CI due to timeouts
* test: ensure that JS files are part of bundle too
- ensures that TS understands the JS w/ DTS w/o error
- and that rpt2 filters out JS while Rollup still resolves it on its own (since Rollup understands ESM)
- similar to testing w/ a different plugin (i.e. literally testing an "integration"), but this is native Rollup behavior in this case where it doesn't need a plugin to understand ESM
- also the first test of actual code contents
- reformat the cache test a bit into its own block since we now have ~3 different sets of tests in the suite
* optim(test): don't need to check cache each time
- this doesn't test a new code path and the first test already tests the entire bundle for the fixture, so the other tests just repeat that
* test: add initial error checking integration tests
- refactor: rename `integration/index.spec` -> `integration/no-errors.spec`
- refactor: split `genBundle` func out into a helper file to be used by multiple integration test suites
- simplify the `genBundle` within `no-errors` as such
- create new `errors` fixture just with some simple code that doesn't type-check for now
- add test to check that the exact semantic error pops up
- and it even tests colors 😮 ...though I was confused for some time why the strings weren't matching... 😐
- add test to make sure it doesn't pop up when `check: false` or `abortOnError: false`
- when `abortOnError: false`, detect that a warning is created instead
- due to the new `errors` dir in the fixtures dir, the fixtures `tsconfig` now picks up two dirs
- which changes the `rootDir` etc
- so create two tiny `tsconfig`s in both fixture dirs that just extend that one
- and now tests all run simiarly to before
* fix(ci): increase integration test `errors` timeout
- this too timed out, probably due to the checks that _don't_ error
* optim(test): split non-erroring error tests into a different suite
- so that Jest can parallelize these
- CI was timing out on this, so splitting it out should help as it'll be 10s each
* fix(ci): bump integration test timeout to 15s
- bc it was still timing out in some cases 😕
- this time the `no-errors` suite was timing out, so just increase all around
* fix(test): output a `.js` bundle, not `.ts`
- woooops... was wondering why it was `.ts`; turns out because I wrote the `output.file` setting that way 😅 😅 😅
- also add a missing comment in errors for consistency
- and put code checks _after_ file structure checks, since that's a deeper check
* test: check that `emitDeclarationOnly` works as expected
- should output declaration and declaration map for file
- code + declaration should contain the one-line function
- code _shouldn't_ contain anything from TS files
- since this is plain ESM code, we don't need another plugin to process this
- nice workaround to installing another plugin that I hadn't thought of till now!
* test: add a syntactic error, refactor a bit
- add a file to `errors` with a syntax error in it
- apparently this does throw syntax err, but does not cause `emitSkipped: true`... odd...
- so may need another test for that...
- `abortOnError: false` / `check: false` both cause Rollup to error out instead
- rename `errors/index` -> `errors/semantic` since we have different kinds now
- change the `include` to only take a single file, so that we don't unnecessarily generate declarations or type-check other error files
- refactor(test): rewrite `genBundle` in both files to take a relative path to a file
- simplifies the `emitDeclarationOnly` test as we can now just reuse the local `genBundle` instead of calling `helpers.genBundle` directly
- use the same structure for `errors`'s different files as well
- refactor(test): split `errors.spec` into `tsconfig` errors, semantic errors, and syntactic errors (for now)
- add a slightly hacky workaround to get `fs.remove` to not error
- seems to be a race condition due to the thrown errors and file handles not being closed immediately on throw (seems like they close during garbage collection instead?)
- see linked issue in the comment; workaround is to just give it some more time
- not sure that there is a true fix for this, since an improper close may cause indeterminate behavior
* fix(test): normalize as arguments to `include`
- got a Windows error in CI for the `errors` test suite
79 lines
5.7 KiB
Markdown
79 lines
5.7 KiB
Markdown
# Contributing
|
|
|
|
## Reporting bugs
|
|
|
|
Report any bugs [in the GitHub Issue Tracker](https://github.com/ezolenko/rollup-plugin-typescript2/issues).
|
|
|
|
Please follow the issue template as closely as possible:
|
|
|
|
- Attach your `tsconfig.json`, `package.json` (for versions of dependencies), `rollup.config.js`, and any other pieces of your environment that could influence module resolution, ambient types, and TS compilation.
|
|
|
|
Some additional debugging steps you can take to help diagnose the issue:
|
|
|
|
- Attach plugin output with `verbosity` option set to `3` (this will list all files being transpiled and their imports).
|
|
- If it makes sense, check if running `tsc` directly produces similar results.
|
|
- Check if you get the same problem with `clean` option set to `true` (might indicate a bug in the cache).
|
|
- Check if the problem is reproducible after running `npm prune` to clear any rogue types from `node_modules` (by default TS grabs _all_ ambient types).
|
|
|
|
## Developing
|
|
|
|
Use the [standard GitHub process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model) of forking, making a branch, creating a PR when ready, and fixing any failing checks on the PR.
|
|
|
|
### Linting and Style
|
|
|
|
1. Use an editor that supports [`editorconfig`](https://editorconfig.org/), or match the settings from [`.editorconfig`](./.editorconfig) manually.
|
|
1. Fix all linting problems with `npm run lint`.
|
|
|
|
### Testing
|
|
|
|
1. `npm test` to verify that all tests pass
|
|
1. `npm run test:watch` to run tests in watch mode while developing
|
|
1. `npm run test:coverage` to run tests and output a test coverage report
|
|
|
|
While this repo now has an assortment of unit tests and integration tests, it still needs more integration tests with various scenarios and expected outcomes.
|
|
Test coverage improvements for existing files and untested files is needed as well.
|
|
|
|
### Building and Self-Build
|
|
|
|
One can test changes by doing a self-build; the plugin is part of its own build system.
|
|
|
|
1. make changes
|
|
1. run `npm run build` (uses last released version on npm)
|
|
1. check that you get expected changes in `dist`
|
|
1. run `npm run build-self` (uses fresh local build)
|
|
1. check `dist` for the expected changes
|
|
1. run `npm run build-self` _again_ to make sure plugin built by new version can still build itself
|
|
|
|
If `build-self` breaks at some point, fix the problem and restart from the `build` step (a known good copy).
|
|
|
|
## Learning the codebase
|
|
|
|
If you're looking to learn more about the codebase, either to contribute or just to educate yourself, this section contains an outline as well as tips and useful resources.<br />
|
|
These docs have been written by contributors who have gone through the process of learning the codebase themselves!
|
|
|
|
### General Overview
|
|
|
|
Before starting, make sure you're familiar with the [`README`](README.md) in its entirety, as it describes this plugin's options that make up its API surface.<br />
|
|
It can also be useful to review some issues and have a "goal" in mind (especially if you're looking to contribute), so that you can focus on understanding how a certain part of the codebase works.
|
|
|
|
1. Can read [`get-options-overrides`](src/get-options-overrides.ts) as a quick intro to the codebase that dives a bit deeper into the `compilerOptions` that this plugin forces.
|
|
- The [TSConfig Reference](https://www.typescriptlang.org/tsconfig) can be a helpful resource to understand these options.
|
|
1. Get a _quick_ read-through of [`index`](src/index.ts) (which is actually relatively small), to get a general understanding of this plugin's workflow.
|
|
- Rollup's [Plugin docs](https://rollupjs.org/guide/en/#plugins-overview) are _very_ helpful to reference as you're going through, especially if you're not familiar with the Rollup Plugin API.
|
|
|
|
### Deeper Dive
|
|
|
|
Once you have some understanding of the codebase's main workflow, you can start to dive deeper into pieces that require more domain knowledge.<br />
|
|
A useful resource as you dive deeper are the [unit tests](__tests__/). They're good to look through as you dig into a module to understand how it's used.
|
|
|
|
1. From here, you can start to read more of the modules that integrate with the TypeScript API, such as [`host`](src/host.ts), [`parse-tsconfig`](src/parse-tsconfig.ts), [`check-tsconfig`](src/check-tsconfig.ts), and maybe how TS is imported in [`tsproxy`](src/tsproxy.ts) and [`tslib`](src/tslib.ts)
|
|
- A _very_ useful reference here is the [TypeScript Wiki](https://github.com/microsoft/TypeScript/wiki), which has two main articles that are the basis for most Compiler integrations:
|
|
- [Using the Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
|
|
- [Using the Language Service API](https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API)
|
|
- _NOTE_: These are fairly short and unfortunately leave a lot to be desired... especially when you consider that this plugin is actually one of the simpler integrations out there.
|
|
1. At this point, you may be ready to read the more complicated bits of [`index`](src/index.ts) in detail and see how it interacts with the other modules.
|
|
- The [integration tests](__tests__/integration/) could be useful to review at this point as well.
|
|
1. Once you're pretty familiar with `index`, you can dive into some of the cache code in [`tscache`](src/tscache.ts) and [`rollingcache`](src/rollingcache.ts).
|
|
1. And finally, you can see some of the Rollup logging nuances in [`context`](src/context.ts) and [`rollupcontext`](src/rollupcontext.ts), and then the TS logging nuances in [`print-diagnostics`](src/print-diagnostics.ts), and [`diagnostics-format-host`](src/diagnostics-format-host.ts)
|
|
- While these are necessary to the implementation, they are fairly ancillary to understanding and working with the codebase.
|