added new example notebooks

Author: nocomplexity

docs/_toc.yml

@@ -80,6 +80,8 @@ parts:
   - file: apidocs/api_intro
     sections:    
     - file: examples/ca_api_example_overview
+    - file: examples/example_risk_heatmap
+    - file: examples/example_weakness_perfile_view
     - file: examples/ca_api_example_checks
     - file: examples/ca_api_example_scanning
     - file: examples/ca_api_example_json

docs/apidocs/codeaudit.rst

@@ -10,3 +10,9 @@ Public Interfaces module
    :undoc-members:
    :show-inheritance:
 
+
+.. automodule:: codeaudit.altairplots
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

docs/apidocs/modules.rst

@@ -5,3 +5,4 @@ API Reference
    :maxdepth: 4
 
    codeaudit
+   

docs/examples/demoscan.json

@@ -1,7 +1,7 @@
 {
   "name": "Python_Code_Audit",
   "version": "1.6.5rc3",
-  "generated_on": "2026-04-25 14:32",
+  "generated_on": "2026-05-02 14:26",
   "file_security_info": {
     "0": {
       "FileName": "demofile.py",

docs/examples/example_risk_heatmap.ipynb

@@ -119,7 +119,7 @@ def module_distribution_view(scanresult):
     return donut
 
 
-def make_chart(y_field, df):
+def _make_chart(y_field, df):
     """Function to create a single bar chart with red and grey bars."""
 
     # Calculate the median (or use any other threshold if needed)
@@ -160,7 +160,7 @@ def multi_bar_chart(df):
         "Complexity_Score",
     ]
     rows = [
-        alt.hconcat(*[make_chart(metric, df) for metric in metrics[i : i + 2]])
+        alt.hconcat(*[_make_chart(metric, df) for metric in metrics[i : i + 2]])
         for i in range(0, len(metrics), 2)
     ]
 
@@ -245,18 +245,64 @@ def issue_overview(df):
 
 
 def complexity_heatmap(scanresult):
-    """Create an interactive heatmap of file complexity and size.
-
-    Highlights high-risk files based on complexity and lines of code,
-    with dynamic filtering and threshold controls.
+    """Generate an interactive heatmap of file complexity and size.
+
+    This function visualizes file-level risk by combining code complexity
+    and lines of code into a single interactive heatmap. Files are ranked
+    and filtered to highlight the most potentially risky candidates based
+    on a derived risk score.
+
+    The visualization includes:
+      - A heatmap of file metrics ("Complexity" and "Lines")
+      - A computed "RiskScore" used for sorting and prioritization
+      - Interactive sliders to control threshold levels for complexity
+        and file size
+      - An optional toggle to display only high-risk files
+      - Tooltip details for deeper inspection
+
+    Data is pre-filtered to improve usability and performance:
+      - Top 30 files by complexity
+      - Top 30 files by lines of code
+      - Combined and deduplicated set, sorted by risk score
 
     Args:
-        scanresult (dict): Scan result containing "file_security_info"
-            with file-level complexity and size metrics.
+        scanresult (dict): Scan output containing file-level metrics.
+            Expected structure:
+            {
+                "file_security_info": {
+                    "<file_id>": {
+                        "file_name": str,
+                        "Number_Of_Lines": int,
+                        "Complexity_Score": int | float,
+                        ...
+                    },
+                    ...
+                }
+            }
 
     Returns:
-        altair.Chart | str: Interactive heatmap chart, or a warning
-        message if input is invalid.
+        altair.Chart | str:
+            - An Altair layered chart (heatmap + text overlay) if input is valid.
+            - A warning message string if `scanresult` is invalid or empty.
+
+    Raises:
+        KeyError: If required keys (e.g., "file_security_info") are missing.
+        ValueError: If input data cannot be converted into a valid DataFrame.
+
+    Notes:
+        - RiskScore is computed as:
+              (Complexity / 80) + (Lines / 2000)
+          This normalization balances the influence of both metrics.
+        - Threshold defaults are set to 70% of the maximum observed values.
+        - The chart is optimized for exploratory analysis rather than
+          exhaustive dataset display.
+
+    Example:
+        >>> chart = complexity_heatmap(scanresult)
+        >>> if isinstance(chart, str):
+        ...     print(chart)
+        >>> else:
+        ...     chart.show()
     """
     if not scanresult or not isinstance(scanresult, dict):
         return "⚠️ No scan result available.\n\nPlease run a scan first."
@@ -596,18 +642,24 @@ def ast_nodes_overview(scanresult, width=800, height=400):
 
 
 def weaknesses_overview(scanresult):
-    """Create a bar chart of the most common security weaknesses.
+    """Generate a bar chart of the most common security weaknesses.
 
-    Aggregates and counts validation findings across all files in the
-    scan result, displaying the top occurrences in a bar chart.
+    Aggregates SAST validation findings across all scanned files and
+    displays the most frequent issues. Designed for quick identification
+    of recurring security patterns.
 
     Args:
-        scanresult (dict): Scan result containing "file_security_info"
-            with SAST validation findings per file.
+        scanresult (dict): Scan output containing "file_security_info" with
+            per-file SAST findings. Each finding should include a "validation" field.
 
     Returns:
-        altair.Chart: Bar chart of top security weaknesses, or a fallback
-        text chart if no data is available.
+        altair.Chart: Bar chart of top weaknesses, or a text-based chart if
+        input is invalid or no findings are present.
+
+    Notes:
+        - Only the top 50 most frequent weaknesses are shown.
+        - The top 5 are visually highlighted.
+        - Returns a fallback chart instead of raising errors for invalid input.
     """
     if not scanresult or not isinstance(scanresult, dict):
         return (

docs/examples/example_weakness_perfile_view.ipynb

@@ -1,7 +1,7 @@
 """
 License GPLv3 or higher.
 
-(C) 2025 Created by Maikel Mardjan - https://nocomplexity.com/
+(C) 2025 - 2026 Created by Maikel Mardjan and all contributors - https://nocomplexity.com/
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 
@@ -48,13 +48,13 @@
     total_modules,
 )
 
+
 def version():
     """Returns the version of Python Code Audit - WASM safe"""
     ca_version = __version__
     return {"name": "Python_Code_Audit", "version": ca_version}
 
 
-
 def filescan(input_path, nosec=False):
     """
     Scan a Python source file, a local directory, or a **PyPI package** from PyPI.org for
@@ -114,8 +114,8 @@ def filescan(input_path, nosec=False):
     """
     file_output = {}
     file_path = Path(input_path)
-    ca_version_info = {"name": "Python_Code_Audit", "version": __version__}        
-    
+    ca_version_info = {"name": "Python_Code_Audit", "version": __version__}
+
     now = datetime.datetime.now()
     timestamp_str = now.strftime("%Y-%m-%d %H:%M")
     output = ca_version_info | {"generated_on": timestamp_str}
@@ -405,7 +405,7 @@ def get_default_validations():
 
 def _generation_info():
     """Internal function to retrieve generation info for APIs output"""
-    ca_version_info = {"name": "Python_Code_Audit", "version": __version__}    
+    ca_version_info = {"name": "Python_Code_Audit", "version": __version__}
     now = datetime.datetime.now()
     timestamp_str = now.strftime("%Y-%m-%d %H:%M")
     output = ca_version_info | {"generated_on": timestamp_str}

src/codeaudit/altairplots.py

@@ -1,7 +1,7 @@
 """
 License GPLv3 or higher.
 
-(C) 2025 Created by Maikel Mardjan - https://nocomplexity.com/
+(C) 2025 - 2026 Created by Maikel Mardjan and all contributors - https://nocomplexity.com/
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.