astoncli 0.1.0__py3-none-any.whl

aston/poller.py

@@ -0,0 +1,201 @@
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from packaging.requirements import Requirement
+from packaging.version import InvalidVersion, Version
+from aston.ingestion import get_latest_pypi_version
+from aston.cli.console import info, error, warning, rich_success
+from aston.exceptions import ConfigurationError
+
+
+MAX_WORKERS = 10
+
+
+def is_major_version_change(
+    current_version: str,
+    target_version: str,
+) -> bool:
+    """Return whether the target crosses a major-version boundary."""
+    try:
+        current = Version(current_version)
+        target = Version(target_version)
+
+        # For pre-1.0 packages, minor releases can introduce breaking changes.
+        if current.major == 0 and target.major == 0:
+            return target.minor > current.minor
+
+        return target.major > current.major
+
+    except InvalidVersion:
+        return False
+
+
+def _check_package(
+    line: str,
+) -> tuple[str, str | None, str | None, str | None] | None:
+    """Fetch the latest PyPI version for one requirement."""
+    line = line.strip()
+
+    if not line or line.startswith("#") or line.startswith("-"):
+        return None
+
+    try:
+        req = Requirement(line)
+        package_name = req.name
+
+        # Exact pins are the most reliable declared-version baseline.
+        # For ranges, choose a lower bound when available.
+        declared_version = None
+
+        for spec in req.specifier:
+            if spec.operator == "==":
+                declared_version = spec.version
+                break
+
+        if declared_version is None:
+            lower_bounds = [
+                spec.version
+                for spec in req.specifier
+                if spec.operator in (">=", "~=")
+            ]
+            if lower_bounds:
+                declared_version = lower_bounds[0]
+
+        latest_version = get_latest_pypi_version(package_name)
+
+        if latest_version is None:
+            return package_name, declared_version, None, "PyPI lookup failed"
+
+        # Validate the version returned by the registry.
+        Version(latest_version)
+
+        return package_name, declared_version, latest_version, None
+
+    except (InvalidVersion, ValueError) as exc:
+        return line, None, None, f"Invalid requirement/version: {exc}"
+    except Exception as exc:
+        return line, None, None, str(exc)
+
+
+def watcher(repo_path: str | Path) -> None:
+    """
+    Check requirements against PyPI and report potential major-version changes.
+
+    This is a one-time check, not a continuously running polling loop.
+    """
+    repo_dir = Path(repo_path).expanduser().resolve()
+    req_file = repo_dir / "requirements.txt"
+
+    if not req_file.is_file():
+        raise ConfigurationError(
+            message=f"No requirements.txt found in repository path: {repo_dir}",
+            details="Ensure the target directory contains a valid requirements.txt file before running the watcher."
+        )
+
+    try:
+        lines = req_file.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise ConfigurationError(
+            message=f"Could not read requirements file: {req_file}",
+            details=str(exc)
+        ) from exc
+
+    # Ignore blank lines, comments, and pip directives.
+    requirement_lines = [
+        line for line in lines
+        if line.strip() and not line.strip().startswith(("#", "-"))
+    ]
+
+    if not requirement_lines:
+        warning("No package requirements found.")
+        return
+
+    info(
+        f"Checking {len(requirement_lines)} requirement lines "
+        f"for {repo_dir}..."
+    )
+
+    results = []
+    failures = []
+
+    with ThreadPoolExecutor(max_workers=MAX_WORKERS) as executor:
+        futures = {
+            executor.submit(_check_package, line): line
+            for line in requirement_lines
+        }
+
+        total = len(futures)
+
+        for completed, future in enumerate(as_completed(futures), start=1):
+            try:
+                result = future.result()
+                if result:
+                    package, declared, latest, error_message = result
+
+                    if error_message:
+                        failures.append((package, error_message))
+                    else:
+                        results.append((package, declared, latest))
+
+            except Exception as exc:
+                failures.append((futures[future], str(exc)))
+
+            info(f"Progress: {completed}/{total} requirement lines")
+
+    info("")
+
+    breaking_changes = []
+    unpinned = []
+
+    for package, declared, latest in results:
+        if not declared:
+            unpinned.append(package)
+            info(
+                f"{package}: latest version is {latest}; "
+                "no exact declared version is available for comparison."
+            )
+            continue
+
+        try:
+            current = Version(declared)
+            target = Version(latest)
+        except InvalidVersion:
+            failures.append((package, "Could not compare versions"))
+            continue
+
+        if target <= current:
+            continue
+
+        if is_major_version_change(str(current), str(target)):
+            breaking_changes.append((package, str(current), str(target)))
+            warning(
+                f"Potential breaking upgrade: {package} "
+                f"{current} -> {target}"
+            )
+
+    if failures:
+        error(f"{len(failures)} package lookup(s) failed:")
+        for package, error_message in failures:
+            error(f"- {package}: {error_message}")
+
+    if breaking_changes:
+        warning(
+            "Potential major-version changes found. "
+            "A major version change does not guarantee a breaking change."
+        )
+        info(
+            "Review the migration before running: "
+            f'aston check --run --path "{repo_dir}"'
+        )
+    elif failures:
+        warning(
+            "Check incomplete: some packages could not be checked. "
+            "Do not treat this result as confirmation of compatibility."
+        )
+    else:
+        rich_success("No newer major-version changes detected.")
+
+    if unpinned:
+        warning(
+            f"{len(unpinned)} package(s) lack a usable version "
+            "baseline; their compatibility could not be established."
+        )

aston/relevance.py

@@ -0,0 +1,175 @@
+import re
+
+def normalize_api_symbol(symbol: str) -> str:
+    """
+    Normalize formatting without changing Python identifier casing.
+    """
+    if not isinstance(symbol, str):
+        return ""
+
+    symbol = symbol.strip()
+
+    if symbol.endswith("()"):
+        symbol = symbol[:-2]
+
+    return symbol
+
+
+def canonicalize_usage(record: dict) -> str:
+    """
+    Convert a locally aliased API usage to its fully qualified form,
+    correctly resolving from-imports using the explicit 'imported' field.
+    """
+    package = record.get("package")
+    alias = record.get("local_alias")
+    imported = record.get("imported")
+    usage = record.get("api_usage", "")
+
+    if not isinstance(usage, str):
+        return ""
+
+    if alias and usage.startswith(alias + "."):
+        if imported:
+            return imported + usage[len(alias):]
+        elif package:
+            return package + usage[len(alias):]
+
+    return usage
+
+
+def determine_expected_affected_symbols(
+    stage0_symbols: set[str],
+    migration_doc_text: str,
+) -> set[str]:
+    """
+    Find scanned symbols explicitly referenced in the migration text.
+    """
+    expected = set()
+    doc_lower = (migration_doc_text or "").lower()
+
+    for symbol in stage0_symbols:
+        normalized = normalize_api_symbol(symbol)
+        if not normalized:
+            continue
+
+        parts = normalized.split(".")
+        short_name = ".".join(parts[-2:])
+
+        if (
+            normalized.lower() in doc_lower
+            or short_name.lower() in doc_lower
+        ):
+            expected.add(normalized)
+
+    return expected
+
+
+def find_longest_prefix_match(symbol: str, rules_dict: dict) -> list[dict]:
+    """
+    Find matching rules using longest-prefix matching.
+    E.g., rule for 'openai.ChatCompletion' will match 'openai.ChatCompletion.create'.
+    """
+    # Sort old_apis by length descending so longer/more specific prefixes match first
+    sorted_old_apis = sorted(rules_dict.keys(), key=len, reverse=True)
+    for old_api in sorted_old_apis:
+        if symbol == old_api or symbol.startswith(old_api + "."):
+            return rules_dict[old_api]
+    return []
+
+
+def evaluate_relevance_and_completeness(
+    stage0_symbols: set[str],
+    extracted_records: list[dict],
+    migration_doc_text: str,
+) -> dict:
+    """
+    Evaluate migration-rule coverage using longest-prefix matching and
+    strict validated-only target sets.
+    """
+    observed_symbols = {
+        normalize_api_symbol(symbol)
+        for symbol in stage0_symbols
+        if normalize_api_symbol(symbol)
+    }
+
+    # Index extracted rules by old API
+    old_to_records = {}
+    validated_target_apis = set()
+
+    auto_migration_statuses = {"validated", "valid"}
+
+    for record in extracted_records or []:
+        old_api = normalize_api_symbol(record.get("old_api", ""))
+        new_api = normalize_api_symbol(record.get("new_api", ""))
+        status = str(record.get("validation_status", "")).strip().lower()
+
+        if old_api:
+            old_to_records.setdefault(old_api, []).append(record)
+
+        # Item 8: Build known target APIs ONLY from validated rules
+        if new_api and status in auto_migration_statuses:
+            validated_target_apis.add(new_api)
+
+    relevant_records = []
+    review_records = []
+    directly_covered_symbols = set()
+    review_covered_symbols = set()
+
+    for symbol in observed_symbols:
+        matching_records = find_longest_prefix_match(symbol, old_to_records)
+        if not matching_records:
+            continue
+
+        for record in matching_records:
+            status = str(record.get("validation_status", "")).strip().lower()
+
+            if status in auto_migration_statuses:
+                relevant_records.append({
+                    **record,
+                    "old_api": normalize_api_symbol(record.get("old_api", "")),
+                })
+                directly_covered_symbols.add(symbol)
+            else:
+                review_records.append({
+                    **record,
+                    "old_api": normalize_api_symbol(record.get("old_api", "")),
+                })
+                review_covered_symbols.add(symbol)
+
+    # Item 8: Target compatibility established strictly from validated rules
+    known_target_symbols = observed_symbols & validated_target_apis
+
+    expected_affected_symbols = determine_expected_affected_symbols(
+        observed_symbols,
+        migration_doc_text,
+    )
+
+    uncovered_symbols = (
+        observed_symbols
+        - directly_covered_symbols
+        - known_target_symbols
+    )
+
+    missing_documented_symbols = (
+        expected_affected_symbols
+        - directly_covered_symbols
+        - known_target_symbols
+    )
+
+    is_complete = (
+        not uncovered_symbols
+        and not review_covered_symbols
+    )
+
+    return {
+        "is_complete": is_complete,
+        "observed_symbols": sorted(observed_symbols),
+        "expected_affected_symbols": sorted(expected_affected_symbols),
+        "directly_covered_symbols": sorted(directly_covered_symbols),
+        "already_target_symbols": sorted(known_target_symbols),
+        "review_covered_symbols": sorted(review_covered_symbols),
+        "uncovered_symbols": sorted(uncovered_symbols),
+        "missing_symbols": sorted(missing_documented_symbols),
+        "relevant_records": relevant_records,
+        "review_records": review_records,
+    }

aston/repo_verification.py

@@ -0,0 +1,243 @@
+import subprocess
+from pathlib import Path
+import shlex
+import shutil
+import tempfile
+
+
+def verify_full_repo_in_docker(
+    repo_root: str,
+    migrated_files_path: str | Path,
+    req_file: str | Path,
+    *,
+    python_image: str = "python:3.11-slim",
+    timeout: int = 300,
+    test_command: str = "python -m pytest -q",
+) -> dict:
+    """Verify the migrated repository inside an isolated Docker container."""
+
+    repo_path = Path(repo_root).resolve()
+    migration_path = Path(migrated_files_path).resolve()
+    requirements_path = Path(req_file).resolve()
+
+    if not repo_path.is_dir():
+        return {
+            "status": "INVALID_REPO",
+            "success": False,
+            "exit_code": None,
+            "stdout": "",
+            "stderr": f"Repository directory not found: {repo_path}",
+        }
+
+    if not migration_path.is_dir():
+        return {
+            "status": "INVALID_MIGRATIONS",
+            "success": False,
+            "exit_code": None,
+            "stdout": "",
+            "stderr": f"Migrated files directory not found: {migration_path}",
+        }
+
+    if not requirements_path.is_file():
+        return {
+            "status": "INVALID_REQUIREMENTS",
+            "success": False,
+            "exit_code": None,
+            "stdout": "",
+            "stderr": f"Requirements file not found: {requirements_path}",
+        }
+
+    test_cmd = test_command.strip()
+
+    try:
+        with tempfile.TemporaryDirectory(prefix="aston_verify_") as temp_dir:
+
+            verification_repo = Path(temp_dir) / "repo"
+
+            # 1. Copy the original repository.
+            shutil.copytree(
+                repo_path,
+                verification_repo,
+                ignore=shutil.ignore_patterns(
+                    ".git",
+                    ".venv",
+                    "venv",
+                    "__pycache__",
+                    ".pytest_cache",
+                ),
+            )
+
+            # 2. Overlay migrated files, preserving their relative paths.
+            for migrated_file in migration_path.rglob("*"):
+
+                if not migrated_file.is_file():
+                    continue
+
+                relative_path = migrated_file.relative_to(migration_path)
+
+                # Requirements are handled separately below.
+                if relative_path.as_posix() == "requirements.txt":
+                    continue
+
+                destination = verification_repo / relative_path
+                destination.parent.mkdir(parents=True, exist_ok=True)
+
+                shutil.copy2(migrated_file, destination)
+
+            # 3. Replace requirements with the target requirements.
+            shutil.copy2(
+                requirements_path,
+                verification_repo / "requirements.txt",
+            )
+
+            # 4. Run the assembled repository inside Docker.
+            script = f"""
+export PIP_CACHE_DIR=/root/.cache/pip
+set -eu
+
+echo "--- [Verification] Installing requirements ---"
+python -m pip install --disable-pip-version-check -r /app/requirements.txt ||
+    {{ echo "ASTON_SETUP_FAILED"; exit 20; }}
+"""
+
+            if test_cmd:
+                if "pytest" in test_cmd.lower():
+                    script += """
+echo "--- [Verification] Checking test runner ---"
+if ! python -c "import pytest" 2>/dev/null; then
+    python -m pip install --disable-pip-version-check pytest ||
+        { echo "ASTON_PYTEST_SETUP_FAILED"; exit 23; }
+fi
+"""
+
+            script += """
+echo "--- [Verification] Running AST syntax checks ---"
+python -c '
+import ast
+import sys
+from pathlib import Path
+
+root = Path("/app")
+
+excluded = {
+    ".git",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".pytest_cache",
+}
+
+errors = []
+
+for path in root.rglob("*.py"):
+    if any(part in excluded for part in path.parts):
+        continue
+
+    try:
+        ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    except (SyntaxError, UnicodeDecodeError, OSError) as exc:
+        errors.append((path, exc))
+
+for path, exc in errors:
+    print("Syntax error in {}: {}".format(path, exc), file=sys.stderr)
+
+sys.exit(1 if errors else 0)
+' || { echo "ASTON_SYNTAX_FAILED"; exit 21; }
+"""
+
+            if test_cmd:
+                if "pytest" in test_cmd.lower():
+                    script += f"""
+echo "--- [Verification] Running test suite ---"
+set +e
+export PYTEST_ADDOPTS="${{PYTEST_ADDOPTS:-}} -p no:cacheprovider"
+{test_cmd}
+test_status=$?
+set -e
+
+if [ "$test_status" -eq 5 ]; then
+    echo "ASTON_TESTS_SKIPPED_NO_TESTS: pytest collected no tests."
+elif [ "$test_status" -ne 0 ]; then
+    echo "ASTON_TESTS_FAILED: exit code $test_status"
+    exit 22
+else
+    echo "ASTON_TESTS_PASSED"
+fi
+"""
+                else:
+                    script += f"""
+echo "--- [Verification] Running test suite ---"
+{test_cmd} ||
+    {{ echo "ASTON_TESTS_FAILED"; exit 22; }}
+"""
+
+            script += """
+echo "ASTON_VERIFICATION_PASSED"
+"""
+
+            docker_cmd = [
+                "docker", "run", "--rm",
+                "-v", f"{verification_repo}:/app:ro,Z",
+                "-v", "aston-pip-cache:/root/.cache/pip",
+                "--workdir", "/app",
+                python_image,
+                "sh", "-c", script,
+            ]
+
+            result = subprocess.run(
+                docker_cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+
+            output = result.stdout + "\n" + result.stderr
+
+            if result.returncode == 0 and "ASTON_VERIFICATION_PASSED" in output:
+                status = "PASS"
+            elif "ASTON_SETUP_FAILED" in output:
+                status = "SETUP_ERROR"
+            elif "ASTON_PYTEST_SETUP_FAILED" in output:
+                status = "SETUP_ERROR"
+            elif "ASTON_SYNTAX_FAILED" in output:
+                status = "SYNTAX_ERROR"
+            elif "ASTON_TESTS_FAILED" in output:
+                status = "TEST_FAILED"
+            else:
+                status = "DOCKER_ERROR"
+
+            return {
+                "status": status,
+                "success": status == "PASS",
+                "exit_code": result.returncode,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+            }
+
+    except subprocess.TimeoutExpired as exc:
+        stdout = exc.stdout or ""
+        stderr = exc.stderr or "Repository verification timed out."
+
+        if isinstance(stdout, bytes):
+            stdout = stdout.decode("utf-8", errors="replace")
+
+        if isinstance(stderr, bytes):
+            stderr = stderr.decode("utf-8", errors="replace")
+
+        return {
+            "status": "TIMEOUT",
+            "success": False,
+            "exit_code": None,
+            "stdout": stdout,
+            "stderr": stderr,
+        }
+
+    except OSError as exc:
+        return {
+            "status": "DOCKER_ERROR",
+            "success": False,
+            "exit_code": None,
+            "stdout": "",
+            "stderr": str(exc),
+        }