Skip to main content

Writing a Migration Task

Writing a migration task

Migration tasks are a specialized type of task that are used to help identify features within a project that need to be migrated from one structure to another. This is usually accomplished through groupings of lint rules, which together comprise the definition of the migration.

A good example of this is the Ember Octane migration task. The task is responsible for identifying all of the Ember Classic features that need to be migrated, and then running the appropriate lint rules to identify the changes that need to be made.

Migration tasks are a subclass of the BaseTask class, and have migration-specific methods and properties that make writing them easier. More details on what's included in this class can be found in the BaseMigrationTask documentation.

A simple migration task

Below is a simple example of a migration task.

/tasks/my-migration-task.ts
import { BaseMigrationTask, Task, TaskContext } from '@checkup/core';
import { Result } from 'sarif';

export default class MyMigrationTask extends BaseMigrationTask implements Task {
  taskName = 'my-migration';
  taskDisplayName = 'My Migration';
  description = 'Tracks the migration status of my stuff';
  category = 'migrations';

  constructor(pluginName: string, context: TaskContext) {
    super('My Migration', pluginName, context);

    this.addRuleComponentMetadata();

    // featureIds are typically the same as the lint ruleIds, but can be different
    this.addFeature('some-feature-id', {
      featureName: 'Some Feature Name',
      message: "Use this feature instead, it's better",
      helpUri: 'https://feature-docs/somewhere.com',
    });
  }

  async run(): Promise<Result[]> {
    let rawData = getResults();

    rawData.forEach((result) => {
      let id = result.featureId;
      let feature = this.features.get(id);

      if (feature) {
        this.addFeatureResult(feature, {
          location: {
            uri: lintResult.filePath,
            startColumn: lintResult.column,
            startLine: lintResult.line,
            endColumn: lintResult.endColumn,
            endLine: lintResult.endLine,
          },
        });
      }
    });

    return this.results;
  }

  getResults() {
    // Get results from one or more of the analyzers
  }
}

Coupling this with the pretty formatter, we can get a full picture of the scope of our migration.

$ [yarn|npx] checkup run . --task my-migration --format pretty

Checkup report generated for checkup-app v1.3.0 (46 files analyzed)

This project is 100 days old, with 90 days active days, 375 commits and 46 files.

Checkup ran the following task(s) successfully:

My Migration
=============================
Outstanding features to be migrated: 4
  Some Feature Name 3
  Another Feature Name 1

checkup v1.3.0
config dd17cda1fc2eb2bc6bb5206b41fc1a84