Legacy Migration Toolkit

A starter lab for exploring automated strategies to modernize legacy stacks. It bundles lightweight analyzers, translators, reusable templates, and a pytest-powered harness so you can iterate quickly on migration ideas.

Quick Start

1. Create a virtual environment and install dependencies:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r requirements.txt

2. Populate docs/reports/ by running the analyzers:

   python cli/analyze.py --path .

3. Try a migration path. Example: Python 2 file to Python 3 stub:

   python cli/migrate.py --from python2 --to python3 --path path\to\legacy.py --refactor

   Include --refactor (also available on cli/analyze.py) to enable automated cleanup of globals, oversized functions, and repeated blocks. Translated files land in generated/ with JSON metadata in docs/reports/python2_to_python3/.
4. Launch the API gateway (FastAPI + Uvicorn) for REST access to analyzers and translators:

   python cli/api_gateway.py --host 0.0.0.0 --port 8000

   Visit http://localhost:8000/docs for interactive Swagger docs or export the static schema via:

   python services/api_gateway/export_openapi.py

Demo Translation Endpoint

• POST http://localhost:8000/demo/translate/python2to3 with { "code": "<python2 snippet>" } to see the enhanced Python 2→3 translator in action (refactoring enabled by default).
• The response echoes the original snippet, the translated Python 3 code, and the same metadata JSON you would get from the CLI/CLI file-based runs (refactorings, warnings, line counts, etc.).
• Example PowerShell request:

  $body = @{ code = 'print "hi"' } | ConvertTo-Json
  Invoke-RestMethod -Uri http://localhost:8000/demo/translate/python2to3 -Method POST -Body $body -ContentType 'application/json'

• A recorded sample request/response pair is available at docs/reports/demo_translation_sample.json for quick client demos.

Batch Translation Demo

• POST a .zip of Python 2 files to http://localhost:8000/demo/translate/python2to3/batch (multipart form field upload).
• The gateway unpacks the archive, runs the inline translator on every .py, and streams back a .zip containing:
  • translated/ with <filename>_py3.py stubs
  • metadata/ with per-file JSON metadata
  • consolidated_report.json summarizing totals/refactorings/warnings
  • summary.md highlighting trends and red flags
  • summary_proposal.md – a client-ready proposal outlining totals, refactorings, warnings, and next steps
• Example PowerShell snippet:

  Compress-Archive -Path .\legacy_samples\*.py -DestinationPath batch.zip
  Invoke-RestMethod -Uri http://localhost:8000/demo/translate/python2to3/batch -Method POST -InFile batch.zip -ContentType 'multipart/form-data'

• Sample outputs live under docs/reports/sample_batch_output.zip, docs/reports/demo_batch_translation_sample.json, and the client-facing proposal docs/reports/demo_batch_proposal_sample.md.
  • Optional PDF: when a PDF renderer (pandoc) is available, the batch archive will include summary_proposal.pdf and the repo will contain docs/reports/demo_batch_proposal_sample.pdf.

Included Tools

• analyzers/dependency_scanner.py builds a cross-language import graph (JSON output).
• analyzers/code_smell_detector.py flags common legacy constructs and suggests fixes.
• Translators for Python 2→3, Selenium→Playwright, and PHP→Node generate actionable stubs in templates/; the enhanced Python 2→3 path also emits JSON metadata describing refactorings (docs/reports/python2_to_python3/).
• services/api_gateway exposes those capabilities through FastAPI endpoints plus a generated docs/reports/openapi.json specification.
• test_harness/run_tests.py executes the translator unit tests and publishes docs/reports/test_results.json.

Next Steps

• Add more translators or plug in real migration logic.
• Expand the docs under docs/ with project-specific guidance.
• Integrate the CLI commands into your CI/CD pipeline once you are satisfied with the outputs.