add documentation and support api endpoint for clarity compliance

Signed-off-by: NucleonGodX <racerpro41@gmail.com>

Author: NucleonGodX

docs/policies.rst

@@ -38,6 +38,43 @@ structure similar to the following:
    - ``warning``
    - ``error``
 
+Creating Clarity Thresholds Files
+---------------------------------
+
+A valid clarity thresholds file is required to **enable clarity compliance features**.
+
+The clarity thresholds file, by default named ``policies.yml``, is a **YAML file** with a
+structure similar to the following:
+
+.. code-block:: yaml
+
+    license_clarity_thresholds:
+      91: ok
+      80: warning
+      0: error
+
+- In the example above, the keys ``91``, ``80``, and ``0`` are integer threshold values
+  representing **minimum clarity scores**.
+- The values ``error``, ``warning``, and ``ok`` are the **compliance alert levels** that
+  will be triggered if the project's license clarity score meets or exceeds the
+  corresponding threshold.
+- The thresholds must be listed in **strictly descending order**.
+
+How it works:
+
+- If the clarity score is **91 or above**, the alert is **``ok``**.
+- If the clarity score is **80 to 90**, the alert is **``warning``**.
+- If the clarity score is **below 80**, the alert is **``error``**.
+
+You can adjust the threshold values and alert levels to match your organization's
+compliance requirements.
+
+Accepted values for the alert level:
+
+- ``ok``
+- ``warning``
+- ``error``
+
 App Policies
 ------------
 
@@ -99,7 +136,7 @@ REST API
 --------
 
 For more details on retrieving compliance data through the REST API, see the
-:ref:`rest_api_compliance` section.
+:ref:`rest_api_compliance` section and :ref:`rest_api_clarity_compliance` section 
 
 Command Line Interface
 ----------------------

docs/rest-api.rst

@@ -493,6 +493,29 @@ Data:
         }
     }
 
+.. _rest_api_clarity_compliance:
+
+Clarity Compliance
+^^^^^^^^^^^^^^^^^^
+
+This action returns the **clarity compliance alert** for a project.
+
+The clarity compliance alert is a single value (``ok``, ``warning``, or ``error``) that summarizes
+the project's **license clarity status**, based on the thresholds defined in the ``policies.yml`` file.
+
+``GET /api/projects/6461408c-726c-4b70-aa7a-c9cc9d1c9685/clarity_compliance/``
+
+Data:
+    - ``clarity_compliance_alert``: The overall clarity compliance alert for the project.
+
+      Possible values: ``ok``, ``warning``, ``error``.
+
+.. code-block:: json
+
+    {
+        "clarity_compliance_alert": "warning"
+    }
+
 Reset
 ^^^^^
 

docs/tutorial_license_policies.rst

@@ -83,6 +83,51 @@ detected license, and computed at the codebase resource level, for example:
       "[...]": "[...]"
     }
 
+License Clarity Thresholds and Compliance
+-----------------------------------------
+
+ScanCode.io also supports **license clarity thresholds**, allowing you to enforce
+minimum standards for license detection quality in your codebase. This is managed
+through the ``license_clarity_thresholds`` section in your ``policies.yml`` file.
+
+Defining Clarity Thresholds
+---------------------------
+
+Add a ``license_clarity_thresholds`` section to your ``policies.yml`` file, for example:
+
+.. code-block:: yaml
+
+    license_clarity_thresholds:
+      91: ok
+      80: warning
+      0: error
+
+
+Clarity Compliance in Results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you run a pipeline with clarity thresholds defined in your ``policies.yml``,
+the computed clarity compliance alert is included in the project's ``extra_data`` field.
+
+For example:
+
+.. code-block:: json
+
+    "extra_data": {
+      "md5": "d23df4a4",
+      "sha1": "3e9b61cc98c",
+      "size": 3095,
+      "sha256": "abacfc8bcee59067",
+      "sha512": "208f6a83c83a4c770b3c0",
+      "filename": "cuckoo_filter-1.0.6.tar.gz",
+      "sha1_git": "3fdb0f82ad59",
+      "clarity_compliance_alert": "error"
+    }
+
+The ``clarity_compliance_alert`` value (e.g., ``"error"``, ``"warning"``, or ``"ok"``)
+is computed automatically based on the thresholds you configured and reflects the
+overall license clarity status of the scanned codebase.
+
 Run the ``check-compliance`` command
 ------------------------------------
 
@@ -95,7 +140,7 @@ in the project:
 
 .. code-block:: bash
 
-    4 compliance issues detected on this project.
+    5 compliance issues detected on this project.
     [packages]
      > ERROR: 3
        pkg:pypi/cuckoo-filter@.
@@ -104,7 +149,9 @@ in the project:
     [resources]
      > ERROR: 1
        cuckoo_filter-1.0.6.tar.gz-extract/cuckoo_filter-1.0.6/README.md
+    [License Clarity Compliance]
+     > Alert Level: error
 
 .. tip::
     In case of compliance alerts, the command returns a non-zero exit code which
-    may be useful to trigger a failure in an automated process.
+    may be useful to trigger a failure in an automated process.

scanpipe/api/views.py

@@ -481,6 +481,22 @@ def compliance(self, request, *args, **kwargs):
         compliance_alerts = get_project_compliance_alerts(project, fail_level)
         return Response({"compliance_alerts": compliance_alerts})
 
+    @action(detail=True, methods=["get"])
+    def clarity_compliance(self, request, *args, **kwargs):
+        """
+        Retrieve the clarity compliance alert for a project.
+
+        This endpoint returns the clarity compliance alert stored in the
+        project's extra_data.
+
+        Example:
+          GET /api/projects/{project_id}/clarity_compliance/
+
+        """
+        project = self.get_object()
+        clarity_alert = (project.extra_data or {}).get("clarity_compliance_alert")
+        return Response({"clarity_compliance_alert": clarity_alert})
+
 
 class RunViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
     """Add actions to the Run viewset."""