Honua Migration Tool

Multi-platform migration tool for converting ArcGIS applications to Honua.

Overview

honua-migrate is a comprehensive code migration tool that helps organizations transition from proprietary ArcGIS platforms to the open-source Honua geospatial platform. It provides automated code transformations, migration analysis, and project scaffolding across multiple programming languages and platforms.

Supported Migration Paths

✅ JavaScript (Existing)

• Source: ArcGIS API for JavaScript → Target: Honua JS SDK
• Features: AST transformations, 60+ compatibility modules, automatic import rewriting

🚧 .NET (In Development)

• Source: ArcGIS Runtime .NET → Target: Honua .NET Mobile SDK
• Features: Roslyn-based analysis, MAUI project templates, cross-platform support

🔄 Planned

• Python: ArcPy/ArcGIS API for Python → Honua Python SDK
• Android/iOS: Native ArcGIS Runtime → Honua Mobile SDK

Quick Start

# Install globally
npm install -g honua-migrate

# Scan ArcGIS usage in your codebase
honua-migrate scan --source esri-dotnet ./MyApp

# Convert to Honua
honua-migrate convert \
  --source esri-dotnet \
  --target honua-dotnet \
  --input ./MyApp \
  --output ./HonuaApp \
  --template maui-mobile

# Generate migration report
honua-migrate report --input ./MyApp --format html --output report.html

CLI Commands

scan

Analyze source code for ArcGIS API usage patterns:

honua-migrate scan --source esri-dotnet --input ./src --output scan-results.json

convert

Apply automated code transformations:

honua-migrate convert \
  --source esri-dotnet \
  --target honua-dotnet \
  --input ./src \
  --output ./migrated \
  --template maui-fieldapp

report

Generate comprehensive migration analysis:

honua-migrate report --input scan-results.json --format html --output migration-report.html

wizard

Interactive migration assistant:

honua-migrate wizard

Migration Patterns

JavaScript Example

// BEFORE (ArcGIS API for JavaScript)
import Map from '@arcgis/core/Map';
import MapView from '@arcgis/core/views/MapView';

const map = new Map({ basemap: 'topo' });
const view = new MapView({ map, container: 'map' });

// AFTER (Honua JS SDK with compat layer)
import { Map, MapView } from '@honua/sdk-esri-compat';

const map = new Map({ basemap: 'topo' });
const view = new MapView({ map, container: 'map' });

.NET Example

// BEFORE (ArcGIS Runtime .NET)
var featureTable = new ServiceFeatureTable(new Uri(serviceUrl));
await featureTable.LoadAsync();

var queryParams = new QueryParameters { WhereClause = "STATE = 'CA'" };
var result = await featureTable.QueryFeaturesAsync(queryParams);

// AFTER (Honua .NET Mobile SDK)
var client = await HonuaClient.CreateAsync(config);

var query = new FeatureQuery { WhereClause = "STATE = 'CA'" };
var result = await client.FeatureService.QueryFeaturesAsync("service-id", layerId, query);

Architecture

honua-migrate/
├── core/                    # Shared migration framework
├── sources/                 # Platform-specific analyzers
│   ├── esri-js/            # JavaScript/TypeScript analysis
│   ├── esri-dotnet/        # C# Roslyn analysis
│   └── esri-python/        # Python AST analysis
├── targets/                 # Code generators
│   ├── honua-js/           # JS SDK generation
│   ├── honua-dotnet/       # .NET SDK generation
│   └── honua-python/       # Python SDK generation
└── templates/              # Project scaffolding
    ├── maui-mobile/        # .NET MAUI field apps
    ├── react-native/       # React Native mobile
    └── python-etl/         # Python data processing

Migration Tiers

• Tier A: Direct automated mapping (>90% automation)
• Tier B: Minor adaptation required (70-90% automation)
• Tier C: Significant changes needed (30-70% automation)
• Manual: Requires human intervention (<30% automation)

Features

🔍 Deep Code Analysis

• AST-based parsing for accurate code understanding
• Cross-reference resolution and dependency tracking
• Migration complexity scoring and effort estimation

🤖 Automated Transformations

• Pattern-based code rewriting with high confidence
• Import statement updates and namespace migrations
• API call transformations with parameter mapping

📊 Comprehensive Reporting

• Visual migration complexity analysis
• API usage patterns and compatibility matrices
• Migration readiness assessment with risk factors

🏗️ Project Scaffolding

• Template-based project generation
• Platform-specific configuration and build files
• Best practices integration and modern patterns

🔄 Cross-Platform Support

• Unified CLI experience across all platforms
• Consistent migration patterns and terminology
• Extensible architecture for new source/target platforms

Development

# Clone repository
git clone https://github.com/mikemcdougall/honua-migrate.git
cd honua-migrate

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Development mode
npm run build:watch

Configuration

Create a honua-migrate.config.json file:

{
  "sourcePatterns": {
    "exclude": ["node_modules", "dist", "bin", "obj"]
  },
  "transformations": {
    "esri-dotnet": {
      "enableAutoImports": true,
      "generateBackups": true,
      "customMappings": {
        "MyCustomService": "HonuaCustomService"
      }
    }
  },
  "templates": {
    "maui-mobile": {
      "targetFramework": "net8.0",
      "platforms": ["iOS", "Android", "Windows"]
    }
  }
}

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-platform
3. Add source analyzer: Implement SourceAnalyzer interface
4. Add target generator: Implement TargetGenerator interface
5. Add tests: Ensure >80% code coverage
6. Submit pull request: Include example migrations and documentation

Roadmap

• Q1 2026: Complete .NET migration support
• Q2 2026: Add Python migration support
• Q3 2026: Native Android/iOS migration support
• Q4 2026: Cross-platform migration capabilities
• 2027: Community-driven transformation patterns

Support

• Documentation: docs.honua.dev/migrate
• Community: community.honua.dev
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

Licensed under the Apache License 2.0. See LICENSE for details.

---

Migrate with confidence. Migrate to Honua.