[SP-2991] feat: add depth and min-cutoff-threshold arguments to folder hashing commands

Author: matiasdaloia

CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Upcoming changes...
 
+## [1.31.0] - 2025-08-05
+### Added
+- Add `--min-cutoff-threshold` argument to folder scan command
+- Add `--depth` argument to `folder-scan` and `folder-hash` commands
+
 ## [1.31.4] - 2025-08-20
 ### Added
 - Added support for empty dependency track project policy checks

src/scanoss/cli.py

@@ -57,6 +57,8 @@
 from .components import Components
 from .constants import (
     DEFAULT_API_TIMEOUT,
+    DEFAULT_HFH_DEPTH,
+    DEFAULT_HFH_MIN_CUTOFF_THRESHOLD,
     DEFAULT_HFH_RANK_THRESHOLD,
     DEFAULT_POST_SIZE,
     DEFAULT_RETRY,
@@ -887,6 +889,18 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         help='Filter results to only show those with rank value at or below this threshold (e.g., --rank-threshold 3 '
         'returns results with rank 1, 2, or 3). Lower rank values indicate higher quality matches.',
     )
+    p_folder_scan.add_argument(
+        '--depth',
+        type=int,
+        default=DEFAULT_HFH_DEPTH,
+        help=f'Defines how deep to scan the root directory (optional - default {DEFAULT_HFH_DEPTH})',
+    )
+    p_folder_scan.add_argument(
+        '--min-cutoff-threshold',
+        type=float,
+        default=DEFAULT_HFH_MIN_CUTOFF_THRESHOLD,
+        help=f'Minimum score threshold to consider a match (optional - default: {DEFAULT_HFH_MIN_CUTOFF_THRESHOLD})',
+    )
     p_folder_scan.set_defaults(func=folder_hashing_scan)
 
     # Sub-command: folder-hash
@@ -905,6 +919,12 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         default='json',
         help='Result output format (optional - default: json)',
     )
+    p_folder_hash.add_argument(
+        '--depth',
+        type=int,
+        default=DEFAULT_HFH_DEPTH,
+        help=f'Defines how deep to hash the root directory (optional - default {DEFAULT_HFH_DEPTH})',
+    )
     p_folder_hash.set_defaults(func=folder_hash)
 
     # Output options
@@ -2397,6 +2417,8 @@ def folder_hashing_scan(parser, args):
             client=client,
             scanoss_settings=scanoss_settings,
             rank_threshold=args.rank_threshold,
+            depth=args.depth,
+            min_cutoff_threshold=args.min_cutoff_threshold,
         )
 
         if scanner.scan():
@@ -2430,6 +2452,7 @@ def folder_hash(parser, args):
             scan_dir=args.scan_dir,
             config=folder_hasher_config,
             scanoss_settings=scanoss_settings,
+            depth=args.depth,
         )
 
         folder_hasher.hash_directory(args.scan_dir)

src/scanoss/constants.py

@@ -13,4 +13,6 @@
 
 DEFAULT_API_TIMEOUT = 600
 
-DEFAULT_HFH_RANK_THRESHOLD = 5
+DEFAULT_HFH_RANK_THRESHOLD = 5
+DEFAULT_HFH_DEPTH = 1
+DEFAULT_HFH_MIN_CUTOFF_THRESHOLD = 0.5

src/scanoss/scanners/folder_hasher.py

@@ -6,6 +6,7 @@
 
 from progress.bar import Bar
 
+from scanoss.constants import DEFAULT_HFH_DEPTH
 from scanoss.file_filters import FileFilters
 from scanoss.scanoss_settings import ScanossSettings
 from scanoss.scanossbase import ScanossBase
@@ -72,13 +73,20 @@ class FolderHasher:
 
     It builds a directory tree (DirectoryNode) and computes the associated
     hash data for the folder.
+
+    Args:
+        scan_dir (str): The directory to be hashed.
+        config (FolderHasherConfig): Configuration parameters for the folder hasher.
+        scanoss_settings (Optional[ScanossSettings]): Optional settings for Scanoss.
+        depth (int): How many levels to hash from the root directory (default: 1).
     """
 
     def __init__(
         self,
         scan_dir: str,
         config: FolderHasherConfig,
         scanoss_settings: Optional[ScanossSettings] = None,
+        depth: int = DEFAULT_HFH_DEPTH,
     ):
         self.base = ScanossBase(
             debug=config.debug,
@@ -101,6 +109,7 @@ def __init__(
 
         self.scan_dir = scan_dir
         self.tree = None
+        self.depth = depth
 
     def hash_directory(self, path: str) -> dict:
         """
@@ -123,7 +132,10 @@ def hash_directory(self, path: str) -> dict:
 
         return tree
 
-    def _build_root_node(self, path: str) -> DirectoryNode:
+    def _build_root_node(
+        self,
+        path: str,
+    ) -> DirectoryNode:
         """
         Build a directory tree from the given path with file information.
 
@@ -180,7 +192,7 @@ def _build_root_node(self, path: str) -> DirectoryNode:
         bar.finish()
         return root_node
 
-    def _hash_calc_from_node(self, node: DirectoryNode) -> dict:
+    def _hash_calc_from_node(self, node: DirectoryNode, current_depth: int = 1) -> dict:
         """
         Recursively compute folder hash data for a directory node.
 
@@ -189,12 +201,13 @@ def _hash_calc_from_node(self, node: DirectoryNode) -> dict:
 
         Args:
             node (DirectoryNode): The directory node to compute the hash for.
+            current_depth (int): The current depth level (1-based, root is depth 1).
 
         Returns:
             dict: The computed hash data for the node.
         """
         hash_data = self._hash_calc(node)
-        
+
         # Safely calculate relative path
         try:
             node_path = Path(node.path).resolve()
@@ -204,13 +217,18 @@ def _hash_calc_from_node(self, node: DirectoryNode) -> dict:
             # If relative_to fails, use the node path as is or a fallback
             rel_path = Path(node.path).name if node.path else Path('.')
 
+        # Only process children if we haven't reached the depth limit
+        children = []
+        if current_depth < self.depth:
+            children = [self._hash_calc_from_node(child, current_depth + 1) for child in node.children.values()]
+
         return {
             'path_id': str(rel_path),
             'sim_hash_names': f'{hash_data["name_hash"]:02x}' if hash_data['name_hash'] is not None else None,
             'sim_hash_content': f'{hash_data["content_hash"]:02x}' if hash_data['content_hash'] is not None else None,
             'sim_hash_dir_names': f'{hash_data["dir_hash"]:02x}' if hash_data['dir_hash'] is not None else None,
             'lang_extensions': hash_data['lang_extensions'],
-            'children': [self._hash_calc_from_node(child) for child in node.children.values()],
+            'children': children,
         }
 
     def _hash_calc(self, node: DirectoryNode) -> dict:

src/scanoss/scanners/scanner_hfh.py

@@ -29,7 +29,11 @@
 
 from progress.spinner import Spinner
 
-from scanoss.constants import DEFAULT_HFH_RANK_THRESHOLD
+from scanoss.constants import (
+    DEFAULT_HFH_DEPTH,
+    DEFAULT_HFH_MIN_CUTOFF_THRESHOLD,
+    DEFAULT_HFH_RANK_THRESHOLD,
+)
 from scanoss.cyclonedx import CycloneDx
 from scanoss.file_filters import FileFilters
 from scanoss.scanners.folder_hasher import FolderHasher
@@ -48,13 +52,15 @@ class ScannerHFH:
     and calculates simhash values based on file names and content to detect folder-level similarities.
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         scan_dir: str,
         config: ScannerConfig,
         client: Optional[ScanossGrpc] = None,
         scanoss_settings: Optional[ScanossSettings] = None,
         rank_threshold: int = DEFAULT_HFH_RANK_THRESHOLD,
+        depth: int = DEFAULT_HFH_DEPTH,
+        min_cutoff_threshold: float = DEFAULT_HFH_MIN_CUTOFF_THRESHOLD,
     ):
         """
         Initialize the ScannerHFH.
@@ -65,6 +71,8 @@ def __init__(
             client (ScanossGrpc): gRPC client for communicating with the scanning service.
             scanoss_settings (Optional[ScanossSettings]): Optional settings for Scanoss.
             rank_threshold (int): Get results with rank below this threshold (default: 5).
+            depth (int): How many levels to scan (default: 1).
+            min_cutoff_threshold (float): Minimum score threshold to consider a match (default: 0.5).
         """
         self.base = ScanossBase(
             debug=config.debug,
@@ -87,12 +95,14 @@ def __init__(
             scan_dir=scan_dir,
             config=config,
             scanoss_settings=scanoss_settings,
+            depth=depth,
         )
 
         self.scan_dir = scan_dir
         self.client = client
         self.scan_results = None
         self.rank_threshold = rank_threshold
+        self.min_cutoff_threshold = min_cutoff_threshold
 
     def scan(self) -> Optional[Dict]:
         """
@@ -102,8 +112,9 @@ def scan(self) -> Optional[Dict]:
             Optional[Dict]: The folder hash response from the gRPC client, or None if an error occurs.
         """
         hfh_request = {
-            'root': self.folder_hasher.hash_directory(self.scan_dir),
+            'root': self.folder_hasher.hash_directory(path=self.scan_dir),
             'rank_threshold': self.rank_threshold,
+            'min_cutoff_threshold': self.min_cutoff_threshold,
         }
 
         spinner = Spinner('Scanning folder...')
@@ -193,7 +204,7 @@ def _format_cyclonedx_output(self) -> str:  # noqa: PLR0911
                     }
                 ]
             }
-            
+
             get_vulnerabilities_json_request = {
                 'purls': [{'purl': purl, 'requirement': best_match_version['version']}],
             }
@@ -210,10 +221,10 @@ def _format_cyclonedx_output(self) -> str:  # noqa: PLR0911
                 error_msg = 'ERROR: Failed to produce CycloneDX output'
                 self.base.print_stderr(error_msg)
                 return None
-            
+
             if vulnerabilities:
                 cdx_output = cdx.append_vulnerabilities(cdx_output, vulnerabilities, purl)
-                
+
             return json.dumps(cdx_output, indent=2)
         except Exception as e:
             self.base.print_stderr(f'ERROR: Failed to get license information: {e}')