astoncli 0.1.0

1. The problem ASTon solves
2. Quick start
3. ASTon migration demonstration
4. How it works
5. The 10 stages in detail
6. Command reference
7. Run the complete workflow
8. Example migration
9. Project architecture
10. Generated files and directories
11. Installation
12. Design principles
13. Current scope & roadmap
14. FAQ & troubleshooting
15. Contributing

• Python installed
• Docker installed and running
• Git installed
• GitHub access (for PR creation)
• API key for your configured LLM provider
• A local clone of the target repository (e.g. demo/)

Clone the demo project next to ASTon and run the same three commands from the quick start:

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

The demo project starts on the legacy openai==0.28.1 code, so it shows the same before-and-after the links above describe.

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"]

ASTon includes a watcher that monitors dependencies and identifies available updates.

Current dependency: openai==0.28.1
Available version:  3.41.0

It also keeps version-related state so previously processed updates can be tracked.

Run it:

aston watcher --path demo

When an update is detected, ASTon collects:

• Release notes
• Changelogs
• Migration guides
• Relevant documentation links
• Breaking-change discussions and references

It follows relevant links to gather extra migration context, so extraction doesn't rely on version numbers alone.

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"]

Documentation is written for humans. ASTon uses an LLM to convert it into structured migration rules:

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

Rules can describe:

• API renames
• Removed APIs
• Configuration changes
• New instantiation requirements
• Changes in how an API is accessed

Extracted rules are not automatically assumed to be applicable. They are evaluated against the target version first.

ASTon uses Python's Abstract Syntax Tree (AST) instead of plain text search.

from openai import OpenAI as Client

client = Client()

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

The scanner captures: imported package, imported symbol, local alias, instantiated objects, API usage, source line, and relevant keyword arguments.

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"]

A library can introduce hundreds of changes. Most won't touch your code.

The result is a smaller set of potentially relevant migration rules.

A rule that was valid for an earlier upgrade may not be valid for a later one.

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

Applying the first rule directly to a project targeting Version 2 would leave it on an outdated API. ASTon validates rules against the target version before code generation.

Rules that can't be validated are not silently treated as confirmed. They remain unresolved for further analysis.

# Before
import openai

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

# After
from openai import OpenAI

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

The output is a candidate, not an accepted result. It must pass verification.

Each migrated file is verified inside a Docker container with the target dependency installed. Verification distinguishes between:

• Successful migrations
• Migration errors
• Environment / dependency installation errors
• External service errors
• Timeouts

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

Repair process: the failed candidate plus its real verification feedback are used to attempt a better migration, not just repeat the same replacement. Successful files are saved to the migration output directory.

Passing per-file checks doesn't guarantee the whole project works (one migrated file may depend on another).

The verification environment combines:

• Original repository files that were not migrated
• Successfully migrated files
• Updated target requirements

Then it runs Python syntax checks and the configured test command.

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"]

The PR contains the migrated files and updated dependency requirements. The original source repository is kept separate from ASTon's output during migration, so you stay in control.

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"]

Options can vary between versions. Always confirm with aston <command> --help.

 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

No. Migration output is kept separate (in succ_migrations/) and only reaches your repo as a pull request that you review and merge.

Rules that can't be validated against the target version are never silently treated as confirmed. They stay unresolved so they can be analyzed further instead of risking an incorrect migration.

ASTon sends it through the repair loop, using the real failure output to generate a corrected candidate. Check artifacts/runs/ for each attempt and final_reports/ for the result.

ASTon separates environment, external-service, and timeout failures from true migration errors. Confirm that Docker is running and has network access, then re-run aston check --run --path demo.

Individual success doesn't guarantee cross-file compatibility. Review the verification report in final_reports/ to see whether syntax checks or your configured test command failed.

Check that:

• --repo points to a valid local clone of the target repository
• Your GitHub credentials/environment variables are configured
• --path points to aston/succ_migrations (the successful migration output)
• You have push access to the repository

Flags can differ between versions. Run aston --help and aston <command> --help to see what your installed version supports.