pkgwhy 1.0.0__py3-none-any.whl

pkgwhy/dependencies/reason.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pkgwhy.core.models import DependencyReason, DependencyStatus, PackageMetadata
+from pkgwhy.dependencies.graph import transitive_dependencies_for, transitive_parents_for
+from pkgwhy.imports.scanner import scan_project_imports
+from pkgwhy.manifests.lockfiles import read_lockfile_dependencies
+from pkgwhy.manifests.pyproject import read_pyproject_dependencies
+from pkgwhy.manifests.requirements import read_requirements_dependencies
+from pkgwhy.metadata.installed import get_installed_package, normalize_package_name
+
+
+def explain_dependency_reason(
+    package: str,
+    project_root: Path,
+    project_imports: set[str] | None = None,
+    metadata: PackageMetadata | None = None,
+) -> DependencyReason:
+    normalized = normalize_package_name(package)
+    pyproject_dependencies = read_pyproject_dependencies(project_root / "pyproject.toml")
+    requirements_dependencies = read_requirements_dependencies(project_root / "requirements.txt")
+    declared_dependencies = pyproject_dependencies | requirements_dependencies
+    declared_in: list[str] = []
+    evidence: list[str] = []
+
+    if normalized in pyproject_dependencies:
+        declared_in.append("pyproject.toml")
+        evidence.append("Package is declared in pyproject.toml.")
+    if normalized in requirements_dependencies:
+        declared_in.append("requirements.txt")
+        evidence.append("Package is declared in requirements.txt.")
+
+    lockfiles = read_lockfile_dependencies(project_root)
+    lockfile_hits = sorted(name for name, dependencies in lockfiles.items() if normalized in dependencies)
+    for lockfile in lockfile_hits:
+        evidence.append(f"Package appears in {lockfile}.")
+
+    transitive_dependencies = transitive_dependencies_for(declared_dependencies)
+    transitive_via = sorted(transitive_parents_for(normalized, declared_dependencies))
+    if normalized in transitive_dependencies:
+        evidence.append("Package is reachable from installed dependency metadata for declared project dependencies.")
+        if transitive_via:
+            evidence.append(f"Immediate dependency parent signal: {', '.join(transitive_via)}.")
+
+    installed_metadata = metadata if metadata is not None else get_installed_package(package)
+    installed = installed_metadata is not None
+    if installed:
+        evidence.append("Package is installed in the active Python environment.")
+    else:
+        evidence.append("Package is not installed in the active Python environment.")
+
+    imports = project_imports if project_imports is not None else scan_project_imports(project_root)
+    # Best-effort only: some packages use non-obvious import names such as PIL, bs4, or yaml.
+    imported_by_project = normalized.replace("-", "_") in imports
+    if imported_by_project:
+        evidence.append("Package import name appears in local project source.")
+
+    status = DependencyStatus.UNKNOWN
+    if declared_in:
+        status = DependencyStatus.DIRECT
+    elif normalized in transitive_dependencies:
+        status = DependencyStatus.TRANSITIVE
+    elif imported_by_project:
+        status = DependencyStatus.IMPORTED_BY_PROJECT
+    elif not installed:
+        status = DependencyStatus.NOT_INSTALLED
+
+    return DependencyReason(
+        package=package,
+        normalized_package=normalized,
+        status=status,
+        declared_in=declared_in,
+        lockfiles=lockfile_hits,
+        imported_by_project=imported_by_project,
+        installed=installed,
+        transitive_via=transitive_via,
+        evidence=evidence,
+    )

pkgwhy/dynamic/__init__.py

@@ -0,0 +1,2 @@
+"""Experimental dynamic analysis boundaries."""
+

pkgwhy/dynamic/analysis.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import subprocess
+import shutil
+import sys
+import time
+from pathlib import Path
+
+from pkgwhy.core.models import (
+    AgentDecision,
+    DynamicAnalysisResult,
+    DynamicAnalysisStatus,
+    DynamicFilesystemEvent,
+    DynamicNetworkMode,
+    DynamicProcessEvent,
+)
+
+EXPERIMENTAL_DYNAMIC_WARNING = "Experimental dynamic analysis is not a production sandbox."
+STATIC_DEFAULT_WARNING = "Static package inspection remains the default pkgwhy review path."
+HOST_EXECUTION_REFUSAL = "Refusing to run dynamic analysis for unknown package code on the host."
+DYNAMIC_SCOPE_WARNING = "Dynamic analysis is experimental and not part of the stable security decision surface in this build."
+
+
+def build_unavailable_dynamic_result(
+    target: str,
+    *,
+    container: bool,
+    network: str,
+) -> DynamicAnalysisResult:
+    """Build a safe-fail dynamic result without executing the target."""
+    warnings = [
+        EXPERIMENTAL_DYNAMIC_WARNING,
+        STATIC_DEFAULT_WARNING,
+        HOST_EXECUTION_REFUSAL,
+        DYNAMIC_SCOPE_WARNING,
+    ]
+    limitations = [
+        DYNAMIC_SCOPE_WARNING,
+        "No dynamic sandbox backend is implemented in this build.",
+        "No process, filesystem, or network events were collected.",
+        "Empty event lists are not proof that no behavior would occur in a real run.",
+    ]
+    sandbox_backend = "container" if container else "none"
+    status = DynamicAnalysisStatus.BACKEND_UNAVAILABLE if container else DynamicAnalysisStatus.BLOCKED
+
+    if network != DynamicNetworkMode.OFF.value:
+        warnings.append("Only network mode 'off' is accepted in this pre-alpha skeleton.")
+        limitations.append("Network-enabled dynamic analysis is not supported.")
+        status = DynamicAnalysisStatus.BLOCKED
+    elif container:
+        docker_path = shutil.which("docker")
+        if docker_path is None:
+            warnings.append("Docker container backend is unavailable: docker executable was not found.")
+        else:
+            warnings.append("Docker executable was detected, but container execution is not implemented in this build.")
+        limitations.append("Docker is detected by executable lookup only; pkgwhy does not invoke Docker in this build.")
+    else:
+        warnings.append("No sandbox backend selected. Host execution is not allowed.")
+
+    return DynamicAnalysisResult(
+        target=target,
+        sandbox_backend=sandbox_backend,
+        network_mode=DynamicNetworkMode.OFF,
+        status=status,
+        warnings=warnings,
+        process_events=[],
+        filesystem_events=[],
+        network_events=[],
+        decision=AgentDecision.BLOCK,
+        limitations=limitations,
+    )
+
+
+def run_controlled_fixture(
+    fixture_path: Path,
+    *,
+    fixture_root: Path,
+    scratch_dir: Path,
+    timeout_seconds: float = 5.0,
+) -> DynamicAnalysisResult:
+    """Run a known local fixture for tests without enabling arbitrary package execution."""
+    resolved_fixture = fixture_path.resolve()
+    resolved_fixture_root = fixture_root.resolve()
+    if resolved_fixture_root not in resolved_fixture.parents:
+        raise ValueError("controlled fixture must live under fixture_root")
+    if resolved_fixture.suffix != ".py" or not resolved_fixture.is_file():
+        raise ValueError("controlled fixture must be a Python file")
+
+    scratch_dir.mkdir(parents=True, exist_ok=True)
+    before = _snapshot_scratch(scratch_dir)
+    started_at = time.monotonic()
+    completed = subprocess.run(
+        [sys.executable, str(resolved_fixture)],
+        cwd=scratch_dir,
+        env={"PYTHONIOENCODING": "utf-8"},
+        capture_output=True,
+        text=True,
+        timeout=timeout_seconds,
+        check=False,
+    )
+    duration_ms = int((time.monotonic() - started_at) * 1000)
+    after = _snapshot_scratch(scratch_dir)
+    status = DynamicAnalysisStatus.COMPLETED if completed.returncode == 0 else DynamicAnalysisStatus.FAILED
+    decision = AgentDecision.ALLOW_WITH_CAUTION if completed.returncode == 0 else AgentDecision.BLOCK
+    warnings = [
+        "Controlled fixture execution only; this is not a sandbox for unknown package code.",
+        "No network monitor is implemented for controlled fixture execution.",
+    ]
+    limitations = [
+        "Execution was limited to a caller-provided local fixture path.",
+        "Only scratch filesystem changes are compared.",
+        "No process-tree or network telemetry is collected.",
+    ]
+    if completed.stderr:
+        warnings.append("Controlled fixture wrote to stderr; stderr content is intentionally not included in the result.")
+
+    return DynamicAnalysisResult(
+        target=resolved_fixture.name,
+        sandbox_backend="controlled_fixture",
+        status=status,
+        warnings=warnings,
+        process_events=[
+            DynamicProcessEvent(
+                command=[sys.executable, resolved_fixture.name],
+                exit_code=completed.returncode,
+                duration_ms=duration_ms,
+            )
+        ],
+        filesystem_events=_filesystem_events(before, after),
+        network_events=[],
+        decision=decision,
+        limitations=limitations,
+    )
+
+
+def _snapshot_scratch(root: Path) -> dict[str, int]:
+    snapshot: dict[str, int] = {}
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        try:
+            relative_path = path.relative_to(root).as_posix()
+            snapshot[relative_path] = path.stat().st_mtime_ns
+        except OSError:
+            continue
+    return snapshot
+
+
+def _filesystem_events(before: dict[str, int], after: dict[str, int]) -> list[DynamicFilesystemEvent]:
+    events: list[DynamicFilesystemEvent] = []
+    for path, mtime_ns in sorted(after.items()):
+        if path not in before:
+            events.append(DynamicFilesystemEvent(path=path, action="created"))
+        elif before[path] != mtime_ns:
+            events.append(DynamicFilesystemEvent(path=path, action="modified"))
+    return events

pkgwhy/explanations/__init__.py

@@ -0,0 +1,2 @@
+"""Offline package explanations."""
+

pkgwhy/explanations/explain.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from packaging.utils import canonicalize_name
+
+from pkgwhy.core.models import Confidence, PackageExplanation, PackageMetadata
+from pkgwhy.explanations.local_db import LOCAL_EXPLANATIONS
+
+
+def explain_package(metadata: PackageMetadata | None, requested_name: str, dependency_status: str) -> PackageExplanation:
+    normalized = canonicalize_name(requested_name)
+    base = LOCAL_EXPLANATIONS.get(normalized)
+    if base is not None:
+        explanation = base.model_copy(deep=True)
+        explanation.version = metadata.identity.version if metadata else None
+        explanation.dependency_status = dependency_status
+        return explanation
+
+    if metadata is None:
+        return PackageExplanation(
+            package=normalized,
+            summary="No installed metadata was found for this package in the active Python environment.",
+            dependency_status=dependency_status,
+            confidence=Confidence.LOW,
+            sources_used=["active environment metadata lookup"],
+        )
+
+    summary = metadata.summary or "Installed package metadata does not include a summary."
+    return PackageExplanation(
+        package=normalized,
+        version=metadata.identity.version,
+        summary=summary,
+        why_it_might_be_installed=_why_from_metadata(metadata),
+        dependency_status=dependency_status,
+        confidence=Confidence.MEDIUM if metadata.summary else Confidence.LOW,
+        sources_used=["installed distribution metadata"],
+    )
+
+
+def _why_from_metadata(metadata: PackageMetadata) -> list[str]:
+    reasons: list[str] = []
+    if metadata.entry_points:
+        reasons.append("It declares CLI or plugin entry points.")
+    if metadata.requires:
+        reasons.append("It declares dependencies on other packages.")
+    if metadata.summary:
+        reasons.append("Its installed metadata summary describes its intended purpose.")
+    return reasons or ["Installed metadata is available, but why it is installed is not yet known."]

pkgwhy/explanations/local_db.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pkgwhy.core.models import Confidence, PackageExplanation
+
+
+LOCAL_EXPLANATIONS: dict[str, PackageExplanation] = {
+    "packaging": PackageExplanation(
+        package="packaging",
+        summary="Core utilities for parsing and comparing Python package versions, specifiers, markers, and requirements.",
+        common_use_cases=["Validate dependency specifiers", "Compare package versions", "Parse requirement strings"],
+        common_imports=["packaging.version", "packaging.requirements", "packaging.specifiers"],
+        minimal_usage_example="from packaging.version import Version\nVersion('2.0') > Version('1.9')",
+        common_alternatives=[],
+        why_it_might_be_installed=["Used by packaging tools and dependency-aware applications."],
+        confidence=Confidence.HIGH,
+        sources_used=["built-in pkgwhy explanation database"],
+    ),
+    "pydantic": PackageExplanation(
+        package="pydantic",
+        summary="Data validation and structured model library for Python type hints.",
+        common_use_cases=["Validate structured data", "Define JSON-friendly models", "Parse API payloads and configuration"],
+        common_imports=["pydantic.BaseModel", "pydantic.Field"],
+        minimal_usage_example="from pydantic import BaseModel\nclass Item(BaseModel):\n    name: str",
+        common_alternatives=["attrs", "dataclasses", "marshmallow"],
+        why_it_might_be_installed=["Used by applications that need typed validation or stable JSON output."],
+        confidence=Confidence.HIGH,
+        sources_used=["built-in pkgwhy explanation database"],
+    ),
+    "rich": PackageExplanation(
+        package="rich",
+        summary="Terminal formatting library for tables, colors, tracebacks, progress bars, and structured console output.",
+        common_use_cases=["Render CLI tables", "Improve terminal output", "Display progress and formatted logs"],
+        common_imports=["rich.console", "rich.table"],
+        minimal_usage_example="from rich.console import Console\nConsole().print('[bold]Hello[/bold]')",
+        common_alternatives=["click styling", "blessed"],
+        why_it_might_be_installed=["Used by command-line tools for readable terminal output."],
+        confidence=Confidence.HIGH,
+        sources_used=["built-in pkgwhy explanation database"],
+    ),
+    "typer": PackageExplanation(
+        package="typer",
+        summary="CLI framework built on Click that uses Python type hints to define command-line interfaces.",
+        common_use_cases=["Build Python CLIs", "Create typed command arguments", "Generate command help"],
+        common_imports=["typer"],
+        minimal_usage_example="import typer\napp = typer.Typer()\n@app.command()\ndef main(name: str):\n    typer.echo(name)",
+        common_alternatives=["click", "argparse"],
+        why_it_might_be_installed=["Used by Python projects that expose command-line commands."],
+        confidence=Confidence.HIGH,
+        sources_used=["built-in pkgwhy explanation database"],
+    ),
+}
+

pkgwhy/imports/__init__.py

@@ -0,0 +1,2 @@
+"""Project import scanning."""
+

pkgwhy/imports/scanner.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "site-packages",
+}
+
+
+def scan_project_imports(root: Path) -> set[str]:
+    imports: set[str] = set()
+    for path in root.rglob("*.py"):
+        if any(part in SKIP_DIRS for part in path.parts):
+            continue
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        except (OSError, SyntaxError, UnicodeDecodeError):
+            continue
+        imports.update(_imports_from_tree(tree))
+    return imports
+
+
+def _imports_from_tree(tree: ast.AST) -> set[str]:
+    imports: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.add(alias.name.split(".", 1)[0])
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            imports.add(node.module.split(".", 1)[0])
+    return imports
+

pkgwhy/inspection/__init__.py

@@ -0,0 +1,2 @@
+"""Static package inspection helpers."""
+