java-dependency-analyzer 1.0.0__py3-none-any.whl

java_dependency_analyzer/models/dependency.py

@@ -0,0 +1,80 @@
+"""
+dependency module.
+
+Defines the core data models for dependencies and vulnerabilities.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from dataclasses import dataclass, field
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+
+@dataclass
+class Vulnerability:
+    """
+    Represents a single vulnerability found in a dependency.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    cve_id: str
+    summary: str
+    severity: str
+    affected_versions: list[str] = field(default_factory=list)
+    source: str = "osv"
+    reference_url: str = ""
+
+
+@dataclass
+class Dependency:
+    """
+    Represents a Java dependency with group, artifact, and version coordinates.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    group_id: str
+    artifact_id: str
+    version: str
+    scope: str = "compile"
+    depth: int = 0
+    transitive_dependencies: list["Dependency"] = field(default_factory=list)
+    vulnerabilities: list[Vulnerability] = field(default_factory=list)
+
+    @property
+    def coordinates(self) -> str:
+        """
+        Return Maven coordinates string in group:artifact:version format.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        return f"{self.group_id}:{self.artifact_id}:{self.version}"
+
+    @property
+    def maven_path(self) -> str:
+        """
+        Return the relative path to this artifact in a Maven repository.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        group_path = self.group_id.replace(".", "/")
+        return f"{group_path}/{self.artifact_id}/{self.version}"
+
+    def has_vulnerabilities(self) -> bool:
+        """
+        Return True if this dependency or any transitive dependency has vulnerabilities.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        if self.vulnerabilities:
+            return True
+        return any(dep.has_vulnerabilities() for dep in self.transitive_dependencies)

java_dependency_analyzer/models/report.py

@@ -0,0 +1,108 @@
+"""
+report module.
+
+Defines the ScanResult model for aggregating vulnerability scan findings.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from .dependency import Dependency
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+
+@dataclass
+class ScanResult:
+    """
+    Aggregates all findings from a dependency vulnerability scan.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    source_file: str
+    scanned_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    dependencies: list[Dependency] = field(default_factory=list)
+
+    @property
+    def total_dependencies(self) -> int:
+        """
+        Return the total count of all direct and transitive dependencies.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        return self._count_dependencies(self.dependencies)
+
+    @property
+    def vulnerable_dependencies(self) -> list[Dependency]:
+        """
+        Return a deduplicated flat list of all dependencies that have vulnerabilities.
+
+        Two nodes with identical (group_id, artifact_id, version) are treated as the
+        same dependency regardless of where they appear in the tree.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        result: list[Dependency] = []
+        seen: set[tuple[str, str, str]] = set()
+        self._collect_vulnerable(self.dependencies, result, seen)
+        return result
+
+    @property
+    def total_vulnerabilities(self) -> int:
+        """
+        Return the total number of individual vulnerabilities found across unique dependencies.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        return sum(len(dep.vulnerabilities) for dep in self.vulnerable_dependencies)
+
+    def _count_dependencies(self, deps: list[Dependency]) -> int:
+        """
+        Recursively count all dependencies in the tree.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        count = len(deps)
+        for dep in deps:
+            count += self._count_dependencies(dep.transitive_dependencies)
+        return count
+
+    @staticmethod
+    def _dep_key(dep: Dependency) -> tuple[str, str, str]:
+        """
+        Return a deduplication key for a dependency based on its coordinates.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        return (dep.group_id, dep.artifact_id, dep.version)
+
+    def _collect_vulnerable(
+        self,
+        deps: list[Dependency],
+        result: list[Dependency],
+        seen: set[tuple[str, str, str]],
+    ) -> None:
+        """
+        Recursively collect unique dependencies that have vulnerabilities.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        for dep in deps:
+            if dep.vulnerabilities:
+                key = self._dep_key(dep)
+                if key not in seen:
+                    seen.add(key)
+                    result.append(dep)
+            self._collect_vulnerable(dep.transitive_dependencies, result, seen)

java_dependency_analyzer/parsers/__init__.py

@@ -0,0 +1,11 @@
+"""
+parsers package.
+
+Provides dependency file parsers for Maven and Gradle build files.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"

java_dependency_analyzer/parsers/base.py

@@ -0,0 +1,150 @@
+"""
+base module.
+
+Defines the abstract base class for dependency file parsers and shared
+tree-building utilities.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from pathlib import Path
+
+from ..models.dependency import Dependency
+from ..util.logger import setup_logger
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+# Runtime scopes that contribute to the executable classpath
+RUNTIME_SCOPES = frozenset({"compile", "runtime", "implementation", "api", "runtimeOnly"})
+
+
+def attach_node(
+    dep: Dependency,
+    depth: int,
+    is_leaf: bool,
+    roots: list[Dependency],
+    stack: list[Dependency | None],
+) -> None:
+    """
+    Attach *dep* to the correct position in the dependency tree represented
+    by *roots* (top-level nodes) and *stack* (depth-indexed parent cursor).
+
+    *stack[d]* holds the :class:`Dependency` that is the current parent at
+    depth *d*.  After attaching *dep*, the stack is updated so that
+    ``stack[depth]`` points to *dep* (or ``None`` if *dep* is a leaf).
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    if depth == 0:
+        roots.append(dep)
+    else:
+        parent_depth = depth - 1
+        if parent_depth < len(stack) and stack[parent_depth] is not None:
+            stack[parent_depth].transitive_dependencies.append(dep)  # type: ignore[union-attr]
+
+    new_entry: Dependency | None = None if is_leaf else dep
+    if depth < len(stack):
+        stack[depth] = new_entry
+    else:
+        while len(stack) < depth:
+            stack.append(None)
+        stack.append(new_entry)
+
+
+def build_tree_from_lines(
+    lines: list[str],
+    line_to_entry: Callable[[str], tuple[int, bool, Dependency] | None],
+) -> list[Dependency]:
+    """
+    Build a nested dependency tree from raw text *lines*.
+
+    Each line is passed through *line_to_entry*, which should return a
+    ``(depth, is_leaf, dep)`` tuple or *None* to skip the line.  The
+    resulting entries are assembled into a tree using :func:`attach_node`.
+
+    This function is the shared core of both :class:`GradleDepTreeParser`
+    and :class:`MavenDepTreeParser`.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+    roots: list[Dependency] = []
+    stack: list[Dependency | None] = []
+    for line in lines:
+        entry = line_to_entry(line)
+        if entry is None:
+            continue
+        depth, is_leaf, dep = entry
+        attach_node(dep, depth, is_leaf, roots, stack)
+    return roots
+
+
+class DependencyParser(ABC):
+    """
+    Abstract base class for all dependency file parsers.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    @abstractmethod
+    def parse(self, file_path: str) -> list[Dependency]:
+        """
+        Parse the given build file and return a list of direct dependencies.
+
+        Only runtime-relevant scopes are returned (compile, runtime,
+        implementation, api, runtimeOnly).
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+
+
+class DepTreeParser(DependencyParser):
+    """
+    Intermediate base class for parsers that read pre-generated dependency
+    tree text files (e.g. ``gradle dependencies`` or ``mvn dependency:tree``).
+
+    Subclasses must implement :meth:`_line_to_entry` to convert a single
+    text line into a ``(depth, is_leaf, dep)`` entry.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    def parse(self, file_path: str) -> list[Dependency]:
+        """
+        Read *file_path* and build a dependency tree by passing each line
+        through :meth:`_line_to_entry`.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        _logger.info("Parsing dependency tree from '%s'", file_path)
+        try:
+            content = Path(file_path).read_text(encoding="utf-8")
+        except OSError as exc:
+            _logger.error("Failed to read file: %s", exc)
+            return []
+
+        lines = content.splitlines()
+        return build_tree_from_lines(lines, self._line_to_entry)
+
+    @abstractmethod
+    def _line_to_entry(
+        self, line: str
+    ) -> tuple[int, bool, Dependency] | None:
+        """
+        Convert a single dependency-tree text line into a
+        ``(depth, is_leaf, dep)`` tuple, or return *None* to skip the line.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """

java_dependency_analyzer/parsers/gradle_dep_tree_parser.py

@@ -0,0 +1,125 @@
+"""
+gradle_dep_tree_parser module.
+
+Parses the text output of ``gradle dependencies`` to reconstruct
+the full dependency tree including transitive dependencies.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import re
+
+from ..models.dependency import Dependency
+from ..util.logger import setup_logger
+from .base import DepTreeParser
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+# Matches the tree connector characters at the start of a dependency line.
+# Each level of indentation is exactly 5 characters wide ("     " or "|    ").
+_INDENT_UNIT = 5
+_CONNECTOR_RE = re.compile(r"^((?:[|\\+]\s{3,4}|\s{5})*)([+\\])--- (.+)$")
+
+# Matches a resolved version arrow, e.g. "1.0 -> 2.0" or "RELEASE -> 4.16.0"
+_VERSION_ARROW_RE = re.compile(r"\s*->\s*(\S+)$")
+
+# Suffix appended to repeated subtree roots by Gradle
+_REPEATED_SUFFIX = " (*)"
+
+# Lines annotated as constraints (not actual dependencies)
+_CONSTRAINT_SUFFIX = " (c)"
+
+# Gradle coordinates: group:artifact:version
+_COORD_RE = re.compile(r"^([^:]+):([^:]+):(.+)$")
+
+
+class GradleDepTreeParser(DepTreeParser):
+    """
+    Parses the plain-text output of ``gradle dependencies`` and reconstructs
+    the dependency tree as a list of :class:`~java_dependency_analyzer.models.dependency.Dependency`
+    objects with nested ``transitive_dependencies``.
+
+    The parser is format-agnostic regarding the configuration name; it processes
+    the first dependency-tree block it encounters.  Users should redirect the
+    output of the configuration they care about (e.g. ``runtimeClasspath``) into
+    a text file and pass that file here.
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _line_to_entry(
+        self, line: str
+    ) -> tuple[int, bool, Dependency] | None:
+        """
+        Convert a single Gradle dep-tree line to a ``(depth, is_leaf, dep)``
+        entry, or return *None* to skip the line.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        if line.rstrip().endswith(_CONSTRAINT_SUFFIX):
+            return None
+
+        match = _CONNECTOR_RE.match(line)
+        if match is None:
+            return None
+
+        indent_str, coord_str = match.group(1), match.group(3)
+        depth = len(indent_str) // _INDENT_UNIT
+
+        is_leaf = coord_str.endswith(_REPEATED_SUFFIX)
+        if is_leaf:
+            coord_str = coord_str[: -len(_REPEATED_SUFFIX)]
+
+        dep = self._parse_coordinate(coord_str, depth)
+        if dep is None:
+            return None
+
+        return depth, is_leaf, dep
+
+    def _parse_coordinate(self, coord_str: str, depth: int) -> Dependency | None:
+        """
+        Convert a Gradle coordinate string (with optional ``->`` resolution)
+        into a :class:`Dependency`.  Returns *None* if the string cannot be
+        parsed.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        # Resolve version arrows: "group:artifact:1.0 -> 2.0"
+        arrow_match = _VERSION_ARROW_RE.search(coord_str)
+        if arrow_match:
+            resolved_version = arrow_match.group(1)
+            # Strip the arrow portion from the coordinate
+            coord_str = coord_str[: arrow_match.start()]
+        else:
+            resolved_version = None
+
+        coord_match = _COORD_RE.match(coord_str.strip())
+        if coord_match is None:
+            _logger.debug("Could not parse coordinate: %s", coord_str)
+            return None
+
+        group_id = coord_match.group(1).strip()
+        artifact_id = coord_match.group(2).strip()
+        version = resolved_version or coord_match.group(3).strip()
+
+        if not group_id or not artifact_id or not version:
+            return None
+
+        return Dependency(
+            group_id=group_id,
+            artifact_id=artifact_id,
+            version=version,
+            scope="runtime",
+            depth=depth,
+        )

java_dependency_analyzer/parsers/gradle_parser.py

@@ -0,0 +1,206 @@
+"""
+gradle_parser module.
+
+Parses Gradle build files (build.gradle and build.gradle.kts) to extract
+runtime dependencies using regex-based analysis.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import re
+from pathlib import Path
+
+from ..models.dependency import Dependency
+from ..util.logger import setup_logger
+from .base import DependencyParser, RUNTIME_SCOPES
+
+__author__ = "Ron Webb"
+__since__ = "1.0.0"
+
+_logger = setup_logger(__name__)
+
+# Matches Groovy DSL shorthand: implementation 'group:artifact:version'
+_GROOVY_SHORTHAND = re.compile(
+    r"""(?:^|\s)(?P<config>implementation|api|compile|runtimeOnly|runtime)\s+['"]"""
+    r"""(?P<group>[^:'"]+):(?P<artifact>[^:'"]+):(?P<version>[^:'"]+)['"]""",
+    re.MULTILINE,
+)
+
+# Matches Kotlin DSL shorthand: implementation("group:artifact:version")
+_KOTLIN_SHORTHAND = re.compile(
+    r"""(?:^|\s)(?P<config>implementation|api|compile|runtimeOnly|runtime)\s*\("""
+    r"""["'](?P<group>[^:'"]+):(?P<artifact>[^:'"]+):(?P<version>[^:'"]+)["']\)""",
+    re.MULTILINE,
+)
+
+# Matches Groovy block syntax:
+#   implementation group: 'g', name: 'a', version: 'v'
+_GROOVY_BLOCK = re.compile(
+    r"""(?:^|\s)(?P<config>implementation|api|compile|runtimeOnly|runtime)\s+"""
+    r"""group:\s*['"](?P<group>[^'"]+)['"]\s*,\s*name:\s*"""
+    r"""['"](?P<artifact>[^'"]+)['"]\s*,\s*version:\s*['"](?P<version>[^'"]+)['"]""",
+    re.MULTILINE,
+)
+
+# Matches Groovy ext { } block content (no nested braces)
+_EXT_BLOCK_PATTERN = re.compile(r"\bext\s*\{([^}]*)\}", re.DOTALL)
+
+# Matches simple key = 'value' or key = "value" assignments inside ext blocks
+_EXT_PROPERTY_PATTERN = re.compile(
+    r"""^[ \t]*(\w+)\s*=\s*['"]([^'"]+)['"]""",
+    re.MULTILINE,
+)
+
+# Matches Groovy `def varName = 'value'` or Kotlin `val varName = "value"`
+_DEF_VAL_PATTERN = re.compile(
+    r"""(?:^|\s)(?:def|val)\s+(\w+)\s*=\s*["']([^"']+)["']""",
+    re.MULTILINE,
+)
+
+# Matches Kotlin block syntax:
+#   implementation(group = "g", name = "a", version = "v")
+_KOTLIN_BLOCK = re.compile(
+    r"""(?:^|\s)(?P<config>implementation|api|compile|runtimeOnly|runtime)\s*\(\s*"""
+    r"""group\s*=\s*["'](?P<group>[^'"]+)["']\s*,\s*name\s*=\s*"""
+    r"""["'](?P<artifact>[^'"]+)["']\s*,\s*version\s*=\s*["'](?P<version>[^'"]+)["']\s*\)""",
+    re.MULTILINE,
+)
+
+
+class GradleParser(DependencyParser):
+    """
+    Parses Gradle build files (Groovy DSL and Kotlin DSL) to extract runtime dependencies.
+
+    Supports both shorthand notation and named-parameter block notation.
+    Handles build.gradle (Groovy) and build.gradle.kts (Kotlin DSL).
+
+    :author: Ron Webb
+    :since: 1.0.0
+    """
+
+    def parse(self, file_path: str) -> list[Dependency]:
+        """
+        Parse the given Gradle build file and return a list of direct dependencies.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        _logger.info("Parsing Gradle build file: %s", file_path)
+        path = Path(file_path)
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            _logger.error("Failed to read Gradle file: %s", exc)
+            return []
+
+        is_kotlin_dsl = path.suffix == ".kts"
+        content = self._strip_comments(content, is_kotlin_dsl)
+        ext_props = self._extract_ext_properties(content)
+        if ext_props:
+            content = self._resolve_variables(content, ext_props)
+
+        seen: set[str] = set()
+        deps: list[Dependency] = []
+
+        for dep in self._extract_all(content):
+            key = dep.coordinates
+            if key not in seen:
+                seen.add(key)
+                deps.append(dep)
+
+        _logger.info("Found %d unique dependencies in %s", len(deps), file_path)
+        return deps
+
+    def _extract_ext_properties(self, content: str) -> dict[str, str]:
+        """
+        Extract simple string variable assignments from ``ext {}`` blocks and
+        top-level ``def``/``val`` declarations.
+
+        Returns a mapping of variable name to its string value.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        props: dict[str, str] = {}
+        for block_match in _EXT_BLOCK_PATTERN.finditer(content):
+            for prop_match in _EXT_PROPERTY_PATTERN.finditer(block_match.group(1)):
+                props[prop_match.group(1)] = prop_match.group(2)
+        for def_match in _DEF_VAL_PATTERN.finditer(content):
+            props[def_match.group(1)] = def_match.group(2)
+        return props
+
+    def _resolve_variables(self, content: str, props: dict[str, str]) -> str:
+        """
+        Substitute ``${varName}`` placeholders in *content* using *props*.
+
+        Unrecognised variable references are left unchanged.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        def _replacer(match: re.Match) -> str:
+            return props.get(match.group(1), match.group(0))
+
+        return re.sub(r"\$\{(\w+)\}", _replacer, content)
+
+    def _strip_comments(self, content: str, is_kotlin_dsl: bool) -> str:  # pylint: disable=unused-argument
+        """
+        Remove single-line (//) and block (/* */) comments from the file content.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        # Remove block comments
+        content = re.sub(r"/\*.*?\*/", "", content, flags=re.DOTALL)
+        # Remove single-line comments
+        content = re.sub(r"//.*", "", content)
+        return content
+
+    def _extract_all(self, content: str) -> list[Dependency]:
+        """
+        Run all regex patterns against the content and collect matches.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        deps: list[Dependency] = []
+        for pattern in (_GROOVY_SHORTHAND, _KOTLIN_SHORTHAND, _GROOVY_BLOCK, _KOTLIN_BLOCK):
+            for match in pattern.finditer(content):
+                dep = self._match_to_dependency(match)
+                if dep is not None:
+                    deps.append(dep)
+        return deps
+
+    def _match_to_dependency(self, match: re.Match) -> Dependency | None:
+        """
+        Convert a regex match object to a Dependency instance.
+
+        Returns None if the configuration scope is not runtime-relevant.
+
+        :author: Ron Webb
+        :since: 1.0.0
+        """
+        config = match.group("config")
+        group = match.group("group").strip()
+        artifact = match.group("artifact").strip()
+        version = match.group("version").strip()
+
+        # Normalise scope name: 'compile' -> 'compile', 'implementation' -> 'implementation'
+        scope = config if config in RUNTIME_SCOPES else "compile"
+
+        if not group or not artifact or not version:
+            return None
+
+        # Skip variable references that couldn't be resolved
+        if "$" in version:
+            _logger.debug("Skipping %s:%s — unresolved version: %s", group, artifact, version)
+            return None
+
+        _logger.debug("Found dependency: %s:%s:%s (scope=%s)", group, artifact, version, scope)
+        return Dependency(
+            group_id=group,
+            artifact_id=artifact,
+            version=version,
+            scope=scope,
+        )