orphans 1.0.0__py3-none-any.whl

core/aliases.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+KNOWN_ALIASES: list[tuple[str, str]] = [
+    ("Pillow", "pil"),
+    ("PyYAML", "yaml"),
+    ("python-dateutil", "dateutil"),
+    ("python-dotenv", "dotenv"),
+    ("markdown-it-py", "markdown_it"),
+    ("paho-mqtt", "paho"),
+    ("influxdb-client", "influxdb_client"),
+    ("Pygments", "pygments"),
+    ("pyserial", "serial"),
+    ("cffi", "cffi"),
+    ("cryptography", "cryptography"),
+    ("certifi", "certifi"),
+    ("six", "six"),
+    ("rich", "rich"),
+    ("click", "click"),
+    ("fastapi", "fastapi"),
+    ("uvicorn", "uvicorn"),
+    ("numpy", "numpy"),
+    ("pydantic", "pydantic"),
+    ("starlette", "starlette"),
+    ("httptools", "httptools"),
+    ("uvloop", "uvloop"),
+    ("websockets", "websockets"),
+    ("watchfiles", "watchfiles"),
+    ("python-multipart", "python_multipart"),
+    ("aenum", "aenum"),
+    ("reactivex", "reactivex"),
+    ("reedsolo", "reedsolo"),
+    ("typing-extensions", "typing_extensions"),
+    ("typing-inspection", "typing_inspection"),
+    ("pydantic-core", "pydantic_core"),
+    ("annotated-types", "annotated_types"),
+    ("rich-click", "rich_click"),
+    ("esp-idf-nvs-partition-gen", "esp_idf_nvs_partition_gen"),
+    ("intelhex", "intelhex"),
+    ("bitstring", "bitstring"),
+    ("bitarray", "bitarray"),
+    ("esptool", "esptool"),
+    ("tibs", "tibs"),
+]
+
+PACKAGE_TO_IMPORT: dict[str, str] = {
+    p.lower().replace("-", "_"): i for p, i in KNOWN_ALIASES
+}
+
+IMPORT_TO_PACKAGE: dict[str, str] = {
+    i: p for p, i in KNOWN_ALIASES
+}

core/analyzer.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from models.package import InstallType, Package
+
+
+def find_orphans(packages: list[Package]) -> list[Package]:
+    return [
+        pkg for pkg in packages
+        if pkg.install_type == InstallType.DEPENDENCY
+        and not pkg.dependents
+    ]

core/cleanup.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from core.analyzer import find_orphans
+from core.format import fmt_size
+from core.graph import build_dependency_graph
+from core.health_scorer import score as score_health
+from core.uninstaller import UninstallError, uninstall
+from models.package import Package
+
+
+@dataclass
+class CleanupResult:
+    removed: list[Package] = field(default_factory=list)
+    failed: list[tuple[Package, str]] = field(default_factory=list)
+    skipped: list[Package] = field(default_factory=list)
+
+
+def run(
+    packages: list[Package],
+    *,
+    yes: bool = False,
+    on_confirm: bool = False,
+) -> CleanupResult:
+    build_dependency_graph(packages)
+    orphans = find_orphans(packages)
+    score_health(packages, orphans)
+
+    if not orphans:
+        return CleanupResult()
+
+    if not yes and not on_confirm:
+        return CleanupResult(skipped=orphans)
+
+    result = CleanupResult()
+    for pkg in orphans:
+        try:
+            uninstall(pkg)
+            result.removed.append(pkg)
+        except UninstallError as e:
+            result.failed.append((pkg, str(e)))
+
+    return result
+
+
+def cli_run(packages: list[Package], *, yes: bool = False) -> None:
+    from rich.console import Console
+    from rich.prompt import Confirm
+    from rich.table import Table
+
+    console = Console()
+
+    build_dependency_graph(packages)
+    orphans = find_orphans(packages)
+    score_health(packages, orphans)
+
+    if not orphans:
+        console.print("\n[bold green]No orphan packages found. Nothing to clean up.[/bold green]")
+        return
+
+    orphans.sort(key=lambda p: p.name.lower())
+    total_size = sum(p.size_bytes for p in orphans)
+
+    table = Table(title=f"Orphan Packages ({len(orphans)} found)")
+    table.add_column("Package", style="cyan")
+    table.add_column("Version", style="white")
+    table.add_column("Manager", style="yellow")
+    table.add_column("Size", style="green")
+    table.add_column("Dependents", style="magenta")
+
+    for pkg in orphans:
+        table.add_row(
+            pkg.name,
+            pkg.version or "—",
+            pkg.manager.value,
+            fmt_size(pkg.size_bytes) if pkg.size_bytes else "—",
+            str(len(pkg.dependents)),
+        )
+
+    console.print(table)
+    console.print(f"\nTotal reclaimable space: [bold]{fmt_size(total_size)}[/bold]")
+    console.print(f"Total packages to remove: [bold]{len(orphans)}[/bold]")
+
+    if not yes:
+        confirmed = Confirm.ask("\nRemove these orphan packages?")
+        if not confirmed:
+            console.print("[yellow]Cleanup cancelled.[/yellow]")
+            return
+
+    from core.snapshot import create as create_snapshot
+    snap_id = create_snapshot(packages)
+    console.print(f"[dim]Snapshot: {snap_id}[/dim]")
+
+    result = CleanupResult()
+    with console.status("[bold green]Removing orphan packages...") as status:
+        for pkg in orphans:
+            status.update(f"[bold green]Removing {pkg.name}...[/bold green]")
+            try:
+                uninstall(pkg)
+                result.removed.append(pkg)
+                console.print(f"  [green]\u2713[/green] Removed [cyan]{pkg.name}[/cyan]")
+            except UninstallError as e:
+                result.failed.append((pkg, str(e)))
+                console.print(f"  [red]\u2717[/red] Failed to remove [cyan]{pkg.name}[/cyan]: {e}")
+
+    if result.removed:
+        console.print(
+            f"\n[bold green]Successfully removed {len(result.removed)} package(s).[/bold green]"
+        )
+    if result.failed:
+        console.print(f"\n[bold red]Failed to remove {len(result.failed)} package(s).[/bold red]")
+        for pkg, err in result.failed:
+            console.print(f"  [red]{pkg.name}[/red]: {err}")
+
+
+def dry_run(packages: list[Package]) -> None:
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    build_dependency_graph(packages)
+    orphans = find_orphans(packages)
+    score_health(packages, orphans)
+    if not orphans:
+        console.print("[green]No orphan packages found.[/green]")
+        return
+    table = Table(title="Would remove (dry run)")
+    table.add_column("Package", style="cyan")
+    table.add_column("Size")
+    for p in sorted(orphans, key=lambda x: x.name.lower()):
+        table.add_row(p.name, fmt_size(p.size_bytes) if p.size_bytes else "")
+    console.print(table)
+    console.print(f"[bold]{len(orphans)} package(s) would be removed.[/bold]")

core/cli_output.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from core.format import fmt_size
+from core.project_scanner import Project
+from models.package import Package
+
+_HEALTH_COLOR = {
+    "healthy": "green",
+    "outdated": "yellow",
+    "orphan": "magenta",
+    "deprecated": "red",
+    "vulnerable": "red",
+    "unknown": "dim",
+}
+
+
+def _color_for(status: str) -> str:
+    return _HEALTH_COLOR.get(status, "dim")
+
+
+def render_packages(packages: list[Package], *, no_color: bool = False) -> None:
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console(no_color=no_color)
+    orphans = [p for p in packages if p.health_status.value == "orphan"]
+    total = sum(p.size_bytes for p in packages)
+
+    table = Table(title=f"Packages ({len(packages)})")
+    table.add_column("Package", style="cyan", no_wrap=True)
+    table.add_column("Version", style="white")
+    table.add_column("Manager", style="yellow")
+    table.add_column("Type", style="blue")
+    table.add_column("Size", justify="right")
+    table.add_column("Status")
+    table.add_column("Deps", justify="right")
+    table.add_column("Used", justify="right")
+
+    for pkg in sorted(packages, key=lambda p: p.name.lower()):
+        status = pkg.health_status.value
+        style = "" if no_color else _color_for(status)
+        table.add_row(
+            pkg.name,
+            pkg.version or "",
+            pkg.manager.value,
+            pkg.install_type.value,
+            fmt_size(pkg.size_bytes) if pkg.size_bytes else "",
+            f"[{style}]{status}[/{style}]" if style else status,
+            str(len(pkg.dependents)),
+            str(len(pkg.used_in_projects)),
+        )
+    console.print(table)
+    console.print(f"Total size: [bold]{fmt_size(total)}[/bold]")
+    if orphans:
+        console.print(f"[magenta]{len(orphans)} orphan package(s)[/magenta]")
+    console.print(
+        "[dim]legend: healthy green / outdated yellow / orphan magenta / deprecated red[/dim]"
+    )
+
+
+def render_projects(projects: list[Project]) -> None:
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    table = Table(title=f"Projects ({len(projects)})")
+    table.add_column("Name", style="cyan")
+    table.add_column("Manager", style="yellow")
+    table.add_column("Imports", justify="right")
+    table.add_column("Deps", justify="right")
+    for p in sorted(projects, key=lambda p: p.name.lower()):
+        table.add_row(p.name, p.manager.value, str(len(p.imports)), str(len(p.dependencies)))
+    console.print(table)
+
+
+def render_summary(packages: list[Package]) -> None:
+    from rich.console import Console
+
+    console = Console()
+    counts: dict[str, int] = {}
+    for pkg in packages:
+        counts[pkg.health_status.value] = counts.get(pkg.health_status.value, 0) + 1
+    parts = [f"{v} {k}" for k, v in sorted(counts.items())]
+    console.print("Health: " + ", ".join(parts))

core/config.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_CONFIG_DIR = Path.home() / ".orphans"
+_CONFIG_PATH = _CONFIG_DIR / "config.json"
+
+
+def _ensure_dir() -> None:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_scan_paths() -> list[Path]:
+    _ensure_dir()
+    if _CONFIG_PATH.is_file():
+        try:
+            data = json.loads(_CONFIG_PATH.read_text())
+            return [Path(p) for p in data.get("scan_paths", [])]
+        except (json.JSONDecodeError, OSError):
+            pass
+    return []
+
+
+def save_scan_paths(paths: list[Path]) -> None:
+    _ensure_dir()
+    data = _load_all()
+    data["scan_paths"] = [str(p) for p in paths]
+    _save_all(data)
+
+
+def get_enabled_managers() -> list[str]:
+    _ensure_dir()
+    if _CONFIG_PATH.is_file():
+        try:
+            data = json.loads(_CONFIG_PATH.read_text())
+            return data.get("enabled_managers", ["pip", "npm", "cargo", "brew"])
+        except (json.JSONDecodeError, OSError):
+            pass
+    return ["pip", "npm", "cargo", "brew"]
+
+
+def save_enabled_managers(managers: list[str]) -> None:
+    _ensure_dir()
+    data = _load_all()
+    data["enabled_managers"] = managers
+    _save_all(data)
+
+
+def get_exclude_patterns() -> list[str]:
+    _ensure_dir()
+    if _CONFIG_PATH.is_file():
+        try:
+            data = json.loads(_CONFIG_PATH.read_text())
+            return data.get("exclude_patterns", [])
+        except (json.JSONDecodeError, OSError):
+            pass
+    return []
+
+
+def save_exclude_patterns(patterns: list[str]) -> None:
+    _ensure_dir()
+    data = _load_all()
+    data["exclude_patterns"] = patterns
+    _save_all(data)
+
+
+def _load_all() -> dict:
+    if _CONFIG_PATH.is_file():
+        try:
+            return json.loads(_CONFIG_PATH.read_text())
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def _save_all(data: dict) -> None:
+    _CONFIG_PATH.write_text(json.dumps(data, indent=2))

core/disk_analyzer.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from core.project_scanner import Project
+from models.package import Package
+
+
+@dataclass
+class ProjectDiskUsage:
+    name: str
+    path: str
+    manager: str
+    total_bytes: int = 0
+    exclusive_bytes: int = 0
+    shared_bytes: int = 0
+    package_count: int = 0
+
+
+def analyze(projects: list[Project], packages: list[Package]) -> list[ProjectDiskUsage]:
+    if not projects:
+        return []
+
+    pkg_size_map: dict[str, int] = {p.name: p.size_bytes for p in packages}
+    project_packages: dict[Project, list[str]] = {}
+    for proj in projects:
+        project_packages[proj] = list(proj.dependencies)
+
+    path_to_packages: dict[str, set[str]] = {}
+    for pkg in packages:
+        for proj_path in pkg.used_in_projects:
+            path_to_packages.setdefault(proj_path, set()).add(pkg.name)
+
+    pkg_project_count: dict[str, int] = {}
+    for proj in projects:
+        for dep in proj.dependencies:
+            pkg_project_count[dep] = pkg_project_count.get(dep, 0) + 1
+    for pkg_names in path_to_packages.values():
+        for name in pkg_names:
+            pkg_project_count[name] = pkg_project_count.get(name, 0) + 1
+
+    results: list[ProjectDiskUsage] = []
+    for proj in projects:
+        proj_pkgs = project_packages.get(proj, [])
+        proj_path_str = str(proj.path)
+        pkgs_from_imports = path_to_packages.get(proj_path_str, set())
+
+        all_pkg_names = set(proj_pkgs) | pkgs_from_imports
+        total = sum(pkg_size_map.get(n, 0) for n in all_pkg_names)
+
+        exclusive = 0
+        shared = 0
+        for name in all_pkg_names:
+            count = pkg_project_count.get(name, 0)
+            sz = pkg_size_map.get(name, 0)
+            if count <= 1:
+                exclusive += sz
+            else:
+                shared += sz
+
+        results.append(ProjectDiskUsage(
+            name=proj.name,
+            path=proj_path_str,
+            manager=proj.manager.value,
+            total_bytes=total,
+            exclusive_bytes=exclusive,
+            shared_bytes=shared,
+            package_count=len(all_pkg_names),
+        ))
+
+    results.sort(key=lambda r: -r.total_bytes)
+    return results

core/duplicate_scanner.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from models.package import Package
+
+_KNOWN_CROSS_MANAGER: dict[str, list[str]] = {}
+
+
+def scan(packages: list[Package]) -> None:
+    for pkg in packages:
+        pkg.duplicate_of = []
+
+    norm_map: dict[str, list[Package]] = {}
+    for pkg in packages:
+        norm = _canonical(pkg.name)
+        norm_map.setdefault(norm, []).append(pkg)
+
+    for pkg in packages:
+        norm = _canonical(pkg.name)
+        same_norm = norm_map.get(norm, [])
+        same_aliases = _KNOWN_CROSS_MANAGER.get(norm, [])
+
+        seen: set[str] = set()
+        for other in same_norm:
+            if other is pkg or other.manager == pkg.manager:
+                continue
+            key = f"{other.manager.value}:{norm}"
+            if key not in seen:
+                seen.add(key)
+                pkg.duplicate_of.append(f"{other.name} ({other.manager.value})")
+
+        for alias in same_aliases:
+            alias_lower = alias.lower()
+            for other in norm_map.get(alias_lower, []):
+                if other is pkg or other.manager == pkg.manager:
+                    continue
+                key = f"{other.manager.value}:{alias_lower}"
+                if key not in seen:
+                    seen.add(key)
+                    pkg.duplicate_of.append(f"{other.name} ({other.manager.value})")
+
+
+def _canonical(name: str) -> str:
+    return name.lower().replace("-", "_").replace(".", "_").replace(" ", "_")

core/format.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+def fmt_size(bytes_: int) -> str:
+    if bytes_ < 1024:
+        return f"{bytes_} B"
+    if bytes_ < 1024 ** 2:
+        return f"{bytes_ / 1024:.1f} KB"
+    if bytes_ < 1024 ** 3:
+        return f"{bytes_ / 1024 ** 2:.1f} MB"
+    return f"{bytes_ / 1024 ** 3:.1f} GB"

core/graph.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from models.package import Manager, Package
+
+
+def _normalize(name: str) -> str:
+    return name.lower().replace("-", "_")
+
+
+def _build_index(packages: list[Package]) -> dict[str, Package]:
+    index: dict[str, Package] = {}
+    for p in packages:
+        index[_normalize(p.name)] = p
+        index[p.name] = p
+    return index
+
+
+_INDEXES = {
+    Manager.PIP: "pip",
+    Manager.NPM: "npm",
+    Manager.CARGO: "cargo",
+    Manager.BREW: "brew",
+}
+
+
+def build_dependency_graph(packages: list[Package]) -> None:
+    indexes: dict[str, dict[str, Package]] = {}
+    for mgr, key in _INDEXES.items():
+        mgr_pkgs = [p for p in packages if p.manager == mgr]
+        if mgr_pkgs:
+            indexes[key] = _build_index(mgr_pkgs)
+
+    for pkg in packages:
+        key = _INDEXES.get(pkg.manager, "")
+        index = indexes.get(key)
+        if index is None:
+            continue
+        for dep_name in pkg.dependencies:
+            dep = index.get(dep_name) or index.get(_normalize(dep_name))
+            if dep is not None:
+                dep.dependents.append(pkg.name)

core/health_scorer.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import asyncio
+
+from packaging.version import Version
+
+from core.vulnerability_scanner import scan as scan_vulnerabilities
+from models.package import HealthStatus, Manager, Package
+
+
+def score(packages: list[Package], orphans: list[Package]) -> None:
+    orphan_names = {p.name for p in packages if p in orphans}
+
+    for pkg in packages:
+        if pkg.name in orphan_names:
+            pkg.health_status = HealthStatus.ORPHAN
+        else:
+            pkg.health_status = HealthStatus.HEALTHY
+
+
+def score_from_registry(packages: list[Package]) -> None:
+    asyncio.run(_score_all(packages))
+
+
+async def _score_all(packages: list[Package]) -> None:
+    tasks = []
+    for pkg in packages:
+        if pkg.health_status != HealthStatus.HEALTHY:
+            continue
+        tasks.append(_check_package(pkg))
+
+    if tasks:
+        await asyncio.gather(*tasks)
+
+
+async def _check_package(pkg: Package) -> None:
+    if pkg.manager == Manager.PIP:
+        from registry.pypi_client import fetch as pypi_fetch
+        info = await pypi_fetch(pkg.name)
+    elif pkg.manager == Manager.NPM:
+        from registry.npm_registry_client import fetch as npm_fetch
+        info = await npm_fetch(pkg.name)
+    elif pkg.manager == Manager.CARGO:
+        from registry.crates_client import fetch as cargo_fetch
+        info = await cargo_fetch(pkg.name)
+    elif pkg.manager == Manager.BREW:
+        from registry.brew_client import fetch as brew_fetch
+        info = await brew_fetch(pkg.name)
+    else:
+        return
+
+    if info is None:
+        return
+
+    if info.get("is_deprecated"):
+        pkg.health_status = HealthStatus.DEPRECATED
+        pkg.deprecation_reason = info.get("deprecation_reason", "")
+        if info.get("latest_version"):
+            pkg.latest_version = info["latest_version"]
+        return
+
+    pkg.license = info.get("license", "") or ""
+
+    latest = info.get("latest_version", "")
+    if latest and pkg.version:
+        try:
+            installed = Version(pkg.version)
+            latest_v = Version(latest)
+            if latest_v > installed:
+                pkg.health_status = HealthStatus.OUTDATED
+                pkg.latest_version = latest
+        except Exception:
+            pass
+
+
+def score_vulnerabilities(packages: list[Package], *, deep: bool = False) -> None:
+    scan_vulnerabilities(packages, deep=deep)
+    for pkg in packages:
+        if not pkg.vulnerabilities:
+            continue
+        if pkg.health_status in (HealthStatus.DEPRECATED, HealthStatus.ORPHAN):
+            continue
+        pkg.health_status = HealthStatus.VULNERABLE