slopguard-cli 0.1.0__py3-none-any.whl

slopguard/registry/base.py

@@ -0,0 +1,107 @@
+"""Registry client base + shared metadata type."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+
+import httpx
+
+
+class RegistryError(Exception):
+    """Raised when a registry probe fails in a way the caller should know about."""
+
+
+@dataclass(frozen=True)
+class PackageMetadata:
+    """Subset of registry metadata used by the scoring engine."""
+
+    name: str
+    exists: bool
+    first_release: datetime | None = None
+    latest_release: datetime | None = None
+    publisher: str | None = None
+    publisher_created: datetime | None = None
+    publisher_package_count: int | None = None
+    downloads_recent: int | None = None
+    extras: dict[str, str] = field(default_factory=dict)
+
+
+class RegistryClient(ABC):
+    """Async registry client. Implementations cache responses for the lifetime of one scan."""
+
+    def __init__(
+        self,
+        *,
+        client: httpx.AsyncClient | None = None,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+    ) -> None:
+        self._owned_client = client is None
+        self._client = client or httpx.AsyncClient(
+            timeout=timeout,
+            headers={
+                "User-Agent": "slopguard/0.1 (+https://github.com/hariomunknownslab/slopguard)"
+            },
+        )
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._cache: dict[str, PackageMetadata] = {}
+        self._cache_lock = asyncio.Lock()
+
+    async def __aenter__(self) -> RegistryClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owned_client:
+            await self._client.aclose()
+
+    async def fetch(self, name: str) -> PackageMetadata:
+        """Fetch metadata for ``name``. Returns ``exists=False`` on 404.
+
+        Raises :class:`RegistryError` on any error the caller cannot interpret as
+        existence / non-existence (network failures, persistent 5xx, etc.).
+        """
+        async with self._cache_lock:
+            cached = self._cache.get(name)
+            if cached is not None:
+                return cached
+
+        meta = await self._fetch_uncached(name)
+        async with self._cache_lock:
+            self._cache[name] = meta
+        return meta
+
+    @abstractmethod
+    async def _fetch_uncached(self, name: str) -> PackageMetadata: ...
+
+    async def _request_with_retry(self, method: str, url: str) -> httpx.Response:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(method, url, timeout=self._timeout)
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                last_exc = exc
+                if attempt >= self._max_retries:
+                    raise RegistryError(f"network error fetching {url}: {exc}") from exc
+                await asyncio.sleep(min(2**attempt * 0.2, 2.0))
+                continue
+            if response.status_code == 429:
+                retry_after = float(response.headers.get("Retry-After", "1") or "1")
+                if attempt >= self._max_retries:
+                    raise RegistryError(f"rate limited by {url}")
+                await asyncio.sleep(min(retry_after, 5.0))
+                continue
+            if response.status_code >= 500:
+                if attempt >= self._max_retries:
+                    raise RegistryError(f"server error {response.status_code} at {url}")
+                await asyncio.sleep(min(2**attempt * 0.2, 2.0))
+                continue
+            return response
+        # Should be unreachable; the loop either returns or raises above.
+        raise RegistryError(f"unexpected retry exhaustion fetching {url}: {last_exc}")

slopguard/registry/npm.py

@@ -0,0 +1,78 @@
+"""npm registry client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote
+
+from slopguard.registry.base import PackageMetadata, RegistryClient, RegistryError
+
+NPM_REGISTRY = "https://registry.npmjs.org"
+NPM_DOWNLOADS = "https://api.npmjs.org/downloads/point/last-month"
+
+
+def _parse_iso(value: Any) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    # npm timestamps end with 'Z' — Python <3.11 chokes on it, 3.11+ handles via fromisoformat
+    try:
+        if value.endswith("Z"):
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+class NpmRegistryClient(RegistryClient):
+    """Probe ``registry.npmjs.org`` for package metadata."""
+
+    async def _fetch_uncached(self, name: str) -> PackageMetadata:
+        url = f"{NPM_REGISTRY}/{quote(name, safe='@/')}"
+        response = await self._request_with_retry("GET", url)
+        if response.status_code == 404:
+            return PackageMetadata(name=name, exists=False)
+        if response.status_code != 200:
+            raise RegistryError(f"unexpected status {response.status_code} from {url}")
+        try:
+            data: dict[str, Any] = response.json()
+        except ValueError as exc:
+            raise RegistryError(f"invalid JSON from {url}: {exc}") from exc
+
+        time_raw = data.get("time")
+        time_block: dict[str, Any] = time_raw if isinstance(time_raw, dict) else {}
+        first_release = _parse_iso(time_block.get("created"))
+        latest_release = _parse_iso(time_block.get("modified"))
+
+        publisher: str | None = None
+        maintainers = data.get("maintainers")
+        if isinstance(maintainers, list) and maintainers:
+            first = maintainers[0]
+            if isinstance(first, dict) and isinstance(first.get("name"), str):
+                publisher = first["name"]
+
+        downloads = await self._fetch_downloads(name)
+
+        return PackageMetadata(
+            name=name,
+            exists=True,
+            first_release=first_release,
+            latest_release=latest_release,
+            publisher=publisher,
+            downloads_recent=downloads,
+        )
+
+    async def _fetch_downloads(self, name: str) -> int | None:
+        url = f"{NPM_DOWNLOADS}/{quote(name, safe='@/')}"
+        try:
+            response = await self._request_with_retry("GET", url)
+        except RegistryError:
+            return None
+        if response.status_code != 200:
+            return None
+        try:
+            payload = response.json()
+        except ValueError:
+            return None
+        downloads = payload.get("downloads") if isinstance(payload, dict) else None
+        return downloads if isinstance(downloads, int) else None

slopguard/registry/pypi.py

@@ -0,0 +1,99 @@
+"""PyPI registry client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote
+
+from slopguard.registry.base import PackageMetadata, RegistryClient, RegistryError
+
+PYPI_JSON = "https://pypi.org/pypi"
+PYPISTATS_RECENT = "https://pypistats.org/api/packages"
+
+
+def _parse_iso(value: Any) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        if value.endswith("Z"):
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+class PypiRegistryClient(RegistryClient):
+    """Probe ``pypi.org/pypi/<name>/json`` for package metadata."""
+
+    async def _fetch_uncached(self, name: str) -> PackageMetadata:
+        url = f"{PYPI_JSON}/{quote(name, safe='')}/json"
+        response = await self._request_with_retry("GET", url)
+        if response.status_code == 404:
+            return PackageMetadata(name=name, exists=False)
+        if response.status_code != 200:
+            raise RegistryError(f"unexpected status {response.status_code} from {url}")
+        try:
+            data: dict[str, Any] = response.json()
+        except ValueError as exc:
+            raise RegistryError(f"invalid JSON from {url}: {exc}") from exc
+
+        info_raw = data.get("info")
+        info: dict[str, Any] = info_raw if isinstance(info_raw, dict) else {}
+        releases_raw = data.get("releases")
+        releases: dict[str, Any] = releases_raw if isinstance(releases_raw, dict) else {}
+
+        first_release: datetime | None = None
+        latest_release: datetime | None = None
+        timestamps: list[datetime] = []
+        for files in releases.values():
+            if not isinstance(files, list):
+                continue
+            for f in files:
+                if not isinstance(f, dict):
+                    continue
+                ts = _parse_iso(f.get("upload_time_iso_8601") or f.get("upload_time"))
+                if ts is not None:
+                    timestamps.append(ts)
+        if timestamps:
+            timestamps.sort()
+            first_release = timestamps[0]
+            latest_release = timestamps[-1]
+
+        author = info.get("author")
+        maintainer = info.get("maintainer")
+        publisher: str | None = author if isinstance(author, str) and author else None
+        if not publisher and isinstance(maintainer, str) and maintainer:
+            publisher = maintainer
+
+        downloads = await self._fetch_downloads(name)
+
+        return PackageMetadata(
+            name=name,
+            exists=True,
+            first_release=first_release,
+            latest_release=latest_release,
+            publisher=publisher,
+            downloads_recent=downloads,
+        )
+
+    async def _fetch_downloads(self, name: str) -> int | None:
+        url = f"{PYPISTATS_RECENT}/{quote(name, safe='')}/recent"
+        try:
+            response = await self._request_with_retry("GET", url)
+        except RegistryError:
+            return None
+        if response.status_code != 200:
+            return None
+        try:
+            payload = response.json()
+        except ValueError:
+            return None
+        if not isinstance(payload, dict):
+            return None
+        data = payload.get("data")
+        if isinstance(data, dict):
+            week = data.get("last_week")
+            if isinstance(week, int):
+                return week
+        return None

slopguard/report/__init__.py

@@ -0,0 +1,8 @@
+"""Output formatters."""
+
+from __future__ import annotations
+
+from slopguard.report.json import write_json_report
+from slopguard.report.terminal import render_terminal_report
+
+__all__ = ["render_terminal_report", "write_json_report"]

slopguard/report/json.py

@@ -0,0 +1,17 @@
+"""JSON report writer."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from slopguard.models import ScanReport
+
+
+def write_json_report(report: ScanReport, *, path: Path | None = None) -> str:
+    """Serialise ``report`` to JSON. If ``path`` is set, write it there. Returns the JSON string."""
+    payload = report.model_dump(mode="json")
+    text = json.dumps(payload, indent=2, sort_keys=False) + "\n"
+    if path is not None:
+        path.write_text(text, encoding="utf-8")
+    return text

slopguard/report/terminal.py

@@ -0,0 +1,87 @@
+"""Rich terminal rendering."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+from slopguard.models import Finding, RiskTier, ScanReport
+
+_TIER_STYLE = {
+    RiskTier.HALLUCINATED: "bold red",
+    RiskTier.SUSPICIOUS: "bold yellow",
+    RiskTier.CLEAN: "green",
+    RiskTier.ERROR: "magenta",
+}
+
+_TIER_LABEL = {
+    RiskTier.HALLUCINATED: "HALLUCIN.",
+    RiskTier.SUSPICIOUS: "SUSPICIOUS",
+    RiskTier.CLEAN: "CLEAN",
+    RiskTier.ERROR: "ERROR",
+}
+
+
+def render_terminal_report(
+    report: ScanReport,
+    *,
+    console: Console | None = None,
+    show_clean: bool = True,
+    duration_seconds: float | None = None,
+) -> None:
+    console = console or Console()
+    console.print(f"[bold]SlopGuard v{report.slopguard_version}[/bold] — scanning {report.path}")
+    console.print()
+    if report.manifests:
+        console.print("Detected manifests:")
+        for m in report.manifests:
+            console.print(
+                f"  • {m.path} ([cyan]{m.ecosystem.value}[/cyan], {m.dependency_count} deps)"
+            )
+        console.print()
+
+    total = report.summary.total
+    if duration_seconds is not None:
+        console.print(f"Scanned {total} dependencies in {duration_seconds:.1f}s.\n")
+    else:
+        console.print(f"Scanned {total} dependencies.\n")
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Package", no_wrap=False, max_width=40)
+    table.add_column("Risk", no_wrap=True)
+    table.add_column("Reason", overflow="fold")
+    rows_added = 0
+    for finding in report.findings:
+        if not show_clean and finding.risk is RiskTier.CLEAN:
+            continue
+        style = _TIER_STYLE[finding.risk]
+        label = _TIER_LABEL[finding.risk]
+        reason = _summarise_reason(finding)
+        table.add_row(finding.name, f"[{style}]{label}[/{style}]", reason)
+        rows_added += 1
+    if rows_added == 0:
+        console.print("[green]All dependencies clean.[/green]")
+    else:
+        console.print(table)
+
+    console.print()
+    console.print(
+        f"Summary: [bold red]{report.summary.hallucinated}[/bold red] hallucinated, "
+        f"[bold yellow]{report.summary.suspicious}[/bold yellow] suspicious, "
+        f"[green]{report.summary.clean}[/green] clean, "
+        f"[magenta]{report.summary.errors}[/magenta] error(s)."
+    )
+    console.print(f"Exit code: [bold]{report.exit_code}[/bold]")
+
+
+def _summarise_reason(finding: Finding) -> str:
+    if finding.error:
+        return finding.error
+    if not finding.signals:
+        return "No signals."
+    # Top contributor first, then up to one additional.
+    primary = max(finding.signals, key=lambda s: s.weight)
+    extras = [s for s in finding.signals if s is not primary][:1]
+    parts = [primary.detail]
+    parts.extend(s.detail for s in extras)
+    return " ".join(parts)

slopguard/scoring/__init__.py

@@ -0,0 +1,7 @@
+"""Risk scoring engine."""
+
+from __future__ import annotations
+
+from slopguard.scoring.engine import ScoringEngine
+
+__all__ = ["ScoringEngine"]

slopguard/scoring/engine.py

@@ -0,0 +1,235 @@
+"""Scoring engine — combines signals into a per-dependency risk score."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from slopguard.data import hallucination_index, popular_set
+from slopguard.models import Dependency, DependencySource, Ecosystem, Finding, RiskTier, Signal
+from slopguard.registry.base import PackageMetadata, RegistryClient, RegistryError
+from slopguard.scoring import signals
+
+DEFAULT_SUSPICIOUS_MIN = 0.4
+DEFAULT_HALLUCINATED_MIN = 0.85
+
+_REMEDIATION_HALLUCINATED = (
+    "Remove this dependency. Verify the package your AI suggested actually exists "
+    "at the source you trust."
+)
+_REMEDIATION_SUSPICIOUS = (
+    "Inspect this dependency before installing — recent publication, low downloads, "
+    "or close to a popular package name. If your AI suggested it, double-check the spelling."
+)
+_REMEDIATION_ERROR = (
+    "SlopGuard could not score this dependency. Re-run with network access, or skip "
+    "with --no-network plus an ignore rule."
+)
+_REMEDIATION_CLEAN = "No action required."
+
+
+@dataclass(frozen=True)
+class ScoringConfig:
+    suspicious_min: float = DEFAULT_SUSPICIOUS_MIN
+    hallucinated_min: float = DEFAULT_HALLUCINATED_MIN
+    verbose: bool = False
+
+
+class ScoringEngine:
+    """Scores a list of dependencies against a registry client."""
+
+    def __init__(
+        self,
+        *,
+        npm_client: RegistryClient | None = None,
+        pypi_client: RegistryClient | None = None,
+        config: ScoringConfig | None = None,
+        no_network: bool = False,
+        concurrency: int = 16,
+    ) -> None:
+        self._npm = npm_client
+        self._pypi = pypi_client
+        self._config = config or ScoringConfig()
+        self._no_network = no_network
+        self._semaphore = asyncio.Semaphore(concurrency)
+        self._db = hallucination_index()
+        self._popular_npm = popular_set(Ecosystem.NPM)
+        self._popular_pypi = popular_set(Ecosystem.PYPI)
+
+    async def score_all(self, deps: list[Dependency]) -> list[Finding]:
+        tasks = [self._score_one(d) for d in deps]
+        return await asyncio.gather(*tasks)
+
+    async def _score_one(self, dep: Dependency) -> Finding:
+        async with self._semaphore:
+            return await self._score_one_inner(dep)
+
+    async def _score_one_inner(self, dep: Dependency) -> Finding:
+        # Local file / link refs: scope says ignore. Git URLs: clean with a note.
+        if dep.source in (DependencySource.FILE, DependencySource.LINK):
+            return self._finding(dep, RiskTier.CLEAN, 0.0, [], _REMEDIATION_CLEAN)
+        if dep.source is DependencySource.GIT:
+            return self._finding(
+                dep,
+                RiskTier.CLEAN,
+                0.0,
+                [
+                    Signal(
+                        type="git_dependency",
+                        weight=0.0,
+                        detail="Git URL dependency — out of scope for v0.1 scoring.",
+                    )
+                ],
+                _REMEDIATION_CLEAN,
+            )
+
+        # Scoped npm (@org/pkg) bypasses the registry probe unless the DB has it. Spec §9 edge cases.
+        if dep.ecosystem is Ecosystem.NPM and dep.scoped:
+            entry = self._db.get((dep.ecosystem, dep.name.lower()))
+            if entry is None:
+                return self._finding(dep, RiskTier.CLEAN, 0.0, [], _REMEDIATION_CLEAN)
+            sig = signals.hallucination_db_hit(dep, entry)
+            return self._finalize(dep, [sig] if sig else [])
+
+        collected: list[Signal] = []
+
+        # 1) DB hit short-circuits.
+        entry = self._db.get((dep.ecosystem, dep.name.lower()))
+        db_signal = signals.hallucination_db_hit(dep, entry)
+        if db_signal is not None:
+            collected.append(db_signal)
+            # Only probe further if verbose — for the JSON report's completeness.
+            if not (self._config.verbose and not self._no_network):
+                return self._finalize(dep, collected)
+
+        # 2) --no-network: only DB + name pattern.
+        if self._no_network:
+            pattern_sig = signals.name_pattern_suspicious(dep)
+            if pattern_sig is not None:
+                collected.append(pattern_sig)
+            return self._finalize(dep, collected)
+
+        # 3) Registry probe.
+        client = self._client_for(dep.ecosystem)
+        if client is None:
+            return self._finding(
+                dep,
+                RiskTier.ERROR,
+                0.0,
+                collected,
+                _REMEDIATION_ERROR,
+                error=f"no registry client configured for {dep.ecosystem.value}",
+            )
+
+        try:
+            meta = await client.fetch(dep.name)
+        except RegistryError as exc:
+            return self._finding(
+                dep,
+                RiskTier.ERROR,
+                0.0,
+                collected,
+                _REMEDIATION_ERROR,
+                error=str(exc),
+            )
+        except Exception as exc:
+            return self._finding(
+                dep,
+                RiskTier.ERROR,
+                0.0,
+                collected,
+                _REMEDIATION_ERROR,
+                error=f"{type(exc).__name__}: {exc}",
+            )
+
+        # 4) 404 → registry_not_found and stop. Spec §9 step 3.
+        nf = signals.registry_not_found(meta)
+        if nf is not None:
+            collected.append(nf)
+            # Levenshtein is still informative when the package doesn't exist.
+            lev = signals.levenshtein_typo(dep, self._popular_for(dep.ecosystem))
+            if lev is not None:
+                collected.append(lev)
+            pat = signals.name_pattern_suspicious(dep)
+            if pat is not None:
+                collected.append(pat)
+            return self._finalize(dep, collected)
+
+        # 5) Full signal sweep.
+        collected.extend(self._collect_metadata_signals(dep, meta))
+        return self._finalize(dep, collected)
+
+    def _collect_metadata_signals(self, dep: Dependency, meta: PackageMetadata) -> list[Signal]:
+        out: list[Signal] = []
+        very_recent, recent = signals.recently_published(meta)
+        if very_recent is not None:
+            out.append(very_recent)
+        elif recent is not None:
+            out.append(recent)
+        low = signals.low_downloads(meta)
+        if low is not None:
+            out.append(low)
+        np_sig = signals.new_publisher(meta)
+        if np_sig is not None:
+            out.append(np_sig)
+        solo = signals.single_release_new_account(meta)
+        if solo is not None:
+            out.append(solo)
+        lev = signals.levenshtein_typo(dep, self._popular_for(dep.ecosystem))
+        if lev is not None:
+            out.append(lev)
+        pat = signals.name_pattern_suspicious(dep)
+        if pat is not None:
+            out.append(pat)
+        return out
+
+    def _finalize(self, dep: Dependency, sigs: list[Signal]) -> Finding:
+        score = min(1.0, sum(s.weight for s in sigs))
+        tier = self._tier_for(score)
+        remediation = self._remediation_for(tier)
+        return self._finding(dep, tier, score, sigs, remediation)
+
+    def _tier_for(self, score: float) -> RiskTier:
+        if score >= self._config.hallucinated_min:
+            return RiskTier.HALLUCINATED
+        if score >= self._config.suspicious_min:
+            return RiskTier.SUSPICIOUS
+        return RiskTier.CLEAN
+
+    @staticmethod
+    def _remediation_for(tier: RiskTier) -> str:
+        if tier is RiskTier.HALLUCINATED:
+            return _REMEDIATION_HALLUCINATED
+        if tier is RiskTier.SUSPICIOUS:
+            return _REMEDIATION_SUSPICIOUS
+        if tier is RiskTier.ERROR:
+            return _REMEDIATION_ERROR
+        return _REMEDIATION_CLEAN
+
+    @staticmethod
+    def _finding(
+        dep: Dependency,
+        tier: RiskTier,
+        score: float,
+        sigs: list[Signal],
+        remediation: str,
+        *,
+        error: str | None = None,
+    ) -> Finding:
+        return Finding(
+            name=dep.name,
+            version=dep.version,
+            ecosystem=dep.ecosystem,
+            manifest=dep.manifest,
+            risk=tier,
+            score=round(score, 4),
+            signals=sigs,
+            remediation=remediation,
+            error=error,
+        )
+
+    def _client_for(self, ecosystem: Ecosystem) -> RegistryClient | None:
+        return self._npm if ecosystem is Ecosystem.NPM else self._pypi
+
+    def _popular_for(self, ecosystem: Ecosystem) -> frozenset[str]:
+        return self._popular_npm if ecosystem is Ecosystem.NPM else self._popular_pypi