diff --git a/src/codeActionHandler.ts b/src/codeActionHandler.ts index 19b1216b..8ef64ec9 100644 --- a/src/codeActionHandler.ts +++ b/src/codeActionHandler.ts @@ -118,13 +118,12 @@ function generateSwitchToRecommendedVersionAction(title: string, dependency: str } /** - * Generates a code action to switch to the recommended version. + * Generates a code action to redirect to the recommended version catalog. * @param title - The title of the code action. - * @param dependency - The dependency (package and version) provided by exhort. - * @param versionReplacementString - The version replacement string. + * @param imageRef - The image reference provided by exhort. * @param diagnostic - The diagnostic information. * @param uri - The URI of the file. - * @returns A CodeAction object for switching to the recommended version. + * @returns A CodeAction object for redirecting to the recommended version catalog. */ function generateRedirectToRecommendedVersionAction(title: string, imageRef: string, diagnostic: Diagnostic, uri: string): CodeAction { const codeAction: CodeAction = { diff --git a/src/dependencyAnalysis/analysis.ts b/src/dependencyAnalysis/analysis.ts index 0e9c6cdd..55cea70c 100644 --- a/src/dependencyAnalysis/analysis.ts +++ b/src/dependencyAnalysis/analysis.ts @@ -45,7 +45,7 @@ class DependencyData implements IDependencyData { } /** - * Represents the parsed response of Red Hat Dependency Analysis, with dependencies mapped by string keys. + * Represents the parsed response of Red Hat Dependency Analytics (RHDA) analysis, with dependencies mapped by reference string. */ interface IAnalysisResponse { dependencies: Map; @@ -147,9 +147,10 @@ class AnalysisResponse implements IAnalysisResponse { } /** - * Performs RHDA component analysis on provided manifest contents and fileType based on ecosystem. - * @param fileType - The type of file (e.g., 'pom.xml', 'package.json', 'go.mod', 'requirements.txt', 'Dockerfile'). + * Performs RHDA component analysis on provided manifest contents/path and fileType based on ecosystem. + * @param diagnosticFilePath - The path to the manifest file to analyze. * @param contents - The contents of the manifest file to analyze. + * @param provider - The dependency provider of the corresponding ecosystem. * @returns A Promise resolving to an AnalysisResponse object. */ async function executeComponentAnalysis (diagnosticFilePath: string, contents: string, provider: IDependencyProvider): Promise { diff --git a/src/dependencyAnalysis/diagnostics.ts b/src/dependencyAnalysis/diagnostics.ts index 10657fac..2f72ae96 100644 --- a/src/dependencyAnalysis/diagnostics.ts +++ b/src/dependencyAnalysis/diagnostics.ts @@ -18,9 +18,15 @@ import { AbstractDiagnosticsPipeline } from '../diagnosticsPipeline'; /** * Implementation of DiagnosticsPipeline interface. + * @typeparam DependencyData - The type of elements in the dependency data array. */ -class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { +class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { + /** + * Creates an instance of DiagnosticsPipeline. + * @param dependencyMap - The dependency map containing information about dependencies derived from the dependency manifest. + * @param diagnosticFilePath - The path to the manifest file to retrieve diagnostics from. + */ constructor( private dependencyMap: DependencyMap, diagnosticFilePath: string, @@ -28,6 +34,10 @@ class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { super(diagnosticFilePath); } + /** + * Runs diagnostics on dependencies. + * @param dependencies - A map containing dependency data by reference string. + */ runDiagnostics(dependencies: Map) { Object.entries(dependencies).map(([ref, dependencyData]) => { const dependencyRef = ref.split('@')[0]; diff --git a/src/diagnosticsPipeline.ts b/src/diagnosticsPipeline.ts index fe4ff84e..e72f8273 100644 --- a/src/diagnosticsPipeline.ts +++ b/src/diagnosticsPipeline.ts @@ -6,14 +6,14 @@ import { Diagnostic } from 'vscode-languageserver'; -import { DependencyData } from './dependencyAnalysis/analysis'; import { connection } from './server'; import { decodeUriPath } from './utils'; /** * Diagnostics Pipeline specification. + * @typeparam T - The type of elements in the artifact data array. */ -interface IDiagnosticsPipeline { +interface IDiagnosticsPipeline { /** * Clears diagnostics. */ @@ -24,16 +24,29 @@ interface IDiagnosticsPipeline { reportDiagnostics(); /** * Runs diagnostics on dependencies. - * @param dependencies - A map containing dependency data from exhort. + * @param artifact - A map containing artifact data. */ - runDiagnostics(dependencies: Map); + runDiagnostics(artifact: Map); } -abstract class AbstractDiagnosticsPipeline implements IDiagnosticsPipeline{ - +/** + * Abstract class for implementing a diagnostics pipeline. + * @typeparam T - The type of elements in the artifact data array. + */ +abstract class AbstractDiagnosticsPipeline implements IDiagnosticsPipeline{ + /** + * An array to hold diagnostic information. + */ protected diagnostics: Diagnostic[] = []; + /** + * A map to hold vulnerability count information. + */ protected vulnCount: Map = new Map(); + /** + * Creates an instance of AbstractDiagnosticsPipeline. + * @param diagnosticFilePath - The path to the manifest file to retrieve diagnostics from. + */ constructor(protected readonly diagnosticFilePath: string) {} clearDiagnostics() { @@ -53,7 +66,7 @@ abstract class AbstractDiagnosticsPipeline implements IDiagnosticsPipeline{ }); } - abstract runDiagnostics(dependencies: Map): void; + abstract runDiagnostics(artifact: Map): void; } export { AbstractDiagnosticsPipeline }; \ No newline at end of file diff --git a/src/imageAnalysis/analysis.ts b/src/imageAnalysis/analysis.ts index 1bc74544..b0f88e5e 100644 --- a/src/imageAnalysis/analysis.ts +++ b/src/imageAnalysis/analysis.ts @@ -11,28 +11,46 @@ import { globalConfig } from '../config'; import { isDefined, decodeUriPath } from '../utils'; import { IImage } from '../imageAnalysis/collector'; +/** + * Represents the Red Hat Dependency Analytics (RHDA) analysis report, with images mapped by string keys. + */ interface IExhortAnalysisReport { [key: string]: IImageReport; } +/** + * Represents the RHDA analysis report for a single image. + */ interface IImageReport { providers: Map; } +/** + * Represents a provider of dependencies for an image. + */ interface IProvider { status: IStatus; sources: Map; } +/** + * Represents the status of a provider. + */ interface IStatus { ok: boolean; } +/** + * Represents a source of dependencies. + */ interface ISource { summary: ISummary; dependencies: ISourceDependency[]; } +/** + * Represents the summary of vulnerabilities for a source. + */ interface ISummary { total: number, critical: number, @@ -41,10 +59,16 @@ interface ISummary { low: number, } +/** + * Represents a dependency reported by a source. + */ interface ISourceDependency { recommendation: string | null; } +/** + * Represents data collected related to an image. + */ interface IArtifact { id: string; summary: ISummary; @@ -52,7 +76,7 @@ interface IArtifact { } /** -* Represents data specification related to a dependency. +* Represents data specification related to an image. */ interface IImageData { sourceId: string; @@ -62,8 +86,8 @@ interface IImageData { } /** -* Implementation of IDependencyData interface. -*/ + * Implementation of IImageData interface. + */ class ImageData implements IImageData { constructor( public sourceId: string, @@ -74,7 +98,7 @@ class ImageData implements IImageData { } /** -* Represents the parsed response of Red Hat Dependency Analysis, with dependencies mapped by string keys. +* Represents the parsed response of Red Hat Dependency Analytics (RHDA) analysis report, with images mapped by string keys. */ interface IAnalysisResponse { images: Map; @@ -128,9 +152,9 @@ class AnalysisResponse implements IAnalysisResponse { } /** - * Retrieves the highest vulnerability severity value from a dependency. - * @param dependency The dependency object. - * @returns The highest severity level or NONE if none exists. + * Retrieves the total number of issues from a dependency summary. + * @param summary The dependency summary object. + * @returns The total number of issues. * @private */ private getTotalIssues(summary: any): number { @@ -138,9 +162,9 @@ class AnalysisResponse implements IAnalysisResponse { } /** - * Retrieves the highest vulnerability severity value from a dependency. - * @param dependency The dependency object. - * @returns The highest severity level or NONE if none exists. + * Retrieves the highest vulnerability severity from a source summary. + * @param summary The source summary object. + * @returns The highest severity level. * @private */ private getHighestSeverity(summary: any): string { @@ -158,11 +182,11 @@ class AnalysisResponse implements IAnalysisResponse { return highestSeverity; } - + /** - * Retrieves the recommendation reference from a dependency. - * @param dependencies List of the dependency object. - * @returns The recommendation reference or empty string if none exists. + * Retrieves the recommendation reference from a list of dependency objects. + * @param dependencies The list of dependency objects. + * @returns The recommendation reference or an empty string. * @private */ private getRecommendation(dependencies: ISourceDependency[]): string { @@ -174,6 +198,9 @@ class AnalysisResponse implements IAnalysisResponse { } } +/** + * Represents the options for running image analysis. + */ interface IOptions { RHDA_TOKEN: string; RHDA_SOURCE: string; @@ -191,6 +218,12 @@ interface IOptions { EXHORT_IMAGE_VARIANT: string; } +/** + * Executes RHDA image analysis using the provided images and options. + * @param images - The images to analyze. + * @param options - The options for running image analysis. + * @returns A Promise resolving to the analysis response. + */ function imageAnalysisService(images: IImage[], options: IOptions): Promise { return new Promise((resolve, reject) => { const jarPath = '/home/Ilonas/Documents/SSSC/RHDA/fabric8-analytics-lsp-server/javaApiAdapter/exhort-java-api-adapter-1.0-SNAPSHOT-jar-with-dependencies.jar'; @@ -223,11 +256,10 @@ function imageAnalysisService(images: IImage[], options: IOptions): Promise }); } - /** - * Performs RHDA component analysis on provided manifest contents and fileType based on ecosystem. - * @param fileType - The type of file (e.g., 'pom.xml', 'package.json', 'go.mod', 'requirements.txt', 'Dockerfile'). - * @param contents - The contents of the manifest file to analyze. + * Performs RHDA image analysis on provided images. + * @param diagnosticFilePath - The path to the image file to analyze. + * @param images - The images to analyze. * @returns A Promise resolving to an AnalysisResponse object. */ async function executeImageAnalysis(diagnosticFilePath: string, images: IImage[]): Promise { diff --git a/src/imageAnalysis/collector.ts b/src/imageAnalysis/collector.ts index 6f71f044..333f6883 100644 --- a/src/imageAnalysis/collector.ts +++ b/src/imageAnalysis/collector.ts @@ -9,7 +9,7 @@ import { Range } from 'vscode-languageserver'; import { IPositionedString, IPosition } from '../positionTypes'; /** - * Represents a context with a string value and its associated range. + * Represents an image specification. */ export interface IImage { name: IPositionedString; @@ -18,7 +18,7 @@ export interface IImage { } /** - * Represents a dependency and implements the IDependency interface. + * Represents an image and implements the IImage interface. */ export class Image implements IImage { public platform: string; @@ -30,23 +30,28 @@ export class Image implements IImage { } /** - * Represents an interface for providing ecosystem-specific dependencies. + * Represents an interface for providing ecosystem-specific images. */ export interface IImageProvider { /** - * Collects dependencies from the provided manifest contents. - * @param contents - The manifest contents to collect dependencies from. - * @returns A Promise resolving to an array of dependencies. + * Collects images from the provided image file contents. + * @param contents - The image file contents to collect images from. + * @returns A Promise resolving to an array of images. */ collect(contents: string): Promise; } /** - * Represents a map of dependencies using dependency name as key for easy retrieval of associated details. + * Represents a map of arrays of images using the shared image name as the key for easy retrieval of associated details. */ export class ImageMap { mapper: Map; + + /** + * Creates an instance of ImageMap. + * @param images - The array of images to initialize the map with. + */ constructor(images: IImage[]) { this.mapper = new Map(); @@ -61,9 +66,9 @@ export class ImageMap { } /** - * Retrieves a dependency by its unique name key. - * @param key - The unique name key for the desired dependency. - * @returns The dependency object linked to the specified unique name key. + * Retrieves an array of images by their unique name key. + * @param key - The unique name key for the desired images. + * @returns The array of images linked to the specified unique name key. */ public get(key: string): IImage[] { const images: IImage[] = []; @@ -86,9 +91,9 @@ export class ImageMap { } /** - * Retrieves the range of a dependency version or context within a text document. - * @param dep - The dependency object containing version and context information. - * @returns The range within the text document that represents the dependency. + * Retrieves the range of an image within a image document. + * @param img - The image object image position information. + * @returns The range within the image document that represents the image. */ export function getRange (img: IImage): Range { const pos: IPosition = img.name.position; diff --git a/src/imageAnalysis/diagnostics.ts b/src/imageAnalysis/diagnostics.ts index 6e20c821..5b05cdb9 100644 --- a/src/imageAnalysis/diagnostics.ts +++ b/src/imageAnalysis/diagnostics.ts @@ -16,9 +16,15 @@ import { Vulnerability } from '../vulnerability'; /** * Implementation of DiagnosticsPipeline interface. + * @typeparam ImageData - The type of elements in the image data array. */ -class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { +class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { + /** + * Creates an instance of DiagnosticsPipeline. + * @param imageMap - The image map containing information about image derived from the image file. + * @param diagnosticFilePath - The path to the image file to retrieve diagnostics from. + */ constructor( private imageMap: ImageMap, diagnosticFilePath: string, @@ -26,6 +32,10 @@ class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { super(diagnosticFilePath); } + /** + * Runs diagnostics on images. + * @param images - A map containing image data by reference string. + */ runDiagnostics(images: Map) { Object.entries(images).map(([ref, imageData]) => { const foundImageList = this.imageMap.get(ref); @@ -61,8 +71,7 @@ class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { /** * Creates a code action. * @param loc - Location of code action effect. - * @param ref - The reference name of the recommended package. - * @param context - Dependency context object. + * @param imageRef - The reference name of the image. * @param sourceId - Source ID. * @param vulnerabilityDiagnostic - Vulnerability diagnostic object. * @private @@ -75,10 +84,10 @@ class DiagnosticsPipeline extends AbstractDiagnosticsPipeline { } /** - * Performs diagnostics on the provided manifest file contents. - * @param diagnosticFilePath - The path to the manifest file. - * @param contents - The contents of the manifest file. - * @param provider - The dependency provider of the corresponding ecosystem. + * Performs diagnostics on the provided image file contents. + * @param diagnosticFilePath - The path to the image file. + * @param contents - The contents of the image file. + * @param provider - The image provider of the corresponding ecosystem. * @returns A Promise that resolves when diagnostics are completed. */ async function performDiagnostics(diagnosticFilePath: string, contents: string, provider: IImageProvider) { diff --git a/src/providers/docker.ts b/src/providers/docker.ts index 8956bc28..b20c275b 100644 --- a/src/providers/docker.ts +++ b/src/providers/docker.ts @@ -27,6 +27,12 @@ export class ImageProvider implements IImageProvider { return contents.split('\n'); } + /** + * Replaces placeholders in a string with values from a args map. + * @param imageData - The string containing placeholders. + * @returns The string with placeholders replaced by corresponding values from the args map. + * @private + */ private replaceArgsInString(imageData: string): string { return imageData.replace(/\${([^{}]+)}/g, (match, key) => { const value = this.args.get(key) || ''; @@ -35,10 +41,10 @@ export class ImageProvider implements IImageProvider { } /** - * Parses a line from the file and extracts dependency information. - * @param line - The line to parse for dependency information. + * Parses a line from the file and extracts image information. + * @param line - The line to parse for image information. * @param index - The index of the line in the file. - * @returns An IDependency object representing the parsed dependency or null if no dependency is found. + * @returns An IImage object representing the parsed image or null if no image is found. */ private parseLine(line: string, index: number): IImage | null { const argMatch = line.match(this.ARG_REGEX); @@ -72,9 +78,9 @@ export class ImageProvider implements IImageProvider { } /** - * Extracts dependencies from lines parsed from the file. + * Extracts images from lines parsed from the file. * @param lines - An array of strings representing lines from the file. - * @returns An array of IDependency objects representing extracted dependencies. + * @returns An array of IImage objects representing extracted images. */ private extractDependenciesFromLines(lines: string[]): IImage[] { return lines.reduce((images: IImage[], line: string, index: number) => { @@ -87,9 +93,9 @@ export class ImageProvider implements IImageProvider { } /** - * Collects dependencies from the provided manifest contents. - * @param contents - The manifest content to collect dependencies from. - * @returns A Promise resolving to an array of IDependency objects representing collected dependencies. + * Collects images from the provided image file contents. + * @param contents - The image file content to collect images from. + * @returns A Promise resolving to an array of IImage objects representing collected images. */ async collect(contents: string): Promise { const lines: string[] = this.parseTxtDoc(contents); diff --git a/src/vulnerability.ts b/src/vulnerability.ts index b30244d8..7e2ee205 100644 --- a/src/vulnerability.ts +++ b/src/vulnerability.ts @@ -12,14 +12,14 @@ import { RHDA_DIAGNOSTIC_SOURCE } from './constants'; import { globalConfig } from './config'; /** - * Stores vulnerability data of a specific dependency. + * Stores vulnerability data of a specific artifact (Image and dependency artifacts supported). */ class Vulnerability { /** * Creates a new instance of Vulnerability. * @param range - The text range within the document. - * @param ref - The reference name of the dependency. - * @param artifactData - All vulnerability data regarding the dependency. + * @param ref - The reference name of the artifact. + * @param artifactData - All vulnerability data regarding the artifact. */ constructor( private range: Range, @@ -29,7 +29,7 @@ class Vulnerability { /** * Generate vulnerability information message - * @param artifactData Properties of the dependency object + * @param artifactData Properties of the artifact object * @returns vulnerability information message string */ private generateVulnerabilityInfo(artifactData: DependencyData | ImageData): string { @@ -39,8 +39,8 @@ Highest severity: ${artifactData.highestVulnerabilitySeverity}`; } /** - * Generate recommendation message from source - * @param artifactData Properties of the dependency object + * Generate recommendation message from source + * @param artifactData Properties of the artifact object * @returns source recommendation message string */ private generateRecommendation(artifactData: DependencyData | ImageData): string {