ossiq 0.1.0__py3-none-any.whl

ossiq/__init__.py

@@ -0,0 +1,4 @@
+"""Top-level package for Update Burden."""
+
+__author__ = """Maksym Klymyshyn"""
+__email__ = "klymyshyn@gmail.com"

ossiq/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

ossiq/adapters/api.py

@@ -0,0 +1,47 @@
+"""
+Factory to instantiate API clients
+"""
+
+from ossiq.adapters.api_npm import PackageRegistryApiNpm
+from ossiq.adapters.api_osv import CveApiOsv
+from ossiq.adapters.api_pypi import PackageRegistryApiPypi
+from ossiq.domain.common import ProjectPackagesRegistry, RepositoryProvider
+from ossiq.settings import Settings
+
+from .api_github import SourceCodeProviderApiGithub
+from .api_interfaces import AbstractCveDatabaseApi, AbstractPackageRegistryApi, AbstractSourceCodeProviderApi
+
+
+def create_source_code_provider(provider_type: RepositoryProvider, settings: Settings) -> AbstractSourceCodeProviderApi:
+    """
+    Return source code provider (like Github) using factory and respective type
+    """
+    if provider_type == RepositoryProvider.PROVIDER_GITHUB:
+        return SourceCodeProviderApiGithub(settings.github_token)
+    else:
+        raise ValueError(f"Unknown source code provider type: {provider_type}")
+
+
+def create_package_registry_api(
+    package_registry: ProjectPackagesRegistry, settings: Settings
+) -> AbstractPackageRegistryApi:
+    """
+    Create instance of a specific ecosystem's package registry API
+    """
+
+    if package_registry == ProjectPackagesRegistry.NPM:
+        return PackageRegistryApiNpm(settings)
+    elif package_registry == ProjectPackagesRegistry.PYPI:
+        return PackageRegistryApiPypi(settings)
+    else:
+        raise ValueError(f"Unknown package registry: {package_registry}")
+
+
+def create_cve_database() -> AbstractCveDatabaseApi:
+    """
+    Return CVE database (like osv.dev). The purpose is little different from
+    Source Code Provider or Packages Registry/Ecosystem: there might be
+    more than one CSV database. For externel clients it should look like a
+    single database instance still.
+    """
+    return CveApiOsv()

ossiq/adapters/api_github.py

@@ -0,0 +1,295 @@
+"""
+Implementation of SourceCodeApiClient for Github
+"""
+
+import datetime
+import itertools
+import re
+from collections.abc import Callable, Iterable
+
+import requests
+from rich.console import Console
+
+from ..domain.common import VERSION_DATA_SOURCE_GITHUB_RELEASES, VERSION_DATA_SOURCE_GITHUB_TAGS, RepositoryProvider
+from ..domain.exceptions import GithubRateLimitError
+from ..domain.repository import Repository
+from ..domain.version import Commit, PackageVersion, RepositoryVersion, User, sort_versions
+from .api_interfaces import AbstractSourceCodeProviderApi
+
+console = Console()
+
+GITHUB_API = "https://api.github.com"
+
+
+class SourceCodeProviderApiGithub(AbstractSourceCodeProviderApi):
+    """
+    Implementation of SourceCodeApiClient for Github
+    """
+
+    repository_provider: RepositoryProvider = RepositoryProvider.PROVIDER_GITHUB
+
+    github_token: str | None
+
+    def __init__(self, github_token: str | None):
+        self.github_token = github_token
+        if not self.github_token:
+            # FIXME: pass warning
+            pass
+
+    def __repr__(self):
+        return "<SourceCodeProviderApiGithub instance>"
+
+    def _extract_next_url(self, link_header: str):
+        """
+        Parse header <https://api.github.com/repositories/47118129/tags?page=2>;
+            rel="next" and extract URL
+        """
+        if link_header is None:
+            return None
+
+        match = re.search(r"<(.*?)>; rel=\"next\"", link_header)
+        if match:
+            return match.group(1)
+
+        return None
+
+    def _make_github_api_request(self, url: str, timeout: int = 15) -> tuple[str | None, dict]:
+        """
+        Make a request to the GitHub API and properly handle pagination
+        """
+        headers = {}
+        if self.github_token:
+            headers["Authorization"] = f"Bearer {self.github_token}"
+
+        response = requests.get(url, timeout=timeout, headers=headers)
+
+        # Basically let user know that we're done here with Github.
+        if response.status_code == 403:
+            remaining_rate_limit = response.headers.get("x-ratelimit-remaining", "N/A")
+
+            try:
+                reset_rate_limit_time = datetime.datetime.fromtimestamp(
+                    int(response.headers.get("x-ratelimit-reset", "N/A"))
+                ).isoformat()
+            except (ValueError, TypeError):
+                reset_rate_limit_time = "N/A"
+
+            total_rate_limit = response.headers.get("x-ratelimit-limit", "N/A")
+
+            raise GithubRateLimitError(
+                remaining=remaining_rate_limit,
+                total=total_rate_limit,
+                reset_time=reset_rate_limit_time,
+            )
+
+        response.raise_for_status()
+
+        return self._extract_next_url(response.headers.get("Link", None)), response.json()
+
+    def _paginate_github_api_request(self, url: str) -> Iterable[dict]:
+        """
+        Paginate responses from Github API
+        """
+        next_url = url
+
+        while next_url:
+            next_url, data = self._make_github_api_request(next_url)
+            yield from data
+
+    def _load_releases(self, repository: Repository, versions_set: set[str]) -> Iterable[RepositoryVersion]:
+        """
+        Fetch releases from a GitHub repo that match the provided versions.
+        """
+        url = f"{GITHUB_API}/repos/{repository.owner}/{repository.name}/releases"
+
+        n = 0
+        # NOTE: we need to pull all the releases we're interested in and then break iteration
+        for release in self._paginate_github_api_request(url):
+            normalized_tag = release["tag_name"]
+            if normalized_tag in versions_set:
+                yield RepositoryVersion(
+                    version_source_type=VERSION_DATA_SOURCE_GITHUB_RELEASES,
+                    version=normalized_tag,
+                    ref_name=release["tag_name"],
+                    release_name=release["name"],
+                    release_notes=release.get("body", None),
+                    source_url=release["html_url"],
+                    patch_url=None,
+                    commits=None,
+                    ref_previous=None,
+                )
+                n += 1
+
+            if n == len(versions_set):
+                break
+
+    def _load_commits_between_refs(
+        self, repository: Repository, start_ref: str | None, end_ref: str | None
+    ) -> tuple[str, list[Commit]] | tuple[None, None]:
+        """
+        Load commits between two git references (tags/commits) and its patch URL.
+
+        NOTE: A potential optimization is to pull all commits between the oldest and
+        newest versions in one API call, then associate them with tags client-side.
+        This would reduce API calls but increase complexity.
+        """
+
+        if start_ref or not end_ref:
+            return None, None
+
+        compare_url = f"{GITHUB_API}/repos/{repository.owner}/{repository.name}/compare/{start_ref}...{end_ref}"
+
+        _, compare_data = self._make_github_api_request(compare_url)
+
+        commits_raw = compare_data.get("commits", [])
+        commits = []
+
+        for commit_data in commits_raw:
+            commit = commit_data["commit"]
+            author, committer = commit_data.get("author"), commit_data.get("committer")
+
+            author_user = None
+            if author and commit.get("author"):
+                author_user = User(
+                    id=author.get("id"),
+                    username=author.get("login"),
+                    profile_url=author.get("html_url"),
+                    display_name=commit["author"].get("name"),
+                    email=commit["author"].get("email"),
+                )
+
+            committer_user = None
+            if committer and commit.get("committer"):
+                committer_user = User(
+                    id=committer.get("id"),
+                    username=committer.get("login"),
+                    profile_url=committer.get("html_url"),
+                    display_name=commit["committer"].get("name"),
+                    email=commit["committer"].get("email"),
+                )
+
+            commits.append(
+                Commit(
+                    sha=commit_data["sha"],
+                    message=commit["message"],
+                    author=author_user,
+                    committer=committer_user,
+                    authored_at=commit.get("author", {}).get("date"),
+                    committed_at=commit.get("committer", {}).get("date"),
+                )
+            )
+
+        return str(compare_data.get("patch_url")), commits
+
+    def _get_diff_for_version(self, repository: Repository, repository_version: RepositoryVersion) -> RepositoryVersion:
+        """
+        Pull commits associated with the given RepositoryVersion by
+        comparing it to its previous ref.
+        """
+
+        patch_url, commits = self._load_commits_between_refs(
+            repository,
+            repository_version.ref_previous,
+            repository_version.ref_name,
+        )
+
+        repository_version.patch_url = patch_url
+        repository_version.commits = commits
+
+        return repository_version
+
+    def _load_versions_from_tags(self, repository: Repository, versions_set: set[str]) -> Iterable[RepositoryVersion]:
+        """
+        Fetch tags from a GitHub repo and convert them to RepositoryVersion objects.
+        """
+        url = f"{GITHUB_API}/repos/{repository.owner}/{repository.name}/tags"
+
+        n = 0
+        for tag in self._paginate_github_api_request(url):
+            version = tag["name"]
+            if version in versions_set:
+                source_url = f"{repository.html_url}/releases/tag/{tag['name']}"
+                yield RepositoryVersion(
+                    version_source_type=VERSION_DATA_SOURCE_GITHUB_TAGS,
+                    version=version,
+                    ref_name=tag["name"],
+                    release_name=None,
+                    source_url=source_url,
+                    commits=None,
+                    ref_previous=None,
+                    release_notes=None,
+                    patch_url=None,
+                )
+                n += 1
+            if n == len(versions_set):
+                break
+
+    def repository_info(self, repository_url: str | None) -> Repository:
+        """
+        Extract GitHub repository info from a given github URL.
+        """
+        if repository_url is None:
+            raise ValueError("Repository URL cannot be None")
+        s = repository_url.strip().removeprefix("git+").removeprefix("https://")
+        m = re.search(r"github\.com[:/](?P<owner>[^/]+)/(?P<name>[^/.]+)", s)
+
+        if not m:
+            raise ValueError(f"Invalid GitHub URL: {repository_url}")
+
+        owner, repo_name = m.group("owner"), m.group("name")
+
+        # Fetch repository details to get the description
+        repo_api_url = f"{GITHUB_API}/repos/{owner}/{repo_name}"
+        _, repo_data = self._make_github_api_request(repo_api_url)
+
+        return Repository(
+            provider=RepositoryProvider.PROVIDER_GITHUB,
+            name=repo_name,
+            owner=owner,
+            description=repo_data.get("description"),
+            html_url=f"https://github.com/{owner}/{repo_name}",
+        )
+
+    def repository_versions(
+        self,
+        repository: Repository,
+        package_versions: list[PackageVersion],
+        comparator: Callable,
+    ) -> Iterable[RepositoryVersion]:
+        """
+        Pull versions info available from the given repository. Github releases
+        is the default way to get it, then fallback to tags.
+        """
+        versions_set = {pv.version for pv in package_versions}
+
+        # 1. Try loading from releases first, as they contain more metadata.
+        releases = list(self._load_releases(repository, versions_set))
+
+        released_versions = releases
+
+        # 2. If some versions were not found as releases, fall back to checking tags.
+        # This handles cases where a version is tagged but not formally released.
+        if len(releases) != len(versions_set):
+            released_versions_set = {rv.version for rv in releases}
+            missing_versions = versions_set - released_versions_set
+            tags_as_versions = self._load_versions_from_tags(repository, missing_versions)
+            released_versions = list(itertools.chain(releases, tags_as_versions))
+
+        # 3. Sort all found versions semantically.
+        versions = sort_versions(released_versions, comparator=comparator)
+        if not versions:
+            return
+
+        # 4. The first (oldest) version is our baseline; yield it as is.
+        yield versions[0]
+
+        # 5. For all subsequent versions, calculate the commit difference from the previous one.
+        for version_from, version_to in itertools.zip_longest(versions, versions[1:]):
+            if not version_to:
+                break
+
+            version_to.ref_previous = version_from.ref_name
+
+            version_to_with_diff = self._get_diff_for_version(repository, version_to)
+
+            yield version_to_with_diff

ossiq/adapters/api_interfaces.py

@@ -0,0 +1,138 @@
+"""
+Interfaces related to external APIs
+"""
+
+import abc
+from collections.abc import Callable, Iterable
+
+from ossiq.domain.common import ProjectPackagesRegistry
+from ossiq.domain.cve import CVE
+from ossiq.domain.package import Package
+from ossiq.domain.packages_manager import PackageManagerType
+from ossiq.domain.project import Project
+from ossiq.settings import Settings
+
+from ..domain.repository import Repository
+from ..domain.version import PackageVersion, RepositoryVersion, VersionsDifference
+
+
+class AbstractSourceCodeProviderApi(abc.ABC):
+    """
+    Abstract client to communicate with source code repositories like GitHub
+    """
+
+    @abc.abstractmethod
+    def repository_info(self, repository_url: str | None) -> Repository:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def repository_versions(
+        self, repository: Repository, package_versions: list[PackageVersion], comparator: Callable
+    ) -> Iterable[RepositoryVersion]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __repr__(self):
+        raise NotImplementedError
+
+
+class AbstractPackageRegistryApi(abc.ABC):
+    """
+    Abstract client to communicate with package registries like PyPi or NPM
+    """
+
+    settings: Settings
+    package_registry: ProjectPackagesRegistry
+
+    @staticmethod
+    @abc.abstractmethod
+    def compare_versions(v1: str, v2: str) -> int:
+        """
+        Compare two versions regardless of the registry.
+
+        Versioning is registry-specific, for example
+        JavaScript/NPM follows Semantic Versioning strictly,
+        while Python/PyPI ecosystem follows PEP 440.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    @abc.abstractmethod
+    def difference_versions(v1_str: str | None, v2_str: str | None) -> VersionsDifference:
+        """
+        Calculate version difference using registry-specific semantics.
+
+        Categorizes the difference between two versions (major, minor, patch, etc.)
+        based on the versioning scheme used by the registry.
+
+        Args:
+            v1: First version string (e.g., installed version)
+            v2: Second version string (e.g., latest version)
+
+        Returns:
+            VersionsDifference object with categorized diff index
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def package_info(self, package_name: str) -> Package:
+        """
+        Get a particular package info
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def package_versions(self, package_name: str) -> Iterable[PackageVersion]:
+        """
+        Get a particular package versions between what is installed
+        currently in the project and the latest version available
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __repr__(self):
+        raise NotImplementedError
+
+
+class AbstractCveDatabaseApi(abc.ABC):
+    """
+    Abstract client to communicate with CVEs repositories like osv.dev or github CVE APIs
+    """
+
+    @abc.abstractmethod
+    def get_cves_for_package(self, package: Package, version: PackageVersion) -> set[CVE]:
+        """
+        Method to return a particular CVE info
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __repr__(self):
+        raise NotImplementedError
+
+
+class AbstractPackageManagerApi(abc.ABC):
+    """
+    Abstract Package Manager to extract installed versions
+    of packages from different package managers.
+    """
+
+    settings: Settings
+    package_manager_type: PackageManagerType
+    project_path: str
+
+    @staticmethod
+    @abc.abstractmethod
+    def has_package_manager(project_path: str) -> bool:
+        """
+        Detect that package manager is used in a project_path
+        """
+        pass
+
+    @abc.abstractmethod
+    def project_info(self) -> Project:
+        """
+        Extract project dependencies using file format from a specific
+        package manager.
+        """
+        pass

ossiq/adapters/api_npm.py

@@ -0,0 +1,195 @@
+"""
+Implementation of Package Registry API client for NPM
+"""
+
+from collections.abc import Iterable
+
+import requests
+import semver
+from rich.console import Console
+
+from ossiq.adapters.api_interfaces import AbstractPackageRegistryApi
+from ossiq.domain.common import ProjectPackagesRegistry
+from ossiq.domain.package import Package
+from ossiq.domain.version import (
+    VERSION_DIFF_BUILD,
+    VERSION_DIFF_MAJOR,
+    VERSION_DIFF_MINOR,
+    VERSION_DIFF_PATCH,
+    VERSION_DIFF_PRERELEASE,
+    VERSION_INVERSED_DIFF_TYPES_MAP,
+    VERSION_LATEST,
+    VERSION_NO_DIFF,
+    PackageVersion,
+    VersionsDifference,
+    create_version_difference_no_diff,
+)
+from ossiq.settings import Settings
+
+console = Console()
+
+NPM_REGISTRY = "https://registry.npmjs.org"
+NPM_REGISTRY_FRONT = "https://www.npmjs.com"
+
+NPM_DEPENDENCIES_SECTIONS = (
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+    # FIXME: consider pinned versions as well!
+)
+
+
+class PackageRegistryApiNpm(AbstractPackageRegistryApi):
+    """
+    Implementation of Package Registry API client for NPM
+    """
+
+    package_registry = ProjectPackagesRegistry.NPM
+    settings: Settings
+
+    @staticmethod
+    def compare_versions(v1: str, v2: str) -> int:
+        """
+        Compare two versions following Semantic Versioning.
+        """
+        return semver.Version.parse(v1).compare(semver.Version.parse(v2))
+
+    @staticmethod
+    def _calculate_semver_diff_index(v1: semver.Version, v2: semver.Version) -> int:
+        """
+        Calculate the most significant difference between two semver versions.
+
+        Compares version components in order of significance:
+        1. Major version
+        2. Minor version
+        3. Patch version
+        4. Prerelease
+        5. Build metadata
+
+        Args:
+            v1: First parsed semver version
+            v2: Second parsed semver version
+
+        Returns:
+            Diff index constant indicating the most significant difference level
+        """
+        if v1.major != v2.major:
+            return VERSION_DIFF_MAJOR
+
+        if v1.minor != v2.minor:
+            return VERSION_DIFF_MINOR
+
+        if v1.patch != v2.patch:
+            return VERSION_DIFF_PATCH
+
+        if v1.prerelease != v2.prerelease:
+            return VERSION_DIFF_PRERELEASE
+
+        if v1.build != v2.build:
+            return VERSION_DIFF_BUILD
+
+        return VERSION_NO_DIFF
+
+    @staticmethod
+    def difference_versions(v1_str: str | None, v2_str: str | None) -> VersionsDifference:
+        """
+        Calculate version difference using Semantic Versioning (semver) semantics.
+
+        NPM packages follow strict semver, so we parse and compare major, minor,
+        patch, prerelease, and build components.
+
+        Args:
+            v1_str: First version string (e.g., installed version)
+            v2_str: Second version string (e.g., latest version)
+
+        Returns:
+            VersionsDifference with categorized diff index
+        """
+        # Handle None/empty versions
+        if not v1_str or not v2_str:
+            return create_version_difference_no_diff(v1_str, v2_str)
+
+        # Optimize: check string equality before parsing
+        if v1_str == v2_str:
+            return VersionsDifference(
+                v1_str, v2_str, VERSION_LATEST, diff_name=VERSION_INVERSED_DIFF_TYPES_MAP[VERSION_LATEST]
+            )
+
+        # Parse versions
+        v1 = semver.Version.parse(v1_str)
+        v2 = semver.Version.parse(v2_str)
+
+        # Calculate the difference
+        diff_index = PackageRegistryApiNpm._calculate_semver_diff_index(v1, v2)
+
+        return VersionsDifference(str(v1), str(v2), diff_index, diff_name=VERSION_INVERSED_DIFF_TYPES_MAP[diff_index])
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+
+    def __repr__(self):
+        return "<PackageRegistryApiNpm instance>"
+
+    def _make_request(self, path: str, headers: dict | None = None, timeout: int = 15) -> dict:
+        """
+        Make request and handle retries and errors handling.
+        """
+        r = requests.get(f"{NPM_REGISTRY}{path}", timeout=timeout, headers=headers)
+        r.raise_for_status()
+        return r.json()
+
+    def package_info(self, package_name: str) -> Package:
+        """
+        Fetch npm info for a given package.
+        FIXME: raise custom exception if not found
+        """
+        response = self._make_request(f"/{package_name}")
+        distribution_tags = response.get("dist-tags", {"latest": None, "next": None})
+
+        return Package(
+            registry=ProjectPackagesRegistry.NPM,
+            name=response["name"],
+            latest_version=distribution_tags.get("latest", None),
+            next_version=distribution_tags.get("next", None),
+            repo_url=response.get("repository", {}).get("url", None),
+            author=response.get("author"),
+            homepage_url=response.get("homepage"),
+            description=response.get("description"),
+            package_url=f"{NPM_REGISTRY_FRONT}/package/{package_name}/",
+        )
+
+    def package_versions(self, package_name: str) -> Iterable[PackageVersion]:
+        """
+        Fetch npm versions for a given package.
+        """
+        response = self._make_request(f"/{package_name}")
+        # FIXME: raise custom exception if not found
+        versions = response.get("versions", [])
+        timestamp_map = response.get("time", {})
+        unpublished_response = timestamp_map.pop("unpublished", {})
+
+        # Package version is either published or unpublished
+        if unpublished_response:
+            unpublished_date_iso = unpublished_response.get("time", None)
+            for version in unpublished_response.get("versions", []):
+                yield PackageVersion(
+                    version=version,
+                    license=None,
+                    dependencies={},
+                    package_url=f"{NPM_REGISTRY_FRONT}/package/{package_name}/v/{version}",
+                    unpublished_date_iso=unpublished_date_iso,
+                    is_published=False,
+                )
+        else:
+            for version, details in versions.items():
+                yield PackageVersion(
+                    version=version,
+                    published_date_iso=timestamp_map.get(version, None),
+                    dependencies=details.get("dependencies", {}),
+                    license=details.get("license", None),
+                    runtime_requirements=details.get("engines", None),
+                    dev_dependencies=details.get("devDependencies", {}),
+                    description=details.get("description", None),
+                    package_url=f"{NPM_REGISTRY_FRONT}/package/{package_name}/v/{version}",
+                )