Skip to content
This repository has been archived by the owner on Oct 8, 2024. It is now read-only.

Latest commit

 

History

History
51 lines (38 loc) · 3.14 KB

README.md

File metadata and controls

51 lines (38 loc) · 3.14 KB
Raw

VSCode Migrate

A VSCode extension to migrate source code step by step. This extension is intended for projects that want to benefit from tools like ts-morph or other code manipulation tools that go beyond pattern matching, but lack the coverage to rely on automated tests to verify the correctness of the changes. Find an example of use at https://github.com/tis-gmbh/vscode-migrate-example.

Features

  • Fetches matches with suggested changes from a migration script that you provide (see Migration Scripts)
  • Shows the matches grouped by file in the sidebar
  • Shows a preview of the suggested change using VSCode's diff editor, including coverage info
  • Lets you modify the suggested change
  • Applies the change to the file
  • Trigger verification tasks on the migration script
  • Submit the changes to version control if verification tasks succeed

Usage

  1. Provide a Migration Script.
  2. (Optionally) Have a test runner generate an lcov file to ./coverage/lcov.info and update it on changes.
  3. Run Start Migration command. All registered migrations will be listed. Pick the one you want to run.
  4. Click the change you want to preview in the sidebar.
  5. Inspect and - if needed - modify the suggested change.
  6. Click the checkmark in the editor controls or run the Apply Change command.
  7. Inspect the next change while waiting for the verification tasks and submission to version control to complete.

Extension Settings

Currently none, but will likely be added in the future.

Migration Scripts

If you're writing in TypeScript, use this definition file for type definitions.

Your migration script...

  • needs to be located within the .vscode/migration directory of your project.
  • can be written in JavaScript or TypeScript, the later requiring ts-node to be installed.
  • can register migrations (or their sync or async factory functions) with a name using a global registerMigration function or @Migration decorator.
  • is running in a separate process, which means
    • it has no access to the VSCode Extension Host API, but
    • can safely perform long running tasks without stalling the extension host process, and
    • can be debugged
  • is currently only required once. If you updated it, you can run the 'Restart Migration Script Process' command to load a fresh version of your migration script.

Your migration...

  • needs to have a sync or async getMatchedFiles method, returning a set of file with matches. For more details on the model, check this definition file.
  • will have it's getMatchedFiles method only called when the migration is started.
  • does NOT need to update the matches or suggested changes on file changes.
  • can define a sync or async verify method to run verification tasks like linting or running tests before submitting a change to version control.
  • can throw an error within the verify method, if the verification tasks fail and submission to version control needs to be aborted.
  • will have the verify method called every time a change is applied.