Add a new "Package Set" tab to the Package details view #276 (#305)

Signed-off-by: tdruez <tdruez@nexb.com>

Author: tdruez

CHANGELOG.rst

@@ -149,6 +149,10 @@ Release notes
   merged and kept for the data update.
   https://github.com/aboutcode-org/dejacode/issues/303
 
+- Add a new "Package Set" tab to the Package details view.
+  This tab displays related packages grouped by their normalized ("plain") Package URL.
+  https://github.com/aboutcode-org/dejacode/issues/276
+
 ### Version 5.2.1
 
 - Fix the models documentation navigation.

component_catalog/models.py

@@ -18,10 +18,14 @@
 from django.core.exceptions import ValidationError
 from django.core.validators import EMPTY_VALUES
 from django.db import models
+from django.db.models import Case
 from django.db.models import CharField
 from django.db.models import Count
 from django.db.models import Exists
+from django.db.models import F
 from django.db.models import OuterRef
+from django.db.models import Value
+from django.db.models import When
 from django.db.models.functions import Concat
 from django.dispatch import receiver
 from django.template.defaultfilters import filesizeformat
@@ -1651,6 +1655,65 @@ def __str__(self):
 PACKAGE_URL_FIELDS = ["type", "namespace", "name", "version", "qualifiers", "subpath"]
 
 
+def get_plain_package_url_expression():
+    """
+    Return a Django expression to compute the "PLAIN" Package URL (PURL).
+    Return an empty string if the required `type` or `name` values are missing.
+    """
+    plain_package_url = Concat(
+        Value("pkg:"),
+        F("type"),
+        Case(
+            When(namespace="", then=Value("")),
+            default=Concat(Value("/"), F("namespace")),
+            output_field=CharField(),
+        ),
+        Value("/"),
+        F("name"),
+        Case(
+            When(version="", then=Value("")),
+            default=Concat(Value("@"), F("version")),
+            output_field=CharField(),
+        ),
+        output_field=CharField(),
+    )
+
+    return Case(
+        When(type="", then=Value("")),
+        When(name="", then=Value("")),
+        default=plain_package_url,
+        output_field=CharField(),
+    )
+
+
+def get_package_url_expression():
+    """
+    Return a Django expression to compute the "FULL" Package URL (PURL).
+    Return an empty string if the required `type` or `name` values are missing.
+    """
+    package_url = Concat(
+        get_plain_package_url_expression(),
+        Case(
+            When(qualifiers="", then=Value("")),
+            default=Concat(Value("?"), F("qualifiers")),
+            output_field=CharField(),
+        ),
+        Case(
+            When(subpath="", then=Value("")),
+            default=Concat(Value("#"), F("subpath")),
+            output_field=CharField(),
+        ),
+        output_field=CharField(),
+    )
+
+    return Case(
+        When(type="", then=Value("")),
+        When(name="", then=Value("")),
+        default=package_url,
+        output_field=CharField(),
+    )
+
+
 class PackageQuerySet(PackageURLQuerySetMixin, VulnerabilityQuerySetMixin, DataspacedQuerySet):
     def has_package_url(self):
         """Return objects with Package URL defined."""
@@ -1666,6 +1729,26 @@ def annotate_sortable_identifier(self):
             sortable_identifier=Concat(*PACKAGE_URL_FIELDS, "filename", output_field=CharField())
         )
 
+    def annotate_plain_package_url(self):
+        """
+        Annotate the QuerySet with a computed 'plain' Package URL (PURL).
+
+        This plain PURL is a simplified version that includes only the core fields:
+        `type`, `namespace`, `name`, and `version`. It omits any qualifiers or
+        subpath components, providing a normalized and minimal representation
+        of the Package URL.
+        """
+        return self.annotate(plain_purl=get_plain_package_url_expression())
+
+    def annotate_package_url(self):
+        """
+        Annotate the QuerySet with a fully-computed Package URL (PURL).
+
+        This includes the core PURL fields (`type`, `namespace`, `name`, `version`)
+        as well as any qualifiers and subpath components.
+        """
+        return self.annotate(purl=get_package_url_expression())
+
     def only_rendering_fields(self):
         """Minimum requirements to render a Package element in the UI."""
         return self.only(
@@ -2533,17 +2616,12 @@ def update_from_purldb(self, user):
             for field_name in [*hash_field_names, *identifier_fields]:
                 package_data.pop(field_name, None)
 
-        # try:
         updated_fields = self.update_from_data(
             user,
             package_data,
             override=False,
             override_unknown=True,
         )
-        # except IntegrityError as e:
-        #     logger.error(f"[update_from_purldb] Skipping {self} due to IntegrityError: {e}")
-        #     return []
-
         return updated_fields
 
     def update_from_scan(self, user):
@@ -2560,6 +2638,32 @@ def update_from_scan(self, user):
             updated_fields = scancodeio.update_from_scan(package=self, user=user)
             return updated_fields
 
+    def get_related_packages_qs(self):
+        """
+        Return a QuerySet of packages that are considered part of the same
+        "Package Set".
+
+        A "Package Set" consists of all packages that share the same "plain"
+        Package URL (PURL), meaning they have identical values for the following PURL
+        components:
+        `type`, `namespace`, `name`, and `version`.
+        The `qualifiers` and `subpath` components  are ignored for this comparison.
+        """
+        plain_package_url = self.plain_package_url
+        if not plain_package_url:
+            return None
+
+        return (
+            self.__class__.objects.scope(self.dataspace)
+            .for_package_url(plain_package_url, exact_match=True)
+            .order_by(
+                *PACKAGE_URL_FIELDS,
+                "filename",
+                "download_url",
+            )
+            .distinct()
+        )
+
 
 class PackageAssignedLicense(DataspacedModel):
     package = models.ForeignKey(

component_catalog/templates/component_catalog/tabs/tab_package_set.html

@@ -0,0 +1,41 @@
+{% load i18n %}
+{% spaceless %}
+<table class="table table-bordered table-hover table-md text-break">
+  <thead>
+    <tr>
+      <th>{% trans 'Package URL' %}</th>
+      <th>{% trans 'Filename' %}</th>
+      <th>{% trans 'Download URL' %}</th>
+      <th>{% trans 'Concluded license' %}</th>
+    </tr>
+  </thead>
+  <tbody>
+    {% for package in values %}
+      <tr data-uuid="{{ package.uuid }}">
+        <td class="fw-bold">
+          {% if package.uuid == object.uuid %}
+            {{ package.package_url }}
+            <div>
+              <span class="badge bg-secondary">Current package</span>
+            </div>
+          {% else %}
+            <a href="{{ package.get_absolute_url }}" target="_blank">
+              {{ package.package_url }}
+            </a>
+          {% endif %}
+        </td>
+        <td>{{ package.filename|default_if_none:"" }}</td>
+        <td>
+          {% if package.download_url %}
+            <i class="fa-solid fa-download me-1"></i>
+            {{ package.download_url|urlize }}
+          {% endif %}
+        </td>
+        <td>
+          {{ package.license_expression_linked|default_if_none:"" }}
+        </td>
+      </tr>
+    {% endfor %}
+  </tbody>
+</table>
+{% endspaceless %}

component_catalog/tests/test_models.py

@@ -2693,6 +2693,20 @@ def test_package_model_update_from_purldb_duplicate_exception(self, mock_get_pur
         package_no_download_url.refresh_from_db()
         self.assertEqual(purldb_entry["description"], package_no_download_url.description)
 
+    def test_package_model_get_related_packages_qs(self):
+        package_url = "pkg:pypi/django@5.0"
+        package1 = make_package(self.dataspace, package_url=package_url)
+        related_packages_qs = package1.get_related_packages_qs()
+        self.assertQuerySetEqual(related_packages_qs, [package1])
+
+        package2 = make_package(
+            self.dataspace,
+            package_url=package_url,
+            filename="Django-5.0.tar.gz",
+        )
+        related_packages_qs = package1.get_related_packages_qs()
+        self.assertQuerySetEqual(related_packages_qs, [package1, package2])
+
     def test_package_model_vulnerability_queryset_mixin(self):
         package1 = make_package(self.dataspace, is_vulnerable=True)
         package2 = make_package(self.dataspace)
@@ -2709,3 +2723,32 @@ def test_vulnerability_mixin_is_vulnerable_property(self):
         package2 = make_package(self.dataspace)
         self.assertTrue(package1.is_vulnerable)
         self.assertFalse(package2.is_vulnerable)
+
+    def test_package_queryset_has_package_url(self):
+        package1 = make_package(self.dataspace, package_url="pkg:pypi/django@5.0")
+        make_package(self.dataspace)
+        qs = Package.objects.has_package_url()
+        self.assertQuerySetEqual(qs, [package1])
+
+    def test_package_queryset_annotate_sortable_identifier(self):
+        package1 = make_package(self.dataspace, package_url="pkg:pypi/django@5.0")
+        package2 = make_package(self.dataspace)
+        qs = Package.objects.annotate_sortable_identifier()
+        self.assertEqual("pypidjango5.0", qs.get(pk=package1.pk).sortable_identifier)
+        self.assertEqual(package2.filename, qs.get(pk=package2.pk).sortable_identifier)
+
+    def test_package_queryset_annotate_package_url(self):
+        package_url = "pkg:pypi/django@5.0?qualifier=true#path"
+        package1 = make_package(self.dataspace, package_url=package_url)
+        package2 = make_package(self.dataspace)
+        qs = Package.objects.annotate_package_url()
+        self.assertEqual(package_url, qs.get(pk=package1.pk).purl)
+        self.assertEqual("", qs.get(pk=package2.pk).purl)
+
+    def test_package_queryset_annotate_plain_package_url(self):
+        package_url = "pkg:pypi/django@5.0?qualifier=true#path"
+        package1 = make_package(self.dataspace, package_url=package_url)
+        package2 = make_package(self.dataspace)
+        qs = Package.objects.annotate_plain_package_url()
+        self.assertEqual("pkg:pypi/django@5.0", qs.get(pk=package1.pk).plain_purl)
+        self.assertEqual("", qs.get(pk=package2.pk).plain_purl)

component_catalog/tests/test_views.py

@@ -39,6 +39,7 @@
 from component_catalog.models import ComponentType
 from component_catalog.models import Package
 from component_catalog.models import Subcomponent
+from component_catalog.tests import make_package
 from component_catalog.views import ComponentAddView
 from component_catalog.views import ComponentListView
 from component_catalog.views import PackageTabScanView
@@ -1239,8 +1240,21 @@ def test_package_list_multi_send_about_files_view(self):
         )
 
     def test_package_details_view_num_queries(self):
+        # Create a Package Set
+        package_url = "pkg:pypi/django@5.0"
+        self.package1.set_package_url(package_url)
+        self.package1.save()
+        license_expression = "{} AND {}".format(self.license1.key, self.license2.key)
+        make_package(self.dataspace, package_url=package_url, license_expression=license_expression)
+        make_package(
+            self.dataspace,
+            package_url=package_url,
+            license_expression=license_expression,
+            filename="Django-5.0.tar.gz",
+        )
+
         self.client.login(username=self.super_user.username, password="secret")
-        with self.assertNumQueries(28):
+        with self.assertNumQueries(30):
             self.client.get(self.package1.get_absolute_url())
 
     def test_package_details_view_content(self):
@@ -1332,6 +1346,25 @@ def test_package_details_view_aboutcode_tab(self):
         self.assertContains(response, "This tab renders a preview of the AboutCode files")
         self.assertContains(response, "about_resource: package1")
 
+    def test_package_details_view_tab_package_set(self):
+        self.client.login(username=self.super_user.username, password="secret")
+
+        package_url = "pkg:pypi/django@5.0"
+        package1 = make_package(self.dataspace, package_url=package_url)
+        details_url = package1.get_absolute_url()
+
+        expected = 'id="tab_package-set-tab"'
+        response = self.client.get(details_url)
+        self.assertNotContains(response, expected)
+
+        make_package(
+            self.dataspace,
+            package_url=package_url,
+            filename="Django-5.0.tar.gz",
+        )
+        response = self.client.get(details_url)
+        self.assertContains(response, expected)
+
     def test_package_list_view_add_to_product(self):
         user = create_user("user", self.dataspace)
         self.client.login(username=user.username, password="secret")

component_catalog/views.py

@@ -65,6 +65,7 @@
 from component_catalog.license_expression_dje import get_dataspace_licensing
 from component_catalog.license_expression_dje import get_formatted_expression
 from component_catalog.license_expression_dje import get_unique_license_keys
+from component_catalog.models import PACKAGE_URL_FIELDS
 from component_catalog.models import Component
 from component_catalog.models import Package
 from component_catalog.models import PackageAlreadyExistsWarning
@@ -1144,6 +1145,7 @@ class PackageDetailsView(
             ],
         },
         "product_usage": {},
+        "package_set": {},
         "activity": {},
         "external_references": {
             "fields": [
@@ -1297,6 +1299,24 @@ def tab_others(self):
 
         return {"fields": fields}
 
+    def tab_package_set(self):
+        related_packages_qs = self.object.get_related_packages_qs()
+        if related_packages_qs is None:
+            return
+
+        related_packages = related_packages_qs.only(
+            "uuid",
+            *PACKAGE_URL_FIELDS,
+            "filename",
+            "download_url",
+            "license_expression",
+            "dataspace__name",
+        ).prefetch_related("licenses")
+
+        template = "component_catalog/tabs/tab_package_set.html"
+        if len(related_packages) > 1:
+            return {"fields": [(None, related_packages, None, template)]}
+
     def tab_product_usage(self):
         user = self.request.user
         # Product data in Package views are not available to AnonymousUser for security reason

dje/tests/test_permissions.py

@@ -110,6 +110,7 @@ def test_permissions_get_all_tabsets(self):
                 "others",
                 "components",
                 "product_usage",
+                "package_set",
                 "activity",
                 "external_references",
                 "usage_policy",

setup.cfg

@@ -51,7 +51,7 @@ install_requires =
     wheel==0.45.1
     pip==25.0.1
     # Django
-    Django==5.1.8
+    Django==5.1.9
     asgiref==3.8.1
     typing_extensions==4.12.2
     sqlparse==0.5.3