libyear-multi 0.1.0__tar.gz

libyear_multi-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,167 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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