# febrifelis/migrasafe architecture

> Architecture diagram of the GitHub repository febrifelis/migrasafe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/febrifelis/migrasafe
- Repository: https://github.com/febrifelis/migrasafe

## Overview

migrasafe is a SQL-migration safety checker: an engineer or CI job submits migration files, and the CLI scans them, reports risks and suggested fixes, and exits with a safety status. The main path parses SQL into statements, applies visitor-based checks with rule fallbacks, enriches findings, and builds scan-level risk and dependency results for output. The repository also documents dashboards, policy and approval workflows, plugin rules, coverage reporting, and an AI suggestion capability. Connections for unsampled features are included only where the README or indexed source references support them.

Main entry points: [`src/index.ts`](https://github.com/febrifelis/migrasafe/blob/master/src/index.ts) (CLI commands), [`src/engine/pipeline.ts`](https://github.com/febrifelis/migrasafe/blob/master/src/engine/pipeline.ts) (Rule pipeline), [`src/checker/checker.ts`](https://github.com/febrifelis/migrasafe/blob/master/src/checker/checker.ts) (File and directory checks), [`src/engine/risk.ts`](https://github.com/febrifelis/migrasafe/blob/master/src/engine/risk.ts) (Scan risk scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["CLI commands<br/>[index.ts]"]
end

subgraph group_scan["Migration scanning"]
  node_checker["File and directory checks<br/>[checker.ts]"]
  node_parser["SQL parser<br/>[parser.ts]"]
  node_lexer["SQL lexer<br/>[lexer.ts]"]
  node_pipeline["Rule pipeline<br/>[pipeline.ts]"]
  node_visitors["Statement visitors<br/>[alter.ts]"]
  node_rules["Built-in rules<br/>[rules.ts]"]
  node_plugin_loader["Plugin rules<br/>[loader.ts]"]
  node_config["Configuration<br/>[config.ts]"]
end

subgraph group_analysis["Risk analysis"]
  node_semantic["Semantic analysis<br/>[semantic.ts]"]
  node_dependency_graph["Dependency graph<br/>[graph.ts]"]
  node_risk["Scan risk scoring<br/>[risk.ts]"]
  node_lock["Lock analysis<br/>[lock.ts]"]
  node_rollback["Rollback analysis<br/>[rollback.ts]"]
  node_cost["Cost analysis<br/>[cost.ts]"]
  node_rewrite["Rewrite analysis<br/>[rewrite.ts]"]
  node_objects["Affected objects<br/>[objects.ts]"]
end

subgraph group_services["Reporting and policy"]
  node_formatter["Result formatting<br/>[formatter.ts]"]
  node_ai_suggestions["AI suggestions<br/>[suggestions.ts]"]
  node_dashboard["Dashboard generator<br/>[generator.ts]"]
  node_history["Scan history<br/>[history.ts]"]
  node_policy["Policy evaluation<br/>[policy.ts]"]
  node_approval["Approval requests<br/>[approval.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
  node_coverage["Rule coverage report<br/>[index.ts]"]
  node_catalog["Rule catalog<br/>[index.ts]"]
end

subgraph group_ide["Editor integration"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
  node_diagnostics["Editor diagnostics<br/>[diagnostics.ts]"]
  node_editor_runner["Scan runner<br/>[runner.ts]"]
  node_code_actions["Code actions<br/>[codeActions.ts]"]
end

node_engineer(("Engineer or CI"))

node_engineer -->|"runs checks"| node_cli
node_cli -->|"scans files"| node_checker
node_checker -->|"parses statements"| node_parser
node_parser -->|"tokenizes SQL"| node_lexer
node_checker -->|"checks statements"| node_pipeline
node_pipeline -->|"dispatches visits"| node_visitors
node_pipeline -->|"checks fallback rules"| node_rules
node_checker -->|"loads plugin rules"| node_plugin_loader
node_plugin_loader -->|"validates rules"| node_rules
node_checker -->|"analyzes statements"| node_semantic
node_checker -->|"builds dependencies"| node_dependency_graph
node_checker -->|"computes scan risk"| node_risk
node_pipeline -->|"analyzes locks"| node_lock
node_pipeline -->|"assesses rollback"| node_rollback
node_pipeline -->|"estimates cost"| node_cost
node_pipeline -->|"analyzes rewrites"| node_rewrite
node_pipeline -->|"finds affected objects"| node_objects
node_risk -->|"uses scores"| node_lock
node_risk -->|"uses scores"| node_rollback
node_risk -->|"uses estimates"| node_cost
node_risk -->|"uses estimates"| node_rewrite
node_cli -->|"formats results"| node_formatter
node_cli -->|"loads settings"| node_config
node_cli -->|"loads history"| node_history
node_cli -->|"generates dashboard"| node_dashboard
node_dashboard -->|"renders history"| node_history
node_cli -->|"evaluates policy"| node_policy
node_cli -->|"generates requests"| node_approval
node_cli -->|"uses notifications"| node_notifications
node_cli -->|"requests suggestions"| node_ai_suggestions
node_cli -->|"reports coverage"| node_coverage
node_cli -->|"builds catalog"| node_catalog
node_vscode -->|"registers diagnostics"| node_diagnostics
node_vscode -->|"registers actions"| node_code_actions
node_diagnostics -->|"runs scan"| node_editor_runner
node_engineer -.->|"uses editor"| node_vscode

click node_cli "https://github.com/febrifelis/migrasafe/blob/master/src/index.ts"
click node_vscode "https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/extension.ts"
click node_diagnostics "https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/diagnostics.ts"
click node_editor_runner "https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/runner.ts"
click node_code_actions "https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/codeActions.ts"
click node_checker "https://github.com/febrifelis/migrasafe/blob/master/src/checker/checker.ts"
click node_parser "https://github.com/febrifelis/migrasafe/blob/master/src/ast/parser.ts"
click node_lexer "https://github.com/febrifelis/migrasafe/blob/master/src/ast/lexer.ts"
click node_pipeline "https://github.com/febrifelis/migrasafe/blob/master/src/engine/pipeline.ts"
click node_visitors "https://github.com/febrifelis/migrasafe/blob/master/src/engine/visitors/alter.ts"
click node_rules "https://github.com/febrifelis/migrasafe/blob/master/src/checker/rules.ts"
click node_plugin_loader "https://github.com/febrifelis/migrasafe/blob/master/src/plugins/loader.ts"
click node_semantic "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/semantic.ts"
click node_dependency_graph "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/graph.ts"
click node_risk "https://github.com/febrifelis/migrasafe/blob/master/src/engine/risk.ts"
click node_lock "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/lock.ts"
click node_rollback "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/rollback.ts"
click node_cost "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/cost.ts"
click node_rewrite "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/rewrite.ts"
click node_objects "https://github.com/febrifelis/migrasafe/blob/master/src/analysis/objects.ts"
click node_formatter "https://github.com/febrifelis/migrasafe/blob/master/src/output/formatter.ts"
click node_ai_suggestions "https://github.com/febrifelis/migrasafe/blob/master/src/ai/suggestions.ts"
click node_dashboard "https://github.com/febrifelis/migrasafe/blob/master/src/dashboard/generator.ts"
click node_history "https://github.com/febrifelis/migrasafe/blob/master/src/dashboard/history.ts"
click node_policy "https://github.com/febrifelis/migrasafe/blob/master/src/enterprise/policy.ts"
click node_approval "https://github.com/febrifelis/migrasafe/blob/master/src/enterprise/approval.ts"
click node_notifications "https://github.com/febrifelis/migrasafe/blob/master/src/enterprise/notifications.ts"
click node_coverage "https://github.com/febrifelis/migrasafe/blob/master/src/coverage/index.ts"
click node_catalog "https://github.com/febrifelis/migrasafe/blob/master/src/catalog/index.ts"
click node_config "https://github.com/febrifelis/migrasafe/blob/master/src/config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_checker,node_parser,node_lexer,node_pipeline,node_visitors,node_rules,node_plugin_loader,node_config toneAmber
class node_semantic,node_dependency_graph,node_risk,node_lock,node_rollback,node_cost,node_rewrite,node_objects toneMint
class node_formatter,node_ai_suggestions,node_dashboard,node_history,node_policy,node_approval,node_notifications,node_coverage,node_catalog toneRose
class node_vscode,node_diagnostics,node_editor_runner,node_code_actions,node_engineer toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/febrifelis/migrasafe/blob/master/src/index.ts): `src/index.ts`

### Migration scanning

- [File and directory checks](https://github.com/febrifelis/migrasafe/blob/master/src/checker/checker.ts): `src/checker/checker.ts`
- [SQL parser](https://github.com/febrifelis/migrasafe/blob/master/src/ast/parser.ts): `src/ast/parser.ts`
- [SQL lexer](https://github.com/febrifelis/migrasafe/blob/master/src/ast/lexer.ts): `src/ast/lexer.ts`
- [Rule pipeline](https://github.com/febrifelis/migrasafe/blob/master/src/engine/pipeline.ts): `src/engine/pipeline.ts`
- [Statement visitors](https://github.com/febrifelis/migrasafe/blob/master/src/engine/visitors/alter.ts): `src/engine/visitors/alter.ts`
- [Built-in rules](https://github.com/febrifelis/migrasafe/blob/master/src/checker/rules.ts): `src/checker/rules.ts`
- [Plugin rules](https://github.com/febrifelis/migrasafe/blob/master/src/plugins/loader.ts): `src/plugins/loader.ts`
- [Configuration](https://github.com/febrifelis/migrasafe/blob/master/src/config.ts): `src/config.ts`

### Risk analysis

- [Semantic analysis](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/semantic.ts): `src/analysis/semantic.ts`
- [Dependency graph](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/graph.ts): `src/analysis/graph.ts`
- [Scan risk scoring](https://github.com/febrifelis/migrasafe/blob/master/src/engine/risk.ts): `src/engine/risk.ts`
- [Lock analysis](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/lock.ts): `src/analysis/lock.ts`
- [Rollback analysis](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/rollback.ts): `src/analysis/rollback.ts`
- [Cost analysis](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/cost.ts): `src/analysis/cost.ts`
- [Rewrite analysis](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/rewrite.ts): `src/analysis/rewrite.ts`
- [Affected objects](https://github.com/febrifelis/migrasafe/blob/master/src/analysis/objects.ts): `src/analysis/objects.ts`

### Reporting and policy

- [Result formatting](https://github.com/febrifelis/migrasafe/blob/master/src/output/formatter.ts): `src/output/formatter.ts`
- [AI suggestions](https://github.com/febrifelis/migrasafe/blob/master/src/ai/suggestions.ts): `src/ai/suggestions.ts`
- [Dashboard generator](https://github.com/febrifelis/migrasafe/blob/master/src/dashboard/generator.ts): `src/dashboard/generator.ts`
- [Scan history](https://github.com/febrifelis/migrasafe/blob/master/src/dashboard/history.ts): `src/dashboard/history.ts`
- [Policy evaluation](https://github.com/febrifelis/migrasafe/blob/master/src/enterprise/policy.ts): `src/enterprise/policy.ts`
- [Approval requests](https://github.com/febrifelis/migrasafe/blob/master/src/enterprise/approval.ts): `src/enterprise/approval.ts`
- [Notifications](https://github.com/febrifelis/migrasafe/blob/master/src/enterprise/notifications.ts): `src/enterprise/notifications.ts`
- [Rule coverage report](https://github.com/febrifelis/migrasafe/blob/master/src/coverage/index.ts): `src/coverage/index.ts`
- [Rule catalog](https://github.com/febrifelis/migrasafe/blob/master/src/catalog/index.ts): `src/catalog/index.ts`

### Editor integration

- [VS Code extension](https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/extension.ts): `vscode-extension/src/extension.ts`
- [Editor diagnostics](https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/diagnostics.ts): `vscode-extension/src/diagnostics.ts`
- [Scan runner](https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/runner.ts): `vscode-extension/src/runner.ts`
- [Code actions](https://github.com/febrifelis/migrasafe/blob/master/vscode-extension/src/codeActions.ts): `vscode-extension/src/codeActions.ts`

### Other components

- **Engineer or CI**

## Connections

- Engineer or CI → CLI commands: runs checks
- CLI commands → File and directory checks: scans files (evidence: `src/index.ts`)
- File and directory checks → SQL parser: parses statements (evidence: `src/checker/checker.ts`)
- SQL parser → SQL lexer: tokenizes SQL (evidence: `src/ast/parser.ts`)
- File and directory checks → Rule pipeline: checks statements (evidence: `src/checker/checker.ts`)
- Rule pipeline → Statement visitors: dispatches visits (evidence: `src/engine/pipeline.ts`)
- Rule pipeline → Built-in rules: checks fallback rules (evidence: `src/engine/pipeline.ts`)
- File and directory checks → Plugin rules: loads plugin rules (evidence: `src/checker/checker.ts`)
- Plugin rules → Built-in rules: validates rules (evidence: `src/plugins/loader.ts`)
- File and directory checks → Semantic analysis: analyzes statements (evidence: `src/checker/checker.ts`)
- File and directory checks → Dependency graph: builds dependencies (evidence: `src/checker/checker.ts`)
- File and directory checks → Scan risk scoring: computes scan risk (evidence: `src/checker/checker.ts`)
- Rule pipeline → Lock analysis: analyzes locks (evidence: `src/engine/pipeline.ts`)
- Rule pipeline → Rollback analysis: assesses rollback (evidence: `src/engine/pipeline.ts`)
- Rule pipeline → Cost analysis: estimates cost (evidence: `src/engine/pipeline.ts`)
- Rule pipeline → Rewrite analysis: analyzes rewrites (evidence: `src/engine/pipeline.ts`)
- Rule pipeline → Affected objects: finds affected objects (evidence: `src/engine/pipeline.ts`)
- Scan risk scoring → Lock analysis: uses scores (evidence: `src/engine/risk.ts`)
- Scan risk scoring → Rollback analysis: uses scores (evidence: `src/engine/risk.ts`)
- Scan risk scoring → Cost analysis: uses estimates (evidence: `src/engine/risk.ts`)
- Scan risk scoring → Rewrite analysis: uses estimates (evidence: `src/engine/risk.ts`)
- CLI commands → Result formatting: formats results (evidence: `src/index.ts`)
- CLI commands → Configuration: loads settings (evidence: `src/index.ts`)
- CLI commands → Scan history: loads history (evidence: `src/index.ts`)
- CLI commands → Dashboard generator: generates dashboard (evidence: `src/index.ts`)
- Dashboard generator → Scan history: renders history (evidence: `src/dashboard/generator.ts`)
- CLI commands → Policy evaluation: evaluates policy (evidence: `src/index.ts`)
- CLI commands → Approval requests: generates requests (evidence: `src/index.ts`)
- CLI commands → Notifications: uses notifications (evidence: `src/index.ts`)
- CLI commands → AI suggestions: requests suggestions (evidence: `src/index.ts`)
- CLI commands → Rule coverage report: reports coverage (evidence: `src/index.ts`)
- CLI commands → Rule catalog: builds catalog (evidence: `src/index.ts`)
- VS Code extension → Editor diagnostics: registers diagnostics (evidence: `vscode-extension/src/extension.ts`)
- VS Code extension → Code actions: registers actions (evidence: `vscode-extension/src/extension.ts`)
- Editor diagnostics → Scan runner: runs scan (evidence: `vscode-extension/src/diagnostics.ts`)
- Engineer or CI → VS Code extension: uses editor
