Add deprecation warnings to summary plugins

setup.cfg

@@ -177,7 +177,7 @@ scancode_scan =
 # module for details and doc.
 scancode_post_scan =
     summary = summarycode.summarizer:ScanSummary
-    summary2 = summarycode.summarizer2:ScanSummary
+    summary-legacy = summarycode.summarizer:ScanSummaryLegacy
     summary-keeping-details = summarycode.summarizer:ScanSummaryWithDetails
     summary-key-files = summarycode.summarizer:ScanKeyFilesSummary
     summary-by-facet = summarycode.summarizer:ScanByFacetSummary

src/summarycode/plugin_consolidate.py

@@ -7,6 +7,7 @@
 # See https://aboutcode.org for more information about nexB OSS projects.
 #
 
+import warnings
 from collections import Counter
 
 import attr
@@ -109,6 +110,10 @@ def to_dict(self, **kwargs):
         return package
 
 
+class ConsolidatorPluginDeprecationWarning(DeprecationWarning):
+    pass
+
+
 @post_scan_impl
 class Consolidator(PostScanPlugin):
     """
@@ -152,6 +157,16 @@ def is_enabled(self, consolidate, **kwargs):
         return consolidate
 
     def process_codebase(self, codebase, **kwargs):
+        deprecation_message = "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+        warnings.simplefilter('always', ConsolidatorPluginDeprecationWarning)
+        warnings.warn(
+            deprecation_message,
+            ConsolidatorPluginDeprecationWarning,
+            stacklevel=2,
+        )
+        codebase_header = codebase.get_or_create_current_header()
+        codebase_header.warnings.append(deprecation_message)
+
         # Collect ConsolidatedPackages and ConsolidatedComponents
         # TODO: Have a "catch-all" Component for the things that we haven't grouped
         consolidations = []

src/summarycode/summarizer.py

@@ -8,6 +8,7 @@
 #
 
 from collections import Counter
+import warnings
 
 import attr
 
@@ -57,7 +58,9 @@ class ScanSummary(PostScanPlugin):
         PluggableCommandLineOption(('--summary',),
             is_flag=True, default=False,
             help='Summarize license, copyright and other scans at the codebase level.',
-            help_group=POST_SCAN_GROUP)
+            help_group=POST_SCAN_GROUP,
+            required_options=['classify', 'license_clarity_score']
+        )
     ]
 
     def is_enabled(self, summary, **kwargs):
@@ -68,6 +71,47 @@ def process_codebase(self, codebase, summary, **kwargs):
         summarize_codebase(codebase, keep_details=False, **kwargs)
 
 
+class SummaryLegacyPluginDeprecationWarning(DeprecationWarning):
+    pass
+
+
+@post_scan_impl
+class ScanSummaryLegacy(PostScanPlugin):
+    """
+    Summarize a scan at the codebase level.
+    """
+    sort_order = 10
+
+    codebase_attributes = dict(summary=attr.ib(default=attr.Factory(dict)))
+
+    options = [
+        PluggableCommandLineOption(('--summary-legacy',),
+            is_flag=True, default=False,
+            help='Summarize license, copyright and other scans at the codebase level.',
+            help_group=POST_SCAN_GROUP)
+    ]
+
+    def is_enabled(self, summary, **kwargs):
+        return summary
+
+    def process_codebase(self, codebase, summary, **kwargs):
+        deprecation_message = "The --summary-legacy option will be deprecated in a future version of scancode-toolkit."
+        warnings.simplefilter('always', SummaryLegacyPluginDeprecationWarning)
+        warnings.warn(
+            deprecation_message,
+            SummaryLegacyPluginDeprecationWarning,
+            stacklevel=2,
+        )
+        codebase_header = codebase.get_or_create_current_header()
+        codebase_header.warnings.append(deprecation_message)
+        if TRACE_LIGHT: logger_debug('ScanSummaryLegacy:process_codebase')
+        summarize_codebase(codebase, keep_details=False, legacy=True, **kwargs)
+
+
+class SummaryWithDetailsDeprecationWarning(DeprecationWarning):
+    pass
+
+
 @post_scan_impl
 class ScanSummaryWithDetails(PostScanPlugin):
     """
@@ -92,29 +136,47 @@ def is_enabled(self, summary_with_details, **kwargs):
         return summary_with_details
 
     def process_codebase(self, codebase, summary_with_details, **kwargs):
-        summarize_codebase(codebase, keep_details=True, **kwargs)
+        deprecation_message = "The --summary-with-details option will be deprecated in a future version of scancode-toolkit."
+        warnings.simplefilter('always', SummaryWithDetailsDeprecationWarning)
+        warnings.warn(
+            deprecation_message,
+            SummaryWithDetailsDeprecationWarning,
+            stacklevel=2,
+        )
+        codebase_header = codebase.get_or_create_current_header()
+        codebase_header.warnings.append(deprecation_message)
+        summarize_codebase(codebase, keep_details=True, legacy=True, **kwargs)
 
 
-def summarize_codebase(codebase, keep_details, **kwargs):
+def summarize_codebase(codebase, keep_details, legacy=False, **kwargs):
     """
     Summarize a scan at the codebase level for available scans.
 
     If `keep_details` is True, also keep file and directory details in the
     `summary` file attribute for every file and directory.
+
+    If `legacy` is True, summarize copyrights, authors, programming languages,
+    and packages.
     """
-    from summarycode.copyright_summary import author_summarizer
-    from summarycode.copyright_summary import copyright_summarizer
     from summarycode.copyright_summary import holder_summarizer
 
     attrib_summarizers = [
         ('license_expressions', license_summarizer),
-        ('copyrights', copyright_summarizer),
         ('holders', holder_summarizer),
-        ('authors', author_summarizer),
-        ('programming_language', language_summarizer),
-        ('packages', package_summarizer),
     ]
 
+    if legacy:
+        from summarycode.copyright_summary import author_summarizer
+        from summarycode.copyright_summary import copyright_summarizer
+
+        attrib_summarizers.extend([
+            ('copyrights', copyright_summarizer),
+            ('authors', author_summarizer),
+            ('programming_language', language_summarizer),
+            ('packages', package_summarizer),
+        ])
+
+
     # find which attributes are available for summarization by checking the root
     # resource
     root = codebase.root
@@ -256,6 +318,10 @@ def summarize_values(values, attribute):
     return value_summarizers_by_attr[attribute](values)
 
 
+class SummaryKeyFilesDeprecationWarning(DeprecationWarning):
+    pass
+
+
 @post_scan_impl
 class ScanKeyFilesSummary(PostScanPlugin):
     """
@@ -283,6 +349,15 @@ def is_enabled(self, summary_key_files, **kwargs):
         return summary_key_files
 
     def process_codebase(self, codebase, summary_key_files, **kwargs):
+        deprecation_message = "The --summary-key-files option will be deprecated in a future version of scancode-toolkit."
+        warnings.simplefilter('always', SummaryKeyFilesDeprecationWarning)
+        warnings.warn(
+            deprecation_message,
+            SummaryKeyFilesDeprecationWarning,
+            stacklevel=2,
+        )
+        codebase_header = codebase.get_or_create_current_header()
+        codebase_header.warnings.append(deprecation_message)
         summarize_codebase_key_files(codebase, **kwargs)
 
 
@@ -330,6 +405,10 @@ def summarize_codebase_key_files(codebase, **kwargs):
     if TRACE: logger_debug('codebase summary_of_key_files:', sorted_summaries)
 
 
+class SummaryByFacetPluginDeprecationWarning(DeprecationWarning):
+    pass
+
+
 @post_scan_impl
 class ScanByFacetSummary(PostScanPlugin):
     """
@@ -352,6 +431,15 @@ def is_enabled(self, summary_by_facet, **kwargs):
         return summary_by_facet
 
     def process_codebase(self, codebase, summary_by_facet, **kwargs):
+        deprecation_message = "The --summary-by-facet option will be deprecated in a future version of scancode-toolkit."
+        warnings.simplefilter('always', SummaryByFacetPluginDeprecationWarning)
+        warnings.warn(
+            deprecation_message,
+            SummaryByFacetPluginDeprecationWarning,
+            stacklevel=2,
+        )
+        codebase_header = codebase.get_or_create_current_header()
+        codebase_header.warnings.append(deprecation_message)
         if TRACE_LIGHT: logger_debug('ScanByFacetSummary:process_codebase')
         summarize_codebase_by_facet(codebase, **kwargs)
 

tests/summarycode/data/classify/cli.expected.json

@@ -9,11 +9,12 @@
         "--json-pp": "<file>"
       },
       "notice": "Generated with ScanCode and provided on an \"AS IS\" BASIS, WITHOUT WARRANTIES\nOR CONDITIONS OF ANY KIND, either express or implied. No content created from\nScanCode should be considered or used as legal advice. Consult an Attorney\nfor any legal advice.\nScanCode is a free software code scanning tool from nexB Inc. and others.\nVisit https://github.com/nexB/scancode-toolkit/ for support and download.",
-      "output_format_version": "1.0.0",
+      "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [],
       "extra_data": {
-        "spdx_license_list_version": "3.14",
+        "spdx_license_list_version": "3.16",
         "files_count": 8
       }
     }

tests/summarycode/data/facet/cli.expected.json

@@ -13,11 +13,12 @@
         "--json-pp": "<file>"
       },
       "notice": "Generated with ScanCode and provided on an \"AS IS\" BASIS, WITHOUT WARRANTIES\nOR CONDITIONS OF ANY KIND, either express or implied. No content created from\nScanCode should be considered or used as legal advice. Consult an Attorney\nfor any legal advice.\nScanCode is a free software code scanning tool from nexB Inc. and others.\nVisit https://github.com/nexB/scancode-toolkit/ for support and download.",
-      "output_format_version": "1.0.0",
+      "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [],
       "extra_data": {
-        "spdx_license_list_version": "3.14",
+        "spdx_license_list_version": "3.16",
         "files_count": 56
       }
     }

tests/summarycode/data/generated/cli.expected.json

@@ -8,11 +8,12 @@
         "--json-pp": "<file>"
       },
       "notice": "Generated with ScanCode and provided on an \"AS IS\" BASIS, WITHOUT WARRANTIES\nOR CONDITIONS OF ANY KIND, either express or implied. No content created from\nScanCode should be considered or used as legal advice. Consult an Attorney\nfor any legal advice.\nScanCode is a free software code scanning tool from nexB Inc. and others.\nVisit https://github.com/nexB/scancode-toolkit/ for support and download.",
-      "output_format_version": "1.0.0",
+      "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [],
       "extra_data": {
-        "spdx_license_list_version": "3.14",
+        "spdx_license_list_version": "3.16",
         "files_count": 7
       }
     }

tests/summarycode/data/plugin_consolidate/component-package-build-expected.json

@@ -15,6 +15,9 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
         "spdx_license_list_version": "3.16",
         "files_count": 8

tests/summarycode/data/plugin_consolidate/component-package-expected.json

@@ -15,6 +15,9 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
         "spdx_license_list_version": "3.16",
         "files_count": 7

tests/summarycode/data/plugin_consolidate/e2fsprogs-expected.json

@@ -20,6 +20,7 @@
       "output_format_version": null,
       "message": null,
       "errors": [],
+      "warnings": [],
       "extra_data": {
         "files_count": 2183
       }
@@ -36,8 +37,11 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
-        "spdx_license_list_version": "3.15",
+        "spdx_license_list_version": "3.16",
         "files_count": 2183
       }
     }

tests/summarycode/data/plugin_consolidate/license-holder-rollup-expected.json

@@ -15,8 +15,11 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
-        "spdx_license_list_version": "3.15",
+        "spdx_license_list_version": "3.16",
         "files_count": 3
       }
     }

tests/summarycode/data/plugin_consolidate/multiple-same-holder-and-license-expected.json

@@ -15,8 +15,11 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
-        "spdx_license_list_version": "3.15",
+        "spdx_license_list_version": "3.16",
         "files_count": 2
       }
     }

tests/summarycode/data/plugin_consolidate/package-files-not-counted-in-license-holders-expected.json

@@ -15,6 +15,9 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
         "spdx_license_list_version": "3.16",
         "files_count": 6

tests/summarycode/data/plugin_consolidate/package-fileset-expected.json

@@ -15,6 +15,9 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
         "spdx_license_list_version": "3.16",
         "files_count": 4

tests/summarycode/data/plugin_consolidate/package-manifest-expected.json

@@ -15,6 +15,9 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
         "spdx_license_list_version": "3.16",
         "files_count": 1

tests/summarycode/data/plugin_consolidate/report-subdirectory-with-minority-origin-expected.json

@@ -15,8 +15,11 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
-        "spdx_license_list_version": "3.15",
+        "spdx_license_list_version": "3.16",
         "files_count": 4
       }
     }

tests/summarycode/data/plugin_consolidate/return-nested-local-majority-expected.json

@@ -15,8 +15,11 @@
       "output_format_version": "2.0.0",
       "message": null,
       "errors": [],
+      "warnings": [
+        "The --consolidate option will be deprecated in a future version of scancode-toolkit."
+      ],
       "extra_data": {
-        "spdx_license_list_version": "3.15",
+        "spdx_license_list_version": "3.16",
         "files_count": 4
       }
     }