docs: add and update type doc annotations

Signed-off-by: Ilona Shishov <[email protected]>

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 = {

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<string, DependencyData[]>;
@@ -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<AnalysisResponse> {

src/dependencyAnalysis/diagnostics.ts

@@ -18,16 +18,26 @@ 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<DependencyData> {
 
+    /**
+     * 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,
     ) {
         super(diagnosticFilePath);
     }
 
+    /**
+     * Runs diagnostics on dependencies.
+     * @param dependencies - A map containing dependency data by reference string.
+     */
     runDiagnostics(dependencies: Map<string, DependencyData[]>) {
         Object.entries(dependencies).map(([ref, dependencyData]) => {
             const dependencyRef = ref.split('@')[0];

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<T> {
     /**
      * 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<string, DependencyData[]>);
+    runDiagnostics(artifact: Map<string, T[]>);
 }
 
-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<T> implements IDiagnosticsPipeline<T>{
+     /**
+     * An array to hold diagnostic information.
+     */
     protected diagnostics: Diagnostic[] = [];
+    /**
+     * A map to hold vulnerability count information.
+     */
     protected vulnCount: Map<string, number> = new Map<string, number>();
 
+    /**
+     * 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<string, DependencyData[]>): void;
+    abstract runDiagnostics(artifact: Map<string, T[]>): void;
 }
 
 export { AbstractDiagnosticsPipeline };

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<string, IProvider>;
 }
 
+/**
+ * Represents a provider of dependencies for an image.
+ */
 interface IProvider {
   status: IStatus;
   sources: Map<string, ISource>;
 }
 
+/**
+ * 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,18 +59,24 @@ 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;
   dependencies: ISourceDependency[];
 }
 
 /**
-* 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<string, ImageData[]>;
@@ -128,19 +152,19 @@ 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 {
       return isDefined(summary, 'total') ? summary.total : 0;
   }
 
   /**
-   * 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<any> {
     return new Promise<any>((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<any>
     });
   }
 
-
 /**
- * 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<AnalysisResponse> {

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<IImage[]>;
 }
 
 /**
- * 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<string, IImage[]>;
+
+  /**
+   * 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;