Sort combined scan headers #1439

    * Update comments

Signed-off-by: Jono Yang <jyang@nexb.com>

Author: JonoYang

src/scancode/cli.py

@@ -544,6 +544,11 @@ def echo_func(*_args, **_kwargs):
     elif len(input) == 1:
         # we received a single input path, so we treat this as a single path
         input = input[0]  # NOQA
+
+    # This is the case where we have a list of inputs, but the list of inputs are not from the
+    # `from_json` option. If the `from_json` option is available and we have a list of inputs
+    # from it, we can pass `input` just fine when we create a VirtualCodebase, otherwise we have to
+    # process `input` below.
     elif not from_json:
         # we received a several input paths: we can handle this IFF they share
         # a common root directory and none is an absolute path

src/scancode/resource.py

@@ -1401,7 +1401,7 @@ def _get_scan_data(self, location):
         - a JSON string
         - a Python mapping
 
-        or `location` is a List that contains multiple paths to scans that are to be joined together.
+        or `location` is a List or a Tuple that contains multiple paths to scans that are to be joined together.
         """
         if isinstance(location, dict):
             return location
@@ -1411,6 +1411,7 @@ def _get_scan_data(self, location):
                 scan_data = self._get_scan_data_helper(loc)
                 combined_scan_data['headers'].extend(scan_data['headers'])
                 combined_scan_data['files'].extend(scan_data['files'])
+            combined_scan_data['headers'] = sorted(combined_scan_data['headers'], key=lambda x: x['start_timestamp'])
             return combined_scan_data
         return self._get_scan_data_helper(location)
 
@@ -1544,6 +1545,7 @@ def _populate(self, scan_data):
         # Create root resource without setting root data just yet. If we run into the root data
         # while we iterate through `resources_data`, we fill in the data then.
 
+        # Create a virtual root if we are merging multiple scans together
         multiple_input = isinstance(self.location, (list, tuple,)) and len(self.location) > 1
         if multiple_input:
             root_path = 'virtual_root'
@@ -1562,6 +1564,7 @@ def _populate(self, scan_data):
 
         for resource_data in resources_data:
             path = resource_data.get('path')
+            # Append virtual_root path to imported Resource path if we are merging multiple scans
             if multiple_input:
                 path = os.path.join(root_path, path)
             name = resource_data.get('name', None)