TypeScript Language Service Plugin for migrex
TypeScript Language Service Plugin for migrex - provides IDE integration including diagnostics, hover information, and quick fixes for migration code.
- Diagnostics on consume() calls: Detects when code doesn't properly handle single vs multi-value preserved fields
- Hover information: Shows field profiles ('always-single' or 'sometimes-multi') when hovering over field names
- Quick fixes: Suggests code fixes for handling multi-value cases
``bash`
npm install @migrex/ts-plugin typescript @migrex/core
Add the plugin to your tsconfig.json:
`json`
{
"compilerOptions": {
"plugins": [
{
"name": "@migrex/ts-plugin",
"graphPath": "./src/migrations/graph.ts",
"enableHover": true,
"enableQuickFixes": true
}
]
}
}
- graphPath (string, optional): Path to migration graph file (relative to project root)
- enableHover (boolean, optional): Enable hover information for field profiles (default: true)
- enableQuickFixes (boolean, optional): Enable quick fixes for multi-value handling (default: true)
The plugin will be automatically loaded by the TypeScript language server when you open a TypeScript file. Make sure you're using the workspace TypeScript version:
1. Open a .ts fileCmd+Shift+P
2. Press (Mac) or Ctrl+Shift+P (Windows/Linux)
3. Select "TypeScript: Select TypeScript Version..."
4. Choose "Use Workspace Version"
Any editor that uses the TypeScript Language Service should automatically load the plugin from your tsconfig.json.
The plugin will show warnings when you consume a field that can have multiple values without checking the kind property:
`typescript
// ⚠️ Warning: Field "theme" can have multiple preserved values
const theme = ctx.consume('theme');
// ✅ Correct: Check kind before using
const theme = ctx.consume('theme');
if (theme) {
if (theme.kind === 'single') {
// Handle single value: theme.value
} else {
// Handle multiple values: theme.values
}
}
`
Hover over a field name in a consume() or preserve() call to see its profile:
`typescripttheme
// Hover over 'theme' to see:
// migrex field profile
// Field is preserved at most once on any migration path.field.kind === "single"
// Safe to use: is always true.`
const theme = ctx.consume('theme');
When a diagnostic appears, you can use the quick fix (light bulb) to automatically generate proper multi-value handling code.
The plugin:
1. Loads your migration graph from the configured path
2. Analyzes the graph to determine field profiles
3. Checks consume() calls against the field profiles
4. Provides diagnostics, hover info, and quick fixes through the TypeScript Language Service
The plugin uses the proxy pattern to wrap the base TypeScript Language Service:
- plugin.ts: Main proxy logic that intercepts specific LanguageService methods
- diagnostics.ts: Generates diagnostics for consume() calls
- hover.ts: Augments hover information with field profiles
- quick-fixes.ts: Provides code fixes for multi-value handling
- analysis-cache.ts: Caches graph analysis results for performance
- graph-loader.ts: Loads migration graph from user code
`bashBuild the plugin
pnpm build
UNLICENSED