feat(refactor): PEP8, type annotations, docstrings and PyJWT security fix

backend/app/routers/compliance.py

@@ -1,32 +1,45 @@
 """Compliance endpoints — framework status, reports, and gap analysis.
 
-Thin HTTP adapter: delegates all data logic to compliance_service.
-
+Thin HTTP adapter that delegates all data logic to compliance_service.
 Provides compliance posture assessment by mapping MITRE ATT&CK technique
 coverage to compliance framework controls.
 """
 
+# Import APIRouter, Depends from fastapi
 from fastapi import APIRouter, Depends
+
+# Import StreamingResponse from fastapi.responses
 from fastapi.responses import StreamingResponse
+
+# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
+# Import get_db from app.database
 from app.database import get_db
+
+# Import get_current_user, require_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_role
+
+# Import User from app.models.user
 from app.models.user import User
-from app.services.compliance_service import (
-    list_frameworks,
-    get_framework_status,
-    build_framework_report_csv,
-    get_framework_gaps,
-)
+
+# Import  from app.services.compliance_import_service
 from app.services.compliance_import_service import (
-    import_nist_800_53_mappings,
     import_cis_controls_v8_mappings,
     import_dora_mappings,
     import_iso_27001_mappings,
     import_iso_42001_mappings,
 )
 
+# Import  from app.services.compliance_service
+from app.services.compliance_service import (
+    build_framework_report_csv,
+    get_framework_gaps,
+    get_framework_status,
+    list_frameworks,
+)
+
+# Assign router = APIRouter(prefix="/compliance", tags=["compliance"])
 router = APIRouter(prefix="/compliance", tags=["compliance"])
 
 
@@ -34,11 +47,23 @@ router = APIRouter(prefix="/compliance", tags=["compliance"])
 
 
 @router.get("/frameworks")
+# Define function list_frameworks_endpoint
 def list_frameworks_endpoint(
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(get_current_user),
-):
-    """List all available compliance frameworks."""
+) -> list:
+    """List all available compliance frameworks.
+
+    Args:
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated user making the request.
+
+    Returns:
+        list: List of framework summary dicts containing id, name, and control counts.
+    """
+    # Return list_frameworks(db)
     return list_frameworks(db)
 
 
@@ -46,12 +71,26 @@ def list_frameworks_endpoint(
 
 
 @router.get("/frameworks/{framework_id}/status")
+# Define function framework_status
 def framework_status(
+    # Entry: framework_id
     framework_id: str,
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(get_current_user),
-):
-    """Get compliance status for each control in a framework."""
+) -> dict:
+    """Get compliance status for each control in a framework.
+
+    Args:
+        framework_id (str): Identifier of the compliance framework (e.g. ``nist-800-53``).
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated user making the request.
+
+    Returns:
+        dict: Mapping of control IDs to their coverage status and linked techniques.
+    """
+    # Return get_framework_status(db, framework_id)
     return get_framework_status(db, framework_id)
 
 
@@ -59,12 +98,26 @@ def framework_status(
 
 
 @router.get("/frameworks/{framework_id}/report")
+# Define function framework_report
 def framework_report(
+    # Entry: framework_id
     framework_id: str,
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(get_current_user),
-):
-    """Get the full compliance report (same as status but marked as report)."""
+) -> dict:
+    """Get the full compliance report (same as status but marked as report).
+
+    Args:
+        framework_id (str): Identifier of the compliance framework.
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated user making the request.
+
+    Returns:
+        dict: Full compliance report with per-control coverage details.
+    """
+    # Return get_framework_status(db, framework_id)
     return get_framework_status(db, framework_id)
 
 
@@ -72,17 +125,35 @@ def framework_report(
 
 
 @router.get("/frameworks/{framework_id}/report/csv")
+# Define function framework_report_csv
 def framework_report_csv(
+    # Entry: framework_id
     framework_id: str,
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(get_current_user),
-):
-    """Export compliance report as CSV."""
+) -> StreamingResponse:
+    """Export compliance report as CSV.
+
+    Args:
+        framework_id (str): Identifier of the compliance framework to export.
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated user making the request.
+
+    Returns:
+        StreamingResponse: CSV file attachment with compliance coverage data.
+    """
+    # csv_bytes, filename = build_framework_report_csv(db, framework_id)
     csv_bytes, filename = build_framework_report_csv(db, framework_id)
+    # Return StreamingResponse(
     return StreamingResponse(
         iter([csv_bytes]),
+        # Keyword argument: media_type
         media_type="text/csv",
+        # Keyword argument: headers
         headers={
+            # Literal argument value
             "Content-Disposition": f"attachment; filename={filename}",
         },
     )
@@ -92,12 +163,26 @@ def framework_report_csv(
 
 
 @router.get("/frameworks/{framework_id}/gaps")
+# Define function framework_gaps
 def framework_gaps(
+    # Entry: framework_id
     framework_id: str,
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(get_current_user),
-):
-    """Get controls with techniques that are not adequately covered."""
+) -> dict:
+    """Get controls with techniques that are not adequately covered.
+
+    Args:
+        framework_id (str): Identifier of the compliance framework to analyse.
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated user making the request.
+
+    Returns:
+        dict: Controls flagged as gaps, with linked technique IDs and coverage ratios.
+    """
+    # Return get_framework_gaps(db, framework_id)
     return get_framework_gaps(db, framework_id)
 
 
@@ -105,22 +190,49 @@ def framework_gaps(
 
 
 @router.post("/import/nist-800-53")
+# Define function import_nist
 def import_nist(
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-):
-    """Import NIST 800-53 Rev 5 mappings (admin only)."""
+) -> dict:
+    """Import NIST 800-53 Rev 5 mappings (admin only).
+
+    Args:
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated admin user.
+
+    Returns:
+        dict: Import result with counts of created and updated control mappings.
+    """
+    # Assign result = import_nist_800_53_mappings(db)
     result = import_nist_800_53_mappings(db)
+    # Return result
     return result
 
 
+# Apply the @router.post decorator
 @router.post("/import/cis-controls-v8")
+# Define function import_cis
 def import_cis(
+    # Entry: db
     db: Session = Depends(get_db),
+    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-):
-    """Import CIS Controls v8 mappings (admin only)."""
+) -> dict:
+    """Import CIS Controls v8 mappings (admin only).
+
+    Args:
+        db (Session): SQLAlchemy database session.
+        current_user (User): Authenticated admin user.
+
+    Returns:
+        dict: Import result with counts of created and updated control mappings.
+    """
+    # Assign result = import_cis_controls_v8_mappings(db)
     result = import_cis_controls_v8_mappings(db)
+    # Return result
     return result