@samchon/ts-patch 3.2.2-dev.20241204

package/CHANGELOG.md

@@ -0,0 +1,268 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### [3.2.1](https://github.com/nonara/ts-patch/compare/v3.2.0...v3.2.1) (2024-06-26)
+
+
+### Bug Fixes
+
+* Added TS 5.5.2 support ([31eb80f](https://github.com/nonara/ts-patch/commit/31eb80f1dcca45d15917e4b6621769f80e57ebe1))
+
+## [3.2.0](https://github.com/nonara/ts-patch/compare/v3.1.2...v3.2.0) (2024-06-03)
+
+
+### Features
+
+* Added support for TS 5.5 ([2c4954d](https://github.com/nonara/ts-patch/commit/2c4954d91def5f0654804bfbf64704720f605840))
+
+### [3.1.2](https://github.com/nonara/ts-patch/compare/v3.1.1...v3.1.2) (2024-01-10)
+
+
+### Bug Fixes
+
+* don't break if other plugin is added ([f2b591e](https://github.com/nonara/ts-patch/commit/f2b591e1a78636d009af048689f2ae1c0bb89bea))
+
+### [3.1.1](https://github.com/nonara/ts-patch/compare/v3.1.0...v3.1.1) (2023-12-06)
+
+
+### Bug Fixes
+
+* parseAllJsDoc breaking with < ts 5.3 ([d21e02e](https://github.com/nonara/ts-patch/commit/d21e02ef6401f04301972f8f107799b8c287275b))
+
+## [3.1.0](https://github.com/nonara/ts-patch/compare/v3.0.2...v3.1.0) (2023-12-05)
+
+
+### Features
+
+* Added Plugin Package Configuration + parseAllJsDoc (closes [#134](https://github.com/nonara/ts-patch/issues/134) closes [#133](https://github.com/nonara/ts-patch/issues/133)) ([15570d0](https://github.com/nonara/ts-patch/commit/15570d05e422dd02635eb3c63dc6b3a036cb543a))
+* Added support for chaining transformers in single factory (closes [#122](https://github.com/nonara/ts-patch/issues/122) closes [#120](https://github.com/nonara/ts-patch/issues/120)) ([aabf389](https://github.com/nonara/ts-patch/commit/aabf3894a610047fade6d2d9fb9949f17afe09df))
+
+
+### Bug Fixes
+
+* TsExtras 'ts' type registering as 'any' (fixes [#127](https://github.com/nonara/ts-patch/issues/127)) ([069411e](https://github.com/nonara/ts-patch/commit/069411e49819aa87c880c7c5ff2ab04ecb68eea3))
+* tsp.currentLibrary was not set (detail) ([24d8031](https://github.com/nonara/ts-patch/commit/24d8031bafcd6483fa762ed9ad8437c4a4070093))
+
+### [3.0.2](https://github.com/nonara/ts-patch/compare/v3.0.1...v3.0.2) (2023-07-20)
+
+
+### Bug Fixes
+
+* Plugins returning TransformerBasePlugin not supported (fixes [#113](https://github.com/nonara/ts-patch/issues/113)) ([12ee3a2](https://github.com/nonara/ts-patch/commit/12ee3a23b9afebb6a42c046b33f257a2bde2467c))
+
+### [3.0.1](https://github.com/nonara/ts-patch/compare/v3.0.0...v3.0.1) (2023-06-22)
+
+
+### Bug Fixes
+
+* Added explicit error if ts is patched and cached backup is removed ([ac25743](https://github.com/nonara/ts-patch/commit/ac25743140f8f3954aceb8c0e43a731eeeab03a1))
+* ESM temp files not cleaned up ([8802054](https://github.com/nonara/ts-patch/commit/8802054481a9f2b4847001cb227db029e0475a72))
+* Lock file deletion check ([#102](https://github.com/nonara/ts-patch/issues/102)) ([cacf908](https://github.com/nonara/ts-patch/commit/cacf9084fd4e5a2a1263103f8dc52d2dd7062402))
+
+## [3.0.0](https://github.com/nonara/ts-patch/compare/v2.1.0...v3.0.0) (2023-06-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rewrote for new major v3 (see detail) ([cd69c1c](https://github.com/nonara/ts-patch/commit/cd69c1c02b2e4674731178def7d217d5699bde25)), closes [#58](https://github.com/nonara/ts-patch/issues/58) [#75](https://github.com/nonara/ts-patch/issues/75) [#83](https://github.com/nonara/ts-patch/issues/83) [#93](https://github.com/nonara/ts-patch/issues/93) [#85](https://github.com/nonara/ts-patch/issues/85)
+
+### Features
+
+* Added Live Compiler (on-the-fly, in-memory patching), which allows ttypescript migration
+* Added experimental ES Module support (closes #58)
+* Added mutex locks (closes #75)
+* Updated to support TS v5+ (closes #83 closes #93)
+* Added caching
+
+### Bug Fixes
+
+* Fixed patching for non-standard libraries (cannot guarantee they will work as expected in IDEs) (closes #85)
+
+## [2.1.0](https://github.com/nonara/ts-patch/compare/v2.0.2...v2.1.0) (2022-12-08)
+
+
+### Features
+
+* Updated to support TS 4.9 ([26f6099](https://github.com/nonara/ts-patch/commit/26f6099543d258a2a430f8344b482aba85ac9b0e))
+
+### [2.0.2](https://github.com/nonara/ts-patch/compare/v2.0.1...v2.0.2) (2022-08-10)
+
+
+### Changes
+
+* Upgraded dependencies ([a878131](https://github.com/nonara/ts-patch/commit/a87813190eb31b918574509e4dfe4ef3b427b212))
+
+### [2.0.1](https://github.com/nonara/ts-patch/compare/v1.4.5...v2.0.1) (2021-11-01)
+
+### Bug Fixes
+
+* Corrected path error in previous release ([7c56d56](https://github.com/nonara/ts-patch/commit/7c56d56b5165affb9c58a3c65c2753391f3e967a))
+
+## [2.0.0](https://github.com/nonara/ts-patch/compare/v1.4.5...v2.0.0) (2021-11-01)
+
+
+### Summary
+
+This is not the planned rewrite, but the codebase was in desperate need of an update. The patch build system with rollup was failing with newer versions and was hacky under the best of circumstances, anyway. This new version has a proper custom build system that produces a much leaner patch. Additionally, I reorganized the codebase, improved tests, and dropped old TS support.
+
+_Note: If you absolutely need it, it will still work with older TS. Simply fork and remove the version check_
+
+### Changes
+
+- Soft deprecated `--basedir` (use `--dir`)
+- Zero bundled dependencies in patch (much lighter)
+- ⚠️ Hard deprecated `--persist` option (use `package.json` -> `prepare` script)
+- ⚠️ Requires TS >= 4.0
+
+_(⚠️ denotes potential "breaking" change)_
+
+### Development Changes
+
+- Removed rollup and created light-weight custom build system
+- Cleaned up file structure
+- Improved test speed & methodology
+- Changed patch detection signature
+
+### [1.4.5](https://github.com/nonara/ts-patch/compare/v1.4.4...v1.4.5) (2021-10-25)
+
+
+### Bug Fixes
+
+* compilation fails if basedir resolves to cwd ([#65](https://github.com/nonara/ts-patch/issues/65)) ([9bac698](https://github.com/nonara/ts-patch/commit/9bac698993cd287de6d62caba48205bf53b4e52e))
+
+### [1.4.4](https://github.com/nonara/ts-patch/compare/v1.4.3...v1.4.4) (2021-08-27)
+
+
+### Bug Fixes
+
+* `--basedir` flag fails if dir is not a subdir of a package ([5912288](https://github.com/nonara/ts-patch/commit/5912288f36f98a1722252d150a456c139e3f8382))
+
+### [1.4.3](https://github.com/nonara/ts-patch/compare/v1.4.2...v1.4.3) (2021-08-23)
+
+
+### Bug Fixes
+
+* Relative transform paths do not resolve from project root dir with compiler API (fixes [#59](https://github.com/nonara/ts-patch/issues/59)) ([e38655a](https://github.com/nonara/ts-patch/commit/e38655ac20f3905e61bcf8bfc03b97a5386b76f8))
+* ts 3.6.5 does not patch properly (fixes [#55](https://github.com/nonara/ts-patch/issues/55)) ([1babac9](https://github.com/nonara/ts-patch/commit/1babac9284d330983a9658794680a5058e7c64c0))
+
+### [1.4.2](https://github.com/nonara/ts-patch/compare/v1.4.1...v1.4.2) (2021-08-01)
+
+
+### Bug Fixes
+
+* Patch fails on ts v3.1 - 3.5 (fixes [#54](https://github.com/nonara/ts-patch/issues/54)) ([0fabe3c](https://github.com/nonara/ts-patch/commit/0fabe3c85129357a6ad453e48739dd1759efe18d))
+
+### [1.4.1](https://github.com/nonara/ts-patch/compare/v1.4.0...v1.4.1) (2021-07-13)
+
+
+### Bug Fixes
+
+* Only patch 'tsc.js' and 'typescript.js' by default (closes [#52](https://github.com/nonara/ts-patch/issues/52)) ([4d029f6](https://github.com/nonara/ts-patch/commit/4d029f666abdf5e2862c773eeba97eeddbb80089))
+
+## [1.4.0](https://github.com/nonara/ts-patch/compare/v1.3.4...v1.4.0) (2021-07-13)
+
+
+### Features
+
+* Add tsserver.js to supported libraries ([08262ed](https://github.com/nonara/ts-patch/commit/08262ede07c6e69b178751013988da772661ef02))
+
+
+### Bug Fixes
+
+* Require ts-node installation to be handled by user (fixes [#51](https://github.com/nonara/ts-patch/issues/51)) ([979338c](https://github.com/nonara/ts-patch/commit/979338ca5f0642b233de46dd6d293daa7f552ac4))
+
+### [1.3.4](https://github.com/nonara/ts-patch/compare/v1.3.3...v1.3.4) (2021-06-30)
+
+
+### Bug Fixes
+
+* Install adds ts-node to deps instead of devDeps (fixes [#38](https://github.com/nonara/ts-patch/issues/38)) ([a2d586b](https://github.com/nonara/ts-patch/commit/a2d586b286a4af0650faf69d3163115442aec8ab))
+
+### [1.3.3](https://github.com/nonara/ts-patch/compare/v1.3.2...v1.3.3) (2021-04-23)
+
+
+### Bug Fixes
+
+* **patch:** Patched emit does not pass all arguments (fixes [#36](https://github.com/nonara/ts-patch/issues/36)) ([9b130bc](https://github.com/nonara/ts-patch/commit/9b130bc8fd1a5bf3e7b33f796990ed7383aa5449))
+
+### [1.3.2](https://github.com/nonara/ts-patch/compare/v1.3.1...v1.3.2) (2021-01-31)
+
+## [1.3.1] (11-25-2020)
+
+### Fixed
+- Fixed #21 (Could not specify `--basedir` with dir name other than `typescript` - affected yarn aliasing)
+
+## [1.3.0] (07-26-2020)
+
+### Added
+- Added ability to specify tsconfig.json file for transformer (`tsConfig` option)
+  Note: This opens up the door to specify compilerOptions, which can be useful
+- Added path mapping support (requires [tsconfig-paths](https://npmjs.com/tsconfig-paths))
+
+## [1.2.2] (05-23-2020)
+
+### Fixed
+- Possible recursion issue with program transformer
+- In some older TS versions, tsc wasn't passing diagnostics array
+- Various CLI bugs
+
+### Added
+- Added 'library' to TspExtras
+- install and patch actions now will proceed to run if already patched but current version is out-dated
+
+### Code
+- Substantial re-design of certain parts (see release commit message for more)
+
+## [1.2.0] (05-20-2020)
+
+### Changed: `beforeEmit` -> `tranformProgram`
+
+The mechanism of action for `Program` transformation has been moved from inside
+`program.emit()` to `ts.createProgram()`. 
+
+In the new methodology, the `Program` instance is transformed at the point of creation _before_ it is returned from the 
+factory function, which is a far better approach.
+
+While the option name has been updated to reflect the new behaviour, the old `beforeEmit` can still function as an alias
+to the new behaviour, so this is not a breaking change.
+
+### Added: Inspect or alter diagnostics
+
+Using the `program` type entry point, the `extras` field has been revised.
+
+ | property | status | description |
+ | -------- | ------ | ----------- |
+ | diagnostics | _new_ | Reference to `Diagnostic[]` created during `ts.emitFilesAndReportErrors()` (works with tsc also)
+ | addDiagnostic | _changed_ | Directly add `Diagnostic` to `diagnostics` array |
+ | removeDiagnostic | _new_ | Directly remove `Diagnostic` from `diagnostics` array (uses splice, for safe removal)
+ 
+See `README.md` for full detail.
+
+## [1.1.0] (05-08-2020)
+
+### Added
+- Added `beforeEmit` option, which allows 'transforming' `Program` instance before `program.emit()` is called.
+
+## [1.0] (2019 - 2020)
+
+### Fixed
+- Updated for Node v14
+  _(Addresses [#7](https://github.com/nonara/ts-patch/issues/8), [shelljs/shelljs#991](https://github.com/shelljs/shelljs/issues/991))_  
+- Adjusted ts-node compilerOptions to ES2018
+  _(Fixes [#7](https://github.com/nonara/ts-patch/issues/7))_  
+- Exposed & fixed `addDiagnostic` helper
+  _(Fixes [#6](https://github.com/nonara/ts-patch/issues/6))_
+- Rolled `resolve` package into patch
+  _(Fixes [#5](https://github.com/nonara/ts-patch/issues/5))_
+- Converted EOL to LF (MacOS support)
+  _(Fixes [#3](https://github.com/nonara/ts-patch/issues/3) [#4](https://github.com/nonara/ts-patch/issues/4))_
+- Edge cases occurred in which TypeScript based transformers using CommonJS were not being interpretted properly. 
+  _(Should address [issue #1](https://github.com/nonara/ts-patch/issues/1))_
+
+[1.3.1]: https://github.com/nonara/ts-patch/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/nonara/ts-patch/compare/v1.2.2...v1.3.0
+[1.2.2]: https://github.com/nonara/ts-patch/compare/v1.1.0...v1.2.2
+[1.2.0]: https://github.com/nonara/ts-patch/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/nonara/ts-patch/compare/v1.0.10...v1.1.0
+[1.0]: https://github.com/nonara/ts-patch/releases/tag/v1.0.0...v1.0.10

package/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2021 Ron Spickenagel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation 
+files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, 
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom 
+the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+[![npm version](https://badge.fury.io/js/ts-patch.svg)](https://badge.fury.io/js/ts-patch)
+[![NPM Downloads](https://img.shields.io/npm/dm/ts-patch.svg?style=flat)](https://npmjs.org/package/ts-patch)
+![Build Status](https://github.com/nonara/ts-patch/workflows/Build/badge.svg)
+
+# ts-patch
+
+Patch typescript to allow custom transformers (plugins) during build.
+
+Plugins are specified in `tsconfig.json`, or provided programmatically in `CompilerOptions`.
+
+_Migrating from ttypescript is easy! See: [Method 1: Live Compiler](#method-1-live-compiler)_
+
+## Features
+
+* Patch typescript installation via on-the-fly, in-memory patching _or_ as a persistent patch
+* Can patch individual libraries (see `ts-patch /?`)
+* Hook build process by transforming the `Program` (see: [Transforming Program](#transforming-program))
+* Add, remove, or modify diagnostics (see: [Altering Diagnostics](#altering-diagnostics))
+* Fully compatible with legacy [ttypescript](https://github.com/cevek/ttypescript) projects
+* **(new)** Experimental support for ES Module based transformers
+
+# Table of Contents
+
+<!-- TOC -->
+* [ts-patch](#ts-patch)
+  * [Features](#features)
+* [Table of Contents](#table-of-contents)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Method 1: Live Compiler](#method-1-live-compiler)
+  * [Method 2: Persistent Patch](#method-2-persistent-patch)
+* [Configuration](#configuration)
+  * [Plugin Options](#plugin-options)
+* [Writing Transformers](#writing-transformers)
+  * [Source Transformers](#source-transformers)
+    * [Source Transformer Entry Point](#source-transformer-entry-point)
+    * [Source Transformer Example](#source-transformer-example)
+    * [Altering Diagnostics](#altering-diagnostics)
+    * [Note](#note)
+  * [Program Transformers](#program-transformers)
+    * [Program Transformer Entry Point](#program-transformer-entry-point)
+    * [Configuring Program Transformers](#configuring-program-transformers)
+    * [Program Transformer Example](#program-transformer-example)
+  * [Plugin Package Configuration](#plugin-package-configuration)
+    * [Example](#example)
+  * [Resources](#resources)
+    * [Recommended Reading](#recommended-reading)
+    * [Recommended Tools](#recommended-tools)
+    * [Discussion](#discussion)
+* [Advanced Options](#advanced-options)
+* [Maintainers](#maintainers)
+  * [Help Wanted](#help-wanted)
+* [License](#license)
+<!-- TOC -->
+
+# Installation
+
+1. Install package
+```sh
+<yarn|npm|pnpm> add -D ts-patch
+```
+
+# Usage
+
+## Method 1: Live Compiler
+
+The live compiler patches on-the-fly, each time it is run.
+
+**Via commandline:** Simply use `tspc` (instead of `tsc`)
+
+**With tools such as ts-node, webpack, ts-jest, etc:** specify the compiler as  `ts-patch/compiler`
+
+## Method 2: Persistent Patch
+
+Persistent patch modifies the typescript installation within the node_modules path. It requires additional configuration
+to remain persisted, but it carries less load time and complexity compared to the live compiler.
+
+1. Install the patch
+
+```shell
+# For advanced options, see: ts-patch /?
+ts-patch install
+```
+
+2. Add `prepare` script (keeps patch persisted after npm install)
+
+`package.json`
+ ```jsonc
+{
+  /* ... */
+  "scripts": {
+    "prepare": "ts-patch install -s"
+  }
+}
+ ```
+
+# Configuration
+
+**tsconfig.json**: Add transformers to `compilerOptions` in `plugins` array.
+
+**Examples**
+```jsonc
+{
+    "compilerOptions": {
+        "plugins": [
+            // Source Transformers
+            { "transform": "transformer-module" },
+            { "transform": "transformer2", "extraOption": 123 },
+            { "transform": "trans-with-mapping", "resolvePathAliases": true },
+            { "transform": "esm-transformer", "isEsm": true },
+
+            // Program Transformer
+            { "transform": "transformer-module5", "transformProgram": true }
+        ]
+    }
+}
+```
+
+## Plugin Options
+
+| Option             | Type    | Description                                                                                                   |
+|--------------------|---------|:--------------------------------------------------------------------------------------------------------------|
+| **transform**      | string  | Module name or path to transformer _(*.ts or *.js)_                                                           |
+| after              | boolean | Apply transformer after stock TS transformers                                                                 |
+| afterDeclarations  | boolean | Apply transformer to declaration (*.d.ts) files                                                               |
+| transformProgram   | boolean | Transform `Program` during `ts.createProgram()` _(see: [Program Transformers](#program-transformers))_        |
+| isEsm              | boolean | Transformer is ES Module (_note: experimental_ — requires [esm](https://www.npmjs.com/package/esm))           |
+| resolvePathAliases | boolean | Resolve path aliases in transformer (requires [tsconfig-paths](https://www.npmjs.com/package/tsconfig-paths)) |
+| type               | string  | See: [Source Transformer Entry Point](#source-transformer-entry-point) (default: 'program')                   |
+| import             | string  | Name of exported transformer function _(defaults to `default` export)_                                        |
+| tsConfig           | string  | tsconfig.json file _for transformer_ (allows specifying compileOptions, path mapping support, etc)            |
+| _..._              |         | Provide your own custom options, which will be passed to the transformer                                      |
+
+_Note: Required options are bold_
+
+# Writing Transformers
+
+For an overview of the typescript compiler (such as what a `SourceFile` and `Program` is) see: [Typescript Compiler Notes](https://github.com/microsoft/TypeScript-Compiler-Notes).
+
+## Source Transformers
+
+Source Transformers will transform the AST of SourceFiles during compilation, allowing you to alter the output of the JS or declarations files.
+
+### Source Transformer Entry Point
+
+```ts
+(program: ts.Program, config: PluginConfig, extras: TransformerExtras) => ts.TransformerFactory
+```
+
+**PluginConfig**: [Type Declaration](https://github.com/nonara/ts-patch/blob/master/projects/core/shared/plugin-types.ts)  
+**TransformerExtras**: [Type Declaration](https://github.com/nonara/ts-patch/blob/master/projects/core/shared/plugin-types.ts)  
+**ts.TransformerFactory**: `(context: ts.TransformationContext) => (sourceFile: ts.SourceFile) => ts.SourceFile`
+
+_Note: Additional [legacy signatures](https://github.com/cevek/ttypescript#pluginconfigtype) are supported, but it is not recommended to develop a new transformer using them._
+
+### Source Transformer Example
+
+Transformers can be written in JS or TS.
+
+```ts
+import type * as ts from 'typescript';
+import type { TransformerExtras, PluginConfig } from 'ts-patch';
+
+/** Changes string literal 'before' to 'after' */
+export default function (program: ts.Program, pluginConfig: PluginConfig, { ts: tsInstance }: TransformerExtras) {
+  return (ctx: ts.TransformationContext) => {
+    const { factory } = ctx;
+    
+    return (sourceFile: ts.SourceFile) => {
+      function visit(node: ts.Node): ts.Node {
+        if (tsInstance.isStringLiteral(node) && node.text === 'before') {
+          return factory.createStringLiteral('after');
+        }
+        return tsInstance.visitEachChild(node, visit, ctx);
+      }
+      return tsInstance.visitNode(sourceFile, visit);
+    };
+  };
+}
+
+```
+
+**Live Examples**:
+
+[`{ transform: "typescript-transform-paths" }`](https://github.com/LeDDGroup/typescript-transform-paths)
+
+[`{ transform: "typescript-is/lib/transform-inline/transformer" }`](https://github.com/woutervh-/typescript-is)
+
+[`{ transform: "typia/lib/transform" }`](https://github.com/samchon/typia) ([💻playground](https://typia.io/playground))
+
+[`{ transform: "@nestia/core/lib/transform" }`](https://github.com/samchon/nestia)
+
+### Altering Diagnostics
+
+Diagnostics can be altered in a Source Transformer.
+
+To alter diagnostics you can use the following, provided from the `TransformerExtras` parameter:
+
+| property           | description                                         |
+|--------------------|-----------------------------------------------------|
+| diagnostics        | Reference to `Diagnostic` array                     |   
+| addDiagnostic()    | Safely add `Diagnostic` to `diagnostics` array      |
+| removeDiagnostic() | Safely remove `Diagnostic` from `diagnostics` array | 
+
+### Note
+
+_This alters diagnostics during _emit only_. If you want to alter diagnostics in your IDE as well, you'll need to create a LanguageService plugin to accompany your source transformer_
+
+## Program Transformers
+
+Sometimes you want to do more than just transform source code. For example you may want to:
+
+- TypeCheck code after it's been transformed
+- Generate code and add it to the program
+- Add or remove emit files during transformation
+
+For this, we've introduced what we call a Program Transformer. The transform action takes place during `ts.createProgram`, and allows
+re-creating the `Program` instance that typescript uses.
+
+### Program Transformer Entry Point
+
+```ts
+(program: ts.Program, host: ts.CompilerHost | undefined, options: PluginConfig, extras: ProgramTransformerExtras) => ts.Program
+```
+
+**ProgramTransformerExtras** >>> [Type Declaration](https://github.com/nonara/ts-patch/blob/master/projects/core/shared/plugin-types.ts)
+
+### Configuring Program Transformers
+
+To configure a Program Transformer, supply `"transformProgram": true` in the config transformer entry.
+
+_Note: The `before`, `after`, and `afterDeclarations` options do not apply to a Program Transformer and will be ignored_
+
+[See Config Example](#configuration)
+
+### Program Transformer Example
+```TypeScript
+/** 
+ * Add a file to Program
+ */
+import * as path from 'path';
+import type * as ts from 'typescript';
+import type { ProgramTransformerExtras, PluginConfig } from 'ts-patch';
+
+export const newFile = path.resolve(__dirname, 'added-file.ts');
+
+export default function (
+  program: ts.Program, 
+  host: ts.CompilerHost | undefined, 
+  options: PluginConfig, 
+  { ts: tsInstance }: ProgramTransformerExtras
+) {
+  return tsInstance.createProgram(
+    /* rootNames */ program.getRootFileNames().concat([ newFile ]),
+    program.getCompilerOptions(),
+    host,
+    /* oldProgram */ program
+  );
+}
+```
+
+**Note:** For a more complete example, see [Transforming Program with additional AST transformations](https://github.com/nonara/ts-patch/discussions/29#discussioncomment-325979)
+
+**Live Examples**:
+
+[`{ transform: "@typescript-virtual-barrel/compiler-plugin", transformProgram: true }`](https://github.com/zaguiini/typescript-virtual-barrel)
+
+[`{ transform: "ts-overrides-plugin", transformProgram: true }`](https://github.com/DiFuks/ts-overrides-plugin)
+
+## Plugin Package Configuration
+
+The plugin package configuration allows you to specify custom options for your TypeScript plugin. 
+This configuration is defined in the `package.json` of your plugin under the `tsp` property.
+
+An example use case is enabling `parseAllJsDoc` if you require full JSDoc parsing in tsc for your transformer in TS v5.3+. (see: [5.3 JSDoc parsing changes](https://devblogs.microsoft.com/typescript/announcing-typescript-5-3/#optimizations-by-skipping-jsdoc-parsing))
+
+For all available options, see the `PluginPackageConfig` type in [plugin-types.ts](https://github.com/nonara/ts-patch/blob/master/projects/core/shared/plugin-types.ts)
+
+### Example
+
+```jsonc
+{
+  "name": "your-plugin-name",
+  "version": "1.0.0",
+  "tsp": {
+    "tscOptions": {
+      "parseAllJsDoc": true
+    }
+  }
+}
+```
+
+## Resources
+
+### Recommended Reading
+
+- How-To: [Advice for working with the TS Compiler API](https://github.com/nonara/ts-patch/discussions/31)
+- How-To: [TypeScript Transformer Handbook](https://github.com/madou/typescript-transformer-handbook)
+- Article: [How to Write a TypeScript Transform (Plugin)](https://dev.doctorevidence.com/how-to-write-a-typescript-transform-plugin-fc5308fdd943)
+- Article: [Creating a TypeScript Transformer](https://43081j.com/2018/08/creating-a-typescript-transform?source=post_page-----731e2b0b66e6----------------------)
+
+### Recommended Tools
+
+| Tool                                                                 | Type        | Description                                                                                 |
+|----------------------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------|
+| [TS AST Viewer](https://ts-ast-viewer.com/)                          | Web App     | Allows you to see the `Node` structure and other TS properties of your source code.         |
+| [ts-expose-internals](https://github.com/nonara/ts-expose-internals) | NPM Package | Exposes internal types and methods of the TS compiler API                                   |
+
+### Discussion
+
+- `#compiler-internals-and-api` on [TypeScript Discord Server](https://discord.com/invite/typescript)
+- TSP [Discussions](https://github.com/nonara/ts-patch/discussions) Board
+
+# Advanced Options
+
+**(env) `TSP_SKIP_CACHE`**
+
+Skips patch cache when patching via cli or live compiler.
+
+**(env) `TSP_COMPILER_TS_PATH`**
+
+Specify typescript library path to use for `ts-patch/compiler` (defaults to `require.resolve('typescript')`)
+
+**(env) `TSP_CACHE_DIR`**
+
+Override patch cache directory
+
+**(cli) `ts-patch clear-cache`**
+
+Cleans patch cache & lockfiles
+
+# Maintainers
+
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+    <td align="center"><a href="https://github.com/nonara"><img src="https://avatars0.githubusercontent.com/u/1427565?v=4" width="100px;" alt=""/><br /><sub><b>Ron S.</b></sub></a></td>
+  </tr>
+</table>
+
+## Help Wanted
+
+If you're interested in helping and are knowledgeable with the TS compiler codebase, feel free to reach out!
+
+# License
+
+This project is licensed under the MIT License, as described in `LICENSE.md`

package/actions/check.d.ts

@@ -0,0 +1,11 @@
+import { PatchDetail } from "../patch/patch-detail";
+import { InstallerOptions } from "../options";
+interface CheckResult {
+    [moduleName: string]: PatchDetail | undefined;
+}
+/**
+ * Check if files can be patched
+ */
+export declare function check(moduleName?: string | string[], opts?: Partial<InstallerOptions>): CheckResult;
+export declare function check(moduleNames?: string[], opts?: Partial<InstallerOptions>): CheckResult;
+export {};