feat: SP-3574 add GitLab matches summary report generator into inspect command

  Implements GitLab-compatible Markdown summary reports for SCANOSS matches with the following changes:
  - Add new 'inspect gitlab matches' CLI command to generate match summaries
  - Create MatchSummary class to process and format scan results with collapsible sections
  - Extract table generation utilities into shared markdown_utils module
  - Extract JSON file loading into shared file_utils module
  - Add support for GitLab file links with line range anchors

Author: agustingroh

CHANGELOG.md

@@ -11,7 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.38.0] - 2025-10-22
 ### Added
-- Added GitLab Code Quality report format support
+- Added `glc-codequality` format to convert subcomand
+- Added `inspect gitlab matches` subcommand to generate GitLab-compatible Markdown match summary from SCANOSS scan results
+- Added utility modules for shared functionality (`markdown_utils.py` and `file_utils.py`)
+### Changed
+- Refactored table generation utilities into shared `markdown_utils` module
+- Refactored JSON file loading into shared `file_utils` module
 
 ## [1.37.1] - 2025-10-21
 ### Added

src/scanoss/cli.py

@@ -40,6 +40,7 @@
 )
 from scanoss.inspection.raw.component_summary import ComponentSummary
 from scanoss.inspection.raw.license_summary import LicenseSummary
+from scanoss.inspection.raw.match_summary import MatchSummary
 from scanoss.scanners.container_scanner import (
     DEFAULT_SYFT_COMMAND,
     DEFAULT_SYFT_TIMEOUT,
@@ -73,6 +74,7 @@
 from .csvoutput import CsvOutput
 from .cyclonedx import CycloneDx
 from .filecount import FileCount
+from .gitlabqualityreport import GitLabQualityReport
 from .inspection.raw.copyleft import Copyleft
 from .inspection.raw.undeclared_component import UndeclaredComponent
 from .results import Results
@@ -85,7 +87,6 @@
 from .spdxlite import SpdxLite
 from .threadeddependencies import SCOPE
 from .utils.file import validate_json_file
-from .gitlabqualityreport import GitLabQualityReport
 
 HEADER_PARTS_COUNT = 2
 
@@ -284,7 +285,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         '--format',
         '-f',
         type=str,
-        choices=['cyclonedx', 'spdxlite', 'csv', 'glcodequality'],
+        choices=['cyclonedx', 'spdxlite', 'csv', 'glc-codequality'],
         default='spdxlite',
         help='Output format (optional - default: spdxlite)',
     )
@@ -795,6 +796,66 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         help='Timeout (in seconds) for API communication (optional - default 300 sec)',
     )
 
+
+    # ==============================================================================
+    # GitLab Integration Parser
+    # ==============================================================================
+    # Main parser for GitLab-specific inspection commands and report generation
+    p_gitlab_sub = p_inspect_sub.add_parser(
+        'gitlab',
+        aliases=['glc'],
+        description='Generate GitLab-compatible reports from SCANOSS scan results (Markdown summaries)',
+        help='Generate GitLab integration reports',
+    )
+
+    # GitLab sub-commands parser
+    # Provides access to different GitLab report formats and inspection tools
+    p_gitlab_sub_parser = p_gitlab_sub.add_subparsers(
+        title='GitLab Report Types',
+        dest='subparser_subcmd',
+        description='Available GitLab report formats for scan result analysis',
+        help='Select the type of GitLab report to generate',
+    )
+
+    # ==============================================================================
+    # GitLab Matches Summary Command
+    # ==============================================================================
+    # Analyzes scan results and generates a GitLab-compatible Markdown summary
+    p_gl_inspect_matches = p_gitlab_sub_parser.add_parser(
+        'matches',
+        aliases=['ms'],
+        description='Generate a Markdown summary report of scan matches for GitLab integration',
+        help='Generate Markdown summary report of scan matches',
+    )
+
+    # Input file argument - SCANOSS scan results in JSON format
+    p_gl_inspect_matches.add_argument(
+        '-i',
+        '--input',
+        required=True,
+        type=str,
+        help='Path to SCANOSS scan results file (JSON format) to analyze'
+    )
+
+    # Line range prefix for GitLab file navigation
+    # Enables clickable file references in the generated report that link to specific lines in GitLab
+    p_gl_inspect_matches.add_argument(
+        '-lpr',
+        '--line-range-prefix',
+        required=True,
+        type=str,
+        help='Base URL prefix for GitLab file links with line ranges (e.g., https://gitlab.com/org/project/-/blob/main)'
+    )
+
+    # Output file argument - where to save the generated Markdown report
+    p_gl_inspect_matches.add_argument(
+        '--output',
+        '-o',
+        required=False,
+        type=str,
+        help='Output file path for the generated Markdown report (default: stdout)'
+    )
+
     # TODO Move to the command call def location
     # RAW results
     p_inspect_raw_undeclared.set_defaults(func=inspect_undeclared)
@@ -808,6 +869,8 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
     p_inspect_legacy_component_summary.set_defaults(func=inspect_component_summary)
     # Dependency Track
     p_inspect_dt_project_violation.set_defaults(func=inspect_dep_track_project_violations)
+    # GitLab
+    p_gl_inspect_matches.set_defaults(func=inspect_gitlab_matches)
 
     # =========================================================================
     # END INSPECT SUBCOMMAND CONFIGURATION
@@ -1157,6 +1220,7 @@ def setup_args() -> None:  # noqa: PLR0912, PLR0915
         p_inspect_legacy_license_summary,
         p_inspect_legacy_component_summary,
         p_inspect_dt_project_violation,
+        p_gl_inspect_matches,
         c_provenance,
         p_folder_scan,
         p_folder_hash,
@@ -1613,7 +1677,7 @@ def convert(parser, args):
             print_stderr('Producing CSV report...')
         csvo = CsvOutput(debug=args.debug, output_file=args.output)
         success = csvo.produce_from_file(args.input)
-    elif args.format == 'glcodequality':
+    elif args.format == 'glc-codequality':
         if not args.quiet:
             print_stderr('Producing Gitlab code quality report...')
         glcCodeQuality = GitLabQualityReport(debug=args.debug, output_file=args.output)
@@ -1891,6 +1955,58 @@ def inspect_dep_track_project_violations(parser, args):
         sys.exit(1)
 
 
+def inspect_gitlab_matches(parser, args):
+    """
+    Handle GitLab matches summary inspection command.
+
+    Analyzes SCANOSS scan results and generates a GitLab-compatible Markdown summary
+    report of component matches. The report includes match details, file locations,
+    and optionally clickable links to source files in GitLab repositories.
+
+    This command processes SCANOSS scan output and creates human-readable Markdown.
+
+    Parameters
+    ----------
+    args : Namespace
+        Parsed command line arguments containing:
+        - input: Path to SCANOSS scan results file (JSON format) to analyze
+        - line_range_prefix: Base URL prefix for generating GitLab file links with line ranges
+                            (e.g., 'https://gitlab.com/org/project/-/blob/main')
+        - output: Optional output file path for the generated Markdown report (default: stdout)
+        - debug: Enable debug output for troubleshooting
+        - trace: Enable trace-level logging
+        - quiet: Suppress informational messages
+
+    Notes
+    -----
+    - The output is formatted in Markdown for optimal display in GitLab
+    - Line range prefix enables clickable file references in the report
+    - If output is not specified, the report is written to stdout
+    """
+    # Initialize output file if specified (create/truncate)
+    if args.output:
+        initialise_empty_file(args.output)
+
+    try:
+        # Create GitLab matches summary generator with configuration
+        match_summary = MatchSummary(
+            debug=args.debug,
+            trace=args.trace,
+            quiet=args.quiet,
+            scanoss_results_path=args.input,  # Path to SCANOSS JSON results
+            output=args.output,  # Output file path or None for stdout
+            line_range_prefix=args.line_range_prefix,  # GitLab URL prefix for file links
+        )
+
+        # Execute the summary generation
+        match_summary.run()
+    except Exception as e:
+        # Handle any errors during report generation
+        print_stderr(e)
+        if args.debug:
+            traceback.print_exc()
+        sys.exit(1)
+
 # =============================================================================
 # END INSPECT COMMAND HANDLERS
 # =============================================================================

src/scanoss/gitlabqualityreport.py

@@ -5,6 +5,7 @@
 
 from .scanossbase import ScanossBase
 
+
 @dataclass
 class Lines:
     begin: int
@@ -73,8 +74,10 @@ def _get_code_quality(self, file_name: str,result: dict) -> CodeQuality or None:
         if len(lines) == 0:
             self.print_debug(f"Warning: empty lines for result: {result}")
             return None
+        end_line = lines[len(lines) - 1] if len(lines) > 1 else lines[0]
+        description = f"Snippet found in: {file_name} - lines {lines[0]}-{end_line}"
         return CodeQuality(
-            description=f"Snippet found in: {file_name} - lines {lines[0]}-{lines[len(lines) - 1] if len(lines) > 1 else lines[0]}",
+            description=description,
             check_name=file_name,
             fingerprint=result.get('file_hash'),
             severity="info",

src/scanoss/inspection/dependency_track/project_violation.py

@@ -28,6 +28,7 @@
 
 from ...services.dependency_track_service import DependencyTrackService
 from ..policy_check import PolicyCheck, PolicyStatus
+from ..utils.markdown_utils import generate_jira_table, generate_table
 
 # Constants
 PROCESSING_RETRY_DELAY = 5  # seconds
@@ -195,7 +196,7 @@ def _markdown(self, project_violations: list[PolicyViolationDict]) -> Dict[str,
         Returns:
             Dictionary with formatted Markdown details and summary
         """
-        return self._md_summary_generator(project_violations, self.generate_table)
+        return self._md_summary_generator(project_violations, generate_table)
 
     def _jira_markdown(self, data: list[PolicyViolationDict]) -> Dict[str, Any]:
         """
@@ -207,7 +208,7 @@ def _jira_markdown(self, data: list[PolicyViolationDict]) -> Dict[str, Any]:
         Returns:
             Dictionary containing Jira markdown formatted results and summary
         """
-        return self._md_summary_generator(data, self.generate_jira_table)
+        return self._md_summary_generator(data, generate_jira_table)
 
     def is_project_updated(self, dt_project: Dict[str, Any]) -> bool:
         """

src/scanoss/inspection/policy_check.py

@@ -137,48 +137,6 @@ def _jira_markdown(self, data: list[T]) -> Dict[str, Any]:
         """
         pass
 
-    def generate_table(self, headers, rows, centered_columns=None):
-        """
-        Generate a Markdown table.
-
-        :param headers: List of headers for the table.
-        :param rows: List of rows for the table.
-        :param centered_columns: List of column indices to be centered.
-        :return: A string representing the Markdown table.
-        """
-        col_sep = ' | '
-        centered_column_set = set(centered_columns or [])
-        if headers is None:
-            self.print_stderr('ERROR: Header are no set')
-            return None
-
-        # Decide which separator to use
-        def create_separator(index):
-            if centered_columns is None:
-                return '-'
-            return ':-:' if index in centered_column_set else '-'
-
-        # Build the row separator
-        row_separator = col_sep + col_sep.join(create_separator(index) for index, _ in enumerate(headers)) + col_sep
-        # build table rows
-        table_rows = [col_sep + col_sep.join(headers) + col_sep, row_separator]
-        table_rows.extend(col_sep + col_sep.join(row) + col_sep for row in rows)
-        return '\n'.join(table_rows)
-
-    def generate_jira_table(self, headers, rows, centered_columns=None):
-        col_sep = '*|*'
-        if headers is None:
-            self.print_stderr('ERROR: Header are no set')
-            return None
-
-        table_header = '|*' + col_sep.join(headers) + '*|\n'
-        table = table_header
-        for row in rows:
-            if len(headers) == len(row):
-                table += '|' + '|'.join(row) + '|\n'
-
-        return table
-
     def _get_formatter(self) -> Callable[[List[dict]], Dict[str, Any]] or None:
         """
         Get the appropriate formatter function based on the specified format.

src/scanoss/inspection/raw/__init__.py

@@ -27,6 +27,7 @@
 from typing import Any, Dict, List
 
 from ..policy_check import PolicyStatus
+from ..utils.markdown_utils import generate_jira_table, generate_table
 from .raw_base import RawBase
 
 
@@ -111,7 +112,7 @@ def _markdown(self, components: list[Component]) -> Dict[str, Any]:
         :param components: List of components with copyleft licenses
         :return: Dictionary with formatted Markdown details and summary
         """
-        return self._md_summary_generator(components, self.generate_table)
+        return self._md_summary_generator(components, generate_table)
 
     def _jira_markdown(self, components: list[Component]) -> Dict[str, Any]:
         """
@@ -120,7 +121,7 @@ def _jira_markdown(self, components: list[Component]) -> Dict[str, Any]:
         :param components: List of components with copyleft licenses
         :return: Dictionary with formatted Markdown details and summary
         """
-        return self._md_summary_generator(components, self.generate_jira_table)
+        return self._md_summary_generator(components, generate_jira_table)
 
     def _md_summary_generator(self, components: list[Component], table_generator):
         """