chore(hfh):SP-4188 include license info into hfh results

Author: agustingroh

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `--format raw` option to `folder-scan` command to export HFH results in snippet-scanner JSON format
   - Expands directory-level HFH results into per-file entries keyed by relative file path
   - Assigns each file to the most specific matching `path_id` (deepest directory match wins)
+- Added license decoration to folder hash scan results via dependency service
+  - Each component version in HFH results is now decorated with license information
+  - CycloneDX output uses pre-decorated licenses instead of making a separate dependency API call
 
 ## [1.50.1] - 2026-03-23
 ### Fixed

src/scanoss/scanners/scanner_hfh.py

@@ -116,17 +116,108 @@ def __init__(  # noqa: PLR0913
 
     def _execute_grpc_scan(self, hfh_request: Dict) -> None:
         """
-        Execute folder hash scan.
+        Execute folder hash scan and decorate results with license information.
 
         Args:
             hfh_request: Request dictionary for the gRPC call
         """
         try:
             self.scan_results = self.client.folder_hash_scan(hfh_request, self.use_grpc)
+            self._decorate_with_licenses()
         except Exception as e:
             self.base.print_stderr(f'Error during folder hash scan: {e}')
             self.scan_results = None
 
+    def _decorate_with_licenses(self) -> None:
+        """
+        Decorate each component version in scan results with license information
+        by calling the dependency service.
+        """
+        if not self.scan_results or not self.client:
+            return
+        results = self.scan_results.get('results', [])
+        if not results:
+            return
+
+        dep_files = self._collect_dep_files(results)
+        if not dep_files:
+            return
+
+        try:
+            decorated = self.client.get_dependencies({'files': dep_files})
+        except Exception as e:
+            self.base.print_stderr(f'Warning: Failed to fetch license data: {e}')
+            return
+
+        if not decorated or 'files' not in decorated:
+            return
+
+        license_map = self._build_license_map(decorated)
+        self._inject_licenses(results, license_map)
+
+    @staticmethod
+    def _collect_dep_files(results: List[Dict]) -> List[Dict]:
+        """Collect dependency file entries for all component versions in the results."""
+        dep_files = []
+        for result in results:
+            path_id = result.get('path_id', '')
+            for component in result.get('components', []):
+                purl = component.get('purl', '')
+                if not purl:
+                    continue
+                for version_entry in component.get('versions', []):
+                    version = version_entry.get('version', '')
+                    if not version:
+                        continue
+                    dep_files.append({
+                        'file': path_id,
+                        'purls': [{'purl': purl, 'requirement': version}],
+                    })
+        return dep_files
+
+    @staticmethod
+    def _build_license_map(decorated: Dict) -> Dict[str, List]:
+        """Build a purl@requirement -> licenses lookup from the dependency service response.
+
+        Args:
+            decorated (Dict): The response from the dependency service containing
+                decorated files with license information.
+
+        Returns:
+            Dict[str, List]: A mapping of 'purl@requirement' keys to their
+                corresponding list of license dictionaries.
+        """
+        license_map = {}
+        for dep_file in decorated.get('files', []):
+            for dep in dep_file.get('dependencies', []):
+                dep_purl = dep.get('purl', '')
+                # Use 'requirement' instead of 'version' as the key because the service
+                # may resolve a different version, but the requirement always matches what was sent.
+                dep_requirement = dep.get('requirement', '')
+                licenses = dep.get('licenses', [])
+                if dep_purl and licenses:
+                    license_map[f'{dep_purl}@{dep_requirement}'] = licenses
+        return license_map
+
+    @staticmethod
+    def _inject_licenses(results: List[Dict], license_map: Dict[str, List]) -> None:
+        """Inject licenses from the lookup map into each component version entry.
+
+        Args:
+            results (List[Dict]): The 'results' list from the HFH scan response.
+                Each result contains components with version entries that will
+                be mutated in place to include license data.
+            license_map (Dict[str, List]): A mapping of 'purl@version' keys to
+                their corresponding list of license dictionaries, as built by
+                ``_build_license_map``.
+        """
+        for result in results:
+            for component in result.get('components', []):
+                purl = component.get('purl', '')
+                for version_entry in component.get('versions', []):
+                    version = version_entry.get('version', '')
+                    version_entry['licenses'] = license_map.get(f'{purl}@{version}', [])
+
     def scan(self) -> Optional[Dict]:
         """
         Scan the provided directory using the folder hashing algorithm.
@@ -215,30 +306,34 @@ def _format_cyclonedx_output(self) -> str:  # noqa: PLR0911
             if not best_match_component.get('versions'):
                 self.base.print_stderr('ERROR: No versions found for best match component')
                 return ''
-
             best_match_version = best_match_component['versions'][0]
             purl = best_match_component['purl']
+            version = best_match_version['version']
+            licenses = best_match_version.get('licenses', [])
 
-            get_dependencies_json_request = {
-                'files': [
+            # Build scan_results from already-decorated HFH data
+            scan_results = {
+                f'{best_match_component["name"]}:{version}': [
                     {
-                        'file': f'{best_match_component["name"]}:{best_match_version["version"]}',
-                        'purls': [{'purl': purl, 'requirement': best_match_version['version']}],
+                        'id': 'dependency',
+                        'dependencies': [
+                            {
+                                'purl': purl,
+                                'component': best_match_component.get('name', ''),
+                                'version': version,
+                                'licenses': licenses,
+                            }
+                        ],
                     }
                 ]
             }
 
             get_vulnerabilities_json_request = {
-                'components': [{'purl': purl, 'requirement': best_match_version['version']}],
+                'components': [{'purl': purl, 'requirement': version}],
             }
-
-            decorated_scan_results = self.scanner.client.get_dependencies(get_dependencies_json_request)
             vulnerabilities = self.scanner.client.get_vulnerabilities_json(get_vulnerabilities_json_request)
 
             cdx = CycloneDx(self.base.debug)
-            scan_results = {}
-            for f in decorated_scan_results['files']:
-                scan_results[f['file']] = [f]
             success, cdx_output = cdx.produce_from_json(scan_results)
             if not success:
                 error_msg = 'ERROR: Failed to produce CycloneDX output'
@@ -250,7 +345,7 @@ def _format_cyclonedx_output(self) -> str:  # noqa: PLR0911
 
             return json.dumps(cdx_output, indent=2)
         except Exception as e:
-            self.base.print_stderr(f'ERROR: Failed to get license information: {e}')
+            self.base.print_stderr(f'ERROR: Failed to produce CycloneDX output: {e}')
             return None
 
     def _format_spdxlite_output(self) -> str:
@@ -411,6 +506,19 @@ def _build_file_match_entry(
         """
         purl = component.get('purl', '')
         version = best_version.get('version', '')
+        licenses = [
+            {
+                'name': lic.get('spdx_id') or lic.get('name', ''),
+                'patent_hints': '',
+                'copyleft': '',
+                'checklist_url': '',
+                'incompatible_with': '',
+                'osadl_updated': '',
+                'source': 'component_declared',
+                'url': f"https://spdx.org/licenses/{lic['spdx_id']}.html" if lic.get('spdx_id') else '',
+            }
+            for lic in best_version.get('licenses', [])
+        ]
 
         url = purl2url.get_repo_url(purl) if purl else ''
         return {
@@ -428,7 +536,7 @@ def _build_file_match_entry(
             'source_hash': file_hash,
             'url_hash': '',
             'release_date': '',
-            'licenses': [],
+            'licenses': licenses,
             'lines': 'all',
             'oss_lines': 'all',
             'status': 'pending',

tests/test_scanner_hfh.py

@@ -212,7 +212,13 @@ class TestBuildFileMatchEntry(unittest.TestCase):
     def test_basic_entry(self, mock_purl2url):
         mock_purl2url.get_repo_url.return_value = 'https://github.com/vendor/comp'
         component = {'purl': 'pkg:github/vendor/comp', 'name': 'comp', 'vendor': 'vendor'}
-        best_version = {'version': '1.0.0', 'licenses': [{'name': 'MIT'}]}
+        # HFH API license format
+        best_version = {
+            'version': '1.0.0',
+            'licenses': [
+                {'name': 'MIT License', 'spdx_id': 'MIT', 'is_spdx_approved': True, 'url': 'https://spdx.org/licenses/MIT.html'},
+            ],
+        }
 
         entry = ScannerHFHPresenter._build_file_match_entry(
             component, best_version, 'src/file.py', 'abc123', 'https://api.example.com'
@@ -232,7 +238,17 @@ def test_basic_entry(self, mock_purl2url):
         self.assertEqual(entry['source_hash'], 'abc123')
         self.assertEqual(entry['url_hash'], '')
         self.assertEqual(entry['release_date'], '')
-        self.assertEqual(entry['licenses'], [{'name': 'MIT'}])
+        # License should be transformed from HFH format to snippet-scanner format
+        self.assertEqual(len(entry['licenses']), 1)
+        lic = entry['licenses'][0]
+        self.assertEqual(lic['name'], 'MIT')
+        self.assertEqual(lic['source'], 'component_declared')
+        self.assertEqual(lic['url'], 'https://spdx.org/licenses/MIT.html')
+        self.assertEqual(lic['patent_hints'], '')
+        self.assertEqual(lic['copyleft'], '')
+        self.assertEqual(lic['checklist_url'], '')
+        self.assertEqual(lic['incompatible_with'], '')
+        self.assertEqual(lic['osadl_updated'], '')
         self.assertEqual(entry['lines'], 'all')
         self.assertEqual(entry['oss_lines'], 'all')
         self.assertEqual(entry['status'], 'pending')
@@ -266,6 +282,64 @@ def test_missing_fields_use_defaults(self, mock_purl2url):
         self.assertEqual(entry['version'], '')
         self.assertEqual(entry['licenses'], [])
 
+    @patch('scanoss.scanners.scanner_hfh.purl2url')
+    def test_license_uses_spdx_id_as_name(self, mock_purl2url):
+        mock_purl2url.get_repo_url.return_value = ''
+        component = {'purl': 'pkg:github/v/c', 'name': 'c', 'vendor': 'v'}
+        best_version = {
+            'version': '1.0',
+            'licenses': [
+                {'name': 'GNU General Public License v2.0 only', 'spdx_id': 'GPL-2.0-only', 'is_spdx_approved': True, 'url': 'https://spdx.org/licenses/GPL-2.0-only.html'},
+            ],
+        }
+
+        entry = ScannerHFHPresenter._build_file_match_entry(
+            component, best_version, 'file.py', 'hash', 'https://api.example.com'
+        )
+
+        lic = entry['licenses'][0]
+        self.assertEqual(lic['name'], 'GPL-2.0-only')
+        self.assertEqual(lic['url'], 'https://spdx.org/licenses/GPL-2.0-only.html')
+
+    @patch('scanoss.scanners.scanner_hfh.purl2url')
+    def test_license_without_spdx_id_falls_back_to_name(self, mock_purl2url):
+        mock_purl2url.get_repo_url.return_value = ''
+        component = {'purl': 'pkg:github/v/c', 'name': 'c', 'vendor': 'v'}
+        best_version = {
+            'version': '1.0',
+            'licenses': [{'name': 'Some Custom License'}],
+        }
+
+        entry = ScannerHFHPresenter._build_file_match_entry(
+            component, best_version, 'file.py', 'hash', 'https://api.example.com'
+        )
+
+        lic = entry['licenses'][0]
+        self.assertEqual(lic['name'], 'Some Custom License')
+        self.assertEqual(lic['url'], '')
+
+    @patch('scanoss.scanners.scanner_hfh.purl2url')
+    def test_multiple_licenses_transformed(self, mock_purl2url):
+        mock_purl2url.get_repo_url.return_value = ''
+        component = {'purl': 'pkg:github/v/c', 'name': 'c', 'vendor': 'v'}
+        best_version = {
+            'version': '1.0',
+            'licenses': [
+                {'name': 'MIT License', 'spdx_id': 'MIT', 'is_spdx_approved': True, 'url': 'https://spdx.org/licenses/MIT.html'},
+                {'name': 'Apache License 2.0', 'spdx_id': 'Apache-2.0', 'is_spdx_approved': True, 'url': 'https://spdx.org/licenses/Apache-2.0.html'},
+            ],
+        }
+
+        entry = ScannerHFHPresenter._build_file_match_entry(
+            component, best_version, 'file.py', 'hash', 'https://api.example.com'
+        )
+
+        self.assertEqual(len(entry['licenses']), 2)
+        self.assertEqual(entry['licenses'][0]['name'], 'MIT')
+        self.assertEqual(entry['licenses'][0]['url'], 'https://spdx.org/licenses/MIT.html')
+        self.assertEqual(entry['licenses'][1]['name'], 'Apache-2.0')
+        self.assertEqual(entry['licenses'][1]['url'], 'https://spdx.org/licenses/Apache-2.0.html')
+
     @patch('scanoss.scanners.scanner_hfh.purl2url')
     def test_purl2url_returns_none(self, mock_purl2url):
         mock_purl2url.get_repo_url.return_value = None