libyear-multi 0.1.0__py3-none-any.whl

libyear_multi/__init__.py

@@ -0,0 +1,16 @@
+from .core import Dependency, EcosystemAdapter
+from .scanner import LibyearScanner
+from .scoring import DependencyAgeScore, score_dependency_age, summary_line
+from .cache import Cache
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Dependency",
+    "EcosystemAdapter",
+    "LibyearScanner",
+    "DependencyAgeScore",
+    "score_dependency_age",
+    "summary_line",
+    "Cache",
+]

libyear_multi/adapters/__init__.py

@@ -0,0 +1,14 @@
+from .pypi import PyPIAdapter
+from .npm import NpmAdapter
+from .cargo import CargoAdapter
+from .rubygems import RubyGemsAdapter
+
+ALL_ADAPTERS = [PyPIAdapter, NpmAdapter, CargoAdapter, RubyGemsAdapter]
+
+__all__ = [
+    "PyPIAdapter",
+    "NpmAdapter",
+    "CargoAdapter",
+    "RubyGemsAdapter",
+    "ALL_ADAPTERS",
+]

libyear_multi/adapters/cargo.py

@@ -0,0 +1,51 @@
+"""crates.io adapter for Rust Cargo.lock files."""
+
+import json
+import os
+import re
+import urllib.request
+from datetime import datetime
+
+from ..core import EcosystemAdapter
+
+
+class CargoAdapter(EcosystemAdapter):
+    name = "cargo"
+
+    def detect(self, project_path: str) -> bool:
+        return os.path.exists(os.path.join(project_path, "Cargo.lock"))
+
+    def list_dependencies(self, project_path: str) -> list[tuple[str, str]]:
+        path = os.path.join(project_path, "Cargo.lock")
+        deps = []
+        with open(path) as f:
+            content = f.read()
+        # Parse package blocks directly so the core package has no TOML runtime
+        # dependency. This is sufficient for the fields needed by the scanner.
+        for block in content.split("[[package]]")[1:]:
+            name_match = re.search(r'name\s*=\s*"([^"]+)"', block)
+            version_match = re.search(r'version\s*=\s*"([^"]+)"', block)
+            if name_match and version_match:
+                deps.append((name_match.group(1), version_match.group(1)))
+        return deps
+
+    def get_latest_version(self, name: str) -> str | None:
+        try:
+            url = f"https://crates.io/api/v1/crates/{name}"
+            req = urllib.request.Request(url, headers={"User-Agent": "libyear-multi"})
+            with urllib.request.urlopen(req, timeout=10) as r:
+                data = json.load(r)
+            return data["crate"]["max_stable_version"]
+        except Exception:
+            return None
+
+    def get_release_date(self, name: str, version: str) -> datetime | None:
+        try:
+            url = f"https://crates.io/api/v1/crates/{name}/{version}"
+            req = urllib.request.Request(url, headers={"User-Agent": "libyear-multi"})
+            with urllib.request.urlopen(req, timeout=10) as r:
+                data = json.load(r)
+            ts = data["version"]["created_at"]
+            return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        except Exception:
+            return None

libyear_multi/adapters/npm.py

@@ -0,0 +1,50 @@
+"""npm adapter for Node.js package.json files."""
+
+import json
+import os
+import urllib.request
+from datetime import datetime
+
+from ..core import EcosystemAdapter
+
+
+class NpmAdapter(EcosystemAdapter):
+    name = "npm"
+
+    def detect(self, project_path: str) -> bool:
+        return os.path.exists(os.path.join(project_path, "package.json"))
+
+    def list_dependencies(self, project_path: str) -> list[tuple[str, str]]:
+        path = os.path.join(project_path, "package.json")
+        with open(path) as f:
+            pkg = json.load(f)
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        cleaned = []
+        for name, version in deps.items():
+            v = version.lstrip("^~=v ").strip()
+            # Registry metadata cannot resolve Git, file, or workspace specs.
+            if any(c in v for c in ["/", ":", "*", "workspace"]):
+                continue
+            cleaned.append((name, v))
+        return cleaned
+
+    def get_latest_version(self, name: str) -> str | None:
+        try:
+            url = f"https://registry.npmjs.org/{name}"
+            with urllib.request.urlopen(url, timeout=10) as r:
+                data = json.load(r)
+            return data.get("dist-tags", {}).get("latest")
+        except Exception:
+            return None
+
+    def get_release_date(self, name: str, version: str) -> datetime | None:
+        try:
+            url = f"https://registry.npmjs.org/{name}"
+            with urllib.request.urlopen(url, timeout=10) as r:
+                data = json.load(r)
+            ts = data.get("time", {}).get(version)
+            if not ts:
+                return None
+            return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        except Exception:
+            return None

libyear_multi/adapters/pypi.py

@@ -0,0 +1,50 @@
+"""PyPI adapter for Python requirements.txt files."""
+
+import json
+import os
+import re
+import urllib.request
+from datetime import datetime
+
+from ..core import EcosystemAdapter
+
+
+class PyPIAdapter(EcosystemAdapter):
+    name = "pypi"
+
+    def detect(self, project_path: str) -> bool:
+        return os.path.exists(os.path.join(project_path, "requirements.txt"))
+
+    def list_dependencies(self, project_path: str) -> list[tuple[str, str]]:
+        deps = []
+        path = os.path.join(project_path, "requirements.txt")
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                match = re.match(r"^([A-Za-z0-9_.\-]+)\s*==\s*([A-Za-z0-9_.\-]+)", line)
+                if match:
+                    deps.append((match.group(1), match.group(2)))
+        return deps
+
+    def get_latest_version(self, name: str) -> str | None:
+        try:
+            with urllib.request.urlopen(f"https://pypi.org/pypi/{name}/json", timeout=10) as r:
+                data = json.load(r)
+            return data["info"]["version"]
+        except Exception:
+            return None
+
+    def get_release_date(self, name: str, version: str) -> datetime | None:
+        try:
+            url = f"https://pypi.org/pypi/{name}/{version}/json"
+            with urllib.request.urlopen(url, timeout=10) as r:
+                data = json.load(r)
+            urls = data.get("urls") or []
+            if not urls:
+                return None
+            ts = urls[0]["upload_time_iso_8601"].replace("Z", "+00:00")
+            return datetime.fromisoformat(ts)
+        except Exception:
+            return None

libyear_multi/adapters/rubygems.py

@@ -0,0 +1,64 @@
+"""RubyGems adapter for Ruby Gemfile.lock files."""
+
+import json
+import os
+import re
+import urllib.request
+from datetime import datetime
+
+from ..core import EcosystemAdapter
+
+
+class RubyGemsAdapter(EcosystemAdapter):
+    name = "rubygems"
+
+    def detect(self, project_path: str) -> bool:
+        return os.path.exists(os.path.join(project_path, "Gemfile.lock"))
+
+    def list_dependencies(self, project_path: str) -> list[tuple[str, str]]:
+        path = os.path.join(project_path, "Gemfile.lock")
+        deps = []
+        in_specs = False
+        with open(path) as f:
+            for line in f:
+                stripped = line.strip()
+                if stripped == "specs:":
+                    in_specs = True
+                    continue
+                if in_specs:
+                    if not line.startswith("    ") or line.startswith("     "):
+                        # Nested entries are transitive dependencies. The
+                        # scanner currently reports only top-level gems.
+                        if not re.match(r"^\s{4}\S", line):
+                            continue
+                    match = re.match(r"^\s{4}([A-Za-z0-9_.\-]+)\s+\(([^)]+)\)", line)
+                    if match:
+                        deps.append((match.group(1), match.group(2)))
+                    elif line.strip() == "" or not line.startswith(" "):
+                        in_specs = False
+        return deps
+
+    def get_latest_version(self, name: str) -> str | None:
+        try:
+            url = f"https://rubygems.org/api/v1/versions/{name}.json"
+            with urllib.request.urlopen(url, timeout=10) as r:
+                data = json.load(r)
+            for entry in data:
+                if not entry.get("prerelease"):
+                    return entry["number"]
+            return data[0]["number"] if data else None
+        except Exception:
+            return None
+
+    def get_release_date(self, name: str, version: str) -> datetime | None:
+        try:
+            url = f"https://rubygems.org/api/v1/versions/{name}.json"
+            with urllib.request.urlopen(url, timeout=10) as r:
+                data = json.load(r)
+            for entry in data:
+                if entry["number"] == version:
+                    ts = entry["created_at"]
+                    return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            return None
+        except Exception:
+            return None

libyear_multi/cache.py

@@ -0,0 +1,112 @@
+"""
+Lightweight SQLite cache for registry lookups.
+
+Release dates for a given (ecosystem, package, version) never change, so we
+cache them forever. "Latest version" lookups are cached with a TTL since
+they go stale.
+"""
+
+import sqlite3
+import threading
+import time
+import json
+from datetime import datetime
+from pathlib import Path
+
+
+DEFAULT_CACHE_PATH = Path.home() / ".cache" / "libyear-multi" / "cache.sqlite3"
+LATEST_VERSION_TTL_SECONDS = 24 * 60 * 60  # 1 day
+
+
+class Cache:
+    """
+    Thread-safe wrapper around a SQLite cache.
+
+    The scanner resolves dependencies concurrently via a thread pool, and
+    sqlite3 connections can't be shared across threads by default, so we
+    open a connection per thread (cached in thread-local storage) and guard
+    writes with a lock to avoid "database is locked" errors.
+    """
+
+    def __init__(self, path: Path | str = DEFAULT_CACHE_PATH):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._local = threading.local()
+        self._write_lock = threading.Lock()
+        self._init_schema()
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if not hasattr(self._local, "conn"):
+            self._local.conn = sqlite3.connect(self.path, timeout=30)
+        return self._local.conn
+
+    def _init_schema(self):
+        self.conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS release_dates (
+                ecosystem TEXT,
+                package TEXT,
+                version TEXT,
+                iso_date TEXT,
+                PRIMARY KEY (ecosystem, package, version)
+            )
+            """
+        )
+        self.conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS latest_versions (
+                ecosystem TEXT,
+                package TEXT,
+                version TEXT,
+                fetched_at REAL,
+                PRIMARY KEY (ecosystem, package)
+            )
+            """
+        )
+        self.conn.commit()
+
+    def get_release_date(self, ecosystem: str, package: str, version: str) -> datetime | None:
+        row = self.conn.execute(
+            "SELECT iso_date FROM release_dates WHERE ecosystem=? AND package=? AND version=?",
+            (ecosystem, package, version),
+        ).fetchone()
+        if row is None:
+            return None
+        return datetime.fromisoformat(row[0])
+
+    def set_release_date(self, ecosystem: str, package: str, version: str, date: datetime | None):
+        if date is None:
+            return
+        with self._write_lock:
+            self.conn.execute(
+                "INSERT OR REPLACE INTO release_dates VALUES (?, ?, ?, ?)",
+                (ecosystem, package, version, date.isoformat()),
+            )
+            self.conn.commit()
+
+    def get_latest_version(self, ecosystem: str, package: str) -> str | None:
+        row = self.conn.execute(
+            "SELECT version, fetched_at FROM latest_versions WHERE ecosystem=? AND package=?",
+            (ecosystem, package),
+        ).fetchone()
+        if row is None:
+            return None
+        version, fetched_at = row
+        if time.time() - fetched_at > LATEST_VERSION_TTL_SECONDS:
+            return None
+        return version
+
+    def set_latest_version(self, ecosystem: str, package: str, version: str | None):
+        if version is None:
+            return
+        with self._write_lock:
+            self.conn.execute(
+                "INSERT OR REPLACE INTO latest_versions VALUES (?, ?, ?, ?)",
+                (ecosystem, package, version, time.time()),
+            )
+            self.conn.commit()
+
+    def close(self):
+        if hasattr(self._local, "conn"):
+            self._local.conn.close()

libyear_multi/cli.py

@@ -0,0 +1,72 @@
+"""
+Command-line entrypoint.
+
+Usage:
+    python -m libyear_multi.cli /path/to/project
+    python -m libyear_multi.cli /path/to/project --json
+"""
+
+import argparse
+import json as json_lib
+import sys
+
+from .scanner import LibyearScanner
+from .scoring import score_dependency_age, summary_line
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Compute libyear across any codebase, any language.")
+    parser.add_argument("path", help="Path to the project to scan")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON instead of a text report")
+    parser.add_argument("--max-workers", type=int, default=8, help="Parallel registry lookups")
+    args = parser.parse_args()
+
+    scanner = LibyearScanner(max_workers=args.max_workers)
+    deps = scanner.scan(args.path)
+
+    if not deps:
+        print("No supported dependency manifests found (requirements.txt, package.json, Cargo.lock, Gemfile.lock).", file=sys.stderr)
+        sys.exit(1)
+
+    score = score_dependency_age(deps)
+
+    if args.json:
+        payload = {
+            "summary": {
+                "total_libyears": score.total_libyears,
+                "avg_libyears": score.avg_libyears,
+                "median_libyears": score.median_libyears,
+                "max_libyears": score.max_libyears,
+                "pct_severely_outdated": score.pct_severely_outdated,
+                "dependency_count": score.dependency_count,
+                "unresolved_count": score.unresolved_count,
+                "risk_band": score.to_risk_band(),
+            },
+            "dependencies": [
+                {
+                    "name": d.name,
+                    "ecosystem": d.ecosystem,
+                    "installed_version": d.installed_version,
+                    "latest_version": d.latest_version,
+                    "libyears": d.libyears,
+                }
+                for d in sorted(deps, key=lambda d: (d.libyears or 0), reverse=True)
+            ],
+        }
+        print(json_lib.dumps(payload, indent=2))
+        return
+
+    print(summary_line(score))
+    print(f"Risk band: {score.to_risk_band()}\n")
+
+    worst = sorted([d for d in deps if d.libyears is not None], key=lambda d: d.libyears, reverse=True)[:15]
+    print("Most outdated dependencies:")
+    for d in worst:
+        print(f"  [{d.ecosystem}] {d.name}: {d.installed_version} -> {d.latest_version}  ({d.libyears} libyears)")
+
+    if score.unresolved_count:
+        print(f"\nNote: {score.unresolved_count} dependencies could not be resolved (registry errors, yanked versions, etc.)")
+
+
+if __name__ == "__main__":
+    main()

libyear_multi/core.py

@@ -0,0 +1,59 @@
+"""
+Core data structures and libyear math.
+This part is language-agnostic. Every adapter feeds into these structures.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from abc import ABC, abstractmethod
+
+
+@dataclass
+class Dependency:
+    name: str
+    installed_version: str
+    latest_version: str
+    installed_date: datetime | None
+    latest_date: datetime | None
+    ecosystem: str
+
+    @property
+    def libyears(self) -> float | None:
+        """Years of staleness between installed and latest release."""
+        if not self.installed_date or not self.latest_date:
+            return None
+        delta_days = (self.latest_date - self.installed_date).days
+        return round(delta_days / 365.25, 2)
+
+    @property
+    def is_up_to_date(self) -> bool:
+        return self.installed_version == self.latest_version
+
+
+class EcosystemAdapter(ABC):
+    """
+    One adapter per language / package manager.
+
+    To add support for a new ecosystem, subclass this and implement
+    the four methods below, then register it with the scanner.
+    """
+
+    name: str = "unknown"
+
+    @abstractmethod
+    def detect(self, project_path: str) -> bool:
+        """Return True if this project uses this ecosystem."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_dependencies(self, project_path: str) -> list[tuple[str, str]]:
+        """Return [(name, installed_version), ...]."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_latest_version(self, name: str) -> str | None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_release_date(self, name: str, version: str) -> datetime | None:
+        raise NotImplementedError

libyear_multi/scanner.py

@@ -0,0 +1,77 @@
+"""Orchestrates adapters across a project directory."""
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from .core import Dependency, EcosystemAdapter
+from .adapters import ALL_ADAPTERS
+from .cache import Cache
+
+
+class LibyearScanner:
+    def __init__(self, adapters: list[EcosystemAdapter] | None = None, cache: Cache | None = None, max_workers: int = 8):
+        self.adapters = adapters or [cls() for cls in ALL_ADAPTERS]
+        self.cache = cache or Cache()
+        self.max_workers = max_workers
+
+    def scan(self, project_path: str) -> list[Dependency]:
+        detected = [a for a in self.adapters if a.detect(project_path)]
+        if not detected:
+            return []
+
+        jobs = []
+        for adapter in detected:
+            for name, installed_version in adapter.list_dependencies(project_path):
+                jobs.append((adapter, name, installed_version))
+
+        results: list[Dependency] = []
+        with ThreadPoolExecutor(max_workers=self.max_workers) as pool:
+            futures = {
+                pool.submit(self._resolve, adapter, name, installed_version): (adapter, name)
+                for adapter, name, installed_version in jobs
+            }
+            for future in as_completed(futures):
+                dep = future.result()
+                if dep is not None:
+                    results.append(dep)
+
+        return results
+
+    def _resolve(self, adapter: EcosystemAdapter, name: str, installed_version: str) -> Dependency | None:
+        eco = adapter.name
+
+        latest_version = self.cache.get_latest_version(eco, name)
+        if latest_version is None:
+            latest_version = adapter.get_latest_version(name)
+            self.cache.set_latest_version(eco, name, latest_version)
+
+        if latest_version is None:
+            return Dependency(
+                name=name,
+                installed_version=installed_version,
+                latest_version="unknown",
+                installed_date=None,
+                latest_date=None,
+                ecosystem=eco,
+            )
+
+        installed_date = self.cache.get_release_date(eco, name, installed_version)
+        if installed_date is None:
+            installed_date = adapter.get_release_date(name, installed_version)
+            self.cache.set_release_date(eco, name, installed_version, installed_date)
+
+        if latest_version == installed_version:
+            latest_date = installed_date
+        else:
+            latest_date = self.cache.get_release_date(eco, name, latest_version)
+            if latest_date is None:
+                latest_date = adapter.get_release_date(name, latest_version)
+                self.cache.set_release_date(eco, name, latest_version, latest_date)
+
+        return Dependency(
+            name=name,
+            installed_version=installed_version,
+            latest_version=latest_version,
+            installed_date=installed_date,
+            latest_date=latest_date,
+            ecosystem=eco,
+        )

libyear_multi/scoring.py

@@ -0,0 +1,59 @@
+"""Aggregate scoring on top of a list of Dependency results."""
+
+from dataclasses import dataclass
+from statistics import mean, median
+
+from .core import Dependency
+
+
+@dataclass
+class DependencyAgeScore:
+    total_libyears: float
+    avg_libyears: float
+    median_libyears: float
+    max_libyears: float
+    pct_severely_outdated: float  # Fraction of dependencies beyond the threshold.
+    dependency_count: int
+    unresolved_count: int  # Dependencies without release dates.
+
+    def to_risk_band(self) -> str:
+        if self.dependency_count == 0:
+            return "unknown"
+        if self.avg_libyears < 0.5 and self.pct_severely_outdated < 0.05:
+            return "low"
+        elif self.avg_libyears < 1.5 and self.pct_severely_outdated < 0.20:
+            return "moderate"
+        elif self.avg_libyears < 3.0 and self.pct_severely_outdated < 0.40:
+            return "high"
+        else:
+            return "severe"
+
+
+def score_dependency_age(dependencies: list[Dependency], severe_threshold_years: float = 2.0) -> DependencyAgeScore:
+    valid = [d for d in dependencies if d.libyears is not None]
+    unresolved = len(dependencies) - len(valid)
+
+    if not valid:
+        return DependencyAgeScore(0, 0, 0, 0, 0, len(dependencies), unresolved)
+
+    years = [d.libyears for d in valid]
+    severe = [y for y in years if y > severe_threshold_years]
+
+    return DependencyAgeScore(
+        total_libyears=round(sum(years), 2),
+        avg_libyears=round(mean(years), 2),
+        median_libyears=round(median(years), 2),
+        max_libyears=round(max(years), 2),
+        pct_severely_outdated=round(len(severe) / len(years), 2),
+        dependency_count=len(valid),
+        unresolved_count=unresolved,
+    )
+
+
+def summary_line(score: DependencyAgeScore) -> str:
+    return (
+        f"{score.dependency_count} dependencies scanned: "
+        f"{score.total_libyears} total libyears of staleness "
+        f"(avg {score.avg_libyears} yrs/package, "
+        f"{int(score.pct_severely_outdated * 100)}% severely outdated)."
+    )

libyear_multi-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: libyear-multi
+Version: 0.1.0
+Summary: Language-agnostic libyear: dependency staleness scoring across PyPI, npm, crates.io, RubyGems and more.
+Author: Shreyas Dhakal
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# libyear-multi
+
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+
+`libyear-multi` measures dependency staleness across the package managers used
+by a project. It detects supported manifests, looks up release dates, and
+reports a single score that can be used to prioritise maintenance work.
+
+The [libyear](https://libyear.com/) metric measures dependency age in calendar
+time rather than semantic-version distance. A package released three years ago
+whose latest release shipped yesterday represents approximately three libyears
+of staleness.
+
+## Highlights
+
+- Scans multiple ecosystems in one repository, including monorepos.
+- Reports total, average, median, and maximum libyears.
+- Classifies results into low, moderate, high, and severe risk bands.
+- Provides both human-readable and JSON output.
+- Caches registry responses locally to reduce repeated network requests.
+
+## Supported Ecosystems
+
+| Ecosystem | Manifest file | Registry |
+| --- | --- | --- |
+| Python | `requirements.txt` with pinned `==` versions | PyPI |
+| Node.js | `package.json` | npm registry |
+| Rust | `Cargo.lock` | crates.io |
+| Ruby | `Gemfile.lock` | RubyGems |
+
+Additional adapters are welcome. See [Adding an ecosystem](#adding-an-ecosystem).
+
+## Installation
+
+```bash
+python -m pip install -e .
+```
+
+The package is not published to PyPI yet. Install it from a clone or use the
+`libyear_multi/` package directly.
+
+## Usage
+
+### Command line
+
+```bash
+python -m libyear_multi.cli /path/to/project
+```
+
+Example output:
+
+```text
+14 dependencies scanned: 22.4 total libyears of staleness (avg 1.6 yrs/package, 21% severely outdated).
+Risk band: high
+
+Most outdated dependencies:
+  [npm] left-pad: 1.1.0 -> 1.3.0  (4.2 libyears)
+  [pypi] requests: 2.20.0 -> 2.32.3  (3.8 libyears)
+```
+
+Use JSON output for scripts and CI integrations:
+
+```bash
+python -m libyear_multi.cli /path/to/project --json
+```
+
+The number of concurrent registry lookups can be configured with
+`--max-workers`.
+
+### Python API
+
+```python
+from libyear_multi import LibyearScanner, score_dependency_age, summary_line
+
+scanner = LibyearScanner()
+dependencies = scanner.scan("/path/to/project")
+
+score = score_dependency_age(dependencies)
+print(summary_line(score))
+print(score.to_risk_band())
+
+for dependency in dependencies:
+    print(dependency.name, dependency.ecosystem, dependency.libyears)
+```
+
+## How It Works
+
+1. Each adapter checks whether its manifest exists in the target directory.
+2. Detected adapters parse the manifest into package and installed-version pairs.
+3. Registry APIs provide the latest version and release dates.
+4. Staleness is calculated as `(latest_date - installed_date).days / 365.25`.
+5. Individual results are aggregated into a project score.
+
+Release dates are cached permanently in
+`~/.cache/libyear-multi/cache.sqlite3`. Latest-version lookups expire after 24
+hours.
+
+## Development
+
+Clone the repository and install the development dependencies:
+
+```bash
+git clone https://github.com/shreyasdhakal/libyear-multi.git
+cd libyear-multi
+python -m pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+python -m pytest
+```
+
+Before opening a pull request, make sure tests pass and that changes are
+covered by tests where practical. Network-dependent registry calls are not part
+of the unit test suite.
+
+## Adding an Ecosystem
+
+Subclass `EcosystemAdapter` in `libyear_multi/core.py` and implement its four
+abstract methods:
+
+```python
+from datetime import datetime
+
+from libyear_multi.core import EcosystemAdapter
+
+
+class MyAdapter(EcosystemAdapter):
+    name = "my_ecosystem"
+
+    def detect(self, project_path: str) -> bool: ...
+    def list_dependencies(self, project_path: str) -> list[tuple[str, str]]: ...
+    def get_latest_version(self, name: str) -> str | None: ...
+    def get_release_date(self, name: str, version: str) -> datetime | None: ...
+```
+
+Register the adapter in `libyear_multi/adapters/__init__.py` and add parsing
+tests in `tests/`. Good future candidates include Go, Maven, Composer, and
+NuGet.
+
+## Known Limitations
+
+- Python adapters currently expect pinned `==` versions.
+- Rust and Ruby adapters read lockfiles, while npm currently reads `package.json`.
+- Non-registry npm specifications such as Git URLs and workspace references are skipped.
+- Transitive dependencies are only included when they appear in a parsed lockfile.
+- Large repositories may encounter registry rate limits. The default worker limit is eight and responses are cached.
+- The metric uses registry release dates and does not measure repository activity or abandonment.
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before
+submitting a change. Bug reports, documentation improvements, new adapters, and
+focused fixes are all useful.
+
+## Security
+
+Please report suspected vulnerabilities privately by following the instructions
+in [SECURITY.md](SECURITY.md). Do not disclose exploitable details in a public
+issue.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).
+
+Copyright (c) 2026 Shreyas Dhakal.

libyear_multi-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+libyear_multi/__init__.py,sha256=kqfj35KfMj9ZOz3qKRgtxrWuMIJJh3EYJCjUp65lmQs,373
+libyear_multi/cache.py,sha256=28GTlybZCfz4Q7s8DhdV3NvPR3CBWylduIfqthiX4Yo,3698
+libyear_multi/cli.py,sha256=TjHOleW8GQC9iXpmWgyXVmxAbwQ0yxDBTsQgFhkdge4,2603
+libyear_multi/core.py,sha256=0ZIIcSgh6NUgHrk3Y92HaDUg7DwDTqkWpBBU2czrda8,1695
+libyear_multi/scanner.py,sha256=tSQwSef0fYlrbgJzDzG66-Ulz21IFWVTn53fKTGuF_k,2989
+libyear_multi/scoring.py,sha256=IYY52bfJPAne_LkiGuU2nezmYDSqavt2JKfXRlLsmJM,2043
+libyear_multi/adapters/__init__.py,sha256=4HIt64uduV4AnVdZTuG2-yKBE2JICQOXnMbOeSCZyPw,316
+libyear_multi/adapters/cargo.py,sha256=nilB1tSpALYwbQDzte10ScFG5-ulGx9-CMlQ2XLrBG8,1997
+libyear_multi/adapters/npm.py,sha256=eu4Y-s6MBEDD5buaZ9GhtXnaqvfvxcWTobwWCBfMprQ,1762
+libyear_multi/adapters/pypi.py,sha256=2zIDfn3bpYqtxCebX02D78EbmeLlyWE0v4rMYqWFAZ8,1710
+libyear_multi/adapters/rubygems.py,sha256=PohmB1YuQE_VUHukJXKtEVk-KEkertZVVnTaQ0gQapc,2420
+libyear_multi-0.1.0.dist-info/licenses/LICENSE,sha256=U7l75bzTn7dkL8LRURoaPfhgjC2wilSMhiN2BpRJNDs,1071
+libyear_multi-0.1.0.dist-info/METADATA,sha256=5kq6Cv9AHBxu8fqptrtrkK6s09qjC15M7l3m72brx_Y,5602
+libyear_multi-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+libyear_multi-0.1.0.dist-info/entry_points.txt,sha256=XWNR4h73BsyQmd9HXUSL9I2DKtxjTzCy3hKEzHfA6-Y,57
+libyear_multi-0.1.0.dist-info/top_level.txt,sha256=JkJnOisb2AwwySvV2gzf4zxg97c8AV8hHYN3DXna2Qs,14
+libyear_multi-0.1.0.dist-info/RECORD,,

libyear_multi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

libyear_multi-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+libyear-multi = libyear_multi.cli:main

libyear_multi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreyas Dhakal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

libyear_multi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+libyear_multi