From 017341f2d5c66a11ccacc5aa4357ff4cc59c7144 Mon Sep 17 00:00:00 2001 From: Agustin Isasmendi Date: Fri, 22 Mar 2024 20:23:34 +0100 Subject: [PATCH] SP-247 Adds comments on code --- dist/index.js | 42 +++++++++++++++++++++++++ src/policies/copyleft-policy-check.ts | 5 +++ src/policies/undeclared-policy-check.ts | 7 +++++ src/services/result.service.ts | 14 +++++++++ src/services/scan.service.ts | 42 ++++++++++++++++++++++++- 5 files changed, 109 insertions(+), 1 deletion(-) diff --git a/dist/index.js b/dist/index.js index 958d678..96d3972 100644 --- a/dist/index.js +++ b/dist/index.js @@ -125966,6 +125966,11 @@ const app_config_1 = __nccwpck_require__(29014); const policy_check_1 = __nccwpck_require__(63702); const result_service_1 = __nccwpck_require__(32414); const markdown_utils_1 = __nccwpck_require__(96011); +/** + * This class checks if any of the components identified in the scanner results are subject to copyleft licenses. + * It filters components based on their licenses and looks for those with copyleft obligations. + * It then generates a summary and detailed report of the findings. + */ class CopyleftPolicyCheck extends policy_check_1.PolicyCheck { constructor() { super(`${app_config_1.CHECK_NAME}: Copyleft Policy`); @@ -126296,6 +126301,13 @@ const result_service_1 = __nccwpck_require__(32414); const inputs = __importStar(__nccwpck_require__(483)); const sbom_utils_1 = __nccwpck_require__(31156); const markdown_utils_1 = __nccwpck_require__(96011); +/** + * Verifies that all components identified in scanner results are declared in the project's SBOM. + * The run method compares components found by the scanner against those declared in the SBOM. + * + * It identifies and reports undeclared components, generating a summary and detailed report of the findings. + * + */ class UndeclaredPolicyCheck extends policy_check_1.PolicyCheck { constructor() { super(`${app_config_1.CHECK_NAME}: Undeclared Policy`); @@ -126545,6 +126557,14 @@ var ComponentID; Object.defineProperty(exports, "__esModule", ({ value: true })); exports.getLicenses = exports.getComponents = void 0; const result_interfaces_1 = __nccwpck_require__(61554); +/** + * This function groups components by their `purl` and aggregates their licenses, + * ensuring that each unique `purl` is represented once with a comprehensive list of licenses. + * + * @param results - The raw scanner results to be processed of type {@link ScannerResults} + * @returns An array of {@link Component} objects, each representing a unique component + * with an aggregated list of licenses. + */ function getComponents(results) { const components = new Array(); for (const component of Object.values(results)) { @@ -126601,6 +126621,12 @@ function getComponents(results) { return unqiqueComponents; } exports.getComponents = getComponents; +/** + * This function generate an array of {@link License } from raw scanner results {@link ScannerResults } + * + * @param results - The raw scanner results to be processed of type {@link ScannerResults} + * @returns An array of {@link License} objects + */ function getLicenses(results) { const licenses = new Array(); for (const component of Object.values(results)) { @@ -126718,6 +126744,10 @@ async function uploadResults() { await artifact.uploadArtifact(path.basename(inputs.OUTPUT_FILEPATH), [inputs.OUTPUT_FILEPATH], path.dirname(inputs.OUTPUT_FILEPATH)); } exports.uploadResults = uploadResults; +/** + * `ScanService` is a class that wraps the `scanoss.py` Docker image, providing a simplified interface + * for configuring and executing source code scans + */ class ScanService { options; constructor(options) { @@ -126746,6 +126776,18 @@ class ScanService { ${this.options.apiUrl ? `--apiurl ${this.options.apiUrl}` : ''} ${this.options.apiKey ? `--key ${this.options.apiKey}` : ''}`.replace(/\n/gm, ' '); } + /** + * Constructs the command segment for SBOM ingestion based on the current configuration. This method checks if SBOM + * ingestion is enabled and verifies the SBOM file's existence before constructing the command. + * + * @example + * // When SBOM ingestion is enabled with a specified SBOM file and type: + * // sbomEnabled = true, sbomFilepath = "/src/SBOM.json", sbomType = "identify" + * // returns "--identify /src/SBOM.json" + * + * @returns A command string segment for SBOM ingestion or an empty string if conditions are not met. + * @private + */ async detectSBOM() { if (!this.options.sbomEnabled || !this.options.sbomFilepath) return ''; diff --git a/src/policies/copyleft-policy-check.ts b/src/policies/copyleft-policy-check.ts index 71ec260..f5aa1ff 100644 --- a/src/policies/copyleft-policy-check.ts +++ b/src/policies/copyleft-policy-check.ts @@ -27,6 +27,11 @@ import { PolicyCheck } from './policy-check'; import { Component, getComponents } from '../services/result.service'; import { generateTable } from '../utils/markdown.utils'; +/** + * This class checks if any of the components identified in the scanner results are subject to copyleft licenses. + * It filters components based on their licenses and looks for those with copyleft obligations. + * It then generates a summary and detailed report of the findings. + */ export class CopyleftPolicyCheck extends PolicyCheck { constructor() { super(`${CHECK_NAME}: Copyleft Policy`); diff --git a/src/policies/undeclared-policy-check.ts b/src/policies/undeclared-policy-check.ts index 0a73743..257b40f 100644 --- a/src/policies/undeclared-policy-check.ts +++ b/src/policies/undeclared-policy-check.ts @@ -29,6 +29,13 @@ import * as inputs from '../app.input'; import { parseSBOM } from '../utils/sbom.utils'; import { generateTable } from '../utils/markdown.utils'; +/** + * Verifies that all components identified in scanner results are declared in the project's SBOM. + * The run method compares components found by the scanner against those declared in the SBOM. + * + * It identifies and reports undeclared components, generating a summary and detailed report of the findings. + * + */ export class UndeclaredPolicyCheck extends PolicyCheck { constructor() { super(`${CHECK_NAME}: Undeclared Policy`); diff --git a/src/services/result.service.ts b/src/services/result.service.ts index b1383e5..793f519 100644 --- a/src/services/result.service.ts +++ b/src/services/result.service.ts @@ -38,6 +38,14 @@ export interface Component { licenses: License[]; } +/** + * This function groups components by their `purl` and aggregates their licenses, + * ensuring that each unique `purl` is represented once with a comprehensive list of licenses. + * + * @param results - The raw scanner results to be processed of type {@link ScannerResults} + * @returns An array of {@link Component} objects, each representing a unique component + * with an aggregated list of licenses. + */ export function getComponents(results: ScannerResults): Component[] { const components = new Array(); @@ -99,6 +107,12 @@ export function getComponents(results: ScannerResults): Component[] { return unqiqueComponents; } +/** + * This function generate an array of {@link License } from raw scanner results {@link ScannerResults } + * + * @param results - The raw scanner results to be processed of type {@link ScannerResults} + * @returns An array of {@link License} objects + */ export function getLicenses(results: ScannerResults): License[] { const licenses = new Array(); diff --git a/src/services/scan.service.ts b/src/services/scan.service.ts index 1bdd704..5e78592 100644 --- a/src/services/scan.service.ts +++ b/src/services/scan.service.ts @@ -40,19 +40,47 @@ export async function uploadResults(): Promise { } export interface Options { - sbomType?: string; + /** + * Whether SBOM ingestion is enabled. Optional. + */ sbomEnabled?: boolean; + + /** + * Specifies the SBOM processing type: "identify" or "ignore". Optional. + */ + sbomType?: string; + + /** + * Absolute path to the SBOM file. Required if sbomEnabled is set to true. + */ sbomFilepath?: string; + /** + * Enables scanning for dependencies, utilizing scancode internally. Optional. + */ dependenciesEnabled?: boolean; + /** + * Credentials for SCANOSS, enabling unlimited scans. Optional. + */ apiKey?: string; apiUrl?: string; + /** + * Absolute path where scan results are saved. Required. + */ outputFilepath: string; + + /** + * Absolute path of the folder or file to scan. Required. + */ inputFilepath: string; } +/** + * `ScanService` is a class that wraps the `scanoss.py` Docker image, providing a simplified interface + * for configuring and executing source code scans + */ export class ScanService { private options: Options; constructor(options?: Options) { @@ -83,6 +111,18 @@ export class ScanService { ${this.options.apiKey ? `--key ${this.options.apiKey}` : ''}`.replace(/\n/gm, ' '); } + /** + * Constructs the command segment for SBOM ingestion based on the current configuration. This method checks if SBOM + * ingestion is enabled and verifies the SBOM file's existence before constructing the command. + * + * @example + * // When SBOM ingestion is enabled with a specified SBOM file and type: + * // sbomEnabled = true, sbomFilepath = "/src/SBOM.json", sbomType = "identify" + * // returns "--identify /src/SBOM.json" + * + * @returns A command string segment for SBOM ingestion or an empty string if conditions are not met. + * @private + */ private async detectSBOM(): Promise { if (!this.options.sbomEnabled || !this.options.sbomFilepath) return '';