refactor: refactor the function to get the purl-based directory path to a separated module and add tests for it

Author: Trong Nhan Mai

src/macaron/database/table_definitions.py

@@ -11,7 +11,6 @@
 For table associated with a check see the check module.
 """
 import logging
-import os
 import string
 from datetime import datetime
 from pathlib import Path
@@ -36,6 +35,7 @@
 from macaron.database.database_manager import ORMBase
 from macaron.database.db_custom_types import ProvenancePayload, RFC3339DateTime
 from macaron.errors import InvalidPURLError
+from macaron.path_utils.purl_based_path import get_purl_based_dir
 from macaron.repo_finder.repo_finder_enums import CommitFinderInfo, RepoFinderInfo
 from macaron.slsa_analyzer.provenance.intoto import InTotoPayload, ProvenanceSubjectPURLMatcher
 from macaron.slsa_analyzer.slsa_req import ReqName
@@ -256,15 +256,11 @@ def report_dir_name(self) -> str:
         str
             The report directory name.
         """
-        # Sanitize the path and make sure it's a valid file name.
-        # A purl string is an ASCII URL string that can allow uppercase letters for
-        # certain parts. So we shouldn't change uppercase letters with lower case
-        # to avoid merging results for two distinct PURL strings.
-        allowed_chars = string.ascii_letters + string.digits + "-"
-        p_type = "".join(c if c in allowed_chars else "_" for c in self.type)
-        p_namespace = "".join(c if c in allowed_chars else "_" for c in self.namespace) if self.namespace else ""
-        p_name = "".join(c if c in allowed_chars else "_" for c in self.name)
-        return os.path.join(p_type, p_namespace, p_name)
+        return get_purl_based_dir(
+            purl_name=self.name,
+            purl_namespace=self.namespace,
+            purl_type=self.type,
+        )
 
 
 class Repository(ORMBase):

src/macaron/path_utils/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.

src/macaron/path_utils/purl_based_path.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
+
+"""This module contains functions to manage PackageURL-based paths."""
+
+import os
+import string
+
+
+def get_purl_based_dir(
+    purl_type: str,
+    purl_name: str,
+    purl_namespace: str | None = None,
+) -> str:
+    """Return a directory path according to components of a PackageURL.
+
+    Parameters
+    ----------
+    purl_type: str
+        The type component of the PackageURL as string.
+    purl_name:str
+        The name component of the PackageURL as string.
+    purl_namespace: str | None = None
+        The namespace component of the PackageURL as string (optional).
+
+    Returns
+    -------
+    str
+        The directory path.
+
+    Examples
+    --------
+    >>> get_purl_based_dir(purl_type="maven", purl_name="macaron", purl_namespace="oracle")
+    'maven/oracle/macaron'
+    """
+    # Sanitize the path and make sure it's a valid file name.
+    # A purl string is an ASCII URL string that can allow uppercase letters for
+    # certain parts. So we shouldn't change uppercase letters with lower case
+    # to avoid merging results for two distinct PURL strings.
+    allowed_chars = string.ascii_letters + string.digits + "-"
+    p_type = "".join(c if c in allowed_chars else "_" for c in purl_type)
+    p_namespace = "".join(c if c in allowed_chars else "_" for c in purl_namespace) if purl_namespace else ""
+    p_name = "".join(c if c in allowed_chars else "_" for c in purl_name)
+    return os.path.join(p_type, p_namespace, p_name)

tests/path_utils/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.

tests/path_utils/test_purl_based_path.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
+
+"""This module tests the purl_based_path module."""
+
+import pytest
+
+from macaron.path_utils.purl_based_path import get_purl_based_dir
+
+
+@pytest.mark.parametrize(
+    ("purl_type", "purl_namespace", "purl_name", "expected"),
+    [
+        pytest.param(
+            "maven",
+            "oracle",
+            "macaron",
+            "maven/oracle/macaron",
+            id="simple_case_with_no_special_characters",
+        ),
+        pytest.param(
+            "maven",
+            None,
+            "macaron",
+            "maven/macaron",
+            id="no_namespace",
+        ),
+        pytest.param(
+            "maven",
+            "boo#bar",
+            "macaron@oracle",
+            "maven/boo_bar/macaron_oracle",
+            id="handle_non_allow_chars",
+        ),
+        pytest.param(
+            "maven",
+            "boo123bar",
+            "macaron123oracle",
+            "maven/boo123bar/macaron123oracle",
+            id="digits_are_allowed",
+        ),
+        pytest.param(
+            "maven",
+            "boo-bar",
+            "macaron-oracle",
+            "maven/boo-bar/macaron-oracle",
+            id="dashes_are_allowed",
+        ),
+    ],
+)
+def test_get_purl_based_dir(
+    purl_type: str,
+    purl_namespace: str,
+    purl_name: str,
+    expected: str,
+) -> None:
+    """Test the get_purl_based_dir function."""
+    assert (
+        get_purl_based_dir(
+            purl_type=purl_type,
+            purl_name=purl_name,
+            purl_namespace=purl_namespace,
+        )
+        == expected
+    )