astoncli 0.1.0__py3-none-any.whl

aston/rule_validation.py

@@ -0,0 +1,437 @@
+"""Validate extracted migration rules against a target dependency environment.
+Documentation evidence and runtime API probing are deliberately tracked
+separately: finding an attribute in the target package does not prove that a
+migration rule is semantically correct.
+"""
+
+from __future__ import annotations
+import json
+import subprocess
+import tempfile
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+
+def _mark_unprobed(rule: dict[str, Any], reason: str) -> dict[str, Any]:
+    """Mark a rule as not runtime-validated without discarding its evidence."""
+    rule["target_api_status"] = "unprobed"
+    rule["validation_status"] = "not_validated"
+    rule["resolution_reason"] = reason
+    return rule
+
+
+def _mark_pending_as_failed(
+    rules: list[dict[str, Any]],
+    reason: str,
+    *,
+    status: str = "probe_failed",
+) -> list[dict[str, Any]]:
+    """Give every rule whose API probe did not finish an explicit outcome."""
+    for rule in rules:
+        if rule.get("target_api_status") == "pending":
+            rule["target_api_status"] = status
+            rule["validation_status"] = "unverifiable"
+            rule["resolution_reason"] = reason
+    return rules
+
+
+def validate_all_rules(
+    all_rules: list[dict[str, Any]],
+    all_target_versions: dict[str, str],
+    req_file: str | Path,
+    distribution_names: dict[str, str] | None = None,
+    *,
+    python_image: str = "python:3.11-slim",
+    timeout: int = 600,
+) -> list[dict[str, Any]]:
+    """Validate shared rules once per import-package/target-version group.
+
+    Args:
+        all_rules: Extracted migration rules. Each rule should include
+            ``package`` (the Python import name), ``old_api`` and ``new_api``.
+        all_target_versions: Target versions keyed by Python import name.
+        req_file: Requirements file used to build the validation environment.
+        distribution_names: Optional mapping from Python import names to pip
+            distribution names, e.g. ``{"yaml": "PyYAML"}``.
+        python_image: Docker image used for validation.
+        timeout: Maximum seconds allowed for each Docker validation run.
+
+    Returns:
+        A new list of rules with runtime-probe results attached. Input rule
+        dictionaries are not mutated in place.
+    """
+    distribution_names = distribution_names or {}
+    req_path = Path(req_file).expanduser().resolve()
+    groups: dict[tuple[str, str], list[tuple[int, dict[str, Any]]]] = defaultdict(list)
+    result_by_index: dict[int, dict[str, Any]] = {}
+
+    for index, original in enumerate(all_rules):
+        rule = dict(original)
+        # Keep the original documentation/rule assessment separate from the
+        # result of probing whether the destination API exists at runtime.
+        rule.setdefault("evidence_status", "unknown")
+        rule.setdefault("chain_status", "unresolved")
+        rule.setdefault("verification_status", "not_run")
+        rule["documentation_validation_status"] = rule.get(
+            "documentation_validation_status",
+            rule.get("validation_status", "not_validated"),
+        )
+        rule.setdefault("target_api_status", "unprobed")
+
+        package = rule.get("package")
+        if not package:
+            result_by_index[index] = _mark_unprobed(
+                rule, "Rule has no package identifier"
+            )
+            continue
+
+        target_version = all_target_versions.get(package)
+        if not target_version:
+            result_by_index[index] = _mark_unprobed(
+                rule, f"No target version configured for import package {package}"
+            )
+            continue
+
+        groups[(package, str(target_version))].append((index, rule))
+
+    for (package, target_version), indexed_rules in groups.items():
+        validated = validate_rules_against_target(
+            rules=[rule for _, rule in indexed_rules],
+            pkg_name=package,
+            target_version=target_version,
+            all_target_versions=all_target_versions,
+            req_file=req_path,
+            distribution_name=distribution_names.get(package),
+            distribution_names=distribution_names,
+            python_image=python_image,
+            timeout=timeout,
+        )
+
+        if len(validated) != len(indexed_rules):
+            raise RuntimeError(
+                f"Rule validator returned {len(validated)} rules for "
+                f"{len(indexed_rules)} inputs for {package}=={target_version}. "
+                "Refusing to silently pass unvalidated rules downstream."
+            )
+
+        for (original_index, _), validated_rule in zip(indexed_rules, validated):
+            result_by_index[original_index] = validated_rule
+
+    # Preserve original ordering, including rules that could not be grouped.
+    return [result_by_index[index] for index in range(len(all_rules))]
+
+
+def reconcile_report(
+    extraction_report: dict[str, Any],
+    validated_rules: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Return an extraction report whose rules and counts match validation."""
+    report = dict(extraction_report)
+    report["rules"] = validated_rules
+    report["total_rules"] = len(validated_rules)
+
+    report["target_api_exists"] = sum(
+        rule.get("target_api_status") == "target_api_exists"
+        for rule in validated_rules
+    )
+    report["target_api_missing"] = sum(
+        rule.get("target_api_status") == "target_api_missing"
+        for rule in validated_rules
+    )
+    report["unverifiable_rules"] = sum(
+        rule.get("target_api_status") in {
+            "unverifiable",
+            "probe_failed",
+            "unprobed",
+        }
+        for rule in validated_rules
+    )
+    report["not_probed_rules"] = sum(
+        rule.get("target_api_status") in {"pending", "unprobed"}
+        for rule in validated_rules
+    )
+    report["documentation_validated_rules"] = sum(
+        rule.get("documentation_validation_status") == "validated"
+        for rule in validated_rules
+    )
+    return report
+
+
+def validate_rules_against_target(
+    rules: list[dict[str, Any]],
+    pkg_name: str,
+    target_version: str,
+    all_target_versions: dict[str, str] | None = None,
+    req_file: str | Path = "temp_requirements.txt",
+    distribution_name: str | None = None,
+    distribution_names: dict[str, str] | None = None,
+    python_image: str = "python:3.11-slim",
+    timeout: int = 600,
+) -> list[dict[str, Any]]:
+    """Probe candidate destination APIs in an isolated target-version env.
+
+    ``pkg_name`` and rule ``package`` values are Python import names.
+    ``distribution_names`` maps those import names to pip distribution names.
+    """
+    req_path = Path(req_file).expanduser().resolve()
+    distribution_names = dict(distribution_names or {})
+    if distribution_name:
+        distribution_names.setdefault(pkg_name, distribution_name)
+    all_target_versions = dict(all_target_versions or {pkg_name: target_version})
+
+    prepared_rules: list[dict[str, Any]] = []
+    for original in rules:
+        rule = dict(original)
+        rule.setdefault("evidence_status", "unknown")
+        rule.setdefault("chain_status", "unresolved")
+        rule.setdefault("verification_status", "not_run")
+        rule["documentation_validation_status"] = rule.get(
+            "documentation_validation_status",
+            rule.get("validation_status", "not_validated"),
+        )
+
+        candidate = rule.get("candidate_new_api") or rule.get("new_api")
+        rule["candidate_new_api"] = candidate
+
+        if not isinstance(candidate, str) or not candidate.strip() or "UNRESOLVED" in candidate.upper():
+            rule["target_api_status"] = "unverifiable"
+            rule["validation_status"] = "not_validated"
+            rule["resolution_reason"] = (
+                rule.get("resolution_reason") or "No documented replacement API"
+            )
+        else:
+            rule["target_api_status"] = "pending"
+            # Do not overwrite documentation_validation_status here.
+            rule["validation_status"] = "pending"
+        prepared_rules.append(rule)
+
+    if not prepared_rules:
+        return []
+
+    if not req_path.is_file():
+        return _mark_pending_as_failed(
+            prepared_rules,
+            f"Requirements file not found: {req_path}",
+            status="unprobed",
+        )
+
+    # The worker installs distribution names but imports and probes Python
+    # import names. The version map sent to it is keyed by distribution name.
+    install_version_map: dict[str, str] = {}
+    for import_name, version in all_target_versions.items():
+        dist_name = distribution_names.get(import_name, import_name)
+        if dist_name in install_version_map and install_version_map[dist_name] != version:
+            raise ValueError(
+                f"Conflicting target versions for distribution {dist_name!r}: "
+                f"{install_version_map[dist_name]!r} and {version!r}"
+            )
+        install_version_map[dist_name] = str(version)
+
+    worker_script = r'''\
+import importlib
+import json
+import subprocess
+import sys
+
+requirements_path, import_name, version_map_json, rules_path = sys.argv[1:5]
+version_map = json.loads(version_map_json)
+
+
+def install(args):
+    result = subprocess.run(
+        [sys.executable, "-m", "pip", "install", *args],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode:
+        raise RuntimeError("pip install failed:\\n" + result.stderr[-12000:])
+
+
+def resolve_attribute(root, path):
+    current = root
+    for part in path.split("."):
+        if not part:
+            raise AttributeError("Empty attribute in API path")
+        current = getattr(current, part)
+    return current
+
+
+def probe_api(module, api):
+    if not isinstance(api, str) or not api.strip():
+        return "unverifiable", "No usable candidate API"
+    api = api.strip()
+
+    # Generic probing cannot instantiate arbitrary client objects safely.
+    if api.startswith("client."):
+        return "unverifiable", "Instance-based API requires a package-specific adapter"
+
+    if api == import_name:
+        path = ""
+    elif api.startswith(import_name + "."):
+        path = api[len(import_name) + 1:]
+    else:
+        path = api
+
+    if not path:
+        return "exists", "Package module imported successfully"
+
+    try:
+        resolve_attribute(module, path)
+        return "exists", "Destination attribute resolved"
+    except (AttributeError, ImportError, ModuleNotFoundError) as exc:
+        return "missing", f"{type(exc).__name__}: {exc}"
+    except Exception as exc:
+        return "unverifiable", f"{type(exc).__name__}: {exc}"
+
+
+try:
+    # Install the project's base environment, then pin all target distributions.
+    install(["-r", requirements_path])
+    upgrade_args = ["--upgrade", "--upgrade-strategy", "only-if-needed"]
+    for dist_name, version in version_map.items():
+        upgrade_args.append(f"{dist_name}=={version}")
+    install(upgrade_args)
+
+    check = subprocess.run(
+        [sys.executable, "-m", "pip", "check"],
+        capture_output=True,
+        text=True,
+    )
+    if check.returncode:
+        print(json.dumps({
+            "environment_status": "dependency_conflict",
+            "details": (check.stdout + "\\n" + check.stderr)[-12000:],
+            "rules": [],
+        }))
+        sys.exit(0)
+
+    try:
+        module = importlib.import_module(import_name)
+    except Exception as exc:
+        print(json.dumps({
+            "environment_status": "import_failed",
+            "details": f"{type(exc).__name__}: {exc}",
+            "rules": [],
+        }))
+        sys.exit(0)
+
+    with open(rules_path, encoding="utf-8") as file:
+        rules = json.load(file)
+
+    results = []
+    for index, rule in enumerate(rules):
+        candidate = rule.get("candidate_new_api") or rule.get("new_api")
+        if not isinstance(candidate, str) or not candidate.strip() or "UNRESOLVED" in candidate.upper():
+            results.append({
+                "index": index,
+                "status": "unverifiable",
+                "reason": "No documented replacement API",
+            })
+            continue
+        status, reason = probe_api(module, candidate)
+        results.append({"index": index, "status": status, "reason": reason})
+
+    print(json.dumps({"environment_status": "ready", "rules": results}))
+except Exception as exc:
+    print(json.dumps({
+        "environment_status": "install_failed",
+        "details": f"{type(exc).__name__}: {exc}",
+        "rules": [],
+    }))
+'''
+
+    with tempfile.TemporaryDirectory(prefix="aston-validation-") as tmp:
+        temp_dir = Path(tmp)
+        script_path = temp_dir / "validate.py"
+        rules_path = temp_dir / "rules.json"
+        script_path.write_text(worker_script, encoding="utf-8")
+        rules_path.write_text(json.dumps(prepared_rules), encoding="utf-8")
+
+        command = [
+            "docker", "run", "--rm",
+            "-v", f"{req_path.parent}:/project:ro",
+            "-v", f"{temp_dir}:/work:ro",
+            "-w", "/work",
+            python_image,
+            "python", "/work/validate.py",
+            f"/project/{req_path.name}",
+            pkg_name,
+            json.dumps(install_version_map),
+            "/work/rules.json",
+        ]
+
+        try:
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            return _mark_pending_as_failed(
+                prepared_rules, f"Validation timed out after {timeout} seconds"
+            )
+        except OSError as exc:
+            return _mark_pending_as_failed(
+                prepared_rules, f"Could not start Docker validation: {exc}"
+            )
+
+        if result.returncode != 0:
+            details = (result.stderr or result.stdout or "No Docker output")[-4000:]
+            return _mark_pending_as_failed(
+                prepared_rules, f"Docker validation failed: {details}"
+            )
+
+        try:
+            report = json.loads(result.stdout.strip().splitlines()[-1])
+        except (IndexError, json.JSONDecodeError):
+            return _mark_pending_as_failed(
+                prepared_rules, "Could not parse Docker validation report"
+            )
+
+    if report.get("environment_status") != "ready":
+        details = report.get("details", report.get("environment_status", "unknown error"))
+        return _mark_pending_as_failed(prepared_rules, str(details))
+
+    seen_indices: set[int] = set()
+    for item in report.get("rules", []):
+        index = item.get("index")
+        if not isinstance(index, int) or not 0 <= index < len(prepared_rules):
+            continue
+        seen_indices.add(index)
+        rule = prepared_rules[index]
+        status = item.get("status", "unverifiable")
+        reason = str(item.get("reason", "No probe explanation supplied"))
+        documentation_status = rule.get(
+            "documentation_validation_status", "not_validated"
+        )
+
+        if status == "exists":
+            rule["target_api_status"] = "target_api_exists"
+            # Runtime existence is necessary but not sufficient for rule validity.
+            rule["validation_status"] = (
+                "validated" if documentation_status == "validated"
+                else documentation_status
+            )
+        elif status == "missing":
+            rule["target_api_status"] = "target_api_missing"
+            rule["validation_status"] = "needs_review"
+        else:
+            rule["target_api_status"] = "unverifiable"
+            rule["validation_status"] = (
+                "needs_review" if documentation_status == "validated"
+                else documentation_status
+            )
+
+        rule["resolution_reason"] = reason
+        rule["environment_status"] = "ready"
+
+    # A malformed/partial worker report must not leave any rule pending.
+    for index, rule in enumerate(prepared_rules):
+        if index not in seen_indices and rule.get("target_api_status") == "pending":
+            rule["target_api_status"] = "probe_failed"
+            rule["validation_status"] = "unverifiable"
+            rule["resolution_reason"] = "Rule missing from Docker validation report"
+
+    return prepared_rules

aston/scanner.py

@@ -0,0 +1,211 @@
+import ast
+import libcst as cst
+from libcst.display import dump
+from libcst.metadata import VisitorMetadataProvider, MetadataWrapper, PositionProvider, ParentNodeProvider
+from pathlib import Path
+from libcst import matchers as m
+import json
+import jedi
+from typing import Sequence
+import hashlib
+
+class Tracker(VisitorMetadataProvider):
+    METADATA_DEPENDENCIES = (PositionProvider, ParentNodeProvider)
+
+    def __init__(self, relative_path: str, code_text: str, file_path: Path | None = None):
+        super().__init__()
+        self.relative_path = relative_path
+        self.code_text = code_text
+        self.code_lines = code_text.splitlines()
+        self.file_path = file_path
+        self._jedi_script = None  
+        
+        self.usages = []
+        self.symbols = {}
+        self.imports = []
+        self.local_calls = []  
+        self.scope_stack = []
+        self.local_imports = {}
+        self.current_func_params = set()
+
+    @property
+    def jedi_script(self):
+        if self._jedi_script is None:
+            if self.file_path and self.file_path.exists():
+                self._jedi_script = jedi.Script(path=str(self.file_path))
+            else:
+                self._jedi_script = jedi.Script(self.code_text)
+        return self._jedi_script
+
+    def visit_ImportFrom(self, node: cst.ImportFrom) -> None:
+        if node.module and not isinstance(node.names, cst.ImportStar):
+            pkg = cst.Module([]).code_for_node(node.module).strip()
+            for alias in node.names:
+                imported_name = alias.name.value
+                local_alias = alias.asname.name.value if alias.asname else imported_name
+                self.local_imports[local_alias] = {"package": pkg, "imported": imported_name}
+                
+                self.imports.append({
+                    "module": pkg,
+                    "imported_name": imported_name,
+                    "alias": alias.asname.name.value if alias.asname else None,
+                    "line": self.get_metadata(PositionProvider, node).start.line,
+                    "import_type": "from_import"
+                })
+
+    def visit_Import(self, node: cst.Import) -> None:
+        for alias in node.names:
+            pkg = cst.Module([]).code_for_node(alias.name).strip()
+            local_alias = alias.asname.name.value if alias.asname else pkg
+            self.local_imports[local_alias] = {"package": pkg, "imported": pkg}
+            
+            self.imports.append({
+                "module": pkg,
+                "imported_name": None,
+                "alias": alias.asname.name.value if alias.asname else None,
+                "line": self.get_metadata(PositionProvider, node).start.line,
+                "import_type": "module"
+            })
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> None:
+        func_name = node.name.value
+        pos = self.get_metadata(PositionProvider, node)
+        params = [param.name.value for param in node.params.params]
+        
+        symbol_key = f"{self.relative_path}::{func_name}"
+        self.symbols[symbol_key] = {
+            "file": self.relative_path,
+            "qualified_name": func_name,
+            "kind": "function",
+            "line_start": pos.start.line,
+            "line_end": pos.end.line,
+            "parameters": params,
+            "reach": "unknown",
+            "watched_usage_ids": []
+        }
+        self.scope_stack.append(func_name)
+        self.current_func_params = set(params)
+
+    def leave_FunctionDef(self, node: cst.FunctionDef) -> None:
+        if self.scope_stack:
+            self.scope_stack.pop()
+        self.current_func_params = set()
+
+    def _get_result_use(self, node: cst.Call) -> str:
+        current = node
+        while True:
+            parent = self.get_metadata(ParentNodeProvider, current)
+            if parent is None:
+                return "discarded"
+            if isinstance(parent, cst.Return):
+                return "returned"
+            if isinstance(parent, cst.Assign):
+                return "assigned"
+            if isinstance(parent, cst.Arg):
+                return "argument"
+            if isinstance(parent, cst.Expr):
+                return "discarded"
+            current = parent
+
+    def visit_Call(self, node: cst.Call) -> None:
+        pos = self.get_metadata(PositionProvider, node)
+        line = pos.start.line
+        col = pos.start.column
+        end_line = pos.end.line
+        end_col = pos.end.column
+        
+        call_expr = cst.Module([]).code_for_node(node.func).strip()
+        enclosing_symbol = self.scope_stack[-1] if self.scope_stack else None
+
+        # 1. Capture local / parameter call sites (strictly Name nodes like ask_assistant() or postprocess())
+        if enclosing_symbol and isinstance(node.func, cst.Name):
+            callee_name = node.func.value
+            self.local_calls.append({
+                "source_file": self.relative_path,
+                "source_symbol": enclosing_symbol,
+                "callee_name": callee_name,
+                "line": line,
+                "column": col,
+                "end_line": end_line,
+                "end_column": end_col,
+                "is_parameter": callee_name in self.current_func_params
+            })
+
+        # 2. Target external API usage tracking (Attribute nodes like openai.ChatCompletion.create)
+        if not isinstance(node.func, cst.Attribute):
+            return
+
+        root_name = call_expr.split(".")[0]
+        package = None
+        imported = None
+
+        if root_name in self.local_imports:
+            package = self.local_imports[root_name]["package"]
+            imported = self.local_imports[root_name]["imported"]
+
+        if not package:
+            try:
+                defs = self.jedi_script.goto(line=line, column=col) or self.jedi_script.infer(line=line, column=col)
+                if defs:
+                    target = defs[0]
+                    if target.module_name and target.module_name not in ("builtins", "__main__"):
+                        package = target.module_name
+                        imported = target.name
+            except Exception:
+                pass
+
+        if package and ("openai" in package or "openai" in call_expr):
+            usage_id = f"{self.relative_path}:{line}:{col}"
+            result_use = self._get_result_use(node)
+
+            kwargs = {}
+            for arg in node.args:
+                if arg.keyword:
+                    kwargs[arg.keyword.value] = cst.Module([]).code_for_node(arg.value).strip()
+
+            self.usages.append({
+                "id": usage_id,
+                "package": package,
+                "imported": imported,
+                "local_alias": root_name,
+                "api_usage": call_expr,
+                "result_use": result_use,
+                "enclosing_symbol": enclosing_symbol,
+                "line": line,
+                "column": col,
+                "end_line": end_line,
+                "end_column": end_col,
+                "usage_kind": "call",
+                "kwargs": kwargs
+            })
+             
+
+
+def parser(path: str | Path, relative_path: str, project: jedi.Project | None = None):
+
+    path = Path(path)
+    if not path.exists():
+        path = Path("before.py")
+
+    code_text = path.read_text(encoding="utf-8")
+    file_hash = hashlib.sha256(code_text.encode("utf-8")).hexdigest()
+    
+    module = cst.parse_module(code_text)
+    visitor = Tracker(relative_path=relative_path, code_text=code_text, file_path=path)
+    wrapper = cst.metadata.MetadataWrapper(module)
+    wrapper.visit(visitor)
+
+    return {
+        "file_meta": {
+            "path": relative_path,
+            "sha256": file_hash,
+            "parse_status": "success"
+        },
+        "imports": visitor.imports,
+        "usages": visitor.usages,
+        "symbols": visitor.symbols,
+        "local_calls": visitor.local_calls,
+        "diagnostics": []
+    }
+
+# parser()