astoncli 0.1.1

 █████╗ ███████╗████████╗ ██████╗ ███╗   ██╗
██╔══██╗██╔════╝╚══██╔══╝██╔═══██╗████╗  ██║
███████║███████╗   ██║   ██║   ██║██╔██╗ ██║
██╔══██║╚════██║   ██║   ██║   ██║██║╚██╗██║
██║  ██║███████║   ██║   ╚██████╔╝██║ ╚████║
╚═╝  ╚═╝╚══════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═══╝

 ██████╗██╗     ██╗
██╔════╝██║     ██║
██║     ██║     ██║
██║     ██║     ██║
╚██████╗███████╗██║
 ╚═════╝╚══════╝╚═╝

https://github.com/user-attachments/assets/812a1990-13c3-4c45-8a8e-080f602c7a3f

Automated dependency migration, from breaking-change detection to a verified pull request.

Quick Start • Live Demo • How It Works • Commands • Architecture • FAQ • Contributing

Making dependency migrations less manual.

Table of Contents

The problem ASTon solves

Your project uses an older version of a Python library. A new version ships and some APIs change.

# Old API
import openai

openai.ChatCompletion.create(...)

# New API
from openai import OpenAI

client = OpenAI()
client.chat.completions.create(...)

Simply bumping the version can break your app. Traditionally you would have to:

1. Read release notes and migration guides
2. Find the breaking changes relevant to your code
3. Search your codebase for affected APIs
4. Rewrite the affected code
5. Run tests and debug failures
6. Commit and open a pull request

ASTon automates that entire loop and hands you a reviewable PR.

Quick start

Three commands, from update detection to pull request:

aston watcher --path demo          # 1. detect dependency updates
aston check --run --path demo      # 2. run the migration pipeline
aston pr --path aston/succ_migrations --repo demo   # 3. open the PR

Not sure what's available? Run aston --help or aston <command> --help at any time.

ASTon Migration Demonstration

This repository demonstrates ASTon's end-to-end dependency migration workflow using a Python application built with the legacy OpenAI Python SDK.

ASTon analyzed the repository, identified deprecated API usage across multiple Python modules, generated migration changes, verified the updated code, and submitted a GitHub pull request that was subsequently merged.

The demo recording is at the top of this README.

Migration details

• Source dependency: openai==0.28.1
• Target dependency: openai==3.41.0
• Migration scope: Multiple Python modules
• Verification: Docker-based verification and repository-wide tests

Migration evidence

What this demonstrates

1. Breaking-change discovery from dependency documentation.
2. Identification of affected code across multiple modules.
3. Automated migration rule generation and code modification.
4. Docker-based verification and repository-wide testing.
5. GitHub pull request creation and merging.

git clone https://github.com/2022n02511-stack/demo_aston.git demo

aston watcher --path demo
aston check --run --path demo
aston pr --path aston/succ_migrations --repo demo

Note: This is a demonstration project designed to showcase ASTon's migration capabilities, not a production customer deployment.

How it works

The 30-second view

 ┌──────────────────────────────────────────────────────────────────────────┐
 │                         ASTon  MIGRATION PIPELINE                        │
 └──────────────────────────────────────────────────────────────────────────┘

   ① WATCH        ② INGEST         ③ EXTRACT        ④ SCAN
 ┌─────────┐    ┌───────────┐    ┌────────────┐    ┌────────────┐
 │ new pkg │───▶│ changelog │───▶│ LLM builds │───▶│ AST usage  │
 │ version │    │ + guides  │    │ rules.json │    │ map of repo│
 └─────────┘    └───────────┘    └────────────┘    └─────┬──────┘
                                                          │
   ⑧ VERIFY       ⑦ GENERATE       ⑥ VALIDATE       ⑤ RELEVANCE
 ┌──────────┐   ┌────────────┐   ┌────────────┐   ┌──────┴──────┐
 │ Docker   │◀──│ candidate  │◀──│ rules vs   │◀──│ which rules │
 │ per file │   │ migrations │   │ target ver │   │ hit my code?│
 └────┬─────┘   └────────────┘   └────────────┘   └─────────────┘
      │
      ├── fail ──▶ REPAIR ──▶ (back to ⑧)
      │
      └── pass
            │
            ▼
   ⑨ FULL-REPO VERIFY              ⑩ DELIVER
 ┌─────────────────────┐        ┌──────────────────────┐
 │ syntax + test cmd   │──pass─▶│ branch → commit →    │──▶ Human review
 │ on combined project │        │ push → GitHub PR     │       & merge
 └──────────┬──────────┘        └──────────────────────┘
            │
          fail
            ▼
     Verification report

The full workflow (Mermaid)

flowchart TD
    A["Start ASTon"] --> B["Watch for dependency updates"]
    B --> C["Discover new package version"]
    C --> D["Collect release notes and migration documentation"]
    D --> E["Extract migration rules"]
    E --> F["Build repository usage map"]
    F --> G["Identify relevant breaking changes"]
    G --> H["Validate migration rules"]
    H --> I["Generate code migrations"]
    I --> J["Verify individual files in Docker"]
    J --> K{"Migration successful?"}
    K -->|No| L["Repair failed migration"]
    L --> J
    K -->|Yes| M["Save migrated files"]
    M --> N["Verify complete repository"]
    N --> O{"Repository verification passed?"}
    O -->|No| P["Report verification failure"]
    O -->|Yes| Q["Create GitHub pull request"]

Which CLI command runs which stages?

 aston watcher ───▶ aston check --run ───▶ aston pr
   (stage 1)          (stages 2 – 9)        (stage 10)

The 10 stages in detail

Click any stage to expand it.

Current dependency: openai==0.28.1
Available version:  3.41.0

aston watcher --path demo

flowchart TD
    A["New package version"] --> B["Find release information"]
    B --> C["Collect changelog"]
    C --> D["Find migration documentation"]
    D --> E["Follow relevant documentation links"]
    E --> F["Combine collected information"]
    F --> G["Documentation for rule extraction"]

{
  "package": "openai",
  "old_api": "openai.ChatCompletion.create",
  "new_api": "client.chat.completions.create",
  "migration_type": "rename"
}

from openai import OpenAI as Client

client = Client()

response = client.chat.completions.create(
    model="example-model",
    messages=[]
)

flowchart TD
    A["Python source files"] --> B["Python AST parser"]
    B --> C["Inspect imports"]
    B --> D["Inspect function calls"]
    B --> E["Inspect object instantiation"]
    C --> F["Usage map"]
    D --> F
    E --> F
    F --> G["Repository dependency usage"]

Version 0 → Version 1      API A → API B
Version 1 → Version 2      API B → API C

# Before
import openai

response = openai.ChatCompletion.create(...)

# After
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(...)

flowchart TD
    A["Generated candidate"] --> B["Create Docker environment"]
    B --> C["Install target requirements"]
    C --> D["Run verification"]
    D --> E{"Passed?"}
    E -->|Yes| F["Save successful migration"]
    E -->|No| G["Analyze verification error"]
    G --> H["Generate repaired candidate"]
    H --> B

flowchart TD
    A["Original repository"] --> C["Build verification copy"]
    B["Successful migrated files"] --> C
    D["Target requirements"] --> C
    C --> E["Install dependencies"]
    E --> F["Check Python syntax"]
    F --> G["Run repository tests"]
    G --> H{"Passed?"}
    H -->|Yes| I["Ready for pull request"]
    H -->|No| J["Report verification failure"]

flowchart TD
    A["Verified migration output"] --> B["Prepare migration branch"]
    B --> C["Copy migrated files"]
    C --> D["Commit changes"]
    D --> E["Push branch"]
    E --> F["Create GitHub pull request"]
    F --> G["Developer reviews changes"]
    G --> H["Merge when approved"]

Command reference

1. Check available commands

aston --help

2. Start the dependency watcher

aston watcher --path demo

View watcher-specific options:

aston watcher --help

3. Run the migration pipeline

aston check --run --path demo

View migration command options:

aston check --help

4. Create a GitHub pull request

aston pr \
  --path aston/succ_migrations \
  --repo demo \
  --branch demo_aston \
  --title "Migrate OpenAI dependency" \
  --body "Automated dependency migration generated and verified by ASTon."

View PR command options:

aston pr --help

Run the complete workflow

Chain everything in one go. Each command runs only if the previous one succeeds (&&).

aston watcher --path demo && \
aston check --run --path demo && \
aston pr \
  --path aston/succ_migrations \
  --repo demo \
  --branch demo_aston \
  --title "Migrate OpenAI dependency" \
  --body "Automated dependency migration generated and verified by ASTon."

 ┌──────────────┐  ok   ┌──────────────────┐  ok   ┌────────────┐
 │ aston watcher│──────▶│ aston check --run│──────▶│  aston pr  │──▶ PR opened
 └──────┬───────┘       └────────┬─────────┘       └─────┬──────┘
        │ fail                   │ fail                  │ fail
        ▼                        ▼                       ▼
      stop                     stop                    stop

Example migration

This is the migration shown in the demonstration above.

Your project uses:

openai==0.28.1

You want to move to:

openai==3.41.0

flowchart TD
    A["openai 0.28.1"] --> B["Discover target 3.41.0"]
    B --> C["Collect migration documentation"]
    C --> D["Extract API migration rules"]
    D --> E["Scan project for OpenAI usage"]
    E --> F["Identify relevant rules"]
    F --> G["Validate rules for 3.41.0"]
    G --> H["Generate migrated Python files"]
    H --> I["Verify and repair"]
    I --> J["Verify complete repository"]
    J --> K["Create pull request"]

Instead of manually hunting down every affected API, you receive a pull request with the proposed changes.

Project architecture

 WATCH      watcher.py ── poller.py
   │
 INGEST     ingestion.py ── changes/chain.py
   │
 EXTRACT    axios.py (LLM) ──▶ rules.json
   │
 SCAN       scanner.py ──▶ repo_index/repo_map.py ──▶ repo_index.json
   │
 FILTER     relevance.py ── rule_validation.py
   │
 MIGRATE    pipeline.py ◀──▶ docker.py   (generate ⇄ verify ⇄ repair)
   │
 VERIFY     repo_verification.py
   │
 DELIVER    github_integrations/pr.py

 INTERFACE  cli/main.py ── cli/console.py ── cli_ui/rich.py

Generated files and directories

Installation

From PyPI (recommended)

pip install astoncli
aston --help

The package is named astoncli on PyPI, and the command it installs is aston.

From source

# 1. Clone
git clone https://github.com/2022n02511-stack/ASTon.git
cd ASTon

# 2. Install the project
pip install -e .

# 3. Install dependencies if needed
pip install -r requirements.txt

# 4. Verify the CLI works
aston --help

Then configure the environment variables required by your selected LLM provider and GitHub integration. A template is provided in .env.example.

External requirements: Docker must be installed and running, and you need an API key for your LLM provider and a GitHub token for pull requests. Installing the package does not provide these.

Design principles

Current scope & roadmap

ASTon is under active development. The current implementation focuses on Python dependency migrations, with the OpenAI Python SDK as the test case demonstrated above. It has been run end to end on one demo project so far.

The architecture separates ingestion, rule extraction, repository analysis, code generation, verification, and delivery, so more packages can be supported without tying the system to one library.

• Dependency watching
• Documentation ingestion & rule extraction
• AST-based repository usage mapping
• Docker-isolated per-file verification with repair
• Full-repository verification
• GitHub pull request creation
• Version-aware rule validation across more version chains (in progress)
• Reliability across more real-world repositories
• Support for additional Python packages
• pip install astoncli distribution
• Broader language ecosystem support

FAQ & troubleshooting

Contributing

Contributions, feedback, and ideas are welcome!

If you hit a migration issue, please include:

• The dependency and source version
• The target version
• The affected code
• The migration report or verification output

These details make problems far easier to reproduce and investigate.