Programmatic API

Use MigrationPilot as a library in your Node.js applications.

Installation

Install MigrationPilot as a dependency:

npm install migrationpilot

Basic Usage

Import and use the analysis pipeline:

import { analyzeSQL, allRules } from 'migrationpilot';

const sql = `
  ALTER TABLE users ADD COLUMN email text;
  CREATE INDEX idx_users_email ON users (email);
`;

const result = await analyzeSQL(sql, 'migration.sql', 17, allRules);

console.log(result.overallRisk);    // { level: 'YELLOW', score: 35 }
console.log(result.violations);     // Array of violations
console.log(result.statements);     // Parsed statements with lock types

Available Exports

The programmatic API exports these functions and types:

import {
  // Core analysis
  analyzeSQL,              // Full analysis pipeline
  parseMigration,          // SQL → AST parsing
  extractTargets,          // AST → table/column targets
  classifyLock,            // Statement → lock type

  // Rules
  allRules,                // All free-tier rules
  runRules,                // Run rules against statements

  // Scoring
  calculateRisk,           // Calculate risk score

  // Output formatters
  formatCliOutput,         // Terminal table output
  formatSarif,             // SARIF v2.1.0
  formatJson,              // Structured JSON
  formatPrComment,         // GitHub PR comment

  // Auto-fix
  autoFix,                 // Apply automatic fixes
  isFixable,               // Check if a rule is fixable

  // Utilities
  detectFrameworks,        // Detect migration frameworks
  loadConfig,              // Load configuration
} from 'migrationpilot';

Custom Rule Filtering

Filter rules to only check specific categories:

import { analyzeSQL, allRules } from 'migrationpilot';

// Only check lock-related rules
const lockRules = allRules.filter(r =>
  ['MP001', 'MP004', 'MP006', 'MP008'].includes(r.id)
);

const result = await analyzeSQL(sql, 'file.sql', 17, lockRules);

JSON Output Schema

The JSON output follows a versioned schema for stability:

{
  "$schema": "https://migrationpilot.dev/schemas/report-v1.json",
  "version": "1.4.0",
  "file": "migration.sql",
  "overallRisk": { "level": "RED", "score": 75 },
  "statementCount": 3,
  "ruleCount": 80,
  "violations": [
    {
      "ruleId": "MP001",
      "ruleName": "require-concurrent-index",
      "severity": "critical",
      "message": "CREATE INDEX acquires ACCESS EXCLUSIVE lock...",
      "statement": "CREATE INDEX idx_users_email ON users (email);",
      "line": 2,
      "fix": "CREATE INDEX CONCURRENTLY idx_users_email ON users (email);"
    }
  ]
}

← CI Integration CLI Reference →